@aionis/substrate 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -2,6 +2,39 @@
 
 All notable changes to Aionis Substrate are documented here.
 
+## Unreleased
+
+## 0.1.2 - 2026-06-26
+
+### Added
+
+- CLI commands for `inspect`, `preview-context`, `backup`, `restore`, `compact`, and `import-runtime-snapshot`.
+- CLI integration tests that run the store commands against real SQLite stores and Runtime Lite snapshot fixtures.
+
+### Changed
+
+- CLI documentation now covers store operations, Runtime snapshot import, and sidecar checks as separate surfaces.
+
+## 0.1.1 - 2026-06-26
+
+### Added
+
+- v0.2 roadmap that freezes Substrate hardening scope and excludes Runtime policy, vector recall, Agent harnesses, and SaaS concerns.
+- Scoped audit read APIs for relations, feedback, and decision receipts.
+- SQLite schema migration registry with durable applied-migration records.
+- Durability negative controls for orphan decision receipts, checksum-valid corrupt backups, and post-compaction invalid writes.
+- Runtime sidecar stabilization report that combines read-only snapshot parity and same-source reference corpus parity.
+- Published package CLI `aionis-substrate` with a `sidecar` command for read-only Runtime sidecar stabilization checks.
+- CLI documentation covering install, sidecar reports, and common failure interpretation.
+
+### Changed
+
+- Documented audit reads as side-effect-free adapter parity surfaces.
+- Documented SQLite migrations as explicit adapter-scoped schema changes.
+- Decision traces now require every decision memory id to reference an existing node in the same scope.
+- Documented Runtime sidecar validation as staged gates, keeping real dual-write explicit and isolated.
+- README now separates package install, minimal API usage, and Runtime sidecar validation paths.
+
 ## 0.1.0 - 2026-06-26
 
 ### Added

package/README.md

@@ -17,6 +17,34 @@ It is not Aionis Runtime core, not an Agent framework, and not a vector database
 
 The project is intentionally independent from `AionisRuntime-focused`. It can import real Runtime Lite SQLite snapshots for validation and run isolated sidecar dual-write experiments, but it does not mutate Runtime source code or replace Runtime storage.
 
+## Install
+
+```bash
+npm install @aionis/substrate
+```
+
+Run the published CLI without adding a dependency:
+
+```bash
+npx @aionis/substrate --help
+```
+
+After installing into a project:
+
+```bash
+npx aionis-substrate --help
+```
+
+Common CLI operations:
+
+```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
+npx aionis-substrate backup --adapter sqlite --path ./substrate.sqlite --output ./backup.json
+npx aionis-substrate restore --adapter sqlite --path ./restored.sqlite --input ./backup.json
+npx aionis-substrate compact --adapter sqlite --path ./substrate.sqlite
+```
+
 ## Goal
 
 Define the storage semantics Aionis needs before choosing or building a storage engine:
@@ -49,7 +77,7 @@ This first version ships two embedded adapters:
 - every write is serialized and persisted.
 - reopening the store rebuilds the same state from disk.
 - every store reports its substrate schema version through `getStoreInfo`.
-- the SQLite adapter persists schema metadata and rejects stores created by a newer unsupported schema.
+- the SQLite adapter persists schema metadata, records applied schema migrations, and rejects stores created by a newer unsupported schema.
 - event-log backups can be exported, checksum-verified, and restored to either file or SQLite stores.
 - checkpoint compaction can rewrite a store event log to one checksum-covered checkpoint event without changing governed state.
 - `searchNodes` provides scoped deterministic lexical/structured search over memory nodes without mutating events or admission state. It is not ANN, vector recall, semantic retrieval, or a Recall Engine.
@@ -63,8 +91,12 @@ See [docs/STORE_CONTRACT.md](docs/STORE_CONTRACT.md).
 
 API usage is documented in [docs/API_USAGE.md](docs/API_USAGE.md).
 
+CLI usage is documented in [docs/CLI.md](docs/CLI.md).
+
 Adapter consistency requirements are documented in [docs/ADAPTER_CONTRACT.md](docs/ADAPTER_CONTRACT.md).
 
+The v0.2 roadmap is documented in [docs/V0_2_ROADMAP.md](docs/V0_2_ROADMAP.md).
+
 Backup and restore are documented in [docs/BACKUP_RESTORE.md](docs/BACKUP_RESTORE.md).
 
 Checkpoint compaction is documented in [docs/CHECKPOINT_COMPACTION.md](docs/CHECKPOINT_COMPACTION.md).
@@ -73,6 +105,8 @@ Runtime snapshot import is documented in [docs/RUNTIME_SNAPSHOT_IMPORT.md](docs/
 
 Runtime reference corpus parity is documented in [docs/RUNTIME_REFERENCE_CORPUS.md](docs/RUNTIME_REFERENCE_CORPUS.md).
 
+Runtime sidecar stabilization is documented in [docs/RUNTIME_SIDECAR_STABILIZATION.md](docs/RUNTIME_SIDECAR_STABILIZATION.md).
+
 External admission parity is documented in [docs/EXTERNAL_ADMISSION_PARITY.md](docs/EXTERNAL_ADMISSION_PARITY.md).
 
 Runtime dual-write experimentation is documented in [docs/RUNTIME_DUAL_WRITE_EXPERIMENT.md](docs/RUNTIME_DUAL_WRITE_EXPERIMENT.md).
@@ -95,6 +129,39 @@ npm run example:basic
 
 Node 24+ is required because the project runs TypeScript directly.
 
+## Minimal API Loop
+
+```ts
+import { openSqliteAionisSubstrate } from "@aionis/substrate";
+
+const store = await openSqliteAionisSubstrate({
+  path: "./aionis-substrate.sqlite",
+});
+
+await store.putNode({
+  id: "current-route",
+  scope: "repo-a",
+  kind: "procedure",
+  summary: "Use src/runtime.ts after verifier passed.",
+  lifecycle: "active",
+  authority: "trusted",
+  confidence: 0.95,
+  targetFiles: ["src/runtime.ts"],
+});
+
+const context = await store.compileContext({
+  scope: "repo-a",
+  query: "continue the runtime implementation",
+});
+
+console.log(context.use_now.map((node) => node.id));
+console.log(context.decision_trace);
+
+await store.close();
+```
+
+Use `previewContext` when you need the same governed buckets without writing a decision receipt.
+
 ## Contract Benchmark
 
 ```bash
@@ -152,6 +219,20 @@ npm run check:runtime-reference-corpus -- \
 
 This scans Runtime `agent_context` / `memory_decision_trace` JSON and only counts a reference when its memory ids overlap a real Runtime SQLite scope. Unmatched demo/export files are reported separately.
 
+Runtime sidecar stabilization report:
+
+```bash
+npm run check:runtime-sidecar -- \
+  --source /path/to/aionis-runtime-lite.sqlite \
+  --scope repo-a \
+  --reference /path/to/runtime-guide-or-measure.json \
+  --source-root /path/to/AionisRuntime-focused/.tmp \
+  --reference-root /path/to/runtime-references \
+  --output reports/runtime-sidecar-manual/summary.json
+```
+
+This combines read-only snapshot parity and same-source reference corpus parity into one sidecar report. It does not start Runtime and does not replace Runtime storage.
+
 External admission parity against focused Runtime:
 
 ```bash
@@ -209,6 +290,15 @@ npm run check:release
 
 `check:install-smoke` packs the built package, installs that tarball into a fresh temporary project, imports `@aionis/substrate`, and runs real file/SQLite store operations from the installed package.
 
+After publishing to npm, run the registry package checks:
+
+```bash
+npm run check:registry-install
+npm run check:published-runtime-smoke
+```
+
+These commands install `@aionis/substrate@<package.json version>` from the npm registry into a fresh temporary project. `check:published-runtime-smoke` also creates a Runtime Lite SQLite fixture and verifies published-package snapshot import into a separate Substrate store.
+
 ## Scale Smoke
 
 ```bash

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export declare function runCli(argv?: string[]): Promise<void>;
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAiqBA,wBAAsB,MAAM,CAAC,IAAI,WAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CAmCxE"}