@astragenie/astramemory-local 0.7.2

package/dist/storage/memories.d.ts

@@ -0,0 +1,51 @@
+import type { DB } from './db.js';
+import type { Memory, MemoryScope, MemoryType } from '../contracts/index.js';
+import type { MemoryEventRepo } from './memory-events.js';
+export interface InsertInput {
+    type: MemoryType;
+    text: string;
+    normalized_text: string;
+    repo: string | null;
+    project: string | null;
+    branch: string | null;
+    agent: string | null;
+    session_id: string | null;
+    hash: string;
+    source_hash: string | null;
+    importance?: number;
+    confidence?: number;
+    embedding_provider?: string | null;
+    embedding_model?: string | null;
+    embedding_dim?: number | null;
+    evidence?: string | null;
+    /** ADR-009 scope. Defaults to 'personal'. */
+    scope?: MemoryScope;
+}
+export interface FtsHit {
+    id: string;
+    text: string;
+    type: MemoryType;
+    bm25: number;
+}
+export declare class MemoryRepo {
+    private db;
+    constructor(db: DB);
+    insert(input: InsertInput): string;
+    /**
+     * Insert + append a 'create' memory_event (ADR-002) in the SAME
+     * transaction. Dedup-aware like insert(): if a memory with this hash
+     * already exists, no row is inserted and no event is appended — matches
+     * insert()'s existing dedup semantics, so a re-ingest never fabricates a
+     * duplicate create event for an atom that already has one.
+     */
+    insertWithCreateEvent(input: InsertInput, events: MemoryEventRepo): {
+        id: string;
+        created: boolean;
+    };
+    /** Raw insert — no dedup check (caller has already decided to insert). */
+    private insertRow;
+    get(id: string): Memory | null;
+    /** Parse the JSON-stored derived_from column into a string[] | null. */
+    private static hydrate;
+    searchFts(query: string, limit: number): FtsHit[];
+}

package/dist/storage/memories.js

@@ -0,0 +1,67 @@
+import { randomUUID } from 'node:crypto';
+export class MemoryRepo {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    insert(input) {
+        const existing = this.db.prepare('SELECT id FROM memories WHERE hash = ?').get(input.hash);
+        if (existing)
+            return existing.id;
+        return this.insertRow(input);
+    }
+    /**
+     * Insert + append a 'create' memory_event (ADR-002) in the SAME
+     * transaction. Dedup-aware like insert(): if a memory with this hash
+     * already exists, no row is inserted and no event is appended — matches
+     * insert()'s existing dedup semantics, so a re-ingest never fabricates a
+     * duplicate create event for an atom that already has one.
+     */
+    insertWithCreateEvent(input, events) {
+        const tx = this.db.transaction(() => {
+            const existing = this.db.prepare('SELECT id FROM memories WHERE hash = ?').get(input.hash);
+            if (existing)
+                return { id: existing.id, created: false };
+            const id = this.insertRow(input);
+            events.append({ event_type: 'create', atom_id: id, content_hash: input.hash });
+            return { id, created: true };
+        });
+        return tx();
+    }
+    /** Raw insert — no dedup check (caller has already decided to insert). */
+    insertRow(input) {
+        const id = randomUUID();
+        const now = Date.now();
+        this.db.prepare(`
+      INSERT INTO memories
+        (id, type, text, normalized_text, repo, project, branch, agent, session_id,
+         importance, confidence, hash, embedding_provider, embedding_model, embedding_dim,
+         created_at, updated_at, source_hash, evidence, valid_from, scope)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(id, input.type, input.text, input.normalized_text, input.repo, input.project, input.branch, input.agent, input.session_id, input.importance ?? 0.5, input.confidence ?? 0.5, input.hash, input.embedding_provider ?? null, input.embedding_model ?? null, input.embedding_dim ?? null, now, now, input.source_hash, input.evidence ?? null, now, input.scope ?? 'personal');
+        return id;
+    }
+    get(id) {
+        const row = this.db.prepare('SELECT * FROM memories WHERE id = ?').get(id);
+        return row ? MemoryRepo.hydrate(row) : null;
+    }
+    /** Parse the JSON-stored derived_from column into a string[] | null. */
+    static hydrate(row) {
+        return {
+            ...row,
+            derived_from: row.derived_from ? JSON.parse(row.derived_from) : null,
+            archived: row.archived === 1,
+        };
+    }
+    searchFts(query, limit) {
+        const rows = this.db.prepare(`
+      SELECT m.id, m.text, m.type, bm25(memories_fts) AS bm25
+      FROM memories_fts
+      JOIN memories m ON m.rowid = memories_fts.rowid
+      WHERE memories_fts MATCH ?
+      ORDER BY bm25 LIMIT ?
+    `).all(query, limit);
+        return rows;
+    }
+}
+//# sourceMappingURL=memories.js.map

package/dist/storage/memories.js.map

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

package/dist/storage/memory-events.d.ts

@@ -0,0 +1,145 @@
+/**
+ * memory_events append-only log + lifecycle operations (ADR-002 decision
+ * point 1, migration 007). The log is the source of truth for state
+ * *changes*; the materialized `memories` row is updated in the SAME
+ * transaction as the event append (log + tables in one file, not full event
+ * sourcing — no view rebuilding, no projection framework).
+ */
+import type { DB } from './db.js';
+import type { MemoryScope } from '../contracts/index.js';
+export type MemoryEventType = 'create' | 'invalidate' | 'supersede' | 'promote_scope' | 'erase_request' | 'usefulness' | 'archive' | 'restore';
+export interface MemoryEvent {
+    seq: number;
+    event_id: string;
+    event_type: MemoryEventType;
+    atom_id: string;
+    payload_json: string | null;
+    content_hash: string | null;
+    created_at: number;
+    synced_at: number | null;
+}
+export interface AppendEventInput {
+    event_type: MemoryEventType;
+    atom_id: string;
+    /** JSON-serialized on write; use listForAtom + JSON.parse to read back. */
+    payload?: unknown;
+    content_hash?: string | null;
+    created_at?: number;
+    /**
+     * Globally-unique event identity (ADR-011). Local single-device writers
+     * never pass this — it is always freshly generated (node:crypto
+     * randomUUID()). Only the pull-ingest path (src/sync/puller.ts) writes
+     * remote-originated events with their OWN pre-existing event_id, and it
+     * does so via a raw dedup-insert, not through this method — append() is
+     * exclusively the local-origin path.
+     */
+    event_id?: string;
+}
+/** Memory not found for the requested lifecycle op — maps to HTTP 404. */
+export declare class MemoryNotFoundError extends Error {
+    readonly atomId: string;
+    constructor(atomId: string);
+}
+/** State conflict (e.g. already invalidated) — maps to HTTP 409. */
+export declare class MemoryConflictError extends Error {
+    constructor(message: string);
+}
+/** Invalid scope transition (e.g. downward promotion) — maps to HTTP 400. */
+export declare class InvalidScopeTransitionError extends Error {
+    constructor(message: string);
+}
+export declare class MemoryEventRepo {
+    private db;
+    constructor(db: DB);
+    /** Low-level append. Caller owns the transaction boundary. */
+    append(event: AppendEventInput): number;
+    /** Full event log for one atom, ordered by seq (append order). */
+    listForAtom(atomId: string): MemoryEvent[];
+    /**
+     * Invalidate a memory: sets valid_to = now, appends an 'invalidate' event,
+     * both in one transaction. Idempotent-safe: throws MemoryConflictError if
+     * the memory is already invalid rather than silently double-invalidating.
+     */
+    invalidate(atomId: string, reason?: string): void;
+    /**
+     * Supersede oldId with newId: sets old.valid_to = now AND
+     * old.superseded_by = newId, appends a 'supersede' event on oldId — all in
+     * one transaction. Validates both ids exist; oldId must currently be valid
+     * (not already invalidated/superseded); newId must be valid (valid_to null).
+     *
+     * FEAT-401 fix: also co-issues newId.valid_from = the SAME `now` used for
+     * old.valid_to. Without this, newId keeps the valid_from it was stamped
+     * with at insert() time (which normally predates the supersede() call by
+     * however long the caller took to decide to supersede), producing an
+     * overlap window [newId.valid_from, oldId.valid_to) where an as_of query
+     * would match BOTH generations — a bitemporal-window leak. Co-issuing the
+     * boundary keeps the two windows contiguous and non-overlapping
+     * (old.valid_to === new.valid_from), matching the half-open-interval
+     * model as_of resolution assumes (ADR-001, FEAT-401 AC-1/AC-5): the
+     * successor becomes "the believed value" exactly as of the supersede
+     * instant, not as of whenever it happened to be inserted.
+     *
+     * FEAT-402 AC-3: also deletes oldId's memory_entities links in the same
+     * transaction. The memories row itself is NOT deleted (bitemporal history
+     * is kept for as_of queries), so this can't rely on the erase() path's
+     * ON DELETE CASCADE — it's explicit here instead. A superseded memory's
+     * facts should stop counting as current evidence for an entity even
+     * though the row survives for audit.
+     */
+    supersede(oldId: string, newId: string): void;
+    /**
+     * Archive a memory (FEAT-404 TTL/archival tiers): sets valid_to = now +
+     * archived = 1 + archived_at = now, appends an 'archive' event — all in
+     * one transaction. Reuses the exact non-destructive valid_to bookkeeping
+     * invalidate()/supersede() already use (row survives, restorable via
+     * restore()) — the only difference is *why* the row stopped being
+     * current, which is why this is a distinct event type rather than a
+     * relabeled invalidate().
+     *
+     * Deliberately does NOT append a 'memory_corrected' usefulness signal the
+     * way invalidate()/supersede() do: staleness-triggered archival is
+     * routine housekeeping driven by low usefulness, not a correction of a
+     * wrong/superseded fact — appending one would create a feedback loop
+     * that further penalizes an atom the policy might restore later.
+     *
+     * Throws MemoryConflictError if the memory is already invalid (including
+     * already archived) rather than silently double-archiving.
+     */
+    archive(atomId: string, reason?: string): void;
+    /**
+     * Restore a previously-archived memory (FEAT-404 AC-4): clears valid_to
+     * and archived/archived_at, appends a 'restore' event — all in one
+     * transaction. The memory immediately re-qualifies for every
+     * `valid_to IS NULL` candidate filter (search.ts, recall/pack.ts), so it
+     * reappears in search with no further wiring needed.
+     *
+     * Throws MemoryNotFoundError if the id doesn't exist, MemoryConflictError
+     * if it isn't currently archived (e.g. it was invalidated/superseded
+     * through a different path, or was never archived).
+     */
+    restore(atomId: string): void;
+    /**
+     * Promote a memory's scope: personal -> team -> org (ADR-009). Only
+     * upward promotions are allowed; same-scope or downward requests throw
+     * InvalidScopeTransitionError. State update + event append in one
+     * transaction.
+     */
+    promoteScope(atomId: string, toScope: MemoryScope): void;
+    /**
+     * Erase a memory (erasure v1, ADR-006 W5): HARD-deletes the memories row
+     * (FTS cleans up via the AFTER DELETE trigger) and its vector index row,
+     * and appends an 'erase_request' event — the event IS the tombstone:
+     *   - payload.scope lets the sync shipper (ADR-009) ship the tombstone to
+     *     the cloud even though the memories row is gone,
+     *   - content_hash = the memory's hash powers the replay filter (stage 8
+     *     refuses to resurrect an erased memory on re-distillation).
+     * Erasure always wins over retention/replay — the text is unrecoverable
+     * locally after this call.
+     */
+    erase(atomId: string, reason?: string): void;
+    /**
+     * Replay filter (erasure v1): true when a memory with this content hash
+     * has been erased — re-distillation must not resurrect it.
+     */
+    isErasedHash(contentHash: string): boolean;
+}

package/dist/storage/memory-events.js

@@ -0,0 +1,287 @@
+/**
+ * memory_events append-only log + lifecycle operations (ADR-002 decision
+ * point 1, migration 007). The log is the source of truth for state
+ * *changes*; the materialized `memories` row is updated in the SAME
+ * transaction as the event append (log + tables in one file, not full event
+ * sourcing — no view rebuilding, no projection framework).
+ */
+import { randomUUID } from 'node:crypto';
+/** Memory not found for the requested lifecycle op — maps to HTTP 404. */
+export class MemoryNotFoundError extends Error {
+    atomId;
+    constructor(atomId) {
+        super(`memory not found: ${atomId}`);
+        this.atomId = atomId;
+        this.name = 'MemoryNotFoundError';
+    }
+}
+/** State conflict (e.g. already invalidated) — maps to HTTP 409. */
+export class MemoryConflictError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'MemoryConflictError';
+    }
+}
+/** Invalid scope transition (e.g. downward promotion) — maps to HTTP 400. */
+export class InvalidScopeTransitionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'InvalidScopeTransitionError';
+    }
+}
+// ADR-009: scope only ever moves upward — personal -> team -> org.
+const SCOPE_RANK = { personal: 0, team: 1, org: 2 };
+export class MemoryEventRepo {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    /** Low-level append. Caller owns the transaction boundary. */
+    append(event) {
+        const createdAt = event.created_at ?? Date.now();
+        const payloadJson = event.payload !== undefined ? JSON.stringify(event.payload) : null;
+        const eventId = event.event_id ?? randomUUID();
+        const result = this.db
+            .prepare(`
+        INSERT INTO memory_events (event_id, event_type, atom_id, payload_json, content_hash, created_at)
+        VALUES (?, ?, ?, ?, ?, ?)
+      `)
+            .run(eventId, event.event_type, event.atom_id, payloadJson, event.content_hash ?? null, createdAt);
+        return Number(result.lastInsertRowid);
+    }
+    /** Full event log for one atom, ordered by seq (append order). */
+    listForAtom(atomId) {
+        return this.db
+            .prepare('SELECT * FROM memory_events WHERE atom_id = ? ORDER BY seq ASC')
+            .all(atomId);
+    }
+    /**
+     * Invalidate a memory: sets valid_to = now, appends an 'invalidate' event,
+     * both in one transaction. Idempotent-safe: throws MemoryConflictError if
+     * the memory is already invalid rather than silently double-invalidating.
+     */
+    invalidate(atomId, reason) {
+        const tx = this.db.transaction(() => {
+            const row = this.db
+                .prepare('SELECT id, valid_to FROM memories WHERE id = ?')
+                .get(atomId);
+            if (!row)
+                throw new MemoryNotFoundError(atomId);
+            if (row.valid_to !== null) {
+                throw new MemoryConflictError(`memory ${atomId} is already invalid`);
+            }
+            const now = Date.now();
+            this.db.prepare('UPDATE memories SET valid_to = ?, updated_at = ? WHERE id = ?').run(now, now, atomId);
+            this.append({ event_type: 'invalidate', atom_id: atomId, payload: { reason: reason ?? null }, created_at: now });
+            // ADR-010: negative usefulness signal — same tx as the state change.
+            // Payload shape documented in src/storage/usefulness.ts (memory_corrected family).
+            this.append({
+                event_type: 'usefulness',
+                atom_id: atomId,
+                payload: { family: 'memory_corrected', action: 'invalidated' },
+                created_at: now,
+            });
+        });
+        tx();
+    }
+    /**
+     * Supersede oldId with newId: sets old.valid_to = now AND
+     * old.superseded_by = newId, appends a 'supersede' event on oldId — all in
+     * one transaction. Validates both ids exist; oldId must currently be valid
+     * (not already invalidated/superseded); newId must be valid (valid_to null).
+     *
+     * FEAT-401 fix: also co-issues newId.valid_from = the SAME `now` used for
+     * old.valid_to. Without this, newId keeps the valid_from it was stamped
+     * with at insert() time (which normally predates the supersede() call by
+     * however long the caller took to decide to supersede), producing an
+     * overlap window [newId.valid_from, oldId.valid_to) where an as_of query
+     * would match BOTH generations — a bitemporal-window leak. Co-issuing the
+     * boundary keeps the two windows contiguous and non-overlapping
+     * (old.valid_to === new.valid_from), matching the half-open-interval
+     * model as_of resolution assumes (ADR-001, FEAT-401 AC-1/AC-5): the
+     * successor becomes "the believed value" exactly as of the supersede
+     * instant, not as of whenever it happened to be inserted.
+     *
+     * FEAT-402 AC-3: also deletes oldId's memory_entities links in the same
+     * transaction. The memories row itself is NOT deleted (bitemporal history
+     * is kept for as_of queries), so this can't rely on the erase() path's
+     * ON DELETE CASCADE — it's explicit here instead. A superseded memory's
+     * facts should stop counting as current evidence for an entity even
+     * though the row survives for audit.
+     */
+    supersede(oldId, newId) {
+        const tx = this.db.transaction(() => {
+            const oldRow = this.db
+                .prepare('SELECT id, valid_to FROM memories WHERE id = ?')
+                .get(oldId);
+            if (!oldRow)
+                throw new MemoryNotFoundError(oldId);
+            const newRow = this.db
+                .prepare('SELECT id, valid_to FROM memories WHERE id = ?')
+                .get(newId);
+            if (!newRow)
+                throw new MemoryNotFoundError(newId);
+            if (oldRow.valid_to !== null) {
+                throw new MemoryConflictError(`memory ${oldId} is already invalid`);
+            }
+            if (newRow.valid_to !== null) {
+                throw new MemoryConflictError(`memory ${newId} must be valid to supersede with — it is already invalid`);
+            }
+            const now = Date.now();
+            this.db
+                .prepare('UPDATE memories SET valid_to = ?, superseded_by = ?, updated_at = ? WHERE id = ?')
+                .run(now, newId, now, oldId);
+            this.db
+                .prepare('UPDATE memories SET valid_from = ?, updated_at = ? WHERE id = ?')
+                .run(now, now, newId);
+            // FEAT-402 AC-3: zero orphan links — the superseded memory no longer
+            // contributes to "everything about entity X".
+            this.db.prepare('DELETE FROM memory_entities WHERE memory_id = ?').run(oldId);
+            this.append({ event_type: 'supersede', atom_id: oldId, payload: { superseded_by: newId }, created_at: now });
+            // ADR-010: negative usefulness signal — same tx as the state change.
+            // Payload shape documented in src/storage/usefulness.ts (memory_corrected family).
+            this.append({
+                event_type: 'usefulness',
+                atom_id: oldId,
+                payload: { family: 'memory_corrected', action: 'superseded' },
+                created_at: now,
+            });
+        });
+        tx();
+    }
+    /**
+     * Archive a memory (FEAT-404 TTL/archival tiers): sets valid_to = now +
+     * archived = 1 + archived_at = now, appends an 'archive' event — all in
+     * one transaction. Reuses the exact non-destructive valid_to bookkeeping
+     * invalidate()/supersede() already use (row survives, restorable via
+     * restore()) — the only difference is *why* the row stopped being
+     * current, which is why this is a distinct event type rather than a
+     * relabeled invalidate().
+     *
+     * Deliberately does NOT append a 'memory_corrected' usefulness signal the
+     * way invalidate()/supersede() do: staleness-triggered archival is
+     * routine housekeeping driven by low usefulness, not a correction of a
+     * wrong/superseded fact — appending one would create a feedback loop
+     * that further penalizes an atom the policy might restore later.
+     *
+     * Throws MemoryConflictError if the memory is already invalid (including
+     * already archived) rather than silently double-archiving.
+     */
+    archive(atomId, reason) {
+        const tx = this.db.transaction(() => {
+            const row = this.db
+                .prepare('SELECT id, valid_to, archived FROM memories WHERE id = ?')
+                .get(atomId);
+            if (!row)
+                throw new MemoryNotFoundError(atomId);
+            if (row.valid_to !== null) {
+                throw new MemoryConflictError(`memory ${atomId} is already invalid — cannot archive`);
+            }
+            const now = Date.now();
+            this.db
+                .prepare('UPDATE memories SET valid_to = ?, archived = 1, archived_at = ?, updated_at = ? WHERE id = ?')
+                .run(now, now, now, atomId);
+            this.append({ event_type: 'archive', atom_id: atomId, payload: { reason: reason ?? null }, created_at: now });
+        });
+        tx();
+    }
+    /**
+     * Restore a previously-archived memory (FEAT-404 AC-4): clears valid_to
+     * and archived/archived_at, appends a 'restore' event — all in one
+     * transaction. The memory immediately re-qualifies for every
+     * `valid_to IS NULL` candidate filter (search.ts, recall/pack.ts), so it
+     * reappears in search with no further wiring needed.
+     *
+     * Throws MemoryNotFoundError if the id doesn't exist, MemoryConflictError
+     * if it isn't currently archived (e.g. it was invalidated/superseded
+     * through a different path, or was never archived).
+     */
+    restore(atomId) {
+        const tx = this.db.transaction(() => {
+            const row = this.db
+                .prepare('SELECT id, valid_to, archived FROM memories WHERE id = ?')
+                .get(atomId);
+            if (!row)
+                throw new MemoryNotFoundError(atomId);
+            if (row.archived !== 1) {
+                throw new MemoryConflictError(`memory ${atomId} is not archived`);
+            }
+            const now = Date.now();
+            this.db
+                .prepare('UPDATE memories SET valid_to = NULL, archived = 0, archived_at = NULL, updated_at = ? WHERE id = ?')
+                .run(now, atomId);
+            this.append({ event_type: 'restore', atom_id: atomId, created_at: now });
+        });
+        tx();
+    }
+    /**
+     * Promote a memory's scope: personal -> team -> org (ADR-009). Only
+     * upward promotions are allowed; same-scope or downward requests throw
+     * InvalidScopeTransitionError. State update + event append in one
+     * transaction.
+     */
+    promoteScope(atomId, toScope) {
+        const tx = this.db.transaction(() => {
+            const row = this.db
+                .prepare('SELECT id, scope FROM memories WHERE id = ?')
+                .get(atomId);
+            if (!row)
+                throw new MemoryNotFoundError(atomId);
+            if (SCOPE_RANK[toScope] <= SCOPE_RANK[row.scope]) {
+                throw new InvalidScopeTransitionError(`cannot promote memory ${atomId} from '${row.scope}' to '${toScope}' — only upward promotions allowed (personal -> team -> org)`);
+            }
+            const now = Date.now();
+            this.db.prepare('UPDATE memories SET scope = ?, updated_at = ? WHERE id = ?').run(toScope, now, atomId);
+            this.append({
+                event_type: 'promote_scope',
+                atom_id: atomId,
+                payload: { from: row.scope, to: toScope },
+                created_at: now,
+            });
+        });
+        tx();
+    }
+    /**
+     * Erase a memory (erasure v1, ADR-006 W5): HARD-deletes the memories row
+     * (FTS cleans up via the AFTER DELETE trigger) and its vector index row,
+     * and appends an 'erase_request' event — the event IS the tombstone:
+     *   - payload.scope lets the sync shipper (ADR-009) ship the tombstone to
+     *     the cloud even though the memories row is gone,
+     *   - content_hash = the memory's hash powers the replay filter (stage 8
+     *     refuses to resurrect an erased memory on re-distillation).
+     * Erasure always wins over retention/replay — the text is unrecoverable
+     * locally after this call.
+     */
+    erase(atomId, reason) {
+        const tx = this.db.transaction(() => {
+            const row = this.db
+                .prepare('SELECT id, rowid, scope, hash FROM memories WHERE id = ?')
+                .get(atomId);
+            if (!row)
+                throw new MemoryNotFoundError(atomId);
+            const now = Date.now();
+            // Tombstone first (same tx): the event survives the row.
+            this.append({
+                event_type: 'erase_request',
+                atom_id: atomId,
+                payload: { scope: row.scope, reason: reason ?? null },
+                content_hash: row.hash,
+                created_at: now,
+            });
+            this.db.prepare('DELETE FROM memories_vec WHERE rowid = ?').run(BigInt(row.rowid));
+            this.db.prepare('DELETE FROM memories WHERE id = ?').run(atomId); // FTS trigger fires
+        });
+        tx();
+    }
+    /**
+     * Replay filter (erasure v1): true when a memory with this content hash
+     * has been erased — re-distillation must not resurrect it.
+     */
+    isErasedHash(contentHash) {
+        const row = this.db
+            .prepare(`SELECT 1 AS x FROM memory_events WHERE event_type = 'erase_request' AND content_hash = ? LIMIT 1`)
+            .get(contentHash);
+        return row !== undefined;
+    }
+}
+//# sourceMappingURL=memory-events.js.map

package/dist/storage/memory-events.js.map

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

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

@@ -0,0 +1,16 @@
+export type EncryptMigrationResult = 'migrated' | 'already-encrypted' | 'missing';
+/** Exported for key-aware CLI opens (open-runtime-db.ts): a plaintext file
+ *  must be opened WITHOUT a key — PRAGMA key on plaintext reads as garbage. */
+export declare function isPlaintextSqlite(dbPath: string): boolean;
+/**
+ * Detects a plaintext DB at `dbPath` and migrates it to encrypted form with
+ * `key`. Returns:
+ *   - 'missing'           — no file at dbPath (fresh install; openDb() with
+ *                            a key will create an encrypted file directly).
+ *   - 'already-encrypted' — file exists and is not plaintext (already
+ *                            migrated, or created encrypted from the start).
+ *   - 'migrated'          — a plaintext DB was found and successfully
+ *                            converted; `<dbPath>.pre-encryption.bak` now
+ *                            holds the pre-migration plaintext copy.
+ */
+export declare function encryptIfPlaintext(dbPath: string, key: string): EncryptMigrationResult;