Chapter 17
The seam monitor
The monitor has a build-time half and a run-time half over one record. Source analysis produces evidence, a gate adjudicates it, a confirmed seam is registered as a surface, and soak measures whether the closure holds against real inputs.
What it is
Five stages, each with one job and one output. The separation matters: the scanner is an evidence producer, not an adjudicator.
| Stage | Role | Output |
|---|---|---|
| Source scan | Evidence producer | A candidate interpretation edge, as structural facts |
| Interpretation gate | Semantic adjudication | A typed disposition |
| Registration | Declaration | A surface on the append-only record |
| Run-time producer | Viability measurement | Soak findings on live traffic |
| Authority state | Consumer | The per-surface reading over all of the above |
The scan reports what it can establish structurally: that a value originates from a known source locus, flows through named identifiers, reaches a branch, threshold, pattern or key sink, and that the default path has a particular shape. It never emits a verdict.
The three dispositions
The gate answers one question before the authority machine asks any of its own: is this a closure over an open interpreted domain at all?
| Disposition | Meaning |
|---|---|
certain-interpreted | The input's meaning is not fixed by its representation and the edge governs authority. A real seam; the state machine applies. |
certain-mechanical | The edge is deterministic or the domain is closed. An exact match, an enum lookup. Not a seam. |
unresolved | Abstain. The apparatus cannot yet tell, so it withholds the disposition and keeps measuring. |
Only certain-interpreted edges become registered records. Abstention here means
withholding a consequential disposition and continuing to measure. It is not a queue of requests
for a human.
Why it matters
The scanner is its own dark surface
Finding seams is itself a closure over an open domain, namely arbitrary code, so it reports its own blind spots as first-class coverage rather than as silence.
coverage.status: the overall coverage state for the scanned unit.coverage.supported_constructs: the language constructs the front end actually handles.coverage.unresolved_edges: edges the taint could not fully follow.coverage.unparsed: code the front end could not parse.coverage.dynamic_escape: points where dynamic dispatch, reflection or serialization broke the path.
Partial coverage is never reported as no seams. A scan that could not follow an edge says so, and the hook that reports into a build session says so too rather than issuing a false all-clear.
Propose only
The monitor flags and drafts. It does not edit code and it does not block on the lens's own authority. Whether a build stops is a policy the operator or CI sets, and the detector must qualify before that policy is even eligible: observe first, everywhere, including the detector run against its own repository.
The criterion that governs that qualification is the one the invariant demands of every other instrument. Under rising uncertainty the detector must abstain more, not assert more.
How to use it
- Scan a repository and push its seams to the lens, or run the hook so a seam is reported into the session that wrote it.
--propose-sinksand--propose-skipsmechanically propose candidates for the authority-sink and skip-path lists rather than asking you to author them cold.- Accepted declarations are honored: a seam you declare drops from the lens as well as from the scan.
- Each reported seam names the authority sink it reaches, so the choice is to declare it or restructure around it.
Soak: the run-time half
A soak is the empirical life of a registered seam: how often its no-match or abstention path actually fires, which branch it takes, how the decided value's identity churns over time, and optionally whether that value is efficacious.
A soak observation is a full evaluation event rather than a new event kind, so every existing tool works on it unchanged: the producers, the dashboard, retention and husking, the judge link. The seam-ness lives on the run-time configuration axes instead.
| Axis | Value |
|---|---|
provenance | seam. The isolation key. It sits in neither the production-state nor the exploratory-state set, so soaks are excluded from every default analysis and cannot drown a small agent's readings. |
runMode | The shared enum. Isolation is provenance-keyed and independent of run mode, so eval and replay mean here what they mean everywhere. |
lightSourceIdentifier | seam/<component>/<scan>. A seam is a light source that is not a model, and it takes the slot honestly rather than faking a vendor. |
The husk-surviving facts, whether it abstained and which path it took and the value fingerprint, ride in the surface dimension, the substrate columns and the cohort tags. A raw decided value rides in the payload and husks away like a judge rationale.
Reading the output
Soaks file under one reserved surface, adjacent to the surface registered seams file under, with
individual seams as loci inside it. Findings from both reach the attention spine as
builder-seam and seam-soak sources, alongside every other finding the
instrument produces.
Reference
The shared vocabulary, the four sink shapes, the default-path forms and the sink kinds, lives in the public contract package so the build-time scanner and the run-time producer name the same things. The interpretation disposition is the same enum the authority state machine reads.