@arnilo/prism 0.6.0 → 0.8.0

package/docs/knowledge-sync.md

@@ -0,0 +1,84 @@
+# Knowledge synchronization
+
+## What it does
+
+`syncKnowledge` in `@arnilo/prism-memory/rag` pages an injected `KnowledgeConnector`, applies source upserts/deletes/ACL/withhold actions through existing `replaceSource` / `deleteSource` / `setSourceAccess`, and compare-and-swaps an opaque resume cursor on a host `CheckpointStore` **only after that page is fully committed**. Unchanged content hashes skip embedding. Source freshness (`current` / `stale` / `unavailable`) is recorded on ingestion status. `createGoogleDriveConnector` is the first connector: Drive `files.list` bootstrap plus `changes.list` incremental sync.
+
+## When to use it
+
+Use it when a host must keep a RAG corpus aligned with an enterprise file source without a full re-index and without trusting notification payloads as authorization. Do not use it as a general crawler, as a substitute for work-connector file tools, or as a way to infer group membership from Drive.
+
+## Inputs / request
+
+| API/field | Meaning |
+| --- | --- |
+| `syncKnowledge({ connector, checkpoints, checkpoint, store, embedder, scope, ... })` | Runs at most `maxPages` committed pages. |
+| `KnowledgeConnector.listChanges({ cursor, limit, signal })` | Returns `{ changes, resumeCursor, done }`. `done` means caught up. |
+| `KnowledgeChange` | `upsert` (text + contentHash + grants), `delete`, `acl`, or `withhold` (`stale` / `unavailable`). |
+| `createGoogleDriveConnector({ tokenProvider, resolveAccess, driveId?, folderId? })` | Drive adapter. Token is resolved per request. `resolveAccess` is host-owned ACL mapping. |
+| `onInvalidCursor` | `"resync"` (default) restarts bootstrap once; `"fail"` throws `RagSyncCursorError`. |
+| `pageSize` / `maxPages` / `maxRetries` | Defaults 50 / 8 / 3; hard caps 200 / 64 / 8. |
+
+`authorization` on retrieve remains host-verified RAG ACL from Task 11. Empty grants withhold. Missing ACL capability on the store fails closed.
+
+## Outputs / response / events
+
+- `{ pages, upserted, deleted, skipped, withheld, cursor?, exhausted }`
+- Cursor value `{ v: 1, cursor }` under the host checkpoint namespace/key. Crash before CAS replays the same page; `contentHash` skip makes replay embed-free.
+- Ingestion status `freshness` is `current` after a granted upsert, `stale`/`unavailable` after withhold. Deletes remove status.
+
+No tools, no watch-channel authorization, no events.
+
+## Request/response example
+
+```json
+{
+  "scope": { "tenantId": "t1", "resourceId": "docs", "corpusId": "drive" },
+  "result": { "pages": 1, "upserted": 2, "deleted": 0, "skipped": 0, "withheld": 1, "exhausted": false }
+}
+```
+
+## Implementation example
+
+```ts
+import { createMemoryCheckpointStore } from "@arnilo/prism";
+import { createHashEmbedder, createMemoryVectorStore } from "@arnilo/prism-memory";
+import { createGoogleDriveConnector, syncKnowledge } from "@arnilo/prism-memory/rag";
+
+const store = createMemoryVectorStore();
+await syncKnowledge({
+  connector: createGoogleDriveConnector({
+    tokenProvider: () => process.env.DRIVE_TOKEN!, // resolved at the HTTP edge only
+    resolveAccess: (permission) =>
+      permission.type === "user" && permission.emailAddress ? { principalId: permission.emailAddress } : undefined,
+  }),
+  checkpoints: createMemoryCheckpointStore(),
+  checkpoint: { namespace: "prism.rag.sync", key: "handbook", tenantId: "t1" },
+  store,
+  embedder: createHashEmbedder(),
+  scope: { tenantId: "t1", resourceId: "docs", corpusId: "handbook" },
+});
+```
+
+Drive `changes.watch` payloads are wake-ups only — call `syncKnowledge` again; never treat a notification body as ACL or content.
+
+## Extension and configuration notes
+
+- Any `KnowledgeConnector` can be injected; only Google Drive ships. Hosts own OAuth (`drive.readonly` via `createGoogleWorkspaceOAuthProvider({ capabilities: ["files"] })`), checkpoint durability, and `resolveAccess`.
+- Shared drives: pass `driveId`. Folder-scoped bootstrap: pass `folderId` (Drive identifier charset only).
+- Unsupported Google-native types (Sheets, Slides, folders) are skipped. Google Docs export as `text/plain`. Public `anyone`/`domain` permissions withhold the file unless `resolveAccess` maps them.
+- Task 14 can schedule `syncKnowledge` as an ordinary workload; this package does not add a second scheduler.
+
+## Security and performance notes
+
+- Credentials never enter argv, cursors, status, or logs. Token header only.
+- Model-supplied metadata `filter` is still not authorization. Notification payloads are not authorization. Unmapped groups are omitted, not inferred. Unmapped `anyone`/`domain` withholds the source.
+- 403 on content → `unavailable` withhold (empty grants). 404/`removed`/`trashed` → delete. 400/410 page tokens → `RagSyncCursorError`. 429 → `RagSyncThrottleError` with bounded retries.
+- Pages are bounded. Unchanged hashes perform no embedding. Only committed pages CAS the cursor.
+
+## Related APIs
+
+- [Retrieval-augmented generation](rag.md): `replaceSource`, document ACL, retrieval.
+- [Work connectors](work-connectors.md): GWS CLI file tools are a different surface.
+- [Credentials and redaction](credentials-and-redaction.md): OAuth token providers.
+- [Live and end-to-end testing](live-testing.md): `PRISM_TEST_DRIVE_ACCESS_TOKEN` skip-not-fail probe.

package/docs/language-intelligence.md

@@ -18,7 +18,7 @@
 
 Use when a host wants IDE-like language intelligence without embedding a parser framework or trusting model-chosen server commands. Wire host-pinned server binaries (for example `typescript-language-server --stdio`) and gate renames with the same `ExecutionPolicy` used for write/edit tools.
 
-Do not use this as a sandbox, tool registry, or process session manager. Optional process-session registration of LSP children can use `createProcessSessions` ([Process sessions](process-sessions.md)).
+Do not use this as a sandbox, tool registry, or process session manager. Optional process-session registration of LSP children can use `createProcessSessions` ([Process sessions](process-sessions.md)). When paired with a container sandbox, language server processes, shell operations, and filesystem tools must agree on the single declared workspace root (typically `/workspace` inside Docker) to maintain workspace coherence and prevent split-brain states.
 
 ```ts
 import { createLanguageIntelligence } from "@arnilo/prism-coding-tools/agent";

package/docs/live-testing.md

@@ -71,22 +71,25 @@ Set only the rows you want to run; everything else skips. Least-privilege scope
 | `web-tools/obscura-live` | active | `PRISM_LIVE_OBSCURA` + `PRISM_OBSCURA_BIN` | — | Local obscura CLI binary; suite fails closed if flag set without binary. | Local process, no API spend. |
 | `memory/observational-live` | active | `PRISM_LIVE_OBSERVATIONAL_MEMORY_TESTS` + `OPENAI_API_KEY` | `PRISM_LIVE_OPENAI_MODEL` (not wired yet) | Reuses the OpenAI key as the compaction worker provider. | A few small summarization requests. |
 | `memory/compaction-llm-live` | active | `PRISM_LIVE_COMPACTION_TESTS` | — | Stub leg today: live summary-provider checks are wired by plans/064 Task 6 (provider key + model env TBD there). | n/a until wired. |
-| `office/libreoffice-golden` | active | `PRISM_TEST_LIBREOFFICE` | — | Local LibreOffice binary renders golden documents; no secret. | Local process, no API spend. |
-| `office/drawio-live` | active | any of: `PRISM_LIVE_DRAWIO_URL` / `PRISM_TEST_DRAWIO_URL` | — | Operator-hosted drawio export service URL (not a secret). | 1-2 export requests to your own service. |
+| `work/libreoffice-golden` | active | `PRISM_TEST_LIBREOFFICE` | — | Local LibreOffice binary renders golden documents; no secret. | Local process, no API spend. |
+| `work/drawio-live` | active | any of: `PRISM_LIVE_DRAWIO_URL` / `PRISM_TEST_DRAWIO_URL` | — | Operator-hosted drawio export service URL (not a secret). | 1-2 export requests to your own service. |
 | `core/postgres` | active | `PRISM_TEST_POSTGRES_URL` | — | Throwaway PostgreSQL database URL (sessions + enterprise + event-source + memory vector legs). | Local/container DB, no API spend. |
 | `core/nats` | active | `PRISM_TEST_NATS_URL` | — | NATS server URL with JetStream enabled. | Local/container server, no API spend. |
 | `coding-tools/docker-sandbox` | active | `PRISM_TEST_DOCKER_SANDBOX` + `PRISM_TEST_DOCKER_BIN` + `PRISM_TEST_DOCKER_IMAGE` + `PRISM_TEST_DOCKER_USER` | — | Local Docker daemon + pinned minimal sandbox image; no secret. | Local containers, no API spend. |
+| `coding-tools/e2b-sandbox-live` | active | `PRISM_TEST_E2B_API_KEY` | — | E2B API key; least privilege: one throwaway sandbox, no production templates. | 1 create + 2 exec + filesystem-only pause + connect/resume + kill. |
+| `work/mistral-ocr-live` | active | `PRISM_TEST_MISTRAL_API_KEY` | — | Mistral OCR API key; least privilege: one throwaway 2-page sample PDF, no Files API upload. | 1 OCR request against mistral-ocr-latest. |
 | `core/keychain` | active | `PRISM_TEST_KEYCHAIN` | — | Real OS keychain; writes throwaway test entries only. | Local, no API spend. |
 | `acp/client-smoke` | active | `PRISM_TEST_ACP_CLIENT` | — | Real ACP SDK client over stdio in a subprocess; sandboxed, policy never disabled. | Local process, no API spend. |
 | `canaries/deployed` | active | `PRISM_LIVE_CANARIES`; optional: `PRISM_CANARY_TIMEOUT_MS` `PRISM_CANARY_REPORT` | — | Deployed prism provider/MCP/A2A endpoints; script itself validates all PRISM_CANARY_* URL/token vars and credential-free HTTPS. | 1-4 bounded requests (64 KiB JSON cap) against your deployments. |
 | `providers/azure` | active | `PRISM_LIVE_PROVIDER_TESTS` + `AZURE_OPENAI_ENDPOINT` + `AZURE_OPENAI_API_KEY` + `PRISM_LIVE_AZURE_MODEL` | `PRISM_LIVE_AZURE_MODEL` (default `gpt-5.1`) | Azure OpenAI resource key. | 3-4 requests on the configured deployment. |
-| `providers/bedrock` | active | `PRISM_LIVE_PROVIDER_TESTS` + `AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY` + `AWS_REGION` | `PRISM_LIVE_BEDROCK_MODEL` (default `us.anthropic.claude-haiku-4-5-20251001-v1:0`) | AWS access key + secret (SigV4). | 3-4 requests on haiku-class model. |
+| `providers/bedrock` | active | `PRISM_LIVE_PROVIDER_TESTS` + `AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY` + `AWS_REGION` | `PRISM_LIVE_BEDROCK_MODEL` (default `us.anthropic.claude-haiku-4-5-20251001-v1:0`) | AWS access key + secret (SigV4). | 6-8 requests on haiku-class model (compatible SSE + native Converse/ConverseStream). |
 | `providers/vertex` | active | `PRISM_LIVE_PROVIDER_TESTS` + `GOOGLE_VERTEX_PROJECT` + `PRISM_VERTEX_ACCESS_TOKEN` | `PRISM_LIVE_VERTEX_MODEL` (default `gemini-2.5-flash`) | Pre-minted Vertex bearer token (e.g. gcloud auth print-access-token). | 3-4 requests on flash-class model. |
 | `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). |
 | `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/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. |
 | `mcp/client-smoke` | active | `PRISM_TEST_MCP_CLIENT` | — | Real @modelcontextprotocol/client SDK over a real stdio subprocess serving createPrismMcpServer. | Local only; ≤30s. |
@@ -101,6 +104,8 @@ Set only the rows you want to run; everything else skips. Least-privilege scope
 | `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. |
 | `ag-ui/conformance` | active | — (hermetic leg) | — | AG-UI + ACP conformance suites: real-event replay over the acp/a2a/ag-ui protocol surfaces (fixture agents, real event-source wire semantics). | Hermetic; no network. |
 | `prism-providers/conformance` | active | — (hermetic leg) | — | Plan-065 machine-checked thinking coverage: every first-party reasoning catalog model declares capabilities.thinkingLevels + a compat.thinkingFamily stamp and emits a legal effort field on the wire (14 catalogs walked hermetically). | free |
+| `channels/telegram-live` | active | `PRISM_LIVE_TELEGRAM` + `TELEGRAM_BOT_TOKEN`; optional: `PRISM_LIVE_TELEGRAM_CHAT_ID` | — | Operator-owned Telegram bot token. getMe + 1s poll; send only if PRISM_LIVE_TELEGRAM_CHAT_ID names a chat you operate. Never creates contacts. | 1 getMe + 1 getWebhookInfo (+ optional 1 sendMessage). |
+| `channels/signal-live` | active | `PRISM_LIVE_SIGNAL` + `PRISM_LIVE_SIGNAL_SOCKET` + `PRISM_LIVE_SIGNAL_ACCOUNT` + `PRISM_LIVE_SIGNAL_TERMS_VERSION`; optional: `PRISM_LIVE_SIGNAL_RECIPIENT_UUID` | — | Existing private signal-cli v0.14.8 Unix socket and account you already operate. Never registers or links. Send only to PRISM_LIVE_SIGNAL_RECIPIENT_UUID. | 1 subscribeReceive + health (+ optional 1 send). |
 <!-- generated:live-matrix:end -->
 
 ## Strict CI workflow

package/docs/mcp-tools.md

@@ -48,7 +48,7 @@ await bridge.listResources();
 await bridge.getPrompt("review", { topic: "security" });
 ```
 
-Roots and sampling callbacks are **deprecated with MCP 2026-07-28 (SEP-2577)** and kept only for existing legacy callers; Synapta adds nothing on those surfaces and they may be removed when the protocol revision does (earliest per spec: a revision released on or after 2027-07-28). Elicitation is the active capability: on the modern era a server answering a tool call with `input_required` is fulfilled by the SDK's MRTR driver against the same `elicitation` callback, capped by `maxMrtrRounds` (default 10, the SDK's own bound — the option can only tighten it) with the call timeout as the outer ceiling; on the legacy era the same handler serves direct `elicitation/create` requests. `humanInteraction: true` remains mandatory for accepted elicitation, and no hand-written retry/state machinery exists on either path.
+Roots and sampling callbacks are **deprecated with MCP 2026-07-28 (SEP-2577)** and kept only for existing legacy callers; Prism MCP adds nothing on those surfaces and they may be removed when the protocol revision does (earliest per spec: a revision released on or after 2027-07-28). Elicitation is the active capability: on the modern era a server answering a tool call with `input_required` is fulfilled by the SDK's MRTR driver against the same `elicitation` callback, capped by `maxMrtrRounds` (default 10, the SDK's own bound — the option can only tighten it) with the call timeout as the outer ceiling; on the legacy era the same handler serves direct `elicitation/create` requests. `humanInteraction: true` remains mandatory for accepted elicitation, and no hand-written retry/state machinery exists on either path.
 
 Server capability matrix for the modular TypeScript SDK v2 (`@modelcontextprotocol/client` + `@modelcontextprotocol/server` 2.0.0): tools/resources/prompts and their list-change notifications are supported through official registrations; roots/sampling/form+URL elicitation are supported as explicit client callbacks. Missing server resources/prompts throw `McpUnsupportedCapabilityError` with `ERR_PRISM_MCP_UNSUPPORTED_CAPABILITY`. Resource/prompt results and sampling/elicitation inputs/results are bounded JSON. Accepted form/URL elicitation requires host-only `humanInteraction: true`; bridge strips marker before protocol output and fails closed when absent. Automatic root discovery/consent, model selection, credential resolution, URL navigation, generic command proxying, and custom JSON-RPC are unsupported.
 
@@ -221,6 +221,7 @@ Remote MCP tools default to `external_mutation`/`unsupported` unless the host `e
 | Untrusted subprocess (stdio) | Explicit `command` / `args` / `env` / `cwd`; review before deploy |
 | SSRF / DNS rebinding / redirects (HTTP) | Exact HTTPS origins; credentials/fragments/redirects denied; every DNS answer public; one address pinned per request; explicit loopback-only HTTP escape hatch. Since 0.2.1 the client transport re-routes through the shared core `pinnedFetch` primitive (DNS-pinned fetch) with byte-identical `McpBridgeError`/`McpOAuthError` wrapping |
 | Hostile discovery / schema compilation | Raw SDK `tools/list` requests avoid SDK Ajv output-schema compilation; finite pages/tools/cursors/metadata/schema totals; failed refresh leaves previous tools unchanged |
+| Stale or revoked tool after refresh | Loaded `execute` compares the listing digest (schema + effect) to the current remote tool; mismatch or deletion fails closed before `tools/call` |
 | Tool-name shadowing | Prefixed names + `createToolRegistry({ duplicate: "error" })` |
 | MCP Apps metadata/HTML | Explicit extension acknowledgement; bounded nested metadata; app-only tools absent from model list; only linked `ui://` HTML/MIME resource body reaches the host renderer |
 | Oversized/deep/wide server output | One aggregate byte/depth/property walk covers content, structured content, compatibility `toolResult`, and bounded remote errors before `ToolResult` |
@@ -304,6 +305,7 @@ The scenario stays sandboxed (read-only echo tool, authorize-gated denial, no po
 
 ## Related APIs
 
+- [Connected apps](connected-apps.md): identity-bound host admission and lifecycle for a small set of MCP bridges.
 - [Agent identity](agent-identity.md): optional verified identity on MCP authorize results
 - [Tools](tools.md): registry, dispatch, validation
 - [Web search, fetch, and extraction](web-tools.md): preferred direct bounded Brave/Exa/Firecrawl production path

package/docs/memory-fabric.md

@@ -0,0 +1,416 @@
+# Memory fabric
+
+## What it does
+
+Typed notes over the memory stores a host already configured. `createMemoryFabric()` does not add a
+store, a database, or a second memory engine: it writes notes through `createMemory()` and reads them
+back with the same consent, redaction, and lineage rules.
+
+| Kind | Backing store | Notes |
+| --- | --- | --- |
+| `fact` | vector store | `metadata.fabric` carries the note fields. |
+| `procedure` | vector store | Never returned by an untyped recall; request `kinds: ["procedure"]`. |
+| `file` | vector store | `path` is required; `content` defaults to the path. The fabric does not read the file. |
+| `working` | working store | Labeled block under the `_fabric.blocks` key of the scope's working value. |
+| `episode` | observational memory | A **view** over an existing observation id. Nothing is written. |
+
+`recall` returns ranked notes plus a parallel `explain` row for each hit, and `searchConversation`
+lexically searches the current branch and returns the observational-memory page around each match.
+`tools()` builds the five governed tools a host may hand to an agent, and `forget` tombstones one note
+or working block.
+
+### Relationship to observational memory
+
+Observational memory stays **episodic**: its ledger is still the source-backed record of what happened
+in a session, its observer/reflector/dropper workers are still the only writers of observations and
+reflections, and nothing here re-observes, re-folds, or re-scores a transcript. The `episode` kind is a
+**view**: it reads an existing 12-hex observation id through the attached session's ledger and stores
+nothing, so an episode note cannot disagree with the observation it names, and a valid id that survives
+folding keeps working without a copy. Semantic (`fact`, `procedure`, `file`) and working notes are the
+fabric's own rows in the stores `createMemory()` already owns; they never become observations. Hosts
+that want a concluded case promoted out of the ledger write the generalizable part as a `procedure` and
+keep the specifics as a `fact` or an `episode` view — promotion is an explicit host decision, and one
+that a case conclusion filed as a `procedure` fails an invariant on (see the eval fixture below). The
+fabric can make that decision cheap without turning it into an implicit one: for `fact`/`procedure`,
+`remember({ reflectionId })` derives the note content from a reflection that carries an explicit
+`om.scope.bound` entry on a **closed** work scope ([work-scope index](compaction-observational-memory.md)).
+An unknown, unbound, or open-scope-only reflection is rejected, the note records the bind it came from
+as `promotedFrom: { reflectionId, scopeId }`, and no other field changes — the fold, consent, and
+worker rules of a normal `fact`/`procedure` write all still apply.
+
+An imported fabric starts nothing: no workers, no timers, no tools, no context provider until a host
+calls one of its methods. Calling `tools()` registers nothing anywhere — it returns definitions.
+
+### Write path (consolidation, default on)
+
+A `fact`, `procedure`, or `file` write first recalls the nearest same-kind note (one bounded
+`memory.recall` batch using the same oversample factor recall uses) and then folds:
+
+| Nearest note | Write |
+| --- | --- |
+| below `consolidate.threshold` (default 0.85) | insert a new row. |
+| the same note — same tokens, or the same `path` for `file` | rewrite that row in place: same id, annotations union, the new note's claims win. |
+| the same subject with changed content | set `validTo` on the old row, then insert a new row carrying `supersedes`. |
+
+A `file` note never folds across paths (two paths are two documents), `working` notes are already
+keyed by block label, and `episode` views write nothing. A rewrite keeps the row's `createdAt`,
+consent, importance, and every non-fabric metadata key; an explicit `id` or `supersedes` from the
+caller disables auto-folding for that write.
+
+### Workers (opt-in)
+
+Both workers run inline (awaited) after the write, see redacted text only, call no model and no
+tools, and are skipped entirely by `passive: true`:
+
+| Worker | Option | Does |
+| --- | --- | --- |
+| Linker | `linker: { enabled, topK }` (off by default, `topK` 3) | stores `related` edges to the closest neighbors, weight = embedding similarity. |
+| Evolution | `evolution: { enabled, maxPatches }` (off by default) | unions the new note's keywords into neighbor notes and fills a missing neighbor `context` — never content, validity, consent, or `sourceEntryIds`. |
+
+Workers run only while a session is attached (`attach`), so an unattached fabric enriches nothing even
+when the options ask for it — the plain `remember` path writes notes and stops there.
+
+## When to use it
+Use it when a host wants durable, time-bounded notes (facts, procedures, file references, promoted
+episodes) alongside the plain working/semantic memory it already has, or wants one call that returns
+both the matching notes and why they matched. Skip it when plain `createMemory()` recall is enough —
+the fabric is an opt-in layer, not a replacement.
+
+## Inputs / request
+
+**Option surfaces** — `createMemoryFabric` takes `CreateMemoryFabricOptions`; `attach` takes `MemoryFabricAttachOptions`; `tools()` returns definitions configured by `MemoryFabricToolsOptions`; the reflection paths use `MemoryFabricWriteOptions` and `MemoryFabricRecallOptions`; and the opt-in workers are configured by `MemoryFabricConsolidationOptions`, `MemoryFabricLinkerOptions`, `MemoryFabricEvolutionOptions`, `MemoryFabricConversationSearchOptions`, and `CreateFabricFileJailOptions`.
+
+`createMemoryFabric(options)`
+
+| Field | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `memory` | `Memory` | yes | An existing `createMemory()` instance; supplies scope, embedder, stores, consent, and limits. |
+| `observational` | `{ session: { entries() } }` | only for `episode` | An attached observational-memory session (`om.attach(session)` result satisfies it). |
+| `consolidate` | `boolean \| { threshold? }` | no | Default `true`; `false` writes unconditionally, `threshold` (default 0.85) is the cosine floor for folding. |
+| `linker` | `boolean \| { enabled?, topK? }` | no | Default off; `topK` defaults to 3 and is capped at 32. |
+| `evolution` | `boolean \| { enabled?, maxPatches? }` | no | Default off; `maxPatches` defaults to the worker per-turn budget and is capped at 32. |
+| `passive` | `boolean` | no | `true` skips both opt-in workers; consolidation is part of the write path and still runs. |
+| `workerLimits` | `MemoryWorkerLimitOptions` | no | Observational-memory worker caps resolved by `resolveMemoryWorkerLimits` (patches per write, patch payload bytes). |
+
+`remember(input)` fields:
+
+| Field | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `kind` | `"working" \| "episode" \| "fact" \| "procedure" \| "file"` | yes | Note kind; unknown kinds throw. |
+| `id` | 12-hex string | `episode` yes | Note id (the observation id for `episode`). Derived when omitted for `fact`/`procedure`/`file`; rejected for `working`. |
+| `content` | non-empty string | except `episode`, or `fact`/`procedure` with `reflectionId` | Note text, capped by `limits.maxEntryTextChars`. |
+| `reflectionId` | 12-hex string | no | Derives content from an observational-memory reflection; `fact`/`procedure` only, rejected with `content`, and the reflection must be bound to a closed work scope. |
+| `block` | `[a-z0-9][a-z0-9._-]{0,63}` | `working` yes | Block label; the working note id is derived from it. |
+| `path` | non-empty string | `file` yes | Workspace path; stored as metadata. |
+| `tRef` / `validFrom` / `validTo` | ISO timestamp | no | Reference time and validity window: `validFrom` inclusive, `validTo` exclusive. |
+| `keywords` / `tags` / `sourceEntryIds` | non-empty strings | no | Annotations; `sourceEntryIds` are session entry ids. |
+| `context` | non-empty string | no | Short context line. |
+| `links` | `{ id, relation?, weight? }[]` | no | Edges to other note ids (12-hex). |
+| `supersedes` | 12-hex string | no | Id of the note this one replaces. |
+| `importance` | number in [0,1] | no | Stored recall weight. |
+| `consent` | `MemoryConsentInput` | no | Forwarded to `createMemory()`; the fabric never widens visibility. |
+
+`recall(query, options)`
+
+| Field | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `kinds` | `MemoryNoteKind[]` | `["fact", "file"]` | Kinds to return; `procedure` and `working` are opt-in. Empty or unknown kinds throw. |
+| `asOf` | ISO string or `Date` | now | Evaluation point for `validFrom` / `validTo`. |
+| `topK` | number | `memory.limits.topK` | Maximum hits, clamped by the memory hard cap. |
+| `budget` | positive integer | none | Ceiling on the summed `tokenCount` of the returned hits. The best hit is always returned; the ranking stops at the first note that would not fit. |
+| `scoring` | `RecallScoringOptions` | none | Passed through to `memory.recall()`. |
+
+`searchConversation(query, options)` — lexical search over the current branch, each hit carrying the
+observational-memory page around it. Requires the `observational` source; without it the call fails
+closed.
+
+| Field | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `limit` | page limit | 20 | Messages per page around a hit; the observational-memory limit (hard cap 100, out of range throws). |
+| `direction` | `"backward" \| "forward"` | `"backward"` | Page direction, same semantics as the branch page. |
+| `detail` | `"summary" \| "full"` | `"summary"` | Page rendering detail. |
+| `topK` | number | 5 | Matching messages returned; hard cap 100. |
+| `signal` | `AbortSignal` | none | Aborts the scan or the page loop. |
+
+`tools(options)` — five inert tool definitions for the host to register. `root` is the directory
+the file tools are jailed to; without it those tools fail closed and only block operations work.
+
+| Tool | Kind | Arguments | Does |
+| --- | --- | --- | --- |
+| `memory.view` | read | `{ path? }` | lists a directory inside `root` (default: the root), names and byte sizes, at most 200 entries. |
+| `memory.read` | read | `{ path }` | reads one file inside `root`, cut at the byte cap and flagged when truncated. |
+| `memory.insert` | edit | `{ text, block? \| path? }` | appends to a labeled working block, or to a file inside `root` and refreshes that file's note. |
+| `memory.recall` | search | `{ query, kinds?, topK?, asOf?, budget? }` | `recall()` with the same kinds, validity, and budget rules. |
+| `memory.forget` | delete | `{ id? \| block?, hold? }` | `forget()` with the same tombstone rules. |
+
+`forget(input)` — `{ id?, block?, hold? }`, exactly one of `id`/`block`:
+
+| Target | Effect |
+| --- | --- |
+| `id` | `memory.forget()` in this memory's own thread scope: rows are marked and deleted, or kept as a `legal_hold` when `hold: true`. |
+| `block` | the block's content is cleared and stamped with `forgottenAt`, freeing the label for a later insert. |
+
+The result is `{ id?, block?, deleted, held }` — `deleted` counts removed rows (1 for a tombstoned
+block, 0 when the note was held or was not in this scope).
+
+`attach(session, options?)` — the one way to authorize a session, and the only way the workers run.
+It returns `{ session, contextProvider, settings, detach() }`; `detach()` (or aborting
+`options.signal`) takes the session back. Attaching fails closed on anything that is not a session
+(no id, or a non-function `entries`) and on a session that is not the fabric's `observational`
+session — an attached session may not read another branch. Nothing happens per turn: no timers, no
+loop, no session proxy; `attach` only flips the gate that `tools()` and the workers read.
+
+`createContextProvider(options?)` — the context seam, with the same options as
+`memory.createContextProvider` (`includeWorking`, `includeSemantic`, `query`, `topK`,
+`messageRange`, `name`). Blocks are tagged exactly like `createMemory`'s: working memory as
+`working-memory`, recall as `semantic-memory` — the fabric is semantic memory, so it adds no block
+type and no layer id. With the attention compiler off, these blocks still reach the provider input
+through the normal context assembly.
+
+### Attach and the definition recipe
+
+A host registers the provider under any name it likes and lists that name in the definition; core
+`AgentDefinition` has no fabric field and takes on no memory dependency:
+
+```ts
+registries.contextProviders.register("memory-fabric", fabric.createContextProvider());
+
+const agent = await resolveAgentDefinition(
+  { name: "assistant", model, context: ["memory-fabric"], tools: ["memory.recall"] },
+  { registries, providerSource },
+);
+
+const session = createAgentSession({ agent });
+fabric.attach(session); // tools run and workers enrich only from here
+```
+
+`context: ["memory-fabric"]` resolves through `registries.contextProviders`, so it works only when
+the host registered that name; omitting it is the default (an agent with no fabric injection).
+
+A runnable end-to-end demo — notes, folding, supersession, the attach gate, the provider, and
+`forget` — lives in `examples/memory-fabric.ts` (network-free, `node examples/memory-fabric.ts`).
+
+### Tools and the file jail
+
+Every tool call is refused unless the fabric was attached to the calling session. `view`, `read`, and
+the `path` form of `insert` resolve against `root` and fail closed on anything that leaves it — `..`
+segments, absolute paths, and symlinks are all rejected with a `MemoryValidationError`, and no file is
+touched when the check fails. A refused insert leaves the file and the working-memory version exactly
+as they were.
+
+`insert` appends: a working block grows to `limits.maxEntryTextChars` (over that it throws and the
+stored version is untouched, with the write versioned against concurrent writers), and a file grows to
+`maxFileBytes` (default 50 KiB, hard cap 1 MiB) with a newline added when the file already has content
+and the text does not start with one. A file insert also refreshes the `kind: "file"` note for that
+path with the file's text, so recall can find what was written; the indexed text is truncated at
+`limits.maxEntryTextChars` and the tool reports `noteTruncated` when it was. Parent directories are
+created inside the jail as needed — `view` never creates anything.
+
+## Outputs / response / events
+
+`remember` resolves to one `MemoryNote`: `{ id, kind, content, ingestedAt, tokenCount, ... }` plus the
+optional fields above, `scope`, and (for `working`) `block` or (for `file`) `path`. A reflection-derived
+note also carries `promotedFrom: { reflectionId, scopeId }`. A folded write
+returns the surviving id: the rewritten row for a same-note fold, and a new id carrying `supersedes`
+for a superseded one.
+
+`recall` resolves to `{ hits, explain }`: `hits` are notes plus `score` and, when scoring wasrequested, `similarity` and `recency`; `explain[i]` is the parallel provenance row for `hits[i]`
+(`{ id, score, similarity?, recency?, importance?, link, valid }`). A hit whose `explain.link` is
+true arrived through a `links` edge from a seed hit rather than the query ranking. `working` notes are
+not recall hits — they belong to the working value — and a note recorded with `validFrom`/`validTo`
+outside `asOf` is omitted.
+
+`searchConversation` resolves to `{ hits, scanned }`: each hit is
+`{ entryId, score, timestamp, page }`, where `score` is the share of query terms the message contains
+and `page` is the `recallObservationalMemoryBranchPage` result for that message (entries, cursors, and
+rendered text). Events are whatever `createMemory()` already emits; the fabric adds none.
+
+## Request/response example
+
+```json
+{
+  "kind": "fact",
+  "id": "2f9c1a0b7d3e",
+  "content": "User prefers metric units",
+  "validFrom": "2026-01-01T00:00:00.000Z",
+  "tags": ["prefs"],
+  "metadata": { "fabric": { "v": 1, "kind": "fact", "validFrom": "2026-01-01T00:00:00.000Z", "tags": ["prefs"] } }
+}
+```
+
+`recall` response shape: `hits[i]` and `explain[i]` describe the same note.
+
+```json
+{
+  "hits": [
+    { "id": "2f9c1a0b7d3e", "kind": "fact", "content": "User prefers metric units", "tokenCount": 7, "score": 0.91, "similarity": 0.91 },
+    { "id": "7c4d2f10ab98", "kind": "fact", "content": "Rollout health lives on the deploy dashboard", "tokenCount": 11, "score": 0.42 }
+  ],
+  "explain": [
+    { "id": "2f9c1a0b7d3e", "score": 0.91, "similarity": 0.91, "link": false, "valid": true },
+    { "id": "7c4d2f10ab98", "score": 0.42, "link": true, "valid": true }
+  ]
+}
+```
+
+`searchConversation` response shape (one hit, abbreviated page):
+
+```json
+{
+  "hits": [
+    {
+      "entryId": "m4",
+      "score": 1,
+      "timestamp": "2026-01-01T00:03:00.000Z",
+      "page": { "found": true, "cursor": "m4", "direction": "backward", "limit": 2, "entries": [], "nextCursor": "m2", "text": "..." }
+    }
+  ],
+  "scanned": 12
+}
+```
+
+## Implementation example
+
+```ts
+import { createMemory, createMemoryVectorStore, createHashEmbedder } from "@arnilo/prism-memory";
+import { createMemoryFabric } from "@arnilo/prism-memory/fabric";
+
+const memory = createMemory({
+  tenantId: "acme",
+  resourceId: "user-1",
+  threadId: "thread-1",
+  embedder: createHashEmbedder(),
+  vectorStore: createMemoryVectorStore(),
+});
+
+const fabric = createMemoryFabric({ memory, linker: { enabled: true, topK: 3 } });
+
+await fabric.remember({ kind: "fact", content: "User prefers metric units", tags: ["prefs"] });
+await fabric.remember({ kind: "procedure", content: "Deploy via canary first" });
+await fabric.remember({ kind: "working", block: "core", content: "Prefers terse output" });
+
+// Same note: rewritten in place, same id, annotations unioned.
+const repeated = await fabric.remember({ kind: "fact", content: "User prefers metric units", keywords: ["units"] });
+// Changed fact: the old row gets validTo, this note carries supersedes.
+const changed = await fabric.remember({ kind: "fact", content: "User prefers metric units and Celsius" });
+// changed.supersedes → the id of the note it replaced; changed.links → derived `related` edges.
+
+const { hits, explain } = await fabric.recall("preferred units", {
+  scoring: { recencyWeight: 0.3, importanceWeight: 0.2, halfLifeMs: 7 * 86_400_000 },
+  budget: 400,
+});
+// hits[0].content → "User prefers metric units"; procedures stay out until kinds: ["procedure"].
+// explain[1].link === true → that hit came in through a links edge from a seed hit.
+```
+
+Conversation search over an attached session (`om.attach(session)` result):
+
+```ts
+const fabric = createMemoryFabric({ memory, observational: om });
+const { hits, scanned } = await fabric.searchConversation("canary rollout", { limit: 4, topK: 3 });
+// hits[0].page.entries → the four branch messages ending at the match; hits[0].page.text → rendered window.
+```
+
+Giving the agent the tools, jailed to a notes directory:
+
+```ts
+const tools = fabric.tools({ root: "/srv/agent/memories", maxFileBytes: 50 * 1024 });
+// tools.map((tool) => tool.name) →
+// ["memory.view", "memory.read", "memory.insert", "memory.recall", "memory.forget"]
+```
+
+Attaching a session and handing its provider to a definition:
+
+```ts
+registries.contextProviders.register("memory-fabric", fabric.createContextProvider({ includeWorking: true }));
+const agent = await resolveAgentDefinition(
+  { name: "assistant", model, context: ["memory-fabric"], tools: ["memory.recall"] },
+  { registries, providerSource },
+);
+const attached = fabric.attach(createAgentSession({ agent }));
+// attached.settings.linker.enabled → whether enrichment is live for this fabric
+// attached.contextProvider → the same provider the registry now holds
+attached.detach();
+```
+
+## Extension and configuration notes
+
+The host owns the embedder, vector store, working store, tenant/resource/thread scope, redactor,
+`requireConsent` mode, and working-memory schema — the fabric only writes through them. `metadata.fabric`
+is the reserved metadata key on vector records, and `_fabric.blocks` is the reserved key inside the
+working value; a host schema must allow both if it validates the working value. A host that validates
+working values still sees every block append, so its schema remains the last word on block content.
+Episode views require an
+observational-memory session passed as `observational`; without it, `kind: "episode"` fails closed as
+does `searchConversation`. `budget` bounds injected note tokens; `topK` bounds both the primary hits
+and the 1-hop expansions.
+Enrichment is opt-in per fabric: `consolidate` (default on, `threshold` in [0,1]), `linker.topK` and
+`evolution.maxPatches` (both capped at 32), `passive` to skip the workers, and `workerLimits` for the
+observational-memory worker caps. Tool schemas are small and fixed, and a host may rename or wrap any
+definition it registers.
+
+## Security and performance notes
+
+Everything here is opt-in and inert by default: importing the subpath starts no worker, no timer, and
+no context provider, `tools()` registers nothing, and no note reaches a prompt until a host registers a
+provider and attaches a session. No fabric path calls a model — not on write, not on fold, not in the
+linker or evolution workers, and not in `searchConversation` (lexical coverage, no embedder call) — so
+there is no LLM-on-write step an injected document could steer, and no inferred field to audit.
+
+Kinds keep the process/case split: `procedure` is the reusable recipe and never comes back from an
+untyped recall, while case-bound specifics belong in `fact`/`file` or in an `episode` view. A case
+conclusion filed as a `procedure` is caught by the package's invariant fixture
+(`caseConclusionsNotProcedures`, wrapped as `defineScorer({ invariant: true })` by a host harness),
+which scores 0 rather than averaging away.
+
+Text and metadata are redacted by `createMemory()` before embedding, and recall hits are redacted
+before they reach the caller; the fabric adds no path around either. Consent, visibility, revocation,
+and `requireConsent` filtering are applied inside `memory.recall()`, so a fabric recall can never see
+more than the underlying memory — including for linked neighbors, which are promoted from the same
+recalled batch rather than read back by id. The lineage plane is the only revocation plane: a note
+whose source was corrected, revoked, forgotten, or put on legal hold is excluded from recall **and**
+from injected context before any background cleanup runs, exactly as `createMemory()` excludes it —
+legal-hold rows are retained but never injected, and the fabric does not invent a second tombstone or a
+parallel derivation table (it stores `sourceEntryIds`/`supersedes` and lets that plane decide).
+A malformed or foreign `metadata.fabric` payload is
+skipped rather than injected, and unknown kinds fail closed at write time. The fabric echoes no query
+text into hits, explain rows, or events; explanations carry scores and provenance flags only.
+
+One `remember` of a fact is one bounded `memory.recall` candidate batch plus one
+`memory.remember(..., { wait: true })` call — no extra full scan, no extra round trip — and it waits so
+the note (and any fold) is durable when the call resolves. Recall requests an explicit oversample (up
+to `RECALL_OVERSAMPLE` × `topK`, bounded by the hard top-K cap) because kind and validity filtering
+happen after ranking; working-store byte caps and `maxEntryTextChars` are unchanged.
+
+Recall costs exactly one store query: 1-hop expansion is served from the oversampled batch the query
+already returned (up to `topK` extra hits), so a linked neighbor outside that window is not fetched —
+`Memory` has no id lookup. `searchConversation` scans the branch entries the session already returned
+(`scanned` reports how many), scores them by query-term coverage, then calls the observational-memory
+page helper per returned hit; the page limit is validated by that helper (1..100), so the scan and the
+result are both bounded.
+
+The workers have no model, no tools, and no network: the linker and evolution read the redacted
+candidate batch the write already fetched. Evolution rewrites a neighbor only when it actually gains
+an annotation, and each patched payload is measured against the resolved worker byte budget, so a
+pathological keyword list cannot grow a row past it. Superseded rows stay in the store (auditable) and
+are filtered out of recall by `validTo` until retention or `forget` removes them.
+
+`forget` and the tools add no privilege: a note is deleted in this memory instance's own thread scope,
+working blocks by label in the same scope, and every tool refuses to run for a session the fabric was
+not attached to. An attach is a gate read on each call, not a background process: an unattached fabric
+starts nothing and enriches nothing, and `detach` (or aborting the attach signal) closes the gate
+again. The jail re-checks the real path of the longest existing ancestor before any read or
+append, so a symlink placed inside `root` cannot be used to read or grow a file outside it; reads are
+bounded before they are retained (a 1 GiB file costs one capped buffer), and `insert` refuses before
+writing, so an over-cap append is a no-op. Inserted content is data: it never activates tools, skills,
+or configuration, and it is validated by the host's working-memory schema like any other block value.
+
+## Related APIs
+
+- [Observational memory](compaction-observational-memory.md): observations and reflections whose ids `episode` notes reference — still the episodic ledger and its workers; the fabric views, never re-observes.
+- [`createMemory`](working-and-semantic-memory.md): working store, semantic recall, consent, redaction, lineage — the store this subpath writes through.
+- [Attention compiler](attention-compiler.md): measures injected context cost; it does not attach or configure a fabric.
+- [Session stores](session-stores.md): branch entries and bounded session search used for conversation-level queries.
+- [Agent definitions](agent-definitions.md): `resolveAgentDefinition` resolves `context` names against `registries.contextProviders`; no fabric field is added to the contract.
+- [Tools](tools.md): how a host registers and governs tool definitions, and what the agent sees.
+- [Coding security](coding-security.md): the path-containment rules the file jail follows locally.