@oscharko-dev/keiko-memory-vault 0.2.0

package/dist/embeddings.js

@@ -0,0 +1,116 @@
+// Embedding I/O. Vectors are encoded as a packed Float32 little-endian byte buffer so a vault
+// written on one host opens byte-identical on another, regardless of platform endianness.
+// Reading a host-endian `Float32Array` directly off the buffer would be silently wrong on a
+// big-endian host (rare in practice, but the round-trip test catches the regression class).
+//
+// Storage is upsert by primary key (memory_id). Replacing an embedding is the common path: the
+// retrieval layer (#210) reschedules a re-embedding when the model identity drifts.
+import { MemoryStorageError } from "./errors.js";
+// Hard upper bound on vector dimensions. The largest production embedding model in scope today
+// (OpenAI text-embedding-3-large) is 3072 dims; 4096 gives one binary-doubling of headroom while
+// capping the per-row BLOB at 16 KiB. Without this bound a caller could request a 2^31 element
+// Float32 allocation (8 GiB) via the in-process API and crash the process — CWE-400.
+export const MAX_EMBEDDING_DIMENSIONS = 4096;
+export const ALLOWED_EMBEDDING_METRICS = [
+    "cosine",
+    "euclidean",
+    "dot",
+];
+const UPSERT_SQL = `
+INSERT INTO memory_embeddings (
+  memory_id, provider, model_id, model_revision, vector_dimensions,
+  vector_metric, vector, created_at
+) VALUES (?,?,?,?,?,?,?,?)
+ON CONFLICT(memory_id) DO UPDATE SET
+  provider = excluded.provider,
+  model_id = excluded.model_id,
+  model_revision = excluded.model_revision,
+  vector_dimensions = excluded.vector_dimensions,
+  vector_metric = excluded.vector_metric,
+  vector = excluded.vector,
+  created_at = excluded.created_at
+`;
+const SELECT_SQL = "SELECT * FROM memory_embeddings WHERE memory_id = ?";
+const BULK_SELECT_CHUNK_SIZE = 500;
+const BYTES_PER_FLOAT32 = 4;
+function encodeVectorLE(vector) {
+    const buf = Buffer.alloc(vector.length * BYTES_PER_FLOAT32);
+    const view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
+    for (let i = 0; i < vector.length; i += 1) {
+        // setFloat32(..., true) writes little-endian regardless of host endianness so the on-disk
+        // byte layout is identical across Linux/macOS/Windows on x86/arm and theoretical big-endian
+        // hosts.
+        view.setFloat32(i * BYTES_PER_FLOAT32, vector[i] ?? 0, true);
+    }
+    return buf;
+}
+function decodeVectorLE(bytes, dimensions) {
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const out = new Float32Array(dimensions);
+    for (let i = 0; i < dimensions; i += 1) {
+        out[i] = view.getFloat32(i * BYTES_PER_FLOAT32, true);
+    }
+    return out;
+}
+export function upsertEmbeddingRow(db, memoryId, embedding, nowMs, cipher) {
+    // The vector is memory CONTENT (ADR-0035), so the packed LE bytes are sealed before they touch
+    // the BLOB column. vector_dimensions / vector_metric stay cleartext for retrieval-side dispatch.
+    const bytes = cipher.sealBytes(encodeVectorLE(embedding.vector));
+    db.prepare(UPSERT_SQL).run(memoryId, embedding.provider, embedding.modelId, embedding.modelRevision ?? null, embedding.vector.length, embedding.metric, bytes, nowMs);
+}
+function narrowMetric(raw) {
+    if (!ALLOWED_EMBEDDING_METRICS.includes(raw)) {
+        throw new MemoryStorageError("schema-mismatch", "Stored embedding metric is not in the allowed set.");
+    }
+    return raw;
+}
+function openVectorBytes(stored, cipher) {
+    // The BLOB is ALWAYS a sealed binary envelope here: the v1->v2 migration (run before any read in
+    // openMemoryDatabase) seals every embedding row, and there is no unambiguous plaintext-vs-sealed
+    // marker for raw Float32 bytes, so we never guess. openBytes throws loudly on a wrong key or a
+    // tampered/corrupt envelope rather than silently returning plaintext.
+    return cipher.openBytes(Buffer.from(stored));
+}
+export function getEmbeddingRow(db, memoryId, cipher) {
+    const row = db.prepare(SELECT_SQL).get(memoryId);
+    if (row === undefined)
+        return undefined;
+    return rowToEmbedding(row, cipher);
+}
+function rowToEmbedding(row, cipher) {
+    const plainVector = openVectorBytes(row.vector, cipher);
+    // Read-side soundness: a tampered DB row (or a future schema drift) must not silently land a
+    // bad metric string in the typed return shape, and the DECRYPTED BLOB length must match the
+    // declared dimension count so callers can rely on `vector.length === dimensions`.
+    const expectedBytes = row.vector_dimensions * BYTES_PER_FLOAT32;
+    if (plainVector.byteLength !== expectedBytes) {
+        throw new MemoryStorageError("schema-mismatch", "Stored embedding vector byte length does not match declared dimensions.");
+    }
+    const base = {
+        memoryId: row.memory_id,
+        provider: row.provider,
+        modelId: row.model_id,
+        dimensions: row.vector_dimensions,
+        metric: narrowMetric(row.vector_metric),
+        vector: decodeVectorLE(plainVector, row.vector_dimensions),
+        createdAt: row.created_at,
+    };
+    return row.model_revision === null ? base : { ...base, modelRevision: row.model_revision };
+}
+export function getEmbeddingRows(db, memoryIds, cipher) {
+    const out = new Map();
+    if (memoryIds.length === 0)
+        return out;
+    const uniqueIds = [...new Set(memoryIds)];
+    for (let i = 0; i < uniqueIds.length; i += BULK_SELECT_CHUNK_SIZE) {
+        const chunk = uniqueIds.slice(i, i + BULK_SELECT_CHUNK_SIZE);
+        const placeholders = chunk.map(() => "?").join(",");
+        const rows = db
+            .prepare(`SELECT * FROM memory_embeddings WHERE memory_id IN (${placeholders})`)
+            .all(...chunk);
+        for (const row of rows) {
+            out.set(row.memory_id, rowToEmbedding(row, cipher));
+        }
+    }
+    return out;
+}

package/dist/errors.d.ts

@@ -0,0 +1,14 @@
+export type MemoryStorageErrorCode = "invalid-path" | "invalid-input" | "not-found" | "constraint-violation" | "schema-mismatch" | "internal";
+export declare class MemoryStorageError extends Error {
+    readonly code: MemoryStorageErrorCode;
+    constructor(code: MemoryStorageErrorCode, message: string);
+}
+export interface MemoryStorageValidationFailure {
+    readonly path: readonly string[];
+    readonly message: string;
+}
+export declare class MemoryStorageValidationError extends MemoryStorageError {
+    readonly failures: readonly MemoryStorageValidationFailure[];
+    constructor(message: string, failures: readonly MemoryStorageValidationFailure[]);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,sBAAsB,GAC9B,cAAc,GACd,eAAe,GACf,WAAW,GACX,sBAAsB,GACtB,iBAAiB,GACjB,UAAU,CAAC;AAEf,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,SAAgB,IAAI,EAAE,sBAAsB,CAAC;gBAE1B,IAAI,EAAE,sBAAsB,EAAE,OAAO,EAAE,MAAM;CAKjE;AAKD,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,qBAAa,4BAA6B,SAAQ,kBAAkB;IAClE,SAAgB,QAAQ,EAAE,SAAS,8BAA8B,EAAE,CAAC;gBAEjD,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,8BAA8B,EAAE;CAKxF"}

package/dist/errors.js

@@ -0,0 +1,20 @@
+// Typed error taxonomy for keiko-memory-vault. Stable string codes so callers in audit (#214),
+// capture (#207), and the eventual UI (#211) can branch on `error.code` without parsing messages.
+// Messages MUST NOT include raw paths, SQL fragments, or system error strings — those surface to
+// downstream BFF envelopes that may log to disk.
+export class MemoryStorageError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "MemoryStorageError";
+        this.code = code;
+    }
+}
+export class MemoryStorageValidationError extends MemoryStorageError {
+    failures;
+    constructor(message, failures) {
+        super("invalid-input", message);
+        this.name = "MemoryStorageValidationError";
+        this.failures = failures;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { KEIKO_MEMORY_VAULT_VERSION } from "./version.js";
+export { createMemoryVault } from "./vault.js";
+export { MemoryStorageError, MemoryStorageValidationError, type MemoryStorageErrorCode, type MemoryStorageValidationFailure, } from "./errors.js";
+export { MEMORY_DB_FILENAME, MEMORY_DIR_NAME, DEFAULT_STATE_DIR, resolveMemoryDir, resolveMemoryDbPath, } from "./paths.js";
+export { MEMORY_VAULT_SCHEMA_VERSION } from "./schema.js";
+export type { DeleteMemoryOptions, ListMemoriesOptions, MemoryAccessStat, MemoryBatchDelete, MemoryBatchUpdate, MemoryDeleteResult, MemoryEmbeddingInput, MemoryEmbeddingMetric, MemoryEmbeddingRow, MemoryEvent, MemoryTombstone, MemoryUpdatePatch, MemoryVaultFactoryOptions, MemoryVaultStore, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EACL,kBAAkB,EAClB,4BAA4B,EAC5B,KAAK,sBAAsB,EAC3B,KAAK,8BAA8B,GACpC,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,gBAAgB,EAChB,mBAAmB,GACpB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,2BAA2B,EAAE,MAAM,aAAa,CAAC;AAC1D,YAAY,EACV,mBAAmB,EACnB,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,EAClB,oBAAoB,EACpB,qBAAqB,EACrB,kBAAkB,EAClB,WAAW,EACX,eAAe,EACf,iBAAiB,EACjB,yBAAyB,EACzB,gBAAgB,GACjB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,9 @@
+// Public surface of @oscharko-dev/keiko-memory-vault (Epic #204 child #206). Keeping this file
+// the SOLE entry point prevents downstream packages from reaching into private modules
+// (ADR-0019 trust rule 7). Subpath exports are intentionally absent; the package is small
+// enough that a single barrel is the lowest-friction surface for #207-#214 consumers.
+export { KEIKO_MEMORY_VAULT_VERSION } from "./version.js";
+export { createMemoryVault } from "./vault.js";
+export { MemoryStorageError, MemoryStorageValidationError, } from "./errors.js";
+export { MEMORY_DB_FILENAME, MEMORY_DIR_NAME, DEFAULT_STATE_DIR, resolveMemoryDir, resolveMemoryDbPath, } from "./paths.js";
+export { MEMORY_VAULT_SCHEMA_VERSION } from "./schema.js";

package/dist/memories.d.ts

@@ -0,0 +1,11 @@
+import type { DatabaseSync } from "node:sqlite";
+import type { MemoryId, MemoryRecord, MemoryScope } from "@oscharko-dev/keiko-contracts/memory";
+import type { ListMemoriesOptions } from "./types.js";
+import type { MemoryContentCipher } from "./cipher.js";
+export declare function insertMemoryRow(db: DatabaseSync, record: MemoryRecord, cipher: MemoryContentCipher): void;
+export declare function getMemoryRow(db: DatabaseSync, id: MemoryId, cipher: MemoryContentCipher): MemoryRecord | undefined;
+export declare function updateMemoryRow(db: DatabaseSync, record: MemoryRecord, cipher: MemoryContentCipher): void;
+export declare function deleteMemoryRow(db: DatabaseSync, id: MemoryId): boolean;
+export declare function listMemoriesRows(db: DatabaseSync, options: ListMemoriesOptions, nowMs: number, cipher: MemoryContentCipher): readonly MemoryRecord[];
+export declare function listMemoriesByScopeRows(db: DatabaseSync, scope: MemoryScope, options: ListMemoriesOptions, nowMs: number, cipher: MemoryContentCipher): readonly MemoryRecord[];
+//# sourceMappingURL=memories.d.ts.map

package/dist/memories.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memories.d.ts","sourceRoot":"","sources":["../src/memories.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EACV,QAAQ,EACR,YAAY,EACZ,WAAW,EAEZ,MAAM,sCAAsC,CAAC;AAG9C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACtD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAuFvD,wBAAgB,eAAe,CAC7B,EAAE,EAAE,YAAY,EAChB,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,mBAAmB,GAC1B,IAAI,CAEN;AAED,wBAAgB,YAAY,CAC1B,EAAE,EAAE,YAAY,EAChB,EAAE,EAAE,QAAQ,EACZ,MAAM,EAAE,mBAAmB,GAC1B,YAAY,GAAG,SAAS,CAG1B;AAED,wBAAgB,eAAe,CAC7B,EAAE,EAAE,YAAY,EAChB,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,mBAAmB,GAC1B,IAAI,CAkCN;AAED,wBAAgB,eAAe,CAAC,EAAE,EAAE,YAAY,EAAE,EAAE,EAAE,QAAQ,GAAG,OAAO,CAGvE;AAiED,wBAAgB,gBAAgB,CAC9B,EAAE,EAAE,YAAY,EAChB,OAAO,EAAE,mBAAmB,EAC5B,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,mBAAmB,GAC1B,SAAS,YAAY,EAAE,CAkBzB;AAED,wBAAgB,uBAAuB,CACrC,EAAE,EAAE,YAAY,EAChB,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,mBAAmB,EAC5B,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,mBAAmB,GAC1B,SAAS,YAAY,EAAE,CAoBzB"}

package/dist/memories.js

@@ -0,0 +1,195 @@
+// Prepared SQL for the memories table. Every parameter binds positionally; no template
+// concatenation with caller data so SQL injection is structurally impossible at this layer.
+// The validator gate sits in vault.ts, BEFORE these functions are called, so this module assumes
+// inputs are already shape-valid and only owes the SQL.
+import { memoryRecordToRow, rowToMemoryRecord } from "./serialize.js";
+import { scopeCoordinateOf, scopeKindOf } from "./scope-key.js";
+import { MemoryStorageError } from "./errors.js";
+const INSERT_SQL = `
+INSERT INTO memories (
+  id, schema_version, type, scope_kind, scope_coordinate, body, payload_json,
+  status, sensitivity, pinned, confidence, valid_from, valid_until, stale_reason,
+  tags_json, source_kind, source_conversation_id, source_workflow_run_id,
+  source_evidence_manifest_id, captured_at, capture_rationale, model_provider,
+  model_id, model_revision, retention_policy_key, retention_retain_until,
+  retention_notes, created_at, updated_at
+) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)
+`;
+const SELECT_BY_ID_SQL = "SELECT * FROM memories WHERE id = ?";
+const DELETE_SQL = "DELETE FROM memories WHERE id = ?";
+// UPDATE rewrites every column from the resolved record so a partial patch can land without
+// touching SQL per-field. The vault composes the merge in TypeScript (validator-safe) and hands
+// us a final record; we just write it.
+const UPDATE_SQL = `
+UPDATE memories SET
+  type = ?,
+  body = ?,
+  payload_json = ?,
+  status = ?,
+  sensitivity = ?,
+  pinned = ?,
+  confidence = ?,
+  valid_from = ?,
+  valid_until = ?,
+  stale_reason = ?,
+  tags_json = ?,
+  source_kind = ?,
+  source_conversation_id = ?,
+  source_workflow_run_id = ?,
+  source_evidence_manifest_id = ?,
+  captured_at = ?,
+  capture_rationale = ?,
+  model_provider = ?,
+  model_id = ?,
+  model_revision = ?,
+  retention_policy_key = ?,
+  retention_retain_until = ?,
+  retention_notes = ?,
+  updated_at = ?
+WHERE id = ?
+`;
+function bindValues(record, cipher) {
+    const r = memoryRecordToRow(record, cipher);
+    return [
+        r.id,
+        r.schema_version,
+        r.type,
+        r.scope_kind,
+        r.scope_coordinate,
+        r.body,
+        r.payload_json,
+        r.status,
+        r.sensitivity,
+        r.pinned,
+        r.confidence,
+        r.valid_from,
+        r.valid_until,
+        r.stale_reason,
+        r.tags_json,
+        r.source_kind,
+        r.source_conversation_id,
+        r.source_workflow_run_id,
+        r.source_evidence_manifest_id,
+        r.captured_at,
+        r.capture_rationale,
+        r.model_provider,
+        r.model_id,
+        r.model_revision,
+        r.retention_policy_key,
+        r.retention_retain_until,
+        r.retention_notes,
+        r.created_at,
+        r.updated_at,
+    ];
+}
+export function insertMemoryRow(db, record, cipher) {
+    db.prepare(INSERT_SQL).run(...bindValues(record, cipher));
+}
+export function getMemoryRow(db, id, cipher) {
+    const row = db.prepare(SELECT_BY_ID_SQL).get(id);
+    return row === undefined ? undefined : rowToMemoryRecord(row, cipher);
+}
+export function updateMemoryRow(db, record, cipher) {
+    const r = memoryRecordToRow(record, cipher);
+    const info = db
+        .prepare(UPDATE_SQL)
+        .run(r.type, r.body, r.payload_json, r.status, r.sensitivity, r.pinned, r.confidence, r.valid_from, r.valid_until, r.stale_reason, r.tags_json, r.source_kind, r.source_conversation_id, r.source_workflow_run_id, r.source_evidence_manifest_id, r.captured_at, r.capture_rationale, r.model_provider, r.model_id, r.model_revision, r.retention_policy_key, r.retention_retain_until, r.retention_notes, r.updated_at, r.id);
+    if (info.changes === 0) {
+        throw new MemoryStorageError("not-found", "Memory not found.");
+    }
+}
+export function deleteMemoryRow(db, id) {
+    const info = db.prepare(DELETE_SQL).run(id);
+    return info.changes > 0;
+}
+function buildEnumClause(column, values) {
+    if (values === undefined || values.length === 0)
+        return undefined;
+    const placeholders = values.map(() => "?").join(",");
+    return { clauses: [`${column} IN (${placeholders})`], params: values };
+}
+function buildExpiryClause(includeExpired, nowMs) {
+    if (includeExpired === true)
+        return undefined;
+    return { clauses: ["(valid_until IS NULL OR valid_until > ?)"], params: [nowMs] };
+}
+function buildPinnedClause(pinned) {
+    if (pinned === undefined)
+        return undefined;
+    return { clauses: ["pinned = ?"], params: [pinned ? 1 : 0] };
+}
+const ORDER_COLUMN_MAP = {
+    createdAt: "created_at",
+    updatedAt: "updated_at",
+    validFrom: "valid_from",
+};
+function resolveOrderBy(options) {
+    const column = ORDER_COLUMN_MAP[options.orderBy ?? "createdAt"];
+    const dir = options.orderDir === "asc" ? "ASC" : "DESC";
+    return { column, dir };
+}
+function buildListSql(where, options) {
+    const { column, dir } = resolveOrderBy(options);
+    let sql = "SELECT * FROM memories";
+    if (where.length > 0) {
+        sql += ` WHERE ${where.join(" AND ")}`;
+    }
+    sql += ` ORDER BY ${column} ${dir}`;
+    if (typeof options.limit === "number") {
+        sql += " LIMIT ?";
+        if (typeof options.offset === "number") {
+            sql += " OFFSET ?";
+        }
+    }
+    return sql;
+}
+function appendPagingParams(params, options) {
+    if (typeof options.limit !== "number")
+        return;
+    params.push(options.limit);
+    if (typeof options.offset === "number") {
+        params.push(options.offset);
+    }
+}
+export function listMemoriesRows(db, options, nowMs, cipher) {
+    const params = [];
+    const where = [];
+    for (const built of [
+        buildEnumClause("type", options.type),
+        buildEnumClause("status", options.status),
+        buildPinnedClause(options.pinned),
+        buildExpiryClause(options.includeExpired, nowMs),
+    ]) {
+        if (built === undefined)
+            continue;
+        where.push(...built.clauses);
+        params.push(...built.params);
+    }
+    appendPagingParams(params, options);
+    const rows = db
+        .prepare(buildListSql(where, options))
+        .all(...params);
+    return rows.map((row) => rowToMemoryRecord(row, cipher));
+}
+export function listMemoriesByScopeRows(db, scope, options, nowMs, cipher) {
+    const kind = scopeKindOf(scope);
+    const coordinate = scopeCoordinateOf(scope);
+    const params = [kind, coordinate];
+    const where = ["scope_kind = ?", "scope_coordinate = ?"];
+    for (const built of [
+        buildEnumClause("type", options.type),
+        buildEnumClause("status", options.status),
+        buildPinnedClause(options.pinned),
+        buildExpiryClause(options.includeExpired, nowMs),
+    ]) {
+        if (built === undefined)
+            continue;
+        where.push(...built.clauses);
+        params.push(...built.params);
+    }
+    appendPagingParams(params, options);
+    const rows = db
+        .prepare(buildListSql(where, options))
+        .all(...params);
+    return rows.map((row) => rowToMemoryRecord(row, cipher));
+}

package/dist/migrate-encrypt.d.ts

@@ -0,0 +1,4 @@
+import type { DatabaseSync } from "node:sqlite";
+import type { MemoryContentCipher } from "./cipher.js";
+export declare function encryptExistingContent(db: DatabaseSync, cipher: MemoryContentCipher): void;
+//# sourceMappingURL=migrate-encrypt.d.ts.map

package/dist/migrate-encrypt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate-encrypt.d.ts","sourceRoot":"","sources":["../src/migrate-encrypt.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAyEvD,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,YAAY,EAAE,MAAM,EAAE,mBAAmB,GAAG,IAAI,CAK1F"}

package/dist/migrate-encrypt.js

@@ -0,0 +1,69 @@
+// Eager v1→v2 encryption sweep (ADR-0035). v1 DBs stored content columns in plaintext; this sweep
+// re-encrypts every existing plaintext content value in place, inside the migration transaction, so
+// the upgrade is atomic. It is IDEMPOTENT: the user_version gate in runMigrations ensures this sweep
+// runs at most once (when user_version < ENCRYPTION_VERSION), so a half-migrated DB (interrupted
+// before COMMIT) re-runs cleanly because user_version stayed < 2. Each string column is sealed
+// unless it is already a genuine envelope (see isAlreadySealed: a try-open, NOT a "kv1." prefix
+// sniff — a plaintext value that merely starts with "kv1." must still be encrypted, not skipped).
+// That keeps the sweep idempotent for a genuinely sealed value without the prefix false-positive.
+// (table, column) pairs whose TEXT values are sealed as kv1 string envelopes.
+const STRING_TARGETS = [
+    { table: "memories", column: "body" },
+    { table: "memories", column: "payload_json" },
+    { table: "memories", column: "tags_json" },
+    { table: "memories", column: "capture_rationale" },
+    { table: "memories", column: "stale_reason" },
+    { table: "memory_edges", column: "provenance_summary" },
+    { table: "memory_tombstones", column: "reason" },
+];
+// A value is "already sealed" only if it actually AES-GCM-opens. The "kv1." prefix alone is
+// ambiguous — a legacy plaintext body can literally start with "kv1." (see KV1_PREFIX_BODY in the
+// tests); a prefix sniff would wrongly skip it, leave it as plaintext, and crash on the next read.
+// A genuine envelope opens cleanly; a "kv1."-prefixed plaintext throws. This keeps the sweep
+// idempotent (a genuinely sealed value — e.g. from an interrupted or mixed migration — is skipped
+// rather than double-sealed) without the prefix false-positive.
+function isAlreadySealed(cipher, value) {
+    if (!cipher.isSealed(value))
+        return false;
+    try {
+        cipher.openString(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function sweepStringColumn(db, table, column, cipher) {
+    // Identifiers come from the hard-coded STRING_TARGETS list, never from caller data, so the
+    // interpolation is not an injection surface (the same rule schema.ts relies on for PRAGMA).
+    const rows = db
+        .prepare(`SELECT rowid AS rowid, ${column} AS value FROM ${table}`)
+        .all();
+    const update = db.prepare(`UPDATE ${table} SET ${column} = ? WHERE rowid = ?`);
+    for (const row of rows) {
+        if (row.value === null || isAlreadySealed(cipher, row.value))
+            continue;
+        update.run(cipher.sealString(row.value), row.rowid);
+    }
+}
+// Unlike the string columns, the embedding BLOB has NO unambiguous "already sealed" marker: a
+// legacy plaintext Float32-LE vector can legitimately start with byte 0x01, so a magic-byte sniff
+// would wrongly skip it and leave plaintext that then fails to decrypt. Correctness instead rests on
+// the user_version gate in runMigrations: this sweep runs exactly once, in the same transaction that
+// sets user_version = 2, at which point EVERY embedding row is still v1 plaintext. So we seal all of
+// them unconditionally. An interrupted run rolls back (user_version stays < 2) and re-seals cleanly.
+function sweepEmbeddingVectors(db, cipher) {
+    const rows = db
+        .prepare("SELECT memory_id, vector FROM memory_embeddings")
+        .all();
+    const update = db.prepare("UPDATE memory_embeddings SET vector = ? WHERE memory_id = ?");
+    for (const row of rows) {
+        update.run(cipher.sealBytes(Buffer.from(row.vector)), row.memory_id);
+    }
+}
+export function encryptExistingContent(db, cipher) {
+    for (const target of STRING_TARGETS) {
+        sweepStringColumn(db, target.table, target.column, cipher);
+    }
+    sweepEmbeddingVectors(db, cipher);
+}

package/dist/paths.d.ts

@@ -0,0 +1,6 @@
+export declare const MEMORY_DB_FILENAME = "keiko-memory.db";
+export declare const MEMORY_DIR_NAME = "memory";
+export declare const DEFAULT_STATE_DIR = ".keiko";
+export declare function resolveMemoryDir(explicit: string | undefined, env: Readonly<Record<string, string | undefined>>): string;
+export declare function resolveMemoryDbPath(explicit: string | undefined, env: Readonly<Record<string, string | undefined>>): string;
+//# sourceMappingURL=paths.d.ts.map

package/dist/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAiBA,eAAO,MAAM,kBAAkB,oBAAoB,CAAC;AACpD,eAAO,MAAM,eAAe,WAAW,CAAC;AACxC,eAAO,MAAM,iBAAiB,WAAW,CAAC;AAsD1C,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,GAChD,MAAM,CAgBR;AAED,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,GAChD,MAAM,CAER"}

package/dist/paths.js

@@ -0,0 +1,82 @@
+// Path resolution for the local memory vault. The precedence ladder mirrors ADR-0013 D4 (UI DB):
+//   1. explicit `memoryDir` factory option
+//   2. $KEIKO_MEMORY_DIR
+//   3. $KEIKO_STATE_DIR/memory/                 (shared keiko local-state convention)
+//   4. homedir()/.keiko/memory/                  (fallback)
+//
+// Every configured path is forced to be absolute, outside the current working directory except for
+// the gitignored .keiko/ runtime root, not a symlink, and not under a symlinked ancestor. These
+// guards prevent a stray relative path from silently storing a customer's enterprise memory inside
+// their project tree (where it would be committed by accident) or being aimed at a symlink that
+// points back into a sensitive location.
+import { homedir } from "node:os";
+import { existsSync, lstatSync } from "node:fs";
+import { dirname, isAbsolute, join, normalize, parse, resolve, sep } from "node:path";
+import { MemoryStorageError } from "./errors.js";
+export const MEMORY_DB_FILENAME = "keiko-memory.db";
+export const MEMORY_DIR_NAME = "memory";
+export const DEFAULT_STATE_DIR = ".keiko";
+function invalidPath(message) {
+    return new MemoryStorageError("invalid-path", message);
+}
+function isInsideCwd(candidate) {
+    const cwd = resolve(process.cwd());
+    const r = resolve(candidate);
+    return r === cwd || r.startsWith(`${cwd}${sep}`);
+}
+function isInsideRuntimeStateRoot(candidate) {
+    const runtimeRoot = resolve(process.cwd(), DEFAULT_STATE_DIR);
+    const r = resolve(candidate);
+    return r === runtimeRoot || r.startsWith(`${runtimeRoot}${sep}`);
+}
+function hasSymlinkAncestor(path) {
+    let current = dirname(path);
+    const root = parse(current).root;
+    while (current !== root) {
+        if (existsSync(current)) {
+            return lstatSync(current).isSymbolicLink();
+        }
+        current = dirname(current);
+    }
+    return false;
+}
+function guard(path, label) {
+    // NUL bypass (CWE-22): path.normalize() leaves NUL bytes intact, so a string like
+    // "/safe/path\0/etc/passwd" satisfies the CWD-containment check but open(2) truncates
+    // at the NUL and lands on a completely different file. Reject NUL bytes first so the
+    // downstream guards reason about the same string the kernel will syscall on.
+    if (path.includes("\0")) {
+        throw invalidPath(`${label} must not contain NUL bytes.`);
+    }
+    if (!isAbsolute(path)) {
+        throw invalidPath(`${label} must be absolute.`);
+    }
+    const normalized = normalize(path);
+    if (isInsideCwd(normalized) && !isInsideRuntimeStateRoot(normalized)) {
+        throw invalidPath(`${label} must not be inside the current workspace.`);
+    }
+    if (existsSync(normalized) && lstatSync(normalized).isSymbolicLink()) {
+        throw invalidPath(`${label} must not be a symlink.`);
+    }
+    if (hasSymlinkAncestor(normalized)) {
+        throw invalidPath(`${label} must not be inside a symlinked directory.`);
+    }
+    return normalized;
+}
+export function resolveMemoryDir(explicit, env) {
+    if (explicit !== undefined && explicit.length > 0) {
+        return guard(explicit, "Memory vault directory");
+    }
+    const fromEnv = env.KEIKO_MEMORY_DIR;
+    if (fromEnv !== undefined && fromEnv.length > 0) {
+        return guard(fromEnv, "KEIKO_MEMORY_DIR");
+    }
+    const stateDir = env.KEIKO_STATE_DIR;
+    if (stateDir !== undefined && stateDir.length > 0) {
+        return guard(join(guard(stateDir, "KEIKO_STATE_DIR"), MEMORY_DIR_NAME), "KEIKO_STATE_DIR/memory");
+    }
+    return join(homedir(), DEFAULT_STATE_DIR, MEMORY_DIR_NAME);
+}
+export function resolveMemoryDbPath(explicit, env) {
+    return join(resolveMemoryDir(explicit, env), MEMORY_DB_FILENAME);
+}

package/dist/redact-record.d.ts

@@ -0,0 +1,8 @@
+import type { MemoryEdge, MemoryRecord } from "@oscharko-dev/keiko-contracts/memory";
+import type { MemoryTombstone } from "./types.js";
+type Redactor = (input: string) => string;
+export declare function redactMemoryRecord(record: MemoryRecord, redact: Redactor): MemoryRecord;
+export declare function redactMemoryEdge(edge: MemoryEdge, redact: Redactor): MemoryEdge;
+export declare function redactTombstone(t: MemoryTombstone, redact: Redactor): MemoryTombstone;
+export {};
+//# sourceMappingURL=redact-record.d.ts.map

package/dist/redact-record.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redact-record.d.ts","sourceRoot":"","sources":["../src/redact-record.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EACV,UAAU,EACV,YAAY,EAGb,MAAM,sCAAsC,CAAC;AAC9C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,KAAK,QAAQ,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;AA0B1C,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,QAAQ,GAAG,YAAY,CAoBvF;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,GAAG,UAAU,CAG/E;AAED,wBAAgB,eAAe,CAAC,CAAC,EAAE,eAAe,EAAE,MAAM,EAAE,QAAQ,GAAG,eAAe,CAGrF"}

package/dist/redact-record.js

@@ -0,0 +1,67 @@
+// Boundary redaction for memory records. Applies the caller-supplied redactString to every
+// free-text field that may carry secret-shaped content. Keys redacted:
+//   - body
+//   - tags[]
+//   - structured payload (string-list items / key-value entries)
+//   - provenance.captureRationale
+//   - staleReason
+//   - retentionHint.notes
+//   - edge.provenanceSummary
+//   - tombstone.reason
+//
+// This is defence-in-depth, NOT a substitute for the capture-policy gate in #207. The contract
+// validator runs FIRST (so we never persist a structurally bad record); redaction runs SECOND on
+// the validator-approved record so the only string transformation between contract-valid input
+// and SQL bind is this redact step.
+function redactPayload(payload, redact) {
+    switch (payload.kind) {
+        case "string-list":
+            return { kind: "string-list", items: payload.items.map(redact) };
+        case "key-value":
+            return {
+                kind: "key-value",
+                entries: payload.entries.map((e) => ({ key: e.key, value: redact(e.value) })),
+            };
+    }
+}
+function redactRetentionHint(hint, redact) {
+    const base = {
+        policyKey: hint.policyKey,
+    };
+    if (hint.retainUntil !== undefined)
+        base.retainUntil = hint.retainUntil;
+    if (hint.notes !== undefined)
+        base.notes = redact(hint.notes);
+    return base;
+}
+export function redactMemoryRecord(record, redact) {
+    const prov = record.provenance;
+    const newProvenance = {
+        ...prov,
+        ...(prov.captureRationale !== undefined
+            ? { captureRationale: redact(prov.captureRationale) }
+            : {}),
+    };
+    const out = {
+        ...record,
+        body: redact(record.body),
+        tags: record.tags.map(redact),
+        provenance: newProvenance,
+        ...(record.payload !== undefined ? { payload: redactPayload(record.payload, redact) } : {}),
+        ...(record.staleReason !== undefined ? { staleReason: redact(record.staleReason) } : {}),
+        ...(record.retentionHint !== undefined
+            ? { retentionHint: redactRetentionHint(record.retentionHint, redact) }
+            : {}),
+    };
+    return out;
+}
+export function redactMemoryEdge(edge, redact) {
+    if (edge.provenanceSummary === undefined)
+        return edge;
+    return { ...edge, provenanceSummary: redact(edge.provenanceSummary) };
+}
+export function redactTombstone(t, redact) {
+    if (t.reason === undefined)
+        return t;
+    return { ...t, reason: redact(t.reason) };
+}

package/dist/schema.d.ts

@@ -0,0 +1,5 @@
+import type { DatabaseSync } from "node:sqlite";
+import type { MemoryContentCipher } from "./cipher.js";
+export declare const MEMORY_VAULT_SCHEMA_VERSION = 6;
+export declare function runMigrations(db: DatabaseSync, cipher: MemoryContentCipher): void;
+//# sourceMappingURL=schema.d.ts.map

package/dist/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAoBvD,eAAO,MAAM,2BAA2B,IAAI,CAAC;AAmJ7C,wBAAgB,aAAa,CAAC,EAAE,EAAE,YAAY,EAAE,MAAM,EAAE,mBAAmB,GAAG,IAAI,CAmCjF"}