theurian 0.1.0.dev2__tar.gz → 0.1.0.dev3__tar.gz

{theurian-0.1.0.dev2 → theurian-0.1.0.dev3}/.gitignore

@@ -30,6 +30,22 @@ htmlcov/
 *.sqlite-wal
 *.sqlite-shm
 
+# --- Documentation site (derived) ---
+# `mkdocs build` writes site/. The Pages workflow copies the logo into
+# docs/assets/ before building, so anyone replicating that build locally
+# creates it too; the tracked copy is assets/theurian-logo.svg.
+#
+# The workflow also fetches the mermaid bundle into docs/js/ before building.
+#
+# Every pattern in this section is anchored, unlike the older ones above, and
+# the anchors matter here. An unanchored site/ would also ignore docs/site/,
+# packages/*/site/ and tests/fixtures/site/. Naming the generated files rather
+# than the directories docs/assets/ and docs/js/ leaves anything else added to
+# them visible to git status — docs/js/ also holds tracked source.
+/site/
+/docs/assets/theurian-logo.svg
+/docs/js/mermaid.min.js
+
 # --- OS / editor ---
 .DS_Store
 .idea/

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

@@ -12,6 +12,498 @@ Pre-1.0, a MINOR bump may change the protocol. Post-1.0, only a MAJOR may.
 
 ## [Unreleased]
 
+## [0.1.0.dev3] - 2026-08-15
+
+### Added
+
+- **A present-only `integrity` object discloses derived-state damage on
+  `knowledge.search`, `knowledge.get` and `knowledge.status`**
+  ([#30](https://github.com/theurian/theurian/issues/30), PR1 of five positions —
+  one closes here, four remain).
+
+  ```json
+  {
+    "integrity": {
+      "damageDetected": true,
+      "remedy": "Run `theurian migrate apply` to rebuild the derived state from the Git-tracked migrations. If this signal persists, delete `.theurian/state/` and run `theurian migrate apply` again, then `theurian index build` to restore ranked retrieval; the state is derived, so nothing is lost."
+    }
+  }
+  ```
+
+  **The key is present only when a bounded check detected a discrepancy, and its
+  absence asserts nothing.** No `integrity` key means the check did not fire —
+  which is *not* "verified clean" and must not be read as one. There is
+  deliberately no `damageDetected: false` form: the detector is incomplete by
+  design, so a `false` token would publish "checked and clean" over a check that
+  never made that claim, while absence cannot be misread without a caller
+  inventing a claim of its own. `damageDetected` is therefore always `true` when
+  present, kept explicit rather than reduced to a bare boolean so the object can
+  gain a second field without a wire break. This is the same present-only shape
+  `raptorPath` already uses (ADR-0008 decision 8), so the wire already branches on
+  key presence; the schema declares the key as an optional property precisely so
+  `additionalProperties: false` keeps holding when it appears
+  (`knowledge-search-response.schema.json`,
+  `knowledge-status-response.schema.json`; `knowledge.get` still publishes no
+  response schema, [#20](https://github.com/theurian/theurian/issues/20)).
+
+  **What PR1 detects is a migration-count mismatch, and nothing finer.**
+  `expected` is the active pointer's own `migrationCount`, carried from the same
+  resolution of `active.json` that chose the state database rather than re-read;
+  `live` is `SELECT COUNT(*) FROM migration_history INDEXED BY
+  idx_migration_history_sequence WHERE project_id = ?`. The state database is
+  immutable once built, so a healthy project has `live == expected` and any
+  difference is damage — `!=`, not `<`, so another project's rows reaching this
+  one count too (`test_a_surplus_migration_row_is_damage_on_every_read_tool`,
+  which is RED against `>=` in place of `!=`; the `WHERE project_id = ?` that
+  keeps a *sibling* project's rows out of `live` is
+  `test_a_sibling_projects_rows_in_the_same_file_forge_no_mismatch`). Both sides
+  are pinned: a lost row surfaces the field from each of the three tools
+  (`test_a_lost_migration_row_surfaces_integrity_from_knowledge_search`,
+  `…_status`, `…_get`, each RED when that tool's emission is unplugged) and a
+  healthy build emits it from none of them
+  (`test_a_healthy_build_emits_no_integrity_field_from_any_tool`, and
+  `test_a_re_apply_and_a_third_migration_leave_every_tool_silent` for the same
+  silence after the pointer has moved). The wire form is validated against the
+  schemas from a damaged project rather than a healthy one, where the optional
+  key is never present to check
+  (`test_the_damaged_captures_really_carry_the_optional_integrity_key`,
+  `test_the_integrity_conformance_check_can_fail`).
+
+  **The signal carries no bit about withheld content, and its cost carries none
+  either.** It reads `migration_history`, a table no gate filters, so nothing it
+  counts scales with the withheld set —
+  `test_the_integrity_signal_is_identical_across_a_withheld_only_difference`
+  measures whether the key appears across two corpora differing only in
+  twenty-five `rejected` items and asserts it is identical for all three tools.
+  The added per-request read on `knowledge.search` is answered from the covering
+  index — SQLite plans `SEARCH migration_history USING COVERING INDEX
+  idx_migration_history_sequence (project_id=?)`, so its cost is `O(migrations)`
+  and independent of the corpus — which is what keeps it off the `O(withheld)`
+  timing channels [#19](https://github.com/theurian/theurian/issues/19) and
+  [#158](https://github.com/theurian/theurian/issues/158) closed
+  (`test_the_search_integrity_count_is_answered_by_a_covering_index`, pinning both
+  the `INDEXED BY` hint in the statement the store really runs and the plan
+  SQLite produces for it). The plan assertion requires the *seek* — `SEARCH`, the
+  index name, and the `(project_id=?` that opens the constraint list — because the
+  index name alone appears on a `SCAN` line too: reversing the declared columns to
+  `(sequence, project_id)` keeps the name and walks every project's migration
+  entries at 172× the work, measured, and passed the earlier substring. The same
+  strengthening was applied to `idx_items_status`'s assertion in
+  `test_status_count_is_answered_by_a_covering_index`.
+
+  **`knowledge.get` distinguishes damage from absence in its refusal message.**
+  It refuses with a bare string and no field, so the distinction lives in the
+  text: where the check reports damage, an item it could not read is now reported
+  as a project that "could not be fully read: its derived state holds a different
+  number of migration-history rows than its own records expect", not as an item
+  that is not present. Both directions are pinned, because either alone is
+  satisfied by a tool that says one thing always
+  (`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`). The SEC-13
+  rule that a withheld id and an absent id get the same message is unchanged.
+
+  **What this does not cover.** Four `SILENTLY_EMPTIED` positions remain and are
+  carried to PR2 — `(knowledge.search, knowledge_items, item_id)`,
+  `(knowledge.search, knowledge_items, project_id)`,
+  `(knowledge.status, knowledge_items, project_id)`,
+  `(knowledge.status, knowledge_items, status)`. A migration-count check cannot
+  see any of them: they empty a result rather than the migration history, so
+  `live` still equals `expected` and the key stays absent exactly as on a healthy
+  project. That is what "absence asserts nothing" means in practice.
+
+  **The `remedy` names a fallback, because one command does not cure both
+  directions.**
+  `theurian migrate apply` is the cheap cure and comes first — measured, it clears
+  a lost row, a sentinel in `migration_history.project_id`, and an over-counting
+  pointer. It clears nothing for a *surplus* row: every authored migration is
+  already applied, so three consecutive runs exited 0 with `applied: [], changed:
+  false` and left the key present. Deleting `.theurian/state/` makes the next apply
+  rebuild the database (`databaseCreated: true`, key absent), and `theurian index
+  build` is named third because that deletion takes the published retrieval index
+  with it — measured, `retrieval.indexed` is `false` with `fallbackReason:
+  "no-index"` until the rebuild runs, so without the third step "nothing is lost"
+  would be false. The efficacy is measured, not yet pinned by a test.
+
+  Two further limits, measured rather than assumed, both recorded in
+  [the threat model](../../docs/security/threat-model.md) under T-17:
+
+  - **A pointer whose `migrationCount` is wrong in the same direction as the rows
+    is undetectable.** The check compares two derived numbers against each other,
+    never against the Git-tracked migrations, so a state that lost its migration
+    row *and* a pointer recording `0` agree — measured, all three tools answer,
+    `knowledge.status` publishes `appliedMigrations: 0` against a project holding
+    one applied migration, and `migrate status`, `migrate apply` and `index build`
+    all exit 0. A pointer wrong on its own does fire the key (measured at `2` and
+    at `0` against one live row), but the signal cannot say which side is wrong,
+    and `appliedMigrations` publishes the pointer's number either way.
+  - **Corrupt `migration_history.applied_at` or `.sequence` is seen by no shipped
+    surface at all** — measured: all three tools answer cleanly, and `migrate
+    status`, `migrate apply` (with and without a new migration to apply) and
+    `index build` all exit 0.
+
+### Changed
+
+- **`knowledge.status` reports `appliedMigrations` from the active pointer's
+  `migrationCount`, not from a live count of `migration_history` rows**
+  ([#30](https://github.com/theurian/theurian/issues/30) PR1). On a healthy
+  project the two are equal by construction and no response changes. They diverge
+  only under damage, and there the pointer's count is the authoritative one:
+  before this change a corrupt `migration_history.project_id` dropped every row
+  out of the `WHERE`, so the tool answered `appliedMigrations: 0` against a
+  project that had applied several — a successful, false statement, and the
+  `SILENTLY_EMPTIED` position PR1 closes. The live count is now compared against
+  the pointer and any difference — in either direction — disclosed through
+  `integrity` instead of published as the answer
+  (`test_a_corrupt_migration_project_id_is_disclosed_not_silently_emptied`;
+  `test_no_tool_answers_with_less_than_the_intact_database_holds` holds the set at
+  four members and goes RED if the field starts shrinking again). **A behaviour
+  change for a caller that compares this field against a row count it obtained
+  some other way**: over a damaged state the two now disagree by design, and the
+  `integrity` key is what says so.
+
+- **A negative `migrationCount` in `.theurian/state/active.json` is now refused
+  at parse time, where it used to be published**
+  ([#30](https://github.com/theurian/theurian/issues/30) PR1). `knowledge.status`
+  reports that field as `appliedMigrations`, whose schema declares `minimum: 0`,
+  and `ActiveState.from_json` accepted any integer. Measured before the fix:
+  `migrationCount: -5` reached the wire as `appliedMigrations: -5`, so the
+  response violated its own published contract — and a strict client rejects the
+  whole response, including the `integrity` key riding along on it to say the
+  state is damaged. The one field reporting the damage was thrown away by the
+  damage. It is now a `DomainError` at parse time, converted by
+  `read_active_state` into the `ProjectError` a corrupt pointer already produced,
+  so all three read tools refuse with "Malformed active state pointer:
+  migrationCount is negative (-5)" and the delete-the-pointer-and-re-apply cure
+  (`test_a_negative_migration_count_is_refused_by_every_read_tool`). **A behaviour
+  change for anyone who hand-edits the pointer**: a value that used to be answered
+  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.
+  ([#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,
+  and it now calls a bare `COUNT` that interprets neither. Measured on the
+  corruption corpus: with a sentinel in either column the tool returns its six
+  keys and no `integrity` — the count is unaffected, so the check does not fire —
+  while `applied_migrations` over the same database still raises
+  `StateDatabaseUnreadableError`. No published `knowledge.status` field is
+  derived from either cell, and `migrate status` and `migrate apply` still exit 4
+  over both, so migration tamper is still detected where it is acted on. Recorded
+  rather than marked BREAKING because no published contract promised the refusal
+  and no field, type or tool name changed (see *Changing this contract* in
+  [`docs/protocol/mcp-tools.md`](../../docs/protocol/mcp-tools.md)).
+
+  **It is a real reduction in what the read tools notice, and it is now pinned as
+  an exact six-cell set** rather than left to a reader:
+  `ANSWERED_CLEAN_OVER_A_DAMAGED_CELL` in
+  `tests/integration/test_canonical_store_corruption.py` names all three tools
+  over both cells, and
+  `test_exactly_these_positions_answer_cleanly_over_a_cell_the_cli_calls_tampering`
+  reads it against the CLI sweep — so the silence is only green while `migrate
+  status` and `migrate apply` keep exiting non-zero on the same cells, and a read
+  tool that starts refusing again fails it too. Its counterpart
+  `test_exactly_these_positions_disclose_migration_history_damage_as_integrity`
+  keeps that set from going vacuous by naming the three positions
+  (`migration_history.project_id` on each tool) that must fire the key.
+
+- **`theurian setup` and `theurian auth rotate` rewrite only the Theurian-owned
+  block in `<data_dir>/env`, and leave every other byte of that file alone**
+  ([#128](https://github.com/theurian/theurian/issues/128)). Both used to render
+  the whole file and truncate whatever else was in it, and `probe_env_reference`
+  reported `Missing` on any difference — so a line somebody had added to a file
+  whose own header says "Sourced by your shell profile" was destroyed with no
+  diff, no backup and no mention in `changedPaths`, on every run of a command whose
+  contract is that running it twice changes nothing (FR-L2). §6.2 row 7 of the
+  requirements analysis had required "rewrite the Theurian-owned block only"
+  throughout. The block is delimited by `# >>> theurian >>>` and
+  `# <<< theurian <<<`, spelled exactly as the pair `theurian init` writes into a
+  `.gitignore` so that someone who has seen one managed block recognises the
+  other, and the merge is computed *before* the file is opened — so a file that
+  cannot be delimited is never opened at all.
+
+  **What an operator upgrading from `0.1.0.dev0`–`dev2` sees.** Those versions
+  wrote the whole file as a fixed rendering of the data directory, so the first
+  `setup` or `auth rotate` after upgrading recognises that rendering and replaces
+  it *in place* with the marked block: one `export THEURIAN_MCP_TOKEN` afterwards
+  and not two, with lines added before it still before it and lines added after
+  it still after it. Appending the block beside the old rendering would have left
+  two assignments naming different paths once a data directory moves — the shell
+  taking whichever came last, while setup reported the machine converged.
+
+  **Recognition is exact, and deliberately not fuzzy**: those lines must be
+  consecutive and whole, and must name *this* data directory's token path. A
+  rendering somebody edited, and one written for another installation, are
+  therefore left alone and the block is appended below them — two visible
+  exports, the shell keeping the block because it reads it last. That is the
+  honest answer for a line somebody changed on purpose; matching it loosely is
+  what glued the block over half of one in the first cut.
+
+  **A marker is a whole line, and the first cut of this fix did not do that.**
+  Review found it substring-based: `str.find` opened the span at the first
+  *occurrence* of the start marker, so `echo "everything between
+  # >>> theurian >>> and here"` opened one and the rewrite cut that line in half,
+  leaving an unclosed quote that poisons every line after it in a sourced file;
+  the count that was supposed to catch a second start looked only at what
+  followed the *end* marker, so `S`, a user's line, `S`, the block, `E` — what
+  repairing an unterminated block by pasting a fresh one under it leaves — was
+  swallowed whole; and the dev0–dev2 rendering was matched as a substring, so
+  `export THEURIAN_MCP_TOKEN  # my note` had the block spliced over its first
+  half and the leftovers glued onto the end marker. Measured over every file a
+  start marker, an end marker and a user's line build up to five lines long, 363
+  arrangements: **39 took the wrong refusal decision and 16 of those reported
+  success while dropping 19 of the user's lines**, one of them an
+  `export AWS_SECRET_ACCESS_KEY`, with the run reporting `converged` and the
+  re-probe `satisfied`. What shipped matches whole lines — split on `\n` alone,
+  a trailing `\r` dropped, so a CRLF file delimits — and counts the start lines
+  over the whole file *before* choosing a span, which is what makes the second
+  one's position irrelevant.
+
+  **A behaviour change for a file whose markers do not delimit exactly one
+  block** — two or more start lines anywhere in the file, or a start line with no
+  end line after it. That used to be overwritten; it is now `Conflicting`,
+  because once the delimiters disagree setup cannot tell which lines are its own.
+  An *end* line with no start above it, and a second end line, are not that: they
+  delimit nothing, and they are kept like any other line. `setup` writes nothing
+  there, declares no path for it, and stops at consent; `--approve-conflicts`
+  applies the rest of the plan and still leaves that file byte-identical,
+  finishing `degraded` with the step named in `warnings`. `auth rotate` leaves the
+  file untouched, **still rotates the token**, and prepends one line to
+  `nextSteps` naming the file to repair — an exposed credential outranks a comment
+  marker, and the token has already been replaced by the time that file is
+  reached. The same holds when the OS refuses the write — a read-only checkout, a
+  file another account owns, a full disk: rotation completes and `nextSteps`
+  carries the exception's class name and never its message, which holds
+  `strerror`, the errno and on some platforms a second path. The conflict detail
+  carries the two marker strings, the path they are in and the command to re-run,
+  and no other line out of that file, because `doctor --report` publishes it
+  (O-3, SEC-6).
+
+  **A run can be right about the block and wrong about the machine, and now says
+  so for the direct assignment forms.** A shell keeps the last assignment it
+  reads, so a line *below* the block assigning `THEURIAN_MCP_TOKEN` again is what
+  gets exported while the probe — deliberately blind to lines it does not own —
+  reports the block current. That line is not Theurian's to edit and it is not a
+  conflict either; the step stays `satisfied` and carries a caveat, which
+  `_reservations` turns into a warning, so the run ends **`degraded` where it
+  used to end `converged`**. The warning names the path, the variable and the
+  start marker to move the line above, and never the line itself. A bare
+  `export THEURIAN_MCP_TOKEN` or a commented-out assignment is not an override
+  and leaves the run converged. Currency is asked first, so a block that is both
+  stale and shadowed is rewritten and *then* reported, rather than reported
+  instead of fixed.
+
+  **What finds that line is a heuristic, and the scope is published rather than
+  implied.** `contains_shadowing_assignment` reads one line at a time and
+  recognises a first word spelled `THEURIAN_MCP_TOKEN=…`, or that word after
+  `export`, `declare`, `typeset` or `readonly`. It is wrong in both directions,
+  measured with `/bin/bash` sourcing the block and then the line: an `&&` list,
+  an `if`/`then`, a `{ }` group and an `eval` each assign the variable while the
+  run stays **silent and `converged`**, and an assignment inside a quoted heredoc
+  *body* draws the warning although the shell keeps the block's value. The four
+  misses are pinned **as** the recorded boundary, each through a real shell
+  rather than restated against the function, so a change that starts warning on
+  one of them has to arrive with an argument and update the pin deliberately. Not
+  extended, and that is the decision rather than a to-do: what a line does is
+  settled by the shell at run time — `eval` takes a string that need not exist
+  until then, and a heredoc body is not shell at all — and a probe that runs
+  somebody's shell profile is not a probe. The residual is carried in the wording
+  instead: both published sentences say the line *appears* to assign and the
+  block *appears* to be overridden, which is what keeps the heredoc case honest,
+  and both are pinned — dropping the hedge from the `summary` alone, the sentence
+  a reader who stops at `satisfied` sees, survived all 2,442 tests while the
+  `detail`'s was held. **What stays unqualified** is the other arm's summary,
+  "`…/env` exports `THEURIAN_MCP_TOKEN` by reference" — and the `converged` the
+  run reports beside it. On a machine using one of the four evading shapes both
+  are true of the block and incomplete about the machine; measured through the
+  real CLI, `theurian doctor --json` publishes that summary, zero warnings and
+  exit 0 while `bash` exports the later line's value. Recorded here and in §6.2
+  row 7 rather than fixed, because no line-level rule can tell that machine from
+  a healthy one.
+
+  **`theurian doctor` and `theurian setup --dry-run` now carry that warning
+  too**, which is the caller-visible half of this. The sentence was built in the
+  verification pass alone, so on one machine `theurian setup` said `degraded`
+  with the caveat while `theurian doctor --json` said `"warnings": []` and exited
+  0 — the caveat sitting in the payload the whole time as the `detail` of a step
+  whose status reads `satisfied`, which is where a reader stops. Both surfaces
+  that publish a plan now build their warnings with the same `_reservations`, so
+  a shadowed machine gains one `env-reference: …` line in `doctor --json`,
+  `doctor --report` and the `--dry-run` plan the plugin renders. Nothing else
+  moved, deliberately: a reservation is a finding with no work attached, so
+  `healthy`, `problemCount` and the exit status stay tied to what setup would
+  change and what needs consent, and a machine whose only finding is a line
+  Theurian will not touch still exits 0. The reports built on the way *past* a
+  plan — `aborted`, `awaiting_consent` and `halted` — carry no reservations, and
+  that is recorded rather than closed in `_reservations`' docstring: each hands
+  the reader a larger question first, and the step's `detail` still travels with
+  the report.
+
+  **Line endings are bytes somebody chose.** Both writers read and write with
+  newline translation off, so a file edited on Windows keeps its `\r` bytes
+  outside the block — including a `\r` inside a quoted value, which translation
+  would turn into a newline and split the assignment in two. The block itself is
+  written with `\n`, so a block that arrived with CRLF markers is normalised on
+  the first run and is a fixed point after that.
+
+  **The same class in `theurian init`.** `ensure_gitignore` writes an
+  identically-spelled block into a repository's `.gitignore` with the same
+  `str.find` and no count of the start markers, so a file holding two of them —
+  what resolving a merge conflict by keeping both sides leaves behind — had every
+  rule between them swallowed by the rewrite and reported as `changed: true` with
+  nothing else said. It now matches whole lines, counts the starts first, keeps a
+  CRLF `.gitignore`'s line endings, and refuses both undelimited shapes. **The
+  refusal also reaches a person differently**: it used to arrive as a Typer
+  traceback with the remedy buried in it, because the only `except` in
+  `init_command` wrapped context resolution, and it is now `error: …` plus a
+  remedy on stderr with exit 1. A refused run leaves the `.theurian/`
+  directories it had already created; nothing else is written.
+
+  **Not marked BREAKING, and here is the one place it is arguable.** No MCP tool,
+  field, type or name changed, and no published contract promised any of this
+  (see *Changing this contract* in
+  [`docs/protocol/mcp-tools.md`](../../docs/protocol/mcp-tools.md)). What did
+  change for a script is exit status on two inputs. `theurian init` over a
+  `.gitignore` holding two start markers used to exit 0 having silently eaten the
+  rules between them, and now exits 1 (an *unterminated* block already failed,
+  though as a traceback). `theurian setup` over an env file in either state used
+  to rewrite it and count the step converged; it now stops the whole run at
+  consent — exit 5, `EXIT_NEEDS_CONSENT` — before `_apply` is reached, so nothing
+  at all is written. Both are the fix, not a side effect of it.
+
+  Idempotence is now measured on the file rather than on the report: a converged
+  second run does not reopen it at all, witnessed on the mtime, so a run that
+  rewrote identical bytes fails the pin. The write goes *through* the inode
+  rather than temp-and-rename, because this file is a symlink into a dotfiles
+  repository on plenty of machines, and through an `io.BufferedWriter`, because a
+  short write here would now destroy lines Theurian did not author. 74 tests, 97
+  collected cases: `tests/unit/test_env_file_merge.py` (33 tests, including one
+  that sweeps all 363 arrangements against a rule read off the symbols rather
+  than off the code), `tests/integration/test_setup_env_file.py` (21, driving the
+  real `SetupService` over real files because the defect lived in the seam — a
+  probe asking one question while the apply performs a different write is exactly
+  what shipped, two of them — five cases — asking a real `bash` what a file
+  exports rather than asking the heuristic to agree with itself),
+  `tests/integration/test_init_gitignore_block.py` (9, through the real
+  `theurian init`), `tests/integration/test_auth_rotate.py` (6 added),
+  `tests/integration/test_setup_cli.py` (3 added, for the `doctor` and
+  `--dry-run` parity above), and `tests/integration/test_setup_service.py` (2
+  added). The last two of those close pins that were simply absent: nothing
+  asserted `CONVERGED` by value — replacing `_verify`'s state choice with an
+  unconditional `DEGRADED` passed the whole suite, because `succeeded` is true of
+  both — and nothing asserted the *status* half of the reservation test, so
+  reporting every explained `NOT_APPLICABLE` step as a warning, which would turn
+  the supply-chain note on row 3 into something wrong with this install, passed
+  it too. Four parser decision points gained pins the same way: a marker line
+  with a trailing space is not a marker, in the env file **and** in the
+  `.gitignore` scan beside it; the block is searched for before the dev0–dev2
+  rendering; markers that cannot be resolved are refused even where that
+  rendering is also present; and the probe asks currency before shadowing.
+
+  **Round two re-measured the parser rather than re-reading it.** A second sweep
+  over an extended alphabet, 2,800 shapes, found no arrangement that loses a line
+  outside the block or takes the wrong refusal decision; the two writers were
+  compared over 84 file-state combinations and produce identical bytes; and the
+  six numbers this entry publishes — 363, 229 refused, 134 merged, and the first
+  cut's 39, 16 and 19 — were re-measured exact. Those are review measurements and
+  not suite tests: what guards the rule from here on is the 363-arrangement
+  sweep, which asserts its own population size so a shrunken alphabet fails
+  rather than passing quietly.
+
+  **Two remedies now describe the state they are reached from.** The `.gitignore`
+  refusal said "Add `# <<< theurian <<<` where the block ends" to a person whose
+  file appears to have that line already — a marker is matched as a whole line,
+  so a trailing space is the likeliest way to reach an unterminated block, and
+  the remedy sent them looking for what was in front of them; it now says what
+  the line must be, trailing space and all. `auth rotate`'s `OSError` remedy
+  offered "an older block, or readable by other accounts" for a file that can
+  also be left *empty*, since the `open` truncates before the write that failed —
+  reproduced under `RLIMIT_FSIZE`, 588 bytes in and 16 out — and now admits that
+  state. A third correction is not user-visible: the comment above the rotation's
+  env-file refresh enumerated the shapes it handles, absent, stale and
+  pre-marker, without the residual — a line below the block that assigns the
+  token again survives the rotation and produces the 401 anyway, and `doctor` is
+  what reports it.
+
+  This supersedes one sentence of `0.1.0.dev2`'s `changed_paths` entry below. The
+  env file's truncation is still disclosed on the arm that motivated it, but
+  "what it replaced is preserved nowhere" no longer holds: what a completed write
+  puts back includes the lines the run did not author. What stays unpinned, as
+  there, is the window between the truncation and the write's last byte.
+
+### Security
+
+- **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).**
+  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
+  revision row. When that first item was withheld (for example `status:
+  rejected`), its full body — title, source anchors, and any secret that caused
+  the rejection — reached `knowledge.get` and `knowledge.search` for a caller who
+  requested the *approved* item's id. Requesting the withheld id directly was
+  still correctly refused; the reuse bypassed that gate, and `migrate validate` /
+  `migrate apply` reported nothing.
+
+  **Fixed** by making `append_revision` refuse to treat a reused `revisionId` as
+  an idempotent no-op when the stored row belongs to a different item — a revision
+  id names one item for the life of a project — with a symmetric store-level guard
+  in `put_item` that refuses a `current_revision_id` naming another item's
+  revision. The state database `SCHEMA_VERSION` is bumped from 1 to 2 (an input to
+  the derived-state hash), so a state database written by an affected version — the
+  old shape, opened and served regardless of provenance — is refused on open and
+  rebuilt from the Git-tracked migrations on the next `theurian migrate apply`. The
+  derived state carries no data that is not recoverable from those migrations, so
+  the rebuild strands nothing. If the migration set itself encodes the reuse, that
+  rebuild refuses it (exit 4, naming the reused `revisionId`) until the operation
+  is given its own id. **Updating the build alone does not remediate a database an
+  affected version already wrote; run `theurian migrate apply` after upgrading.**
+
+  Affected: `theurian` 0.1.0.dev0, 0.1.0.dev1, 0.1.0.dev2. Fixed in 0.1.0.dev3.
+
+- **The substring-search fallback's withheld-count timing channel is closed**
+  ([#158](https://github.com/theurian/theurian/issues/158)), the twin of #19's
+  `knowledge.status` fix. `knowledge.search`'s unranked fallback
+  (`mcp/search.py::_scan`) used to read every item with `list_items` (`SELECT *`,
+  no status predicate) and drop the withheld rows in Python, so its response time
+  scaled with the withheld count and a caller with a stopwatch could recover by
+  subtraction exactly what `count` withholds (T-17). It now resolves the
+  surfaceable statuses and reads through `SqliteCanonicalStore.list_items_by_status`,
+  whose `status IN (...)` is forced through the `idx_items_status` index, so a
+  withheld row is never materialised and the read cost is independent of the
+  withheld count: SQLite VM steps stay flat at 119–120 across 0/50/300/1,000
+  withheld where the old scan went 63 → 913 → 5,163, and the result set is
+  byte-identical. Pinned by
+  `test_the_substring_scan_reads_items_through_idx_items_status`,
+  `test_the_substring_scan_materializes_the_same_rows_however_many_are_withheld`,
+  and `test_the_substring_scan_never_surfaces_a_retired_item_even_with_include_unapproved`
+  in `tests/integration/test_mcp_tools.py`. Two trades are recorded, not fixed: a
+  corrupt `status` cell on this path is now silently dropped by the SQL filter
+  rather than crashing the Python `may_surface` parse it replaced — the same
+  crash → silent-drop trade #19 made for `knowledge.status`, carried with that
+  integrity class as [#30](https://github.com/theurian/theurian/issues/30) — and
+  the fallback's rows-and-memory page bound stays a deferred DoS residual (T-6),
+  since bounding it changes the search fallback's published surface.
+
+- **The unresolved-project error now bounds the `projectId` it echoes**
+  ([#17](https://github.com/theurian/theurian/issues/17)), the last member of the
+  error-echo amplification class. `mcp/tools.py::_unresolvable` interpolated the
+  caller's raw `projectId` into the "not registered" message with no length bound:
+  `_resolve` runs before any `ProjectId` is constructed, so a 2,000,000-character
+  id produced a 2,000,141-character message — an ~1× amplifier of the caller's own
+  bytes. An unregistered id longer than `MAX_IDENTIFIER_LENGTH` (200, the ceiling a
+  `ProjectId` cannot exceed, duplicated in the JSON schemas as `maxLength: 200`) is
+  now reported by its length and never echoed; a well-formed unregistered id within
+  the ceiling is still named so a typo stays visible. That matches the discipline
+  `MAX_QUERY_CHARS` already holds for `query` and `ItemId` for `itemId`, so all
+  three error-echo members are bounded. Not a disclosure — the caller only ever
+  gets back bytes it sent (the `Registered:` list is the daemon's own registry
+  contents, SEC-13). Pinned by
+  `test_an_over_long_project_id_is_reported_by_length_not_echoed` and
+  `test_the_project_id_echo_is_named_up_to_the_id_ceiling_then_by_length` in
+  `tests/integration/test_mcp_tools.py`; see T-6 in
+  [the threat model](../../docs/security/threat-model.md).
+
 ## [0.1.0.dev2] - 2026-08-12
 
 ### Added

{theurian-0.1.0.dev2 → theurian-0.1.0.dev3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: theurian
-Version: 0.1.0.dev2
+Version: 0.1.0.dev3
 Summary: Git-native engineering knowledge platform: versioned, traceable context for AI agents.
 Project-URL: Homepage, https://github.com/theurian/theurian
 Project-URL: Documentation, https://github.com/theurian/theurian/tree/main/docs

{theurian-0.1.0.dev2 → theurian-0.1.0.dev3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "theurian"
-version = "0.1.0.dev2"
+version = "0.1.0.dev3"
 description = "Git-native engineering knowledge platform: versioned, traceable context for AI agents."
 readme = "README.md"
 requires-python = ">=3.13"

{theurian-0.1.0.dev2 → theurian-0.1.0.dev3}/src/theurian/__init__.py

@@ -8,7 +8,7 @@ plugin must never import them (ADR-0001, CP-2).
 
 from theurian.domain.compatibility import CURRENT_PROTOCOL_VERSION
 
-__version__ = "0.1.0.dev2"
+__version__ = "0.1.0.dev3"
 __protocol_version__ = CURRENT_PROTOCOL_VERSION
 
 __all__ = ["__protocol_version__", "__version__"]