hippo-memory 1.70.0 → 1.72.0

package/dist/store/connectors/github.js

@@ -2,31 +2,31 @@
 import { withWriteScope } from '../../db/index.js';
 import { archiveRawMemory } from '../raw-archive.js';
 import { onHandle } from '../open.js';
-export function eventSeenAt(db, idempotencyKey) {
+import { getDlqRow, insertDlqRow, listDlqRows, markDlqRetried } from './dlq.js';
+export function githubEventSeenAt(db, idempotencyKey) {
     const row = db.prepare(`SELECT 1 FROM github_event_log WHERE idempotency_key = ?`).get(idempotencyKey);
     return !!row;
 }
-export function eventMemoryAt(db, idempotencyKey) {
+export function githubEventMemoryAt(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;
 }
 /** 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) {
+export function markGitHubEventSeenAt(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;
 }
-/** 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 onHandle(hippoRoot, (db) => githubEventSeenAt(db, idempotencyKey) ? { seen: true, memoryId: githubEventMemoryAt(db, idempotencyKey) } : { seen: false });
 }
-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 +36,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 insertDlqAt(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 insertDlq(hippoRoot, row) {
-    return onHandle(hippoRoot, (db) => insertDlqAt(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 +67,31 @@ function rowToItem(r) {
         bucket: r.bucket == null ? 'parse_error' : String(r.bucket),
     };
 }
-function listDlqAt(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 listDlqRows(hippoRoot, tenantId, limit) {
-    return onHandle(hippoRoot, (db) => listDlqAt(db, tenantId, limit));
-}
-function dlqEntryAt(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);
-}
-export function dlqEntry(hippoRoot, id) {
-    return onHandle(hippoRoot, (db) => dlqEntryAt(db, id));
-}
-export function bumpDlqRetry(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);
+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) => listDlqRows(db, 'github_dlq', SELECT_COLUMNS, tenantId, limit).map(rowToItem));
+}
+export function githubDlqEntry(hippoRoot, 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,7 @@
 // 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 { 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.
@@ -51,6 +52,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 +69,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

@@ -5,10 +5,11 @@ import { withReadSnapshot } from '../db/busy.js';
 import { pragmaDataVersion } from '../db/meta.js';
 import { tableExists } from '../db/tables.js';
 import { storedVectorIds } from '../db/vector-store.js';
-import { openStore } from './open.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';
+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 <> '')`;
@@ -24,7 +25,7 @@ function toDashboardRow(row) {
         retrieval_count: Number(row.retrieval_count ?? 0),
         half_life_days: Number(row.half_life_days ?? 7),
         layer: row.layer,
-        tags: parseJsonArray(row.tags_json),
+        tags: parseJsonArray(row.tags_json, { table: 'memories', id: row.id, column: 'tags_json' }),
         emotional_valence: row.emotional_valence ?? 'neutral',
         outcome_positive: Number(row.outcome_positive ?? 0),
         outcome_negative: Number(row.outcome_negative ?? 0),
@@ -39,27 +40,23 @@ function toDashboardRow(row) {
 }
 /** One tenant's live rows and the counts of the rest, read in one transaction so the two agree. */
 export function loadDashboardRows(hippoRoot, tenantId) {
-    const db = openStore(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         return withReadSnapshot(db, () => {
             // 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)
                     excluded[why] = Number(n);
             return { live: live.map(toDashboardRow), excluded };
         });
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
 /** The dashboard's one read-only connection, kept across refreshes for the commit signal; it opens on the first read that finds a database. */
 export class DashboardConnection {

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

@@ -8,16 +8,8 @@ export declare const MEMORY_BACKED_TABLES: readonly ["predictions", "decisions",
 export declare function memoriesBackingObjects(hippoRoot: string): Set<string>;
 /** memoriesBackingObjects on the caller's handle. */
 export declare function memoriesBackingObjectsOn(db: DatabaseSyncLike): Set<string>;
-/**
- * db-scoped delete core, so a delete can compose inside a caller's transaction.
- * NO filesystem I/O: the caller's transaction may still roll back, and mirrors are written post-commit.
- *
- * `opts.suppressForgetAudit` (default false): `rejectValue` and `resolveConflict` set it because each
- * writes its own aggregate audit row, so a removed row must not ALSO emit a `forget` row.
- *
- * Returns `{tenantId, dagParentId}` for the removed row, or `null` if no row with `id`
- * existed or `automatic` refused it (pinned, raw, kept for good or backing an object at DELETE time, so a late pin wins).
- */
+/** db-scoped delete core, composable inside a caller's transaction; NO filesystem I/O, mirrors are written post-commit. `suppressForgetAudit` is set by
+ * rejectValue and resolveConflict (own audit row). Returns `{tenantId, dagParentId}`, or null if absent or `automatic` refused it. */
 export declare function deleteEntryCore(db: ReturnType<typeof openHippoDb>, id: string, opts?: {
     actor?: string;
     suppressForgetAudit?: boolean;
@@ -27,29 +19,23 @@ export declare function deleteEntryCore(db: ReturnType<typeof openHippoDb>, id:
     tenantId: string;
     dagParentId: string | null;
 } | null;
-/**
- * Delete an entry from SQLite and mirrors.
- *
- * `opts.actor` defaults to 'cli'. The api.* layer threads `ctx.actor` so HTTP
- * callers land with `api_key:<key_id>` in the audit log without a duplicate
- * emit from the api wrapper.
- *
- * Thin wrapper over `deleteEntryCore` (open → core → mirrors → close);
- * behavior is byte-identical to the pre-split implementation for every
- * existing caller.
- */
+/** Delete an entry from SQLite and mirrors; thin wrapper over `deleteEntryCore` (open, core, mirrors, close).
+ * `opts.actor` defaults to 'cli'; the api layer threads `ctx.actor` so HTTP callers land as `api_key:<key_id>` in the audit log. */
 export declare function deleteEntry(hippoRoot: string, id: string, opts?: {
     actor?: string;
     reason?: string;
     automatic?: boolean;
 }): boolean;
-/** Writes, deletes and dormant moves in one transaction. With `snapshot` (rows as the caller loaded them), a write keeps only
- *  the fields the caller changed, takes the rest from the live row, and never resurrects a row that is gone.
- *
- *  `dormant` (src/store/dormant.ts): each move's snapshot is inserted into `dormant_memories` and its `memories` row
- *  leaves exactly like a delete (FTS row, DAG parent dirty-mark, mirrors), in the same transaction, so a memory
- *  is never in both places or in neither. Deletes and moves both skip rows that are no longer auto-deletable
- *  (pinned, raw, kept for good or backing an object since the caller decided). Returns the ids that left `memories`, deleted or moved. */
+/** 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.
+ * Dormant moves (src/store/dormant.ts) leave `memories` like a delete; both skip rows no longer auto-deletable. Returns ids that left `memories`. */
 export declare function batchWriteAndDelete(hippoRoot: string, toWrite: MemoryEntry[], toDeleteIds: string[], opts?: {
     snapshot?: ReadonlyMap<string, MemoryEntry>;
     dormant?: DormantMove[];
@@ -70,10 +56,10 @@ export declare function deleteEntriesOneByOne(hippoRoot: string, targets: readon
     actor?: string;
     automatic?: boolean;
 }): boolean[];
-/** Commits whole components in transactions of about `budget.holdMs` on one store handle, letting other writers in between; returns the ids that left `memories`.
- *  The snapshot keeps what other writers changed after the caller loaded its rows. */
+/** Commits whole components in transactions of about `budget.holdMs`, letting other writers in between; returns the ids that left `memories`.
+ * The snapshot keeps what other writers changed after the caller loaded its rows. */
 export declare function commitInChunks(hippoRoot: string, components: readonly FlushComponent[], opts: {
-    snapshot: ReadonlyMap<string, MemoryEntry>;
+    snapshot: LoadedRows;
     budget: WriteBudget;
     busyWaitMs: number;
 }): Promise<string[]>;