# Specification engine

The engine keeps a repository's requirements, verification obligations, prose fixtures, executable
bindings, implementation units, and generated projections synchronized. It enforces relationships.
It decides no meaning.

Requirement identifiers here are engine-owned and use the `SE-` prefix. They are independent of
any consuming repository's requirement registry.

## Authority

**SE-CORE-01.** The engine owns relationship mechanics only: identity, revision, polarity,
fingerprint, containment, uniqueness, reachability, and freshness. It never asserts that a fixture
meaningfully verifies a requirement, or that declared obligations fully express its prose.

**SE-CORE-02.** The engine contains no product-domain fact. Verification lanes, identifier grammar,
registry locations, tool invocation, and projection preambles arrive through the `profile` module.
A fact that both the engine and a consumer need lives in the profile, never in duplicate.

**SE-CORE-03.** Generated output owns no semantics. Any file the engine writes is reproducible from
its owning registries and may be deleted and regenerated at any time.

## Relationship graph

**SE-GRAPH-01.** The graph is:

```text
document#anchor
    owns
requirement@revision
    owns
verification obligation@revision
    ├── realized by implementation unit@revision
    └── claimed by fixture oracle through test specification@revision
                     executed through binding@revision → generated Zig test
```

**SE-GRAPH-02.** Fixtures never link to documents and never link to requirements directly. Claims
and implementation units meet at obligation revisions, so presentation structure can change without
invalidating verification.

**SE-GRAPH-03.** Every link names a stable identifier and an exact revision. A reference to a
superseded revision fails the gate and is resolved by review, never by advancing the number.

## Verification lifecycle

**SE-LIFE-01.** Verification state is derived from artifacts, never declared by an editable flag.

| Present | Derived state |
|---|---|
| Prose fixture only | specified |
| Fixture plus one `zig tj-test` fence | instrumented |
| Instrumented fixture plus current binding | bound |
| Generated test compiled into its declared suite | executable |
| Result for exact revisions | executed |
| Successful result | passed |

**SE-LIFE-02.** A prose-only fixture is a valid specified test. Instrumentation is optional;
a binding without instrumentation, or instrumentation without a binding, fails.

**SE-LIFE-03.** A descriptor is not coverage. Passing a claim is evidence for its obligations and
never a statement of complete requirement coverage.

## Suite evidence records

**SE-EVID-01.** The build graph writes one bounded, transient record per suite immediately after a
fresh, successful run of that suite's generated tests. The record freezes the test-specification,
fixture, binding, artifact, toolchain, and option identities of that run. Attribution never rereads
changed manifests: every identity enters the record at build time.

**SE-EVID-02.** Records are untracked build output. Each suite owns at most one record, replaced
atomically. A failed, interrupted, cached-only, filtered, empty, or skipped run writes no success
record, and the repository's prohibition on skipped tests is unaffected.

**SE-EVID-03.** The join between records and the current graph is deterministic. An exact identity
match yields `passed`; a suite record without the exact identity yields `superseded`; no record
yields `not_executed`. A missing record is never a failure verdict and never becomes one through
presentation.

**SE-EVID-04.** Suite evidence records suite execution only. It never equates suite success with
requirement acceptance, never covers unregistered work, and never replaces the evidence fields and
suite-specific records required by the repository testing document.

## Fixtures and instrumentation

**SE-FIX-01.** A prose fixture owns one scenario: setup, stimulus, required observations, forbidden
effects, variations, and limitations. It specializes linked requirements and introduces no competing
behavior. It carries a stable identifier and semantic revision.

**SE-FIX-02.** An executable fixture contains exactly one `zig tj-test` fenced block under an
exact `## Instrumentation` heading. Generation places its body verbatim into an ordinary Zig
`test` with the binding module's `Fixture` in scope. Zig owns the instrumentation language, type
checking, error propagation, discovery, execution, and reporting. The engine adds no expression
evaluator and no parallel assertion engine.

**SE-FIX-03.** Fixture methods use `given_`, `when_`, `then_`, and `forbid_` prefixes. Phase order
is enforced, at least one `given_` and exactly one `when_` are required, and each `then_` or
`forbid_` call maps uniquely onto a declared oracle present in both the prose and the claim set.

**SE-FIX-04.** A test specification owns identity, revision, suite, exact fixture revision and
fingerprint, production boundary, and the claims mapping each oracle to exact obligation revisions.
It never restates fixture prose.

## Strict synchronization

**SE-SYNC-01.** Prose fixtures, fixture binding sources, and implementation sources carry reviewed
SHA-256 fingerprints. Any byte change invalidates the reviewed link until the change is classified.

**SE-SYNC-02.** Updating a fingerprint records that a change was reviewed. It never advances a
semantic revision and never constitutes semantic acceptance.

**SE-SYNC-03.** Every source under the profile's implementation root belongs to exactly one
implementation unit. Every fixture implementation under the profile's binding root has exactly one
current binding.

**SE-SYNC-04.** Every executable product test originates from one instrumented prose fixture.
Handwritten product and binding sources contain no Zig `test` declaration. Engine self-tests run
only from the engine's own test target and never count as product evidence.

## Generation before linking

**SE-GEN-01.** Prefer generation whenever downstream content is derivable from one authoritative
owner. Generated code, tests, projections, manifests, and indexes contain no manually maintained
relationship.

**SE-GEN-02.** Use explicit links only where generation cannot decide: oracle to obligation, and
implementation unit to obligation.

**SE-GEN-03.** Transformations offered by the tool are explicit and on demand. One never chooses a
semantic relationship, never advances a semantic revision, and never runs from a read-only gate.

## Build integration

**SE-BUILD-01.** The build graph is derived from the registries. Adding a test specification, a
binding, or a suite changes no build file. A consumer's build reads the test and binding registries
and creates one generated test root, one module per binding, and one target per suite that has at
least one binding.

**SE-BUILD-02.** Every declared suite is either runnable or absent. A suite with bindings always has
a target; a suite without bindings has none. Suites are partitioned into local suites, which run in
ordinary gates, and reserved suites, which run only in the continuous-integration gate.

## Scaffolds and transformations

**SE-SCAF-01.** Scaffolds and authoring plans are disposable material written to standard output.
They mutate no registry, register no test, and claim no coverage. A generator may create a file that
does not exist yet when asked explicitly, and never overwrites one.

**SE-SCAF-02.** An unfinished generated implementation fails compilation through `@compileError`. It
never passes, skips, or reports coverage.

**SE-SCAF-03.** Gates validate before answering. Generators, transformations, and reports do not,
because their purpose is to resolve an inconsistent model. A command that repairs a condition never
refuses to run because of that condition.

**SE-SCAF-04.** Fingerprint synchronization is a transformation, not a decision. It reports every
digest it changes and restates that a semantic change still needs a revision increment and link
migration.

## Reporting

**SE-REP-01.** Status is derived, never stored. It distinguishes obligations that are unclaimed,
claimed but unbound, and executable, and separately reports whether an implementation unit realizes
them.

**SE-REP-02.** Reports state evidence, never sufficiency. An executable obligation means a generated
test exercises the claim, not that the requirement is completely covered.

**SE-REP-03.** Status derives requirement progress as `done`, `partial`, or `missing` from the
obligation graph, reports the first incomplete requirement as `next`, and exposes the same data in
human-readable and JSON output. Structural diagnostics include `status` as an inspection reference
when graph progress can help resolve the failure.

## Diagnostics

Diagnostics are the engine's only instruction channel. See [`DIAGNOSTICS.md`](DIAGNOSTICS.md).

**SE-DIAG-01.** Every failure names a stable code, the kind of disputed fact, its canonical owner,
the commands that inspect it and its dependents, the permitted resolution, and the command that
verifies the fix.

**SE-DIAG-02.** No consuming repository is expected to document engine usage. If an author needs a
procedure that is not derivable from a failure message or a generator, the diagnostic is defective
and is fixed in the engine rather than described in prose.