omp-fabric 0.85.0

package/docs/providers.md

@@ -0,0 +1,109 @@
+# External providers
+
+Fabric [captures normal `omp.registerTool()` tools automatically](configuration.md#captured-extension-tools). Extensions use the versioned provider protocol for non-tool capabilities or virtual action catalogs with risk data.
+
+Fabric mounts each non-kernel first-party provider through a pinned component. External providers can use direct registration with a host-owned lifetime. A provider that belongs to a supervised external component calls `context.provide()` for staged publication and rolling replacement. The same component link controls dependency withdrawal.
+
+```ts
+import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent";
+import {
+  FABRIC_PROVIDER_DISCOVER_EVENT,
+  FABRIC_PROVIDER_REGISTER_EVENT,
+  type FabricProvider,
+  type FabricProviderDiscovery,
+} from "omp-fabric/protocol";
+
+export default function extension(omp: ExtensionAPI) {
+  const provider: FabricProvider = {
+    name: "example",
+    description: "Example actions",
+    async list() {
+      return [];
+    },
+    async describe() {
+      return undefined;
+    },
+    async invoke() {
+      return null;
+    },
+  };
+
+  omp.events.emit(FABRIC_PROVIDER_REGISTER_EVENT, {
+    version: 1,
+    provider,
+    overwrite: true,
+  });
+
+  omp.events.on(FABRIC_PROVIDER_DISCOVER_EVENT, (event: FabricProviderDiscovery) => {
+    event.register(provider, { overwrite: true });
+  });
+}
+```
+
+Each provider owns its schemas, its state, and how its actions execute. OMP Fabric validates arguments, enforces the declared risk policy, records nested-call audits, and propagates cancellation. A provider can also enrich the generic [activity surface](interface.md#data-driven-activity) without registering a TUI component:
+
+```ts
+async invoke(actionName, args, context) {
+  context.activity?.({ type: "entity", id: job.id, kind: "custom", name: job.name });
+  context.activity?.({ type: "progress", message: "Indexing package 3/12" });
+  context.activity?.({ type: "metrics", tokens: 4200, toolCalls: 9 });
+  return job.result;
+}
+```
+
+## Effect semantics and scoped acquisition
+
+Action descriptors can declare effect semantics. Descriptor hashes and committed component and actor views carry this metadata. Omitting it is the conservative choice. Read-risk actions then resolve as commutative `none`, and every other risk resolves as unknown-order `emission`.
+
+Actions with `kind: "scoped"` must implement `provider.acquire()` and return `{ value, dispose }`. Components call these actions through `context.acquire()`. That path validates arguments, pins the provider generation, and registers a single-shot disposer in the component scope. Ordinary `invoke()` stays available for `none`, `transactional`, and `emission` actions. A component that declares the `revertible` guarantee can normally call only `none` and `transactional` actions. Fabric rejects emissions from it.
+
+The `resources` field names the affected resource classes, and `ordering` is `commutative`, `ordered`, or `unknown`. Fabric records concurrent non-read calls with an unknown footprint, along with overlapping non-commutative resources, in `audits[].effectConflicts`. Revertible components reject those calls. Fabric never reorders calls based on provider claims. These fields carry scheduling and lifecycle semantics. They do not replace authorization, and `risk` continues to drive approval policy. Providers whose descriptors can change in place may implement `subscribeCatalog(listener)`. Fabric then re-resolves dependent component targets and unsubscribes when that provider generation closes. See [components and committed capabilities](components.md).
+
+## Nested `tool_result` proxy
+
+Results from MCP, agent, memory, state, schema, mesh, components, compact, and external providers pass through OMP's `tool_result` middleware before Fabric enforces `maxNestedResultChars`. A user extension can then externalize or replace an oversized provider result before that result crosses into QuickJS.
+
+A proxied event carries:
+
+- `toolName` holding the fully qualified Fabric ref, such as `mcp.github.search`;
+- a `toolCallId` that starts with `FABRIC_NESTED_TOOL_CALL_ID_PREFIX`;
+- text `content` holding the raw string result or a JSON projection;
+- `details` matching `FabricToolResultProxyDetailsV1`, whose `result` is the exact host-side structured value.
+
+```ts
+import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent";
+import {
+  FABRIC_NESTED_TOOL_CALL_ID_PREFIX,
+  readFabricToolResultProxyDetailsV1,
+} from "omp-fabric/protocol";
+
+export default function resultGuard(omp: ExtensionAPI) {
+  omp.on("tool_result", async (event) => {
+    if (!event.toolCallId.startsWith(FABRIC_NESTED_TOOL_CALL_ID_PREFIX)) return;
+    const proxy = readFabricToolResultProxyDetailsV1(event.details);
+    if (!proxy || proxy.ref !== event.toolName) return;
+
+    const serialized =
+      typeof proxy.result === "string"
+        ? proxy.result
+        : (JSON.stringify(proxy.result) ?? String(proxy.result));
+    if (serialized.length <= 6_144) return;
+
+    const artifact = await persistPrivately(serialized);
+    const replacement = {
+      fabricTruncated: true,
+      originalChars: serialized.length,
+      preview: `${serialized.slice(0, 3_000)}\n…`,
+      artifact,
+    };
+    return {
+      content: [{ type: "text", text: replacement.preview }],
+      details: { ...proxy, result: replacement },
+    };
+  });
+}
+```
+
+If you change only `content`, the nested sandbox value becomes the patched text. To keep a structured replacement, return the proxy envelope in `details` with a changed `result`, as in the example above. When both fields are patched, a valid changed `details.result` takes precedence. Returning `isError: true` fails the nested provider invocation.
+
+OMP core tools and captured extension tools skip this generic proxy, because they already replay their native `tool_call`, `tool_result`, and `tool_execution_*` lifecycle. Nested shell calls still emit their native identity: `omp.bash()` uses `toolName: "bash"`/`isBashToolResult()`. Proxied events act as middleware only. They create no separate persisted tool-result messages.

package/docs/repairs.md

@@ -0,0 +1,69 @@
+# Catalog repairs
+
+OMP Fabric learns **silent catalog-argument repairs** from unique invocation near-misses. It does not rewrite guidelines, `AGENTS.md`, or the system prompt. Session JSONL remains the only log. The durable product is a catalog-scoped table of spilled→declared maps.
+
+KPI: repeat **invocation** fingerprints → 0. Bash nonzero, edit misses, missing files, and guest typecheck/syntax are classified for status but never promoted.
+
+## Loop
+
+```text
+invalid args / unknown action
+        │
+  unique bijection against the live schema
+        │
+        ├─ effect / didactic / typecheck  → count, do not promote
+        └─ unique extra key or unique verb → insert into current.json
+                │
+         next ActionRegistry prepare / resolve applies the row
+         (canonical input is a no-op)
+```
+
+Repair-candidate observation and apply happen in `ActionRegistry` only. Unique extra keys are observed on the **caller's spilled args** before `prepareArguments`, so a bundled lexicon repair still persists the map for providers that lack one. `tool_execution_end` records effect drops and non-promotable fingerprints without double-counting inner invocation errors.
+
+## Store
+
+`<active OMP agent dir>/fabric/repairs/current.json` (`OMP_FABRIC_AGENT_DIR` overrides the agent dir).
+
+`catalogDigest` hashes sorted provider names plus captured tool names. A digest change starts empty and **clears in-memory fingerprint counters** so a previous candidate cannot be re-inserted. Schema field/action renames do not bump the digest; apply re-proves each row's unique mapping against the **live** declared names instead. Repairs are **global across models**, not per project.
+
+Table rows:
+
+- `keyAlias`: extra argument key → declared key (`sessionId` → `session`)
+- `actionAlias`: spilled action name → declared name (never applied when a committed capability view pins the call)
+
+Cap: 256 rows. Promotion is on the first unique hit; uniqueness against the
+live schema is the bound. A promoted row becomes active in memory immediately,
+while persistence queues behind a single asynchronous writer. Insert is
+identity-keyed (idempotent) and locked across OMP processes sharing the agent
+directory; lock retries yield to the event loop, and stale-lock recovery is an
+exclusive rename claim, so racing reapers can never delete a lock a fresh
+writer owns. Queued writes merge with rows another process persisted and flush
+before runtime teardown. Persistence failures never fail or delay the user's
+invocation and appear in `/fabric repairs`. Apply is a no-op when the schema
+accepts extension keys, the live mapping is absent or ambiguous, or the call is
+already canonical.
+
+Two failure modes stay visible, never silent:
+
+- A **transient catalog** (capture suspension between sessions or during `/fabric reload`) never re-keys the table: the surface freezes until the catalog re-arms, so promotion cannot persist rows under an empty-catalog digest that would destroy the stable table.
+- A **damaged table** (unreadable or malformed `current.json`) surfaces as `storeError` in `/fabric repairs`, blocks the merge that would overwrite it, and keeps promoted rows active in memory. A missing table, or one persisted under a different digest, starts fresh without an error.
+
+## Commands
+
+```text
+/fabric repairs              # status, top fingerprints, current table
+```
+
+## Configuration
+
+```json
+{
+  "repairs": {
+    "enabled": true
+  }
+}
+```
+
+Disable with `"enabled": false`. Promotion never edits execution guidance or Schema text.
+
+The repair table is the profiler for [tool entropy](entropy.md): the deterministic meter, ratchet gate, and `certify:entropy` compiler loop turn promoted rows into reviewable surface diffs.

package/docs/residency-runtime.md

@@ -0,0 +1,82 @@
+# Durable residency through OMP
+
+## Purpose
+
+Fabric participants with `residency: "durable"` continue after the originating
+OMP session closes. They run in one background resident host per Fabric root.
+The host owns durable actors and one-shot durable agents; mesh state and the
+residency directory provide reconnection and control routing.
+
+## Why the host starts through OMP
+
+OMP packages intentionally leave OMP core packages as host-provided peers. A raw
+Node process started from an installed Fabric package therefore cannot resolve
+`@oh-my-pi/pi-coding-agent`. OMP's extension loader supplies those imports.
+
+The resident host must consequently run inside a headless OMP process, rather
+than directly under `node`.
+
+## Process topology
+
+```text
+Fabric residency client
+  -> detached Node launcher
+    -> omp --mode rpc --no-session --no-tools --extension omp-entry.js
+      -> OMP extension loader
+        -> ResidentHost
+```
+
+`launcher.js` is Node-core-only. It keeps RPC stdin open because OMP RPC exits on
+`omp-entry.js` starts `ResidentHost` on `session_start`, aborts it on
+`session_shutdown`, and shuts OMP down after the host reaches its idle exit.
+
+## Files and responsibilities
+
+- `src/residency/client.ts` writes host configuration and starts the launcher.
+- `src/residency/launcher.ts` creates the detached headless OMP child.
+- `src/residency/omp-entry.ts` bridges OMP lifecycle events to the host.
+- `src/residency/host.ts` owns requests, mesh control, `owner.json`, and idle
+  shutdown.
+- `src/index.ts` registers `residency/launcher.js`; this registration must not
+  point back to `host.js`.
+
+The residency protocol is unchanged: `config.json`, `owner.json`, request,
+response, and mesh files remain the durable interface.
+
+## Context and lifecycle
+
+Residency does not share agent contexts. Each actor or agent retains its own
+runner session. Shared work must use mesh state, files, or an explicit external
+channel. Residency only keeps the execution owner available for later control
+and reconnection.
+
+The host exits after its normal idle grace once it owns no live durable actor or
+running durable agent.
+
+## Validation
+
+Run:
+
+```bash
+bun run typecheck
+bun run build
+bunx vitest run tests/type-checker.test.ts tests/residency.test.ts tests/fabric-runtime-components.test.ts
+```
+
+Also validate a locally installed package in OMP: create a durable actor, verify
+its `owner.json`, route `stop`, and confirm the actor becomes `stopped` with a
+resident `ownerHostId`.
+
+## Known Windows limitation
+
+Durable residency E2E is POSIX-only today. On Windows, the launcher's spawn of
+the `omp` binary through the installed `node_modules/.bin` shims hangs before
+the child starts, so the resident host never starts.
+The launcher, ownership observation, and protocol logic are platform-agnostic
+and are tested on every operating system.
+
+## Future direction
+
+A native OMP extension-host subprocess API could replace `launcher.js` later.
+Keep the launcher boundary isolated so that migration changes no residency
+protocol or public Fabric API.

package/docs/schema-enforcement.md

@@ -0,0 +1,166 @@
+# Schema enforcement
+
+Schema enforcement adds host authorization and a local-file transaction layer to Fabric. You opt in explicitly. The mode defaults to `off` for compatibility.
+
+```json
+{
+  "schema": {
+    "mode": "enforce",
+    "certificateTtlMs": 30000,
+    "maxFiles": 100,
+    "maxBytes": 10485760,
+    "trustedCommands": {
+      "focused-tests": {
+        "command": "bun",
+        "args": ["exec", "vitest", "run", "tests/focused.test.ts"],
+        "shell": false,
+        "timeoutMs": 30000
+      }
+    }
+  }
+}
+```
+
+`mode` accepts `off`, `audit`, or `enforce`. An invalid value becomes `off`. Fabric clamps the certificate TTL between 1 second and 10 minutes. It limits the file count to 1 through 1,000 and transaction bytes to 1 KiB through 100 MiB. The defaults are `off`, 30 seconds, 100 files, and 10 MiB. The session locks the mode at startup, and a config reload takes effect only in the next session.
+
+Fabric treats its global configuration as trusted host input. OMP reads a project `.omp/fabric.json` only when it marks that project trusted. A model action or an untrusted project configuration can never supply `trustedCommands`.
+
+## Modes
+
+- **off** leaves action authorization and tool visibility unchanged. The `schema.*` control plane stays available and does not gate other actions.
+- **audit** leaves host behavior unchanged. Fabric publishes a durable `would_block` event to `fabric.schema` for every nested Fabric action or top-level OMP tool call that enforce mode would deny.
+- **enforce** permits only this extension's exact, source-provenanced `fabric_exec` definition at the top level. A `tool_call` gate blocks every other built-in, external-extension, and SDK `customTools` call before execution. Fabric admits a nested call only while an owned outer invocation is active and only when its id starts with Fabric's generated `NESTED_TOOL_CALL_ID_PREFIX`, because such a call already passed registry authorization. The central resolved-action gate stays authoritative inside Fabric. Direct refs and computed `tools.call` refs share the same decision.
+
+Under enforce mode, discovery and workflow display operations still work, along with these exact host-owned actions:
+
+- `omp.read`, `omp.grep`, `omp.find`, `omp.ls`;
+- `memory.recall`, `memory.expand`, `memory.sessions`;
+- `state.get`, `state.history`, `state.complexity`;
+- `mesh.self`, `mesh.read`, `mesh.members`, `mesh.get`, `mesh.list`;
+- `compact.status`;
+- `components.list`, `components.status`, `components.graph`;
+- `schema.status`, `schema.hypothesize`, `schema.verify`, `schema.commit`, `schema.abort`.
+
+The gate blocks `omp.edit`, `omp.write`, `omp.bash`, all agent/actor actions, mesh and state writes or execution, `compact.request`, `compact.cancel`, `components.reload`, MCP, captured extensions, and every external provider, whatever risk it declares. Enforce sessions keep declarative component entries in configuration without activating them, and registered definitions stay visible to diagnostics. A provider that claims `risk: "read"` still fails this exact-reference policy. Fabric records guard failures in the existing typed execution trace with `failureStage: "guard"`.
+
+An enforce session never restores persistent actors, and host-event actor dispatch stays off. Fabric disables agent execution, so the gate also blocks agent actions. Capture `keepVisible`, descriptor risk, claimed source metadata, or tool visibility cannot authorize a second top-level path. Fabric blocks a colliding external or SDK tool named `fabric_exec` unless OMP's canonical `sourceInfo.path` identifies this extension's entry exactly.
+
+## Transaction protocol
+
+Run all steps inside one `fabric_exec` invocation. Fabric binds certificates to its `parentToolCallId`, and a later call cannot adopt them.
+
+1. Call `schema.hypothesize` with a nonempty typed evidence set, a label, and a summary. Fabric stores a durable hypothesis bound to the current state head/version, the workspace fingerprint, the workspace generation, and the invocation.
+2. Call `schema.verify`. It checks that every binding is still current, evaluates each evidence item, and fingerprints the workspace before and after the evidence runs. Missing, empty, nonconfirmed, errored, timed-out, cancelled, or workspace-changing evidence fails closed. Only a fully confirmed run issues a cryptographically random certificate bounded by the TTL.
+3. Call `schema.commit`. Fabric requires both write and execute approval. The commit consumes the certificate exactly once by compare-and-swap, checks all bindings again, captures durable before images, applies the bounded declared operations sequentially, and requires a nonempty typed postcondition set. A failed operation, undeclared drift, or a failed postcondition restores every declared path. Fabric records a failed rollback as `quarantined` and a successful one as `rolled_back`.
+4. Call `schema.abort` to close an uncommitted hypothesis and, when present, its certificate. Fabric also abandons active artifacts as soon as their `fabric_exec` invocation ends.
+
+Call known Schema actions through the typed first-class proxy, and keep `tools.call()` for refs you compute at runtime:
+
+```ts
+const hypothesis = await schema.hypothesize({
+  label: "update-parser",
+  summary: "The parser accepts the new local form without changing existing cases",
+  evidence: [
+    { kind: "file_sha256", path: "src/parser.ts", sha256: "sha256:<64 hex>" },
+    { kind: "trusted_command", name: "focused-tests" }
+  ]
+});
+
+const verification = await schema.verify({
+  hypothesisId: hypothesis.hypothesisId
+});
+const { certificate: _certificate, ...safeVerification } = verification;
+if (!verification.verified || !verification.certificate) {
+  if (verification.certificate) {
+    await schema.abort({
+      hypothesisId: hypothesis.hypothesisId,
+      certificate: verification.certificate
+    });
+  }
+  return { status: "failed", verification: safeVerification };
+}
+const parserEvidence = verification.results.find(
+  (result) => result.evidence.path === "src/parser.ts",
+);
+if (!parserEvidence?.observedSha256) {
+  await schema.abort({
+    hypothesisId: hypothesis.hypothesisId,
+    certificate: verification.certificate
+  });
+  return {
+    status: "failed",
+    reason: "missing observed SHA-256",
+    verification: safeVerification
+  };
+}
+
+const commit = await schema.commit({
+  hypothesisId: hypothesis.hypothesisId,
+  certificate: verification.certificate,
+  operations: [{
+    kind: "edit",
+    path: "src/parser.ts",
+    oldText: "old literal",
+    newText: "new literal",
+    expectedSha256: parserEvidence.observedSha256
+  }],
+  postconditions: [
+    { kind: "file_contains", path: "src/parser.ts", literal: "new literal" },
+    { kind: "trusted_command", name: "focused-tests" }
+  ]
+});
+return { status: commit.outcome === "committed" ? "success" : "failed", commit };
+```
+
+## Evidence and preconditions
+
+Evidence is data. The model cannot supply shell content through it. When evidence about an existing file confirms, Fabric returns the `observedSha256` measured at verification time. You can feed that hash into the commit precondition, and no shell access is involved:
+
+- `file_exists: { path }`;
+- `file_absent: { path }`;
+- `file_contains: { path, literal }`, matching by literal containment;
+- `file_sha256: { path, sha256 }`;
+- `trusted_command: { name }`, picking a host-configured command that takes no model arguments.
+
+Fabric never classifies command text, source text, or prose with a regex policy. SHA-256 syntax and provider/config identifiers get ordinary structural validation only.
+
+Trusted commands belong to the trusted computing base. With `shell: false`, the default, Fabric invokes the configured executable directly with the configured static argv, and no shell interprets the line. With `shell: true`, `command` holds the complete trusted shell program. Fabric then normalizes `args` to an empty array, because escaping shell argv portably is unsound. Both forms stay trusted configuration, and the model can never supply them. Make verification commands local, deterministic, and read-only. Fabric detects workspace changes after a command runs. It cannot stop a misconfigured trusted command from causing transient or non-workspace side effects.
+
+Commit operations run exactly and stay local:
+
+- `write` requires `expected: { absent: true }` or `expected: { sha256 }`;
+- `edit` requires `expectedSha256`, and `oldText` must occur exactly once;
+- `delete` requires `expectedSha256`.
+
+Every path must be project-relative and point at a regular file. Fabric rejects absolute paths, `..` escapes, symbolic links in any component, non-file targets, and missing parent directories. A transaction never creates directories. Before-image bytes plus write/edit payload bytes must fit `maxBytes`, and the count of distinct declared paths must fit `maxFiles`.
+
+A hypothesis can set `complexityReduction: true`. The committed outcome reports `complexityReductionCertified: true` only after all its nonempty postconditions pass. The flag certifies those stated postconditions. Proving semantic equivalence or measuring objective complexity falls outside its scope.
+
+## Workspace binding and durability
+
+Inside a Git worktree, the deterministic fingerprint covers:
+
+- the exact `HEAD` identity, or an unborn head;
+- the NUL-delimited index stage listing;
+- path and content/type hashes for every tracked worktree path;
+- path and content/type hashes for untracked, non-ignored paths.
+
+Fabric invokes Git with machine-oriented output and passes `-z` wherever paths appear. It never parses human `git status` prose. The session `cwd` must equal the worktree root. An unsupported tracked non-file entry, such as a submodule directory, makes the snapshot fail with an error. Outside Git, Fabric hashes eligible project files recursively under conservative file and byte bounds, and it skips dependency, build, and cache directories. Host mesh and transaction-journal storage sits outside the protected snapshot, so recording a hypothesis never invalidates itself.
+
+Fabric stores hypotheses, certificates, gate reports, and outcomes as durable mesh records and events under `schema/*` and topic `fabric.schema`. Successful outcomes serialize through a workspace generation compare-and-swap on top of a cross-process commit lock. Before mutation, Fabric writes before images with owner-only permissions under the mesh transaction journal. On initialization, Fabric restores an `applying` journal whose owner process is gone. An unreadable or unrestorable journal stays available for operator quarantine. Fabric consumes certificates by compare-and-swap before the first file operation, so a crash can never make one reusable.
+
+A clean commit advances the Schema generation. It also appends a normal state outcome transition on a best-effort basis. Contention over the state transition cannot falsify the already durable Schema workspace outcome.
+
+## Exact guarantee and limitations
+
+The host process, the filesystem, the trusted Fabric configuration, the configured trusted commands, and OMP's canonical tool lifecycle/provenance all behave as trusted components. Under that assumption, enforce mode guarantees that **only this extension's source-provenanced top-level `fabric_exec`, driving one same-invocation, fresh-certificate `schema.commit` path, can authorize model-originated mutation of regular files under the initialized local workspace**. The guarantee carries explicit preconditions, declared paths, bounded captured before images, nonempty typed postconditions, single-use compare-and-swap consumption, and rollback reporting.
+
+The guarantee covers this defined scope:
+
+- It excludes remote services, network calls, databases, device files, other processes, and writes performed outside Fabric. Enforce mode blocks model access to those provider channels. Its rollback guarantee covers Fabric-managed workspace files.
+- No kernel sandbox protects you from a malicious extension, SDK host, or host process. Trusted host code can invoke effects without model tool calls, and it can falsify lifecycle/provenance data.
+- Nested-call admission relies on OMP delivering Fabric's reserved generated id prefix unchanged, and on Fabric tracking an active owned outer invocation. Arbitrary top-level ids with that prefix still pass through the gate when no owned outer call is active.
+- Trusted commands form an explicit TCB, and unsafe configuration can give them effects.
+- Filesystem rollback cannot be perfectly atomic across process death or hostile concurrent writers. Journals recover declared regular files, and Fabric quarantines failures.
+- File postconditions and tests supply scoped evidence only, and they do not constitute proof.
+- Host metadata under the configured mesh root sits outside the protected fingerprint.

package/docs/skills.md

@@ -0,0 +1,48 @@
+# OMP Fabric skills
+
+OMP Fabric uses a core-first, user-opt-in skill hierarchy.
+
+## Invocation contract
+
+- The model can invoke one skill only: `fabric-exec`. It covers normal OMP core work through `fabric_exec`, `omp.*`, discovery, and stable provider proxies.
+- The user invokes every advanced workflow. Each one declares `disable-model-invocation: true` and stays out of the model catalog. Agent policy forbids reading one autonomously or delegating from one user-only skill to another. The policy governs agent behavior. It is not a filesystem authorization boundary.
+- `/skill:fabric-guide` is the user-only router. It names one exact advanced command and stops there. The router never invokes the recommendation.
+- Each user-facing description summarizes its command. The `fabric-exec` description is the only one that spends always-on model context.
+
+The parent agent behaves like regular OMP until the user explicitly opts into orchestration, recursion, Schema, ambient actors, or swarm coordination.
+
+## Information hierarchy
+
+1. Put required ordered actions and checkable completion criteria in `SKILL.md`.
+2. Use a **hard pointer** for material that the run must load before execution.
+3. Use a **branch pointer** when some runs need the material and others do not.
+4. Use a **soft pointer** for optional depth that improves quality. Correctness does not require it.
+5. Keep skill-owned references beside the skill that owns them. Package-level profiles may point to that single source of truth.
+
+In a packaged `SKILL.md`, write every cross-document path with the `<skill-dir>` marker, for example `<skill-dir>/references/setup.md` or `<skill-dir>/../shared/references/setup.md`. Fabric replaces the marker inline with the directory that contains the loaded `SKILL.md`. Slash-invoked skills resolve through OMP's expanded `<skill location="...">` form. For a direct `SKILL.md` read, Fabric uses the actual read path. The marker is an explicit opt-in by the author. Fabric does not match skill names, enumerate directories, or alter ordinary document reads.
+
+A mandatory pointer serves legibility and single-source maintenance. Per-run token savings are only a side effect. Keep always-required executable code whole even when a split would shorten the skill.
+
+## Authoring rules
+
+- Give each meaning one source of truth.
+- Prefer stable leading words that Fabric already uses: **one program**, **bounded**, **verifier**, **decision point**, **evidence loop**, **CAS claim**, and **outside observer**.
+- Add a checkable **Completion criterion** only when it matches runtime behavior and does not push the agent toward whole-flow retries.
+- Classify each dependency as hard, branch-conditioned, or soft.
+- Apply the no-op test sentence by sentence: cut any text that leaves model behavior unchanged.
+- State the target behavior in positive terms. Reserve prohibitions for safety or invocation boundaries.
+- Preserve the executable TypeScript examples and their contract tests. Expensive fan-out returns `success`, `partial`, or `failed`. A `partial` result on its own implies no automatic whole-flow retry.
+
+## User-invoked workflows
+
+- `/skill:fabric-guide`: choose a workflow.
+- `/skill:fabric-workflow`: run finite fan-out or pipeline work with verification.
+- `/skill:fabric-council`: get role diversity from the same model.
+- `/skill:fabric-fusion`: run multi-model deliberation (compare) or acting (read-only references + one actor).
+- `/skill:fabric-rlm`: decompose context recursively.
+- `/skill:fabric-schema`: gate mutation behind evidence.
+- `/skill:fabric-advisor`: get persistent peer advice.
+- `/skill:fabric-supervisor`: supervise a persistent goal.
+- `/skill:fabric-spec`: supervise spec compliance persistently.
+- `/skill:fabric-ambient`: route directly to an advisor or supervisor profile.
+- `/skill:fabric-swarm`: coordinate durable actors.

package/docs/speculation.md

@@ -0,0 +1,132 @@
+# Speculative programmatic tool calling
+
+Speculative PTC (sPTC; Zhang, 2026, <https://alexzhang13.github.io/blog/2026/spec-ptc/>)
+pre-launches tool calls while the model is still streaming the `fabric_exec`
+program, so tool latency overlaps token generation. Fabric implements the
+streaming-overlap half of the technique with a correctness contract the blog
+leaves informal: a served speculative result is indistinguishable from the
+call having executed at its natural program point.
+
+## Pipeline
+
+```
+message_update (OMP extension event)
+  │  toolcall_start / toolcall_delta / toolcall_end for fabric_exec
+  ▼
+PartialCodeFieldExtractor        src/speculation/partial-json.ts
+  │  incrementally unescapes the streamed `"code"` JSON string field
+  ▼
+LiteralCallScanner               src/speculation/scanner.ts
+  │  reparses only when appended bytes contain `)`; emits completed
+  │  root.fn({...}) calls whose arguments are entirely literals;
+  │  namespaces shadowed by local bindings are tainted for the stream
+  ▼
+eligibility gate                 src/speculation/eligibility.ts
+  │  static Tier-A set / MCP allowlist, then descriptor-level re-check
+  ▼
+ActionRegistry.speculate()       src/core/action-registry.ts
+  │  resolve → gate → prepareArguments → validate → provider.invoke
+  ▼
+FabricSpeculationStore           src/speculation/store.ts
+  │  keyed by (parentToolCallId, ref, stableJsonHash(preparedArgs));
+  │  per-entry AbortController, freshness checker, side-channel replay sink
+  ▼
+ActionRegistry.invoke()          serve-or-reexecute at the real call site
+```
+
+## The correctness contract
+
+1. **Eligibility is read-only by construction.** Tier A is a closed set of
+   refs that are `risk: "read"` with `effect.kind: "none"`, never prompt for
+   approval, and cost nothing when wasted (`omp.read`/`grep`/`find`/`ls`,
+   `memory.recall`/`expand`/`sessions`, `state.get`/`history`/`complexity`,
+   `schema.status`, `compact.status`, `components.list`/`status`/`graph`).
+   The gate re-runs against the resolved descriptor at launch, so a provider
+   or config change that reclassifies a ref closes speculation off.
+2. **Freshness, not staleness.** A stored promise is served only when both
+   conditions hold:
+   - The **mutation epoch** has stayed constant since launch. Every real
+     in-program invocation whose effect kind differs from `"none"` bumps the
+     epoch after the provider call completes (success and failure alike; a
+     failed `bash` may still have written), invalidating all older
+     speculation.
+   - The entry's **freshness checker** still holds. `omp.read` snapshots
+     `{mtimeMs, size}` of the resolved path at launch and re-stats at serve,
+     which also catches external edits. Other Tier-A refs rely on the epoch
+     plus the fact that their stores cannot be written by this guest surface.
+3. **No approval bypass.** Speculation launches only actions that never
+   prompt; the serve path runs the complete normal pipeline (authorize,
+   prepare, validate, approve, audit, result middleware) before answering
+   from the store. On any serve miss the provider call re-executes within
+   that same invocation, so policies observe exactly the calls the program
+   makes.
+4. **Failures always degrade to plain execution.** A speculative call that
+   errored is discarded and the real call runs. A program that never invokes
+   the candidate leaves waste and nothing more. Unserved entries are aborted
+   when the invocation ends, and everything is dropped at turn end.
+5. **Take-once, occurrence-safe.** Serving deletes the entry, so one
+   speculation can never answer two calls. The store also retains only one
+   entry per identical call signature, so a duplicate read past the first
+   executes fresh through the normal pipeline, which is always safe.
+
+Observable differences show up only in observability surfaces: audits record
+`speculated: true` on served calls, and side-channel outputs captured during
+the speculative invoke (`attachMedia`, `updateArguments`, `attachPreview`) are
+replayed into the real audit.
+
+## Entropy compile interplay
+
+The compiled entropy surface participates at both ends of the pipeline. On
+the launch side, speculate() consults it exactly like the invoke path: a
+quarantined ref never pre-launches, and prepared arguments validate against
+the overlaid schema, so the store never warms a call the serve path would
+reject. The serve side is unchanged and stays authoritative: the real call
+runs the full pipeline before the store may answer, so a surface activated
+between launch and serve (a compile landing mid-session) can never serve an
+entry the live surface would reject. Entries launched under an older
+surface remain take-once, TTL-bounded, and drop at turn end like any other
+waste.
+
+## Tier B: MCP reads
+
+MCP tools are `risk: "network"` and excluded by default. Operators opt in per
+tool through config: `speculation.mcpAllowlist: ["exa.*", "github.get_file"]`
+(matched against the ref after the `mcp.` prefix). Cached MCP tool
+annotations, when the runtime surfaces them, override the allowlist in one
+direction only: `destructiveHint: true` or `readOnlyHint: false` refuses even
+an allowlisted tool. Networked results carry no freshness guarantee. The
+epoch still covers in-program effects, yet the world can change behind a
+read; keep the allowlist to stable, idempotent reads.
+
+## Configuration
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `speculation.enabled` | `true` | Master switch (Tier A only unless the MCP allowlist is set). |
+| `speculation.maxConcurrent` | `4` | In-flight speculative call cap; excess candidates are skipped. |
+| `speculation.maxEntries` | `64` | Retained unserved entries per turn. |
+| `speculation.maxBufferBytes` | `2 MiB` | Per-stream cap while extracting the streamed `code` field. |
+| `speculation.entryTtlMs` | `180_000` | Unserved entries older than this are aborted. |
+| `speculation.mcpAllowlist` | `[]` | Tier B patterns: `server.tool`, `server.*`. |
+
+## Deliberately excluded
+
+- `omp.edit`/`write`/`bash`, `state.transition`/`goal`/`verify`/`checkGoal`,
+  every `write`/`execute`/`agent` risk class, and `compact.cancel`
+  (reclassified from a historic mislabeled `"read"` to `"write"`).
+- Calls with non-literal arguments, positional or multi-argument calls (their
+  normalization lives on the guest bridge), and calls on namespace roots the
+  program shadows locally. These are Cases 2 and 3 in the blog (shadow-REPL
+  dependency resolution) and belong to later work. Literal arguments (Case 1)
+  cover the common generated shapes, including `Promise.all` fan-out.
+- `agents.*` sub-calls, the blog's headline target: a wrong speculation
+  spends real tokens. A confirmer-backed variant belongs to a later phase,
+  keyed off the budget ledger.
+
+## Cost profile
+
+Worst case per turn: a handful of wasted local reads (or allowlisted MCP
+reads when the model rewrites mid-stream), one TS reparse per `)`-carrying
+delta debounced to 20 per second, and a bounded stream buffer. Steady state:
+Tier-A hits make `omp.read` effectively free against generation time, which is
+where fabric programs on thinking models spend wall clock.