@aionis/substrate 0.1.4 → 0.1.6

package/dist/zvec-candidate-index.js

@@ -0,0 +1,463 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, renameSync, rmSync } from "node:fs";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+const ZVEC_PACKAGE = "@zvec/zvec";
+const DEFAULT_COLLECTION_NAME = "aionis_substrate_candidates_v1";
+const DEFAULT_VECTOR_FIELD = "embedding";
+const MANIFEST_FILE = "manifest.json";
+function assertStatus(status, operation) {
+    const statuses = Array.isArray(status) ? status : [status];
+    const failed = statuses.find((item) => !item.ok);
+    if (failed)
+        throw new Error(`Zvec candidate index ${operation} failed: ${failed.code} ${failed.message}`);
+}
+function normalizeVector(value, label) {
+    if (value === null || value === undefined)
+        return null;
+    if (!Array.isArray(value) || value.length === 0)
+        throw new Error(`${label} vector must be a non-empty number array`);
+    const out = value.map((item, index) => {
+        if (!Number.isFinite(item))
+            throw new Error(`${label} vector contains a non-finite value at index ${index}`);
+        return Number(item);
+    });
+    return out;
+}
+function metadataVector(node) {
+    const metadata = node.metadata ?? {};
+    const candidates = [
+        metadata.embedding,
+        metadata.embedding_vector,
+        metadata.vector,
+        metadata.query_vector,
+    ];
+    for (const candidate of candidates) {
+        if (!Array.isArray(candidate))
+            continue;
+        if (candidate.every((item) => typeof item === "number" && Number.isFinite(item)))
+            return [...candidate];
+    }
+    return null;
+}
+function vectorHash(vector) {
+    const hash = createHash("sha256");
+    for (const value of vector)
+        hash.update(String(value)).update("\0");
+    return hash.digest("hex");
+}
+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 nodeFingerprint(node, vector, embeddingModel) {
+    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: stableMetadataText(node.metadata),
+        updatedAt: node.updatedAt,
+        embeddingModel,
+        vectorHash: vectorHash(vector),
+    });
+}
+function docIdFor(scope, memoryId, embeddingModel) {
+    return createHash("sha256")
+        .update(scope)
+        .update("\0")
+        .update(memoryId)
+        .update("\0")
+        .update(embeddingModel)
+        .digest("hex");
+}
+function manifestKey(scope, memoryId, embeddingModel) {
+    return `${scope}\u0000${memoryId}\u0000${embeddingModel}`;
+}
+function dimensionDirName(dimension) {
+    return `dim-${dimension}`;
+}
+function parseDimensionDirName(value) {
+    const match = /^dim-(\d+)$/.exec(value);
+    if (!match)
+        return null;
+    const dimension = Number(match[1]);
+    return Number.isInteger(dimension) && dimension > 0 ? dimension : null;
+}
+function stringLiteral(value) {
+    return `'${value.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`;
+}
+function filterExpression(input, embeddingModel) {
+    const clauses = [
+        `scope = ${stringLiteral(input.scope)}`,
+        `embedding_model = ${stringLiteral(embeddingModel)}`,
+    ];
+    if (input.kinds?.length)
+        clauses.push(`kind in (${input.kinds.map(stringLiteral).join(", ")})`);
+    if (input.lifecycle?.length)
+        clauses.push(`lifecycle in (${input.lifecycle.map(stringLiteral).join(", ")})`);
+    if (input.authority?.length)
+        clauses.push(`authority in (${input.authority.map(stringLiteral).join(", ")})`);
+    if (input.agentId !== undefined)
+        clauses.push(`agent_id = ${input.agentId === null ? "''" : stringLiteral(input.agentId)}`);
+    if (input.teamId !== undefined)
+        clauses.push(`team_id = ${input.teamId === null ? "''" : stringLiteral(input.teamId)}`);
+    return clauses.join(" AND ");
+}
+function normalizeScore(rawScore) {
+    if (!Number.isFinite(rawScore))
+        return 0;
+    return Math.max(-1, Math.min(1, 1 - rawScore));
+}
+async function loadZvecModule() {
+    try {
+        return await import(__rewriteRelativeImportExtension(ZVEC_PACKAGE));
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`Zvec candidate index requires optional dependency ${ZVEC_PACKAGE}. Install it with npm install ${ZVEC_PACKAGE}@0.5.0. Cause: ${message}`);
+    }
+}
+function createSchema(zvec, collectionName, vectorField, dimension) {
+    return new zvec.ZVecCollectionSchema({
+        name: collectionName,
+        vectors: {
+            name: vectorField,
+            dataType: zvec.ZVecDataType.VECTOR_FP32,
+            dimension,
+            indexParams: {
+                indexType: zvec.ZVecIndexType.FLAT,
+                metricType: zvec.ZVecMetricType.COSINE,
+            },
+        },
+        fields: [
+            { name: "memory_id", dataType: zvec.ZVecDataType.STRING, indexParams: { indexType: zvec.ZVecIndexType.INVERT } },
+            { name: "scope", dataType: zvec.ZVecDataType.STRING, indexParams: { indexType: zvec.ZVecIndexType.INVERT } },
+            { name: "embedding_model", dataType: zvec.ZVecDataType.STRING, indexParams: { indexType: zvec.ZVecIndexType.INVERT } },
+            { name: "kind", dataType: zvec.ZVecDataType.STRING, indexParams: { indexType: zvec.ZVecIndexType.INVERT } },
+            { name: "lifecycle", dataType: zvec.ZVecDataType.STRING, indexParams: { indexType: zvec.ZVecIndexType.INVERT } },
+            { name: "authority", dataType: zvec.ZVecDataType.STRING, indexParams: { indexType: zvec.ZVecIndexType.INVERT } },
+            { name: "agent_id", dataType: zvec.ZVecDataType.STRING, nullable: true, indexParams: { indexType: zvec.ZVecIndexType.INVERT } },
+            { name: "team_id", dataType: zvec.ZVecDataType.STRING, nullable: true, indexParams: { indexType: zvec.ZVecIndexType.INVERT } },
+            { name: "updated_at", dataType: zvec.ZVecDataType.STRING, indexParams: { indexType: zvec.ZVecIndexType.INVERT } },
+        ],
+    });
+}
+function recordToDoc(node, vector, embeddingModel) {
+    const fields = {
+        memory_id: node.id,
+        scope: node.scope,
+        embedding_model: embeddingModel,
+        kind: node.kind,
+        lifecycle: node.lifecycle,
+        authority: node.authority,
+        updated_at: node.updatedAt,
+    };
+    if (node.agentId)
+        fields.agent_id = node.agentId;
+    if (node.teamId)
+        fields.team_id = node.teamId;
+    return {
+        id: docIdFor(node.scope, node.id, embeddingModel),
+        vectors: { [DEFAULT_VECTOR_FIELD]: vector },
+        fields,
+    };
+}
+async function readManifest(path) {
+    try {
+        const parsed = JSON.parse(await readFile(path, "utf8"));
+        const entries = Array.isArray(parsed.entries) ? parsed.entries : [];
+        return new Map(entries.map((entry) => [manifestKey(entry.scope, entry.memoryId, entry.embeddingModel), entry]));
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return new Map();
+        throw err;
+    }
+}
+async function writeManifest(path, entries) {
+    const payload = {
+        version: 1,
+        entries: Array.from(entries.values()).sort((a, b) => a.scope.localeCompare(b.scope) ||
+            a.memoryId.localeCompare(b.memoryId) ||
+            a.embeddingModel.localeCompare(b.embeddingModel)),
+    };
+    const tempPath = `${path}.tmp-${process.pid}-${Date.now()}`;
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(tempPath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+    await rename(tempPath, path);
+}
+export class ZvecCandidateIndex {
+    zvecPromise = null;
+    collections = new Map();
+    manifest = null;
+    options;
+    path;
+    manifestPath;
+    collectionName;
+    vectorField;
+    embeddingModel;
+    manifestDirty = false;
+    constructor(options) {
+        this.options = options;
+        if (!options.path.trim())
+            throw new Error("Zvec candidate index path is required");
+        this.path = options.path;
+        this.manifestPath = join(options.path, MANIFEST_FILE);
+        this.collectionName = options.collectionName ?? DEFAULT_COLLECTION_NAME;
+        this.vectorField = options.vectorField ?? DEFAULT_VECTOR_FIELD;
+        this.embeddingModel = options.embeddingModel ?? "default";
+        mkdirSync(options.path, { recursive: true });
+    }
+    async zvec() {
+        this.zvecPromise ??= loadZvecModule();
+        return this.zvecPromise;
+    }
+    async loadManifest() {
+        this.manifest ??= await readManifest(this.manifestPath);
+        return this.manifest;
+    }
+    async saveManifest() {
+        await writeManifest(this.manifestPath, await this.loadManifest());
+        this.manifestDirty = false;
+    }
+    markManifestDirty() {
+        this.manifestDirty = true;
+    }
+    async flushManifest() {
+        if (!this.manifestDirty)
+            return;
+        await this.saveManifest();
+    }
+    async collectionForDimension(dimension) {
+        if (!Number.isInteger(dimension) || dimension <= 0)
+            throw new Error(`invalid Zvec vector dimension: ${dimension}`);
+        const existing = this.collections.get(dimension);
+        if (existing)
+            return existing.collection;
+        const zvec = await this.zvec();
+        const collectionPath = join(this.path, dimensionDirName(dimension));
+        const collection = existsSync(collectionPath)
+            ? zvec.ZVecOpen(collectionPath)
+            : zvec.ZVecCreateAndOpen(collectionPath, createSchema(zvec, this.collectionName, this.vectorField, dimension));
+        this.collections.set(dimension, { dimension, collection });
+        return collection;
+    }
+    async nodeVector(node) {
+        const raw = this.options.vectorForNode
+            ? await this.options.vectorForNode(node)
+            : metadataVector(node);
+        return normalizeVector(raw, `node ${node.id}`);
+    }
+    async queryVector(input) {
+        const raw = this.options.vectorForQuery
+            ? await this.options.vectorForQuery(input)
+            : input.queryVector;
+        return normalizeVector(raw, "query");
+    }
+    async upsertNode(node) {
+        const vector = await this.nodeVector(node);
+        if (!vector) {
+            await this.deleteNode(node.scope, node.id);
+            return;
+        }
+        const embeddingModel = node.metadata?.embedding_model && typeof node.metadata.embedding_model === "string"
+            ? node.metadata.embedding_model
+            : this.embeddingModel;
+        const collection = await this.collectionForDimension(vector.length);
+        assertStatus(collection.upsertSync({
+            ...recordToDoc(node, vector, embeddingModel),
+            vectors: { [this.vectorField]: vector },
+        }), "upsert");
+        const manifest = await this.loadManifest();
+        manifest.set(manifestKey(node.scope, node.id, embeddingModel), {
+            scope: node.scope,
+            memoryId: node.id,
+            docId: docIdFor(node.scope, node.id, embeddingModel),
+            dimension: vector.length,
+            embeddingModel,
+            fingerprint: nodeFingerprint(node, vector, embeddingModel),
+        });
+        this.markManifestDirty();
+    }
+    async deleteNode(scope, id) {
+        const manifest = await this.loadManifest();
+        const entries = Array.from(manifest.entries()).filter(([, entry]) => entry.scope === scope && entry.memoryId === id);
+        if (entries.length > 0) {
+            for (const [key, entry] of entries) {
+                const collection = await this.collectionForDimension(entry.dimension);
+                assertStatus(collection.deleteSync(entry.docId), "delete");
+                manifest.delete(key);
+            }
+            this.markManifestDirty();
+            return;
+        }
+        for (const dimension of this.knownDimensions()) {
+            const collection = await this.collectionForDimension(dimension);
+            assertStatus(collection.deleteByFilterSync(`scope = ${stringLiteral(scope)} AND memory_id = ${stringLiteral(id)}`), "delete");
+        }
+    }
+    async search(input) {
+        const vector = await this.queryVector(input);
+        if (!vector)
+            return null;
+        const embeddingModel = input.embeddingModel ?? this.embeddingModel;
+        const collection = await this.collectionForDimension(vector.length);
+        const rows = collection.querySync({
+            fieldName: this.vectorField,
+            vector,
+            topk: input.limit ?? 50,
+            filter: filterExpression(input, embeddingModel),
+            includeVector: false,
+            outputFields: ["memory_id"],
+        });
+        return rows
+            .map((row) => {
+            const memoryId = typeof row.fields.memory_id === "string" ? row.fields.memory_id : row.id;
+            const reasons = [{
+                    code: "zvec_candidate_index_match",
+                    detail: `Zvec candidate score=${normalizeScore(row.score).toFixed(6)}`,
+                }];
+            return {
+                scope: input.scope,
+                memoryId,
+                score: normalizeScore(row.score),
+                reasons,
+            };
+        })
+            .sort((a, b) => b.score - a.score || a.memoryId.localeCompare(b.memoryId));
+    }
+    async rebuild(nodes) {
+        const buffered = [];
+        for (const node of nodes) {
+            const vector = await this.nodeVector(node);
+            if (!vector)
+                continue;
+            const embeddingModel = node.metadata?.embedding_model && typeof node.metadata.embedding_model === "string"
+                ? node.metadata.embedding_model
+                : this.embeddingModel;
+            buffered.push({ node, vector, embeddingModel });
+        }
+        const tmpPath = `${this.path}.rebuild-${process.pid}-${Date.now()}`;
+        rmSync(tmpPath, { recursive: true, force: true });
+        const next = new ZvecCandidateIndex({
+            ...this.options,
+            path: tmpPath,
+            collectionName: this.collectionName,
+            vectorField: this.vectorField,
+            embeddingModel: this.embeddingModel,
+        });
+        try {
+            for (const item of buffered)
+                await next.upsertNode(item.node);
+            const nextManifest = await next.loadManifest();
+            await next.close();
+            await this.close();
+            rmSync(this.path, { recursive: true, force: true });
+            renameSync(tmpPath, this.path);
+            mkdirSync(this.path, { recursive: true });
+            this.manifest = new Map(nextManifest);
+            this.manifestDirty = false;
+            return await this.verify(nodes);
+        }
+        catch (err) {
+            await next.close().catch(() => undefined);
+            rmSync(tmpPath, { recursive: true, force: true });
+            throw err;
+        }
+    }
+    async verify(nodes) {
+        const manifest = await this.loadManifest();
+        const expected = new Map();
+        for (const node of nodes) {
+            const vector = await this.nodeVector(node);
+            if (!vector)
+                continue;
+            const embeddingModel = node.metadata?.embedding_model && typeof node.metadata.embedding_model === "string"
+                ? node.metadata.embedding_model
+                : this.embeddingModel;
+            expected.set(manifestKey(node.scope, node.id, embeddingModel), {
+                node,
+                vector,
+                embeddingModel,
+                fingerprint: nodeFingerprint(node, vector, embeddingModel),
+            });
+        }
+        const missingNodeIds = [];
+        const orphanNodeIds = [];
+        const staleNodeIds = [];
+        for (const [key, expectedEntry] of expected) {
+            const actual = manifest.get(key);
+            if (!actual) {
+                missingNodeIds.push(expectedEntry.node.id);
+                continue;
+            }
+            if (actual.fingerprint !== expectedEntry.fingerprint)
+                staleNodeIds.push(expectedEntry.node.id);
+            const collection = await this.collectionForDimension(actual.dimension);
+            const fetched = collection.fetchSync({ ids: actual.docId, outputFields: ["memory_id"], includeVector: false });
+            if (!fetched[actual.docId] && !missingNodeIds.includes(expectedEntry.node.id)) {
+                missingNodeIds.push(expectedEntry.node.id);
+            }
+        }
+        for (const [key, actual] of manifest) {
+            if (!expected.has(key))
+                orphanNodeIds.push(actual.memoryId);
+        }
+        missingNodeIds.sort();
+        orphanNodeIds.sort();
+        staleNodeIds.sort();
+        return {
+            ok: missingNodeIds.length === 0 && orphanNodeIds.length === 0 && staleNodeIds.length === 0,
+            sourceCount: expected.size,
+            indexedCount: manifest.size,
+            missingNodeIds,
+            orphanNodeIds,
+            staleNodeIds,
+        };
+    }
+    async close() {
+        await this.flushManifest();
+        for (const { collection } of this.collections.values())
+            collection.closeSync();
+        this.collections.clear();
+    }
+    knownDimensions() {
+        const dimensions = new Set(this.collections.keys());
+        if (existsSync(this.path)) {
+            for (const entry of readdirSync(this.path, { withFileTypes: true })) {
+                if (!entry.isDirectory())
+                    continue;
+                const dimension = parseDimensionDirName(entry.name);
+                if (dimension)
+                    dimensions.add(dimension);
+            }
+        }
+        return Array.from(dimensions).sort((a, b) => a - b);
+    }
+}
+export function createZvecCandidateIndex(options) {
+    return new ZvecCandidateIndex(options);
+}
+//# sourceMappingURL=zvec-candidate-index.js.map

package/dist/zvec-candidate-index.js.map

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

package/docs/ADAPTER_CONTRACT.md

@@ -100,7 +100,17 @@ Given the same durable node state, adapters must return the same `searchNodes` i
 
 Search is read-only. It must not append `memory.decision.recorded`, lifecycle events, or any other event.
 
-Search is not a vector index and not the full Runtime admission policy. It is a deterministic substrate query for locating candidate memory nodes before higher-level governance decides whether they can affect an Agent turn.
+Search is a deterministic substrate query for locating candidate memory nodes before higher-level governance decides whether they can affect an Agent turn. Vector candidate indexes can narrow the search window, while final node loading and scoring stay inside the adapter's canonical Substrate path.
+
+When a candidate index is configured, both adapters must preserve the same final `searchNodes` ids, scores, and reason-code semantics. The index is allowed to preselect candidate ids, but the adapter must reload canonical nodes from the truth store before returning results.
+
+Candidate index synchronization requirements:
+
+- open-time rebuild is enabled by default;
+- `putNode` write-through updates the index after the durable node mutation succeeds;
+- `transitionLifecycle` write-through updates the index after the durable lifecycle mutation succeeds;
+- `verify(nodes)` must expose missing, orphan, and stale entries so operators can rebuild instead of trusting silent drift.
+- Zvec-backed indexes may require `queryVector`; if no usable query vector is supplied, the adapter must fall back to canonical deterministic search instead of returning an empty result set.
 
 ### 8. Context Preview and Decision Receipt Side Effect
 
@@ -167,7 +177,7 @@ The test suite currently checks:
 The adapter contract does not define:
 
 - vector similarity search;
-- embedding storage/indexing;
+- embedding model management or embedding provider calls;
 - full Aionis Runtime admission policy;
 - SaaS tenancy;
 - external Agent orchestration.

package/docs/API_USAGE.md

@@ -137,6 +137,141 @@ It supports structured filters for kind, lifecycle, authority, target files, own
 
 It is not vector search, semantic adjudication, or admission policy. Use `compileContext` when the Agent needs governed prompt surfaces.
 
+## Optional Candidate Index
+
+Use a candidate index when the store needs a database-like lookup boundary before final Substrate scoring:
+
+```ts
+import { createMemoryCandidateIndex, openSqliteAionisSubstrate } from "@aionis/substrate";
+
+const candidateIndex = createMemoryCandidateIndex();
+const store = await openSqliteAionisSubstrate({
+  path: "./substrate.sqlite",
+  candidateIndex,
+});
+
+await store.putNode({
+  id: "route-current",
+  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 health = await candidateIndex.verify(await store.listNodes("repo-a"));
+const results = await store.searchNodes({
+  scope: "repo-a",
+  query: "runtime verifier",
+  limit: 10,
+});
+```
+
+The index is optional. When configured, it receives write-through node updates and is rebuilt on open unless `rebuildCandidateIndexOnOpen: false` is set. Search still reloads canonical nodes from the store and applies Substrate scoring/filtering; the index only supplies candidate ids.
+
+### Zvec Candidate Index
+
+Install Zvec only when local vector preselection is needed:
+
+```bash
+npm install @aionis/substrate @zvec/zvec
+```
+
+```ts
+import { createZvecCandidateIndex, openSqliteAionisSubstrate } from "@aionis/substrate";
+
+const candidateIndex = createZvecCandidateIndex({
+  path: "./substrate.zvec",
+  embeddingModel: "text-embedding-3-small",
+});
+
+const store = await openSqliteAionisSubstrate({
+  path: "./substrate.sqlite",
+  candidateIndex,
+});
+
+await store.putNode({
+  id: "route-current",
+  scope: "repo-a",
+  kind: "procedure",
+  summary: "Use src/runtime.ts after verifier passed.",
+  lifecycle: "active",
+  authority: "trusted",
+  confidence: 0.95,
+  targetFiles: ["src/runtime.ts"],
+  metadata: {
+    embedding_model: "text-embedding-3-small",
+    embedding: [0.12, 0.34, 0.56],
+  },
+});
+
+const results = await store.searchNodes({
+  scope: "repo-a",
+  queryVector: [0.11, 0.35, 0.55],
+  embeddingModel: "text-embedding-3-small",
+  candidateLimit: 20,
+  limit: 10,
+});
+```
+
+`createZvecCandidateIndex` is a candidate-index adapter. File/SQLite remain the truth store, and queries without `queryVector` fall back to deterministic Substrate search.
+
+### Embedding Projection
+
+Substrate does not call embedding providers by itself, but it exposes a stable
+projection contract for hosts that want to generate vectors consistently:
+
+```ts
+import {
+  buildAionisEmbeddingDocument,
+  buildAionisEmbeddingQuery,
+  createZvecCandidateIndex,
+  openSqliteAionisSubstrate,
+} from "@aionis/substrate";
+
+const memory = {
+  id: "route-current",
+  scope: "repo-a",
+  kind: "procedure" as const,
+  summary: "Use src/runtime.ts after verifier passed.",
+  lifecycle: "active" as const,
+  authority: "trusted" as const,
+  confidence: 0.95,
+  targetFiles: ["src/runtime.ts"],
+};
+
+const documentText = buildAionisEmbeddingDocument(memory);
+const documentVector = await embedAsDocument(documentText);
+
+const candidateIndex = createZvecCandidateIndex({
+  path: "./substrate.zvec",
+  embeddingModel: "text-embedding-v4",
+  vectorForQuery: async (input) => {
+    if (!input.query) return null;
+    return await embedAsQuery(buildAionisEmbeddingQuery(input.query));
+  },
+});
+
+const store = await openSqliteAionisSubstrate({
+  path: "./substrate.sqlite",
+  candidateIndex,
+});
+
+await store.putNode({
+  ...memory,
+  metadata: {
+    embedding_model: "text-embedding-v4",
+    embedding: documentVector,
+  },
+});
+```
+
+Use the same projection version for writes and searches. The structured
+projection labels memory documents and retrieval queries separately, which is
+useful for providers that distinguish document and query embeddings.
+
 ## Preview Context
 
 ```ts