hippo-memory 1.70.0 → 1.72.0

package/dist/store/raw-archive.js

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

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

@@ -1,19 +1,6 @@
-/**
- * Retrieval-trace persistence.
- *
- * Single producer for the `recall_traces` / `recall_trace_results` /
- * `recall_trace_outcomes` tables (schema v40). Every recall on the three
- * wired paths (api.recall, api.getContext, CLI cmdRecall) writes a trace
- * row: the ids + ranks + scores actually returned. Outcome events that
- * resolve their targets from last-retrieval state link back to the trace
- * they judge via `recordTraceOutcome`. This is the (query, shown, outcome)
- * training triple every Track LC learned component needs.
- *
- * All writes here are fail-soft: a broken trace write must never break the
- * surrounding recall or outcome call. Failures are logged to stderr and
- * swallowed (matches the api.ts ~2843 "audit emit failed" precedent — no
- * new debug env var).
- */
+/** Retrieval-trace persistence: the single producer for `recall_traces`, `recall_trace_results` and `recall_trace_outcomes`.
+ * One trace row per recall on api.recall, api.getContext and CLI cmdRecall: the (query, shown, outcome) triple the learned components train on.
+ * All writes are fail-soft: a failed trace write is logged to stderr and swallowed, never breaking the surrounding call. */
 import { type DatabaseSyncLike } from '../db/index.js';
 import type { RerankStep } from '../core/search-types.js';
 import { type DeliveryEventInput } from './delivery-recorder.js';
@@ -31,7 +18,7 @@ export interface RecallTraceInput {
     sessionId?: string | null;
     pipeline: 'api' | 'cli' | 'context' | 'mcp';
     /** Raw query text. NEVER persisted — only its sha256/16 hash + length are
-     *  stored (GDPR Path A / audit convention, cli.ts:1532). */
+     *  stored (GDPR Path A / audit convention, CLI). */
     query: string;
     /** True when the caller ran with explain/--why (per-result rerank steps
      *  may be present). Defaults to false. */
@@ -39,39 +26,11 @@ export interface RecallTraceInput {
     /** Results in returned rank order (index 0 = rank 1). */
     results: RecallTraceResultInput[];
 }
-/**
- * Insert a `recall_traces` row + its `recall_trace_results` rows in ONE
- * transaction, on the connection handed in. Fail-soft: never throws —
- * logs to stderr and returns null on any failure.
- *
- * Connection policy: api.recall and api.getContext reach this through
- * `finishRecallAt`, on the handle that recall's other writes use. CLI
- * cmdRecall goes through `writeRecallTraceAtRoot` instead, since its audit
- * handle is already closed by the time tracing runs.
- */
+/** Insert a `recall_traces` row and its results rows in ONE transaction on the given connection. Fail-soft: logs to stderr and returns null on failure.
+ * api.recall/getContext reach this via `finishRecallAt` on their own handle; CLI cmdRecall uses `writeRecallTraceAtRoot` (its audit handle is closed). */
 export declare function writeRecallTrace(db: DatabaseSyncLike, input: RecallTraceInput): number | null;
-/**
- * Convenience wrapper: opens a fresh short-lived connection at `root`,
- * writes the trace, and closes. Returns the new trace id, or null on any
- * failure (fail-soft).
- *
- * Used at CLI cmdRecall, where the block's own convention is per-call
- * handles (writeEntry, saveIndex) and the earlier audit handle is already
- * closed. NOT used by api.recall, which must reuse the caller's open handle
- * (no-side-effects contract, tests/api-recall-no-side-effects.test.ts).
- *
- * This function does NOT touch the `last_trace_id` meta key: its own connection
- * would commit apart from `saveIndex`, so a crash could advance one key alone. LOCKSTEP
- * INVARIANT: `last_trace_id` must only ever advance in the SAME write as
- * `last_retrieval_ids`. The caller now does: call this function FIRST, set
- * `localIndex.last_trace_id` from the returned id, THEN call `saveIndex`
- * once — `saveIndex` persists both meta keys in one transaction
- * (store.ts). Call sites that trace WITHOUT advancing `last_retrieval_ids`
- * (CLI cmdRecall's zero-result path) simply never touch `localIndex` at
- * all, so they can't desync by construction.
- *
- * Fail-soft: never throws, including on connection failure.
- */
+/** Short-lived connection at `root`: writes the trace, closes; returns the id or null (fail-soft). For CLI cmdRecall; api.recall must reuse its open handle.
+ * LOCKSTEP: never touches `last_trace_id`, which advances only in the same `saveIndex` write as `last_retrieval_ids`; the caller sets it from the id. */
 export declare function writeRecallTraceAtRoot(root: string, input: RecallTraceInput): number | null;
 /** Input to `recordTraceOutcome`. */
 export interface RecordTraceOutcomeInput {
@@ -81,34 +40,8 @@ export interface RecordTraceOutcomeInput {
     /** Ids actually credited by this outcome event (post tenant-filtering). */
     memoryIds: string[];
 }
-/**
- * Record an outcome event against a trace, linking the (query, shown,
- * outcome) triple. Called ONLY where the credited ids actually come from
- * the last-retrieval mechanism (api.outcomeForLastRecall and any outcome
- * flow that resolves its targets from last-retrieval state) or from an
- * SDK caller's explicit `traceId` opt — never unconditionally from
- * api.outcome, which would mislink an explicit-id caller to a stale,
- * unrelated trace.
- *
- * Lives in its own append-only table, not audit_log metadata: audit_log is
- * pruned by `pruneAuditLog`, and pruning must never erase training data.
- *
- * Validation: `traceId`/`memoryIds` reach
- * this function from caller-side state (`last_trace_id` / applied outcome
- * ids) that can go stale relative to the trace it names — a forgotten
- * memory, a tenant switch mid-session, or a race between two callers. Two
- * checks run before the insert, both skip with one log.warn line
- * rather than throw:
- *   1. The named trace must exist and belong to `input.tenantId` — a
- *      tenant mismatch or a dangling id (deleted trace) skips.
- *   2. `input.memoryIds` is intersected against the trace's OWN
- *      `recall_trace_results.memory_id` set — only ids that trace actually
- *      returned are recorded. An id that was never in this trace's result
- *      set (stale caller state) is silently dropped rather than recorded
- *      as a false credit. If the intersection is empty, no row is written.
- *
- * Fail-soft: never throws.
- */
+/** Record an outcome against a trace; call ONLY with ids from last-retrieval state or an SDK `traceId`, never from api.outcome (stale-trace mislink).
+ * Skips (log.warn) unless the trace is in `input.tenantId`; keeps only memoryIds it returned. Own table so `pruneAuditLog` cannot erase training data. */
 export declare function recordTraceOutcome(db: DatabaseSyncLike, input: RecordTraceOutcomeInput): void;
 /** Pruned on write, counted back from the event's ts capped at the real clock, so a far-future fake time spares real rows. */
 export declare const DELIVERY_LEDGER_RETENTION_DAYS = 90;
@@ -168,6 +101,8 @@ export interface DeliveryEventRow {
     recall_hash: string | null;
     emitted_hash: string | null;
     elapsed_ms: number;
+    tool_use_id: string | null;
+    failure_id: number | null;
     candidates: DeliveryCandidateRow[];
 }
 /** One event plus its candidates in one write transaction, then prune; fail-soft. The caller must not hold a transaction on `db`. */

package/dist/store/recall-trace.js

@@ -1,33 +1,14 @@
-/**
- * Retrieval-trace persistence.
- *
- * Single producer for the `recall_traces` / `recall_trace_results` /
- * `recall_trace_outcomes` tables (schema v40). Every recall on the three
- * wired paths (api.recall, api.getContext, CLI cmdRecall) writes a trace
- * row: the ids + ranks + scores actually returned. Outcome events that
- * resolve their targets from last-retrieval state link back to the trace
- * they judge via `recordTraceOutcome`. This is the (query, shown, outcome)
- * training triple every Track LC learned component needs.
- *
- * All writes here are fail-soft: a broken trace write must never break the
- * surrounding recall or outcome call. Failures are logged to stderr and
- * swallowed (matches the api.ts ~2843 "audit emit failed" precedent — no
- * new debug env var).
- */
-import { createHash } from 'node:crypto';
-import { openHippoDb, closeHippoDb, rethrowIfSqliteBlocked, withWriteScope } from '../db/index.js';
+/** Retrieval-trace persistence: the single producer for `recall_traces`, `recall_trace_results` and `recall_trace_outcomes`.
+ * One trace row per recall on api.recall, api.getContext and CLI cmdRecall: the (query, shown, outcome) triple the learned components train on.
+ * All writes are fail-soft: a failed trace write is logged to stderr and swallowed, never breaking the surrounding call. */
+import { openHippoDb, closeHippoDb, withWriteScope } from '../db/index.js';
+import { rethrowIfSqliteBlocked } from '../util/sqlite-blocked.js';
 import { DELIVERY_LEDGER_VERSION, isBoundaryEvent } from './delivery-recorder.js';
-import { errorMessage, log } from '../util/log.js';
+import { errorFields, errorMessage, log } from '../util/log.js';
 import { DAY_MS } from '../util/time.js';
-/**
- * Strip a RerankStep down to {stage, multiplier, scoreBefore, scoreAfter}
- * before persisting. `note` is
- * free-form human text — the CLI's goal-boost step embeds matched goal tag
- * text there, so persisting it verbatim would leak raw user content into
- * training data via `rerank_json`. Only the four structured fields survive;
- * any other/future free-form field is dropped by construction (allowlist,
- * not a denylist).
- */
+import { blockHash } from '../util/token-text.js';
+/** Strip a RerankStep to {stage, multiplier, scoreBefore, scoreAfter}: `note` is free-form (the CLI goal-boost step embeds goal tag text) and would leak
+ * user content into `rerank_json`; an allowlist, so any future free-form field is dropped too. */
 function sanitizeRerankSteps(steps) {
     return steps.map((s) => ({
         stage: s.stage,
@@ -36,19 +17,11 @@ function sanitizeRerankSteps(steps) {
         scoreAfter: s.scoreAfter,
     }));
 }
-/**
- * Insert a `recall_traces` row + its `recall_trace_results` rows in ONE
- * transaction, on the connection handed in. Fail-soft: never throws —
- * logs to stderr and returns null on any failure.
- *
- * Connection policy: api.recall and api.getContext reach this through
- * `finishRecallAt`, on the handle that recall's other writes use. CLI
- * cmdRecall goes through `writeRecallTraceAtRoot` instead, since its audit
- * handle is already closed by the time tracing runs.
- */
+/** Insert a `recall_traces` row and its results rows in ONE transaction on the given connection. Fail-soft: logs to stderr and returns null on failure.
+ * api.recall/getContext reach this via `finishRecallAt` on their own handle; CLI cmdRecall uses `writeRecallTraceAtRoot` (its audit handle is closed). */
 export function writeRecallTrace(db, input) {
     try {
-        const queryHash = createHash('sha256').update(input.query).digest('hex').slice(0, 16);
+        const queryHash = blockHash(input.query);
         const ts = new Date().toISOString();
         return withWriteScope(db, 'write_recall_trace', () => {
             const insertTrace = db.prepare(`
@@ -68,32 +41,12 @@ export function writeRecallTrace(db, input) {
         });
     }
     catch (error) {
-        log.error(`recall trace write failed: ${errorMessage(error)}`);
+        log.error(`recall trace write failed: ${errorMessage(error)}`, errorFields(error));
         return null;
     }
 }
-/**
- * Convenience wrapper: opens a fresh short-lived connection at `root`,
- * writes the trace, and closes. Returns the new trace id, or null on any
- * failure (fail-soft).
- *
- * Used at CLI cmdRecall, where the block's own convention is per-call
- * handles (writeEntry, saveIndex) and the earlier audit handle is already
- * closed. NOT used by api.recall, which must reuse the caller's open handle
- * (no-side-effects contract, tests/api-recall-no-side-effects.test.ts).
- *
- * This function does NOT touch the `last_trace_id` meta key: its own connection
- * would commit apart from `saveIndex`, so a crash could advance one key alone. LOCKSTEP
- * INVARIANT: `last_trace_id` must only ever advance in the SAME write as
- * `last_retrieval_ids`. The caller now does: call this function FIRST, set
- * `localIndex.last_trace_id` from the returned id, THEN call `saveIndex`
- * once — `saveIndex` persists both meta keys in one transaction
- * (store.ts). Call sites that trace WITHOUT advancing `last_retrieval_ids`
- * (CLI cmdRecall's zero-result path) simply never touch `localIndex` at
- * all, so they can't desync by construction.
- *
- * Fail-soft: never throws, including on connection failure.
- */
+/** Short-lived connection at `root`: writes the trace, closes; returns the id or null (fail-soft). For CLI cmdRecall; api.recall must reuse its open handle.
+ * LOCKSTEP: never touches `last_trace_id`, which advances only in the same `saveIndex` write as `last_retrieval_ids`; the caller sets it from the id. */
 export function writeRecallTraceAtRoot(root, input) {
     let db;
     try {
@@ -101,7 +54,7 @@ export function writeRecallTraceAtRoot(root, input) {
     }
     catch (error) {
         rethrowIfSqliteBlocked(error);
-        log.error(`recall trace connection failed: ${errorMessage(error)}`);
+        log.error(`recall trace connection failed: ${errorMessage(error)}`, errorFields(error));
         return null;
     }
     try {
@@ -111,34 +64,8 @@ export function writeRecallTraceAtRoot(root, input) {
         closeHippoDb(db);
     }
 }
-/**
- * Record an outcome event against a trace, linking the (query, shown,
- * outcome) triple. Called ONLY where the credited ids actually come from
- * the last-retrieval mechanism (api.outcomeForLastRecall and any outcome
- * flow that resolves its targets from last-retrieval state) or from an
- * SDK caller's explicit `traceId` opt — never unconditionally from
- * api.outcome, which would mislink an explicit-id caller to a stale,
- * unrelated trace.
- *
- * Lives in its own append-only table, not audit_log metadata: audit_log is
- * pruned by `pruneAuditLog`, and pruning must never erase training data.
- *
- * Validation: `traceId`/`memoryIds` reach
- * this function from caller-side state (`last_trace_id` / applied outcome
- * ids) that can go stale relative to the trace it names — a forgotten
- * memory, a tenant switch mid-session, or a race between two callers. Two
- * checks run before the insert, both skip with one log.warn line
- * rather than throw:
- *   1. The named trace must exist and belong to `input.tenantId` — a
- *      tenant mismatch or a dangling id (deleted trace) skips.
- *   2. `input.memoryIds` is intersected against the trace's OWN
- *      `recall_trace_results.memory_id` set — only ids that trace actually
- *      returned are recorded. An id that was never in this trace's result
- *      set (stale caller state) is silently dropped rather than recorded
- *      as a false credit. If the intersection is empty, no row is written.
- *
- * Fail-soft: never throws.
- */
+/** Record an outcome against a trace; call ONLY with ids from last-retrieval state or an SDK `traceId`, never from api.outcome (stale-trace mislink).
+ * Skips (log.warn) unless the trace is in `input.tenantId`; keeps only memoryIds it returned. Own table so `pruneAuditLog` cannot erase training data. */
 export function recordTraceOutcome(db, input) {
     try {
         // SAFETY: row shape matches the single `tenant_id` column named in the
@@ -165,7 +92,7 @@ export function recordTraceOutcome(db, input) {
     `).run(input.traceId, new Date().toISOString(), input.tenantId, input.outcome, JSON.stringify(credited));
     }
     catch (error) {
-        log.error(`recall trace outcome write failed: ${errorMessage(error)}`);
+        log.error(`recall trace outcome write failed: ${errorMessage(error)}`, errorFields(error));
     }
 }
 /** Pruned on write, counted back from the event's ts capped at the real clock, so a far-future fake time spares real rows. */
@@ -179,7 +106,7 @@ const DELIVERY_EVENT_COLUMNS = [
     'session_id', 'session_state', 'host_turn_id', 'turn_seq', 'duplicate_of', 'prompt_hash', 'prompt_length', 'query_hash',
     'recall_trace_id', 'block_state', 'prompt_recall', 'considered_count', 'filtered_count', 'selected_count', 'emitted_count',
     'rejected_count', 'rejected_unlisted', 'sections_shown', 'sections_dropped', 'budget_tokens', 'selected_tokens',
-    'injected_tokens', 'static_hash', 'recall_hash', 'emitted_hash', 'elapsed_ms',
+    'injected_tokens', 'static_hash', 'recall_hash', 'emitted_hash', 'elapsed_ms', 'tool_use_id', 'failure_id',
 ];
 function findDuplicateBoundary(db, input) {
     // SAFETY: rows carry exactly the `id` and `ts` columns selected.
@@ -191,7 +118,21 @@ function findDuplicateBoundary(db, input) {
     const at = Date.parse(input.ts);
     return rows.find((r) => Math.abs(Date.parse(r.ts) - at) <= DELIVERY_DUPLICATE_WINDOW_MS)?.id ?? null;
 }
+function findDuplicateToolFailure(db, input) {
+    // Without a call id a time window would merge parallel failures, so two such fires stay two rows.
+    if (input.toolUseId === undefined || input.toolUseId === null)
+        return null;
+    // SAFETY: a single `id` column, undefined when no row matches.
+    const row = db.prepare(`
+    SELECT id FROM delivery_events
+    WHERE tenant_id = ? AND session_id = ? AND event_type = ? AND tool_use_id = ? AND turn_seq IS NOT NULL
+    ORDER BY id LIMIT 1
+  `).get(input.tenantId, input.sessionId, input.eventType, input.toolUseId);
+    return row?.id ?? null;
+}
 function findDuplicateTurn(db, input) {
+    if (input.eventType === 'tool-failure')
+        return findDuplicateToolFailure(db, input);
     // A boundary has no prompt, and two compactions of one session never start within the window, so time alone decides.
     if (isBoundaryEvent(input.eventType))
         return findDuplicateBoundary(db, input);
@@ -239,6 +180,7 @@ export function writeDeliveryEvent(db, input) {
                 input.consideredCount, input.filteredCount, input.selectedCount, input.emittedCount, input.rejectedCount,
                 input.rejectedUnlisted, input.sectionsShown, input.sectionsDropped, input.budgetTokens, input.selectedTokens,
                 input.injectedTokens, input.staticHash, input.recallHash, input.emittedHash, Math.round(input.elapsedMs),
+                input.toolUseId ?? null, input.failureId ?? null,
             ];
             const eventId = Number(db.prepare(`
         INSERT INTO delivery_events (${DELIVERY_EVENT_COLUMNS.join(', ')})
@@ -258,8 +200,7 @@ export function writeDeliveryEvent(db, input) {
         });
     }
     catch (error) {
-        // The prompt hook's stderr shows this exact `[hippo] delivery ledger` line, so it stays off the logger's format.
-        console.error(`[hippo] delivery ledger write failed: ${errorMessage(error)}`);
+        log.error(`delivery ledger write failed: ${errorMessage(error)}`);
         return null;
     }
 }
@@ -270,8 +211,7 @@ export function writeDeliveryEventAtRoot(root, input) {
         db = openHippoDb(root);
     }
     catch (error) {
-        // Same hook stderr line as writeDeliveryEvent above.
-        console.error(`[hippo] delivery ledger write failed: ${errorMessage(error)}`);
+        log.error(`delivery ledger write failed: ${errorMessage(error)}`);
         return null;
     }
     try {

package/dist/store/rejected-values.js

@@ -9,9 +9,10 @@ import { entryRejectRowAt, selectAllEntries } from './entry-reads.js';
 import { stampOriginProject } from './entry-row.js';
 import { writeEntryDbOnly, writeEntryMirrors } from './entry-writes.js';
 import { purgeMirrorBestEffort } from './mirrors.js';
-import { openStore } from './open.js';
+import { onHandle, openStore } from './open.js';
 import { archiveRawMemory, markMirrorCleaned } from './raw-archive.js';
-import { RejectedValueError, checkRejectionGuard, deleteRejectedValue, insertRejectedValue, listRejectedValues, normalizeValueForRejection, rejectionDigest, } from './rejection.js';
+import { checkRejectionGuard, deleteRejectedValue, insertRejectedValue, listRejectedValues, normalizeValueForRejection, rejectionDigest, } from './rejection.js';
+import { RejectedValueError } from '../core/api-errors.js';
 function removeLiveRows(db, hippoRoot, rejection, holdsValue, removal) {
     const { tenantId, actor, reason } = rejection;
     const { removedIds, removedRawIds, successors } = removal;
@@ -81,8 +82,7 @@ function purgeRemovedMirrors(db, hippoRoot, removal) {
  *  text (live or dormant, whole or inside a merged row) and one reject_value audit row. Markdown mirrors follow the commit. */
 export function applyRejection(hippoRoot, rejection) {
     const { tenantId, actor, reason, memoryId } = rejection;
-    const db = openStore(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         const content = rejection.textOf(memoryId === undefined ? undefined : entryRejectRowAt(db, memoryId));
         const digest = rejectionDigest(content);
         const rejectedAt = new Date().toISOString();
@@ -108,16 +108,12 @@ export function applyRejection(hippoRoot, rejection) {
         purgeRemovedMirrors(db, hippoRoot, removal);
         const { removedIds, removedRawIds, successors, dormantSuccessorIds } = removal;
         return { digest, content, removedIds, removedRawIds, successorIds: successors.map((s) => s.id), dormantSuccessorIds };
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
 /** Deletes the tenant's one rejected value whose digest starts with `digestPrefix` and writes its unreject_value audit row.
  *  No match, or more than one, writes nothing. */
 export function liftRejection(hippoRoot, tenantId, digestPrefix, actor) {
-    const db = openStore(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         const matches = listRejectedValues(db, tenantId).filter((r) => r.digest.startsWith(digestPrefix));
         const target = matches[0];
         if (target === undefined)
@@ -127,20 +123,13 @@ export function liftRejection(hippoRoot, tenantId, digestPrefix, actor) {
         deleteRejectedValue(db, tenantId, target.digest);
         audit(db, 'unreject_value', { tenantId, actor, targetId: target.sourceMemoryId ?? undefined, metadata: { digest: target.digest, reason: target.reason } });
         return { status: 'ok', digest: target.digest, reason: target.reason };
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
 /** The tenant's rejected values, newest first. */
 export function loadRejectedValues(hippoRoot, tenantId) {
-    const db = openStore(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         return listRejectedValues(db, tenantId);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
 /** Whether the write guard would refuse `content` under `entryId`, as a write of that row would find it. Reads on a plain open
  *  and writes nothing, so a dry run counts the values a real run refuses. */

package/dist/store/rejection-probe.d.ts

@@ -0,0 +1,4 @@
+export type RejectionProbe = (tenantId: string, entryId: string, content: string) => boolean;
+/** Runs `fn` with a probe that says whether the write guard would refuse the content; the handle closes after. */
+export declare function withRejectionProbe<T>(hippoRoot: string, fn: (wouldReject: RejectionProbe) => T): T;
+//# sourceMappingURL=rejection-probe.d.ts.map

package/dist/store/rejection-probe.js

@@ -0,0 +1,19 @@
+// A rejected-value check for a dry run, on a handle the caller never sees.
+import { onHandle } from './open.js';
+import { checkRejectionGuard } from './rejection.js';
+import { RejectedValueError } from '../core/api-errors.js';
+/** Runs `fn` with a probe that says whether the write guard would refuse the content; the handle closes after. */
+export function withRejectionProbe(hippoRoot, fn) {
+    return onHandle(hippoRoot, (db) => fn((tenantId, entryId, content) => {
+        try {
+            checkRejectionGuard(db, tenantId, entryId, content);
+            return false;
+        }
+        catch (err) {
+            if (err instanceof RejectedValueError)
+                return true;
+            throw err;
+        }
+    }));
+}
+//# sourceMappingURL=rejection-probe.js.map

package/dist/store/rejection.d.ts

@@ -1,52 +1,11 @@
-/**
- * Rejected-value tombstone: core invariant.
- *
- * Exact-normalized-value semantics: a human who rejects a fact can refuse
- * byte-stable re-ingestion of the same value across remember/capture/import/
- * sync surfaces. Paraphrase/semantic matching is explicitly out of scope
- * (documented limitation, plan "Design").
- *
- * Kept db-agnostic (helpers take a `DatabaseSyncLike` handle) and does NOT
- * import from store.ts — store.ts imports from here, and the reverse would
- * be a cycle.
- */
+/** Rejected-value tombstone: a human can refuse byte-stable re-ingestion of a rejected fact (exact normalized value); paraphrase matching is out of scope.
+ * db-agnostic (helpers take a `DatabaseSyncLike`) and imports nothing from the store layer above it, which imports this (the reverse is a cycle). */
 import type { DatabaseSyncLike } from '../db/index.js';
-import { BadRequestError } from '../core/api-errors.js';
-/**
- * Normalize content for rejection-digest comparisons: Unicode NFC →
- * lowercase → collapse whitespace runs to a single space → trim. No
- * punctuation stripping — over-normalization creates false refusals, which
- * are worse than misses (plan §1).
- */
+/** Normalize content for rejection digests: NFC, lowercase, collapse whitespace runs, trim. No punctuation stripping: over-normalizing causes false
+ * refusals, worse than misses. */
 export declare function normalizeValueForRejection(content: string): string;
-/**
- * Full sha256 hex (64 chars) of the normalized content. Reuses the strong-
- * identity convention (importers.ts:814 content-hash tag), NOT the privacy-
- * lossy 16-char convention (recall-trace query hashing) — a tombstone lookup
- * key needs collision resistance, not redaction (plan §1).
- */
+/** Full 64-char sha256 hex of the normalized content: a tombstone key needs collision resistance, not the 16-char redaction hash used for query hashing. */
 export declare function rejectionDigest(content: string): string;
-/**
- * Thrown by the write-path guard (checkRejectionGuard, called from
- * upsertEntryRow) when an incoming write would introduce a value matching a
- * tombstoned digest. Carries enough context for the transaction-owner catch
- * blocks (writeEntry, api.supersede) to write a post-rollback
- * `reject_refusal` audit row via `auditRejectionRefusal` (plan §3).
- */
-export declare class RejectedValueError extends BadRequestError {
-    readonly digest: string;
-    readonly tenantId: string;
-    readonly entryId: string;
-    readonly reason: string | null;
-    readonly rejectedAt: string;
-    constructor(opts: {
-        digest: string;
-        tenantId: string;
-        entryId: string;
-        reason: string | null;
-        rejectedAt: string;
-    });
-}
 export interface RejectedValueRow {
     tenantId: string;
     digest: string;
@@ -56,15 +15,9 @@ export interface RejectedValueRow {
     sourceMemoryId: string | null;
     normalizedChars: number | null;
 }
-/**
- * Look up a tombstone by tenant + digest. One indexed point query — the
- * guard's common-case cost, a miss ends the guard (plan §3).
- */
+/** Look up a tombstone by tenant + digest: one indexed point query, the guard's common-case cost; a miss ends the guard. */
 export declare function findRejectedValue(db: DatabaseSyncLike, tenantId: string, digest: string): RejectedValueRow | null;
-/**
- * Insert (or refresh) a tombstone row. Caller owns the transaction — used by
- * the `reject` verb and `resolveConflict`'s `rejectLoserValue` path.
- */
+/** Insert (or refresh) a tombstone row; the caller owns the transaction (used by the `reject` verb and `resolveConflict`'s `rejectLoserValue`). */
 export declare function insertRejectedValue(db: DatabaseSyncLike, opts: {
     tenantId: string;
     digest: string;
@@ -74,27 +27,11 @@ export declare function insertRejectedValue(db: DatabaseSyncLike, opts: {
     sourceMemoryId?: string | null;
     normalizedChars: number;
 }): void;
-/**
- * Delete a tombstone by tenant + exact digest: the `unreject` verb, the
- * only escape hatch.
- */
+/** Delete a tombstone by tenant + exact digest: the `unreject` verb, the only escape hatch. */
 export declare function deleteRejectedValue(db: DatabaseSyncLike, tenantId: string, digest: string): boolean;
 /** List tombstones for a tenant, newest first: the `rejections` verb. */
 export declare function listRejectedValues(db: DatabaseSyncLike, tenantId: string): RejectedValueRow[];
-/**
- * The write-path guard's check helper, called from `upsertEntryRow`
- * (store.ts). Fires when the incoming content's digest matches a tombstone
- * AND the write *introduces* that content: the row is new, OR the stored
- * row's content digest differs from the incoming one — an UPSERT editing a
- * same-id row TO a rejected value is a content introduction and must be
- * refused. Unchanged same-id re-persists (recall boost, decay, star toggle)
- * are exempt by construction (plan §3).
- *
- * Ordering minimizes queries on the common (miss) path: (a) caller has
- * already computed nothing yet — this does the digest + point lookup first;
- * (b) a miss returns immediately (ONE indexed point query); (c) only on a
- * tombstone hit does it SELECT the stored row's content to classify
- * new-row vs content-introduction (+1 query, rare path).
- */
+/** Write-path guard check: fires when the digest matches a tombstone AND the write introduces that content (a new row, or a same-id UPSERT changing it).
+ * Unchanged same-id re-persists (recall boost, decay, star toggle) are exempt. A miss costs ONE indexed point query; only a hit SELECTs the stored row. */
 export declare function checkRejectionGuard(db: DatabaseSyncLike, tenantId: string, entryId: string, content: string): void;
 //# sourceMappingURL=rejection.d.ts.map