theurian 0.1.0.dev7__tar.gz → 0.1.0.dev8__tar.gz

{theurian-0.1.0.dev7 → theurian-0.1.0.dev8}/.gitignore

@@ -19,17 +19,6 @@ dist/
 coverage.xml
 htmlcov/
 
-# --- Theurian derived artifacts -------------------------------------------
-# Canonical state is rebuilt from Git-tracked migrations and content.
-# Never commit any of these. See docs/adr/0004-sqlite-is-a-derived-artifact.md
-.theurian/state/
-.theurian/cache/
-.theurian/runtime/
-.theurian/generated/
-*.sqlite
-*.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
@@ -58,3 +47,14 @@ htmlcov/
 .env.*
 !.env.example
 *.token
+
+# >>> theurian >>>
+# Derived artifacts. Rebuilt from Git-tracked migrations (ADR-0004).
+.theurian/state/
+.theurian/cache/
+.theurian/runtime/
+.theurian/generated/
+*.sqlite
+*.sqlite-wal
+*.sqlite-shm
+# <<< theurian <<<

{theurian-0.1.0.dev7 → theurian-0.1.0.dev8}/CHANGELOG.md

@@ -12,6 +12,166 @@ Pre-1.0, a MINOR bump may change the protocol. Post-1.0, only a MAJOR may.
 
 ## [Unreleased]
 
+## [0.1.0.dev8] - 2026-08-20
+
+### Added
+
+- **`evidence.json` now records the `migrationId` and `itemId` its proposal
+  drafted** ([#253](https://github.com/theurian/theurian/issues/253)). These are
+  the two fields of that file Core reads back: together they let `propose accept`
+  ask whether a migration with that id, operating on that item, is in
+  `.theurian/migrations/`. Both are a contributor's claim, not authority —
+  `evidence.json` is committed and untrusted (ADR-0013 point 7) — so `itemId` is
+  the cross-check that stops a forged `migrationId` (one pointing at another
+  proposal's landed migration) from reading as accepted. Optional on read: the 26
+  proposals committed in this repository predate both fields and are diagnosed by
+  best-effort inference, which their message says.
+
+### Fixed
+
+- **The installed migration schema resolved `$ref`s over the network, and its
+  resolution failures escaped as raw tracebacks**
+  ([#235](https://github.com/theurian/theurian/issues/235)). The migration
+  schema was validated with `jsonschema`'s default registry, whose retrieve
+  callable fetches an external `$ref` over the network
+  (`urllib.request.urlopen`) at validate time — and reads a `file://` ref off
+  disk the same way. An SSRF-shaped read gated only on the installed schema
+  being corrupted or replaced (an operator-side precondition; `schema_root()`
+  never reads user-project paths), and covered by no existing claim:
+  `parsers/openapi.py`'s "external `$ref` targets are recorded, never fetched"
+  governs *ingested* documents, not the schema this build ships. Every
+  validator is now built with `referencing`'s `EMPTY_REGISTRY` — no retrieve
+  callable — so an external `$ref` fails closed; internal `#/$defs/…` refs
+  still resolve from the schema's own root resource, so the bundled schema
+  validates unchanged. Separately, the resulting resolution failures — an
+  unresolvable `$ref`/`$dynamicRef` raises `referencing.exceptions.Unresolvable`
+  and a self-recursive or empty `$ref` raises `RecursionError`, neither a
+  `ValidationError` — used to slip past every `except ValidationError` seam and
+  reach `resolve_context` as a raw traceback under `--json`. Both are now
+  translated to `SchemaUnreadableError`, the type every other
+  installed-schema-corruption failure already carries, at both validate seams
+  (`migrate validate` / `propose`, and any command that loads migrations from
+  disk).
+- **A path-containment refusal told the user to go somewhere they already were,
+  and could instruct them to delete their own work**
+  ([#233](https://github.com/theurian/theurian/issues/233)). With
+  `.theurian/migrations` — or one `*.yaml` file inside it — a symlink pointing
+  outside the project, `theurian migrate validate --json` printed
+  `{"error": "Path escapes the permitted root /<absolute>/<project>", "remedy":
+  "Run this inside an initialised Theurian project."}` at exit 1. The refusal
+  itself was correct and is unchanged; what it said about itself was not.
+  `PathEscapeError` set no `remedy` of its own, so the CLI's generic fallback
+  won — the "exception that does not describe itself" shape
+  [#205](https://github.com/theurian/theurian/issues/205) exists to end. It now
+  names, relative to the project root and with the `!r` quoting its siblings
+  use, *where* the problem is — and **no remedy names a file to delete.** That
+  is the substantive change: an escape happens through a symbolic link somewhere
+  on the entry's ancestor chain or its resolution chain, and which link it is
+  cannot be determined from the entry alone. Three successive attempts to
+  determine it anyway were each refuted by a deeper construction — the last by
+  `x.yaml → y.yaml → outside`, where following the remedy deleted two
+  Git-tracked files and ended at `valid: true` while the minimal cure was
+  repointing `y` alone. So the remedy now states only what `lstat` proves — that
+  the named entry is or is not itself a link — and then hands over the finite
+  checklist: this entry, the directories above it, the links it resolves
+  through. "Repoint that link, or remove that link" refers to whichever the
+  reader finds; Theurian never names it. Related: an outside-pointing
+  `.theurian` is reachable from a plain `git clone`
+  ([#237](https://github.com/theurian/theurian/issues/237)). The offending path
+  is still never echoed (SEC-7), and neither is the absolute project root.
+- **A `contentFile` refusal no longer denies the commonest cure.** The
+  path-escape remedy for a `contentFile` used to say that removing the `..` was
+  "not the cure" — wrong for a plain over-traversal typo, which involves no
+  symlink at all and is fixed by exactly that edit, and in conflict with the
+  sibling `MigrationContentUnreadableError`, which tells the author to fix the
+  path. It now offers both candidates: correct the path, or find the link
+  something it traverses goes through.
+- **Exit code:** a `PathEscapeError` raised while resolving a project now exits
+  `EXIT_STATE_ERROR` (4) rather than 1 for the commands routed through
+  `_require_project` — measured, all nine: `migrate validate`, `migrate status`,
+  `migrate apply`, `index build`, `index status`, `index gc`, `ingest`,
+  `propose` and `propose accept` — matching every sibling refusal on the same
+  load path (`MigrationsDirectoryUnreadableError`,
+  `MigrationFileUnreadableError`, `MigrationError`). A script keying on exit 1
+  for those must be updated. `init` and `project register` call
+  `resolve_context` directly and still exit 1; `project status` reports at exit
+  0 as it always has. All three now carry the new remedy text.
+- **A path refused only for nesting too deep no longer claims to have escaped**
+  ([#233](https://github.com/theurian/theurian/issues/233)). `resolve_within_root`
+  refuses a path past `MAX_PATH_DEPTH` whether or not it ever leaves the root,
+  and reported it as `Path escapes the permitted root` — false for a path
+  sitting entirely inside. It now raises `PathDepthExceededError` with its own
+  message and a remedy about flattening the nesting. The new type is a
+  `PathEscapeError` subclass, so every existing `except` and every exit-code
+  route catches it unchanged; only what the caller is told differs.
+- **An interrupted `theurian propose` was diagnosed as an accepted one**
+  ([#253](https://github.com/theurian/theurian/issues/253)). `propose accept`
+  read the presence of `evidence.json` as "this proposal has already been
+  accepted", but `propose` writes the body, then the evidence, then the
+  migration — so a run killed before its last write left exactly that shape.
+  `accept` reported that the migration had been moved into
+  `.theurian/migrations/` and that no action was needed beyond opening a pull
+  request, while `.theurian/migrations/` held nothing and the drafted knowledge
+  existed nowhere. The remedy discarded the draft.
+
+  Acceptance is a **best-effort diagnosis over untrusted input, not a
+  tamper-proof fact**: the proposal directory is contributor-controlled, so the
+  recorded `migrationId` is a claim (cross-checked by `itemId` against the
+  migration it names), a `evidence.json` that is present but unreadable is
+  answered as *indeterminate* rather than collapsed into "no record", and every
+  fallible branch points the reader at `.theurian/migrations/` first — no branch
+  emits an unconditional "no action is needed" or "draft it again", so none can
+  tell the author to discard work that may exist or duplicate a change that
+  already landed. Whether a migration is in place under the recorded id is read
+  from the same approved `MigrationSet` `migrate validate`/`apply` read — keyed by
+  the migration's inner id, not by a filename match — so `propose accept` cannot
+  disagree with the loader about what has landed, whatever a migration file was
+  renamed to or whether it is a symlink. The three states are kept distinct by
+  their exit codes: a migration in place under the recorded id — whether or not
+  the item cross-checks — exits 4 ("read before acting"), and only a recorded id
+  the loaded set holds *no* migration for exits 1 ("nothing landed, re-draft"), so
+  following exit 1 can never mint a duplicate of a change on disk. Absent
+  `evidence.json` (a legacy proposal, or
+  one interrupted before its evidence write) falls to inference over the
+  directory, which reads only the body shape the generator produces, so a
+  reviewer's notes or a `Thumbs.db` left beside an accepted proposal no longer
+  flips the verdict.
+
+- **A committed proposal could forge `theurian propose accept`'s own output**
+  ([#253](https://github.com/theurian/theurian/issues/253)). A proposal directory
+  arrives through a contributor's pull request, and a file name or a migration's
+  `contentFile` carrying `ESC [ 2 K` and a carriage return erases the line the
+  terminal has drawn and prints its own in place of it — reproduced printing this
+  command's own output under its own name, on both the refusal path and the
+  exit-0 **success** payload (`bodyFiles`, `migrationFile`). The CLI now escapes
+  every terminal-control character — the whole C0 block, `DEL` and C1 — at one
+  shared sink that every text-mode emitter routes each value and key through, so
+  no value any command prints, from any source, reaches a terminal with a raw
+  control byte. A value's own newline is escaped too (the output's structural
+  newlines are the emitters' own), while printable Unicode (a Japanese title) is
+  kept. The `--json` output was never affected.
+
+### Changed
+
+- **BREAKING — re-accepting an already-accepted proposal now exits 4, not 1**
+  ([#254](https://github.com/theurian/theurian/issues/254)). The published exit
+  code table documented 4 for "that migration is already in place", while the
+  natural route to that state — running `theurian propose accept` twice — exited
+  1 alongside "no such proposal", an interrupted draft, and a refused
+  `contentFile`. Exit 4 keeps its meaning and gains this case: *the knowledge
+  state refuses this move, so read it before acting*. It is not "already done" —
+  an approved migration set that cannot be read also exits 4, with the proposal
+  still waiting — and the published table now says so rather than promising that
+  1 always means nothing landed. Scripts that treat any non-zero exit as failure
+  are unaffected; one that special-cased 1 for "already accepted" must read 4.
+
+  Breaking by the compatibility table in
+  [`docs/protocol/plugin-core-compatibility.md`](../../docs/protocol/plugin-core-compatibility.md),
+  and `protocolVersion` is **not** bumped for it — a recorded, narrowly scoped
+  exemption on the same grounds as `system.capabilities.milestone`'s (#206),
+  written up under "Changing this contract" in
+  [`docs/protocol/mcp-tools.md`](../../docs/protocol/mcp-tools.md).
+
 ## [0.1.0.dev7] - 2026-08-19
 
 ### Added

{theurian-0.1.0.dev7 → theurian-0.1.0.dev8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: theurian
-Version: 0.1.0.dev7
+Version: 0.1.0.dev8
 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
@@ -22,6 +22,7 @@ Requires-Dist: jsonschema==4.26.0
 Requires-Dist: pydantic==2.13.4
 Requires-Dist: python-ulid==4.0.1
 Requires-Dist: pyyaml==6.0.3
+Requires-Dist: referencing==0.37.0
 Requires-Dist: typer==0.27.1
 Provides-Extra: all
 Requires-Dist: mcp==2.0.0; extra == 'all'

{theurian-0.1.0.dev7 → theurian-0.1.0.dev8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "theurian"
-version = "0.1.0.dev7"
+version = "0.1.0.dev8"
 description = "Git-native engineering knowledge platform: versioned, traceable context for AI agents."
 readme = "README.md"
 requires-python = ">=3.13"
@@ -36,6 +36,11 @@ dependencies = [
     "pydantic==2.13.4",
     "python-ulid==4.0.1",
     "pyyaml==6.0.3",
+    # jsonschema's public reference-resolution API, imported directly for the
+    # no-network registry that keeps the installed migration schema offline
+    # (issue #235). A transitive dep of jsonschema, declared here because we
+    # import it -- ADR-0014's "import what you declare".
+    "referencing==0.37.0",
     "typer==0.27.1",
 ]
 

{theurian-0.1.0.dev7 → theurian-0.1.0.dev8}/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.dev7"
+__version__ = "0.1.0.dev8"
 __protocol_version__ = CURRENT_PROTOCOL_VERSION
 
 __all__ = ["__protocol_version__", "__version__"]