hippo-memory 1.71.0 → 2.0.0

package/dist/store/conflicts.js

@@ -2,15 +2,17 @@ import { DEFAULT_TENANT_ID } from '../util/env.js';
 import { closeHippoDb, withWriteScope } from '../db/index.js';
 import { rejectionDigest, insertRejectedValue, normalizeValueForRejection } from './rejection.js';
 import { archiveRawMemory } from './raw-archive.js';
-import { rowToMemoryConflict } from './rows.js';
+import { parseJsonArray, rowToMemoryConflict } from './rows.js';
 import { audit } from './audit-event.js';
 import { syncChangedMirrors, purgeMirrorBestEffort } from './mirrors.js';
-import { chunked, selectEntriesByIds } from './entry-reads.js';
+import { selectEntriesByIds } from './entry-reads.js';
+import { chunked } from '../util/chunked.js';
 import { onHandle, openStore } from './open.js';
 import { deleteEntryCore } from './delete-and-batch.js';
 import { BadRequestError } from '../core/api-errors.js';
-import { canTouchScope, isPersonalScope } from './recall-scope.js';
+import { canTouchScope, isPersonalScope } from '../core/recall-scope.js';
 import { selectMemoryReach } from './tenant-lookup.js';
+import { placeholders } from '../util/sql.js';
 // The one place MemoryConflictRow's columns are listed; CONFLICT_COLS_MC is the same list under the `mc` alias.
 const CONFLICT_COLS = 'id, memory_a_id, memory_b_id, reason, score, status, detected_at, updated_at';
 const CONFLICT_COLS_MC = CONFLICT_COLS.split(', ').map((c) => `mc.${c}`).join(', ');
@@ -131,7 +133,7 @@ function readConflictRefresh(db, detected) {
     }
     const given = [...new Set(detected.flatMap((c) => [c.memory_a_id, c.memory_b_id]))].filter((id) => !tenantById.has(id));
     for (const ids of chunked(given)) {
-        const marks = ids.map(() => '?').join(',');
+        const marks = placeholders(ids.length);
         // SAFETY: rows' shape matches the two columns named in the SELECT.
         const found = db.prepare(`SELECT id, tenant_id FROM memories WHERE id IN (${marks})`).all(...ids);
         for (const r of found)
@@ -252,7 +254,7 @@ function findResolvableConflict(db, conflictId, keepId, tenantId) {
 }
 /** Resolve a conflict by keeping one memory and halving the loser's half-life; `--forget` removes the loser, `opts.rejectLoserValue` also tombstones its
  * digest. Every path emits a `conflict_resolve` audit row. Returns the resolved conflict, or null if not found. */
-export function resolveConflict(hippoRoot, conflictId, keepId, forgetLoser = false, tenantId, opts) {
+export function resolveConflict(hippoRoot, { conflictId, keepId, forgetLoser = false, tenantId }, opts) {
     const db = openStore(hippoRoot);
     const scope = conflictMemScope(tenantId);
     try {
@@ -351,7 +353,8 @@ function recordRejectedLoserValue(db, t, loserRow, digest, who) {
 /** Tombstones the loser's digest and removes its same-tenant duplicates into `removal`; returns the digest. */
 function tombstoneLoserValue(db, t, loserRow, who, removal) {
     if (isPersonalScope(loserRow.scope)) {
-        throw new BadRequestError(`cannot reject the value of personal memory ${t.loserId}: a rejection reaches the whole tenant, so its reason would show to everyone; resolve with forget instead`);
+        throw new BadRequestError(`cannot reject the value of personal memory ${t.loserId}: a rejection reaches the whole tenant, ` +
+            `so its reason would show to everyone; resolve with forget instead`);
     }
     const { actor, reason } = who;
     const rejectedDigest = rejectionDigest(loserRow.content);
@@ -387,7 +390,7 @@ function stripConflictRefs(db, t, loserRemoved) {
     // SAFETY: keepRow's shape matches the single `conflicts_with_json` column selected above.
     const keepRow = db.prepare(`SELECT conflicts_with_json FROM memories WHERE id = ?${memScope}`).get(keepId, ...memArgs);
     if (keepRow) {
-        const refs = JSON.parse(keepRow.conflicts_with_json || '[]');
+        const refs = parseJsonArray(keepRow.conflicts_with_json, { table: 'memories', id: keepId, column: 'conflicts_with_json' });
         const cleaned = refs.filter((r) => r !== loserId);
         db.prepare(`UPDATE memories SET conflicts_with_json = ?, updated_at = datetime('now') WHERE id = ?${memScope}`)
             .run(JSON.stringify(cleaned), keepId, ...memArgs);
@@ -397,7 +400,7 @@ function stripConflictRefs(db, t, loserRemoved) {
         // column named in the SELECT below.
         const loserRow = db.prepare(`SELECT conflicts_with_json FROM memories WHERE id = ?${memScope}`).get(loserId, ...memArgs);
         if (loserRow) {
-            const refs = JSON.parse(loserRow.conflicts_with_json || '[]');
+            const refs = parseJsonArray(loserRow.conflicts_with_json, { table: 'memories', id: loserId, column: 'conflicts_with_json' });
             const cleaned = refs.filter((r) => r !== keepId);
             db.prepare(`UPDATE memories SET conflicts_with_json = ?, updated_at = datetime('now') WHERE id = ?${memScope}`)
                 .run(JSON.stringify(cleaned), loserId, ...memArgs);
@@ -438,7 +441,8 @@ function purgeRemovedLoserMirrors(hippoRoot, db, loserId, removal) {
 /** The conflict and loser ids every conflict_resolve audit row names. */
 export function conflictResolveAuditsAt(db) {
     // SAFETY: SELECT of two fields every conflict_resolve audit row carries (ConflictResolveMeta above).
-    return db.prepare(`SELECT json_extract(metadata_json, '$.conflictId') AS conflictId, json_extract(metadata_json, '$.loserId') AS loserId FROM audit_log WHERE op = 'conflict_resolve'`).all();
+    return db.prepare(`SELECT json_extract(metadata_json, '$.conflictId') AS conflictId, json_extract(metadata_json, '$.loserId') AS loserId ` +
+        `FROM audit_log WHERE op = 'conflict_resolve'`).all();
 }
 /** Every resolved conflict with both sides. */
 export function resolvedConflictsAt(db) {

package/dist/store/connectors/dlq.d.ts

@@ -0,0 +1,10 @@
+import type { DatabaseSyncLike } from '../../db/index.js';
+export type DlqTable = 'slack_dlq' | 'github_dlq';
+export type DlqRawValue = string | number | bigint | null;
+export type DlqRawRow = Record<string, DlqRawValue>;
+/** Inserts one row, stamping received_at; `columns` pairs each column name with its value, in insert order. */
+export declare function insertDlqRow(db: DatabaseSyncLike, table: DlqTable, columns: ReadonlyArray<readonly [string, string | null]>): number;
+export declare function listDlqRows(db: DatabaseSyncLike, table: DlqTable, selectColumns: string, tenantId: string, limit: number): DlqRawRow[];
+export declare function getDlqRow(db: DatabaseSyncLike, table: DlqTable, selectColumns: string, id: number): DlqRawRow | null;
+export declare function markDlqRetried(db: DatabaseSyncLike, table: DlqTable, id: number): void;
+//# sourceMappingURL=dlq.d.ts.map

package/dist/store/connectors/dlq.js

@@ -0,0 +1,33 @@
+// The dead-letter statements both connectors share; each connector names its table and columns and maps rows to its own item type.
+import { placeholders } from '../../util/sql.js';
+/** Inserts one row, stamping received_at; `columns` pairs each column name with its value, in insert order. */
+export function insertDlqRow(db, table, columns) {
+    const names = [...columns.map(([name]) => name), 'received_at'];
+    const values = [...columns.map(([, value]) => value), new Date().toISOString()];
+    const result = db
+        .prepare(`INSERT INTO ${table} (${names.join(', ')}) VALUES (${placeholders(names.length)})`)
+        .run(...values);
+    return Number(result.lastInsertRowid);
+}
+export function listDlqRows(db, table, selectColumns, tenantId, limit) {
+    // SAFETY: the caller's selectColumns names exactly the fields its rowToItem reads.
+    return db
+        .prepare(`SELECT ${selectColumns}
+         FROM ${table}
+        WHERE tenant_id = ?
+        ORDER BY received_at ASC
+        LIMIT ?`)
+        .all(tenantId, limit);
+}
+export function getDlqRow(db, table, selectColumns, id) {
+    // SAFETY: the caller's selectColumns names exactly the fields its rowToItem reads.
+    const row = db
+        .prepare(`SELECT ${selectColumns} FROM ${table} WHERE id = ?`)
+        .get(id);
+    return row ?? null;
+}
+export function markDlqRetried(db, table, id) {
+    db.prepare(`UPDATE ${table} SET retried_at = ?, retry_count = retry_count + 1 WHERE id = ?`)
+        .run(new Date().toISOString(), id);
+}
+//# sourceMappingURL=dlq.js.map

package/dist/store/connectors/event-log.d.ts

@@ -0,0 +1,13 @@
+import type { DatabaseSyncLike } from '../../db/index.js';
+import type { ConnectorEventRecord } from '../port.js';
+/** Which log table a connector writes and the column its dedupe key lives in. */
+export interface EventLogSpec {
+    readonly table: 'slack_event_log' | 'github_event_log';
+    readonly keyColumn: 'event_id' | 'idempotency_key';
+}
+export declare function eventSeenAt(db: DatabaseSyncLike, log: EventLogSpec, key: string): boolean;
+export declare function eventMemoryAt(db: DatabaseSyncLike, log: EventLogSpec, key: string): string | null;
+/** Records the key unless a row holds it already; false means another writer got there first. `extra` pairs connector-only columns with values. */
+export declare function markEventSeenAt(db: DatabaseSyncLike, log: EventLogSpec, key: string, extra: ReadonlyArray<readonly [string, string]>, memoryId: string | null): boolean;
+export declare function eventRecord(hippoRoot: string, log: EventLogSpec, key: string): ConnectorEventRecord;
+//# sourceMappingURL=event-log.d.ts.map

package/dist/store/connectors/event-log.js

@@ -0,0 +1,24 @@
+// The event-log statements both connectors share; each connector names its table, key column and extra columns.
+import { placeholders } from '../../util/sql.js';
+import { onHandle } from '../open.js';
+export function eventSeenAt(db, log, key) {
+    return !!db.prepare(`SELECT 1 FROM ${log.table} WHERE ${log.keyColumn} = ?`).get(key);
+}
+export function eventMemoryAt(db, log, key) {
+    // SAFETY: the SELECT projects only `memory_id`, a nullable column; .get() returns undefined when no row matches.
+    const row = db.prepare(`SELECT memory_id FROM ${log.table} WHERE ${log.keyColumn} = ?`).get(key);
+    return row?.memory_id ?? null;
+}
+/** Records the key unless a row holds it already; false means another writer got there first. `extra` pairs connector-only columns with values. */
+export function markEventSeenAt(db, log, key, extra, memoryId) {
+    const names = [log.keyColumn, ...extra.map(([name]) => name), 'ingested_at', 'memory_id'];
+    const values = [key, ...extra.map(([, value]) => value), new Date().toISOString(), memoryId];
+    const inserted = db
+        .prepare(`INSERT OR IGNORE INTO ${log.table} (${names.join(', ')}) VALUES (${placeholders(names.length)})`)
+        .run(...values);
+    return Number(inserted.changes ?? 0) !== 0;
+}
+export function eventRecord(hippoRoot, log, key) {
+    return onHandle(hippoRoot, (db) => eventSeenAt(db, log, key) ? { seen: true, memoryId: eventMemoryAt(db, log, key) } : { seen: false });
+}
+//# sourceMappingURL=event-log.js.map

package/dist/store/connectors/github.d.ts

@@ -1,4 +1,5 @@
 import { type DatabaseSyncLike } from '../../db/index.js';
+import type { ConnectorEventRecord } from '../port.js';
 /** One github_event_log row to write; `memoryId` is null for an event that produced no memory. */
 export interface GitHubEventLogEntry {
     idempotencyKey: string;
@@ -6,15 +7,12 @@ export interface GitHubEventLogEntry {
     eventName: string;
     memoryId: string | null;
 }
-export declare function eventSeenAt(db: DatabaseSyncLike, idempotencyKey: string): boolean;
-export declare function eventMemoryAt(db: DatabaseSyncLike, idempotencyKey: string): string | null;
+export declare function githubEventSeenAt(db: DatabaseSyncLike, idempotencyKey: string): boolean;
+export declare function githubEventMemoryAt(db: DatabaseSyncLike, idempotencyKey: string): string | null;
 /** False when the key was already logged, so a caller inside a write scope can roll its own row back. */
-export declare function logEventAt(db: DatabaseSyncLike, entry: GitHubEventLogEntry): boolean;
-/** The memory an already-seen key points at, or null when the key is new. */
-export declare function seenEvent(hippoRoot: string, idempotencyKey: string): {
-    memoryId: string | null;
-} | null;
-export declare function logEvent(hippoRoot: string, entry: GitHubEventLogEntry): void;
+export declare function markGitHubEventSeenAt(db: DatabaseSyncLike, entry: GitHubEventLogEntry): boolean;
+export declare function githubEventRecord(hippoRoot: string, idempotencyKey: string): ConnectorEventRecord;
+export declare function markGitHubEventSeen(hippoRoot: string, entry: GitHubEventLogEntry): void;
 export interface ArtifactDeletion {
     tenantId: string;
     artifactRef: string;
@@ -60,7 +58,7 @@ export interface GitHubDlqInsert {
 export declare function insertGitHubDlq(hippoRoot: string, row: GitHubDlqInsert): number;
 export declare function listGitHubDlq(hippoRoot: string, tenantId: string, limit: number): DlqItem[];
 export declare function githubDlqEntry(hippoRoot: string, id: number): DlqItem | null;
-export declare function bumpGitHubDlqRetryCount(hippoRoot: string, id: number): void;
+export declare function markGitHubDlqRetried(hippoRoot: string, id: number): void;
 /** What the routing tables say about one webhook; `tenant` is the installation match, or the repo match when no installation was sent. */
 export interface GitHubRouting {
     installations: number;

package/dist/store/connectors/github.js

@@ -2,31 +2,29 @@
 import { withWriteScope } from '../../db/index.js';
 import { archiveRawMemory } from '../raw-archive.js';
 import { onHandle } from '../open.js';
-export function eventSeenAt(db, idempotencyKey) {
-    const row = db.prepare(`SELECT 1 FROM github_event_log WHERE idempotency_key = ?`).get(idempotencyKey);
-    return !!row;
+import { eventMemoryAt, eventRecord, eventSeenAt, markEventSeenAt } from './event-log.js';
+import { getDlqRow, insertDlqRow, listDlqRows, markDlqRetried } from './dlq.js';
+const GITHUB_LOG = { table: 'github_event_log', keyColumn: 'idempotency_key' };
+export function githubEventSeenAt(db, idempotencyKey) {
+    return eventSeenAt(db, GITHUB_LOG, idempotencyKey);
 }
-export function eventMemoryAt(db, idempotencyKey) {
-    // SAFETY: the SELECT projects exactly the memory_id column of github_event_log.
-    const row = db.prepare(`SELECT memory_id FROM github_event_log WHERE idempotency_key = ?`).get(idempotencyKey);
-    return row?.memory_id ?? null;
+export function githubEventMemoryAt(db, idempotencyKey) {
+    return eventMemoryAt(db, GITHUB_LOG, idempotencyKey);
 }
 /** False when the key was already logged, so a caller inside a write scope can roll its own row back. */
-export function logEventAt(db, entry) {
-    const inserted = db.prepare(`INSERT OR IGNORE INTO github_event_log (idempotency_key, delivery_id, event_name, ingested_at, memory_id) VALUES (?, ?, ?, ?, ?)`).run(entry.idempotencyKey, entry.deliveryId, entry.eventName, new Date().toISOString(), entry.memoryId);
-    return Number(inserted.changes ?? 0) !== 0;
+export function markGitHubEventSeenAt(db, entry) {
+    return markEventSeenAt(db, GITHUB_LOG, entry.idempotencyKey, [['delivery_id', entry.deliveryId], ['event_name', entry.eventName]], entry.memoryId);
 }
-/** The memory an already-seen key points at, or null when the key is new. */
-export function seenEvent(hippoRoot, idempotencyKey) {
-    return onHandle(hippoRoot, (db) => eventSeenAt(db, idempotencyKey) ? { memoryId: eventMemoryAt(db, idempotencyKey) } : null);
+export function githubEventRecord(hippoRoot, idempotencyKey) {
+    return eventRecord(hippoRoot, GITHUB_LOG, idempotencyKey);
 }
-export function logEvent(hippoRoot, entry) {
-    onHandle(hippoRoot, (db) => { logEventAt(db, entry); });
+export function markGitHubEventSeen(hippoRoot, entry) {
+    onHandle(hippoRoot, (db) => { markGitHubEventSeenAt(db, entry); });
 }
 /** Archives every active raw row of one tenant's artifact and logs the delete event; a failed archive rolls back the batch and the log row. */
 export function archiveDeletedArtifact(hippoRoot, del) {
     return onHandle(hippoRoot, (db) => {
-        if (eventSeenAt(db, del.idempotencyKey))
+        if (githubEventSeenAt(db, del.idempotencyKey))
             return { duplicate: true, archived: 0 };
         const logged = { idempotencyKey: del.idempotencyKey, deliveryId: del.deliveryId, eventName: del.eventName };
         // SAFETY: the SELECT projects only the `id` column.
@@ -36,29 +34,17 @@ export function archiveDeletedArtifact(hippoRoot, del) {
         const memoryIds = rows.map((r) => r.id);
         if (memoryIds.length === 0) {
             // Still logged, so a retry of the same delete answers 'duplicate'.
-            logEventAt(db, { ...logged, memoryId: null });
+            markGitHubEventSeenAt(db, { ...logged, memoryId: null });
             return { duplicate: false, archived: 0 };
         }
         withWriteScope(db, 'github_delete_all', () => {
             for (const id of memoryIds)
                 archiveRawMemory(db, id, { reason: del.reason, who: del.who });
-            logEventAt(db, { ...logged, memoryId: memoryIds[0] });
+            markGitHubEventSeenAt(db, { ...logged, memoryId: memoryIds[0] });
         });
         return { duplicate: false, archived: memoryIds.length };
     });
 }
-function insertGitHubDlqAt(db, row) {
-    const result = db
-        .prepare(`INSERT INTO github_dlq
-        (tenant_id, raw_payload, error, event_name, delivery_id, signature,
-         installation_id, repo_full_name, received_at, bucket)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
-        .run(row.tenantId, row.rawPayload, row.error, row.eventName ?? null, row.deliveryId ?? null, row.signature, row.installationId ?? null, row.repoFullName ?? null, new Date().toISOString(), row.bucket);
-    return Number(result.lastInsertRowid);
-}
-export function insertGitHubDlq(hippoRoot, row) {
-    return onHandle(hippoRoot, (db) => insertGitHubDlqAt(db, row));
-}
 const SELECT_COLUMNS = `id, tenant_id, raw_payload, error, event_name, delivery_id,
             signature, installation_id, repo_full_name, retry_count,
             received_at, retried_at, bucket`;
@@ -79,42 +65,31 @@ function rowToItem(r) {
         bucket: r.bucket == null ? 'parse_error' : String(r.bucket),
     };
 }
-function listGitHubDlqAt(db, tenantId, limit) {
-    // SAFETY: SELECT_COLUMNS projects exactly DlqRawRow's fields.
-    const rows = db
-        .prepare(`SELECT ${SELECT_COLUMNS}
-         FROM github_dlq
-        WHERE tenant_id = ?
-        ORDER BY received_at ASC
-        LIMIT ?`)
-        .all(tenantId, limit);
-    return rows.map(rowToItem);
+export function insertGitHubDlq(hippoRoot, row) {
+    return onHandle(hippoRoot, (db) => insertDlqRow(db, 'github_dlq', [
+        ['tenant_id', row.tenantId],
+        ['raw_payload', row.rawPayload],
+        ['error', row.error],
+        ['event_name', row.eventName ?? null],
+        ['delivery_id', row.deliveryId ?? null],
+        ['signature', row.signature],
+        ['installation_id', row.installationId ?? null],
+        ['repo_full_name', row.repoFullName ?? null],
+        ['bucket', row.bucket],
+    ]));
 }
 export function listGitHubDlq(hippoRoot, tenantId, limit) {
-    return onHandle(hippoRoot, (db) => listGitHubDlqAt(db, tenantId, limit));
-}
-function githubDlqEntryAt(db, id) {
-    // SAFETY: SELECT_COLUMNS projects exactly DlqRawRow's fields.
-    const row = db
-        .prepare(`SELECT ${SELECT_COLUMNS}
-         FROM github_dlq
-        WHERE id = ?`)
-        .get(id);
-    if (!row)
-        return null;
-    return rowToItem(row);
+    return onHandle(hippoRoot, (db) => listDlqRows(db, 'github_dlq', SELECT_COLUMNS, tenantId, limit).map(rowToItem));
 }
 export function githubDlqEntry(hippoRoot, id) {
-    return onHandle(hippoRoot, (db) => githubDlqEntryAt(db, id));
-}
-export function bumpGitHubDlqRetryCount(hippoRoot, id) {
-    onHandle(hippoRoot, (db) => {
-        db.prepare(`UPDATE github_dlq
-          SET retry_count = retry_count + 1,
-              retried_at = ?
-        WHERE id = ?`).run(new Date().toISOString(), id);
+    return onHandle(hippoRoot, (db) => {
+        const row = getDlqRow(db, 'github_dlq', SELECT_COLUMNS, id);
+        return row ? rowToItem(row) : null;
     });
 }
+export function markGitHubDlqRetried(hippoRoot, id) {
+    onHandle(hippoRoot, (db) => markDlqRetried(db, 'github_dlq', id));
+}
 export function githubRouting(hippoRoot, args) {
     return onHandle(hippoRoot, (db) => {
         // SAFETY: the SELECT projects exactly one column, `c`, as a COUNT(*).

package/dist/store/connectors/slack.d.ts

@@ -1,4 +1,5 @@
 import type { DatabaseSyncLike } from '../../db/index.js';
+import type { ConnectorEventRecord } from '../port.js';
 export declare function slackCursorAt(db: DatabaseSyncLike, tenantId: string, channelId: string): string | null;
 export declare function saveSlackCursorAt(db: DatabaseSyncLike, tenantId: string, channelId: string, latestTs: string): void;
 export declare function slackCursor(hippoRoot: string, tenantId: string, channelId: string): string | null;
@@ -7,14 +8,7 @@ export declare function slackEventSeenAt(db: DatabaseSyncLike, eventId: string):
 /** Records the event unless a row already holds its id; false means another writer got there first. */
 export declare function markSlackEventSeenAt(db: DatabaseSyncLike, eventId: string, memoryId: string | null): boolean;
 export declare function slackEventMemoryAt(db: DatabaseSyncLike, eventId: string): string | null;
-/** What the event log holds for one event id; `memoryId` is null for an event seen without a memory. */
-export type SlackEventRecord = {
-    seen: false;
-} | {
-    seen: true;
-    memoryId: string | null;
-};
-export declare function slackEventRecord(hippoRoot: string, eventId: string): SlackEventRecord;
+export declare function slackEventRecord(hippoRoot: string, eventId: string): ConnectorEventRecord;
 export declare function markSlackEventSeen(hippoRoot: string, eventId: string, memoryId: string | null): void;
 /** The raw memory a Slack message became. The tenant filter keeps one tenant's deletion from reaching another's row with the same ref. */
 export declare function rawMemoryIdForArtifactAt(db: DatabaseSyncLike, artifactRef: string, tenantId: string): string | null;
@@ -42,13 +36,10 @@ export interface SlackDlqInsert {
     signature: string | null;
     slackTimestamp?: string | null;
 }
-/** Counts a failed replay and leaves `retried_at` alone, so the row still reads as never drained. */
-export declare function bumpSlackDlqRetryCountAt(db: DatabaseSyncLike, id: number): void;
 export declare function insertSlackDlq(hippoRoot: string, row: SlackDlqInsert): number;
 export declare function listSlackDlq(hippoRoot: string, tenantId: string, limit: number): DlqItem[];
 export declare function slackDlqEntry(hippoRoot: string, id: number): DlqItem | null;
 export declare function markSlackDlqRetried(hippoRoot: string, id: number): void;
-export declare function bumpSlackDlqRetryCount(hippoRoot: string, id: number): void;
 /** The tenant a team maps to, or how many workspaces are registered when it maps to none. */
 export type SlackTeamRoute = {
     tenantId: string;

package/dist/store/connectors/slack.js

@@ -1,6 +1,8 @@
 // Every statement the Slack connector runs on hippo.db: backfill cursors, the event log, the dead-letter queue and workspace routing.
 // `xAt(db, ...)` runs on the caller's handle; the same name without `At` opens hippo.db for that one call.
 import { onHandle } from '../open.js';
+import { eventMemoryAt, eventRecord, eventSeenAt, markEventSeenAt } from './event-log.js';
+import { getDlqRow, insertDlqRow, listDlqRows, markDlqRetried } from './dlq.js';
 // Backfill cursors
 export function slackCursorAt(db, tenantId, channelId) {
     // SAFETY: the SELECT names the single `latest_ts` column; sqlite returns undefined when no row matches.
@@ -20,24 +22,19 @@ export function saveSlackCursor(hippoRoot, tenantId, channelId, latestTs) {
     onHandle(hippoRoot, (db) => saveSlackCursorAt(db, tenantId, channelId, latestTs));
 }
 // Event log
+const SLACK_LOG = { table: 'slack_event_log', keyColumn: 'event_id' };
 export function slackEventSeenAt(db, eventId) {
-    const row = db.prepare(`SELECT 1 FROM slack_event_log WHERE event_id = ?`).get(eventId);
-    return !!row;
+    return eventSeenAt(db, SLACK_LOG, eventId);
 }
 /** Records the event unless a row already holds its id; false means another writer got there first. */
 export function markSlackEventSeenAt(db, eventId, memoryId) {
-    const inserted = db
-        .prepare(`INSERT OR IGNORE INTO slack_event_log (event_id, ingested_at, memory_id) VALUES (?, ?, ?)`)
-        .run(eventId, new Date().toISOString(), memoryId);
-    return Number(inserted.changes ?? 0) !== 0;
+    return markEventSeenAt(db, SLACK_LOG, eventId, [], memoryId);
 }
 export function slackEventMemoryAt(db, eventId) {
-    // SAFETY: the SELECT names only `memory_id`, a nullable column; .get() returns undefined when no row matches.
-    const row = db.prepare(`SELECT memory_id FROM slack_event_log WHERE event_id = ?`).get(eventId);
-    return row?.memory_id ?? null;
+    return eventMemoryAt(db, SLACK_LOG, eventId);
 }
 export function slackEventRecord(hippoRoot, eventId) {
-    return onHandle(hippoRoot, (db) => slackEventSeenAt(db, eventId) ? { seen: true, memoryId: slackEventMemoryAt(db, eventId) } : { seen: false });
+    return eventRecord(hippoRoot, SLACK_LOG, eventId);
 }
 export function markSlackEventSeen(hippoRoot, eventId, memoryId) {
     onHandle(hippoRoot, (db) => markSlackEventSeenAt(db, eventId, memoryId));
@@ -51,6 +48,8 @@ export function rawMemoryIdForArtifactAt(db, artifactRef, tenantId) {
         .get(artifactRef, tenantId);
     return row?.id ?? null;
 }
+const SELECT_COLUMNS = `id, tenant_id, team_id, raw_payload, error, received_at, retried_at,
+              bucket, retry_count, signature, slack_timestamp`;
 function rowToItem(r) {
     return {
         id: Number(r.id),
@@ -66,60 +65,28 @@ function rowToItem(r) {
         slackTimestamp: r.slack_timestamp == null ? null : String(r.slack_timestamp),
     };
 }
-function insertSlackDlqAt(db, row) {
-    const result = db
-        .prepare(`INSERT INTO slack_dlq
-        (tenant_id, team_id, raw_payload, error, received_at, bucket, signature, slack_timestamp)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`)
-        .run(row.tenantId, row.teamId ?? null, row.rawPayload, row.error, new Date().toISOString(), row.bucket, row.signature, row.slackTimestamp ?? null);
-    return Number(result.lastInsertRowid);
-}
-function listSlackDlqAt(db, tenantId, limit) {
-    // SAFETY: row shape matches the columns named in the SELECT below.
-    const rows = db
-        .prepare(`SELECT id, tenant_id, team_id, raw_payload, error, received_at, retried_at,
-              bucket, retry_count, signature, slack_timestamp
-         FROM slack_dlq
-        WHERE tenant_id = ?
-        ORDER BY received_at ASC
-        LIMIT ?`)
-        .all(tenantId, limit);
-    return rows.map(rowToItem);
-}
-function slackDlqEntryAt(db, id) {
-    // SAFETY: row shape matches the columns named in the SELECT below.
-    const row = db
-        .prepare(`SELECT id, tenant_id, team_id, raw_payload, error, received_at, retried_at,
-              bucket, retry_count, signature, slack_timestamp
-         FROM slack_dlq
-        WHERE id = ?`)
-        .get(id);
-    if (!row)
-        return null;
-    return rowToItem(row);
-}
-function markSlackDlqRetriedAt(db, id) {
-    db.prepare(`UPDATE slack_dlq SET retried_at = ?, retry_count = retry_count + 1 WHERE id = ?`)
-        .run(new Date().toISOString(), id);
-}
-/** Counts a failed replay and leaves `retried_at` alone, so the row still reads as never drained. */
-export function bumpSlackDlqRetryCountAt(db, id) {
-    db.prepare(`UPDATE slack_dlq SET retry_count = retry_count + 1 WHERE id = ?`).run(id);
-}
 export function insertSlackDlq(hippoRoot, row) {
-    return onHandle(hippoRoot, (db) => insertSlackDlqAt(db, row));
+    return onHandle(hippoRoot, (db) => insertDlqRow(db, 'slack_dlq', [
+        ['tenant_id', row.tenantId],
+        ['team_id', row.teamId ?? null],
+        ['raw_payload', row.rawPayload],
+        ['error', row.error],
+        ['bucket', row.bucket],
+        ['signature', row.signature],
+        ['slack_timestamp', row.slackTimestamp ?? null],
+    ]));
 }
 export function listSlackDlq(hippoRoot, tenantId, limit) {
-    return onHandle(hippoRoot, (db) => listSlackDlqAt(db, tenantId, limit));
+    return onHandle(hippoRoot, (db) => listDlqRows(db, 'slack_dlq', SELECT_COLUMNS, tenantId, limit).map(rowToItem));
 }
 export function slackDlqEntry(hippoRoot, id) {
-    return onHandle(hippoRoot, (db) => slackDlqEntryAt(db, id));
+    return onHandle(hippoRoot, (db) => {
+        const row = getDlqRow(db, 'slack_dlq', SELECT_COLUMNS, id);
+        return row ? rowToItem(row) : null;
+    });
 }
 export function markSlackDlqRetried(hippoRoot, id) {
-    onHandle(hippoRoot, (db) => markSlackDlqRetriedAt(db, id));
-}
-export function bumpSlackDlqRetryCount(hippoRoot, id) {
-    onHandle(hippoRoot, (db) => bumpSlackDlqRetryCountAt(db, id));
+    onHandle(hippoRoot, (db) => markDlqRetried(db, 'slack_dlq', id));
 }
 export function slackTeamRouteAt(db, teamId) {
     // SAFETY: the SELECT names only `tenant_id`; .get() returns undefined when no row matches.

package/dist/store/dashboard-reads.js

@@ -8,7 +8,9 @@ import { storedVectorIds } from '../db/vector-store.js';
 import { onHandle, openStore } from './open.js';
 import { QUARANTINE_SCOPE_PREFIX } from './quarantine.js';
 import { parseJsonArray } from './rows.js';
-const LIVE_COLUMNS = 'id, created, last_retrieved, retrieval_count, half_life_days, layer, tags_json, emotional_valence, outcome_positive, outcome_negative, pinned, confidence, content, superseded_by, kind, scope, origin_project';
+// Full content stays: dashboard-snapshot's Fact.lower serves search over the whole text, so a preview would change which rows match.
+const LIVE_COLUMNS = 'id, created, last_retrieved, retrieval_count, half_life_days, layer, tags_json, emotional_valence, outcome_positive, ' +
+    'outcome_negative, pinned, confidence, content, superseded_by, kind, scope, origin_project';
 // SQL twins of isQuarantineScope and of the two halves of isLiveMemory; substr compares bytes, as startsWith does, where LIKE would fold case.
 const QUARANTINED = `(scope IS NOT NULL AND substr(scope, 1, ${QUARANTINE_SCOPE_PREFIX.length}) = '${QUARANTINE_SCOPE_PREFIX}')`;
 const SUPERSEDED_BY = `(superseded_by IS NOT NULL AND superseded_by <> '')`;
@@ -44,11 +46,11 @@ export function loadDashboardRows(hippoRoot, tenantId) {
             // SAFETY: the SELECT names exactly LiveRow's columns.
             const live = db.prepare(`SELECT ${LIVE_COLUMNS} FROM memories WHERE tenant_id = ? AND ${LIVE} ORDER BY created ASC, id ASC`).all(tenantId);
             // SAFETY: the SELECT names exactly these two fields, and `why` is one of the three CASE arms or NULL.
-            const counts = db.prepare(`
-        SELECT CASE WHEN ${QUARANTINED} THEN 'quarantined' WHEN ${SUPERSEDED_BY} OR ${KIND} = 'superseded' THEN 'superseded' WHEN ${KIND} = 'archived' THEN 'archived' END AS why,
-               COUNT(*) AS n
-        FROM memories WHERE tenant_id = ? AND NOT (${LIVE}) GROUP BY why
-      `).all(tenantId);
+            const counts = db.prepare(`\n        SELECT CASE WHEN ${QUARANTINED} THEN 'quarantined' ` +
+                `WHEN ${SUPERSEDED_BY} OR ${KIND} = 'superseded' THEN 'superseded' ` +
+                `WHEN ${KIND} = 'archived' THEN 'archived' END AS why,\n` +
+                `               COUNT(*) AS n\n` +
+                `        FROM memories WHERE tenant_id = ? AND NOT (${LIVE}) GROUP BY why\n      `).all(tenantId);
             const excluded = { superseded: 0, archived: 0, quarantined: 0 };
             for (const { why, n } of counts)
                 if (why !== null)

package/dist/store/delete-and-batch.d.ts

@@ -26,6 +26,12 @@ export declare function deleteEntry(hippoRoot: string, id: string, opts?: {
     reason?: string;
     automatic?: boolean;
 }): boolean;
+/** deleteEntry with `automatic` for each removal and its own forget row and reason, all in one transaction after one read of the id set.
+ *  Returns the ids deleted, in `removals` order; a missing, repeated, pinned, raw or object-backing id is left out. */
+export declare function deleteEntriesAutomatically(hippoRoot: string, removals: readonly {
+    id: string;
+    reason: string;
+}[], actor: string): string[];
 /** Each row as the caller loaded it, by id; a `ReadonlyMap` fits. */
 export type LoadedRows = Pick<ReadonlyMap<string, MemoryEntry>, 'get'>;
 /** Writes, deletes and dormant moves in one transaction. With `snapshot`, a write keeps only the fields the caller changed and never resurrects a gone row.

package/dist/store/delete-and-batch.js

@@ -2,7 +2,8 @@ import { DEFAULT_TENANT_ID } from '../util/env.js';
 import { RawAppendOnlyError } from '../core/raw-append-only.js';
 import { AUTO_DELETABLE_SQL } from './rule-sql.js';
 import { closeHippoDb, withWriteScope } from '../db/index.js';
-import { checkRejectionGuard, RejectedValueError } from './rejection.js';
+import { checkRejectionGuard } from './rejection.js';
+import { RejectedValueError } from '../core/api-errors.js';
 import { markSummaryDirtyInTx } from './summary-dirty.js';
 import { insertDormantRow } from './dormant.js';
 import { log } from '../util/log.js';
@@ -12,6 +13,8 @@ import { deleteFtsRow, replaceFtsRows, stampOriginProject, upsertMemoryRow } fro
 import { purgeMirrorBestEffort, mirrorBestEffort, writeMarkdownMirror } from './mirrors.js';
 import { onHandle, openStore } from './open.js';
 import { clock } from '../util/write-budget.js';
+import { chunked } from '../util/chunked.js';
+import { placeholders } from '../util/sql.js';
 /** Tables whose rows keep a first-class object's backing memory in `memory_id` (ON DELETE SET NULL); tests/dormant-memories.test.ts pins it to the schema. */
 export const MEMORY_BACKED_TABLES = ['predictions', 'decisions', 'incidents', 'processes', 'policies', 'skills', 'project_briefs', 'customer_notes'];
 /** Deleting a memory that backs an object nulls the object's link, and no restore can repair it, so no automatic pass may. */
@@ -61,8 +64,10 @@ export function deleteEntryCore(db, id, opts) {
     const row = db
         .prepare(`SELECT id, tenant_id, dag_parent_id FROM memories WHERE id = ?`)
         .get(id);
-    if (!row?.id)
-        return null;
+    return row?.id ? deleteTargetRow(db, row, opts) : null;
+}
+function deleteTargetRow(db, row, opts) {
+    const { id } = row;
     const guard = opts?.automatic ? ` AND ${AUTOMATIC_DELETE_SQL}` : '';
     if (deleteMemoryRow(db, `DELETE FROM memories WHERE id = ?${guard}`, id) === 0)
         return null;
@@ -92,6 +97,35 @@ function deleteEntryOn(db, hippoRoot, id, opts) {
     purgeMirrorBestEffort(hippoRoot, id, false, 'deleteEntry');
     return true;
 }
+/** deleteEntry with `automatic` for each removal and its own forget row and reason, all in one transaction after one read of the id set.
+ *  Returns the ids deleted, in `removals` order; a missing, repeated, pinned, raw or object-backing id is left out. */
+export function deleteEntriesAutomatically(hippoRoot, removals, actor) {
+    if (removals.length === 0)
+        return [];
+    const deleted = onHandle(hippoRoot, (db) => withWriteScope(db, 'delete_entries_automatically', () => {
+        const rows = selectDeleteTargets(db, removals.map((removal) => removal.id));
+        return removals
+            .filter(({ id, reason }) => {
+            const row = rows.get(id);
+            return row !== undefined && deleteTargetRow(db, row, { actor, reason, automatic: true }) !== null;
+        })
+            .map((removal) => removal.id);
+    }), openStore);
+    for (const id of deleted)
+        purgeMirrorBestEffort(hippoRoot, id, false, 'deleteEntry');
+    return deleted;
+}
+function selectDeleteTargets(db, ids) {
+    const rows = new Map();
+    for (const chunk of chunked([...new Set(ids)])) {
+        // SAFETY: rows' shape matches the three columns named in the SELECT.
+        const found = db.prepare(`SELECT id, tenant_id, dag_parent_id FROM memories WHERE id IN (${placeholders(chunk.length)})`)
+            .all(...chunk);
+        for (const row of found)
+            rows.set(row.id, row);
+    }
+    return rows;
+}
 // The child fields a level-2/3 summary is built from (loadChildrenOfSummary, generateDagSummary).
 const SUMMARY_INPUTS = ['content', 'created', 'dag_parent_id', 'kind'];
 function mergeOwnChanges(base, ours, live) {
@@ -215,7 +249,7 @@ function moveDormantAndDelete(db, dormantMoves, deletableIds, out) {
 /** The still auto-deletable rows among `ids`, recording each one's DAG parent as dirty. Placeholders come from `ids` itself. */
 function selectAutoDeletableRows(db, ids, dirty) {
     // SAFETY: rows' shape matches the three columns named in the SELECT.
-    const rows = db.prepare(`SELECT id, dag_parent_id, tenant_id FROM memories WHERE id IN (${ids.map(() => '?').join(',')}) AND ${AUTOMATIC_DELETE_SQL}`).all(...ids);
+    const rows = db.prepare(`SELECT id, dag_parent_id, tenant_id FROM memories WHERE id IN (${placeholders(ids.length)}) AND ${AUTOMATIC_DELETE_SQL}`).all(...ids);
     for (const row of rows) {
         if (row.dag_parent_id) {
             dirty.parents.add(row.dag_parent_id);
@@ -254,13 +288,13 @@ function applyBatchWrites(db, stampedWrites, snapshot, out) {
         // Hook for writes: a new child, or a change to what its summary reads, marks the parent dirty; decay alone does not.
         if (row.dag_parent_id && (!live || SUMMARY_INPUTS.some((k) => row[k] !== live[k]))) {
             dirty.parents.add(row.dag_parent_id);
-            dirty.tenantById.set(row.dag_parent_id, row.tenantId);
+            dirty.tenantById.set(row.dag_parent_id, row.tenant_id);
         }
     }
 }
 /** True, after auditing the refusal, when the write would introduce a rejected value. */
 function isRejectedBatchWrite(db, row) {
-    const entryTenantId = row.tenantId ?? DEFAULT_TENANT_ID;
+    const entryTenantId = row.tenant_id ?? DEFAULT_TENANT_ID;
     // checkRejectionGuard, not a bare tombstone probe: a tombstone can coexist with a live same-content row,
     // and skipping every re-persist would starve it of decay/replay updates; only new or changed content is refused.
     try {