@aionis/substrate 0.1.3 → 0.1.5

package/docs/CLI.md

@@ -6,9 +6,11 @@ It is intentionally narrow:
 
 - it inspects, previews, backs up, restores, and compacts Substrate stores;
 - it imports Runtime Lite SQLite snapshots into separate Substrate stores;
+- 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
@@ -123,6 +125,56 @@ The JSON output includes imported/skipped counts plus structured `diagnostics.so
 `diagnostics.skipReasons`, and `diagnostics.jsonIssues` so bridge failures can be classified
 without scraping warning strings.
 
+## Runtime Live Sidecar
+
+Use `live-sidecar` to keep a separate Substrate store in sync with Runtime Lite evidence without replaying unchanged rows:
+
+```bash
+npx aionis-substrate live-sidecar \
+  --source /path/to/aionis-runtime-lite.sqlite \
+  --target ./substrate.sqlite \
+  --adapter sqlite \
+  --checkpoint ./runtime-live-checkpoint.json \
+  --scope repo-a
+```
+
+The Runtime source is opened read-only. The target is a Substrate store owned by this command.
+The checkpoint file records stable fingerprints for mapped Runtime nodes, relations, feedback,
+and decisions. Re-running the command applies only new or changed evidence.
+
+Use `--dry-run` to inspect the apply plan without writing the target or checkpoint:
+
+```bash
+npx aionis-substrate live-sidecar \
+  --source /path/to/aionis-runtime-lite.sqlite \
+  --target ./substrate.sqlite \
+  --adapter sqlite \
+  --checkpoint ./runtime-live-checkpoint.json \
+  --scope repo-a \
+  --dry-run
+```
+
+Use `--watch` for a bounded polling loop with a single-instance lock:
+
+```bash
+npx aionis-substrate live-sidecar \
+  --source /path/to/aionis-runtime-lite.sqlite \
+  --target ./substrate.sqlite \
+  --adapter sqlite \
+  --checkpoint ./runtime-live-checkpoint.json \
+  --scope repo-a \
+  --watch \
+  --iterations 20 \
+  --interval-ms 5000
+```
+
+The default lock path is `<checkpoint>.lock`. Override it with `--lock <path>`.
+Use `--no-lock` only for controlled tests. The watch report contract is
+`aionis_runtime_live_sidecar_watch_report_v1`.
+
+The report contract is `aionis_runtime_live_sidecar_report_v1`. Read `import_summary` as source coverage
+and `apply_summary` as the checkpointed sidecar result.
+
 ## Sidecar Check
 
 Use `sidecar` when you already have Runtime Lite SQLite evidence and want to check whether Substrate can mirror the governed context surface from outside the Runtime boundary.
@@ -163,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.
@@ -181,6 +252,10 @@ The reference files were scanned, but none of their memory ids overlap the disco
 
 The imported Substrate buckets do not match the supplied Runtime guide/measure surface. Inspect the generated `summary.json` before changing code; the mismatch may be a scope, reference, or fixture problem.
 
+`checkpoint ignored because target store is empty`
+
+The live sidecar found an existing checkpoint, but the target store had no events. It replayed the Runtime snapshot into the target so the checkpoint cannot hide a missing or newly created target.
+
 `ExperimentalWarning: SQLite is an experimental feature`
 
 Node 24 currently marks `node:sqlite` as experimental. This is expected for the current embedded SQLite adapter.

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_LIVE_SIDECAR.md

@@ -0,0 +1,142 @@
+# Runtime Live Sidecar
+
+The Runtime live sidecar is an external, one-way bridge from an Aionis Runtime Lite SQLite database into an independent Aionis Substrate store.
+
+It exists for a narrow productization step:
+
+- Runtime remains the source of execution memory writes.
+- Substrate mirrors Runtime evidence into a durable substrate store.
+- A checkpoint prevents replaying unchanged Runtime rows on every poll.
+- No Runtime table, source file, policy, or guide path is mutated.
+
+This is not a replacement for Runtime policy. It is a sidecar substrate sync primitive.
+
+## Command
+
+```bash
+npx aionis-substrate live-sidecar \
+  --source /path/to/aionis-runtime-lite.sqlite \
+  --target ./substrate.sqlite \
+  --adapter sqlite \
+  --checkpoint ./runtime-live-checkpoint.json \
+  --scope repo-a
+```
+
+Run the command repeatedly from a scheduler or host process. Each run:
+
+1. opens the Runtime SQLite source read-only;
+2. maps Runtime memory nodes, relations, feedback, and decisions through the snapshot importer;
+3. fingerprints each mapped Substrate write;
+4. writes only new or changed evidence into the target store;
+5. atomically updates the checkpoint file.
+
+Use `--adapter file` when the target is a file-backed Substrate directory.
+
+Use `--dry-run` to report what would be applied without writing the target or checkpoint:
+
+```bash
+npx aionis-substrate live-sidecar \
+  --source /path/to/aionis-runtime-lite.sqlite \
+  --target ./substrate.sqlite \
+  --adapter sqlite \
+  --checkpoint ./runtime-live-checkpoint.json \
+  --scope repo-a \
+  --dry-run
+```
+
+## Bounded Watch Loop
+
+Use `--watch` when a host wants Substrate to poll Runtime Lite repeatedly in one process:
+
+```bash
+npx aionis-substrate live-sidecar \
+  --source /path/to/aionis-runtime-lite.sqlite \
+  --target ./substrate.sqlite \
+  --adapter sqlite \
+  --checkpoint ./runtime-live-checkpoint.json \
+  --scope repo-a \
+  --watch \
+  --iterations 20 \
+  --interval-ms 5000
+```
+
+`--watch` is intentionally bounded in this package version. The host chooses the number
+of iterations and can restart the command through cron, launchd, systemd, a supervisor,
+or its own Agent host process.
+
+The watch command creates a single-instance lock by default at:
+
+```text
+<checkpoint>.lock
+```
+
+Override it with `--lock <path>`. Use `--no-lock` only for controlled tests.
+
+The watch report contract is `aionis_runtime_live_sidecar_watch_report_v1`.
+It contains:
+
+- `reports`: every per-iteration `aionis_runtime_live_sidecar_report_v1`;
+- `apply_summary`: aggregate attempted/applied/unchanged counts across all iterations;
+- `lock_path`: the lock used for this run;
+- `iterations_requested` and `iterations_completed`.
+
+## Soak Check
+
+Use the soak check before release or before embedding the sidecar in a long-running host:
+
+```bash
+npm run check:runtime-live-sidecar-soak
+```
+
+The check creates a real Runtime Lite SQLite fixture, appends evidence in batches,
+and runs bounded watch loops against a separate real Substrate SQLite target. It
+verifies:
+
+- every newly appended Runtime row is applied exactly once;
+- unchanged rows remain checkpoint-skipped on later polls;
+- the checkpoint fingerprint count matches the mirrored target;
+- the lock file is released after every watch loop;
+- the target store can be reopened with the same node and event counts.
+
+The report contract is `aionis_runtime_live_sidecar_soak_report_v1`.
+
+## Report
+
+The report contract is `aionis_runtime_live_sidecar_report_v1`.
+
+Important fields:
+
+- `import_summary`: the Runtime snapshot importer coverage for this scan.
+- `apply_summary`: what the live sidecar actually applied or skipped through the checkpoint.
+- `checkpoint_before`: whether a checkpoint existed and how many fingerprints it contained.
+- `checkpoint_after`: fingerprint counts after the run.
+- `store_before` / `store_after`: target store event counters.
+- `warnings`: importer warnings plus sidecar consistency warnings.
+
+`import_summary.nodesImported` can be larger than `apply_summary.nodes.applied`. That is expected: the importer reports what it mapped from Runtime; the live sidecar reports what was new or changed after checkpoint comparison.
+
+## Checkpoint Behavior
+
+The checkpoint is scoped to:
+
+- Runtime source path;
+- optional Runtime scope;
+- mapped Substrate object fingerprints.
+
+If the checkpoint path points to a different Runtime source or scope, the command fails. This prevents accidental cross-source reuse.
+
+If the checkpoint contains fingerprints but the target store is empty, the sidecar ignores the checkpoint and replays the Runtime snapshot into the target. This prevents a stale checkpoint from hiding a lost or newly created target store.
+
+If an individual node, relation, feedback row, or decision is missing from the target even though the checkpoint says it is unchanged, the sidecar re-applies that object.
+
+## Product Boundary
+
+The live sidecar is external infrastructure:
+
+- it does not replace Runtime Lite;
+- it does not install dual-write inside Runtime;
+- it does not change Runtime guide/admission policy;
+- it does not encode benchmark-specific rules;
+- it does not make Substrate the full Runtime policy engine.
+
+Use it when you want a live Substrate mirror for inspection, backup, product experiments, or external host integration without touching Runtime core.

package/docs/RUNTIME_SNAPSHOT_IMPORT.md

@@ -14,6 +14,9 @@ The importer exists to answer one engineering question:
 
 > Can the Substrate contract represent Runtime memory evidence, relations, feedback, and decision traces without polluting the focused Runtime?
 
+For repeated checkpointed mirroring, use the separate Runtime live sidecar documented in
+[RUNTIME_LIVE_SIDECAR.md](RUNTIME_LIVE_SIDECAR.md). Snapshot import is a one-shot copy path.
+
 ## Source Tables
 
 The importer currently understands the focused Runtime Lite write-store tables:

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

@@ -54,7 +54,7 @@ Keep Runtime experiments isolated:
 - dual-write sidecar continues to write into a separate Substrate store;
 - no replacement of Aionis Runtime storage in v0.2.
 
-Initial implementation status: `check:runtime-sidecar` now combines read-only Runtime snapshot parity and same-source reference corpus parity into a single report contract. Real Runtime dual-write remains an explicit separate gate through `check:runtime-dual-write` because it starts focused Runtime.
+Initial implementation status: `check:runtime-sidecar` now combines read-only Runtime snapshot parity and same-source reference corpus parity into a single report contract. `live-sidecar` adds a checkpointed external mirror from Runtime Lite SQLite into a separate Substrate target for repeated host-managed sync, including bounded watch polling and a checkpoint lock. Real Runtime dual-write remains an explicit separate gate through `check:runtime-dual-write` because it starts focused Runtime.
 
 ### 5. Product CLI and Docs
 
@@ -64,11 +64,22 @@ Make the substrate boundary easier to consume without widening policy scope:
 - document install, minimal API usage, and sidecar reports separately;
 - keep repository-only Runtime process experiments explicit and separate.
 
-Initial implementation status: the package exposes `aionis-substrate sidecar` for read-only snapshot/reference checks 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.
+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.
@@ -82,6 +93,7 @@ Before v0.2 can be tagged:
 - `npm run typecheck`
 - `npm test`
 - `npm run bench:contract`
+- `npm run check:runtime-live-sidecar-soak`
 - `npm run check:release`
 - `npm run check:scale -- --nodes 10000 --scopes 10 --relations 2000 --feedback 1000`
 - adapter parity tests for every new public API;

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.