hippo-memory 1.69.0 → 1.71.0

package/dist/{quality-repair.js → store/quality-repair.js}

@@ -1,20 +1,19 @@
-import fs from 'node:fs';
-import path from 'node:path';
 import { appendAuditEvent } from './audit.js';
-import { withBackup } from './db/backup.js';
-import { assertSqliteAllowed } from './db/open.js';
-import { DatabaseSync } from './db/sqlite.js';
-import { getMeta, setMeta } from './db/meta.js';
-import { tableColumns } from './db/tables.js';
-import { assertBinaryCompatible } from './db/migrate.js';
+import { withBackup } from '../db/backup.js';
+import { withTrialScope, withWriteScope } from '../db/busy.js';
+import { withUnmigratedDb } from '../db/open.js';
+import { getMeta, pragmaUserVersion, setMeta } from '../db/meta.js';
+import { tableColumns } from '../db/tables.js';
+import { assertBinaryCompatible } from '../db/migrate.js';
 import { insertDormantRow, listDormantSnapshots } from './dormant.js';
-import { calculateStrength, canAutoDelete } from './memory.js';
-import { assessAutomaticMemory, BUNDLE_HEADER, isAutomaticEntry, isCertainReason } from './memory-quality.js';
-import { heldTexts } from './same-text.js';
-import { deleteEntryCore, MEMORY_BACKED_TABLES, memoriesBackingObjectsOn } from './store/delete-and-batch.js';
-import { selectAllEntries } from './store/entry-reads.js';
-import { MEMORY_SELECT_COLUMNS, parseJsonArray } from './store/rows.js';
-import { purgeMirrorBestEffort } from './store/mirrors.js';
+import { calculateStrength, canAutoDelete } from '../core/memory.js';
+import { assessAutomaticMemory, BUNDLE_HEADER, isAutomaticEntry, isCertainReason } from '../core/memory-quality.js';
+import { heldTexts } from '../util/same-text.js';
+import { deleteEntryCore, MEMORY_BACKED_TABLES, memoriesBackingObjectsOn } from './delete-and-batch.js';
+import { selectAllEntries, selectPreviewRows } from './entry-reads.js';
+import { ftsRowExists } from './entry-row.js';
+import { MEMORY_SELECT_COLUMNS, parseJsonArray } from './rows.js';
+import { purgeMirrorBestEffort } from './mirrors.js';
 const REQUIRED_COLUMNS = {
     memories: MEMORY_SELECT_COLUMNS.split(',').map((s) => s.trim()),
     meta: ['key', 'value'],
@@ -104,13 +103,10 @@ function unsupportedPreview(db, tenantId) {
     const columns = tableColumns(db, 'memories');
     if (!columns.has('id') || !columns.has('content'))
         return { total: 0, issues: [] };
-    const tenant = columns.has('tenant_id') ? ' WHERE tenant_id = ?' : '';
-    const column = (name, fallback) => (columns.has(name) ? name : `${fallback} AS ${name}`);
-    const statement = db.prepare(`SELECT id, content, ${column('source', "''")}, ${column('confidence', 'NULL')}, ${column('extracted_from', 'NULL')}, ${column('dag_level', '0')}, ${column('tags_json', "'[]'")} FROM memories${tenant}`);
-    // SAFETY: the SELECT names every Row field, each a literal fallback when its column is missing.
-    const rows = (tenant ? statement.all(tenantId) : statement.all());
+    const rows = selectPreviewRows(db, columns, tenantId);
     const issues = rows.flatMap((row) => {
-        const provenance = { ...row, source: row.source ?? '', confidence: row.confidence ?? 'observed', dag_level: row.dag_level ?? 0, tags: parseJsonArray(row.tags_json) };
+        const tags = parseJsonArray(row.tags_json, { table: 'memories', id: row.id, column: 'tags_json' });
+        const provenance = { ...row, source: row.source ?? '', confidence: row.confidence ?? 'observed', dag_level: row.dag_level ?? 0, tags };
         if (!isAutomaticEntry(provenance))
             return [];
         const { reason } = assessAutomaticMemory(row.content);
@@ -120,8 +116,7 @@ function unsupportedPreview(db, tenantId) {
 }
 function initialResult(db, root, tenantId) {
     const blockers = capabilityBlockers(db);
-    // SAFETY: PRAGMA user_version returns one row with one integer column.
-    const schema = db.prepare('PRAGMA user_version').get().user_version;
+    const schema = pragmaUserVersion(db);
     const plan = blockers.length > 0 ? unsupportedPreview(db, tenantId) : planRows(db, tenantId);
     return {
         root, schema, supported: blockers.length === 0, blockers,
@@ -135,15 +130,14 @@ function setAsideIssue(db, entry, reason, now, backup) {
     if (deleteEntryCore(db, entry.id, { actor, automatic: true, suppressForgetAudit: true }) === null)
         return false;
     insertDormantRow(db, { entry, strength: calculateStrength(entry, now), reason: 'quality-repair', dormantAt: now.toISOString() });
-    if (getMeta(db, 'fts5_available', '0') === '1' && db.prepare('SELECT id FROM memories_fts WHERE id = ?').get(entry.id)) {
+    if (getMeta(db, 'fts5_available', '0') === '1' && ftsRowExists(db, entry.id)) {
         throw new Error(`Quality repair could not remove the full-text row for ${entry.id}`);
     }
     appendAuditEvent(db, { tenantId: entry.tenantId, actor, op: 'quality_repair', targetId: entry.id, metadata: { reason, backup } });
     return true;
 }
 function applyPlan(db, root, tenantId, backup, doneKey) {
-    db.exec('BEGIN IMMEDIATE');
-    try {
+    return withWriteScope(db, 'quality_repair_apply', () => {
         const result = initialResult(db, root, tenantId);
         if (!result.supported)
             throw new Error(`Quality repair capability changed: ${result.blockers.join('; ')}`);
@@ -161,55 +155,31 @@ function applyPlan(db, root, tenantId, backup, doneKey) {
         }
         if (doneKey)
             setMeta(db, doneKey, '1');
-        db.exec('COMMIT');
         return { ...result, appliedIds, backup, warnings };
-    }
-    catch (error) {
-        try {
-            db.exec('ROLLBACK');
-        }
-        catch { /* preserve the mutation error */ }
-        throw error;
-    }
+    });
 }
 function repairOn(db, root, opts) {
-    db.exec('BEGIN');
-    const initial = initialResult(db, root, opts.tenantId);
-    db.exec('ROLLBACK');
+    const initial = withTrialScope(db, 'quality_repair_plan', () => initialResult(db, root, opts.tenantId));
     if (!opts.apply || !initial.supported || !initial.issues.some((issue) => issue.disposition === 'set-aside'))
         return initial;
     db.exec('PRAGMA foreign_keys = ON');
     const result = withBackup(db, root, 'before-quality-repair', (backup) => applyPlan(db, root, opts.tenantId, backup, opts.doneKey));
     const warnings = [...result.warnings];
     for (const id of result.appliedIds) {
-        if (!purgeMirrorBestEffort(root, id, false, 'quality repair'))
-            warnings.push(`Mirror cleanup failed for ${id}; remove its stale mirror before rebuilding the index.`);
+        if (purgeMirrorBestEffort(root, id, false, 'quality repair'))
+            continue;
+        warnings.push(`Mirror cleanup failed for ${id}; remove its stale mirror before rebuilding the index.`);
     }
     return { ...result, warnings };
 }
-function openForRepair(root, readOnly, fn) {
-    // Opens without openHippoDb to skip migrations, so it takes the same refusal itself.
-    assertSqliteAllowed(root);
-    const file = path.join(root, 'hippo.db');
-    if (!fs.existsSync(file))
-        throw new Error(`No existing Hippo database at ${file}`);
-    const db = new DatabaseSync(file, { readOnly });
-    try {
-        db.exec('PRAGMA busy_timeout = 5000');
-        return fn(db);
-    }
-    finally {
-        db.close();
-    }
-}
 /** Preview by default; apply backs the database up, then moves certain defects to dormant storage, without running migrations. */
 export function repairAutomaticMemories(root, opts) {
-    return openForRepair(root, !opts.apply, (db) => repairOn(db, root, opts));
+    return withUnmigratedDb(root, !opts.apply, (db) => repairOn(db, root, opts));
 }
 const AUTO_REPAIR_META_KEY = 'quality_repair_auto';
 /** Applies the repair once per store, so stores that predate the quality gate are cleaned on upgrade with no command; null once done. */
 export function repairQualityOnce(root, tenantId) {
-    return openForRepair(root, false, (db) => {
+    return withUnmigratedDb(root, false, (db) => {
         if (getMeta(db, AUTO_REPAIR_META_KEY) === '1')
             return null;
         // The apply commits the flag with the moves, so a lock taken between them cannot hide what moved.

package/dist/{quarantine.d.ts → store/quarantine.d.ts}

@@ -1,10 +1,8 @@
-/** Quarantine tier (CD5, AT3): pending/approved/rejected record for a memory `remember` flagged as untrusted. */
-import type { DatabaseSyncLike } from './db.js';
-import { type KeysetPosition } from './keyset.js';
+import { type DatabaseSyncLike } from '../db/index.js';
+import type { QuarantineApproval, QuarantineListQuery, QuarantineRejection, QuarantinedMemory } from './port.js';
 export declare const QUARANTINE_SCOPE_PREFIX = "quarantine:private:";
 /** Scope a quarantined memory is stored under; matches PRIVATE_SCOPE_RE so every default-deny site hides it. */
 export declare function quarantineScopeFor(original: string | null): string;
-export declare function isQuarantineScope(scope: string | null | undefined): boolean;
 export type QuarantineStatus = 'pending' | 'approved' | 'rejected';
 export interface QuarantineRow {
     tenantId: string;
@@ -25,8 +23,10 @@ export interface RecordQuarantineOpts {
 }
 /** Insert the quarantine row + its audit event; caller runs this inside the memory's own write transaction. */
 export declare function recordQuarantine(db: DatabaseSyncLike, opts: RecordQuarantineOpts): void;
-export declare function getQuarantineRow(db: DatabaseSyncLike, tenantId: string, memoryId: string): QuarantineRow | null;
-export declare function listQuarantineRows(db: DatabaseSyncLike, tenantId: string, status?: QuarantineStatus | 'all', limit?: number, afterRow?: KeysetPosition): QuarantineRow[];
-export declare function approveQuarantineRow(db: DatabaseSyncLike, tenantId: string, memoryId: string, decidedBy: string): void;
-export declare function rejectQuarantineRow(db: DatabaseSyncLike, tenantId: string, memoryId: string, decidedBy: string): void;
+/** A page of the tenant's records, each with its memory's content read in the same query batch. */
+export declare function listQuarantinedAt(db: DatabaseSyncLike, tenantId: string, { status, limit, after }: QuarantineListQuery): QuarantinedMemory[];
+/** Puts the memory back under its original scope; the scope guard refuses a row moved since it was quarantined. */
+export declare function approveQuarantinedAt(db: DatabaseSyncLike, tenantId: string, id: string, actor: string): QuarantineApproval;
+/** Marks the record rejected; the memory row is left as stored. */
+export declare function rejectQuarantinedAt(db: DatabaseSyncLike, tenantId: string, id: string, actor: string): QuarantineRejection;
 //# sourceMappingURL=quarantine.d.ts.map

package/dist/{quarantine.js → store/quarantine.js}

@@ -1,14 +1,13 @@
-/** Quarantine tier (CD5, AT3): pending/approved/rejected record for a memory `remember` flagged as untrusted. */
+// The memory_quarantine table: the review queue's rows, and the approve and reject writes with their audit rows.
 import { appendAuditEvent } from './audit.js';
-import { keysetAfter } from './keyset.js';
+import { withWriteScopeOr } from '../db/index.js';
+import { keysetAfter } from '../util/keyset.js';
+import { selectEntriesByIds } from './entry-reads.js';
 export const QUARANTINE_SCOPE_PREFIX = 'quarantine:private:';
 /** Scope a quarantined memory is stored under; matches PRIVATE_SCOPE_RE so every default-deny site hides it. */
 export function quarantineScopeFor(original) {
     return `${QUARANTINE_SCOPE_PREFIX}${original ?? 'unscoped'}`;
 }
-export function isQuarantineScope(scope) {
-    return scope != null && scope.startsWith(QUARANTINE_SCOPE_PREFIX);
-}
 const SELECT_COLUMNS = 'tenant_id, memory_id, original_scope, reason, status, quarantined_at, decided_at, decided_by';
 function fromDbRow(row) {
     return {
@@ -16,31 +15,19 @@ function fromDbRow(row) {
         memoryId: row.memory_id,
         originalScope: row.original_scope,
         reason: row.reason,
-        // SAFETY: this module's own INSERT/UPDATE statements are the only writers of status.
+        // SAFETY: the quarantine INSERT and this module's UPDATE statements are the only writers of status.
         status: row.status,
         quarantinedAt: row.quarantined_at,
         decidedAt: row.decided_at,
         decidedBy: row.decided_by,
     };
 }
-/** Insert the quarantine row + its audit event; caller runs this inside the memory's own write transaction. */
-export function recordQuarantine(db, opts) {
-    db.prepare(`INSERT INTO memory_quarantine (tenant_id, memory_id, original_scope, reason, status, quarantined_at)
-     VALUES (?, ?, ?, ?, 'pending', ?)`).run(opts.tenantId, opts.memoryId, opts.originalScope, opts.reason, new Date().toISOString());
-    appendAuditEvent(db, {
-        tenantId: opts.tenantId,
-        actor: opts.actor,
-        op: 'quarantine',
-        targetId: opts.memoryId,
-        metadata: { reason: opts.reason, originalScope: opts.originalScope },
-    });
-}
-export function getQuarantineRow(db, tenantId, memoryId) {
+function getQuarantineRow(db, tenantId, memoryId) {
     const row = db.prepare(`SELECT ${SELECT_COLUMNS} FROM memory_quarantine WHERE tenant_id = ? AND memory_id = ?`)
         .get(tenantId, memoryId);
     return row ? fromDbRow(row) : null;
 }
-export function listQuarantineRows(db, tenantId, status = 'pending', limit = 100, afterRow) {
+function listQuarantineRows(db, tenantId, status = 'pending', limit = 100, afterRow) {
     // A pending row whose memory was deleted (e.g. Slack message_deleted) is dead; keep its history, drop it from the queue.
     const live = status === 'pending'
         ? ' AND EXISTS (SELECT 1 FROM memories m WHERE m.id = memory_quarantine.memory_id AND m.tenant_id = memory_quarantine.tenant_id)'
@@ -55,12 +42,67 @@ export function listQuarantineRows(db, tenantId, status = 'pending', limit = 100
     // SAFETY: both branches select SELECT_COLUMNS, matching QuarantineDbRow's field set.
     return rows.map(fromDbRow);
 }
-export function approveQuarantineRow(db, tenantId, memoryId, decidedBy) {
+/** Insert the quarantine row + its audit event; caller runs this inside the memory's own write transaction. */
+export function recordQuarantine(db, opts) {
+    db.prepare(`INSERT INTO memory_quarantine (tenant_id, memory_id, original_scope, reason, status, quarantined_at)
+     VALUES (?, ?, ?, ?, 'pending', ?)`).run(opts.tenantId, opts.memoryId, opts.originalScope, opts.reason, new Date().toISOString());
+    appendAuditEvent(db, {
+        tenantId: opts.tenantId,
+        actor: opts.actor,
+        op: 'quarantine',
+        targetId: opts.memoryId,
+        metadata: { reason: opts.reason, originalScope: opts.originalScope },
+    });
+}
+function approveQuarantineRow(db, tenantId, memoryId, decidedBy) {
     db.prepare(`UPDATE memory_quarantine SET status = 'approved', decided_at = ?, decided_by = ? WHERE tenant_id = ? AND memory_id = ?`)
         .run(new Date().toISOString(), decidedBy, tenantId, memoryId);
 }
-export function rejectQuarantineRow(db, tenantId, memoryId, decidedBy) {
+function rejectQuarantineRow(db, tenantId, memoryId, decidedBy) {
     db.prepare(`UPDATE memory_quarantine SET status = 'rejected', decided_at = ?, decided_by = ? WHERE tenant_id = ? AND memory_id = ?`)
         .run(new Date().toISOString(), decidedBy, tenantId, memoryId);
 }
+/** A page of the tenant's records, each with its memory's content read in the same query batch. */
+export function listQuarantinedAt(db, tenantId, { status, limit, after }) {
+    const rows = listQuarantineRows(db, tenantId, status, limit, after);
+    const entries = selectEntriesByIds(db, rows.map((row) => row.memoryId), tenantId);
+    return rows.map((row) => ({ ...row, content: entries.get(row.memoryId)?.content ?? null }));
+}
+/** The pending record, or why a decision on `id` is refused. */
+function pendingOrRefusal(db, tenantId, id) {
+    const row = getQuarantineRow(db, tenantId, id);
+    if (!row)
+        return { outcome: 'not_quarantined' };
+    if (row.status !== 'pending')
+        return { outcome: 'already_decided', status: row.status };
+    return row;
+}
+/** Puts the memory back under its original scope; the scope guard refuses a row moved since it was quarantined. */
+export function approveQuarantinedAt(db, tenantId, id, actor) {
+    return withWriteScopeOr(db, 'quarantine_approve', (rollback) => {
+        const row = pendingOrRefusal(db, tenantId, id);
+        if ('outcome' in row)
+            return rollback(row);
+        const quarantineScope = quarantineScopeFor(row.originalScope);
+        const updated = db
+            .prepare(`UPDATE memories SET scope = ? WHERE id = ? AND tenant_id = ? AND scope = ?`)
+            .run(row.originalScope, id, tenantId, quarantineScope);
+        if (Number(updated.changes ?? 0) !== 1)
+            return rollback({ outcome: 'scope_moved' });
+        approveQuarantineRow(db, tenantId, id, actor);
+        appendAuditEvent(db, { tenantId, actor, op: 'quarantine_approve', targetId: id, metadata: { originalScope: row.originalScope } });
+        return { outcome: 'approved' };
+    });
+}
+/** Marks the record rejected; the memory row is left as stored. */
+export function rejectQuarantinedAt(db, tenantId, id, actor) {
+    return withWriteScopeOr(db, 'quarantine_reject', (rollback) => {
+        const row = pendingOrRefusal(db, tenantId, id);
+        if ('outcome' in row)
+            return rollback(row);
+        rejectQuarantineRow(db, tenantId, id, actor);
+        appendAuditEvent(db, { tenantId, actor, op: 'quarantine_reject', targetId: id, metadata: {} });
+        return { outcome: 'rejected' };
+    });
+}
 //# sourceMappingURL=quarantine.js.map

package/dist/store/raw-archive.d.ts

@@ -0,0 +1,14 @@
+import type { DatabaseSyncLike } from '../db/index.js';
+export interface ArchiveOpts {
+    reason: string;
+    who: string;
+    /** Hook run inside the archive SAVEPOINT after the audit row and before RELEASE (the Slack deletion connector marks the event seen atomically);
+     * throwing rolls back the whole archive, audit row included. */
+    afterArchive?: (db: DatabaseSyncLike, archivedMemoryId: string) => void;
+}
+/** Stamps the archived copy of `memoryId` as having its markdown mirror cleaned at `at`. */
+export declare function markMirrorCleaned(db: DatabaseSyncLike, memoryId: string, at: string): void;
+/** The only way to remove a `kind='raw'` row: snapshots it into `raw_archive`, flips `kind` to 'archived' so the append-only trigger allows the delete,
+ * all in one write scope that nests in an outer transaction. Throws if the row is missing or not raw; returns the archived_at. */
+export declare function archiveRawMemory(db: DatabaseSyncLike, id: string, opts: ArchiveOpts): string;
+//# sourceMappingURL=raw-archive.d.ts.map

package/dist/{raw-archive.js → store/raw-archive.js}

@@ -1,11 +1,15 @@
-import { BadRequestError, NotFoundError } from './api-errors.js';
-import { isFtsAvailable, withWriteScope } from './db.js';
+import { DEFAULT_TENANT_ID } from '../util/env.js';
+import { BadRequestError, NotFoundError } from '../core/api-errors.js';
+import { isFtsAvailable, withWriteScope } from '../db/index.js';
 import { appendAuditEvent, reportAuditWriteFailure } from './audit.js';
 import { markSummaryDirtyInTx } from './summary-dirty.js';
+/** Stamps the archived copy of `memoryId` as having its markdown mirror cleaned at `at`. */
+export function markMirrorCleaned(db, memoryId, at) {
+    db.prepare(`UPDATE raw_archive SET mirror_cleaned_at = ? WHERE memory_id = ?`).run(at, memoryId);
+}
 function loadRawRow(db, id) {
-    // SAFETY: SELECT * FROM memories returns every column of the memories table; only
-    // kind, tenant_id, and dag_parent_id are read below, all guaranteed present (possibly
-    // null) by the memories schema.
+    // SAFETY: SELECT * returns every memories column; only kind, tenant_id and dag_parent_id are read below, all guaranteed present (possibly null) by the
+    // schema.
     const row = db.prepare(`SELECT * FROM memories WHERE id = ?`).get(id);
     if (!row)
         throw new NotFoundError(`memory not found: ${id}`);
@@ -15,15 +19,13 @@ function loadRawRow(db, id) {
     return row;
 }
 function moveRowToArchive(db, id, row, opts) {
-    // GDPR: raw_archive stores ONLY metadata, not the original
-    // memory content. The audit_log row appended below carries op='archive_raw'
-    // for the compliance audit trail. True right-to-be-forgotten — the original
-    // content is unrecoverable from raw_archive after this point.
+    // GDPR: raw_archive stores ONLY metadata, never the original content; the archive_raw audit row is the compliance trail,
+    // so the content is unrecoverable from here on.
     const archivedAt = new Date().toISOString();
     const redactedPayload = JSON.stringify({
         redacted: true,
         archived_at: archivedAt,
-        tenant_id: row.tenant_id ?? 'default',
+        tenant_id: row.tenant_id ?? DEFAULT_TENANT_ID,
         kind: row.kind,
         reason: opts.reason,
     });
@@ -36,15 +38,12 @@ function moveRowToArchive(db, id, row, opts) {
         db.prepare(`DELETE FROM memories_fts WHERE id = ?`).run(id);
     return archivedAt;
 }
-// Emit the archive_raw audit event inside the SAVEPOINT so the audit row is
-// committed atomically with the row deletion. Use the row's own tenant_id
-// (fetched above as part of SELECT *), not the env. Archives must be
-// attributed to the tenant that owns the row, not whatever HIPPO_TENANT
-// happens to be set to in the calling shell.
+// Emit the archive_raw audit inside the SAVEPOINT so it commits atomically with the row deletion, attributed to the row's own tenant_id,
+// not whatever HIPPO_TENANT the calling shell has set.
 function auditArchive(db, id, row, opts) {
     try {
         appendAuditEvent(db, {
-            tenantId: String(row.tenant_id ?? 'default'),
+            tenantId: String(row.tenant_id ?? DEFAULT_TENANT_ID),
             actor: opts.who || 'cli',
             op: 'archive_raw',
             targetId: id,
@@ -56,15 +55,8 @@ function auditArchive(db, id, row, opts) {
         reportAuditWriteFailure('archive_raw', String(error), id);
     }
 }
-/**
- * The only legitimate path to remove a `kind='raw'` row from `memories`.
- *
- * Snapshots the full row into `raw_archive`, flips `kind` to `'archived'` so the
- * append-only trigger lets the delete through, then deletes the row. All in one
- * write scope, which nests inside an outer transaction (e.g. batchWriteAndDelete).
- *
- * Throws if the row does not exist or is not `kind='raw'`. Returns the archived_at it wrote.
- */
+/** The only way to remove a `kind='raw'` row: snapshots it into `raw_archive`, flips `kind` to 'archived' so the append-only trigger allows the delete,
+ * all in one write scope that nests in an outer transaction. Throws if the row is missing or not raw; returns the archived_at. */
 export function archiveRawMemory(db, id, opts) {
     const row = loadRawRow(db, id);
     // A SAVEPOINT when already inside a transaction (e.g. batchWriteAndDelete), so a throw here
@@ -75,13 +67,10 @@ export function archiveRawMemory(db, id, opts) {
         // Archiving a child under a level-2 summary marks the parent dirty, inside the
         // SAVEPOINT so the dirty-mark commits atomically with the archive.
         if (row.dag_parent_id) {
-            markSummaryDirtyInTx(db, String(row.dag_parent_id), String(row.tenant_id ?? 'default'), opts.who || 'cli');
+            markSummaryDirtyInTx(db, String(row.dag_parent_id), String(row.tenant_id ?? DEFAULT_TENANT_ID), opts.who || 'cli');
         }
-        // afterArchive hook: connector-level idempotency markers
-        // (e.g. slack_event_log) must commit atomically with the archive itself.
-        // Throwing here rolls back the entire SAVEPOINT — both the archive and any
-        // hook side effects. The hook runs INSIDE the SAVEPOINT so its writes
-        // share the archive's transactional fate.
+        // afterArchive hook: connector idempotency markers (e.g. slack_event_log) must commit atomically with the archive, so it runs INSIDE the SAVEPOINT;
+        // throwing rolls back both.
         if (opts.afterArchive) {
             opts.afterArchive(db, id);
         }

package/dist/store/recall-scope.d.ts

@@ -0,0 +1,78 @@
+/** Recall-side scope predicates, in a leaf module so search-both.ts can apply the same default-deny rule to searchBothHybrid's candidate loads without an
+ * import cycle. src/api/index.ts imports these and re-exports them for back-compat (`api.isPrivateScope`, tests importing `passesScopeFilterForRecall`). */
+import { ForbiddenError } from '../core/api-errors.js';
+/** Literal scopes excluded from recall by default-deny when the caller passes no `scope`; read by the SQL clause in `loadSearchRows` and by
+ * `passesScopeFilterForRecall`. Invariant: never empty, or quarantine scopes would pass both paths silently (the module-load assertion below pins this). */
+export declare const RECALL_DEFAULT_DENY_SCOPES: readonly ["unknown:legacy"];
+/** @internal Runtime guard against blanking a load-bearing literal array; `as const` arrays widen via `readonly T[]` at the call site, so the empty case
+ * is reachable and testable. */
+export declare function assertNonEmpty<T>(arr: readonly T[], name: string): void;
+/** Source-agnostic private-scope detector: private means `<lowercase-source>:private:<rest>` (`slack:private:Cabc`; not `slack:public:x`, null, '',
+ * 'private:foo'). The single source of truth for api.recall, the MCP server, the CLI and search-both.ts, so connector work cannot drift. */
+export declare const PRIVATE_SCOPE_RE: RegExp;
+/** True when `scope` matches the `<source>:private:*` shape. */
+export declare function isPrivateScope(scope: string | null | undefined): boolean;
+export declare const PERSONAL_SCOPE_PREFIX = "personal:private:";
+export declare const PERSONAL_OWNER_MAX: number;
+/** True for a `personal:private:<owner>` scope, any case, so a case variant is never mistaken for a team scope. */
+export declare function isPersonalScope(scope: string | null | undefined): boolean;
+/** The caller's own personal scope, or null when it has no owner that can hold one. */
+export declare function personalScopeOf(actor: {
+    owner?: string;
+} | undefined): string | null;
+/** Refuses a client-sent `personal:` scope: only the server stamps one, from the caller's owner. */
+export declare function assertClientScope(scope: string | null | undefined): void;
+/** True when `actor` may change or delete a row in `scope`: any non-personal scope, or its own personal one. */
+export declare function canTouchScope(actor: {
+    owner?: string;
+}, scope: string | null): boolean;
+/** canTouchScope for a caller known by its own personal scope, as a store method receives it. */
+export declare function ownScopeTouches(ownScope: string | null, scope: string | null): boolean;
+/** JS half of the recall default-deny rule (SQL half: `loadSearchRows`). A non-empty `requested` needs an exact match;
+ * otherwise `<source>:private:*` and `RECALL_DEFAULT_DENY_SCOPES` buckets are denied, while null, public scopes and the caller's `ownScope` pass. */
+export declare function passesScopeFilterForRecall(scope: string | null, requested: string | undefined, ownScope?: string | null): boolean;
+export interface SqlFragment {
+    sql: string;
+    params: string[];
+}
+/** SQL twin of the no-request arm of passesScopeFilterForRecall; `ownScope` is bound and compared with `=`, so `%` or `_` in an owner match nothing extra. */
+export declare function scopeAdmitSql(col: '' | 'm.', ownScope?: string | null): SqlFragment;
+/** SQL twin of canTouchScope, which is also canReadScope for an admin: every row but
+ * another person's personal one. LIKE folds ASCII case as isPersonalScope's /i does. */
+export declare function touchableScopeSql(col: '' | 'm.', ownScope?: string | null): SqlFragment;
+/** CLI `--scope` variant: an explicit `--scope X` UNLOCKS scope X on top of the default-admitted set rather than narrowing to X (api.recall keeps 'exact').
+ * Includes private/quarantine scopes (owner access); a named personal scope never unlocks: the CLI has no caller identity. */
+export declare function passesCliRecallScopeFilter(scope: string | null, requested: string | undefined): boolean;
+/** Thrown when a caller requests a scope its role may not read; the HTTP layer maps it to 403. */
+export declare class ScopeForbiddenError extends ForbiddenError {
+    readonly scope: string;
+    constructor(scope: string);
+}
+/** True for scopes default-deny hides (`<source>:private:*` and the quarantine buckets); naming one explicitly unlocks it, so naming one needs
+ * authorization. */
+export declare function isRestrictedScope(scope: string | null | undefined): boolean;
+/** The identity a scope check runs against: a role, any scope grants, and the person who owns the key. */
+export interface ScopeActor {
+    role: 'admin' | 'member';
+    scopes?: readonly string[];
+    owner?: string;
+}
+/** Personal rows answer to their owner alone: role, key grants and resolver scopes never
+ * open one. Else admin reads all; a member needs an exact grant on a restricted scope. */
+export declare function canReadScope(actor: ScopeActor, scope: string): boolean;
+/** Authorize an explicitly requested scope before any read honours it (member scope grants). */
+export declare function assertScopeRequestAllowed(actor: ScopeActor, requested: string | undefined): void;
+/** Scope a derived row keeps from one source: the restricted scope itself, else null. */
+export declare function derivationScope(scope: string | null | undefined): string | null;
+/** The one derivation scope shared by every source, or `{ ok: false }` when
+ *  two disagree, so the caller skips the derived row instead of under-scoping it. */
+export declare function commonDerivationScope(scopes: readonly (string | null | undefined)[]): {
+    ok: true;
+    scope: string | null;
+} | {
+    ok: false;
+};
+/** Map-partition key for consolidate/dag/dedup producers: tenant + derivation scope + origin project,
+ *  so a derived row never blends two restricted scopes, a mixed pair, or two projects. */
+export declare function derivationPartitionKey(tenantId: string, scope: string | null | undefined, origin: string | null | undefined): string;
+//# sourceMappingURL=recall-scope.d.ts.map