@arnilo/prism 0.8.0 → 0.10.0

package/docs/hooks.md

@@ -0,0 +1,282 @@
+# Hooks
+
+## What it does
+
+Hooks are the seams where host- or package-owned code reacts to a run. Prism splits them by what the
+code is allowed to do, so a hook never gains authority it was not granted:
+
+| Family | Seam | May decide | Owning page |
+| --- | --- | --- | --- |
+| Middleware hooks | Transform a payload at a named boundary: `session_start`, `session_shutdown`, `beforeProviderTurn`, `provider_request`, `input_assembly`, `prompt_build`, `context`, `tool_call`, `tool_result`, `retry`, `compaction_request`, `compaction` | Returns the payload; cannot end the run | [Middleware hooks](middleware-hooks.md) |
+| Guardrails | `input`, `output`, `tool_input`, `tool_output` stages | `allow` / `block` / `tripwire` / `interrupt` — the only seams that can reject | [Guardrails](guardrails.md) |
+| Instruction injectors | Prompt and context injection on the first turn, every turn, or on matching input | Returns `instructions` and `contextBlocks`; cannot mutate the provider request | [Instruction injection](instruction-injection.md) |
+| Stop hooks | A natural loop end, after the model produced an answer | `continue` (bounded) or `stop` | This page |
+| Extension bus | Every emitted `AgentEvent`, optionally bridged read-only | Observes only | [Extensions](extensions.md), [Agent events](agent-events.md) |
+
+This page owns stop hooks and the map from Claude Code / Codex hook events onto Prism seams.
+
+APIs:
+
+- `AgentConfig.stopHooks` / `RunOptions.stopHooks`
+- `StopHook`, `StopHookContext`, `StopHookDecision`
+- `RunLimits.maxStopContinuations`
+- `ExtensionAPI.registerStopHook()` and `activateKernel().stopHooks`
+- `session_start` / `session_shutdown` middleware and `session.close()`
+- `compaction_request` / `compaction` middleware
+- `forwardAgentEvents()` for hosts that already listen on the extension bus
+- `@arnilo/prism-hooks`: `parseHooksConfig()` / `createHooksExtension()` for a declarative `hooks.json`
+
+## When to use it
+
+Use stop hooks for end-of-run policy: nudge the model to address deferred items, verify a checklist
+before finishing, or ask for a final answer shape. Stop hooks run *after* the loop finished naturally,
+when the model produced its answer.
+
+Do not use them as middleware (payload transformation), as guardrails (policy denials), or as turn
+control. `RunOptions.turnPolicy.stop` and the loop ceilings end a run *before* the next provider
+request — see [Agent loops](agent-loops.md).
+
+## Inputs / request
+
+```ts
+interface StopHookContext {
+  readonly sessionId: string;
+  readonly runId: string;
+  /** Provider turns assembled in this run (resumption continues the run's counter). */
+  readonly turn: number;
+  /** Read-only live transcript at loop end. */
+  readonly history: readonly Message[];
+  readonly metadata: Readonly<Record<string, unknown>>;
+  readonly signal: AbortSignal;
+  /** True on every invocation after the first continuation in this run. */
+  readonly stopHookActive: boolean;
+}
+
+type StopHookDecision =
+  | { readonly action: "stop" }
+  | { readonly action: "continue"; readonly reason: string; readonly steer?: string | Message };
+
+interface StopHook {
+  readonly name: string;
+  decide(context: StopHookContext): StopHookDecision | Promise<StopHookDecision>;
+}
+```
+
+Configuration: `AgentConfig.stopHooks` is the agent default; `RunOptions.stopHooks` appends to it for
+one run (agent hooks first). Hooks run serially in order, the first `continue` wins, and every hook
+is consulted before the run settles. `RunLimits.maxStopContinuations` caps continuations — default
+3, `0` observes hooks but never continues, `null` disables the cap — and a run overlay may only
+narrow the agent value (resolution takes the minimum across layers).
+
+## Outputs / response / events
+
+- `continue` queues `reason` (and `steer` after it) as steered input. The next turn sees them in
+  history; input guardrails re-check them exactly like `session.steer()`, so a `block`/`tripwire`
+  decision drops the message (emitting `steer_rejected`) while the continuation still runs, and an
+  `interrupt` decision fails the run.
+- The continuation turn is a normal provider turn: it charges `maxTurns`/token limits, emits
+  `turn_started`/`turn_finished`, and its output joins the transcript.
+- Exceeding the cap ends the run cleanly with `AgentRunResult.stopReason: "hook_limit"`, riding
+  `agent_finished.finishReason` and the finish `RunRecord`; no `error` is set. With
+  `runState: { checkpointPolicy: "every-turn" }` the checkpoint keeps its frontier and
+  `resumeAgentRun(..., { decision: "continue" })` resumes it.
+- A throwing or malformed hook fails the run closed with `ERR_PRISM_STOP_HOOK`. Hooks never run
+  after a loop ceiling (`turn_limit`/`token_limit`/`refusal`), a `turnPolicy` stop (`host_policy`),
+  or a `generate-validate-revise` artifact failure.
+
+## Request/response example
+
+```text
+turn 1: provider answers "draft"
+stop hook: { action: "continue", reason: "address the deferred items" }
+turn 2: provider sees "address the deferred items" in history and answers again
+stop hook: ctx.stopHookActive === true → { action: "stop" }
+result: natural end (no stopReason)
+```
+
+## Implementation example
+
+```ts
+import { createAgent } from "@arnilo/prism";
+
+const agent = createAgent({
+  model: { provider: "mock", model: "demo" },
+  provider,
+  stopHooks: [
+    {
+      name: "checklist",
+      decide: (ctx) =>
+        ctx.stopHookActive
+          ? { action: "stop" }
+          : { action: "continue", reason: "Verify the checklist before finishing." },
+    },
+  ],
+  limits: { maxStopContinuations: 3 },
+});
+
+const result = await agent.createSession().run("Write the report");
+```
+
+## Session lifecycle and boundary hooks
+
+The session and compaction boundaries are middleware, dispatched once each by the agent/session
+runtime (never per turn):
+
+| Hook | Fires | Payload |
+| --- | --- | --- |
+| `session_start` | First run start of a session — after `agent_started`/`agent_resumed`, before the first provider turn. A session rebuilt from a durable checkpoint is a new runtime session, so it opens again. | `{ sessionId, runId }` |
+| `session_shutdown` | `await session.close()`, before every subscriber is closed. Idempotent. | `{ sessionId }` |
+| `compaction_request` | Before a compaction strategy runs — `session.compact()` and auto-compaction both route through it, ordinary turns do not. The payload is the strategy's input, and the return value is what it compacts. | `CompactionContext` (`sessionId`, `entries`, `keepRecentEntries`, `trigger`, `secrets`, `metadata`, `signal`) |
+| `compaction` | After the strategy returns, with the final compacted result. | `{ context, result }` |
+
+They are middleware, not stop hooks: they observe a boundary and must return the payload. A throw
+follows the registry's `errorPolicy` — an `extension_error` event with the run continuing (default),
+or a rejection from `run()`/`close()` with `errorPolicy: "throw"`. Hosts register them through
+`api.use("session_start", ...)`, `api.use("session_shutdown", ...)`, `api.use("compaction_request", ...)`,
+or `api.use("compaction", ...)` and pass the registry as `AgentConfig.middleware`; without it none of
+them fire. `compaction_request` cannot skip compaction (an empty entry set is the strategy's own
+error) and the post-strategy `compaction` hook still sees the result — see
+[Middleware hooks](middleware-hooks.md). Use [Agent events](agent-events.md) or
+`forwardAgentEvents(source, kernel.events)` for finer-grained per-turn observation — the bridge maps
+`agent_started` → `before_agent_start`, `turn_started`/`turn_finished` → `turn`, and
+`tool_execution_started`/`tool_execution_finished` → `tool_call`/`tool_result` as read-only
+notifications.
+
+## Claude Code and Codex event map
+
+Every Claude Code / Codex hook event maps onto one of the seams above — or is a documented non-goal:
+
+| Claude Code / Codex event | Prism surface | `hooks.json` adapter | Notes |
+| --- | --- | --- | --- |
+| `SessionStart` | `session_start` middleware (+ instruction-injector queue) | compiled | `additionalContext` lands in the next assembly. Claude/Codex `source` values `startup` and `resume` both select — the seam cannot tell a fresh session from a resumed one — while `clear` and `compact` do not: compaction never reopens the session here (use the `compaction_request`/`compaction` seams). |
+| `SessionEnd` | `session_shutdown` middleware | not compiled | Teardown cannot inject context or block a run, so cleanup belongs in the middleware or `LoadedExtension.dispose()`. A `hooks.json` file that needs it uses `api.use("session_shutdown", ...)` alongside the adapter. |
+| `UserPromptSubmit` | `input` guardrail (deny) + injector queue | compiled | Exit `2`, `decision: "block"`, or `continue: false` rejects the run with `GuardrailError`; `additionalContext` is injected. |
+| `PreToolUse` | `tool_call` middleware (`updatedInput`, `additionalContext`) + `tool_input` guardrail (deny) | compiled | `permissionDecision: "deny"` and exit `2` return a blocked `ToolResult`; `updatedInput` rewrites the arguments before dispatch; `additionalContext` is queued for the next assembly and dropped when the call is denied. Approvals are host policy — see `PermissionRequest`. |
+| `PermissionRequest` | non-goal — host permission policy | not compiled | A hook that can grant a permission is a privilege-escalation vector: config-authored or third-party code would gain approval authority over the host's tools. Prism keeps grants in host-owned policy — `ExecutionPolicy`, `requiresApproval`, `interruptBeforeTool` — and guardrail packs' [`ask` rules](guardrails.md#asking-for-approval-ask-rules), which suspend a durable run for an explicit host decision. Hook seams (and `@arnilo/prism-hooks`) only ever deny. |
+| `PostToolUse` | `tool_result` middleware (`additionalContext`, rewrite) + `tool_output` guardrail (deny) | compiled | `decision: "block"` and exit `2` replace the result with a refusal-shaped `ToolResult`; `additionalContext` is queued for the next assembly. |
+| `Stop` | stop hooks (`AgentConfig.stopHooks` / `RunOptions.stopHooks`) | compiled | Both harnesses continue with `decision: "block"` + `reason`, or with `additionalContext` (exit `2` also continues, using stderr as the reason): that becomes `{ action: "continue" }`, with the reason as the continuation prompt and `ctx.stopHookActive` true on re-entry. The common-field `continue: false` is the *stop* signal and wins over continuation decisions in the same event. `RunLimits.maxStopContinuations` (default 3) caps how often the loop re-enters before a clean `hook_limit` stop. |
+| `PreCompact` | `compaction_request` middleware | not compiled | Claude/Codex `PreCompact` is decision-only (block the compaction, no replaceable input). Prism's seam adds input rewrite: the returned `CompactionContext` is exactly what the strategy compacts. |
+| `PostCompact` | `compaction` middleware + `compaction_finished` event | not compiled | Observes or rewrites the compacted result after the strategy returned. |
+| `Interrupt` (Codex) | non-goal — hooks run at boundaries | not compiled | Hooks run before and after a turn, not inside one, so they cannot interrupt an in-flight turn. Interruption is the host's abort path: the run's `AbortSignal`, `session.close()`, or a guardrail `interrupt` at the input stage of a durable run (which suspends for approval). |
+| `SubagentStart` / `SubagentStop` | non-goal — no subagent primitive | not compiled | Prism has no implicit child-agent lifecycle: delegation is a host-authored tool or a separate agent/run, so the parent loop is unaffected. Observe child runs with `agent_started`/`agent_finished` and `forwardAgentEvents()`. |
+
+Claude Code's remaining harness-specific events (`Setup`, `Notification`, `StopFailure`,
+`PostToolUseFailure`, `PostToolBatch`, `TeammateIdle`, `TaskCreated`, `TaskCompleted`,
+`Elicitation`, `ElicitationResult`, `PreToolBatch`) have no Prism surface: they belong to a
+terminal/CI harness (init, notifications, multi-teammate gating, MCP elicitation) rather than to the
+agent loop. `StopFailure` and `PostToolUseFailure` are covered as outcomes — `agent_finished.error`
+and a failed `ToolResult` — and the rest are observed through `AgentEvent`s.
+
+## `hooks.json` adapter (`@arnilo/prism-hooks`)
+
+Hosts that already keep a Claude Code or Codex hooks file do not have to rewrite it as SDK
+callbacks. The opt-in capability package `@arnilo/prism-hooks` parses the file and compiles each
+event onto the seams above — no Prism internals, `@arnilo/prism` as its only peer, and no new
+runtime dependency. It compiles the five events marked *compiled* in the map.
+
+```bash
+npm install @arnilo/prism @arnilo/prism-hooks
+```
+
+```ts
+import { activateKernel, createAgent, createExtensionKernel } from "@arnilo/prism";
+import { createHooksExtension, hookCommandHash, parseHooksConfig } from "@arnilo/prism-hooks";
+
+const config = parseHooksConfig(await readFile("hooks.json", "utf8"));
+const audit = { type: "command", command: "node audit-tool.js" } as const;
+const hooks = createHooksExtension(config, { trusted: { [audit.command]: hookCommandHash(audit) } });
+
+const kernel = createExtensionKernel();
+await kernel.load([hooks]);
+const activated = activateKernel(kernel);
+const agent = createAgent({
+  model,
+  provider,
+  guardrails: hooks.guardrails, // required for UserPromptSubmit / PreToolUse / PostToolUse
+  instructionInjectors: activated.instructionInjectors,
+  stopHooks: activated.stopHooks,
+  middleware: activated.middleware,
+});
+```
+
+Schema and semantics:
+
+- Both authoring shapes parse: the flat Claude map (`{ "PreToolUse": [{ "matcher": "Bash", "hooks": [...] }] }`) and Codex's nested `{ "hooks": { "PreToolUse": [...] } }` with bare handler objects. An unknown event name, unknown handler `type`, empty command, non-positive `timeout`, or `"shell": true` throws `ERR_PRISM_HOOKS_CONFIG` — never a silent no-op.
+- Handlers are `{ type: "command", command, args?, timeout?, async?, asyncRewake?, statusMessage? }` or `{ type: "mcp_tool", server, tool, input? }`. HTTP hooks are not implemented.
+- Matchers follow Claude's hybrid rule: letters/digits/`_`/`-`/space/`,`/`|` select literally (with `|`/`,` alternatives), anything else is an unanchored regex, and no `$1` capture substitution exists. `UserPromptSubmit` and `Stop` have no matcher subject, so a matcher there warns and is ignored; `SessionStart` cannot distinguish a fresh session from a checkpoint resume at that seam, so `startup` and `resume` both select.
+- Exit codes are Claude/Codex's: `0` success (JSON stdout parsed), `2` block with stderr as the reason, any other code a non-blocking error reported as a `hooks:warning` extension event. There is no exit code `64`.
+- The common-field `continue: false` is read as the stop signal: on `Stop` it returns `{ action: "stop" }` and wins over continuation decisions from the same event (Codex precedence); on a tool or prompt event it reads as a refusal, the conservative reading, since Claude halts processing there and Codex marks the field unsupported.
+- `timeout` is in **seconds** (default 600). Expiry warns and never blocks: pre-events allow with a warning, additive events simply drop their context.
+- `additionalContextLimit` is a token threshold measured at ~4 code units per token — Codex's unit (default 2500, `0` = unlimited). It is read per handler, and a handler without the field falls back to the config-level value beside `hooks`. Claude's fixed 10,000-character `persistHookOutput` is the same spill behavior at a different unit. Over the limit that handler's text is written to `<temp_dir>/hook_outputs/` and a pointer line is injected instead — the only filesystem write this package performs.
+- `async: true` handlers run detached (`asyncRewake` is accepted for config parity). Their context lands at the next assembly, never on the event path.
+- Trust is a hash allowlist: `options.trusted` maps a command string to a digest from `hookCommandHash()` (default SHA-256 over the tokenized argv, so appending an argument invalidates the entry). A missing or mismatched entry skips the handler with a `hooks:warning`. `trusted: "all"` is the documented escape hatch and logs loudly. `mcp_tool` handlers use the host-supplied client and are trusted by construction.
+- Commands are tokenized locally (quotes and escapes only — no expansion, pipes, or substitutions) and spawned with an argv array; there is no shell. Guardrails and stop hooks stay inert until the host activates them, like every other kernel contribution.
+
+## Migrating from Claude Code or Codex configs
+
+1. Keep the file where it is and parse it: `parseHooksConfig(text)` accepts both the flat
+   `.claude/settings.json` map and Codex's `{ "hooks": { ... } }` shape, including Claude's extra
+   settings keys next to `hooks`.
+2. Drop the events the adapter does not compile — an unknown event name is a loud error, not a
+   silent skip, so filter them explicitly instead of stripping the file by hand:
+
+   ```ts
+   // SessionEnd, PermissionRequest, Interrupt, PreCompact/PostCompact, SubagentStart/Stop are not compiled.
+   const { SessionEnd, PermissionRequest, Interrupt, PreCompact, PostCompact, SubagentStart, SubagentStop, ...compiled } = raw;
+   const config = parseHooksConfig(compiled);
+   ```
+
+   For the non-goals, use the Prism surface named in the map (host permission policy, the
+   `session_shutdown` / `compaction_request` / `compaction` middleware) rather than a handler file.
+3. Decide trust before the first run: `trusted: { [command]: hookCommandHash(handler) }` for each
+   command you have reviewed, or `"all"` only for a config you own end to end. Handlers run
+   out-of-process but with your privileges, so the allowlist is the boundary.
+4. Activate the two halves together: `guardrails: hooks.guardrails` on the agent, plus
+   `middleware` / `instructionInjectors` / `stopHooks` from `activateKernel()` — activating one
+   without the other logs a `hooks:warning` and the blocking decisions do not apply.
+5. Re-check the differences: `timeout` is seconds (default 600), only exit code `2` blocks,
+   `decision: "block"` is what continues a `Stop` (never `continue: false`, which stops), no `$1`
+   capture substitution in matchers, `additionalContext` over `additionalContextLimit` spills to a
+   file pointer, and matchers on `UserPromptSubmit`/`Stop` are ignored with a warning.
+
+## Extension and configuration notes
+
+- `api.registerStopHook({ name, decide })` contributes an inert hook to `kernel.registries.stopHooks`;
+  pass `activateKernel(kernel).stopHooks` into `createAgent({ stopHooks })`. Disposing the loaded
+  extension unwinds the registration.
+- Registrations are keyed by `name` (last write wins, like other contribution registries).
+- `RunOptions.stopHooks` cannot replace agent hooks; it appends. `maxStopContinuations` narrows only.
+- No dedicated `AgentEvent` is added: observe decisions through your own callback and the run outcome.
+
+## Security and performance notes
+
+- In-process seams — middleware, guardrails, injectors, and stop hooks — are host code with the
+  host's full privileges. Registering one is trusting it; Prism validates payload shapes, bounds
+  what reaches the provider, and redacts what reaches events, but it cannot sandbox a callback.
+- Hooks never receive credentials and cannot mutate history: stop hooks get metadata plus the
+  read-only transcript, and continuation text enters through the steer queue, so the 8-message /
+  64 KiB caps bound it and the host redactor applies before it reaches the provider.
+- No hook seam grants authority, by design. Permission and approval decisions stay with host policy
+  (`ExecutionPolicy`, `requiresApproval`, `interruptBeforeTool`, guardrail-pack `ask` rules), so a
+  hook can only deny or add context — the `PermissionRequest` non-goal above.
+- Out-of-process hooks (`@arnilo/prism-hooks`) are the opposite trade: they run in a separate
+  process, but with your user's privileges and an inherited environment, so the hash allowlist plus
+  the per-handler `timeout` are the trust boundary. `mcp_tool` handlers add the MCP client's own
+  transport and auth.
+- Hooks run serially, awaited, once per natural loop end. Each continuation costs full provider
+  turns until the model stops naturally; size `maxStopContinuations` accordingly (`0` = observe
+  only). With no stop hooks configured, the wrapper is skipped entirely. `session_start` /
+  `session_shutdown` fire once per session, `compaction_request` / `compaction` once per compaction,
+  and tool seams once per tool call in their stage.
+
+## Related APIs
+
+- [Agent loops](agent-loops.md): loop strategies, turn policy, and `finishReason` ceilings.
+- [Guardrails](guardrails.md): input/output/tool decisions, steer re-checking, and the `ask` rules that own approvals.
+- [Middleware hooks](middleware-hooks.md): payload transforms at named boundaries, including the session and compaction seams.
+- [Instruction injection](instruction-injection.md): where `additionalContext` from session and prompt hooks lands.
+- [Extensions](extensions.md): `ExtensionAPI.registerStopHook()`, the contribution registries, and the `forwardAgentEvents()` bridge.
+- [Runs and usage ledger](runs-and-usage.md): `maxStopContinuations` and clean stop reasons.
+- [Agent/session runtime](agent-session-runtime.md): `session.close()`, steer queue semantics, and durable resume.
+- [Agent events](agent-events.md): the events the extension bus observes, including `hook_limit`.
+- [Public contracts](public-contracts.md): `RunOptions`, `RunLimits`, and `AgentConfig` surfaces.

package/docs/index.md

@@ -2,14 +2,30 @@
 
 Prism is a TypeScript/Node.js agent harness. Hosts own providers, tools, credentials, storage, and behavior; Prism supplies contracts, registries, events, and replaceable runtime primitives.
 
-## Current line (0.8.0)
+## Current line (0.10.0)
+
+- **Attention budget axes**: `attentionCompiler.trigger` accepts one axis, a predicate, or an any-of array (`input_ratio`, `run_input_ratio`, `token_floor`), and `durable: true` keeps the fold ledger and sticky frontier in the checkpoint across a resume.
+- **Turn traces and exhaustion attribution**: `provider_turn_finished` carries a closed `stopReason`, a `budgets` snapshot, the effective tool menu (`count` / `idsHash`), and provider cache counts; `agent_finished` carries the run outcome, and the execution timeline adds per-turn stop reasons plus `exhaustion`.
+- **Cache-stable disclosure**: late-expanding context (skill bodies, deferred schemas, loaded references) lands at the request tail instead of rewriting the prefix, cache read/write telemetry rides usage records, and `runPrefixStabilityConformance` asserts a shared-prefix floor against a host's own assembly.
+- **Per-turn tool narrowing**: a host callback receives the turn and the run grant and returns the effective subset; out-of-grant names are dropped and reported as `tool_narrowing_clamped`.
+- **Usage estimation and the context meter**: labeled token estimates for providers that report no usage (reported usage always wins, and `usageEstimation: "off"` restores zero-for-no-usage), plus `session.contextMeter()` for cap and spend ratios.
+- **Guardrail packs**: four built-in restrictive packs (`coding-standard`, `destructive-commands`, `validation-respect`, `secrets-hygiene`) compiled onto existing tool stages, each with a trajectory scorer.
+- **Background child agents**: session-lifetime children with milestone or streamed reports, narrowed budget shares, and rate-coalesced child events.
+- **Checkpoint sidecar metadata**: a redacted ≤4 KiB map attached to every checkpoint record without charging `maxStateBytes`, plus restore hooks that revert external layers before a resume claims the run.
+- **Bounded session search**: `store.searchSessions(query)` over workspace/time/provider/label/kind/ownership filters, indexed at append time (SQLite FTS5, Postgres `tsvector`) with a bounded linear matcher for JSONL and memory stores.
+- **Deterministic turns**: the `beforeProviderTurn` middleware hook answers a turn from host data with no provider request, recorded as `deterministic` on the timeline and in usage.
+- **Shared work scopes**: explicitly granted observational-memory scopes shared across sessions, deny-by-default, audited, and revocable at the next read; session-private scopes stay the default.
+- **Retrieval revocation and local reranking**: deletion and revocation propagate through derived vector/wiki artifacts under bounded walks, and an in-process cross-encoder reranker ships with no declared inference dependency.
+- **Live-stream terminal semantics**: one `isTerminalAgentEventType` predicate (`agent_finished` / `agent_denied` / `error`) shared by every source, so a limit death delivers `run_limit_exceeded` → `budget_exhausted` → `error` before a stream or replay ends.
+- **12 publishable packages** at current **0.10.0** lockstep, with the migration guide reachable from the release section below — inventory below.
+
+### Carried from the 0.8.0 line
 
 - **Messaging channels**: `@arnilo/prism-channels` transport-neutral runtime with deny-by-default authorization, owned bindings, one-use durable approvals, official Telegram (private DMs, opt-in granted groups/topics, drafts, bounded media/voice, opt-in notices) and experimental pinned signal-cli Signal.
 - **Connected apps**: identity-bound MCP server sessions admit host-selected transports and register prefixed tools; Google Workspace and Microsoft 365 HTTP adapters live under `@arnilo/prism-work/connectors`.
 - **Work family**: `@arnilo/prism-work` replaces `@arnilo/prism-office` — connectors, documents, sheets, diagrams, document-reader, sandbox, and vendored office skills. No pre-1.0 shim.
 - **Durable long runs**: turn-boundary checkpoints with host-only `decision: "continue"`, turn-stop policy, frozen run-bundle snapshots, claim-grounding guardrail, and typed provider failure classes.
 - **Honesty surfaces**: Postgres release evidence is this-commit, channel lease release stays held until the store acknowledges, and observational-memory workers ignore non-tool events on purpose.
-- **11 publishable packages** at current **0.8.0** lockstep, with the migration guide reachable from the release section below — inventory below.
 
 ### Carried from the 0.7.0 line
 
@@ -60,6 +76,7 @@ Prism is a TypeScript/Node.js agent harness. Hosts own providers, tools, credent
 - [Durable runs](durable-runs.md): turn-boundary `checkpointPolicy: "every-turn"` checkpoints and `decision: "continue"` crash recovery for long runs.
 - [Agent definitions](agent-definitions.md): declarative `AgentDefinition` resolution and `AGENT.md` bundle discovery, fail-closed activation.
 - [Agent loops](agent-loops.md): replaceable loops with `limits.maxToolRounds` budgets and durable revision/restore hooks.
+- [Hooks](hooks.md): the hook model — stop hooks with bounded continuation, session/compaction boundary seams, and the Claude Code / Codex event map plus the `hooks.json` adapter.
 - [Guardrails](guardrails.md): typed fail-closed input/output/tool checks with redacted decision records.
 - [Agent events](agent-events.md): `turn_started`/`tool_call_delta` stream plus durable page/resume sources for reconnect.
 - [Observability](observability.md): OTel GenAI span hierarchy, workflow spans, cockpit aggregations, RAG span tree, bounded trace linkage, exporter isolation.
@@ -79,6 +96,8 @@ Prism is a TypeScript/Node.js agent harness. Hosts own providers, tools, credent
 - [Observational memory compaction subpath](compaction-observational-memory.md): source-backed observations/reflections, an optional work-scope index for the current working set, and exact-id recall; `invalidatedIds` withhold derived injection.
 - [Working and semantic memory](working-and-semantic-memory.md): working-memory store, semantic recall, pgvector path, consent lifecycle, lineage invalidation, parent-child share grants.
 - [Memory fabric](memory-fabric.md): opt-in typed notes (fact/procedure/file/working/episode) with validity windows over the existing vector and working stores.
+- [Scoped memory](scoped-memory.md): workspace-scope guard, gated writes, promotion ladder, decay reads, audit mirror (`@arnilo/prism-memory/scoped`).
+- [Scoped agent memory design concept](scoped-agent-memory.md): workspace-scoped persistent memory — gated writes, promotion ladder, decay-based reads; case study and research basis.
 - [Session stores](session-stores.md): `SessionStore` contract, append options, branches, bounded search — start here for persistence.
 - [Conversations](conversations.md): durable user-scoped threads with versioned metadata and legal-hold-aware deletion.
 - [Work artifacts and review](work-artifacts-and-review.md): artifact attach, revision compare, evidence-bound citations, approve/reject, expiring delivery links.
@@ -213,9 +232,10 @@ Prism is a TypeScript/Node.js agent harness. Hosts own providers, tools, credent
 - [Session store conformance](session-store-conformance.md): assert append/idempotency/conflict/branch invariants for any store.
 - [Run ledger conformance](run-ledger-conformance.md): assert durable run/usage writes and reopen survival.
 - [Compaction conformance](compaction-conformance.md): assert redacted non-empty summaries and abort observation.
+- [Prefix stability conformance](prefix-stability-conformance.md): assert progressive disclosure keeps the provider cache prefix stable.
 - [Tool conformance](tool-conformance.md): assert blocked-reason matrix and success-path dispatch behavior.
 - [Extension conformance](extension-conformance.md): assert inert contributions and redacted setup errors.
-- `examples/`: compile-checked typed examples ([`conversation-durable-replay.ts`](../examples/conversation-durable-replay.ts), [`artifact-review-delivery.ts`](../examples/artifact-review-delivery.ts), [`enterprise-identity.ts`](../examples/enterprise-identity.ts), [`enterprise-policy-audit.ts`](../examples/enterprise-policy-audit.ts), [`enterprise-work-connectors.ts`](../examples/enterprise-work-connectors.ts), [`connected-slack-mcp.ts`](../examples/connected-slack-mcp.ts), [`server-deployment-seams.ts`](../examples/server-deployment-seams.ts), [`neuralwatt-agent-run.ts`](../examples/neuralwatt-agent-run.ts), [`cache-aware-prompt-assembly.ts`](../examples/cache-aware-prompt-assembly.ts), [`ag-ui-server.ts`](../examples/ag-ui-server.ts), [`acp-coding-host.ts`](../examples/acp-coding-host.ts), [`telegram-agent.ts`](../examples/telegram-agent.ts), [`signal-agent.ts`](../examples/signal-agent.ts), [`messaging-agent.ts`](../examples/messaging-agent.ts), and more), plus runnable mock demos.
+- `examples/`: compile-checked typed examples ([`conversation-durable-replay.ts`](../examples/conversation-durable-replay.ts), [`artifact-review-delivery.ts`](../examples/artifact-review-delivery.ts), [`enterprise-identity.ts`](../examples/enterprise-identity.ts), [`enterprise-policy-audit.ts`](../examples/enterprise-policy-audit.ts), [`enterprise-work-connectors.ts`](../examples/enterprise-work-connectors.ts), [`connected-slack-mcp.ts`](../examples/connected-slack-mcp.ts), [`server-deployment-seams.ts`](../examples/server-deployment-seams.ts), [`neuralwatt-agent-run.ts`](../examples/neuralwatt-agent-run.ts), [`cache-aware-prompt-assembly.ts`](../examples/cache-aware-prompt-assembly.ts), [`guardrail-packs.ts`](../examples/guardrail-packs.ts), [`ag-ui-server.ts`](../examples/ag-ui-server.ts), [`acp-coding-host.ts`](../examples/acp-coding-host.ts), [`telegram-agent.ts`](../examples/telegram-agent.ts), [`signal-agent.ts`](../examples/signal-agent.ts), [`messaging-agent.ts`](../examples/messaging-agent.ts), and more), plus runnable mock demos.
 
 ## Third-party integrations
 
@@ -231,6 +251,7 @@ Prism is a TypeScript/Node.js agent harness. Hosts own providers, tools, credent
 ## Release and install
 
 - [Release and install](release-and-install.md): install rules, package graph, and deterministic resumable publication.
+- [Migrate 0.8 → 0.9](migrate-to-0.9.md): the four behavior deltas inside existing surfaces (limit-death stream order, turn-trace metadata, cache-stable disclosure, labeled usage estimates), every new option with its sizing line, and 0.9.0 host migration steps.
 - [Migrate 0.7 → 0.8](migrate-to-0.8.md): work-family import map, messaging channels, connected apps, durable runs, and 0.8.0 host migration steps.
 - [Migrate 0.6 → 0.7](migrate-to-0.7.md): ACP MCP allow-list URL normalization, model router facade fail-closed governance, and 0.7.0 host migration steps.
 - [Migrate 0.5 → 0.6](migrate-to-0.6.md): Node 22 floor, folded 0.5.7 host delta, third-party floors, and upgrade/rollback steps.
@@ -243,19 +264,20 @@ Prism is a TypeScript/Node.js agent harness. Hosts own providers, tools, credent
 The generated inventory below derives from [`scripts/package-truth.json`](../scripts/package-truth.json) — regenerate with `node scripts/package-truth.mjs --emit-docs`, never hand-edit.
 
 <!-- generated:package-truth:inventory begin -->
-**11 publishable manifests** — root `@arnilo/prism` plus 10 workspace packages (4 `prism-*` family packages, 6 capability packages). Generated by `node scripts/package-truth.mjs --emit-docs` — do not hand-edit.
+**12 publishable manifests** — root `@arnilo/prism` plus 11 workspace packages (4 `prism-*` family packages, 7 capability packages). Generated by `node scripts/package-truth.mjs --emit-docs` — do not hand-edit.
 
 | package | version | notes |
 | --- | --- | --- |
-| `@arnilo/prism` | 0.8.0 | core — runtime, CLI/RPC, templates, docs |
-| `@arnilo/prism-channels` | 0.8.0 | family — transport-neutral messaging runtime, durable journal, pairing and one-use approvals; official /telegram (private DMs, opt-in granted groups/topics) and experimental pinned signal-cli /signal |
-| `@arnilo/prism-coding-tools` | 0.8.0 | family — /agent, /security, /openapi, /computer-use-linux, /dev, /caveman, /ponytail, /impeccable subpaths |
-| `@arnilo/prism-core` | 0.8.0 | family — /runtime, /sessions, /governance, /credentials, /enterprise, /validation subpaths |
-| `@arnilo/prism-providers` | 0.8.0 | family — all provider adapters as `/<adapter>` subpaths |
-| `@arnilo/prism-acp-agent` | 0.8.0 | capability — ACP adapter |
-| `@arnilo/prism-ag-ui` | 0.8.0 | capability — AG-UI/A2A/A2UI adapter |
-| `@arnilo/prism-mcp` | 0.8.0 | capability — MCP client/server/OAuth interop |
-| `@arnilo/prism-memory` | 0.8.0 | capability — memory plus /rag, /compaction/*, /fabric, /graft, /wiki subpaths |
-| `@arnilo/prism-web-tools` | 0.8.0 | capability — Brave/Exa/Firecrawl plus peer-gated /browser and /obscura subpaths |
-| `@arnilo/prism-work` | 0.8.0 | capability — /connectors, /documents, /sheets, /diagrams, /document-reader, /sandbox, /skills, /tools subpaths |
+| `@arnilo/prism` | 0.10.0 | core — runtime, CLI/RPC, templates, docs |
+| `@arnilo/prism-channels` | 0.10.0 | family — transport-neutral messaging runtime, durable journal, pairing and one-use approvals; official /telegram (private DMs, opt-in granted groups/topics) and experimental pinned signal-cli /signal |
+| `@arnilo/prism-coding-tools` | 0.10.0 | family — /agent, /security, /openapi, /computer-use-linux, /dev, /caveman, /ponytail, /impeccable subpaths |
+| `@arnilo/prism-core` | 0.10.0 | family — /runtime, /sessions, /governance, /credentials, /enterprise, /validation subpaths |
+| `@arnilo/prism-providers` | 0.10.0 | family — all provider adapters as `/<adapter>` subpaths |
+| `@arnilo/prism-acp-agent` | 0.10.0 | capability — ACP adapter |
+| `@arnilo/prism-ag-ui` | 0.10.0 | capability — AG-UI/A2A/A2UI adapter |
+| `@arnilo/prism-hooks` | 0.10.0 | capability — Claude/Codex-compatible hooks.json adapter compiled onto middleware, guardrail, injector, and stop-hook seams |
+| `@arnilo/prism-mcp` | 0.10.0 | capability — MCP client/server/OAuth interop |
+| `@arnilo/prism-memory` | 0.10.0 | capability — memory plus /rag, /compaction/*, /fabric, /graft, /wiki subpaths |
+| `@arnilo/prism-web-tools` | 0.10.0 | capability — Brave/Exa/Firecrawl plus peer-gated /browser and /obscura subpaths |
+| `@arnilo/prism-work` | 0.10.0 | capability — /connectors, /documents, /sheets, /diagrams, /document-reader, /sandbox, /skills, /tools subpaths |
 <!-- generated:package-truth:inventory end -->

package/docs/input-and-prompt-assembly.md

@@ -62,7 +62,7 @@ Useful exported types:
 - `InputAttachment`: already-loaded text/content blocks (including `audio`, `file`, and `document`) or an explicit URI loaded through a caller-provided `ResourceLoader`.
 - `PromptInstruction`: labeled system instruction text.
 - `DefaultPromptBuilder`: the default `PromptBuilder`; cache-aware by default and legacy-preserving when `inputLayout: "legacy"` is passed in its request.
-- `AssembleProviderInputOptions`: model, input, optional builders, context providers, selected skills, active tools, generic provider options, metadata, signal, and optional `contextBudget` (`maxInputTokens` / `maxInputBytes` / `reportOmissions` / `tokenEstimator`).
+- `AssembleProviderInputOptions`: model, input, optional builders, context providers, selected skills, active tools, generic provider options, metadata, signal, optional session-owned `tailSegments`, and optional `contextBudget` (`maxInputTokens` / `maxInputBytes` / `reportOmissions` / `tokenEstimator`).
 - `applyContextBudget` / `getContextBudgetReport` / `resolveContextBudget`: deterministic eviction + omission report helpers (estimate = UTF-16 code units ÷ 4, or the host's `tokenEstimator`).
 - `PromptTemplateOptions`: missing-variable behavior for `renderPromptTemplate()`.
 
@@ -81,17 +81,17 @@ The builder returns `readonly Message[]`.
 
 The default prompt builder preserves one composition path while honoring layout:
 
-- `cache_aware` (default): leading system messages from input assembly → resolved context blocks → selected/progressively disclosed skills → text tool declarations for text-only/unknown models → remaining input-builder messages (attachments/resources → summaries → history → tool results → current input).
+- `cache_aware` (default): leading system messages from input assembly → resolved context blocks → selected/progressively disclosed skill catalogs → text tool declarations for text-only/unknown models → remaining input-builder messages (attachments/resources → summaries → history → tool results → current input) → optional session tail.
 - `legacy`: context blocks → skills → text tool declarations → all input-builder messages (instructions → summaries → history → current input → attachments/resources → tool results).
 
-In cache-aware mode, leading system instructions form the stable boundary before dynamic context and skills. The provider `tools` field remains the host-supplied schema list; text declarations are only a fallback for models without declared tool support. Changing only current input changes the final suffix; changing context, loaded skills, resources, summaries, history, attachments, or tools changes that boundary or a later suffix. A stable prefix persists only while those stable inputs stay byte-stable; provider cache hits remain best-effort.
+In cache-aware mode, leading system instructions form the stable boundary before dynamic context and skill catalogs. The provider `tools` field remains the host-supplied schema list; text declarations are only a fallback for models without declared tool support. `RuntimeAgentSession` supplies a run-owned `tailSegments` map: URI resources and loaded skill bodies move to the final tail, while their catalog rows remain in place. First insertion fixes tail order (`resource:<uri>` / `skill:<name>`); re-derivation of an id replaces only that segment's bytes, making changed source content an explicit cache-invalidation boundary. Context-budget eviction can omit a tail segment. Custom prompt builders receive the tail in `messages` plus `tailSkillBodies`; a builder that independently renders `skills` must honor that flag. A stable prefix persists only while those stable inputs stay byte-stable; provider cache hits remain best-effort.
 - History is prepended before current input.
 - Instructions and summaries are system messages; compacted branch summaries from `rebuildSessionContext()` use the same path.
 - Text attachments and explicit text resources are user messages; inline `audio`/`file`/`document` blocks pass through unchanged on attachments with `content`.
 - Tool results are tool messages containing `tool_result` content; the agent/session runtime uses this to feed dispatched tool results into the next provider turn, placing the assistant `tool_call` and the matching role `tool` `tool_result` before any final assistant content. Cache-aware layout keeps tool results before the current user suffix so it does not split tool transcripts. A result with no `value`, no `type:text` content, and no error carries the constant `EMPTY_TOOL_RESULT_TEXT` (`"(tool completed with no output)"`) as its `result`, so no provider route serializes an empty or absent tool payload.
 - Middleware runs only when `middleware` is supplied in the context.
 - `assembleProviderInput()` returns a `ProviderRequest` with the caller's model/tools/provider options/metadata/signal and composed messages/context. It stamps missing `sessionId`/`cacheKey` via `applyDefaultProviderRequestOptions` when `sessionId` is passed (agent sessions always pass `session.id`). It also calls `assertMessagesSupportModelCapabilities()` so unsupported `audio`/`file`/`document`/`image` blocks fail with `UnsupportedModalityError` when the model declares `capabilities.input`.
-- Optional `contextBudget` (at least one of `maxInputTokens` / `maxInputBytes`) runs after default message groups are built and before final flatten. `tokenEstimator` replaces the built-in ÷4 heuristic for **eviction accounting only** — it never reaches billing, provider usage, or the wire, byte caps (`maxInputBytes`) stay estimator-independent and are always enforced, and an estimator that returns a non-finite or negative count (or is not a function) fails the assembly closed with `TypeError` instead of making eviction decisions unsound. Eviction drops droppable sections first (toolResults → history → summaries → context → skills → attachments; layout-aware). Within `history`, oldest messages drop first. Protected instructions + current user `input` (+ tools catalog) fail closed with `ContextBudgetError` if they alone exceed the budget. When `reportOmissions: true`, attach `ProviderRequest.metadata[CONTEXT_BUDGET_REPORT_METADATA_KEY]` and read via `getContextBudgetReport(request)` (kinds/ids/sizes only — no secrets). Raw session store entries are never deleted.
+- Optional `contextBudget` (at least one of `maxInputTokens` / `maxInputBytes`) runs after default message groups are built and before final flatten. Sessions forward `AgentConfig.contextBudget` here, so an agent-level budget gets the same semantics. `tokenEstimator` replaces the built-in ÷4 heuristic for **eviction accounting** — and, with `usageEstimation: "fallback"`, also feeds the missing-usage estimate ([Runs and usage](runs-and-usage.md#automatic-fallback-agentconfigusageestimation)); it never reaches billing, provider usage reports, or the wire, byte caps (`maxInputBytes`) stay estimator-independent and are always enforced, and an estimator that returns a non-finite or negative count (or is not a function) fails the assembly closed with `TypeError` instead of making eviction decisions unsound. Eviction drops droppable sections first (toolResults → history → summaries → context → skills → attachments; layout-aware). Within `history`, oldest messages drop first. Protected instructions + current user `input` (+ tools catalog) fail closed with `ContextBudgetError` if they alone exceed the budget. When `reportOmissions: true`, attach `ProviderRequest.metadata[CONTEXT_BUDGET_REPORT_METADATA_KEY]` and read via `getContextBudgetReport(request)` (kinds/ids/sizes only — no secrets). Raw session store entries are never deleted.
 - `renderPromptTemplate()` replaces top-level `{{name}}` variables with caller-supplied JSON-compatible values. Strings are inserted directly; numbers, booleans, `null`, arrays, and objects are stringified deterministically with sorted object keys. Missing variables throw by default or stay unchanged with `{ missing: "preserve" }`.
 
 ## Request/response example

package/docs/instruction-injection.md

@@ -181,3 +181,4 @@ RPC: `prompt`/`followUp` params accept an optional `instructionInjectors: readon
 - [Extensions](extensions.md): `registerInstructionInjector` in the contribution-kinds list.
 - [CLI and RPC](cli-rpc.md): `--instruction`/`--injector-file` flags and the RPC `instructionInjectors` field.
 - [Credentials and redaction](credentials-and-redaction.md): `createSecretRedactor`, `redactProviderRequest`, `redactAgentEvent`.
+- [Hooks](hooks.md): the Claude Code / Codex event map, where hook `additionalContext` is queued for the next assembly.

package/docs/knowledge-sync.md

@@ -29,6 +29,10 @@ Use it when a host must keep a RAG corpus aligned with an enterprise file source
 
 No tools, no watch-channel authorization, no events.
 
+## Delete contract
+
+A connector `delete` change calls `deleteSource()` for that source only: the connector's own chunk rows and ingestion status go away, under exact tenant/resource/corpus scope. Connector payloads are never authorization, so sync cannot reach beyond the corpus it owns — derived artifacts (summaries, observational-memory entries, compiled wiki pages, host projections) survive sync deletes by design. Removing those is a separate privileged pass through `createDeletionPropagator().propagate(sourceId)` (see [RAG deletion propagation](rag.md#deletion-propagation)), driven by the host, not by the connector.
+
 ## Request/response example
 
 ```json

package/docs/live-testing.md

@@ -87,8 +87,10 @@ Set only the rows you want to run; everything else skips. Least-privilege scope
 | `providers/ollama` | active | `PRISM_LIVE_PROVIDER_TESTS` + `OLLAMA_BASE_URL` | `PRISM_LIVE_OLLAMA_MODEL` (default `(first model served by OLLAMA_BASE_URL)`) | No credential for local ollama serve; Ollama Cloud key optional via provider options. | 3-4 requests on the first locally pulled model. |
 | `providers/ai-sdk` | active | `PRISM_LIVE_PROVIDER_TESTS` + `OPENAI_API_KEY` | `PRISM_LIVE_AISDK_MODEL` (default `gpt-5.1`) | Reuses OPENAI_API_KEY through the real @ai-sdk/openai provider. | 3 requests on gpt-5.1. |
 | `providers/model-discovery` | active | `PRISM_LIVE_PROVIDER_TESTS`; any of: `OPENAI_API_KEY` / `GEMINI_API_KEY` | — | Reuses OPENAI_API_KEY or GEMINI_API_KEY for a real listing request. | 2 GET /models requests (second cached in TTL). |
+| `calibration/vendor-count-tokens` | active | `PRISM_LIVE_PROVIDER_TESTS`; any of: `ANTHROPIC_API_KEY` / `GEMINI_API_KEY` / `GOOGLE_API_KEY` | `PRISM_LIVE_ANTHROPIC_MODEL` (default `claude-haiku-4-5`), `PRISM_LIVE_GOOGLE_MODEL` (default `gemini-2.5-flash-lite`) | Count-only token requests (no generation) on non-sensitive fixture text, using the chat key each vendor already needs. | 3 token-count requests per credentialed vendor (prose, CJK, chat transcript); no generation, no streaming. |
 | `cli/live-journey` | planned | `PRISM_LIVE_PROVIDER_TESTS` + `OPENAI_API_KEY` | — | Packed CLI: init/provider-add/print/json/rpc over a real provider; transcript secret-scanned. | 1 pack + install, offline scaffold tests, <=3 wire prompts on the selected provider model (wire legs skip on 401/403). |
 | `memory/rag-rerankers-live` | active | any of: `PRISM_TEST_TEI_RERANKER_URL` / `PRISM_TEST_HOSTED_RERANK_URL`; optional: `PRISM_TEST_HOSTED_RERANK_URL` | `PRISM_LIVE_TEI_RERANKER_MODEL` (default `(endpoint default model)`), `PRISM_LIVE_HOSTED_RERANK_MODEL` (default `(endpoint default model)`) | Real TEI / OpenAI-compatible rerank endpoints; each leg self-skips when its endpoint env is unset. | 1 rerank request per configured endpoint (≤2 total). |
+| `memory/local-rerank-live` | active | `PRISM_TEST_LOCAL_RERANK`; optional: `PRISM_TEST_LOCAL_RERANK_CACHE_DIR` | `PRISM_LIVE_LOCAL_RERANK_MODEL` (default `Xenova/bge-reranker-base`) | In-process cross-encoder (transformers.js, q8/cpu) on this machine; no service and no credential. Weights come from the documented model id into a host cache dir; a cold run downloads a ≈280 MB int8 model. | One ≈280 MB model download on a cold cache; zero network after load, no API spend. ≈30 s wall clock after the cache is warm (the recall leg scores 24 × 96 query/document pairs). |
 | `memory/drive-sync-live` | active | `PRISM_TEST_DRIVE_ACCESS_TOKEN`; optional: `PRISM_TEST_DRIVE_FOLDER_ID` `PRISM_TEST_DRIVE_SHARED_DRIVE_ID` | — | Delegated Drive readonly token; least privilege: one throwaway folder. Folder/shared-drive ids optional. | <=2 Drive list/changes pages plus file media for that page; replay must not re-embed. |
 | `coding-tools/openapi-live` | active | `PRISM_LIVE_OPENAPI_TOOLS` | — | Real public OpenAPI 3.1 spec (warnely.com) + real GET tool calls; no credential. | 3 HTTP requests against example.com-class public hosts (plan budget ≤5). |
 | `coding-tools/computer-use-live` | active | `PRISM_TEST_COMPUTER_USE` + `PRISM_COMPUTER_USE_BIN` | — | Real host computer-use-linux MCP binary over stdio; real tool inventory + one bounded read-only screenshot. | Local desktop only; ≤30s ceiling. |
@@ -98,7 +100,7 @@ Set only the rows you want to run; everything else skips. Least-privilege scope
 | `core/webhooks-live` | active | `PRISM_TEST_WEBHOOK_URL` | — | Operator-controlled signed webhook receiver. | <=3 webhook deliveries (1 signed target + 1 loopback retry receiver). |
 | `core/artifact-bodies-s3-live` | active | `PRISM_TEST_S3_ENDPOINT` + `PRISM_TEST_S3_KEY` + `PRISM_TEST_S3_SECRET` + `PRISM_TEST_S3_BUCKET` | — | Dedicated throwaway S3-compatible bucket. | <=5 S3 requests (put/get/presign/delete x2). |
 | `cli/journey` | active | `PRISM_LIVE_PROVIDER_TESTS`; any of: `OPENAI_API_KEY` / `OPENROUTER_API_KEY` / `KIMI_API_KEY` / `ZAI_API_KEY` / `OPENCODE_API_KEY` / `NEURALWATT_API_KEY` / `DASHSCOPE_API_KEY` / `OLLAMA_API_KEY` | — | First init-catalog provider credential present in the environment. | 4-5 one-shot requests on the default catalog model. |
-| `memory/postgres` | active | `PRISM_TEST_POSTGRES_URL` | — | Postgres memory store + pgvector index round-trips on the operator database. | Bounded insert/query cycles against the configured Postgres. |
+| `memory/postgres` | active | `PRISM_TEST_POSTGRES_URL` | — | Postgres memory store + pgvector index round-trips on the operator database, including durable deletion propagation (1,000 derived rows tombstoned in one transaction) and grant-change re-pointing. | Bounded insert/query cycles against the configured Postgres. |
 | `memory/graft` | active | — (hermetic leg) | — | Graft upstream CLI child-process protocol (real binary spawns against the in-repo fixture graft bin). | Hermetic; no network. |
 | `memory/wiki` | active | — (hermetic leg) | — | Wiki lifecycle over real fs trees (init/refresh/lint/search fallback; qmd child-process client degrades without the binary). | Hermetic; no network. |
 | `coding-tools/lsp-forge` | active | — (hermetic leg) | — | LSP/language-intelligence + forge suites: real child-process spawns over the real LSP/forge wire protocols against fixture binaries. | Hermetic; no network. |

package/docs/memory-fabric.md

@@ -57,6 +57,34 @@ keyed by block label, and `episode` views write nothing. A rewrite keeps the row
 consent, importance, and every non-fabric metadata key; an explicit `id` or `supersedes` from the
 caller disables auto-folding for that write.
 
+### Following the file (path moves and deletes)
+
+A `file` note names its document by `metadata.path`, and that path — not a lineage edge — is the only
+link between note and file. Notes are store-backed metadata rather than derived chunk rows, so the
+`_lineage` walk that revokes derived records can never find them: this handler is the only path.
+
+```ts
+import { createFabricRepointHandler } from "@arnilo/prism-memory/fabric";
+
+// One handler, both seams: a move rewrites `metadata.path`, a delete tombstones.
+const notes = createFabricRepointHandler({ scope, vectorStore: store });
+await repointSource({ scope, vectorStore: store, from: "docs/a.md", to: "docs/b.md", authorization: principal, handlers: [notes] });
+await createDeletionPropagator({ scope, vectorStore: store, authorization: principal, handlers: [notes] }).propagate("docs/a.md");
+```
+
+- Move: only `kind: "file"` notes whose `path` is the moved id are touched. Id, text, embedding,
+  `sourceEntryIds`, and every other metadata field are reused verbatim — no re-embed, no re-score, and
+  no `_lineage` field invented, so the walk stays for records that really are derived. Non-file notes
+  and notes for other paths are untouched, and the write joins one store transaction when the store
+  has one (a plain `upsert` otherwise).
+- Delete: the notes recorded against the deleted path are tombstoned through the store's own
+  invalidation path (`invalidate`, batched at `HARD_INVALIDATION_BATCH`; reason `forgotten` by default,
+  `legal_hold` when both the handler and the propagator are given it), so recall stops serving them
+  with no second revocation plane and no background cleanup to wait for.
+- One scope read per leg, selecting on `metadata.fabric.path` — never on content. A note in another
+  scope is never visible, and a composition whose scope differs from the handler's is refused
+  (`MemoryScopeError`) instead of writing across threads.
+
 ### Workers (opt-in)
 
 Both workers run inline (awaited) after the write, see redacted text only, call no model and no