hippo-memory 1.68.0 → 1.70.0

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

@@ -14,8 +14,8 @@
  * 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';
+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 {
@@ -44,10 +44,10 @@ export interface RecallTraceInput {
  * 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.
+ * 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.
  */
 export declare function writeRecallTrace(db: DatabaseSyncLike, input: RecallTraceInput): number | null;
 /**
@@ -55,11 +55,10 @@ export declare function writeRecallTrace(db: DatabaseSyncLike, input: RecallTrac
  * 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).
+ * 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
@@ -68,8 +67,8 @@ export declare function writeRecallTrace(db: DatabaseSyncLike, input: RecallTrac
  * `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.
+ * (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.
  */
@@ -115,7 +114,7 @@ export declare function recordTraceOutcome(db: DatabaseSyncLike, input: RecordTr
 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}

@@ -15,9 +15,10 @@
  * 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';
+import { openHippoDb, closeHippoDb, rethrowIfSqliteBlocked, withWriteScope } from '../db/index.js';
+import { DELIVERY_LEDGER_VERSION, isBoundaryEvent } from './delivery-recorder.js';
+import { 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
@@ -40,17 +41,16 @@ function sanitizeRerankSteps(steps) {
  * 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.
+ * 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.
  */
 export function writeRecallTrace(db, input) {
     try {
         const queryHash = createHash('sha256').update(input.query).digest('hex').slice(0, 16);
         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,19 +64,11 @@ 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)}`);
         return null;
     }
 }
@@ -85,11 +77,10 @@ export function writeRecallTrace(db, input) {
  * 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).
+ * 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
@@ -98,8 +89,8 @@ export function writeRecallTrace(db, input) {
  * `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.
+ * (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.
  */
@@ -110,7 +101,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)}`);
         return null;
     }
     try {
@@ -174,14 +165,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)}`);
     }
 }
 /** 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 +181,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 +227,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 +252,14 @@ 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)}`);
+        console.error(`[hippo] delivery ledger write failed: ${errorMessage(error)}`);
         return null;
     }
 }
@@ -276,7 +271,7 @@ export function writeDeliveryEventAtRoot(root, input) {
     }
     catch (error) {
         // Same hook stderr line as writeDeliveryEvent above.
-        console.error(`[hippo] delivery ledger write failed: ${error instanceof Error ? error.message : String(error)}`);
+        console.error(`[hippo] 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

package/dist/store/rejected-values.js

@@ -0,0 +1,162 @@
+// Reject, unreject and list rejected values, each on one handle of its own.
+// A file apart from rejection.ts: store/open.ts imports that one, so an open there would be an import cycle.
+import { closeHippoDb, openHippoDb, withWriteScope } from '../db/index.js';
+import { heldTexts } from '../util/same-text.js';
+import { audit } from './audit-event.js';
+import { deleteEntryCore } from './delete-and-batch.js';
+import { deleteDormantRow, listDormantSnapshots, purgeDormantByDigest, replaceDormantEntry } from './dormant.js';
+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 { archiveRawMemory, markMirrorCleaned } from './raw-archive.js';
+import { RejectedValueError, checkRejectionGuard, deleteRejectedValue, insertRejectedValue, listRejectedValues, normalizeValueForRejection, rejectionDigest, } from './rejection.js';
+function removeLiveRows(db, hippoRoot, rejection, holdsValue, removal) {
+    const { tenantId, actor, reason } = rejection;
+    const { removedIds, removedRawIds, successors } = removal;
+    const merged = [];
+    for (const row of selectAllEntries(db, tenantId)) {
+        if (!rejection.inReach(row.scope))
+            continue;
+        if (!holdsValue(row.content)) {
+            if (heldTexts(row).some(holdsValue))
+                merged.push(row);
+            continue;
+        }
+        if (row.kind === 'raw') {
+            // A raw row is append-only: archiving is its one removal path, and its savepoint nests in this write scope.
+            archiveRawMemory(db, row.id, { reason, who: actor });
+            removedRawIds.push(row.id);
+        }
+        else {
+            // The one reject_value row is the trail for these removals, so no forget row each.
+            deleteEntryCore(db, row.id, { actor, suppressForgetAudit: true });
+        }
+        removedIds.push(row.id);
+    }
+    for (const row of merged) {
+        const successor = rejection.successorOf(row, holdsValue, new Set(removedIds));
+        deleteEntryCore(db, row.id, { actor, suppressForgetAudit: true });
+        removedIds.push(row.id);
+        if (!successor)
+            continue;
+        const kept = stampOriginProject(hippoRoot, successor);
+        writeEntryDbOnly(db, kept, { actor });
+        successors.push(kept);
+    }
+}
+// Dormant copies go in the same write scope, so `hippo dormant restore` cannot bring the text back. They have no mirror to purge.
+function removeDormantCopies(db, rejection, digest, holdsValue, removal) {
+    const { tenantId } = rejection;
+    const { removedIds, dormantSuccessorIds } = removal;
+    removedIds.push(...purgeDormantByDigest(db, tenantId, digest, rejection.inReach));
+    for (const dormant of listDormantSnapshots(db, tenantId)) {
+        if (!rejection.inReach(dormant.entry.scope))
+            continue;
+        const successor = rejection.successorOf(dormant.entry, holdsValue, new Set(removedIds));
+        if (successor === undefined)
+            continue;
+        removedIds.push(dormant.entry.id);
+        if (!successor) {
+            deleteDormantRow(db, tenantId, dormant.entry.id);
+            continue;
+        }
+        replaceDormantEntry(db, tenantId, dormant.entry.id, successor);
+        dormantSuccessorIds.push(successor.id);
+    }
+}
+// After the commit, on the same handle: a purged raw mirror is stamped so the reaper skips it, and one that stays is logged.
+function purgeRemovedMirrors(db, hippoRoot, removal) {
+    for (const id of removal.removedIds) {
+        const isRaw = removal.removedRawIds.includes(id);
+        const mirrorOk = purgeMirrorBestEffort(hippoRoot, id, isRaw, 'hippo reject');
+        if (mirrorOk && isRaw)
+            markMirrorCleaned(db, id, new Date().toISOString());
+    }
+    for (const successor of removal.successors)
+        writeEntryMirrors(hippoRoot, successor);
+}
+/** 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 function applyRejection(hippoRoot, rejection) {
+    const { tenantId, actor, reason, memoryId } = rejection;
+    const db = openStore(hippoRoot);
+    try {
+        const content = rejection.textOf(memoryId === undefined ? undefined : entryRejectRowAt(db, memoryId));
+        const digest = rejectionDigest(content);
+        const rejectedAt = new Date().toISOString();
+        const removal = { removedIds: [], removedRawIds: [], successors: [], dormantSuccessorIds: [] };
+        withWriteScope(db, 'reject_value', () => {
+            insertRejectedValue(db, {
+                tenantId,
+                digest,
+                reason,
+                rejectedBy: actor,
+                rejectedAt,
+                sourceMemoryId: memoryId ?? null,
+                normalizedChars: normalizeValueForRejection(content).length,
+            });
+            // SHORTCUT: scans every row of the tenant, fine for a human-run command; a digest column on memories if stores grow a hundredfold.
+            const holdsValue = (text) => rejectionDigest(text) === digest;
+            removeLiveRows(db, hippoRoot, rejection, holdsValue, removal);
+            removeDormantCopies(db, rejection, digest, holdsValue, removal);
+            // Still inside the write scope: a failed audit row is reported and the reject commits without it.
+            const { removedIds } = removal;
+            audit(db, 'reject_value', { tenantId, actor, targetId: memoryId, metadata: { digest, removedIds, count: removedIds.length } });
+        });
+        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);
+    }
+}
+/** 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 {
+        const matches = listRejectedValues(db, tenantId).filter((r) => r.digest.startsWith(digestPrefix));
+        const target = matches[0];
+        if (target === undefined)
+            return { status: 'not_found' };
+        if (matches.length > 1)
+            return { status: 'ambiguous', candidates: matches };
+        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);
+    }
+}
+/** The tenant's rejected values, newest first. */
+export function loadRejectedValues(hippoRoot, tenantId) {
+    const db = openStore(hippoRoot);
+    try {
+        return listRejectedValues(db, tenantId);
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/** 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 function rejectionGuardRefuses(hippoRoot, tenantId, entryId, content) {
+    const db = openHippoDb(hippoRoot);
+    try {
+        checkRejectionGuard(db, tenantId, entryId, content);
+        return false;
+    }
+    catch (err) {
+        if (err instanceof RejectedValueError)
+            return true;
+        throw err;
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+//# sourceMappingURL=rejected-values.js.map

package/dist/{rejection.d.ts → store/rejection.d.ts}

@@ -10,8 +10,8 @@
  * import from store.ts — store.ts imports from here, and the reverse would
  * be a cycle.
  */
-import type { DatabaseSyncLike } from './db.js';
-import { BadRequestError } from './api-errors.js';
+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

package/dist/{rejection.js → store/rejection.js}

@@ -11,7 +11,8 @@
  * be a cycle.
  */
 import { createHash } from 'node:crypto';
-import { BadRequestError } from './api-errors.js';
+import { BadRequestError } from '../core/api-errors.js';
+import { DIGEST_DISPLAY_CHARS } from '../util/token-text.js';
 /**
  * Normalize content for rejection-digest comparisons: Unicode NFC →
  * lowercase → collapse whitespace runs to a single space → trim. No
@@ -44,7 +45,7 @@ export class RejectedValueError extends BadRequestError {
     reason;
     rejectedAt;
     constructor(opts) {
-        super(`Memory value refused: matches a rejected value (digest ${opts.digest.slice(0, 12)}..., ` +
+        super(`Memory value refused: matches a rejected value (digest ${opts.digest.slice(0, DIGEST_DISPLAY_CHARS)}..., ` +
             `reason: ${opts.reason ?? 'none given'}). Run "hippo unreject" to allow it again.`);
         this.name = 'RejectedValueError';
         this.digest = opts.digest;

package/dist/store/rows.d.ts

@@ -1,5 +1,5 @@
-import { Layer, type MemoryEntry, type ConfidenceLevel } from '../memory.js';
-import type { JsonValue } from '../json.js';
+import { Layer, type MemoryEntry, type ConfidenceLevel } from '../core/memory.js';
+import { type JsonValue } from '../util/json.js';
 export interface IndexEntry {
     id: string;
     file: string;
@@ -156,7 +156,6 @@ export declare function parseJsonArray(raw: string | null | undefined): string[]
  * re-parses the raw meta string itself.
  */
 export declare function parseLastTraceId(raw: string | null | undefined): string | null;
-export declare function isPlainJsonObject(x: JsonValue): x is Record<string, JsonValue>;
 export declare function rowToTaskSnapshot(row: TaskSnapshotRow): TaskSnapshot;
 export declare function rowToMemoryConflict(row: MemoryConflictRow): MemoryConflict;
 export declare function rowToSessionEvent(row: SessionEventRow): SessionEvent;

package/dist/store/rows.js

@@ -1,4 +1,6 @@
-import { log } from '../log.js';
+import { FALLBACK_HALF_LIFE_DAYS, DEFAULT_SCHEMA_FIT } from '../core/memory.js';
+import { errorMessage, log } from '../util/log.js';
+import { isJsonObject } from '../util/json.js';
 export const INDEX_VERSION = 3;
 export const MEMORY_SELECT_COLUMNS = `id, created, last_retrieved, retrieval_count, strength, half_life_days, layer, tags_json, emotional_valence, schema_fit, source, outcome_score, outcome_positive, outcome_negative, conflicts_with_json, pinned, confidence, content, parents_json, starred, trace_outcome, source_session_id, valid_from, superseded_by, extracted_from, dag_level, dag_parent_id, kind, scope, owner, artifact_ref, tenant_id, origin_project, descendant_count, earliest_at, latest_at, summary_dirty, last_rebuilt_at, rebuild_count, dag_level_3_built_at`;
 // FTS-join columns for loadSearchRows: each is `m.<col> AS <col>` so rowToEntry's unqualified
@@ -10,22 +12,22 @@ export const MEMORY_SEARCH_COLUMNS = `m.id AS id, m.created AS created, m.last_r
  * this for `RecallResult.windowSize` reporting so the two cannot drift.
  */
 export const DEFAULT_SEARCH_CANDIDATE_LIMIT = 200;
-export function rowToEntry(row) {
+function rowToRetrievalFields(row) {
     // SAFETY: every `as X` below narrows a SQLite column value to an
     // enum/union member of MemoryEntry; `row` comes from MEMORY_SELECT_COLUMNS
     // / MEMORY_SEARCH_COLUMNS, which are the only queries producing MemoryRow,
     // and the DB layer only ever writes these columns from the same enums.
-    const entry = {
+    return {
         id: row.id,
         created: row.created,
         last_retrieved: row.last_retrieved,
         retrieval_count: Number(row.retrieval_count ?? 0),
         strength: Number(row.strength ?? 1),
-        half_life_days: Number(row.half_life_days ?? 7),
+        half_life_days: Number(row.half_life_days ?? FALLBACK_HALF_LIFE_DAYS),
         layer: row.layer,
         tags: parseJsonArray(row.tags_json),
         emotional_valence: row.emotional_valence ?? 'neutral',
-        schema_fit: Number(row.schema_fit ?? 0.5),
+        schema_fit: Number(row.schema_fit ?? DEFAULT_SCHEMA_FIT),
         source: row.source ?? 'cli',
         outcome_score: row.outcome_score === null || row.outcome_score === undefined ? null : Number(row.outcome_score),
         outcome_positive: Number(row.outcome_positive ?? 0),
@@ -37,6 +39,11 @@ export function rowToEntry(row) {
         parents: parseJsonArray(row.parents_json),
         starred: Boolean(row.starred),
         trace_outcome: row.trace_outcome ?? null,
+    };
+}
+function rowToPlacementFields(row) {
+    // SAFETY: the `as MemoryKind` narrows a column the DB layer only writes from that enum.
+    return {
         source_session_id: row.source_session_id ?? null,
         valid_from: row.valid_from ?? row.created,
         superseded_by: row.superseded_by ?? null,
@@ -57,6 +64,9 @@ export function rowToEntry(row) {
         rebuild_count: Number(row.rebuild_count ?? 0),
         dag_level_3_built_at: row.dag_level_3_built_at ?? null,
     };
+}
+export function rowToEntry(row) {
+    const entry = { ...rowToRetrievalFields(row), ...rowToPlacementFields(row) };
     // Preserve bm25_score from the FTS path; `'bm25_score' in row` tells an absent column
     // (non-FTS path) from a present one.
     if ('bm25_score' in row && row.bm25_score !== undefined && row.bm25_score !== null) {
@@ -72,7 +82,7 @@ export function parseJsonArray(raw) {
         return Array.isArray(parsed) ? parsed.map((item) => String(item)) : [];
     }
     catch (err) {
-        log.debug(`store: corrupt JSON array column read as empty: ${err instanceof Error ? err.message : String(err)}`);
+        log.debug(`store: corrupt JSON array column read as empty: ${errorMessage(err)}`);
         return [];
     }
 }
@@ -93,21 +103,18 @@ export function parseLastTraceId(raw) {
         return null;
     return trimmed;
 }
-export function isPlainJsonObject(x) {
-    return x !== null && typeof x === 'object' && !Array.isArray(x);
-}
 function parseJsonObject(raw) {
     if (!raw)
         return {};
     try {
         const parsed = JSON.parse(raw);
-        if (isPlainJsonObject(parsed)) {
+        if (isJsonObject(parsed)) {
             return parsed;
         }
         return {};
     }
     catch (err) {
-        log.debug(`store: corrupt JSON object column read as empty: ${err instanceof Error ? err.message : String(err)}`);
+        log.debug(`store: corrupt JSON object column read as empty: ${errorMessage(err)}`);
         return {};
     }
 }

package/dist/store/search-rows.d.ts

@@ -1,5 +1,5 @@
-import type { MemoryEntry } from '../memory.js';
-import { type DatabaseSyncLike } from '../db.js';
+import type { MemoryEntry } from '../core/memory.js';
+import { type DatabaseSyncLike } from '../db/index.js';
 /**
  * Recall-mode scope filter shape, exported so callers and tests can name it. Three modes:
  *   - 'default-deny': exclude scopes in `RECALL_DEFAULT_DENY_SCOPES`.
@@ -28,6 +28,8 @@ export type RecallScopeFilter = {
 export type OriginFilter = string | readonly string[];
 /** Scope rule for recall: none requested is default-deny; 'exact' narrows to the request; 'additive' adds it to the default set, unless it is personal, which only `ownScope` opens. */
 export declare function recallScopeFilter(requestedScope: string | undefined, mode: 'exact' | 'additive', ownScope?: string): RecallScopeFilter;
+/** Sends term queries down the LIKE path on a build that has FTS. Only tests call it. */
+export declare function _forceLikePathForTests(on: boolean): void;
 /**
  * Load likely search candidates directly from SQLite.
  * Uses FTS5 when available, falls back to LIKE matching, then full-store fallback.
@@ -54,7 +56,16 @@ export declare function loadSearchEntries(hippoRoot: string, query: string, limi
  * `tenantId` is optional because searchBothHybrid's is; undefined means no tenant filter.
  */
 export declare function loadRecallSearchEntries(hippoRoot: string, query: string, limit?: number, tenantId?: string, requestedScope?: string, explicitScopeMode?: 'exact' | 'additive', includeSuperseded?: boolean, originProjects?: OriginFilter, ownScope?: string): MemoryEntry[];
-export declare function loadRecallSearchEntriesFromDb(db: DatabaseSyncLike, query: string, limit?: number, tenantId?: string, requestedScope?: string, explicitScopeMode?: 'exact' | 'additive', includeSuperseded?: boolean, originProjects?: OriginFilter, ownScope?: string): MemoryEntry[];
+export interface RecallSearchEntriesOptions {
+    readonly limit?: number;
+    readonly tenantId?: string;
+    readonly requestedScope?: string;
+    readonly explicitScopeMode?: 'exact' | 'additive';
+    readonly includeSuperseded?: boolean;
+    readonly originProjects?: OriginFilter;
+    readonly ownScope?: string;
+}
+export declare function loadRecallSearchEntriesFromDb(db: DatabaseSyncLike, query: string, options?: RecallSearchEntriesOptions): MemoryEntry[];
 /** Which rows the vector arm of hybrid search may add: the same tenant, scope and superseded rules as the lexical load. */
 export interface VectorCandidateSpec {
     tenantId?: string;
@@ -65,7 +76,7 @@ export interface VectorCandidateSpec {
     origin?: OriginFilter;
 }
 /** The rows nearest `queryVector` that pass `spec`, nearest first. */
-export declare function loadVectorCandidateEntries(hippoRoot: string, queryVector: readonly number[], spec: VectorCandidateSpec): MemoryEntry[];
+export declare function loadVectorCandidateEntries(hippoRoot: string, queryVector: readonly number[], spec: VectorCandidateSpec): Promise<MemoryEntry[]>;
 /** Rarest-K prompt terms for this connection's FTS index, as a space-joined query string.
  *  Without FTS, returns the first 32 terms, as before rarest-term selection. */
 export declare function pickRarestFtsQuery(db: DatabaseSyncLike, terms: readonly string[], maxTerms?: number): string;