@oscharko-dev/keiko-memory-vault 0.2.0

package/dist/schema.js

@@ -0,0 +1,206 @@
+// Memory vault schema V1. Forward-only migration runner keyed off PRAGMA user_version, applied
+// inside a single transaction so a partial failure leaves user_version unchanged. STRICT tables
+// pin the column types at runtime so SQLite cannot silently coerce a wrong-shape insert.
+//
+// Index strategy:
+//   - (scope_kind, scope_coordinate)               for the canonical scoped list (#206 AC)
+//   - (scope_kind, scope_coordinate, created_at)   for bounded retrieval scans (#210)
+//   - (scope_kind, scope_coordinate, type|status) for the common filter combinations
+//   - pinned partial index                         for "list pinned in scope X"
+//   - valid_until                                  for the consolidation sweep (#208)
+//   - updated_at                                   for the "recently changed" surface
+//   - edges from/to and created_at                 for graph traversal (#210)
+//   - tombstones scope                             for the forgetting audit surface (#214)
+//
+// `provenance_*` columns are denormalised onto `memories` so a single SELECT can answer
+// "give me this memory plus its capture lineage" without joining a sidecar table. The structural
+// payload is JSON-encoded into `payload_json` because storing it as a normalised table would
+// require a schema change every time a payload kind landed (#205 ships only two kinds today).
+import { encryptExistingContent } from "./migrate-encrypt.js";
+// v2 = encryption-at-rest (ADR-0035). v1 stored content columns in plaintext; v2 seals them via an
+// eager code sweep (no column changes). The bump is one-way: a v2 DB is unreadable by v1 code.
+// v3 = access tracking (#204). Adds the `memory_access` counter table that feeds the decay /
+// reinforcement maintenance cycle. The table holds ONLY counters + timestamps (no memory
+// content), so it stays CLEARTEXT — the cipher is never applied to it.
+// v4 = tombstone provenance hardening (#209). Adds reviewer_id and original_status to deletion
+// tombstones so audit consumers can distinguish who initiated deletion and what lifecycle state
+// was removed without storing memory body content.
+// v5 = retrieval-path performance indexes (#210). Adds additive composite indexes matching the
+// scoped retrieval ORDER BY and per-memory edge ORDER BY shapes; no data rewrite.
+// v6 = outcome-driven forgetting (#204, O-V1). Adds two counters to memory_access — outcome_count
+// and utility_sum — recording governed retention OUTCOMES (a proposal accepted/rejected, a conflict
+// won/lost, an accepted correction superseding its origin). The maintenance strength model folds
+// their mean into a utility factor so proven-useful memories resist disuse-forgetting and proven-bad
+// ones fade sooner. Counters only (no content) => the table stays CLEARTEXT. Additive: the columns
+// default 0, which yields a neutral factor of 1, so the strength model is byte-identical until a
+// real outcome lands.
+export const MEMORY_VAULT_SCHEMA_VERSION = 6;
+const ENCRYPTION_VERSION = 2;
+const V1_SQL = `
+CREATE TABLE memories (
+  id TEXT NOT NULL PRIMARY KEY,
+  schema_version TEXT NOT NULL,
+  type TEXT NOT NULL,
+  scope_kind TEXT NOT NULL,
+  scope_coordinate TEXT NOT NULL,
+  body TEXT NOT NULL,
+  payload_json TEXT,
+  status TEXT NOT NULL,
+  sensitivity TEXT NOT NULL,
+  pinned INTEGER NOT NULL DEFAULT 0,
+  confidence REAL NOT NULL,
+  valid_from INTEGER NOT NULL,
+  valid_until INTEGER,
+  stale_reason TEXT,
+  tags_json TEXT NOT NULL,
+  source_kind TEXT NOT NULL,
+  source_conversation_id TEXT,
+  source_workflow_run_id TEXT,
+  source_evidence_manifest_id TEXT,
+  captured_at INTEGER NOT NULL,
+  capture_rationale TEXT,
+  model_provider TEXT,
+  model_id TEXT,
+  model_revision TEXT,
+  retention_policy_key TEXT,
+  retention_retain_until INTEGER,
+  retention_notes TEXT,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL
+) STRICT;
+
+CREATE INDEX idx_memories_scope ON memories(scope_kind, scope_coordinate);
+CREATE INDEX idx_memories_scope_created ON memories(scope_kind, scope_coordinate, created_at DESC);
+CREATE INDEX idx_memories_scope_type ON memories(scope_kind, scope_coordinate, type);
+CREATE INDEX idx_memories_scope_status ON memories(scope_kind, scope_coordinate, status);
+CREATE INDEX idx_memories_pinned ON memories(scope_kind, scope_coordinate) WHERE pinned = 1;
+CREATE INDEX idx_memories_valid_until ON memories(valid_until);
+CREATE INDEX idx_memories_updated_at ON memories(updated_at);
+
+CREATE TABLE memory_edges (
+  id TEXT NOT NULL PRIMARY KEY,
+  schema_version TEXT NOT NULL,
+  from_memory_id TEXT NOT NULL REFERENCES memories(id) ON DELETE CASCADE,
+  to_memory_id TEXT NOT NULL REFERENCES memories(id) ON DELETE CASCADE,
+  kind TEXT NOT NULL,
+  created_at INTEGER NOT NULL,
+  confidence REAL,
+  provenance_summary TEXT
+) STRICT;
+
+CREATE INDEX idx_edges_from ON memory_edges(from_memory_id, kind);
+CREATE INDEX idx_edges_to ON memory_edges(to_memory_id, kind);
+CREATE INDEX idx_edges_from_created ON memory_edges(from_memory_id, created_at ASC);
+CREATE INDEX idx_edges_to_created ON memory_edges(to_memory_id, created_at ASC);
+
+CREATE TABLE memory_embeddings (
+  memory_id TEXT NOT NULL PRIMARY KEY REFERENCES memories(id) ON DELETE CASCADE,
+  provider TEXT NOT NULL,
+  model_id TEXT NOT NULL,
+  model_revision TEXT,
+  vector_dimensions INTEGER NOT NULL,
+  vector_metric TEXT NOT NULL,
+  vector BLOB NOT NULL,
+  created_at INTEGER NOT NULL
+) STRICT;
+
+CREATE TABLE memory_tombstones (
+  id TEXT NOT NULL PRIMARY KEY,
+  memory_id TEXT NOT NULL,
+  scope_kind TEXT NOT NULL,
+  scope_coordinate TEXT NOT NULL,
+  type TEXT NOT NULL,
+  forgotten_at INTEGER NOT NULL,
+  forgetter_surface TEXT NOT NULL,
+  reason TEXT
+) STRICT;
+
+CREATE INDEX idx_tombstones_scope ON memory_tombstones(scope_kind, scope_coordinate);
+CREATE INDEX idx_tombstones_memory_id ON memory_tombstones(memory_id);
+`;
+// v3 access-tracking table. STRICT pins the column types; ON DELETE CASCADE removes the access
+// row when its memory is hard-deleted (FK enforcement is enabled via PRAGMA foreign_keys = ON in
+// db.ts). No content column => no cipher. The index on last_accessed_at supports a future
+// "least-recently-touched" sweep without scanning the whole table.
+const V3_SQL = `
+CREATE TABLE memory_access (
+  memory_id TEXT NOT NULL PRIMARY KEY REFERENCES memories(id) ON DELETE CASCADE,
+  last_accessed_at INTEGER NOT NULL,
+  access_count INTEGER NOT NULL DEFAULT 0
+) STRICT;
+
+CREATE INDEX idx_memory_access_last ON memory_access(last_accessed_at);
+`;
+const V4_SQL = `
+ALTER TABLE memory_tombstones ADD COLUMN reviewer_id TEXT;
+ALTER TABLE memory_tombstones ADD COLUMN original_status TEXT;
+`;
+const V5_SQL = `
+CREATE INDEX IF NOT EXISTS idx_memories_scope_created
+  ON memories(scope_kind, scope_coordinate, created_at DESC);
+CREATE INDEX IF NOT EXISTS idx_edges_from_created
+  ON memory_edges(from_memory_id, created_at ASC);
+CREATE INDEX IF NOT EXISTS idx_edges_to_created
+  ON memory_edges(to_memory_id, created_at ASC);
+`;
+// v6 outcome counters on the existing access table (#204, O-V1). STRICT-compatible ALTERs with a
+// constant DEFAULT, so the rewrite is metadata-only and every pre-existing row reads 0/0 (neutral
+// utility factor). No content column => the table stays CLEARTEXT, like the rest of memory_access.
+const V6_SQL = `
+ALTER TABLE memory_access ADD COLUMN outcome_count INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE memory_access ADD COLUMN utility_sum REAL NOT NULL DEFAULT 0;
+`;
+const MIGRATIONS = [
+    { version: 1, sql: V1_SQL },
+    { version: 3, sql: V3_SQL },
+    { version: 4, sql: V4_SQL },
+    { version: 5, sql: V5_SQL },
+    { version: 6, sql: V6_SQL },
+];
+function currentUserVersion(db) {
+    const row = db.prepare("PRAGMA user_version").get();
+    return typeof row?.user_version === "number" ? row.user_version : 0;
+}
+function setUserVersion(db, v) {
+    // user_version cannot be parameter-bound. `v` is a hard-coded integer from MIGRATIONS, never
+    // caller-supplied, so string interpolation here is not an injection surface.
+    db.exec(`PRAGMA user_version = ${String(v)}`);
+}
+export function runMigrations(db, cipher) {
+    const start = currentUserVersion(db);
+    const pendingDdl = MIGRATIONS.filter((m) => m.version > start);
+    const needsEncryption = start < ENCRYPTION_VERSION;
+    if (pendingDdl.length === 0 && !needsEncryption)
+        return;
+    // An EXISTING (already-created) DB crossing into the encryption version had plaintext on disk;
+    // its superseded pages must be purged from the WAL so the plaintext does not linger after upgrade.
+    const upgradedExistingDb = start > 0 && needsEncryption;
+    db.exec("BEGIN");
+    try {
+        for (const m of pendingDdl) {
+            db.exec(m.sql);
+            setUserVersion(db, m.version);
+        }
+        if (needsEncryption) {
+            // Idempotent: skips values already sealed, so a fresh DB (no rows) and a re-run are no-ops.
+            // The encryption sweep is keyed to ENCRYPTION_VERSION (2) but is NOT a user_version write:
+            // post-v2 migrations (v3+) own the version. Setting the version is deferred to the line below
+            // so encryption never regresses a DB that already applied a later DDL migration.
+            encryptExistingContent(db, cipher);
+        }
+        // Pin the final version to the current schema head once every pending DDL and the encryption
+        // sweep have run. A fresh DB applies v1 + later DDL and the encryption sweep, then lands on
+        // the current schema head; older encrypted DBs apply only the later DDL they missed.
+        setUserVersion(db, MEMORY_VAULT_SCHEMA_VERSION);
+        db.exec("COMMIT");
+    }
+    catch (error) {
+        db.exec("ROLLBACK");
+        throw error;
+    }
+    if (upgradedExistingDb) {
+        // Outside the transaction (checkpoint cannot run inside one): truncate the WAL so pages that
+        // held the now-re-encrypted plaintext are reclaimed immediately, not at the next close.
+        db.exec("PRAGMA wal_checkpoint(TRUNCATE)");
+    }
+}

package/dist/scope-key.d.ts

@@ -0,0 +1,4 @@
+import type { MemoryScope, MemoryScopeKind } from "@oscharko-dev/keiko-contracts/memory";
+export declare function scopeKindOf(scope: MemoryScope): MemoryScopeKind;
+export declare function scopeCoordinateOf(scope: MemoryScope): string;
+//# sourceMappingURL=scope-key.d.ts.map

package/dist/scope-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-key.d.ts","sourceRoot":"","sources":["../src/scope-key.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,sCAAsC,CAAC;AAEzF,wBAAgB,WAAW,CAAC,KAAK,EAAE,WAAW,GAAG,eAAe,CAE/D;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAe5D"}

package/dist/scope-key.js

@@ -0,0 +1,27 @@
+// Canonical scope coordinate for storage. The `(scope_kind, scope_coordinate)` column pair is the
+// SOLE identity surface a scoped query keys on, so the encoding MUST be:
+//   - deterministic (same scope -> same string, bit-for-bit)
+//   - kind-disjoint at the row level (kind is its own column; coordinate is only the id)
+//
+// We deliberately do NOT serialise `kind:id` into one column. Kind is already stored separately;
+// concatenating would make two records at different kinds but matching coordinates structurally
+// equal if a caller ever forgot the kind filter. The factory enforces both filters together.
+export function scopeKindOf(scope) {
+    return scope.kind;
+}
+export function scopeCoordinateOf(scope) {
+    switch (scope.kind) {
+        case "user":
+            return scope.userId;
+        case "workspace":
+            return scope.workspaceId;
+        case "project":
+            return scope.projectId;
+        case "workflow":
+            return scope.workflowDefinitionId;
+        case "global":
+            // Global scope has no coordinate value; the empty string is the canonical placeholder so the
+            // NOT NULL column is always populated and an indexed equality check still works.
+            return "";
+    }
+}

package/dist/serialize.d.ts

@@ -0,0 +1,67 @@
+import type { MemoryRecord } from "@oscharko-dev/keiko-contracts/memory";
+import type { MemoryContentCipher } from "./cipher.js";
+export interface MemoryRow {
+    readonly id: string;
+    readonly schema_version: string;
+    readonly type: string;
+    readonly scope_kind: string;
+    readonly scope_coordinate: string;
+    readonly body: string;
+    readonly payload_json: string | null;
+    readonly status: string;
+    readonly sensitivity: string;
+    readonly pinned: number;
+    readonly confidence: number;
+    readonly valid_from: number;
+    readonly valid_until: number | null;
+    readonly stale_reason: string | null;
+    readonly tags_json: string;
+    readonly source_kind: string;
+    readonly source_conversation_id: string | null;
+    readonly source_workflow_run_id: string | null;
+    readonly source_evidence_manifest_id: string | null;
+    readonly captured_at: number;
+    readonly capture_rationale: string | null;
+    readonly model_provider: string | null;
+    readonly model_id: string | null;
+    readonly model_revision: string | null;
+    readonly retention_policy_key: string | null;
+    readonly retention_retain_until: number | null;
+    readonly retention_notes: string | null;
+    readonly created_at: number;
+    readonly updated_at: number;
+}
+export declare function rowToMemoryRecord(row: MemoryRow, cipher: MemoryContentCipher): MemoryRecord;
+export interface MemoryRowWrite {
+    readonly id: string;
+    readonly schema_version: string;
+    readonly type: string;
+    readonly scope_kind: string;
+    readonly scope_coordinate: string;
+    readonly body: string;
+    readonly payload_json: string | null;
+    readonly status: string;
+    readonly sensitivity: string;
+    readonly pinned: number;
+    readonly confidence: number;
+    readonly valid_from: number;
+    readonly valid_until: number | null;
+    readonly stale_reason: string | null;
+    readonly tags_json: string;
+    readonly source_kind: string;
+    readonly source_conversation_id: string | null;
+    readonly source_workflow_run_id: string | null;
+    readonly source_evidence_manifest_id: string | null;
+    readonly captured_at: number;
+    readonly capture_rationale: string | null;
+    readonly model_provider: string | null;
+    readonly model_id: string | null;
+    readonly model_revision: string | null;
+    readonly retention_policy_key: string | null;
+    readonly retention_retain_until: number | null;
+    readonly retention_notes: string | null;
+    readonly created_at: number;
+    readonly updated_at: number;
+}
+export declare function memoryRecordToRow(record: MemoryRecord, cipher: MemoryContentCipher): MemoryRowWrite;
+//# sourceMappingURL=serialize.d.ts.map

package/dist/serialize.d.ts.map

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

package/dist/serialize.js

@@ -0,0 +1,213 @@
+// Pure row↔record translation. The row shape mirrors the schema.ts column layout 1:1; the record
+// shape is the contract's MemoryRecord. We keep both layers in this single module so a schema
+// column rename has exactly one place to update.
+//
+// Encoding choices:
+//   - tags          → JSON array string
+//   - payload       → JSON-stringified discriminated union (NULL when absent)
+//   - validUntil    → NULL when absent (NOT undefined-as-string)
+//   - staleReason   → NULL when absent
+//   - retentionHint → flattened across three columns; NULL all when absent
+//   - sensitivity   → flat column (validator treats it as a provenance attribute but storing it
+//                     flat keeps the scoped-list query free of payload parsing for the common case)
+import { scopeCoordinateOf, scopeKindOf } from "./scope-key.js";
+import { MemoryStorageError } from "./errors.js";
+// Content-vs-metadata split (ADR-0035): only the columns that carry remembered TEXT are sealed —
+// body, payload_json, tags_json, capture_rationale, stale_reason. Every other column (ids, scope,
+// status, sensitivity, pinned, confidence, all timestamps, source_*, model_*, retention_*) stays
+// cleartext so SQL indexes and the UI scope display keep working without a key. Crypto is confined
+// to the two wrapper functions below; the pure row↔record builders never see a key.
+function openNullable(cipher, value) {
+    return value === null ? null : cipher.openString(value);
+}
+// Returns a row whose sealed content columns are decrypted in place, so the pure builders below run
+// on plaintext exactly as they did before encryption landed.
+function decryptContentColumns(row, cipher) {
+    return {
+        ...row,
+        body: cipher.openString(row.body),
+        payload_json: openNullable(cipher, row.payload_json),
+        tags_json: cipher.openString(row.tags_json),
+        capture_rationale: openNullable(cipher, row.capture_rationale),
+        stale_reason: openNullable(cipher, row.stale_reason),
+    };
+}
+function sealNullable(cipher, value) {
+    return value === null ? null : cipher.sealString(value);
+}
+// Returns a write-row whose content columns are sealed, leaving every metadata column untouched.
+function encryptContentColumns(row, cipher) {
+    return {
+        ...row,
+        body: cipher.sealString(row.body),
+        payload_json: sealNullable(cipher, row.payload_json),
+        tags_json: cipher.sealString(row.tags_json),
+        capture_rationale: sealNullable(cipher, row.capture_rationale),
+        stale_reason: sealNullable(cipher, row.stale_reason),
+    };
+}
+function buildScopeFromRow(kind, coord) {
+    switch (kind) {
+        case "user":
+            return { kind: "user", userId: coord };
+        case "workspace":
+            return { kind: "workspace", workspaceId: coord };
+        case "project":
+            return { kind: "project", projectId: coord };
+        case "workflow":
+            return { kind: "workflow", workflowDefinitionId: coord };
+        case "global":
+            return { kind: "global" };
+        default:
+            throw new MemoryStorageError("schema-mismatch", "Stored memory scope kind is not recognized.");
+    }
+}
+function buildProvenanceFromRow(row) {
+    const base = {
+        sourceKind: row.source_kind,
+        capturedAt: row.captured_at,
+        confidence: row.confidence,
+        sensitivity: row.sensitivity,
+    };
+    if (row.source_conversation_id !== null) {
+        base.sourceConversationId = row.source_conversation_id;
+    }
+    if (row.source_workflow_run_id !== null) {
+        base.sourceWorkflowRunId = row.source_workflow_run_id;
+    }
+    if (row.source_evidence_manifest_id !== null) {
+        base.sourceEvidenceManifestId = row.source_evidence_manifest_id;
+    }
+    if (row.capture_rationale !== null) {
+        base.captureRationale = row.capture_rationale;
+    }
+    if (row.model_provider !== null && row.model_id !== null) {
+        const identity = {
+            provider: row.model_provider,
+            modelId: row.model_id,
+        };
+        if (row.model_revision !== null)
+            identity.modelRevision = row.model_revision;
+        base.modelIdentity = identity;
+    }
+    return base;
+}
+function buildValidityFromRow(row) {
+    return row.valid_until === null
+        ? { validFrom: row.valid_from }
+        : { validFrom: row.valid_from, validUntil: row.valid_until };
+}
+function buildRetentionHintFromRow(row) {
+    if (row.retention_policy_key === null)
+        return undefined;
+    const hint = {
+        policyKey: row.retention_policy_key,
+    };
+    if (row.retention_retain_until !== null)
+        hint.retainUntil = row.retention_retain_until;
+    if (row.retention_notes !== null)
+        hint.notes = row.retention_notes;
+    return hint;
+}
+function parseTagsJson(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new MemoryStorageError("schema-mismatch", "Stored memory tags JSON is invalid.");
+    }
+    if (!Array.isArray(parsed))
+        return [];
+    return parsed.filter((v) => typeof v === "string");
+}
+function parsePayloadJson(raw) {
+    if (raw === null)
+        return undefined;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new MemoryStorageError("schema-mismatch", "Stored memory payload JSON is invalid.");
+    }
+}
+export function rowToMemoryRecord(row, cipher) {
+    const decrypted = decryptContentColumns(row, cipher);
+    return decryptedRowToMemoryRecord(decrypted);
+}
+function decryptedRowToMemoryRecord(row) {
+    const payload = parsePayloadJson(row.payload_json);
+    const retentionHint = buildRetentionHintFromRow(row);
+    const base = {
+        id: row.id,
+        schemaVersion: "1",
+        scope: buildScopeFromRow(row.scope_kind, row.scope_coordinate),
+        type: row.type,
+        body: row.body,
+        provenance: buildProvenanceFromRow(row),
+        validity: buildValidityFromRow(row),
+        status: row.status,
+        pinned: row.pinned === 1,
+        tags: parseTagsJson(row.tags_json),
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+    };
+    const out = {
+        ...base,
+        ...(payload !== undefined ? { payload } : {}),
+        ...(row.stale_reason !== null ? { staleReason: row.stale_reason } : {}),
+        ...(retentionHint !== undefined ? { retentionHint } : {}),
+    };
+    return out;
+}
+function modelIdentityFieldsToRow(identity) {
+    return {
+        model_provider: identity?.provider ?? null,
+        model_id: identity?.modelId ?? null,
+        model_revision: identity?.modelRevision ?? null,
+    };
+}
+function provenanceFieldsToRow(prov) {
+    return {
+        sensitivity: prov.sensitivity,
+        confidence: prov.confidence,
+        source_kind: prov.sourceKind,
+        source_conversation_id: prov.sourceConversationId ?? null,
+        source_workflow_run_id: prov.sourceWorkflowRunId ?? null,
+        source_evidence_manifest_id: prov.sourceEvidenceManifestId ?? null,
+        captured_at: prov.capturedAt,
+        capture_rationale: prov.captureRationale ?? null,
+        ...modelIdentityFieldsToRow(prov.modelIdentity),
+    };
+}
+function retentionFieldsToRow(hint) {
+    return {
+        retention_policy_key: hint?.policyKey ?? null,
+        retention_retain_until: hint?.retainUntil ?? null,
+        retention_notes: hint?.notes ?? null,
+    };
+}
+export function memoryRecordToRow(record, cipher) {
+    return encryptContentColumns(plainRecordToRow(record), cipher);
+}
+function plainRecordToRow(record) {
+    return {
+        id: record.id,
+        schema_version: record.schemaVersion,
+        type: record.type,
+        scope_kind: scopeKindOf(record.scope),
+        scope_coordinate: scopeCoordinateOf(record.scope),
+        body: record.body,
+        payload_json: record.payload === undefined ? null : JSON.stringify(record.payload),
+        status: record.status,
+        pinned: record.pinned ? 1 : 0,
+        valid_from: record.validity.validFrom,
+        valid_until: record.validity.validUntil ?? null,
+        stale_reason: record.staleReason ?? null,
+        tags_json: JSON.stringify(record.tags),
+        ...provenanceFieldsToRow(record.provenance),
+        ...retentionFieldsToRow(record.retentionHint),
+        created_at: record.createdAt,
+        updated_at: record.updatedAt,
+    };
+}

package/dist/tombstones.d.ts

@@ -0,0 +1,8 @@
+import type { DatabaseSync } from "node:sqlite";
+import type { MemoryScope } from "@oscharko-dev/keiko-contracts/memory";
+import type { MemoryTombstone } from "./types.js";
+import type { MemoryContentCipher } from "./cipher.js";
+export declare function insertTombstoneRow(db: DatabaseSync, tombstone: MemoryTombstone, cipher: MemoryContentCipher): void;
+export declare function listTombstonesByScopeRows(db: DatabaseSync, scope: MemoryScope, cipher: MemoryContentCipher): readonly MemoryTombstone[];
+export declare function deleteTombstonesByScopeBeforeRows(db: DatabaseSync, scope: MemoryScope, forgottenBeforeMs: number): number;
+//# sourceMappingURL=tombstones.d.ts.map

package/dist/tombstones.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tombstones.d.ts","sourceRoot":"","sources":["../src/tombstones.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAGV,WAAW,EAIZ,MAAM,sCAAsC,CAAC;AAE9C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAsDvD,wBAAgB,kBAAkB,CAChC,EAAE,EAAE,YAAY,EAChB,SAAS,EAAE,eAAe,EAC1B,MAAM,EAAE,mBAAmB,GAC1B,IAAI,CAcN;AAED,wBAAgB,yBAAyB,CACvC,EAAE,EAAE,YAAY,EAChB,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,mBAAmB,GAC1B,SAAS,eAAe,EAAE,CAK5B;AAED,wBAAgB,iCAAiC,CAC/C,EAAE,EAAE,YAAY,EAChB,KAAK,EAAE,WAAW,EAClB,iBAAiB,EAAE,MAAM,GACxB,MAAM,CAKR"}

package/dist/tombstones.js

@@ -0,0 +1,57 @@
+// Prepared SQL for the memory_tombstones table. Tombstones are intentionally NOT a foreign key
+// against memories.id — the memory row is gone by the time the tombstone is written; the FK
+// would either reject the insert or force ON DELETE SET NULL, both of which lose the audit
+// signal. We therefore store memory_id as a denormalised TEXT column and accept that listing a
+// tombstone tells you "this id existed in this scope at this time," not "follow the FK."
+import { scopeCoordinateOf, scopeKindOf } from "./scope-key.js";
+const INSERT_SQL = `
+INSERT INTO memory_tombstones (
+  id, memory_id, scope_kind, scope_coordinate, type, forgotten_at,
+  forgetter_surface, reviewer_id, original_status, reason
+) VALUES (?,?,?,?,?,?,?,?,?,?)
+`;
+const LIST_BY_SCOPE_SQL = `
+SELECT * FROM memory_tombstones
+WHERE scope_kind = ? AND scope_coordinate = ?
+ORDER BY forgotten_at ASC
+`;
+const DELETE_BY_SCOPE_BEFORE_SQL = `
+DELETE FROM memory_tombstones
+WHERE scope_kind = ? AND scope_coordinate = ? AND forgotten_at < ?
+`;
+// `reason` is the only free-text tombstone column, so it is the only sealed one (ADR-0035).
+function rowToTombstone(row, cipher) {
+    const base = {
+        id: row.id,
+        memoryId: row.memory_id,
+        scopeKind: row.scope_kind,
+        scopeCoordinate: row.scope_coordinate,
+        type: row.type,
+        forgottenAt: row.forgotten_at,
+        forgetterSurface: row.forgetter_surface,
+    };
+    return {
+        ...base,
+        ...(row.reviewer_id === null ? {} : { reviewerId: row.reviewer_id }),
+        ...(row.original_status === null
+            ? {}
+            : { originalStatus: row.original_status }),
+        ...(row.reason === null ? {} : { reason: cipher.openString(row.reason) }),
+    };
+}
+export function insertTombstoneRow(db, tombstone, cipher) {
+    const reason = tombstone.reason === undefined ? null : cipher.sealString(tombstone.reason);
+    db.prepare(INSERT_SQL).run(tombstone.id, tombstone.memoryId, tombstone.scopeKind, tombstone.scopeCoordinate, tombstone.type, tombstone.forgottenAt, tombstone.forgetterSurface, tombstone.reviewerId ?? null, tombstone.originalStatus ?? null, reason);
+}
+export function listTombstonesByScopeRows(db, scope, cipher) {
+    const rows = db
+        .prepare(LIST_BY_SCOPE_SQL)
+        .all(scopeKindOf(scope), scopeCoordinateOf(scope));
+    return rows.map((row) => rowToTombstone(row, cipher));
+}
+export function deleteTombstonesByScopeBeforeRows(db, scope, forgottenBeforeMs) {
+    const info = db
+        .prepare(DELETE_BY_SCOPE_BEFORE_SQL)
+        .run(scopeKindOf(scope), scopeCoordinateOf(scope), forgottenBeforeMs);
+    return Number(info.changes);
+}