ADR-0040: The traceability representation, and where Phase C's edges come from

  • Status: accepted
  • Date: 2026-10-28
  • Deciders: Theurian maintainers
  • Requirements: FR-T2, FR-T3, INV-6, SEC-13, SEC-15
  • Resolves docs/roadmap.md §9 ADR candidate 4 — formalising the traceability representation (#275)
  • Situates against ADR-0038 (the id space a trace endpoint lives in, and the gate properties its Positive lists), ADR-0039 (how a closed set changes), ADR-0029 (the Git trailer reader Core already has), and ADR-0007, ADR-0016 and ADR-0017 (what the state hash covers, and the exact-match schema version)

This ADR records a decision and ships no code. No enum member, operation, schema, table or tool moves here. Its implementation is three issues: edge collection and INV-6 enforcement (#1033), the knowledge.trace tool (#1034), and Phase C's exit demonstration (#1035).

Every repository fact below was measured on 2026-10-28 against origin/main at 5ad30799. Source paths are relative to packages/theurian-core/src/theurian/; paths beginning docs/, schemas/ or .theurian/ are from the repository root. Each count names its key, run at 5ad30799, and is marked dated — a measurement #1033–#1035 are expected to move — or standing — an invariant this record rests on, so a change that moves it must move this record too. Line cites outside Context were re-measured in

1033's schema-v5 pull request (#1059);

Context's are as measured at 5ad30799.

Records this decision moves. Decision 3 narrows ADR-0038 decision 2, which required a spec id named by an edge source to be resolved to its item id when the edge is populated. Decision 2 keeps ADR-0016 decision 4's "Git is simply not consulted when computing the hash" true, and ends what it implied: a state's contents are no longer a function of its hash alone. Decision 8 adds a ninth set to the eight ADR-0039 decision 1 governs. Decision 5 settles which relations INV-6 covers, which two other records state differently (F8). Each of those records carries an amendment pointing here, in this pull request (Compliance). The roadmap's Phase C Architecture row, which planned three edge sources, is corrected with this record.

Context

What exists

  • F1. (dated) The dogfood corpus has 26 items, 24 of them ADR twins, against 40 ADR files. The twins anchor ADR-0001 to ADR-0024; ADR-0025 to ADR-0040 have no twin.

sh # 26 unique item ids created git ls-tree -r --name-only 5ad30799 .theurian/migrations/ | grep '\.yaml$' \ | xargs -I{} git show 5ad30799:{} | grep -A1 -e '- op: createItem' \ | grep -o 'itemId: .*' | sort -u | wc -l # 24 items created by a migration whose revision anchors a docs/adr/ file for f in $(git ls-tree -r --name-only 5ad30799 .theurian/migrations/ | grep '\.yaml$'); do git show 5ad30799:$f | grep -q 'filePath: docs/adr/' \ && git show 5ad30799:$f | grep -A1 -e '- op: createItem' | grep -o 'itemId: .*' done | sort -u | wc -l # the 24 ADR numbers anchored: 0001 to 0024 git grep -h -o -E 'filePath: docs/adr/[0-9]{4}' 5ad30799 -- .theurian/migrations | sort -u # 40 ADR files git ls-tree --name-only 5ad30799 docs/adr/ | grep -c -E '/[0-9]{4}-'

  • F2. (dated) The corpus holds no relation and no specification. The op key prints two lines, 58 op: createItem and 58 op: upsertRevision: 0 addRelation, 0 deprecateItem and 0 registerSpecification. addRelation and deprecateItem are the only operations that write a relation row — the engine's two writer.add_relation( calls, application/migration_engine.py:506 for deprecateItem's supersededBy and :522 for addRelation — so the dogfood state holds no relation row.

sh git grep -h -o -E 'op: [A-Za-z]+' 5ad30799 -- .theurian/migrations | sort | uniq -c git grep -n 'writer.add_relation(' 5ad30799 -- packages/theurian-core/src

  • F3. (dated) scope.paths does not discriminate between modules. Of the 58 revisions (F2), 56 carry scope.paths, and their sorted glob sets take exactly three values: 48 packages/theurian-core/**, 7 '**' (quoted so in the YAML) and 1 plugins/**. None names a module or a file. A module under packages/theurian-core/ matches 55 of the 56 (48 + 7).

sh git ls-tree -r --name-only 5ad30799 .theurian/migrations/ | grep '\.yaml$' \ | xargs -I{} git show 5ad30799:{} \ | python3 -c 'import re,sys,collections; print(collections.Counter(tuple(sorted(g.strip()[2:] for g in m.split("\n") if g.strip())) for m in re.findall(r"\n\s+scope:\n\s+paths:\n((?:\s+- .*\n)+)", sys.stdin.read())))'

  • F4. (dated) No commit on main carries a Refs: trailer; 380 lines of its history mention an ADR number. The first key prints 0. The second counts lines, not commits: a commit naming two ADRs on one line counts once, on two lines twice.

sh git log 5ad30799 --format=%B | grep -c -E '^Refs: ' git log 5ad30799 --format='%H %B' | grep -c -E 'ADR-[0-9]{4}'

  • F5. (dated) No adapter implements the edge port. CanonicalStore declares add_traceability_edge and list_traceability_edges (domain/ports/canonical_store.py:371, :373). The key prints nothing; without its grep -v it prints those two port lines, which is its positive control.

sh git grep -n -E 'def (add_traceability_edge|list_traceability_edges)[(]' 5ad30799 \ -- packages/theurian-core/src | grep -v ports/

  • F6. The table and the version check. (dated) traceability_edges (infrastructure/sqlite/schema.py:386-398) has no source_commit column, and SCHEMA_VERSION is 4 (schema.py:58). (standing) is_supported returns schema_version == SCHEMA_VERSION (schema.py:468) — "deliberately no compatibility window" (ADR-0017). _connect opens a state database in three places (infrastructure/sqlite/connection.py:1044, :1069, :1415): create_database, which writes the DDL into a new file, and the two openers of an existing one, open_read_connection and the write transaction's. Both run _prepare (:1046, :1417), whose _assert_schema_version (:980) reads schema_metadata's schema_version and nothing else before refusing a mismatch.

sh git grep -n -E '^SCHEMA_VERSION|return schema_version == SCHEMA_VERSION|_assert_schema_version\(|_prepare\(connection|_connect\(database_path' \ 5ad30799 -- packages/theurian-core/src/theurian/infrastructure/sqlite

  • F7. (standing) An addRelation endpoint is always an item id. $defs/opAddRelation requires sourceItemId and targetItemId, each a $ref to #/$defs/itemId, and sets additionalProperties: false, so a module cannot be an endpoint of a migration-declared relation.

sh git show 5ad30799:schemas/migrations/migration.schema.json | python3 -c 'import json,sys; d=json.load(sys.stdin)["$defs"]["opAddRelation"]; print(d["required"], d["properties"]["sourceItemId"], d["properties"]["targetItemId"], d["additionalProperties"])'

  • F8. INV-6 is declared and not enforced, and three records disagree on its set. (dated) KnowledgeRelation.must_be_acyclic (domain/knowledge.py:470) has no caller in src: the key prints nothing, and the same key over packages/theurian-core/tests prints two lines, the call at test_domain_invariants.py:342 and a docstring at test_adr_0038_claims.py:172, its positive control. The three sets: docs/architecture/requirements-analysis.md:1027 says supersedes; ACYCLIC_RELATIONS (domain/enums.py:104) holds supersedes, superseded_by and depends_on; docs/roadmap.md:604 says supersedes and depends_on.

sh git grep -n -E '\.must_be_acyclic([^a-z_]|$)' 5ad30799 -- packages/theurian-core/src

  • F9. (dated) TraceNodeType has 12 members and no commit (domain/enums.py:160-174), and ADR-0039 never names it: git show 5ad30799:docs/adr/0039-closed-set-extension-compatibility.md | grep -c TraceNodeType prints 0. TraceabilityEdge.relation_type is typed str (domain/specification.py:88).
  • F10. (dated) ingest reads no Git history and writes no state. Its docstring (cli/commands.py:3246) names .theurian/cache/ingestion.json as the only file written. Its Git reads are current_commit and repository_url (cli/commands.py:3316-3317), which run git rev-parse HEAD and git remote get-url origin (cli/context.py:84, :115). The only git log invocations in src are the two adapters under infrastructure/git/, imported by cli/findings_commands.py and mcp/tools.py and not by ingest. The state database, where traceability_edges lives, is created on the migrate apply path (cli/migration_pipeline.py:211, :374; cli/commands.py:2657).

    sh git grep -n -E '"log",' 5ad30799 -- packages/theurian-core/src

  • F11. (dated) system.capabilities publishes "traceability": False, hard-coded at mcp/tools.py:3325.

  • F12. (dated) The relation gate reads each endpoint non-resolving and body-free. _relation_is_visible (mcp/tools.py:1124) reads both endpoints through get_item_exact_metadata (infrastructure/sqlite/store.py:516), whose _ITEM_METADATA_SQL (store.py:1657) selects knowledge_items metadata columns WHERE project_id = ? AND item_id = ? and consults no alias.

Two further facts the decisions rest on

  • (standing) A label names no single item. A revision's labels are a JSON list in knowledge_revisions.labels (schema.py:259), and the migration schema's $defs/revisionMetadata/properties/labels is uniqueItems within one list only, so nothing makes a label unique across items. A label's grammar is a string of at most 64 characters, so adr-0040 is both a valid label and a valid item id.
  • (standing) The state hash reads no Git. Its inputs are the migrations, their body checksums, SCHEMA_VERSION and MIGRATION_ENGINE_VERSION (StateInputs, domain/state.py:47-54), and decision 2 keeps it so. (dated) Every CLI command that resolves a project computes it, in resolve_context (cli/context.py:262). Search compares a published index build's recorded hash against the current one and labels the answer stale when they differ (mcp/search.py:655), and index status reports indexStale on the same comparison (cli/index_status_report.py:217).

What the roadmap planned

Phase C's Architecture row planned "Three edge sources to start: ① migration declarations (addRelation, existing), ② commit trailers (Refs: ADR-0021) collected by ingest, ③ scope.paths". Measured against the corpus, ① can reach no module (F7), ② has no instance on main (F4), its example names an ADR number rather than an item id, and ingest writes no state (F10), and ③ names no module (F3). The exit criterion — "why is this module shaped this way" traces to an ADR — needs an edge from a module to an item, and none of the three supplies one today.

Decision

1. The edge source: a Refs: commit trailer naming a literal item id

From this ADR onward, a commit declares that it relates to a knowledge item with a Refs: <item id> trailer, and that trailer is Phase C's one edge source. For each path the commit changed, it yields one edge:

  • source TraceNode(CODE, <the repository-relative path>);
  • target TraceNode(KNOWLEDGE, <the item id>);
  • relation related_to, confidence 1.0;
  • evidence SourceAnchor(commit_sha=<the commit>, file_path=<the path>), and the same commit as the edge's source_commit (decision 4).

The commit is evidence of the edge and its measurement point, not a node, so TraceNodeType needs no commit member (F9). The source needs no new migration operation and no new closed-set member: CODE, KNOWLEDGE and related_to all exist. Under roadmap §9 item 3 as ADR-0039 recorded it — "a new kind or RelationType member is additive, a new operation bumps apiVersion" — this source moves neither.

Main has no Refs: trailer today (F4), so recorded edges begin at the convention's first commit. No commit before it carries anything to collect, and a trace response claims no coverage (decision 7).

related_to, not constrained_by. The declaration is made once per commit and projected onto every path the commit changed. constrained_by would assert, of each of those paths, that the item constrains it — of a lockfile or a fixture the same commit touched, that is an overclaim. related_to asserts only what the evidence holds: a commit that changed this path declared this item. Confidence 1.0 records that the declaration is explicit, a person wrote it, which is what confidence separates in traceability.md ("Explicit edges get confidence 1.0"); it is not a strength of relation.

Every path is a CODE node. The collector does not classify paths: calling one TEST by its name would be inference, and an inferred node type on an explicit edge would mix the two things confidence exists to keep apart.

The four alternatives, with their keys: every source the roadmap or traceability.md names that exists here today; review threads and test names are collected nowhere (Neutral).

Source Measured Verdict
(i) Refs: <item id> trailer 0 lines on main (F4) Chosen. Explicit, per commit, reaches a path
(ii) Prose mentions in commit messages, ADR-NNNN 380 lines (F4) Rejected. Roadmap §10 names false traceability the product's largest risk, and a mention is not a declaration: a message saying "unlike ADR-0007" mentions it. A mention names an ADR number, which needs resolving to an item (decision 3), and 16 of 40 ADRs have no twin (F1). If ever added, it is a distinct source, with a published confidence below 1.0 and field names that keep it apart from recorded edges
(iii) Hand-authored addRelation migrations 0 in the corpus (F2) Rejected. Item to item only (F7). Reaching a module needs either a new operation — an apiVersion bump under ADR-0039 decision 3, and an owner decision — or modules entered as items, which is a new kind, additive under ADR-0039 decision 2 but due only after #849 and #853, and a governed item per module. addRelation rows stay item-to-item edges that knowledge.trace walks (decision 7)
(iv) scope.paths globs 55 of 56 match any core module (F3) Rejected. An edge from every core module to nearly every item says nothing. It stays a candidate source once the corpus's globs are module-level

2. Every apply collects, over first-parent history at HEAD; the commit is recorded, not hashed

Collection runs inside the state build — the write transaction migrate apply already runs (apply_migration_set, cli/migration_pipeline.py) — after the migration set applies. It resolves HEAD once to the walk commit's OID — a second read of HEAD can name another commit — reads from that OID alone each first-parent commit's Refs: trailers (decision 3) and the paths it changed against its first parent, and writes the edges into traceability_edges.

Every migrate apply collects, including one with nothing pending, and replaces the whole edge set, the recorded walk commit and the boundary inside its write transaction. It is a full replace, not an incremental walk from the stored commit: after a rebase or a reset, the stored commit is not an ancestor of HEAD. The expected-count record keeps its condition (cli/migration_pipeline.py:146), because edges are not that record.

The walk commit is recorded, not hashed. It is §6 principle 2's "commit it was measured against", recorded in schema_metadata (decision 4) and published by every trace (decision 7). Principle 2 asks a response to state its commit, not that every commit invalidate the state, and ADR-0016 rejected a commit sha in the hash: "a code-only commit touching no knowledge would invalidate a valid state". A commit that changes no migration and no body a migration references leaves state_hash unchanged.

A state's identity is (state_hash, walk commit, boundary), and two states with one identity hold the same edges; a state whose collection was capped or bounded never shares an identity with one whose was not. state_hash names the canonical state (ADR-0016) and, through MIGRATION_ENGINE_VERSION, the collector's rules, so a change to them, the bounds and caps below among them, bumps it. The boundary is what the walk left uncollected: the shallow digest, whether the depth bound or the read budget stopped it, and the capped digest. The collector reads Git and nothing else (decision 3(b)), so after an apply the edges are a function of the objects first-parent-reachable from the walk commit, the shallow list and those rules alone: no environment variable, no configuration at any level, and no replace ref, graft or commit-graph reaches them. That holds under the prerequisites an independent source read names, each held below or recorded outside the claim:

  • Plumbing, over the walk OID. git rev-list --first-parent --parents <OID> lists the commits, every line OIDs or the build refuses, and each is one stdin record of git diff-tree --stdin -r --root --no-renames --name-status -z --always --ignore-submodules=none: C P1, or C for a root or shallow-boundary commit, so no merge-mode default applies (at 2.56, -m --first-parent diffs a merge against every parent). --name-status keeps a path named like the next commit's OID from reading as its header; --always gives an empty commit its record. The build refuses unless diff-tree returns one record per commit fed, in order — it drops an unknown stdin commit with status 0 — and unless #1012's log form, under -c i18n.logOutputEncoding=UTF-8, reads the messages in rev-list's sequence. Under --no-renames a rename yields both paths.
  • #1012's bound, its module docstring verbatim: "With each spawn's own flags it neutralises every documented git feature that can make a deciding read admit what this repository's own objects do not, except two that are tracked: an attribute-driven conversion on the committed check (#1015) and, below git 2.45, the fetch child's reading of repository config (#1016). Features that can only make a read refuse are outside this bound. A direct write to the object store, a cache file or a ref can still forge any answer." Every spawn runs under its child_environment and argv prefix, unchanged — which keep tracing out of every captured stream (#1012's 342ea607) — plus --no-pager and -c core.fsmonitor=false: a configured fsmonitor hook runs during diff-tree's index read and moved its output. The cache files are one class, kept out of every read by -c core.commitGraph=false and -c core.multiPackIndex=false. --ignore-submodules=none closes submodule.<name>.ignore in configuration and in the worktree, index or HEAD .gitmodules, each of which moved the output without it.
  • Outside the claim: object-store integrity, alternates included, is #1012's direct-write residual; a corrupt index, core.maxTreeDepth, malformed configuration and safe.directory can only make a read refuse; the git executable's identity is a process prerequisite; and behaviour below git 2.56 is established only where the source read cites a version. #1015 does not reach a read of names, which converts no content; #1016 does not reach a walk that #1012's environment keeps from fetching. Key: independent source read, Codex, 2026-10-29, git 2.56.0 sources; re-check python3 -I probe.py, b_plumb3.py and b_framing.py (#1036's round record), which #1033's determinism tests become.
  • A commit message that is not UTF-8 is contained to its own record (#496) and reported by its sha only, so 3(a)'s "never echoed" holds; ADR-0029's reader keeps up to 120 bytes of it (trailer_source.py:182, :423). A path git emits that is not UTF-8 is not collected.
  • An edge's id and created_at derive from its commit — the sha, the path and the item id; the committer date — never from the engine's clock or an id generator. The evidence's required source_uri derives from the commit and the path, never from git remote get-url origin, which differs between clones and prints a filesystem path for a local remote — an operator's layout, the class GHSA-923w-f36f-jcfq closed in MCP error responses.
  • A failure to read HEAD, a walk that fails or outlives the 30-second subprocess timeout (infrastructure/git/trailer_source.py:95), and a stream the framing cannot read refuse the build. None of them degrades to "no edges", because then one identity would name two edge sets. current_commit returns None for an unborn HEAD and a failure alike (cli/context.py:89-102), so the collector reads HEAD through a call that tells the two apart.

What git emits to the walk is bounded by recorded constants: at most 10,000 first-parent commits, the walk commit first, and a read budget of 100,000 path entries and 64 MiB, counted as each stream arrives, never read whole, capped commits included. Git is terminated where a commit would cross a bound; it and every older commit are not collected, and the boundary records which bound stopped the walk. A commit listing more than 1,000 paths yields no edges and joins the capped digest, all or none by 3(c)'s rule. So one apply writes at most 32 × 100,000 = 3,200,000 edges. A bound stops every machine at the same commit; under a time limit the edge set, or whether migrate apply succeeds for any tool, would vary with the machine's load. At 5ad30799 the walk reads 427 commits (git rev-list --first-parent --count 5ad30799), 3,998 path entries, at most 99 in one commit, and 2,061,969 bytes, in 71 to 87 ms here. The budget is 25 and 32 times that read, the depth 23 times this history, the per-commit cap 10 times its largest commit; at its mean of 9.4 entries and 4.8 KB per commit the depth binds first, near 93,600 entries and 48 MB. At the budget the read took at most 0.68 s (Negative, third item), 44 times inside the 30-second timeout, which git's own reads can still cross (Negative, fourth item).

It reads HEAD, not ADR-0029's refs/remotes/origin/main, which ADR-0029 pins so that no embargoed finding enters a corpus built from it: an edge describes the branch the state describes (ADR-0016), in its own state database.

First-parent is the line the branch itself records. Under this repository's squash merges it is the whole history (git rev-list --merges --count 5ad30799 prints 0). In a merge workflow a side-branch commit's trailer is collected only when the merge commit's message carries it (Negative).

The collector never discovers a repository. apply_migration_set takes the root the composition root resolved (find_git_root, cli/context.py:61, :257) or None. None collects nothing and records the walk commit and the boundary as null, as an unborn HEAD does; a trace then reports a null commit and zero edges walked. With a root, every read names it (--git-dir), or the collector refuses unless rev-parse --show-toplevel equals it. The rehearsal passes None: with TMPDIR inside a clone, its throwaway copy discovered that clone and read its history (measured), so cli/migration_pipeline.py:71-75's comment is #1033's to restate.

On a shallow clone, the walk stops at the shallow boundary. The shallow digest is the lowercase hex SHA-256 of the clone's shallow-commit list — the lines of the file git rev-parse --git-path shallow names, sorted byte-wise, each followed by a newline — and null when no such file exists, which is a full clone. The build refuses unless every line is exactly one lowercase hex OID of the repository's hash length. A commit the list names yields no edges: its parent is absent, so its C record diffs it against the empty tree. In a depth-2 clone at 5ad30799 the boundary commit 54a9f673 lists 1,159 paths, its whole tree (git ls-tree -r --name-only 54a9f673 | wc -l), against the 2 the full history lists. A trace publishes the shallow flag, not the digest (decision 7). The build reads the digest before the walk and again after it and refuses unless the two are equal, since rev-list and the log form each read the list again; a list rewritten and restored between the two reads passes, by construction, and is outside the identity claim above.

Amended in Phase C, by #1033. The derivation said "the shas in the file", which read as its whitespace-separated tokens. Git reads the file one OID per line, so one line holding two OIDs and two lines holding one each gave one token-wise digest and two different walks (measured on #1036). The digest is over the file's lines, and a line that is not exactly one OID refuses the build.

Not in ingest (F10), and not a new command: either gives the state database a second writer whose run is optional, so whether a state held any edges would depend on a command nothing else requires.

3. The trailer grammar: a literal item id, untrusted, never resolved

  • Extraction is ADR-0029's rule. A Refs: trailer is a line of the whole commit message, subject included, that begins at column 0 with exactly Refs: — ADR-0029 Amendment 1's D1, which keyed_lines (domain/review_finding.py:293) implements for Review-Finding: — so one placed above the Signed-off-by: paragraph is read, and an indented or quoted one is not. Its value is the rest of that one physical line with surrounding ASCII whitespace removed. One item per line; a commit naming two items carries two lines, and a repeated id yields one edge per path.
  • The value is untrusted. A commit message is author-controlled bytes, the same standing as indexed content under T-3.
  • (a) A value that is not a valid item id is not collected and never echoed. Valid means the whole value is an ItemId: _DottedId's _DOTTED_PATTERN, at most MAX_IDENTIFIER_LENGTH (200) characters (domain/identifiers.py:35, :44, :128-144). An invalid value yields no edge, and no message, log line, report field or error carries it. That includes the InvalidIdentifierError _DottedId raises, whose message repeats the value (got {value!r}, identifiers.py:143), so it is caught and its text discarded. The build reports to its operator the commit's sha and how many values it refused, never their text. Refs: ADR-0040 (upper case), Refs: #1033 and Refs: a.b, c.d all fail.
  • (b) A valid id that names no item when the state is built is recorded. Three reasons. The collector then reads Git and nothing else, so the stored edges are a function of history alone and identical in two corpora that differ only by a withheld item; a drop-on-absence rule would store the edge where the item exists and is withheld, and not where it is absent, so the edge table itself would vary with withheld content. The per-hop gate withholds a missing endpoint (decision 6), so a recorded edge to an absent id surfaces exactly what one to a withheld item does: nothing. And a dropped declaration is an edge the contributor believes exists; a recorded one starts to surface, through the gate, at the first build in which its item exists, with no rewrite of history. Observable consequence: no knowledge.trace response shows such an edge, counts it, or gives it a slot. The build report counts, per commit, recorded edges whose item endpoint named no item at that build — a CLI surface read by an operator who can read every migration — and that is where a typo becomes visible. Decision 9's rows 1, 2 and 5 hold it on the wire. Refs: adr-0040 is this case: a valid _DottedId that names a label, not an item, recorded and inert.
  • (c) A commit naming more than 32 distinct valid ids yields no edges, and the boundary records it. Its edges are one per id per changed path, both sizes its author chose. The count takes every distinct valid id, item or not, so the cap reads Git alone ((b)). All or none, since a partial rule needs an order among ids. The capped digest is the lowercase hex SHA-256 of the capped commits' shas, sorted byte-wise, each followed by a newline, and null when there are none; the build reports each sha, never its values, as (a) does. It does not refuse, or every capped commit would refuse every later build that walks it; the timeout does, for content that drives git's own reads past it (Negative, fourth item). 32 is over four times the most distinct ADR numbers one commit message on main names, 7 at f665ecf6, the nearest measure while main has no Refs: trailer (F4): git rev-list 5ad30799 | while read c; do git log -1 --format=%B $c | grep -o -E 'ADR-[0-9]{4}' | sort -u | wc -l; done | sort -n | tail -1.
  • Collection resolves no alias and no label. A label names no single item (Two further facts). An alias is an author-chosen key whose target a later migration moves, so a resolved edge would point wherever the alias map of the build's migrations sent it, not at what the commit's author named; and resolution feeding an authority decision is exactly what T-21 found leaking. Resolution would also read canonical rows, which (b)'s first reason keeps out of the collector. This narrows ADR-0038 decision 2, which required a spec id named by an edge source to be resolved to its item id at population: for this source, the trailer names the item id itself.

4. The schema: source_commit, and SCHEMA_VERSION 4 → 5

traceability_edges gains source_commit TEXT NOT NULL — every edge is measured against a commit, roadmap §10's "mandatory commit anchor". The commit is also inside evidence, but that column is a JSON array SQL cannot index or compare, and a later source may carry evidence from several commits while source_commit names the one it was measured against. relation_type holds a RelationType value, and #1033 narrows TraceabilityEdge.relation_type from str (F9) to RelationType; roadmap §4 keeps edge types closed. schema_metadata gains decision 2's walk commit and boundary — the shallow digest, the depth and budget flags and the capped digest — all null with no walk.

These are DDL changes, so SCHEMA_VERSION goes from 4 to 5. Under the exact match (F6), a v4 build refuses a v5 database and a v5 build a v4 one, per database, at open, in _assert_schema_version, before any row other than schema_metadata's is read. That is the shape #853 requires: decided per database, never per row. SCHEMA_VERSION is also a state-hash input (domain/state.py), so on the build path a v5 Core never selects a v4 database's name. Re-check, after #1033: the key under F6 prints SCHEMA_VERSION: Final = 5, the exact comparison, and the opener's call.

5. INV-6: one set, enforced over the graph an apply leaves

The set is ACYCLIC_RELATIONS as declared — supersedes, superseded_by and depends_on — read as two graphs. In the supersession graph a stored superseded_by row from A to B is the supersedes row from B to A (INVERSE_RELATIONS, domain/enums.py:95-100); checked apart, a cycle that alternates orientation (A supersedes B, A superseded_by B) would pass. The dependency graph is depends_on alone. A loop mixing the two graphs violates neither reason enums.py records — "a superseded chain that loops has no current revision, and a dependency loop has no resolution order" — so it is not refused. The requirements row's supersedes alone is the record that is too narrow, and the roadmap's supersedes and depends_on names the inverse only implicitly (F8); both owe the set stated here.

Enforcement is a whole-set guard in the migration engine, run inside migrate apply's write transaction after the set's operations, over every relation row of the project the apply leaves — whatever operation wrote it, addRelation or deprecateItem's supersededBy (F2). A later removeRelation in the same set therefore cures an earlier cycle, and no applied document, which is frozen, ever needs editing. A refusal rolls the transaction back. Ids the alias map connects, through any chain, are one node, since list_relations resolves an alias first (store.py:927-941), so a rename whose supersededBy names its successor is refused.

The refusal is a new RelationCycleError, a MigrationError, not MigrationCycleError. That one means a dependsOn cycle among migrations, so "no application order exists" (domain/errors.py:116-122); it carries migration ids, and the CLI's remedy for it is "Break the dependency cycle shown above, then retry." (cli/commands.py:767-768). A relation cycle's cure is a new migration with a removeRelation, so the new error names the relation type and the cycle's item ids, and its remedy says that. The guard is in the engine, so the error reaches every CLI site that replays a set: the first key below prints six wiring sites, five of them reachable, and each surfaces the error its own way:

  • migrate apply: the error and its own remedy, exit 4;
  • migrate validate: the error text in permissiveMovesUnavailable, with valid still true — ADR-0027 decision 2's recorded design, which #1056 re-decides;
  • theurian propose, for an item the set creates, and propose accept: the error text inside their own refusal, whose remedy names migrate apply when the landed set holds the cycle, and the proposal's file when its own relations close it;
  • okf import, for an item the set creates: the T-25 refusal literal, which names only the class of the proposal service's refusal, ProposalError.

The sixth, okf_commands.py:382's rehearsal, is unreachable: okf import holds its service through DraftOnlyProposals, whose __slots__ are the two draft entries, and of ProposalService's public methods only accept reaches self._rehearse. The MCP composition root wires the rehearsal to _accept_is_unreachable (mcp/tools.py:1973), so no MCP response carries it.

# the six wiring sites; 9 lines without the ':!' exclusion
git grep -n -P '\b(apply_migration_set|rehearse_migration_set|current_item_in|permissive_moves_in)\(' -- packages/theurian-core/src/theurian/cli ':!packages/theurian-core/src/theurian/cli/migration_pipeline.py' | grep -v -E ':[0-9]+:\s*(#|def )'
# what `okf import` holds, then the public methods reaching the rehearsal:
# ['accept'] from _rehearse, and ['accept', 'draft'] from _current_item
grep -n '__slots__' packages/theurian-core/src/theurian/application/draft_only_proposals.py
python3 -I - packages/theurian-core/src/theurian/application/proposal_service.py _rehearse <<'EOF'
import ast, sys
tree = ast.parse(open(sys.argv[1]).read())
cls = next(n for n in tree.body if getattr(n, "name", "") == "ProposalService")
uses = {f.name: {a.attr for a in ast.walk(f) if isinstance(a, ast.Attribute) and getattr(a.value, "id", "") == "self"} for f in cls.body if isinstance(f, ast.FunctionDef)}
reach = {sys.argv[2]}
for _ in uses:
    reach |= {name for name, used in uses.items() if used & reach}
print(sorted(name for name in reach if not name.startswith("_")))
EOF

What an existing cyclic corpus meets. The dogfood corpus meets nothing: it holds no relation row (F2). Corpora in other repositories cannot be measured from here. One with a cycle meets RelationCycleError at its first apply under the enforcing Core, naming the cycle; until a migration removes a relation of it, that Core publishes no state for the project.

No apiVersion, protocolVersion or MIGRATION_ENGINE_VERSION bump. ADR-0039 decision 6 sends a change that "moves which rows a gate reads", relation rows among them, to "decision 8's ADR-first route"; this record is that ADR. Decision 6's engine-version path is for when "a Core must change what an earlier-version document does" — "#841's case, where the table the retired operations write goes away". Refusing a set the old engine applied reads as that case and is not: the guard adds a refusal and writes nothing, so it changes which sets are accepted, not what an accepted operation does, and an engine bump — the version "still describes the engine, not the format" (ADR-0039, Neutral) and is hashed into the state hash — would invalidate every state built from an acyclic set to buy nothing. The one set whose outcome changes was never valid: INV-6 predates the format — its row arrived in 481bd0f0, four commits before the migration schema's first commit, 0f8c387d (git rev-list --count 481bd0f0..0f8c387d prints 4). No operation's meaning changes and no wire field moves, so apiVersion and protocolVersion stay. The refusal is a break — a Core MINOR before 1.0, a MAJOR after (ADR-0039, The matrix) — named BREAKING in the CHANGELOG.

The guard validates the whole relation set the apply leaves, on every apply, including one with nothing pending, so a cyclic set built by a non-enforcing Core is refused at its next apply. Without the nothing-pending clause, "next apply" would not reach a project that adds no migration.

Why the guard ships with schema v5 (read from source, not run). A refused apply rolls back and publishes nothing, and the serve path opens the pointer's state without reading engine_version (ADR-0039, Context) or the relation set. A cyclic state built at the enforcing Core's own SCHEMA_VERSION would therefore hash identically, be reused, and keep serving after its refused re-apply: the failure Compliance's sequencing condition (#1033) prevents. Under that condition, every state an enforcing Core serves or applies into was built by an enforcing Core. A state a non-enforcing Core built is v4: the enforcing Core refuses it at open (_assert_schema_version, infrastructure/sqlite/connection.py:1083-1089) and names another database for the project, since SCHEMA_VERSION is a state-hash input (resolve_state_hash(loaded, SCHEMA_VERSION), cli/context.py:273, cli/migration_pipeline.py:209, :362), which only the enforcing apply builds.

6. The per-hop visibility gate

The roadmap's Phase C Security row states the requirements. Its T-21 and T-26 sentences, verbatim:

Apply the per-edge visibility gate at every hop — and apply it in T-21's corrected form, because per-edge gating on its own is what leaked: a traversal hop must not resolve an alias when deciding authority.

Reachability may resolve; the visibility decision on each hop's endpoint reads the literally-named row's metadata — through get_item_exact_metadata or an equivalent that neither resolves an alias (T-21) nor reads the body (T-26), never the joined get_item_exact: a gate on that read materialises a withheld endpoint's body before withholding it, so the refusal's duration carries the body's size.

Write the two-corpora equality test for trace responses in the same change as the implementation — not afterwards.

Its next sentence, verbatim except that its link to ADR-0038 is rewritten for this directory:

An equivalent must also keep the existing gate's other properties, which ADR-0038 Positive lists: both endpoints judged on status and sensitivity (may_surface, may_disclose), with no direction inference; a missing endpoint withheld; and the read scoped to the project, as _ITEM_METADATA_SQL's project_id scopes it — a TraceNode carries no project, so it cannot scope the read.

Decided. Every item endpoint a hop reaches is read by the id it literally names, through get_item_exact_metadata or an equivalent that keeps all of the above, and judged on may_surface and may_disclose:

  • Both endpoints, no direction inference. A knowledge_relations row is judged on both of its items, as _relation_is_visible judges it (F12). A traceability edge has one item endpoint under decision 1, and it is judged whichever way the hop crossed the edge.
  • A missing endpoint is withheld, exactly as a withheld one is.
  • The read is scoped by the edge's project_id. Edges are listed by the request's project — both edge indexes lead with project_id (schema.py:425-426) — and each endpoint is read in the edge row's project_id, which that listing makes the request's. A TraceNode carries no project, so the edge row is the only thing that can scope the read. #845's M-4, the gate's project scope, becomes an acceptance criterion of #1034: a real store holding two projects, an edge in one naming an item id that exists only in the other, and a trace from either that surfaces nothing of the other.
  • An external endpoint surfaces only as the endpoint of an edge whose item endpoint passed. A CODE node is never judged on its own; it appears because an edge from it reached a visible item, or because the caller named it as the start. An edge with no item endpoint therefore surfaces nothing, and no source this ADR admits writes one.

7. The response: recorded edges, a commit, no coverage claim

Fields. Every knowledge.trace response carries §6 principle 2's three statements, under names that say recorded edges:

Field Carries
recordedEdgesCommit the commit the state's edges were collected at (decision 2); null with no Git history
recordedEdgesWalked how many recorded edges the traversal walked — counted after the gate, so only edges whose endpoints passed
recordedEdgesHistoryShallow whether collection stopped at a shallow boundary
recordedEdgesDepthBounded whether collection stopped at the depth bound (decision 2)
recordedEdgesBudgetBounded whether collection stopped at the read budget (decision 2)
recordedEdgesCapped whether collection skipped a commit over a per-commit cap (decisions 2 and 3(c))
recordedEdgesCoverage the constant "not-claimed": the response asserts nothing about edges that were never recorded

Descriptions say recorded edges and never claim completeness (Phase C Risks). Evidence and confidence pass through unchanged from the stored edge. A knowledge_relations hop is published with exactly the fields knowledge.get's relations publishes for that row after the same gate, so trace publishes no field of a relation that knowledge.get withholds. No title, body or excerpt of any item is in a trace response; a caller reads content through knowledge.get. Every response carries SEC-15's triple, SAFETY's contentClassification, mayContainInstructions and executable (mcp/results.py:45-49): a hop's note, a CODE id and an evidence path are author-controlled text (T-3).

What a hop follows. A recorded traceability edge, in either direction — related_to is not in INVERSE_RELATIONS, so an edge stored from a path to an item is also walked from the item — or a knowledge_relations row.

Limits, as numbers. Depth at most 4, default 2 — the chain the roadmap's User value names, code → PR → spec → ADR → requirement, is four hops. At most 100 nodes and 500 edges per response. Every limit counts units that passed the gate, so a withheld node never takes a slot; reaching one sets truncated. Each endpoint is read at most once per request. The pre-gate rows a request reads are bounded by 100 times the largest stored fan-out of a node; with each node's edges listed once, its edge rows are at most twice the 3,200,000 one apply writes (decision 2), and its relation rows are the corpus's. #1034 records the measured cost on the dogfood corpus.

The start node. An absent or withheld item id gets knowledge.get's absent-id refusal, byte for byte. A CODE start is the caller's own string, not gated; it reaches only what its edges reach through the gate.

8. Governed parameters, and TraceNodeType joins ADR-0039's sets

knowledge.trace's edge-type, direction and node-type parameters are typed str in the handler and parsed by _closed_value (mcp/tools.py:1253), never annotated with a Literal or an enum. An annotation reaches the input schema the SDK serves for the tool, the form #856 records ADR-0039's tripwires missing; a str whose description names the set keeps a new member off the wire contract, as ADR-0039 decision 9's ground requires. The response publishes node and relation types as strings for the same reason.

TraceNodeType joins ADR-0039's governed sets, as a vocabulary set, because #1034 makes it wire-visible and #1033 stores it in the derived state — the two faces ADR-0039 governs for kind and relationType. Its publication is the trace wire and the state, not the migration format, so ADR-0039 decision 2's additive rule, decision 7 on reordering and decision 9's ground apply to it, and decisions 3 and 5, which are about apiVersion, do not: no migration names a node type. Adding a member is a Core MINOR, and #853's per-database check is due before the first new member, as it is for kind and relationType. ADR-0039 decision 1's "eight entries" becomes nine, in an amendment there.

9. The disclosure families of a graph response

The equality instrument is one query against two corpora, at every hop: corpus A holds a withheld item W, with whatever relations name it; corpus B never held W; both share one Git history. Every response must be byte-identical between them.

The closure argument. Decision 3(b) makes the traceability_edges rows identical in A and B, since the collector reads Git alone. What differs is W's knowledge_items row and the knowledge_relations rows that name it. Every read of knowledge_items on the trace path is the per-hop gate's read (decision 6), which gives W and an absent id the same outcome. Every knowledge_relations row is gated on both endpoints before it reaches a count, a slot or a field, and a row naming W fails the gate in A and does not exist in B. Every limit and count is taken after the gate (decision 7). So every published value is a function of rows that are identical in A and B. That argument holds rows 1, 2, 4, 5 and 7. It does not cover four families, and the table names what does: the time and the rows spent reading and dropping (rows 3 and 6), which state a request reads (row 8), and a decode that runs before the gate decides (row 9).

# Family Its face in a trace response Held by #1034's test, by role
1 A published field recordedEdgesWalked, any edge or node count Counted after the gate; edges to W or to an absent id count in neither Two-corpora equality on every field, a start whose only edges reach W
2 Which rows reached a field A withheld node taking one of the 100 slots moves where the walk truncates Limits count gated units only (decision 7) Two-corpora equality at the truncation point: a start with more than 100 visible neighbours plus edges to W
3 A duration One gate read per hop: W found and decoded, an absent id not found Body-free metadata read, so the cost does not scale with W's body (T-26); one read per endpoint per request. The found-versus-missing difference remains, and this ADR does not claim it is zero A two-corpora timing measurement across hop counts, reported as a measurement
4 A statistic over rows the caller may not see A count over all stored edges or relations of a node No pre-gate count is published, by trace or by knowledge.status A schema walk of the trace response asserting no field is computed before the gate, plus equality
5 An error that tells withheld from absent At the start node; at a hop The start refusal is knowledge.get's absent-id refusal; a hop never errors on an endpoint, it withholds A start at W against a start at an absent id: identical bytes; a hop to W against a hop to an absent id: identical response
6 A resource consumed Pre-gate rows read: relation rows naming W are read and dropped in A and do not exist in B Bounded by 100 × the largest fan-out (decision 7); the per-row cost is the one knowledge.get's relations already pays A measurement of rows read per request on the dogfood corpus
7 Another tool reaching the same content knowledge.get and trace on one item trace publishes no relation field knowledge.get withholds and no item content at all (decision 7) For every item in a corpus holding withheld rows, trace's relations of it are a subset of knowledge.get's
8 State, lifecycle and concurrency A v4 database under a v5 Core; a trace racing a rebuild, or an apply replacing the edges in place (decision 2) Exact match at open (decision 4); one read session per request, and the active pointer read once, so a trace sees one state whole A two-way open test; a trace racing either sees the old state or the new one, never both
9 A closed-set value decoded before the gate (#853's class) A TraceNodeType or RelationType member a Core lacks, decoded before the hop's gate decides traceability_edges rows are identical in A and B (3(b)), so their decode cannot differ; an item row or a knowledge_relations row naming W is the face #853 records, held by its per-database check, due before the first new member (ADR-0039) A withheld row carrying an unknown member against an absent id: identical responses, the acceptance ADR-0039 Compliance item 3 states

Consequences

Positive

  • The exit demonstration needs no new operation, no new member and no apiVersion bump (decision 1). AC: git diff origin/main...HEAD -- schemas is empty for this record.
  • The edge table cannot vary with withheld content (decision 3(b)), so five of decision 9's nine families close on one argument over one gate, and the other four are named with what holds them.
  • A mistyped or early declaration costs nothing at read time and starts to surface when its item exists.

Negative

  • Coverage starts at zero. No commit on main carries a trailer (F4), and no edge is recorded for anything before the convention's first commit. The 380 lines that mention an ADR are not collected.
  • ADR-0025 to ADR-0040 have no twin (F1). A trailer naming one of them names nothing until a migration creates its twin, and is recorded and inert until then (decision 3(b)). #1033 plans a squash body carrying Refs: with ADR-0040's item id; that item does not exist at 5ad30799. #1035's demonstration needs a trailer naming one of the 24 twins, or a twin created first.
  • Between a commit, or a checkout that leaves the migrations alone, and the next apply, the edges describe the walk commit, not HEAD (decision 2). recordedEdgesCommit says which; nothing raises a staleness alarm. Every apply pays the walk and a full replace, near two minutes at the budget: a read of at most 0.68 s, then 3,200,000 rows into schema.py's DDL verbatim plus decision 4's source_commit, 62.6 s written fresh and 116.6 s as a replace, in a 2.71 GB database (git 2.56.0, SQLite 3.53.1; python3 -I at_budget_read.py, python3 -I at_budget_write.py <schema.py> v5, #1036's round record). A commit larger than what remains of the budget stops every walk there until 10,000 newer first-parent commits pass it.
  • The budget bounds git's output; git's reads to produce it are bounded only by each spawn's 30-second timeout, which refuses the build and names the spawn that timed out, so the operator sees what to act on. Commit content reaches that bound two ways. Headers no spawn emits: 100 first-parent commits, each with a 330 MiB gpgsig header (475 MB on disk), let rev-list and diff-tree exit 0 in 4.25 s and 9.38 s (8,159 and 5,274 bytes out), and log timed out at 30.01 s, refusing the build. Trees compared on changed paths: a flat directory of 100,000 entries costs 9 ms per commit that changes it, about 90 s at the depth bound. Measured against the walk form at #1036's branch commit 7685dc5d, git 2.56.0, scripts in #1036's round record. The refusal persists while those commits are inside the 10,000-commit window, and whether a walk near the timeout succeeds varies with the machine's load. Metering git's reads, a commit object-size cap and a tree-size cap on changed paths, is filed under #1038; rev-list's own read stays outside any such meter.
  • A rename breaks the path link. An edge names the path its commit changed; the module at its new path has no edge until a later commit with a trailer changes it.
  • In a merge workflow, a side-branch commit's trailer is lost unless the merge commit's message carries it (decision 2). The squash-body rule in orchestration.md is this repository's form of that.
  • A commit-level declaration is projected onto every path the commit changed. related_to keeps the claim true, and weak.

Neutral

  • traceability.md's other sources and its nine tools are not built. Review threads, test names and scope.paths stay design; trace is the one tool.
  • No commit node type. A commit is evidence and source_commit, never a node (decision 1).
  • UNPOPULATED_TABLES moves in #1033. packages/theurian-core/tests/integration/test_canonical_store_corruption.py excludes traceability_edges, and only it, from its every-table-holds-a-row check (ADR-0038, Neutral); the slice that populates it owns the change.
  • ADR-0038's revision pin stays unrepresented. An edge does not carry the pin the fold drops, which ADR-0038 left to this record: it carries a commit, and ADR-0038 records why a commit is not that pin.

Alternatives considered

Alternative Why rejected
Prose mentions, addRelation, scope.paths as the source Decision 1's table, each with its key
constrained_by as the relation Projects a commit-level declaration onto every changed path as a per-path constraint (decision 1)
A commit TraceNode, with edges path → commit → item A new TraceNodeType member, so #853 first (decision 8); two hops per declaration against the four-hop depth limit; and the commit is what measured the edge, not what the edge is about
Collect in ingest, as the roadmap row planned, or in a new command ingest writes no state (F10); either gives the state database an optional second writer (decision 2)
HEAD in state_hash §6 principle 2 asks the response to state its commit, not that every commit invalidate the state, and ADR-0016 rejected a commit sha in the hash for invalidating a valid state on a code-only commit. A staleness alarm after every commit, the stale index label (Two further facts) among its faces, is §10's trust failure by another route: a signal that is always on is read as noise. Read from source, not run (decision 2)
Hash a digest of the collected edges Every command that resolves a project computes the hash, and the digest needs the whole walk each time (decision 2)
Porcelain git log --name-only with -c pins A global ~/.gitconfig log.showRoot=false moved the edges under ADR-0029's hardening and under #1012's, and diff.ignoreSubmodules=all survived #1012 plus a showRoot pin; the population "every key porcelain honours" has no closing key (decision 2)
Bound the walk by wall time The edge set, or whether the build succeeds, would vary with the machine's load (decision 2)
Keep the edges in a database of their own, keyed by HEAD, as the index is kept apart (ADR-0022) What it would keep — ADR-0016 decision 4 and the index's freshness untouched — decision 2 keeps without it. Its price is a trace reading two databases built at different moments: the per-hop gate would judge an edge from one state against items from another, and family 8 would hold two pointers instead of one
Resolve an alias or label at collection, ADR-0038 decision 2's form Labels name no single item, an alias's target moves with later migrations, and resolution reads canonical rows into the collector (decision 3)
Drop a valid id that names no item The edge table would vary with withheld content, and the declaration would vanish silently (decision 3(b))
Reuse MigrationCycleError for INV-6 It names a migration-ordering cycle, carries migration ids, and its remedy edits dependsOn (decision 5)
Bump MIGRATION_ENGINE_VERSION with INV-6 The guard changes which sets are accepted, not what an accepted operation does, so the bump would invalidate every state built from an acyclic set to buy nothing, and the whole-set guard already refuses a cyclic one at its next apply (decision 5)
Check INV-6 after each migration rather than over the set A frozen migration that closed a cycle a later one breaks would refuse forever, with no cure but editing history
Annotate trace parameters with Literal or an enum Publishes an enum on the served schema, #856's trigger (decision 8)

Compliance

This ADR ships no behaviour. Its enforcement is a claims pin over the facts it states, plus the obligations below.

Landing with this pull request:

  • Amendments pointing here, each in the record this decision moves: ADR-0038 decision 2 and its Compliance item 3 (decisions 1, 3, 4 and 6 answer that item); ADR-0016 decision 4 (decision 2); ADR-0039 decision 1's eight entries (decision 8); and the INV-6 row of docs/architecture/requirements-analysis.md and roadmap §4 item 3, for decision 5's set.
  • packages/theurian-core/tests/unit/test_adr_0040_claims.py, the claims pin, written by the tests step after this record. It is owed both directions for each fact under Context: a prose side that reddens when this record drifts from what it says, and a fact side derived from live source that reddens when the codebase moves. Of the facts under Context, F6's exact match, F7's two item-id endpoints, the label's lack of cross-item uniqueness, and the state hash's reading no Git stand; the rest are dated, and only F10's has a fact side. Its failure message names #1033, as the census units' below do; none names #1034. Since #1033 the pin also holds five sentences outside Context as standing: decision 4's SCHEMA_VERSION 5, schema_metadata walk columns and source_commit TEXT NOT NULL, decision 5's guard in the migration engine, and the edge adapter's landing below. Decision 2's identity and digests and 3(c)'s cap have no fact side until #1033 builds them. Its reach is stated in its module docstring.

Rests on enforcement that already holds:

  • The one-hop gate. _relation_is_visible reads both endpoints through get_item_exact_metadata (F12), the read decision 6 extends to every hop.
  • The exact-match open (F6), which decision 4's v4/v5 refusal is.
  • ADR-0029's trailer extraction (keyed_lines), which decision 3 reuses; decision 2's environment is #1012's (342ea607).
  • _closed_value, the parse decision 8 requires.

Landed from item 1 below in #1033's schema-v5 pull request (#1059):

  • SCHEMA_VERSION 5 and decision 4's columns: test_the_schema_version_is_five, test_schema_metadata_has_the_walk_record_columns, test_traceability_edges_has_a_source_commit_column;
  • decision 5's guard, called from MigrationEngine.apply: test_must_be_acyclic_has_one_caller_under_src, and the RED drivers test_a_v4_state_holding_a_supersession_cycle_is_refused_and_its_rebuild_raises and test_an_apply_with_nothing_pending_refuses_a_planted_cycle_and_publishes_nothing;
  • the two-way open: test_a_database_of_the_other_version_is_refused_before_any_row_is_decoded;
  • the BREAKING CHANGELOG entry, and FR-K8 restated.

Landed from item 1 below in #1033's edge-adapter pull request: the SQLite adapter for both port methods, which nothing under packages/theurian-core/src calls yet.

  • SqliteWriter.add_traceability_edge and SqliteCanonicalStore.list_traceability_edges: test_a_traceability_edge_round_trips_every_field, two edges written and read back equal, source_commit included, each relation_type a RelationType, one listed by its source and the other by its target; and test_the_sqlite_store_is_the_one_adapter_of_the_edge_port, by the key its module docstring states;
  • decision 4's source_commit: test_an_edge_refuses_any_other_source_commit_without_echoing_it, nine values that are not a full lowercase hex commit id, each refused with the same fixed message;
  • decision 4's walk record: test_an_incoherent_walk_record_is_refused_by_its_own_check, eight incoherent schema_metadata updates, each refused with SQLite naming the CHECK the case expects.

Still owed, with the issue or slice that will satisfy it:

  1. #1033, edge collection: the collector of decisions 2 and 3 with the build report of 3(a) to 3(c); schema v5 (decision 4); the SQLite adapter for both port methods; tests for determinism at one HEAD, each of decision 2's levers with its positive control; pins that every rev-list line is validated as OIDs, that the messages arrive in rev-list's sequence, and that diff-tree returns one record per commit fed, an empty commit and a path named like an OID included; a pin that a rehearsal with TMPDIR inside a clone records a null commit and 0 edges, against TMPDIR outside any repository; a pin that a fetch --deepen interleaved between the two shallow-digest reads refuses the build; tests for no Git history, an unborn HEAD, a shallow clone and its boundary commit, the depth bound and both budgets, the path cap at 1,000 and 1,001 paths, 3(c)'s cap and capped digest at 32 and 33 ids, and the full replace after a rebase; a no-echo test: an invalid value and a non-UTF-8 message planted, and none of their bytes in any stdout, stderr, log, report field or exception text, got {value!r} (identifiers.py:143) included; a perturbation pin that a commit changing no migration and no body a migration references leaves state_hash unchanged; UNPOPULATED_TABLES; the CHANGELOG; Negative's third item re-measured through its adapter; and, in the same change, each sentence decision 2's write or decision 5's guard makes false. Census at 5ad30799: every tracked text, each JSON description on its own, then whitespace-joined sentences; a hit is a unit matching, case-insensitively, both immutab|changed nothing|changes nothing|change nothing|writes nothing|wrote nothing|write nothing|nothing (is )?pending|nothing to apply|\bno-?op\b|already (fully )?applied|once (it is |it's )?built|never (re)?written|read-only once and state|database|\bDB\b|appl|migrat|built|build: 393 units in 200 files, read at every match (FR-K8's row is a second match). The 25 units it finds false are listed, file by file, under #1033's Sentences this slice falsifies; every other hit stays true, is out of class, or is a .theurian/ twin (#971). Sequencing condition: decision 5's guard, on every apply, and RelationCycleError land in one commit with the SCHEMA_VERSION 4→5 bump, on the branch and so in the squash — never earlier (under v4 a cyclic state built by core-v0.5.3 hashes identically and is reused; its refused re-apply rolls back and keeps serving it), never later (a Core built between them serves a v5 state no guard checked, and a rule that no core-v* tag sits between them leans on release ordering, which this ADR rejects). Check: these three each print one sha, the same one: on the branch the commit that bumps the version, on main the squash commit.

sh git log -S'SCHEMA_VERSION: Final = 5' --format=%H -- packages/theurian-core/src/theurian/infrastructure/sqlite/schema.py git log -S'.must_be_acyclic(' --format=%H -- packages/theurian-core/src git log -S'class RelationCycleError' --format=%H -- packages/theurian-core/src

Their positive control, -G'^SCHEMA_VERSION: Final = ' over the same file, lists every commit that changed the version line, newest first; before #1033 its first is the 3 → 4 bump, 7d7195b0. A later revert or cherry-pick that moves one without the other is outside the condition. Its pull request also carries a BREAKING CHANGELOG entry naming the refusal; FR-K8's "a no-op, not an error" (docs/architecture/requirements-analysis.md:38), restated as scope over applied sets, since under the condition a cyclic set is never applied; and the RED driver: a state holding a cycle written without the guard, whose next apply, with nothing pending, is refused. The collector and the adapter may be their own pull request on either side of it. 2. #1034, knowledge.trace: decisions 6–8, with TraceNodeType added to the governed classes of ADR-0039's scan, which is decision 9's ground; decision 9's tests, in the same change as the tool; #845's M-4 as an acceptance criterion; system.capabilities's traceability flipped to true (F11); and the Phase C Tests row's pin that every hop's visibility decision goes through the non-resolving, body-free read; a SAFETY pin on every response. 3. #1035, the exit demonstration: a commit carrying a trailer that names one of the 24 ADR twins, or a twin created first (Negative, second item), traced from a module to that ADR. 4. #853, before the first new TraceNodeType member (decision 8).