@aionis/substrate 0.1.4 → 0.1.5

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/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.

package/examples/live-sidecar/index.mjs

@@ -0,0 +1,189 @@
+import assert from "node:assert/strict";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import {
+  openSqliteAionisSubstrate,
+  runRuntimeLiveSidecarOnce,
+} from "../../dist/index.js";
+
+const scope = "repo-a";
+const workspace = await mkdtemp(join(tmpdir(), "aionis-substrate-live-sidecar-"));
+
+function createRuntimeLiteSource(path) {
+  const db = new DatabaseSync(path);
+  try {
+    db.exec(`
+      CREATE TABLE lite_memory_nodes (
+        id TEXT PRIMARY KEY,
+        scope TEXT NOT NULL,
+        client_id TEXT,
+        type TEXT NOT NULL,
+        tier TEXT NOT NULL,
+        title TEXT,
+        text_summary TEXT,
+        slots_json TEXT NOT NULL,
+        raw_ref TEXT,
+        evidence_ref TEXT,
+        embedding_vector_json TEXT,
+        embedding_model TEXT,
+        memory_lane TEXT NOT NULL,
+        producer_agent_id TEXT,
+        owner_agent_id TEXT,
+        owner_team_id TEXT,
+        embedding_status TEXT NOT NULL,
+        embedding_last_error TEXT,
+        salience REAL NOT NULL,
+        importance REAL NOT NULL,
+        confidence REAL NOT NULL,
+        redaction_version INTEGER NOT NULL,
+        commit_id TEXT NOT NULL,
+        created_at TEXT NOT NULL
+      );
+    `);
+  } finally {
+    db.close();
+  }
+}
+
+function insertRuntimeNode(path, row) {
+  const db = new DatabaseSync(path);
+  try {
+    db.prepare(`
+      INSERT INTO lite_memory_nodes (
+        id, scope, client_id, type, tier, title, text_summary, slots_json, raw_ref, evidence_ref,
+        embedding_vector_json, embedding_model, memory_lane, producer_agent_id, owner_agent_id,
+        owner_team_id, embedding_status, embedding_last_error, salience, importance, confidence,
+        redaction_version, commit_id, created_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(
+      row.id,
+      scope,
+      `client-${row.id}`,
+      row.type,
+      row.tier,
+      row.title,
+      row.summary,
+      JSON.stringify(row.slots),
+      row.rawRef ?? null,
+      row.evidenceRef ?? null,
+      null,
+      "demo-embedding",
+      "execution",
+      "agent-a",
+      "agent-a",
+      "team-a",
+      "ready",
+      null,
+      0.8,
+      0.85,
+      row.confidence,
+      1,
+      "demo-commit",
+      row.createdAt,
+    );
+  } finally {
+    db.close();
+  }
+}
+
+try {
+  const runtimeSource = join(workspace, "runtime-lite.sqlite");
+  const substrateTarget = join(workspace, "substrate.sqlite");
+  const checkpoint = join(workspace, "runtime-live-checkpoint.json");
+  createRuntimeLiteSource(runtimeSource);
+
+  insertRuntimeNode(runtimeSource, {
+    id: "current-route",
+    type: "procedure",
+    tier: "hot",
+    title: "Current route",
+    summary: "Use src/runtime.ts after verifier passed.",
+    confidence: 0.95,
+    createdAt: "2026-06-26T00:00:00.000Z",
+    slots: {
+      summary_kind: "workflow_anchor",
+      contract_trust: "trusted",
+      target_files: ["src/runtime.ts", "tests/runtime.test.ts"],
+      execution_result_summary: { status: "passed" },
+    },
+  });
+
+  insertRuntimeNode(runtimeSource, {
+    id: "failed-branch",
+    type: "procedure",
+    tier: "hot",
+    title: "Failed branch",
+    summary: "The legacy src/legacy.ts path failed the verifier and should not steer the next turn.",
+    confidence: 0.9,
+    createdAt: "2026-06-26T00:01:00.000Z",
+    slots: {
+      summary_kind: "workflow_anchor",
+      contract_trust: "rejected",
+      target_files: ["src/legacy.ts"],
+      execution_result_summary: { status: "failed" },
+    },
+  });
+
+  insertRuntimeNode(runtimeSource, {
+    id: "raw-trace",
+    type: "trace_pointer",
+    tier: "cold",
+    title: "Raw terminal trace",
+    summary: "Full terminal trace is retained as payload evidence but should only be rehydrated on demand.",
+    rawRef: "file://trace.log",
+    confidence: 0.88,
+    createdAt: "2026-06-26T00:02:00.000Z",
+    slots: {
+      summary_kind: "raw_trace_pointer",
+      target_files: ["src/runtime.ts"],
+    },
+  });
+
+  const store = await openSqliteAionisSubstrate({ path: substrateTarget });
+  try {
+    const first = await runRuntimeLiveSidecarOnce({
+      sourcePath: runtimeSource,
+      target: store,
+      checkpointPath: checkpoint,
+      scope,
+    });
+    const second = await runRuntimeLiveSidecarOnce({
+      sourcePath: runtimeSource,
+      target: store,
+      checkpointPath: checkpoint,
+      scope,
+    });
+
+    const context = await store.previewContext({
+      scope,
+      query: "continue the current runtime implementation route",
+      maxPerBucket: 8,
+    });
+
+    assert.equal(first.apply_summary.nodes.applied, 3);
+    assert.equal(second.apply_summary.nodes.applied, 0);
+    assert.deepEqual(context.use_now.map((node) => node.id), ["current-route"]);
+    assert.deepEqual(context.do_not_use.map((node) => node.id), ["failed-branch"]);
+    assert.deepEqual(context.rehydrate.map((node) => node.id), ["raw-trace"]);
+
+    console.log(JSON.stringify({
+      ok: true,
+      runtime_source: runtimeSource,
+      substrate_target: substrateTarget,
+      first_sidecar_run: first.apply_summary.nodes,
+      second_sidecar_run: second.apply_summary.nodes,
+      governed_context: {
+        use_now: context.use_now.map((node) => node.id),
+        inspect_before_use: context.inspect_before_use.map((node) => node.id),
+        do_not_use: context.do_not_use.map((node) => node.id),
+        rehydrate: context.rehydrate.map((node) => node.id),
+      },
+    }, null, 2));
+  } finally {
+    await store.close();
+  }
+} finally {
+  await rm(workspace, { recursive: true, force: true });
+}