@aionis/substrate 0.1.4 → 0.1.6

package/CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to Aionis Substrate are documented here.
 
 ## Unreleased
 
+### Added
+
+- Live sidecar integration example that builds a real Runtime Lite SQLite source, mirrors it through the checkpointed sidecar, and previews governed context buckets.
+- Optional candidate index boundary with rebuild, verify, write-through node sync, and candidate-id narrowing before canonical Substrate scoring.
+- Optional Zvec-backed candidate index adapter for local vector preselection while keeping file/SQLite as truth storage.
+- Runtime Zvec candidate-index validation gate that imports real Runtime Lite SQLite scopes into isolated Substrate stores and checks Zvec health plus canonical-search parity.
+- Zvec scale-maintenance gate that writes a SQLite truth store with a Zvec candidate sidecar, verifies write-through health, wide-search parity, narrow seeded recovery, lifecycle-transition sync, compaction, and reopen rebuild.
+- Provider-backed Zvec embedding eval that calls OpenAI-compatible or MiniMax native embeddings endpoints and reports raw Zvec candidate hit rate separately from final Substrate search hit rate.
+- Candidate-index semantic fusion that lets Zvec/provider candidates influence final `searchNodes()` ranking without bypassing scope, lifecycle, authority, confidence, or target-file filters.
+- DashScope native `text-embedding-v4` provider eval with query/document projection, optional query instructions, and projection-aware reports.
+- Stable SDK embedding projection helpers for provider hosts: `buildAionisEmbeddingDocument`, `buildAionisEmbeddingQuery`, and `AIONIS_EMBEDDING_PROJECTION_VERSION`.
+
 ## 0.1.4 - 2026-06-26
 
 ### Added

package/README.md

@@ -4,7 +4,7 @@ Aionis Substrate is an independent storage-contract project for Aionis memory an
 
 It defines the durable substrate Aionis needs for governed working memory: append-only evidence, lifecycle state, relations, feedback, decision receipts, and context admission buckets.
 
-It is not Aionis Runtime core, not an Agent framework, and not a vector database replacement.
+Aionis Runtime can use this layer as a durable governed memory substrate. Agents and Runtime policy remain above it; file/SQLite remain the truth store; optional indexes such as Zvec can accelerate candidate preselection.
 
 ## Status
 
@@ -47,6 +47,24 @@ npx aionis-substrate live-sidecar --source ./runtime.sqlite --target ./substrate
 npx aionis-substrate live-sidecar --source ./runtime.sqlite --target ./substrate.sqlite --adapter sqlite --checkpoint ./runtime-live-checkpoint.json --scope repo-a --watch --iterations 20 --interval-ms 5000
 ```
 
+## Two-Minute Live Sidecar Demo
+
+From a cloned repository:
+
+```bash
+npm run example:live-sidecar
+```
+
+The demo creates a real Runtime Lite SQLite source, inserts current route, failed
+branch, and raw-trace pointer evidence, mirrors that source into a separate
+Substrate SQLite store through `runRuntimeLiveSidecarOnce`, and previews the
+governed context buckets. The expected output shows:
+
+- `current-route` in `use_now`;
+- `failed-branch` in `do_not_use`;
+- `raw-trace` in `rehydrate`;
+- the second sidecar run applying zero unchanged rows.
+
 ## Goal
 
 Define the storage semantics Aionis needs before choosing or building a storage engine:
@@ -58,15 +76,11 @@ Define the storage semantics Aionis needs before choosing or building a storage
 - decision traces that explain why memory was admitted, downgraded, blocked, or deferred
 - controlled forgetting as state transitions, not silent deletion
 
-## What It Is Not
+## Product Boundary
 
-- not a RAG library;
-- not a vector index;
-- not a chat memory store;
-- not a benchmark harness;
-- not the full Aionis Runtime policy engine.
+Aionis Substrate owns durable memory evidence, lifecycle state, relation graph, feedback receipts, audit reads, side-effect-free preview, and the minimum governed context contract.
 
-The admission logic here is a substrate-level minimum contract. Full Aionis Runtime policy remains above this layer.
+Aionis Runtime owns richer admission policy, product orchestration, Agent-facing guide behavior, and model/provider workflows above this storage-contract layer.
 
 ## Current Scope
 
@@ -82,7 +96,10 @@ This first version ships two embedded adapters:
 - 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.
+- `searchNodes` provides scoped deterministic lexical/structured search over memory nodes without mutating events or admission state.
+- stores can be opened with an optional candidate index. The index is rebuilt on open by default, receives write-through node updates, can be verified for missing/orphan/stale entries, and only narrows candidate ids before Substrate reloads truth nodes and scores them.
+- `createZvecCandidateIndex` provides an optional Zvec-backed candidate index for local vector preselection. Substrate fuses candidate-index rank into final search while preserving scope, lifecycle, authority, confidence, and target-file filters. It requires installing `@zvec/zvec`; file/SQLite remain the truth store.
+- `buildAionisEmbeddingDocument` and `buildAionisEmbeddingQuery` expose the stable SDK projection for hosts that generate provider vectors before writing nodes or querying Zvec.
 - `importRuntimeLiteSnapshot` can import an existing Runtime Lite SQLite database into an isolated Substrate store through a read-only source connection.
 - `runRuntimeLiveSidecarOnce`, `runRuntimeLiveSidecarWatch`, and `aionis-substrate live-sidecar` incrementally mirror Runtime Lite evidence into a separate Substrate target through a checkpoint file.
 
@@ -106,8 +123,19 @@ Checkpoint compaction is documented in [docs/CHECKPOINT_COMPACTION.md](docs/CHEC
 
 Runtime snapshot import is documented in [docs/RUNTIME_SNAPSHOT_IMPORT.md](docs/RUNTIME_SNAPSHOT_IMPORT.md).
 
+The product contract is documented in [docs/PRODUCT_CONTRACT.md](docs/PRODUCT_CONTRACT.md).
+
 Runtime live sidecar sync is documented in [docs/RUNTIME_LIVE_SIDECAR.md](docs/RUNTIME_LIVE_SIDECAR.md).
 
+Published Runtime bridge validation is documented in the release checks section below. It installs the published npm package into a fresh temporary project, reads a real Runtime Lite SQLite source, writes only separate Substrate target stores, and verifies snapshot/live parity plus checkpoint idempotency.
+
+Runtime Zvec candidate-index validation is documented in [docs/RUNTIME_ZVEC_CANDIDATE_INDEX.md](docs/RUNTIME_ZVEC_CANDIDATE_INDEX.md).
+
+Zvec scale and maintenance validation is documented in [docs/ZVEC_SCALE_MAINTENANCE.md](docs/ZVEC_SCALE_MAINTENANCE.md).
+
+Provider-backed Zvec embedding validation is documented in [docs/ZVEC_PROVIDER_EMBEDDING_EVAL.md](docs/ZVEC_PROVIDER_EMBEDDING_EVAL.md).
+The provider eval supports OpenAI-compatible embedding endpoints and MiniMax native embeddings for checking Zvec candidate preselection with real provider vectors.
+
 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).
@@ -137,10 +165,11 @@ Node 24+ is required because the project runs TypeScript directly.
 ## Minimal API Loop
 
 ```ts
-import { openSqliteAionisSubstrate } from "@aionis/substrate";
+import { createMemoryCandidateIndex, openSqliteAionisSubstrate } from "@aionis/substrate";
 
 const store = await openSqliteAionisSubstrate({
   path: "./aionis-substrate.sqlite",
+  candidateIndex: createMemoryCandidateIndex(),
 });
 
 await store.putNode({
@@ -210,6 +239,18 @@ npm run check:runtime-corpus -- \
 
 This scans Runtime Lite SQLite files read-only, imports selected scopes into temporary Substrate stores, and writes an aggregate matrix report under `reports/runtime-snapshot-corpus-*`. The report includes bucket totals, node/relation/feedback/decision coverage, source-table presence, skip reasons, and Runtime JSON issues.
 
+Runtime Zvec candidate-index check:
+
+```bash
+npm run check:runtime-zvec-index -- \
+  --root /path/to/AionisRuntime-focused/.tmp \
+  --max-scopes 20 \
+  --min-nodes 3 \
+  --probes-per-scope 8
+```
+
+This imports real Runtime Lite SQLite scopes into isolated Substrate SQLite stores, rebuilds a Zvec candidate index, verifies missing/orphan/stale health, and checks that wide candidate search preserves canonical Substrate search while narrow candidate search recovers seeded real Runtime memory nodes.
+
 Runtime live sidecar mirror:
 
 ```bash
@@ -286,6 +327,23 @@ npm run check:runtime-dual-write -- \
 
 The soak report includes per-scenario latency summaries, chain-probe latency, reopen latency, event-sequence continuity, and SQLite file sizes.
 
+Runtime product bridge gate:
+
+```bash
+npm run check:runtime-product-bridge -- \
+  --runtime-root /path/to/AionisRuntime-focused
+```
+
+This is the product-level bridge check. It runs real focused Runtime
+`observe -> guide -> feedback -> measure`, verifies external Substrate
+dual-write parity, closes and reopens the Substrate store, runs lifecycle/relation
+chain probes, mirrors the Runtime Lite SQLite source through read-only
+`live-sidecar`, re-runs `live-sidecar` to prove checkpoint idempotency, and then
+compares the mirrored Substrate `previewContext` buckets back against Runtime
+guide surfaces. The default gate runs 4 fixed scenarios, 96 deterministic
+generated scenarios, and 16 chain probes. It writes a single
+`product-bridge-gate-summary.json` report and exits non-zero if any stage fails.
+
 ## Development Checks
 
 ```bash
@@ -297,6 +355,7 @@ npm run check:runtime-live-sidecar-soak
 npm run check:pack
 npm run check:install-smoke
 npm run example:basic
+npm run example:live-sidecar
 ```
 
 The CI workflow runs the same checks on every push and pull request.
@@ -318,10 +377,13 @@ After publishing to npm, run the registry package checks:
 ```bash
 npm run check:registry-install
 npm run check:published-runtime-smoke
+AIONIS_RUNTIME_SQLITE_SOURCE=/path/to/aionis-lite.sqlite npm run check:published-runtime-bridge
 ```
 
 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.
 
+`check:published-runtime-bridge` is the real Runtime bridge gate. It reads the Runtime Lite SQLite source passed through `AIONIS_RUNTIME_SQLITE_SOURCE`, imports it into an isolated snapshot store, runs checkpointed `live-sidecar` twice into an isolated live store, verifies the second pass does not mutate the target, verifies snapshot/live event parity, and verifies the Runtime source file was not modified.
+
 ## Scale Smoke
 
 ```bash
@@ -333,3 +395,32 @@ npm run check:scale -- \
 ```
 
 The scale smoke writes a temporary SQLite substrate, verifies event sequence continuity, runs scoped search, compiles context, compacts the store, reopens it, and writes a report under `reports/scale-*`.
+
+SQLite + Zvec scale maintenance:
+
+```bash
+npm run check:zvec-scale -- \
+  --nodes 10000 \
+  --scopes 10 \
+  --relations 2000 \
+  --feedback 1000 \
+  --probes 100 \
+  --narrow-candidate-limit 20
+```
+
+This writes a temporary SQLite truth store with a Zvec candidate sidecar, verifies write-through index health, compares wide-window Zvec search against canonical Substrate search, checks narrow-window seeded recovery, transitions lifecycle state, compacts, reopens, and writes a report under `reports/zvec-scale-*`.
+
+Provider-backed Zvec embedding eval:
+
+```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
+```
+
+This uses a real embedding provider, stores provider vectors on generated Substrate nodes, runs Zvec candidate search, and reports both raw Zvec candidate hit rate and final Substrate search hit rate. The runner supports OpenAI-compatible endpoints, MiniMax native embeddings, and DashScope native `text-embedding-v4` with query/document projection.

package/dist/candidate-index.d.ts

@@ -0,0 +1,25 @@
+import type { AionisMemoryNode, AionisMemorySearchInput, AionisMemorySearchReason } from "./types.ts";
+export type AionisCandidateIndexSearchResult = {
+    scope: string;
+    memoryId: string;
+    score: number;
+    reasons: AionisMemorySearchReason[];
+};
+export type AionisCandidateIndexHealthReport = {
+    ok: boolean;
+    sourceCount: number;
+    indexedCount: number;
+    missingNodeIds: string[];
+    orphanNodeIds: string[];
+    staleNodeIds: string[];
+};
+export type AionisCandidateIndex = {
+    upsertNode(node: AionisMemoryNode): Promise<void>;
+    deleteNode(scope: string, id: string): Promise<void>;
+    search(input: AionisMemorySearchInput): Promise<AionisCandidateIndexSearchResult[] | null>;
+    rebuild(nodes: AionisMemoryNode[]): Promise<AionisCandidateIndexHealthReport>;
+    verify(nodes: AionisMemoryNode[]): Promise<AionisCandidateIndexHealthReport>;
+    close?(): Promise<void>;
+};
+export declare function createMemoryCandidateIndex(nodes?: AionisMemoryNode[]): AionisCandidateIndex;
+//# sourceMappingURL=candidate-index.d.ts.map

package/dist/candidate-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"candidate-index.d.ts","sourceRoot":"","sources":["../src/candidate-index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAIV,gBAAgB,EAChB,uBAAuB,EACvB,wBAAwB,EACzB,MAAM,YAAY,CAAC;AAEpB,MAAM,MAAM,gCAAgC,GAAG;IAC7C,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,wBAAwB,EAAE,CAAC;CACrC,CAAC;AAEF,MAAM,MAAM,gCAAgC,GAAG;IAC7C,EAAE,EAAE,OAAO,CAAC;IACZ,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,UAAU,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD,MAAM,CAAC,KAAK,EAAE,uBAAuB,GAAG,OAAO,CAAC,gCAAgC,EAAE,GAAG,IAAI,CAAC,CAAC;IAC3F,OAAO,CAAC,KAAK,EAAE,gBAAgB,EAAE,GAAG,OAAO,CAAC,gCAAgC,CAAC,CAAC;IAC9E,MAAM,CAAC,KAAK,EAAE,gBAAgB,EAAE,GAAG,OAAO,CAAC,gCAAgC,CAAC,CAAC;IAC7E,KAAK,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB,CAAC;AAyJF,wBAAgB,0BAA0B,CAAC,KAAK,GAAE,gBAAgB,EAAO,GAAG,oBAAoB,CA0E/F"}

package/dist/candidate-index.js

@@ -0,0 +1,217 @@
+const DEFAULT_INDEX_LIMIT = 200;
+function indexKey(scope, id) {
+    return `${scope}\u0000${id}`;
+}
+function normalizeText(value) {
+    return value.toLowerCase().normalize("NFKC");
+}
+function tokenize(value) {
+    return Array.from(new Set(normalizeText(value).match(/[\p{L}\p{N}_./:-]+/gu) ?? []));
+}
+function normalizePath(value) {
+    return value.trim().replaceAll("\\", "/").replace(/\/+/g, "/").toLowerCase();
+}
+function stableMetadataText(metadata) {
+    if (!metadata)
+        return "";
+    return Object.entries(metadata)
+        .filter(([, value]) => typeof value === "string" || typeof value === "number" || typeof value === "boolean")
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([key, value]) => `${key}:${String(value)}`)
+        .join(" ");
+}
+function nodeSearchText(node) {
+    return [
+        node.id,
+        node.kind,
+        node.title ?? "",
+        node.summary,
+        ...(node.targetFiles ?? []),
+        node.payloadRef ?? "",
+        node.agentId ?? "",
+        node.teamId ?? "",
+        stableMetadataText(node.metadata),
+    ].filter(Boolean).join(" ");
+}
+function nodeFingerprint(node) {
+    return JSON.stringify({
+        id: node.id,
+        scope: node.scope,
+        kind: node.kind,
+        title: node.title ?? null,
+        summary: node.summary,
+        lifecycle: node.lifecycle,
+        authority: node.authority,
+        confidence: node.confidence,
+        targetFiles: node.targetFiles ?? [],
+        payloadRef: node.payloadRef ?? null,
+        agentId: node.agentId ?? null,
+        teamId: node.teamId ?? null,
+        metadata: node.metadata ?? {},
+        updatedAt: node.updatedAt,
+    });
+}
+function toIndexedNode(node) {
+    const text = nodeSearchText(node);
+    return {
+        node,
+        fingerprint: nodeFingerprint(node),
+        text: normalizeText(text),
+        tokens: new Set(tokenize(text)),
+        targetFiles: new Set((node.targetFiles ?? []).map(normalizePath).filter(Boolean)),
+    };
+}
+function hasAnyTargetFile(indexed, targetFiles) {
+    if (targetFiles.length === 0)
+        return true;
+    return targetFiles.some((target) => indexed.targetFiles.has(normalizePath(target)));
+}
+function setContains(filter, value) {
+    return !filter || filter.has(value);
+}
+function compareIso(value, boundary) {
+    return value.localeCompare(boundary);
+}
+function scoreQuery(indexed, query) {
+    const queryTokens = tokenize(query ?? "");
+    if (queryTokens.length === 0)
+        return {
+            score: indexed.node.confidence,
+            reasons: [{ code: "candidate_index_scope_match", detail: `scope=${indexed.node.scope}` }],
+        };
+    let score = indexed.node.confidence;
+    const matched = [];
+    for (const token of queryTokens) {
+        if (indexed.tokens.has(token)) {
+            score += 2;
+            matched.push(token);
+        }
+        else if (indexed.text.includes(token)) {
+            score += 1;
+            matched.push(token);
+        }
+    }
+    if (matched.length === 0)
+        return null;
+    return {
+        score,
+        reasons: [{
+                code: "candidate_index_query_match",
+                detail: `candidate index matched ${matched.length}/${queryTokens.length} query tokens: ${matched.join(", ")}`,
+            }],
+    };
+}
+function healthFrom(indexed, nodes) {
+    const source = new Map(nodes.map((node) => [indexKey(node.scope, node.id), node]));
+    const missingNodeIds = [];
+    const orphanNodeIds = [];
+    const staleNodeIds = [];
+    for (const [key, node] of source) {
+        const current = indexed.get(key);
+        if (!current) {
+            missingNodeIds.push(node.id);
+        }
+        else if (current.fingerprint !== nodeFingerprint(node)) {
+            staleNodeIds.push(node.id);
+        }
+    }
+    for (const [key, current] of indexed) {
+        if (!source.has(key))
+            orphanNodeIds.push(current.node.id);
+    }
+    missingNodeIds.sort();
+    orphanNodeIds.sort();
+    staleNodeIds.sort();
+    return {
+        ok: missingNodeIds.length === 0 && orphanNodeIds.length === 0 && staleNodeIds.length === 0,
+        sourceCount: source.size,
+        indexedCount: indexed.size,
+        missingNodeIds,
+        orphanNodeIds,
+        staleNodeIds,
+    };
+}
+export function createMemoryCandidateIndex(nodes = []) {
+    const indexed = new Map();
+    for (const node of nodes)
+        indexed.set(indexKey(node.scope, node.id), toIndexedNode(node));
+    return {
+        async upsertNode(node) {
+            indexed.set(indexKey(node.scope, node.id), toIndexedNode(node));
+        },
+        async deleteNode(scope, id) {
+            indexed.delete(indexKey(scope, id));
+        },
+        async search(input) {
+            const scope = input.scope.trim();
+            if (!scope)
+                throw new Error("scope is required");
+            const limit = input.limit === undefined ? DEFAULT_INDEX_LIMIT : input.limit;
+            if (!Number.isInteger(limit) || limit < 1)
+                throw new Error("limit must be a positive integer");
+            if (input.minConfidence !== undefined && (!Number.isFinite(input.minConfidence) || input.minConfidence < 0 || input.minConfidence > 1)) {
+                throw new Error("minConfidence must be between 0 and 1");
+            }
+            const kindFilter = input.kinds === undefined ? null : new Set(input.kinds);
+            const lifecycleFilter = input.lifecycle === undefined ? null : new Set(input.lifecycle);
+            const authorityFilter = input.authority === undefined ? null : new Set(input.authority);
+            const targetFiles = input.targetFiles?.map((item) => item.trim()).filter(Boolean) ?? [];
+            const results = [];
+            for (const item of indexed.values()) {
+                const node = item.node;
+                if (node.scope !== scope)
+                    continue;
+                if (!setContains(kindFilter, node.kind))
+                    continue;
+                if (!setContains(lifecycleFilter, node.lifecycle))
+                    continue;
+                if (!setContains(authorityFilter, node.authority))
+                    continue;
+                if (input.agentId !== undefined && node.agentId !== input.agentId)
+                    continue;
+                if (input.teamId !== undefined && node.teamId !== input.teamId)
+                    continue;
+                if (input.minConfidence !== undefined && node.confidence < input.minConfidence)
+                    continue;
+                if (input.updatedAfter !== undefined && compareIso(node.updatedAt, input.updatedAfter) < 0)
+                    continue;
+                if (input.updatedBefore !== undefined && compareIso(node.updatedAt, input.updatedBefore) > 0)
+                    continue;
+                if (!hasAnyTargetFile(item, targetFiles))
+                    continue;
+                const query = scoreQuery(item, input.query);
+                if (!query)
+                    continue;
+                results.push({
+                    scope: node.scope,
+                    memoryId: node.id,
+                    score: query.score,
+                    reasons: query.reasons,
+                });
+            }
+            return results
+                .sort((a, b) => {
+                const byScore = b.score - a.score;
+                if (byScore !== 0)
+                    return byScore;
+                const aNode = indexed.get(indexKey(a.scope, a.memoryId))?.node;
+                const bNode = indexed.get(indexKey(b.scope, b.memoryId))?.node;
+                const byTime = (bNode?.updatedAt ?? "").localeCompare(aNode?.updatedAt ?? "");
+                if (byTime !== 0)
+                    return byTime;
+                return a.memoryId.localeCompare(b.memoryId);
+            })
+                .slice(0, limit);
+        },
+        async rebuild(nodes) {
+            indexed.clear();
+            for (const node of nodes)
+                indexed.set(indexKey(node.scope, node.id), toIndexedNode(node));
+            return healthFrom(indexed, nodes);
+        },
+        async verify(nodes) {
+            return healthFrom(indexed, nodes);
+        },
+    };
+}
+//# sourceMappingURL=candidate-index.js.map

package/dist/candidate-index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"candidate-index.js","sourceRoot":"","sources":["../src/candidate-index.ts"],"names":[],"mappings":"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"}

package/dist/embedding-projection.d.ts

@@ -0,0 +1,16 @@
+import type { AionisMemoryNode, AionisMemoryNodeInput } from "./types.ts";
+export declare const AIONIS_EMBEDDING_PROJECTION_VERSION = "aionis_substrate_embedding_projection_v1";
+export type AionisEmbeddingProjectionMode = "plain" | "structured";
+export type AionisEmbeddingDocumentOptions = {
+    projection?: AionisEmbeddingProjectionMode;
+    includeIdentity?: boolean;
+    includeOwner?: boolean;
+    metadataKeys?: "all" | string[] | false;
+};
+export type AionisEmbeddingQueryOptions = {
+    projection?: AionisEmbeddingProjectionMode;
+    task?: string;
+};
+export declare function buildAionisEmbeddingDocument(node: AionisMemoryNode | AionisMemoryNodeInput, options?: AionisEmbeddingDocumentOptions): string;
+export declare function buildAionisEmbeddingQuery(query: string, options?: AionisEmbeddingQueryOptions): string;
+//# sourceMappingURL=embedding-projection.d.ts.map

package/dist/embedding-projection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedding-projection.d.ts","sourceRoot":"","sources":["../src/embedding-projection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAE1E,eAAO,MAAM,mCAAmC,6CAA6C,CAAC;AAE9F,MAAM,MAAM,6BAA6B,GAAG,OAAO,GAAG,YAAY,CAAC;AAEnE,MAAM,MAAM,8BAA8B,GAAG;IAC3C,UAAU,CAAC,EAAE,6BAA6B,CAAC;IAC3C,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,YAAY,CAAC,EAAE,KAAK,GAAG,MAAM,EAAE,GAAG,KAAK,CAAC;CACzC,CAAC;AAEF,MAAM,MAAM,2BAA2B,GAAG;IACxC,UAAU,CAAC,EAAE,6BAA6B,CAAC;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AA0EF,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,gBAAgB,GAAG,qBAAqB,EAC9C,OAAO,GAAE,8BAAmC,GAC3C,MAAM,CAmBR;AAED,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,2BAAgC,GACxC,MAAM,CAWR"}

package/dist/embedding-projection.js

@@ -0,0 +1,101 @@
+export const AIONIS_EMBEDDING_PROJECTION_VERSION = "aionis_substrate_embedding_projection_v1";
+const VECTOR_METADATA_KEYS = new Set([
+    "embedding",
+    "embedding_vector",
+    "vector",
+    "query_vector",
+]);
+function normalizeText(value) {
+    return value
+        .normalize("NFKC")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+function optionalValue(value) {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value === "string") {
+        const normalized = normalizeText(value);
+        return normalized.length > 0 ? normalized : null;
+    }
+    if (typeof value === "number" || typeof value === "boolean")
+        return String(value);
+    return null;
+}
+function joinList(values) {
+    const normalized = (values ?? [])
+        .map((value) => normalizeText(value))
+        .filter(Boolean)
+        .sort((a, b) => a.localeCompare(b));
+    return normalized.length > 0 ? normalized.join(", ") : null;
+}
+function stableMetadataText(metadata, metadataKeys = false) {
+    if (!metadata)
+        return null;
+    if (metadataKeys === false)
+        return null;
+    const allowedKeys = Array.isArray(metadataKeys) ? new Set(metadataKeys) : null;
+    const rows = Object.entries(metadata)
+        .filter(([key, value]) => !VECTOR_METADATA_KEYS.has(key) &&
+        (allowedKeys === null || allowedKeys.has(key)) &&
+        optionalValue(value) !== null)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([key, value]) => `${key}=${optionalValue(value)}`);
+    return rows.length > 0 ? rows.join("; ") : null;
+}
+function line(label, value) {
+    const normalized = optionalValue(value);
+    return normalized === null ? null : `${label}: ${normalized}`;
+}
+function plainDocumentText(node, options) {
+    return [
+        node.title,
+        node.summary,
+        node.kind,
+        node.lifecycle,
+        node.authority,
+        joinList(node.targetFiles),
+        node.payloadRef,
+        options.includeOwner ? node.agentId : null,
+        options.includeOwner ? node.teamId : null,
+        stableMetadataText(node.metadata, options.metadataKeys),
+    ].flatMap((value) => {
+        const normalized = optionalValue(value);
+        return normalized === null ? [] : [normalized];
+    }).join(" ");
+}
+export function buildAionisEmbeddingDocument(node, options = {}) {
+    const projection = options.projection ?? "structured";
+    if (projection === "plain")
+        return plainDocumentText(node, options);
+    return [
+        AIONIS_EMBEDDING_PROJECTION_VERSION,
+        "type: memory_document",
+        options.includeIdentity ? line("id", node.id) : null,
+        options.includeIdentity ? line("scope", node.scope) : null,
+        line("kind", node.kind),
+        line("lifecycle", node.lifecycle),
+        line("authority", node.authority),
+        line("title", node.title),
+        line("summary", node.summary),
+        line("target_files", joinList(node.targetFiles)),
+        line("payload_ref", node.payloadRef),
+        options.includeOwner ? line("agent_id", node.agentId) : null,
+        options.includeOwner ? line("team_id", node.teamId) : null,
+        line("metadata", stableMetadataText(node.metadata, options.metadataKeys)),
+    ].filter((value) => value !== null).join("\n");
+}
+export function buildAionisEmbeddingQuery(query, options = {}) {
+    const normalizedQuery = normalizeText(query);
+    const projection = options.projection ?? "structured";
+    if (projection === "plain")
+        return normalizedQuery;
+    const task = normalizeText(options.task ?? "retrieve the memory document that best answers this implementation question");
+    return [
+        AIONIS_EMBEDDING_PROJECTION_VERSION,
+        "type: retrieval_query",
+        `task: ${task}`,
+        `query: ${normalizedQuery}`,
+    ].join("\n");
+}
+//# sourceMappingURL=embedding-projection.js.map

package/dist/embedding-projection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedding-projection.js","sourceRoot":"","sources":["../src/embedding-projection.ts"],"names":[],"mappings":"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"}

package/dist/file-substrate.d.ts

@@ -1,7 +1,10 @@
+import type { AionisCandidateIndex } from "./candidate-index.ts";
 import type { AionisSubstrate } from "./types.ts";
 export type FileAionisSubstrateOptions = {
     dir: string;
     now?: () => Date;
+    candidateIndex?: AionisCandidateIndex | null;
+    rebuildCandidateIndexOnOpen?: boolean;
 };
 export declare function openFileAionisSubstrate(options: FileAionisSubstrateOptions): Promise<AionisSubstrate>;
 //# sourceMappingURL=file-substrate.d.ts.map

package/dist/file-substrate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"file-substrate.d.ts","sourceRoot":"","sources":["../src/file-substrate.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAcV,eAAe,EAChB,MAAM,YAAY,CAAC;AAGpB,MAAM,MAAM,0BAA0B,GAAG;IACvC,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAClB,CAAC;AAyEF,wBAAsB,uBAAuB,CAAC,OAAO,EAAE,0BAA0B,GAAG,OAAO,CAAC,eAAe,CAAC,CAiZ3G"}
+{"version":3,"file":"file-substrate.d.ts","sourceRoot":"","sources":["../src/file-substrate.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AACjE,OAAO,KAAK,EAcV,eAAe,EAChB,MAAM,YAAY,CAAC;AAGpB,MAAM,MAAM,0BAA0B,GAAG;IACvC,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IACjB,cAAc,CAAC,EAAE,oBAAoB,GAAG,IAAI,CAAC;IAC7C,2BAA2B,CAAC,EAAE,OAAO,CAAC;CACvC,CAAC;AAyEF,wBAAsB,uBAAuB,CAAC,OAAO,EAAE,0BAA0B,GAAG,OAAO,CAAC,eAAe,CAAC,CA+b3G"}