The specification · Introduction

Reading the specification

spec/README.md gives a reading order. The files are layered rather than alphabetical, each assuming the vocabulary the previous one introduced.

The reading order

1. Start with grammar.md, which owns the S-* rules. It is the statement gate and the expression productions, decidable from syntax alone. Every F-* rule in the next file is keyed to a production in this one.
2. Read judgments.md next; it owns the F-* judgments: J1 expression evaluation and J2 the per-file verdict; J3 the identity-taint fixpoint and J4 properties and observables. Its preamble states the objective the whole mechanism serves.
3. Then comes values.md, which owns F-Val-*, the value domain. It says what a fold produces: the closed union of cases a folded value can be, and the envelope shapes that stand in for things the build has not resolved yet.
4. The fourth file, divergence.md, owns F-Direction, F-Div-* and F-Exc-*. One subset has two consumers with unequal information, the shape classifier and the folder. This file states the direction in which they may disagree, enumerates every known divergence, and gives the two tolerated exceptions with a reason each.
5. Last is hosts.md, which owns F-Host-*, the host interface. Seven things a host supplies, and the rule by which each is admitted.

Each of those five ends with a non-normative Rationale section, where the reasoning lives; the rule text above it is deliberately terse.

Two further files are not rule files.

inventory.md is the coverage ledger. A decision point is anywhere the mechanism chooses between admitting and rejecting, between evaluation modes, or between representations. There is one row per decision point, derived from a complete read of chant core’s fold path, and the last column names the S-* or F-* rule that governs the row, or GAP with an out-of-scope reason.

prior-art.md is a survey rather than a rule. Graceful fallback from static evaluation to execution is well established. What the sweep found no precedent for is the combination of per-file granularity with shared object identity across the boundary, which is what forces J3.

The process rules

spec/README.md also carries rules about the document set rather than about the mechanism. No fixture cites them; CI structure enforces them.

Every normative rule carries a stable identifier. Each identifier is exercised by at least one fixture, and each fixture cites a real identifier, checked in both directions in CI. Rejections are located, by node and rule, with the wording unconstrained, because message stability is not normative.

spec/README.md is published as the specification index, and it is the shortest route to the rest.