hippo-memory 1.71.0 → 1.72.0

package/dist/store/compactions-record.js

@@ -0,0 +1,417 @@
+// The compaction record's SQL: one record per Claude Code compaction, and the rows its summary's items become.
+import * as path from 'path';
+import { ConflictError } from '../core/api-errors.js';
+import { COMPACTION_DB_WAIT_MS, REPLAY_AFTER_MS, TRANSCRIPT_FILL_WINDOW_MS } from '../core/compaction-timing.js';
+import { isStringValue } from '../core/capture-contract.js';
+import { selectItemRows } from '../util/compaction-items.js';
+import { isSharedStore, loadConfig } from '../core/config.js';
+import { closeHippoDb, isSqliteBusy, openHippoDb, withWriteScopeOr } from '../db/index.js';
+import { gatedWrite } from './gated-write.js';
+import { COMPACTION_MEMORY_TAG, COMPACTION_SOURCE_PREFIX, Layer, createMemory, generateId } from '../core/memory.js';
+import { fallbackOrigin, isGlobalStoreRoot, projectId, projectNames, resolveProjectIdentity } from '../core/project-identity.js';
+import { closeStartedWithoutSummary, compactionProgress, compactionRowsByRequest, heldMemoryRows, insertStartedCompaction, insertSummarisedCompaction, latestCompactionRows, latestStartedRows, markCompactionDone, markCompactionSummarised, markSnapshotSavedRow, nextCompactionStart, openTranscriptRows, stalledSummarisedRows, } from './compactions.js';
+import { strengthenRetrievedOn, writeEntryMirrors } from './entry-writes.js';
+import { isRecallBoostAblated } from '../core/ablation.js';
+import { updateStats } from './index-and-stats.js';
+import { resolveTenantId } from './tenant.js';
+import { errorMessage, reportCompactionFailure } from '../util/log.js';
+/** The marker redactSecretsStrict writes; an item holding it was a secret before it was stored. */
+const REDACTED = '[REDACTED]';
+/** Where the session ran: rows written through the global store or a shared store keep the project the session was in. */
+function compactionProject(hippoRoot, cwd) {
+    if (!isGlobalStoreRoot(hippoRoot) && !isSharedStore(hippoRoot))
+        return resolveProjectIdentity(path.dirname(hippoRoot));
+    // No cwd means user-global, as stampOriginProject gives the global store; undefined would fall back to the hook's own cwd.
+    return cwd === null ? '' : resolveProjectIdentity(cwd);
+}
+/** The record column cannot hold NULL, but an item from an unknown folder on a shared store must not read as user-global. */
+function itemOrigin(hippoRoot, ctx) {
+    return ctx.cwd === null && isSharedStore(hippoRoot) ? fallbackOrigin(hippoRoot) : ctx.originProject;
+}
+function compactionOrigin(hippoRoot, cwd) {
+    return projectId(compactionProject(hippoRoot, cwd));
+}
+/** The names a record's held rows may carry: its origin, plus the folder name rows saved before project ids used. */
+function heldOrigins(hippoRoot, cwd, originProject) {
+    const names = projectNames(compactionProject(hippoRoot, cwd));
+    return names.includes(originProject) ? names : [originProject];
+}
+function toRecord(row) {
+    const listed = row.items_json === null ? [] : JSON.parse(row.items_json);
+    return {
+        id: row.id,
+        tenantId: row.tenant_id,
+        sessionId: row.session_id,
+        originProject: row.origin_project,
+        trigger: row.compact_trigger,
+        cwd: row.cwd,
+        transcriptPath: row.transcript_path,
+        snapshotSaved: row.snapshot_saved === 1,
+        startedAt: row.started_at,
+        summarisedAt: row.summarised_at,
+        summary: row.summary,
+        items: Array.isArray(listed) ? listed.filter(isStringValue) : [],
+        itemsWritten: row.items_written,
+        status: row.status,
+    };
+}
+export function startCompaction(db, tenantId, start, at = new Date()) {
+    const id = generateId('cmp');
+    insertStartedCompaction(db, tenantId, { id, ...start, startedAt: at.toISOString() });
+    return id;
+}
+/** A session's newest record, or null. */
+export function latestCompaction(db, tenantId, sessionId) {
+    return latestCompactionRows(db, tenantId, sessionId).map(toRecord)[0] ?? null;
+}
+/** The record a caller's request made, whatever state it reached, so a retry neither writes its items twice nor starts a second record.
+ * Another session's id is a ConflictError. */
+export function compactionByRequest(db, tenantId, requestId, sessionId) {
+    const record = compactionRowsByRequest(db, tenantId, requestId).map(toRecord)[0] ?? null;
+    // Sessions are owner-bound, so this also keeps one owner from reading or finishing another's record.
+    if (record !== null && record.sessionId !== sessionId)
+        throw new ConflictError('request id belongs to another session');
+    return record;
+}
+/** Pre-compact's record for the compaction that is ending: the session's newest `started` one within REPLAY_AFTER_MS before `at`.
+ * An older one is left for the transcript fill. */
+function latestStarted(db, tenantId, sessionId, at) {
+    return latestStartedRows(db, tenantId, sessionId, at.toISOString(), new Date(at.getTime() - REPLAY_AFTER_MS).toISOString()).map(toRecord)[0] ?? null;
+}
+function markSummarised(db, tenantId, id, options) {
+    const { text, summarisedAt, requestId } = options;
+    return markCompactionSummarised(db, tenantId, id, { summary: text.summary, itemsJson: JSON.stringify(text.items), summarisedAt, requestId });
+}
+/** Best effort, never throws: a compaction must not fail because its record could not be written. */
+export function recordCompactionStart(hippoRoot, start, log) {
+    let db;
+    try {
+        db = openHippoDb(hippoRoot, { busyWaitMs: COMPACTION_DB_WAIT_MS });
+        return startCompaction(db, resolveTenantId({}), { ...start, originProject: compactionOrigin(hippoRoot, start.cwd) });
+    }
+    catch (err) {
+        log(`compaction record not started: ${errorMessage(err)}`);
+        return null;
+    }
+    finally {
+        if (db)
+            closeHippoDb(db);
+    }
+}
+/** On the caller's handle and tenant, so a server marks the record under the caller's tenant with its own wait. */
+export function markSnapshotSaved(db, tenantId, recordId) {
+    markSnapshotSavedRow(db, tenantId, recordId);
+}
+export function recordSnapshotSaved(hippoRoot, tenantId, recordId, log) {
+    let db;
+    try {
+        db = openHippoDb(hippoRoot, { busyWaitMs: COMPACTION_DB_WAIT_MS });
+        markSnapshotSaved(db, tenantId, recordId);
+    }
+    catch (err) {
+        log(`compaction record not marked with its snapshot: ${errorMessage(err)}`);
+    }
+    finally {
+        if (db)
+            closeHippoDb(db);
+    }
+}
+/** Puts the summary on the session's `started` record, or inserts a `summarised` one when pre-compact wrote none. One statement each. */
+export function recordSummary(db, hippoRoot, tenantId, options) {
+    const { meta, text, at, caller = {} } = options;
+    const now = new Date().toISOString();
+    const itemsJson = JSON.stringify(text.items);
+    const { requestId } = caller;
+    const started = latestStarted(db, tenantId, meta.sessionId, at);
+    if (started && markSummarised(db, tenantId, started.id, { text, summarisedAt: now, requestId })) {
+        return { ...started, summary: text.summary, items: text.items, summarisedAt: now, status: 'summarised' };
+    }
+    const originProject = caller.originProject ?? compactionOrigin(hippoRoot, meta.cwd);
+    const id = generateId('cmp');
+    insertSummarisedCompaction(db, tenantId, { ...meta, originProject, startedAt: at.toISOString() }, { id, summary: text.summary, itemsJson, summarisedAt: now, requestId });
+    return {
+        id, tenantId, sessionId: meta.sessionId, originProject, trigger: meta.trigger, cwd: meta.cwd, transcriptPath: meta.transcriptPath,
+        snapshotSaved: false, startedAt: at.toISOString(), summarisedAt: now, summary: text.summary, items: text.items, itemsWritten: 0, status: 'summarised',
+    };
+}
+/** Words whose loss reverses or narrows a statement: "do not", "can't", "only", "unless". */
+const PROTECTED_WORDS = new Set(['not', 'no', 'never', 'none', 'nor', 'without', 'cannot', 't', 'only', 'except', 'unless', 'until']);
+/** Below this share of the held text's words, an item is a fragment of something longer, not a restatement. */
+const RESTATE_MIN_SHARE = 0.5;
+function words(text) {
+    return text.normalize('NFC').toLowerCase().split(/[^\p{L}\p{M}\p{N}_]+/u).filter(Boolean);
+}
+/** True when `item` is `held` with words left out, in the same order, keeping every number and protected word. Spacing, case and punctuation may differ. */
+function restates(item, held) {
+    if (item.length === 0 || item.length < RESTATE_MIN_SHARE * held.length)
+        return false;
+    const kept = new Set(item);
+    let next = 0;
+    for (const w of held) {
+        if (next < item.length && w === item[next])
+            next++;
+        else if (!kept.has(w) && (PROTECTED_WORDS.has(w) || /\p{N}/u.test(w)))
+            return false;
+    }
+    return next === item.length;
+}
+/** Live rows of one tenant and origin that default recall shows: a compaction often restates what an earlier one, or the user, already saved. */
+function heldRows(db, tenantId, origins) {
+    return heldMemoryRows(db, tenantId, origins).map((r) => ({ id: r.id, sessionId: r.source_session_id, words: words(r.content) }));
+}
+function compactionEntry(text, ctx, origin, baseHalfLifeDays) {
+    return {
+        ...createMemory(text, {
+            layer: Layer.Episodic,
+            tags: [COMPACTION_MEMORY_TAG],
+            source: `${COMPACTION_SOURCE_PREFIX}${ctx.sessionId}`,
+            confidence: 'observed',
+            kind: 'distilled',
+            source_session_id: ctx.sessionId,
+            tenantId: ctx.tenantId,
+            baseHalfLifeDays,
+        }),
+        origin_project: origin,
+    };
+}
+/** Runs inside saveItems' transaction: restatements of held rows are counted, the rest go through the write gate. */
+function writeItemRows(db, hippoRoot, ctx, rows, baseHalfLifeDays) {
+    const out = { written: [], repeats: 0, refused: 0, restated: [] };
+    const held = heldRows(db, ctx.tenantId, ctx.caller?.origins ?? heldOrigins(hippoRoot, ctx.cwd, ctx.originProject));
+    const origin = ctx.caller === undefined ? itemOrigin(hippoRoot, ctx) : ctx.originProject;
+    const restated = new Set();
+    for (const text of rows) {
+        const itemWords = words(text);
+        const match = held.find((h) => restates(itemWords, h.words));
+        if (match) {
+            out.repeats++;
+            if (match.id !== null && match.sessionId !== ctx.sessionId)
+                restated.add(match.id);
+            continue;
+        }
+        // createMemory throws below 3 chars, which would sink the whole transaction.
+        if (text.trim().length < 3) {
+            out.refused++;
+            continue;
+        }
+        const entry = compactionEntry(text, ctx, origin, baseHalfLifeDays);
+        if (gatedWrite(db, hippoRoot, entry, { actor: ctx.caller?.actor ?? 'post-compact' }) === 'written') {
+            out.written.push(entry);
+            held.push({ id: null, sessionId: ctx.sessionId, words: itemWords });
+        }
+        else {
+            out.refused++;
+        }
+    }
+    out.restated = [...restated];
+    return out;
+}
+/** After commit: report skips, mirror the new rows, bump the counter. */
+function finishItemWrites(hippoRoot, writes, log) {
+    if (writes.repeats > 0)
+        log(`skipped ${writes.repeats} item(s) the store already holds`);
+    if (writes.refused > 0)
+        log(`skipped ${writes.refused} item(s) the write gate refused`);
+    for (const entry of writes.written)
+        writeEntryMirrors(hippoRoot, entry);
+    if (writes.written.length > 0) {
+        try {
+            updateStats(hippoRoot, { remembered: writes.written.length });
+        }
+        catch (err) {
+            // The rows are committed; a counter that could not be bumped must not turn that into a failed step.
+            log(`remembered counter not updated: ${errorMessage(err)}`);
+        }
+    }
+}
+/** Items that become rows, then the record `done`, in one transaction so two sessions cannot both insert one text. Mirrors after commit. */
+export function saveItems(db, hippoRoot, ctx, log) {
+    const usable = ctx.items.filter((item) => !item.includes(REDACTED));
+    if (usable.length < ctx.items.length)
+        log(`skipped ${ctx.items.length - usable.length} item(s) as secret`);
+    const { rows, tooLong, capped } = selectItemRows(usable);
+    if (tooLong > 0)
+        log(`item too long: ${tooLong} kept in the record only`);
+    if (capped > 0)
+        log(`capped: ${capped} more kept in the record only`);
+    const baseHalfLifeDays = loadConfig(hippoRoot).defaultHalfLifeDays;
+    let finishedItems = 0;
+    const writes = withWriteScopeOr(db, 'save_items', (rollback) => {
+        if (ctx.recordId !== null) {
+            // A replayer that read the record before another finished it must not write its items again.
+            const current = compactionProgress(db, ctx.tenantId, ctx.recordId);
+            if (current?.status !== 'summarised') {
+                finishedItems = current?.items_written ?? 0;
+                return rollback(null);
+            }
+        }
+        const written = writeItemRows(db, hippoRoot, ctx, rows, baseHalfLifeDays);
+        // Said again by another session is the same signal as being recalled; the same session carrying it forward is not.
+        strengthenRetrievedOn(db, written.restated, { tenantId: ctx.tenantId, recallBoostAblated: isRecallBoostAblated() });
+        if (ctx.recordId !== null) {
+            markCompactionDone(db, ctx.tenantId, ctx.recordId, written.written.length);
+        }
+        return written;
+    });
+    if (writes === null) {
+        log(`${ctx.recordId} was already finished by another process`);
+        return finishedItems;
+    }
+    finishItemWrites(hippoRoot, writes, log);
+    return writes.written.length;
+}
+function recordStep(step) {
+    try {
+        const record = recordSummary(step.db, step.hippoRoot, step.tenantId, { meta: step.meta, text: step.text, at: step.at });
+        step.result.snapshotSaved = record.snapshotSaved;
+        return record;
+    }
+    catch (err) {
+        if (isSqliteBusy(err))
+            throw err;
+        reportCompactionFailure(step.log, 'record step', errorMessage(err));
+        return null;
+    }
+}
+/** Busy with a saved record defers to sleep; any other failure goes to the caller. */
+function itemsStep(step, record) {
+    const { meta, hippoRoot, log } = step;
+    try {
+        step.result.written = saveItems(step.db, hippoRoot, {
+            tenantId: step.tenantId,
+            recordId: record?.id ?? null,
+            sessionId: meta.sessionId,
+            originProject: record?.originProject ?? compactionOrigin(hippoRoot, meta.cwd),
+            cwd: meta.cwd,
+            items: step.text.items,
+        }, log);
+    }
+    catch (err) {
+        if (!isSqliteBusy(err) || record === null)
+            throw err;
+        // The record already holds the items; sleep finishes them.
+        step.result.deferred = true;
+        log(`store busy, items left for the next sleep: ${errorMessage(err)}`);
+    }
+}
+/** The PostCompact store work, on a handle of its own: record the summary, then write its items. Each step is independent. Never throws. */
+export function saveCompactionAt(hippoRoot, meta, text, at, log) {
+    const result = { written: null, deferred: false, snapshotSaved: false };
+    let db;
+    try {
+        db = openHippoDb(hippoRoot, { busyWaitMs: COMPACTION_DB_WAIT_MS });
+        const step = { db, hippoRoot, tenantId: resolveTenantId({}), meta, text, at, result, log };
+        itemsStep(step, recordStep(step));
+    }
+    catch (err) {
+        if (isSqliteBusy(err) || db === undefined)
+            return { result, spoolReason: errorMessage(err) };
+        reportCompactionFailure(log, 'items step', errorMessage(err));
+    }
+    finally {
+        if (db)
+            closeHippoDb(db);
+    }
+    return { result, spoolReason: null };
+}
+function closeWithoutSummary(db, tenantId, id, log) {
+    if (closeStartedWithoutSummary(db, tenantId, id) > 0)
+        log(`${id} closed as no-summary: its transcript holds no summary for it`);
+}
+function nextStartedAt(db, record) {
+    return nextCompactionStart(db, record.tenantId, record.sessionId, record.startedAt);
+}
+/** The one place a record becomes the argument saveItems takes. */
+function itemContext(tenantId, record, items = record.items) {
+    return { tenantId, recordId: record.id, sessionId: record.sessionId, originProject: record.originProject, cwd: record.cwd, items };
+}
+/** Records a spooled summary, then writes its items. */
+function spoolRecorder(db, hippoRoot, log) {
+    return (spooled, recorded) => {
+        const record = recordSummary(db, hippoRoot, spooled.tenantId, { meta: spooled.payload, text: spooled.text, at: spooled.at });
+        // The record holds the items now, so the file is done even if the write below fails.
+        recorded();
+        saveItems(db, hippoRoot, itemContext(spooled.tenantId, record), log);
+    };
+}
+/** Runs `step` over each record until the deadline; a record that throws is logged and the rest still run. Returns how many `step` finished. */
+function replayEach(run, records, what, step) {
+    let finished = 0;
+    for (const record of records) {
+        if (Date.now() > run.deadline)
+            break;
+        try {
+            if (step(record))
+                finished++;
+        }
+        catch (err) {
+            run.log(`${what} of ${record.id} failed: ${errorMessage(err)}`);
+        }
+    }
+    return finished;
+}
+function replayStalled(run) {
+    const stalled = stalledSummarisedRows(run.db, run.tenantId, new Date(run.now - REPLAY_AFTER_MS).toISOString()).map(toRecord);
+    return replayEach(run, stalled, 'replay', (record) => {
+        saveItems(run.db, run.hippoRoot, itemContext(run.tenantId, record), run.log);
+        return true;
+    });
+}
+function replaySpool(run) {
+    try {
+        return run.sources.importSpool(run.tenantId, run.deadline, spoolRecorder(run.db, run.hippoRoot, run.log));
+    }
+    catch (err) {
+        run.log(`spool import failed: ${errorMessage(err)}`);
+        return 0;
+    }
+}
+/** Fills one open record from its transcript; true when it saved items. */
+function fillFromTranscript(run, record) {
+    const { db, hippoRoot, tenantId, sources, log } = run;
+    if (record.transcriptPath === null || !sources.transcriptExists(record.transcriptPath))
+        return false;
+    const next = nextStartedAt(db, record);
+    const found = sources.transcriptText(record.transcriptPath, Date.parse(record.startedAt), next === null ? Number.POSITIVE_INFINITY : Date.parse(next));
+    if (found === null) {
+        // The record is past REPLAY_AFTER_MS, so a window that is fully scanned or out of reach stays empty.
+        closeWithoutSummary(db, tenantId, record.id, log);
+        return false;
+    }
+    const { text, listed } = found;
+    if (!listed)
+        log(`no memories section in the transcript summary for ${record.id}`);
+    if (!markSummarised(db, tenantId, record.id, { text, summarisedAt: new Date().toISOString() })) {
+        log(`${record.id} was filled by another process`);
+        return false;
+    }
+    saveItems(db, hippoRoot, itemContext(tenantId, record, text.items), log);
+    return true;
+}
+function replayOpen(run) {
+    const open = openTranscriptRows(run.db, run.tenantId, new Date(run.now - REPLAY_AFTER_MS).toISOString(), new Date(run.now - TRANSCRIPT_FILL_WINDOW_MS).toISOString()).map(toRecord);
+    return replayEach(run, open, 'transcript fill', (record) => fillFromTranscript(run, record));
+}
+/** Finishes what a killed hook or a busy store left: `summarised` records, spool files, and `started` records the transcript can fill.
+ * Returns how many compactions it saved. */
+function replayCompactions(db, hippoRoot, sources, log, deadline) {
+    const run = { db, hippoRoot, tenantId: resolveTenantId({}), now: Date.now(), sources, log, deadline };
+    return replayStalled(run) + replaySpool(run) + replayOpen(run);
+}
+/** For `hippo sleep` and post-compact: opens the store itself and never throws. */
+export function replayStoredCompactions(hippoRoot, sources, log, opts = {}) {
+    let db;
+    try {
+        db = openHippoDb(hippoRoot, { busyWaitMs: opts.busyWaitMs });
+        return replayCompactions(db, hippoRoot, sources, log, opts.deadline ?? Number.POSITIVE_INFINITY);
+    }
+    catch (err) {
+        log(`replay failed: ${errorMessage(err)}`);
+        return 0;
+    }
+    finally {
+        if (db)
+            closeHippoDb(db);
+    }
+}
+//# sourceMappingURL=compactions-record.js.map

package/dist/store/compactions.js

@@ -1,6 +1,7 @@
 import { originInSql } from '../core/project-identity.js';
-import { scopeAdmitSql } from './recall-scope.js';
-const COLUMNS = 'tenant_id, id, session_id, origin_project, compact_trigger, cwd, transcript_path, snapshot_saved, started_at, summarised_at, summary, items_json, items_written, status';
+import { scopeAdmitSql } from './rule-sql.js';
+const COLUMNS = 'tenant_id, id, session_id, origin_project, compact_trigger, cwd, transcript_path, snapshot_saved, started_at, summarised_at, summary, ' +
+    'items_json, items_written, status';
 function selectRows(db, where, ...params) {
     // SAFETY: the SELECT names exactly COLUMNS, matching CompactionRow's field set.
     return db.prepare(`SELECT ${COLUMNS} FROM compactions WHERE ${where}`).all(...params);
@@ -42,8 +43,9 @@ export function insertSummarisedCompaction(db, tenantId, meta, row) {
     // Only a caller names the column, so a store from before it was added still takes local writes.
     const stamp = requestId === undefined ? [] : [requestId];
     const [col, mark] = stamp.length === 0 ? ['', ''] : [', request_id', ', ?'];
-    db.prepare(`INSERT INTO compactions(tenant_id, id, session_id, origin_project, compact_trigger, cwd, transcript_path, started_at, summarised_at, summary, items_json, status${col})
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'summarised'${mark})`).run(tenantId, id, meta.sessionId, meta.originProject, meta.trigger, meta.cwd, meta.transcriptPath, meta.startedAt, summarisedAt, summary, itemsJson, ...stamp);
+    db.prepare(`INSERT INTO compactions(tenant_id, id, session_id, origin_project, compact_trigger, cwd, transcript_path, started_at, ` +
+        `summarised_at, summary, items_json, status${col})\n` +
+        `     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'summarised'${mark})`).run(tenantId, id, meta.sessionId, meta.originProject, meta.trigger, meta.cwd, meta.transcriptPath, meta.startedAt, summarisedAt, summary, itemsJson, ...stamp);
 }
 export function markSnapshotSavedRow(db, tenantId, recordId) {
     db.prepare(`UPDATE compactions SET snapshot_saved = 1 WHERE tenant_id = ? AND id = ?`).run(tenantId, recordId);

package/dist/store/conflicts.js

@@ -5,11 +5,12 @@ import { archiveRawMemory } from './raw-archive.js';
 import { 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';
 // 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';
@@ -351,7 +352,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);
@@ -438,7 +440,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,32 @@
+// The dead-letter statements both connectors share; each connector names its table and columns and maps rows to its own item type.
+/** 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 (${names.map(() => '?').join(', ')})`)
+        .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/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;