theurian 0.1.0.dev4__tar.gz → 0.1.0.dev5__tar.gz

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

@@ -12,6 +12,713 @@ 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