hippo-memory 1.69.0 → 1.70.0

package/dist/api/promote.js

@@ -1,20 +1,13 @@
 // Promote to the global store, supersede with a successor, and archive raw memories.
-import { openHippoDb, closeHippoDb } from '../db.js';
-import { ConflictError, NotFoundError } from '../api-errors.js';
+import { openHippoDb, closeHippoDb } from '../db/index.js';
+import { ConflictError, NotFoundError } from '../core/api-errors.js';
 import { stampOriginProject } from '../store/entry-row.js';
-import { writeEntryMirrors } from '../store/entry-writes.js';
-import { cleanArchivedMirrors, commitSupersede } from '../store/entry-writes-group.js';
-import { readEntry } from '../store/entry-reads.js';
-import { updateStatsUnlessBusy } from '../store/index-and-stats.js';
-import { requireGroup } from '../store-port.js';
-import { log } from '../log.js';
-import { createSuccessor } from '../memory.js';
-import { appendAuditEvent } from '../audit.js';
-import { promoteToGlobal } from '../shared.js';
-import { archiveRawMemory } from '../raw-archive.js';
-import { loadConfig } from '../config.js';
+import { createSuccessor } from '../core/memory.js';
+import { promoteToGlobal } from '../sharing/shared.js';
+import { loadConfig } from '../core/config.js';
+import { andThen, notPorted, onStore } from './on-store.js';
 import { selectMemoryReach } from '../store/tenant-lookup.js';
-import { canTouchScope, personalScopeOf } from '../recall-scope.js';
+import { canTouchScope, personalScopeOf } from '../store/recall-scope.js';
 export function promote(ctx, id) {
     // Tenant scope: promoteToGlobal reads the entry from the local root via
     // readEntry without a tenant filter, so a Bearer for tenant A could
@@ -36,64 +29,24 @@ export function promote(ctx, id) {
     const globalEntry = promoteToGlobal(ctx.hippoRoot, id, {
         actor: ctx.actor.subject,
         tenantId: ctx.tenantId,
-        afterWrite: (db, globalId) => appendAuditEvent(db, {
-            tenantId: ctx.tenantId,
-            actor: ctx.actor.subject,
-            op: 'promote',
-            targetId: globalId,
-            metadata: { sourceId: id },
-        }),
+        auditAs: { tenantId: ctx.tenantId, actor: ctx.actor.subject },
     });
     return { ok: true, sourceId: id, globalId: globalEntry.id };
 }
 export function supersede(ctx, oldId, newContent) {
-    const reply = ctx.store ? supersedeThroughStore(ctx, ctx.store, oldId, newContent) : supersedeOnHippoDb(ctx, oldId, newContent);
-    // SAFETY: a C typed with a store gets the promise its path returns; a wide C is typed as the union, which a caller has to await anyway.
-    return reply;
-}
-async function supersedeThroughStore(ctx, store, oldId, newContent) {
-    const entryWrites = requireGroup(store, 'entryWrites');
-    const [old] = await store.entriesByIds([oldId], ctx.tenantId);
-    const newEntry = createSuccessor(assertSupersedable(ctx, oldId, old ?? null), newContent, {
-        tenantId: ctx.tenantId,
-        baseHalfLifeDays: loadConfig(ctx.hippoRoot).defaultHalfLifeDays,
+    return onStore(ctx, (port) => {
+        const entryWrites = port.entryWrites ?? notPorted(port, 'entryWrites');
+        return andThen(port.entriesByIds([oldId], ctx.tenantId), ([old]) => {
+            const newEntry = createSuccessor(assertSupersedable(ctx, oldId, old ?? null), newContent, {
+                tenantId: ctx.tenantId,
+                baseHalfLifeDays: loadConfig(ctx.hippoRoot).defaultHalfLifeDays,
+            });
+            // A store writes origin_project as given, so the served folder's fallback is stamped here.
+            const successor = stampOriginProject(ctx.hippoRoot, newEntry);
+            const write = { tenantId: ctx.tenantId, actor: ctx.actor.subject, ownScope: personalScopeOf(ctx.actor), oldId, successor };
+            return andThen(entryWrites.supersede(write), () => ({ ok: true, oldId, newId: successor.id }));
+        });
     });
-    // The store writes origin_project as given, so the served folder's fallback is stamped here.
-    const successor = stampOriginProject(ctx.hippoRoot, newEntry);
-    await entryWrites.supersede({ tenantId: ctx.tenantId, actor: ctx.actor.subject, ownScope: personalScopeOf(ctx.actor), oldId, successor });
-    return { ok: true, oldId, newId: successor.id };
-}
-function supersedeOnHippoDb(ctx, oldId, newContent) {
-    const old = assertSupersedable(ctx, oldId, readEntry(ctx.hippoRoot, oldId, ctx.tenantId));
-    const successor = stampOriginProject(ctx.hippoRoot, createSuccessor(old, newContent, {
-        tenantId: ctx.tenantId,
-        baseHalfLifeDays: loadConfig(ctx.hippoRoot).defaultHalfLifeDays,
-    }));
-    // Race-safe transition: open a fresh db handle, BEGIN IMMEDIATE, run all
-    // three steps (CAS on old + writeEntryDbOnly(new) + supersede audit row)
-    // inside the same transaction. Two concurrent supersedes: exactly one CAS
-    // wins (changes=1), the other gets changes=0 and throws CONFLICT. No
-    // dangling-pointer window: the new memory's row commits atomically with
-    // the old.superseded_by pointer.
-    const db = openHippoDb(ctx.hippoRoot);
-    try {
-        commitSupersede(db, { tenantId: ctx.tenantId, actor: ctx.actor.subject, ownScope: personalScopeOf(ctx.actor), oldId, successor });
-        // Mirrors after COMMIT, while the db handle is still open. Same
-        // invariant as the original writeEntry: a mirror failure leaves disk
-        // MISSING the markdown for the new memory (rebuildIndex rewrites every
-        // markdown mirror from the DB) but DOES NOT desync the DB or
-        // roll back the supersede. Logged + swallowed, non-fatal.
-        try {
-            writeEntryMirrors(ctx.hippoRoot, successor);
-        }
-        catch (mirrorErr) {
-            log.error(`supersede: mirror write failed (non-fatal, will self-heal): ${mirrorErr instanceof Error ? mirrorErr.message : String(mirrorErr)}`);
-        }
-    }
-    finally {
-        closeHippoDb(db);
-    }
-    return { ok: true, oldId, newId: successor.id };
 }
 /** The tenant-scoped row to supersede; another tenant's id, or someone else's personal row, reads as not found. */
 function assertSupersedable(ctx, oldId, old) {
@@ -107,44 +60,14 @@ function assertSupersedable(ctx, oldId, old) {
     return old;
 }
 export function archiveRaw(ctx, id, reason, opts = {}) {
-    const reply = ctx.store ? archiveRawThroughStore(ctx, ctx.store, id, reason, opts) : archiveRawOnHippoDb(ctx, id, reason, opts);
-    // SAFETY: a C typed with a store gets the promise its path returns; a wide C is typed as the union, which a caller has to await anyway.
-    return reply;
-}
-/** afterArchive writes on hippo.db's own handle, and only connectors send it, so a store refuses it. */
-async function archiveRawThroughStore(ctx, store, id, reason, opts) {
-    const entryWrites = requireGroup(store, 'entryWrites');
-    if (opts.afterArchive)
-        throw new Error('afterArchive runs on hippo.db only, never through a store');
-    const archivedAt = await entryWrites.archiveRaw({ tenantId: ctx.tenantId, actor: ctx.actor.subject, ownScope: personalScopeOf(ctx.actor), id, reason });
-    return { ok: true, archivedAt };
-}
-function archiveRawOnHippoDb(ctx, id, reason, opts) {
-    const db = openHippoDb(ctx.hippoRoot);
-    let archivedAt;
-    try {
-        // Tenant scope: archiveRawMemory looks up the row by id alone, so a
-        // Bearer for tenant A could archive tenant B's raw row without this
-        // pre-check. Deny cross-tenant access with the same not-found message
-        // archiveRawMemory itself would throw on a missing row, so we don't
-        // leak whether the id exists in another tenant.
-        const reach = selectMemoryReach(db, id);
-        if (reach?.tenantId !== ctx.tenantId || !canTouchScope(ctx.actor, reach.scope)) {
-            throw new NotFoundError(`memory not found: ${id}`);
-        }
-        archivedAt = archiveRawMemory(db, id, {
-            reason,
-            who: ctx.actor.subject,
-            afterArchive: opts.afterArchive,
-        });
-        cleanArchivedMirrors(db, ctx.hippoRoot, id);
-    }
-    finally {
-        closeHippoDb(db);
-    }
-    // Counted here rather than in the CLI: the HTTP archive route calls this too,
-    // so a routed archive would otherwise never reach the forgotten counter.
-    updateStatsUnlessBusy(ctx.hippoRoot, { forgotten: 1 }, `removed ${id}`);
-    return { ok: true, archivedAt };
+    return onStore(ctx, (port) => {
+        const entryWrites = port.entryWrites ?? notPorted(port, 'entryWrites');
+        const archive = { tenantId: ctx.tenantId, actor: ctx.actor.subject, ownScope: personalScopeOf(ctx.actor), id, reason };
+        const { event } = opts;
+        const archived = event
+            ? (port.connectorWrites ?? notPorted(port, 'connectorWrites')).archiveConnectorEntry({ ...archive, event })
+            : entryWrites.archiveRaw(archive);
+        return andThen(archived, (archivedAt) => ({ ok: true, archivedAt }));
+    });
 }
 //# sourceMappingURL=promote.js.map

package/dist/{prompt-hook.d.ts → api/prompt-hook.d.ts}

@@ -1,11 +1,11 @@
-import { type Context, type ContextResult, type ContextResultEntry } from './api.js';
-import { type openHippoDb } from './db.js';
-import type { DeliveryRecorder } from './delivery-recorder.js';
-import { type JsonValue } from './json.js';
-import type { MemoryEntry } from './memory.js';
+import { type Context, type ContextResult, type ContextResultEntry } from './index.js';
+import type { DeliveryRecorder } from '../store/delivery-recorder.js';
+import { type JsonValue } from '../util/json.js';
+import type { MemoryEntry } from '../core/memory.js';
 import { type PilotArm } from './pilot-arm.js';
-/** With `db`, writes on the token ledger's handle (same store); without it, opens its own. A second flush is a no-op. */
-export declare function flushDeliveryRecorder(rec: DeliveryRecorder | null, db?: ReturnType<typeof openHippoDb>): void;
+import type { DeliveryWrite } from '../store/ledger-turn.js';
+/** With `write`, stores on the token ledger's connection (same store); without it, opens its own. A second flush is a no-op. */
+export declare function flushDeliveryRecorder(rec: DeliveryRecorder | null, write?: DeliveryWrite): void;
 /** What one render needs once api.getContext has answered. */
 export interface ContextView {
     readonly hippoRoot: string;

package/dist/{prompt-hook.js → api/prompt-hook.js}

@@ -1,27 +1,28 @@
 // The per-prompt hook's block and ledger rows, rendered here for `hippo context` and for promptHookContext (a remote hook route's call).
 // promptHookContext keeps the server-side copy of the CLI's getContext flags (cli/context.ts); the CLI parity case in tests/prompt-hook-context.test.ts is all that ties the two.
-import { getContext } from './api.js';
-import { BadRequestError } from './api-errors.js';
-import { isSharedStore, loadConfig } from './config.js';
+import { getContext } from './index.js';
+import { BadRequestError } from '../core/api-errors.js';
+import { isSharedStore, loadConfig } from '../core/config.js';
 import { contextBlockLines, contextCost, crossProjectLines, handoffText, sessionTrailText, settleTokens, snapshotText } from './context-render.js';
-import { isSqliteBusy, noteStoreBusy } from './db.js';
-import { MAX_ID_LEN } from './http-util.js';
-import { isJsonString } from './json.js';
-import { withLedgerDb } from './ledger-db.js';
+import { MAX_ID_LEN } from '../util/http-util.js';
+import { isJsonString } from '../util/json.js';
+import { bookLedgerTurn, ledgerLastSent, noteLedgerRowSkipped } from './ledger-db.js';
 import { sessionPilotArm } from './pilot-arm.js';
-import { assertCallerProject, MAX_PROJECT_ALIASES } from './project-identity.js';
-import { writeDeliveryEventAtRoot, writeDeliveryEventOnHandle } from './recall-trace.js';
-import { blockHash, estimateTokens, hookPayloadString, isSubagentPayload, lastSentState, recordTokenUse, shouldSkipUnchanged, } from './token-ledger.js';
-/** With `db`, writes on the token ledger's handle (same store); without it, opens its own. A second flush is a no-op. */
-export function flushDeliveryRecorder(rec, db) {
+import { assertCallerProject, MAX_PROJECT_ALIASES } from '../core/project-identity.js';
+import { writeDeliveryEventAtRoot } from '../store/recall-trace.js';
+import { hookPayloadString, isSubagentPayload, shouldSkipUnchanged, } from '../store/token-ledger.js';
+import { blockHash, estimateTokens } from '../util/token-text.js';
+import { errorMessage } from '../util/log.js';
+/** With `write`, stores on the token ledger's connection (same store); without it, opens its own. A second flush is a no-op. */
+export function flushDeliveryRecorder(rec, write) {
     if (rec === null)
         return;
     try {
-        rec.flush((input) => (db ? writeDeliveryEventOnHandle(db, input) : writeDeliveryEventAtRoot(rec.root, input)));
+        rec.flush(write ?? ((input) => writeDeliveryEventAtRoot(rec.root, input)));
     }
     catch (error) {
         // The hook's one-line stderr contract pins this exact text, so it bypasses the leveled logger.
-        console.error(`[hippo] delivery ledger write failed:${error instanceof Error ? error.message : String(error)}`);
+        console.error(`[hippo] delivery ledger write failed:${errorMessage(error)}`);
     }
 }
 /** A Copilot sessionStart reply's wrapper, picked by the sender's casing: stdin.ts keeps a camelCase `sessionId`, which only the Copilot harness sends. */
@@ -113,51 +114,31 @@ function skipUnchangedStatic(view, surface, staticBlock, recallBlock, staticCoun
     // Before the ledger read, so a caller that did not print this block books no skip row.
     if (view.printedHash !== undefined && view.printedHash !== staticHash)
         return false;
-    const last = withLedgerDb(hippoRoot, (db) => lastSentState(db, view.tenantId, payloadSessionId, surface), ledgerOpts);
+    const last = ledgerLastSent(hippoRoot, view.tenantId, payloadSessionId, surface, ledgerOpts);
     if (!shouldSkipUnchanged(last ?? null, staticHash, refreshTurns))
         return false;
-    withLedgerDb(hippoRoot, (db) => {
-        recordTokenUse(db, {
-            tenantId: view.tenantId, sessionId: payloadSessionId, surface, event: 'skip',
-            items: staticCount, tokens: estimateTokens(staticBlock), hash: staticHash,
-        });
-        if (recallBlock.trim())
-            return;
-        rec?.delivered({ state: 'reused', staticHash, staticReused: true });
-        flushDeliveryRecorder(rec, db);
+    bookLedgerTurn(hippoRoot, {
+        uses: [{
+                tenantId: view.tenantId, sessionId: payloadSessionId, surface, event: 'skip',
+                items: staticCount, tokens: estimateTokens(staticBlock), hash: staticHash,
+            }],
+        delivery: recallBlock.trim() ? undefined : (write) => {
+            rec?.delivered({ state: 'reused', staticHash, staticReused: true });
+            flushDeliveryRecorder(rec, write);
+        },
     }, ledgerOpts);
     return true;
 }
-/** One connection for both rows; each insert in its own try so one failing doesn't skip the other. */
+/** One connection for both rows; a failed row is logged and the other still lands, because a ledger failure must not break the hook. */
 function recordAdditionalContextRows(view, surface, staticPart, recallPart) {
-    withLedgerDb(view.hippoRoot, (db) => {
-        if (staticPart.text) {
-            try {
-                recordTokenUse(db, {
-                    tenantId: view.tenantId, sessionId: view.ledgerSessionId, surface, event: 'inject',
-                    items: staticPart.items, tokens: estimateTokens(staticPart.text), hash: blockHash(staticPart.text),
-                });
-                // Best-effort row: only a busy store is actionable, and a ledger failure must not break the hook.
-            }
-            catch (error) {
-                if (isSqliteBusy(error))
-                    noteStoreBusy('token ledger row skipped');
-            }
-        }
-        if (recallPart.text) {
-            try {
-                recordTokenUse(db, {
-                    tenantId: view.tenantId, sessionId: view.ledgerSessionId, surface: 'hook_recall', event: 'inject',
-                    items: recallPart.items, tokens: estimateTokens(recallPart.text), hash: blockHash(recallPart.text),
-                });
-                // Same best-effort rule as the inject row above.
-            }
-            catch (error) {
-                if (isSqliteBusy(error))
-                    noteStoreBusy('token ledger row skipped');
-            }
-        }
-        flushDeliveryRecorder(view.rec, db);
+    const row = (part, on) => ({
+        tenantId: view.tenantId, sessionId: view.ledgerSessionId, surface: on, event: 'inject',
+        items: part.items, tokens: estimateTokens(part.text), hash: blockHash(part.text),
+    });
+    bookLedgerTurn(view.hippoRoot, {
+        uses: [...(staticPart.text ? [row(staticPart, surface)] : []), ...(recallPart.text ? [row(recallPart, 'hook_recall')] : [])],
+        onRowError: noteLedgerRowSkipped,
+        delivery: (write) => flushDeliveryRecorder(view.rec, write),
     }, { sharedStore: view.sharedStore });
 }
 // The flags HIPPO_PINNED_INJECT_COMMAND gives the local hook; the CLI parity test fails if the two drift.

package/dist/api/quarantine.d.ts

@@ -1,5 +1,5 @@
-import { type QuarantineStatus } from '../quarantine.js';
-import type { KeysetPosition } from '../keyset.js';
+import type { QuarantineStatus } from '../store/quarantine.js';
+import type { KeysetPosition } from '../util/keyset.js';
 import type { Context } from './types.js';
 export interface QuarantineListItem {
     id: string;
@@ -16,9 +16,9 @@ export declare function quarantineList(ctx: Context, opts?: {
     status?: QuarantineStatus | 'all';
     limit?: number;
     after?: KeysetPosition;
-}): QuarantineListItem[];
+}): Promise<QuarantineListItem[]>;
 /** Release a quarantined memory to its original scope. Admin only; the scope guard refuses a row moved since (mirrors restoreDormant). */
-export declare function quarantineApprove(ctx: Context, id: string): void;
+export declare function quarantineApprove(ctx: Context, id: string): Promise<void>;
 /** Keep a quarantined memory hidden for good. Admin only; the raw row is untouched (append-only). */
-export declare function quarantineReject(ctx: Context, id: string): void;
+export declare function quarantineReject(ctx: Context, id: string): Promise<void>;
 //# sourceMappingURL=quarantine.d.ts.map

package/dist/api/quarantine.js

@@ -1,122 +1,46 @@
 // Quarantine review: list, approve and reject held memories.
-import { openHippoDb, closeHippoDb } from '../db.js';
-import { ConflictError, ForbiddenError, NotFoundError } from '../api-errors.js';
-import { writeEntryMirrors } from '../store/entry-writes.js';
-import { readEntry, selectEntriesByIds } from '../store/entry-reads.js';
-import { quarantineScopeFor, getQuarantineRow, listQuarantineRows, approveQuarantineRow, rejectQuarantineRow, } from '../quarantine.js';
-import { log } from '../log.js';
-import { appendAuditEvent } from '../audit.js';
+import { ConflictError, ForbiddenError, NotFoundError } from '../core/api-errors.js';
+import { requireGroup, storeFor } from '../store/index.js';
 const QUARANTINE_PREVIEW_CHARS = 200;
 /** A tenant's quarantined memories, newest first. Default `status` is 'pending' (the review queue). */
-export function quarantineList(ctx, opts = {}) {
-    const db = openHippoDb(ctx.hippoRoot);
-    try {
-        const rows = listQuarantineRows(db, ctx.tenantId, opts.status ?? 'pending', opts.limit, opts.after);
-        const entries = selectEntriesByIds(db, rows.map((row) => row.memoryId), ctx.tenantId);
-        return rows.map((row) => {
-            const entry = entries.get(row.memoryId);
-            return {
-                id: row.memoryId,
-                originalScope: row.originalScope,
-                reason: row.reason,
-                status: row.status,
-                quarantinedAt: row.quarantinedAt,
-                decidedAt: row.decidedAt,
-                decidedBy: row.decidedBy,
-                contentPreview: entry ? entry.content.slice(0, QUARANTINE_PREVIEW_CHARS) : '',
-            };
-        });
-    }
-    finally {
-        closeHippoDb(db);
-    }
+export async function quarantineList(ctx, opts = {}) {
+    const rows = await requireGroup(storeFor(ctx), 'quarantine')
+        .listQuarantined(ctx.tenantId, { status: opts.status ?? 'pending', limit: opts.limit, after: opts.after });
+    return rows.map((row) => ({
+        id: row.memoryId,
+        originalScope: row.originalScope,
+        reason: row.reason,
+        status: row.status,
+        quarantinedAt: row.quarantinedAt,
+        decidedAt: row.decidedAt,
+        decidedBy: row.decidedBy,
+        contentPreview: (row.content ?? '').slice(0, QUARANTINE_PREVIEW_CHARS),
+    }));
 }
-function loadPendingQuarantineRow(db, tenantId, id) {
-    const row = getQuarantineRow(db, tenantId, id);
-    if (!row)
-        throw new NotFoundError(`not quarantined: ${id}`);
-    if (row.status !== 'pending')
-        throw new ConflictError(`${id} is already ${row.status}`);
-    return row;
+function refusalError(id, refusal) {
+    if (refusal.outcome === 'not_quarantined')
+        return new NotFoundError(`not quarantined: ${id}`);
+    return new ConflictError(`${id} is already ${refusal.status}`);
 }
 /** Release a quarantined memory to its original scope. Admin only; the scope guard refuses a row moved since (mirrors restoreDormant). */
-export function quarantineApprove(ctx, id) {
+export async function quarantineApprove(ctx, id) {
     if (ctx.actor.role !== 'admin') {
         throw new ForbiddenError('Only an admin key can approve a quarantined memory');
     }
-    const db = openHippoDb(ctx.hippoRoot);
-    try {
-        db.exec('BEGIN IMMEDIATE');
-        try {
-            const row = loadPendingQuarantineRow(db, ctx.tenantId, id);
-            const quarantineScope = quarantineScopeFor(row.originalScope);
-            const updated = db
-                .prepare(`UPDATE memories SET scope = ? WHERE id = ? AND tenant_id = ? AND scope = ?`)
-                .run(row.originalScope, id, ctx.tenantId, quarantineScope);
-            if (Number(updated.changes ?? 0) !== 1) {
-                throw new ConflictError(`memory ${id} scope changed since quarantine; refusing to approve`);
-            }
-            approveQuarantineRow(db, ctx.tenantId, id, ctx.actor.subject);
-            appendAuditEvent(db, {
-                tenantId: ctx.tenantId,
-                actor: ctx.actor.subject,
-                op: 'quarantine_approve',
-                targetId: id,
-                metadata: { originalScope: row.originalScope },
-            });
-            db.exec('COMMIT');
-        }
-        catch (err) {
-            try {
-                db.exec('ROLLBACK');
-            }
-            catch { /* already rolled back */ }
-            throw err;
-        }
-    }
-    finally {
-        closeHippoDb(db);
-    }
-    // Post-commit, best-effort: a failed rewrite leaves the mirror showing the quarantine scope (fail-closed).
-    try {
-        const restored = readEntry(ctx.hippoRoot, id, ctx.tenantId);
-        if (restored)
-            writeEntryMirrors(ctx.hippoRoot, restored);
-    }
-    catch (err) {
-        log.error(`quarantine: mirror rewrite failed for ${id}: ${err instanceof Error ? err.message : String(err)}`);
-    }
+    const result = await requireGroup(storeFor(ctx), 'quarantine').approveQuarantined(ctx.tenantId, id, ctx.actor.subject);
+    if (result.outcome === 'approved')
+        return;
+    if (result.outcome === 'scope_moved')
+        throw new ConflictError(`memory ${id} scope changed since quarantine; refusing to approve`);
+    throw refusalError(id, result);
 }
 /** Keep a quarantined memory hidden for good. Admin only; the raw row is untouched (append-only). */
-export function quarantineReject(ctx, id) {
+export async function quarantineReject(ctx, id) {
     if (ctx.actor.role !== 'admin') {
         throw new ForbiddenError('Only an admin key can reject a quarantined memory');
     }
-    const db = openHippoDb(ctx.hippoRoot);
-    try {
-        db.exec('BEGIN IMMEDIATE');
-        try {
-            loadPendingQuarantineRow(db, ctx.tenantId, id);
-            rejectQuarantineRow(db, ctx.tenantId, id, ctx.actor.subject);
-            appendAuditEvent(db, {
-                tenantId: ctx.tenantId,
-                actor: ctx.actor.subject,
-                op: 'quarantine_reject',
-                targetId: id,
-                metadata: {},
-            });
-            db.exec('COMMIT');
-        }
-        catch (err) {
-            try {
-                db.exec('ROLLBACK');
-            }
-            catch { /* already rolled back */ }
-            throw err;
-        }
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    const result = await requireGroup(storeFor(ctx), 'quarantine').rejectQuarantined(ctx.tenantId, id, ctx.actor.subject);
+    if (result.outcome !== 'rejected')
+        throw refusalError(id, result);
 }
 //# sourceMappingURL=quarantine.js.map

package/dist/api/recall-core.d.ts

@@ -0,0 +1,4 @@
+import type { CliCoreRanker, RecallOpts, RecallResult } from './recall-types.js';
+import type { Context } from './types.js';
+export declare function retrieveWithCliCore(ctx: Context, opts: RecallOpts, core: CliCoreRanker): Promise<RecallResult>;
+//# sourceMappingURL=recall-core.d.ts.map

package/dist/api/recall-core.js

@@ -0,0 +1,112 @@
+// The CLI ranking core as a ranker of retrieve(): rank, let the caller pick the list it shows, then record that list once.
+import { ForbiddenError } from '../core/api-errors.js';
+import { reportAuditWriteFailure } from '../store/audit.js';
+import { decidePlanningFallacy, detectPlanningClaim } from '../predictions/planning-fallacy.js';
+import { rankRecall } from './recall-pipeline.js';
+import { writeRecallTraceAtRoot } from '../store/recall-trace.js';
+import { saveIndex } from '../store/index-and-stats.js';
+import { sqliteStore } from '../store/index.js';
+import { estimateTokens } from '../util/token-text.js';
+import { callerOf, recallAuditMetadata, recallAuditRow, strengthenOf } from './recall-record.js';
+import { recordTokens } from './tokens.js';
+// entriesByIds reads at most this many ids a call.
+const ID_READ_CHUNK = 500;
+export async function retrieveWithCliCore(ctx, opts, core) {
+    // This ranker applies the operator's scope rule and may search a second store, so no bearer client may reach it.
+    if (!ctx.actor.hostAdmin)
+        throw new ForbiddenError('The CLI ranking core serves the host admin only');
+    const globalRoot = core.sources?.globalRoot;
+    // The ranking core reads hippo.db itself, so its writes go to the same file whatever store the context names.
+    const store = sqliteStore(ctx.hippoRoot);
+    const ranking = await rankRecall({ hippoRoot: ctx.hippoRoot, globalRoot, tenantId: ctx.tenantId, note: core.note }, { ...core.rank, query: opts.query, sessionId: opts.sessionId, goalTag: opts.goalTag });
+    if (ranking.halted) {
+        // The stages that ran earned these rows, so the caller's flag error does not drop them.
+        if (ranking.goalRecallLog.length > 0)
+            await store.finishRecall({ goalLog: ranking.goalRecallLog, audit: [] });
+        return resultOf(ranking, []);
+    }
+    if ('inspect' in core) {
+        core.inspect(ranking);
+        return resultOf(ranking, ranking.results);
+    }
+    const planning = await planningFor(ctx, store, opts.query);
+    const shown = core.show(ranking, planning?.output ?? {});
+    await recordShown(ctx, store, opts, core, { ranking, shown, planningAudit: planning?.audit });
+    const result = resultOf(ranking, shown.results);
+    if (planning?.output.hint)
+        result.planningFallacyHint = planning.output.hint;
+    if (planning?.output.watching)
+        result.planningFallacyWatching = planning.output.watching;
+    return result;
+}
+async function planningFor(ctx, store, query) {
+    const claim = detectPlanningClaim(query);
+    if (!claim)
+        return null;
+    return decidePlanningFallacy(claim, await store.planningFallacyEvidence(ctx.tenantId, claim.classQueryTokens), ctx.tenantId, ctx.actor.subject);
+}
+function resultOf(ranking, shown) {
+    const results = shown.map((r) => ({ id: r.entry.id, content: r.entry.content, score: r.score, layer: r.entry.layer, strength: r.entry.strength }));
+    return {
+        results,
+        total: ranking.totalCandidates + ranking.graphAdded,
+        tokens: results.reduce((sum, r) => sum + estimateTokens(r.content), 0),
+    };
+}
+/** Audit rows first: a recall they cannot be written for leaves no strengthen, trace, marker or count, as under the other rankers. */
+async function recordShown(ctx, store, opts, core, done) {
+    const { ranking, shown, planningAudit } = done;
+    const ids = shown.results.map((r) => r.entry.id);
+    const recallRow = recallAuditRow(callerOf(ctx), 'recall', undefined, recallAuditMetadata(opts.query, ids.length));
+    const second = core.sources?.globalRoot !== undefined && core.sources.globalRoot !== ctx.hippoRoot ? core.sources.globalRoot : undefined;
+    const heldElsewhere = second !== undefined ? await idsNotHeld(store, ids, ctx.tenantId) : [];
+    const audited = await finishOrReport(store, {
+        goalLog: ranking.goalRecallLog,
+        audit: [...(planningAudit ? [planningAudit] : []), ...shown.audit, recallRow],
+        strengthen: strengthenOf(ctx, ids),
+    });
+    if (audited) {
+        // The second store logs that it was searched, and strengthens only the rows the first does not hold.
+        if (second !== undefined)
+            await finishOrReport(sqliteStore(second), { goalLog: [], audit: [recallRow], strengthen: strengthenOf(ctx, heldElsewhere) });
+        await traceAndMark(ctx, store, opts, core, shown.results);
+    }
+    // The ledger books the text the caller prints, and it prints whether or not the record was written.
+    await recordTokens(ctx, 'recall', { items: ids.length, tokens: shown.tokens, sessionId: core.hostSessionId ?? null });
+}
+// The caller has ranked and is about to print, so a failed audit write is logged and counted, never thrown.
+async function finishOrReport(store, writes) {
+    try {
+        await store.finishRecall(writes);
+        return true;
+    }
+    catch (err) {
+        reportAuditWriteFailure('recall', String(err));
+        return false;
+    }
+}
+async function idsNotHeld(store, ids, tenantId) {
+    const held = new Set();
+    for (let i = 0; i < ids.length; i += ID_READ_CHUNK) {
+        for (const entry of await store.entriesByIds(ids.slice(i, i + ID_READ_CHUNK), tenantId))
+            held.add(entry.id);
+    }
+    return ids.filter((id) => !held.has(id));
+}
+async function traceAndMark(ctx, store, opts, core, shown) {
+    // An empty list is traced too, so a coverage gap still reaches the training corpus.
+    const traceId = writeRecallTraceAtRoot(ctx.hippoRoot, {
+        tenantId: ctx.tenantId,
+        sessionId: opts.sessionId || core.hostSessionId || null,
+        pipeline: 'cli',
+        query: opts.query,
+        explainMode: core.rank.why === true,
+        results: shown.map((r) => ({ memoryId: r.entry.id, score: r.score, rerankSteps: r.rerankTrace })),
+    });
+    if (shown.length === 0)
+        return;
+    // One write for both markers, so `hippo outcome` never pairs these ids with an older trace.
+    saveIndex(ctx.hippoRoot, { last_retrieval_ids: shown.map((r) => r.entry.id), last_trace_id: traceId !== null ? String(traceId) : null });
+    await store.bumpRecallStats(shown.length);
+}
+//# sourceMappingURL=recall-core.js.map