Mostly Done.
Contents

13 Semantics that cross boundaries

The repository boundary is not the truth boundary.

A parser accepts the text, but two output modes disagree on trailing whitespace. A workflow declares a gate that can never run. A checkpoint resumes while the audit trail describes a different path. In language tools and workflow engines, syntactic validity says nothing about semantic truth.

These systems need proof that follows state across boundaries, including boundaries the current repository does not contain.

13.1 Design the language model before the parser

Design gates surface the decisions that shape every later component. Should composition cascade, include, or expand into tokens? Where should an unterminated quote be rejected? What does a migration preserve? Which runtime consumes the output?

A parser can implement any of these models faithfully. Correctness depends on choosing the right one.

The design should state:

The parser comes after the contract.

13.2 Test byte boundaries explicitly

Language tools often pass semantic tests while corrupting bytes that other tools care about. Consider a prompt-composition feature with two packaging modes, inline and source, whose contract is byte identity at the final line. The inline path routed composed fragments through a formatter block that right-trimmed; the source path used the raw composition. A fragment ending in a newline produced different bytes in different modes, on the exact final-line contract the feature existed to preserve. The repair normalized whitespace in one shared function, applied only when fragments are composed, with an early return that leaves ordinary content untouched. The scope of a byte-level fix is part of its correctness.

Round-trip tests should cover:

When byte identity is the contract, parse-tree equality is not a substitute.

13.3 Use a simple reference implementation

Pair compact language machinery, an escape-aware condition parser for instance, with a reference implementation that is allowed to be slow and inelegant. Its job is not production. Its job is disagreement.

for input in generated_cases:
    assert production(input) == reference(input)

Generated inputs are cheap, so run tens of thousands of them. Emphasize combinations that hand-written examples miss: nested escapes, empty tokens, repeated separators, partial endings, and boundaries around maximum lengths.

The reference must differ enough from production to avoid sharing the same bug. A straightforward decoder and an optimized state machine are a useful pair. Two copies of the same algorithm are not.

13.4 Prove workflow reachability, not declaration

A goal gate that never executes can still appear covered. Workflow tests need to distinguish several states that broad coverage metrics may merge:

A test that observes only final success can miss the path that produced it. The audit and checkpoint state should allow the system to explain which edges ran and why.

Useful workflow properties include:

These are state-machine claims, even when the code is written as ordinary functions.

13.5 Keep runtime reality in the loop

The sharpest cross-boundary failures depend on facts from a separate repository. Consider a workflow definition language whose output executes in a runtime that lives in another checkout. The language tool modeled retry destinations as routing edges. In the runtime, a retry outcome dispatches to a dedicated path that never consults edge selection at all. From the tool’s side, retry and routing looked related. In the runtime they were disjoint channels with their own defaults.

The blind spot extended to the tool’s own simulator, which exercises graph structure. Retry outcomes arise from runtime infrastructure, cost limits, and no-progress conditions that no graph walk produces. A migrated workflow could keep a byte-identical happy path while corrupting retry behavior, and every local tool would agree it was fine.

Your checkout may define syntax without defining execution. An agent working in it can reason perfectly from incomplete premises.

Cross-repository assumptions should be written into the design and verified against the consumer. Useful methods include:

The repository boundary is not the truth boundary.

13.6 Sweep every language surface

A language feature changes more than a parser. A complete sweep covers documentation, the website, examples, editor grammars, embedded agent instructions, migrations, and downstream expectations in the same batch.

This prevents a distinctive agentic failure: one model updates the parser, another later reads stale instructions and generates the old language with equal confidence.

The sweep itself should be tested. Parse every example in the repository with the real parser and linter, with specific lint codes forbidden. Give the embedded machine specification a freshness test that regenerates it and fails on staleness. Require exactly one explanation per diagnostic code, no more and no fewer. Instructions that machines consume need executable checks, because to another agent they are code.

13.7 Refuse speculative workflow patches

Workflow failures often depend on remote state or diagnostic artifacts. When you have ruled out every code path in the checkout and the remaining cause lives in an artifact you do not have, stopping is the correct completed result. A speculative patch to a workflow engine can create a second state inconsistency while hiding the first.

The language and workflow domains reward patience because their failures travel. A one-line parser change can alter migrations, editors, agents, and runtimes. A one-line state change can alter checkpoints, retries, and audit history. Design, proof, and release must travel with it.

use ← and → to turn pages