hippo-memory 1.69.0 → 1.71.0

package/dist/{recall-scope.js → store/recall-scope.js}

@@ -1,54 +1,20 @@
-/**
- * Recall-side scope predicates, in a leaf module so shared.ts (which api.ts
- * imports) can apply the same default-deny rule to searchBothHybrid's internal
- * candidate loads without an import cycle. api.ts imports
- * these for its own call sites AND re-exports them for back-compat
- * (`api.isPrivateScope`, test imports of `passesScopeFilterForRecall`).
- */
-import { BadRequestError, ForbiddenError } from './api-errors.js';
-import { MAX_ID_LEN } from './http-util.js';
-/**
- * Literal scopes excluded from recall by default-deny when the
- * caller passes no `scope`. The SQL clause in `loadSearchRows` and the JS
- * helper `passesScopeFilterForRecall` (src/api.ts) both read from this
- * constant. Adding a deny scope is a one-place change.
- *
- * Regex-based denies (e.g. `<source>:private:*`) stay in
- * `passesScopeFilterForRecall` as a separate JS step — they don't translate
- * cleanly to SQL.
- *
- * Invariant: never empty. An empty array would silently allow quarantine
- * scopes through both paths (SQL clause omitted, JS check vacuous). The
- * module-load assertion below pins this loudly.
- */
+/** Recall-side scope predicates, in a leaf module so search-both.ts can apply the same default-deny rule to searchBothHybrid's candidate loads without an
+ * import cycle. src/api/index.ts imports these and re-exports them for back-compat (`api.isPrivateScope`, tests importing `passesScopeFilterForRecall`). */
+import { BadRequestError, ForbiddenError } from '../core/api-errors.js';
+import { MAX_ID_LEN } from '../util/http-util.js';
+/** Literal scopes excluded from recall by default-deny when the caller passes no `scope`; read by the SQL clause in `loadSearchRows` and by
+ * `passesScopeFilterForRecall`. Invariant: never empty, or quarantine scopes would pass both paths silently (the module-load assertion below pins this). */
 export const RECALL_DEFAULT_DENY_SCOPES = ['unknown:legacy'];
-/**
- * @internal Runtime guard against a future maintainer blanking a
- * load-bearing literal array. Extracted from the inline guard so the throw
- * path is directly testable. `as const` arrays widen via `readonly T[]` at
- * the call site so the empty case is reachable at runtime.
- */
+/** @internal Runtime guard against blanking a load-bearing literal array; `as const` arrays widen via `readonly T[]` at the call site, so the empty case
+ * is reachable and testable. */
 export function assertNonEmpty(arr, name) {
     if (arr.length === 0) {
         throw new Error(`${name} cannot be empty — would silently allow quarantine scopes`);
     }
 }
 assertNonEmpty(RECALL_DEFAULT_DENY_SCOPES, 'RECALL_DEFAULT_DENY_SCOPES');
-/**
- * Source-agnostic private-scope detector. A scope string is treated
- * as private when it has the shape `<lowercase-source>:private:<rest>`.
- *
- * Examples that match:
- *   slack:private:Cabc, github:private:owner/repo, jira:private:PROJ-1
- * Examples that DO NOT match:
- *   slack:public:Cgeneral, acme:public:my-private-channel, null, '',
- *   'unknown:legacy', 'private' (alone), 'private:foo' (no source prefix).
- *
- * Used by api.recall, mcp/server.ts (hippo_recall + hippo_context),
- * cli.ts (cmdRecall + cmdExplain + continuity), shared.ts (searchBothHybrid
- * recall mode). Keep these in sync — the export is the single source of
- * truth so connector work cannot drift.
- */
+/** Source-agnostic private-scope detector: private means `<lowercase-source>:private:<rest>` (`slack:private:Cabc`; not `slack:public:x`, null, '',
+ * 'private:foo'). The single source of truth for api.recall, the MCP server, the CLI and search-both.ts, so connector work cannot drift. */
 export const PRIVATE_SCOPE_RE = /^[a-z][a-z0-9_-]*:private:/;
 function isScopeString(value) {
     return typeof value === 'string';
@@ -89,15 +55,8 @@ export function canTouchScope(actor, scope) {
 export function ownScopeTouches(ownScope, scope) {
     return !isPersonalScope(scope) || scope === ownScope;
 }
-/**
- * Recall-side scope filter — the canonical JS half of the recall default-deny
- * rule (the SQL half lives in `loadSearchRows` via `loadRecallSearchEntries`).
- *
- * - When `requested` is set and non-empty: exact match required.
- * - When `requested` is undefined/empty: default-deny on any
- *   `<source>:private:*` scope and on the `RECALL_DEFAULT_DENY_SCOPES`
- *   quarantine buckets. `null` and public scopes pass, and so does `ownScope`, the caller's own personal scope.
- */
+/** JS half of the recall default-deny rule (SQL half: `loadSearchRows`). A non-empty `requested` needs an exact match;
+ * otherwise `<source>:private:*` and `RECALL_DEFAULT_DENY_SCOPES` buckets are denied, while null, public scopes and the caller's `ownScope` pass. */
 export function passesScopeFilterForRecall(scope, requested, ownScope) {
     if (requested !== undefined && requested !== '') {
         return scope === requested;
@@ -113,40 +72,23 @@ export function scopeAdmitSql(col, ownScope) {
     // The own arm sits inside the outer parentheses so a caller's `AND ${sql}` cannot split it off.
     return { sql: `(${admitted} OR ${col}scope = ?)`, params: [...RECALL_DEFAULT_DENY_SCOPES, ownScope] };
 }
-/** SQL twin of canTouchScope, which is also canReadScope for an admin: every row but another person's personal one. LIKE folds ASCII case as isPersonalScope's /i does. */
+/** SQL twin of canTouchScope, which is also canReadScope for an admin: every row but
+ * another person's personal one. LIKE folds ASCII case as isPersonalScope's /i does. */
 export function touchableScopeSql(col, ownScope) {
     const notPersonal = `${col}scope IS NULL OR ${col}scope NOT LIKE '${PERSONAL_SCOPE_PREFIX}%'`;
     if (ownScope == null)
         return { sql: `(${notPersonal})`, params: [] };
     return { sql: `(${notPersonal} OR ${col}scope = ?)`, params: [ownScope] };
 }
-/**
- * The CLI `--scope` variant of the recall filter (JS half of the
- * SQL 'default-deny-or-exact' mode in loadSearchRows).
- *
- * The CLI flag predates the envelope column as a TAG-boost ranking hint
- * (`scope:<v>` tags, HIPPO_SCOPE, detectScope()), so an explicit `--scope X`
- * UNLOCKS envelope scope X in addition to the default-admitted set — it does
- * NOT narrow the result to X (that would return zero rows for every
- * tag-scoped workflow, whose envelope scope is NULL). api.recall keeps the
- * narrowing 'exact' semantics via `passesScopeFilterForRecall`.
- *
- * Note the unlock applies to whatever scope was explicitly named — including
- * a private scope or a quarantine bucket (`--scope unknown:legacy`). That is
- * deliberate owner access, identical in reach to api.recall's exact-match
- * for the same input; only NON-requested private/quarantine scopes stay
- * denied. A named personal scope never unlocks: the CLI has no caller identity to check it against.
- */
+/** CLI `--scope` variant: an explicit `--scope X` UNLOCKS scope X on top of the default-admitted set rather than narrowing to X (api.recall keeps 'exact').
+ * Includes private/quarantine scopes (owner access); a named personal scope never unlocks: the CLI has no caller identity. */
 export function passesCliRecallScopeFilter(scope, requested) {
     if (requested !== undefined && requested !== '' && !isPersonalScope(requested) && scope === requested) {
         return true;
     }
     return passesScopeFilterForRecall(scope, undefined);
 }
-/**
- * Thrown when a caller requests a scope its role may not read. The HTTP layer
- * maps it to 403.
- */
+/** Thrown when a caller requests a scope its role may not read; the HTTP layer maps it to 403. */
 export class ScopeForbiddenError extends ForbiddenError {
     scope;
     constructor(scope) {
@@ -155,20 +97,17 @@ export class ScopeForbiddenError extends ForbiddenError {
         this.scope = scope;
     }
 }
-/**
- * True for scopes that default-deny hides: `<source>:private:*` and the
- * quarantine buckets. Naming one explicitly is what unlocks it, so naming one
- * is the act that needs authorization.
- */
+/** True for scopes default-deny hides (`<source>:private:*` and the quarantine buckets); naming one explicitly unlocks it, so naming one needs
+ * authorization. */
 export function isRestrictedScope(scope) {
     if (!isScopeString(scope))
         return false;
-    // SAFETY: RECALL_DEFAULT_DENY_SCOPES is a readonly tuple of string
-    // literals; widening the array (not the input) lets .includes() take any scope.
-    // `:private:` anywhere, any case, matches the store's SQL default-deny (store/search-rows.ts) so JS never admits what SQL hides.
+    // SAFETY: RECALL_DEFAULT_DENY_SCOPES is a readonly tuple of string literals; widening the array lets .includes() take any scope.
+    // `:private:` anywhere, any case, matches the SQL default-deny in src/store/search-rows.ts so JS never admits what SQL hides.
     return isPrivateScope(scope) || /:private:/i.test(scope) || RECALL_DEFAULT_DENY_SCOPES.includes(scope);
 }
-/** Personal rows answer to their owner alone: role, key grants and resolver scopes never open one. Else admin reads all; a member needs an exact grant on a restricted scope. */
+/** Personal rows answer to their owner alone: role, key grants and resolver scopes never
+ * open one. Else admin reads all; a member needs an exact grant on a restricted scope. */
 export function canReadScope(actor, scope) {
     if (isPersonalScope(scope))
         return scope === personalScopeOf(actor);

package/dist/{recall-trace.d.ts → store/recall-trace.d.ts}

@@ -1,21 +1,8 @@
-/**
- * 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 { type DatabaseSyncLike } from './db.js';
-import type { RerankStep } from './search/types.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 { type DatabaseSyncLike } from '../db/index.js';
+import type { RerankStep } from '../core/search-types.js';
 import { type DeliveryEventInput } from './delivery-recorder.js';
 /** One ranked result to persist alongside its trace row. */
 export interface RecallTraceResultInput {
@@ -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,40 +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 (per the plan): api.recall calls this directly on its
- * own already-open handle. api.getContext and CLI cmdRecall go through
- * `writeRecallTraceAtRoot` instead, since their audit handles are 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 api.getContext and CLI cmdRecall — sites where the block's own
- * convention is per-call handles (writeEntry, saveIndex) and the earlier
- * audit handles are 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, getContext's empty-result path) simply
- * never touch `localIndex` at all — 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 {
@@ -82,40 +40,14 @@ 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;
 /** Lock wait for the ledger's own connection: a busy store drops the row rather than slow the hook. */
 export declare const DELIVERY_LEDGER_WAIT_MS = 50;
-/** Two prompt-identical events without a host turn id this close together are one turn fired twice. */
+/** Two prompt-identical events without a host turn id, or two boundary events of one type, this close are one fire twice. */
 export declare const DELIVERY_DUPLICATE_WINDOW_MS = 2000;
 /** One stored `delivery_candidates` row. */
 export interface DeliveryCandidateRow {

package/dist/{recall-trace.js → store/recall-trace.js}

@@ -1,32 +1,13 @@
-/**
- * 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 } from './db.js';
-import { DELIVERY_LEDGER_VERSION } from './delivery-recorder.js';
-import { log } from './log.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).
- */
+/** 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, rethrowIfSqliteBlocked, withWriteScope } from '../db/index.js';
+import { DELIVERY_LEDGER_VERSION, isBoundaryEvent } from './delivery-recorder.js';
+import { errorFields, errorMessage, log } from '../util/log.js';
+import { DAY_MS } from '../util/time.js';
+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,
@@ -35,22 +16,13 @@ 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 (per the plan): api.recall calls this directly on its
- * own already-open handle. api.getContext and CLI cmdRecall go through
- * `writeRecallTraceAtRoot` instead, since their audit handles are 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();
-        db.exec('BEGIN IMMEDIATE');
-        try {
+        return withWriteScope(db, 'write_recall_trace', () => {
             const insertTrace = db.prepare(`
         INSERT INTO recall_traces (ts, tenant_id, session_id, pipeline, query_hash, query_length, result_count, explain_mode)
         VALUES (?, ?, ?, ?, ?, ?, ?, ?)
@@ -64,45 +36,16 @@ export function writeRecallTrace(db, input) {
             input.results.forEach((r, i) => {
                 insertResult.run(traceId, input.tenantId, r.memoryId, i + 1, r.score, r.rerankSteps && r.rerankSteps.length > 0 ? JSON.stringify(sanitizeRerankSteps(r.rerankSteps)) : null);
             });
-            db.exec('COMMIT');
             return traceId;
-        }
-        catch (error) {
-            try {
-                db.exec('ROLLBACK');
-            }
-            catch { /* already rolled back; keep the original error */ }
-            throw error;
-        }
+        });
     }
     catch (error) {
-        log.error(`recall trace write failed: ${error instanceof Error ? error.message : String(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 api.getContext and CLI cmdRecall — sites where the block's own
- * convention is per-call handles (writeEntry, saveIndex) and the earlier
- * audit handles are 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, getContext's empty-result path) simply
- * never touch `localIndex` at all — 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 {
@@ -110,7 +53,7 @@ export function writeRecallTraceAtRoot(root, input) {
     }
     catch (error) {
         rethrowIfSqliteBlocked(error);
-        log.error(`recall trace connection failed: ${error instanceof Error ? error.message : String(error)}`);
+        log.error(`recall trace connection failed: ${errorMessage(error)}`, errorFields(error));
         return null;
     }
     try {
@@ -120,34 +63,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
@@ -174,14 +91,14 @@ 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: ${error instanceof Error ? error.message : String(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. */
 export const DELIVERY_LEDGER_RETENTION_DAYS = 90;
 /** Lock wait for the ledger's own connection: a busy store drops the row rather than slow the hook. */
 export const DELIVERY_LEDGER_WAIT_MS = 50;
-/** Two prompt-identical events without a host turn id this close together are one turn fired twice. */
+/** Two prompt-identical events without a host turn id, or two boundary events of one type, this close are one fire twice. */
 export const DELIVERY_DUPLICATE_WINDOW_MS = 2000;
 const DELIVERY_EVENT_COLUMNS = [
     'ts', 'ledger_version', 'tenant_id', 'runtime', 'event_type', 'surface', 'store_hash', 'write_store', 'project_hash',
@@ -190,7 +107,20 @@ const DELIVERY_EVENT_COLUMNS = [
     'rejected_count', 'rejected_unlisted', 'sections_shown', 'sections_dropped', 'budget_tokens', 'selected_tokens',
     'injected_tokens', 'static_hash', 'recall_hash', 'emitted_hash', 'elapsed_ms',
 ];
+function findDuplicateBoundary(db, input) {
+    // SAFETY: rows carry exactly the `id` and `ts` columns selected.
+    const rows = db.prepare(`
+    SELECT id, ts FROM delivery_events
+    WHERE tenant_id = ? AND session_id = ? AND event_type = ? AND turn_seq IS NOT NULL
+    ORDER BY id
+  `).all(input.tenantId, input.sessionId, input.eventType);
+    const at = Date.parse(input.ts);
+    return rows.find((r) => Math.abs(Date.parse(r.ts) - at) <= DELIVERY_DUPLICATE_WINDOW_MS)?.id ?? null;
+}
 function findDuplicateTurn(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);
     if (input.hostTurnId !== null) {
         // SAFETY: a single `id` column, undefined when no row matches.
         const row = db.prepare(`
@@ -223,8 +153,7 @@ function nextTurnSeq(db, input) {
 /** One event plus its candidates in one write transaction, then prune; fail-soft. The caller must not hold a transaction on `db`. */
 export function writeDeliveryEvent(db, input) {
     try {
-        db.exec('BEGIN IMMEDIATE');
-        try {
+        return withWriteScope(db, 'write_delivery_event', () => {
             // Missing-session and sub-agent events are not turns of a session, so they get no number and no duplicate check.
             const isTurn = input.sessionId !== null && (input.sessionState === 'payload' || input.sessionState === 'env');
             const duplicateOf = isTurn ? findDuplicateTurn(db, input) : null;
@@ -249,22 +178,13 @@ export function writeDeliveryEvent(db, input) {
                 insertCandidate.run(eventId, input.tenantId, c.memoryId, c.sourceStore, c.pool, c.stage, c.outcome, c.reason, c.rank, c.score, c.tokens);
             }
             const pruneFrom = Math.min(Date.parse(input.ts), Date.now());
-            const cutoff = new Date(pruneFrom - DELIVERY_LEDGER_RETENTION_DAYS * 86_400_000).toISOString();
+            const cutoff = new Date(pruneFrom - DELIVERY_LEDGER_RETENTION_DAYS * DAY_MS).toISOString();
             db.prepare(`DELETE FROM delivery_events WHERE ts < ?`).run(cutoff);
-            db.exec('COMMIT');
             return eventId;
-        }
-        catch (error) {
-            try {
-                db.exec('ROLLBACK');
-            }
-            catch { /* SQLite may already have rolled back (SQLITE_FULL, IOERR); keep the original error */ }
-            throw error;
-        }
+        });
     }
     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: ${error instanceof Error ? error.message : String(error)}`);
+        log.error(`delivery ledger write failed: ${errorMessage(error)}`);
         return null;
     }
 }
@@ -275,8 +195,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: ${error instanceof Error ? error.message : String(error)}`);
+        log.error(`delivery ledger write failed: ${errorMessage(error)}`);
         return null;
     }
     try {

package/dist/store/rejected-values.d.ts

@@ -0,0 +1,55 @@
+import type { MemoryEntry } from '../core/memory.js';
+import { entryRejectRowAt } from './entry-reads.js';
+import { type RejectedValueRow } from './rejection.js';
+type HoldsValue = (text: string) => boolean;
+/** The text, tenant and scope of the memory a rejection names. */
+export type RejectionSource = NonNullable<ReturnType<typeof entryRejectRowAt>>;
+/** One rejection as the store applies it. The three functions are the caller's policy over plain rows; none is handed the handle. */
+export interface Rejection {
+    readonly tenantId: string;
+    readonly actor: string;
+    readonly reason: string;
+    /** The memory whose row `textOf` is given; unset when the caller supplies the text itself. */
+    readonly memoryId?: string;
+    /** The text to reject. `source` is undefined when `memoryId` is unset or names no row; a throw refuses before any write. */
+    readonly textOf: (source: RejectionSource | undefined) => string;
+    /** False for a row this caller may not remove. */
+    readonly inReach: (scope: string | null | undefined) => boolean;
+    /** What replaces a merged row once the rejected text leaves it: undefined when it holds none, null when nothing else is left. */
+    readonly successorOf: (row: MemoryEntry, holdsValue: HoldsValue, removedIds: ReadonlySet<string>) => MemoryEntry | null | undefined;
+}
+export interface AppliedRejection {
+    digest: string;
+    /** The rejected text: the stored row keeps only its digest, so no later read can return it. */
+    content: string;
+    /** Every row removed, live or dormant: each whose digest matched, duplicates included, and each sleep-merged row holding the text. */
+    removedIds: string[];
+    /** The removedIds of kind 'raw', archived instead of deleted. */
+    removedRawIds: string[];
+    /** The rows that carry a live merged row's other texts; dormantSuccessorIds is the same for a dormant one. */
+    successorIds: string[];
+    dormantSuccessorIds: string[];
+}
+/** Applies one rejection on one handle and in one write scope: the rejected-value row, the removal of every row in reach that holds the
+ *  text (live or dormant, whole or inside a merged row) and one reject_value audit row. Markdown mirrors follow the commit. */
+export declare function applyRejection(hippoRoot: string, rejection: Rejection): AppliedRejection;
+export type LiftedRejection = {
+    status: 'ok';
+    digest: string;
+    reason: string | null;
+} | {
+    status: 'not_found';
+} | {
+    status: 'ambiguous';
+    candidates: RejectedValueRow[];
+};
+/** 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 declare function liftRejection(hippoRoot: string, tenantId: string, digestPrefix: string, actor: string): LiftedRejection;
+/** The tenant's rejected values, newest first. */
+export declare function loadRejectedValues(hippoRoot: string, tenantId: string): RejectedValueRow[];
+/** 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. */
+export declare function rejectionGuardRefuses(hippoRoot: string, tenantId: string, entryId: string, content: string): boolean;
+export {};
+//# sourceMappingURL=rejected-values.d.ts.map