hippo-memory 1.70.0 → 1.72.0

package/dist/api/sleep-run.js

@@ -1,9 +1,10 @@
 // The sleep pipeline behind `sleep`, with its phase dependencies injectable; kept out of the package root.
 import { loadAllEntries } from '../store/entry-reads.js';
-import { deleteEntry, memoriesBackingObjects } from '../store/delete-and-batch.js';
-import { reportAuditWriteFailure, auditMemories } from '../store/audit.js';
+import { memoriesBackingObjects } from '../store/delete-and-batch.js';
+import { reportAuditWriteFailure } from '../store/audit.js';
+import { auditMemories } from '../core/memory-audit.js';
 import { sqliteSyncStore } from '../store/sqlite/store.js';
-import { autoShare } from '../sharing/shared.js';
+import { AUTO_SHARE_MIN_SCORE, autoShare } from '../sharing/share.js';
 import { consolidate } from '../consolidate/sleep.js';
 import { failedUnitOf } from '../store/delete-and-batch.js';
 import { loadConfig } from '../core/config.js';
@@ -11,6 +12,7 @@ import { deduplicateStore } from '../consolidate/dedupe.js';
 import { computeAmbientState } from '../core/ambient.js';
 import { loadPendingExtractionTenants, markPendingProcessedUpTo } from '../store/graph-queue.js';
 import { extractGraphChunked } from '../graph/extract.js';
+import { removeAuditErrors } from './audit.js';
 import { errorMessage } from '../util/log.js';
 const DEFAULT_SLEEP_PHASES = {
     consolidate,
@@ -18,7 +20,6 @@ const DEFAULT_SLEEP_PHASES = {
     auditMemories,
     autoShare,
     loadAllEntries,
-    deleteEntry,
     computeAmbientState,
     loadConfig,
     loadPendingExtractionTenants,
@@ -28,18 +29,15 @@ const DEFAULT_SLEEP_PHASES = {
 export async function runSleep(ctx, opts, overrides = {}) {
     const dryRun = Boolean(opts.dryRun);
     const phases = { ...DEFAULT_SLEEP_PHASES, ...overrides };
-    // Phase counters for the consolidate audit emit (in finally).
-    // Accumulated as each phase completes so partial-failure paths still report
-    // accurate "what got done before the failure" data.
+    // Phase counters for the consolidate audit emit (in finally), accumulated per phase so a partial failure still reports what got done.
     const counts = { consolidation: 0, dedup: 0, auditDeleted: 0, ambient: 0 };
     let phaseError = null;
     try {
         return await runSleepPhases(ctx, opts, phases, counts);
     }
     catch (err) {
-        // SAFETY: phaseError is read via phaseError.message / (phaseError !==
-        // null) below, both safe even if a non-Error was thrown; this mirrors
-        // the existing lenient (err as Error) pattern used throughout this catch chain.
+        // SAFETY: phaseError is only read via phaseError.message / (phaseError !== null) below, safe even if a non-Error was thrown;
+        // this mirrors the lenient (err as Error) pattern used through this catch chain.
         phaseError = err;
         throw err;
     }
@@ -54,20 +52,23 @@ async function runSleepPhases(ctx, opts, phases, counts) {
     const consolidateResult = await phases.consolidate(ctx.hippoRoot, { dryRun });
     counts.consolidation = consolidateResult.semanticCreated + consolidateResult.merged;
     const result = sleepResultFrom(consolidateResult, dryRun);
+    // One read after consolidation serves dedup, the audit and ambient: dedup reports every row it deletes, so later phases subtract instead of reading again.
+    const loaded = { entries: phases.loadAllEntries(ctx.hippoRoot), backing: memoriesBackingObjects(ctx.hippoRoot) };
     // Phase 2: Dedup (post-consolidate near-duplicate cleanup).
-    const dedupResult = phases.deduplicateStore(ctx.hippoRoot, { dryRun, actor: ctx.actor.subject });
+    const dedupResult = phases.deduplicateStore(ctx.hippoRoot, { dryRun, actor: ctx.actor.subject, loaded });
     counts.dedup = dedupResult.removed;
     if (dedupResult.removed > 0)
         result.deduped = dedupSummary(dedupResult);
     // Phase 3: Quality audit (remove junk, report warnings; a dry run skips rows earlier phases would remove).
-    counts.auditDeleted = runQualityAudit(ctx, phases, { dryRun, consolidateResult, dedupResult, result });
+    const audited = runQualityAudit(ctx, phases, { dryRun, consolidateResult, dedupResult, result, loaded });
+    counts.auditDeleted = audited.removed;
     if (dryRun)
         return result;
     // Phase 4: Auto-share high-transfer-score memories to global.
     if (!opts.noShare)
         shareOnSleep(ctx, phases, result);
     // Phase 5: Post-sleep ambient state summary.
-    counts.ambient = summarizeAmbient(ctx, phases, result);
+    counts.ambient = summarizeAmbient(ctx, phases, result, audited.remaining);
     await drainGraphQueue(ctx, phases, snapshot, result);
     return result;
 }
@@ -115,28 +116,27 @@ function dedupSummary(dedupResult) {
         crossDups,
     };
 }
+/** `removed` counts audit errors deleted (or that would be under dryRun); `remaining` is what the audit read, less the rows it deleted. */
 function runQualityAudit(ctx, phases, options) {
-    const { dryRun, consolidateResult, dedupResult, result } = options;
-    const planned = new Set(dryRun ? [...(consolidateResult.removedIds ?? []), ...dedupResult.pairs.map((p) => p.removed)] : []);
-    const allEntries = phases.loadAllEntries(ctx.hippoRoot).filter((e) => !planned.has(e.id));
-    const auditOut = phases.auditMemories(allEntries, memoriesBackingObjects(ctx.hippoRoot));
+    const { dryRun, consolidateResult, dedupResult, result, loaded } = options;
+    // The load followed consolidation, so only a dry run still holds the rows consolidation would remove; dedup's pairs are gone or would be.
+    const planned = new Set([...(dryRun ? consolidateResult.removedIds ?? [] : []), ...dedupResult.pairs.map((p) => p.removed)]);
+    const allEntries = loaded.entries.filter((e) => !planned.has(e.id));
+    const auditOut = phases.auditMemories(allEntries, loaded.backing);
     if (auditOut.issues.length === 0)
-        return 0;
+        return { removed: 0, remaining: allEntries };
     const errors = auditOut.issues.filter((i) => i.severity === 'error');
     const warnings = auditOut.issues.filter((i) => i.severity === 'warning');
-    let removed = 0;
-    for (const issue of errors) {
-        const reason = `sleep-audit: ${issue.reason}`;
-        if (dryRun || phases.deleteEntry(ctx.hippoRoot, issue.memoryId, { actor: ctx.actor.subject, reason, automatic: true }))
-            removed++;
-    }
+    const gone = dryRun ? errors.map((issue) => issue.memoryId) : removeAuditErrors(ctx, 'sleep-audit', errors);
+    const removed = gone.length;
+    const deleted = new Set(gone);
     if (removed > 0 || warnings.length > 0) {
         result.audit = {
             errorsRemoved: removed,
             warningCount: warnings.length,
         };
     }
-    return removed;
+    return { removed, remaining: allEntries.filter((e) => !deleted.has(e.id)) };
 }
 function shareOnSleep(ctx, phases, result) {
     const sleepConfig = phases.loadConfig(ctx.hippoRoot);
@@ -144,7 +144,7 @@ function shareOnSleep(ctx, phases, result) {
         return;
     // Both skip counters are surfaced so the secret veto and the rejection tombstone are observable, not silent.
     const autoShareStats = { secretSkipped: 0, rejectedSkipped: 0 };
-    const shared = phases.autoShare(ctx.hippoRoot, { minScore: 0.6, stats: autoShareStats });
+    const shared = phases.autoShare(ctx.hippoRoot, { minScore: AUTO_SHARE_MIN_SCORE, stats: autoShareStats });
     if (shared.length > 0) {
         result.shared = shared.length;
     }
@@ -156,11 +156,11 @@ function shareOnSleep(ctx, phases, result) {
     }
 }
 /** Returns the ambient total the audit row reports: 0 when ambient is off or no current row is left. */
-function summarizeAmbient(ctx, phases, result) {
+function summarizeAmbient(ctx, phases, result, loaded) {
     const postSleepConfig = phases.loadConfig(ctx.hippoRoot);
     if (!postSleepConfig.ambient.enabled)
         return 0;
-    const postSleepEntries = phases.loadAllEntries(ctx.hippoRoot).filter((e) => !e.superseded_by);
+    const postSleepEntries = loaded.filter((e) => !e.superseded_by);
     if (postSleepEntries.length === 0)
         return 0;
     result.ambient = phases.computeAmbientState(postSleepEntries);

package/dist/api/sleep.d.ts

@@ -4,23 +4,17 @@ import type { Context } from './types.js';
 export interface SleepOpts {
     /** Report what a sleep would change without applying it; sharing, the ambient summary and the graph refresh are skipped. */
     dryRun?: boolean;
-    /** Skip copying high-scoring memories to the global store under `HIPPO_HOME`. Default false, so every tenant's memories are eligible; multi-tenant callers pass `true`. */
+    /** Skip copying high-scoring memories to the global store under `HIPPO_HOME`. Default
+     * false, so every tenant's memories are eligible; multi-tenant callers pass `true`. */
     noShare?: boolean;
 }
 export interface SleepResult {
     active: number;
     removed: number;
-    /**
-     * Faded memories the decay pass moved to the dormant store instead of
-     * deleting (config `dormant.enabled`). Absent when 0. Per-invocation
-     * activity counter, same class as `removed`.
-     */
+    /** Faded memories the decay pass moved to the dormant store instead of deleting (config `dormant.enabled`); absent when 0. Per-invocation counter, like
+     * `removed`. */
     dormant?: number;
-    /**
-     * Dormant memories deleted for good this sleep because they outlived
-     * `dormant.retentionDays`. Absent when 0. Same per-invocation class as
-     * `removed`.
-     */
+    /** Dormant memories deleted for good this sleep for outliving `dormant.retentionDays`; absent when 0. Per-invocation counter, like `removed`. */
     dormantExpired?: number;
     mergedEpisodic: number;
     newSemantic: number;
@@ -36,26 +30,13 @@ export interface SleepResult {
         warningCount: number;
     };
     shared?: number;
-    /**
-     * Count of memories the auto-share secret veto withheld this sleep
-     * — rows that passed every other admission gate (transfer score,
-     * not-already-global) and were blocked solely by `detectSecret`. Absent
-     * when 0 or when auto-share did not run.
-     */
+    /** Memories the auto-share secret veto withheld: rows that passed every other gate but `detectSecret`; absent when 0 or auto-share did not run. */
     secretSkipped?: number;
-    /**
-     * Count of auto-share candidates the GLOBAL store's rejection
-     * tombstone refused this sleep; copy paths must not let one rejected
-     * candidate abort the batch. Absent when 0 or when auto-share did not run.
-     */
+    /** Auto-share candidates the GLOBAL store's rejection tombstone refused (one must not abort the batch); absent when 0 or auto-share did not run. */
     rejectedSkipped?: number;
     ambient?: AmbientState | null;
-    /**
-     * Graph re-extraction totals across the tenants rebuilt
-     * this sleep. Absent when no tenant was dirty, and under dryRun (the graph
-     * phase runs only on a real sleep). Cross-tenant aggregate, one reason
-     * /v1/sleep stays loopback-only.
-     */
+    /** Graph re-extraction totals across tenants rebuilt this sleep; absent when none was dirty or under dryRun.
+     * Cross-tenant aggregate: one reason /v1/sleep stays loopback-only. */
     graph?: {
         tenants: number;
         entities: number;

package/dist/api/status.d.ts

@@ -0,0 +1,24 @@
+import type { PhysicsParticle } from '../core/physics.js';
+import type { LegacyStats } from '../store/rows.js';
+import { type StatusCounts } from '../store/candidates.js';
+import { type StoredVectorSummary } from '../store/vector-index.js';
+import { type CorrectionLatencyReport } from './correction-latency.js';
+import { type ProvenanceCoverage } from './provenance-coverage.js';
+import { type Context } from './types.js';
+export interface StoreStatus {
+    stats: LegacyStats;
+    counts: StatusCounts;
+}
+/** Lifetime stats and row counts for the whole store. Every tenant, so the host admin only. */
+export declare function storeStatus(ctx: Context, now: Date, atRiskBelow: number): StoreStatus;
+/** Ids and dimension of the stored vectors. Every tenant, so the host admin only. */
+export declare function vectorSummary(ctx: Context): StoredVectorSummary;
+/** Whether the stored vectors were built by a different model than `providerId`. Every tenant, so the host admin only. */
+export declare function embeddingReindexNeeded(ctx: Context, providerId: string): boolean;
+/** Every stored physics particle. Every tenant, so the host admin only. */
+export declare function storedParticles(ctx: Context): PhysicsParticle[];
+/** Correction latency over every superseded row in the store. Every tenant, so the host admin only. */
+export declare function correctionLatencyReport(ctx: Context): CorrectionLatencyReport;
+/** Provenance coverage over every kind=raw row in the store. Every tenant, so the host admin only. */
+export declare function provenanceCoverageReport(ctx: Context): ProvenanceCoverage;
+//# sourceMappingURL=status.d.ts.map

package/dist/api/status.js

@@ -0,0 +1,40 @@
+// Store-wide status reads: counts, stats, vector index state and the correction and provenance reports.
+import { loadCorrectionEntries, loadRawEntries } from '../store/report-reads.js';
+import { loadStats } from '../store/index-and-stats.js';
+import { loadStatusCounts } from '../store/candidates.js';
+import { embeddingModelRequiresReindex } from '../store/embeddings/index.js';
+import { loadStoredParticles, storedVectorSummary } from '../store/vector-index.js';
+import { buildCorrectionLatency } from './correction-latency.js';
+import { buildProvenanceCoverage } from './provenance-coverage.js';
+import { requireHostAdmin } from './types.js';
+/** Lifetime stats and row counts for the whole store. Every tenant, so the host admin only. */
+export function storeStatus(ctx, now, atRiskBelow) {
+    requireHostAdmin(ctx, 'Reading every tenant');
+    return { stats: loadStats(ctx.hippoRoot), counts: loadStatusCounts(ctx.hippoRoot, now, atRiskBelow) };
+}
+/** Ids and dimension of the stored vectors. Every tenant, so the host admin only. */
+export function vectorSummary(ctx) {
+    requireHostAdmin(ctx, 'Reading every tenant');
+    return storedVectorSummary(ctx.hippoRoot);
+}
+/** Whether the stored vectors were built by a different model than `providerId`. Every tenant, so the host admin only. */
+export function embeddingReindexNeeded(ctx, providerId) {
+    requireHostAdmin(ctx, 'Reading every tenant');
+    return embeddingModelRequiresReindex(ctx.hippoRoot, providerId);
+}
+/** Every stored physics particle. Every tenant, so the host admin only. */
+export function storedParticles(ctx) {
+    requireHostAdmin(ctx, 'Reading every tenant');
+    return loadStoredParticles(ctx.hippoRoot);
+}
+/** Correction latency over every superseded row in the store. Every tenant, so the host admin only. */
+export function correctionLatencyReport(ctx) {
+    requireHostAdmin(ctx, 'Reading every tenant');
+    return buildCorrectionLatency(loadCorrectionEntries(ctx.hippoRoot));
+}
+/** Provenance coverage over every kind=raw row in the store. Every tenant, so the host admin only. */
+export function provenanceCoverageReport(ctx) {
+    requireHostAdmin(ctx, 'Reading every tenant');
+    return buildProvenanceCoverage(loadRawEntries(ctx.hippoRoot));
+}
+//# sourceMappingURL=status.js.map

package/dist/api/store-init.d.ts

@@ -0,0 +1,4 @@
+import { type Context } from './types.js';
+/** Create the store at `ctx.hippoRoot`, or finish setting up one that exists; a store holds every tenant, so the host admin only. */
+export declare function initMemoryStore(ctx: Context): void;
+//# sourceMappingURL=store-init.d.ts.map

package/dist/api/store-init.js

@@ -0,0 +1,9 @@
+// Creating a store for `hippo init`: the database, its mirror folders and first-run setup.
+import { initStore } from '../store/open.js';
+import { requireHostAdmin } from './types.js';
+/** Create the store at `ctx.hippoRoot`, or finish setting up one that exists; a store holds every tenant, so the host admin only. */
+export function initMemoryStore(ctx) {
+    requireHostAdmin(ctx, 'Creating a store');
+    initStore(ctx.hippoRoot);
+}
+//# sourceMappingURL=store-init.js.map

package/dist/api/tokens.d.ts

@@ -1,21 +1,14 @@
 import type { TokenSummary, TokenSurface } from '../store/token-ledger.js';
 import type { FailureSummary } from '../store/failure-log.js';
 import type { Context } from './types.js';
-/**
- * Record memory text handed to an agent in the token ledger.
- * Best-effort: never throws, because a ledger failure must not fail the
- * recall or context call that produced the text.
- */
+/** Records memory text handed to an agent in the token ledger. Best-effort: never throws, since a ledger failure must not fail the recall or context call. */
 export declare function recordTokens(ctx: Context, surface: TokenSurface, use: {
     items: number;
     tokens: number;
     sessionId?: string | null;
 }): Promise<void>;
-/**
- * Token ledger totals for the tenant over the last `days` days (default 30):
- * tokens sent, skipped as unchanged and re-read by later model calls, per
- * surface, with session counts and mean tokens per session.
- */
+/** Token ledger totals for the tenant over the last `days` days (default 30): tokens sent, skipped as unchanged and re-read,
+ * per surface, with session counts and mean tokens per session. */
 export declare function tokenSummary(ctx: Context, opts?: {
     days?: number;
 }): TokenSummary;

package/dist/api/tokens.js

@@ -1,14 +1,10 @@
 // Token-use and failure reports.
-import { rethrowIfSqliteBlocked } from '../db/index.js';
+import { rethrowIfSqliteBlocked } from '../util/sqlite-blocked.js';
 import { storeFor } from '../store/index.js';
 import { failureLogSummary, tokenUseSummary } from '../store/usage-reports.js';
 import { errorMessage, log } from '../util/log.js';
 import { DAY_MS } from '../util/time.js';
-/**
- * Record memory text handed to an agent in the token ledger.
- * Best-effort: never throws, because a ledger failure must not fail the
- * recall or context call that produced the text.
- */
+/** Records memory text handed to an agent in the token ledger. Best-effort: never throws, since a ledger failure must not fail the recall or context call. */
 export async function recordTokens(ctx, surface, use) {
     try {
         await storeFor(ctx).recordTokens({
@@ -25,11 +21,8 @@ export async function recordTokens(ctx, surface, use) {
         log.warnThenDebug('api-token-ledger', `token ledger write failed; the reply is unaffected: ${errorMessage(err)}`);
     }
 }
-/**
- * Token ledger totals for the tenant over the last `days` days (default 30):
- * tokens sent, skipped as unchanged and re-read by later model calls, per
- * surface, with session counts and mean tokens per session.
- */
+/** Token ledger totals for the tenant over the last `days` days (default 30): tokens sent, skipped as unchanged and re-read,
+ * per surface, with session counts and mean tokens per session. */
 export function tokenSummary(ctx, opts = {}) {
     return tokenUseSummary(ctx.hippoRoot, ctx.tenantId, reportWindowStart(opts.days));
 }

package/dist/api/types.d.ts

@@ -1,12 +1,7 @@
 import { BadRequestError } from '../core/api-errors.js';
 import type { HippoStore } from '../store/index.js';
-/**
- * Actor identity + authorization role for a Context.
- *
- * Carries the audit-log subject plus a role for /v1/sleep admin gating. Audit
- * helpers take the bare `string`, so callers pass `ctx.actor.subject`. Role checks happen at the request
- * boundary (e.g. /v1/sleep), except in authCreate and authRevoke (ForbiddenError).
- */
+/** Actor identity + role for a Context: the audit-log subject (pass `ctx.actor.subject` to audit helpers) and the role for admin gating.
+ * Role checks happen at the request boundary (e.g. /v1/sleep), except in authCreate and authRevoke (ForbiddenError). */
 export interface Actor {
     /** 'cli' | 'localhost:cli' | 'api_key:<key_id>' | 'mcp' | 'connector:slack' | 'connector:github' */
     subject: string;
@@ -34,31 +29,15 @@ export type StoreReply<C extends Context, R> = C extends {
     readonly hippoRoot: string;
     readonly store?: undefined;
 } ? R : R | Promise<R>;
-/**
- * Helper for building process-local Actor values (admin and host admin),
- * used by CLI and CLI-run connector Context constructors so the role
- * boilerplate isn't repeated at every site. Bearer-authed callers (HTTP
- * /v1/*) construct Actor directly from the api_keys row's role column via
- * buildContextWithAuth in src/server.ts.
- */
+/** Builds process-local Actor values (admin and host admin) for CLI and CLI-run connector Contexts; Bearer-authed callers build Actor from the api_keys row
+ * instead. */
 export declare function adminActor(subject: string): Actor;
+/** Throws unless the caller is the host's operator: `action` reaches past the caller's tenant. */
+export declare function requireHostAdmin(ctx: Context, action: string): void;
 /** The per-person key: an unowned key gets its own bucket by key id rather than sharing one. */
 export declare function ownerOrSubject(actor: Actor): string;
-/**
- * Thrown by `api.recall` when a caller's options violate a recall contract
- * that has been opted into via env. Carries a stable `code` field for HTTP /
- * MCP / CLI render paths to discriminate without parsing the message.
- *
- * Codes:
- *   - 'fresh_tail_requires_session_id' — `freshTailCount > 0` AND no
- *     `freshTailSessionId` AND `HIPPO_REQUIRE_SESSION_SCOPED_FRESH_TAIL=1`.
- *     Default behaviour (env unset) returns tenant-wide rows; the env gate
- *     is opt-in so multi-session tenants can fail loud instead of silently
- *     surfacing cross-session rows tagged `isFreshTail=true`.
- *   - 'invalid_scorer_window' — `opts.scorerWindow` is set to a non-positive,
- *     non-integer, or non-finite value. 0 would route through FTS/LIKE
- *     `LIMIT 0` and then an uncapped full-store fallback, so it is validated upfront.
- */
+/** Thrown by `api.recall` on a contract violation; the stable `code` lets callers discriminate without parsing the message.
+ * 'fresh_tail_requires_session_id' (needs HIPPO_REQUIRE_SESSION_SCOPED_FRESH_TAIL=1) or 'invalid_scorer_window' (0 would hit an uncapped fallback). */
 export declare class RecallContractError extends BadRequestError {
     readonly code: 'fresh_tail_requires_session_id' | 'invalid_scorer_window';
     constructor(code: 'fresh_tail_requires_session_id' | 'invalid_scorer_window', message: string);

package/dist/api/types.js

@@ -1,34 +1,21 @@
 // Request context (caller identity and tenant) shared by every API module, plus the recall contract error.
-import { BadRequestError } from '../core/api-errors.js';
-/**
- * Helper for building process-local Actor values (admin and host admin),
- * used by CLI and CLI-run connector Context constructors so the role
- * boilerplate isn't repeated at every site. Bearer-authed callers (HTTP
- * /v1/*) construct Actor directly from the api_keys row's role column via
- * buildContextWithAuth in src/server.ts.
- */
+import { BadRequestError, ForbiddenError } from '../core/api-errors.js';
+/** Builds process-local Actor values (admin and host admin) for CLI and CLI-run connector Contexts; Bearer-authed callers build Actor from the api_keys row
+ * instead. */
 export function adminActor(subject) {
     return { subject, role: 'admin', hostAdmin: true };
 }
+/** Throws unless the caller is the host's operator: `action` reaches past the caller's tenant. */
+export function requireHostAdmin(ctx, action) {
+    if (!ctx.actor.hostAdmin)
+        throw new ForbiddenError(`${action} requires a host admin`);
+}
 /** The per-person key: an unowned key gets its own bucket by key id rather than sharing one. */
 export function ownerOrSubject(actor) {
     return actor.owner ?? actor.subject;
 }
-/**
- * Thrown by `api.recall` when a caller's options violate a recall contract
- * that has been opted into via env. Carries a stable `code` field for HTTP /
- * MCP / CLI render paths to discriminate without parsing the message.
- *
- * Codes:
- *   - 'fresh_tail_requires_session_id' — `freshTailCount > 0` AND no
- *     `freshTailSessionId` AND `HIPPO_REQUIRE_SESSION_SCOPED_FRESH_TAIL=1`.
- *     Default behaviour (env unset) returns tenant-wide rows; the env gate
- *     is opt-in so multi-session tenants can fail loud instead of silently
- *     surfacing cross-session rows tagged `isFreshTail=true`.
- *   - 'invalid_scorer_window' — `opts.scorerWindow` is set to a non-positive,
- *     non-integer, or non-finite value. 0 would route through FTS/LIKE
- *     `LIMIT 0` and then an uncapped full-store fallback, so it is validated upfront.
- */
+/** Thrown by `api.recall` on a contract violation; the stable `code` lets callers discriminate without parsing the message.
+ * 'fresh_tail_requires_session_id' (needs HIPPO_REQUIRE_SESSION_SCOPED_FRESH_TAIL=1) or 'invalid_scorer_window' (0 would hit an uncapped fallback). */
 export class RecallContractError extends BadRequestError {
     code;
     constructor(code, message) {

package/dist/capture/caller-session.d.ts

@@ -1,5 +1,4 @@
 import { type Context } from '../api/types.js';
-import { type DatabaseSyncLike } from '../db/index.js';
 import { type CallerProject } from '../api/prompt-hook.js';
 import type { ContinuityKey } from '../store/sessions.js';
 import { type WorkingState } from './working-state.js';
@@ -11,6 +10,4 @@ export declare function callerInHoldout(ctx: Context, sessionId: string): boolea
 export declare function checkedWorkingState(state: WorkingState | null): WorkingState | null;
 export declare function assertTrigger(trigger: string | null): void;
 export declare function assertRequestId(requestId: string): void;
-/** Opens with the request's own lock wait, so a busy store becomes a 503 rather than a long stall. */
-export declare function withCallerDb<T>(ctx: Context, fn: (db: DatabaseSyncLike) => T): T;
 //# sourceMappingURL=caller-session.d.ts.map

package/dist/capture/caller-session.js

@@ -1,8 +1,7 @@
 // The checks every caller call shares: ids, project, the session's owner and the pilot arm, all from the request, never the server's env or folder.
 import { BadRequestError } from '../core/api-errors.js';
 import { ownerOrSubject } from '../api/types.js';
-import { closeHippoDb, openHippoDb } from '../db/index.js';
-import { MAX_ID_LEN } from '../util/http-util.js';
+import { MAX_ID_LEN } from '../util/limits.js';
 import { sessionPilotArm } from '../api/pilot-arm.js';
 import { assertCallerIds } from '../api/prompt-hook.js';
 import { assertCallerProject, projectNames } from '../core/project-identity.js';
@@ -45,14 +44,4 @@ export function assertRequestId(requestId) {
     if (requestId.length > MAX_ID_LEN)
         throw new BadRequestError(`request id: at most ${MAX_ID_LEN} characters`);
 }
-/** Opens with the request's own lock wait, so a busy store becomes a 503 rather than a long stall. */
-export function withCallerDb(ctx, fn) {
-    const db = openHippoDb(ctx.hippoRoot);
-    try {
-        return fn(db);
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
 //# sourceMappingURL=caller-session.js.map

package/dist/capture/capture-error.d.ts

@@ -1,7 +1,7 @@
-import { type CaptureErrorOutcome } from '../store/failure-log.js';
+import type { CaptureErrorOutcome } from '../store/failure-log.js';
 import type { JsonValue } from '../util/json.js';
 /** Store a failure as an error memory unless it is routine or a repeat, and log it either way, even when storing throws. */
-export declare function captureToolFailure(hippoRoot: string, tenantId: string, payload: JsonValue): CaptureErrorOutcome;
+export declare function captureToolFailure(hippoRoot: string, tenantId: string, payload: JsonValue, onLogged?: (failureId: number | null) => void): CaptureErrorOutcome;
 /** Who sent a failure from another machine: the audit actor and the project its lesson and repeat check belong to. */
 export interface LessonCaller {
     actor: string;

package/dist/capture/capture-error.js

@@ -5,11 +5,10 @@ import { createMemory } from '../core/memory.js';
 import { writeEntry } from '../store/entry-writes.js';
 import { loadContentsWithTag } from '../store/entry-reads.js';
 import { loadConfig } from '../core/config.js';
-import { closeHippoDb, openHippoDb } from '../db/index.js';
-import { recordFailure } from '../store/failure-log.js';
+import { recordFailureAt } from '../store/failure-log-at.js';
 import { failureHash, failureSignature, lessonFromFailure, payloadString, } from './failure-reading.js';
 /** Store a failure as an error memory unless it is routine or a repeat, and log it either way, even when storing throws. */
-export function captureToolFailure(hippoRoot, tenantId, payload) {
+export function captureToolFailure(hippoRoot, tenantId, payload, onLogged) {
     const lesson = lessonFromFailure(payload);
     let outcome = 'store-failed';
     try {
@@ -17,26 +16,32 @@ export function captureToolFailure(hippoRoot, tenantId, payload) {
         return outcome;
     }
     finally {
-        logFailure(hippoRoot, tenantId, payload, lesson, outcome);
+        logAndReport(hippoRoot, tenantId, payload, lesson, outcome, onLogged);
     }
 }
-function logFailure(hippoRoot, tenantId, payload, lesson, outcome) {
-    const hash = (s) => (s === null ? null : failureHash(s));
-    const db = openHippoDb(hippoRoot);
+/** Logs the failure, then tells the caller the row id, or null when the write threw; the throw goes on. */
+function logAndReport(hippoRoot, tenantId, payload, lesson, outcome, onLogged) {
+    let id;
     try {
-        recordFailure(db, {
-            tenantId,
-            sessionId: payloadString(payload, 'session_id'),
-            tool: payloadString(payload, 'tool_name'),
-            outcome,
-            rule: 'rule' in lesson ? lesson.rule : null,
-            sigHash: hash(lesson.text),
-            detailHash: hash(lesson.detail),
-        });
+        id = logFailure(hippoRoot, tenantId, payload, lesson, outcome);
     }
-    finally {
-        closeHippoDb(db);
+    catch (error) {
+        onLogged?.(null);
+        throw error;
     }
+    onLogged?.(id);
+}
+function logFailure(hippoRoot, tenantId, payload, lesson, outcome) {
+    const hash = (s) => (s === null ? null : failureHash(s));
+    return recordFailureAt(hippoRoot, {
+        tenantId,
+        sessionId: payloadString(payload, 'session_id'),
+        tool: payloadString(payload, 'tool_name'),
+        outcome,
+        rule: 'rule' in lesson ? lesson.rule : null,
+        sigHash: hash(lesson.text),
+        detailHash: hash(lesson.detail),
+    });
 }
 export function storeLesson(hippoRoot, tenantId, text, caller) {
     const sig = failureSignature(text);

package/dist/capture/codex-patch.js

@@ -35,7 +35,9 @@ export function patchPaths(body) {
     }
     return paths.filter(Boolean);
 }
-const HEREDOC = /^\s*(?:cd\s+(?<cd>'[^']*'|"[^"]*"|[^\s'"&|;]+)\s+&&\s+)?(?:apply_patch|applypatch)\s+<<\s*(?<q>['"]?)(?<tag>\w+)\k<q>[ \t]*\r?\n(?<body>[\s\S]*?)\r?\n\s*\k<tag>\s*$/;
+const HEREDOC = new RegExp(String.raw `^\s*(?:cd\s+(?<cd>'[^']*'|"[^"]*"|[^\s'"&|;]+)\s+&&\s+)?` +
+    String.raw `(?:apply_patch|applypatch)\s+<<\s*(?<q>['"]?)(?<tag>\w+)\k<q>[ \t]*\r?\n` +
+    String.raw `(?<body>[\s\S]*?)\r?\n\s*\k<tag>\s*$`);
 /** The script a shell argv runs, for the shells Codex checks for an apply_patch heredoc. */
 function shellScript(argv) {
     const exe = path.basename(argv[0] ?? '').toLowerCase().replace(/\.exe$/, '');

package/dist/capture/command.d.ts

@@ -12,21 +12,13 @@ export interface CaptureOptions {
     stdinText?: string;
     stdinTimedOut?: boolean;
     sessionTurns?: readonly SessionTurn[];
-    /**
-     * Tee stdout/stderr to this log file while capture runs. Mirrors the
-     * pattern used by `hippo sleep --log-file` so the SessionEnd hook output
-     * (invisible during TUI teardown) can be surfaced via `hippo last-sleep`
-     * on the next session start. Appends rather than truncates — `hippo sleep`
-     * writes the same file first in the SessionEnd sequence.
-     */
+    /** Tee stdout/stderr to this log file while capture runs, so SessionEnd output (lost in TUI teardown) shows via `hippo last-sleep`.
+     *  Appends, because `hippo sleep` writes the same file first. */
     logFile?: string;
     dryRun: boolean;
     global: boolean;
-    /**
-     * Tenant scope for the dedup read in `cmdCaptureCore`. When provided
-     * AND `global` is false, the dedup check only considers this tenant's
-     * existing memories. Undefined means host-wide dedup. Ignored when `global: true` (global captures are host-wide).
-     */
+    /** Tenant scope for the dedup read in `cmdCaptureCore`: when set and `global` is false, only this tenant's memories count.
+     *  Undefined means host-wide dedup; ignored when `global: true`. */
     tenantId?: string;
     /** The session's project: rows are stamped with its id, and dedup reads its rows under either name. */
     originProject?: ProjectRef;