hippo-memory 1.71.0 → 1.72.0

package/dist/store/open.js

@@ -2,26 +2,15 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { DEFAULT_HALF_LIFE_DAYS, Layer } from '../core/memory.js';
-import { closeHippoDb, currentRequestStores, openHippoDb, getMeta, setMeta, withWriteScope } from '../db/index.js';
+import { closeHippoDb, currentRequestStores, openHippoDb, getMeta, setMeta, withWriteScope, pruneConsolidationRuns, } from '../db/index.js';
 import { openHippoDbWithFacts } from '../db/open.js';
-import { findHippoStoreDir } from '../core/project-identity.js';
-import { realpathOrResolve } from '../util/real-path.js';
-import { RejectedValueError } from './rejection.js';
-import { errorMessage, log } from '../util/log.js';
+import { RejectedValueError } from '../core/api-errors.js';
+import { errorFields, errorMessage, log } from '../util/log.js';
 import { audit } from './audit-event.js';
-import { deserializeEntry } from './markdown.js';
+import { deserializeEntry } from '../core/markdown.js';
 import { stampOriginProjectForImport, upsertEntryRow } from './entry-row.js';
 import { ensureMirrorDirectories, syncMirrorFiles, layerDir } from './mirrors.js';
 import { isJsonObject } from '../util/json.js';
-/** Nearest ancestor store like git; the strict join is the fallback so `hippo init` still creates `<cwd>/.hippo`. */
-export function getHippoRoot(cwd = process.cwd(), opts) {
-    return findHippoStoreDir(cwd, opts) ?? path.join(realpathOrResolve(cwd), '.hippo');
-}
-export function isInitialized(hippoRoot) {
-    // autoInstallHooks / setupDailySchedule can create a bare .hippo with no hippo.db; counting
-    // that as initialized makes `hippo init` skip initStore, so only hippo.db counts.
-    return fs.existsSync(path.join(hippoRoot, 'hippo.db'));
-}
 export function initStore(hippoRoot) {
     closeHippoDb(openStore(hippoRoot));
 }
@@ -48,8 +37,9 @@ export function openStore(hippoRoot, opts) {
         try {
             closeHippoDb(db);
         }
-        catch {
-            // Best effort only; surface the original init error.
+        catch (closeErr) {
+            // The init error is the one thrown; the close failure is only logged.
+            log.error(`openStore: closing the handle after a failed init failed: ${errorMessage(closeErr)}`, errorFields(closeErr));
         }
         throw error;
     }
@@ -142,6 +132,8 @@ function importLegacyIndexAndStats(db, hippoRoot) {
         const row = run;
         insertRun.run(String(row.timestamp ?? new Date().toISOString()), Number(row.decayed ?? 0), Number(row.merged ?? 0), Number(row.removed ?? 0));
     }
+    // Same cap as every later sleep, so stats.json and the table agree from the first open.
+    pruneConsolidationRuns(db);
 }
 export function loadLegacyEntriesFromMarkdown(hippoRoot) {
     const entries = [];
@@ -152,52 +144,47 @@ export function loadLegacyEntriesFromMarkdown(hippoRoot) {
         for (const file of fs.readdirSync(dir)) {
             if (!file.endsWith('.md'))
                 continue;
-            const raw = fs.readFileSync(path.join(dir, file), 'utf8');
-            const entry = deserializeEntry(raw);
-            if (entry)
-                entries.push(entry);
+            try {
+                const entry = deserializeEntry(fs.readFileSync(path.join(dir, file), 'utf8'));
+                if (entry)
+                    entries.push(entry);
+            }
+            catch (err) {
+                log.warn(`store: skipped unreadable legacy file ${file}: ${errorMessage(err)}`);
+            }
         }
     }
     return entries;
 }
-function loadLegacyIndexFile(hippoRoot) {
-    const indexPath = path.join(hippoRoot, 'index.json');
-    if (!fs.existsSync(indexPath)) {
-        return { version: 1, entries: {}, last_retrieval_ids: [], last_trace_id: null };
-    }
+function readLegacyJsonObject(file) {
+    let parsed;
     try {
-        // SAFETY: index.json is only written by writeIndexMirror below, which serializes a HippoIndex;
-        // a hand-edited file that violates the shape falls through to the catch block's fallback.
-        return JSON.parse(fs.readFileSync(indexPath, 'utf8'));
+        parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
     }
     catch (err) {
-        log.debug(`store: unreadable index.json read as empty: ${errorMessage(err)}`);
-        return { version: 1, entries: {}, last_retrieval_ids: [], last_trace_id: null };
+        log.warn(`store: unreadable ${path.basename(file)} read as empty: ${errorMessage(err)}`);
+        return null;
+    }
+    if (!isJsonObject(parsed)) {
+        log.warn(`store: ${path.basename(file)} is not a JSON object, read as empty`);
+        return null;
     }
+    return parsed;
+}
+function loadLegacyIndexFile(hippoRoot) {
+    const indexPath = path.join(hippoRoot, 'index.json');
+    const empty = { version: 1, entries: {}, last_retrieval_ids: [], last_trace_id: null };
+    if (!fs.existsSync(indexPath))
+        return empty;
+    // SAFETY: index.json is written by writeIndexMirror as a HippoIndex; readers default every field, so only the object shape is checked.
+    return readLegacyJsonObject(indexPath) ?? empty;
 }
 function loadLegacyStatsFile(hippoRoot) {
     const statsPath = path.join(hippoRoot, 'stats.json');
-    if (!fs.existsSync(statsPath)) {
-        return {
-            total_remembered: 0,
-            total_recalled: 0,
-            total_forgotten: 0,
-            consolidation_runs: [],
-        };
-    }
-    try {
-        // SAFETY: stats.json is only written by writeStatsMirror below with exactly these four fields; callers also guard every read with `?? 0` / `Array.isArray`,
-        // so a hand-edited file is tolerated even if this cast is wrong.
-        return JSON.parse(fs.readFileSync(statsPath, 'utf8'));
-    }
-    catch (err) {
-        log.debug(`store: unreadable stats.json read as zero: ${errorMessage(err)}`);
-        return {
-            total_remembered: 0,
-            total_recalled: 0,
-            total_forgotten: 0,
-            consolidation_runs: [],
-        };
-    }
+    const empty = { total_remembered: 0, total_recalled: 0, total_forgotten: 0, consolidation_runs: [] };
+    if (!fs.existsSync(statsPath))
+        return empty;
+    // SAFETY: callers guard every field read with `?? 0` / `Array.isArray`, so only the object shape is checked.
+    return readLegacyJsonObject(statsPath) ?? empty;
 }
 //# sourceMappingURL=open.js.map

package/dist/store/pilot-arm.d.ts

@@ -0,0 +1,12 @@
+import { type DatabaseSyncLike } from '../db/index.js';
+export type PilotArm = 'hippo' | 'holdout';
+/** Deterministic split: the same session and rate always land in the same arm. */
+export declare function hashArm(sessionId: string, rateBp: number): PilotArm;
+/** The session's first stored arm, or null; never writes. Without `tenantId` any tenant's row counts, since on one machine a session has one arm. */
+export declare function readPilotArm(db: DatabaseSyncLike, sessionId: string, tenantId?: string): PilotArm | null;
+/** The stored arm, else the hash arm written once; on any error the hash arm comes back unrecorded. */
+export declare function ensurePilotArm(db: DatabaseSyncLike, tenantId: string, sessionId: string, rateBp: number, opts?: {
+    ownTenantOnly?: boolean;
+    now?: string;
+}): PilotArm;
+//# sourceMappingURL=pilot-arm.d.ts.map

package/dist/store/pilot-arm.js

@@ -0,0 +1,42 @@
+// Pilot arm: one token_ledger row per session names its arm, `hippo` or `holdout`, so a pilot can compare them.
+// `items` holds the holdout rate in basis points; readers outside this repo depend on these rows, so their shape is fixed.
+import { createHash } from 'node:crypto';
+import { HOOK_DB_WAIT_MS, scopedBusyWait, withWriteScope } from '../db/index.js';
+import { errorMessage, log } from '../util/log.js';
+import { firstPilotArmHash } from './token-ledger-rows.js';
+import { recordTokenUse } from './token-ledger.js';
+/** Deterministic split: the same session and rate always land in the same arm. */
+export function hashArm(sessionId, rateBp) {
+    const bucket = parseInt(createHash('sha256').update(sessionId).digest('hex').slice(0, 8), 16) % 10000;
+    return bucket < rateBp ? 'holdout' : 'hippo';
+}
+/** The session's first stored arm, or null; never writes. Without `tenantId` any tenant's row counts, since on one machine a session has one arm. */
+export function readPilotArm(db, sessionId, tenantId) {
+    const row = firstPilotArmHash(db, sessionId, tenantId);
+    return row?.block_hash === 'holdout' || row?.block_hash === 'hippo' ? row.block_hash : null;
+}
+/** The stored arm, else the hash arm written once; on any error the hash arm comes back unrecorded. */
+// The wait is the caller's lock-wait scope (a hook's 1 s, a server request's 250 ms); it holds on a handle opened in that scope.
+export function ensurePilotArm(db, tenantId, sessionId, rateBp, opts = {}) {
+    const hashed = hashArm(sessionId, rateBp);
+    const readTenant = opts.ownTenantOnly ? tenantId : undefined;
+    try {
+        // A stored row is the common case after the first prompt, so it must not take the write lock.
+        const existing = readPilotArm(db, sessionId, readTenant);
+        if (existing !== null)
+            return existing;
+        return withWriteScope(db, 'pilot_arm', () => {
+            const stored = readPilotArm(db, sessionId, readTenant);
+            if (stored === null) {
+                recordTokenUse(db, { tenantId, sessionId, surface: 'pilot', event: 'arm', items: rateBp, tokens: 0, hash: hashed, now: opts.now });
+            }
+            return stored ?? hashed;
+        }, { busyWaitMs: scopedBusyWait() ?? HOOK_DB_WAIT_MS });
+    }
+    catch (err) {
+        // A prompt hook must not fail on pilot bookkeeping; concurrent callers still agree on the hash arm.
+        log.debug(`pilot arm not stored, using the hash arm: ${errorMessage(err)}`);
+        return hashed;
+    }
+}
+//# sourceMappingURL=pilot-arm.js.map

package/dist/store/port.d.ts

@@ -10,11 +10,12 @@ import type { JsonValue } from '../util/json.js';
 import type { KeysetPosition } from '../util/keyset.js';
 import type { MemoryEntry } from '../core/memory.js';
 import type { PhysicsParticle } from '../core/physics.js';
-import type { BriefReceipt, Incident, IncidentFields, ObjectByKind, ObjectFields, ObjectKind, Policy, SavableKind, Skill } from './object-types.js';
+import type { BriefReceipt, Incident, IncidentFields, ObjectByKind, ObjectFields, ObjectKind, Policy, SavableKind, Skill } from '../core/object-types.js';
 import type { PlanningFallacyEvidence } from './planning-fallacy-evidence.js';
-import type { ClosureState, Prediction, PredictionBaserate, SavePredictionOpts } from './predictions.js';
+import type { Prediction, PredictionBaserate, SavePredictionOpts } from './predictions.js';
+import type { ClosureState } from '../core/prediction.js';
 import type { QuarantineRow, QuarantineStatus } from './quarantine.js';
-import type { ScopeActor } from './recall-scope.js';
+import type { ScopeActor } from '../core/recall-scope.js';
 import type { RecallTraceInput } from './recall-trace.js';
 import type { AmbientLoadResult, AmbientRecallRequest, ContextCandidateFilter, RecentOrigins } from './candidates.js';
 import type { GitHubDlqInsert, GitHubRouting } from './connectors/github.js';
@@ -603,6 +604,11 @@ export type StoreGroup = 'base' | keyof StoreGroups;
 export declare function hasGroup(store: HippoStore, group: StoreGroup): boolean;
 /** The group's methods; a store without them throws StoreNotPortedError, which answers 501 as any unported path does. */
 export declare function requireGroup<G extends keyof StoreGroups>(store: HippoStore, group: G): StoreGroups[G];
+export declare const STORE_BUSY_MESSAGE = "store busy (another hippo process holds the write lock); retry shortly";
+/** A store behind the port throws this when its lock wait runs out, so the server answers 503 as it does for a busy hippo.db. */
+export declare class StoreBusyError extends Error {
+    constructor(message?: string, options?: ErrorOptions);
+}
 /** What `serve()` reads and writes through. Each method is atomic and no transaction spans an
  * await, since SQLite's lock wait blocks the event loop; a lock timeout throws `StoreBusyError`. */
 export interface HippoStore extends Partial<StoreGroups> {

package/dist/store/port.js

@@ -14,4 +14,12 @@ export function requireGroup(store, group) {
         throw new StoreNotPortedError(store.kind, group);
     return methods;
 }
+export const STORE_BUSY_MESSAGE = 'store busy (another hippo process holds the write lock); retry shortly';
+/** A store behind the port throws this when its lock wait runs out, so the server answers 503 as it does for a busy hippo.db. */
+export class StoreBusyError extends Error {
+    constructor(message = STORE_BUSY_MESSAGE, options) {
+        super(message, options);
+        this.name = 'StoreBusyError';
+    }
+}
 //# sourceMappingURL=port.js.map

package/dist/store/predictions.d.ts

@@ -4,8 +4,7 @@
 import { type MemoryEntry } from '../core/memory.js';
 import { type KeysetPosition } from '../util/keyset.js';
 import type { PredictionSave } from './port.js';
-export type ClosureState = 'open' | 'closed' | 'closed-unknown';
-export declare const VALID_CLOSURE_STATES: ReadonlySet<ClosureState>;
+import { type ClosureState } from '../core/prediction.js';
 export interface Prediction {
     id: number;
     /** Nullable: ON DELETE SET NULL allows memory deletion (forget /

package/dist/store/predictions.js

@@ -1,6 +1,7 @@
 /** First-class prediction: an ex-ante claim closed against an outcome. The `predictions` table is the source of truth; the memory row only mirrors the claim.
  * Every helper requires tenantId; `trg_predictions_tenant_match_*` triggers enforce the prediction's tenant matches the referenced memory's.
  * `savePrediction` writes memory and prediction inside `writeEntry`'s SAVEPOINT (via afterWrite), so a failure in either rolls back both. */
+import { DEFAULT_LIST_LIMIT } from '../util/limits.js';
 import { BadRequestError, NotFoundError } from '../core/api-errors.js';
 import { withWriteScope } from '../db/index.js';
 import { onHandle } from './open.js';
@@ -10,15 +11,11 @@ import { createMemory, Layer } from '../core/memory.js';
 import { appendAuditEvent } from './audit.js';
 import { loadConfig } from '../core/config.js';
 import { keysetAfter } from '../util/keyset.js';
-const DEFAULT_PREDICTION_PAGE_SIZE = 100;
+import { VALID_CLOSURE_STATES } from '../core/prediction.js';
+const DEFAULT_PREDICTION_PAGE_SIZE = DEFAULT_LIST_LIMIT;
 const SELECT_COLUMNS = `id, memory_id, tenant_id, class_tag, claim_text,
   estimate_value, estimate_unit, target_date,
   actual_value, closure_state, closed_at, closure_note, created_at`;
-export const VALID_CLOSURE_STATES = new Set([
-    'open',
-    'closed',
-    'closed-unknown',
-]);
 function rowToPrediction(row) {
     return {
         id: row.id,

package/dist/store/project-tags.d.ts

@@ -0,0 +1,62 @@
+import { type DatabaseSyncLike } from '../db/index.js';
+import { type MemoryEntry } from '../core/memory.js';
+import { type AppendAuditOpts, type AuditEvent } from './audit.js';
+import { type DormantReason, type DormantSnapshot } from './dormant.js';
+import { type SetAsideResult, type SetAsideWhy } from './set-aside.js';
+export type ProjectTagOp = 'project_merge' | 'project_repair';
+export interface ProjectTagReads {
+    entries(): MemoryEntry[];
+    liveEntriesBySourcePrefix(prefix: string): MemoryEntry[];
+    entriesByIds(ids: readonly string[]): Map<string, MemoryEntry>;
+    dormant(): DormantSnapshot[];
+    auditEvents(op: ProjectTagOp): AuditEvent[];
+    compactionTranscripts(): Array<{
+        transcript: string;
+        cwd: string | null;
+    }>;
+    compactionOriginsWithCwd(): Array<{
+        origin: string;
+        cwd: string;
+    }>;
+    holdsOrigin(table: 'memories' | 'compactions', name: string): boolean;
+}
+export interface ProjectTagWrites extends ProjectTagReads {
+    setAside(tag: string, row: MemoryEntry, why: SetAsideWhy): SetAsideResult;
+    restampOrigin(from: string, into: string): void;
+    restampCompactions(from: string, into: string): number;
+    replaceDormant(id: string, entry: MemoryEntry): void;
+    stampOrigins(rows: ReadonlyArray<{
+        readonly id: string;
+        readonly origin: string;
+    }>): void;
+    /** A live row to dormant storage, restorable, as sleep's dormant move does. */
+    retire(row: MemoryEntry, reason: DormantReason, now: Date): void;
+    audit(op: ProjectTagOp, metadata: AppendAuditOpts['metadata']): void;
+}
+/** A rewrite's answer plus the ids whose mirrors are rewritten, and those whose mirrors go, once it commits. */
+export interface TagRewrite<T> {
+    readonly result: T;
+    readonly rewrite: readonly string[];
+    readonly purge: readonly string[];
+}
+export interface ProjectTagStore extends ProjectTagReads {
+    readonly hippoRoot: string;
+    /** One transaction; a dry run rolls back with no backup, else the store is backed up first and mirrors follow the commit. */
+    rewrite<T>(opts: {
+        readonly dryRun: boolean;
+        readonly backupLabel: string;
+    }, body: (tx: ProjectTagWrites, backup: string | null) => TagRewrite<T>): T;
+    repairedOnce(): boolean;
+    markRepairedOnce(): void;
+}
+export interface ProjectTagScope {
+    readonly hippoRoot: string;
+    readonly tenantId: string;
+    /** Who the audit rows name. */
+    readonly actor: string;
+}
+/** Reads on a handle the caller opened and closes, for doctor's read-only check and the note sync. */
+export declare function projectTagReads(db: DatabaseSyncLike, tenantId: string): ProjectTagReads;
+/** Runs `fn` on hippo.db under `scope.hippoRoot`, opened for this call and closed after. */
+export declare function onProjectTags<T>(scope: ProjectTagScope, fn: (store: ProjectTagStore) => T): T;
+//# sourceMappingURL=project-tags.d.ts.map

package/dist/store/project-tags.js

@@ -0,0 +1,67 @@
+// The rows `hippo projects` and sleep's tag repair read and write, bound to one hippo.db handle and tenant,
+// so the merge and repair rules in src/sharing/project-merge.ts decide without holding the handle.
+import { getMeta, setMeta, withTrialScope, withWriteScope } from '../db/index.js';
+import { withBackup } from '../db/backup.js';
+import { calculateStrength } from '../core/memory.js';
+import { appendAuditEvent, queryAuditEvents } from './audit.js';
+import { compactionOriginsWithCwd, compactionTranscripts, holdsOrigin, restampCompactionOrigin } from './compactions.js';
+import { insertDormantRow, listDormantSnapshots, replaceDormantEntry } from './dormant.js';
+import { selectAllEntries, selectEntriesByIds, selectLiveEntriesBySourcePrefix } from './entry-reads.js';
+import { deleteEntryRowInTx, restampOriginProjectAt, stampOriginProjectsAt, writeEntryMirrors } from './entry-writes.js';
+import { removeEntryMirrors } from './mirrors.js';
+import { onHandle } from './open.js';
+import { setAsideRow } from './set-aside.js';
+const AUDIT_READ_CAP = 10000;
+const TX_LABEL = 'merge_projects';
+const AUTO_REPAIR_META_KEY = 'project_repair_auto';
+/** Reads on a handle the caller opened and closes, for doctor's read-only check and the note sync. */
+export function projectTagReads(db, tenantId) {
+    return {
+        entries: () => selectAllEntries(db, tenantId),
+        liveEntriesBySourcePrefix: (prefix) => selectLiveEntriesBySourcePrefix(db, tenantId, prefix),
+        entriesByIds: (ids) => selectEntriesByIds(db, ids, tenantId),
+        dormant: () => listDormantSnapshots(db, tenantId),
+        auditEvents: (op) => queryAuditEvents(db, { tenantId, op, limit: AUDIT_READ_CAP }),
+        compactionTranscripts: () => compactionTranscripts(db, tenantId),
+        compactionOriginsWithCwd: () => compactionOriginsWithCwd(db, tenantId),
+        holdsOrigin: (table, name) => holdsOrigin(db, table, tenantId, name),
+    };
+}
+function projectTagWrites(db, { tenantId, actor }) {
+    return {
+        ...projectTagReads(db, tenantId),
+        setAside: (tag, row, why) => setAsideRow(db, tag, row, why),
+        restampOrigin: (from, into) => restampOriginProjectAt(db, tenantId, from, into),
+        restampCompactions: (from, into) => restampCompactionOrigin(db, tenantId, from, into),
+        replaceDormant: (id, entry) => replaceDormantEntry(db, tenantId, id, entry),
+        stampOrigins: (rows) => stampOriginProjectsAt(db, tenantId, rows),
+        retire: (row, reason, now) => {
+            insertDormantRow(db, { entry: row, strength: calculateStrength(row, now), reason, dormantAt: now.toISOString() });
+            deleteEntryRowInTx(db, row, actor);
+        },
+        audit: (op, metadata) => appendAuditEvent(db, { tenantId, actor, op, metadata }),
+    };
+}
+function rewriteOn(db, scope, opts, body) {
+    const tx = projectTagWrites(db, scope);
+    if (opts.dryRun)
+        return withTrialScope(db, TX_LABEL, () => body(tx, null)).result;
+    const done = withBackup(db, scope.hippoRoot, opts.backupLabel, (backup) => withWriteScope(db, TX_LABEL, () => body(tx, backup)));
+    // After commit, as the agent memory sync does: a stale mirror would bring the old tag back on the next rebuild.
+    for (const entry of selectEntriesByIds(db, done.rewrite, scope.tenantId).values())
+        writeEntryMirrors(scope.hippoRoot, entry);
+    for (const id of done.purge)
+        removeEntryMirrors(scope.hippoRoot, id);
+    return done.result;
+}
+/** Runs `fn` on hippo.db under `scope.hippoRoot`, opened for this call and closed after. */
+export function onProjectTags(scope, fn) {
+    return onHandle(scope.hippoRoot, (db) => fn({
+        ...projectTagReads(db, scope.tenantId),
+        hippoRoot: scope.hippoRoot,
+        rewrite: (opts, body) => rewriteOn(db, scope, opts, body),
+        repairedOnce: () => getMeta(db, AUTO_REPAIR_META_KEY) === '1',
+        markRepairedOnce: () => setMeta(db, AUTO_REPAIR_META_KEY, '1'),
+    }));
+}
+//# sourceMappingURL=project-tags.js.map

package/dist/store/quarantine.js

@@ -1,4 +1,5 @@
 // The memory_quarantine table: the review queue's rows, and the approve and reject writes with their audit rows.
+import { DEFAULT_LIST_LIMIT } from '../util/limits.js';
 import { appendAuditEvent } from './audit.js';
 import { withWriteScopeOr } from '../db/index.js';
 import { keysetAfter } from '../util/keyset.js';
@@ -27,7 +28,7 @@ function getQuarantineRow(db, tenantId, memoryId) {
         .get(tenantId, memoryId);
     return row ? fromDbRow(row) : null;
 }
-function listQuarantineRows(db, tenantId, status = 'pending', limit = 100, afterRow) {
+function listQuarantineRows(db, tenantId, status = 'pending', limit = DEFAULT_LIST_LIMIT, afterRow) {
     // A pending row whose memory was deleted (e.g. Slack message_deleted) is dead; keep its history, drop it from the queue.
     const live = status === 'pending'
         ? ' AND EXISTS (SELECT 1 FROM memories m WHERE m.id = memory_quarantine.memory_id AND m.tenant_id = memory_quarantine.tenant_id)'

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

@@ -101,6 +101,8 @@ export interface DeliveryEventRow {
     recall_hash: string | null;
     emitted_hash: string | null;
     elapsed_ms: number;
+    tool_use_id: string | null;
+    failure_id: number | null;
     candidates: DeliveryCandidateRow[];
 }
 /** One event plus its candidates in one write transaction, then prune; fail-soft. The caller must not hold a transaction on `db`. */

package/dist/store/recall-trace.js

@@ -1,7 +1,8 @@
 /** 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 { openHippoDb, closeHippoDb, withWriteScope } from '../db/index.js';
+import { rethrowIfSqliteBlocked } from '../util/sqlite-blocked.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';
@@ -105,7 +106,7 @@ const DELIVERY_EVENT_COLUMNS = [
     'session_id', 'session_state', 'host_turn_id', 'turn_seq', 'duplicate_of', 'prompt_hash', 'prompt_length', 'query_hash',
     'recall_trace_id', 'block_state', 'prompt_recall', 'considered_count', 'filtered_count', 'selected_count', 'emitted_count',
     'rejected_count', 'rejected_unlisted', 'sections_shown', 'sections_dropped', 'budget_tokens', 'selected_tokens',
-    'injected_tokens', 'static_hash', 'recall_hash', 'emitted_hash', 'elapsed_ms',
+    'injected_tokens', 'static_hash', 'recall_hash', 'emitted_hash', 'elapsed_ms', 'tool_use_id', 'failure_id',
 ];
 function findDuplicateBoundary(db, input) {
     // SAFETY: rows carry exactly the `id` and `ts` columns selected.
@@ -117,7 +118,21 @@ function findDuplicateBoundary(db, input) {
     const at = Date.parse(input.ts);
     return rows.find((r) => Math.abs(Date.parse(r.ts) - at) <= DELIVERY_DUPLICATE_WINDOW_MS)?.id ?? null;
 }
+function findDuplicateToolFailure(db, input) {
+    // Without a call id a time window would merge parallel failures, so two such fires stay two rows.
+    if (input.toolUseId === undefined || input.toolUseId === null)
+        return null;
+    // SAFETY: a single `id` column, undefined when no row matches.
+    const row = db.prepare(`
+    SELECT id FROM delivery_events
+    WHERE tenant_id = ? AND session_id = ? AND event_type = ? AND tool_use_id = ? AND turn_seq IS NOT NULL
+    ORDER BY id LIMIT 1
+  `).get(input.tenantId, input.sessionId, input.eventType, input.toolUseId);
+    return row?.id ?? null;
+}
 function findDuplicateTurn(db, input) {
+    if (input.eventType === 'tool-failure')
+        return findDuplicateToolFailure(db, input);
     // A boundary has no prompt, and two compactions of one session never start within the window, so time alone decides.
     if (isBoundaryEvent(input.eventType))
         return findDuplicateBoundary(db, input);
@@ -165,6 +180,7 @@ export function writeDeliveryEvent(db, input) {
                 input.consideredCount, input.filteredCount, input.selectedCount, input.emittedCount, input.rejectedCount,
                 input.rejectedUnlisted, input.sectionsShown, input.sectionsDropped, input.budgetTokens, input.selectedTokens,
                 input.injectedTokens, input.staticHash, input.recallHash, input.emittedHash, Math.round(input.elapsedMs),
+                input.toolUseId ?? null, input.failureId ?? null,
             ];
             const eventId = Number(db.prepare(`
         INSERT INTO delivery_events (${DELIVERY_EVENT_COLUMNS.join(', ')})

package/dist/store/rejected-values.js

@@ -11,7 +11,8 @@ import { writeEntryDbOnly, writeEntryMirrors } from './entry-writes.js';
 import { purgeMirrorBestEffort } from './mirrors.js';
 import { onHandle, openStore } from './open.js';
 import { archiveRawMemory, markMirrorCleaned } from './raw-archive.js';
-import { RejectedValueError, checkRejectionGuard, deleteRejectedValue, insertRejectedValue, listRejectedValues, normalizeValueForRejection, rejectionDigest, } from './rejection.js';
+import { checkRejectionGuard, deleteRejectedValue, insertRejectedValue, listRejectedValues, normalizeValueForRejection, rejectionDigest, } from './rejection.js';
+import { RejectedValueError } from '../core/api-errors.js';
 function removeLiveRows(db, hippoRoot, rejection, holdsValue, removal) {
     const { tenantId, actor, reason } = rejection;
     const { removedIds, removedRawIds, successors } = removal;

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

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

package/dist/store/rejection-probe.js

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

package/dist/store/rejection.d.ts

@@ -1,28 +1,11 @@
 /** Rejected-value tombstone: a human can refuse byte-stable re-ingestion of a rejected fact (exact normalized value); paraphrase matching is out of scope.
  * db-agnostic (helpers take a `DatabaseSyncLike`) and imports nothing from the store layer above it, which imports this (the reverse is a cycle). */
 import type { DatabaseSyncLike } from '../db/index.js';
-import { BadRequestError } from '../core/api-errors.js';
 /** Normalize content for rejection digests: NFC, lowercase, collapse whitespace runs, trim. No punctuation stripping: over-normalizing causes false
  * refusals, worse than misses. */
 export declare function normalizeValueForRejection(content: string): string;
 /** Full 64-char sha256 hex of the normalized content: a tombstone key needs collision resistance, not the 16-char redaction hash used for query hashing. */
 export declare function rejectionDigest(content: string): string;
-/** Thrown by the write-path guard (checkRejectionGuard, via upsertEntryRow) when a write would introduce a tombstoned value; carries what the
- * transaction-owner catch blocks (writeEntry, api.supersede) need to write the post-rollback `reject_refusal` audit row via `auditRejectionRefusal`. */
-export declare class RejectedValueError extends BadRequestError {
-    readonly digest: string;
-    readonly tenantId: string;
-    readonly entryId: string;
-    readonly reason: string | null;
-    readonly rejectedAt: string;
-    constructor(opts: {
-        digest: string;
-        tenantId: string;
-        entryId: string;
-        reason: string | null;
-        rejectedAt: string;
-    });
-}
 export interface RejectedValueRow {
     tenantId: string;
     digest: string;

package/dist/store/rejection.js

@@ -1,8 +1,7 @@
 /** 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';
-import { BadRequestError } from '../core/api-errors.js';
-import { DIGEST_DISPLAY_CHARS } from '../util/token-text.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) {
@@ -12,25 +11,6 @@ export function normalizeValueForRejection(content) {
 export function rejectionDigest(content) {
     return createHash('sha256').update(normalizeValueForRejection(content)).digest('hex');
 }
-/** Thrown by the write-path guard (checkRejectionGuard, via upsertEntryRow) when a write would introduce a tombstoned value; carries what the
- * transaction-owner catch blocks (writeEntry, api.supersede) need to write the post-rollback `reject_refusal` audit row via `auditRejectionRefusal`. */
-export class RejectedValueError extends BadRequestError {
-    digest;
-    tenantId;
-    entryId;
-    reason;
-    rejectedAt;
-    constructor(opts) {
-        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;
-        this.tenantId = opts.tenantId;
-        this.entryId = opts.entryId;
-        this.reason = opts.reason;
-        this.rejectedAt = opts.rejectedAt;
-    }
-}
 function rowToRejectedValue(row) {
     return {
         tenantId: row.tenant_id,

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

@@ -2,4 +2,13 @@
  *  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. */
+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. */
+export declare function touchableScopeSql(col: '' | 'm.', ownScope?: string | null): SqlFragment;
 //# sourceMappingURL=rule-sql.d.ts.map

package/dist/store/rule-sql.js

@@ -1,7 +1,8 @@
-// The SQL twins of the model's strength and keep rules (src/core/memory.ts); keep in step with calculateStrength and canAutoDelete.
+// 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';
 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. */
@@ -30,8 +31,26 @@ 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) WHERE value = ${sqlText(p.tag)}) AND substr(source, 1, ${p.sourcePrefix.length}) = ${sqlText(p.sourcePrefix)})`;
+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 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:%')`;
+    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.
+    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. */
+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] };
+}
 //# sourceMappingURL=rule-sql.js.map