Boundary Discipline

Boundary Discipline

A robust system is built from boundaries: places where data changes its epistemic status. Inside a boundary you assume; crossing it you verify. The discipline has one law and four boundary kinds — but the work splits three ways, and picking the right one is the first and most important step.

STEP 0 — Pick the mode (do this before anything else)

Decision rule: building something new → IMPLEMENT. Reporting on what exists → AUDIT. Restructuring what exists without changing behavior → REFACTOR.

Anti-pattern to avoid (the reason these are separate): when the task is to build a feature, do NOT first audit the surrounding codebase. Implement mode scopes to the new code's own pipeline and only touches boundaries that code directly crosses. A feature request is not an audit request — mixing them balloons scope and buries the work. The modes hand off explicitly instead: an audit reports a misplaced boundary; fixing it is a separate refactor.

Then read references/model.md once (the shared vocabulary), and follow your chosen mode file.

The one law (always keep in mind)

One unit, one epistemic status. A function/module operates entirely on data of one status: it parses untrusted input OR works on proven data; it decides OR acts; it owns exactly one invariant's atomicity. Every misplaced boundary is a unit straddling two statuses — the boundary living inside the unit instead of around it. (Single-responsibility, in terms of data status.)

The four boundaries (one line each — full reference in model.md)

• Trust unknown → Proven<T> | Rejection — parse untrusted input into a domain type. Home: earliest point (ingress). Fingerprint: input you didn't construct (req.body, JSON.parse, env, DB reads).
• Effect Decision → IO<Outcome> — turn a pure decision into a side effect. Home: latest point (rim). Fingerprint: await, fetch, fs, DB writes, clocks, randomness.
• Consistency (State, Δ) → Committed | Conflict — arbitrate concurrent writes against an invariant. Home: the serialization point (constraint/lock). Fingerprint: read-then-write, check-then-act.
• Containment Risky → Bounded — bound the failure of a risky call. Home: wrapping the effect boundary. Fingerprint: un-timed network/IO, shared pools.

Trust pushed inward + effects pushed outward = the pure functional core in between. Structure is fractal: trust resets at every process edge, so every service re-parses at its own ingress.

Files

• references/model.md — shared reference: signatures, flow rules, concept families, misplacement diagnostics, maturity ladder. Read once per task.
• references/audit.md — find & report gaps in existing code.
• references/implement.md — place boundaries in new code (with scope guard).
• references/refactor.md — relocate a misplaced boundary, behavior-preserving.
• scripts/scan.py — mechanizes the AUDIT fingerprints into triage candidates (grouped by boundary, with hotspots). Run it at the start of an audit to find candidates fast, then classify each by hand against audit.md — the script surfaces, the model judges. Config-driven (boundary.config.json) with TS defaults, so it runs zero-config: python scripts/scan.py <path>.