@hraness/oh 0.2.3

package/package.json

@@ -0,0 +1,121 @@
+{
+  "name": "@hraness/oh",
+  "version": "0.2.3",
+  "description": "open-source tools for agentic research",
+  "type": "module",
+  "license": "MIT",
+  "author": "Hraness",
+  "homepage": "https://oh.computer",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hraness/oh.git"
+  },
+  "bugs": {
+    "url": "https://github.com/hraness/oh/issues"
+  },
+  "keywords": [
+    "agentic-research",
+    "knowledge-graph",
+    "ontology",
+    "sqlite"
+  ],
+  "private": false,
+  "sideEffects": false,
+  "packageManager": "bun@1.3.14",
+  "engines": {
+    "bun": ">=1.3.14",
+    "node": ">=24"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "oh": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./sdk": {
+      "types": "./dist/sdk.d.ts",
+      "import": "./dist/sdk.js"
+    },
+    "./store": {
+      "types": "./dist/store.d.ts",
+      "import": "./dist/store.js"
+    },
+    "./libsql": {
+      "types": "./dist/libsql.d.ts",
+      "import": "./dist/libsql.js"
+    },
+    "./sqlite": {
+      "types": "./dist/sqlite/index.d.ts",
+      "import": "./dist/sqlite/index.js"
+    },
+    "./sync": {
+      "types": "./dist/sync.d.ts",
+      "import": "./dist/sync.js"
+    },
+    "./semantic": {
+      "types": "./dist/semantic.d.ts",
+      "import": "./dist/semantic.js"
+    },
+    "./projection": {
+      "types": "./dist/projection-public.d.ts",
+      "import": "./dist/projection-public.js"
+    },
+    "./experimental/projection-suss": {
+      "types": "./dist/projection-suss.d.ts",
+      "import": "./dist/projection-suss.js"
+    },
+    "./experimental/memory": {
+      "types": "./dist/memory.d.ts",
+      "import": "./dist/memory.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "spec",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "bun run build:js && bun run build:portable && bun run build:types",
+    "build:js": "bun build ./src/index.ts ./src/sdk.ts ./src/sqlite/index.ts ./src/sync.ts ./src/semantic.ts ./src/cli.ts --outdir ./dist --target bun --format esm --external bun:sqlite",
+    "build:portable": "bun build ./src/store.ts ./src/libsql.ts ./src/projection-public.ts ./src/projection-suss.ts ./src/memory.ts --outdir ./dist --target node --format esm --external @suss/datalog",
+    "build:types": "tsc -p tsconfig.build.json",
+    "check": "bun run typecheck && bun run test && bun run build && bun run test:types:node && bun run test:node && bun run test:node-projection",
+    "test:node": "node ./tests/node-portable.mjs",
+    "test:types:node": "tsc -p tsconfig.node-portable.json --noEmit",
+    "test": "bun test ./src ./tests ./site/tests/source.test.ts",
+    "test:node-projection": "node --test ./scripts/projection-node.test.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "devDependencies": {
+    "@suss/datalog": "0.20.0",
+    "@types/bun": "1.3.14",
+    "typescript": "5.9.3"
+  },
+  "peerDependencies": {
+    "@libsql/client": ">=0.17.4 <1",
+    "@suss/datalog": "0.20.0",
+    "@tobilu/qmd": "2.5.3"
+  },
+  "peerDependenciesMeta": {
+    "@libsql/client": {
+      "optional": true
+    },
+    "@suss/datalog": {
+      "optional": true
+    },
+    "@tobilu/qmd": {
+      "optional": true
+    }
+  }
+}

package/skills/oh/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: oh
+description: Operate a local hraness/oh ontology store through its checked CLI or SDK. Use when a coding agent needs to initialize, inspect, write, search, verify, export, import, or synchronize content-addressed research records in an Oh SQLite space.
+---
+
+# Operate Oh
+
+Keep the selected SQLite space authoritative. Inspect its contract and head
+before writing, use generation-checked mutations, and verify replay after a
+batch of changes.
+
+## Preserve authorization and location
+
+- Resolve the repository instructions that apply to the target files first.
+- Resolve the exact database path and space. Use `.oh/oh.sqlite` and `default`
+  only when they already exist or the user chose the defaults.
+- Do not run a database command against a missing path merely to inspect it.
+  Oh opens and initializes the selected database as part of normal commands.
+- Creating a database, tombstoning a record, importing a bundle, or syncing a
+  remote requires the user's request to include that write or its direct
+  workflow.
+- Never put credentials, authentication tokens, or sensitive source text into
+  a record unless the user explicitly selected an appropriately protected
+  database and destination.
+
+`oh --help` and `oh version` are side-effect-free installation checks:
+
+```sh
+oh --help
+oh version
+```
+
+The supported CLI is `@hraness/oh@0.2.3` from the immutable `v0.2.3` GitHub
+tag. It requires Bun 1.3.14 or newer. The versioned contract is published at
+<https://oh.computer/spec/>.
+
+## Open an existing space
+
+Confirm that the exact database is a regular file before a read command. First
+inspect the installed runtime contract, then replay the database operation log:
+
+```sh
+test -f .oh/oh.sqlite
+oh contract
+oh verify --db .oh/oh.sqlite --space default
+```
+
+Stop if the installed contract differs from `oh.ontology.v1`, opening the
+database reports a stored-contract mismatch, replay fails, or the user named
+another database. Do not repair an integrity or contract failure by deleting
+state.
+
+Use the narrowest read:
+
+```sh
+oh get entity:ada-lovelace --db .oh/oh.sqlite --space default
+oh list --kind statement --limit 50 --db .oh/oh.sqlite --space default
+oh log --limit 20 --db .oh/oh.sqlite --space default
+oh search "analytical engine" --mode keyword --limit 10 \
+  --db .oh/oh.sqlite --space default
+```
+
+A missing `get` exits with status 3 and prints no record. Treat it as absence,
+not a corrupt database. CLI output is canonical JSON, so parse it rather than
+scraping presentation text.
+
+## Initialize only when requested
+
+Choose a confined path owned by the user's task. Do not overwrite or merge an
+unrelated database.
+
+```sh
+oh init --db .oh/oh.sqlite --space default
+oh verify --db .oh/oh.sqlite --space default
+```
+
+Record the returned head. Add the database directory to the repository's
+ignore rules when it is local working state.
+
+## Write one checked record
+
+Choose a stable lowercase logical key and one V1 kind. Current kinds include
+`entity`, `statement`, `assertion`, `evidence`, `context`, `inquiry`, `schema`,
+`vocabulary`, and the remaining kinds printed by `oh contract`.
+
+1. Read every declared dependency with `oh get`.
+2. Run `oh verify` and take `head.generation` from its JSON result.
+3. Prepare one valid JSON value. Prefer `--file` for structured or multiline
+   content and `--json` for a short literal.
+4. Use a stable operation ID when an exact retry must be idempotent.
+5. Pass the reviewed generation.
+
+```sh
+oh put \
+  --kind statement \
+  --key statement:ada-program \
+  --depends-on entity:ada-lovelace \
+  --file /absolute/path/to/statement.json \
+  --actor agent.local \
+  --operation op_ada_program_v1 \
+  --expected-generation 4 \
+  --db .oh/oh.sqlite \
+  --space default
+```
+
+If the expected generation is stale, read the new head and affected records,
+reconcile the intended change, and create a new operation. Do not loop on a
+conflict or change the expected generation without reviewing intervening work.
+
+After a write batch, run:
+
+```sh
+oh verify --db .oh/oh.sqlite --space default
+```
+
+## Tombstone deliberately
+
+A tombstone removes the current record from the materialized graph while the
+operation remains in history. Confirm the exact key and current digest. Check
+that no retained record depends on it. Then require the reviewed generation:
+
+```sh
+oh tombstone statement:obsolete \
+  --expected-generation 5 \
+  --operation op_remove_obsolete_v1 \
+  --db .oh/oh.sqlite \
+  --space default
+```
+
+Run replay verification immediately. Do not edit SQLite tables directly to
+bypass dependency or compare-and-swap checks.
+
+## Search with explicit evidence lanes
+
+Use `keyword` for the model-free CLI path. `semantic` and `hybrid` need an SDK
+instance configured with the optional local QMD backend. If a response contains
+`semantic-unavailable`, report that diagnostic and preserve any keyword result;
+do not substitute a hosted model.
+
+Treat a search score as retrieval evidence, not proof that a research claim is
+true. Open the returned record and its dependencies before relying on it.
+
+## Export or import an operation bundle
+
+An export is read-only but writes a file when redirected. Choose the output
+path explicitly and protect it like the source research:
+
+```sh
+oh sync export --after 0 --limit 1000 \
+  --db .oh/oh.sqlite --space default > /absolute/path/to/oh-bundle.json
+```
+
+Before import, preserve the destination, inspect its contract and head, and
+confirm the bundle belongs to the same space. Import is sequential rather than
+bundle-atomic: if a later operation conflicts, an earlier valid prefix may
+already be present. After an error, inspect the destination head and run replay
+verification before retrying.
+
+```sh
+oh sync import --file /absolute/path/to/oh-bundle.json \
+  --db .oh/oh.sqlite --space default
+oh verify --db .oh/oh.sqlite --space default
+```
+
+Remote libSQL or Turso sync is an SDK workflow. The user must select the remote
+and credential source. Never print credentials or embed them in records. Oh
+settles fast-forward histories only; preserve both logs when it reports a
+divergence.
+
+## Use composite memory only through host bindings
+
+`@hraness/oh/experimental/memory` is an SDK-only surface. Do not let a model
+construct its options. Trusted application code must bind two distinct
+authority handles, exact binding digests, a pinned canonical head, working
+codecs, a working actor, domain extractor relation ownership and digests,
+host-purposed named rule/query programs, and named nomination routes before
+giving the returned object to an agent.
+
+The agent-facing object may call only `remember`, `query`, `explain`, and
+`nominate`. Never add a tool parameter for a database path or URL, authority,
+realm, space, store profile, rule pack, raw query, sync destination, canonical
+write, caller-asserted actor/time, or purge operation. Preserve lane, conflict,
+fact-policy, and premise-authority labels in query output. Treat every result
+as derived. A nomination may select only a host-registered route and is a
+prepared dependency-closure candidate for destination-owned review, not
+permission to write durable knowledge or import the working operation chain.
+
+Use `createOhMemoryAgentV2` only when the host has registered primitive
+query-body parameters and fixed all projection, row, page, and page-byte
+limits. Expose only the exact bindings object, program ID, and continuation to
+the model. Do not expose parameter declarations, page size, or evaluator
+options as tool input. Follow `hasMore` until the continuation is `null`, and
+restart the named query after an integrity error; never combine pages across a
+working-head change. A V2 `query-limit` or `result-bytes` condition is a failed
+query, not a partial answer. Treat each continuation as a bearer cursor: pass
+it back unchanged only to the exact query and do not log or edit it. If the
+host reconstructs the facade or routes across replicas, it must provide the
+same private 32 through 64 byte `continuationKey` in host options; never expose
+that key as tool input. Keep row-level `proofsTruncated` evidence visible.
+
+## Finish with evidence
+
+Report the exact database and space, reads or mutations performed, final head
+generation and operation digest, replay result, search diagnostics, and any
+sync counts. Do not claim success from a command exit alone when `oh verify`
+was part of the requested workflow.

package/skills/oh/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Oh"
+  short_description: "Operate local agentic research records"
+  default_prompt: "Use $oh to inspect and safely update my local research space."

package/spec/README.md

@@ -0,0 +1,74 @@
+# Oh specification
+
+This directory is the versioned public contract for Oh. It defines the
+canonical bytes, ontology identities, graph envelopes, schema revisions,
+SQLite and direct libSQL authority, operation sync, store profiles, and local
+embedding profile that independent implementations need to interoperate.
+
+[`manifest.json`](manifest.json) is the discovery document. V1 is current and
+binds these versions:
+
+| Component | Version |
+| --- | --- |
+| Ontology | `1.0.0` |
+| Contract ID | `oh.ontology.v1` |
+| Graph format | `1` |
+| Schema format | `1` |
+| SQLite schema | `2` |
+| Sync protocol | `oh.sync.v1` |
+| Embedding profile | `1` |
+| Projection semantics | `oh.projection.positive-datalog.v1` |
+| Composite memory | `experimental v1` |
+
+## V1 documents
+
+- [Canonical JSON and digests](v1/canonical-json.md)
+- [Ontology](v1/ontology.md)
+- [Schema evolution](v1/schema-evolution.md)
+- [Graph and operations](v1/graph.md)
+- [SQLite storage](v1/storage.md)
+- [Store ports, profiles, and direct libSQL authority](v1/store.md)
+- [Sync protocol](v1/sync.md)
+- [Local embedding profile](v1/embedding.md)
+- [Derived projections](v1/projection.md)
+- [Experimental composite agent memory](v1/memory.md)
+- [Compatibility and migration](v1/migration.md)
+
+Machine-readable V1 artifacts:
+
+- [`contract.json`](v1/contract.json)
+- [`ontology.json`](v1/ontology.json)
+- [`embedding-profile.json`](v1/embedding-profile.json)
+- [`contract.schema.json`](v1/contract.schema.json)
+- [`record.schema.json`](v1/record.schema.json)
+- [`schema-revision.schema.json`](v1/schema-revision.schema.json)
+- [`operation.schema.json`](v1/operation.schema.json)
+- [`sync-bundle.schema.json`](v1/sync-bundle.schema.json)
+- [`projection-rule-pack.schema.json`](v1/projection-rule-pack.schema.json)
+- [`projection-query.schema.json`](v1/projection-query.schema.json)
+- [`projection-identity.schema.json`](v1/projection-identity.schema.json)
+- [`projection-result.schema.json`](v1/projection-result.schema.json)
+
+## Conformance
+
+The words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY state interoperability
+requirements. JSON Schemas validate exchange structure. The narrative
+documents and runtime parsers also define canonical order, digest preimages,
+byte limits, dependency laws, and replay behavior that JSON Schema cannot
+express.
+
+An implementation conforms to V1 only when it reproduces exact canonical JSON
+and digests, rejects malformed or noncanonical input, preserves ordered
+operation history, and passes the same replay laws. Accepting more input is not
+conformance when the extra input changes persisted or exchanged bytes.
+
+## Versioning
+
+An existing version is immutable. A change to serialized keys, accepted value
+grammar, ordering, a digest preimage, a record kind, a limit, migration SQL, or
+protocol meaning needs a new version. New convenience APIs may retain the
+current contract when they produce the same checked bytes.
+
+Schema records inside an Oh graph have their own namespace, code, revision, and
+content digest. Their evolution rules are separate from the version of the Oh
+envelope itself.

package/spec/manifest.json

@@ -0,0 +1,41 @@
+{
+  "current": "v1",
+  "homepage": "https://oh.computer",
+  "package": "@hraness/oh",
+  "repository": "https://github.com/hraness/oh",
+  "v": 1,
+  "versions": [
+    {
+      "contract": "./v1/contract.json",
+      "contractId": "oh.ontology.v1",
+      "contractSha256": "e53ae573c2af417082be9f554d0f6f3e317f054daf745181f462608e3f622594",
+      "embeddingProfile": "./v1/embedding-profile.json",
+      "id": "v1",
+      "memory": {
+        "specification": "./v1/memory.md"
+      },
+      "ontology": "./v1/ontology.json",
+      "projection": {
+        "identitySchema": "./v1/projection-identity.schema.json",
+        "querySchema": "./v1/projection-query.schema.json",
+        "resultSchema": "./v1/projection-result.schema.json",
+        "rulePackSchema": "./v1/projection-rule-pack.schema.json",
+        "specification": "./v1/projection.md"
+      },
+      "schemas": [
+        "./v1/contract.schema.json",
+        "./v1/record.schema.json",
+        "./v1/schema-revision.schema.json",
+        "./v1/operation.schema.json",
+        "./v1/sync-bundle.schema.json",
+        "./v1/projection-rule-pack.schema.json",
+        "./v1/projection-query.schema.json",
+        "./v1/projection-identity.schema.json",
+        "./v1/projection-result.schema.json"
+      ],
+      "specification": "./v1/ontology.md",
+      "status": "current",
+      "v": 1
+    }
+  ]
+}

package/spec/v1/canonical-json.md

@@ -0,0 +1,59 @@
+# Canonical JSON and digests V1
+
+Every content digest in Oh is SHA-256 over UTF-8 canonical JSON. The lowercase
+64-character hexadecimal digest is part of the record, operation, schema,
+vocabulary, contract, or sync envelope that names it.
+
+## Accepted JSON
+
+V1 accepts JSON null, booleans, strings, finite numbers other than negative
+zero, arrays, and plain objects. It rejects non-finite numbers, `-0`, unpaired
+UTF-16 surrogates, cycles, non-plain objects, `undefined`, bigint, symbols, and
+functions.
+
+Canonical encoding has these rules:
+
+1. Sort object keys by JavaScript's default UTF-16 code-unit order.
+2. Preserve array order exactly.
+3. Encode strings and finite numbers with the ECMAScript JSON representation.
+4. Emit no insignificant whitespace.
+5. Preserve a valid string's code points. General canonical JSON does not
+   normalize text. Ontology text fields separately require NFC where stated.
+
+The result is RFC 8785-style canonical JSON for the narrower JSON subset
+accepted by Oh. Implementations MUST reproduce Oh's exact V1 ordering and
+number rules instead of substituting a serializer whose edge cases differ.
+
+## Parsing canonical bytes
+
+A canonical JSON parser MUST bound input before parsing, parse JSON, encode the
+value again with the V1 rules, and require byte-for-byte equality with the
+input. Pretty-printed or differently ordered JSON can be accepted as user
+input only when the receiving command explicitly canonicalizes it before the
+value reaches a persisted or exchanged boundary.
+
+## Digest preimages
+
+Each creator hashes the envelope without its own digest field:
+
+- `recordSha256` hashes `dependencies`, `key`, `kind`, `v`, and `value`.
+- `schemaSha256` hashes the schema revision without `schemaSha256`.
+- `vocabularySha256` hashes the vocabulary revision without
+  `vocabularySha256`.
+- `recordsSha256` hashes the ordered complete record-reference array. Each
+  reference contains `dependencies`, `key`, `kind`, `sha256`, and `v`.
+- `graphRevisionSha256` hashes `changes`, `operationId`,
+  `parentGraphRevisionSha256`, `recordsSha256`, `revision`, and `v`.
+- `operationSha256` hashes the operation without `operationSha256`.
+- `bundleSha256` hashes the sync bundle without `bundleSha256`.
+- `contractSha256` hashes the contract manifest without `contractSha256`.
+
+Parsers MUST recompute and compare the digest. They MUST NOT trust a digest
+because its syntax is valid.
+
+## Bounds
+
+V1 bounds a graph record value at 1,048,576 canonical UTF-8 bytes and an
+operation at 67,108,864 bytes. The general canonical text parser defaults to
+16 MiB. More specific ontology fields may have smaller limits. A receiver MUST
+apply the smallest applicable bound before unbounded allocation or work.

package/spec/v1/contract.json

@@ -0,0 +1,28 @@
+{
+  "contractId": "oh.ontology.v1",
+  "contractSha256": "e53ae573c2af417082be9f554d0f6f3e317f054daf745181f462608e3f622594",
+  "graphFormatVersion": 1,
+  "ontologyVersion": "1.0.0",
+  "recordKinds": [
+    "activity",
+    "assertion",
+    "context",
+    "dependency-manifest",
+    "edition",
+    "entity",
+    "evidence",
+    "identity-operation",
+    "inquiry",
+    "inquiry-event",
+    "review-decision",
+    "rights-decision",
+    "schema",
+    "shape",
+    "statement",
+    "type-membership",
+    "view",
+    "vocabulary"
+  ],
+  "schemaFormatVersion": 1,
+  "v": 1
+}

package/spec/v1/contract.schema.json

@@ -0,0 +1,58 @@
+{
+  "$id": "https://oh.computer/spec/v1/contract.schema.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": false,
+  "properties": {
+    "contractId": {
+      "const": "oh.ontology.v1"
+    },
+    "contractSha256": {
+      "const": "e53ae573c2af417082be9f554d0f6f3e317f054daf745181f462608e3f622594"
+    },
+    "graphFormatVersion": {
+      "const": 1
+    },
+    "ontologyVersion": {
+      "const": "1.0.0"
+    },
+    "recordKinds": {
+      "const": [
+        "activity",
+        "assertion",
+        "context",
+        "dependency-manifest",
+        "edition",
+        "entity",
+        "evidence",
+        "identity-operation",
+        "inquiry",
+        "inquiry-event",
+        "review-decision",
+        "rights-decision",
+        "schema",
+        "shape",
+        "statement",
+        "type-membership",
+        "view",
+        "vocabulary"
+      ]
+    },
+    "schemaFormatVersion": {
+      "const": 1
+    },
+    "v": {
+      "const": 1
+    }
+  },
+  "required": [
+    "contractId",
+    "contractSha256",
+    "graphFormatVersion",
+    "ontologyVersion",
+    "recordKinds",
+    "schemaFormatVersion",
+    "v"
+  ],
+  "title": "Oh contract manifest V1",
+  "type": "object"
+}

package/spec/v1/embedding-profile.json

@@ -0,0 +1,11 @@
+{
+  "dimensions": 768,
+  "distance": "cosine",
+  "documentFormat": "title: {title} | text: {content}",
+  "documentation": "https://ai.google.dev/gemma/docs/embeddinggemma",
+  "engine": "@tobilu/qmd@2.5.3",
+  "model": "hf:ggml-org/embeddinggemma-300M-GGUF/embeddinggemma-300M-Q8_0.gguf",
+  "normalization": "l2",
+  "queryFormat": "task: search result | query: {query}",
+  "v": 1
+}

package/spec/v1/embedding.md

@@ -0,0 +1,56 @@
+# Local embedding profile V1
+
+Oh semantic search is optional, local, and derived. SQLite records remain
+authoritative. Keyword search remains available without a model.
+
+## Exact profile
+
+| Field | Value |
+| --- | --- |
+| Engine | `@tobilu/qmd@2.5.3` |
+| Model | `hf:ggml-org/embeddinggemma-300M-GGUF/embeddinggemma-300M-Q8_0.gguf` |
+| Dimensions | `768` |
+| Distance | `cosine` |
+| Normalization | `l2` |
+| Documentation | `https://ai.google.dev/gemma/docs/embeddinggemma` |
+| Query format | `task: search result | query: {query}` |
+| Document format | `title: {title} \| text: {content}` |
+| Profile version | `1` |
+
+The native 768-dimensional output follows the
+[EmbeddingGemma model profile](https://ai.google.dev/gemma/docs/embeddinggemma).
+Implementations MUST NOT silently truncate it to another Matryoshka dimension
+under profile V1.
+
+## Derived document contract
+
+For each current record, Oh writes one local Markdown document whose filename
+is the SHA-256 digest of the logical key. The document includes the key, kind,
+and canonical JSON value. A canonical manifest binds that filename to the
+logical key and exact `recordSha256`.
+
+Before returning a semantic hit, Oh resolves the filename through the manifest,
+loads the current SQLite record, and requires its digest to match. Stale,
+unknown, duplicate, non-finite, or out-of-range results are discarded.
+
+## Search modes
+
+- `keyword` uses the local FTS5 index only.
+- `semantic` uses the configured local backend only.
+- `hybrid` combines keyword and semantic ranks while preserving lane, rank,
+  and score as evidence.
+
+When no semantic backend is configured, semantic and hybrid requests return a
+`semantic-unavailable` diagnostic rather than contacting a hosted provider.
+Hybrid can still return its keyword lane.
+
+## Deployment boundary
+
+The base package MUST remain usable without QMD. A serverless or browser bundle
+SHOULD exclude QMD and model artifacts. Cloud applications SHOULD keep exact
+and keyword retrieval on the request path and run semantic indexing in a
+bounded, long-lived local-model worker. Unavailable semantic search should be
+visible as a diagnostic, never replaced silently by a different model.
+
+The cache directory can contain derived record text. It needs the same local
+confidentiality treatment as the source data even though it can be rebuilt.