omp-fabric 0.85.0

package/docs/architecture.md

@@ -0,0 +1,139 @@
+# Architecture & security
+
+## Architecture
+
+```text
+fabric_exec
+    │
+    ▼
+TypeScript checker → QuickJS sandbox (default)
+                   └→ disposable Node process (unsafe opt-in)
+    │ JSON-only host bridge
+    ▼
+ActionRegistry ◀── staged commit ── ComponentSupervisor
+    ├── omp.*                          ├── pinned first-party providers
+    ├── extensions.*                  └── configured and discovered components
+    ├── mcp.*
+    ├── agents.* ──▶ actors + participant control
+    ├── mesh.* ──▶ state.*
+    ├── schema.*
+    ├── memory.*
+    ├── compact.*
+    ├── components.* kernel diagnostics and reload
+    └── external providers
+
+ActivityStore → compact widget + footer status + interactive dashboard
+```
+
+Unique provider extra keys and unknown actions feed a [catalog repair table](repairs.md). Session JSONL is the log; `current.json` holds unique schema maps. Effect failures (bash, edit miss) and guest typecheck are classified for status but never promoted.
+
+In the default QuickJS runtime, guest code runs without `process`, `require`, filesystem, network, or subprocess globals. Every effect crosses the host bridge, and schemas, approvals, audit records, timeouts, and cancellation apply there. Each execution gets a fresh QuickJS context. Strings the caller names in the `payloads` tool parameter appear as `omp.key`. Reading a missing key throws a clear, actionable error that lists the provided keys.
+
+The optional `node-process` executor runs the same type-checked guest API and host-call protocol inside a fresh child process with a configurable V8 heap. It serves workloads that exceed the WASM32 memory ceiling. This mode is not a security boundary, because Node's `vm` module cannot safely contain hostile code. Fabric restricts this mode to trusted configuration and describes it as unsafe in `/fabric settings`. Schema enforce mode disables it. Parent-side deadlines and cancellation terminate the whole child process.
+
+## Component control plane
+
+The [component plane](components.md) supervises provider registry changes under the lifecycle laws and author duties in the [component calculus](component-calculus.md). A [provider specialization](provider-component-calculus.md) applies those rules to first-party namespaces and rolling replacement.
+
+Before activation, a definition declares its required actions and optional services while the loader resolves a capability view with versioned descriptor hashes. Mounted providers stay staged until their effects finish and the target passes a second check, which makes publication atomic.
+
+Replacement retires the old generation, which makes dependents unload before its provider inverse runs. Retained views and active calls can use that generation until quiescence. Transition epochs prevent stale publication at yield boundaries, and disjoint provisions keep each namespace unique. Parent-owned child fibers unwind before the parent. Effect scopes apply their inverses in LIFO order and send cleanup failures to quarantine.
+
+The dashboard renders the requirement graph as a component group. Participant ownership uses a separate topology. Enabled first-party providers mount through pinned components. `components.*` remains in the kernel and controls the graph. Runtime initialization completes each pinned mount before it creates the execution service.
+
+The same committed-view protocol can close an actor child's Fabric surface around a portable descriptor digest. The child resolves that digest, then each nested call uses the pinned view. This behavior defines capability coherence. Host component code runs as trusted code outside the sandbox.
+
+## Tool discovery and generic calls
+
+Inside `fabric_exec`, the `tools` surface discovers and calls any provider generically. This helps when you do not know the exact ref ahead of time:
+
+```ts
+const providers = await tools.providers();
+const candidates = await tools.search({ query: "GitHub issues" });
+const schema = await tools.describe({ ref: candidates[0].ref });
+const result = await tools.call({
+  ref: schema.ref,
+  args: { query: "is:open label:bug" },
+});
+return result;
+```
+
+Known actions keep first-class proxies, and they still cross the same registry path: `mcp.<sanitized_server>.<sanitized_tool>(args)`, `memory.*`, `state.*`, `schema.*`, `components.*`, and `compact.*`. `mcp.fal_ai.get_model_schema(args)` resolves the mcporter names `fal-ai` and `get-model-schema`. Captured extension tools take the form `extensions.<tool>(args)` in full code mode. Reserve `tools.call()` for refs you discover or compute at runtime.
+
+Refs are namespaced: `omp.grep`, `extensions.<tool>`, `mcp.<server>.<tool>`, `schema.<action>`. Calls with bare names are rejected. `tools.describe({ref})` falls back to a bare action name when exactly one provider exposes it, and ambiguous names return an error that lists the qualified refs. `tools.providers()` → `[{name,description}]`; `tools.catalog({provider?,limit?})` → the deterministic current provider/action head tree with descriptor hashes and explicit non-historical metadata; `tools.search({query,limit?})` → `FabricAction[]`; `tools.describe({ref})` → the full `FabricAction` (read its `inputSchema` first); `tools.call({ref,args?})`; `tools.list({provider?,namespace?,query?,limit?})`; `tools.models()` → OMP `[{provider,id,name,key}]`; `agents.models({runner:"claude"})` → Claude Code runtime models. For the exact signatures and the read → describe → retry error loop, see the model-facing `fabric-exec` skill.
+
+## Tool-call robustness
+
+The model-facing `fabric_exec` schema is flat. It carries one large `code` string plus scalar/optional parameters, and it contains no nested arrays-of-objects holding escaped content. Newer SOTA models are post-trained on one dominant harness's flat tool shapes. Such models can invent trailing keys at the highest-entropy point of a nested escaped-JSON field, for example right after closing a long multiline string, and a strict schema rejects those keys. The only nested field, `display`, ignores unknown keys. The schema accepts extras and filters them to `{ name, description }` before execution, which mirrors the silent-filter behavior the dominant harness's client is trained against.
+
+The model writes TypeScript that calls tools. Deterministic, type-checked code builds each nested object. Fabric's TypeScript checker catches incorrect code and returns an actionable error with line numbers.
+
+OMP Fabric applies a narrow compatibility layer at each boundary before authoritative validation runs. The outer `fabric_exec.prepareArguments` hook wraps a root code string, joins all-string code arrays, omits null optional metadata, and canonicalizes `display`. Inside the guest, `omp.*` calls normalize positional forms, observed field aliases, numeric strings, and known optional nulls. The registry then validates against the native OMP schema. Required nulls, mixed arrays, unknown keys, and otherwise ambiguous shapes still fail normally.
+
+For provider-level corruption, or for sessions that expose OMP tools directly, install [pi-tool-repair](https://github.com/monotykamary/pi-tool-repair) as a companion. The OMP host validates before `tool_call`. The companion repairs the finalized assistant `toolCall` arguments at `message_end` against each active tool's live schema, and it revalidates them before committing. In full code mode it can repair the outer `fabric_exec` call, leaked tool-call grammars, anchor bleed, and phantom tool-use responses. Fabric stays responsible for nested `omp.*` calls that the TypeScript guest creates later. The packages register no competing tool wrappers.
+
+The provider owns the Anthropic strict tool use setting. When enabled, strict mode stops the server from sampling keys that are absent from the schema. Anthropic limits the complexity of strict tool definitions.
+
+## Shell exit status and result middleware
+
+`omp.bash(..., { settle: true })` and `(..., { settle: true })` convert an ordinary native nonzero exit into
+`{ ok: false, exitCode, output, details, error }`. Fabric classifies that exit
+before `tool_result` middleware runs and transports the status separately from
+display text in both runtimes. Trimming, redaction, newline changes, or replacing
+the display text cannot erase the exit status. `output` and `error` use the final
+middleware text; they never restore text removed by a middleware. Native status
+line removal is best-effort display cleanup; ambiguous text is preserved.
+
+Timeout, cancellation, approval and preflight failures remain exceptions. A
+middleware failure after a successful command also remains an exception, and
+middleware recovery through `isError: false` remains effective. OMP's
+`emitToolResult` returns the **effective** `isError`, without identifying whether
+a handler introduced a new failure. After a native nonzero exit, Fabric cannot
+distinguish an annotation/redaction from an additional middleware veto expressed
+only through text and `isError: true`. Such a veto needs a separate explicit
+provenance contract; this limitation is not solved by shell settlement. For now,
+checks that must prevent command execution belong in approval or `tool_call`
+preflight, and callers requiring all final errors to throw should omit `settle`.
+
+## Model-context economy
+
+Fabric caps final `fabric_exec` output at 50,000 characters by default, which matches OMP's built-in 50KB tool ceiling. Failed executions get a tighter 20,000-character visible ceiling, and the complete output stays in the same private artifact. An oversized structured return shares that budget across every multiline section and preserves both ends with explicit omission markers. Unstructured output keeps its global beginning and end. Fabric writes the complete output to a mode-`0600` temporary artifact and includes the artifact path inside the visible ceiling. The model can then retrieve a targeted range without carrying the entire result. Type-check diagnostics use the same ceiling. Models should still filter noisy commands and return only useful evidence, because source-side projection preserves more relevant information than post-format truncation. When a later nested call fails after earlier calls completed, the error adds a bounded list of completed refs and paths. The model can inspect that list before repeating side effects. Nested outputs the guest did not return are never exposed.
+
+## Federated participant topology
+
+Fabric separates **identity** from **execution ownership**. Each root, one-shot or recursive agent, and actor carries a single intrinsic participant record with `rootId`, optional `parentId`, `ownerHostId`, `residency`, and the owner's authenticated wire identity. Main and Peer are projections of root records. Every process publishes one leased host record plus the participants it manages directly. An ancestor never re-advertises recursively discovered UI descendants. Readers treat every record behind an expired host as stale. Crash cleanup then covers the whole host. Shared summaries contain operational metadata only. Agent prompts, results, and errors stay local. Local run/actor managers overlay richer private detail only when the directory marks that participant local.
+
+Cross-process control targets one resolved owner. The sender addresses a versioned command to that owner and accepts a reply only when its target and wire identity match. Before execution, the owner checks the target against its local managers. Unknown, stale, rejected, spoofed, replayed, and expired commands fail closed.
+
+The owner claims each command ID in reserved state before execution and stores the result before replying. Claims remain while the command is present in the bounded retained event log. A restart can return the stored result without running the command again. A crash after the claim but before the result returns an explicit indeterminate rejection.
+
+Long actor asks run outside the control poll loop, so they do not block stop or cancellation commands. The request deadline aborts work on the owner. Caller cancellation sends an authenticated cancel command to the same owner. Actor replies share one mesh byte budget across text and structured data; an unexpected oversized result becomes an explicit rejection and never becomes a silent timeout.
+
+Control topics and topology and legacy state prefixes are reserved from guest mesh writes. The old `fabric.steer` relay and dual-written root and actor presence remain for mixed-version sessions. OMP children inherit absolute project and mesh roots, including worktree and recursive launches, so descendants join the same topology.
+
+## Security and limitations
+
+- When no captured override exists, OMP Fabric invokes separately constructed OMP built-in definitions. With OMP's extension runner available, Fabric replays their native `tool_call`, `tool_result`, and `tool_execution_*` lifecycle. Captured overrides and extension tools use that same lifecycle. Fabric's approval and audit layer stays authoritative around every nested call.
+- A captured exact-name core override contributes only a bounded, execution-local object overload and authored guidance to its existing `omp.<name>` slot wherever Fabric uses effective full-code execution, including Schema enforce mode. Built-in shorthand and normalized result contracts remain unchanged; the live registry schema and enforce host gate remain authoritative.
+- Non-OMP provider results emit a transient namespaced `tool_result` proxy before the QuickJS result bound. The proxy's details envelope exposes the exact host-side result to trusted user extensions. Those extensions can inspect or externalize sensitive provider data. The proxy does not create a separate persisted tool-result message.
+- Captured tools execute with the full privileges of their owning extension. Hiding a tool schema optimizes context. It does not sandbox anything. Captured tools keep their definitions and native renderers. Nested calls still render inside the enclosing Fabric execution, so they do not appear as separate native tool rows.
+- Registry interception composes through the public `ExtensionRunner.getAllRegisteredTools()` method. If an extension replaces that method and fails to delegate to the previous implementation, it can prevent capture.
+- MCP servers, external providers, and component definitions execute with their own host privileges. Review their configuration and code before you enable them. Component effect scopes can unwind registered effects only. Ambient side effects hidden from the supervisor are outside their reach.
+- Type checking improves reliability. It is not a security boundary. In the default runtime, QuickJS isolation and the host capability bridge form the boundaries. The optional Node process runs as trusted native execution outside the QuickJS boundary.
+- Child OMP processes load normal extensions by default, so provider-backed models keep working. Claude children use the official installed CLI with its existing authentication. Both runners restrict the active model-facing tools to `defaultTools`. OMP adds `fabric_exec` only for explicit recursion. Claude rejects recursion and unmapped tools.
+- `agents.handoff` schedules an explicit `agent`-risk delegation at the complete outer `fabric_exec` boundary. The guest call returns a deferred marker, and the rest of the Fabric program continues. Once every nested call and the outer result middleware finish, Fabric forks through the native assistant `fabric_exec` entry, appends its exact finalized native `toolResult`, and starts the target from that branch. Fabric does not create synthetic nested assistant turns or a custom context dump. The mode-`0600` child session lives inside the managed run directory. The source session and its history stay unchanged. Normal outer output and trace limits apply before the fork. The target model can see the Fabric source and result, so do not hand off a trajectory that contains secrets to a provider that should not receive them.
+- `/fabric prewalk` pre-authorizes the same one-shot delegation through `prewalk.model` or an interactively selected OMP executor. The command adapts [Stencil's Prewalk](https://stencil.so/blog/prewalk) and [oh-my-pi's in-place implementation](https://github.com/can1357/oh-my-pi/blob/main/packages/coding-agent/src/session/agent-session.ts) into a prompt-free form. It uses a coarser atomic boundary. The first monitored mutation marks the outer Fabric invocation, every remaining nested call still runs, and the executor starts only from the complete native `fabric_exec` call/result pair.
+- Claude `extensions: true` preserves the user's normal Claude Code customizations, including applicable settings and hooks. Those hooks execute with their usual host privileges. Set `extensions: false` for Claude safe mode. When allowed, `Bash` stays unrestricted inside the child, in the same way as Fabric's `bash` capability.
+- Claude model discovery sends a local initialization control request and never invokes a model. One-shot and actor activations use the account or API billing already configured in Claude Code. Fabric records the CLI's reported `total_cost_usd` in its normal usage and budget ledgers.
+- A Git worktree isolates files. It does not isolate credentials, network access, processes, or external services. Fabric-managed worktrees live at `<repo>/.omp/fabric/worktrees/<id>` and clone the source tree copy-on-write when the filesystem allows it.
+- Fabric projects agent transcripts from local `events.jsonl` run logs. The dashboard redacts common credentials from compact tool previews. The permission-restricted raw event log can still contain assistant text, tool arguments and results, diagnostics, and extension protocol payloads. Persisted `fabric_exec` traces also retain projected bash command text for command previews. Treat retained session and run data as sensitive.
+- Fabric stops session-resident background children when the parent OMP session shuts down. A hidden per-root resident host launches `agents.spawn({ residency: "durable" })`, and that child continues after the TUI exits. A detached spawn sends a follow-up completion message unless the caller later waits for it or `notifyOnComplete` is disabled. Resident completion messages queue in mesh state until Main resumes. Durable participant lifecycle subscriptions deliver source-qualified OMP and run notifications across roots, agents, and actors with no transcript disclosure. Completed worktrees are retained on purpose.
+- Fabric suspends session-resident actors on shutdown and restores them after project trust. `agents.create({ residency: "durable" })` transfers execution to the hidden resident host before it returns. The mailbox, mesh subscriptions, relayed Main events, and runner session continue after Main exits.
+- Claude actor session IDs point to Claude Code's private session store. Removing that session makes resume fail. Removing the Fabric actor does not delete Claude Code's transcript.
+- Project actors live under `.omp/fabric/mesh/actors/` and survive `/new`; session actors live under `.omp/fabric/mesh/actors/<sessionId>/`. `agents.create({ scope })` selects either boundary per actor, while `mesh.actorScope` supplies the omitted default, so both kinds coexist. Mode-`0600` binding files store each caller session's model and thinking values without changing project defaults. Root session identity propagates through participant agents. Mesh topics and shared state remain project-scoped. Do not put secrets in actor prompts, messages, or mesh state.
+- Approving `agents.create()` delegates future subscribed events until someone stops the actor. Durable residency lets that delegation outlive the approving TUI. Each mailbox item stores one model and thinking view before it queues: call override → session binding → project default → Fabric default. The runner and tool allowlist remain fixed for that activation. Review them before approval. Tool changes affect later activations only.
+- Only an approved durable `agents.spawn` or `agents.create` action in a trusted mesh-enabled project starts the hidden resident host. Its mode-`0600` config, command spool, run metadata, and PID lock live below the root's mesh residency directory. This IPC is crash-conservative: an interrupted claimed request reports an indeterminate outcome, and the request is not replayed. The IPC is not a boundary against arbitrary host filesystem access. Trusted code with direct access to `.omp/fabric` can corrupt residency state in the same way it can corrupt the mesh. Empty resident hosts exit after a short grace period.
+- Actor responses enter the main context only through the delivery policy fixed at creation. Directive output passes schema validation. It is still untrusted model output, and the main agent should weigh it.
+- A project-scoped actor has one execution owner. Passive sessions do not consume host events, drain a second mailbox, or persist shutdown state. They can read the shared definition, mailbox, and logs; change their own model and thinking binding; and send direct calls to the authenticated owner. The owner can also execute a routed `stop`. Shared runtime settings stay owner-only. Fabric routes durable removal to the resident owner.
+- A persisted actor can lose its advertised owner after a host lease expires. If its lineage root is also absent, a residency-matched host may adopt it and change `rootId`. The registry grants ownership only after it stores the new `rootId` and an `adoptedAt` fence under lock. Concurrent starters converge on one adopter. The 30-second fence gives a new adopter time to publish its participant record.
+- Shared `actors.json` writes use a stale-safe lock and merge only records owned by the writer. One owner cannot overwrite another owner's newer actor record. Use session scope for independent actor sets or private mailbox histories. Different model or thinking choices do not require it. Mesh events remain append-only until bounded compaction keeps the newest tail. Archive or remove an old mesh root when that retained history is no longer useful.

package/docs/audit-trace.md

@@ -0,0 +1,116 @@
+# Fabric execution trace V1
+
+The final `fabric_exec` result details form a bounded durable envelope that holds `success`, `trace`, the rich render `audits`, `phases`, and `error`. The privacy-projected trace stays the functional record for compaction, memory, and tool ownership. The audits persist verbatim with full arguments, results, and previews. A resumed transcript re-renders and expands the same way as the live one. Collapsed cards provide the visual boundary. The record itself keeps the full data. Final session JSONL details never contain logs, return values, type errors, media payloads, or in-memory media notes.
+
+The serialized final details object never exceeds 512 KiB. Consumers use current traces structurally. The chat renderer allows one compatibility exception. It can match a pre-change bash digest against string literals or named strings already visible in the outer `fabric_exec` arguments, so old previews can show the original command.
+
+## Envelope
+
+```ts
+interface FabricPersistedExecutionDetailsV1 {
+  success: boolean;
+  trace: FabricExecutionTraceV1;
+  audits: FabricLegacyRenderAudit[];
+  phases: string[];
+  error?: string;
+}
+
+interface FabricExecutionTraceV1 {
+  kind: "omp-fabric.execution";
+  version: 1;
+  outcome: "succeeded" | "failed" | "aborted" | "timed_out";
+  phases: string[];
+  operations: FabricExecutionTraceOperationV1[];
+  counts: {
+    droppedValues: number;
+    truncatedValues: number;
+    redactedValues: number;
+    droppedOperations: number;
+  };
+  error?: string;
+}
+```
+
+A trace excludes run and call timestamps, elapsed durations, random call IDs, source code, media payloads, and arbitrary argument or result content. Runtime and call errors become fixed stage and outcome messages. Provider, validator, approval, or guest exception prose never enters the trace.
+
+`phases` records occurrences in order. Repeated transitions stay in place, so `A → B → A` appears as `["A", "B", "A"]`.
+
+## Call operation
+
+```ts
+interface FabricExecutionTraceOperationV1 {
+  type: "call";
+  sequence: number;
+  ref: string;
+  provider?: string;
+  action?: string;
+  args: Record<string, JsonValue>;
+  outcome: "succeeded" | "failed" | "aborted" | "timed_out";
+  failureStage?: "resolve" | "prepare" | "validate" | "approve" | "invoke" | "guard";
+  error?: string;
+  result?: JsonValue;
+}
+```
+
+The host bridge assigns `sequence` when it receives any durable operation. A parallel completion only updates the existing record, and operation order stays unchanged. Fabric issues action attempts before reference resolution, preparation, schema validation, approval, and execution guards. Discovery and workflow attempts go out before their guards, lookups, validation, or activity mutation, so failures in those stages stay visible. The configured executor returns a typed termination reason. Trace sealing uses that reason for deadline and cancellation outcomes, and it never classifies exception text.
+
+V1 keeps `type: "call"` for wire compatibility. Exact internal refs separate discovery, lifecycle, and combinator operations from provider action calls. V1 also leaves `result` optional, and discovery, workflow lifecycle, and combinator operations never persist one. The generic recorder drops provider results, with a single exception: the exact `{ created: true }` creation outcome from `omp.write`. No output or provider details accompany that outcome. Argument projection follows the exact reference:
+
+- `omp.read`: local `path`, numeric `offset`, numeric `limit`
+- `omp.grep`: local `path`, numeric `context`, numeric `limit`. Drops pattern and query
+- `omp.find`, `omp.ls`: local `path`, numeric `limit`. Drops pattern and query
+- `omp.edit`, `omp.write`: local `path` only. Drops edit replacements and write content. `omp.write` can keep `{ created: true }`
+- `omp.bash`: bounded command text
+- selected `agents.*` lifecycle calls: `id` only. Drops task, message, instructions, names, model options, and outputs
+- `mesh.publish`/`read`: topic/address and numeric cursor/limit. Drops payload text and data
+- `mesh.get`/`put`/`delete`/`list`: key or prefix and limit. Drops values
+- memory, state, schema, compact, MCP, extension, unknown, and external calls: no arguments or results
+
+### Discovery operations
+
+Read-only discovery still bypasses mutation authorization and approval budgets. Fabric persists every attempt in the same `sequence` space as actions and workflow activity:
+
+- `fabric.discovery.providers`: no arguments or results
+- `fabric.discovery.models`: no arguments or results
+- `fabric.discovery.catalog`: identifier-shaped `provider` plus numeric `limit`. Drops catalog metadata and results
+- `fabric.discovery.list`: identifier-shaped `provider` and `namespace`, plus numeric `limit`. Drops the free-form `query` and results
+- `fabric.discovery.search`: numeric `limit`. Drops the free-form `query` and results
+- `fabric.discovery.describe`: identifier-shaped action `ref`. Drops results
+
+Each discovery operation records `succeeded`, `failed`, `aborted`, or `timed_out`, along with the applicable `guard`, `resolve`, or `invoke` stage. Model-registry enumeration keeps its best-effort empty-list behavior when enumeration throws. Fabric marks the corresponding operation failed.
+
+### Workflow lifecycle operations
+
+Declarative workflow calls still feed transient activity updates to the live UI. Each call also persists as a durable occurrence record:
+
+- `fabric.workflow.configure`: `name`. Drops the description
+- `fabric.workflow.phase`: `name`, identifier-shaped `id`, numeric `total`. Drops the description
+- `fabric.workflow.item`: identifier-shaped `id`, `status`, `phase`, and `kind`, plus numeric `total` and `completed`. Drops label, detail, current value, and data
+- `fabric.workflow.event`: identifier-shaped `level`. Drops message and data
+- `fabric.workflow.progress`: no arguments. Drops the message
+
+Fabric records these operations in bridge issue order, alongside actions and discovery. The separate `phases` compatibility field keeps occurrence order and retains repeated transitions.
+
+### Workflow combinator spans
+
+The shared guest implementation instruments calls to `workflow.parallel` and `workflow.pipeline` and records them as `fabric.workflow.parallel` and `fabric.workflow.pipeline`. Start creates one operation, and end updates that same operation. Persisted metadata stays limited to `kind`, numeric `itemCount`, numeric `stageCount` for pipelines, and the effective bounded `concurrency` for parallel calls. Empty combinators produce records too. A pipeline nests its parallel fan-out, so the pipeline operation goes out before the nested parallel operation, and both precede stage actions.
+
+Guest span IDs are deterministic execution-local bridge correlation values. Fabric never persists them, and the internal start/end bridge stays closure-private, outside the guest API. Internal span calls skip provider resolution, authorization, approval, and agent-budget accounting. A thrown stage closes active spans as failed. A runtime failure, deadline, or cancellation seals any still-open operation with the typed final execution outcome.
+
+Traces retain only plain local paths. They drop URL paths, together with credentials and query/fragment data. Plain paths lose their query/fragment suffixes as well. Sensitive-key normalization, media/base64 rejection, JSON safety, depth/node limits, and UTF-8 truncation still run after projection and add defense in depth. Projection provides the primary secrecy mechanism.
+
+Identifiers (`ref`, `provider`, `action`), outcomes, failure stage, operation sequence, and occurrence-ordered phase labels stay durable. These fields, the retained local paths and mesh addresses, and bash command text are not secret containers. Callers must never place credentials in identifiers, local filenames, topics, keys, phase names, or commands.
+
+## Reading and rendering traces
+
+The package exports `isFabricExecutionTraceV1`, `isFabricExecutionTraceOperationV1`, `readFabricExecutionTraceV1`, `createFabricPersistedExecutionDetails`, and `readFabricExecutionRenderDetails`. Its guards reject malformed envelopes, extra fields, oversized data, and unknown versions.
+
+Current sessions render resumed cards from the persisted `details.audits`. These audits win over the trace, and they restore full nested read bodies, edit diffs, bash output, and previews on expand. Sessions written before audit persistence hold the trace alone. Their audits come from operation metadata, which keeps bash command text. Each reconstructed audit carries a trace-derived marker, and its missing payloads show `not retained across reload`. The renderer shows no fabricated content. Old sessions that contain `details.audits` and `details.phases` still render through the legacy adapter. For old digest-only bash traces, the renderer matches the digest against literal and named strings that the outer `fabric_exec` arguments already expose. When the renderer finds no exact command, it drops the digest and shows no hash.
+
+Compaction and memory read only `toolResult.details.trace`, and both pass it through the trace guard. Compaction emits phases and operations in sequence order with stable `entryId/subordinal` addresses. Memory emits one normalized child per operation with address `<outer-entry-id>/<sequence>`. Neither consumer parses `fabric_exec` source, outer output, operation results, or rendered audit prose to recover calls, files, or failures.
+
+An invalid or unknown trace, when present, blocks semantic legacy reinterpretation. Compaction can use its separate strict old-session `details.audits` adapter only when the trace field is absent. Memory indexes trace operations only.
+
+## Limitations
+
+Persisted audits are verbatim. Resumed final rendering shows read bodies, edit diffs, write bodies, bash output, agent tasks, and provider results. Durable traces still store bounded projections. Bash command text stays in the trace, and arbitrary argument or result content never enters it. That exclusion covers discovery queries, workflow descriptions and data, external and MCP arguments, and provider results. When arguments are omitted from the trace, generic failure resolution keeps only the ref identity. The envelope stays bounded. Past 512 KiB, display-only audits trim first. Trace-only cards, old or trimmed, render `not retained across reload` markers for content the session record does not hold. Workflow activity content stays available only while the live execution result or activity store remains in memory.

package/docs/certification.md

@@ -0,0 +1,134 @@
+# Context and memory certification
+
+The repository provides three evaluation commands:
+
+- `bun certify:context` is deterministic, runs offline, and costs nothing.
+- `bun run certify:entropy` is deterministic and offline: fixed corpora through the versioned [tool-entropy meter](entropy.md), with a ratchet proof, the compile loop (applied, gate-rejected, and converged rounds), ingestion checks, and, against a real corpus with `--trial`, the held-out divergence trial that fails if the compiled artifact would reject any recorded successful call. With `--trial` and no `--artifact`, the compiled artifact is read from `<agent dir>/fabric/entropy/compiled.json`, where the agent dir is `OMP_FABRIC_AGENT_DIR` (expanding `~` and `file://`) and otherwise the host's `getAgentDir()` default of `~/.omp/agent`; a missing artifact fails `trial-mode` and names the directory it searched.
+- `bun benchmark:real-resume` is an opt-in, billable OMP RPC benchmark with a safe skip as its default behavior.
+
+`bun test` excludes these commands, which keeps the normal test suite offline and fast.
+
+## Deterministic certification
+
+Both certification commands run under Bun. They import the installed host package, whose `exports` map points `import` at TypeScript sources, and Node refuses to strip types for files under `node_modules`:
+
+```sh
+bun certify:context
+bun certify:context -- --json /tmp/omp-fabric-certification.json
+```
+
+The package command builds `dist/` first, then runs `scripts/certify-context.mjs`. It prints a human summary followed by the complete JSON report. When any threshold fails, the command exits nonzero.
+
+### Compaction endurance
+
+The harness builds a persisted session through OMP's `SessionManager`. Messages and compactions go in through its public methods. The active parent-linked branch comes back through `getBranch()`. Under deterministic settings (`contextWindow=64`, `reserveTokens=63`, `keepRecentTokens=1`), the harness performs exactly 100 Fabric compactions. Before every hook event it sums the host's `estimateTokens` over `SessionManager.buildSessionContext().messages`, applies `shouldCompact`, and requires `prepareCompaction` to return a preparation. It then invokes the callback registered by `registerCompactionHook` with OMP's `SessionBeforeCompactEvent` shape: `type`, `preparation`, `branchEntries`, an optional `customInstructions`, and `signal`. That event carries neither a compaction reason nor a retry flag, so certification asserts nothing about either.
+
+The host package is `@oh-my-pi/pi-coding-agent`. Certification reads the installed version from its own `package.json` and checks it against the range `omp-fabric` declares in `peerDependencies`, so no certified version is hard-coded; a host outside the declared range aborts the run and reports both the range and the resolved version and path. Each function is then resolved from a supported entry point, and a missing one aborts the run naming the entry point: `SessionManager` and `buildSessionContext` from the package root, `estimateTokens` from `@oh-my-pi/pi-coding-agent/extensibility/legacy-pi-coding-agent-shim`, and `prepareCompaction` plus `shouldCompact` from `@oh-my-pi/pi-agent-core/compaction`. At the pinned 18.1.10 host the package root exports `SessionManager` and `buildSessionContext`, does not export `prepareCompaction` or `shouldCompact`, and has no `buildContextEntries` export at all; the report records each of those observations under `hostApi.rootExports`. No public API supplies a preparation unless an `AgentSession` runs with a model, so certification makes no claim past that.
+
+Every persisted summary carries a cycle-unique `PRIOR_SUMMARY_POISON_991_…` suffix inside the actual `CompactionEntry`. On the next cycle, OMP's preparation has to expose that exact stored previous summary. A proxy around the event preparation records whether the registered Fabric callback reads `previousSummary`. The result derives from those accesses. Fabric must leave the value unread and keep its poison out of anything it emits. No step converts a summary into a user message by hand.
+
+Every cycle also checks:
+
+- the original goal, constraint, and pinned Unicode rare fact
+- the cumulative source, file, and unresolved-error addresses
+- tool-call/result closure at the kept boundary
+- the presence of every nonempty `firstKeptEntryId` on the active branch
+- exact round trips of persisted summaries and details
+- agreement between `SessionManager.buildSessionContext()` and the public `buildSessionContext(entries, leafId)`
+- a resolved context that, after the compaction and after each subsequent append, is identical to the context the host resolves from the retained entries alone: those from `firstKeptEntryId` onward, the `compaction` entry, and everything appended after it
+- a valid UTF-8 summary size of at most 32 KiB.
+
+The last 20 summary sizes must span a range of at most 512 bytes. Their absolute least-squares slope must stay at or under 16 bytes per cycle. These bounds catch late unbounded growth while letting cycle sizes differ.
+
+Six explicit eligible closure fixtures must each run at least once: normal, compact-all, OMP split-turn preparation, parallel/delayed results, reverse-order call/result, and malformed prior boundary. The harness checks every resulting Fabric cut for call/result closure.
+
+A separate maximal source of about 330 KiB mixes multibyte goals, instructions, paths, errors, turns, and typed Fabric activity. Its summary must reach at least 24 KiB, stay within 32 KiB, and survive a round trip through a fatal UTF-8 decoder. This fixture pushes the bound close to its reachable projection saturation. The endurance fixture alone plateaus naturally at roughly 5.8 KiB.
+
+The certificate covers deterministic cumulative projection, OMP eligibility and context behavior, closure handling for the named fixtures, and byte-safe saturation for generated typed event streams. Arbitrary human conversations and general model behavior require separate evaluation.
+
+### Cross-layer memory
+
+The same run creates 1,000 additional persisted OMP sessions. One unique rare-fact session receives an old source mtime. It must classify as cold. Only eight sessions may stay hot. Certification calls `MemoryProvider` directly. No shell output gets parsed.
+
+The pass conditions are:
+
+- at least 1,000 eligible sessions with complete indexing coverage
+- exact lexical recall of the cold rare fact
+- exact structural selection of a cold `omp.grep` operation by persisted ref/outcome, followed by source- and lineage-bound hydration
+- a nonexistent-ref structural negative control that returns zero results
+- a session header whose recorded id matches `SessionManager.getSessionId()`, so a session that cannot be identified from its own JSONL cannot pass
+- exact source expansion by its stable entry ID
+- exact expansion of every distinct entry ID emitted by the 100 compaction summaries or their structured details
+- 100% address expansion agreement with a fresh normalization of the source JSONL
+- V6 `sourceHash` integrity checks on both cold hydration and context address expansion.
+
+`memory.expand` caps exact selectors and returned entries per call, so the harness requests the emitted addresses in batches of at most 100 selectors and follows each response's `next` cursor until the selection is exhausted, concatenating the text chunks per entry. Every page has to report the same `sourceHash`; a change mid-expansion fails the run. The JSON report includes the eligible, indexed, and stale counts. It also lists the emitted and expanded address counts plus the cache and source byte sizes.
+
+This proves lexical addressability and exact capability-head addressability through the current cache, digest, search, and source-expansion layers. Fuzzy semantic retrieval, ranking under unrelated corpora, cache performance on all filesystems, and recovery after source deletion stay outside that proof.
+
+### Continuation QA
+
+Continuation QA creates two small temporary repositories. Each holds exact expected final files, an executable Node oracle, and files that must stay byte-identical. A no-model handoff simulator receives only:
+
+1. the compacted summary and the structured compaction details
+2. constrained current-session pointer and expansion APIs backed by `MemoryProvider`.
+
+The source phase persists a handoff envelope that holds the compacted context and the current OMP session ID. Task operations and captured session paths never enter that envelope. In the resume phase, the simulator reads that output, builds a fresh `MemoryProvider`, and asks it for a V6 integrity-bound current-session pointer. It then derives the cumulative source entry ID from the compaction details and expands that address with `expectedSourceHash`. The `addressResolved` score comes from the returned entry. The harness never substitutes a constant. No callback closes over `manager.getSessionFile()`.
+
+The simulator decodes `CERT_TASK_V1` and applies its operations only after the source expansion succeeds. When an exact operation or file payload is unavailable, it throws and fails the run. It never fabricates a success. The external oracle then scores exact filesystem state, forbidden-file integrity, and process exit status. The oracle never supplies `task.operations` to the simulator.
+
+This proves that the emitted address, the current persisted session identity, and the allowed memory operations can carry these mechanically executable tasks across a fresh handoff. OMP's compaction result itself exposes no session ID and no source hash. Those two values come from persisted current-session context and from `MemoryProvider`, in that order. Whether arbitrary prose can turn into operations, whether a model will choose to recall, and whether the two fixtures represent all software work stay unresolved here.
+
+## Real OMP RPC benchmark
+
+The benchmark compares two arms in deterministic randomized paired order:
+
+- `baseline`: resumes the full, uncompacted context
+- `fabric`: compacts with Fabric, terminates that process, then resumes in a fresh process.
+
+The resumed process receives exactly:
+
+```text
+Resume and complete the task.
+```
+
+A filesystem and test oracle outside the model scores the result. Reports capture pass/fail diff reasons, tokens, USD cost, tool calls, recall calls, wall time, summary bytes, Wilson 95% pass-rate intervals, and paired win/tie rates. A report names the credential variable and never shows its value. Session and repository data live in a temporary directory. The run removes that directory afterward.
+
+The RPC reader implements strict LF JSONL framing. It splits only on `\n`, strips an optional trailing `\r`, and preserves U+2028/U+2029 inside JSON strings. Node's `readline` plays no part in the reader.
+
+### Safety gate
+
+Without configuration, this command exits zero and reports `SKIP`:
+
+```sh
+bun benchmark:real-resume
+```
+
+A billable run requires all of these gates:
+
+```sh
+OMP_FABRIC_REAL_RESUME=1 \
+OMP_FABRIC_BENCH_PROVIDER=anthropic \
+OMP_FABRIC_BENCH_MODEL=claude-sonnet-4-5 \
+OMP_FABRIC_BENCH_KEY_ENV=ANTHROPIC_API_KEY \
+OMP_FABRIC_BENCH_REPEATS=3 \
+OMP_FABRIC_BENCH_MAX_USD=5 \
+bun benchmark:real-resume
+```
+
+`OMP_FABRIC_BENCH_KEY_ENV` names an already-set credential environment variable. The benchmark checks the observed session cost before each next arm starts. It stops once the run reaches the configured budget. A single in-flight request can still exceed the remaining budget. Treat the maximum as a stop boundary. Hard spending caps live on the provider side.
+
+The benchmark proves end-to-end behavior for the selected model, provider, fixture, extension versions, and repeats only. Small samples carry wide confidence intervals. General superiority and full isolation of provider variance stay outside that proof.
+
+The benchmark compares only the explicitly selected baseline and Fabric arms. Its oracle and paired report remain bounded evidence for the configured model, provider, fixture, extension version, and repeats; they do not claim general provider superiority.
+
+## Test coverage
+
+The suite in `tests/certification/` covers:
+
+- strict LF JSONL parsing, including split UTF-8 and Unicode line separators
+- the default skip gate and the complete opt-in gate
+- deterministic paired order and benchmark confidence/paired reporting
+- executable continuation oracle passes and forbidden-change failures
+- certification rejection under sabotage of eligibility, poison exclusion, address resolution, or the external oracle
+- certification report threshold failures.