hippo-memory 1.69.0 → 1.70.0

package/dist/api/learn.js

@@ -1,14 +1,15 @@
 // Git auto-learn: fix/revert/bug commit subjects become memories. `hippo learn`, init, sleep and MCP hippo_learn share it.
-import { ForbiddenError } from '../api-errors.js';
-import { fetchGitLog, extractLessons, partitionLessons, isGitRepo } from '../autolearn.js';
-import { loadConfig } from '../config.js';
-import { embedMemory } from '../embeddings.js';
-import { extractInvalidationTarget, invalidateMatching } from '../invalidation.js';
-import { computeSchemaFit, createMemory, Layer } from '../memory.js';
-import { extractPathTags } from '../path-context.js';
-import { canReadScope, personalScopeOf, touchableScopeSql } from '../recall-scope.js';
-import { RejectedValueError } from '../rejection.js';
-import { duplicateKey, longestWord, storedTextKeys } from '../same-text.js';
+import { ForbiddenError } from '../core/api-errors.js';
+import { fetchGitLog, extractLessons, partitionLessons, isGitRepo } from '../learn/autolearn.js';
+import { loadConfig } from '../core/config.js';
+import { withRequestStoresSync } from '../db/request-stores.js';
+import { embedMemory } from '../store/embeddings/index.js';
+import { extractInvalidationTarget, invalidateMatchingAmong } from '../learn/invalidation.js';
+import { computeSchemaFit, createMemory, Layer } from '../core/memory.js';
+import { extractPathTags } from '../search/path-context.js';
+import { canReadScope, personalScopeOf, touchableScopeSql } from '../store/recall-scope.js';
+import { RejectedValueError } from '../store/rejection.js';
+import { duplicateKey, longestWord, storedTextKeys } from '../util/same-text.js';
 import { loadTextsHoldingWords } from '../store/candidates.js';
 import { loadAllEntries } from '../store/entry-reads.js';
 import { writeEntry } from '../store/entry-writes.js';
@@ -38,53 +39,60 @@ export function learn(ctx, opts) {
 function writeLessons(ctx, lessons, opts, config) {
     const { hippoRoot, tenantId } = ctx;
     const { profile } = opts;
-    // Schema fit needs every row; without it, only rows holding a lesson's longest word can be its copy. Learn is host-admin only, so both read what an admin can.
-    const existing = profile.full ? loadAllEntries(hippoRoot, tenantId).filter((e) => e.scope == null || canReadScope(ctx.actor, e.scope)) : undefined;
-    const readable = touchableScopeSql('', personalScopeOf(ctx.actor));
-    const keys = storedTextKeys(existing ?? loadTextsHoldingWords(hippoRoot, tenantId, lessons.map(longestWord), undefined, readable));
-    const pathTags = profile.full ? extractPathTags(opts.repoPath) : [];
-    const counts = { added: 0, skipped: 0, rejected: 0, invalidations: [] };
-    for (const lesson of lessons) {
-        if (keys.has(duplicateKey(lesson))) {
-            counts.skipped++;
-            continue;
-        }
-        const target = profile.full ? extractInvalidationTarget(lesson) : null;
-        if (target) {
-            const { invalidated } = invalidateMatching(hippoRoot, target, tenantId);
-            if (invalidated > 0)
-                counts.invalidations.push({ from: target.from, count: invalidated });
-        }
-        const entry = createMemory(lesson, {
-            layer: Layer.Episodic,
-            tags: [...profile.tags],
-            source: profile.source,
-            confidence: 'observed',
-            schema_fit: existing && computeSchemaFit(lesson, [...profile.tags], existing),
-            tenantId,
-            baseHalfLifeDays: config.defaultHalfLifeDays,
-        });
-        for (const tag of pathTags)
-            if (!entry.tags.includes(tag))
-                entry.tags.push(tag);
-        // A refused lesson must not abort the rest of the git-log scan.
-        try {
-            writeEntry(hippoRoot, entry, { actor: ctx.actor.subject });
-        }
-        catch (err) {
-            if (err instanceof RejectedValueError) {
-                counts.rejected++;
+    // `hippo init` calls this outside any request, so the batch brings its own scope: every read and write below shares one handle.
+    return withRequestStoresSync(() => {
+        // One read serves the batch: invalidation matches against `live`, which follows every write below, as a reload per lesson did.
+        const live = profile.full ? loadAllEntries(hippoRoot, tenantId) : [];
+        // Schema fit needs every row; without it, only rows holding a lesson's longest word can be its copy. Learn is host-admin only, so both read what an admin can.
+        const existing = profile.full ? live.filter((e) => e.scope == null || canReadScope(ctx.actor, e.scope)) : undefined;
+        const readable = touchableScopeSql('', personalScopeOf(ctx.actor));
+        const keys = storedTextKeys(existing ?? loadTextsHoldingWords(hippoRoot, tenantId, lessons.map(longestWord), undefined, readable));
+        const pathTags = profile.full ? extractPathTags(opts.repoPath) : [];
+        const counts = { added: 0, skipped: 0, rejected: 0, invalidations: [] };
+        for (const lesson of lessons) {
+            if (keys.has(duplicateKey(lesson))) {
+                counts.skipped++;
                 continue;
             }
-            throw err;
+            const target = profile.full ? extractInvalidationTarget(lesson) : null;
+            if (target) {
+                const { invalidated } = invalidateMatchingAmong(hippoRoot, live, target, tenantId);
+                if (invalidated > 0)
+                    counts.invalidations.push({ from: target.from, count: invalidated });
+            }
+            const entry = createMemory(lesson, {
+                layer: Layer.Episodic,
+                tags: [...profile.tags],
+                source: profile.source,
+                confidence: 'observed',
+                schema_fit: existing && computeSchemaFit(lesson, [...profile.tags], existing),
+                tenantId,
+                baseHalfLifeDays: config.defaultHalfLifeDays,
+            });
+            for (const tag of pathTags)
+                if (!entry.tags.includes(tag))
+                    entry.tags.push(tag);
+            // A refused lesson must not abort the rest of the git-log scan.
+            try {
+                writeEntry(hippoRoot, entry, { actor: ctx.actor.subject });
+            }
+            catch (err) {
+                if (err instanceof RejectedValueError) {
+                    counts.rejected++;
+                    continue;
+                }
+                throw err;
+            }
+            if (profile.full) {
+                updateStats(hippoRoot, { remembered: 1 });
+                live.push(entry);
+            }
+            keys.add(duplicateKey(lesson));
+            if (profile.full)
+                void embedMemory(hippoRoot, entry);
+            counts.added++;
         }
-        if (profile.full)
-            updateStats(hippoRoot, { remembered: 1 });
-        keys.add(duplicateKey(lesson));
-        if (profile.full)
-            void embedMemory(hippoRoot, entry);
-        counts.added++;
-    }
-    return counts;
+        return counts;
+    });
 }
 //# sourceMappingURL=learn.js.map

package/dist/api/ledger-db.d.ts

@@ -0,0 +1,20 @@
+import { type openHippoDb } from '../db/index.js';
+import { type LedgerTurn } from '../store/ledger-turn.js';
+import type { LastSent, TokenSurface, TokenUse } from '../store/token-ledger.js';
+export interface LedgerRootOpts {
+    /** The store serves many people, so the global store of the user running it belongs to none of them. */
+    readonly sharedStore?: boolean;
+}
+/** `hippoRoot` when it holds a store, else the global store (the prompt hook fires where no local one exists), else null. */
+export declare function ledgerRoot(hippoRoot: string, opts?: LedgerRootOpts): string | null;
+/** Says why a ledger row did not land, at the level its class earns: busy warns once through noteStoreBusy, absent is debug with no stack, unexpected warns once with the error class and stack. */
+export declare function noteLedgerRowSkipped<E>(error: E): void;
+/** Books one row in ledgerRoot's store, best-effort. */
+export declare function bookTokenUse(hippoRoot: string, use: TokenUse, opts?: LedgerRootOpts): void;
+/** Books a turn's rows and then its delivery event on one connection of ledgerRoot's store, best-effort. */
+export declare function bookLedgerTurn(hippoRoot: string, turn: LedgerTurn, opts?: LedgerRootOpts): void;
+/** What the session last sent on `surface` in ledgerRoot's store; undefined with no ledger or a failed read. */
+export declare function ledgerLastSent(hippoRoot: string, tenantId: string, sessionId: string | null | undefined, surface: TokenSurface, opts?: LedgerRootOpts): LastSent | null | undefined;
+/** Runs `fn` on a handle of ledgerRoot's store, best-effort as the calls above. */
+export declare function withLedgerDb<T>(hippoRoot: string, fn: (db: ReturnType<typeof openHippoDb>) => T, opts?: LedgerRootOpts): T | undefined;
+//# sourceMappingURL=ledger-db.d.ts.map

package/dist/api/ledger-db.js

@@ -0,0 +1,79 @@
+// The store the token ledger writes to for a caller's root; context, recall and the session hooks share it.
+import { isSqliteBusy, noteStoreBusy } from '../db/index.js';
+import { errorFields, errorMessage, log } from '../util/log.js';
+import { getGlobalRoot } from '../sharing/shared.js';
+import { lastSentOnSurface, recordLedgerTurn } from '../store/ledger-turn.js';
+import { isInitialized, onHandle } from '../store/open.js';
+import { sqliteSyncStore } from '../store/sqlite/store.js';
+/** `hippoRoot` when it holds a store, else the global store (the prompt hook fires where no local one exists), else null. */
+export function ledgerRoot(hippoRoot, opts) {
+    if (isInitialized(hippoRoot))
+        return hippoRoot;
+    if (opts?.sharedStore)
+        return null;
+    const globalRoot = getGlobalRoot();
+    return isInitialized(globalRoot) ? globalRoot : null;
+}
+// SQLite's result codes for a hippo.db it cannot read: a corrupt image, and a file that is no database.
+const SQLITE_CORRUPT = 11;
+const SQLITE_NOTADB = 26;
+/** The one rule for a skipped ledger row. `absent` is a store with no token_ledger table or a hippo.db SQLite cannot read; the command that owns the store reports that, and a hook must stay quiet about it. */
+function ledgerSkipClass(error) {
+    if (isSqliteBusy(error))
+        return 'busy';
+    const code = error instanceof Error && 'errcode' in error ? error.errcode : undefined;
+    if (code === SQLITE_CORRUPT || code === SQLITE_NOTADB)
+        return 'absent';
+    return errorMessage(error).includes('no such table: token_ledger') ? 'absent' : 'unexpected';
+}
+/** Says why a ledger row did not land, at the level its class earns: busy warns once through noteStoreBusy, absent is debug with no stack, unexpected warns once with the error class and stack. */
+export function noteLedgerRowSkipped(error) {
+    const skip = ledgerSkipClass(error);
+    if (skip === 'busy') {
+        noteStoreBusy('token ledger row skipped');
+        return;
+    }
+    const message = `token ledger row skipped: ${errorMessage(error)}`;
+    if (skip === 'absent')
+        log.debug(message);
+    else
+        log.warnThenDebug('token-ledger-row', message, errorFields(error));
+}
+/** Runs `call` on ledgerRoot's store root. Best-effort: undefined on any failure, because a ledger failure must not break context or recall. */
+function onLedgerRoot(hippoRoot, opts, call) {
+    let root = null;
+    try {
+        root = ledgerRoot(hippoRoot, opts);
+    }
+    catch (error) {
+        // An unreadable store root means no ledger write; the ledger must never break context or recall.
+        log.debug(`token ledger skipped, store root unreadable: ${errorMessage(error)}`);
+        return undefined;
+    }
+    if (root === null)
+        return undefined;
+    try {
+        return call(root);
+    }
+    catch (error) {
+        noteLedgerRowSkipped(error);
+        return undefined;
+    }
+}
+/** Books one row in ledgerRoot's store, best-effort. */
+export function bookTokenUse(hippoRoot, use, opts) {
+    onLedgerRoot(hippoRoot, opts, (root) => sqliteSyncStore(root).recordTokens(use));
+}
+/** Books a turn's rows and then its delivery event on one connection of ledgerRoot's store, best-effort. */
+export function bookLedgerTurn(hippoRoot, turn, opts) {
+    onLedgerRoot(hippoRoot, opts, (root) => recordLedgerTurn(root, turn));
+}
+/** What the session last sent on `surface` in ledgerRoot's store; undefined with no ledger or a failed read. */
+export function ledgerLastSent(hippoRoot, tenantId, sessionId, surface, opts) {
+    return onLedgerRoot(hippoRoot, opts, (root) => lastSentOnSurface(root, tenantId, sessionId, surface));
+}
+/** Runs `fn` on a handle of ledgerRoot's store, best-effort as the calls above. */
+export function withLedgerDb(hippoRoot, fn, opts) {
+    return onLedgerRoot(hippoRoot, opts, (root) => onHandle(root, fn));
+}
+//# sourceMappingURL=ledger-db.js.map

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

@@ -0,0 +1,16 @@
+import type { HippoStore, StoreGroups } from '../store/port.js';
+import { type SqliteLocal } from '../store/sqlite/local.js';
+import { type SqliteSyncStore } from '../store/sqlite/store.js';
+import type { Context, StoreReply } from './types.js';
+/** What a port call answers: a Promise from a served store, the value itself from hippo.db. */
+export type Reply<T> = T | Promise<T>;
+/** The port one body is written against: a served store, or hippo.db answering the same methods at once. */
+export type StorePort = HippoStore | SqliteSyncStore;
+/** `next` on the reply's value, at once for a value, so hippo.db's path never becomes a Promise. */
+export declare function andThen<T, U>(reply: Reply<T>, next: (value: T) => Reply<U>): Reply<U>;
+/** Stands in for a group the store lacks, as `port.keyAudit ?? notPorted(port, 'keyAudit')`; it answers 501 as any unported path does. */
+export declare function notPorted(port: StorePort, group: keyof StoreGroups): never;
+/** Runs `run` on `ctx.store`, where a throw rejects, else on hippo.db under `ctx.hippoRoot`, where it throws. The store path never reads `hippoRoot`.
+ *  `local` runs what needs hippo.db's own handle or meta table; a served store refuses it, or does without where the write allows. */
+export declare function onStore<C extends Context, R>(ctx: C, run: (port: StorePort, local: SqliteLocal) => Reply<R>): StoreReply<C, R>;
+//# sourceMappingURL=on-store.d.ts.map

package/dist/api/on-store.js

@@ -0,0 +1,36 @@
+// The one place an api function picks between a served store and hippo.db, so each operation has one body.
+// Only functions published as StoreReply use this carrier (see "Sync core, async port" in docs/ARCHITECTURE.md);
+// a new operation is async and goes through storeFor(ctx).
+import { SqliteBlockedError, StoreNotPortedError } from '../util/sqlite-blocked.js';
+import { REFUSED_ON_A_STORE, sqliteLocal } from '../store/sqlite/local.js';
+import { sqliteSyncStore } from '../store/sqlite/store.js';
+/** `next` on the reply's value, at once for a value, so hippo.db's path never becomes a Promise. */
+export function andThen(reply, next) {
+    return reply instanceof Promise ? reply.then(next) : next(reply);
+}
+/** Stands in for a group the store lacks, as `port.keyAudit ?? notPorted(port, 'keyAudit')`; it answers 501 as any unported path does. */
+export function notPorted(port, group) {
+    throw new StoreNotPortedError(port.kind, group);
+}
+/** A served store's stand-in for SqliteLocal. The last recall sits in hippo.db's meta table, so only a store that is hippo.db keeps and reads it, on `hippoRoot`. */
+function servedLocal(store, hippoRoot) {
+    if (store.kind === 'sqlite')
+        return { ...sqliteLocal(hippoRoot), ...REFUSED_ON_A_STORE };
+    return {
+        ...REFUSED_ON_A_STORE,
+        applyOutcomeToLastRecall() {
+            throw new SqliteBlockedError(store.kind);
+        },
+        finishLastRecall: (writes) => store.finishRecall(writes),
+    };
+}
+/** Runs `run` on `ctx.store`, where a throw rejects, else on hippo.db under `ctx.hippoRoot`, where it throws. The store path never reads `hippoRoot`.
+ *  `local` runs what needs hippo.db's own handle or meta table; a served store refuses it, or does without where the write allows. */
+export function onStore(ctx, run) {
+    const { store } = ctx;
+    // No await before `run`: an add-on relies on the first port call starting inside this call.
+    const reply = store ? (async () => run(store, servedLocal(store, ctx.hippoRoot)))() : run(sqliteSyncStore(ctx.hippoRoot), sqliteLocal(ctx.hippoRoot));
+    // SAFETY: the store path is an async function's Promise and hippo.db's port calls answer values, so the Promise comes back exactly when ctx has a store, as StoreReply says.
+    return reply;
+}
+//# sourceMappingURL=on-store.js.map

package/dist/api/outcome.d.ts

@@ -1,53 +1,16 @@
 import type { Context, StoreReply } from './types.js';
-/**
- * Apply a positive/negative outcome to a list of recently-recalled memory ids.
- * Used by the MCP `hippo_outcome` tool and the HTTP `POST /v1/outcome` route.
- * Tenant-scoped: ids outside ctx.tenantId, or in someone else's personal scope, are silently skipped
- * (matches the prior MCP semantics — a stale id from another tenant doesn't
- * crash the call). Each successful outcome emits one audit_log row with
- * op='outcome' tagged with ctx.actor.subject.
- *
- * Returns `{applied, appliedIds}`. `appliedIds` is the tenant-filtered subset
- * of input ids that actually had `applyOutcome` run on them (i.e. ids found
- * in ctx.tenantId). Callers that surface the id list
- * over a multi-tenant boundary (HTTP /v1/outcome last-recall path, Python SDK)
- * MUST return `appliedIds` instead of the raw input list — otherwise the
- * non-applied (cross-tenant) ids leak to the caller.
- *
- * `opts.traceId`:
- * OPTIONAL additive opt so a programmatic caller can link this outcome to
- * the recall_traces row it judges. NOT applied unconditionally — an SDK
- * caller passing explicit ids with no preceding CLI/context recall would
- * otherwise get linked to a stale, unrelated trace. `outcomeForLastRecall`
- * supplies this automatically from `last_trace_id`; every other caller
- * (server.ts explicit-ids path, MCP hippo_outcome) omits it and gets no
- * linkage, which is correct.
- */
+/** An id outside ctx.tenantId, or in someone else's personal scope, is skipped, so a stale id never fails the call.
+ *  `appliedIds` holds only the ids applied: a caller that answers across tenants returns it, never the ids it was sent. */
 export interface OutcomeResult {
     applied: number;
     appliedIds: string[];
 }
+/** `opts.traceId` links the outcome to the recall trace it judges. Only outcomeForLastRecall sends one: explicit ids may follow no recall at all. */
 export declare function outcome<C extends Context>(ctx: C, ids: ReadonlyArray<string>, good: boolean, opts?: {
     traceId?: number;
 }): StoreReply<C, OutcomeResult>;
-/**
- * Apply an outcome to the ids most recently returned by `recall()`.
- *
- * Reads `loadIndex(ctx.hippoRoot).last_retrieval_ids` (per-hippoRoot local
- * state; not tenant-scoped at the index layer) and forwards to `outcome()`,
- * which DOES tenant-filter its read by `ctx.tenantId`. Cross-tenant
- * ids in `last_retrieval_ids` are silently skipped, matching the MCP
- * `hippo_outcome` semantics.
- *
- * **Tenant-safe response shape:** the returned `ids`
- * field contains ONLY the tenant-filtered subset that actually had outcomes
- * applied (i.e. `appliedIds` from the inner `outcome()` call). It lives in this
- * helper so every caller (CLI, HTTP /v1/outcome, MCP) inherits the contract.
- *
- * Do NOT tighten `loadIndex` with `tenantId` inside this helper — doing so
- * would break the (correct) cross-tenant-silent-skip behavior covered by
- * the test in `tests/api-outcome-for-last-recall.test.ts`.
- */
+/** The last recall's ids and its trace sit in hippo.db's meta table, which only the CLI and context write, so a store of another kind is refused.
+ *  `ids` holds only the ids applied in ctx.tenantId: the index is not tenant-scoped, so the ids read from it are never returned. */
 export interface OutcomeForLastRecallResult {
     applied: number;
     ids: string[];

package/dist/api/outcome.js

@@ -1,86 +1,21 @@
 // Outcome feedback on recalled memories.
-import { closeHippoDb } from '../db.js';
-import { openStore } from '../store/open.js';
-import { writeEntryOn } from '../store/entry-writes.js';
-import { selectEntriesByIds } from '../store/entry-reads.js';
-import { loadIndex } from '../store/index-and-stats.js';
-import { entryAfterOutcome } from '../memory.js';
-import { appendAuditEvent } from '../audit.js';
-import { recordTraceOutcome } from '../recall-trace.js';
-import { canTouchScope, personalScopeOf } from '../recall-scope.js';
-import { SqliteBlockedError } from '../db/sqlite-blocked.js';
-import { requireGroup } from '../store-port.js';
+import { personalScopeOf } from '../store/recall-scope.js';
+import { andThen, notPorted, onStore } from './on-store.js';
+/** `opts.traceId` links the outcome to the recall trace it judges. Only outcomeForLastRecall sends one: explicit ids may follow no recall at all. */
 export function outcome(ctx, ids, good, opts) {
-    const reply = ctx.store ? outcomeThroughStore(ctx, ctx.store, ids, good, opts) : outcomeOnHippoDb(ctx, ids, good, 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;
-}
-/** The rows and their audit rows commit together here; the trace link has no store method, since only the last-recall path sends one. */
-async function outcomeThroughStore(ctx, store, ids, good, opts) {
-    const entryWrites = requireGroup(store, 'entryWrites');
-    if (opts?.traceId !== undefined)
-        throw new Error('an outcome links its recall trace on hippo.db only, never through a store');
-    const appliedIds = await entryWrites.applyOutcome({ tenantId: ctx.tenantId, actor: ctx.actor.subject, ownScope: personalScopeOf(ctx.actor), ids, good });
-    return { applied: appliedIds.length, appliedIds };
-}
-function outcomeOnHippoDb(ctx, ids, good, opts) {
-    const appliedIds = [];
-    const db = openStore(ctx.hippoRoot);
-    try {
-        const live = selectEntriesByIds(db, ids, ctx.tenantId);
-        for (const id of ids) {
-            const entry = live.get(id);
-            if (!entry || !canTouchScope(ctx.actor, entry.scope ?? null))
-                continue;
-            const updated = entryAfterOutcome(entry, good);
-            writeEntryOn(db, ctx.hippoRoot, updated, { actor: ctx.actor.subject });
-            live.set(id, updated); // a repeated id builds on its first outcome, as a fresh read would
-            appendAuditEvent(db, {
-                tenantId: ctx.tenantId,
-                actor: ctx.actor.subject,
-                op: 'outcome',
-                targetId: id,
-                metadata: { good },
-            });
-            appliedIds.push(id);
-        }
-        // Link the outcome to its trace, recording only the ids actually
-        // credited (post tenant-filtering, matches appliedIds). Lives in its own
-        // append-only table so audit_log pruning can never erase training data.
-        if (opts?.traceId !== undefined && appliedIds.length > 0) {
-            recordTraceOutcome(db, {
-                traceId: opts.traceId,
-                tenantId: ctx.tenantId,
-                outcome: good ? 'positive' : 'negative',
-                memoryIds: appliedIds,
-            });
-        }
-    }
-    finally {
-        closeHippoDb(db);
-    }
-    return { applied: appliedIds.length, appliedIds };
+    return onStore(ctx, (port, local) => {
+        const entryWrites = port.entryWrites ?? notPorted(port, 'entryWrites');
+        const write = { tenantId: ctx.tenantId, actor: ctx.actor.subject, ownScope: personalScopeOf(ctx.actor), ids, good };
+        const traceId = opts?.traceId;
+        // The trace link is written on hippo.db's own handle after the commit, so a served store refuses a traceId.
+        const applied = traceId === undefined ? entryWrites.applyOutcome(write) : local.applyOutcome(write, traceId);
+        return andThen(applied, (appliedIds) => ({ applied: appliedIds.length, appliedIds }));
+    });
 }
 export function outcomeForLastRecall(ctx, good) {
-    const reply = ctx.store ? lastRecallUnderStore(ctx, ctx.store, good) : outcomeForLastRecallOnHippoDb({ ...ctx, store: undefined }, good);
-    // 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;
-}
-/** The last recall's ids and trace sit in hippo.db's meta table, which only the CLI and context write, so no other store holds them. */
-async function lastRecallUnderStore(ctx, store, good) {
-    if (store.kind !== 'sqlite')
-        throw new SqliteBlockedError(store.kind);
-    return outcomeForLastRecallOnHippoDb({ ...ctx, store: undefined }, good);
-}
-function outcomeForLastRecallOnHippoDb(ctx, good) {
-    const idx = loadIndex(ctx.hippoRoot);
-    const ids = idx.last_retrieval_ids;
-    if (ids.length === 0)
-        return { applied: 0, ids: [] };
-    // Same `loadIndex` snapshot as the ids; buildIndexFromDb already strict-parses it to a
-    // positive-integer string or null, so no trace_id=0/NaN reaches outcome().
-    const traceId = idx.last_trace_id !== null ? Number(idx.last_trace_id) : null;
-    const { applied, appliedIds } = outcome(ctx, ids, good, traceId !== null ? { traceId } : undefined);
-    return { applied, ids: appliedIds };
+    return onStore(ctx, (_port, local) => {
+        const ids = local.applyOutcomeToLastRecall({ tenantId: ctx.tenantId, actor: ctx.actor.subject, ownScope: personalScopeOf(ctx.actor) }, good);
+        return { applied: ids.length, ids };
+    });
 }
 //# sourceMappingURL=outcome.js.map

package/dist/{pilot-arm.d.ts → api/pilot-arm.d.ts}

@@ -1,4 +1,4 @@
-import { type DatabaseSyncLike } from './db.js';
+import { type DatabaseSyncLike } from '../db/index.js';
 import { type LedgerRootOpts } from './ledger-db.js';
 export type PilotArm = 'hippo' | 'holdout';
 export interface SessionArmOpts extends LedgerRootOpts {

package/dist/{pilot-arm.js → api/pilot-arm.js}

@@ -1,10 +1,12 @@
 // 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 { loadConfig } from './config.js';
-import { execWithBusyRetry, HOOK_DB_WAIT_MS, scopedBusyWait } from './db.js';
+import { loadConfig } from '../core/config.js';
+import { HOOK_DB_WAIT_MS, scopedBusyWait, withWriteScope } from '../db/index.js';
 import { ledgerRoot, withLedgerDb } from './ledger-db.js';
-import { recordTokenUse } from './token-ledger.js';
+import { errorMessage, log } from '../util/log.js';
+import { firstPilotArmHash } from '../store/token-ledger-rows.js';
+import { recordTokenUse } from '../store/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;
@@ -12,10 +14,7 @@ export function hashArm(sessionId, rateBp) {
 }
 /** 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 params = tenantId === undefined ? [sessionId] : [sessionId, tenantId];
-    // SAFETY: the SELECT names exactly this one column.
-    const row = db.prepare(`SELECT block_hash FROM token_ledger WHERE session_id = ?${tenantId === undefined ? '' : ' AND tenant_id = ?'}
-     AND surface = 'pilot' AND event = 'arm' ORDER BY id LIMIT 1`).get(...params);
+    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. */
@@ -23,29 +22,22 @@ export function readPilotArm(db, sessionId, tenantId) {
 export function ensurePilotArm(db, tenantId, sessionId, rateBp, opts = {}) {
     const hashed = hashArm(sessionId, rateBp);
     const readTenant = opts.ownTenantOnly ? tenantId : undefined;
-    let began = false;
     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;
-        execWithBusyRetry(db, 'BEGIN IMMEDIATE', scopedBusyWait() ?? HOOK_DB_WAIT_MS);
-        began = true;
-        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 });
-        }
-        db.exec('COMMIT');
-        return stored ?? hashed;
+        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 {
+    catch (err) {
         // A prompt hook must not fail on pilot bookkeeping; concurrent callers still agree on the hash arm.
-        if (began) {
-            try {
-                db.exec('ROLLBACK');
-            }
-            catch { /* keep the hash arm */ }
-        }
+        log.debug(`pilot arm not stored, using the hash arm: ${errorMessage(err)}`);
         return hashed;
     }
 }

package/dist/api/promote.d.ts

@@ -1,4 +1,4 @@
-import { type DatabaseSyncLike } from '../db.js';
+import type { ConnectorEvent } from '../store/port.js';
 import type { Context, StoreReply } from './types.js';
 /**
  * Copy a local memory into the global store. Mirrors `cmdPromote` in cli.ts:
@@ -27,21 +27,10 @@ export interface SupersedeResult {
     newId: string;
 }
 export declare function supersede<C extends Context>(ctx: C, oldId: string, newContent: string): StoreReply<C, SupersedeResult>;
-/**
- * Archive a kind='raw' memory: snapshot into raw_archive, mark archived, delete.
- *
- * `archiveRawMemory` audits the operation internally (op='archive_raw') using the
- * row's own tenant_id. We DO NOT emit a second audit event here to avoid double-
- * emitting the archive_raw op. Instead we pass `ctx.actor.subject` through as `who`,
- * and raw-archive.ts uses that for the audit row.
- */
+/** Archive a kind='raw' memory: its metadata moves to raw_archive and the row is deleted. The store writes the one archive_raw audit row, under the caller's subject. */
 export interface ArchiveRawOpts {
-    /**
-     * Connector idempotency hook. Runs inside the same
-     * SAVEPOINT as the archive — throwing rolls the archive back. Used by the
-     * Slack deletion connector to mark the deletion event seen atomically.
-     */
-    afterArchive?: (db: DatabaseSyncLike, archivedMemoryId: string) => void;
+    /** The connector event this archive answers. The store logs it in the archive's own transaction, so a redelivery finds it logged. */
+    event?: ConnectorEvent;
 }
 export interface ArchiveRawResult {
     ok: true;