textus 0.47.0 → 0.49.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c87fe067b0988d187beac617c4540e1563d0f006a08d6090b2b483c699555d46
-  data.tar.gz: 4f0503119ebf3eeff28d7a16aee8dc8c62673e6b41912e85bc3453e596075e65
+  metadata.gz: 29a370d0ed895357e5a2e70d5f9b41542b0a4e5036472aa6f728f7a0bc459838
+  data.tar.gz: 87bf64e383226fad74ca8534fca9f8b8de707f1e01bc910c05ad1266e5de032a
 SHA512:
-  metadata.gz: fde04b0339e798e545c98699462afaf2767a772f1e76811c4f8833b561b69d02b172e4879cf17ffaea1dd51f1930846007abf4523a801ccfb5525c53e1365b7f
-  data.tar.gz: 10a4343781cb2251ba8f91121c0a89b1fe211702e7c5057693fce27357eee55c3abe6bfe7a88009ffc89f5fcc49ad6c44fcf258f532f5ac9d69d960857e833c6
+  metadata.gz: d3f2279c8660c754b64defe04aeac05e198095ef056b7a4aee534d3bd290baac7bf13d206999872a82c6bc61f723771f852bbfde2594fbaa17f80a19082df877
+  data.tar.gz: e11ce9e704b3ea33ef94012d8425624dd3391152869d1ecb6b00e5422042a50d4c3c75612227ddd61f9ed8c10720e6f254c818e1492056a2ca3d00751500554b

data/CHANGELOG.md

@@ -9,6 +9,45 @@ The **gem version** (`0.x.y`) is distinct from the **protocol version**
 bump is a breaking change that requires a store migration; the gem version
 tracks both additive improvements and breaking protocol bumps independently.
 
+## 0.49.0 — 2026-06-04 — Normalize the key-verb family + remove `migrate` (ADR 0082)
+
+The single-key mutation verbs gain the `key_` family stem, and the `migrate` orchestrator is removed.
+
+### Changed (breaking)
+
+- **`mv` → `key_mv` and `delete` → `key_delete`**, renamed everywhere the token is load-bearing: the verb / MCP-tool id, the guard transition symbol, the manifest `guard:` transition key, and the audit-log verb string. The single-key verbs now share the `key_` stem with their bulk cousins `key_mv_prefix`/`key_delete_prefix`; `zone_mv` is unchanged. **The CLI is unchanged** — `key mv`, `key delete`, `key mv-prefix`, `key delete-prefix` keep their spelling. **Migration:** manifests with `guard: { mv: … }` / `guard: { delete: … }` blocks must rename those keys to `key_mv` / `key_delete`; MCP clients pinned to the `mv`/`delete` tool ids must update; audit rows written before this release keep their `mv`/`delete` verb strings (readers must accept both).
+
+### Removed (breaking)
+
+- **The `migrate` verb (YAML-plan orchestrator).** It was non-transactional and added a second input format for no capability the primitives lack — its `zone_mv`/`key_mv_prefix`/`key_delete_prefix` ops remain individually callable, each with `--dry-run`. Removed from the CLI and the MCP catalog.
+
+## 0.48.0 — 2026-06-04 — Unified `lifecycle` policy + docs become canon (ADR 0079, 0081)
+
+Staleness and retention collapse into one age policy, and the upkeep verb surface shrinks 8→3.
+
+### Changed
+
+- **`docs/` is now textus canon (ADR 0081).** Every committed doc is authored under `.textus/zones/knowledge/` and published back to `docs/` by `textus build` (the same projection mechanism as `CLAUDE.md`/`AGENTS.md`); `docs/` is now a committed, sentinel-managed mirror. Adopt-in-place (ADR 0050) made the migration a zero-diff republish. `docs/assets/` (branding binaries) moved to repo-root `assets/`; `docs/plans/` (gitignored) is unchanged.
+- **One `lifecycle: { ttl, on_expire }` rule slot** replaces the separate `fetch:` (intake freshness) and `retention:` (leaf pruning) slots. `on_expire` is `refresh` (re-pull intake), `warn` (flag on read), `drop` (delete), or `archive` (copy aside then delete). An action's *destructiveness* decides where it runs: non-destructive `refresh`/`warn` are applied lazily on `get`; destructive `drop`/`archive` run only on the `tend` sweep. A read never deletes.
+- **`tend` is now the destructive-only sweep** — it drops/archives expired entries and refreshes cold intake, superseding the composite body of ADR 0078. Result keys are `dropped`/`archived`/`refreshed`/`failed` (apply) and `would_drop`/`would_archive`/`would_refresh` (`--dry-run`).
+- **`freshness` reports the unified verdict** (`fresh`/`expired`/`no_policy`) and the matched `on_expire` action; `pulse`'s `stale` list now reflects expired entries.
+
+### Removed
+
+- **The `stale`, `retainable`, `fetch`, `fetch_all`, and `retain` verbs.** Read-through refresh is `get` (lazy); destructive pruning is `tend`; `FetchWorker` remains as the internal executor for `get`/`tend`. Generator/build drift (dependency-based, not age-based) is now the `textus doctor` `generator_drift` check.
+- **The `fetch:`/`retention:` rule slots and the per-rule `fetch_timeout_seconds` override** (accepted loss; the constant ceiling applies to every intake).
+
+### Added
+
+- **`doctor` checks `lifecycle.action_invalid`** (`refresh` only on intake; `drop`/`archive` only on stored entries) and **`generator_drift`** (the surviving home for build-drift detection).
+
+## 0.47.1 — 2026-06-04 — External entries are a non-build path
+
+### Fixed
+
+- **`build` no longer materializes `external` derived entries.** External entries are generated by an out-of-band runner — textus only tracks their staleness. Previously they flowed through `Derived#publish_via` → `Pipeline.run` and hit a catch-all branch that emitted an empty payload and re-stamped the volatile `generated_at` (contrary to ADR 0070), which for an entry with publish targets would **clobber the runner's artifact with an empty render**. External is now skipped in `Derived#publish_via`, and `Pipeline.run` raises loudly if a non-projection source reaches it (only projection-derived entries are buildable).
+- **`compute.command` is now parsed for `external` entries.** The parser read `compute["runner"]`, a key the manifest schema forbids (`COMPUTE_KEYS` allows `command`), so `External#command` was always `nil`. The data field is renamed `runner` → `command` and now reads `compute["command"]`.
+
 ## 0.47.0 — 2026-06-04 — Close the agent loop over MCP
 
 The edit→accept→rebuild loop now closes over a single MCP transport: `build` is surfaced to MCP, `init --with-agent` scaffolds a connectable agent setup, and connection-lifecycle hardening (whole-contract drift fingerprint + a connect-time event carrying the resolved role) underpins it.

data/README.md

@@ -1,7 +1,7 @@
 <p align="center">
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/branding/wordmark-dark.png">
-    <img src="docs/assets/branding/wordmark.png" alt="textus" width="360">
+    <source media="(prefers-color-scheme: dark)" srcset="assets/branding/wordmark-dark.png">
+    <img src="assets/branding/wordmark.png" alt="textus" width="360">
   </picture>
 </p>
 
@@ -184,7 +184,7 @@ textus get knowledge.notes.org.jane
 textus list --zone=knowledge
 printf '%s' '{"_meta":{"name":"bob","org":"acme"},"body":"hi\n"}' \
   | textus put knowledge.notes.bob --as=human --stdin
-textus freshness --zone=artifacts    # per-entry fresh/stale/never_fetched/no_policy
+textus freshness --zone=artifacts    # per-entry fresh/expired/no_policy + on_expire action
 textus rule list                     # show every rule block
 textus audit --limit=20              # query the audit log
 ```
@@ -263,12 +263,14 @@ Textus.hook do |reg|
 end
 ```
 
-To keep a batch of stale intake entries current in one shot:
+Stale intake entries refresh lazily on read: a `textus get KEY` whose matched
+`lifecycle` rule says `on_expire: refresh` re-pulls the source in-process before
+returning. To find what is due, list the expired entries:
 
 ```sh
-textus fetch all --prefix=feeds --zone=feeds --as=automation
-# or just fetch everything past its TTL in the feeds zone:
-textus fetch all --zone=feeds --as=automation
+textus freshness --zone=feeds --output=json   # rows with status: "expired"
+# then read each one (read-through refresh per its lifecycle rule):
+textus get feeds.calendar.events --as=automation
 ```
 
 See SPEC.md §5.10 for the full hook contract.

data/SPEC.md

@@ -148,7 +148,7 @@ Textus internals (`manifest.yaml`, `schemas/`, `templates/`, `hooks/`) live dire
 
 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.
 
-`.textus/audit.log` is an append-only NDJSON file written under a file lock by every successful `put`, `delete`, `accept`, and `build`. `.textus/role` (one line containing a role name) is optional and participates in the role-resolution order (§5).
+`.textus/audit.log` is an append-only NDJSON file written under a file lock by every successful `put`, `key_delete`, `accept`, and `build`. `.textus/role` (one line containing a role name) is optional and participates in the role-resolution order (§5).
 
 ### 3.1 Store location precedence
 
@@ -208,7 +208,7 @@ entries:
 
 rules:
   - match: feeds.**
-    fetch: { ttl: 6h, on_stale: warn }
+    lifecycle: { ttl: 6h, on_expire: warn }
 
 audit:
   max_size: 10485760   # bytes before rotating (default: 10 485 760 = 10 MiB)
@@ -454,9 +454,9 @@ A sentinel is written for each published file at `<store_root>/.run/sentinels/<t
 
 **Subtree mirror.** A nested entry MAY declare `publish: { tree: "dir" }` instead of `to:` (see §4). On every build, textus walks the entry's full stored subtree (`zones/<path>/**`), applies the entry's `ignore:` filter, and byte-copies each file to the target directory, preserving relative layout — one sentinel per file under `<store_root>/.run/sentinels/`. The mirror is path-driven: no keys are enumerated, no template variables are interpreted, and mirrored files are opaque payload (never addressable). On rebuild, the entire target directory is pruned of textus-managed files the current source no longer produces; unmanaged files are never touched. The build envelope grows a `published_leaves` array — one row per mirrored file, with `key`, `source`, and `target` — alongside the existing `built` array, plus a `pruned` array listing any orphaned managed files removed on this build. Targets that would resolve outside the repo root are refused. When a `publish.tree` target overlaps a `derived` entry's `publish.to` (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` (ADR 0047).
 
-### 5.4 Intake (declared, fetched via registered intake handler)
+### 5.4 Intake (declared, refreshed via registered intake handler)
 
-Intake entries declare an external source by naming an **intake handler** — a registered, named function that pulls data into the entry. textus itself still makes no implicit network calls: an intake handler only runs when explicitly invoked by `textus fetch KEY --as=automation` (or by `textus fetch all`). The declaration is data only:
+Intake entries declare an external source by naming an **intake handler** — a registered, named function that pulls data into the entry. textus itself still makes no implicit network calls: an intake handler only runs when a read-through `textus get KEY` encounters a stale entry whose `lifecycle` rule says `on_expire: refresh`. The declaration is data only:
 
 ```yaml
 - key: feeds.calendar.events
@@ -468,23 +468,22 @@ Intake entries declare an external source by naming an **intake handler** — a
 
 rules:
   - match: feeds.calendar.**
-    fetch:
+    lifecycle:
       ttl: 6h
-      on_stale: warn            # warn | sync | timed_sync (default: warn)
-      sync_budget_ms: 500       # only used when on_stale: timed_sync (default: 500)
+      on_expire: refresh        # refresh | warn | drop | archive
+      budget_ms: 500            # bound the in-process refresh (default: 500)
 ```
 
-`handler` names a registered `:resolve_intake` hook (see §5.10 for the hook contract); `config` is an opaque hash handed to the handler. The freshness budget (`ttl`, `on_stale`, `sync_budget_ms`) lives in a top-level **`rules:`** block matched by key glob (§5.11).
+`handler` names a registered `:resolve_intake` hook (see §5.10 for the hook contract); `config` is an opaque hash handed to the handler. The freshness budget (`ttl`, `on_expire`, `budget_ms`) lives in a top-level **`rules:`** block matched by key glob (§5.11).
 
-#### `on_stale:` semantics
+#### `on_expire:` semantics
 
-`on_stale:` declares what happens when `get` encounters a stale intake entry. `get` is **read-through on every surface** (CLI, Ruby, MCP): it returns the freshest obtainable envelope, fetching on a stale verdict per the entry's fetch rule and degrading to a pure on-disk read for keys with no fetch rule (ADR 0062). The value lives on the matching policy block, not on the entry. Vocabulary: `warn | sync | timed_sync`.
+`on_expire:` declares what happens when `get` encounters an expired (past-TTL) intake entry. `get` is **read-through on every surface** (CLI, Ruby, MCP): it returns the freshest obtainable envelope, refreshing on an expired verdict per the entry's `lifecycle` rule and degrading to a pure on-disk read for keys with no lifecycle rule (ADR 0062). The value lives on the matching policy block, not on the entry. For intake entries the only valid actions are `refresh` and `warn` (`drop`/`archive` apply to stored entries and are enforced by `doctor` via `lifecycle.action_invalid`).
 
 | Value | Behaviour |
 |---|---|
 | `warn` (default) | Return the entry immediately with `stale: true`, `stale_reason:` populated, and `fetching: false`. No blocking. |
-| `sync` | Block the `get` call, run the intake handler in-process, write the fetched result, then return the fresh envelope. The caller waits. |
-| `timed_sync` | Like `sync`, but with a `sync_budget_ms` deadline (default 500 ms). If the handler finishes within the budget the fresh envelope is returned. If it does not finish in time, return the stale envelope (with `stale: true`, `fetching: true`) and let the fetch complete in the background. Fires `:fetch_backgrounded` when the deadline is exceeded. |
+| `refresh` | Block the `get` call, run the intake handler in-process under a `budget_ms` deadline (default 500 ms), write the result, and return the fresh envelope. If the handler does not finish in time, return the stale envelope (with `stale: true`, `fetching: true`) and let the refresh complete in the background. Fires `:fetch_backgrounded` when the deadline is exceeded. |
 
 > **Note:** `list`/`where` paths do **not** annotate freshness — only `get` does.
 
@@ -496,10 +495,10 @@ In intake mode the handler MUST return one of three shapes, all normalized by th
 
 **Built-in intake handlers.** `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.
 
-**Fetch paths.** Two are supported:
+**Refresh paths.** Two are supported:
 
-1. **In-process** — `textus fetch KEY --as=automation` resolves the entry's `intake.handler`, invokes the registered `:resolve_intake` hook with `(caps:, config:, args: {})`, and writes the result under a role holding `fetch` (`automation` by default).
-2. **External automation** — a cron job or agent harness reads `textus list --zone=intake --stale --output=json`, fetches the source out of band, and pipes bytes back through `textus put KEY --as=automation --stdin`. The CLI verb `textus fetch all [--prefix=K] [--zone=Z]` drives this loop in one shot.
+1. **In-process** — a read-through `textus get KEY --as=automation` on a stale entry whose rule says `on_expire: refresh` resolves the entry's `intake.handler`, invokes the registered `:resolve_intake` hook with `(caps:, config:, args: {})`, and writes the result under a role holding `fetch` (`automation` by default).
+2. **External automation** — a cron job or agent harness reads `textus freshness --zone=intake --output=json`, fetches sources reported `expired` out of band, and pipes bytes back through `textus put KEY --as=automation --stdin`.
 
 Both paths share the same write gate, audit-log entry, and `:entry_fetched` event. User-supplied hooks live in `.textus/hooks/**/*.rb` and auto-load at `Store#initialize` — see §5.10 for the full hook contract.
 
@@ -536,9 +535,9 @@ Schema (one JSON object per line, no interior whitespace):
 
 `seq` is a monotonic integer counter, auto-incremented on each append. It is the foundation for cursor-based queries: `textus audit --seq-since=N` returns only rows with `seq > N`, and `textus pulse --since=N` builds its `changed` array from the same cursor. When an agent's cursor falls below the oldest available seq (due to log rotation), the operation raises `CursorExpired`.
 
-`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`, `mv`, ...). `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).
+`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`, `key_delete`, `accept`, `compute`, `key_mv`, ...; rows written before ADR 0082 used `delete`/`mv` — readers must accept both). `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).
 
-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.
+For `key_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.
 
 **Rotation.** After every successful append the implementation checks whether `audit.log` exceeds `max_size` bytes (checked inside the held `flock`, so the check sees the post-write size). If it does, the active log is rotated:
 
@@ -688,10 +687,10 @@ A manifest MAY declare a top-level `rules:` block — a list of rule blocks matc
 ```yaml
 rules:
   - match: feeds.**
-    fetch: { ttl: 6h, on_stale: warn }
+    lifecycle: { ttl: 6h, on_expire: warn }
 
   - match: feeds.calendar.**
-    fetch: { ttl: 30m, on_stale: timed_sync, sync_budget_ms: 800 }
+    lifecycle: { ttl: 30m, on_expire: refresh, budget_ms: 800 }
     intake_handler_allowlist: [ical-events]
 
   - match: proposals.**
@@ -703,24 +702,21 @@ rules:
 
 | Slot | Type | Meaning |
 |---|---|---|
-| `fetch` | `{ ttl, on_stale, sync_budget_ms, fetch_timeout_seconds }` | Freshness budget for intake entries. `on_stale` is `warn` (default), `sync`, or `timed_sync`. |
+| `lifecycle` | `{ ttl, on_expire, budget_ms? }` | Unified age policy (ADR 0079). `on_expire` is `refresh` (re-pull intake), `warn` (flag on read), `drop` (delete), or `archive` (copy to `<store>/archive/<relative-path>` then delete). Non-destructive actions (`refresh`/`warn`) are applied lazily on `get`; destructive actions (`drop`/`archive`) only on the `tend` sweep. `refresh` is valid only for intake entries; `drop`/`archive` only for stored entries (`doctor` `lifecycle.action_invalid` enforces). Age is measured from `_meta.last_fetched_at` (intake) when present, else the leaf file's modification time. `budget_ms` (optional) bounds a `refresh` to a deadline, returning the stale envelope and refreshing in the background when exceeded. |
 | `intake_handler_allowlist` | list of strings | Constrains which `intake.handler:` names may be used by 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`, `delete`, `mv`, `accept`, `reject`, `fetch`). 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. |
-| `retention` | `{ expire_after:, archive_after: }` | Pruning policy for matched leaves. Duration strings: `30s`, `90m`, `12h`, `30d`, or bare integer seconds. `textus retain --as=ROLE` sweeps matched leaves: `expire_after` is checked first, so a leaf older than `expire_after` is deleted (and audited); otherwise a leaf older than `archive_after` is copied to `<store>/archive/<relative-path>` and then deleted. Age is measured from the leaf file's modification time. The `--as` role must be allowed to write the matched zone. |
+| `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`, `fetch`). 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. |
 
-Both retention windows are optional, and `expire_after` is evaluated before
-`archive_after` — so when both apply, a leaf past the (longer) `expire_after`
-window is deleted rather than archived. The usual configuration is therefore
-`archive_after < expire_after` (archive a leaf, then delete it once older).
-`textus retain --as=ROLE` runs the sweep; `--prefix` and `--zone` narrow it, and
-any leaf whose zone the `--as` role cannot write is reported as a failure rather
-than aborting the run.
+The `lifecycle:` slot unifies the former `fetch:` (intake freshness) and
+`retention:` (leaf pruning) slots into one age policy (ADR 0079). Generator/build
+drift — a derived entry whose sources changed since its `generated.at` — is
+dependency-based, not age-based, and is reported by the `textus doctor`
+`generator_drift` check rather than this slot.
 
 **Match grammar.** `match:` is a single glob using `*` (single segment) and `**` (any depth). A literal segment ranks more specifically than `*`; `*` ranks more specifically than `**`.
 
-**Resolution.** For each key textus computes a `RuleSet { fetch, intake_handler_allowlist, guard, retention }` by walking every block whose `match` matches the key, ranked by specificity. **Per slot, the most specific block wins.** Two blocks of equal specificity that match the same key and fill the same slot is a manifest error reported by `textus doctor` (`rule_ambiguity`).
+**Resolution.** For each key textus computes a `RuleSet { handler_allowlist, guard, lifecycle }` by walking every block whose `match` matches the key, ranked by specificity. **Per slot, the most specific block wins.** Two blocks of equal specificity that match the same key and fill the same slot is a manifest error reported by `textus doctor` (`rule_ambiguity`).
 
-**Read surface.** `textus rule list` dumps every block. `textus rule explain KEY` shows the resolved `RuleSet` for one key — lean effective `{fetch, guard}` by default; `--detail` adds every matched block and the effective guard predicate names for every write transition (ADR 0059).
+**Read surface.** `textus rule list` dumps every block. `textus rule explain KEY` shows the resolved `RuleSet` for one key — lean effective `{lifecycle, guard}` by default; `--detail` adds every matched block and the effective guard predicate names for every write transition (ADR 0059).
 
 ### 5.12 Storage formats
 
@@ -826,9 +822,9 @@ Every successful CLI response (`--output=json`) is a single JSON envelope:
 - `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.
-- `stale` is `true` when the entry's TTL has elapsed and the data has not yet been fetched; `false` otherwise. Only populated for entries matched by a `fetch:` rule slot (typically `feeds` / quarantine zone); always `false` elsewhere.
+- `stale` is `true` when the entry's TTL has elapsed and the data has not yet been refreshed; `false` otherwise. Only populated for entries matched by a `lifecycle:` rule slot (typically `feeds` / quarantine zone); always `false` elsewhere.
 - `stale_reason` is a short human-readable string describing why the entry is stale (e.g. `"ttl_exceeded"`, `"never_fetched"`), or `null` when `stale` is `false`.
-- `fetching` is `true` when a `timed_sync` background fetch is in flight for this entry; `false` otherwise. Callers observing `stale: true, fetching: true` SHOULD retry after a short delay.
+- `fetching` is `true` when an `on_expire: refresh` background refresh is in flight for this entry; `false` otherwise. Callers observing `stale: true, fetching: true` SHOULD retry after a short delay.
 
 > **Note:** `list`/`where` envelopes do **not** include `stale`, `stale_reason`, or `fetching` — freshness annotation is only provided by `get`.
 
@@ -867,7 +863,7 @@ All verbs accept `--output=json` and emit a canonical envelope (success or error
 |---|---|---|
 | `list [--prefix=K] [--zone=Z]` | read | any |
 | `where K` | read | any |
-| `get K [--no-fetch]` | read (read-through by default: fetch-on-stale per the entry's fetch rule, degrades to a pure read; `--no-fetch` / `{fetch:false}` for an explicit pure on-disk read) | any |
+| `get K [--no-fetch]` | read (read-through by default: refresh-on-stale per the entry's `lifecycle` rule when `on_expire: refresh`, degrades to a pure read; `--no-fetch` / `{fetch:false}` for an explicit pure on-disk read) | any |
 | `schema show K` | read | any |
 | `freshness [--prefix=K] [--zone=Z]` | read | any |
 | `audit [--key=K] [--zone=Z] [--role=R] [--verb=V] [--since=X] [--correlation-id=ID] [--limit=N]` | read | any |
@@ -883,10 +879,8 @@ All verbs accept `--output=json` and emit a canonical envelope (success or error
 | `put K --stdin --as=R [--fetch=NAME]` | write | per zone |
 | `propose K --stdin --as=R` | write | `propose`-holder (auto-prefixes propose_zone) |
 | `key delete K --if-etag=E --as=R` | write | per zone |
-| `fetch KEY --as=automation` | write | `fetch`-holder (typically `automation`) |
-| `fetch all [--prefix=K] [--zone=Z] [--as=automation]` | write | `fetch`-holder (typically `automation`) |
 | `build [--prefix=K] [--dry-run]` | write | `build`-holder (typically `automation`) |
-| `retain [--prefix=K] [--zone=Z] --as=ROLE` | write | per zone (role must write the matched zone) |
+| `tend [--prefix=K] [--zone=Z] [--dry-run] --as=ROLE` | write | per zone (role must write the matched zone) |
 | `accept K --as=human` | write | `author`-holder (typically `human`) |
 | `reject K --as=human` | write | `author`-holder (typically `human`) |
 | `init` | write | `human` |
@@ -900,7 +894,7 @@ All verbs accept `--output=json` and emit a canonical envelope (success or error
 {
   "agent_quickstart": {
     "read_verbs":     ["get", "list", "pulse", "schema_show", "boot", "rule_explain", "where", "deps", "rdeps"],
-    "write_verbs":    ["accept", "delete", "fetch", "fetch_all", "mv", "propose", "put", "reject"],
+    "write_verbs":    ["accept", "key_delete", "key_mv", "propose", "put", "reject"],
     "writable_zones": ["proposals"],
     "propose_zone":   "proposals",
     "latest_seq":     1842
@@ -910,7 +904,7 @@ All verbs accept `--output=json` and emit a canonical envelope (success or error
 
 `read_verbs` is derived from the MCP verb catalog — the verbs the agent can actually call over its transport — so it lists the read/discovery verbs (`schema_show` for an entry's field shape, `rule_explain` for its freshness/guard policy, and the graph reads `where`/`deps`/`rdeps`, ADR 0060) and never the CLI-only `audit`/`freshness`/`doctor` (ADR 0056). An agent learns an entry's `_meta` shape by calling the `schema_show` verb before a `put`/`propose`, not by shelling out to a CLI. The graph reads `deps`/`rdeps` return a structured `{key, deps}`/`{key, rdeps}` envelope on every surface (CLI, Ruby, MCP) — a hash, not a bare array, consistent with the other structured read responses such as `where` (ADR 0060 amendment).
 
-The agent's MCP write surface includes the single-key `delete` and `mv` tools alongside their bulk `key_delete_prefix`/`key_mv_prefix` cousins (ADR 0060 amendment). All of these apply by default; `dry_run: true` is a uniform opt-in preview that returns a Plan without mutating (ADR 0071 — verbs are actions, dry-run is opt-in on every surface). Single-key `delete` additionally accepts an optional `if_etag` optimistic-concurrency check. The blast-radius reads (`where`/`deps`/`rdeps`) remain on MCP so an agent can look before it leaps. The promotion verbs `accept` and `reject` are also on MCP (ADR 0072): they are gated by the `author_held` capability floor, not by transport absence — a default-`agent` connection is refused, while a connection launched as a role holding `author` (`--as`/`TEXTUS_ROLE`/`.textus/role`, resolved once at launch per ADR 0040) can promote, closing the propose→accept loop over one transport. `build` is also on MCP (ADR 0076): it is caller-agnostic and self-elevating — it always runs as the manifest's `build`-capable actor regardless of the calling role, grants no authority over content (build is a pure, idempotent function of already-accepted canon, ADR 0070), and is serialized by a shared single-writer lock across all transports so a concurrent CLI or background build cannot collide with an MCP-triggered one.
+The agent's MCP write surface includes the single-key `key_delete` and `key_mv` tools alongside their bulk `key_delete_prefix`/`key_mv_prefix` cousins (ADR 0060 amendment; the single-key tools were renamed from `delete`/`mv` to share the `key_` family stem in ADR 0082, which also removed the `migrate` YAML-plan orchestrator — its `zone_mv`/`key_mv_prefix`/`key_delete_prefix` ops remain individually callable). All of these apply by default; `dry_run: true` is a uniform opt-in preview that returns a Plan without mutating (ADR 0071 — verbs are actions, dry-run is opt-in on every surface). Single-key `key_delete` additionally accepts an optional `if_etag` optimistic-concurrency check. The blast-radius reads (`where`/`deps`/`rdeps`) remain on MCP so an agent can look before it leaps. The promotion verbs `accept` and `reject` are also on MCP (ADR 0072): they are gated by the `author_held` capability floor, not by transport absence — a default-`agent` connection is refused, while a connection launched as a role holding `author` (`--as`/`TEXTUS_ROLE`/`.textus/role`, resolved once at launch per ADR 0040) can promote, closing the propose→accept loop over one transport. `build` is also on MCP (ADR 0076): it is caller-agnostic and self-elevating — it always runs as the manifest's `build`-capable actor regardless of the calling role, grants no authority over content (build is a pure, idempotent function of already-accepted canon, ADR 0070), and is serialized by a shared single-writer lock across all transports so a concurrent CLI or background build cannot collide with an MCP-triggered one.
 
 `latest_seq` is the current high-water mark of the audit log; agents should use it as the starting cursor for `pulse`.
 
@@ -939,7 +933,7 @@ The agent's MCP write surface includes the single-key `delete` and `mv` tools al
   "if_etag": "sha256:8f3c…" }
 ```
 
-`if_etag` is optional on both `put` and `delete`. When provided, the write fails with `etag_mismatch` if the on-disk file's etag differs. When omitted, the write is unconditional (last-writer-wins).
+`if_etag` is optional on both `put` and `key_delete`. When provided, the write fails with `etag_mismatch` if the on-disk file's etag differs. When omitted, the write is unconditional (last-writer-wins).
 
 **`textus freshness` output shape:**
 
@@ -952,14 +946,14 @@ The agent's MCP write surface includes the single-key `delete` and `mv` tools al
       "last_fetched_at": "2026-05-21T13:21:17Z",
       "age_seconds": 65000,
       "ttl_seconds": 43200,
-      "on_stale": "warn",
-      "status": "stale",
+      "on_expire": "warn",
+      "status": "expired",
       "next_due_at": "2026-05-22T01:21:17Z" }
   ]
 }
 ```
 
-Each row reports one entry's verdict (`fresh`, `stale`, `never_fetched`, or `no_policy`) against its matched `fetch:` rule. `textus build` consumes its own staleness signal and executes derived entries' projections under a `build`-holding role (`automation` by default); `--dry-run` prints the plan without executing.
+Each row reports one entry's verdict (`fresh`, `expired`, or `no_policy`) plus the matched rule's `on_expire` action, against its matched `lifecycle:` rule. `textus build` consumes its own staleness signal and executes derived entries' projections under a `build`-holding role (`automation` by default); `--dry-run` prints the plan without executing.
 
 `textus accept K --as=human` promotes a pending entry into its target zone: it copies the patch body into the target key, deletes the pending entry, and writes one audit line per side (§audit). Only a role holding the `author` capability (the trust anchor — `human` by default) may invoke `accept`.
 
@@ -1008,7 +1002,7 @@ Given a manifest entry where `key: identity.self` lives in the `identity` zone (
 Given the `person` schema and a `put` whose frontmatter omits `relationship`, the result is the error envelope with `code: "schema_violation"`, `details.missing: ["relationship"]`, and exit code 1.
 
 **Fixture D — Staleness detection:**
-Given a manifest entry `intake.notes` matched by a `rules: [{ match: intake.notes, fetch: { ttl: 1h } }]` block and an envelope on disk whose `_meta.last_fetched_at` is older than `now - ttl`, `textus freshness --output=json` includes a row for `intake.notes` with `status: "stale"`. Calling `textus freshness` does NOT trigger a fetch.
+Given a manifest entry `intake.notes` matched by a `rules: [{ match: intake.notes, lifecycle: { ttl: 1h, on_expire: warn } }]` block and an envelope on disk whose `_meta.last_fetched_at` is older than `now - ttl`, `textus freshness --output=json` includes a row for `intake.notes` with `status: "expired"`. Calling `textus freshness` does NOT trigger a refresh.
 
 **Fixture E — Projection build:**
 Given a manifest entry `derived.catalogs.skills` whose `compute: { kind: projection }` clause selects fields from `working.projects` entries, `textus build derived.catalogs.skills` materializes the derived entry on disk with frontmatter and body matching the projected shape. The output is content-addressed (no `generated_at` timestamp, ADR 0070), so rebuilding with unchanged sources reproduces it byte-for-byte and writes nothing.
@@ -1020,7 +1014,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/.run/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`, `key_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 proposal entry `proposals.knowledge.self.patch` proposing a change to `knowledge.identity.self`, `textus accept proposals.knowledge.self.patch --as=human` copies the patch body into the target key, deletes the proposal entry, and appends two audit lines (one for the target write, one for the proposals delete) in that order.
@@ -1066,7 +1060,7 @@ A `textus/3` implementation MUST:
 - [ ] Refuse writes whose resolved role lacks the capability the target zone-kind requires with `write_forbidden`.
 - [ ] 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 freshness` per §5.1 and §9, walking each entry, matching it against the top-level `rules:` block, and reporting `fresh|stale|never_fetched|no_policy` without invoking any fetch.
+- [ ] Implement `textus freshness` per §5.1 and §9, walking each entry, matching it against the top-level `rules:` block, and reporting `fresh|expired|no_policy` (plus the `on_expire` action) without invoking any refresh.
 - [ ] Pass the conformance fixtures A–I in §12.
 
 A `textus/3` implementation MAY:

data/docs/reference/conventions.md

@@ -88,38 +88,39 @@ Full contract for both shapes is in [`../../SPEC.md` §5.2.1 and §5.2.2](../../
 
 ## Intake and freshness
 
-External inputs land via `:resolve_intake` hooks, not shell commands. Each intake entry names a registered handler; fetch is on demand:
+External inputs land via `:resolve_intake` hooks, not shell commands. Each intake entry names a registered handler; refresh is on demand via a read-through `get`:
 
 ```sh
-textus fetch feeds.notion.roadmap --as=automation
-textus fetch all --zone=feeds --as=automation   # everything past its TTL
+textus get feeds.notion.roadmap --as=automation        # refreshes if stale
+textus freshness --zone=feeds --output=json            # which entries are expired
 ```
 
-Freshness budgets live in the top-level `rules:` block, matched by glob:
+Lifecycle budgets live in the top-level `rules:` block, matched by glob:
 
 ```yaml
 rules:
   - match: feeds.notion.**
-    fetch: { ttl: 6h, on_stale: warn }   # warn | sync | timed_sync
+    lifecycle: { ttl: 6h, on_expire: refresh }   # refresh | warn | drop | archive
 ```
 
-A typical scheduled-fetch integration shells the `fetch all` sweep itself:
+A typical scheduled integration reads each expired feed (a read-through `get`
+refreshes it in-process):
 
 ```sh
-textus fetch all --zone=feeds --as=automation   # in cron / CI
+textus get feeds.notion.roadmap --as=automation   # in cron / CI
 ```
 
 See [`./zones.md` §6](zones.md) for the full intake contract and [`../how-to/writing-hooks.md`](../how-to/writing-hooks.md) for writing custom handlers.
 
-### Read vs. fetch
+### Read vs. refresh
 
 There is one public read operation (ADR 0062):
 
 | Operation | Behaviour | Use for |
 |-----------|-----------|---------|
-| `ops.get` | Read-through by default — fetches on stale per the entry's fetch rule; degrades to a pure on-disk read when the key has no fetch rule. Pass `fetch: false` (CLI `--no-fetch`, MCP `{fetch:false}`) for an explicit pure read | all callers, including interactive reads, dashboards, and scripts that want the freshest obtainable envelope |
+| `ops.get` | Read-through by default — refreshes on stale per the entry's `lifecycle` rule when `on_expire: refresh`; degrades to a pure on-disk read when the key has no lifecycle rule. Pass `fetch: false` (CLI `--no-fetch`, MCP `{fetch:false}`) for an explicit pure read | all callers, including interactive reads, dashboards, and scripts that want the freshest obtainable envelope |
 
-Build pipelines and other internal callers that must never trigger a fetch (materializer, projection, schema tooling, accept/reject/publish, uid, validator) construct `Read::Get` directly with the method default `fetch: false` — a pure, orchestrator-free read. They bypass the verb-dispatch injection that sets `fetch: true`, so they always get pure reads without any extra argument.
+Build pipelines and other internal callers that must never trigger a refresh (materializer, projection, schema tooling, accept/reject/publish, uid, validator) construct `Read::Get` directly with the method default `fetch: false` — a pure, orchestrator-free read. They bypass the verb-dispatch injection that sets `fetch: true`, so they always get pure reads without any extra argument.
 
 ## Body content
 

data/lib/textus/boot.rb

@@ -87,8 +87,8 @@ module Textus
       { "name" => "accept",   "summary" => "apply a queued proposal to its target zone; requires the author capability" },
       { "name" => "key",      "summary" => "key operations: 'key delete', 'key mv', 'key uid'" },
       { "name" => "build",    "summary" => "materialize derived entries; publish_to and publish_tree fan out copies" },
-      { "name" => "fetch" },
-      { "name" => "freshness", "summary" => "per-entry freshness report (status, age, ttl, on_stale)" },
+      { "name" => "tend" },
+      { "name" => "freshness", "summary" => "per-entry lifecycle report (status, age, ttl, on_expire action)" },
       { "name" => "audit",    "summary" => "query .textus/audit.log with filters (key, role, since, correlation-id, ...)" },
       { "name" => "blame",    "summary" => "audit rows for one key joined with git commit metadata" },
       { "name" => "rule",     "summary" => "inspect effective rules: 'rule list', 'rule explain KEY'" },

data/lib/textus/builder/pipeline.rb

@@ -1,5 +1,4 @@
 require "fileutils"
-require "time"
 
 module Textus
   module Builder
@@ -42,19 +41,25 @@ module Textus
       end
 
       def self.run(mentry:, deps:)
-        # 1. Load sources + project + reduce
+        # 1. Load sources + project + reduce. Only projection-derived entries are
+        # buildable in-process; External entries are generated out-of-band and are
+        # filtered out upstream (Derived#publish_via), so reaching here with a
+        # non-projection source is a wiring bug — fail loudly rather than emit an
+        # empty payload (and never re-stamp the volatile generated_at, ADR 0070).
+        unless mentry.is_a?(Textus::Manifest::Entry::Derived) && mentry.projection?
+          raise UsageError.new(
+            "builder: '#{mentry.key}' is not a projection-derived entry; only projections are buildable",
+          )
+        end
+
         data =
-          if mentry.is_a?(Textus::Manifest::Entry::Derived) && mentry.projection?
-            Textus::Projection.new(
-              reader: deps.reader,
-              spec: mentry.source.to_h.transform_keys(&:to_s),
-              lister: deps.lister,
-              rpc: deps.rpc,
-              transform_context: deps.transform_context,
-            ).run
-          else
-            { "entries" => [], "count" => 0, "generated_at" => Time.now.utc.iso8601 }
-          end
+          Textus::Projection.new(
+            reader: deps.reader,
+            spec: mentry.source.to_h.transform_keys(&:to_s),
+            lister: deps.lister,
+            rpc: deps.rpc,
+            transform_context: deps.transform_context,
+          ).run
         data = data.merge("boot" => deps.inject_boot.call) if mentry.inject_boot && deps.inject_boot
 
         # 2. Render

data/lib/textus/cli/runner.rb

@@ -137,10 +137,11 @@ module Textus
       BEHAVIORAL_HATCHES = %i[get put build].freeze
 
       # Contract verbs whose CLI is a plain `< Verb` command, not a projection at
-      # all — worker verbs and composite reports assembled outside the contract:
-      #   fetch, fetch_all — background intake workers (not request/response)
-      #   boot, doctor     — composite reports
-      NON_PROJECTED_CLI = %i[fetch fetch_all boot doctor].freeze
+      # all — composite reports assembled outside the contract:
+      #   boot, doctor — composite reports
+      # (fetch/fetch_all were removed in ADR 0079: FetchWorker is now internal,
+      # driven by get's read-through orchestrator and the tend sweep.)
+      NON_PROJECTED_CLI = %i[boot doctor].freeze
 
       # The installer skips generation for either category.
       HAND_AUTHORED_VERBS = (BEHAVIORAL_HATCHES + NON_PROJECTED_CLI).freeze

data/lib/textus/dispatcher.rb

@@ -7,14 +7,11 @@ module Textus
       # Write
       put: Textus::Write::Put,
       propose: Textus::Write::Propose,
-      delete: Textus::Write::Delete,
-      mv: Textus::Write::Mv,
+      key_delete: Textus::Write::KeyDelete,
+      key_mv: Textus::Write::KeyMv,
       accept: Textus::Write::Accept,
       reject: Textus::Write::Reject,
       build: Textus::Write::Build,
-      fetch: Textus::Write::FetchWorker,
-      fetch_all: Textus::Write::FetchAll,
-      retain: Textus::Write::RetentionSweep,
 
       # Read
       get: Textus::Read::Get,
@@ -24,7 +21,6 @@ module Textus
       blame: Textus::Read::Blame,
       audit: Textus::Read::Audit,
       freshness: Textus::Read::Freshness,
-      stale: Textus::Read::Stale,
       deps: Textus::Read::Deps,
       rdeps: Textus::Read::Rdeps,
       pulse: Textus::Read::Pulse,
@@ -35,14 +31,13 @@ module Textus
       validate_all: Textus::Read::ValidateAll,
       doctor: Textus::Read::Doctor,
       boot: Textus::Read::Boot,
-      retainable: Textus::Read::Retainable,
       capabilities: Textus::Read::Capabilities,
 
       # Maintenance
-      migrate: Textus::Maintenance::Migrate,
       zone_mv: Textus::Maintenance::ZoneMv,
       key_mv_prefix: Textus::Maintenance::KeyMvPrefix,
       key_delete_prefix: Textus::Maintenance::KeyDeletePrefix,
+      tend: Textus::Maintenance::Tend,
       rule_lint: Textus::Maintenance::RuleLint,
     }.freeze
 

data/lib/textus/doctor/check/generator_drift.rb

@@ -0,0 +1,28 @@
+module Textus
+  module Doctor
+    class Check
+      # ADR 0079: generator/build drift — a derived/external entry whose sources
+      # changed since its generated.at. Dependency-based (not age-based), so it
+      # stays OUT of the lifecycle/freshness unification and lives here as a
+      # health signal. This is the surviving home for what the removed `stale`
+      # verb reported.
+      class GeneratorDrift < Check
+        def call
+          gen = Textus::Domain::Staleness::GeneratorCheck.new(
+            manifest: manifest,
+            file_stat: Textus::Ports::Storage::FileStat.new,
+          )
+          manifest.data.entries.flat_map { |m| gen.rows_for(m) }.map do |row|
+            {
+              "code" => "generator_drift",
+              "level" => "warning",
+              "subject" => row["key"],
+              "message" => row["reason"],
+              "fix" => "rebuild the entry: `textus build`",
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/textus/doctor/check/lifecycle_action_invalid.rb

@@ -0,0 +1,39 @@
+module Textus
+  module Doctor
+    class Check
+      # ADR 0079: refresh is valid only for intake entries; drop/archive are
+      # invalid for intake entries (they would re-fetch, not prune).
+      class LifecycleActionInvalid < Check
+        def call
+          manifest.data.entries.filter_map do |mentry|
+            policy = manifest.rules.for(mentry.key).lifecycle
+            next if policy.nil?
+
+            intake = mentry.is_a?(Textus::Manifest::Entry::Intake)
+            bad = (policy.on_expire == :refresh && !intake) || (policy.destructive? && intake)
+            next unless bad
+
+            issue_for(mentry, policy, intake)
+          end
+        end
+
+        private
+
+        def issue_for(mentry, policy, intake)
+          {
+            "code" => "lifecycle.action_invalid",
+            "level" => "error",
+            "subject" => mentry.key,
+            "message" => "on_expire: #{policy.on_expire} is not valid for a " \
+                         "#{intake ? "intake" : "stored"} entry",
+            "fix" => if intake
+                       "use on_expire: refresh|warn for intake entries"
+                     else
+                       "use on_expire: drop|archive|warn for stored entries"
+                     end,
+          }
+        end
+      end
+    end
+  end
+end

data/lib/textus/doctor/check/rule_ambiguity.rb

@@ -6,7 +6,7 @@ module Textus
       # guard). Ties are non-deterministic in the parser's pick step, so
       # they're a configuration smell — surface them.
       class RuleAmbiguity < Check
-        SLOTS = %i[fetch handler_allowlist guard].freeze
+        SLOTS = %i[lifecycle handler_allowlist guard].freeze
 
         def call
           out = []

data/lib/textus/doctor.rb

@@ -27,6 +27,8 @@ module Textus
       Check::OrphanedPublishTargets,
       Check::PublishTreeIndexOverlap,
       Check::ProposalTargets,
+      Check::LifecycleActionInvalid,
+      Check::GeneratorDrift,
     ].freeze
 
     ALL_CHECKS = CHECKS.map(&:name_key).freeze