theurian 0.1.0.dev3__tar.gz → 0.1.0.dev5__tar.gz

{theurian-0.1.0.dev3 → theurian-0.1.0.dev5}/CHANGELOG.md

@@ -12,6 +12,982 @@ Pre-1.0, a MINOR bump may change the protocol. Post-1.0, only a MAJOR may.
 
 ## [Unreleased]
 
+## [0.1.0.dev5] - 2026-08-19
+
+### Added
+
+- **`theurian propose` drafts a knowledge change, `theurian propose accept`
+  moves it into place** ([#212](https://github.com/theurian/theurian/issues/212)).
+  Packages ADR-0013 §4's previously manual flow into the CLI: `theurian propose`
+  writes a proposal directory under `.theurian/proposals/<id>/` — a schema-valid,
+  directly applicable migration named `<migration-ulid>-<slug>.yaml`, the body in
+  its native format under a sub-path mirroring its knowledge namespace, and
+  `evidence.json` — and writes nowhere else. `theurian propose accept <id>` moves
+  the migration into `.theurian/migrations/` and the body to the path its
+  `contentFile` names. Neither approves anything: `accept` moves files and stops
+  short of the judgement, and approval is a human merging the pull request that
+  carries the proposal (ADR-0013 point 4). There is no CLI or MCP surface that
+  stands in for that merge.
+
+- **`theurian migrate validate` names every revision whose body no digest pins**
+  ([#210](https://github.com/theurian/theurian/issues/210)). `contentSha256` is
+  optional in the schema and is the only thing that freezes a body: where it is
+  declared, the loader hashes the file on every load and refuses a mismatch;
+  where it is absent, the loader adopts whatever the file hashes to now as that
+  revision's own content hash. Measured on an unpinned migration: apply it, edit
+  the body out of band, and `migrate validate` still reports `valid: true` at
+  exit 0, while the next `migrate apply` records the edited bytes under the same
+  revision id and returns `changed: true`. Nothing recommended the field and
+  nothing reported its absence.
+
+  Validate's output now carries `unpinnedRevisions` — one line per
+  `upsertRevision` that declares no pin, naming the migration, the revision
+  inside it, the body's **project-relative** path (the one a reader can `shasum`
+  from the repository root, not the authored `contentFile`, which is relative to
+  the migration file), and the remedy — in `--json` and in the default human
+  output alike. The remedy carries its applied-case escape: the warning fires on
+  already-applied migrations too, and editing an applied migration to add the pin
+  trips FR-K5's checksum guard, so pinning an already-applied body means editing
+  it, deleting `.theurian/state/`, and rebuilding (FR-K4) — a warning that
+  stopped at "add the pin" would loop a reader between two errors, the way issue
+  #63's HIGH-1 did. Additive and **always present**, an empty list when
+  every revision pins. It is a **warning, not a refusal**: `valid` stays `true`
+  and the exit code stays 0. Requiring the pin instead would be a breaking schema
+  change with a measured cost — both shipped example migrations under
+  `examples/sample-project/` are unpinned, and at this branch's base
+  (`8b8abd7`) 21 of the 22 test files naming `upsertRevision` never mentioned the
+  field — so it is recorded on #210 as a Milestone 7 decision rather than taken
+  here. `theurian propose` already pins every revision it writes (ADR-0013).
+  Reported per operation rather than per migration, because the fix is a digest
+  taken from one named body file. Documented in
+  [`docs/protocol/migrations.md`](../../docs/protocol/migrations.md).
+
+### Changed
+
+- **BREAKING — one body file may back only one revision across a migration set**
+  ([#210](https://github.com/theurian/theurian/issues/210)).
+
+  **Old shape:** a set in which two *different* revisions named one `contentFile`
+  applied. Measured: two hand-written migrations sharing one path, with a correct
+  `expectedRevision` chain and no `contentSha256`, both applied at exit 0 — and
+  the earlier revision recorded the *later* body under its own title and author.
+  Having adopted that body's hash where no pin was declared, the wrong record was
+  self-consistent afterwards, so nothing could detect it later.
+
+  **New shape:** `migrate validate` and `migrate apply` both refuse the whole set
+  with `DuplicateContentFileError` at exit 4, naming both revisions, both authored
+  paths, and the resolved body. `apply` refuses before it creates a database file,
+  so a refused set costs no state — the property issue #63's refusal already has.
+  The refusal is **unconditional of pinning**: even a pair that both pin the same
+  `contentSha256` is refused, because one file cannot be independently frozen or
+  attributed to two revisions — the hazard is the sharing, not the missing pin.
+  The remedy says to give the later revision a body file of its own, and says what
+  to do when the offending migration was already applied: editing it trips FR-K5's
+  applied-migration checksum guard, so the fix there is the edit plus a
+  `.theurian/state/` rebuild (FR-K4).
+
+  The comparison key is the body's **filesystem identity** (`st_dev`/`st_ino`),
+  not the path string, so two revisions that reach one physical file through
+  *different* spellings still collide — a `./` segment, and the case-variant and
+  NFC/NFD spellings a case-insensitive filesystem (APFS, NTFS) collapses onto one
+  inode, and a second hardlinked name. A string key left those distinct and let a
+  second revision name the same body through a variant spelling; casefolding the
+  string would go wrong the other way and refuse two genuinely different files on
+  a case-sensitive filesystem, so identity is the platform-correct key. Re-declaring
+  one revision against its own body — how an in-place status change such as
+  `reject` is written, where the revision id does not move, only `status` differs,
+  and `append_revision` stays the no-op FR-K8 requires (ADR-0024 decision 5) —
+  still passes, because the key that separates a re-declaration from a collision is
+  the revision id. `migrate status` does not refuse — its contract is observation —
+  but names every refused migration under `refusedIds`, matching how it treats the
+  tenant/ACL rule.
+
+  Breaking because a migration set that applied on `0.1.0.dev4` and earlier now
+  refuses. No stable release exists — the published versions are `0.1.0.devN` —
+  and no compatibility promise covers it, but the break is named here rather than
+  filed as a fix. Documented in
+  [`docs/protocol/migrations.md`](../../docs/protocol/migrations.md).
+
+### Removed
+
+- **BREAKING — `system.capabilities` no longer publishes `milestone`**
+  ([#206](https://github.com/theurian/theurian/issues/206)). The field
+  reported a build-progress integer that had drifted stale against the
+  README's own milestone claim since the Milestone 6 close, and nothing —
+  test, schema, or `docs/protocol/mcp-tools.md` — pinned its value or even
+  its presence: a mutation setting it to `99` survived the whole suite. It
+  had exactly one producer (`mcp/tools.py`) and no consumer anywhere in this
+  repository, plugin included, and was never defined in that document or in
+  any schema under `schemas/mcp/`.
+
+  Breaking by the table in
+  [`docs/protocol/plugin-core-compatibility.md`](../../docs/protocol/plugin-core-compatibility.md)
+  ("Removing a field" is always breaking), and `protocolVersion` is not
+  bumped for it anyway — a recorded, narrowly-scoped exemption specific to
+  this one field, not a precedent for others. The reasoning is in *Changing
+  this contract* in
+  [`docs/protocol/mcp-tools.md`](../../docs/protocol/mcp-tools.md):
+  `milestone` was protocol-undefined and had no defined purpose anywhere in
+  this repository, which `version` and `protocolVersion` are not — both are
+  named in that document's field-role paragraph, and each re-publishes a
+  process constant a real consumer elsewhere (`theurian compat check`)
+  reads directly, even though that consumer reads the constant and never
+  this response.
+
+  `test_the_system_capabilities_response_holds_exactly_the_keys_that_are_pinned`
+  now pins the response's exact top-level key set, and
+  `test_capabilities_report_what_is_and_is_not_built` newly pins `version`,
+  `protocolVersion`, `schemaVersion` and the load-bearing substring of
+  `note` — closing the four siblings review found unpinned beside
+  `milestone`.
+
+### Fixed
+
+- **An external `$ref` destined for a host no longer records as a local file,
+  and one past a walk cap no longer vanishes**
+  ([#203](https://github.com/theurian/theurian/issues/203)). `_external_refs`
+  recorded the scheme `urlsplit` found and defaulted to `relative-file` when it
+  found none, which put four measured shapes on the wrong side of the one field
+  Milestone 7's scheme allowlist (T-7, #129) will key on:
+
+  - `//evil.test/x.json` (a protocol-relative URL) and
+    `\\smb-host\share\x.json` (a UNC path) both name a host, and both recorded
+    `relative-file` — the label such a gate is most likely to accept, so the
+    error was in the fail-open direction;
+  - `C:\Windows\system32\x.json` recorded the scheme `c`, a drive letter
+    `urlsplit` reads as a scheme;
+  - a `$ref` nested past `MAX_REF_DEPTH` (64) was dropped in silence, and the
+    document reported `unresolvedRefCount` 0 — the same answer a document with
+    no external references gives;
+  - `http://[::1` made `urlsplit` raise `ValueError("Invalid IPv6 URL")` from
+    inside the recording branch. That exception escaped `parse`, so one
+    malformed reference discarded the *whole* document — every operation,
+    schema and other reference in it — with a message naming no remedy.
+
+  A reference carrying no scheme is now classified by its structure, following
+  RFC 3986 §4.2, into `protocol-relative`, `unc`, `absolute-file` or
+  `relative-file`; one that carries a scheme records that scheme, lowercased,
+  matched against RFC 3986 §3.1 rather than through `urllib.parse`. The split is
+  structural rather than a list of bad spellings, so the mixed `/\host\x` that
+  Windows and browsers accept lands on the network side without being
+  enumerated, and `x://host/y` keeps its one-letter *scheme* while
+  `C:\Windows\x` does not. `NETWORK_PATH_SCHEMES` and `LOCAL_PATH_SCHEMES`
+  publish the two groups for the gate that will read them.
+
+  **Both walk caps stay where they were** — `MAX_REFS` (5000) and
+  `MAX_REF_DEPTH` (64) — and each now records where it stopped, one record per
+  reason and two reasons, so the marker list holds at most two entries however
+  many nodes sit at a cap. That bound is on the marker list and not on the walk:
+  the traversal revisits shared sub-objects rather than memoising them, so
+  neither cap is a resource-exhaustion control
+  ([#245](https://github.com/theurian/theurian/issues/245)).
+  Neither marks a node that could not have held a reference: a scalar
+  has no children and an empty container has none either, and emptiness is
+  answerable without descending, which is what lets the check sit in front of a
+  cap that forbids descending. A non-empty container stays marked even when it
+  holds only scalars, because knowing better means reading the children the cap
+  refused. The parser's metadata gains `refWalkTruncated`, which says whether
+  `unresolvedRefCount` is a total or a lower bound, and the index gains
+  `refWalkTruncations`. That count is over the document's distinct `$ref`
+  strings only — not occurrences, not distinct targets, and not the other
+  resolution keywords a specification can carry, which this walk does not visit
+  ([#246](https://github.com/theurian/theurian/issues/246)). Both counts stop at the parser boundary — `IngestedDocument`
+  has no metadata field, so what survives ingestion is `_index`'s
+  `externalRefs` and `refWalkTruncations`, which is where a Milestone 7 gate
+  should read. Nothing fetches, and the never-fetched pins in
+  `tests/unit/test_network_call_sites.py` are untouched.
+
+  **Not covered: a scheme that is faithful and still remote.**
+  `file://evil.test/share/x.json` records `file`, which is what it is. A gate
+  that allows `file` at all has to inspect the authority, exactly as it has to
+  inspect the path of an equally local `file:///etc/shadow`; the residual is
+  recorded in `docs/security/threat-model.md` (T-7) and pinned as a decision by
+  `test_a_file_url_with_a_host_records_its_scheme_and_leaves_the_authority_alone`.
+
+- **`--json` commands no longer crash with a raw traceback when a migration's
+  content cannot be read**
+  ([#205](https://github.com/theurian/theurian/issues/205)). Every CLI command
+  that resolves a project loads and validates its migrations first, and a raw
+  filesystem-call failure on that path escaped through Typer as a Rich traceback
+  — exit 1, empty stdout, no `{error, remedy}` document — even under `--json`.
+  Reproduced against `migrate validate --json` and `init`; it reached all eleven
+  `resolve_context`/`_require_project` call sites, `project status` included,
+  whose contract is to answer rather than crash. Each read failure now raises a
+  `TheurianError` subtype that those call sites already guard, so it renders as a
+  structured `{error, remedy}` failure at exit 1 instead. The class covered is
+  filesystem-call failures that *raise*:
+
+  - a `contentFile` that cannot be resolved or read — missing, a permission
+    problem, a directory, or a path holding a NUL byte, which makes
+    `Path.resolve()` raise `ValueError` before any syscall, one call site earlier
+    than the read;
+  - a migration file the loader cannot read;
+  - a `.theurian/migrations/` directory whose probe (`Path.is_dir()`) re-raises
+    `EACCES` — for example its execute bit removed;
+  - a project registry — data directory or registry file — that cannot be read;
+  - the installed package's JSON Schema, when a candidate is found but reading it
+    fails.
+
+  Each remedy is selected by *why* the read failed, not one guess per `OSError`:
+  a missing or malformed path points at path resolution, `EACCES`/`EPERM` at
+  permissions, `EISDIR` at "this names a directory, not a file." `project status
+  --json` now surfaces the remedy in its unresolved-project payload too.
+
+  **Not covered when this entry was written — two adjacent defects shared this
+  symptom but not its root cause.** A `.theurian/migrations/` directory that
+  `Path.glob` cannot list swallowed the `PermissionError` and reported
+  `valid: true, migrationCount: 0` — a silent false-negative, because nothing
+  raised ([#214](https://github.com/theurian/theurian/issues/214)). A malformed
+  migration YAML raised `yaml.YAMLError` at parse time, which the loader did not
+  catch, so it still escaped as a traceback under `--json`
+  ([#217](https://github.com/theurian/theurian/issues/217)). Both are fixed
+  below.
+
+- **`migrate validate|status|apply --json` (and every other `resolve_context`
+  consumer) refuse a malformed migration, an unreadable migrations directory,
+  or a corrupted installed schema with the structured `{error, remedy}`
+  shape, instead of a raw traceback or a silent false positive**
+  ([#214](https://github.com/theurian/theurian/issues/214),
+  [#217](https://github.com/theurian/theurian/issues/217)). Closes the two
+  defects the `#205` fix above named as not covered, a third face of #214
+  that reproducing it found and that neither issue had named, three more
+  members of the same class that this branch's own review round two found on
+  the same load path, three further members round three found on the
+  round-two fixes themselves, and four further members round four found —
+  two more ways `migrations_dir` itself can behave like a broken symlink, a
+  dependency of a multi-failure refusal's named entry on filesystem
+  enumeration order, and a `RecursionError` escape round three's own new
+  `check_schema` call introduced — not new issues, escapes the round-one
+  through round-three fixes each left open.
+
+  - **#217 — a YAML syntax error, or a NUL byte in the migration source, no
+    longer crashes.** `load_yaml_mapping` raises `yaml.YAMLError` on either —
+    a scanner syntax error, and a reader NUL-byte error
+    (`yaml.reader.ReaderError`, also a `YAMLError` subclass) — neither of
+    which is the `UnicodeDecodeError` or `ValueError` that `_load_one`'s
+    `except` clause around it caught. Both now convert to `MigrationError`
+    naming the file and the parse problem. `proposal_service.py`'s own two
+    `load_yaml_mapping` call sites already catch `yaml.YAMLError`, but not
+    identically: `_parse_migration` (the `propose accept` path) already
+    translated it into a `ProposalError`, while `_pinned_digest_at` catches it
+    only to skip a malformed *existing* migration silently — documented there
+    as deliberate, since that migration already fails `migrate validate` on
+    its own and diagnosing it is not `propose accept`'s job.
+  - **#214 — an unreadable `migrations_dir` no longer reports the never-read
+    set as an empty one.** `chmod 000`/`0o111` on `.theurian/migrations/`
+    itself, not its parent (`is_dir()` needs no permission on the target,
+    only its ancestors), left `Path.glob("*.yaml")`'s own `scandir` catching
+    the `PermissionError` internally and yielding nothing: `migrate validate
+    --json` reported `valid: true` with `migrationCount: 0`, and `migrate
+    apply --json` went on to create a state database for the set it wrongly
+    believed was the whole story. Enumeration is now `iterdir()`-based, with
+    the directory listing and every entry's `is_file()` stat inside one
+    `try`, so any `OSError` there raises `MigrationsDirectoryUnreadableError`.
+  - **A third face of #214, found while reproducing it and named in neither
+    issue.** `chmod 0o444` leaves the directory listable but not traversable,
+    so the same per-entry `is_file()` stat raised an uncaught
+    `PermissionError` instead — a raw traceback, not the silent false
+    positive above. Same root cause, same fix: caught by the same `try`.
+  - **Round two — a YAML document nested past PyYAML's recursion limit no
+    longer crashes.** `RecursionError` is not outside `Exception`'s hierarchy
+    — it is a `RuntimeError` subclass, and a bare `except Exception` would
+    have caught it fine — but no `except` clause on this path named
+    `RuntimeError` or `RecursionError` at all: `load_yaml_mapping`'s three
+    callers (`migration_loader.py`'s `_load_one`, and `proposal_service.py`'s
+    `_parse_migration` and `_pinned_digest_at`) each caught only
+    `UnicodeDecodeError`, `ValueError`, and `yaml.YAMLError` —
+    `_pinned_digest_at` also catches `OSError`, which the other two do not,
+    but none of the three named `RuntimeError` or `RecursionError` — so it
+    escaped every one of them and reached `resolve_context` as a raw
+    traceback under `--json`. About 1 KB of nested YAML is already enough to
+    trigger it (measured: `"["*495 + "]"*495`, 990 bytes — 1,023 was the full
+    migration document this was reproduced against, not this bracket string
+    alone). `load_yaml` and
+    `load_yaml_mapping` now catch `RecursionError` and raise `ValueError` in
+    its place — the type every consumer on this path already handles.
+    `load_yaml`'s other three callers, which do not go through
+    `load_yaml_mapping` — the front-matter, structured-YAML, and OpenAPI
+    parsers (`infrastructure/filesystem/parsers/`) — get the identical fix
+    from the same one seam, rather than a catch clause added at each of the
+    six.
+  - **Round two — a symlink chain at `.theurian/migrations` longer than the
+    platform's loop limit no longer reports real migrations as an empty
+    set.** `Path.is_dir()` swallows every `OSError` it hits internally,
+    `ELOOP` included, and reports `False` — the same convenience the #214 fix
+    above relies on for the genuinely-absent case — so a directory that was
+    actually a loop was misreported as "does not exist": `migrate validate
+    --json` reported `valid: true` with `migrationCount: 0`, and `migrate
+    apply --json` seeded a state database for the empty set it wrongly
+    believed was the whole story. The probe is now an explicit `os.stat`:
+    `ENOENT`/`ENOTDIR` still answer the legitimate empty case, but `ELOOP`
+    and every other errno now raise `MigrationsDirectoryUnreadableError`,
+    whose remedy is keyed on `errno` (the loop, a permission problem, or an
+    unnamed residual case) rather than one permission-shaped message for all
+    three. **This is a behaviour change, not only a fix**: a symlink loop at
+    this path used to validate as an empty migration set by accident, and now
+    refuses instead — any earlier description of a symlink loop as a
+    legitimate empty shape no longer holds.
+  - **Round two, never itself given a line in this entry until now — the
+    enumeration's own `ENOENT`/`ENOTDIR` answer relaxed from a refusal (round
+    one) back to an empty set.** Round one's enumeration `except OSError`
+    (the #214 fix above) converted *every* `OSError` to
+    `MigrationsDirectoryUnreadableError`, `ENOENT`/`ENOTDIR` included, so a
+    `migrations_dir` that raced its own deletion between the directory probe
+    and the `iterdir()` listing refused rather than answering
+    `LoadedMigrations.empty()`. The `os.stat`-probe rewrite in the bullet
+    above added the identical `if exc.errno in (ENOENT, ENOTDIR): return
+    empty()` branch to the enumeration's own `except` too, quietly changing
+    this one case back to the pre-#214 answer — a deliberate race policy, not
+    an oversight: the probe's own answer went stale between the check and the
+    listing, and a directory that has since vanished means nothing to load,
+    not a corrupted install. Shipped in round two but not previously named
+    here, unlike the `ELOOP` change beside it, which this entry already
+    flagged as a behaviour change; pinned by
+    `test_load_migrations_treats_a_stale_enumeration_failure_as_an_empty_set`.
+  - **Round two — a corrupted installed schema no longer crashes
+    `_validator`.** Truncated or empty JSON raised `json.JSONDecodeError`;
+    non-UTF-8 bytes raised `UnicodeDecodeError` at the same
+    `read_text(encoding="utf-8")` call; and a schema that parses but is a
+    JSON list rather than an object raised `AttributeError` one line later,
+    at `Draft202012Validator` construction (`jsonschema` calls
+    `schema.get(...)` internally, and a list has no `.get`). All three, and
+    the original `OSError`, now convert to `SchemaUnreadableError`. Round
+    three (below) removes the `AttributeError` translation and replaces it
+    with a check performed before construction, rather than after.
+  - **Round three — a `*.yaml` entry that is a symlink loop, or a symlink
+    whose target is missing, no longer vanishes silently from the loaded
+    set.** `Path.is_file()` — used by both `glob` and round one/two's
+    `iterdir()`-based enumeration — swallows `ELOOP` and `ENOENT` internally
+    and reports `False` for both, the identical directory-level convenience
+    the #214 and round-two fixes above exist to close, one level down:
+    `migrate validate --json` reported a lower `migrationCount` with no error
+    at all, and `migrate apply --json` seeded a state database for the
+    migrations it did see. Per-entry classification now `lstat`s each entry
+    first to tell a symlink from an ordinary file, and a symlink whose
+    resolution fails is refused by name as `MigrationFileUnreadableError` —
+    `ENOENT` gets a dangling-link-specific remedy, every other errno (`ELOOP`
+    chief among them) the loop-specific one from the bullet above. A
+    non-symlink entry that raises `ENOENT`/`ENOTDIR` is still skipped rather
+    than refused: the identical race the enumeration-level bullet above
+    already answers with "nothing to load," one entry down instead of one
+    directory up. Handling the two identically was considered and rejected:
+    an entry-level `try` that answered every stat error with "skip the
+    entry," symlink or not, would turn a directory-wide permission refusal
+    (`chmod 0o444` on `migrations_dir`, #214's own third face above) into a
+    silently shrunken migration set the moment it reached one symlinked entry
+    first — the same worse-regression trap the loop/dangling fix itself
+    exists to avoid, one shape over. Any other non-symlink errno (`EACCES`
+    included) still re-raises to the enumeration's own `except OSError` and
+    surfaces as `MigrationsDirectoryUnreadableError`, unchanged. Reproduced
+    against the real CLI:
+    `test_validate_reports_a_symlink_loop_migration_entry_instead_of_silently_dropping_it`
+    and
+    `test_apply_refuses_a_symlink_loop_migration_entry_without_seeding_a_state_database`.
+  - **Round three — the last path where a deeply nested document could still
+    crash a parser now converts to `ValueError`, and the sibling leg that
+    already converted gains the attribution every other failure branch
+    carries.** `OpenApiParser`'s JSON leg
+    (`infrastructure/filesystem/parsers/openapi.py`) called `json.loads(text)`
+    with no guard around `RecursionError`, so a document nested past the
+    decoder's own recursion limit escaped `_load` uncaught (measured: 20,000
+    nested arrays) — `structured.py`'s `JsonParser` already carried the
+    identical guard, so this closes the class's one remaining crash.
+    `YamlParser.parse` (`structured.py`) never crashed the same way: round
+    two's `load_yaml` fix (above) had already converted its nesting-depth
+    failure to `ValueError`. What it lacked was `anchor.source_uri` on that
+    one branch, unlike every other failure branch in the same method — this
+    round adds it, so the message names the same document every sibling
+    failure already names. Reproduced against the real parsers directly:
+    `test_openapi_reports_the_source_uri_for_json_nested_past_the_recursion_limit`
+    and
+    `test_yaml_parser_names_the_source_uri_for_a_document_nested_past_the_recursion_limit`.
+  - **Round three — the installed schema is now refused, not silently
+    accepted, when it parses but is not usable as a schema.** Two checks in
+    `_validator`, both performed before `Draft202012Validator` construction
+    rather than after: `isinstance(schema, dict)` refuses a schema that is
+    not a JSON object at all — a list (already an `AttributeError` refusal
+    since round two, above) or a bare `true`/`false`, both otherwise-valid
+    top-level JSON Schema documents. Accepting `true` had been silently
+    fail-open: it builds a validator that matches every instance, so an
+    installation corrupted to `true` made every migration in every project
+    validate rather than refusing. `Draft202012Validator.check_schema(schema)`
+    separately refuses a schema whose own keywords are structurally
+    malformed — `required` must be an array of strings, and a bare string
+    previously surfaced only when a schema-*valid* migration tripped over it,
+    misattributed to whichever migration validated first as `'n' is a
+    required property`. Both convert to `SchemaUnreadableError`, and the
+    now-unreachable `except AttributeError` clause is removed rather than
+    kept as a defensive clause nothing can drive. `{}` remains accepted: a
+    valid, if vacuous, schema that matches every instance — deliberately not
+    a third refusal. `test_validator_raises_schema_unreadable_error_for_a_non_object_schema`,
+    `test_validator_raises_schema_unreadable_error_for_structurally_invalid_schema_keywords`,
+    and `test_validator_accepts_the_vacuous_empty_object_schema` pin all
+    three.
+  - **Round four — `migrations_dir` itself being a dangling, looping, or
+    outside-project symlink no longer reports "nothing to load" the way a
+    genuinely absent directory does.** The entry-level symlink policy round
+    three added (two bullets above) never covered the directory `_load_one`
+    reads *from*: the top-of-function probe (`migrations_dir.stat()`, which
+    follows symlinks) cannot tell a dangling symlink from a directory that
+    never existed — both raise the identical `ENOENT` — and an
+    outside-project target was never checked directly at all, only reached
+    incidentally through `_load_one`'s own containment check once a `*.yaml`
+    entry exists to trigger it, which an empty outside directory never
+    reaches. Orchestrator-measured before this fix: a dangling
+    `migrations_dir` symlink made `migrate apply --json` report
+    `databaseCreated: true` and create `.theurian/state/active.json` and a
+    `.sqlite` database for the empty set it wrongly believed was the whole
+    story; a symlink resolving outside `project_root` to an empty directory
+    made `migrate validate --json` report `valid: true, migrationCount: 0`
+    at exit 0. A new check, `_refuse_unusable_migrations_directory_symlink`,
+    now runs before the top-of-function probe: a dangling or looping target
+    raises `MigrationsDirectoryUnreadableError` (the identical dangling-link
+    and loop remedies the entry-level and round-two directory-level cases
+    already use), and a target outside `project_root` raises
+    `PathEscapeError` directly rather than depending on an entry existing to
+    trigger it. **This is a behaviour change, not only a fix**: a dangling or
+    outside-pointing `migrations_dir` symlink used to validate as an empty
+    migration set, and now refuses instead. A `migrations_dir` symlinked to a
+    real, in-project directory still loads normally — this policy narrows
+    only the two broken shapes, not every symlinked directory.
+    `test_load_migrations_refuses_a_dangling_migrations_directory_symlink`,
+    `test_load_migrations_refuses_a_migrations_directory_symlink_to_an_empty_outside_directory`,
+    and
+    `test_load_migrations_follows_a_migrations_directory_symlink_to_a_valid_in_project_directory`
+    pin all three.
+  - **Round four — a multi-failure refusal now names the
+    lexicographically-first failing entry on every filesystem, not whichever
+    one the directory listing happened to yield first.** The enumeration's
+    long-standing `sorted(...)` call sorts the *paths* it is given, but round
+    three's per-entry classification (`_entry_is_migration_file`, which can
+    itself raise `MigrationFileUnreadableError` for a dangling or looping
+    entry) ran *inside* the same generator expression `sorted()` consumed, so
+    it was still evaluated in whatever order `iterdir()` yielded, before
+    sorting ever ran. Two failing entries therefore named
+    whichever one the filesystem happened to enumerate first — APFS is
+    measured here to walk in creation order; ext4's documented `dir_index`
+    hashing walks in hash order (not measured on this machine, which is not
+    Linux), so the identical fixture could name a different offender on
+    each. Enumeration now
+    collects and sorts the `*.yaml` names first, then runs classification
+    over the already-sorted list.
+    `test_load_migrations_names_the_lexicographically_first_entry_when_classification_fails`
+    drives it directly, injecting a reversed-order fixture so the bug
+    reproduces regardless of the developer's own filesystem's enumeration
+    order.
+  - **Round four — a deeply nested installed schema no longer crashes
+    `_validator` through the `check_schema` call round three's own fix
+    added.** `Draft202012Validator.check_schema`, added last round to catch a
+    structurally malformed schema before any migration is checked against
+    it, recurses into a schema's own nested keywords the same way
+    `json.loads` recurses into its document structure — a schema deep enough
+    exhausts the interpreter stack the identical way an attacker-controlled
+    migration document already does, measured directly at 400 levels of
+    nested `not` keywords. Neither the read's own three `except` clauses nor
+    round three's new `except SchemaError` around `check_schema` named
+    `RecursionError` — a `RuntimeError` subclass, not a
+    `jsonschema.exceptions.SchemaError` — so it escaped `_validator` raw, the
+    identical class every other member of this entry was closed for. A
+    regression the branch caught and fixed within its own review loop rather
+    than shipping: `check_schema` did not exist in this function until round
+    three added it (the bullet above), so this gap did not exist before that
+    round either. `_validator` now catches `RecursionError` around both
+    `json.loads` and `check_schema`, converting each to
+    `SchemaUnreadableError`.
+    `test_validator_raises_schema_unreadable_error_for_a_schema_nested_past_the_recursion_limit`
+    pins it. **Not covered by this fix**: a validate-time `$ref` resolution
+    failure — including whatever network fetch `jsonschema`'s own reference
+    resolution performs for a remote `$ref` — is a different failure surface
+    than the schema document's own JSON and keyword nesting, and stays
+    untranslated ([#235](https://github.com/theurian/theurian/issues/235)).
+
+  **The legitimate empty shapes, current as of round four.**
+  `load_migrations` still answers `LoadedMigrations.empty()` — never a
+  refusal — for: a `migrations_dir` that does not exist at all; one that
+  exists but is a regular file rather than a directory
+  (`test_load_migrations_treats_a_migrations_path_that_is_a_regular_file_as_an_empty_set`,
+  round three); an existing, ordinarily-readable, genuinely empty directory
+  (`test_load_migrations_on_an_ordinarily_readable_empty_directory_returns_an_empty_set`);
+  a `*.yaml`-named entry that is a FIFO, a directory, or a symlink resolving
+  to a FIFO, a directory, or a character device, silently excluded from the
+  loaded set rather than counted — the FIFO and directory cases are pinned by
+  `test_load_migrations_skips_a_fifo_and_a_directory_both_named_dot_yaml`
+  (round three); the symlink-to-either-of-those (and to a character device)
+  case follows the identical `entry.stat()`-then-`S_ISREG` path — a symlink
+  to a non-regular target stats successfully and simply fails the type
+  check — and is reasoned from that code path, not pinned by a dedicated
+  test: the shape the round-three adversarial review flagged as missing from
+  this list, recorded here for the first time; and a non-symlink entry that
+  is simply gone by the time it is stat-ed, having raced its own deletion
+  between `iterdir()` listing it and the classification stat that follows
+  (`test_load_migrations_skips_only_a_non_symlink_entry_that_vanishes_mid_enumeration`,
+  round three) — the identical race policy the enumeration-level bullet above
+  already applies one directory up. A directory-level symlink loop at
+  `migrations_dir` itself is deliberately not a member of this list — refused
+  since round two, and refused here too, though round four's new symlink
+  check now catches it before the top-of-function directory probe ever runs
+  (identical `MigrationsDirectoryUnreadableError` loop remedy either way). A
+  dangling or outside-project `migrations_dir` symlink is not a member of
+  this list either, as of round four — see below.
+
+  **Not a legitimate empty shape any more, as of round three: a `*.yaml`
+  entry that is a symlink loop, or a symlink whose target is missing.** Both
+  used to vanish the identical silent way described above — `glob` and every
+  round before this one relied on `Path.is_file()`, which swallows `ELOOP`
+  and `ENOENT` internally and simply excludes the entry, no error, no count.
+  Per-entry classification now raises `MigrationFileUnreadableError` naming
+  the entry instead (round-three bullet above); any earlier description of
+  either as a legitimate empty or silently-skipped shape no longer holds.
+
+  **Not a legitimate empty shape any more, as of round four: a dangling or
+  outside-project `migrations_dir` symlink.** Both used to validate as an
+  empty migration set — a dangling target folded into the identical `ENOENT`
+  a missing directory raises, and an outside-project target holding no
+  `*.yaml` files never reached the containment check that would otherwise
+  catch it. The round-four directory-level bullet above closes both; any
+  earlier description of either as a legitimate empty shape no longer holds.
+
+  **Scope of the directory-level symlink check: the final path component
+  only.** Round four's check is an `lstat` on `migrations_dir` itself, so a
+  symlinked *ancestor* — most visibly `.theurian` being a symlink — is not
+  covered: a dangling `.theurian`, or one pointing at an empty outside
+  directory, still validates as an empty set, and a `.theurian` symlink
+  committed to a repository makes `migrate apply` write state through it,
+  outside the working tree, on `git clone` alone. That is a distinct class
+  from this one — its root cause is the writer/context stack trusting a
+  resolved `.theurian` for every consumer, not the migration load path's
+  error surfacing — and it is tracked separately at
+  [#237](https://github.com/theurian/theurian/issues/237), not closed here.
+
+  Every fault named above — across all four rounds, not counting the
+  enumeration-race policy note, which documents a round-two decision rather
+  than closing a new one — was reproduced against the real CLI, or the real
+  parsers and `_validator` directly for the parser and schema checks; covered
+  by `tests/unit/test_migration_loader_errors.py`,
+  `tests/unit/test_yaml_loading.py`, `tests/unit/test_parsers.py`, and
+  `tests/integration/test_cli_commands.py`.
+
+### Documentation
+
+- **Documents describing review ingestion as shipped, corrected together with
+  the tests that hold the corrected claims**
+  ([#129](https://github.com/theurian/theurian/issues/129)). The class is a
+  security control named in the present tense whose component does not exist:
+  T-7's SSRF entry, the `.theurian/config.yaml` repository allowlist (SEC-10),
+  the `providers.review.repositories` schema key, the sample project's config,
+  and the `review`/`infrastructure.github` package docstrings all read as if the
+  allowlist were in force. No reader of that file exists in `src/`, and
+  `infrastructure/github/` holds no adapter, so nothing consults it; each
+  now says what is owed and names Milestone 7.
+
+  **What the allowlist's absence rests on is now pinned.** T-7's stand-in
+  control is not a filter but the absence of any way to make the request, and
+  that absence was enforced by nothing: a mutation that left `_external_refs`
+  recording exactly as before and added a real `urllib.request.urlopen` beside
+  it survived the whole suite, because
+  `test_external_refs_are_recorded_never_fetched` reads the recorded output and
+  the recording did not change. `tests/unit/test_network_call_sites.py` adds the
+  missing half in three arms —
+  `test_no_module_outside_the_daemon_health_probe_reaches_a_network_client`
+  scans the shipped package and pins the permitted network-client sites to
+  `daemon/instance.py` alone, resolving attribute chains and constant-string
+  dynamic imports; `test_no_module_outside_the_git_and_service_adapters_can_spawn_a_process`
+  does the same over `subprocess`, the `os` spawn/exec family
+  (`system`, `popen`, `spawn*`, `posix_spawn*`, `exec*`) and
+  `asyncio.create_subprocess_*`, because `curl` and `gh api` reach the network
+  with no client module in the diff; and
+  `test_parsing_a_hostile_document_opens_no_socket` watches the socket layer
+  while *every* parser `default_parsers()` returns handles a hostile document,
+  with `test_every_parser_the_registry_ships_has_a_hostile_document` failing
+  when the registry gains a format the table does not know. The threat model now
+  cites the recording pin and the never-fetched pins separately, rather than
+  crediting one test with both, and states the residual all three share: a
+  fetch both spelled at runtime and issued from a child process.
+
+- **`system.capabilities`' `reviewIngestion`, `traceability` and
+  `knowledgeSearch` flags pinned** in
+  `test_capabilities_report_what_is_and_is_not_built`, with
+  `test_the_capability_block_holds_exactly_the_flags_that_are_pinned` holding
+  the key set so a flag added later cannot ship unasserted. All three were
+  unpinned: mutations flipping the first two to `true`, and rewriting
+  `knowledgeSearch` to `"substring"` — indistinguishable to a client from what
+  an un-indexed project reports — survived the suite. That is the same drift
+  that once let the test claim `hybridRetrieval is False` after hybrid retrieval
+  shipped. T-7 cites `reviewIngestion: false` as part of what stands in for the
+  missing allowlist, so the flag is a security-relevant declaration and not a
+  feature toggle.
+
+- **`KnowledgeCandidate.trust_level` cannot be set at construction**, pinned by
+  `test_a_candidate_cannot_be_constructed_with_a_trust_level`. The invariant is
+  one `field(init=False)` keyword and no test named it, so removing it kept the
+  default green while `KnowledgeCandidate(trust_level=REVIEWED)` became
+  constructible — a candidate granting itself the trust a human reviewer exists
+  to grant (ADR-0013, INV-7). `docs/architecture/review-knowledge.md` now names
+  the mechanism behind each promotion invariant rather than attributing all of
+  them to construction.
+
+- **`$ref` recording fidelity stated rather than overclaimed.** T-7 said
+  `_external_refs` "records the target's scheme"; it recorded the scheme only
+  where the target's form carried one, so a protocol-relative (`//host/x.yaml`)
+  or UNC target recorded as `relative-file`, and a ref past either walk cap —
+  `MAX_REFS` (5000) or `MAX_REF_DEPTH` (64), both now named — was dropped from
+  the count entirely. Stating it is what this entry did;
+  [#203](https://github.com/theurian/theurian/issues/203) then fixed the
+  recording itself, in the same release — see *Fixed* above, which is what T-7
+  now describes.
+
+- **How many `git` reads `theurian ingest` performs, measured rather than
+  counted from the module.** `cli/context.py` defines four readers; the ingest
+  path runs three — `rev-parse --show-toplevel`, `rev-parse HEAD` and
+  `remote get-url origin` — because `default_branch`
+  (`symbolic-ref --short HEAD`) is reached only from `project register` and
+  `migrate apply`. Measured by running the command against a `git` shim that
+  logs every invocation. Recorded here because the count is a fact about
+  `cli/context.py`; the document it corrects is the plugin's `/theurian:ingest`,
+  whose own change is in
+  [the plugin changelog](../../plugins/claude-code/CHANGELOG.md).
+
+- **T-7's owed controls listed wherever the entry is summarised.** The threat
+  table in `docs/architecture/requirements-analysis.md` named only the
+  repository allowlist as owed, while SEC-10 also requires the scheme allowlist
+  and the rejection of private-network destinations; it now lists all three, as
+  the threat model itself already did. In the same sweep,
+  `schemas/config/project-config.schema.json` stops attributing every absent
+  loader to Milestone 7 — #129 owes the review-ingestion allowlist reader
+  specifically, and the rest of the file simply has no loader yet — and
+  restores "Not in force." to the head of the `repositories` description, since
+  an editor showing a field's hover text does not show the root note.
+  `ReviewProvider`'s docstring now says the GitHub *adapter* is unbuilt; the
+  port itself exists.
+
+- **The documents described a secret scanner that does not exist**
+  ([#198](https://github.com/theurian/theurian/issues/198)). SEC-11 — scan a
+  candidate revision for secrets and block (default), warn, or do nothing per
+  policy — is not implemented. No content scanner exists anywhere in `src/`, and
+  nothing reads `.theurian/config.yaml` at all (#129), so the
+  `security.secretScan` key selected no behaviour while the published schema
+  declared `"default": "block"`. Six surfaces asserted the control was in force
+  and each now names the absence: T-15's Controls block, the threat summary row,
+  the same T-15 row in `docs/architecture/requirements-analysis.md`,
+  `SECURITY.md`'s "Ingestion warns or blocks per policy", the schema key, and the
+  sample project's config. Same class as the T-7 correction above — a security
+  control written in the present tense whose component does not exist.
+
+  **What stands at SEC-11's trigger point is now stated rather than implied, and
+  neither control is automated:** human review of the authored migration
+  (ADR-0013 — no registered MCP tool can reach a canonical write, and `theurian
+  propose accept` moves files without approving), and supersede or retire with
+  Milestone 6's withdrawal→purge trigger for removing a secret after the fact.
+  Both entries record what neither control does: nothing enforces the merge —
+  `migrate apply` applies whatever is in `.theurian/migrations/`, committed or
+  not.
+
+  **The residual names the boundary the exposure actually starts at.** It is the
+  canonical write, not the index: a secret becomes readable through
+  `knowledge.search` and `knowledge.get` the moment `theurian migrate apply`
+  writes it, before any `index build`, because search degrades to a canonical
+  substring scan when no index can answer (`mcp/search.py`). The repository-side
+  `Secret scan` job (OSS-9, gitleaks) is a different control and is unchanged —
+  it scans this repository's Git history in CI and was never in a user project's
+  ingestion path.
+
+  **Each correction is now pinned, because a corrected claim with no test is a
+  claim that can quietly become false again.** `test_the_secret_scan_policy_publishes_no_default`
+  holds the dropped schema default, with the enum asserted beside it so the
+  no-default assertion cannot pass vacuously against a renamed or deleted key.
+  `tests/unit/test_config_key_call_sites.py` is new and holds the claim the other
+  five surfaces rest on — that no shipped code reads the key:
+  `test_no_shipped_module_reads_a_config_key_the_schema_publishes_as_not_in_force`
+  parses every `.py` under the imported package and matches whole identifiers and
+  whole string constants, which is what separates a reader from the six places
+  `repositories` appears in `src/` as English prose;
+  `test_each_reserved_key_still_publishes_the_absence_the_scan_enforces` closes the
+  reverse direction, where the description moves and no reader is added; and
+  `test_the_config_key_scan_sees_each_naming_form_and_no_other` guards the scanner
+  itself, since a scan that resolves nothing and a package with no reader produce
+  the same green. `test_a_key_the_example_sets_but_nothing_reads_stays_marked_not_in_force`
+  holds the sample project's annotation, which no schema validates. The same
+  three pins cover `providers.review.repositories` (#129), whose schema
+  description makes the identical not-in-force claim.
+
+- **`theurian ingest`'s docstring said it "stores evidence"**, which overstates
+  what the command persists: `IngestionService` has no write path, parsed bodies
+  live in memory for the run, and the only file written is the content-hash
+  manifest `.theurian/cache/ingestion.json`. The docstring and T-15's
+  reference to it now say so. `schemas/config/project-config.schema.json`'s
+  `security.maxSourceFileBytes` gains the same treatment its annotated siblings
+  have: its default documents the shipped `MAX_SOURCE_FILE_BYTES` in
+  `security/paths.py` rather than setting it, and nothing reads the key (#129).
+
+## [0.1.0.dev4] - 2026-08-16
+
+### Added
+
+- **The `integrity` signal takes a second measurement: how many items a caller
+  should be able to see, against the number `theurian migrate apply` recorded**
+  ([#30](https://github.com/theurian/theurian/issues/30) PR2). This is what makes
+  a response's *own* emptiness visible, where PR1 — shipped in `0.1.0.dev3` —
+  could only report damage elsewhere in the state. Three of the four positions
+  PR1 left now disclose, and `SILENTLY_EMPTIED` is deleted — #30's stated closure
+  condition.
+
+  The record is a new `project_integrity` table, one row per project, written by
+  `migrate apply` inside its own write transaction and counted over the rows that
+  transaction just wrote. Nothing on a query path computes it: the reader's half
+  is one `COUNT` over `idx_items_status`, catching a change in the *number* of
+  surfaceable rows — a row leaving or entering the surfaceable scope, in either
+  direction — so an expectation cannot be satisfied by the state it is meant to
+  check
+  (`CanonicalStore.count_surfaceable_items`,
+  `CanonicalStore.expected_surfaceable_count`, `SqliteWriter.record_expected_surfaceable_count`).
+
+  **A missing record is damage, not "not recorded", and a schema bump is what
+  makes that sound.** `SCHEMA_VERSION` went 2 → 3 for this table (below), and
+  `is_supported` is exact-match, so every database this build can open was written
+  by a build that records. `test_a_missing_integrity_record_is_damage_and_not_silence`
+  holds the inference and `test_a_pre_integrity_database_is_refused_unread_by_every_tool`
+  holds the premise on all three tools and over every version below the current
+  one — including that an old database is not reported as a damaged one.
+
+  **What it now catches, pinned by the corruption sweep against the real tools
+  over a real damaged database.** A sentinel in `knowledge_items.project_id`
+  takes every item out of the project scope, and one in `knowledge_items.status`
+  takes a row out of the
+  surfaceable scope: `knowledge.search` answers `count: 0, results: []` and
+  `knowledge.status` answers a shrunken `itemCount` **with the key beside them**,
+  where PR1 answered the same numbers alone; `knowledge.get` refuses those cells
+  as damage rather than reporting them as absence
+  (`test_a_lost_surfaceable_item_is_damage_on_every_read_tool`,
+  `test_a_lost_surfaceable_item_makes_get_refuse_an_absent_id_as_damage`). So an
+  agent can now tell "this project holds nothing" from "part of this project could
+  not be read", and `knowledge.status` no longer publishes a positive
+  `appliedMigrations` beside `itemCount: 0` without comment. The `status` cell is
+  the member `0.1.0.dev2` recorded as "the fifth `SILENTLY_EMPTIED` member,
+  carried to Milestone 6" when #19 stopped parsing every row: it still
+  under-reports, because no read tool can repair a row it cannot parse, but it no
+  longer does so in silence.
+
+  **`knowledge.get`'s damage refusal is reworded, and deliberately says less.**
+  `0.1.0.dev3` reported a project that "could not be fully read: its derived state
+  holds a different number of migration-history rows than its own records expect".
+  Either comparison now reaches that branch, so the text says only that the
+  derived state "disagrees with its own records about what it holds" and names no
+  record — a caller matching on the old substring stops matching. The SEC-13 rule
+  that a withheld id and an absent id get the same message as each other is
+  unchanged, and so is the pair that pins both directions
+  (`test_an_absent_item_over_a_damaged_state_is_refused_as_damage_not_absence`,
+  `test_an_absent_item_over_a_healthy_state_is_refused_as_absence`).
+
+  **One position stays silent and is named rather than rounded away.**
+  `(knowledge.search, knowledge_items, item_id)` moves neither count — the row
+  keeps its `project_id` and its `status`, so both sides still count it — while
+  the item → revision pointer the search walks is broken, and the tool answers one
+  result short with no key. A count is not a checksum, and that is the shape a
+  count cannot see. It is `UNDETECTED_UNDERREPORT` in
+  `tests/integration/test_canonical_store_corruption.py`, an exact set of exactly
+  one member: a second position appearing there is a failure, not an expectation
+  to update.
+
+  **`SILENTLY_EMPTIED` is replaced by three sets that partition the same
+  question**, so no position can slide between outcomes unremarked.
+  `DISCLOSED_AS_INTEGRITY` holds the nine positions that fire the key, keyed on
+  the key's presence and nothing else — six of them fire while every integer in
+  the response stays put, which is the detector's true shape;
+  `DISCLOSED_BESIDE_A_SHRUNKEN_COUNT` holds the three that also shrink a published
+  integer; `UNDETECTED_UNDERREPORT` holds the one that shrinks and says nothing.
+  The sweep asserts the whole shrinking class equals the union of the last two
+  (`test_exactly_these_positions_disclose_damage_as_integrity`,
+  `test_exactly_one_position_answers_with_less_than_the_file_holds_and_says_nothing`
+  — renamed and re-scoped from PR1's
+  `test_exactly_these_positions_disclose_migration_history_damage_as_integrity`
+  and `test_no_tool_answers_with_less_than_the_intact_database_holds`), which is
+  what closes the seam a pair of independently-keyed sets would leave. That
+  partition is over the swept single-cell positions, not a claim that the count
+  catches every wrong answer: a status moved *within* `SURFACEABLE_STATUSES`
+  changes the set's composition without its size and sets no key, and an item
+  whose `current_revision_id` names another item's revision would disclose rather
+  than under-report and is refused at read time by the read-back guard
+  (`61747b3`), a mechanism distinct from this detector.
+
+  **Neither side of the new comparison counts a row the caller may not read.**
+  Both count `SURFACEABLE_STATUSES` — at build time in the `INSERT … SELECT`, at
+  read time in the `COUNT` — so a `rejected`, `deprecated` or `superseded` row is
+  on neither side.
+  `test_the_integrity_signal_is_identical_across_a_withheld_only_difference` holds
+  that whether the key appears is identical across two corpora differing only in
+  twenty-five `rejected` items. Measured beyond what that pins: overwriting a
+  `deprecated` row's `status` produces no key on any tool, where the same
+  overwrite on an `approved` row fires it, and on a `draft` row it fires the key
+  while the default `knowledge.search` answer stays unchanged — a draft is
+  surfaceable even when the default answer omits it. The mirror of that is a
+  recorded residual: overwriting an `approved` row's `status` to another
+  surfaceable value moves neither count and sets no key, while the default answer
+  loses a row it used to surface — the count measures the size of the surfaceable
+  set, not its composition, and the moved row is caller-readable either way. The
+  read cost keeps PR1's
+  shape, `O(surfaceable)` over the covering index rather than `O(total)`, and
+  `knowledge.status` spends no extra query at all: it sums the breakdown it had
+  already read.
+
+  **The remedy's first step deliberately does not clear this shape, and the
+  residual is recorded.** `migrate apply` records only when it created the
+  database or applied a migration; an apply with nothing pending must not
+  re-record, because it is step one of the remedy this signal publishes and
+  re-recording from the damaged state would manufacture its own all-clear
+  (`test_a_pending_free_apply_does_not_re_record_over_a_damaged_state`,
+  `test_an_apply_that_changes_the_store_records_the_new_count`). What stays open,
+  recorded and not fixed: an apply that *does* have a migration to apply re-records
+  over the state as it then is, so damage already present becomes the new
+  expectation. It is the pointer's limit again — a count is not a checksum, and a
+  writer can record only what it can read.
+
+  The detector also found a defect in the test suite it does not own.
+  `tests/integration/test_absence_proof.py` built its pair by hand with a pointer
+  claiming one applied migration over a store holding none, so every response in
+  that file had carried `integrity` since PR1 and each equality was comparing two
+  damage reports. Both records are now written the way `migrate apply` writes
+  them, and `_assert_the_pair_bites` fails an example that answers as a damaged
+  project — the fifth way that file can be green while proving nothing.
+
+### Changed
+
+- **BREAKING — `SCHEMA_VERSION` 2 → 3: every existing state database is refused
+  once, and one `theurian migrate apply` rebuilds it**
+  ([#30](https://github.com/theurian/theurian/issues/30) PR2,
+  [#24](https://github.com/theurian/theurian/issues/24)). The DDL gains the
+  `project_integrity` table and makes the item → revision pointer a composite
+  foreign key; `knowledge.status` therefore publishes `schemaVersion: 3` where it
+  published `2`. A state database is derived and Git-ignored (ADR-0004) and is
+  rebuilt rather than migrated (ADR-0017), so nothing authored is lost — but the
+  rebuild is not automatic, and until it runs the three read tools refuse.
+  BREAKING for a state database on disk, not for the wire: a published value
+  moves and no field, type or tool name does, so `protocolVersion` stays
+  `theurian/v1` (see *Changing this contract* in
+  [`docs/protocol/mcp-tools.md`](../../docs/protocol/mcp-tools.md)).
+
+  Measured end to end rather than argued, against a database `0.1.0.dev3` wrote
+  with the real CLI and then read by this build: `knowledge.search`,
+  `knowledge.get` and `knowledge.status` each refuse with
+
+  ```
+  theurian-state-f1711b98d302.sqlite was written at schema version 2, but this
+  build uses 3. State databases are derived; rebuild with `theurian migrate
+  apply` rather than migrating this file.
+  ```
+
+  and one `theurian migrate apply` answers `databaseCreated: true` with a new
+  state hash — the schema version is an input to that hash, so the rebuilt file is
+  `theurian-state-2e8880bf25be.sqlite` beside the old one — after which all three
+  tools answer, `schemaVersion` reads `3`, and no `integrity` key appears. The old
+  file is left on disk for `theurian index gc` (ADR-0017 decision 5), not deleted
+  under a pinned `snapshotId`.
+
+  A database written at *any* earlier version is refused *unread* rather than
+  reinterpreted, which is what lets the new detector read a missing
+  `project_integrity` row as damage rather than as "this file predates the table"
+  (`test_a_pre_integrity_database_is_refused_unread_by_every_tool`, parametrised
+  over every version below the current one).
+
+- **The item → revision pointer is scoped to its project by the schema, not only
+  by every read of it** ([#24](https://github.com/theurian/theurian/issues/24),
+  closed). `knowledge_items.current_revision_id` referenced
+  `knowledge_revisions(revision_id)` alone while `get_revision` and
+  `list_revisions` both filter on `project_id` as well, so the two never met: a
+  revision whose `project_id` moved — what a project id changing over an unchanged
+  root does — left the item pointing at a row its own project-scoped read could no
+  longer see, and `PRAGMA foreign_key_check` called the database satisfied.
+
+  The key is now composite, `(project_id, current_revision_id)` referencing
+  `knowledge_revisions(project_id, revision_id)` over a new unique index. Measured
+  on SQLite 3.51.2, before and after, against the stranding `UPDATE`: before, the
+  writer's own connection accepted it and `foreign_key_check` returned `[]`;
+  after, the same statement is refused, and forced through with foreign keys off
+  it is reported as `('knowledge_items', <rowid>, 'knowledge_revisions', 0)`.
+  `test_a_revision_cannot_be_moved_out_from_under_the_item_pointing_at_it` holds
+  both arms — the stranding move refused, a revision no item points at still
+  movable — so a key that refused every write to that column would fail it too.
+
+  A `NULL` `current_revision_id` still satisfies the key, because a composite
+  child key with a NULL component imposes no constraint in SQLite; an item exists
+  before its first revision is upserted. The four `# pragma: no cover` branches
+  whose justification was "the pointer is a foreign key" now say what actually
+  holds them, and the claim is true for the first time. INV-2's other half — that
+  the revision belongs to the same *item* — is enforced above the database and in
+  nothing the schema declares: by `KnowledgeItem.with_revision` in the domain, and
+  by `append_revision` and `put_item` in both `MigrationWriter` adapters.
+
+### Security
+
+- **Derived state under `.theurian/state/` is served only if this installation
+  built it (threat-model T-19, ADR-0004, SEC-7).** Everything there — the active
+  pointers and the SQLite databases they name — is derived and git-ignored, but a
+  repository contributor can force-add a doctored copy past that ignore (`git add
+  -f`), and a victim who clones (or downloads the ZIP/tarball), `theurian project
+  register`s, and serves over MCP **without ever running `theurian migrate
+  apply`** was served the attacker's bytes: a `rejected` body relabelled
+  `approved`, rows injected, titles and excerpts rewritten in the index.
+
+  This is the self-consistent face the read-back guards cannot catch. The #30 PR2
+  detector and the item → revision pointer guard above find a derived state that
+  *disagrees with its own records*; this attacker authors both sides, at the
+  current schema version, so there is no inconsistency to find. `active.json`'s
+  `stateHash` binds the migration *set*, not the database bytes, and the database
+  filename is derived from that hash, so the doctored pair is self-consistent by
+  construction. The only property a repository author cannot forge is whether
+  *this installation* built the artifact.
+
+  **Control: an out-of-tree build-provenance anchor.** `theurian migrate apply`
+  and `theurian index build` record the state hash and index build id this
+  install produced for each project root in `THEURIAN_DATA_DIR/provenance.json` —
+  beside the project registry, out of the repository tree where a contributor
+  cannot write (`BuildProvenance`). Every MCP read path checks it before a byte of
+  `.theurian/state/` reaches a caller: `_resolve` refuses a canonical state whose
+  hash this install did not build (`verify_state_provenance`, covering
+  `knowledge.get`, `knowledge.search`, `knowledge.status`); the ranked path stands
+  aside from an index build id this install did not build. Both paths that
+  generate an index are gated on source-index provenance, so neither launders a
+  committed one: `index build` refuses to build *from* an unprovenanced canonical
+  state, and — since commit `dc6aa79` — the withdrawal purge refuses to copy a
+  committed index forward and record it when this install did not build the source
+  index (`UNTRUSTED_SOURCE_INDEX`), the second laundering path review found. And
+  `migrate apply` discards an unprovenanced database and rebuilds from the
+  Git-tracked migrations; a committed `-wal` cannot replay because
+  `create_database` refuses to write over an existing file, so the rebuild deletes
+  the main database and creates a fresh one with no database for the sidecar to
+  replay into — the sidecars are removed too, redundant defense-in-depth.
+  Those migrations are vouched for by human PR review (T-1), not by FR-K5: on a
+  fresh clone nothing has been applied, so FR-K5 has no recorded checksum to
+  disagree with an attacker-authored migration, and re-derivation is safe because
+  a reviewer read the migration diff.
+
+  Delivery-independent by construction: the discriminator is "did this install
+  build it", not "is it tracked by Git", so a clone, a ZIP download and a
+  repackaged tarball are refused alike — which a `git ls-files` probe could not
+  do. Pinned by `tests/integration/test_state_provenance.py`, whose closure
+  invariant is one query against two checkouts: a checkout shipping derived state
+  and one shipping none produce identical served knowledge, both refused until the
+  state is built locally.
+
+  **Effect on existing installs, and it is deliberate.** A project already built
+  by a pre-`0.1.0.dev4` build has no provenance record, so the three read tools
+  refuse it until one `theurian migrate apply` (then `theurian index build`)
+  rebuilds it and records provenance — the same one-command rebuild the
+  `SCHEMA_VERSION` bump above already requires, and nothing authored is lost
+  (ADR-0004). The residual is recorded in T-19: provenance vouches for a hash, not
+  for the database bytes, so replacing a database *after* this install built the
+  matching hash is out of scope for this control and left to the schema gate, the
+  #30 read-back guards, and the corruption checks.
+
+  <!-- Advisory (GHSA) reference for T-19 to be filled at release, when the
+  advisory ships; embargoed until then. -->
+
+- **`knowledge.search` gains one `fallbackReason`, `index-unbuilt`**, emitted when
+  the published index was not built by this installation and the ranked path
+  therefore stands aside to the provenance-gated canonical scan. A new published
+  *value*, not a new field, type or tool, so `protocolVersion` stays `theurian/v1`
+  by the same rule the `SCHEMA_VERSION` entry above applies; the JSON Schema
+  `schemas/mcp/retrieval-metadata.schema.json` adds the `const`.
+
 ## [0.1.0.dev3] - 2026-08-15
 
 ### Added
@@ -179,6 +1155,9 @@ Pre-1.0, a MINOR bump may change the protocol. Post-1.0, only a MAJOR may.
   with is now a refusal. Only negative values are refused — a non-negative integer
   that is simply wrong is still accepted, which is the one-way limit recorded
   above and in the threat model.
+
+- **`knowledge.status` no longer refuses over a corrupt
+  `migration_history.migration_id` or `checksum`; it answers cleanly**
   ([#30](https://github.com/theurian/theurian/issues/30) PR1). The refusal was a
   side effect of parsing rows the tool no longer reads: it used to call
   `applied_migrations`, which converts both cells and raises on a damaged one,
@@ -434,7 +1413,8 @@ Pre-1.0, a MINOR bump may change the protocol. Post-1.0, only a MAJOR may.
 
 - **A reused `revisionId` across two items no longer leaks a withheld item's body**
   ([GHSA-7997-g35f-q59h](https://github.com/theurian/theurian/security/advisories/GHSA-7997-g35f-q59h);
-  fix commit to be linked at publication). **BREAKING (state database schema).**
+  fixed in [`67c0e81`](https://github.com/theurian/theurian/commit/67c0e81)).
+  **BREAKING (state database schema).**
   In 0.1.0.dev0–0.1.0.dev2 a migration that reused an existing `revisionId` under
   a second `itemId` — the shape a copy-pasted `upsertRevision` block produces —
   pointed the second (approved) item's current revision at the first item's