Plan: Polyglot Scanner × Checkpoint Homology

Goal: Wire the polyglot scanner's per-function topology metrics (crossing number, β₁, Kernel Weight, void dimensions, coupling) into the organism-level CheckpointHomology algebra, so that every project in the workspace gets a formally-verified health diagnosis computed from actual code topology — not estimates, not heuristics, but the real crossing numbers from tree-sitter ASTs.

Prerequisite reading:

• SELF_REPAIR_ROADMAP.md — the full trajectory
• lean/Lean/ForkRaceFoldTheorems/CheckpointHomology.lean — the grand reduction
• lean/Lean/ForkRaceFoldTheorems/CodebaseCheckpointSubstrate.lean — codebase as 8th substrate
• packages/polyglot-scanner-core/src/analyzer.ts — the scanner engine
• open-source/a0/src/organism-topology.ts — current organism analysis (uses rg estimates)
• open-source/a0/src/checkpoint-substrates.ts — TS runtime of the Lean proofs

The Gap

Today, a0 audit organism uses a lightweight estimator (ripgrep function count × baseline complexity = 2) to compute per-project sigma. This gives uniform sigma ≈ 0.1 across all projects — useless for differentiation.

The polyglot scanner already computes real per-function metrics:

• crossingNumber — control-flow branches (regex over tree-sitter AST)
• beta1 — essential loops (for/while/do)
• godWeight — w = R - min(v, R) + 1
• voidDimension — cross_file / temporal / data_plane
• leakPaths, violationPaths — rejection channel counts
• Brunnian coupling detection (n-wise emergent inter-module knots)

These are exactly the inputs to CheckpointHomology.TwoTermComplex:

• rank1 (active channels) = functions with godWeight ≤ threshold (healthy)
• rank0 (destroyed channels) = functions with godWeight > threshold (stressed)
• Or alternatively: rank1 = functions with beta1 > 0 (can learn), rank0 = functions with beta1 = 0 (deaf)

Architecture

polyglot-scanner-core          a0 organism-topology
       │                              │
       │ analyzeFileContent()          │ computeOrganismTopology()
       │ → Finding[]                   │ → OrganismNode[]
       │                              │
       ▼                              ▼
  ┌─────────────────────────────────────────┐
  │   NEW: polyglot-checkpoint-bridge.ts     │
  │                                         │
  │   aggregateFindings(findings) →          │
  │     TwoTermComplex per project          │
  │                                         │
  │   diagnoseProject(complex) →             │
  │     { health, sigma, beta1, deficit,    │
  │       repairPath, godFormulaOrdering }  │
  │                                         │
  │   Uses: checkpoint-substrates.ts         │
  │   Proves: CheckpointHomology theorems    │
  └─────────────────────────────────────────┘
       │                              │
       ▼                              ▼
  organism-topology.ts          liveness.ts
  (real sigma per project)      (real sigma in ejection plans)
       │                              │
       ▼                              ▼
  liveness-explorer             a0 audit organism
  (helix colors from real       (health distribution from
   code topology)                real code topology)

Implementation Steps

Step 1: Create the bridge module

File: open-source/a0/src/polyglot-checkpoint-bridge.ts

import { analyzeFileContent, type Finding } from '@a0n/polyglot-scanner-core';
import {
  type CheckpointedSystem,
  codebaseToUniversal,
  diagnose,
  godFormulaWeight,
} from './checkpoint-substrates.ts';

interface ProjectScanResult {
  projectName: string;
  findings: Finding[];
  functionCount: number;
  totalCrossingNumber: number;
  totalBeta1: number;
  totalKernelWeight: number;
  maxKernelWeight: number;
  hotspotCount: number;  // godWeight > 10
  defectProfile: Record<string, number>;  // defect category → count
  voidDimensions: {
    cross_file: number;
    temporal: number;
    data_plane: number;
  };
}

interface ProjectCheckpointProfile {
  projectName: string;
  /** Functions with beta1 > 0 (can learn from feedback) */
  activeChannels: number;
  /** Functions with beta1 = 0 (deaf — no loops, no learning) */
  destroyedChannels: number;
  /** CheckpointedSystem mapped from the profile */
  system: CheckpointedSystem;
  /** Diagnosis from checkpoint-substrates.ts */
  diagnosis: ReturnType<typeof diagnose>;
  /** Per-function Kernel Formula ordering for repair priority */
  repairOrdering: Array<{ function: string; file: string; godWeight: number }>;
  /** Sigma: normalized stress (real, from actual code topology) */
  sigma: number;
}

Key function: scanAndDiagnoseProject(workspaceRoot, projectRoot)

1. Walk all source files in the project
2. Run analyzeFileContent() on each
3. Aggregate findings into ProjectScanResult
4. Map to CheckpointedSystem via the bridge
5. Run diagnose() from checkpoint-substrates.ts
6. Return ProjectCheckpointProfile

Step 2: Replace the rg estimator in organism-topology.ts

File: open-source/a0/src/organism-topology.ts

Replace scanProject() (which uses rg -c for function counting) with a call to scanAndDiagnoseProject() from the bridge. This gives every OrganismNode a real sigma computed from actual crossing numbers, not estimates.

The sigma computation becomes:

// Old (estimate): sigma = avgKernelWeight / 20
// New (real): sigma = totalKernelWeight / (functionCount * maxPossibleKernelWeight)
// Or simpler: sigma = hotspotCount / functionCount (fraction of stressed functions)

The health classification becomes:

// Old: based on sigma thresholds
// New: based on CheckpointHomology diagnosis
//   - healthy: diagnosis.health === 'healthy'
//   - stressed: diagnosis.health === 'stressed'
//   - cancerous: system.isDeaf (beta1 = 0)
//   - necrotic: no functions found

Step 3: Wire real sigma into the liveness helix

File: open-source/a0/src/liveness.ts

Currently, helix nodes get sigma from a heuristic:

let sigma = 0.1; // baseline
if (!isAlive) sigma += 0.4;
if (plan) sigma += 0.3;

Replace with:

const scanResult = projectCheckpointProfiles.get(projectName);
let sigma = scanResult?.sigma ?? 0.1;
// Boost for dead/orphaned (same as before, additive)
if (!isAlive) sigma += 0.2;

This makes the helix visualization show real code stress — high crossing number regions glow hot, low beta1 regions fade cold.

Step 4: Kernel Formula repair ordering in ejection plans

File: open-source/a0/src/liveness.ts

When generating ejection plans, use the Kernel Formula to order which functions/files to repair first within each project:

// In generateEjectionPlans():
if (plan.strategy === 'adopt-project') {
  const profile = projectCheckpointProfiles.get(plan.target);
  if (profile?.repairOrdering) {
    plan.repairOrdering = profile.repairOrdering.slice(0, 5);
    // "Start with these 5 functions — they have the highest Kernel Weight
    //  and will give the most beta1 gain per clinamen"
  }
}

Step 5: Void dimension integration

The scanner's three void dimensions (cross_file, temporal, data_plane) map to three independent crossing spaces. Each is a separate chain complex:

interface ProjectVoidProfile {
  cross_file: TwoTermComplex;   // inter-module coupling stress
  temporal: TwoTermComplex;     // load-dependent timing stress
  data_plane: TwoTermComplex;   // query/wire crossing stress
  composite: TwoTermComplex;    // direct sum of all three
}

The CheckpointHomology.directSum theorem proves that the composite health is the sum of the three dimensions. A project can be healthy in cross_file but stressed in temporal — the void profile tells you WHERE the disease lives, not just THAT it exists.

Step 6: Brunnian coupling as interference

The scanner's detectBrunnianCoupling finds n-wise emergent coupling (three modules that are pairwise fine but form a knot together). This is the interference term missing from the current algebra.

Map to: CoupledCheckpointedSystem (Phase 1.1 of SELF_REPAIR_ROADMAP.md)

• Adjacency graph from import patterns
• Coupling strength from Brunnian detection count
• Interference propagation: destroying a Brunnian-coupled module partially degrades its partners

Step 7: Cache and performance

Full polyglot scanning is expensive (~10s per large project). Strategy:

• Cache scan results in .a0/cache/polyglot-scan/{project-hash}.json
• Invalidate via fingerprintProjectRoot() from cache.ts (already exists)
• a0 audit organism --full runs the scanner; default uses cache
• The liveness-data.json bundled snapshot includes scan results

Step 8: Lean proof of the scanner-to-checkpoint functor

File: lean/Lean/ForkRaceFoldTheorems/PolyglotCheckpointFunctor.lean

Prove that the aggregation from Finding[] to TwoTermComplex preserves the homological invariants:

/-- A function scan result maps to a single channel. -/
def findingToChannel (f : Finding) : RejectionChannel where
  capacity := f.godWeight
  positive := by omega  -- godWeight ≥ 1

/-- Aggregating findings preserves conservation. -/
theorem scan_preserves_conservation (findings : List Finding)
    (threshold : ℕ) :
    let active := findings.filter (fun f => f.beta1 > 0)
    let destroyed := findings.filter (fun f => f.beta1 = 0)
    active.length + destroyed.length = findings.length

This closes the loop: Lean proves the algebra, the scanner computes the inputs, the bridge maps scanner output to the algebra, and the theorems guarantee the diagnosis is sound.

Verification

1. pnpm run a0 -- audit organism shows differentiated sigma per project (not uniform 0.1)
2. pnpm run a0 -- audit organism --json includes void dimension profiles
3. pnpm run liveness:explore helix colors reflect real code stress
4. Playwright e2e tests still pass (17/17)
5. pnpm run a0 -- audit liveness --verify merkle root changes when code topology changes (not just dependency topology)
6. Kernel Formula ordering in ejection plan drill-down shows top 5 functions

Success Criteria

The organism formalizes the codebase. Its health is not estimated — it is computed from tree-sitter ASTs, aggregated via the polyglot scanner, mapped through the checkpoint-homology functor, and diagnosed by the same algebra that diagnoses cancer, tokamaks, hearts, oceans, turbulence, markets, and weather. 195 Lean theorems guarantee the diagnosis is sound. The helix visualization shows where the disease lives. The Kernel Formula tells you what to fix first. The merkle root proves it worked.

From rg -c to formally-verified health diagnostics. One bridge module.