hippo-memory 1.71.0 → 2.0.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,13 +37,15 @@ 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;
     }
 }
-/** One call on a handle of its own, closed after; pass openStore where the call also sets up mirror folders and legacy rows. */
+/** One call on a handle of its own, closed after (a request scope's handle stays open);
+ *  pass openStore where the call also sets up mirror folders and legacy rows. */
 export function onHandle(hippoRoot, fn, open = openHippoDb) {
     const db = open(hippoRoot);
     try {
@@ -142,6 +133,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 +145,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

@@ -1,7 +1,8 @@
 import type { AmbientTallies } from '../core/ambient.js';
 import type { AmbientStoreFilter } from './ambient.js';
 import type { ApiKeyListRow, ApiKeyRecord, ListApiKeysOpts, NewApiKey } from './auth.js';
-import type { AppendAuditOpts, AuditEvent, ListAuditAfterOpts, QueryAuditOpts } from './audit.js';
+import type { AppendAuditOpts, AuditEvent, AuditPrune, ListAuditAfterOpts, QueryAuditOpts } from './audit.js';
+import type { QualityRepairResult } from './quality-repair.js';
 import type { EmbeddingIndexState } from './vector-index.js';
 import type { Entity, Relation } from './graph-rows.js';
 import type { ActiveGoals, GetActiveGoalsOpts, GoalRecallLogRow } from './goals.js';
@@ -10,13 +11,14 @@ 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 { AmbientLoadResult, AmbientRecallRequest, ContextCandidateFilter, HeldText, RecentOrigins } from './candidates.js';
 import type { GitHubDlqInsert, GitHubRouting } from './connectors/github.js';
 import type { SlackDlqInsert, SlackTeamRoute } from './connectors/slack.js';
 import type { StrengthenOptions } from './entry-writes.js';
@@ -410,6 +412,18 @@ export interface Readiness {
     /** Resolves once one cheap read has answered; rejects with the store's own error when it cannot. */
     ping(): Promise<void>;
 }
+/** A recall's writes when the store keeps it as its last one: `strengthen.ids` are the ids it returned. */
+export type LastRecallWrites = RecallWrites & Required<Pick<RecallWrites, 'strengthen'>>;
+/** The last recall a store keeps, so a later outcome can name it, and the outcome linked to a recall trace. */
+export interface LastRecall {
+    /** entryWrites.applyOutcome, then a link from recall trace `traceId` to the ids applied; resolves to those ids. */
+    applyTracedOutcome(outcome: OutcomeWrite, traceId: number): Promise<string[]>;
+    /** applyTracedOutcome on the ids and trace of the last recall, read together so an outcome never pairs them with an older trace. */
+    applyOutcomeToLast(target: EntryTarget, good: boolean): Promise<string[]>;
+    /** finishRecall, then the ids this store lacks strengthened under `globalRoot`, then the ids and their trace saved as the last
+     *  recall in one write; resolves to the trace id, null when none was asked or its write failed. */
+    finishRecall(writes: LastRecallWrites, globalRoot: string | undefined): Promise<number | null>;
+}
 /** Which of a tenant's quarantine records a list reads; `limit` is 100 when unset. */
 export interface QuarantineListQuery {
     readonly status: QuarantineStatus | 'all';
@@ -574,8 +588,49 @@ export interface VectorViews {
     /** The same ids and values as `VectorReads.storedVectors`, each value a Float32 view. */
     storedVectorViews(ids: readonly string[]): Promise<Map<string, Float32Array>>;
 }
+/** The store is hippo.db and its files under `hippoRoot`, so a path that reopens them by folder (sleep, its child process, the global store) may run. */
+export interface LocalFiles {
+    readonly hippoRoot: string;
+}
+/** The reads and writes behind the memory-quality audit, its repair and audit-log retention. */
+export interface AuditMaintenance {
+    /** Every memory of the tenant, in `loadAllEntries` order. */
+    tenantEntries(tenantId: string): Promise<MemoryEntry[]>;
+    /** The ids of every memory a typed object row names, in any tenant; an automatic pass never deletes one. */
+    objectBackedIds(): Promise<Set<string>>;
+    /** Deletes each removal's row with its own forget row, leaving a pinned, raw, kept or object-backing row; resolves to the ids deleted. */
+    deleteAutomatically(removals: readonly {
+        readonly id: string;
+        readonly reason: string;
+    }[], actor: string): Promise<string[]>;
+    /** Counts (dryRun) or deletes the tenant's audit rows before `cutoff`, then appends one audit_prune row; resolves to the count. */
+    pruneAuditRows(prune: AuditPrune): Promise<number>;
+    /** A preview, or with `apply` the moves of certain defects to dormant storage behind a backup. */
+    repairQuality(tenantId: string, apply: boolean): Promise<QualityRepairResult>;
+    /** repairQuality applied once per store; null once it ran there. */
+    repairQualityOnce(tenantId: string): Promise<QualityRepairResult | null>;
+}
+/** The reads and writes behind git auto-learn's batch. */
+export interface LessonWrites {
+    /** Every memory of the tenant, in `loadAllEntries` order. */
+    tenantEntries(tenantId: string): Promise<MemoryEntry[]>;
+    /** Content, source and origin of the tenant's rows holding any of `words`, among the rows a team member or `ownScope`'s owner may touch. */
+    textsHoldingWords(tenantId: string, words: readonly string[], ownScope: string | null): Promise<HeldText[]>;
+    /** Writes each entry in one transaction; a rejected value writes its refusal row and is skipped. Resolves to the ids written. */
+    writeSkippingRejected(entries: readonly MemoryEntry[], actor: string): Promise<string[]>;
+    /** Rewrites each entry in one transaction, all or none. */
+    writeTogether(entries: readonly MemoryEntry[]): Promise<void>;
+    /** Adds `count` to the store-wide remembered counter. */
+    bumpRemembered(count: number): Promise<void>;
+}
 /** The optional groups: a store sets each one whole or leaves it unset, and a route or MCP tool names the one it needs. */
 export interface StoreGroups {
+    /** Unset on any store but hippo.db; a request then runs fenced from hippo.db, and a route or tool that names no group answers 501. */
+    readonly localFiles: LocalFiles;
+    /** Unset on a store without it, where the quality audit, its repair and audit prune answer 501. */
+    readonly auditMaintenance: AuditMaintenance;
+    /** Unset on a store without it, where git learn answers 501. */
+    readonly lessonWrites: LessonWrites;
     /** Unset on a store built before them, where hybrid and physics recall under an embedding provider answer 501. */
     readonly vectors: VectorReads;
     /** Unset on a store without them, where recall scores the number[] copies `vectors` returns, to the same ranking. */
@@ -598,15 +653,22 @@ export interface StoreGroups {
     readonly objects: Objects;
     /** Unset on a store built before it, where GET /ready answers 200 with `store: "unchecked"`. */
     readonly readiness: Readiness;
+    /** Unset on a store that keeps no last recall, where outcomeForLastRecall and a traced outcome answer 501 and context writes no last recall. */
+    readonly lastRecall: LastRecall;
 }
 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> {
-    /** 'sqlite' is hippo.db under the served root. Under any other kind, an unported route answers 501 and a hippo.db open inside a request throws. */
+    /** A name for logs and errors; what a store can do is the groups it sets, `localFiles` above all. */
     readonly kind: string;
     /** The api_keys row for `keyId` with its scope grants, revoked or not; null when no row matches. */
     findApiKey(keyId: string): Promise<ApiKeyRecord | null>;

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/quality-repair.js

@@ -133,7 +133,7 @@ function setAsideIssue(db, entry, reason, now, backup) {
     if (getMeta(db, 'fts5_available', '0') === '1' && ftsRowExists(db, entry.id)) {
         throw new Error(`Quality repair could not remove the full-text row for ${entry.id}`);
     }
-    appendAuditEvent(db, { tenantId: entry.tenantId, actor, op: 'quality_repair', targetId: entry.id, metadata: { reason, backup } });
+    appendAuditEvent(db, { tenantId: entry.tenant_id, actor, op: 'quality_repair', targetId: entry.id, metadata: { reason, backup } });
     return true;
 }
 function applyPlan(db, root, tenantId, backup, doneKey) {

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,11 +1,13 @@
 /** 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';
 import { blockHash } from '../util/token-text.js';
+import { placeholders } from '../util/sql.js';
 /** Strip a RerankStep to {stage, multiplier, scoreBefore, scoreAfter}: `note` is free-form (the CLI goal-boost step embeds goal tag text) and would leak
  * user content into `rerank_json`; an allowlist, so any future free-form field is dropped too. */
 function sanitizeRerankSteps(steps) {
@@ -105,7 +107,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 +119,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,10 +181,11 @@ 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(', ')})
-        VALUES (${DELIVERY_EVENT_COLUMNS.map(() => '?').join(', ')})
+        VALUES (${placeholders(DELIVERY_EVENT_COLUMNS.length)})
       `).run(...values).lastInsertRowid);
             const insertCandidate = db.prepare(`
         INSERT INTO delivery_candidates (event_id, tenant_id, memory_id, source_store, pool, stage, outcome, reason, cand_rank, score, tokens)