@equationalapplications/core-llm-wiki 7.15.1 → 7.16.0

package/README.md

@@ -10,1614 +10,43 @@ Platform-agnostic TypeScript engine for hybrid LLM memory. Features episodic fac
 
 > Inspired by [Andrej Karpathy's LLM Wiki memory spec](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f).
 
+**📖 Documentation: [equationalapplications.github.io/expo-llm-wiki/packages/core](https://equationalapplications.github.io/expo-llm-wiki/packages/core/)**. Start with the [Node.js quickstart](https://equationalapplications.github.io/expo-llm-wiki/start/quickstart-node/), or go straight to the [API reference](https://equationalapplications.github.io/expo-llm-wiki/reference/wiki-memory/).
 
 ## Features
 
-- **Platform-agnostic** — Zero runtime dependencies; works with any SQLite driver via the `SQLiteAdapter` interface
-- **Semantic search** — Vector embeddings via your LLM's `embed` function, ranked by cosine similarity
-- **Keyword fallback** — SQLite FTS5 index stored in the database file, or an in-memory [MiniSearch](https://github.com/lucaong/minisearch) index where FTS5 is unavailable (see `indexStrategy`), for offline/degraded scenarios when embeddings unavailable
-- **Retrieval tuning** — Per-call overrides for `maxResults`, `preFilterLimit`, `hybridWeight`, `tierWeights`, `tierFloors`, and `includeZeroWeightEntities`
-- **Multi-entity reads** — Search across multiple `entity_id` namespaces in one pass with per-entity score multipliers (`tierWeights`); `tierFloors` reserves each namespace's top-N matching results; optional `factScores` and `metadata` for explainability
-- **Immutable vs mutable facts** — Use `WikiFact.source_type` to distinguish document-sourced facts (`immutable_document`) from derived or user-provided facts (`librarian_inferred`, `user_stated`, `user_confirmed`). Immutable document facts are not rewritten by `runLibrarian()` or `runHeal()` and can only be removed by `forget()` or re-ingesting.
-- **Full-featured memory** — Facts, tasks, events, maintenance jobs (librarian, heal, reembed, prune)
-- **Type-safe** — Built with TypeScript, full type exports
-- **Interoperability:** Supports [Open Knowledge Format (OKF)](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf) v0.1 + v0.2 import and export via the [llm-wiki OKF profiles](https://github.com/equationalapplications/expo-llm-wiki/blob/main/docs/okf-profile.md) (default `llm-wiki/2`, back-compat `llm-wiki/1`).
-- **Per-entity seeded ontology** — Optional Strict, Emergent, or Off modes govern LLM graph extraction; seed taxonomies per entity and persist typed facts with inline edges.
-- **Diagnostics** — Optional `onDiagnostic` hook with typed, content-free reports of dropped chunks, facts, edges, embedding failures and background-job failures ([Diagnostics](#diagnostics))
-- **Draft review** — `excludeDrafts` on reads and traversal, plus `listDrafts` / `promoteDraft` ([Draft Review](#draft-review))
-- **Evidence grounding** — Opt-in `grounding` check; facts that don't quote their source are stored as drafts ([Grounding](#grounding))
-- **Optional classifier** — `LLMProvider.classify` types facts during ontology backfill when you opt in with `ontology.backfillClassifier: 'auto'` ([Ontology backfill](#ontology-backfill))
-
-## GraphRAG & Multi-Modal Retrieval
-
-`@equationalapplications/core-llm-wiki` exposes three complementary retrieval modes, each addressing a different shape of query:
-
-| Mode | API | Best for |
-|---|---|---|
-| **Semantic** (vector cosine) | `wiki.read(entityId, query)` with `embed` configured | Open-ended natural-language questions; "what do I know about X" |
-| **Keyword** (FTS5 or MiniSearch) | `wiki.read(entityId, query)` with `embed` absent or offline | Exact terms, identifiers, names; offline fallback |
-| **GraphRAG** (recursive CTE) | `wiki.traverseGraph(entityId, options)` + `formatGraphContext(result)` | Structural questions; "what connects to X", "everything two hops from this fact", "summarise the people, places, and projects linked to Alice" |
-
-The GraphRAG path is structurally distinct: it doesn't rank by relevance to a query string, it walks `llm_wiki_edges` from a known anchor fact. The result is dense and connected — subgraphs, not loose top-K hits.
-
-### Graph traversal APIs
-
-```typescript
-import { WikiMemory, formatGraphContext } from '@equationalapplications/core-llm-wiki';
-
-const graph = await wikiMemory.traverseGraph('user-123', {
-  sourceId: '<anchor-fact-id>',
-  maxDepth: 2,
-  direction: 'both',          // 'inbound' | 'outbound' | 'both'
-  edgeTypes: ['reports_to'],   // optional filter
-  excludeSourceTypes: ['immutable_document'],
-  minTraversalConfidence: 'inferred',
-  maxTraversalNodes: 20,
-});
-
-const promptContext = formatGraphContext(graph);
-// → dense text block ready for prompt injection
-```
-
-`traverseGraph` runs as a single recursive CTE in SQLite (see the root README's ["The SQL: how traversal works in one query"](../../README.md#the-sql-how-traversal-works-in-one-query) for the query shape). No external graph database.
-
-### Deterministic graph seeding (no LLM)
-
-For programmatic pipelines — importing pre-classified data, building a GraphRAG corpus from a CSV, or seed-loading from a JSON file — use `upsertGraph()`. It writes nodes and edges directly under the same `(sourceRef, sourceHash)` ownership semantics as `ingestDocument()`, but skips the LLM extraction step. See [Direct Graph Write](#direct-graph-write) for the canonical signature, including the required `SQLiteAdapter` argument and transactional semantics.
-
-This is the GraphRAG seed path: load a corpus, walk it.
-
-## Direct fact writes
-
-`remember()` stores one mutable fact in one transaction, with no text-generation (LLM) call, and returns the stored row. When `llmProvider.embed` is configured it does await one embedding call before resolving (failures surface as `embedding_failed`, not a throw). Use it when the host already knows the fact (a user preference, an agent's observation the user approved). To replace a fact, use `supersede()` so history is kept.
-
-```typescript
-const fact = await wiki.remember('user-123', {
-  title: 'Prefers merge commits',
-  body: 'Kurt wants PRs merged with merge commits, never squashed.',
-  tags: ['git'],                 // default []
-  confidence: 'certain',         // default
-  source_type: 'user_stated',    // or 'user_confirmed'; default 'user_stated'
-  okf_type: 'Preference',        // optional; resolved like an upsertGraph node type
-  valid_from: Date.parse('2026-03-01'), // optional epoch ms
-});
-fact.id; // 'fact_…' — the row as stored: timestamps, defaults, isStale, trustTier
-```
-
-- Validation throws `TypeError` before anything is written: `title` non-empty, `body` a string, `tags` an array of strings, known `confidence` and `source_type` (explicit `null` is rejected; omit the field to take the default), `okf_type` a non-empty string or null, finite and >= 0 `valid_from`. Nothing is clipped; length limits are the host's.
-- `okf_type` follows the `upsertGraph` rule: the manifest's canonical slug when known; `WikiStrictOntologyViolation` under strict mode otherwise; `null` otherwise.
-- Never starts the librarian or heal and writes no event, in `'auto'` and `'deferred'` mode alike. Embeds through `llmProvider.embed` when present (failures surface as `embedding_failed` with `operation: 'remember'`); keyword-only otherwise, and `getPendingMaintenance().reembedPending` picks it up once an `embed` exists.
-- Not idempotent: two identical calls store two facts. Hosts that expose retries own the idempotency key.
-- Opens its own transaction. Do not call it inside `withTransactionAsync`.
-
-## Temporal facts
-
-Facts carry an optional validity window. Nothing changes until you use it: facts without validity data are always current.
-
-```typescript
-// The user tells you they moved; the move happened on March 1.
-await wiki.supersede('user-123', seattleFactId, { title: 'Lives in San Francisco', body: 'Moved in March.' }, {
-  validFrom: Date.parse('2026-03-01'),
-});
-
-await wiki.read('user-123', 'where do I live');                                  // current: San Francisco
-await wiki.read('user-123', 'where do I live', { asOf: Date.parse('2026-02-01') }); // then: Seattle
-await wiki.history('user-123', seattleFactId);                                    // [Seattle, San Francisco]
-
-// Record when an event really happened (defaults to ingestion time):
-await wiki.write('user-123', { event_type: 'observation', summary: 'Moved to SF', occurred_at: Date.parse('2026-03-01') });
-```
-
-- Validity is half-open: `[valid_from, valid_to)`. At the switch instant only the new fact matches.
-- `asOf` answers "what do we now know was true at T". Learning late about a past change still answers correctly for the past.
-- `supersede()` refuses `immutable_document` facts (re-ingest the document instead), cycles, facts owned by another entity, and facts already superseded. It throws `WikiSupersedeError` with a `reason`.
-- `traverseGraph({ asOf })` only walks edges whose two facts are both live at that instant.
-- History is kept. Set `config.pruneSupersededAfter` (days) to let `runPrune` retire expired facts.
-- `getMemoryBundle()` and `exportDump()` return every non-deleted fact, including history.
-
-## Librarian strategies
-
-`config.librarian.strategy` selects how events become facts. The default, `'legacy'`, is unchanged from 7.x.
-
-```typescript
-new WikiMemory(db, {
-  llmProvider,
-  config: { librarian: { strategy: 'ops', gate: { k: 5, dupThreshold: 0.89, novelThreshold: 0.30 } } },
-});
-```
-
-`'ops'` works in three steps:
-
-1. **Extract.** Candidate facts come from the events since the last pass. Existing facts are not sent.
-2. **Gate, with no LLM call.** Each candidate is compared with its closest current facts. An identical fact is a no-op, and a candidate with no close match is added. Only candidates that are similar but different continue to step 3. Similar is not the same as identical: "lives in Seattle" and "moved to San Francisco" score as similar, so they go to the model.
-3. **Resolve, in one batched call.** The model returns `ADD`, `UPDATE`, `SUPERSEDE` or `NOOP` for each remaining candidate. `SUPERSEDE` uses `supersede()`, so history is kept and `read({ asOf })` still sees the old fact.
-
-- The thresholds depend on your embedding model. The defaults are provisional.
-- Without `embed`, the gate uses keyword search. Every keyword match then goes to the resolve step.
-- Under `'ops'`, `runLibrarian`'s `promptOverride` and `prompts.librarianSystemPrompt` are ignored: the ops prompts use a different schema.
-- A model answer that can't be used never loses a fact. It is added, or stored as a draft, and a diagnostic is emitted.
-
-## Deferred maintenance
-
-By default, `write()` starts the librarian and heal in the background when thresholds are crossed. On serverless or request-scoped hosts those background promises can be frozen or killed. Set `maintenance: 'deferred'` to decide when maintenance runs:
-
-```typescript
-const wiki = new WikiMemory(db, {
-  llmProvider,
-  config: { maintenance: 'deferred', librarian: { strategy: 'ops' } },
-});
-
-await wiki.write(entityId, { event_type: 'observation', summary, occurred_at });
-
-const report = await wiki.runPendingMaintenance({ tokenBudget: 20_000, deadlineMs: 8_000 });
-// report.stoppedReason: complete | deadline | budget_exhausted | budget_too_small
-// Nothing is still running here, so it is safe to persist the database.
-```
-
-- `getPendingMaintenance()` shows the backlog per entity without calling a model.
-- `remember()` and `supersede()` never schedule maintenance in either mode; only `write()` does.
-- The budget covers text-generation tokens only; embedding calls are not counted. Figures are provider-reported when `generateTextWithUsage` exists, otherwise estimated at characters ÷ 4.
-- Entities share the budget fairly: each round runs one batch per entity.
-- `budget_too_small` names the first job and entity whose smallest step needed more than the whole budget; other entities may have hit the same limit in that run.
-- A crash mid-batch loses nothing. The librarian's progress marker only advances after a batch commits.
-- In `'auto'` mode, call `drain()` before the app is suspended or closed. `autoLibrarianTokenThreshold` also triggers the librarian on the size of the pending text.
-- Use `'deferred'` with the ops strategy. The legacy strategy reads only the newest 50 events per pass and marks them processed, so a backlog larger than that is skipped.
-- Under `'deferred'` or the ops strategy, `runPrune` never deletes events the librarian has not processed.
-- `JobManager` locks only work within one process. Guarantee a single writer per database file across processes.
-
-See the [SynapseTree integration guide](../../docs/synapsetree-integration.md) for the end-to-end pattern on tenant-aware hosts (S3-backed SQLite, request lifecycle, `entity_id` scheme, MCP surface, costs). Benchmarks live at [docs/benchmarks.md](../../docs/benchmarks.md).
+- **Any SQLite driver.** Pure TypeScript with no native code. You pass a small [`SQLiteAdapter`](https://equationalapplications.github.io/expo-llm-wiki/guides/sqlite-adapter/) for `better-sqlite3`, `sql.js`, `expo-sqlite` or anything else.
+- **Bring your own inference.** One `generateText` function, plus an optional `embed` for semantic search. The engine owns prompts, JSON parsing and database writes.
+- **Hybrid retrieval.** Vector cosine ranking with a keyword fallback (SQLite FTS5 or in-memory MiniSearch), [tunable](https://equationalapplications.github.io/expo-llm-wiki/guides/tune-retrieval/) per call.
+- **Multi-entity reads.** Search several namespaces in one pass with `tierWeights` and `tierFloors`.
+- **GraphRAG.** Per-entity [seeded ontologies](https://equationalapplications.github.io/expo-llm-wiki/guides/ontologies/) (Strict, Emergent or Off) and SQL-only [graph traversal](https://equationalapplications.github.io/expo-llm-wiki/guides/graphrag/).
+- **Background maintenance.** Librarian, heal, reembed and prune jobs, run inline or [deferred](https://equationalapplications.github.io/expo-llm-wiki/guides/maintenance/).
+- **Temporal facts, drafts and grounding** for [trust and provenance](https://equationalapplications.github.io/expo-llm-wiki/concepts/trust-and-provenance/).
+- **OKF v0.1 and v0.2** [import and export](https://equationalapplications.github.io/expo-llm-wiki/guides/okf/).
+- **Diagnostics.** An optional `onDiagnostic` hook with typed, content-free reports.
 
 ## Installation
 
 ```bash
 npm install @equationalapplications/core-llm-wiki
+npm install better-sqlite3   # Node.js, or sql.js for the browser
 ```
 
-## Semantic Search with Embeddings
-
-Provide an `embed` function in `llmProvider` to enable vector-based retrieval:
-
-```typescript
-import { WikiMemory } from '@equationalapplications/core-llm-wiki';
-
-const wikiMemory = new WikiMemory(db, {
-  llmProvider: {
-    generateText: async ({ systemPrompt, userPrompt }) => {
-      // Your LLM call for extracting facts, tasks
-      return 'Model output';
-    },
-    maxOutputTokens: 4096, // optional — lets runHeal/runOntologyBackfill size their first LLM call correctly instead of discovering the ceiling via a truncated response and retrying smaller
-    embed: async (text: string) => {
-      // Your embedding service (e.g., OpenAI, Cohere, local)
-      const response = await fetch('https://your-app.example.com/api/embed', {
-        method: 'POST',
-        body: JSON.stringify({ text }),
-      });
-      const { embedding } = await response.json();
-      return embedding; // number[]
-    },
-  },
-});
-
-await wikiMemory.setup();
-
-// Query with semantic matching
-const memory = await wikiMemory.read('user-123', 'What should I do this weekend?');
-// Returns facts semantically similar to the query, not lexical matches
-// E.g., fact "Saturday hiking trip" ranks high even though no lexical overlap
-```
-
-When `embed` is unavailable, `read()` silently falls back to keyword search. If an embedding attempt throws, `read()` falls back and calls `onRetrievalFallback` if provided:
-
-```typescript
-const wikiMemory = new WikiMemory(db, {
-  llmProvider: {
-    generateText: async () => { /* ... */ },
-    embed: undefined, // or throws on network error
-  },
-  onRetrievalFallback: (error) => {
-    console.warn('Embedding retrieval unavailable, using keyword search:', error);
-  },
-});
-
-// read() returns keyword results, onRetrievalFallback not called (embed absent is expected)
-// read() returns keyword results, onRetrievalFallback called (embed threw)
-```
-
-### Token budgets
-
-```typescript
-const bundle = await wiki.read('user-123', 'what should I cook?', { tokenBudget: 800 });
-const prompt = formatContext(bundle, { compact: true });
-```
-
-`tokenBudget` keeps the most relevant facts per token that fit within about 800 tokens. Tokens are estimated as characters ÷ 4. The top fact is always included, truncated if it alone is too big. Tasks and events are unaffected. `traverseGraph` accepts the same option and keeps nodes in breadth-first order. A `read_budget` diagnostic reports how many facts were packed.
-
-## Configuration
-
-All `WikiConfig` fields are optional:
-
-```typescript
-const wikiMemory = new WikiMemory(db, {
-  llmProvider: { /* ... */ },
-  config: {
-    tablePrefix: 'llm_wiki_',          // default: 'llm_wiki_'
-    maxResults: 10,                    // default: 10
-    autoLibrarianThreshold: 20,        // default: 20 — events before librarian auto-runs
-    autoHealThreshold: 100,            // default: 100 — events before heal auto-runs
-    maxChunkLength: 12000,             // default: 12000 (char count per ingestDocument chunk; exported as DEFAULT_MAX_CHUNK_LENGTH)
-    chunkOverlap: 400,                 // default: 400 (overlap between chunks in characters; exported as DEFAULT_CHUNK_OVERLAP)
-    chunkConcurrency: 1,               // default: 1 (parallel LLM calls per ingestDocument)
-    maxEmbedChars: 6000,               // default: 6000 (chars of title+body+tags sent to embed(); hard ceiling 16000; exported as DEFAULT_MAX_EMBED_CHARS)
-    pruneRetainSoftDeletedFor: 7,      // default: 7 (days before hard-deleting soft-deleted facts)
-    pruneEventsAfter: 30,              // default: 30 (days before hard-deleting old events)
-    orphanAfterDays: 30,               // default: 30 (days before runHeal flags sourceless facts; null to disable)
-    staleInferredAfterDays: 60,        // default: 60 (days before runHeal downgrades inferred facts; null to disable)
-    preFilterLimit: 50,                // default: undefined — keyword pre-filter before cosine scan; recommended for >500 facts
-    hybridWeight: 0.7,                 // default: undefined — blend semantic (1.0) ↔ keyword (0.0); pure semantic when unset
-    // Keyword-index backend (#257): 'fts5' stores the index inside the database file, fed by triggers on the
-    // entries table, so memory stays flat at any size; setup() throws if the adapter's SQLite lacks FTS5 or json1.
-    // 'minisearch' keeps the in-RAM MiniSearch index, whose memory grows with total stored text; 'auto' (default)
-    // probes at setup() and uses FTS5 when present, else MiniSearch (e.g. sql.js, which ships without FTS5).
-    // The first setup() that attaches FTS5 to an existing database rebuilds the index in one transaction, holding
-    // the write lock for its whole duration. Keyword rankings differ between the two backends; set 'minisearch'
-    // to keep the pre-7.11 behavior.
-    // Under 'auto', a failed FTS5 init is retried once, then setup() completes with keyword search unavailable
-    // (queries throw WikiSearchUnavailableError); it never silently demotes to MiniSearch. While unavailable,
-    // runHeal returns searchUnavailable: true, runPendingMaintenance lists skipped jobs in perEntity[].searchUnavailable,
-    // and a no-arg syncSearchIndex() retries the init (after a failure, backing off from 5 s up to 5 min). MiniSearch holds all
-    // entry text in the JS heap — the measured ceiling is ~1M entries on a default Node heap (--max-old-space-size).
-    indexStrategy: 'auto',             // default: 'auto' — 'fts5' | 'minisearch' | 'auto'
-    enableOutbox: false,               // default: false — when true, entry/task mutations write to an internal SQLite outbox table for external sync (e.g. via @equationalapplications/prisma-outbox)
-    excludeDrafts: false,              // default: false — engine default for read()/traverseGraph() excludeDrafts; see Draft Review
-    grounding: { mode: 'off' },        // default: off — 'draft' checks evidence quotes; see Grounding
-    ontology: {
-      // mode, seedManifests: see Per-Entity Seeded Ontology
-      backfillClassifier: 'llm',       // default: 'llm' — 'auto' uses llmProvider.classify when present; see Ontology backfill
-      classifyMinConfidence: 0.5,      // default: 0.5 — classifier answers below this are left untyped
-    },
-
-    // Global prompt overrides — librarianSystemPrompt and healSystemPrompt apply to write() auto-runs;
-    // ingestSystemPrompt applies only to explicit ingestDocument() calls.
-    // ⚠ Overrides replace the entire default prompt, including the JSON output contract.
-    // See "JSON Output Contracts" in the Prompt Management & Overrides section below.
-    prompts: {
-      ingestSystemPrompt: `Extract core facts from this document: {{documentChunk}}\n\nReturn ONLY valid JSON: { "facts": [{ "title": "string", "body": "string", "tags": ["string"], "confidence": "certain|inferred|tentative" }] }. No markdown.`,
-      librarianSystemPrompt: `You are an expert curator. Synthesize these thoughts:\n{{events}}\n\nCurrent Facts:\n{{currentFacts}}\n\nReturn ONLY valid JSON: { "facts": [{ "title": "string", "body": "string", "tags": ["string"], "confidence": "certain|inferred|tentative" }], "tasks": [{ "description": "string", "priority": 0 }] }. No markdown.`,
-      healSystemPrompt: `Fix the memory graph based on these candidates: {{healCandidates}}\n\nReturn ONLY valid JSON: { "downgraded": ["factId"], "deleted": ["factId"], "newFacts": [{ "title": "string", "body": "string", "tags": ["string"], "confidence": "certain|inferred|tentative" }] }. No markdown.`,
-    },
-  },
-  // Host callbacks sit beside llmProvider, not inside config:
-  // onDiagnostic: (d) => { ... }, // see Diagnostics
-});
-```
-
-### Opening inside a writer lease
-
-One-time upgrade work (schema migrations, the `source_ref` normalize) can take minutes on a large store. If you open the store inside a time-limited writer lease, refuse that work instead of running it:
-
-```typescript
-try {
-  await wiki.setup({ migrations: 'refuse' });   // also settable as config.migrations
-} catch (err) {
-  if (!(err instanceof WikiMigrationRequiredError)) throw err;
-  // err.pendingWork says what is pending. Release the lease, then:
-  await wiki.setup();                           // runs the work out of lease (resumable if interrupted)
-  // ...re-acquire the lease and open again with 'refuse'.
-}
-```
-
-`'allow'` (default) runs everything; `'auto'` throws on a pending schema migration but runs a pending normalize. Await `setup()` before any other call on the instance.
-
-## Prompt Management & Overrides
-
-Core maintenance tasks (`ingestDocument`, `runLibrarian`, `runHeal`) use system prompts to instruct the LLM. You can customize these prompts using `{{mustache}}` style variables to inject context dynamically.
-
-> **JSON Output Contracts:** Prompt overrides replace the *entire* default system prompt, including the JSON response schema the parser depends on. Your override **must** instruct the LLM to return raw JSON — no markdown. Required shapes:
->
-> | Operation | Required JSON shape |
-> |-----------|-------------------|
-> | `ingestDocument` | `{ "facts": [{ "title": "string", "body": "string", "tags": ["string"], "confidence": "certain\|inferred\|tentative" }] }` |
-> | `runLibrarian` | `{ "facts": [...], "tasks": [{ "description": "string", "priority": 5 }] }` — `priority` is an integer 0–10 |
-> | `runHeal` | `{ "downgraded": ["factId"], "deleted": ["factId"], "newFacts": [...] }` |
->
-> **Grounding:** when [`config.grounding`](#grounding) is on, the evidence instruction is appended after your override (and after ontology context) for every writer in `grounding.writers`. Your override does not need to ask for `evidence` itself.
+Requires Node.js 20 or later. Using Expo or React? Install [`expo-llm-wiki`](https://equationalapplications.github.io/expo-llm-wiki/packages/expo/) or [`react-llm-wiki`](https://equationalapplications.github.io/expo-llm-wiki/packages/react/) instead. Both re-export core.
 
-### Global Overrides (Auto-Runs)
-
-If your application relies on `write()` to automatically maintain the memory graph in the background (via `autoLibrarianThreshold` and `autoHealThreshold`), configure custom prompts globally at instantiation. This ensures the internal `WriteService` uses your domain-specific instructions when it triggers an auto-run.
-
-```typescript
-const wikiMemory = new WikiMemory(db, {
-  llmProvider,
-  config: {
-    prompts: {
-      // Override must include the JSON output contract — it replaces the entire default prompt.
-      librarianSystemPrompt: `You are an expert curator. Synthesize these thoughts:\n{{events}}\n\nCurrent Facts:\n{{currentFacts}}\n\nReturn ONLY a valid JSON object: { "facts": [{ "title": "string", "body": "string", "tags": ["string"], "confidence": "certain|inferred|tentative" }], "tasks": [{ "description": "string", "priority": 0 }] }. No markdown.`,
-    },
-  },
-});
-
-// WriteService uses the global prompt whenever autoLibrarianThreshold is hit
-await wikiMemory.write('user-123', { event_type: 'observation', summary: '...' });
-```
-
-Available `{{variables}}` per prompt type:
-
-| Prompt | Variables |
-|--------|-----------|
-| `ingestSystemPrompt` | `{{documentChunk}}` |
-| `librarianSystemPrompt` | `{{events}}`, `{{currentFacts}}` |
-| `healSystemPrompt` | `{{healCandidates}}`, `{{documentAnchors}}`, `{{allTasks}}`, `{{recentEvents}}` |
-
-When a template contains `{{variable}}` tags, the matching data is hydrated directly into `systemPrompt` and a short fixed string is used as `userPrompt`. When a template has no `{{}}` tags, the raw data is appended as `userPrompt` — backward compatible with plain-string overrides.
-
-### Runtime Overrides (Manual Execution)
-
-Pass `promptOverride` per-call for one-off instructions. **Runtime overrides apply only to that single call — they do not persist for future auto-runs triggered by `write()`.**
-
-```typescript
-// Override the base default AND global config for this single execution.
-// Each override must include the JSON output contract (replaces the entire default prompt).
-await wikiMemory.runLibrarian('user-123', {
-  promptOverride: `One-off extraction task:\n{{events}}\n\nReturn ONLY valid JSON: { "facts": [{ "title": "string", "body": "string", "tags": ["string"], "confidence": "certain|inferred|tentative" }], "tasks": [{ "description": "string", "priority": 0 }] }. No markdown.`,
-});
-
-await wikiMemory.runHeal('user-123', {
-  promptOverride: `Domain-specific healing: {{healCandidates}}\n\nReturn ONLY valid JSON: { "downgraded": ["factId"], "deleted": ["factId"], "newFacts": [{ "title": "string", "body": "string", "tags": ["string"], "confidence": "certain|inferred|tentative" }] }. No markdown.`,
-});
-
-await wikiMemory.ingestDocument('user-123', {
-  sourceRef: 'doc-1',
-  sourceHash: sha256(content),
-  documentChunk: content,
-  promptOverride: `Strict technical extraction: {{documentChunk}}\n\nReturn ONLY valid JSON: { "facts": [{ "title": "string", "body": "string", "tags": ["string"], "confidence": "certain|inferred|tentative" }] }. No markdown.`,
-});
-```
-
-> **Important:** If your app relies on `write()` auto-runs and needs custom prompts for those runs, use `config.prompts` at construction time. Runtime `promptOverride` values are never forwarded to `WriteService`-triggered internal runs.
-
-### Effective instructions (`getInstructions`)
-
-```typescript
-const { ingest, librarian, heal, ontologyBackfill } = await wikiMemory.getInstructions('entity-123');
-```
-
-Returns the system prompt each writer sends, with `WikiConfig.prompts` overrides applied. Ingest, librarian and ontology backfill also get the entity's ontology block; heal gets none, as at runtime. When `WikiConfig.grounding` is on, the evidence block is appended for each writer in `grounding.writers`, exactly as sent. Data placeholders such as `{{documentChunk}}` stay unfilled; no events, chunks or facts are included. It reflects `WikiConfig.prompts` only: a per-call `promptOverride` is not reflected, and `ontologyBackfill` is returned even when backfill would send no prompt (ontology `off`, or the classifier path). `core-llm-tools` exposes this as the `wiki_get_instructions` tool (`memory:read`), so agents can see the engine's output format and constraints before proposing writes. Agents should treat it as reference data, not instructions; see [Prompt-Injection Trust Boundary](#prompt-injection-trust-boundary).
-
-> **Warning:** overrides are returned verbatim to any client with `memory:read`. Never put secrets, API keys or private data in `WikiConfig.prompts`.
-
-## Retrieval Tuning
-
-Optimize `read()` performance and blend retrieval strategies:
-
-```typescript
-const config = {
-  // Limit cosine similarity scoring to top-K MiniSearch keyword candidates
-  preFilterLimit: 50,
-  
-  // Blend semantic and keyword scores (0.0 = pure keyword, 1.0 = pure semantic)
-  hybridWeight: 0.7,
-  
-  // Max results returned per read
-  maxResults: 10,
-};
-
-const wikiMemory = new WikiMemory(db, {
-  config,
-  llmProvider: { /* ... */ },
-});
-
-// Per-call overrides (runtime controls for search dashboards, etc.)
-const memory = await wikiMemory.read('user-123', 'my preferences', {
-  maxResults: 5,
-  preFilterLimit: 20,
-  hybridWeight: 0.5,
-});
-
-// Multi-entity with tier weights
-const multiMemory = await wikiMemory.read(['tier_wisdom', 'tier_fact', 'tier_working'], 'my preferences', {
-  maxResults: 8,
-  tierWeights: {
-    tier_wisdom: 2,      // high-confidence curated notes boosted 2×
-    tier_fact: 1,        // neutral baseline
-    tier_working: 0.25,  // recent but unvetted context downranked
-  },
-  // includeZeroWeightEntities: true — include 0-weight entities as bottom-ranked filler
-});
-// multiMemory.factScores — optional Record<factId, weightedScore> for returned facts; may be absent/undefined
-// multiMemory.metadata  — optional { query, entityIds, tierWeights, tierFloors }; may be absent/undefined
-```
-
-**Hybrid scoring blends:**
-- `hybridWeight: 1.0` → all-semantic blend with semantic scores clamped to non-negative range (no keyword component)
-- `hybridWeight: 0.5` → balanced semantic + keyword (50/50 blend)
-- `hybridWeight: 0.0` → pure keyword ranking, skips `embed()` entirely (no LLM API cost)
-
-True cosine-range pure semantic ranking (including negative cosine values) is used when `hybridWeight` is left `undefined`.
-
-**Tier weights:**
-- `tierWeights` applies a per-entity multiplier after semantic/keyword scoring: `finalScore = retrievalScore × weight`
-- Missing weights default to `1.0`. Negative weights clamp to `0`. Non-finite weights default to `1.0`.
-- `tierWeights[entity] = 0` skips that entity's scored retrieval branch (no compute cost).
-- `includeZeroWeightEntities: true` includes zero-weight entities as bottom-ranked filler instead of skipping them.
-- `tierFloors: Record<string, number>` reserves that entity's top-N scored results before the global `maxResults` cut — a floor on entity `X` means at least `N` of the returned facts come from `X`. Floors apply *after* scoring (including `tierWeights`) and *after* `preFilterLimit`'s candidate selection, so a row excluded by `preFilterLimit` cannot be resurrected by a floor. An entity with fewer matching facts than its floor contributes what it has — this is not an error. Only meaningful when `entityId` is an array; ignored for single-string calls and for empty-query ("recent facts") reads. Throws `WikiInvalidReadOptions` when a floor cannot be satisfied by construction: floors summing above `maxResults`, a floor keyed to an entity not in `entityId`, or a floor on an entity excluded by `tierWeights: 0` when `includeZeroWeightEntities` is not set. With an external `vectorRanker`, ranker-omitted rows (typically un-embedded facts) for a floored entity are pre-reserved before the global backfill budget is spent, so an unembedded floored entity still satisfies its floor.
-- `factScores` is present for array-shaped `entityId` calls only when the query is non-empty and at least one fact is scored; empty-query ("recent facts") reads leave it absent even when `entityId` is an array. Plain string calls never expose it. `metadata` is present for all array-shaped calls regardless of query.
-- `maxResults` applies globally across all requested entities.
-- Tasks are capped at `min(20 × entityCount, 200)`; events at `min(10 × entityCount, 100)` for multi-entity reads.
-
-**Pre-filtering optimization:**
-When `preFilterLimit: 50` is set with 1000 facts, cosine similarity is computed only for the top 50 keyword matches, reducing O(N) scoring to O(50).
-
-## Draft Review
-
-Facts can carry `lifecycle_status: 'draft'`, for example when a host marks model output as unreviewed. Drafts stay visible by default. To keep them out of results:
+## Quick look
 
 ```ts
-await wiki.read('user-1', 'deploy process', { excludeDrafts: true });
-await wiki.traverseGraph('user-1', { sourceId, excludeDrafts: true });
-// or engine-wide:
-createWiki(db, { llmProvider, config: { excludeDrafts: true } });
-```
+import { createWiki, formatContext } from '@equationalapplications/core-llm-wiki';
 
-- On every `read()` path, drafts are removed **before** `maxResults`, `tierFloors`, and pre-filter cuts, so they never take slots from reviewed facts.
-- In traversal, drafts are dead ends. The starting fact is always returned.
-- Status is read from SQLite on every call. A promotion is visible immediately, with no re-indexing.
+const wiki = createWiki(adapter, { llmProvider }); // your SQLiteAdapter and LLMProvider
+await wiki.setup();
 
-Review API:
-
-```ts
-const { facts, nextCursor } = await wiki.listDrafts('user-1', { limit: 50 });
-await wiki.promoteDraft(facts[0].id, 'user-1', { by: 'human:alice' }); // → stable, trustTier 'human-reviewed'
-// Reject with setLifecycleStatus(id, entityId, 'deprecated') or forget().
+await wiki.write('user-123', { event_type: 'observation', summary: 'Loves hiking on weekends.' });
+await wiki.runLibrarian('user-123'); // extract facts from events
+const context = formatContext(await wiki.read('user-123', 'weekend plans'));
 ```
 
-`promoteDraft` throws `WikiDraftNotFound` when no live draft with that id exists for the entity. The error is contextless by design. Promotion does not change `updated_at`, so a promoted fact keeps its recency position.
-
-## Grounding
-
-Opt-in, deterministic evidence check for LLM-authored facts. When on, writers you choose must quote the source they were shown. A fact whose quotes are missing or not found is stored as a `draft` (see [Draft Review](#draft-review)), not rejected. A fact whose quotes all check out is stored `stable` with a `process:grounding-check` verifier, so its `trustTier` is `machine-confirmed`. Default off: 7.x write behavior is unchanged.
-
-```ts
-new WikiMemory(db, {
-  llmProvider,
-  config: {
-    grounding: {
-      mode: 'draft',            // 'off' (default) | 'draft'
-      writers: ['ingest'],      // default ['ingest']; also 'librarian', 'heal'
-      minEvidenceChars: 20,     // shorter quotes count as absent
-      maxEvidence: 3,           // quotes asked for per fact
-      maxEvidenceChars: 300,
-    },
-  },
-});
-```
-
-- **What counts as source.**
-  - Ingest: the chunk text.
-  - Librarian: the `summary` of each event in the prompt.
-  - Heal: the `summary` of each recent event in the prompt, plus the bodies of non-draft document anchors. When heal is a writer, anchors are shown with their body clipped to 800 characters.
-  - Instructions, the ontology manifest, existing facts and identifiers never count, so a model cannot ground a claim by quoting them.
-- **The check.** Both sides are normalized with NFKC, whitespace runs collapse to one space, and matching is case-sensitive. A fact with more than 10 quotes, or any quote not found, fails.
-- **Diagnostics.** `grounding_missing` (reasons `no_evidence`, `evidence_too_short`) and `grounding_failed` (reasons `quote_not_found`, `too_many_quotes`), one per fact, with the new fact's `factId`. Quotes are never included.
-- **Duplicate titles in one ingest.** When chunks yield facts with the same title, ingest keeps one: a grounded fact beats one with missing or failed evidence, and on a tie the first one wins. The others are reported as `fact_deduplicated`. A fact already stored for the same `sourceRef` is not replaced by a later partial ingest, and that skip is reported the same way. Either way the diagnostic carries `{ sourceRef, chunkIndex, itemIndex }` for the skipped fact, whether or not grounding is enabled.
-- **`upsertGraph`** nodes are host-supplied and never grounded.
-- **Librarian and heal** synthesize across events, so their pass rates are unknown. Measure them on your own event log before opting them in.
-- Evidence quotes are not stored.
-
-## Pluggable Vector Retrieval
-
-When your entity corpus grows, in-process cosine similarity scoring becomes a bottleneck. The optional **`VectorRanker`** interface lets you delegate semantic ranking to [**sqlite-vec**](https://github.com/asg017/sqlite-vec), [**sqlite-vss**](https://github.com/asg017/sqlite-vss), or an external vector database while `WikiMemory` handles embedding validation, hybrid scoring, and tier-2 row hydration.
-
-### `VectorRanker` purpose
-
-`VectorRanker` provides an optional injection point for approximate nearest-neighbor (ANN) ranking:
-
-```typescript
-export interface VectorRanker {
-  /**
-   * Return semantic scores for facts in scope, sorted by similarity.
-   * - `entityId`: restricts results to one entity
-   * - `queryVec`: the embedded query (Float32Array or number[])
-   * - `candidateIds` (optional): when set, rank only within this set (MiniSearch pre-filter mode)
-   * - `limit`: requested top-K count
-   */
-  rankBySimilarity(args: VectorRankerRankArgs): Promise<VectorRankerSemanticResult[]>;
-
-  /**
-   * Optional hook called after embedding persistence (upsert, reembed, delete).
-   * Implementations use this to keep external indexes (sqlite-vec, remote ANN) in sync.
-   */
-  onEmbeddingPersisted?(event: {
-    entityId: string;
-    factId: string;
-    vector: Float32Array | null; // null = embedding removed
-  }): void | Promise<void>;
-}
-```
-
-**When no ranker is configured**, `WikiMemory` uses built-in JS cosine similarity — the same behavior as today. When a ranker is supplied and embeddings preconditions are met (`embed` available, dimensions match, no mismatches), `WikiMemory` delegates scoring to the ranker and blends results with keyword scores.
-
-### Example: sqlite-vec adapter
-
-```typescript
-import { WikiMemory } from '@equationalapplications/core-llm-wiki';
-import type { VectorRanker, VectorRankerRankArgs, VectorRankerSemanticResult } from '@equationalapplications/core-llm-wiki';
-
-// Minimal sqlite-vec adapter (pseudo-code)
-const sqliteVecRanker: VectorRanker = {
-  async rankBySimilarity(args: VectorRankerRankArgs): Promise<VectorRankerSemanticResult[]> {
-    const { entityId, queryVec, candidateIds, limit } = args;
-
-    // Build KNN query using sqlite-vec's distance functions.
-    // sqlite-vec returns cosine distance (0 = identical, 2 = opposite) ascending.
-    // Invert to semanticScore: higher = more similar, matching VectorRanker contract.
-    let sql = `SELECT id, (1.0 - distance) AS semanticScore FROM vec_facts 
-              WHERE entity_id = ? AND deleted_at IS NULL`;
-    const params: any[] = [entityId];
-
-    // Apply pre-filter if provided
-    if (candidateIds) {
-      sql += ` AND id IN (${candidateIds.map(() => '?').join(',')})`;
-      params.push(...candidateIds);
-    }
-
-    // KNN search (example syntax; adjust for your sqlite-vec version)
-    sql += ` ORDER BY vec MATCH vec_neighbor(?) LIMIT ?`;
-    params.push(queryVec, limit);
-
-    const rows = await db.getAllAsync<{ id: string; semanticScore: number }>(sql, params);
-    return rows; // sorted descending by semanticScore (closest distance → highest similarity)
-  },
-
-  async onEmbeddingPersisted(event) {
-    const { entityId, factId, vector } = event;
-    if (vector) {
-      // Upsert into sqlite-vec table
-      await db.runAsync(
-        `INSERT OR REPLACE INTO vec_facts (id, entity_id, vec) VALUES (?, ?, ?)`,
-        [factId, entityId, vector]
-      );
-    } else {
-      // Delete when embedding is removed
-      await db.runAsync(`DELETE FROM vec_facts WHERE id = ?`, [factId]);
-    }
-  },
-};
-
-const wikiMemory = new WikiMemory(db, {
-  llmProvider: { /* ... */ },
-  vectorRanker: sqliteVecRanker,
-});
-
-// read() now uses sqlite-vec for scoring instead of JS cosine
-const memory = await wikiMemory.read('user-123', 'my preferences');
-```
-
-### Fallback policies
-
-When `rankBySimilarity` rejects (e.g., ANN service outage, misconfiguration), `WikiMemory` applies a recovery policy:
-
-```typescript
-export type VectorRankerFallback =
-  | 'js-cosine'  // (default) Score candidates in-process with JS cosine — same as no ranker
-  | 'keyword'    // Skip semantic ranking; return keyword-only results
-  | 'empty'      // Semantic facts list empty for this read; tasks/events still included
-  | 'throw';     // Reject read() with the ranker error
-
-const wikiMemory = new WikiMemory(db, {
-  llmProvider: { /* ... */ },
-  vectorRanker: sqliteVecRanker,
-  vectorRankerFallback: 'js-cosine', // default
-  onVectorRankerFallback: (info) => {
-    console.warn(
-      `Ranker failed (policy: ${info.policy}); error:`,
-      info.error
-    );
-  },
-});
-```
-
-- **`'js-cosine'` (default):** Seamless degradation; same behavior as if no ranker was configured.
-- **`'keyword'`:** Useful when semantic ranking is optional; keyword search proceeds normally.
-- **`'empty'`:** Return no facts for this query (but tasks/events still load); useful for strict consistency.
-- **`'throw'`:** Propagate the error and fail the read.
-
-### `onEmbeddingPersisted` eventual consistency
-
-If `vectorRanker.onEmbeddingPersisted` returns a pending Promise, the hook **may resolve asynchronously**. This supports ANN indexes that rebuild on a schedule (e.g., sqlite-vec triggers on transaction commit) or external services with eventual consistency.
-
-**Best practice:**
-- If your adapter has **synchronous guarantees** (in-process sqlite-vec, same transaction), await the promise.
-- If your adapter is **eventually consistent** (remote ANN, async rebuild), document the lag and document that queries may miss recently-added facts until the index refreshes.
-- The **SQLite blob remains the source of truth**; `WikiMemory` always writes embeddings to `embedding_blob` first before calling the hook.
-
-### Hybrid scoring with ranker
-
-When both `vectorRanker` and `hybridWeight` are configured, `WikiMemory` still applies hybrid blending after the ranker returns scores:
-
-```typescript
-const wikiMemory = new WikiMemory(db, {
-  config: {
-    hybridWeight: 0.7, // 70% semantic, 30% keyword
-  },
-  vectorRanker: sqliteVecRanker,
-});
-
-// ranker returns semanticScore; WikiMemory blends with MiniSearch keyword score
-const memory = await wikiMemory.read('user-123', 'my preferences', {
-  hybridWeight: 0.5, // per-call override to 50/50 blend
-});
-```
-
-Note on semantics:
-- Leave `hybridWeight` undefined for true pure-semantic cosine-range scoring.
-- Set `hybridWeight: 1` for an all-semantic variant that clamps negative semantic scores to 0.
-
-For details on hybrid scoring formulas and trade-offs, see [Retrieval Tuning](#retrieval-tuning) above.
-
-### Spec and issue reference
-
-- **Full spec:** [`docs/superpowers/specs/2026-05-07-pluggable-vector-retrieval.md`](https://github.com/equationalapplications/expo-llm-wiki/blob/main/docs/superpowers/specs/2026-05-07-pluggable-vector-retrieval.md)
-- **GitHub issue:** [#15](https://github.com/equationalapplications/expo-llm-wiki/issues/15)
-
-## Vector Cache
-
-Parsed embedding vectors from full-scan `read()` calls are cached in memory, keyed by entity ID (max 16 entities, max 500 vectors per entity). This avoids redundant `Float32Array` parsing on repeated queries for the same entity. When the 16-entity limit is reached, the oldest-inserted entity is evicted to make room; if an entity exceeds 500 facts, its vectors are not cached at all for that read.
-
-After heavy read workloads or on memory-constrained runtimes, you can release the entire cache explicitly:
-
-```typescript
-// Release all cached embedding vectors
-wikiMemory.clearVectorCache();
-```
-
-The cache is also automatically invalidated on any mutation (`runLibrarian`, `runHeal`, `runPrune`, `runReembed`, `ingestDocument`, `importDump`, `forget`).
-
-## Re-Embedding & Retry Behavior
-
-`runReembed(entityId?, opts?)` returns `{ embedded, skipped, failed, deferred, permanentlyFailed }`.
-
-- `failed` — attempted this sweep and failed.
-- `deferred` — previously failed and still inside its exponential backoff window (60s doubling, capped at 24h). Not an error; a later sweep will retry.
-- `permanentlyFailed` — excluded for good: a `float32_overflow` failure, or 5 failed attempts. Pass `{ force: true }` to retry these anyway.
-
-Convergence loops should test `failed`, never `deferred` — deferred rows clear themselves once their backoff elapses.
-
-Two caveats on that guidance:
-
-- A `storage_error` failure counts in `failed` but is never marked for backoff — a failure marker is itself a DB write, which is exactly what is broken. While DB writes fail, every sweep re-attempts every row, so a loop testing `failed` can spin without converging. Treat repeated `storage_error` failures as an infrastructure signal to fix, not a retry window to wait out.
-- `{ force: true }` bypasses more than `permanentlyFailed`: it also skips the backoff window, so rows that would otherwise be `deferred` are re-attempted immediately.
-
-## Entity Status
-
-`WikiMemory` exposes the in-flight job state for a single entity through two complementary APIs.
-
-### `getEntityStatus(entityId)`
-
-Synchronous point-in-time snapshot:
-
-```typescript
-const status = wikiMemory.getEntityStatus('user-42');
-// { ingesting: boolean, librarian: boolean, heal: boolean }
-```
-
-Use this when you only need the current value (e.g. inside a request handler).
-
-### `subscribeEntityStatus(entityId, callback)`
-
-Push-based change notification — the callback fires synchronously once with the current status, then again on every transition where any of the three booleans flips. There is no polling and no duplicate snapshots.
-
-```typescript
-const unsubscribe = wikiMemory.subscribeEntityStatus('user-42', (status) => {
-  console.log(status); // { ingesting, librarian, heal }
-});
-
-// Later:
-unsubscribe(); // idempotent — safe to call more than once
-```
-
-Notes:
-
-- The first invocation happens **before** `subscribeEntityStatus` returns. Treat it as the initial render value.
-- Each emission may be a fresh object literal. Do not rely on referential equality between callbacks; equality of the three booleans is the contract.
-- A throwing callback is caught (logged via `console.error`) and does not block other subscribers or the underlying job.
-- Subscriptions are scoped to a single `entityId`. There is no wildcard or "all entities" form.
-
-## Diagnostics
-
-Pass `onDiagnostic` to receive typed, content-free reports of events core used to drop silently or only log: failed chunks, rejected facts and tasks, dedupe drops, dropped edges, embedding and host-hook failures, heal skips, and background-job failures.
-
-```ts
-const wiki = createWiki(db, {
-  llmProvider,
-  onDiagnostic: (d) => {
-    // d.code, d.severity ('info' | 'warn' | 'error'), d.operation, d.trigger ('call' | 'auto'),
-    // d.entityId, d.at, d.message, d.detail?: { factId, sourceRef, chunkIndex, itemIndex,
-    // edgeType, sourceNodeType, targetNodeType, reason, count, chunkIndexes }
-    telemetry.record(d);
-  },
-});
-```
-
-- **Content-free.** Diagnostics carry IDs, indexes, counts, ontology slugs and reason slugs only. They never carry titles, bodies, LLM output, provider error messages, or hashes of content.
-- **Isolated.** The hook is called synchronously. A throwing or rejecting hook never affects the operation, and its failure is logged with `console.warn`.
-- **After commit.** Transactional diagnostics are delivered after the operation's transaction commits. An operation that throws delivers none; the exception is the signal. `upsertGraph` runs in your transaction, so its diagnostics are delivered when it resolves. Disregard them if you roll back.
-- **`trigger`.** `'auto'` marks work started by `autoLibrarianThreshold` / `autoHealThreshold`. A failed background job is reported as `background_job_failed` with `operation` set to the job.
-- **`operation`** names the entry point: `ingest`, `upsertGraph`, `librarian`, `heal`, `ontologyBackfill`, `reembed`, `importDump`, `write`, `supersede`, `remember`, `read`, `prune`. New values may be added in minor releases.
-- **Forward-compatible.** New codes may be added in minor releases; ignore codes you don't recognize.
-- **Console output is unchanged** when a hook is set and succeeds: every existing core line is identical. A throwing or rejecting hook adds only its own `console.warn`, and a non-function `onDiagnostic` warns once.
-
-## Per-Entity Seeded Ontology
-
-Control how librarian and ingest passes classify facts and extract graph relationships. The system defaults to **`off`** so existing deployments behave unchanged.
-
-### The Three Modes
-
-| Mode | Behavior |
-|------|----------|
-| **`off`** (default) | No ontology guidance. LLM output and persistence match pre-ontology behavior: `okf_type` stays `null` on LLM-created facts; maintenance passes do not create edges. OKF import still populates `okf_type` and edges independently. |
-| **`strict`** | The LLM must use only `node_types` and `edge_types` from the entity manifest. Invalid `okf_type` falls back to an untyped fact with no edges; invalid individual edges are dropped while a valid `okf_type` and matching edges are kept. |
-| **`emergent`** | Same validation as Strict, plus the LLM may return `ontology_updates` with new node/edge types. Updates are append-only (deduped by `type` string) and take effect before facts from the same response are validated. |
-
-Mode resolution per entity: persisted DB row `mode` (when present) → `seedManifests[entityId].mode` (when no row but a seed exists) → `WikiConfig.ontology.mode` → `'off'`.
-
-### WikiConfig
-
-Set a global default mode and bootstrap manifests for known entities at construction time:
-
-```typescript
-const wikiMemory = new WikiMemory(db, {
-  llmProvider,
-  config: {
-    ontology: {
-      mode: 'strict', // global default when an entity has no per-entity override
-      seedManifests: {
-        'team-alpha': {
-          mode: 'emergent', // optional per-entity override
-          manifest: {
-            node_types: [
-              { type: 'person', description: 'An individual or user.' },
-              { type: 'project', description: 'An ongoing initiative.' },
-            ],
-            edge_types: [
-              {
-                type: 'contributes_to',
-                source_type: 'person',
-                target_type: 'project',
-                description: 'Person working on a project.',
-              },
-            ],
-          },
-        },
-      },
-    },
-  },
-});
-```
-
-`seedManifests` entries are written to SQLite the first time an entity's ontology is
-resolved *inside a transaction* (ingest, heal) and no row exists for it. A read outside a
-transaction — including `getOntologyManifest` — resolves the seed without persisting it, so
-a configured entity can report a manifest while still having no row in `entity_manifests`.
-That distinction matters for `ifAbsent` below.
-
-### Public API
-
-Read or seed an entity's ontology at runtime:
-
-```typescript
-// Read effective mode + manifest (DB row, then seedManifests fallback)
-const ontology = await wikiMemory.getOntologyManifest('team-alpha');
-// { mode: 'emergent', manifest: { node_types: [...], edge_types: [...] } }
-// null when no row and no seed entry
-
-// Seed or replace manifest; optional per-entity mode override
-await wikiMemory.setOntologyManifest('team-alpha', {
-  node_types: [{ type: 'person', description: 'An individual.' }],
-  edge_types: [{
-    type: 'reports_to',
-    source_type: 'person',
-    target_type: 'person',
-    description: 'Reporting hierarchy.',
-  }],
-}, { mode: 'strict' });
-```
-
-Seed several entities atomically — all manifests are written in one transaction,
-so a failure partway through leaves none of them behind:
-
-```typescript
-const { written, skipped } = await wikiMemory.setOntologyManifests(
-  [
-    { entityId: 'tier_fact', manifest, mode: 'strict' },
-    { entityId: 'tier_wisdom', manifest, mode: 'strict' },
-  ],
-  { ifAbsent: true },
-);
-// written: entities whose manifest this call wrote
-// skipped: entities that already had a persisted manifest (only under `ifAbsent`)
-```
-
-`ifAbsent` makes each write create-if-absent rather than an upsert, so a
-concurrent initializer loses the race by writing nothing instead of overwriting
-a manifest it never read. Omit it for replace-on-conflict, which is what
-`setOntologyManifest` does.
-
-**`ifAbsent` tests for a persisted row, not for an effective manifest.** An entity
-whose manifest comes from `WikiConfig.ontology.seedManifests` has no row until an
-ingest materializes one, so `ifAbsent` writes over the configured seed and reports
-the entity in `written`; after an ingest has run for that entity the same call
-reports it in `skipped`. Don't mix the two seeding routes for one entity: seed it
-through the config, or through this method, not both.
-
-The method takes data, never a transaction handle: `WikiMemory` serializes
-transactions on the adapter it is given, so a transaction opened on the adapter
-you passed to `createWiki` would not participate in that serialization.
-
-### Fact Shape Extensions
-
-In **Strict** and **Emergent** modes, librarian and ingest JSON may include typed facts with inline edges:
-
-```json
-{
-  "facts": [{
-    "title": "Jane reports to Bob",
-    "body": "Jane reports to Bob Smith.",
-    "tags": [],
-    "confidence": "certain",
-    "okf_type": "person",
-    "edges": [{ "edge_type": "reports_to", "target_title": "Bob Smith" }]
-  }]
-}
-```
-
-- `okf_type` maps to a `node_types[].type` entry (case-insensitive lookup; canonical manifest casing is persisted).
-- `edges` are resolved by `target_title` within the same maintenance transaction and persisted via `EdgeRepository`.
-- Invalid `okf_type` falls back to `null` with no edges for that fact. Invalid individual edges are dropped; valid `okf_type` and matching edges are still persisted.
-
-See the design spec: [`docs/superpowers/specs/2026-06-23-per-entity-seeded-ontology-design.md`](https://github.com/equationalapplications/expo-llm-wiki/blob/main/docs/superpowers/specs/2026-06-23-per-entity-seeded-ontology-design.md).
-
-### Ontology type inheritance
-
-`OntologyNodeType` accepts an optional `parent_type` field for **one-level type inheritance** — the building block for polymorphic queries like "all CreativeWorks" without deep, multi-level hierarchies.
-
-```ts
-// packages/core/src/types.ts
-export interface OntologyNodeType {
-  type: string;
-  description: string;
-  /** Optional parent type slug. One level only — the parent must exist in the
-   *  same manifest and must not itself declare a `parent_type`. */
-  parent_type?: string;
-}
-```
-
-A concrete type declares `parent_type: '<parent-slug>'`; the parent must be a top-level node in the same manifest. A `design_spec` node with `parent_type: 'creativework'` is treated as both itself *and* a `creativework` during edge matching.
-
-#### Inheritance rules (strictly enforced)
-
-`validateManifest` enforces the **one-level invariant** at every persist and read (`entity_manifests.manifest_json` is `JSON.parse`d on every read, so validation runs on the read path too). Violations throw:
-
-| Condition | Error |
-|-----------|-------|
-| `parent_type` references an unknown slug | `Parent type not found: <slug>` |
-| `parent_type` equals the node's own slug | `Self-parent: <type>` |
-| The referenced parent also declares a `parent_type` | `Parent chain too deep: <a> → <b> → <grandparent>` |
-| `parent_type` is present but blank (`''` / whitespace) or non-string (`number`, `null`, `object`) | `Ontology parent_type must be a non-empty string when present: <type>` |
-
-Two consequences worth knowing:
-
-- The depth check rejects **2-cycles** (`a → b → a`) which a self-parent check alone would miss.
-- A *present* `parent_type` key is required to be a usable string; an *absent* key (`undefined`) is fine and means "no parent". This is the same rule core applies to blank slugs elsewhere (`Ontology node type slug must be non-empty`).
-
-Parent types are **instantiable** — a fact may be classified as bare `creativework`, and `resolveNodeType('creativework')` returns `'creativework'` normally. There is no `abstract` flag; if you want a parent to stay abstract, write the description to steer classification toward the concrete children.
-
-#### Edge matching (symmetric, exact-first)
-
-Edge matching is parent-aware on **both** sides and routes through a single primitive, `typeSatisfies(declaredType, concreteType, manifest)`:
-
-- `declaredType === concreteType` (case-insensitive) → **exact match**, short-circuits before the node lookup. Manifests with no `parent_type` behave bit-for-bit as before.
-- Otherwise: looks up `concreteType`'s definition in the manifest and returns `true` if its `parent_type` equals `declaredType`. One hop only — `typeSatisfies` never recurses.
-
-`typeSatisfies` is used at four gates — `validateInlineEdges` (source), `OntologyService.resolveEdges` (source and target, via two-pass), `IngestionService.upsertGraph` (source) — so a parent-satisfied edge that validates will also persist.
-
-**Targets resolve exact-first.** When resolving an edge against a target fact, `OntologyService.resolveEdges` runs two passes over candidate defs:
-
-```ts
-// Packages/core/src/services/OntologyService.ts (abridged)
-const targetType = (target.okf_type ?? '').trim().toLowerCase();
-const def = candidates.find(d => d.target_type.trim().toLowerCase() === targetType)
-  ?? candidates.find(d => typeSatisfies(d.target_type, targetType, manifest));
-```
-
-The exact pass runs first, so a `design_spec` target with both `about creativework → creativework` and `about creativework → design_spec` declared resolves to the **narrower** row — array order never decides which pass wins. Ties within a single pass are immaterial: only `def.type` is read off the winning def, and `validateManifest` already rejects a manifest whose triples spell one edge name with different casing, so every candidate within a pass yields a byte-identical edge row.
-
-> **Accepted cost:** declaring `→ creativework` now admits every child of `creativework`, and there is no way to say "the parent type only." A type that needs an exact-only target must not be given children.
-
-#### Emergent prompt schema
-
-In `emergent` mode the LLM may propose new types via `ontology_updates`. The prompt schema (`EMERGENT_EXTRA` in `packages/core/src/prompts/ontology.ts`) advertises the optional `parent_type` so emergent proposals can suggest children of an existing type:
-
-```json
-"ontology_updates": {
-  "node_types": [{ "type": "slug", "description": "...", "parent_type": "optional existing slug" }],
-  "edge_types": [{ "type": "slug", "source_type": "...", "target_type": "...", "description": "..." }]
-}
-```
-
-The rest of the manifest reaches the LLM unchanged — `buildPromptContext` does `JSON.stringify(manifest, null, 2)`, so an established manifest's `parent_type` fields appear verbatim alongside `type` and `description`.
-
-Emergent proposals are **untrusted input**: `mergeOntologyUpdates` drops any `parent_type` (rather than throwing) when it is a non-string, blank, unresolvable, self-referential, or whose referenced parent already declares its own parent. The lenient merge contract keeps malformed LLM proposals from aborting an ingest transaction. Changing an established type's parent is a `setOntologyManifest` operation.
-
-#### Backwards compatibility
-
-`parent_type` is optional and manifests persist as a whole JSON blob in `entity_manifests.manifest_json`. Existing manifests without the field validate identically; no SQLite migration is needed. `setOntologyManifest` rejects a two-level chain at the public API boundary, so callers cannot accidentally introduce an unenforced chain through a typo.
-
-`typeSatisfies` is intentionally **not** re-exported from the package's public surface (`packages/core/src/index.ts`). No host needs the primitive to author or validate a manifest; publishing it would freeze an internal matching rule into the package's public surface.
-
-See the design spec: [`docs/superpowers/specs/2026-08-28-ontology-parent-field-spec.md`](https://github.com/equationalapplications/expo-llm-wiki/blob/main/docs/superpowers/specs/2026-08-28-ontology-parent-field-spec.md).
-
-### Ontology backfill
-
-Facts that enter the store without passing through the librarian (synced-down
-remote facts via `importDump`, or facts created before the ontology feature)
-have `okf_type = NULL` and no edges, so `traverseGraph` cannot reach them.
-`runOntologyBackfill` types them in place:
-
-```ts
-const result = await wiki.runOntologyBackfill(entityId);
-// { scanned, typed, failedValidation, edgesAdded, remaining, deferred, skipped }
-```
-
-- **When to call it:** you own the trigger — the library provides the operation,
-  not a scheduler (same as `runLibrarian`/`runHeal`). A good default is after
-  each sync/import completes. `WikiBusyError` under concurrency is safe to
-  swallow; the next trigger retries.
-- **Cost model:** one or more LLM calls only when eligible untyped facts exist;
-  otherwise one SELECT. Each run scans at most 25 facts (override via
-  `options.batchSize`), oldest first. Facts are sent to the LLM in bounded
-  sub-batches — sized from `llmProvider.maxOutputTokens` when supplied,
-  otherwise a conservative default — with the full serialized prompt
-  (system + user) capped at 40k chars. A sub-batch whose response is truncated
-  or fails to parse is halved and retried automatically; a single fact that
-  still fails alone is counted in `skipped` rather than aborting the run.
-- **Convergence:** loop `while (result.remaining > 0)` to drain a backlog.
-  `remaining` counts only *eligible* untyped facts, so the loop terminates even
-  when unclassifiable facts exist; those are cooldown-stamped and retried after
-  7 days (`deferred` reports them). Because of that weekly retry, host
-  dashboards may see small recurring bumps in `scanned`/`failedValidation` as
-  the unclassifiable backlog is re-tested — expected, not a regression.
-- **Strictly additive:** never creates, deletes, or rewrites facts, and never
-  overwrites an existing `okf_type` (guarded in SQL, not just convention).
-  `updated_at` is never touched, so sync merge resolution is unaffected.
-- **Prompt customization:** per-call `options.promptOverride`, or global
-  `config.prompts.ontologyBackfillSystemPrompt` (template may use `{{facts}}`
-  and the ontology placeholders).
-
-#### Classifier mode (optional)
-
-A System-One classifier (for example TypeSafe's Jev, an OpenJev-style open model, or a local ONNX classifier) can type facts during backfill without generating text. Add `classify` to your provider and opt in:
-
-```ts
-const wiki = createWiki(db, {
-  llmProvider: { generateText, classify },
-  config: { ontology: { backfillClassifier: 'auto', classifyMinConfidence: 0.5 } },
-});
-await wiki.runOntologyBackfill('user-1');                        // uses classify
-await wiki.runOntologyBackfill('user-1', { classifier: 'llm' }); // force the generative path
-```
-
-- Providing `classify` changes nothing by itself. The default is `'llm'`.
-- Each untyped fact gets one `choice` question over the entity manifest's node types. Answers below `classifyMinConfidence` (default 0.5) are left untyped and retried after the cooldown.
-- **No edges are proposed in classifier mode** (`edgesAdded: 0`): a classifier cannot extract edge targets. Run with `classifier: 'llm'` when you want edges.
-- Manifests with more than 255 node types, or providers without `classify`, use the generative path.
-- Answers are validated as untrusted. Off-list choices and out-of-range probabilities count toward `failedValidation`. A thrown `classify` counts toward `skipped` and is retried on the next pass.
-
-Example adapter for Cloudflare Workers AI's `typesafe/jev`. This is illustrative, not a supported package; check the provider's current API reference before use.
-
-```ts
-const classify: LLMProvider['classify'] = async ({ state, questions }) => {
-  const jevQuestions = Object.fromEntries(Object.entries(questions).map(([key, q]) => [key,
-    q.kind === 'choice' ? { type: 'choice', instructions: q.instructions, criteria: Object.fromEntries(q.options.map((o) => [o, o])) }
-    : q.kind === 'score' ? { type: 'score', instructions: q.instructions, criteria: q.levels }
-    : { type: 'noul', instructions: q.instructions },
-  ]));
-  const res = await env.AI.run('typesafe/jev', { state, questions: jevQuestions });
-  const answers = Object.fromEntries(Object.entries(res.answers).map(([key, a]: [string, any]) => [key,
-    a.type === 'choice' ? { kind: 'choice', choice: a.choice, confidence: a.confidence, probabilities: a.probabilities }
-    : a.type === 'score' ? {
-        kind: 'score', score: a.score, confidence: a.confidence,
-        probabilities: Object.keys(a.probabilities).sort((x, y) => Number(x) - Number(y)).map((k) => a.probabilities[k]),
-      }
-    : { kind: 'binary', probability: a.noul },
-  ]));
-  return { answers };
-};
-```
-
-## OKF Import/Export
-
-The core package integrates with `@equationalapplications/core-okf` to seamlessly adapt wiki data dumps to and from Open Knowledge Format (OKF) bundles (v0.1 and v0.2; `formatOkfBundle` defaults to the v0.2 / `llm-wiki/2` profile).
-
-### Exporting an OKF Bundle
-
-Convert an existing wiki dump into a flat array of OKF files, ready to be written to disk or zipped:
-
-```typescript
-import { formatOkfBundle } from '@equationalapplications/core-llm-wiki';
-
-const dump = await wiki.exportDump(['entity-123']);
-const { files } = formatOkfBundle(dump);
-
-// files: Array<{ path: string; content: string }>
-// e.g., [{ path: 'entities/entity-123/facts/fact_abc.md', content: '---\n...' }]
-```
-
-### Importing an OKF Bundle
-
-Parse raw OKF files back into a `MemoryDump` that the wiki can ingest:
-
-```typescript
-import { parseOkfBundle } from '@equationalapplications/core-llm-wiki';
-
-// Assuming you read OKF files for this entity (e.g. under `entities/entity-123/`) from disk/zip into OkfFile[] shape
-const dump = parseOkfBundle('entity-123', files, {
-  defaultSchema: 'fact',
-  typeMapping: {
-    'custom_type': 'fact',
-    'archived': 'ignore', // Skips these concepts
-  },
-});
-
-await wiki.importDump(dump, { merge: true });
-```
-
-**Routing Precedence:** Concepts are routed into either the `entries` (facts) or `tasks` tables based on a three-step fallback:
-
-1. `OkfImportOptions.typeMapping` explicitly mapping an OKF `type` to `'fact'`, `'task'`, or `'ignore'`.
-2. Directory convention (e.g., files in `/facts/` become facts, `/tasks/` become tasks).
-3. The `OkfImportOptions.defaultSchema` (defaults to `'fact'`).
-
-### WikiEdge and the `## Related` Section
-
-A `WikiEdge` represents a directed link between two concepts (`source_id`, `target_id`, `edge_type`). In profile llm-wiki/1, edges are serialized in a trailing `## Related` section on each concept file. `parseOkfBundle()` extracts them into `WikiEdge` rows and strips the section from stored bodies; `formatOkfBundle()` emits the section from the `edges` array in the dump.
-
-See [`docs/okf-profile.md`](https://github.com/equationalapplications/expo-llm-wiki/blob/main/docs/okf-profile.md) for the full normative spec and [`packages/okf/fixtures/`](https://github.com/equationalapplications/expo-llm-wiki/tree/main/packages/okf/fixtures) for conformance bundles.
-
-`importDump` persists an imported entity summary (profile ≥ 1 bundles) and
-`exportDump` re-emits it, so the profile §4 round-trip holds across storage.
-Read it directly with `wiki.getEntitySummary(entityId)`. The value lives in the
-`{prefix}meta` table under `entity_summary:{entity_id}` and is removed by
-`forget(entityId, { clearAll: true })`. See the
-[design spec](../../docs/superpowers/specs/2026-07-05-okf-summary-persistence-design.md)
-for import/merge semantics and wipe-path cleanup.
-
-### The `okf_type` Field
-
-Facts and tasks include a nullable `okf_type` column. This preserves the literal OKF `type` string from an imported bundle frontmatter, independent of whether the item was routed to the `entries` or `tasks` table. When `formatOkfBundle` runs, it restores this specific string, falling back to `'fact'` or `'task'` if the field is null (ensuring non-imported rows export cleanly).
-
-## Security
-
-`@equationalapplications/core-llm-wiki` enforces multiple security layers:
-
-### VectorRanker Adapter Security
-
-If implementing a custom `VectorRanker`:
-
-- **SQL Injection**: ALWAYS use parameterized queries for `entityId`, `factId`, `candidateIds`. Never concatenate into SQL strings.
-- **Entity Isolation**: Filter by `entityId` in all queries to prevent cross-tenant data leaks.
-- **Credential Scrubbing**: Strip API keys, tokens, connection strings from thrown errors before surfacing to host.
-- **Resource Limits**: Cap `limit` and `candidateIds.length` to prevent DoS. Do NOT retain `vector` references beyond callback scope — blocks GC.
-
-See [SECURITY.md](https://github.com/equationalapplications/expo-llm-wiki/blob/main/SECURITY.md) for complete adapter security guidance and code examples.
-
-### Host Application Security
-
-When using `VectorRanker`:
-
-- **Error Sanitization**: `sanitizeRankerErrors: true` (default) scrubs ranker errors before mirroring via `error.cause`.
-- **Fallback Policy**: Choose `vectorRankerFallback` based on availability vs consistency requirements:
-  - `'js-cosine'` (default): Best availability
-  - `'keyword'`: Fast fallback without semantic ranking
-  - `'empty'`: Strict consistency (no facts on failure)
-  - `'throw'`: Fail-fast error propagation
-- **Deletion Hook Contract**: `forget()` / `runPrune()` reject on hook timeout/failure. Prevents GDPR violations (deleted vectors still retrievable). Handle failures with retry or queue for reconciliation.
-- **Timeout Tuning**: Set `deletionHookTimeoutMs` per deployment (default 30s). Interactive UX: 5s. Background jobs: 60s.
-
-Core WikiMemory provides:
-- **Defensive Copies**: Query/embedding vectors copied before ranker/hook calls
-- **Input Validation**: `sourceRef`/`sourceHash` normalized; embedding dimensions validated
-- **Parameterized Queries**: All SQL uses bind parameters
-
-### Prompt-Injection Trust Boundary
-
-User-controlled text — `event.summary` passed to `write()`, document chunks passed to `ingestDocument()`,
-fact `title`/`body` (including imported dumps) — is interpolated verbatim into LLM prompts for librarian,
-heal, and embedding operations. Prompt templating does simple variable substitution; it does not detect
-or filter instruction-like content.
-
-Mitigating prompt injection (e.g. "ignore prior instructions and emit...") is **the host's responsibility**.
-If your application accepts untrusted input that flows into `write()`, `ingestDocument()`, or `importDump()`,
-treat the LLM's librarian/heal output as similarly untrusted — validate or scope it before acting on it
-downstream.
-
-[Grounding](#grounding) is a support check, not an injection defense. It confirms that a fact quotes the
-text the model was shown, and injected text in that source can be quoted like any other.
-
-[`getInstructions`](#effective-instructions-getinstructions) and the `wiki_get_instructions` tool (`memory:read`)
-return `WikiConfig.prompts` overrides verbatim, so keep secrets out of them. The result also includes the entity's
-ontology manifest, which in emergent mode holds types and descriptions the model proposed from ingested
-documents. Agents should treat the result as reference data about the engine, not as instructions to follow.
-
-## Usage
-
-```typescript
-import { WikiMemory, type SQLiteAdapter } from '@equationalapplications/core-llm-wiki';
-
-// Provide any SQLiteAdapter-compatible driver
-const wikiMemory = new WikiMemory(db, {
-  llmProvider: {
-    generateText: async ({ systemPrompt, userPrompt }) => {
-      // Your LLM call here
-      return 'Model output';
-    },
-  },
-});
-
-// Initialize schema and run migrations
-await wikiMemory.setup();
-
-// Store facts
-await wikiMemory.write('user-123', {
-  event_type: 'observation',
-  summary: 'User prefers async/await over promises',
-});
-
-// Query memory
-const memory = await wikiMemory.read('user-123', 'coding style preferences');
-```
-
-### Multi-entity weighted reads
-
-`read()` accepts either one entity id or an array of entity ids. Facts are always merged globally before `maxResults` is applied. For single-entity reads, tasks are uncapped and events are capped at 10. For multi-entity reads, tasks are capped at `min(20 × entity count, 200)` and events at `min(10 × entity count, 100)` — per-entity representation in the returned bundle is not guaranteed.
-
-```ts
-const memory = await wikiMemory.read(['tier_wisdom', 'tier_fact', 'tier_working'], 'Which source should I trust?', {
-  maxResults: 8,
-  tierWeights: {
-    tier_wisdom: 2,
-    tier_fact: 1,
-    tier_working: 0.25,
-  },
-});
-
-console.log(memory.metadata);
-console.log(memory.factScores);
-```
-
-### Librarian prompt override contract
-
-Core exports prompt utilities for weighted retrieval-based synthesis. Use `mapLibrarianOptionsToReadOptions()` to map `entityWeights` to `tierWeights`, then hydrate a prompt with `query`, `context`, and `tasks`.
-
-```ts
-import {
-  DEFAULT_LIBRARIAN_SYNTHESIS_PROMPT,
-  formatContext,
-  hydrateLibrarianPrompt,
-  mapLibrarianOptionsToReadOptions,
-  validateLibrarianPromptTemplate,
-} from '@equationalapplications/core-llm-wiki';
-
-const options = {
-  entityWeights: { tier_wisdom: 2, tier_fact: 1, tier_working: 0.25 },
-  systemPrompt: `You are a strict fact checker.
-Question:
-{{query}}
-
-Retrieved context:
-{{context}}
-
-{{tasks}}`,
-};
-
-const query = 'Which source should I trust for recent project decisions?';
-
-const memory = await wikiMemory.read(['tier_wisdom', 'tier_fact', 'tier_working'], query, {
-  ...mapLibrarianOptionsToReadOptions(options),
-  maxResults: 8,
-});
-
-const template = options.systemPrompt ?? DEFAULT_LIBRARIAN_SYNTHESIS_PROMPT;
-const warnings = validateLibrarianPromptTemplate(template, {
-  custom: options.systemPrompt != null,
-  taskCount: memory.tasks.length,
-});
-
-for (const warning of warnings) console.warn(warning);
-
-const finalPrompt = hydrateLibrarianPrompt(template, {
-  query,
-  context: formatContext(memory, { includeEntityIds: true, includeFactScores: true }),
-  tasks: formatContext({ facts: [], tasks: memory.tasks, events: [] }, { format: 'plain' }),
-});
-```
-
-## Platform Random Source
-
-Wiki record IDs must be cryptographically random. The core engine resolves a random source in this order:
-
-1. `crypto.randomUUID()` (Web / Node 19+)
-2. `crypto.getRandomValues()` (Web / Node / polyfilled global)
-3. A source injected via `configureRandomSource()` (e.g. `expo-crypto` on Hermes/React Native)
-
-Web and Node are unchanged — global `crypto` wins when present. React Native / Hermes typically has no `crypto` global; use a platform package or inject your own implementation:
-
-```typescript
-import { configureRandomSource } from '@equationalapplications/core-llm-wiki';
-import { getRandomValues } from 'expo-crypto';
-
-// Call once at module load, before any wiki writes
-configureRandomSource(getRandomValues);
-```
-
-`@equationalapplications/expo-llm-wiki` does this automatically on import (main entry and `/factory` subpath). If you use `@equationalapplications/core-llm-wiki` directly on React Native without the expo package, you must call `configureRandomSource()` yourself or polyfill `globalThis.crypto.getRandomValues`.
-
-## Entity Enumeration
-
-List all entities that have stored data in the wiki:
-
-```typescript
-const entityIds = await wikiMemory.listEntityIds();
-// Returns all entity_ids with at least one row (including soft-deleted-only entities)
-// Optional prefix filter: await wikiMemory.listEntityIds({ prefix: 'tier_' });
-```
-
-Use this for maintenance scheduling, multi-entity operations, or discovering which namespaces exist. Includes entities with only soft-deleted rows so `runPrune()` can reclaim orphaned storage.
-
-## Source Reference Enumeration
-
-List all documents currently stored for an entity:
-
-```typescript
-const sourceRefs = await wikiMemory.listSourceRefs('user-123');
-// One row per live sourceRef (soft-deleted rows are excluded):
-// Array<{ sourceRef: string; sourceHash: string | null; factCount: number; lastIngestedAt: number }>
-// factCount — number of live facts under that sourceRef
-// lastIngestedAt — Unix timestamp in ms from the most recently updated live entry
-```
-
-Use this to audit stored documents, validate external sync state, or preview the blast radius before `forget()` operations.
-
-## Direct Graph Write
-
-Write structured graph data directly without LLM extraction — useful for programmatic fact ingestion, parsers, and deterministic pipelines:
-
-```typescript
-const { nodesWritten, edgesWritten, superseded } = await wikiMemory.upsertGraph('entity-123', {
-  sourceRef: 'codebase_main.ts',
-  sourceHash: sha256(sourceCode),
-  nodes: [
-    { id: 'fn_processData', type: 'function', title: 'processData', body: 'Processes user data' },
-    { id: 'class_UserService', type: 'class', title: 'UserService', body: 'User management service' },
-  ],
-  edges: [
-    { type: 'calls', sourceId: 'fn_processData', targetId: 'class_UserService' },
-  ],
-}, adapter); // SQLiteAdapter from your platform driver — writes join the caller's transaction
-```
-
-`upsertGraph` is "the tail of `ingestDocument` with the middle (LLM extraction) step removed" — it accepts caller-supplied nodes (`{ id, type, title, body? }`) and edges (`{ type, sourceId, targetId, id? }`) and writes them under the same `(sourceRef, sourceHash)` semantics. If a *different* live `sourceRef` already holds the same `sourceHash`, it throws `WikiSourceRefHashCollision`; re-writing the identical `(sourceRef, sourceHash)` is a no-op returning zero counts. The adapter parameter is required so writes participate in the caller's transaction.
-
-Core never sees your transaction commit, so it can't index the new nodes itself. Until you tell it, they won't show up in keyword or hybrid `read()` results on the same instance. Call `syncSearchIndex` **after** the commit, not inside the transaction:
-
-```typescript
-await db.withTransactionAsync((tx) => wikiMemory.upsertGraph('entity-123', params, tx));
-await wikiMemory.syncSearchIndex('entity-123'); // or syncSearchIndex() for every entity written
-```
-
-It is cheap on an entity that is already current, runs in order with core's own index syncs, and never rejects for a valid `entityId` (an empty or non-string id throws `TypeError`). It does not compute embeddings; those still come from the maintenance sweep.
-
-Entry IDs occupy one globally shared namespace within a database. An ID belongs
-to its existing entity while its row exists, including after soft deletion.
-Same-entity updates and resurrection retain their existing behavior; physically
-absent IDs may be inserted. Hosts remain responsible for authenticating callers
-and selecting the authorized entity ID. Entity-qualified deterministic IDs can
-avoid accidental collisions, but are not required by the API.
-
-A foreign node ID rejects the entire non-no-op graph write with
-`WikiGraphNodeOwnershipConflict` (code `WIKI_GRAPH_NODE_OWNERSHIP_CONFLICT`).
-The error does not identify the owner, conflicting node, or stored details.
-A collision visible to node preflight performs no persistent writes, including
-seed-manifest writes. The live source-hash probe still runs first: an identical
-mapping is a zero-count no-op; a different live reference retains its hash
-collision error. Deleted source-reference mappings do not trigger that probe.
-
-Call `upsertGraph` inside the host transaction and pass that callback's `tx`.
-It neither starts nor ends a transaction. Propagate later failures so the host
-transaction rolls back partial writes; catching a late error and committing is
-not atomic. Foreign edge-ID collisions retain their existing late bare `Error`
-and require host rollback, even though the foreign edge is never overwritten.
-
-`ingestDocument` shares ownership enforcement on both its full and partial paths
-and may also throw `WikiGraphNodeOwnershipConflict`. It normally generates new
-IDs, so collisions are unexpected. Unlike direct graph preflight, ingestion may
-already have persisted ontology or other state when rejection occurs; its
-transaction rollback, not a zero-write preflight guarantee, protects atomicity.
-
-## Duplicate Hash Detection
-
-Control behavior when a different live `sourceRef` already holds the same `sourceHash`. The option is passed as a third argument to `ingestDocument`, not inside the params object:
-
-```typescript
-await wikiMemory.ingestDocument(
-  'entity-123',
-  {
-    sourceRef: 'doc.md',
-    sourceHash: sha256(content),
-    documentChunk: content,
-  },
-  { onDuplicateHash: 'ingest' }  // 'ingest' (default) | 'skip' | 'throw'
-);
-```
-
-- `'ingest'` (default): No duplicate pre-check; extraction proceeds as before this option existed. If a different live `sourceRef` is found holding the same hash at commit time (a concurrent-writer race caught by the source-ref unique index), the call still throws `WikiDuplicateHashError`.
-- `'skip'`: Pre-check before any LLM call; if a different live `sourceRef` already holds the hash, return a zero-chunk result without writing.
-- `'throw'`: Pre-check before any LLM call; throw `WikiDuplicateHashError` (carries the canonical `sourceRef`).
-- The guard only considers **live** references — soft-deleted refs do not trigger it in any mode.
-
-When the pre-check passes but a concurrent writer claims the hash before the write commits, the transaction rolls back after the LLM extraction has already run. You still receive the diagnostics that describe that extraction — `ingest_chunk_failed`, `fact_rejected` and `fact_deduplicated` — in every mode, and also in the rarer case where the winning writer has itself rolled back by the time core looks, so the call surfaces the raw database error instead of `WikiDuplicateHashError`. Diagnostics tied to the rolled-back write (`grounding_*`, `edge_dropped`) are dropped, because the `factId`s they carry name rows that were never committed.
-
-## Batch Change Detection
-
-Check multiple documents for changes in one call:
-
-```typescript
-const batch = [
-  { sourceRef: 'doc1.md', sourceHash: sha256(content1) },
-  { sourceRef: 'doc2.md', sourceHash: sha256(content2) },
-  { sourceRef: 'doc3.md', sourceHash: sha256(content3) },
-];
-const changes = await wikiMemory.hasChanged('entity-123', batch);
-// changes: Array<{ sourceRef: string; changed: boolean; duplicateOf?: string }>
-// duplicateOf — when present, the canonical stored different sourceRef holding
-// the same hash (DB-normalized spelling; sourceRef echoes the raw caller value).
-// Per-document change detection; internally batched across queries
-```
-
-`pendingSources` returns one status per input, in order, and adds the partial-ingest state:
-
-```typescript
-const statuses = await wikiMemory.pendingSources('entity-123', batch);
-// Array<{ sourceRef: string; status: 'new' | 'changed' | 'partial' | 'current' }>
-```
-
-- `current` means exactly what `hasChanged` returning `false` means.
-- `partial` means live facts exist for the ref, but none has a stored hash: for example a first ingest where a chunk failed, or imported rows that carry no hash. Re-ingest to retry. A failed re-ingest of a ref that already has hashed rows reports `changed`, not `partial`.
-
-## Lint
-
-Read-only health report for one entity. It reports problems and never repairs them.
-
-```typescript
-const report = await wikiMemory.lint('entity-123');
-// {
-//   danglingEdges,       // source or target missing, soft-deleted, or another entity's
-//   manifestViolations,  // (source type, edge type, target type) not in the effective manifest
-//   untypedFacts,        // okf_type is null
-//   drafts,              // lifecycle_status = 'draft' (see Draft Review)
-//   unverifiedInferred,  // librarian_inferred facts with no okf_verified entry
-//   sample: { danglingEdgeIds, manifestViolationEdgeIds }, // up to 20 each
-// }
-```
-
-- Manifest violations are 0 when ontology is off or the manifest is empty.
-- An edge with an untyped endpoint counts as a violation.
-- Partial-ingest rows are not reported here; use `pendingSources`.
-
-## Dry-Run Deletion
-
-Preview deletion impact without writing:
-
-```typescript
-const preview = await wikiMemory.forget('entity-123', { sourceRef: 'doc.md' }, { dryRun: true });
-// preview: { deleted: { entries: number; tasks: number } }
-// No database writes performed; safe for blast-radius validation
-```
-
-## Chunking Utilities
-
-`ingestDocument()` splits a document into chunks before extraction. That same chunking is exported as a pure function, so a consumer can reproduce ingest-time chunk boundaries exactly — useful for recovering the passage a fact was extracted from, by re-chunking the source and ranking chunks against the fact's stored embedding.
-
-```typescript
-import {
-  chunkText,
-  safeSlice,
-  DEFAULT_MAX_CHUNK_LENGTH,  // 12000
-  DEFAULT_CHUNK_OVERLAP,     // 400
-} from '@equationalapplications/core-llm-wiki';
-
-const { chunks, truncated } = chunkText(
-  sourceDocument,
-  DEFAULT_MAX_CHUNK_LENGTH,
-  DEFAULT_CHUNK_OVERLAP
-);
-```
-
-`chunkText(input, maxChunkLength, overlap)` returns `{ chunks, truncated }`. It prefers to split on a paragraph break, then a sentence terminator, then whitespace, falling back to a hard cut only when none is found within the window — `truncated` is `true` if any split needed that fallback. Consecutive chunks repeat up to `overlap` characters so context isn't lost at a boundary (less than `overlap` when the previous chunk was shorter than that). Empty/whitespace-only input returns `{ chunks: [], truncated: false }` without validating `maxChunkLength`/`overlap`; otherwise throws if `maxChunkLength` is not an integer >= 2, or if `overlap` is not a non-negative integer < `maxChunkLength`.
-
-`safeSlice(value, start, end?)` slices like `String.prototype.slice` but clamps out-of-range indices, swaps a start-after-end range, and never splits a UTF-16 surrogate pair.
-
-`DEFAULT_MAX_CHUNK_LENGTH` and `DEFAULT_CHUNK_OVERLAP` are the values `ingestDocument()` uses when neither the call nor `WikiConfig` overrides them. Pass the same values your host app configured (`config.maxChunkLength` / `config.chunkOverlap`) to match a non-default ingest.
-
-> **Note:** `ingestDocument()` clamps the resolved overlap — whether it came from `chunkOverlap`, `WikiConfig`, or `DEFAULT_CHUNK_OVERLAP` — to `maxChunkLength - 1`. The clamp is evaluated on every call and is a no-op at the shipped defaults (`400 < 12000 - 1`), but it also bites when a custom `maxChunkLength` alone leaves the resolved overlap too large (e.g. `maxChunkLength: 100` with the default overlap `400` ingests at an effective overlap of `99`). That clamp is internal: passing the unclamped pair straight to `chunkText` throws, since it requires `overlap < maxChunkLength`. Apply the same `Math.min(overlap, maxChunkLength - 1)` yourself when re-chunking under a custom config.
-
-## Schema Migrations
-
-`wikiMemory.setup()` runs pending schema migrations in order and records the applied version. Migrations are additive and safe to re-run.
-
-**Migration v9** (`add_live_hash_unique_index`) adds a partial `UNIQUE` index on `(entity_id, source_hash)` scoped to live (`deleted_at IS NULL`), non-null-hash rows. This closes a TOCTOU race where two concurrent `ingestDocument()` calls for different `sourceRef`s could both pass the duplicate-hash pre-check before either write committed, leaving two live rows with the same content hash.
-
-If your existing database already has live rows that violate this invariant (created before the app-level race fix shipped), `setup()` throws:
-
-```text
-Migration v9 (add_live_hash_unique_index) failed: existing live rows violate the new UNIQUE index. …
-```
-
-The error lists the offending `(entity_id, source_hash)` groups. `setup()` performs no destructive cleanup on this path — the index is not created and the schema version is not advanced, so it's safe to retry after remediation. To remediate, either soft-delete (or re-ingest with a corrected `sourceRef`) all but one live row per listed group, then re-run `setup()`.
-
-## Adapter Interface
-
-Implement `SQLiteAdapter` to use your platform's SQLite driver:
-
-```typescript
-export interface SQLiteAdapter {
-  execAsync(sql: string): Promise<void>;
-  runAsync(sql: string, params?: unknown[]): Promise<{ changes: number; lastInsertRowId: number }>;
-  getAllAsync<T>(sql: string, params?: unknown[]): Promise<T[]>;
-  getFirstAsync<T>(sql: string, params?: unknown[]): Promise<T | null>;
-  withTransactionAsync<T>(fn: (tx: SQLiteAdapter) => Promise<T>): Promise<T>;
-  closeAsync(): Promise<void>;
-}
-```
-
-`runAsync().changes` must accurately count written rows: a conflict-suppressed
-write reports 0, while a permitted value-identical update still counts its row.
-Host adapters are responsible for this contract; see the full affected-row
-requirements on [`SQLiteAdapter.runAsync`](src/types.ts). Ownership checks,
-edge counts, metadata compare-and-set, and maintenance depend on accurate counts.
-
-`@equationalapplications/expo-llm-wiki` provides a pre-built adapter for Expo/React Native. For web and Node.js, implement the interface yourself — examples below.
-
-**Browser ([sql.js](https://github.com/sql-js/sql.js)):**
-
-```typescript
-import initSqlJs from 'sql.js';
-import type { SQLiteAdapter } from '@equationalapplications/core-llm-wiki';
-
-const SQL = await initSqlJs({ locateFile: (f) => `/wasm/${f}` });
-const sqlDb = new SQL.Database();
-
-const adapter: SQLiteAdapter = {
-  async execAsync(sql) { sqlDb.run(sql); },
-  async runAsync(sql, params = []) {
-    sqlDb.run(sql, params as any[]);
-    // sql.js doesn't expose lastInsertRowId; hardcode 0 since WikiMemory uses internal ID generation
-    return { changes: sqlDb.getRowsModified(), lastInsertRowId: 0 };
-  },
-  async getAllAsync<T>(sql, params = []) {
-    const stmt = sqlDb.prepare(sql);
-    stmt.bind(params as any[]);
-    const rows: T[] = [];
-    while (stmt.step()) rows.push(stmt.getAsObject() as T);
-    stmt.free();
-    return rows;
-  },
-  async getFirstAsync<T>(sql, params = []) {
-    const stmt = sqlDb.prepare(sql);
-    stmt.bind(params as any[]);
-    const row = stmt.step() ? stmt.getAsObject() as T : null;
-    stmt.free();
-    return row;
-  },
-  async withTransactionAsync(fn) {
-    sqlDb.run('BEGIN');
-    try { const r = await fn(this); sqlDb.run('COMMIT'); return r; }
-    catch (e) { sqlDb.run('ROLLBACK'); throw e; }
-  },
-  async closeAsync() { sqlDb.close(); },
-};
-```
-
-**Node.js ([better-sqlite3](https://github.com/WiseLibs/better-sqlite3)):**
-
-```typescript
-import Database from 'better-sqlite3';
-import type { SQLiteAdapter } from '@equationalapplications/core-llm-wiki';
-
-const db = new Database('wiki.db');
-
-const adapter: SQLiteAdapter = {
-  async execAsync(sql) { db.exec(sql); },
-  async runAsync(sql, params = []) {
-    const info = db.prepare(sql).run(...(params as any[]));
-    return { changes: info.changes, lastInsertRowId: Number(info.lastInsertRowid) };
-  },
-  async getAllAsync<T>(sql, params = []) {
-    return db.prepare(sql).all(...(params as any[])) as T[];
-  },
-  async getFirstAsync<T>(sql, params = []) {
-    return (db.prepare(sql).get(...(params as any[])) ?? null) as T | null;
-  },
-  async withTransactionAsync(fn) {
-    db.exec('BEGIN');
-    try { const r = await fn(this); db.exec('COMMIT'); return r; }
-    catch (e) { db.exec('ROLLBACK'); throw e; }
-  },
-  async closeAsync() { db.close(); },
-};
-```
-
-## Concurrency
-
-All write APIs are safe to call from concurrent async contexts. Transactions are
-serialized internally on the single database connection — you never need to know that
-SQLite forbids nested `BEGIN`, and you never need to throttle callers yourself.
-
-- One connection per database file per process is the supported topology.
-- Non-transactional reads are **not** serialized, so read latency is unaffected.
-- Inside a transaction callback, use only the provided `tx` handle — never the outer
-  database handle. Using the outer handle deadlocks; opening a nested transaction throws.
-
-### `WikiTransactionError`
-
-Thrown when a SQLite driver error escapes a transaction (nested `BEGIN`,
-`SQLITE_BUSY`, constraint violation). Stable `instanceof` target for observability:
-
-- `error.cause` — the original driver error (the chain bottoms out here, not at a
-  rollback red herring).
-- `error.sqliteErrorCode` — best-effort SQLite code (e.g. `'SQLITE_BUSY'`), present
-  when it can be parsed. Group on this in Sentry/Datadog instead of inspecting
-  `error.cause` recursively.
-
-Domain errors thrown from your own callback logic (validation, `WikiBusyError`)
-pass through unwrapped with their original type intact.
-
-## How It Works
-
-```mermaid
-flowchart TD
-    A["read(entityId | entityId[], query, options?)"] --> B{hybridWeight = 0?}
-    B -->|Yes| C["MiniSearch only<br/>(skip embed)"]
-    B -->|No| D{embed available?}
-    D -->|No| C
-    D -->|Yes| F["Embed query"]
-    F -->|throws| E["onRetrievalFallback<br/>callback"]
-    E --> C
-    F -->|succeeds| G{preFilterLimit<br/>active?}
-    G -->|Yes| H["MiniSearch pre-filter<br/>top K candidates"]
-    H --> I["Phase 1: Cosine score<br/>top K candidates"]
-    G -->|No| J["Phase 1: Cosine score<br/>all facts"]
-    J --> K["Cache vectors<br/>in-memory<br/>(full scan only)"]
-    K --> L{hybridWeight = 1?}
-    I --> L
-    L -->|Yes| M["Pure semantic<br/>ranking"]
-    L -->|No| N["Hybrid blend:<br/>semantic + keyword<br/>via MiniSearch"]
-    M --> O["Phase 2: Fetch full rows<br/>top maxResults"]
-    N --> O
-    C --> P["MiniSearch ranking"]
-    P --> O
-    O --> R["Track access"]
-    R --> Q["Return MemoryBundle"]
-```
-
-The flowchart shows:
-1. **Fast-path** when `hybridWeight = 0` (pure keyword, no embed cost)
-2. **Fallback chain** when embed unavailable (MiniSearch silently) or throws (`onRetrievalFallback` callback, then MiniSearch)
-3. **Pre-filtering** to limit cosine scoring to top-K keyword matches (O(N) → O(K))
-4. **Two-phase SELECT**: phase 1 scores all/filtered facts with minimal columns, phase 2 fetches full rows for winners
-5. **Hybrid scoring** to blend semantic and keyword rankings
-6. **Vector caching** on full scans only; reads with `preFilterLimit` active skip cache population
+The [Node.js quickstart](https://equationalapplications.github.io/expo-llm-wiki/start/quickstart-node/) shows a complete `adapter` and `llmProvider`.
 
 ## Monorepo Ecosystem
 
@@ -1633,30 +62,6 @@ The flowchart shows:
 | [@equationalapplications/schema-software-org](https://github.com/equationalapplications/expo-llm-wiki/blob/main/packages/schema-software-org/README.md) | Software-organization executive ontology manifest — 17 node types, 40 edges, warm-agent superset, data-only |
 | [@equationalapplications/mcp-server](https://github.com/equationalapplications/expo-llm-wiki/blob/main/packages/mcp-server/README.md) | MCP server exposing SynapseTree memory tools to coding agents |
 
-## OKF v0.2 conformance (llm-wiki/2)
-
-`formatOkfBundle` defaults to `okf_version: 0.2` + `profile: llm-wiki/2`. To force a v0.1 export, pass `{ profile: 'llm-wiki/1' }`:
-
-```ts
-formatOkfBundle(dump, { profile: 'llm-wiki/1' });
-```
-
-`parseOkfBundle` auto-detects the profile from the root index frontmatter:
-
-- `profile === 'llm-wiki/2'` → v0.2 path (new fields populated).
-- `profile === 'llm-wiki/1'` → v0.1 path (unchanged behavior).
-- `profile === undefined && okf_version === '0.1'` → v0.1 legacy path.
-- `profile === undefined && okf_version === undefined` → profile-0 (legacy) path.
-
-New public methods on `WikiMemory` for OKF v0.2 trust/provenance writes (each DAO method omits `updated_at` from its SQL):
-
-- `writeOkfTrust(entryId, entityId, verified)`
-- `writeOkfSources(entryId, entityId, sources)`
-- `setLifecycleStatus(entryId, entityId, status)`
-- `setStaleAfter(entryId, entityId, date | null)`
-- `setGeneratedBy(entryId, entityId, actor)`
-- (and `…Task` variants of all five)
-
 ## License
 
 MIT