hippo-memory 1.72.0 → 2.1.0

package/dist/store/rejection.js

@@ -1,16 +1,10 @@
-/** 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 { createHash } from 'node:crypto';
+/** 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 { normalizeValueForRejection, rejectionDigest } from '../core/rejection-digest.js';
 import { RejectedValueError } from '../core/api-errors.js';
-/** Normalize content for rejection digests: NFC, lowercase, collapse whitespace runs, trim. No punctuation stripping: over-normalizing causes false
- * refusals, worse than misses. */
-export function normalizeValueForRejection(content) {
-    return content.normalize('NFC').toLowerCase().replace(/\s+/g, ' ').trim();
-}
-/** 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 function rejectionDigest(content) {
-    return createHash('sha256').update(normalizeValueForRejection(content)).digest('hex');
-}
+// store-kit publishes rejectionDigest from this path.
+export { normalizeValueForRejection, rejectionDigest };
 function rowToRejectedValue(row) {
     return {
         tenantId: row.tenant_id,
@@ -22,7 +16,8 @@ function rowToRejectedValue(row) {
         normalizedChars: row.normalized_chars,
     };
 }
-/** Look up a tombstone by tenant + digest: one indexed point query, the guard's common-case cost; a miss ends the guard. */
+/** Look up a tombstone by tenant + digest: one indexed point query, the guard's common-case cost; a miss ends the
+ * guard. */
 export function findRejectedValue(db, tenantId, digest) {
     // SAFETY: row's shape matches the columns named in the SELECT above.
     const row = db
@@ -31,9 +26,11 @@ export function findRejectedValue(db, tenantId, digest) {
         .get(tenantId, digest);
     return row ? rowToRejectedValue(row) : null;
 }
-/** Insert (or refresh) a tombstone row; the caller owns the transaction (used by the `reject` verb and `resolveConflict`'s `rejectLoserValue`). */
+/** Insert (or refresh) a tombstone row; the caller owns the transaction (used by the `reject` verb and
+ * `resolveConflict`'s `rejectLoserValue`). */
 export function insertRejectedValue(db, opts) {
-    db.prepare(`INSERT INTO rejected_values(tenant_id, digest, reason, rejected_by, rejected_at, source_memory_id, normalized_chars)
+    db.prepare(`INSERT INTO rejected_values(tenant_id, digest, reason, rejected_by, rejected_at, source_memory_id, ` +
+        `normalized_chars)
      VALUES (?, ?, ?, ?, ?, ?, ?)
      ON CONFLICT(tenant_id, digest) DO UPDATE SET
        reason = excluded.reason,
@@ -56,15 +53,17 @@ export function listRejectedValues(db, tenantId) {
         .all(tenantId);
     return rows.map(rowToRejectedValue);
 }
-/** 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. */
+/** 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 function checkRejectionGuard(db, tenantId, entryId, content) {
     const incomingDigest = rejectionDigest(content);
     const tombstone = findRejectedValue(db, tenantId, incomingDigest);
     if (!tombstone)
         return; // miss ends the guard — the overwhelmingly common case
-    // Id-only on purpose (ids are global ULIDs; the tombstone lookup is tenant-scoped); tenant_id is read as a tenantId-only upsert introduces content there.
-    // SAFETY: storedRow's shape matches the two columns named in the SELECT above.
+    // Id-only on purpose (ids are global ULIDs; the tombstone lookup is tenant-scoped); tenant_id is read as a
+    // tenantId-only upsert introduces content there. SAFETY: storedRow's shape matches the two columns named in the
+    // SELECT above.
     const storedRow = db.prepare(`SELECT content, tenant_id FROM memories WHERE id = ?`).get(entryId);
     const isNewRow = storedRow === undefined;
     const tenantChanged = !isNewRow && storedRow.tenant_id !== tenantId;

package/dist/store/report-reads.d.ts

@@ -1,5 +1,6 @@
 import type { MemoryEntry } from '../core/memory.js';
-/** Every superseded row, the row that replaced it and that row's extraction source, in loadAllEntries' order: all a correction-latency report reads. */
+/** Every superseded row, the row that replaced it and that row's extraction source, in loadAllEntries' order: all a
+ * correction-latency report reads. */
 export declare function loadCorrectionEntries(hippoRoot: string): MemoryEntry[];
 /** The kind='raw' rows in loadAllEntries' order: all a provenance-coverage report reads. */
 export declare function loadRawEntries(hippoRoot: string): MemoryEntry[];

package/dist/store/report-reads.js

@@ -1,6 +1,7 @@
 import { MEMORY_SELECT_COLUMNS, rowToEntry } from './rows.js';
 import { onHandle, openStore } from './open.js';
-/** Every superseded row, the row that replaced it and that row's extraction source, in loadAllEntries' order: all a correction-latency report reads. */
+/** Every superseded row, the row that replaced it and that row's extraction source, in loadAllEntries' order: all a
+ * correction-latency report reads. */
 export function loadCorrectionEntries(hippoRoot) {
     return onHandle(hippoRoot, (db) => {
         const superseded = `superseded_by IS NOT NULL AND superseded_by != ''`;

package/dist/store/rows.d.ts

@@ -137,14 +137,16 @@ export interface SessionEvent {
 export declare const INDEX_VERSION = 3;
 export declare const MEMORY_SELECT_COLUMNS: string;
 export declare const MEMORY_SEARCH_COLUMNS: string;
-/** Default candidate-pool size for `loadSearchEntries` when `limit` is undefined; `api.recall` imports it for `RecallResult.windowSize` so the two cannot
- * drift. */
+/** Default candidate-pool size for `loadSearchEntries` when `limit` is undefined; `api.recall` imports it for
+ * `RecallResult.windowSize` so the two cannot drift. */
 export declare const DEFAULT_SEARCH_CANDIDATE_LIMIT = 200;
 export declare function rowToEntry(row: MemoryRow): MemoryEntry;
-/** A column that is not JSON reads as empty. With `site` the row is named at warn once; without it no row is known and the line stays at debug. */
+/** A column that is not JSON reads as empty. With `site` the row is named at warn once; without it no row is known and
+ * the line stays at debug. */
 export declare function parseJsonArray(raw: string | null | undefined, site?: StoredJsonSite): string[];
-/** Strict parse for `last_trace_id`: Number(raw) turns '' or garbage into 0/NaN (a masked FK violation); require a clean positive integer string, else unset.
- * The ONE place that decides 'clean'; consumers read the validated value from `buildIndexFromDb`'s result and never re-parse. */
+/** Strict parse for `last_trace_id`: Number(raw) turns '' or garbage into 0/NaN (a masked FK violation); require a
+ * clean positive integer string, else unset. The ONE place that decides 'clean'; consumers read the validated value
+ * from `buildIndexFromDb`'s result and never re-parse. */
 export declare function parseLastTraceId(raw: string | null | undefined): string | null;
 export declare function rowToTaskSnapshot(row: TaskSnapshotRow): TaskSnapshot;
 export declare function rowToMemoryConflict(row: MemoryConflictRow): MemoryConflict;

package/dist/store/rows.js

@@ -1,6 +1,6 @@
 import { DEFAULT_TENANT_ID } from '../util/env.js';
-import { FALLBACK_HALF_LIFE_DAYS, DEFAULT_SCHEMA_FIT } from '../core/memory.js';
-import { errorMessage, log } from '../util/log.js';
+import { FALLBACK_HALF_LIFE_DAYS, DEFAULT_SCHEMA_FIT, } from '../core/memory.js';
+import { errorMessage, log, errorFields } from '../util/log.js';
 import { isJsonObject } from '../util/json.js';
 import { warnDamagedColumn } from '../util/stored-json.js';
 export const INDEX_VERSION = 3;
@@ -18,12 +18,13 @@ export const MEMORY_SEARCH_COLUMNS = [
     ...MEMORY_COLUMN_NAMES.map((c) => `m.${c} AS ${c}`),
     'bm25(memories_fts) AS bm25_score',
 ].join(', ');
-/** Default candidate-pool size for `loadSearchEntries` when `limit` is undefined; `api.recall` imports it for `RecallResult.windowSize` so the two cannot
- * drift. */
+/** Default candidate-pool size for `loadSearchEntries` when `limit` is undefined; `api.recall` imports it for
+ * `RecallResult.windowSize` so the two cannot drift. */
 export const DEFAULT_SEARCH_CANDIDATE_LIMIT = 200;
 function rowToRetrievalFields(row) {
-    // SAFETY: every `as X` narrows a SQLite column to a MemoryEntry enum/union member; `row` comes from MEMORY_SELECT_COLUMNS / MEMORY_SEARCH_COLUMNS,
-    // the only queries producing MemoryRow, and the DB layer writes these columns only from the same enums.
+    // SAFETY: every `as X` narrows a SQLite column to a MemoryEntry enum/union member; `row` comes from
+    // MEMORY_SELECT_COLUMNS / MEMORY_SEARCH_COLUMNS, the only queries producing MemoryRow, and the DB layer writes these
+    // columns only from the same enums.
     return {
         id: row.id,
         created: row.created,
@@ -39,7 +40,11 @@ function rowToRetrievalFields(row) {
         outcome_score: row.outcome_score === null || row.outcome_score === undefined ? null : Number(row.outcome_score),
         outcome_positive: Number(row.outcome_positive ?? 0),
         outcome_negative: Number(row.outcome_negative ?? 0),
-        conflicts_with: parseJsonArray(row.conflicts_with_json, { table: 'memories', id: row.id, column: 'conflicts_with_json' }),
+        conflicts_with: parseJsonArray(row.conflicts_with_json, {
+            table: 'memories',
+            id: row.id,
+            column: 'conflicts_with_json',
+        }),
         pinned: Boolean(row.pinned),
         confidence: row.confidence ?? 'observed',
         content: row.content,
@@ -61,12 +66,12 @@ function rowToPlacementFields(row) {
         scope: row.scope ?? null,
         owner: row.owner ?? null,
         artifact_ref: row.artifact_ref ?? null,
-        tenantId: row.tenant_id ?? DEFAULT_TENANT_ID,
+        tenant_id: row.tenant_id ?? DEFAULT_TENANT_ID,
         origin_project: row.origin_project ?? null,
         descendant_count: Number(row.descendant_count ?? 0),
         earliest_at: row.earliest_at ?? null,
         latest_at: row.latest_at ?? null,
-        summary_dirty: (Number(row.summary_dirty ?? 0) === 1 ? 1 : 0),
+        summary_dirty: Number(row.summary_dirty) === 1,
         last_rebuilt_at: row.last_rebuilt_at ?? null,
         rebuild_count: Number(row.rebuild_count ?? 0),
         dag_level_3_built_at: row.dag_level_3_built_at ?? null,
@@ -81,7 +86,8 @@ export function rowToEntry(row) {
     }
     return entry;
 }
-/** A column that is not JSON reads as empty. With `site` the row is named at warn once; without it no row is known and the line stays at debug. */
+/** A column that is not JSON reads as empty. With `site` the row is named at warn once; without it no row is known and
+ * the line stays at debug. */
 export function parseJsonArray(raw, site) {
     if (!raw)
         return [];
@@ -93,12 +99,13 @@ export function parseJsonArray(raw, site) {
         if (site)
             warnDamagedColumn(site, 'not valid JSON');
         else
-            log.debug(`store: corrupt JSON array column read as empty: ${errorMessage(err)}`);
+            log.debug(`store: corrupt JSON array column read as empty: ${errorMessage(err)}`, errorFields(err));
         return [];
     }
 }
-/** Strict parse for `last_trace_id`: Number(raw) turns '' or garbage into 0/NaN (a masked FK violation); require a clean positive integer string, else unset.
- * The ONE place that decides 'clean'; consumers read the validated value from `buildIndexFromDb`'s result and never re-parse. */
+/** Strict parse for `last_trace_id`: Number(raw) turns '' or garbage into 0/NaN (a masked FK violation); require a
+ * clean positive integer string, else unset. The ONE place that decides 'clean'; consumers read the validated value
+ * from `buildIndexFromDb`'s result and never re-parse. */
 export function parseLastTraceId(raw) {
     const trimmed = (raw ?? '').trim();
     if (!/^\d+$/.test(trimmed) || Number(trimmed) <= 0)

package/dist/store/rule-sql.d.ts

@@ -1,12 +1,16 @@
-/** calculateStrength's clock-basis formula as SQL over `memories` columns, flags and multipliers baked in; keep in step.
- *  An unparseable date scores NULL here and 0 in JS, so sums agree. */
+/** calculateRewardFactor as SQL over `memories` columns; strengthSql and the context-candidate rank both build on it,
+ * so the slope has one source. */
+export declare function rewardFactorSql(): string;
+/** calculateStrength's clock-basis formula as SQL over `memories` columns, flags and multipliers baked in; keep in
+ * step. An unparseable date scores NULL here and 0 in JS, so sums agree. */
 export declare function strengthSql(now: Date): string;
 export declare const AUTO_DELETABLE_SQL: string;
 export interface SqlFragment {
     sql: string;
     params: string[];
 }
-/** SQL twin of the no-request arm of passesScopeFilterForRecall; `ownScope` is bound and compared with `=`, so `%` or `_` in an owner match nothing extra. */
+/** SQL twin of the no-request arm of passesScopeFilterForRecall; `ownScope` is bound and compared with `=`, so `%` or
+ * `_` in an owner match nothing extra. */
 export declare function scopeAdmitSql(col: '' | 'm.', ownScope?: string | null): SqlFragment;
 /** 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. */

package/dist/store/rule-sql.js

@@ -1,26 +1,36 @@
-// The SQL twins of the model's rules in src/core: strength and keep (memory.ts), recall scope (recall-scope.ts); keep each in step with its JS half.
+// The SQL twins of the model's rules in src/core: strength and keep (memory.ts), recall scope (recall-scope.ts); keep
+// each in step with its JS half.
 import { DAY_MS } from '../util/time.js';
 import { isDecayAblated, isOutcomeSlowAblated, isRecallBoostAblated } from '../core/ablation.js';
 import { DECAY_BASE, EMOTIONAL_MULTIPLIERS, FALLBACK_HALF_LIFE_DAYS, KEEP_PAIRS, MAX_WRONG_HALVINGS, RETRIEVAL_BOOST_SLOPE, REWARD_SLOPE, applyLossAversionRatio, } from '../core/memory.js';
 import { PERSONAL_SCOPE_PREFIX, RECALL_DEFAULT_DENY_SCOPES } from '../core/recall-scope.js';
+import { placeholders } from '../util/sql.js';
 const UNIX_EPOCH_JULIAN_DAY = 2440587.5;
-/** calculateStrength's clock-basis formula as SQL over `memories` columns, flags and multipliers baked in; keep in step.
- *  An unparseable date scores NULL here and 0 in JS, so sums agree. */
+/** calculateRewardFactor as SQL over `memories` columns; strengthSql and the context-candidate rank both build on it,
+ * so the slope has one source. */
+export function rewardFactorSql() {
+    if (isOutcomeSlowAblated())
+        return '1.0';
+    const pos = 'COALESCE(outcome_positive, 0)';
+    const neg = 'COALESCE(outcome_negative, 0)';
+    return `(CASE WHEN ${pos} = 0 AND ${neg} = 0 THEN 1.0 ELSE 1.0 + ${REWARD_SLOPE} * (${pos} - ${neg}) / (${pos} + ` +
+        `${neg} + 1.0) END)`;
+}
+/** calculateStrength's clock-basis formula as SQL over `memories` columns, flags and multipliers baked in; keep in
+ * step. An unparseable date scores NULL here and 0 in JS, so sums agree. */
 export function strengthSql(now) {
     const num = (n) => (Number.isInteger(n) ? n.toFixed(1) : String(n));
     const pos = 'COALESCE(outcome_positive, 0)';
     const neg = 'COALESCE(outcome_negative, 0)';
     const wrong = isOutcomeSlowAblated() || isDecayAblated() ? '0' : `MAX(0, ${neg} - ${pos})`;
-    const reward = isOutcomeSlowAblated()
-        ? '1.0'
-        : `(CASE WHEN ${pos} = 0 AND ${neg} = 0 THEN 1.0 ELSE 1.0 + ${REWARD_SLOPE} * (${pos} - ${neg}) / (${pos} + ${neg} + 1.0) END)`;
-    const halfLife = `(COALESCE(half_life_days, ${FALLBACK_HALF_LIFE_DAYS}) * ${reward})`;
+    const halfLife = `(COALESCE(half_life_days, ${FALLBACK_HALF_LIFE_DAYS}) * ${rewardFactorSql()})`;
     const anchor = isRecallBoostAblated() ? 'created' : 'last_retrieved';
     const nowJulian = num(now.getTime() / DAY_MS + UNIX_EPOCH_JULIAN_DAY);
     const decay = isDecayAblated() ? '1.0' : `pow(${DECAY_BASE}, (${nowJulian} - julianday(${anchor})) / ${halfLife})`;
     const boost = isRecallBoostAblated()
         ? '1.0'
-        : `(CASE WHEN ${wrong} > 0 THEN 1.0 ELSE 1.0 + ${RETRIEVAL_BOOST_SLOPE} * log2(COALESCE(retrieval_count, 0) + 1) END)`;
+        : `(CASE WHEN ${wrong} > 0 THEN 1.0 ELSE 1.0 + ${RETRIEVAL_BOOST_SLOPE} * log2(COALESCE(retrieval_count, 0) + 1) ` +
+            `END)`;
     const valences = /* SAFETY: a Record keyed by EmotionalValence */ Object.keys(EMOTIONAL_MULTIPLIERS);
     const emotion = `(CASE COALESCE(emotional_valence, 'neutral') ${valences
         .map((v) => `WHEN '${v}' THEN ${num(applyLossAversionRatio(v, EMOTIONAL_MULTIPLIERS[v]))}`)
@@ -31,15 +41,18 @@ export function strengthSql(now) {
 }
 const sqlText = (s) => `'${s.replace(/'/g, "''")}'`;
 // json_each matches the tag as a whole element; substr, not LIKE, keeps the prefix case-sensitive like startsWith.
-const keepPairSql = (p) => `(COALESCE(superseded_by, '') = '' AND EXISTS (SELECT 1 FROM json_each(CASE WHEN json_valid(tags_json) THEN tags_json ELSE '[]' END) ` +
+const keepPairSql = (p) => `(COALESCE(superseded_by, '') = '' AND EXISTS (SELECT 1 FROM json_each(CASE WHEN json_valid(tags_json) THEN ` +
+    `tags_json ELSE '[]' END) ` +
     `WHERE value = ${sqlText(p.tag)}) AND substr(source, 1, ${p.sourcePrefix.length}) = ${sqlText(p.sourcePrefix)})`;
 // Pinned and kept rows stay (a superseded row is not kept: its successor carries the tag and
 // source); raw rows leave only through archiveRawMemory. The SQL twin guards the DELETE itself.
-export const AUTO_DELETABLE_SQL = `pinned = 0 AND kind != 'raw'${KEEP_PAIRS.map((p) => ` AND NOT ${keepPairSql(p)}`).join('')}`;
-/** SQL twin of the no-request arm of passesScopeFilterForRecall; `ownScope` is bound and compared with `=`, so `%` or `_` in an owner match nothing extra. */
+export const AUTO_DELETABLE_SQL = `pinned = 0 AND kind != ` +
+    `'raw'${KEEP_PAIRS.map((p) => ` AND NOT ${keepPairSql(p)}`).join('')}`;
+/** SQL twin of the no-request arm of passesScopeFilterForRecall; `ownScope` is bound and compared with `=`, so `%` or
+ * `_` in an owner match nothing extra. */
 export function scopeAdmitSql(col, ownScope) {
-    const placeholders = RECALL_DEFAULT_DENY_SCOPES.map(() => '?').join(', ');
-    const admitted = `${col}scope IS NULL OR (${col}scope NOT IN (${placeholders}) AND ${col}scope NOT LIKE '%:private:%')`;
+    const marks = placeholders(RECALL_DEFAULT_DENY_SCOPES.length);
+    const admitted = `${col}scope IS NULL OR (${col}scope NOT IN (${marks}) AND ${col}scope NOT LIKE '%:private:%')`;
     if (ownScope == null)
         return { sql: `(${admitted})`, params: [...RECALL_DEFAULT_DENY_SCOPES] };
     // The own arm sits inside the outer parentheses so a caller's `AND ${sql}` cannot split it off.

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

@@ -1,7 +1,8 @@
 import type { MemoryEntry } from '../core/memory.js';
 import { type DatabaseSyncLike } from '../db/index.js';
-/** Recall scope filter: 'default-deny' (exclude RECALL_DEFAULT_DENY_SCOPES), 'exact' (m.scope = value), 'default-deny-or-exact' (both; CLI `--scope`).
- * @internal Internal SQL-builder shape; not re-exported from `src/index.ts`. Subject to change. */
+/** Recall scope filter: 'default-deny' (exclude RECALL_DEFAULT_DENY_SCOPES), 'exact' (m.scope = value),
+ * 'default-deny-or-exact' (both; CLI `--scope`). @internal Internal SQL-builder shape; not re-exported from
+ * `src/index.ts`. Subject to change. */
 export type RecallScopeFilter = {
     mode: 'default-deny';
     ownScope?: string;
@@ -15,16 +16,12 @@ export type RecallScopeFilter = {
 };
 /** One project name, or every name a project's rows carry. */
 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. */
+/** 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: FTS5 when available, else LIKE, then full-store fallback. With `tenantId` every SELECT filters by it; omitted = no filter. */
+/** Load likely search candidates: FTS5 when available, else LIKE, then full-store fallback. With `tenantId` every
+ * SELECT filters by it; omitted = no filter. */
 export declare function loadSearchEntries(hippoRoot: string, query: string, limit?: number, tenantId?: string): MemoryEntry[];
-/** Recall-mode loader: scope predicate in SQL so `unknown:legacy` cannot leak. Empty `requestedScope` default-denies (admits `ownScope`); else exact match.
- * SQL `NOT LIKE '%:private:%'` runs before the LIMIT so private rows cannot starve admitted ones; `passesScopeFilterForRecall` is the exact post-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 interface RecallSearchEntriesOptions {
     readonly limit?: number;
     readonly tenantId?: string;
@@ -34,8 +31,16 @@ export interface RecallSearchEntriesOptions {
     readonly originProjects?: OriginFilter;
     readonly ownScope?: string;
 }
+/** Recall-mode loader: scope predicate in SQL so `unknown:legacy` cannot leak. Empty `requestedScope` default-denies
+ * (admits `ownScope`); else exact match. SQL `NOT LIKE '%:private:%'` runs before the LIMIT so private rows cannot
+ * starve admitted ones; `passesScopeFilterForRecall` is the exact post-filter. */
+export declare function loadRecallEntries(hippoRoot: string, query: string, options?: RecallSearchEntriesOptions): MemoryEntry[];
+/** Positional form of `loadRecallEntries`, kept internal because the frozen q3b-ranker-floor benchmark imports it from
+ * dist. */
+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, options?: RecallSearchEntriesOptions): MemoryEntry[];
-/** Which rows the vector arm of hybrid search may add: the same tenant, scope and superseded rules as the lexical load. */
+/** 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;
     scope?: RecallScopeFilter;

package/dist/store/search-rows.js

@@ -3,13 +3,15 @@ import { tokenize } from '../util/tokenize.js';
 import { isPersonalScope } from '../core/recall-scope.js';
 import { scopeAdmitSql } from './rule-sql.js';
 import { ftsTermParts, RAREST_TERM_COUNT, rarestFtsQuery } from '../core/prompt-recall.js';
-import { errorMessage, log } from '../util/log.js';
+import { errorMessage, log, errorFields } from '../util/log.js';
 import { originInSql } from '../core/project-identity.js';
 import { topVectorMatches } from '../db/vector-store.js';
 import { MEMORY_SELECT_COLUMNS, MEMORY_SEARCH_COLUMNS, DEFAULT_SEARCH_CANDIDATE_LIMIT, rowToEntry, } from './rows.js';
 import { onHandle, openStore } from './open.js';
 import { escapeLike } from '../util/escape.js';
-/** The recall scope rule for a table column prefix (`m.` or none); `passesScopeFilterForRecall` in recall-scope.ts is its JS twin. */
+import { placeholders } from '../util/sql.js';
+/** The recall scope rule for a table column prefix (`m.` or none); `passesScopeFilterForRecall` in recall-scope.ts is
+ * its JS twin. */
 function recallScopeClause(col, scopeFilter) {
     if (scopeFilter === undefined)
         return { sql: '', params: [] };
@@ -32,19 +34,17 @@ function withProject(scope, col, origin) {
         params: [...scope.params, ...originProjects],
     };
 }
-/** 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. */
+/** 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 function recallScopeFilter(requestedScope, mode, ownScope) {
-    if (!requestedScope || (mode === 'additive' && isPersonalScope(requestedScope)))
+    if (!requestedScope || (mode === 'additive' && isPersonalScope(requestedScope))) {
         return { mode: 'default-deny', ownScope };
-    return mode === 'additive' ? { mode: 'default-deny-or-exact', value: requestedScope, ownScope } : { mode: 'exact', value: requestedScope };
+    }
+    return mode === 'additive'
+        ? { mode: 'default-deny-or-exact', value: requestedScope, ownScope }
+        : { mode: 'exact', value: requestedScope };
 }
 const FTS_QUERY_SYNTAX_RE = /fts5: syntax error|unterminated string/i;
-let forceLikePath = false;
-/** Sends term queries down the LIKE path on a build that has FTS. Only tests call it. */
-export function _forceLikePathForTests(on) {
-    forceLikePath = on;
-}
 function loadSearchRows(db, query, limit, tenantId, options = {}) {
     const { scopeFilter, includeSuperseded = true, originProjects } = options;
     const p = searchPredicates(tenantId, scopeFilter, includeSuperseded, originProjects);
@@ -53,8 +53,7 @@ function loadSearchRows(db, query, limit, tenantId, options = {}) {
         // LIMIT here too, so every candidate path honours the caller's cap.
         return selectAllCandidates(db, p, limit);
     }
-    // The test switch is read here, not in `isFtsAvailable`, so writes never skip FTS index sync.
-    if (!forceLikePath && isFtsAvailable(db)) {
+    if (isFtsAvailable(db)) {
         const rows = selectFtsCandidates(db, terms, p, limit);
         if (rows.length > 0)
             return rows;
@@ -67,14 +66,16 @@ function loadSearchRows(db, query, limit, tenantId, options = {}) {
     return selectAllCandidates(db, p, limit);
 }
 function searchPredicates(tenantId, scopeFilter, includeSuperseded, originProjects) {
-    // tenantId undefined = no tenant filter (legacy callers / cross-deployment helpers); set = strict isolation via the composite idx_memories_tenant_created.
+    // tenantId undefined = no tenant filter (legacy callers / cross-deployment helpers); set = strict isolation via the
+    // composite idx_memories_tenant_created.
     const tenantPredicate = tenantId !== undefined ? ` AND m.tenant_id = ?` : '';
     const tenantOnlyPredicate = tenantId !== undefined ? ` WHERE tenant_id = ?` : '';
     const tenantParams = tenantId !== undefined ? [tenantId] : [];
     // Defensive: kind='archived' is a transient sentinel inside archiveRawMemory's SAVEPOINT, so this only
     // guards against a dropped SAVEPOINT, a persisted 'archived' state, or direct-SQL writes.
     const archivedClauseAlias = ` AND m.kind != 'archived'`;
-    // Tenant-only path: with no tenant `tenantOnlyPredicate` is '', so the archived clause switches between ' AND' and ' WHERE' by caller context.
+    // Tenant-only path: with no tenant `tenantOnlyPredicate` is '', so the archived clause switches between ' AND' and '
+    // WHERE' by caller context.
     const archivedClauseTenantOnly = tenantId !== undefined ? ` AND kind != 'archived'` : ` WHERE kind != 'archived'`;
     const aliasScope = withProject(recallScopeClause('m.', scopeFilter), 'm.', originProjects);
     const plainScope = withProject(recallScopeClause('', scopeFilter), '', originProjects);
@@ -99,8 +100,9 @@ function selectAllCandidates(db, p, limit) {
 function selectFtsCandidates(db, terms, p, limit) {
     try {
         const ftsQuery = terms.map((t) => `"${t.replace(/"/g, '""')}"`).join(' OR ');
-        // memories_fts has no tenant_id column; filter via the joined memories row (cheap with idx_memories_tenant_created).
-        // SAFETY: MEMORY_SEARCH_COLUMNS aliases every column like MEMORY_SELECT_COLUMNS (plus bm25_score), matching MemoryRow.
+        // memories_fts has no tenant_id column; filter via the joined memories row (cheap with
+        // idx_memories_tenant_created). SAFETY: MEMORY_SEARCH_COLUMNS aliases every column like MEMORY_SELECT_COLUMNS (plus
+        // bm25_score), matching MemoryRow.
         return db.prepare(`
         SELECT ${MEMORY_SEARCH_COLUMNS}
         FROM memories m
@@ -113,24 +115,30 @@ function selectFtsCandidates(db, terms, p, limit) {
     catch (err) {
         // A query FTS5 cannot parse is expected input; anything else means the index itself is broken.
         const message = errorMessage(err);
-        if (!FTS_QUERY_SYNTAX_RE.test(message))
-            log.once('fts-match-fallback', 'warn', `FTS search failed, using the slower LIKE match: ${message}`);
+        if (!FTS_QUERY_SYNTAX_RE.test(message)) {
+            const failure = `FTS search failed, using the slower LIKE match: ${message}`;
+            log.once('fts-match-fallback', 'warn', failure, errorFields(err));
+        }
         return [];
     }
 }
-/** Newest admitted rows the substring match tests, so a query matching nothing costs the same in a store of any size. */
+/** Newest admitted rows the substring match tests, so a query matching nothing costs the same in a store of any
+ * size. */
 const LIKE_WINDOW_ROWS = 2000;
-/** Substring matches in content or tags among the newest admitted rows: the lexical path without FTS5, and the catch for a part-word that FTS5 tokens miss. */
+/** Substring matches in content or tags among the newest admitted rows: the lexical path without FTS5, and the catch
+ * for a part-word that FTS5 tokens miss. */
 function selectLikeCandidates(db, terms, p, limit) {
-    const where = terms.map(() => `(LOWER(content) LIKE ? ESCAPE '\\' OR LOWER(tags_json) LIKE ? ESCAPE '\\')`).join(' OR ');
+    const where = terms
+        .map(() => `(LOWER(content) LIKE ? ESCAPE '\\' OR LOWER(tags_json) LIKE ? ESCAPE '\\')`)
+        .join(' OR ');
     const params = terms.flatMap((term) => {
         const like = `%${escapeLike(term)}%`;
         return [like, like];
     });
     // idx_memories_tenant_created serves a tenant's newest rows; with no tenant only the table's own order needs no sort.
     const newestFirst = p.tenantParams.length > 0 ? 'created DESC' : 'rowid DESC';
-    // SHORTCUT: no index serves a substring, so a match older than the window is missed; an FTS5 trigram index is the upgrade.
-    // SAFETY: the outer query selects exactly MEMORY_SELECT_COLUMNS, matching MemoryRow's field set.
+    // SHORTCUT: no index serves a substring, so a match older than the window is missed; an FTS5 trigram index is the
+    // upgrade. SAFETY: the outer query selects exactly MEMORY_SELECT_COLUMNS, matching MemoryRow's field set.
     return db.prepare(`
     SELECT ${MEMORY_SELECT_COLUMNS}
     FROM (
@@ -144,18 +152,31 @@ function selectLikeCandidates(db, terms, p, limit) {
     LIMIT ?
   `).all(...p.tenantParams, ...p.scopeParams, Math.max(limit, LIKE_WINDOW_ROWS), ...params, limit);
 }
-/** Load likely search candidates: FTS5 when available, else LIKE, then full-store fallback. With `tenantId` every SELECT filters by it; omitted = no filter. */
+/** Load likely search candidates: FTS5 when available, else LIKE, then full-store fallback. With `tenantId` every
+ * SELECT filters by it; omitted = no filter. */
 export function loadSearchEntries(hippoRoot, query, limit = DEFAULT_SEARCH_CANDIDATE_LIMIT, tenantId) {
     return onHandle(hippoRoot, (db) => {
         return loadSearchRows(db, query, limit, tenantId).map(rowToEntry);
     }, openStore);
 }
-/** Recall-mode loader: scope predicate in SQL so `unknown:legacy` cannot leak. Empty `requestedScope` default-denies (admits `ownScope`); else exact match.
- * SQL `NOT LIKE '%:private:%'` runs before the LIMIT so private rows cannot starve admitted ones; `passesScopeFilterForRecall` is the exact post-filter. */
+/** Recall-mode loader: scope predicate in SQL so `unknown:legacy` cannot leak. Empty `requestedScope` default-denies
+ * (admits `ownScope`); else exact match. SQL `NOT LIKE '%:private:%'` runs before the LIMIT so private rows cannot
+ * starve admitted ones; `passesScopeFilterForRecall` is the exact post-filter. */
+export function loadRecallEntries(hippoRoot, query, options = {}) {
+    return onHandle(hippoRoot, (db) => loadRecallSearchEntriesFromDb(db, query, options), openStore);
+}
+/** Positional form of `loadRecallEntries`, kept internal because the frozen q3b-ranker-floor benchmark imports it from
+ * dist. */
 export function loadRecallSearchEntries(hippoRoot, query, limit = DEFAULT_SEARCH_CANDIDATE_LIMIT, tenantId, requestedScope, explicitScopeMode = 'exact', includeSuperseded = true, originProjects, ownScope) {
-    return onHandle(hippoRoot, (db) => {
-        return loadRecallSearchEntriesFromDb(db, query, { limit, tenantId, requestedScope, explicitScopeMode, includeSuperseded, originProjects, ownScope });
-    }, openStore);
+    return loadRecallEntries(hippoRoot, query, {
+        limit,
+        tenantId,
+        requestedScope,
+        explicitScopeMode,
+        includeSuperseded,
+        originProjects,
+        ownScope,
+    });
 }
 // Split out so callers with an already-open db (the prompt-recall path) skip
 // the initStore+open/close cycle per store per call.
@@ -176,7 +197,8 @@ export async function loadVectorCandidateEntries(hippoRoot, queryVector, spec) {
         if (matches.length === 0)
             return [];
         // SAFETY: the SELECT names exactly MEMORY_SELECT_COLUMNS, matching MemoryRow's field set.
-        const rows = db.prepare(`SELECT ${MEMORY_SELECT_COLUMNS} FROM memories WHERE id IN (${matches.map(() => '?').join(', ')})`)
+        const rows = db
+            .prepare(`SELECT ${MEMORY_SELECT_COLUMNS} FROM memories WHERE id IN (${placeholders(matches.length)})`)
             .all(...matches.map((m) => m.id));
         const byId = new Map(rows.map((r) => [r.id, rowToEntry(r)]));
         return matches.flatMap((m) => byId.get(m.id) ?? []);
@@ -197,7 +219,7 @@ export function pickRarestFtsQuery(db, terms, maxTerms = RAREST_TERM_COUNT) {
         return '';
     // SAFETY: rows' shape matches the two columns named in the SELECT.
     const rows = db
-        .prepare(`SELECT term, doc FROM temp.z1_rarest_vocab WHERE term IN (${vocab.map(() => '?').join(', ')})`)
+        .prepare(`SELECT term, doc FROM temp.z1_rarest_vocab WHERE term IN (${placeholders(vocab.length)})`)
         .all(...vocab);
     const counts = new Map(rows.map((r) => [r.term, r.doc]));
     return rarestFtsQuery(terms, (part) => counts.get(part) ?? 0, maxTerms);

package/dist/store/sessions.d.ts

@@ -17,7 +17,7 @@ export interface ContinuityStamp {
 export declare function continuityWhere(key: ContinuityKey): ContinuityFilter;
 /** The columns a keyed write stamps; a partial key throws, since a row it wrote would match no reader. */
 export declare function continuityStamp(key: ContinuityKey): ContinuityStamp;
-type SnapshotInput = {
+export type SnapshotInput = {
     task: string;
     summary: string;
     next_step: string;
@@ -27,11 +27,13 @@ type SnapshotInput = {
 };
 export declare function saveActiveTaskSnapshot(hippoRoot: string, tenantId: string, snapshot: SnapshotInput, key?: ContinuityKey): TaskSnapshot;
 export declare function loadActiveTaskSnapshot(hippoRoot: string, tenantId: string, key?: ContinuityKey): TaskSnapshot | null;
-/** Default freshness bound for AMBIENT active-task-snapshot reads: 72h rather than 48h so a Friday-evening orphan still offers continuity on Monday;
- * override via `loadFreshActiveTaskSnapshot`'s `opts.maxAgeMs`; deliberately no env knob. */
+/** Default freshness bound for AMBIENT active-task-snapshot reads: 72h rather than 48h so a Friday-evening orphan still
+ * offers continuity on Monday; override via `loadFreshActiveTaskSnapshot`'s `opts.maxAgeMs`; deliberately no env
+ * knob. */
 export declare const SNAPSHOT_AMBIENT_MAX_AGE_MS: number;
-/** Bounded read for AMBIENT snapshot surfaces so orphaned snapshots expire. The owner (both session ids non-empty and `===`) always sees its own state;
- * all others, null ids included (null === null is no match), get it only if age(updated_at) <= maxAgeMs (default `SNAPSHOT_AMBIENT_MAX_AGE_MS`), else null. */
+/** Bounded read for AMBIENT snapshot surfaces so orphaned snapshots expire. The owner (both session ids non-empty and
+ * `===`) always sees its own state; all others, null ids included (null === null is no match), get it only if
+ * age(updated_at) <= maxAgeMs (default `SNAPSHOT_AMBIENT_MAX_AGE_MS`), else null. */
 export declare function loadFreshActiveTaskSnapshot(hippoRoot: string, tenantId: string, opts?: {
     maxAgeMs?: number;
     sessionId?: string | null;
@@ -42,10 +44,10 @@ export declare function freshActiveSnapshot(snapshot: TaskSnapshot | null, opts?
     sessionId?: string | null;
 }): TaskSnapshot | null;
 export declare function clearActiveTaskSnapshot(hippoRoot: string, tenantId: string, clearedStatus?: string): boolean;
-/** Close the `active` task snapshot(s) owned by `sessionId` at session end; the WHERE scopes on `session_id` too so an ending session can never close a
- * newer session's snapshot. Returns the number of rows closed. */
+/** Close the `active` task snapshot(s) owned by `sessionId` at session end; the WHERE scopes on `session_id` too so an
+ * ending session can never close a newer session's snapshot. Returns the number of rows closed. */
 export declare function closeTaskSnapshotsForSession(hippoRoot: string, tenantId: string, sessionId: string, status?: string, key?: ContinuityKey): number;
-interface SessionEventInput {
+export interface SessionEventInput {
     session_id: string;
     event_type: string;
     content: string;
@@ -60,7 +62,8 @@ export declare function listSessionEvents(hippoRoot: string, tenantId: string, o
     task?: string;
     limit?: number;
 }): SessionEvent[];
-/** Session_ids with a `session_complete` event newer than `sinceMs`; bounds the sleep auto-promotion scan to a fixed window. */
+/** Session_ids with a `session_complete` event newer than `sinceMs`; bounds the sleep auto-promotion scan to a fixed
+ * window. */
 export declare function findPromotableSessions(hippoRoot: string, tenantId: string, sinceMs: number): Array<{
     session_id: string;
 }>;
@@ -76,5 +79,4 @@ export interface SessionOwnerBinding {
 }
 /** The owner stored for the session id, binding `binding.owner` first when none is stored. */
 export declare function sessionOwnerOrBind(hippoRoot: string, binding: SessionOwnerBinding): string | null;
-export {};
 //# sourceMappingURL=sessions.d.ts.map