@aionis/substrate 0.1.1 → 0.1.3

package/docs/CLI.md

@@ -1,9 +1,11 @@
 # CLI
 
-`@aionis/substrate` publishes a small CLI for validation and sidecar integration work.
+`@aionis/substrate` publishes a small CLI for local store operations, validation, and sidecar integration work.
 
 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 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`;
@@ -26,6 +28,101 @@ npx aionis-substrate --help
 
 The CLI requires Node 24+.
 
+## Store Commands
+
+All store commands use explicit adapter and path arguments:
+
+```bash
+npx aionis-substrate inspect --adapter sqlite --path ./substrate.sqlite --scope repo-a
+npx aionis-substrate preview-context --adapter sqlite --path ./substrate.sqlite --scope repo-a --query "continue runtime work"
+npx aionis-substrate backup --adapter sqlite --path ./substrate.sqlite --output ./substrate-backup.json
+npx aionis-substrate restore --adapter sqlite --path ./restored.sqlite --input ./substrate-backup.json
+npx aionis-substrate compact --adapter sqlite --path ./substrate.sqlite
+```
+
+Use `--adapter file` with a directory path for the file-backed adapter:
+
+```bash
+npx aionis-substrate inspect --adapter file --path ./substrate-store --scope repo-a
+```
+
+### Inspect
+
+`inspect` prints store metadata. With `--scope`, it also prints scoped counts and memory-node summaries:
+
+```bash
+npx aionis-substrate inspect \
+  --adapter sqlite \
+  --path ./substrate.sqlite \
+  --scope repo-a
+```
+
+The report contract is `aionis_substrate_inspect_report_v1`.
+
+### Preview Context
+
+`preview-context` compiles the governed buckets without writing a `memory.decision.recorded` receipt:
+
+```bash
+npx aionis-substrate preview-context \
+  --adapter sqlite \
+  --path ./substrate.sqlite \
+  --scope repo-a \
+  --query "continue the current route" \
+  --max-per-bucket 8
+```
+
+The report includes `read_only: true` when event counts and sequence numbers are unchanged.
+
+### Backup and Restore
+
+`backup` writes a checksum-covered event backup:
+
+```bash
+npx aionis-substrate backup \
+  --adapter sqlite \
+  --path ./substrate.sqlite \
+  --output ./substrate-backup.json
+```
+
+`restore` verifies the backup before writing an empty target:
+
+```bash
+npx aionis-substrate restore \
+  --adapter sqlite \
+  --path ./restored.sqlite \
+  --input ./substrate-backup.json
+```
+
+Use `--overwrite` only when replacing an existing restore target is intentional.
+
+### Compact
+
+`compact` rewrites the event history into one checkpoint event without changing governed state:
+
+```bash
+npx aionis-substrate compact \
+  --adapter sqlite \
+  --path ./substrate.sqlite
+```
+
+## Runtime Snapshot Import
+
+Use `import-runtime-snapshot` to copy Runtime Lite SQLite evidence into a separate Substrate store:
+
+```bash
+npx aionis-substrate import-runtime-snapshot \
+  --source /path/to/aionis-runtime-lite.sqlite \
+  --target ./substrate.sqlite \
+  --adapter sqlite \
+  --scope repo-a
+```
+
+The Runtime source is opened read-only. The target is a Substrate store owned by this command.
+The JSON output includes imported/skipped counts plus structured `diagnostics.sourceTables`,
+`diagnostics.skipReasons`, and `diagnostics.jsonIssues` so bridge failures can be classified
+without scraping warning strings.
+
 ## 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.

package/docs/RUNTIME_SNAPSHOT_CORPUS.md

@@ -8,7 +8,7 @@ It is a read-only validation path:
 2. select Runtime scopes;
 3. import each scope into a temporary Substrate SQLite store;
 4. compile Substrate context;
-5. aggregate import coverage, bucket counts, warnings, and failures.
+5. aggregate import coverage, bucket counts, warnings, failures, and structured import diagnostics.
 
 It does not replace Runtime storage and does not install dual-write.
 
@@ -35,7 +35,11 @@ The command writes a report under `reports/runtime-snapshot-corpus-*` unless `--
 - `passed_scopes`: scopes imported and compiled successfully.
 - `failed_scopes`: scopes that failed import or compile.
 - `total_nodes_imported`: imported Runtime nodes.
+- `total_nodes_read` / `total_nodes_skipped`: node-level import coverage.
+- `total_relations_*`, `total_feedback_*`, `total_decisions_*`: bridge coverage for Runtime relation, outcome, and decision evidence.
 - `total_warnings`: scan and import warnings.
+- `bucket_totals`: aggregate compiled Substrate admission buckets across imported scopes.
+- `diagnostics_summary`: machine-readable source table coverage, skip reasons, and JSON issues aggregated across scopes.
 - `scope_reports`: per-scope import and bucket summary.
 
 ## Interpretation
@@ -47,7 +51,8 @@ Good results mean:
 - Runtime SQLite sources can be opened read-only;
 - Runtime memory nodes can be mapped into Substrate nodes;
 - Substrate can compile governed context for real scopes;
-- warnings and failures are visible.
+- warnings and failures are visible;
+- skipped evidence is attributable to concrete causes such as missing endpoints, missing referenced rule nodes, audit-only nodes, empty summaries, or malformed Runtime JSON.
 
 Bad results should be treated as mapping or substrate-contract evidence, not as a reason to mutate Aionis Runtime core.
 
@@ -65,17 +70,26 @@ npm run check:runtime-corpus -- \
   --max-per-bucket 50
 ```
 
-Result on 2026-06-25:
+Result on 2026-06-26:
 
 - discovered SQLite files: 30
 - Runtime SQLite files: 14
 - candidate scopes: 128
-- attempted scopes: 100
-- passed scopes: 100
+- attempted scopes: 128
+- passed scopes: 128
 - failed scopes: 0
-- imported Runtime nodes: 8,948
-- warnings: 0
+- Runtime nodes read: 9,069
+- Runtime nodes imported: 8,941
+- Runtime nodes skipped: 128
+- relation rows skipped: 0
+- feedback rows skipped: 0
+- decision rows skipped: 0
+- bucket totals: `use_now=128`, `inspect_before_use=3,789`, `do_not_use=80`, `rehydrate=0`
+- source table coverage: `lite_memory_nodes=128/128`, `lite_memory_edges=128/128`, `lite_memory_execution_native_index=41/128`, `lite_memory_rule_feedback=128/128`, `lite_memory_execution_decisions=128/128`
+- skip reason totals: `not_agent_facing=128`, all other skip reasons `0`
+- JSON issues: 0
+- warnings: 128, all from intentionally skipped non-agent-facing Runtime nodes
 
 Local report:
 
-`reports/runtime-snapshot-corpus-2026-06-25T11-54-32-014Z/summary.json`
+`reports/runtime-snapshot-corpus-2026-06-26T09-00-03-229Z/summary.json`

package/docs/RUNTIME_SNAPSHOT_IMPORT.md

@@ -72,7 +72,20 @@ node scripts/import-runtime-snapshot.ts \
   --adapter file
 ```
 
-The command prints a JSON summary with imported/skipped counts and warnings.
+The command prints a JSON summary with imported/skipped counts, warnings, and
+structured diagnostics.
+
+The diagnostic block is machine-readable:
+
+- `sourceTables`: which Runtime Lite tables were present in the read-only source;
+- `skipReasons.nodes`: `not_agent_facing` and `empty_summary` counts;
+- `skipReasons.relations`: relation rows skipped because an endpoint was not imported;
+- `skipReasons.feedback`: feedback rows skipped because the referenced rule node was not imported;
+- `skipReasons.decisions`: decision rows skipped because none of the referenced source rules were imported;
+- `jsonIssues`: malformed or shape-mismatched Runtime JSON fields.
+
+Warnings remain for human inspection, but downstream tooling should prefer the
+diagnostic counters when classifying import coverage failures.
 
 ## Parity Checker
 

package/docs/V0_2_ROADMAP.md

@@ -64,7 +64,7 @@ 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. It does 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 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.
 
 ## Excluded
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aionis/substrate",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Durable governed memory substrate for Aionis execution state.",
   "type": "module",
   "main": "./dist/index.js",