hippo-memory 1.72.0 → 2.1.0

package/dist/api/context.js

@@ -4,27 +4,28 @@ import { freshActiveSnapshot, SNAPSHOT_AMBIENT_MAX_AGE_MS } from '../store/sessi
 import { estimateTokens } from '../util/token-text.js';
 import { markRetrieved, COMPACTION_MEMORY_TAG } from '../core/memory.js';
 import { isWorthSurfacing } from '../core/memory-quality.js';
-import { getGlobalRoot } from '../sharing/global-store.js';
 import { evalNow, strengthAblation } from '../core/ablation.js';
 import { dropHeldCopies } from '../util/same-text.js';
 import { BadRequestError } from '../core/api-errors.js';
-import { isSharedStore, loadConfig } from '../core/config.js';
+import { isSharedStore } from '../core/config.js';
+import { configOf } from './config-of.js';
 import { rethrowIfSqliteBlocked } from '../util/sqlite-blocked.js';
-import { errorMessage, log } from '../util/log.js';
-import { resolveProjectIdentity, classifyOriginProject, isGlobalStoreRoot, isInitialized, projectId, projectNames, } from '../core/project-identity.js';
+import { errorMessage, log, errorFields } from '../util/log.js';
+import { resolveProjectIdentity, classifyOriginProject, projectId, projectNames, } from '../core/project-identity.js';
 import { promptTokens } from '../core/prompt-recall.js';
 import { detectSecret } from '../util/secret-detect.js';
 import { isSessionDigestRow } from '../core/session-digest-row.js';
 import { addAmbientTallies, ambientStateFromTallies } from '../core/ambient.js';
-import { requireGroup, sqliteStore, storeFor } from '../store/index.js';
+import { hasGroup } from '../store/index.js';
 import { passesScopeFilterForRecall, assertScopeRequestAllowed, personalScopeOf } from '../core/recall-scope.js';
 import { finiteOr, selectBySearch, selectPinned, selectStrongest, } from './context-select.js';
-import { andThen, onStore } from './on-store.js';
-import { strengthenOf } from './recall-record.js';
+import { strengthenOf } from './recall/finish.js';
+import { tokenPurse } from './recall/render.js';
 import { ownerOrSubject } from './types.js';
 export { oneCopyPerMemory } from './context-select.js';
-/** The single ambient-injection admission policy, shared by getContext and the CLI ambient-state summary so they cannot drift.
- * Secret veto is unconditional (flagged rows inject only in their own project); private scopes need `exactScope`, other projects `includeCrossProject`. */
+/** The single ambient-injection admission policy, shared by getContext and the CLI ambient-state summary so they cannot
+ * drift. Secret veto is unconditional (flagged rows inject only in their own project); private scopes need
+ * `exactScope`, other projects `includeCrossProject`. */
 function ambientAdmitEntry(e, currentProject, includeCrossProject, exactScope, own) {
     if (!ambientSecretAdmit(e, currentProject))
         return false;
@@ -34,7 +35,8 @@ function ambientAdmitEntry(e, currentProject, includeCrossProject, exactScope, o
         return true;
     return classifyOriginProject(e.origin_project, currentProject) !== 'cross-project';
 }
-/** The secret half of the ambient policy alone, for callers with their own scope rule: a flagged row is admitted only inside its owning project. */
+/** The secret half of the ambient policy alone, for callers with their own scope rule: a flagged row is admitted only
+ * inside its owning project. */
 export function ambientSecretAdmit(e, currentProject) {
     if (!detectSecret(e).flagged)
         return true;
@@ -45,16 +47,18 @@ export function ambientSecretAdmit(e, currentProject) {
 }
 /** Tokens a context block may use when the caller sets no budget; the hook command and the CLI default match it. */
 export const DEFAULT_CONTEXT_BUDGET = 1500;
+// The plan's query when the caller gave none: context then ranks by strength instead of searching.
+export const NO_QUERY = '*';
 /** Most rows per store a no-query context reads; past it, ranking and ambientState see the strongest by decay. */
 const CONTEXT_CANDIDATE_CAP = 2000;
 /** A store's base search and context reads; a store without the group throws StoreNotPortedError. */
 function sourceOf(store) {
-    return { store, reads: requireGroup(store, 'contextReads') };
+    return { store, reads: store.contextReads };
 }
 // The pinned-only branch needs pins and recent-N candidates, not the corpus.
 async function loadAmbientEntries(source, tenantId, options) {
     const { pinnedOnly, recent, admit, recheck, window, recall, onQualityDrop } = options;
-    const ownTenant = (e) => e.tenantId === tenantId;
+    const ownTenant = (e) => e.tenant_id === tenantId;
     if (!pinnedOnly) {
         const rows = 'query' in window
             ? await source.store.searchRecallEntries(window.query, {
@@ -79,30 +83,37 @@ async function loadAmbientEntries(source, tenantId, options) {
         onQualityDrop?.(e);
         return false;
     };
-    const loaded = await source.reads.ambientCandidates(tenantId, { recentNeeded: recent.needed, admit: admitAmbient, recall, origins: recent.origins });
-    // Pins and recent rows reach core only through the store's own call to admit, so core applies it again with the tenant.
+    const loaded = await source.reads.ambientCandidates(tenantId, {
+        recentNeeded: recent.needed,
+        admit: admitAmbient,
+        recall,
+        origins: recent.origins,
+    });
+    // Pins and recent rows reach core only through the store's own
+    // call to admit, so core applies it again with the tenant.
     const entries = loaded.entries.filter((e) => ownTenant(e) && recheck(e));
     return loaded.recall ? { entries, recall: loaded.recall.filter(ownTenant) } : { entries };
 }
-/** Assembles a budget-bounded, tenant-scoped context bundle; mutates `last_retrieval_ids` and emits a 'recall' audit row for non-pinned, non-'*' queries.
- * Returns an empty result when there are no memories, snapshot, handoff or recent events. CLI rendering stays in `cli.ts`. */
+/** Assembles a budget-bounded, tenant-scoped context bundle; mutates `last_retrieval_ids` and emits a 'recall' audit
+ * row for non-pinned, non-'*' queries. Returns an empty result when there are no memories, snapshot, handoff or recent
+ * events. CLI rendering stays in `cli.ts`. */
 export async function getContext(ctx, opts = {}) {
     const budget = opts.budget ?? DEFAULT_CONTEXT_BUDGET;
     assertScopeRequestAllowed(ctx.actor, opts.exactScope);
     if (budget <= 0) {
         return { entries: [], tokens: 0 };
     }
-    const plan = planContext(ctx, opts, sourceOf(storeFor(ctx)));
+    const plan = planContext(ctx, opts, sourceOf(ctx.store));
     const sections = await loadTaskSections(ctx, opts, plan, openBlockBudget(plan, opts, budget));
     const admission = ambientAdmission(opts, plan, sections.shownHandoff);
     const pools = await loadPools(ctx, plan, admission, promptRecallRequest(opts, plan));
     const noSections = !sections.shownSnapshot && !sections.shownHandoff && sections.shownEvents.length === 0;
-    if (!plan.promptRecallPending && pools.local.entries.length === 0 && pools.global.entries.length === 0 && noSections) {
+    if (nothingToInject(plan, pools, noSections)) {
         return { entries: [], tokens: 0 };
     }
     const picked = plan.pinnedOnly
         ? selectPinned(opts, plan, sections.left, pools, admission)
-        : plan.query === '*'
+        : plan.query === NO_QUERY
             ? selectStrongest(plan, sections.left, pools)
             : await selectBySearch(ctx, plan, sections.left, pools, admission);
     if (picked === null) {
@@ -129,8 +140,12 @@ export async function getContext(ctx, opts = {}) {
         ambientState: recorded.ambientState,
     };
 }
+function nothingToInject(plan, pools, noSections) {
+    return (!plan.promptRecallPending && pools.local.entries.length === 0 && pools.global.entries.length === 0 && noSections);
+}
 const isolationWarned = new Set();
-/** A laptop config copied onto a team store must not open every member's rows to every prompt, so the flag loses there. */
+/** A laptop config copied onto a team store must not open every
+ * member's rows to every prompt, so the flag loses there. */
 function warnIsolationIgnored(hippoRoot) {
     if (isolationWarned.has(hippoRoot))
         return;
@@ -139,35 +154,55 @@ function warnIsolationIgnored(hippoRoot) {
 }
 /** Which stores this read can draw on, and what kind the primary one is. */
 function storesInReach(ctx, opts, local) {
-    const other = local.store.kind !== 'sqlite' ? local.store : undefined;
-    // Global memories do not establish a project boundary for task state.
-    const hasLocal = other !== undefined || isInitialized(ctx.hippoRoot);
-    const globalRoot = getGlobalRoot();
+    const other = hasGroup(local.store, 'localFiles') ? undefined : local.store;
+    // No reach means an integrator's own store: one project, no global store beside it.
+    const reach = ctx.reach ?? { hasLocal: true, isGlobal: false, shared: isSharedStore(ctx.hippoRoot) };
     // The store's own flag counts too, so no surface can read a shared store as its owner.
-    const sharedStore = opts.sharedStore === true || isSharedStore(ctx.hippoRoot);
+    const sharedStore = opts.sharedStore === true || reach.shared;
     // A store serving many people is not its operator's, so the operator's own global store stays out.
-    const hasGlobal = !sharedStore && other === undefined && isInitialized(globalRoot);
-    const primaryIsGlobal = isGlobalStoreRoot(ctx.hippoRoot);
-    return { other, hasLocal, globalRoot, sharedStore, hasGlobal, primaryIsGlobal };
+    const hasGlobal = !sharedStore && other === undefined && reach.global !== undefined;
+    // Global memories do not establish a project boundary for task state.
+    return {
+        other,
+        hasLocal: other !== undefined || reach.hasLocal,
+        globalRoot: reach.global?.root ?? '',
+        sharedStore,
+        hasGlobal,
+        primaryIsGlobal: reach.isGlobal,
+    };
+}
+/** The operator's global store, which planContext proved present before it set hasGlobal. */
+function globalSource(ctx) {
+    const global = ctx.reach?.global;
+    if (global === undefined)
+        throw new Error('hasGlobal without a global store in reach');
+    return sourceOf(global.store);
 }
 /** Prices one entry against the budget: the caller's cost model when it gave one, else a token estimate. */
 function entryPricer(cost, currentProject) {
     return (entry, isGlobal, promptRecall) => cost
-        ? cost.entry({ entry, isGlobal, promptRecall, origin: entry.origin_project ?? null, category: classifyOriginProject(entry.origin_project, currentProject) })
+        ? cost.entry({
+            entry,
+            isGlobal,
+            promptRecall,
+            origin: entry.origin_project ?? null,
+            category: classifyOriginProject(entry.origin_project, currentProject),
+        })
         : estimateTokens(entry.content);
 }
 function planContext(ctx, opts, local) {
     const pinnedOnly = opts.pinnedOnly === true;
     const { other, hasLocal, globalRoot, sharedStore, hasGlobal, primaryIsGlobal } = storesInReach(ctx, opts, local);
-    const query = (opts.q ?? '').trim() || '*';
+    const query = (opts.q ?? '').trim() || NO_QUERY;
     // opts.scope is only the tag boost, opts.exactScope the envelope request; other-project memories are
     // excluded unless the caller asks for them (crossProject) or isolation is disabled.
-    const config = loadConfig(ctx.hippoRoot);
+    const config = configOf(ctx);
     const isolationEnabled = config.contextProjectIsolation !== false;
     const currentProject = opts.currentProject ?? resolveProjectIdentity(process.cwd());
     // A caller with no project reads every row as its own; on a shared store those rows are other people's.
-    if (sharedStore && projectId(currentProject).trim() === '')
-        throw new BadRequestError('a shared store needs the caller\'s project');
+    if (sharedStore && projectId(currentProject).trim() === '') {
+        throw new BadRequestError("a shared store needs the caller's project");
+    }
     if (sharedStore && !isolationEnabled)
         warnIsolationIgnored(ctx.hippoRoot);
     const includeCrossProject = opts.crossProject === true || (!isolationEnabled && !sharedStore);
@@ -208,14 +243,22 @@ function promptRecallRequest(opts, plan) {
         ? Array.from(promptTokens(opts.prompt ?? ''))
         : [];
     return promptRecallTerms.length > 0
-        ? { terms: promptRecallTerms, limit: Math.floor(finiteOr(pinnedInject.promptRecallCandidates, 100, 1)), ownScope: plan.ownScope }
+        ? {
+            terms: promptRecallTerms,
+            limit: Math.floor(finiteOr(pinnedInject.promptRecallCandidates, 100, 1)),
+            ownScope: plan.ownScope,
+        }
         : undefined;
 }
 /** Reports the block's facts to the observer and returns the budget left after the fixed headers. */
 function openBlockBudget(plan, opts, budget) {
     const { config, cost, obs, pinnedOnly, promptRecallPending } = plan;
     const blockBudget = pinnedOnly && opts.budget === undefined ? config.pinnedInject.budget : budget;
-    obs?.facts({ projectName: projectId(plan.currentProject), budgetTokens: blockBudget, promptRecall: promptRecallPending });
+    obs?.facts({
+        projectName: projectId(plan.currentProject),
+        budgetTokens: blockBudget,
+        promptRecall: promptRecallPending,
+    });
     if (pinnedOnly && !config.pinnedInject.enabled)
         obs?.disabled();
     if (!pinnedOnly)
@@ -234,7 +277,8 @@ async function loadRawTaskState(ctx, opts, plan) {
     if (!plan.hasLocalTaskState)
         return NO_TASK_STATE;
     const { store, reads } = plan.local;
-    // On a shared store task state is one person's, keyed by owner and project so it follows them into their next session.
+    // On a shared store task state is one person's, keyed by owner
+    // and project so it follows them into their next session.
     const key = plan.sharedStore
         ? { owner: ownerOrSubject(ctx.actor), project: projectNames(plan.currentProject) }
         : null;
@@ -245,18 +289,17 @@ async function loadRawTaskState(ctx, opts, plan) {
     if (snapshot?.session_id)
         return { snapshot, handoff: block.sessionHandoff, events: block.recentSessionEvents };
     // An unfinished handoff's scope is admitted in the read, so a newer denied row can't hide an older eligible one.
-    return { snapshot, handoff: await reads.unfinishedHandoff(ctx.tenantId, SNAPSHOT_AMBIENT_MAX_AGE_MS, key), events: [] };
+    return {
+        snapshot,
+        handoff: await reads.unfinishedHandoff(ctx.tenantId, SNAPSHOT_AMBIENT_MAX_AGE_MS, key),
+        events: [],
+    };
 }
-// Sections print ahead of the memories, so they are paid first; one that does not fit is dropped, as an oversize entry is.
+// Sections print ahead of the memories, so they are paid first;
+// one that does not fit is dropped, as an oversize entry is.
 async function loadTaskSections(ctx, opts, plan, startLeft) {
     const { exactScope, ownScope, cost } = plan;
-    let left = startLeft;
-    const pays = (tokens) => {
-        if (tokens > left)
-            return false;
-        left -= tokens;
-        return true;
-    };
+    const { pays, left } = tokenPurse(startLeft);
     const rowScope = (r) => r?.scope ?? null;
     const raw = await loadRawTaskState(ctx, opts, plan);
     // The same envelope rule ambientAdmitEntry applies to memory rows.
@@ -266,15 +309,20 @@ async function loadTaskSections(ctx, opts, plan, startLeft) {
     const shownSnapshot = activeSnapshot && (!cost || pays(cost.snapshot(activeSnapshot))) ? activeSnapshot : null;
     const shownHandoff = sessionHandoff && (!cost || pays(cost.handoff(sessionHandoff))) ? sessionHandoff : null;
     const shownEvents = recentSessionEvents.length > 0 && (!cost || pays(cost.trail(recentSessionEvents))) ? recentSessionEvents : [];
-    plan.obs?.sections(Number(shownSnapshot !== null) + Number(shownHandoff !== null) + Number(shownEvents.length > 0), Number(activeSnapshot !== shownSnapshot) + Number(sessionHandoff !== shownHandoff) + Number(recentSessionEvents.length !== shownEvents.length));
-    return { activeSnapshot, shownSnapshot, shownHandoff, shownEvents, left };
+    plan.obs?.sections(Number(shownSnapshot !== null) + Number(shownHandoff !== null) + Number(shownEvents.length > 0), Number(activeSnapshot !== shownSnapshot) +
+        Number(sessionHandoff !== shownHandoff) +
+        Number(recentSessionEvents.length !== shownEvents.length));
+    return { activeSnapshot, shownSnapshot, shownHandoff, shownEvents, left: left() };
 }
 function ambientAdmission(opts, plan, shownHandoff) {
     const transcriptHandoffSession = shownHandoff?.evidence?.derivedFrom === 'transcript' ? shownHandoff.sessionId : null;
     const ambientAdmit = (e) => {
         // A printed handoff already carries the session's closing message, which its digest would print a second time.
-        if (transcriptHandoffSession !== null && e.source_session_id === transcriptHandoffSession && isSessionDigestRow(e))
+        if (transcriptHandoffSession !== null &&
+            e.source_session_id === transcriptHandoffSession &&
+            isSessionDigestRow(e)) {
             return false;
+        }
         return ambientAdmitEntry(e, plan.currentProject, plan.includeCrossProject, plan.exactScope, plan.ownScope);
     };
     const ownSessionId = opts.currentSessionId || '';
@@ -282,13 +330,15 @@ function ambientAdmission(opts, plan, shownHandoff) {
     const isOwnCompactionItem = (e) => ownSessionId !== '' &&
         e.source_session_id === ownSessionId &&
         e.tags.includes(COMPACTION_MEMORY_TAG);
-    // Superseded rows never inject; which rows reach ambientAdmitEntry matters because it regex-scans content for secrets.
+    // Superseded rows never inject; which rows reach ambientAdmitEntry
+    // matters because it regex-scans content for secrets.
     const admit = (e) => !e.superseded_by && !isOwnCompactionItem(e) && ambientAdmit(e);
     // The two-store search has always ranked a session's own compaction items; only the local search drops them.
     const bothStoresAdmit = (e) => !e.superseded_by && ambientAdmit(e);
     return { ambientAdmit, admit, bothStoresAdmit };
 }
-/** Origins the recent backfill may read past its first window; on a shared store, only the caller's own project rows. */
+/** Origins the recent backfill may read past its first window;
+ * on a shared store, only the caller's own project rows. */
 function recentOrigins(plan) {
     if (plan.sharedStore)
         return { names: projectNames(plan.currentProject).filter((n) => n !== ''), userGlobal: false };
@@ -297,7 +347,7 @@ function recentOrigins(plan) {
 async function loadPools(ctx, plan, admission, recallRequest) {
     const { obs, pinnedOnly, primaryIsGlobal, hasGlobal, exactScope, ownScope } = plan;
     const recent = { needed: plan.includeRecent, origins: recentOrigins(plan) };
-    const searches = plan.query !== '*' && !pinnedOnly;
+    const searches = plan.query !== NO_QUERY && !pinnedOnly;
     const searchesBoth = searches && hasGlobal && !primaryIsGlobal;
     const poolAdmit = searchesBoth ? admission.bothStoresAdmit : admission.admit;
     const loadAdmit = obs ? obs.watchAdmit(poolAdmit) : poolAdmit;
@@ -318,7 +368,10 @@ async function loadPools(ctx, plan, admission, recallRequest) {
         ? await loadAmbientEntries(plan.local, ctx.tenantId, { ...read, onQualityDrop: qualityDrop(primaryIsGlobal) })
         : { entries: [] };
     const global = hasGlobal && !primaryIsGlobal
-        ? await loadAmbientEntries(sourceOf(sqliteStore(plan.globalRoot)), ctx.tenantId, { ...read, onQualityDrop: qualityDrop(true) })
+        ? await loadAmbientEntries(globalSource(ctx), ctx.tenantId, {
+            ...read,
+            onQualityDrop: qualityDrop(true),
+        })
         : { entries: [] };
     return { local, global };
 }
@@ -327,7 +380,7 @@ function finalizeSelection(picked, plan) {
     const { obs } = plan;
     // Ranking reports nothing itself, so its results are offered here and the cuts below can name what they drop.
     if (!plan.pinnedOnly && obs) {
-        const pool = plan.query === '*' ? 'strength' : 'search';
+        const pool = plan.query === NO_QUERY ? 'strength' : 'search';
         obs.offer(picked.filter((r) => r.isGlobal !== true).map((r) => r.entry), false, pool);
         obs.offer(picked.filter((r) => r.isGlobal === true).map((r) => r.entry), true, pool);
     }
@@ -337,11 +390,13 @@ function finalizeSelection(picked, plan) {
         obs?.dropMissing(selected.map((r) => r.entry), cut.map((r) => r.entry), 'limit', 'limit');
         selected = cut;
     }
-    const heldDropped = dropHeldCopies(selected, (r) => r.entry); // after the last cut, so a merged row that was cut hides nothing
+    // After the last cut, so a merged row that was cut hides nothing.
+    const heldDropped = dropHeldCopies(selected, (r) => r.entry);
     obs?.dropMissing(selected.map((r) => r.entry), heldDropped.map((r) => r.entry), 'limit', 'duplicate');
     selected = heldDropped;
     const tokens = selected.reduce((sum, r) => sum + r.tokens, 0);
-    // Every returned entry carries its origin and how it relates to the active project, so renderers can mark cross-project rows.
+    // Every returned entry carries its origin and how it relates to
+    // the active project, so renderers can mark cross-project rows.
     selected = selected.map((r) => ({
         ...r,
         origin: r.entry.origin_project ?? null,
@@ -363,11 +418,11 @@ async function traceEmptyContext(ctx, opts, plan) {
     };
     // The empty reply is already decided, so a lost trace is logged and the call still answers.
     try {
-        await onStore(ctx, (port) => port.finishRecall({ goalLog: [], audit: [], trace }));
+        await ctx.store.finishRecall({ goalLog: [], audit: [], trace });
     }
     catch (error) {
         rethrowIfSqliteBlocked(error);
-        log.error(`recall trace write failed: ${errorMessage(error)}`);
+        log.error(`recall trace write failed: ${errorMessage(error)}`, errorFields(error));
     }
 }
 /** Strengthens and marks the returned rows, then writes the trace and index together. */
@@ -387,11 +442,13 @@ async function recordRetrieval(ctx, opts, plan, selected, activeSnapshot) {
         })),
     };
     const writes = { goalLog: [], audit: [], trace, strengthen: strengthenOf(ctx, retrievedIds) };
-    // hippo.db keeps the ids as its last recall, which feeds only outcomeForLastRecall, and it alone reads a second root.
-    await onStore(ctx, (port, local) => andThen(local.finishLastRecall(writes, plan.hasGlobal ? plan.globalRoot : undefined), (traceId) => {
-        plan.obs?.traced(traceId);
-        return port.bumpRecallStats(selected.length);
-    }));
+    // The last recall feeds only outcomeForLastRecall, so a store that keeps none still finishes the recall without one.
+    const store = ctx.store;
+    const traceId = store.lastRecall
+        ? await store.lastRecall.finishRecall(writes, plan.hasGlobal ? plan.globalRoot : undefined)
+        : await store.finishRecall(writes).then(() => null);
+    plan.obs?.traced(traceId);
+    await store.bumpRecallStats(selected.length);
     // Replace selectedItems entries with markRetrieved-updated copies so
     // the returned ContextResult reflects post-recall state.
     const items = selected.map((s) => ({
@@ -411,7 +468,7 @@ async function readAmbientState(ctx, plan) {
     };
     const sources = [
         ...(plan.hasLocal ? [plan.local.reads] : []),
-        ...(plan.hasGlobal && !plan.primaryIsGlobal ? [sourceOf(sqliteStore(plan.globalRoot)).reads] : []),
+        ...(plan.hasGlobal && !plan.primaryIsGlobal ? [globalSource(ctx).reads] : []),
     ];
     const tallies = [];
     for (const reads of sources)

package/dist/api/continuity.d.ts

@@ -1,47 +1,50 @@
 import type { HandoffOutcome, SessionHandoff } from '../core/handoff.js';
 import type { SessionEvent, TaskSnapshot } from '../store/rows.js';
-import { appendSessionEvent, listSessionEvents, saveActiveTaskSnapshot } from '../store/sessions.js';
-import { wmClear, wmFlush, wmPush, wmRead, type WorkingMemoryItem } from '../store/working-memory.js';
-import type { Context } from './types.js';
+import type { SessionEventInput, SnapshotInput } from '../store/sessions.js';
+import type { Sessions } from '../store/index.js';
+import type { WorkingMemoryItem } from '../store/working-memory.js';
+import type { ContextWith } from './types.js';
+type Ctx = ContextWith<'sessions'>;
 /** What a snapshot save carries. */
-export type SnapshotSaveInput = Parameters<typeof saveActiveTaskSnapshot>[2];
+export type SnapshotSaveInput = SnapshotInput;
 /** What a session event append carries. */
-export type SessionEventAppendInput = Parameters<typeof appendSessionEvent>[2];
+export type SessionEventAppendInput = SessionEventInput;
 /** What a session event listing filters on. */
-export type SessionEventListOpts = NonNullable<Parameters<typeof listSessionEvents>[2]>;
+export type SessionEventListOpts = Parameters<Sessions['listEvents']>[1];
 /** Save the caller's active task snapshot. */
-export declare function snapshotSave(ctx: Context, input: SnapshotSaveInput): TaskSnapshot;
+export declare function snapshotSave(ctx: Ctx, input: SnapshotSaveInput): Promise<TaskSnapshot>;
 /** Clear the caller's active task snapshot; false when there was none. */
-export declare function snapshotClear(ctx: Context, status: string): boolean;
+export declare function snapshotClear(ctx: Ctx, status: string): Promise<boolean>;
 /** The caller's active task snapshot, or null. */
-export declare function snapshotLoad(ctx: Context): TaskSnapshot | null;
+export declare function snapshotLoad(ctx: Ctx): Promise<TaskSnapshot | null>;
 /** Append a session event in the caller's tenant. */
-export declare function sessionEventAppend(ctx: Context, event: SessionEventAppendInput): SessionEvent;
+export declare function sessionEventAppend(ctx: Ctx, event: SessionEventAppendInput): Promise<SessionEvent>;
 /** List the caller's session events. */
-export declare function sessionEventList(ctx: Context, opts: SessionEventListOpts): SessionEvent[];
+export declare function sessionEventList(ctx: Ctx, opts: SessionEventListOpts): Promise<SessionEvent[]>;
 export interface LatestContinuity {
     snapshot: TaskSnapshot | null;
     events: SessionEvent[];
 }
 /** The active snapshot plus recent events for `sessionId`, falling back to the snapshot's own session. */
-export declare function continuityLatest(ctx: Context, opts: {
+export declare function continuityLatest(ctx: Ctx, opts: {
     sessionId?: string;
     limit: number;
-}): LatestContinuity;
+}): Promise<LatestContinuity>;
 /** Stamp the outcome on the caller's handoff for `sessionId`; returns the rows stamped. */
-export declare function handoffStampOutcome(ctx: Context, sessionId: string, outcome: HandoffOutcome): number;
+export declare function handoffStampOutcome(ctx: Ctx, sessionId: string, outcome: HandoffOutcome): Promise<number>;
 /** Save a session handoff in the caller's tenant. */
-export declare function handoffSave(ctx: Context, handoff: Omit<SessionHandoff, 'updatedAt'>): SessionHandoff;
+export declare function handoffSave(ctx: Ctx, handoff: Omit<SessionHandoff, 'updatedAt'>): Promise<SessionHandoff>;
 /** The caller's latest handoff, optionally for one session. */
-export declare function handoffLatest(ctx: Context, sessionId?: string): SessionHandoff | null;
+export declare function handoffLatest(ctx: Ctx, sessionId?: string): Promise<SessionHandoff | null>;
 /** The caller's handoff by id, or null. */
-export declare function handoffById(ctx: Context, id: number): SessionHandoff | null;
+export declare function handoffById(ctx: Ctx, id: number): Promise<SessionHandoff | null>;
 /** Push a working memory entry in the caller's tenant; returns its row id. */
-export declare function workingMemoryPush(ctx: Context, opts: Omit<Parameters<typeof wmPush>[1], 'tenantId'>): number;
+export declare function workingMemoryPush(ctx: Ctx, opts: Parameters<Sessions['pushWorkingMemory']>[1]): Promise<number>;
 /** The caller's working memory entries, most important first. */
-export declare function workingMemoryRead(ctx: Context, opts: Omit<NonNullable<Parameters<typeof wmRead>[1]>, 'tenantId'>): WorkingMemoryItem[];
+export declare function workingMemoryRead(ctx: Ctx, opts: Parameters<Sessions['readWorkingMemory']>[1]): Promise<WorkingMemoryItem[]>;
 /** Delete the caller's working memory entries; returns the count. */
-export declare function workingMemoryClear(ctx: Context, opts: Omit<NonNullable<Parameters<typeof wmClear>[1]>, 'tenantId'>): number;
+export declare function workingMemoryClear(ctx: Ctx, opts: Parameters<Sessions['clearWorkingMemory']>[1]): Promise<number>;
 /** Flush the caller's working memory at session end; returns the count. */
-export declare function workingMemoryFlush(ctx: Context, opts: Omit<NonNullable<Parameters<typeof wmFlush>[1]>, 'tenantId'>): number;
+export declare function workingMemoryFlush(ctx: Ctx, opts: Parameters<Sessions['clearWorkingMemory']>[1]): Promise<number>;
+export {};
 //# sourceMappingURL=continuity.d.ts.map

package/dist/api/continuity.js

@@ -1,66 +1,64 @@
 // Where-you-left-off ops: task snapshot, session events, handoffs and working memory.
-import { appendSessionEvent, clearActiveTaskSnapshot, listSessionEvents, loadActiveTaskSnapshot, saveActiveTaskSnapshot, } from '../store/sessions.js';
-import { loadHandoffById, loadLatestHandoff, saveSessionHandoff, stampHandoffOutcome } from '../store/handoffs.js';
-import { wmClear, wmFlush, wmPush, wmRead } from '../store/working-memory.js';
 /** Save the caller's active task snapshot. */
 export function snapshotSave(ctx, input) {
-    return saveActiveTaskSnapshot(ctx.hippoRoot, ctx.tenantId, input);
+    return ctx.store.sessions.saveSnapshot(ctx.tenantId, input, null);
 }
 /** Clear the caller's active task snapshot; false when there was none. */
 export function snapshotClear(ctx, status) {
-    return clearActiveTaskSnapshot(ctx.hippoRoot, ctx.tenantId, status);
+    return ctx.store.sessions.clearSnapshot(ctx.tenantId, status);
 }
 /** The caller's active task snapshot, or null. */
 export function snapshotLoad(ctx) {
-    return loadActiveTaskSnapshot(ctx.hippoRoot, ctx.tenantId);
+    return ctx.store.sessions.loadSnapshot(ctx.tenantId, null);
 }
 /** Append a session event in the caller's tenant. */
 export function sessionEventAppend(ctx, event) {
-    return appendSessionEvent(ctx.hippoRoot, ctx.tenantId, event);
+    return ctx.store.sessions.appendEvent(ctx.tenantId, event);
 }
 /** List the caller's session events. */
 export function sessionEventList(ctx, opts) {
-    return listSessionEvents(ctx.hippoRoot, ctx.tenantId, opts);
+    return ctx.store.sessions.listEvents(ctx.tenantId, opts);
 }
 /** The active snapshot plus recent events for `sessionId`, falling back to the snapshot's own session. */
-export function continuityLatest(ctx, opts) {
-    const snapshot = loadActiveTaskSnapshot(ctx.hippoRoot, ctx.tenantId);
-    const events = listSessionEvents(ctx.hippoRoot, ctx.tenantId, {
-        session_id: opts.sessionId || snapshot?.session_id || undefined,
+export async function continuityLatest(ctx, opts) {
+    const { sessions } = ctx.store;
+    const snapshot = await sessions.loadSnapshot(ctx.tenantId, null);
+    const events = await sessions.listEvents(ctx.tenantId, {
+        sessionId: opts.sessionId || snapshot?.session_id || undefined,
         limit: opts.limit,
     });
     return { snapshot, events };
 }
 /** Stamp the outcome on the caller's handoff for `sessionId`; returns the rows stamped. */
 export function handoffStampOutcome(ctx, sessionId, outcome) {
-    return stampHandoffOutcome(ctx.hippoRoot, ctx.tenantId, sessionId, outcome);
+    return ctx.store.sessions.stampHandoffOutcome(ctx.tenantId, sessionId, outcome);
 }
 /** Save a session handoff in the caller's tenant. */
 export function handoffSave(ctx, handoff) {
-    return saveSessionHandoff(ctx.hippoRoot, ctx.tenantId, handoff);
+    return ctx.store.sessions.saveHandoff(ctx.tenantId, handoff, null);
 }
 /** The caller's latest handoff, optionally for one session. */
 export function handoffLatest(ctx, sessionId) {
-    return loadLatestHandoff(ctx.hippoRoot, ctx.tenantId, sessionId);
+    return ctx.store.sessions.latestHandoff(ctx.tenantId, sessionId ?? null, {}, null);
 }
 /** The caller's handoff by id, or null. */
 export function handoffById(ctx, id) {
-    return loadHandoffById(ctx.hippoRoot, ctx.tenantId, id);
+    return ctx.store.sessions.handoffById(ctx.tenantId, id);
 }
 /** Push a working memory entry in the caller's tenant; returns its row id. */
 export function workingMemoryPush(ctx, opts) {
-    return wmPush(ctx.hippoRoot, { ...opts, tenantId: ctx.tenantId });
+    return ctx.store.sessions.pushWorkingMemory(ctx.tenantId, opts);
 }
 /** The caller's working memory entries, most important first. */
 export function workingMemoryRead(ctx, opts) {
-    return wmRead(ctx.hippoRoot, { ...opts, tenantId: ctx.tenantId });
+    return ctx.store.sessions.readWorkingMemory(ctx.tenantId, opts);
 }
 /** Delete the caller's working memory entries; returns the count. */
 export function workingMemoryClear(ctx, opts) {
-    return wmClear(ctx.hippoRoot, { ...opts, tenantId: ctx.tenantId });
+    return ctx.store.sessions.clearWorkingMemory(ctx.tenantId, opts);
 }
 /** Flush the caller's working memory at session end; returns the count. */
 export function workingMemoryFlush(ctx, opts) {
-    return wmFlush(ctx.hippoRoot, { ...opts, tenantId: ctx.tenantId });
+    return ctx.store.sessions.clearWorkingMemory(ctx.tenantId, opts);
 }
 //# sourceMappingURL=continuity.js.map

package/dist/api/correction-latency.d.ts

@@ -18,7 +18,9 @@ export interface CorrectionLatencyReport {
     maxMs: number | null;
     pairs: CorrectionPair[];
 }
-/** Correction latency = `new.created` minus the observation time (the extracted-from row's `created`, else `new.created`).
+/**
+ * Correction latency = `new.created` minus the observation time (the extracted-from row's `created`, else
+ * `new.created`).
  * Manual supersedes have latency 0 and are excluded from percentiles so they do not mask real lag. */
 export declare function buildCorrectionLatency(entries: MemoryEntry[]): CorrectionLatencyReport;
 //# sourceMappingURL=correction-latency.d.ts.map

package/dist/api/correction-latency.js

@@ -10,7 +10,9 @@ function percentile(sorted, q) {
         return sorted[lo];
     return sorted[lo] + (sorted[hi] - sorted[lo]) * (idx - lo);
 }
-/** Correction latency = `new.created` minus the observation time (the extracted-from row's `created`, else `new.created`).
+/**
+ * Correction latency = `new.created` minus the observation time (the extracted-from row's `created`, else
+ * `new.created`).
  * Manual supersedes have latency 0 and are excluded from percentiles so they do not mask real lag. */
 export function buildCorrectionLatency(entries) {
     const byId = new Map();

package/dist/api/error-reply.d.ts

@@ -3,6 +3,9 @@ export interface ApiErrorReply {
     status: number;
     message: string;
 }
-/** Maps by class so rewording a message never moves a status; an untyped error is a 500 whose text stays in the server log. */
+/**
+ * Maps by class so rewording a message never moves a status; an untyped error is a 500 whose text stays in the server
+ * log.
+ */
 export declare function mapApiError<E>(err: E): ApiErrorReply;
 //# sourceMappingURL=error-reply.d.ts.map

package/dist/api/error-reply.js

@@ -1,9 +1,18 @@
-// The one error-to-reply map the HTTP server and the MCP transports share, so a status never depends on which front end caught the error.
+// The one error-to-reply map the HTTP server and the MCP transports share, so a status never depends on which front end
+// caught the error.
 import { ApiError } from '../core/api-errors.js';
-import { BodyTimeoutError, BodyTooLargeError, HttpError, INTERNAL_ERROR_MESSAGE, STORE_NOT_PORTED_MESSAGE } from '../util/http-util.js';
+import { BodyTimeoutError, BodyTooLargeError, HttpError, INTERNAL_ERROR_MESSAGE, STORE_NOT_PORTED_MESSAGE, } from '../util/http-util.js';
 import { SqliteBlockedError } from '../util/sqlite-blocked.js';
-/** Maps by class so rewording a message never moves a status; an untyped error is a 500 whose text stays in the server log. */
+import { STORE_BUSY_MESSAGE } from '../store/port.js';
+import { isStoreBusy } from './busy.js';
+/**
+ * Maps by class so rewording a message never moves a status; an untyped error is a 500 whose text stays in the server
+ * log.
+ */
 export function mapApiError(err) {
+    // A held lock is a retryable 503 in every store, so the surfaces need not know SQLite's busy codes.
+    if (isStoreBusy(err))
+        return { status: 503, message: STORE_BUSY_MESSAGE };
     // An add-on can build an HttpError from any number, and writeHead throws on one outside 100-999.
     if (err instanceof HttpError && !(Number.isInteger(err.status) && err.status >= 100 && err.status <= 999)) {
         return { status: 500, message: INTERNAL_ERROR_MESSAGE };