@aionis/substrate 0.1.4 → 0.1.6

package/docs/CLI.md

@@ -9,7 +9,8 @@ It is intentionally narrow:
 - it incrementally mirrors Runtime Lite evidence into separate Substrate stores with an explicit checkpoint;
 - it runs read-only checks over existing Runtime evidence;
 - it writes reports to local files;
-- it does not start Aionis Runtime unless you explicitly use the separate repository script `check:runtime-dual-write`;
+- it does not start Aionis Runtime unless you explicitly use a repository validation script such as
+  `check:runtime-dual-write` or `check:runtime-product-bridge`;
 - it does not mutate Runtime source code or replace Runtime storage.
 
 ## Install
@@ -214,6 +215,25 @@ npx aionis-substrate sidecar \
 
 The report contract is `aionis_runtime_sidecar_check_report_v1`.
 
+## Runtime Product Bridge Gate
+
+The package CLI is for store operations and sidecar sync. In this repository,
+use `check:runtime-product-bridge` when you need the full product bridge gate
+against a focused Runtime checkout:
+
+```bash
+npm run check:runtime-product-bridge -- \
+  --runtime-root /path/to/AionisRuntime-focused
+```
+
+The gate starts focused Runtime with isolated Lite SQLite paths, runs real
+`observe -> guide -> feedback -> measure`, writes the same observed evidence
+into an external Substrate store, verifies reopen parity, runs chain probes,
+mirrors Runtime Lite SQLite through read-only `live-sidecar`, verifies
+checkpoint idempotency, and compares mirrored Substrate `previewContext` buckets
+against Runtime guide surfaces. The top-level report is
+`product-bridge-gate-summary.json`.
+
 ## What Passing Means
 
 Passing snapshot parity means one Runtime SQLite scope can be imported into an isolated Substrate store and compiled into matching governed buckets.

package/docs/PRODUCT_CONTRACT.md

@@ -0,0 +1,136 @@
+# Aionis Substrate Product Contract
+
+Aionis Substrate is a governed memory substrate for long-running agents.
+
+It gives an agent host a durable place to store execution memory, lifecycle authority, feedback, relations, and memory-decision receipts, then compiles a scoped context object that an agent can safely use on the next turn.
+
+## Product Promise
+
+Aionis Substrate turns raw agent memory into governed working memory:
+
+- active evidence can influence the next turn;
+- stale, failed, low-authority, or payload-only evidence stays visible without silently becoming instruction;
+- raw traces can be restored through rehydrate hooks instead of flooding the prompt;
+- every context decision can leave an auditable receipt;
+- optional semantic candidate indexing can improve recall without replacing lifecycle governance.
+
+## Core Contract
+
+Substrate stores memory as append-only evidence and derived read models.
+
+| Surface | Product meaning | Primary API |
+| --- | --- | --- |
+| Evidence log | Durable record of memory writes, lifecycle transitions, relations, feedback, and decisions | `writeNode`, `transitionLifecycle`, `writeRelation`, `writeFeedback`, `compileContext` |
+| Lifecycle authority | The current status that controls whether memory can act | `active`, `contested`, `suppressed`, `archived` |
+| Admission buckets | The agent-facing context boundary | `use_now`, `inspect_before_use`, `do_not_use`, `rehydrate` |
+| Preview | Read-only context compilation for UI, planning, or dry runs | `previewContext()` |
+| Receipt | Auditable record of a context decision | `compileContext()` |
+| Backup | Checksum-covered export and restore of evidence | `exportBackup`, `restore...` |
+| Runtime bridge | Read-only import or checkpointed sidecar mirror from Aionis Runtime Lite SQLite | `importRuntimeLiteSnapshot`, `runRuntimeLiveSidecarOnce` |
+| Semantic candidate index | Optional Zvec-backed candidate narrowing before deterministic admission | `createZvecCandidateIndex` |
+
+## Admission Semantics
+
+Substrate compiles memory into four buckets.
+
+| Bucket | Meaning |
+| --- | --- |
+| `use_now` | Directly usable memory. The host may place this in the agent context as current working state. |
+| `inspect_before_use` | Relevant but uncertain memory. The agent may inspect it, but it should not be treated as an instruction. |
+| `do_not_use` | Memory blocked from direct use by lifecycle, authority, scope, or relation evidence. |
+| `rehydrate` | Pointer to raw payload or trace evidence that can be restored on demand. |
+
+This contract is intentionally stricter than ordinary vector recall. Search can find candidates; admission decides whether candidates may influence the next turn.
+
+## Host Integration Shape
+
+A host normally integrates Substrate in four calls:
+
+```ts
+import {
+  openSqliteAionisSubstrate,
+  createZvecCandidateIndex,
+  buildAionisEmbeddingDocument,
+  buildAionisEmbeddingQuery,
+} from "@aionis/substrate";
+
+const store = await openSqliteAionisSubstrate({ path: "./aionis-substrate.sqlite" });
+
+await store.writeNode({
+  id: "route-1",
+  scope: "repo-a",
+  kind: "procedure",
+  summary: "Use the active migration path after verifier passes.",
+  lifecycle: "active",
+  authority: "trusted",
+  targetFiles: ["src/migrate.ts"],
+});
+
+const context = await store.previewContext({
+  scope: "repo-a",
+  query: "continue the migration task",
+});
+
+const receipt = await store.compileContext({
+  scope: "repo-a",
+  query: "continue the migration task",
+  traceId: "agent-run-42",
+});
+```
+
+`previewContext()` gives a read-only context object. `compileContext()` produces the same governed buckets and records a decision receipt.
+
+## Embedding Projection Contract
+
+Provider embeddings should be built from stable Substrate projection helpers:
+
+```ts
+const documentText = buildAionisEmbeddingDocument(memoryNode, {
+  projection: "structured",
+});
+
+const queryText = buildAionisEmbeddingQuery(userQuery, {
+  projection: "structured",
+});
+```
+
+The current projection version is:
+
+```ts
+AIONIS_EMBEDDING_PROJECTION_VERSION
+```
+
+Hosts can use this to keep document-side and query-side embeddings aligned across providers. The projection is a recall helper; lifecycle admission still controls whether a retrieved candidate can become `use_now`.
+
+## Runtime Bridge Contract
+
+Substrate can mirror Aionis Runtime Lite SQLite into a separate store:
+
+```bash
+npx aionis-substrate import-runtime-snapshot \
+  --source ./runtime.sqlite \
+  --target ./substrate.sqlite \
+  --adapter sqlite
+
+npx aionis-substrate live-sidecar \
+  --source ./runtime.sqlite \
+  --target ./substrate.sqlite \
+  --adapter sqlite \
+  --checkpoint ./checkpoint.json
+```
+
+The bridge reads Runtime evidence and writes an external Substrate store. Runtime source storage remains untouched.
+
+## Release-Level Guarantees
+
+For `@aionis/substrate@0.1.5`:
+
+- file and SQLite adapters preserve the same admission buckets for the same evidence;
+- invalid writes do not persist partial events;
+- controlled forgetting is a lifecycle transition;
+- backup restore verifies event integrity;
+- Runtime snapshot import is read-only against Runtime source SQLite;
+- live sidecar uses checkpoint fingerprints for repeated sync;
+- published package install smoke verifies CLI and SDK import surfaces;
+- structured embedding projection is exposed as public SDK API.
+

package/docs/RUNTIME_DUAL_WRITE_EXPERIMENT.md

@@ -39,6 +39,20 @@ The compared surfaces are:
 
 ## Command
 
+Product bridge gate:
+
+```bash
+npm run check:runtime-product-bridge -- \
+  --runtime-root /Volumes/ziel/AionisRuntime-focused
+```
+
+This is the full validation path for a product bridge: real focused Runtime
+calls, external Substrate dual-write parity, reopen parity, chain probes,
+read-only `live-sidecar` mirroring, repeated sidecar idempotency, and mirrored
+`previewContext` parity.
+
+Lower-level dual-write experiment:
+
 ```bash
 npm run check:runtime-dual-write -- \
   --runtime-root /Volumes/ziel/AionisRuntime-focused \

package/docs/RUNTIME_ZVEC_CANDIDATE_INDEX.md

@@ -0,0 +1,80 @@
+# Runtime Zvec Candidate Index Check
+
+This check validates the optional Zvec candidate index against real Aionis Runtime Lite SQLite snapshots.
+
+It proves a storage/index contract:
+
+- Runtime Lite SQLite is opened read-only.
+- selected Runtime scopes are imported into an isolated Substrate SQLite store.
+- a Zvec candidate index is rebuilt from the imported Substrate nodes.
+- `verify()` must report no missing, orphan, or stale index entries.
+- wide-window Zvec candidate search must preserve canonical Substrate search ids.
+- narrow-window Zvec candidate search must still recover the seeded real Runtime memory node for exact-node probes.
+
+The check uses a deterministic local text projection to provide vectors for real imported Runtime nodes. It validates Zvec integration, write/rebuild/verify behavior, and candidate-window safety. It does not evaluate embedding-provider semantic quality.
+
+## Run
+
+```bash
+npm run check:runtime-zvec-index -- \
+  --root /Volumes/ziel/AionisRuntime-focused/.tmp \
+  --max-files 10 \
+  --max-scopes 12 \
+  --min-nodes 3 \
+  --probes-per-scope 5
+```
+
+The command writes a report under `reports/runtime-zvec-candidate-index-*` unless `--output` is supplied.
+
+## Options
+
+- `--root <path>`: Runtime directory or SQLite file to scan. Repeatable.
+- `--max-files <n|all>`: maximum Runtime SQLite files to inspect.
+- `--max-scopes <n|all>`: maximum selected scopes to validate.
+- `--max-scopes-per-file <n>`: maximum candidate scopes from each Runtime SQLite file.
+- `--min-nodes <n>`: minimum `lite_memory_nodes` rows required for a scope.
+- `--probes-per-scope <n>`: exact-node search probes to run per selected scope.
+- `--narrow-candidate-limit <n>`: Zvec candidate window for narrow recovery probes.
+- `--result-limit <n>`: final Substrate search result limit.
+- `--keep-store`: keep temporary Substrate SQLite and Zvec files for inspection.
+
+## Report Interpretation
+
+Important fields:
+
+- `passed_scopes` / `failed_scopes`: scope-level storage/index gate.
+- `total_nodes_imported`: real Runtime nodes imported into isolated Substrate stores.
+- `total_vector_indexable_nodes`: imported nodes with a deterministic vector projection.
+- `total_wide_parity_hits / total_probes_attempted`: wide candidate window preserved canonical Substrate search output.
+- `total_narrow_seed_hits / total_probes_attempted`: narrow candidate window recovered the seeded real Runtime node.
+- `zvec_health`: per-scope missing/orphan/stale index diagnostics.
+
+Failures mean the Zvec sidecar needs index-contract work before it should be used for Runtime-scale candidate preselection.
+
+## Local Validation Snapshot
+
+On 2026-06-26, the check was run against local `AionisRuntime-focused/.tmp` Runtime Lite SQLite files:
+
+```bash
+npm run check:runtime-zvec-index -- \
+  --root /Volumes/ziel/AionisRuntime-focused/.tmp \
+  --max-files all \
+  --max-scopes 20 \
+  --min-nodes 3 \
+  --probes-per-scope 8 \
+  --narrow-candidate-limit 20
+```
+
+Result:
+
+- discovered SQLite files: 30
+- Runtime SQLite files with candidate scopes: 14
+- attempted scopes: 20
+- passed scopes: 20
+- imported Runtime nodes: 3,080
+- vector-indexable nodes: 3,080
+- probes attempted: 160
+- wide candidate parity: 100%
+- narrow candidate seed hit rate: 100%
+
+This validates the Zvec storage/index contract on real Runtime snapshots. Semantic embedding quality should be measured separately with a provider-backed embedding eval because this check intentionally uses a deterministic local text projection.

package/docs/STORE_CONTRACT.md

@@ -101,6 +101,21 @@ It must:
 
 Search is not admission. It may find candidate evidence, but it must not decide whether memory can influence the next Agent turn. Governed prompt surfaces are produced by `compileContext`.
 
+### Candidate Index Contract
+
+Stores may be opened with an optional candidate index.
+
+The index contract is:
+
+- source of truth stays in the file or SQLite substrate store;
+- open rebuilds the index from durable nodes unless explicitly disabled;
+- node upserts and lifecycle transitions write through to the index after the truth store mutation succeeds;
+- `verify(nodes)` reports missing, orphan, and stale index entries;
+- indexed search may narrow candidate ids, but returned results are still canonical substrate nodes with substrate scoring and reason codes;
+- index lookup must not append events, mutate lifecycle state, or produce admission decisions.
+
+This boundary allows `createZvecCandidateIndex` and future ANN-backed adapters without turning the index into the memory database or the admission policy.
+
 ### Relation Graph
 
 Relations connect memory evidence:

package/docs/V0_2_ROADMAP.md

@@ -66,9 +66,20 @@ Make the substrate boundary easier to consume without widening policy scope:
 
 Initial implementation status: the package exposes `aionis-substrate sidecar` for read-only snapshot/reference checks, `aionis-substrate live-sidecar` for checkpointed external mirroring, and store commands for inspect, preview-context, backup, restore, compact, and Runtime snapshot import. These commands do not start Runtime, mutate Runtime storage, or implement Runtime admission policy.
 
+### 6. Candidate Index Boundary
+
+Add an optional index boundary for database-style candidate lookup:
+
+- index adapters receive write-through node updates;
+- open can rebuild the index from durable nodes;
+- `verify(nodes)` reports missing, orphan, and stale entries;
+- final search results still come from canonical Substrate nodes.
+
+Initial implementation status: `createMemoryCandidateIndex` provides a deterministic in-process candidate index with rebuild, verify, upsert, delete, and search. `createZvecCandidateIndex` provides an optional Zvec-backed candidate index for local vector preselection. File and SQLite adapters can use either one to narrow candidates before applying the existing Substrate search contract.
+
 ## Excluded
 
-- Vector search, ANN, embeddings, or semantic recall.
+- Built-in embedding generation, hosted ANN services, or semantic recall policy.
 - Full Aionis Runtime admission policy.
 - LLM-as-judge or model-generated lifecycle policy.
 - Agent orchestration or external Agent harnesses.

package/docs/ZVEC_PROVIDER_EMBEDDING_EVAL.md

@@ -0,0 +1,216 @@
+# Zvec Provider Embedding Eval
+
+This eval checks Zvec candidate preselection with real provider embeddings.
+
+It measures two different surfaces:
+
+- raw Zvec candidate hit rate: whether provider embeddings place the expected memory id in the Zvec candidate window.
+- final Substrate search hit rate: whether the current Substrate canonical search contract returns that memory after candidate narrowing.
+
+This distinction matters. Zvec is a candidate sidecar, not the truth store and not the final admission policy. SQLite remains the truth store, and Substrate reloads canonical nodes before returning search results.
+
+## Provider Contract
+
+The eval supports three provider contracts:
+
+- `openai`: OpenAI-compatible embeddings endpoints.
+- `minimax`: MiniMax native embeddings endpoint.
+- `dashscope`: Alibaba Cloud DashScope native embeddings endpoint.
+
+### OpenAI-Compatible
+
+```text
+POST <base-url><endpoint>
+Authorization: Bearer <api-key>
+Content-Type: application/json
+
+{
+  "model": "...",
+  "input": ["text one", "text two"]
+}
+```
+
+The response must contain `data[].embedding` arrays in request order or with `data[].index`.
+
+### MiniMax Native
+
+MiniMax embeddings use a native request shape:
+
+```text
+POST <base-url><endpoint>
+Authorization: Bearer <api-key>
+Content-Type: application/json
+
+{
+  "model": "embo-01",
+  "type": "db",
+  "texts": ["document text one", "document text two"]
+}
+```
+
+The eval calls MiniMax with `type: "db"` for memory-node vectors and
+`type: "query"` for query vectors. The response must contain `vectors[]`.
+
+### DashScope Native
+
+DashScope native embeddings use separate `text_type` values for document and
+query vectors:
+
+```text
+POST <base-url><endpoint>
+Authorization: Bearer <api-key>
+Content-Type: application/json
+
+{
+  "model": "text-embedding-v4",
+  "input": {
+    "texts": ["document text one", "document text two"]
+  },
+  "parameters": {
+    "text_type": "document",
+    "dimension": 1024
+  }
+}
+```
+
+The eval calls DashScope with `text_type: "document"` for memory-node vectors
+and `text_type: "query"` for query vectors. The response must contain
+`output.embeddings[].embedding` arrays, ordered by `text_index`.
+
+## Run
+
+```bash
+AIONIS_EMBEDDING_API_KEY=... \
+AIONIS_EMBEDDING_MODEL=text-embedding-3-small \
+npm run check:zvec-provider-embedding -- \
+  --base-url https://api.openai.com/v1 \
+  --nodes 240 \
+  --scopes 4 \
+  --queries 20 \
+  --candidate-limit 20
+```
+
+For another OpenAI-compatible provider:
+
+```bash
+AIONIS_EMBEDDING_API_KEY=... \
+npm run check:zvec-provider-embedding -- \
+  --base-url https://provider.example/v1 \
+  --endpoint /embeddings \
+  --model provider-embedding-model
+```
+
+For Alibaba Cloud DashScope `text-embedding-v4` through the OpenAI-compatible
+endpoint:
+
+```bash
+AIONIS_EMBEDDING_PROVIDER=openai \
+AIONIS_EMBEDDING_API_KEY=... \
+AIONIS_EMBEDDING_MODEL=text-embedding-v4 \
+npm run check:zvec-provider-embedding -- \
+  --base-url https://dashscope.aliyuncs.com/compatible-mode/v1 \
+  --endpoint /embeddings \
+  --dimensions 1024 \
+  --batch-size 10 \
+  --nodes 240 \
+  --scopes 4 \
+  --queries 20 \
+  --candidate-limit 40
+```
+
+DashScope `text-embedding-v4` accepts small batches on this endpoint, so the
+example uses `--batch-size 10`. In the current provider eval, `--candidate-limit
+40` is a better first setting than `20` because it lets Zvec act as a semantic
+candidate preselector without prematurely excluding lexical matches.
+
+For Alibaba Cloud DashScope `text-embedding-v4` through the native endpoint:
+
+```bash
+AIONIS_EMBEDDING_PROVIDER=dashscope \
+AIONIS_EMBEDDING_API_KEY=... \
+AIONIS_EMBEDDING_MODEL=text-embedding-v4 \
+npm run check:zvec-provider-embedding -- \
+  --dimensions 1024 \
+  --projection structured \
+  --query-instruct "Retrieve the Aionis Substrate memory document that best answers the implementation question." \
+  --batch-size 10 \
+  --nodes 240 \
+  --scopes 4 \
+  --queries 20 \
+  --candidate-limit 40
+```
+
+The native provider path is useful because it preserves the provider's
+query/document embedding contract instead of embedding every text through one
+generic endpoint shape.
+
+For MiniMax:
+
+```bash
+AIONIS_EMBEDDING_PROVIDER=minimax \
+AIONIS_EMBEDDING_API_KEY=... \
+AIONIS_EMBEDDING_MODEL=embo-01 \
+npm run check:zvec-provider-embedding -- \
+  --base-url https://api.minimaxi.com/v1 \
+  --nodes 240 \
+  --scopes 4 \
+  --queries 20 \
+  --candidate-limit 20
+```
+
+The command writes a report under `reports/zvec-provider-embedding-*` unless `--output` is supplied.
+
+## Options
+
+- `--provider <openai|minimax|dashscope>`: embedding provider contract. Defaults to `AIONIS_EMBEDDING_PROVIDER` or `openai`.
+- `--base-url <url>`: provider base URL. Defaults to `AIONIS_EMBEDDING_BASE_URL` or `https://api.openai.com/v1`.
+- `--endpoint <path>`: embeddings endpoint. Defaults to `AIONIS_EMBEDDING_ENDPOINT` or `/embeddings`.
+- `--model <name>`: embedding model. Defaults to `AIONIS_EMBEDDING_MODEL`.
+- `--api-key-var <name>`: environment variable containing the API key. Defaults to `AIONIS_EMBEDDING_API_KEY`.
+- `--dimensions <n>`: optional embedding dimensions request parameter.
+- `--projection <plain|structured>`: embedding text projection. `plain` embeds compact search text; `structured` uses the SDK `buildAionisEmbeddingDocument` and `buildAionisEmbeddingQuery` contract. Defaults to `structured`.
+- `--query-instruct <text>`: optional query instruction for providers that support query-side instructions.
+- `--nodes <n>`: generated Substrate nodes.
+- `--scopes <n>`: generated scopes.
+- `--queries <n>`: semantic query probes. Current built-in fixture supports up to 24.
+- `--batch-size <n>`: provider embedding batch size.
+- `--candidate-limit <n>`: Zvec candidate window.
+- `--result-limit <n>`: final Substrate search result limit.
+- `--keep-store`: keep temporary SQLite and Zvec files for inspection.
+
+## Report Interpretation
+
+Important fields:
+
+- `raw_zvec_candidate_top1_rate`: provider embedding quality at the Zvec candidate layer.
+- `raw_zvec_candidate_topk_rate`: whether the expected memory id entered the candidate window.
+- `final_substrate_topk_rate`: current end-to-end `searchNodes()` output after canonical Substrate scoring.
+- `lexical_substrate_topk_rate`: canonical deterministic search without Zvec.
+- `probe_results`: per-query raw candidate rank, final rank, lexical rank, and returned ids for miss analysis.
+- `embedding_usage`: provider requests, embedded text count, input character count, provider token count when exposed, and failed request count.
+- `zvec_health`: missing, orphan, and stale sidecar diagnostics.
+
+Current DashScope native `text-embedding-v4` smoke results with the SDK
+projection on this fixture:
+
+| Projection | Dimension | Raw Top-1 | Raw Top-K | Final Top-K | Lexical Top-K |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| `plain` | 1024 | 40% | 100% | 75% | 70% |
+| `structured` + query/document | 1024 | 45% | 100% | 85% | 70% |
+
+The useful gain comes from the SDK query/document projection contract instead
+of changing Substrate's final admission or search filters.
+
+If raw Zvec hit rate is strong but final Substrate hit rate is weaker, the provider embeddings are finding useful candidates but the final canonical scorer is still acting as a lexical/structured gate. That is a search-contract boundary, not a provider failure.
+
+The provider eval is intentionally strict about this distinction. A low final
+Substrate hit rate can happen even when provider vectors are valid if the Zvec
+candidate window excludes the expected id or if the final canonical scorer
+prefers lexical/structured evidence over semantic candidates.
+
+Substrate fuses candidate-index evidence into final `searchNodes()` ranking by
+adding auditable `semantic_candidate_fusion` reasons and preserving a small
+semantic recall floor for top-ranked candidates. This only changes ranking after
+normal scope, lifecycle, authority, confidence, team, agent, and target-file
+filters pass. Zvec still remains a sidecar candidate preselector; file/SQLite
+stores remain the truth store.

package/docs/ZVEC_SCALE_MAINTENANCE.md

@@ -0,0 +1,89 @@
+# Zvec Scale Maintenance Check
+
+This check validates the optional Zvec candidate sidecar under Substrate-scale write and maintenance operations.
+
+It proves a storage/index contract:
+
+- SQLite remains the truth store.
+- Zvec receives write-through node upserts while nodes are written.
+- `verify()` reports no missing, orphan, or stale entries after writes.
+- reopening the store rebuilds the sidecar from SQLite truth.
+- wide-window Zvec candidate search preserves canonical Substrate search ids.
+- narrow-window Zvec candidate search recovers seeded exact-node probes.
+- lifecycle transitions update the sidecar fingerprint.
+- checkpoint compaction and post-compaction reopen keep the sidecar verifiable.
+
+The check uses the same deterministic local text projection as the Runtime Zvec validation. It validates storage/index maintenance and candidate-window safety. It does not evaluate embedding-provider semantic quality.
+
+## Run
+
+```bash
+npm run check:zvec-scale -- \
+  --nodes 10000 \
+  --scopes 10 \
+  --relations 2000 \
+  --feedback 1000 \
+  --probes 100 \
+  --narrow-candidate-limit 20
+```
+
+The command writes a report under `reports/zvec-scale-*` unless `--output` is supplied.
+
+## Options
+
+- `--nodes <n>`: generated memory nodes.
+- `--scopes <n>`: generated scopes.
+- `--relations <n>`: generated relation rows.
+- `--feedback <n>`: generated feedback rows.
+- `--probes <n>`: exact-node search probes.
+- `--narrow-candidate-limit <n>`: Zvec candidate window for narrow seeded recovery probes.
+- `--transitions <n>`: lifecycle transitions to apply after reopen.
+- `--output <dir>`: report directory.
+- `--keep-store`: keep the temporary SQLite and Zvec files for inspection.
+
+## Report Interpretation
+
+Important fields:
+
+- `zvec_health.after_write`: write-through index health.
+- `zvec_health.after_reopen`: rebuild-on-open health.
+- `zvec_health.after_transitions`: lifecycle transition sync health.
+- `zvec_health.after_compact` and `after_compact_reopen`: compaction and reopen health.
+- `wide_parity_rate`: wide-window Zvec search matched canonical Substrate search.
+- `narrow_seed_hit_rate`: narrow-window Zvec search recovered seeded nodes.
+- `sqlite_bytes` and `zvec_bytes`: local storage footprint for the generated run.
+
+Any missing, orphan, stale, parity, or seeded-recovery failure means the Zvec sidecar needs maintenance work before it should be used for larger Substrate candidate preselection.
+
+## Local Validation Snapshot
+
+On 2026-06-26, the check was run locally with a 10k-node SQLite truth store and Zvec sidecar:
+
+```bash
+npm run check:zvec-scale -- \
+  --nodes 10000 \
+  --scopes 10 \
+  --relations 2000 \
+  --feedback 1000 \
+  --probes 100 \
+  --narrow-candidate-limit 20
+```
+
+Result:
+
+- nodes: 10,000
+- relations: 2,000
+- feedback records: 1,000
+- lifecycle transitions: 100
+- probes: 100
+- Zvec health after write/reopen/transitions/compact/compact-reopen: pass
+- wide candidate parity: 100%
+- narrow seeded recovery: 100%
+- SQLite bytes: 17,657,856
+- Zvec sidecar bytes: 19,528,279
+- write nodes with Zvec: 2,335 ms
+- close after write, including manifest flush: 171 ms
+- reopen and rebuild: 1,855 ms
+- post-compaction reopen and rebuild: 1,783 ms
+
+This validates the sidecar maintenance path at package scale: write-through indexing, rebuild, lifecycle-transition synchronization, compaction, and candidate-window safety all remain consistent with the SQLite truth store.