@oscharko-dev/keiko-memory-vault 0.2.0

package/dist/types.d.ts

@@ -0,0 +1,127 @@
+import type { MemoryEdge, MemoryEdgeId, MemoryId, MemoryRecord, MemoryReviewerId, MemoryScope, MemoryScopeKind, MemoryStatus, MemoryType } from "@oscharko-dev/keiko-contracts/memory";
+import type { MemoryContentCipher } from "./cipher.js";
+import type { MemoryAccessStat } from "./access.js";
+export type { MemoryAccessStat } from "./access.js";
+export type MemoryEmbeddingMetric = "cosine" | "euclidean" | "dot";
+export interface MemoryEmbeddingInput {
+    readonly provider: string;
+    readonly modelId: string;
+    readonly modelRevision?: string;
+    readonly metric: MemoryEmbeddingMetric;
+    readonly vector: Float32Array;
+}
+export interface MemoryEmbeddingRow {
+    readonly memoryId: MemoryId;
+    readonly provider: string;
+    readonly modelId: string;
+    readonly modelRevision?: string;
+    readonly dimensions: number;
+    readonly metric: MemoryEmbeddingMetric;
+    readonly vector: Float32Array;
+    readonly createdAt: number;
+}
+export interface MemoryTombstone {
+    readonly id: string;
+    readonly memoryId: MemoryId;
+    readonly scopeKind: MemoryScopeKind;
+    readonly scopeCoordinate: string;
+    readonly type: MemoryType;
+    readonly forgottenAt: number;
+    readonly forgetterSurface: string;
+    readonly reviewerId?: MemoryReviewerId;
+    readonly originalStatus?: MemoryStatus;
+    readonly reason?: string;
+}
+export type MemoryEvent = {
+    readonly kind: "memory:inserted";
+    readonly record: MemoryRecord;
+} | {
+    readonly kind: "memory:updated";
+    readonly record: MemoryRecord;
+} | {
+    readonly kind: "memory:deleted";
+    readonly memoryId: MemoryId;
+    readonly scope: MemoryScope;
+    readonly tombstoned: boolean;
+} | {
+    readonly kind: "memory:tombstoned";
+    readonly tombstone: MemoryTombstone;
+} | {
+    readonly kind: "edge:inserted";
+    readonly edge: MemoryEdge;
+} | {
+    readonly kind: "edge:deleted";
+    readonly edgeId: MemoryEdgeId;
+} | {
+    readonly kind: "embedding:upserted";
+    readonly memoryId: MemoryId;
+    readonly provider: string;
+    readonly modelId: string;
+};
+export type MemoryUpdatePatch = Partial<Omit<MemoryRecord, "id" | "schemaVersion" | "scope" | "createdAt">>;
+export interface MemoryBatchUpdate {
+    readonly id: MemoryId;
+    readonly patch: MemoryUpdatePatch;
+    readonly nowMs: number;
+}
+export interface MemoryBatchDelete {
+    readonly id: MemoryId;
+    readonly options: DeleteMemoryOptions;
+}
+export interface MemoryDeleteResult {
+    readonly memoryId: MemoryId;
+    readonly scope: MemoryScope;
+    readonly tombstone: MemoryTombstone | undefined;
+}
+export interface ListMemoriesOptions {
+    readonly type?: readonly MemoryType[];
+    readonly status?: readonly MemoryStatus[];
+    readonly pinned?: boolean;
+    readonly includeExpired?: boolean;
+    readonly limit?: number;
+    readonly offset?: number;
+    readonly orderBy?: "createdAt" | "updatedAt" | "validFrom";
+    readonly orderDir?: "asc" | "desc";
+    readonly nowMs?: number;
+}
+export interface DeleteMemoryOptions {
+    readonly tombstone: boolean;
+    readonly forgetterSurface: string;
+    readonly reviewerId?: MemoryReviewerId;
+    readonly reason?: string;
+    readonly nowMs: number;
+}
+export interface MemoryVaultStore {
+    readonly insertMemory: (record: MemoryRecord) => MemoryRecord;
+    readonly updateMemory: (id: MemoryId, patch: MemoryUpdatePatch, nowMs: number) => MemoryRecord;
+    readonly updateMemories: (updates: readonly MemoryBatchUpdate[]) => readonly MemoryRecord[];
+    readonly getMemory: (id: MemoryId) => MemoryRecord | undefined;
+    readonly deleteMemory: (id: MemoryId, options: DeleteMemoryOptions) => void;
+    readonly deleteMemories: (deletes: readonly MemoryBatchDelete[]) => readonly MemoryDeleteResult[];
+    readonly listMemories: (options?: ListMemoriesOptions) => readonly MemoryRecord[];
+    readonly listMemoriesByScope: (scope: MemoryScope, options?: ListMemoriesOptions) => readonly MemoryRecord[];
+    readonly insertEdge: (edge: MemoryEdge) => MemoryEdge;
+    readonly listOutgoingEdges: (memoryId: MemoryId) => readonly MemoryEdge[];
+    readonly listIncomingEdges: (memoryId: MemoryId) => readonly MemoryEdge[];
+    readonly deleteEdge: (edgeId: MemoryEdgeId) => void;
+    readonly upsertEmbedding: (memoryId: MemoryId, embedding: MemoryEmbeddingInput) => void;
+    readonly getEmbedding: (memoryId: MemoryId) => MemoryEmbeddingRow | undefined;
+    readonly getEmbeddings: (memoryIds: readonly MemoryId[]) => ReadonlyMap<MemoryId, MemoryEmbeddingRow>;
+    readonly listTombstonesByScope: (scope: MemoryScope) => readonly MemoryTombstone[];
+    readonly purgeTombstonesByScopeBefore: (scope: MemoryScope, forgottenBeforeMs: number) => number;
+    readonly recordAccess: (ids: readonly MemoryId[], nowMs: number) => void;
+    readonly recordOutcome: (ids: readonly MemoryId[], utility: number, nowMs: number) => void;
+    readonly getAccessStats: (ids?: readonly MemoryId[]) => ReadonlyMap<MemoryId, MemoryAccessStat>;
+    readonly close: () => void;
+}
+export interface MemoryVaultFactoryOptions {
+    readonly memoryDir?: string;
+    readonly env?: Readonly<Record<string, string | undefined>>;
+    readonly now?: () => number;
+    readonly newTombstoneId?: () => string;
+    readonly redactString?: (input: string) => string;
+    readonly onMemoryEvent?: (event: MemoryEvent) => void;
+    readonly cipher?: MemoryContentCipher;
+    readonly vaultKey?: Buffer;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,UAAU,EACV,YAAY,EACZ,QAAQ,EACR,YAAY,EACZ,gBAAgB,EAChB,WAAW,EACX,eAAe,EACf,YAAY,EACZ,UAAU,EACX,MAAM,sCAAsC,CAAC;AAC9C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD,YAAY,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD,MAAM,MAAM,qBAAqB,GAAG,QAAQ,GAAG,WAAW,GAAG,KAAK,CAAC;AAEnE,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;CAC/B;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;IACpC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,UAAU,CAAC,EAAE,gBAAgB,CAAC;IACvC,QAAQ,CAAC,cAAc,CAAC,EAAE,YAAY,CAAC;IACvC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAID,MAAM,MAAM,WAAW,GACnB;IAAE,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAA;CAAE,GACnE;IAAE,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAA;CAAE,GAClE;IACE,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;CAC9B,GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAA;CAAE,GAC3E;IAAE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;CAAE,GAC7D;IAAE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAA;CAAE,GAChE;IACE,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;IACpC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEN,MAAM,MAAM,iBAAiB,GAAG,OAAO,CACrC,IAAI,CAAC,YAAY,EAAE,IAAI,GAAG,eAAe,GAAG,OAAO,GAAG,WAAW,CAAC,CACnE,CAAC;AAEF,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAC;CACvC;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,eAAe,GAAG,SAAS,CAAC;CACjD;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;IACtC,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IAC1C,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,WAAW,GAAG,WAAW,GAAG,WAAW,CAAC;IAC3D,QAAQ,CAAC,QAAQ,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IAGnC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,UAAU,CAAC,EAAE,gBAAgB,CAAC;IACvC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,YAAY,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,YAAY,CAAC;IAC9D,QAAQ,CAAC,YAAY,EAAE,CAAC,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,iBAAiB,EAAE,KAAK,EAAE,MAAM,KAAK,YAAY,CAAC;IAC/F,QAAQ,CAAC,cAAc,EAAE,CAAC,OAAO,EAAE,SAAS,iBAAiB,EAAE,KAAK,SAAS,YAAY,EAAE,CAAC;IAC5F,QAAQ,CAAC,SAAS,EAAE,CAAC,EAAE,EAAE,QAAQ,KAAK,YAAY,GAAG,SAAS,CAAC;IAC/D,QAAQ,CAAC,YAAY,EAAE,CAAC,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,mBAAmB,KAAK,IAAI,CAAC;IAC5E,QAAQ,CAAC,cAAc,EAAE,CAAC,OAAO,EAAE,SAAS,iBAAiB,EAAE,KAAK,SAAS,kBAAkB,EAAE,CAAC;IAClG,QAAQ,CAAC,YAAY,EAAE,CAAC,OAAO,CAAC,EAAE,mBAAmB,KAAK,SAAS,YAAY,EAAE,CAAC;IAClF,QAAQ,CAAC,mBAAmB,EAAE,CAC5B,KAAK,EAAE,WAAW,EAClB,OAAO,CAAC,EAAE,mBAAmB,KAC1B,SAAS,YAAY,EAAE,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,UAAU,CAAC;IACtD,QAAQ,CAAC,iBAAiB,EAAE,CAAC,QAAQ,EAAE,QAAQ,KAAK,SAAS,UAAU,EAAE,CAAC;IAC1E,QAAQ,CAAC,iBAAiB,EAAE,CAAC,QAAQ,EAAE,QAAQ,KAAK,SAAS,UAAU,EAAE,CAAC;IAC1E,QAAQ,CAAC,UAAU,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,CAAC;IACpD,QAAQ,CAAC,eAAe,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,oBAAoB,KAAK,IAAI,CAAC;IACxF,QAAQ,CAAC,YAAY,EAAE,CAAC,QAAQ,EAAE,QAAQ,KAAK,kBAAkB,GAAG,SAAS,CAAC;IAC9E,QAAQ,CAAC,aAAa,EAAE,CACtB,SAAS,EAAE,SAAS,QAAQ,EAAE,KAC3B,WAAW,CAAC,QAAQ,EAAE,kBAAkB,CAAC,CAAC;IAC/C,QAAQ,CAAC,qBAAqB,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,SAAS,eAAe,EAAE,CAAC;IACnF,QAAQ,CAAC,4BAA4B,EAAE,CAAC,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,KAAK,MAAM,CAAC;IAIjG,QAAQ,CAAC,YAAY,EAAE,CAAC,GAAG,EAAE,SAAS,QAAQ,EAAE,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAMzE,QAAQ,CAAC,aAAa,EAAE,CAAC,GAAG,EAAE,SAAS,QAAQ,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3F,QAAQ,CAAC,cAAc,EAAE,CAAC,GAAG,CAAC,EAAE,SAAS,QAAQ,EAAE,KAAK,WAAW,CAAC,QAAQ,EAAE,gBAAgB,CAAC,CAAC;IAChG,QAAQ,CAAC,KAAK,EAAE,MAAM,IAAI,CAAC;CAC5B;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;IAC5D,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IAC5B,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,MAAM,CAAC;IACvC,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;IAClD,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC;IAItD,QAAQ,CAAC,MAAM,CAAC,EAAE,mBAAmB,CAAC;IACtC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B"}

package/dist/types.js

@@ -0,0 +1,4 @@
+// Public port + supporting types for the memory vault. Package-local types (tombstone, embedding
+// I/O, event union) live here so downstream packages compose them through the barrel without
+// having to know the SQLite encoding.
+export {};

package/dist/validate.d.ts

@@ -0,0 +1,8 @@
+import type { MemoryEdge, MemoryRecord, MemoryScope } from "@oscharko-dev/keiko-contracts/memory";
+import type { DeleteMemoryOptions, MemoryEmbeddingInput } from "./types.js";
+export declare function gateMemoryRecord(record: MemoryRecord): MemoryRecord;
+export declare function gateMemoryEdge(edge: MemoryEdge): MemoryEdge;
+export declare function gateMemoryScope(scope: MemoryScope): MemoryScope;
+export declare function gateEmbeddingInput(input: MemoryEmbeddingInput): MemoryEmbeddingInput;
+export declare function gateDeleteOptions(options: DeleteMemoryOptions): DeleteMemoryOptions;
+//# sourceMappingURL=validate.d.ts.map

package/dist/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,sCAAsC,CAAC;AAGlG,OAAO,KAAK,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAM5E,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,YAAY,GAAG,YAAY,CAMnE;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,CAM3D;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,WAAW,GAAG,WAAW,CAQ/D;AAkBD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,oBAAoB,GAAG,oBAAoB,CAMpF;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,mBAAmB,GAAG,mBAAmB,CAenF"}

package/dist/validate.js

@@ -0,0 +1,71 @@
+// Validator-gate helpers. Wraps the contract validators from @oscharko-dev/keiko-contracts/memory
+// in throw-on-failure form so the vault factory stays imperative. The structured failure list is
+// preserved on the thrown MemoryStorageValidationError so the caller can branch on `.failures`.
+import { validateMemoryEdge, validateMemoryRecord, validateMemoryScope, } from "@oscharko-dev/keiko-contracts/memory";
+import { MemoryStorageValidationError } from "./errors.js";
+import { ALLOWED_EMBEDDING_METRICS, MAX_EMBEDDING_DIMENSIONS } from "./embeddings.js";
+function toFailures(errors) {
+    return errors.map((message) => ({ path: [], message }));
+}
+export function gateMemoryRecord(record) {
+    const result = validateMemoryRecord(record);
+    if (!result.ok) {
+        throw new MemoryStorageValidationError("Invalid memory record.", toFailures(result.errors));
+    }
+    return result.value;
+}
+export function gateMemoryEdge(edge) {
+    const result = validateMemoryEdge(edge);
+    if (!result.ok) {
+        throw new MemoryStorageValidationError("Invalid memory edge.", toFailures(result.errors));
+    }
+    return result.value;
+}
+export function gateMemoryScope(scope) {
+    const result = validateMemoryScope(scope);
+    if (!result.ok) {
+        throw new MemoryStorageValidationError("Invalid memory scope.", toFailures(result.errors));
+    }
+    // validateMemoryScope's signature returns `MemoryValidation<undefined>` — it asserts shape but
+    // does not narrow. The input has the type we promised so we return it directly.
+    return scope;
+}
+function collectEmbeddingErrors(input) {
+    const errors = [];
+    if (input.provider.length === 0)
+        errors.push("embedding.provider must be non-empty");
+    if (input.modelId.length === 0)
+        errors.push("embedding.modelId must be non-empty");
+    if (input.vector.length === 0)
+        errors.push("embedding.vector must have at least one dimension");
+    if (input.vector.length > MAX_EMBEDDING_DIMENSIONS) {
+        errors.push(`embedding.vector length ${String(input.vector.length)} exceeds maximum ${String(MAX_EMBEDDING_DIMENSIONS)}`);
+    }
+    if (!ALLOWED_EMBEDDING_METRICS.includes(input.metric)) {
+        errors.push(`embedding.metric must be one of ${ALLOWED_EMBEDDING_METRICS.join("|")}`);
+    }
+    return errors;
+}
+export function gateEmbeddingInput(input) {
+    const errors = collectEmbeddingErrors(input);
+    if (errors.length > 0) {
+        throw new MemoryStorageValidationError("Invalid embedding input.", toFailures(errors));
+    }
+    return input;
+}
+export function gateDeleteOptions(options) {
+    const errors = [];
+    if (options.forgetterSurface.length === 0) {
+        errors.push("deleteOptions.forgetterSurface must be non-empty");
+    }
+    if (options.reviewerId?.length === 0) {
+        errors.push("deleteOptions.reviewerId must be non-empty when provided");
+    }
+    if (!Number.isFinite(options.nowMs) || options.nowMs < 0) {
+        errors.push("deleteOptions.nowMs must be a finite non-negative number");
+    }
+    if (errors.length > 0) {
+        throw new MemoryStorageValidationError("Invalid delete options.", toFailures(errors));
+    }
+    return options;
+}

package/dist/vault.d.ts

@@ -0,0 +1,3 @@
+import type { MemoryVaultFactoryOptions, MemoryVaultStore } from "./types.js";
+export declare function createMemoryVault(options?: MemoryVaultFactoryOptions): MemoryVaultStore;
+//# sourceMappingURL=vault.d.ts.map

package/dist/vault.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vault.d.ts","sourceRoot":"","sources":["../src/vault.ts"],"names":[],"mappings":"AA4DA,OAAO,KAAK,EAWV,yBAAyB,EACzB,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAgYpB,wBAAgB,iBAAiB,CAAC,OAAO,CAAC,EAAE,yBAAyB,GAAG,gBAAgB,CAMvF"}

package/dist/vault.js

@@ -0,0 +1,301 @@
+// createMemoryVault — the integration layer. Composes path resolution, DB lifecycle, validator
+// gate, boundary redaction, prepared-SQL adapters, and the optional onMemoryEvent callback into
+// a single MemoryVaultStore port. Every public method follows the same order:
+//
+//   1. validate (throws MemoryStorageValidationError before any SQL touches)
+//   2. redact at the boundary (applies the factory redactString to free-text fields)
+//   3. execute the prepared SQL (transactional when the method writes more than one row)
+//   4. fire onMemoryEvent (AFTER commit, never on rollback)
+//
+// Steps 1-3 are pure-functional in TS-space until the SQL prepare() runs, so a thrown validator
+// or redact exception leaves the database untouched. Step 4 sees only the post-commit truth.
+import { DatabaseSync } from "node:sqlite";
+import { randomUUID } from "node:crypto";
+import { openMemoryDatabase } from "./db.js";
+import { resolveMemoryDir, resolveMemoryDbPath } from "./paths.js";
+import { createMemoryContentCipher, resolveVaultKey } from "./cipher.js";
+import { scopeCoordinateOf, scopeKindOf } from "./scope-key.js";
+import { deleteMemoryRow, getMemoryRow, insertMemoryRow, listMemoriesRows, listMemoriesByScopeRows, updateMemoryRow, } from "./memories.js";
+import { deleteEdgeRow, insertEdgeRow, listIncomingEdgeRows, listOutgoingEdgeRows, } from "./edges.js";
+import { getEmbeddingRow, getEmbeddingRows, upsertEmbeddingRow } from "./embeddings.js";
+import { getAccessStatsRows, recordAccessRows, recordOutcomeRows, } from "./access.js";
+import { deleteTombstonesByScopeBeforeRows, insertTombstoneRow, listTombstonesByScopeRows, } from "./tombstones.js";
+import { gateDeleteOptions, gateEmbeddingInput, gateMemoryEdge, gateMemoryRecord, gateMemoryScope, } from "./validate.js";
+import { redactMemoryEdge, redactMemoryRecord, redactTombstone } from "./redact-record.js";
+import { MemoryStorageError } from "./errors.js";
+const IDENTITY = (s) => s;
+const NOOP_EMIT = () => undefined;
+// Single named entry point for the default environment read so the literal `process.env`
+// reference does not appear inline in business logic (audit AC19).
+function defaultEnv() {
+    return process.env;
+}
+function resolveOptions(opts, cipher) {
+    return {
+        now: opts?.now ?? (() => Date.now()),
+        newTombstoneId: opts?.newTombstoneId ?? (() => randomUUID()),
+        redactString: opts?.redactString ?? IDENTITY,
+        emit: opts?.onMemoryEvent ?? NOOP_EMIT,
+        cipher,
+    };
+}
+// Resolve the content cipher. Precedence: an explicitly injected cipher (tests), then an injected
+// raw key (tests/CI), then the real tiered resolver (KEIKO_MEMORY_KEY > keychain > keyfile). The
+// public factory never requires any of these — production callers get the tiered resolver.
+function resolveCipher(opts, env) {
+    if (opts?.cipher !== undefined)
+        return opts.cipher;
+    if (opts?.vaultKey !== undefined)
+        return createMemoryContentCipher(opts.vaultKey);
+    const memoryDir = resolveMemoryDir(opts?.memoryDir, env);
+    return createMemoryContentCipher(resolveVaultKey(env, memoryDir).key);
+}
+// Validate-then-redact for inserts. The validator runs on the CALLER-SUPPLIED record so a
+// validation failure carries the caller's exact failure list. Redaction runs SECOND so the SQL
+// row is the redacted form — a secret-shaped string that slipped past the capture-layer gate
+// in #207 is scrubbed before persistence.
+function preparedForWrite(record, opts) {
+    const validated = gateMemoryRecord(record);
+    return redactMemoryRecord(validated, opts.redactString);
+}
+function preparedEdgeForWrite(edge, opts) {
+    const validated = gateMemoryEdge(edge);
+    return redactMemoryEdge(validated, opts.redactString);
+}
+function mergePatch(existing, patch, nowMs) {
+    // updatedAt is owned by the vault, not the patch, so the caller cannot regress it. createdAt
+    // and the scope coordinate are immutable on update (scope changes require supersession +
+    // re-insert by design — moving a record across scopes is an audit event, not a field write).
+    const next = {
+        ...existing,
+        ...patch,
+        id: existing.id,
+        schemaVersion: existing.schemaVersion,
+        scope: existing.scope,
+        createdAt: existing.createdAt,
+        updatedAt: nowMs,
+    };
+    return next;
+}
+function existingMemoryOrThrow(db, id, cipher) {
+    const existing = getMemoryRow(db, id, cipher);
+    if (existing === undefined) {
+        throw new MemoryStorageError("not-found", "Memory not found.");
+    }
+    return existing;
+}
+function buildTombstone(record, options, opts) {
+    const base = {
+        id: opts.newTombstoneId(),
+        memoryId: record.id,
+        scopeKind: scopeKindOf(record.scope),
+        scopeCoordinate: scopeCoordinateOf(record.scope),
+        type: record.type,
+        forgottenAt: options.nowMs,
+        forgetterSurface: options.forgetterSurface,
+        originalStatus: record.status,
+    };
+    return {
+        ...base,
+        ...(options.reviewerId === undefined ? {} : { reviewerId: options.reviewerId }),
+        ...(options.reason === undefined ? {} : { reason: options.reason }),
+    };
+}
+function prepareDelete(db, id, options, opts) {
+    gateDeleteOptions(options);
+    const existing = existingMemoryOrThrow(db, id, opts.cipher);
+    const tombstone = options.tombstone
+        ? redactTombstone(buildTombstone(existing, options, opts), opts.redactString)
+        : undefined;
+    return { memoryId: id, scope: existing.scope, tombstone };
+}
+function applyPreparedDelete(db, result, opts) {
+    if (!deleteMemoryRow(db, result.memoryId)) {
+        throw new MemoryStorageError("not-found", "Memory not found.");
+    }
+    if (result.tombstone !== undefined) {
+        insertTombstoneRow(db, result.tombstone, opts.cipher);
+    }
+}
+function runDelete(db, id, options, opts) {
+    const ready = prepareDelete(db, id, options, opts);
+    db.exec("BEGIN");
+    try {
+        applyPreparedDelete(db, ready, opts);
+        db.exec("COMMIT");
+    }
+    catch (error) {
+        db.exec("ROLLBACK");
+        throw error;
+    }
+    return ready;
+}
+function runBatchDeleteMemories(db, deletes, opts) {
+    const ready = deletes.map((entry) => prepareDelete(db, entry.id, entry.options, opts));
+    db.exec("BEGIN");
+    try {
+        for (const result of ready) {
+            applyPreparedDelete(db, result, opts);
+        }
+        db.exec("COMMIT");
+    }
+    catch (error) {
+        db.exec("ROLLBACK");
+        throw error;
+    }
+    return ready;
+}
+function updateMemoryInPlace(db, update, opts) {
+    const existing = existingMemoryOrThrow(db, update.id, opts.cipher);
+    const merged = mergePatch(existing, update.patch, update.nowMs);
+    const ready = preparedForWrite(merged, opts);
+    updateMemoryRow(db, ready, opts.cipher);
+    return ready;
+}
+function runBatchUpdateMemories(db, updates, opts) {
+    const ready = [];
+    db.exec("BEGIN");
+    try {
+        for (const update of updates) {
+            ready.push(updateMemoryInPlace(db, update, opts));
+        }
+        db.exec("COMMIT");
+    }
+    catch (error) {
+        db.exec("ROLLBACK");
+        throw error;
+    }
+    return ready;
+}
+function emitUpdatedRecords(records, opts) {
+    for (const record of records) {
+        opts.emit({ kind: "memory:updated", record });
+    }
+}
+function emitDeletedRecords(results, opts) {
+    for (const result of results) {
+        opts.emit({
+            kind: "memory:deleted",
+            memoryId: result.memoryId,
+            scope: result.scope,
+            tombstoned: result.tombstone !== undefined,
+        });
+        if (result.tombstone !== undefined) {
+            opts.emit({ kind: "memory:tombstoned", tombstone: result.tombstone });
+        }
+    }
+}
+function deleteMemoryWithEvents(db, id, options, opts) {
+    const result = runDelete(db, id, options, opts);
+    emitDeletedRecords([result], opts);
+}
+function buildMemoryMutators(db, opts) {
+    return {
+        insertMemory: (record) => {
+            const ready = preparedForWrite(record, opts);
+            insertMemoryRow(db, ready, opts.cipher);
+            opts.emit({ kind: "memory:inserted", record: ready });
+            return ready;
+        },
+        updateMemory: (id, patch, nowMs) => {
+            const ready = updateMemoryInPlace(db, { id, patch, nowMs }, opts);
+            opts.emit({ kind: "memory:updated", record: ready });
+            return ready;
+        },
+        updateMemories: (updates) => {
+            const ready = runBatchUpdateMemories(db, updates, opts);
+            emitUpdatedRecords(ready, opts);
+            return ready;
+        },
+        deleteMemory: (id, options) => {
+            deleteMemoryWithEvents(db, id, options, opts);
+        },
+        deleteMemories: (deletes) => {
+            const ready = runBatchDeleteMemories(db, deletes, opts);
+            emitDeletedRecords(ready, opts);
+            return ready;
+        },
+        getMemory: (id) => getMemoryRow(db, id, opts.cipher),
+        listMemories: (options) => {
+            const effective = options ?? {};
+            const nowMs = effective.nowMs ?? opts.now();
+            return listMemoriesRows(db, effective, nowMs, opts.cipher);
+        },
+        listMemoriesByScope: (scope, options) => {
+            gateMemoryScope(scope);
+            const effective = options ?? {};
+            const nowMs = effective.nowMs ?? opts.now();
+            return listMemoriesByScopeRows(db, scope, effective, nowMs, opts.cipher);
+        },
+    };
+}
+function buildEdgeAndEmbeddingOps(db, opts) {
+    return {
+        insertEdge: (edge) => {
+            const ready = preparedEdgeForWrite(edge, opts);
+            insertEdgeRow(db, ready, opts.cipher);
+            opts.emit({ kind: "edge:inserted", edge: ready });
+            return ready;
+        },
+        listOutgoingEdges: (memoryId) => listOutgoingEdgeRows(db, memoryId, opts.cipher),
+        listIncomingEdges: (memoryId) => listIncomingEdgeRows(db, memoryId, opts.cipher),
+        deleteEdge: (edgeId) => {
+            const removed = deleteEdgeRow(db, edgeId);
+            if (!removed) {
+                throw new MemoryStorageError("not-found", "Edge not found.");
+            }
+            opts.emit({ kind: "edge:deleted", edgeId });
+        },
+        upsertEmbedding: (memoryId, embedding) => {
+            gateEmbeddingInput(embedding);
+            if (getMemoryRow(db, memoryId, opts.cipher) === undefined) {
+                throw new MemoryStorageError("not-found", "Memory not found.");
+            }
+            upsertEmbeddingRow(db, memoryId, embedding, opts.now(), opts.cipher);
+            opts.emit({
+                kind: "embedding:upserted",
+                memoryId,
+                provider: embedding.provider,
+                modelId: embedding.modelId,
+            });
+        },
+        getEmbedding: (memoryId) => getEmbeddingRow(db, memoryId, opts.cipher),
+        getEmbeddings: (memoryIds) => getEmbeddingRows(db, memoryIds, opts.cipher),
+    };
+}
+function buildTombstoneAndAccessOps(db, opts) {
+    return {
+        listTombstonesByScope: (scope) => {
+            gateMemoryScope(scope);
+            return listTombstonesByScopeRows(db, scope, opts.cipher);
+        },
+        purgeTombstonesByScopeBefore: (scope, forgottenBeforeMs) => {
+            gateMemoryScope(scope);
+            return deleteTombstonesByScopeBeforeRows(db, scope, forgottenBeforeMs);
+        },
+        recordAccess: (ids, nowMs) => {
+            recordAccessRows(db, ids, nowMs);
+        },
+        recordOutcome: (ids, utility, nowMs) => {
+            recordOutcomeRows(db, ids, utility, nowMs);
+        },
+        getAccessStats: (ids) => getAccessStatsRows(db, ids),
+    };
+}
+function buildStore(db, opts) {
+    return {
+        ...buildMemoryMutators(db, opts),
+        ...buildEdgeAndEmbeddingOps(db, opts),
+        ...buildTombstoneAndAccessOps(db, opts),
+        close: () => {
+            db.close();
+        },
+    };
+}
+export function createMemoryVault(options) {
+    const env = options?.env ?? defaultEnv();
+    const dbPath = resolveMemoryDbPath(options?.memoryDir, env);
+    const cipher = resolveCipher(options, env);
+    const db = openMemoryDatabase(dbPath, cipher);
+    return buildStore(db, resolveOptions(options, cipher));
+}

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+export declare const KEIKO_MEMORY_VAULT_VERSION: "0.1.0";
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,0BAA0B,EAAG,OAAgB,CAAC"}

package/dist/version.js

@@ -0,0 +1 @@
+export const KEIKO_MEMORY_VAULT_VERSION = "0.1.0";

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@oscharko-dev/keiko-memory-vault",
+  "version": "0.2.0",
+  "type": "module",
+  "license": "Apache-2.0",
+  "description": "MemoriaViva — Internal memory-vault package: governed enterprise memory storage (node:sqlite). Scope-isolated CRUD, edges, embeddings, tombstones, validator-gated boundary, redaction-aware writes (ADR-0019 + Epic #204). Not published independently.",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -b tsconfig.json",
+    "typecheck": "tsc -b tsconfig.json",
+    "test": "vitest run"
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@oscharko-dev/keiko-contracts": "0.2.0",
+    "@oscharko-dev/keiko-security": "0.2.0"
+  }
+}