textus 0.52.0 → 0.53.0

data/SPEC.md

@@ -22,18 +22,17 @@
   - [5.1 Role resolution](#51-role-resolution)
     - [5.1.1 Capabilities](#511-capabilities)
   - [5.2 Source layer (produced entries)](#52-source-layer-produced-entries)
-    - [5.2.1 Projection source (`from: project`)](#521-projection-source-from-project)
-    - [5.2.2 External source (`from: command`)](#522-external-source-from-command)
+    - [5.2.1 Derived source (`from: derive`)](#521-derived-source-from-derive)
+    - [5.2.2 External source (`from: external`)](#522-external-source-from-external)
   - [5.3 Publish layer](#53-publish-layer-publish)
-  - [5.4 Intake source (`from: handler`)](#54-intake-source-from-handler)
+  - [5.4 Intake source (`from: fetch`)](#54-intake-source-from-fetch)
   - [5.5 Pending / accept workflow](#55-pending--accept-workflow)
   - [5.6 Audit log](#56-audit-log)
   - [5.7 Security bounds](#57-security-bounds)
   - [5.8 Schema evolution](#58-schema-evolution)
-  - [5.9 Row transforms](#59-row-transforms)
-  - [5.10 Hooks](#510-hooks)
-  - [5.11 Rules](#511-rules)
-  - [5.12 Storage formats](#512-storage-formats)
+  - [5.9 Hooks](#59-hooks)
+  - [5.10 Rules](#510-rules)
+  - [5.11 Storage formats](#511-storage-formats)
 - [6. Schemas](#6-schemas)
 - [7. Entry file format](#7-entry-file-format)
 - [8. Envelope (the wire format)](#8-envelope-the-wire-format)
@@ -48,10 +47,6 @@
   - [13.1 Layered architecture (internal)](#131-layered-architecture-internal)
 - [14. Open questions (v3.x scope)](#14-open-questions-v3x-scope)
 - [15. Implementation checklist](#15-implementation-checklist)
-- [16. Migrating from textus/2](#16-migrating-from-textus2)
-  - [16.1 Breaking changes in 0.31.0 (capability-based roles)](#161-breaking-changes-in-0310-capability-based-roles)
-  - [16.2 Breaking changes in 0.33.0 (workspace/keep + Setup-1 scaffold)](#162-breaking-changes-in-0330-workspacekeep--setup-1-scaffold)
-  - [16.3 Breaking changes in 0.35.0 (proposal target-canon + `author_held`)](#163-breaking-changes-in-0350-proposal-target-canon--author_held)
 
 ---
 
@@ -97,7 +92,7 @@ textus is organized as five composable layers. Each layer has a single responsib
 
 | Layer | Name | Responsibility |
 |---|---|---|
-| L1 | **Store** | Plain-file backend: `.textus/zones/<zone>/...` with YAML frontmatter + Markdown body, addressed by dotted keys, schema-validated, etag-versioned. |
+| L1 | **Store** | Plain-file backend: `.textus/data/<lane>/...` with YAML frontmatter + Markdown body, addressed by dotted keys, schema-validated, etag-versioned. |
 | L2 | **Sources** | Declared external inputs (the `artifacts` machine zone in the default scaffold, under the `artifacts.feeds.*` keys; any `machine` zone, writable by a role with `converge`): URLs, files, feeds with declared parsers and TTLs. textus *describes* sources; external automation fetches and pipes results through `textus put`. |
 | L3 | **Source** | An entry's `source:` *acquires* **data** — a pure in-process projection from store entries (select/pluck/sort/transform), an external fetch via a handler, or an out-of-band command. Acquire-only: rendering is not a source concern. No shell execution. |
 | L4 | **Publish** | Emits a produced entry's data to repo-relative paths, declared via a **list** of `publish:` targets. A target with no `template:` copies the data verbatim (json/yaml re-serialized without `_meta`; other formats byte-copied); a target with a `template:` renders the data through it. A `{ tree: }` target mirrors a subtree (ADR 0047). Published artifacts are clean content — textus's `_meta` provenance stays in the store. A sentinel under `.textus/.run/sentinels/<target-rel-path>.textus-managed.json` (git-ignored runtime state) records the source, sha256, and `mode: "copy"`. |
@@ -130,22 +125,23 @@ The root is `.textus/` at the project working directory. A typical tree:
 
 ```
 .textus/
-  manifest.yaml          # internal: key → subtree mapping + role/zone declarations
-  audit.log              # internal, append-only NDJSON log of every successful write
+  manifest.yaml          # internal: key → subtree mapping + role/lane declarations
   schemas/               # internal: YAML schema files
   templates/             # internal: Mustache templates referenced by derived entries
-  hooks/                 # internal: one Ruby file per hook
-  .run/sentinels/        # runtime (git-ignored): byte-copied publish bookkeeping, regenerated on build (see §5.3)
-  zones/                 # ALL user content lives here
-    knowledge/           # zone: knowledge (kind: canon — author-holders write; knowledge.identity.* is the identity convention)
-    notebook/            # zone: notebook (kind: workspace — keep-holders write; agent's own durable lane)
-    proposals/           # zone: proposals (kind: queue — propose-holders write)
-    artifacts/           # zone: artifacts (kind: machine — converge-holders write; external inputs artifacts.feeds.* + computed outputs artifacts.derived.*)
+  steps/                 # internal: user-injectable step handlers (fetch, derive, external)
+  .run/                  # runtime (git-ignored): audit log, sentinels, locks, queue, pulse cursors
+    audit.log            # append-only NDJSON log of every successful write
+    sentinels/           # byte-copied publish bookkeeping (see §5.3)
+  data/                  # ALL user content lives here
+    knowledge/           # lane: knowledge (kind: canon — author-holders write)
+    notebook/            # lane: notebook (kind: workspace — keep-holders write; agent's own durable lane)
+    proposals/           # lane: proposals (kind: queue — propose-holders write)
+    artifacts/           # lane: artifacts (kind: machine — converge-holders write)
 ```
 
-Textus internals (`manifest.yaml`, `schemas/`, `templates/`, `hooks/`) live directly under `.textus/`; disposable runtime state (the audit log, publish `sentinels/`, fetch/build locks, pulse cursors) lives under `.textus/.run/` (git-ignored, ADR 0038/0070). **All user content lives under `.textus/zones/`.** Manifest `path:` fields are relative to `.textus/zones/` — they do **not** include the `zones/` prefix. Implementations MUST prepend `zones/` to every `path:` when resolving a key to a filesystem location.
+Textus internals (`manifest.yaml`, `schemas/`, `templates/`, `steps/`) live directly under `.textus/`; disposable runtime state (audit log, publish `sentinels/`, fetch/build locks, pulse cursors, job queue) lives under `.textus/.run/` (git-ignored, ADR 0038/0070). **All user content lives under `.textus/data/`.** Manifest `path:` fields are relative to `.textus/` — they include the `data/` prefix explicitly (e.g. `path: data/knowledge/foo.md`).
 
-Zone directories under `zones/` are conventional; their write semantics are derived from the zone's declared `kind:` (and the capabilities roles hold), not the directory name.
+Lane directories under `data/` are conventional; their write semantics are derived from the lane's declared `kind:` (and the capabilities roles hold), not the directory name.
 
 `.textus/audit.log` is an append-only NDJSON file written under a file lock by every successful `put`, `key_delete`, `key_mv`, and `accept`. Convergence (`drain`/`serve`) writes through these same verbs — a produced entry logs as `put`, a swept entry as `key_delete` — so there is no distinct `drain` audit verb. `.textus/role` (one line containing a role name) is optional and participates in the role-resolution order (§5).
 
@@ -172,7 +168,7 @@ roles:
   - { name: agent,      can: [propose] }
   - { name: automation, can: [converge] }
 
-zones:
+lanes:
   - name: knowledge
     kind: canon
   - name: notebook
@@ -186,20 +182,20 @@ zones:
 
 entries:
   - key: knowledge.identity.self
-    path: knowledge/identity/self.md
-    zone: knowledge
+    path: data/knowledge/identity/self.md
+    lane: knowledge
     schema: identity
 
   - key: knowledge.network.org
-    path: knowledge/network/org
-    zone: knowledge
+    path: data/knowledge/network/org
+    lane: knowledge
     schema: person
     owner: human:network
     nested: true
 
   - key: artifacts.catalogs.people
-    path: artifacts/catalogs/people.md
-    zone: artifacts
+    path: data/artifacts/catalogs/people.md
+    lane: artifacts
     schema: null
     owner: automation:converge
 
@@ -232,9 +228,9 @@ For `nested: true`, the recursive glob matches the format's extension (markdown
 **Subtree mirror (a `{ tree: }` target).** A nested manifest entry MAY include a `{ tree: "dir" }` target to mirror its entire stored subtree (`zones/<path>/**`) to a single target directory, preserving relative layout (case and extension preserved). It is **path-driven, not key-driven**: no keys are enumerated, no template variables are interpreted, and the mirrored files are opaque payload (never addressable). The entry's `ignore:` globs (§4, ADR 0042) filter the walk; each mirrored file gets its own sentinel; and on every drain the whole target directory is pruned of textus-managed files the current source no longer produces (unmanaged files are never touched). When a `{ tree: }` target directory overlaps another entry's `{ to: }` target (e.g. a derived `SKILL.md` written into the mirrored dir), the mirroring entry **must** `ignore:` that filename or prune will delete it — `doctor` flags this as `publish.tree_index_overlap`. See ADR 0047.
 
 ```yaml
-- key: working.skills
-  path: working/skills
-  zone: working
+- key: knowledge.skills
+  path: data/knowledge/skills
+  lane: knowledge
   schema: skill
   nested: true
   publish:
@@ -242,11 +238,9 @@ For `nested: true`, the recursive glob matches the format's extension (markdown
   ignore: ["*.tmp", ".DS_Store"]
 ```
 
-**`inject_boot:` (a publish-target flag).** A to-target with a `template:` MAY declare `inject_boot: true`. When `textus drain` publishes that target, it merges the `textus boot` envelope (§9) into the render data under the key `boot`, so the template can render orientation content (zones, write flows, CLI catalog) alongside the entry's data. `inject_boot:` is per-target and only meaningful alongside a `template:`; on a templateless or tree target it is rejected at load — agents reading the rendered file should be able to trust the preamble was produced by the same source of truth `textus boot` exposes.
+**Lookup rule:** to resolve a key, find the entry with the longest `key:` prefix that matches. If that entry has `nested: true`, the remaining segments map to subdirectories under its `path`. Otherwise the key must equal an entry exactly. The resolved filesystem path is `<.textus root>/<entry.path>[/<remaining>...].md` — manifest `path:` values include the `data/` prefix (e.g. `data/knowledge/network/org`).
 
-**Lookup rule:** to resolve a key, find the entry with the longest `key:` prefix that matches. If that entry has `nested: true`, the remaining segments map to subdirectories under its `path`. Otherwise the key must equal an entry exactly. The resolved filesystem path is `<.textus root>/zones/<entry.path>[/<remaining>...].md` — implementations MUST prepend `zones/` to the manifest `path:` when constructing the filesystem location.
-
-## 5. Zones and capability-based write gates
+## 5. Lanes and capability-based write gates
 
 Write authority is **derived**, never declared per-zone. Each zone declares a `kind:`; each zone-kind requires one capability to write to it. A role may write a zone iff its capability set (`role.can`) contains the verb that zone-kind requires. textus gates **writes, not reads**: reads are unrestricted at the protocol layer (the `.textus/` files are on disk). Per-role read-scoping, if needed, is an agent-surface projection, not a manifest field.
 
@@ -366,24 +360,24 @@ when the acting role holds `author`). See §5.11 for composing extra predicates
 
 ### 5.2 Source layer (produced entries)
 
-Produced entries live in a `machine` zone (writable by a role holding `converge`; `automation` by default) — `artifacts` in the default scaffold. They are not authored by hand; their **data** is acquired from a declared `source:` block with a `from:` discriminator (`project | handler | command`). A `source:` is **acquire-only**: it produces the data the store holds; it does **not** render. Rendering is a publish concern (§5.3). Every produced entry is `kind: produced` (ADR 0095); the **produce-method** is read from `source.from` — `from: project | command` is *derived* (internal projection / out-of-band command), `from: handler` is *intake* (external fetch, §5.4). `kind:` no longer restates the produce-method (the former `kind: derived` / `kind: intake` are rejected at load with a fold hint).
+Produced entries live in a `machine` lane (writable by a role holding `converge`; `automation` by default) — `artifacts` in the default scaffold. They are not authored by hand; their **data** is acquired from a declared `source:` block with a `from:` discriminator (`derive | fetch | external`). A `source:` is **acquire-only**: it produces the data the store holds; it does **not** render. Rendering is a publish concern (§5.3). Every produced entry is `kind: produced` (ADR 0095); the **produce-method** is read from `source.from` — `from: derive | external` is *derived* (internal projection / out-of-band command), `from: fetch` is *intake* (external fetch, §5.4). `kind:` no longer restates the produce-method (the former `kind: derived` / `kind: intake` are rejected at load with a fold hint).
 
-#### 5.2.1 Projection source (`from: project`)
+#### 5.2.1 Derived source (`from: derive`)
 
-A derived entry produced by a pure in-process projection declares `source: { from: project, ... }`. The projection fields are **flat** under `source:` (there is no nested `project:` block). The stored form is **data** — serialized via the `format:` strategy (e.g. `json`, `yaml`, `markdown-table`); no template is consulted at acquire time.
+A derived entry produced by a pure in-process projection declares `source: { from: derive, ... }`. The projection fields are **flat** under `source:` (there is no nested `derive:` block). The stored form is **data** — serialized via the `format:` strategy (e.g. `json`, `yaml`, `markdown-table`); no template is consulted at acquire time.
 
 ```yaml
 - key: artifacts.derived.people
-  kind: produced                   # produce-method (derived) read from source.from: project
-  zone: artifacts
+  kind: produced                   # produce-method (derived) read from source.from: derive
+  lane: artifacts
+  path: data/artifacts/derived/people.json
   source:
-    from: project
+    from: derive
     select: knowledge.network.org  # prefix OR [list of prefixes]
     pluck:  [name, relationship, org]
     sort_by: name                  # optional
     limit: 1000                    # default 1000, max 1000
     format: json                   # one of: list, hash, yaml-list-in-md, json, markdown-table
-    transform: rank_by_recency     # optional — names a :transform_rows hook
     on_write: async                # sync | async (default async)
 ```
 
@@ -391,24 +385,22 @@ A derived entry produced by a pure in-process projection declares `source: { fro
 
 `format` controls how the acquired data is serialized for storage. Permitted values: `list`, `hash`, `yaml-list-in-md`, `json`, `markdown-table`.
 
-`transform:` (optional) names a registered `:transform_rows` hook (see §5.10). The hook receives the projected rows array and may reorder, filter, or augment before serialization — it shapes the **data**, not its presentation.
-
 `on_write:` (`sync` | `async`, default `async`) controls the write-trigger strategy: `sync` rebuilds the entry's data inline before the triggering write returns; `async` defers it to a background pass that completes before process exit.
 
-> **No source-level `template:` / `inject_boot:` / `provenance:`.** Those are retired from `source:` (and from the entry top level). Rendering and boot injection move to a publish target (§5.3); provenance is carried in the data's `_meta` (§5.12), never a flag. A manifest carrying `source: { from: template }`, an entry-level/`source` `template:`/`inject_boot:`/`provenance:`, or a nested `project:` block is **rejected at load** with a fold hint (ADR 0094).
+> **No source-level `template:` / `provenance:`.** Those are retired from `source:` (and from the entry top level). Rendering moves to a publish target (§5.3); provenance is carried in the data's `_meta` (§5.11). A manifest carrying `source: { from: template }` or an entry-level `template:`/`provenance:` is **rejected at load** with a fold hint (ADR 0094).
 
-#### 5.2.2 External source (`from: command`)
+#### 5.2.2 External source (`from: external`)
 
-A derived entry that is produced by a build tool *outside* textus — `rake`, `just`, a shell script, anything — declares `source: { from: command, ... }`. textus does **not** execute the command (consistent with §2); the external automation is responsible for writing the file. textus records `sources:` so `doctor`'s `generator_drift` check can compare source mtimes against the derived file's `_meta.generated.at` and report staleness. (Generator/build drift is dependency-based, not age-based; ADR 0085 keeps it out of the internal `freshness` scan — it is a `doctor` health check.)
+A derived entry that is produced by a build tool *outside* textus — `rake`, `just`, a shell script, anything — declares `source: { from: external, ... }`. textus does **not** execute the command (consistent with §2); the external automation is responsible for writing the file. textus records `sources:` so `doctor`'s `generator_drift` check can compare source mtimes against the derived file's `_meta.generated.at` and report staleness. (Generator/build drift is dependency-based, not age-based; ADR 0085 keeps it out of the internal `freshness` scan — it is a `doctor` health check.)
 
 ```yaml
 - key: artifacts.derived.skills
-  path: artifacts/derived/skills.md
-  kind: produced                   # produce-method (derived) read from source.from: command
-  zone: artifacts
+  path: data/artifacts/derived/skills.md
+  kind: produced                   # produce-method (derived) read from source.from: external
+  lane: artifacts
   owner: automation:catalog-skills
   source:
-    from: command
+    from: external
     command: "rake catalog:skills"   # informational; external automation invokes it
     sources:                          # dotted keys OR repo-relative paths
       - knowledge.projects
@@ -419,7 +411,7 @@ A derived entry that is produced by a build tool *outside* textus — `rake`, `j
 
 **`command:`** is recorded in the staleness row's `generator` field but never executed. It exists so `doctor`'s `generator_drift` output can carry a hint about how to regenerate.
 
-**Generator-drift contract.** An entry with `source: { from: command }` is reported by `doctor`'s `generator_drift` check as drifted when:
+**Generator-drift contract.** An entry with `source: { from: external }` is reported by `doctor`'s `generator_drift` check as drifted when:
 - The derived file does not exist, OR
 - `_meta.generated.at` is missing or unparseable, OR
 - Any `sources:` element has been modified after `_meta.generated.at`.
@@ -435,13 +427,13 @@ generated:
 
 `generated.from` SHOULD match `source.sources` — they're the same list, recorded twice so a diff proves what was actually consumed.
 
-`from: command` and `from: project` are alternatives — exactly one per derived entry. The external automation produces the bytes directly for `from: command`; the in-process projection produces them for `from: project`. Either way the stored form is data; rendering is deferred to publish (§5.3).
+`from: external` and `from: derive` are alternatives — exactly one per derived entry. The external automation produces the bytes directly for `from: external`; the in-process projection produces them for `from: derive`. Either way the stored form is data; rendering is deferred to publish (§5.3).
 
 ### 5.3 Publish layer (`publish:`)
 
 Rendering and emission are a **publish** concern, orthogonal to acquire (§5.2). `publish:` is always a **list** of targets (ADR 0094). Each element is exactly one of two shapes:
 
-- a **to-target** — `{ to: <path>, template?: <name>, inject_boot?: <bool> }` — emit the entry's data to one repo-relative path;
+- a **to-target** — `{ to: <path>, template?: <name> }` — emit the entry's data to one repo-relative path;
 - a **tree-target** — `{ tree: <dir> }` — mirror the entry's stored subtree (ADR 0047).
 
 The legacy *map* forms — `publish: { to: [...] }` and `publish: { tree: ... }` — and the older top-level `publish_to:` / `publish_tree:` keys are **rejected at load** with a migration message: `publish:` is a list, and a mirror is a `{ tree: }` element of it.
@@ -470,7 +462,7 @@ A sentinel is written for each published file at `<store_root>/.run/sentinels/<t
 
 **Publish presence is a uniform rule across all kinds.** Absent → the entry is terminal data (consumed internally via another entry's `select`, or read via `get`). Present → emit to the listed targets, every kind through one publish path. A `from: command` entry with publish targets emits the bytes the command already wrote into the store; without targets it is a staleness-only signal.
 
-### 5.4 Intake source (`from: handler`)
+### 5.4 Intake source (`from: fetch`)
 
 Intake entries acquire their data via `source: { from: handler, ... }` — an external fetch through a registered handler. The `source:` block fully replaces the former `intake:` block; the entry's `kind:` is `produced` and the *intake* produce-method is read from `source.from: handler` (ADR 0095). Like every `source:`, it is acquire-only — a fetched feed is **data**, and if it needs rendering for a consumer that is a publish target's `template:` (§5.3), never the handler's job. textus itself makes no implicit network calls: the handler runs only when `textus drain`/`serve` or a `hook run` event re-pulls a stale entry past its `source.ttl` — a `get` never runs it (ADR 0089).
 
@@ -516,7 +508,7 @@ Proposal entries are full patches authored into the `proposals` queue zone (writ
 proposal:
   target_key: working.network.org.bob
   action: put
-frontmatter:
+_meta:
   name: bob
   relationship: peer
   org: acme
@@ -524,7 +516,7 @@ frontmatter:
 Proposed body content.
 ```
 
-`proposal.target_key` names the entry the patch would create or modify, and `proposal.action` is `put` or `delete`. The remaining frontmatter and body are the proposed new content. A proposal's `target_key` MUST resolve to a `canon` zone; `accept` refuses any other target (`target_is_canon`, ADR 0035).
+`proposal.target_key` names the entry the patch would create or modify, and `proposal.action` is `put` or `delete`. The sibling `_meta` block and the body are the proposed new content — a proposal carries the same `{ _meta, body }` envelope shape it intends `accept` to write (ADR 0113). A proposal's `target_key` MUST resolve to a `canon` zone; `accept` refuses any other target (`target_is_canon`, ADR 0035).
 
 `textus accept <proposal-key>` is a **transition** (not a capability) that requires the **`author` capability**: the resolved role must hold `author` (the single trust anchor — `human` by default). It copies the patch into the target zone, records provenance (originating proposal key, original role, original timestamp) in the audit log, and removes the proposal entry. The `reject` transition likewise requires `author`. Roles holding only `propose` (e.g. `agent`) can propose but cannot accept or reject.
 
@@ -614,11 +606,7 @@ evolution:
 
 **Override rule:** a role holding the `author` capability (the trust anchor — `human` by default) is permitted to write any `maintained_by` field, regardless of declared owner. The trust anchor overrides agent-maintained fields by design: schema field ownership (`maintained_by:`) makes the boundary explicit, not implicit. 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 Row transforms
-
-Row transforms are RPC hooks on the `:transform_rows` event. See §5.10.
-
-### 5.10 Hooks
+### 5.9 Hooks
 
 This section is the normative event table. For the hook-author's guide (how to define and test hooks), see [`docs/how-to/writing-hooks.md`](docs/how-to/writing-hooks.md).
 
@@ -682,7 +670,7 @@ The primary entity is always `key:` (for `:proposal_accepted`, `key:` is the pen
 
 Each handler runs under `Timeout.timeout(2)`.
 
-### 5.11 Rules
+### 5.10 Rules
 
 A manifest MAY declare a top-level `rules:` block — a list of rule blocks matched against entry keys by glob. Each block carries one or more slots:
 
@@ -692,7 +680,7 @@ rules:
     retention: { ttl: 90d, action: archive }
 
   - match: feeds.calendar.**
-    intake_handler_allowlist: [ical-events]
+    handler_permit: [ical-events]
 
   - match: proposals.**
     guard:
@@ -704,7 +692,7 @@ rules:
 | Slot | Type | Meaning |
 |---|---|---|
 | `retention` | `{ ttl, action: drop\|archive }` | Age-based garbage collection (ADR 0093). `action` is `drop` (delete the entry) or `archive` (copy to `<store>/archive/<relative-path>` then delete). Age is measured from `_meta.last_fetched_at` (intake entries) when present, else the leaf file's modification time. **Destructive — applied only on the convergence sweep (the destructive phase of `drain`/`serve`), never on a write or read.** Orthogonal to production: an intake entry may declare both `source: { ..., ttl: 1h }` (re-pull cadence) and a `retention: { ttl: 90d, action: archive }` rule. `retention:` on a `derived` entry is rejected at load. |
-| `intake_handler_allowlist` | list of strings | Constrains which `source.handler:` names may be used by intake entries matched by this block. Enforced by `textus doctor`. |
+| `handler_permit` | list of strings | Constrains which `source.handler:` names may be used by intake entries matched by this block. Enforced by `textus doctor`. |
 | `guard` | `{ <transition>: [predicates] }` | Extra predicates composed (AND) onto a write transition's built-in **base** guard (ADR 0031). Keyed by transition (`put`, `key_delete`, `key_mv`, `accept`, `reject`, `converge`). Predicate names are drawn from the closed vocabulary (`zone_writable_by`, `schema_valid`, `author_held`, `target_is_canon`, `etag_match`, `fresh_within`); parameterized predicates use `{ name: param }` form, e.g. `{ fresh_within: "1h" }`. Enforced — the transition refuses (`guard_failed`) if any predicate fails; the topology refusal keeps the `write_forbidden` code. |
 
 The `retention:` slot handles age-based GC only. Write-trigger strategy for derived entries (`on_write: sync|async`) is declared on the entry's own `source:` block (§5.2.1), not in `rules:`. Generator/build drift — a derived entry whose sources changed since its `generated.at` — is reported by the `textus doctor` `generator_drift` check rather than any rule slot.
@@ -715,7 +703,7 @@ The `retention:` slot handles age-based GC only. Write-trigger strategy for deri
 
 **Read surface.** `textus rule list` dumps every block. `textus rule explain KEY` shows the resolved `RuleSet` for one key — lean effective `{retention, guard}` by default; `--detail` adds every matched block and the effective guard predicate names for every write transition (ADR 0059).
 
-### 5.12 Storage formats
+### 5.11 Storage formats
 
 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.
 
@@ -811,7 +799,7 @@ Every successful CLI response (`--output=json`) is a single JSON envelope:
 **Field rules:**
 - `protocol` MUST be the exact string `textus/3`.
 - `key` MUST be the canonical resolved key.
-- `zone` MUST be one of the zones declared in the manifest (`knowledge`, `notebook`, `feeds`, `proposals`, `artifacts` in the default Setup-1 scaffold).
+- `zone` MUST be one of the lanes declared in the manifest (`knowledge`, `notebook`, `feeds`, `proposals`, `artifacts` in the default Setup-1 scaffold).
 - `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.
@@ -885,15 +873,15 @@ All verbs accept `--output=json` and emit a canonical envelope (success or error
 | `key mv OLD NEW [--as=R] [--dry-run]` | write | per zone (same-zone only) |
 | `key uid K` | read | any |
 
-**`textus boot` envelope extras.** In addition to zones, entries, hooks, write flows, and the `cli_verbs` catalog, the boot envelope includes an `agent_quickstart` block synthesized from the manifest's role capabilities:
+**`textus boot` envelope extras.** In addition to lanes, entries, hooks, write flows, and the `cli_verbs` catalog, the boot envelope includes an `agent_quickstart` block synthesized from the manifest's role capabilities:
 
 ```json
 {
   "agent_quickstart": {
     "read_verbs":     ["get", "list", "pulse", "schema_show", "boot", "rule_explain", "where", "deps", "rdeps"],
     "write_verbs":    ["accept", "key_delete", "key_mv", "propose", "put", "reject"],
-    "writable_zones": ["proposals"],
-    "propose_zone":   "proposals",
+    "writable_lanes": ["proposals"],
+    "propose_lane":   "proposals",
     "latest_seq":     1842
   }
 }
@@ -952,7 +940,7 @@ 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/3", "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: `protocol_version`, `manifest_files`, `schemas`, `schema_parse_error`, `templates`, `hooks`, `intake_registration`, `illegal_keys`, `sentinels`, `audit_log`, `unowned_schema_fields`, `schema_violations`, `rule_ambiguity`, `handler_allowlist`, `fetch_locks`, `proposal_targets`, `publish.tree_index_overlap`. Additional registered `:validate` hooks (§5.10) run after the builtin set. Exit code is 0 on `ok`, 1 otherwise.
+`textus doctor` returns a health-check envelope: `{ "protocol": "textus/3", "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: `protocol_version`, `manifest_files`, `schemas`, `schema_parse_error`, `templates`, `intake_registration`, `illegal_keys`, `sentinels`, `audit_log`, `unowned_schema_fields`, `schema_violations`, `rule_ambiguity`, `handler_permit`, `fetch_locks`, `proposal_targets`, `publish.tree_index_overlap`, `generator_drift`. Additional registered `:validate` hooks (§5.10) run after the builtin set. Exit code is 0 on `ok`, 1 otherwise.
 
 ## 11. Versioning
 
@@ -1018,7 +1006,7 @@ Given a proposal entry `proposals.knowledge.self.patch` proposing a change to `k
 
 ## 13.1 Layered architecture (internal)
 
-Textus internals are organized into four one-way layers — **Interface** (`cli/`, `mcp/`) → **Application** (`application/` use cases) → **Domain** (`domain/` pure values) → **Infrastructure** (`infra/` adapters). Each layer imports only from the one beneath it. Plugin authors touch only the Hook DSL and the manifest YAML; the layering is internal and may evolve.
+Textus internals are organized as one-way layers — **Surfaces** (`surfaces/cli/`, `surfaces/mcp/`) → **Contract** (`contract/`) → **Dispatch** (`dispatch/`) → **Manifest + Core + Ports + Step** (domain and adapters). Each layer imports only from layers to its right. Plugin authors touch only the Step DSL and the manifest YAML; the layering is internal and may evolve.
 
 See [`docs/architecture/README.md`](docs/architecture/README.md) for an ASCII diagram and the full read-path walkthrough.
 
@@ -1050,116 +1038,3 @@ A `textus/3` implementation MAY:
 - Provide alternate output formats (`--output=yaml`, `--output=table`) for human use.
 - Support additional schema field types beyond §6, marked as `vendor:<name>` extensions.
 
-## 16. Migrating from textus/2
-
-textus does not ship a built-in textus/2 → textus/3 migrator. The historical upgrade path (via the one-shot `textus migrate` in the 0.11.x line) is recorded in `CHANGELOG.md` §0.11.0. `textus doctor` refuses a store still declaring `version: textus/2`. The textus/2 → textus/3 rename table is kept below for reference.
-
-**Vocabulary summary** (textus/2 → textus/3 rename table, for reference):
-
-| Category | textus/2 | textus/3 (current) |
-|---|---|---|
-| Actor | `ai` | `agent` |
-| Actor | `script` | `automation` |
-| Actor | `build` | `automation` |
-| Zone | `inbox` | `intake` |
-| Manifest | `writable_by:` | (removed — authority is derived from `kind:` × `can:`) |
-| Manifest | `policies:` | `rules:` |
-| Manifest | `handler_allowlist:` | `intake_handler_allowlist:` |
-| Manifest | `promote_requires:` | `guard: { accept: [...] }` |
-| Manifest | `projection:` | `source: { from: project, select: ..., ... }` (flat fields) |
-| Manifest | `generator:` | `source: { from: command, ... }` |
-| Hook event | `:intake` | `:resolve_handler` |
-| Hook event | `:reduce` | `:transform_rows` |
-| Hook event | `:check` | `:validate` |
-| Hook event | `:put` | `:entry_written` |
-| Hook event | `:deleted` | `:entry_deleted` |
-| Hook event | `:refreshed` | `:entry_fetched` |
-| Hook event | `:built` | `:entry_produced` |
-| Hook event | `:accepted` | `:proposal_accepted` |
-| Hook event | `:reject` | `:proposal_rejected` |
-| Hook event | `:published` | `:entry_published` |
-| Hook event | `:mv` | `:entry_renamed` |
-| Hook event | `:loaded` | `:store_loaded` |
-| Hook event | `:refresh_began` | `:entry_fetch_started` |
-| Hook event | `:refresh_detached` | `:fetch_backgrounded` |
-| Hook event | `:refresh_failed` | `:entry_fetch_failed` |
-| Hook DSL | `Textus.hook(ev, name)` / sugar | `Textus.on(ev, name)` |
-| Source field | `projection.reduce:` | `source.transform:` |
-| `_meta` key | `reducer` | `transform` |
-| CLI flag | `--format=json` (envelope) | `--output=json` |
-| CLI verb | `refresh-stale` | `fetch all` |
-| CLI verb | `policy list/explain` | `rule list/explain` |
-
-**Hook migration.** Legacy event names / DSL methods must be renamed to the textus/3 forms above before a hook will load; see `CHANGELOG.md` §0.11.0 for the full event-rename detail.
-
-### 16.1 Breaking changes in 0.31.0 (capability-based roles)
-
-0.31.0 replaced declared per-zone write policies with **derived** authority and renamed the `refresh` transition to `fetch`. These keys/values are no longer accepted:
-
-| Removed / renamed (≤ 0.30) | 0.31.0 form |
-|---|---|
-| `zones[*].write_policy:` | (removed) authority is derived: `role.can ⊇ { verb_for(zone.kind) }` |
-| `roles[*].kind:` (`accept_authority`/`generator`/`proposer`/`runner`) | `roles[*].can:` (subset of `propose`, `author`, `fetch`, `build`) |
-| Actors `runner`, `builder` | `automation` (`can: [fetch, build]`) by default |
-| `rules[*].refresh:` slot | `rules[*].fetch:` slot |
-| CLI `textus refresh` / `refresh stale` | `textus fetch` / `fetch all` |
-| `_meta.last_refreshed_at` | `_meta.last_fetched_at` |
-| Promotion predicate `:human_accept` / `:accept_authority_signed` | `:author_signed` |
-| Envelope `refreshing` | `fetching` |
-
-A manifest still declaring `write_policy:` or a role `kind:` is rejected at load. There is no compatibility alias — the breaking change requires a new wire-compatible manifest. (Wire string `textus/3` is unchanged: capabilities are a manifest concept and never appear on the wire.)
-
-### 16.2 Breaking changes in 0.33.0 (workspace/keep + Setup-1 scaffold)
-
-0.33.0 adds the fifth coordination primitive (`workspace` zone-kind + `keep` capability), renames the capability `accept` → `author` (and predicate `accept_signed` → `author_signed`), renames zone-kind `origin` → `canon`, and renames the default scaffold zones to the Setup-1 names. These changes affect **manifest files and tooling** only — the `textus/3` wire format is **UNCHANGED** (envelope shape, audit-log schema, key grammar, and the `version: textus/3` field are all identical to 0.32.x).
-
-**Renames (manifest and predicate vocabulary):**
-
-| Removed / renamed (≤ 0.32) | 0.33.0 form |
-|---|---|
-| Zone-kind `origin` | `canon` |
-| Capability `accept` | `author` |
-| Promotion predicate `accept_signed` | `author_signed` |
-| Default scaffold zone `identity` | `knowledge` (identity keys live under `knowledge.identity.*`) |
-| Default scaffold zone `working` | `knowledge` (merged into the same `canon` zone) |
-| Default scaffold zone `intake` | `feeds` |
-| Default scaffold zone `review` | `proposals` |
-| Default scaffold zone `output` | `artifacts` |
-
-**New in 0.33.0:**
-
-| Addition | Detail |
-|---|---|
-| Zone-kind `workspace` | Agent's own durable lane. Required capability: `keep`. Bytes never auto-promote; climb to `canon` only via propose→accept. |
-| Capability `keep` | Authorizes writes to `workspace` zones. Default scaffold: `agent` holds `[propose, keep]`. |
-| Default scaffold zone `notebook` | `kind: workspace`, default owner `agent`. |
-| `owner:` on a zone | OPTIONAL, INFORMATIONAL — not enforced in 0.33.0 (owner-scoped enforcement is deferred). |
-| `desc:` on a zone | OPTIONAL — surfaces as the `purpose` field in `textus boot` zone rows. |
-
-**Clarification (not a breaking change):** `accept` and `reject` are **transition verbs** (CLI commands), not capabilities. Both require the `author` capability. This has always been true; 0.33.0 makes it explicit by removing `accept` from the capability vocabulary.
-
-A manifest declaring `kind: origin` or capability `accept` (in a `can:` list) is rejected at load.
-
-### 16.3 Breaking changes in 0.35.0 (proposal target-canon + `author_held`)
-
-0.35.0 constrains a proposal's target to a `canon` zone and renames the anchor-gate predicate. No `textus/3` wire change; no manifest-schema change.
-
-**Renames (predicate vocabulary):**
-
-| Removed / renamed (≤ 0.34) | 0.35.0 form |
-|---|---|
-| Promotion predicate `author_signed` | `author_held` |
-
-**New in 0.35.0:**
-
-| Addition | Detail |
-|---|---|
-| Floor predicate `target_is_canon` | On the `accept` base guard. A proposal's `target_key` MUST resolve to a `canon` zone; `accept` refuses any other target with `guard_failed` naming `target_is_canon`. Floor-only — not relaxable via `rules[].guard`. |
-| `doctor` check `proposal_targets` | Warns on queued proposals whose `target_key` is non-canon (`proposal.target_not_canon`) or unresolvable (`proposal.target_unresolved`). |
-
-A `rules[].guard` block referencing the predicate by its old name `author_signed` is rejected at load (unknown predicate).
-
----
-
-**Spec word count target:** <2700 words (allowance widened to fit vocabulary axes intro + migration section).
-**Reviewed against community-testing checklist (idea file §"Community-testing"):** ✅ implementable in a day in TS/Python (four concepts: manifest, schema, envelope, staleness check); ✅ conformance fixtures A–I; ✅ "Why not X?" section present (incl. why no execution); ✅ name picked.