Skip to content

Residual-Defect Scan

Audit / scan — instantiates Mobile-Defect Reconfiguration

Sweeps the region the front has already passed to catch what it left behind — the missed spots and new mismatches a moving reconfiguration inevitably seeds.

A moving reconfiguration is never perfectly clean: it skips edge cases and can seed fresh mismatches as it advances. The Residual-Defect Scan is the audit that sweeps the already-processed region and checks two things — that every unit behind the front actually reached the target state (no missed or half-done spots), and that the global structure still holds together (nothing was silently disconnected). Its defining stance is that it looks backward, behind the front, for what was left wrong — detection only, never repair. That backward gaze is what separates it from a checkpoint of the live front and from a pass that stabilises the trail: this mechanism's entire job is to locate residue and certify how much remains.

Example

A team runs an automated codemod to replace a deprecated API across a large monorepo — thousands of call sites rewritten mechanically in one sweep. The tool reports success, but mechanical rewrites always miss things: calls assembled through string concatenation, dynamic dispatch the matcher never saw, a vendored copy outside the traversal. The Residual-Defect Scan runs afterward. It searches the whole tree (grep plus an AST pass) for any surviving old-API usage — the residual defects — and then runs the type-checker and build to confirm every reference still resolves and nothing was orphaned. It reports 37 residual call sites the codemod missed and two modules that no longer compile. The migration that claimed to be done is shown to be about 99% done, with the exact residue located rather than left to surface in production.

How it works

  • Define residue. Specify what a leftover looks like — a surviving old pattern, an orphaned reference, a violated invariant — then sweep the passed region for it. The detector is tuned for recall: find every leftover, tolerate some false alarms.
  • Verify behind the front. Confirm each processed unit actually reached target, and flag those that did not.
  • Check topology. Confirm the global structure survived the moves — references resolve, no cycles were introduced, conserved counts still balance.

It produces a located list of residue and a pass/fail on structural integrity; it does not fix what it finds — that is handed to a stabilisation pass.

Tuning parameters

  • Coverage vs. cost — exhaustive sweep vs. sampling. Full coverage maximises recall but is expensive; sampling is cheap but leaks false negatives.
  • Recall/precision balance — how aggressively to flag suspects. High recall catches more leftovers at the price of more alarms to triage.
  • Residue-definition breadth — how many defect classes the scan looks for. Each added class costs a scanner but narrows the blind spot.
  • Timing — run continuously behind the moving front, or once as a terminal sweep. Continuous catches residue early; terminal is simpler but lets it pile up.
  • Topology depth — shallow (do references resolve?) vs. deep (full invariant re-check).

When it helps, and when it misleads

Its strength is converting "the migration says it's done" into evidence, and locating the exact residue so it can be fixed deliberately rather than discovered live. Its trap is that a clean scan certifies only the defect classes it actually looked for: absence of findings is not absence of defects, and a narrow scan breeds false confidence — the worst outcome being a reassuring green over a real leftover it never thought to check.[1] The misuse that follows is treating a scan-pass as a proof of correctness and closing the migration on it. The discipline is to state the scan's coverage explicitly — what it does and does not check — and to widen the residue definition whenever a production surprise reveals a class the scan was blind to.

How it implements the components

  • behind_front_state_verification — its core: verifying each unit behind the front reached target, and flagging the ones that did not.
  • topology_preservation_check — confirming the global structure and connectivity survived the moves (references resolve, invariants hold, counts balance).

It detects but does not repair the residue (residual_state_reconciliation — Behind-Front Stabilization Pass), and it inspects the settled region behind the front rather than snapshotting the live leading edge for resumability (Front-State Checkpoint).

References

[1] A negative scan bounds only the defect classes it actually searched for — "absence of evidence is not evidence of absence." A clean result certifies coverage, not correctness, which is why the scan's blind spots must be stated explicitly rather than assumed empty. ↩