# The model

**Ends.** Surfex scans four kinds of thing, each with an id and a content hash (its
version):
- `spec`: a markdown section (`spec.md#anchor`, or `spec.md#Heading/Path`), a fenced
  block, or a test hint (```` ```test:hint-id ```` in the spec: a claim a test must verify).
- `code`: a module or function (`MyApp.Cart`, `MyApp.Cart.add/2`).
- `test`: one test case (`test:MyApp.CartTest: totals: an empty cart totals nothing`).
  A `describe` group is not an end; each test in it is.
- `class`: a kind of code the spec deliberately doesn't describe (`classes:` in config).

**Relations** have a type and two ends:
- `implements` code → spec · `verifies` test → spec · `tests` test → code (the test calls
  it) · `refines` spec → spec (a unit inside a section) · `depends_on` · `excuses` class → code.

**The log** (`.surfex/`) records each relation as entries, each at its ends' hashes, with
who, when, the commit and a note. The **tip** is the entry no later entry names as its
parent; it is the judgement in force. Nothing is edited or deleted; `mix surfex.log
--verify` detects tampering.

**States**, derived from the tip against the current scan:
- `current`: both ends at the recorded hashes.
- `dangling`: an end changed since; the report names which.
- `orphaned`: an end is no longer scanned (removed or renamed: see `move`).
- `planned`: recorded before its end existed (`relate --planned`).
- `conflicted`: two tips recorded without seeing each other (parallel branches).
- `retired`: put to rest.

**Basis**, how the tip was validated: `evidence` (test runs), `review` (a test judged
against the unit and run green), `judgement` (named by hand with a note; never for
implements), `baseline` (an adopted, trusted suite), `proposed` (a claim nothing has
validated: a citation, a tag before its failing run). A current `implements` or `verifies`
without a validating basis is **unvalidated**.

**Flags** reported beside states: new (in no relation), unmet (`require:` says it must
relate), broken (a tag naming no spec unit), broken citation (the spec names code that
doesn't exist), failed (a relation's test failed in the run, whatever validated it),
unproven (evidence doesn't bear a confirmation out), undeclared (a test no
longer tags the unit it verifies), unrecorded (a test tags a unit the log records no
`verifies` relation to, or only a retired one), moved (a block or hint no longer sits in
the unit its `refines` relation names), triangle gaps (a unit, its tests and its
code don't meet),
impacted (a `depends_on` end isn't current; information only), marks (`mix surfex.info marks`).