textus 0.4.0 → 0.8.0

data/SPEC.md

@@ -1,7 +1,7 @@
-# textus/1 — Specification
+# textus/2 — Specification
 
-**Status:** Draft v1.0 (2026-05-19)
-**Protocol identifier:** `textus/1`
+**Status:** Draft v2.0 (2026-05-19)
+**Protocol identifier:** `textus/2`
 **Reference implementation:** Ruby gem `textus`
 
 > *textus* — Latin for "the fabric a text is woven from," same root as *context* (from *con-texere*, "to weave together"). This spec defines a storage shape and wire protocol for that fabric.
@@ -31,7 +31,7 @@ textus is organized as five composable layers. Each layer has a single responsib
 ## 2. Goals and non-goals
 
 **Goals**
-- Stable wire format (`textus/1`) any language can speak.
+- Stable wire format (`textus/2`) any language can speak.
 - Deterministic read/write of structured Markdown via a CLI returning JSON.
 - Schema-validated frontmatter using YAML schemas as data.
 - Role-based write gates (humans, scripts, AI, build runners get different permissions per zone).
@@ -91,7 +91,7 @@ The manifest declares: (a) which zones exist and which roles may write to each,
 
 ```yaml
 # .textus/manifest.yaml
-version: textus/1
+version: textus/2
 
 zones:
   - name: canon
@@ -139,7 +139,7 @@ zones:
 
 Old manifests written against textus/1 draft v0.1 therefore parse without modification, and any tooling expecting `fixed`/`state`/`derived` continues to work.
 
-**Key grammar (enforced from v1.2):** dotted segments matching `/^[a-z0-9][a-z0-9-]*$/`. Segments are joined by `.`. A key has at most 8 segments; each segment is at most 64 characters. Segments MUST NOT contain dots, slashes, uppercase letters, or underscores. Example: `working.projects.acme.dashboard`. Enforcement points: manifest load (rejects illegal `key:` declarations and illegal nested file/directory names), `put` (rejects illegal keys before any write), `enumerate` (filters and warns on illegal filenames so existing trees still load with a clear migration message). Run-once migration: `textus migrate-keys --dry-run` then `--write` (see §audit).
+**Key grammar (enforced from v1.2):** dotted segments matching `/^[a-z0-9][a-z0-9-]*$/`. Segments are joined by `.`. A key has at most 8 segments; each segment is at most 64 characters. Segments MUST NOT contain dots, slashes, uppercase letters, or underscores. Example: `working.projects.acme.dashboard`. Enforcement points: manifest load (rejects illegal `key:` declarations and illegal nested file/directory names), `put` (rejects illegal keys before any write), `enumerate` (filters and warns on illegal filenames so existing trees still load with a clear migration message). Run-once migration: `textus key migrate --dry-run` then `--write` (see §audit).
 
 **Per-entry `format:` (enforced from v1.2):** an entry MAY declare `format:` to be one of `markdown` (default), `json`, `yaml`, or `text`. The `format` controls the on-disk shape and which path extension is required:
 
@@ -250,38 +250,36 @@ A sentinel is written for each published file at `<store_root>/sentinels/<target
 
 **Per-leaf publishing.** A nested entry MAY declare `publish_each:` instead of `publish_to:` (see §4). When the build runs, every leaf reachable under the nested entry is byte-copied to the path produced by substituting `{leaf}` / `{basename}` / `{key}` / `{ext}` in the template, with a sentinel written under `<store_root>/sentinels/` at the mirrored target path. The build envelope grows a `published_leaves` array — one row per leaf, with `key`, `source`, and `target` — alongside the existing `built` array. Targets that would resolve outside the repo root are refused.
 
-### 5.4 Intake (declared, refreshed via registered action)
+### 5.4 Intake (declared, refreshed via registered fetch hook)
 
-Intake entries declare an external source by naming an **action** — a registered, named function that pulls data into the entry. textus itself still makes no implicit network calls: an action only runs in intake mode when explicitly invoked by `textus refresh KEY --as=script`. The declaration is data only:
+Intake entries declare an external source by naming a **fetch hook** — a registered, named function that pulls data into the entry. textus itself still makes no implicit network calls: a fetch hook only runs in intake mode when explicitly invoked by `textus refresh KEY --as=script`. The declaration is data only:
 
 ```yaml
 - key: intake.calendar.events
   zone: intake
   source:
-    action: ical-events
+    fetch: ical-events
     config:
       url: "https://calendar.google.com/.../basic.ics"
     ttl: 6h
 ```
 
-`action` names a registered action; `config` is an opaque hash handed to the action; `ttl` is the staleness budget. Implementations MUST reject legacy `source.from`, `source.parse`, and `source.fetcher` with a clear usage error.
+`fetch` names a registered `:fetch` hook (see §5.10 for the hook contract); `config` is an opaque hash handed to the hook; `ttl` is the staleness budget. Implementations MUST reject legacy `source.from`, `source.parse`, `source.fetcher`, and `source.action` with a clear usage error.
 
-**Action contract (intake mode).** An action is registered via `Textus.action(:name) do |config:, store:, args:| ... end`. In intake mode the action MUST return one of three shapes, all normalized by the store into its internal `{frontmatter, body, content}` representation (§5.12):
+In intake mode the hook MUST return one of three shapes, all normalized by the store into its internal `{_meta, body, content}` representation (§5.12):
 
-- `{ frontmatter:, body: }` — markdown-friendly.
+- `{ _meta:, body: }` — markdown-friendly; `_meta` becomes the entry's parsed metadata hash.
 - `{ content: }` — for `format: json|yaml` entries; the parsed object becomes the entry's content.
 - `{ body: }` — raw bytes for `text` or for any format that prefers verbatim writes; the store re-parses and validates per `format:`.
 
-The `store:` argument is a writable `Textus::StoreView` (§5.11) bound to the calling role; the `args:` argument is `{}` in intake mode (it carries CLI flags in verb mode — §5.11). Every action call is wrapped in `Timeout.timeout(2)`; exceptions and timeouts surface as `usage` errors that abort the refresh.
-
-**Built-in actions.** `json`, `csv`, `markdown-links`, `ical-events`, `rss` are always available. They expect raw bytes in `config["bytes"]` and produce structured frontmatter/body. Built-ins do not perform I/O themselves — the caller (or an outer action) is responsible for supplying bytes.
+**Built-in fetch hooks.** `json`, `csv`, `markdown-links`, `ical-events`, `rss` are always available. They expect raw bytes in `config["bytes"]` and produce structured `_meta`/body. Built-ins do not perform I/O themselves — the caller (or an outer hook) is responsible for supplying bytes.
 
 **Refresh paths.** Two are supported:
 
-1. **In-process** — `textus refresh KEY --as=script` resolves the entry's `source.action`, invokes it with `(config:, store:, args: {})`, and writes the result under role `script`.
+1. **In-process** — `textus refresh KEY --as=script` resolves the entry's `source.fetch`, invokes the registered `:fetch` hook with `(config:, store:, args: {})`, and writes the result under role `script`.
 2. **External runner** — a cron job or agent harness reads `textus list --zone=intake --stale --format=json`, fetches the source out of band, and pipes bytes back through `textus put KEY --as=script --stdin`.
 
-Both paths share the same role gate, audit-log entry, and `:refresh` event (§5.10). User-supplied actions live in `.textus/extensions/*.rb` and auto-load at `Store#initialize` (§5.11).
+Both paths share the same role gate, audit-log entry, and `:refresh` event. User-supplied hooks live in `.textus/hooks/*.rb` and auto-load at `Store#initialize` — see §5.10 for the full hook contract.
 
 ### 5.5 Pending / accept workflow
 
@@ -306,15 +304,19 @@ Proposed body content.
 
 ### 5.6 Audit log
 
-Every successful write appends one line to an append-only TSV file at `.textus/audit.log`. The file is opened with `flock(LOCK_EX)` for the duration of each append so concurrent writers serialize cleanly.
+Every successful write appends one compact JSON object (NDJSON) to `.textus/audit.log`. The file is opened with `flock(LOCK_EX)` for the duration of each append so concurrent writers serialize cleanly.
 
-Schema (tab-separated, one record per line):
+Schema (one JSON object per line, no interior whitespace):
 
+```json
+{"ts":"<iso8601-utc>","role":"<role>","verb":"<verb>","key":"<key>","etag_before":<etag-or-null>,"etag_after":<etag-or-null>}
 ```
-<iso8601-utc>\t<role>\t<verb>\t<key>\t<etag-before-or-NULL>\t<etag-after-or-NULL>
-```
 
-`<iso8601-utc>` is the wall-clock timestamp in UTC with second (or finer) precision. `<role>` is the resolved role for the invocation. `<verb>` is the CLI verb (`put`, `delete`, `accept`, `compute`, `migrate-keys`, `mv`, ...). `<key>` is the affected entry key. For `mv`, `<key>` is the **new** key, and an extras JSON column carries `from_key`, `to_key`, `from_path`, `to_path`, and `uid`. `<etag-before>` and `<etag-after>` are the entry etags before and after the write, or the literal string `NULL` when not applicable (e.g. create has no before-etag, delete has no after-etag). `migrate-keys --write` emits one line per renamed file using the new key as `<key>` and the file's pre- and post-rename etags.
+`ts` is the wall-clock timestamp in UTC with second precision. `role` is the resolved role for the invocation. `verb` is the audit-log payload string identifying the operation (`put`, `delete`, `accept`, `compute`, `migrate-keys`, `mv`, ...). Note that `migrate-keys` here is the on-disk payload key — the CLI surface is `textus key migrate`; the payload string is retained for log stability. `key` is the affected entry key. `etag_before` and `etag_after` are the entry etags before and after the write, or JSON `null` when not applicable (e.g. create has no before-etag, delete has no after-etag). `key migrate --write` emits one line per renamed file (with payload `verb: "migrate-keys"`) using the new key as `key` and the file's pre- and post-rename etags.
+
+For `mv`, the structural fields `from_key`, `to_key`, and `uid` appear at the top level of the JSON object. Remaining verb-specific data (e.g. `from_path`, `to_path`) is nested under an `extras` key. The `extras` key is omitted entirely when empty.
+
+**Backward compatibility (v0.5):** files written by v0.4 and earlier contain TSV rows. Readers MUST accept mixed-format files: lines starting with `{` are parsed as JSON; other lines are treated as legacy TSV (`ts\trole\tverb\tkey\tetag_before\tetag_after[\tjson_extras]`). TSV write support is removed in v0.6.
 
 ### 5.7 Security bounds
 
@@ -351,118 +353,51 @@ evolution:
     OLD_FIELD: NEW_FIELD
 ```
 
-`textus schema-migrate NAME` consults `evolution.migrate_from` when invoked without `--rename=OLD:NEW`, applying every declared rename across affected entries in one pass. An explicit `--rename` flag overrides the schema-declared map for that invocation.
+`textus schema migrate NAME` consults `evolution.migrate_from` when invoked without `--rename=OLD:NEW`, applying every declared rename across affected entries in one pass. An explicit `--rename` flag overrides the schema-declared map for that invocation.
 
 **Backwards compat:** v1.0 schemas (no `fields:`, no `evolution:`) continue to parse and behave identically. `schema.maintained_by(field)` returns `nil` for every field; `schema.evolution` returns `{}`.
 
-**Override rule:** the role `human` is permitted to write any `maintained_by` field, regardless of declared owner. This preserves human authority over AI/script-managed data — humans curating canon over AI-written embeddings is a feature, not a bug. All other role mismatches are reported by `validate-all` with code `role_authority`, including fields `key`, `field`, `expected`, and `last_writer`.
+**Override rule:** the role `human` is permitted to write any `maintained_by` field, regardless of declared owner. This preserves human authority over AI/script-managed data — humans curating canon over AI-written embeddings is a feature, not a bug. All other role mismatches are reported by `doctor --check=schema_violations` with code `role_authority`, including fields `key`, `field`, `expected`, and `last_writer`.
 
 ### 5.9 Reducers (v1.2)
 
-Reducers are pure, named functions that shape projection rows into projection rows. Registered via the module-level DSL:
+Reducers are RPC hooks on the `:reduce` event. See §5.10.
 
-```ruby
-Textus.reducer(:rank_by_recency) do |rows:, config:|
-  rows.sort_by { |r| r["updated_at"].to_s }.reverse
-end
-```
-
-**Declaration.** A projection opts into a reducer via `projection.reducer`, with optional `projection.reducer_config`:
+### 5.10 Hooks
 
-```yaml
-projection:
-  select: [working.projects]
-  pluck:  [name, status, updated_at]
-  reducer: rank_by_recency
-  reducer_config: { tiebreak: name }
-  sort_by: updated_at
-  limit: 50
-```
+textus has a single extension verb: `Textus.hook(event, name, **opts) { ... }`. The EVENTS table below defines every extension point. Files in `.textus/hooks/*.rb` are `load`ed at `Store#initialize` in lexical order.
 
-The reducer runs **between pluck and sort**. `config:` receives the manifest's `reducer_config` hash (or `{}`). Rows in, rows out.
+| Event    | Mode    | Args                              | Return        | Failure |
+|----------|---------|-----------------------------------|---------------|---------|
+| :fetch   | rpc     | store:, config:, args:            | {_meta:, body:}       | aborts op |
+| :reduce  | rpc     | store:, rows:, config:            | rows array            | aborts op |
+| :check   | rpc     | store:                            | issues array          | aborts doctor |
+| :put     | pubsub  | store:, key:, envelope:           | (discarded)           | logged   |
+| :delete  | pubsub  | store:, key:                      | (discarded)           | logged   |
+| :refresh | pubsub  | store:, key:, envelope:, change:  | (discarded)           | logged   |
+| :build   | pubsub  | store:, key:, envelope:, sources: | (discarded)           | logged   |
+| :accept  | pubsub  | store:, key:, target_key:         | (discarded)           | logged   |
 
-**Purity.** A reducer MUST NOT perform I/O or mutate the store; no `store:` kwarg is passed.
+**Signature invariant** — every hook receives `store:` as its first keyword argument. Event-specific kwargs follow in stable left-to-right order. The primary entity is always `key:` (for `:accept`, `key:` is the pending key being accepted and `target_key:` is the destination).
 
-**Timeout.** Each invocation is wrapped in `Timeout.timeout(Textus::Projection::REDUCER_TIMEOUT_SECONDS)` (2s). Timeouts, exceptions, and unknown names raise `usage` errors and abort the build.
+**RPC mode** — exactly one handler per (event, name). The manifest references the handler by name (`source.fetch: NAME`, `projection.reduce: NAME`). Failure or timeout aborts the calling operation.
 
-**Auto-load.** Reducers register from `.textus/extensions/*.rb`, loaded at `Store#initialize` in lexical order (§5.11). The registry is per-Store; reducers do not share state across `Store` instances.
+**Pub-sub mode** — zero or more handlers per event. All matching handlers fire. The `keys:` option restricts a handler to keys matching one of the given globs (`File.fnmatch?` rules). Absence of `keys:` fires on every event of that type. Handler failures and 2s timeouts are logged to `audit.log` as `event_error` rows; they NEVER abort the triggering operation.
 
-### 5.10 Events (v1.2)
+The `store:` argument is always a read-only store proxy. Write attempts raise `UsageError`.
 
-Lifecycle events fire in-process. Subscribers register via `Textus.hook(:event, :name) do |**kwargs| ... end`. Hooks are fire-and-forget: return values are discarded.
-
-**Event set and kwargs:**
-
-| Event     | Fired by                | Kwargs                                                       |
-|-----------|-------------------------|--------------------------------------------------------------|
-| `:put`    | `Store#put`             | `key:, envelope:, store:`                                    |
-| `:delete` | `Store#delete`          | `key:, store:`                                               |
-| `:refresh`| `Refresh.call`          | `key:, envelope:, store:, change:` (`:created` or `:updated`)|
-| `:build`  | `Builder#materialize`   | `key:, envelope:, store:, sources:`                          |
-| `:accept` | `Proposal.accept`       | `pending_key:, target_key:, store:`                          |
-
-`:refresh` with `change: :unchanged` does NOT fire — only `:created` and `:updated` are emitted. The `store:` kwarg is always a `Textus::StoreView` (§5.11).
-
-**Timeout and isolation.** Each hook runs under `Timeout.timeout(2)`. Hook errors and timeouts are recorded as `event_error` rows in `.textus/audit.log` (column 7, JSON-encoded extras with `event`, `hook`, `error`) but do NOT abort the triggering operation. The store write that fired the event is already committed by the time hooks run.
-
-**Manifest declarations.** A manifest entry MAY declare external-runner hooks under an `events:` block, keyed by event name:
-
-```yaml
-events:
-  refresh:
-    - { exec: scripts/reindex.sh, as: script }
-  build:
-    - { exec: scripts/rebuild-index.sh, as: build }
-```
-
-Textus does NOT invoke these — they surface only through `textus extensions list --kind=hook` for orchestrators (lefthook, cron, CI) to consume. Each entry has `exec` (opaque runner-resolvable string) and `as` (role to claim, defaults to `script`).
-
-**Removed.** The v1.1 `on_stale` event is removed in 0.2. Staleness is a poll, surfaced by `textus stale`. The `on_`-prefix convention from v1.1 is gone; events are bare symbols.
-
-### 5.11 Extension surface (v1.3)
-
-Four DSL verbs cover all user-supplied code:
-
-```
-Textus.action(:name)         do |config:, store:, args:|  ... end   # intake mode: returns content; verb mode: writes via store.put
-Textus.reducer(:name)        do |rows:, config:|          ... end   # returns rows
-Textus.hook(:event, :name)   do |**kwargs|                ... end   # side effects; return ignored
-Textus.doctor_check(:name)   do |store:|                  ... end   # returns array of issue hashes
-```
-
-Files in `.textus/extensions/*.rb` are loaded at `Store#initialize`, in lexical order, with the registry installed as the current registry for that store. Registries are per-Store: two Store instances in the same process do not share state.
-
-**Action invocation modes.**
-
-| Mode    | Invoked by                | `config:`              | `store:`               | `args:`              | Return                                  |
-|---------|---------------------------|------------------------|------------------------|----------------------|------------------------------------------|
-| intake  | `textus refresh KEY`      | manifest `source.config` | writable view (role from `--as`) | `{}`                | required; normalized into entry write    |
-| verb    | `textus action NAME ...`  | `{}`                   | writable view (role from `--as`) | parsed CLI kv hash   | ignored                                  |
-| put-fetch | `textus put K --action=N --stdin` | `{ "bytes" => stdin }` | read-only view         | `{}`                 | required; merged into the put payload    |
-
-**Failure modes:**
-
-| Surface         | Timeout    | Exception                                   | Bad return |
-|-----------------|------------|---------------------------------------------|------------|
-| action          | aborts op  | aborts op (wrapped as `UsageError`)         | aborts op  |
-| reducer         | aborts op  | aborts op                                   | aborts op  |
-| hook            | logged     | logged (audit `event_error` row)            | n/a        |
-| doctor_check    | reported as `doctor_check.timeout` issue | reported as `doctor_check.failed` issue | reported as `doctor_check.bad_return` |
-
-Actions and reducers are pure transforms in modes where their return matters; their return values flow into the store. Hooks and doctor_checks shape side outputs (event chain, doctor report) — only doctor_check return values are merged.
-
-The `store:` argument is always a `Textus::StoreView`. In intake and verb modes it is writable and bound to the calling role; in put-fetch mode and inside doctor_checks it is read-only. Write attempts on a read-only view raise `Textus::UsageError`.
+Each handler runs under `Timeout.timeout(2)`.
 
 ### 5.12 Storage formats (v1.2)
 
-An entry's `format:` selects a storage strategy. All strategies expose the same `parse(bytes) → {frontmatter, body, content}` and `serialize(frontmatter:, body:, content:) → bytes` contract. The store, audit, etag, and projection layers operate on the parsed shape; only (de)serialization differs.
+An entry's `format:` selects a storage strategy. All strategies expose the same `parse(bytes) → {_meta, body, content}` and `serialize(meta:, body:, content:) → bytes` contract. The store, audit, etag, and projection layers operate on the parsed shape; only (de)serialization differs.
 
-- **markdown** — YAML frontmatter between `---` fences, free-form body. Parse: Psych `safe_load` on the front matter; body is the remainder. Serialize: emit `---\n<yaml>\n---\n<body>`. `content` is always `nil`.
-- **json** — entire file is a JSON document. Parse: `JSON.parse`. Serialize: `JSON.pretty_generate(content)` + trailing newline. `frontmatter` is populated from a top-level `_meta` hash (if present, else `{}`); `body` is the raw bytes; `content` is the parsed object.
-- **yaml** — entire file is a YAML mapping. Parse: `YAML.safe_load(bytes, permitted_classes: [Date, Time], aliases: false)`; anchors/aliases rejected. Serialize: `YAML.dump(content).sub(/\A---\n/, "")`. Same `_meta` / `frontmatter` / `body` / `content` rules as JSON.
-- **text** — raw UTF-8 bytes. Parse: body is the file verbatim, `frontmatter` is `{}`, `content` is `nil`. Serialize: write `body` bytes (with trailing newline if missing).
+- **markdown** — YAML frontmatter between `---` fences, free-form body. Parse: Psych `safe_load` on the frontmatter block; body is the remainder. Serialize: emit `---\n<yaml>\n---\n<body>`. `content` is always `nil`. `_meta` holds the parsed frontmatter hash.
+- **json** — entire file is a JSON document. Parse: `JSON.parse`. Serialize: `JSON.pretty_generate(content)` + trailing newline. `_meta` is populated from the top-level `_meta` hash (if present, else `{}`); `body` is the raw bytes; `content` is the parsed object with `_meta` stripped.
+- **yaml** — entire file is a YAML mapping. Parse: `YAML.safe_load(bytes, permitted_classes: [Date, Time], aliases: false)`; anchors/aliases rejected. Serialize: `YAML.dump(content).sub(/\A---\n/, "")`. Same `_meta` / `body` / `content` rules as JSON.
+- **text** — raw UTF-8 bytes. Parse: body is the file verbatim, `_meta` is `{}`, `content` is `nil`. Serialize: write `body` bytes (with trailing newline if missing).
 
-**Envelope shape.** Every envelope carries `format:` (always present, defaults to `markdown` for back-compat). For `json|yaml`, the envelope additionally carries `content:` (parsed object). `body` is always the raw on-disk bytes. `frontmatter` always exists, and for `json|yaml` mirrors the `_meta` block (`{}` if absent). `text` always has `frontmatter: {}` and no `content`.
+**Envelope shape.** Every envelope carries `format:` (always present, defaults to `markdown` for back-compat). For `json|yaml`, the envelope additionally carries `content:` (parsed object). `body` is always the raw on-disk bytes. `_meta` always exists in the envelope: for `markdown` it holds the parsed YAML frontmatter; for `json|yaml` it mirrors the top-level `_meta` block (`{}` if absent); for `text` it is `{}`.
 
 **`_meta` convention.** Derived structured entries (json, yaml) embed a `_meta` hash as the first top-level key. Builder-injected keys appear in a fixed order for etag stability:
 
@@ -529,13 +464,13 @@ Every successful CLI response (`--format=json`) is a single JSON envelope:
 
 ```json
 {
-  "protocol": "textus/1",
+  "protocol": "textus/2",
   "key": "working.network.org.jane",
   "zone": "working",
   "owner": "textus:network",
   "path": "/absolute/path/to/.textus/zones/working/network/org/jane.md",
   "format": "markdown",
-  "frontmatter": { "name": "jane", "relationship": "peer", "org": "acme" },
+  "_meta": { "name": "jane", "relationship": "peer", "org": "acme" },
   "body": "Short body in Markdown.\n",
   "etag": "sha256:8f3c…",
   "schema_ref": "person",
@@ -544,13 +479,13 @@ Every successful CLI response (`--format=json`) is a single JSON envelope:
 ```
 
 **Field rules:**
-- `protocol` MUST be the exact string `textus/1`.
+- `protocol` MUST be the exact string `textus/2`.
 - `key` MUST be the canonical resolved key.
 - `zone` MUST be one of the zones declared in the manifest (`canon`, `working`, `intake`, `pending`, `derived` for the default v1.0 model; legacy v0.1 manifests synthesize `fixed`, `state`, `derived` per §4).
 - `path` MUST be an absolute filesystem path.
 - `format` MUST be one of `markdown`, `json`, `yaml`, `text` (§5.12). Absent envelopes are treated as `markdown` for back-compat.
 - `body` is the raw on-disk bytes as a UTF-8 string for every format.
-- `content` is present only when `format` is `json` or `yaml`; equals the parsed object. For `json|yaml`, `frontmatter` mirrors the top-level `_meta` (or `{}` if absent).
+- `content` is present only when `format` is `json` or `yaml`; equals the parsed object. For `json|yaml`, `_meta` mirrors the top-level `_meta` block (or `{}` if absent). For `markdown`, `_meta` holds the parsed YAML frontmatter. For `text`, `_meta` is `{}`.
 - `etag` MUST be `sha256:<hex>` of the raw file bytes, computed identically for every format.
 - `schema_ref` MAY be `null` for entries in subtrees with `schema: null`.
 - `uid` is the stable Textus UID (§7) if the entry carries one, else `null`. Always present in the envelope.
@@ -559,7 +494,7 @@ Errors use a distinct envelope:
 
 ```json
 {
-  "protocol": "textus/1",
+  "protocol": "textus/2",
   "ok": false,
   "code": "write_forbidden",
   "message": "zone 'canon' is not writable by role 'ai' for key 'canon.identity'",
@@ -590,29 +525,29 @@ All verbs accept `--format=json` and emit a canonical envelope (success or error
 | `list [--prefix=K] [--zone=Z] [--stale]` | read | any |
 | `where K` | read | any |
 | `get K` | read | any |
-| `schema K` | read | any |
+| `schema show K` | read | any |
 | `stale [--prefix=K] [--strict]` | read | any |
 | `deps K` / `rdeps K` | read | any |
 | `published` | read | any |
-| `validate-all` | read | any |
-| `put K --stdin --as=R [--action=NAME]` | write | per zone |
+| `hook list` | read | any |
+| `doctor [--check=NAME[,NAME]] [--format=json]` | read | any |
+| `intro [--format=json]` | read | any |
+| `put K --stdin --as=R [--fetch=NAME]` | write | per zone |
 | `delete K --if-etag=E --as=R` | write | per zone |
 | `refresh K --as=script` | write | per zone (typically `script`) |
 | `build [--prefix=K] [--dry-run]` | write | `build` (default) |
 | `accept K --as=human` | write | `human` |
 | `init` | write | `human` |
-| `schema-init NAME` / `schema-diff NAME` / `schema-migrate NAME --rename=OLD:NEW` | write | `human` |
-| `migrate-keys [--dry-run\|--write]` | write (with `--write`) | `human` |
-| `mv OLD NEW [--as=R] [--dry-run]` | write | per zone (same-zone only) |
-| `uid K` | read | any |
-| `extensions list [--kind=action\|reducer\|hook]` | read | any |
-| `doctor [--format=json]` | read | any |
-| `intro [--format=json]` | read | any |
+| `schema init NAME` / `schema diff NAME` / `schema migrate NAME [--rename=OLD:NEW]` | write | `human` |
+| `key migrate [--dry-run\|--write]` | write (with `--write`) | `human` |
+| `key mv OLD NEW [--as=R] [--dry-run]` | write | per zone (same-zone only) |
+| `key uid K` | read | any |
+| `hook run NAME` | write | any |
 
 **`put` input** (read from stdin when `--stdin` is given):
 
 ```json
-{ "frontmatter": { "name": "jane", "relationship": "peer", "org": "acme" },
+{ "_meta": { "name": "jane", "relationship": "peer", "org": "acme" },
   "body": "Short body.\n",
   "if_etag": "sha256:8f3c…" }
 ```
@@ -637,7 +572,7 @@ All verbs accept `--format=json` and emit a canonical envelope (success or error
 
 `textus init` scaffolds a fresh `.textus/` tree (manifest, zones, schemas, audit log) under the current directory with a default manifest. Customize by editing `.textus/manifest.yaml` after init.
 
-`textus schema-init NAME` writes a stub schema. `schema-diff NAME` compares the on-disk schema against entries that claim it and prints the deltas. `schema-migrate NAME --rename=OLD:NEW` rewrites the frontmatter key `OLD` to `NEW` across every entry that uses the named schema, in a single transactional sweep that logs each touched file.
+`textus schema show K` prints the schema for entry `K`. `textus schema init NAME` writes a stub schema. `textus schema diff NAME` compares the on-disk schema against entries that claim it and prints the deltas. `textus schema migrate NAME --rename=OLD:NEW` rewrites the `_meta` key `OLD` to `NEW` across every entry that uses the named schema, in a single transactional sweep that logs each touched file.
 
 ## 10. ETag semantics
 
@@ -649,16 +584,17 @@ Every `Textus::Error` exposes `code`, `message`, and an optional `hint:`. The hi
 
 ## 10.2 `textus doctor`
 
-`textus doctor` returns a health-check envelope: `{ "protocol": "textus/1", "ok": bool, "issues": [...], "summary": {error, warning, info} }`. Each issue carries `code`, `level` (`error|warning|info`), `subject`, `message`, and optionally `fix`. `ok` is true iff no error-level issues are present; warnings and info do not flip the bit. Checks include manifest sanity, missing schemas/templates, extension load failures, illegal nested keys (with proposed normalisation), sentinel drift/orphans, and audit-log line corruption. Exit code is 0 on `ok`, 1 otherwise.
+`textus doctor` returns a health-check envelope: `{ "protocol": "textus/2", "ok": bool, "issues": [...], "summary": {error, warning, info} }`. Each issue carries `code`, `level` (`error|warning|info`), `subject`, `message`, and optionally `fix`. `ok` is true iff no error-level issues are present; warnings and info do not flip the bit. Builtin checks: `manifest_files`, `schemas`, `templates`, `hooks`, `illegal_keys`, `sentinels`, `audit_log`, `unowned_schema_fields`, `schema_violations`. Additional registered `:check` hooks (§5.10) run after the builtin set. Exit code is 0 on `ok`, 1 otherwise.
 
 ## 11. Versioning
 
-- The wire string `textus/1` is the protocol version.
-- Backward-compatible additions (new fields, new error codes, new schema types) MAY be made under `textus/1`.
-- Breaking changes (renamed/removed fields, zone semantics, key grammar) require a new wire string `textus/2`.
+- The current wire string is `textus/2`. It was introduced in gem v0.5, which unified the `_meta` block across all storage formats (markdown, json, yaml, text) and replaced the legacy TSV audit-log write path with NDJSON.
+- `textus/1` was the original protocol (gem ≤ v0.4). Manifests declaring `version: textus/1` are still accepted for backward compatibility (§4).
+- Backward-compatible additions (new fields, new error codes, new schema types) MAY be made under `textus/2`.
+- Breaking changes (renamed/removed envelope fields, zone semantics, key grammar) require a new wire string `textus/3`.
 - Implementations MUST reject envelopes whose `protocol` they do not recognize.
 
-The reference Ruby gem follows semver independently. Gem 1.x speaks `textus/1`.
+The reference Ruby gem follows semver independently. The current gem version is `0.8.0`, which speaks `textus/2`.
 
 ## 12. Conformance fixtures
 
@@ -686,7 +622,7 @@ Given a derived entry with a `template` clause referencing a `.mustache` file an
 Given a manifest entry with `publish_to: <path>`, a successful `textus build` for that entry leaves a plain file at `<path>` whose contents are byte-identical to the in-store artifact at `.textus/zones/<...>`, accompanied by a sentinel at `.textus/sentinels/<path>.textus-managed.json` recording `source`, `target`, `sha256`, and `mode: "copy"`. Re-running `build` is idempotent.
 
 **Fixture H — Audit log format:**
-Every successful write verb (`put`, `delete`, `build`, `accept`, `schema-migrate`) appends exactly one line per affected key to the audit log, in the canonical format defined in §audit (timestamp, actor role, verb, key, etag-before, etag-after). No write produces zero or multiple lines per key.
+Every successful write verb (`put`, `delete`, `build`, `accept`, `schema migrate`) appends exactly one line per affected key to the audit log, in the canonical format defined in §audit (timestamp, actor role, verb, key, etag-before, etag-after). No write produces zero or multiple lines per key.
 
 **Fixture I — Pending → accept:**
 Given a pending entry `pending.canon.identity.patch` proposing a change to `canon.identity`, `textus accept canon.identity --as=human` copies the patch body into `canon.identity`, deletes the pending entry, and appends two audit lines (one for the canon write, one for the pending delete) in that order.
@@ -695,19 +631,19 @@ Given a pending entry `pending.canon.identity.patch` proposing a change to `cano
 
 - **Why not MCP?** MCP is a transport; textus is a data model. The two compose: a 50-line MCP server can wrap `textus get/put` as tools. textus exists because the *shape* of agent-readable project memory deserves a standalone spec, separate from how it's served.
 
-- **Why doesn't textus execute generator commands itself?** textus is a dataflow oracle, not a build runner. The moment a spec includes process execution, it inherits shell-injection surface, OS-portability concerns, and signal-handling semantics — and ends up duplicating whatever build system the consumer already runs (make, rake, just, lefthook, CI). Keeping execution external means a Python or TypeScript port of `textus/1` only has to parse YAML and emit JSON; it doesn't have to spawn processes safely. Build runners stay the executor; textus stays a data tool.
+- **Why doesn't textus execute generator commands itself?** textus is a dataflow oracle, not a build runner. The moment a spec includes process execution, it inherits shell-injection surface, OS-portability concerns, and signal-handling semantics — and ends up duplicating whatever build system the consumer already runs (make, rake, just, lefthook, CI). Keeping execution external means a Python or TypeScript port of `textus/2` only has to parse YAML and emit JSON; it doesn't have to spawn processes safely. Build runners stay the executor; textus stays a data tool.
 
 - **Why not plain Markdown vaults (Obsidian / Foam)?** No schema enforcement, no write-gating, no addressable wire format. Fine for human notes; underspecified for agents that must act on the contents deterministically.
 
 - **Why not Notion / Coda?** Closed, hosted, lossy export. textus is local-first, plain-files, diffable in git.
 
-- **Why not JSON Schema for the schemas?** Considered. Bespoke YAML chosen for v1: simpler implementation, lighter dependency footprint, matches the reference impl's house language. JSON Schema MAY be added as an alternate schema-language adapter in a future minor revision without breaking `textus/1`.
+- **Why not JSON Schema for the schemas?** Considered. Bespoke YAML chosen for v1: simpler implementation, lighter dependency footprint, matches the reference impl's house language. JSON Schema MAY be added as an alternate schema-language adapter in a future minor revision without breaking `textus/2`.
 
 - **Why not a database (SQLite, kv store)?** textus's whole point is that the storage is plain files agents and humans both read. A binary store loses git-diff, grep, and editor support.
 
 - **Why not vector embeddings?** Different problem. textus is for facts agents act on deterministically; embeddings are for fuzzy retrieval. They compose — index a textus tree into a vector store if you need both.
 
-## 14. Open questions (v1.x scope)
+## 14. Open questions (v2.x scope)
 
 - **Locking on `put`:** the reference impl uses sha256 etags. Should the spec also define a file-lock fallback for systems where read-before-write is racy?
 - **Schema imports:** can one schema reference another (`type: $ref: person`)? Defer to v1.1.
@@ -716,21 +652,22 @@ Given a pending entry `pending.canon.identity.patch` proposing a change to `cano
 
 ## 15. Implementation checklist
 
-A v1 implementation MUST:
+A `textus/2` implementation MUST:
 
-- [ ] Parse `.textus/manifest.yaml` and validate the `version: textus/1` declaration.
+- [ ] Parse `.textus/manifest.yaml` and accept `version: textus/2` (and `textus/1` for backward compat per §11).
 - [ ] Resolve keys via longest-prefix match against manifest entries.
-- [ ] Read frontmatter + body from `.md` files; validate against the named schema.
+- [ ] Read `_meta` + body from `.md` files; validate against the named schema.
+- [ ] Read `_meta` from the top-level `_meta` hash in `.json` / `.yaml` files; validate against the named schema.
 - [ ] Compute `sha256:<hex>` etags over raw file bytes.
 - [ ] Refuse writes whose resolved role is not in the target zone's `writable_by` list with `write_forbidden`.
-- [ ] Return envelopes matching the shape in §8 exactly.
+- [ ] Return envelopes matching the shape in §8 exactly (with `_meta`, not `frontmatter`).
 - [ ] Use the error codes in §8 and the exit-code table.
 - [ ] Implement `textus stale` per §5.1 and §9, comparing each derived entry's `generator.sources` against its `generated.at` timestamp without invoking any commands.
 - [ ] Pass the conformance fixtures A–I in §12.
 
-A v1 implementation MAY:
+A `textus/2` implementation MAY:
 
-- Add additional CLI verbs (e.g. `move`, vendor-specific reporters) beyond the v1.0 set in §9.
+- Add additional CLI verbs (e.g. `move`, vendor-specific reporters) beyond the current set in §9.
 - Provide alternate output formats (`--format=yaml`, `--format=table`) for human use.
 - Support additional schema field types beyond §6, marked as `vendor:<name>` extensions.
 

data/docs/architecture.md

@@ -2,56 +2,110 @@
 
 How the reference Ruby implementation is organized. The wire protocol itself lives in [`../SPEC.md`](../SPEC.md); this document covers *how* the gem implements that spec.
 
-## Layering
+The codebase is a flat graph of small modules under one CLI dispatcher, not a strict pyramid. The clusters below describe what each module exists for and which other modules it talks to.
+
+## At a glance
 
 ```
-┌──────────────────────────────────────────────┐
-│ exe/textus                                   │  thin shim: load lib, call CLI.run
-├──────────────────────────────────────────────┤
-│ Textus::CLI                                  │  argv parsing, JSON I/O, exit codes
-├──────────────────────────────────────────────┤
-│ Textus::Store                                │  verb implementations (get/put/list/…)
-├───────────────┬───────────────┬──────────────┤
-│ Manifest      │ Schema        │ Entry        │  parse/resolve, validate, (de)serialize
-├───────────────┴───────────────┴──────────────┤
-│ Etag · Errors · version                      │  primitives
-└──────────────────────────────────────────────┘
+exe/textus  →  Textus::CLI  ──┬──►  Store          (facade — delegates to Reader/Writer/Mover)
+                              │       ├──►  Store::Reader  (get/list/where/uid/deps/published/stale/validate_all)
+                              │       ├──►  Store::Writer  (put/delete/accept)
+                              │       ├──►  Store::Mover   (mv)
+                              │       └──►  Hooks::Dispatcher  (lifecycle publish/subscribe)
+                              ├──►  Builder        (build verb — Pipeline + per-format renderers)
+                              ├──►  Refresh        (refresh verb)
+                              ├──►  Doctor         (doctor verb)
+                              ├──►  Init           (init verb)
+                              ├──►  Intro          (intro verb)
+                              ├──►  MigrateKeys    (key migrate, key mv verbs)
+                              ├──►  Schema::Tools  (schema init/diff/migrate verbs)
+                              ├──►  Store::View    (read-only projection over Store::Reader)
+                              └──►  Role           (role gate)
 ```
 
-Each layer talks only to the layer below it. `Store` is the only class that touches the filesystem for read/write; `Manifest` and `Schema` read at load time and are otherwise pure.
+CLI is the single entry point. It parses argv and dispatches each verb to whichever module owns that capability — there is no single mediator below CLI.
+
+## Module clusters
+
+### 1. Request path — core read/write verbs
+
+`Store` is a thin facade (~110 LOC) that holds `Manifest`, `Hooks::Registry`, `Hooks::Dispatcher`, and the lazy `Store::AuditLog`, then delegates verbs to a small set of focused collaborators:
 
-## Key resolution
+- **`Store::Reader`** — owns `get`, `list`, `where`, `uid`, `deps`, `rdeps`, `published`, `schema_envelope`, `stale`, `validate_all`. The only module that reads working-store entry files.
+- **`Store::Writer`** — owns `put`, `delete`, `accept`. Handles serialization, uid minting, etag check, role gate, audit append, and event publication. The only module that writes working-store entry files.
+- **`Store::Mover`** — owns `mv` (same-zone rename) with uid preservation and one audit row.
+- **`Store::Validator`** / **`Store::Staleness`** — back the `validate_all` / `stale` reads. Take explicit collaborators (`reader:`, `manifest:`, `audit_log:`, `schema_for:`) instead of the full store.
 
-`Manifest#resolve(key)` does **longest-prefix match** against `entries[].key`. The matched entry's `path:` is the base; if `nested: true`, remaining dotted segments become `/`-joined subdirectories under that path and a `.md` is appended.
+Shared value modules and primitives consumed by Reader/Writer/Mover:
 
-Resolution is **path-only** — it does not check whether the file exists. Existence is the verb's concern: `get` raises `unknown_key` when the file is missing; `put` happily creates new files in nested entries.
+- **`Textus::Key::Path`** — `Key::Path.resolve(manifest, mentry)` returns the absolute leaf path for a manifest entry. Single source for zone-path construction; used by `Manifest`, `Staleness`, `Builder`, and Writer.
+- **`Textus::Envelope`** — `Envelope.build(...)` returns the canonical envelope hash (protocol, key, zone, owner, path, format, `_meta`, body, etag, schema_ref, uid, optional content). Single source for envelope shape across `get` and `put`.
+- **`Manifest`** — parses `.textus/manifest.yaml`; resolves a dotted key to a path via longest-prefix match. `nested: true` entries treat unmatched suffix segments as `/`-joined subdirs, with `.md` appended. Resolution is path-only; existence is the verb's concern.
+- **`Schema`** — loads YAML schema files; validates frontmatter shape and surfaces unknown-key warnings (the §6 forward-compat rule).
+- **`Entry`** + format adapters (`entry/markdown.rb`, `entry/text.rb`, `entry/json.rb`, `entry/yaml.rb`) — splits raw bytes on `---\n`, feeds the YAML chunk to `YAML.safe_load` (no aliases, restricted classes). The frontmatter `name:` field is enforced against the file basename in Reader/Writer (on read and on write) — mismatch raises `bad_frontmatter`.
+- **`Etag`** — `sha256:<hex>` over raw file bytes. `put` accepts optional `if_etag:`; mismatch raises `etag_mismatch`. No locking, no temp-file-and-rename — v1 leaves stronger guarantees to v1.x.
+- **`Role`** — agent-vs-human gate. Writer checks `Manifest::Entry#zone_writers` before doing anything else; otherwise raises `write_forbidden`.
+- **`Store::AuditLog`** — append-only NDJSON; every successful write emits one line.
+- **`Proposal`** — `accept` verb flow for promoting a pending entry into its target zone.
+- **`Dependencies`** — `deps`/`rdeps`/`published` verb backing; walks manifest declarations.
 
-## Frontmatter parsing
+### 2. Build / publish pipeline
+
+Separate from the request path. Owns derived-entry materialization and byte-copy publish. `Builder` orchestrates per-entry materialization through `Builder::Pipeline`, which runs an ordered step list and dispatches the rendering step to one of four format-specific renderers. Adding a new output format is a single-file change under `lib/textus/builder/renderer/`.
+
+```
+Builder ──► Pipeline ──► LoadSources ──► Project ──► Render (per-format) ──► Write ──► Publisher ──► (sentinel)
+                                                          │
+                                                          └──► Renderer::{Markdown, Text, Json, Yaml}
+```
 
-`Entry.parse` splits raw bytes on `---\n` boundaries and feeds the YAML chunk to `YAML.safe_load` (no aliases, restricted classes). Unknown top-level frontmatter keys are not rejected here — they are surfaced as warnings by `Schema#validate!`. This is the forward-compat rule from §6 of the spec.
+- **`Builder`** — iterates `zone: derived` entries, hands each to `Pipeline.run`, then handles `Publisher` copy-out and fires the `:build` event. Holds no format-specific logic.
+- **`Builder::Pipeline`** — `Pipeline.run(store:, mentry:, template_loader:)` is the orchestrator: runs the projection, merges `intro` if `inject_intro: true`, dispatches to the matching renderer, writes the bytes to the derived path.
+- **`Builder::InjectMeta`** — builds the `_meta` block (`generated_at`, `from`, `template`, `reduce`) and threads it onto JSON/YAML content as the first key per SPEC §6 ordering.
+- **`Builder::Renderer::{Markdown,Text,Json,Yaml}`** — one class per format, inheriting `Builder::Renderer`. Receives a template-loader lambda and `(mentry:, data:)`; returns rendered bytes. Markdown/Text always require a template; JSON/YAML optionally accept one (otherwise default-shape the projection rows).
+- **`Projection`** — collects rows from manifest-declared source keys, applies optional reducer, sorts and positions. Pure data shaping.
+- **`Mustache`** — minimal mustache renderer for templates in `.textus/templates/`.
+- **`Publisher`** — byte-copy from store path to external target path. Refuses to overwrite unmanaged targets; writes a sentinel in `.textus/sentinels/` to track managed targets.
 
-The frontmatter `name:` field is enforced against the file basename inside `Store` (both on read and on write) so a misnamed file or a mistyped `name:` in `put` payload fails fast with `bad_frontmatter`.
+### 3. Extension surface
 
-## Zone enforcement
+Declared in the manifest, loaded on demand, dispatched by `Store` and `Refresh`.
 
-Three zones (`fixed`, `state`, `derived`) declared per-entry in the manifest. `Store#put` checks `ManifestEntry#agent_writable?` (true only for `state`) before doing anything else and raises `write_forbidden` otherwise. Zone semantics live in the manifest, not directory names — a project can rename `state/` to whatever it wants.
+- **`Hooks::Registry`** — loads one `.rb` per hook from `.textus/hooks/`, registers callables under their `(event, name)`. Single source of truth via the `EVENTS` table (rpc vs pubsub, arg shape, failure semantics). For pub-sub events it also forwards registrations to the `Hooks::Dispatcher`.
+- **`Hooks::Dispatcher`** — first-class pub/sub for lifecycle events (`:put`, `:delete`, `:refresh`, `:build`, `:accept`). Owns the 2-second per-handler timeout and the audit-on-failure middleware (raising handlers do not abort the write; they produce an `event_error` audit row). Embedded callers can `store.dispatcher.subscribe(:put, :name) { ... }` outside `.textus/hooks/`.
+- **`Hooks::Builtin`** — ships built-in `:fetch` hooks (e.g. json, csv, ical-events, rss) available without user-supplied hooks.
+- **`Refresh`** — `refresh` verb: looks up the `:fetch` hook for a key, invokes it, normalizes the result by declared format, writes through `Store::Writer` with an etag check.
 
-## ETag and concurrency
+### 4. Operational tooling
 
-`Etag.for_bytes` returns `sha256:<hex>` over the raw file bytes. `put` accepts an optional `if_etag:` — if provided and the on-disk file's etag differs, `etag_mismatch` is raised. No locking, no temp-file-and-rename — the v1 spec leaves stronger guarantees to v1.x (§14 open question).
+First-class CLI verbs that don't fit the read/write/build axes. Read-mostly; side modules off CLI.
 
-## Staleness (the dataflow oracle)
+- **`Doctor`** — `doctor` verb: orchestrator that runs 9 builtin checks under `Doctor::Check::*`. Talks to Manifest/Schema/Entry/Hooks::Registry directly.
+- **`Doctor::Check`** — explicit base class for doctor checks. Each of the 9 builtin checks is its own file under `lib/textus/doctor/check/`.
+- **`MigrateKeys`** — `key migrate` and `key mv` verbs; computes renames against the manifest.
+- **`Schema::Tools`** — `schema init`, `schema diff`, `schema migrate` verbs.
+- **`Init`** — `init` verb: scaffolds `.textus/` with the five zone directories, baseline schemas, empty audit log, starter manifest.
+- **`Intro`** — `intro` verb: emits the human/agent-facing onboarding payload.
+- **`Store::View`** — read-only projection over `Store::Reader` for hook code that should not mutate.
+- **`Key::Distance`** — Levenshtein-ish suggestion for `did-you-mean` on unknown keys.
 
-`Store#stale` walks every `zone: derived` entry that declares a `generator:` block, reads its `generated.at` frontmatter timestamp, and compares against each `generator.sources` entry's current mtime. Returns the offenders **and their declared `command`**; it does **not** execute anything. This is the core "dataflow oracle, not executor" boundary from §5.1 of the spec.
+### 5. Primitives
 
-Sources are heuristically classified: a string matching the textus key grammar with no `/` is treated as a textus key (and enumerated via the manifest); anything else is treated as a repo-relative path.
+- **`Errors`** — `Textus::Error` subclasses, each carrying a stable `code`, a `details` hash, and an `exit_code`. `CLI` catches them at the top level and emits the §8 error envelope on stdout. In `--format=json` mode, errors are **never** written to stderr — agents read stdout.
+- **`version`** — gem semver string (independent of the wire protocol `textus/2`).
 
-## Errors → envelopes
+## Invariants
 
-All `Textus::Error` subclasses carry a stable error `code`, a `details` hash, and an `exit_code`. `CLI` catches them at the top level and emits the §8 error envelope on stdout; the exit code matches the §8 table. Errors are never written to stderr in `--format=json` mode — agents read stdout.
+- **CLI is the only entry point.** No public API surface guarantees outside the verbs CLI exposes.
+- **Manifest is pure.** Reads at load, no mutation.
+- **Store::Writer is the only module that writes to working-store entry files.** Reader reads them; Mover moves them within a zone. Init, MigrateKeys, Publisher, Builder, AuditLog write to **other** parts of `.textus/` (scaffolding, sentinels, audit log, derived targets) — they do not edit existing entry files behind the Store facade's back.
+- **`name:` frontmatter matches file basename.** Enforced on read and write.
+- **Zone semantics live in the manifest, not in directory names.** A project may rename `state/` to anything; the manifest declares which zone each entry belongs to.
+- **`stale` does not execute anything.** It walks `zone: derived` entries with a `generator:` block, compares `generated.at` against source mtimes, and returns offenders **plus their declared `command`**. Build runners execute. This is the §5.1 "dataflow oracle, not executor" boundary.
 
 ## What this implementation deliberately leaves out
 
 - **No process spawning.** Even `stale` does not execute. Build runners do that.
 - **No transport.** No HTTP server, no socket, no MCP server in this gem. Those are downstream wrappers (see [`./conventions.md`](./conventions.md)).
 - **No indexes.** Listing walks the filesystem each time. Premature optimisation for v1.
+- **No locking.** Etag is advisory; concurrent writers can still race. Left to v1.x (§14 open question).