Chapter 16

Seams

A value whose meaning is not fixed by its representation, driving a decision that governs a consequential transition, is a seam. It is permanent. You can close it and you can monitor it. You cannot validate it away.

What it is

A seam is an edge: the path a value travels from where it is produced to the decision that consumes it. Write it I → DP, interpretive source to decision point.

Whether an input is interpreted is a property of that edge, not of the field and not of whether the code is deterministic. The same field can lie on a deterministic edge to one consumer and an interpreted edge to another. A model output, a classifier, an approximate match, a pattern applied to free text, an external feed, a recorded human judgment: each is an interpreted source, and each is interpreted because of what the consuming decision does with it.

The decision point reverts to an ordinary, inert sink under one condition only: it stops making decisions. Its output goes to a log line, a rendered field, a return nobody branches on. Short of that, the seam stays.

Why it matters

Provenance is monotone

Consider a decision that reads free text and returns one of three values:

function decide(ticket): 'page' | 'auto-reply' | 'queue' {
  const msg = (ticket.subject + ticket.body).toLowerCase();   // I0
  if (INCIDENT.test(msg)) return 'page';
  ...
}

const action = decide(ticket);        // I1: deterministic in value, interpreted in provenance
if (action === 'page') pageOnCall();  // dispatch on I1 reaches authority

The enum is not a sanitizer. It is the decision's codomain. action is a first-class interpretive value, deterministic in what it holds and interpreted in where it came from. The chain runs I0 → DP → I1 → DP1 and onward, and the provenance rides through every hop. Relocating the decision upstream moves the decision point; it does not escape anything. The next scan finds it in its new place.

Validation changes the character of the error, not its existence

A schema boundary filters the catastrophic: wrong type, missing field, malformed JSON. It passes the shape-valid-but-wrong. So it raises the floor and, in the same motion, makes the residual error insidious, because the value now looks right, types right, and fails quietly downstream.

A pattern that pulls 'success' out of "I hope you are a great success in life" and resolves it to route.SUCCESS is the whole problem in one line. The enum fixed the form, not the misread. It is a confidently wrong signal wearing a valid badge.

This is why structure cannot finish the job. Closing a seam makes the decision attended and monitorable. It does not make the decision correct. Correctness is a different axis, the empirical misfire rate, and the only instrument for it is soak. Structure hands off exactly the error class it cannot catch to the instrument that can.

Open and closed

With provenance carried, the two states have a precise inductive definition over the chain.

A closed seam is a declared surface. It stays closed only while its measurement holds, which is why closed and ready for soak belong in the same breath.

The four closure shapes

These are the structural forms a closure takes. They are shapes, not an exhaustive list of the decisions that can exercise authority; the sink taxonomy is an open registry.

Model calls are seams

A model call is a seam whose interpreter is not stationary. A pattern does not rewrite itself between releases; a model can be re-routed behind an unchanged alias, and the instrument scoring it is usually another model. So a model seam carries more variance machinery: the four-source decomposition, the served-model axis, judge facets, saturation and orthogonality.

The machinery differs; the lifecycle does not. Code seams and model seams both soak, both file findings on the spine, and both reach authority. They sit on adjacent surfaces, not in separate systems. A seam is itself a light source, recorded as seam/<component>/<scan>, which is how a non-model interpreter takes the same slot a vendor would without pretending to be one.

Reference

The shape is the lens's own judge → verdict → gate → action model applied inside ordinary code: decide → enum → dispatch → sink is the same structure. The enum is a verdict, carrying light from an interpreted source, and a dispatch acting on it is governed by that light.