hippo-memory 2.0.0 → 2.1.0

package/dist/store/sqlite/error-codec.js

@@ -9,13 +9,31 @@ import { errorMessage, log } from '../../util/log.js';
 import { ScopeForbiddenError } from '../../core/recall-scope.js';
 import { RejectedValueError } from '../../core/api-errors.js';
 import { OtherStoreFolderError, SqliteBlockedError, StoreNotPortedError } from '../../util/sqlite-blocked.js';
-// Every class the server maps by, at or below the store layer. Abstract ApiError is absent: only its four subclasses are thrown.
+// Every class the server maps by, at or below the store layer. Abstract ApiError is absent: only its four subclasses
+// are thrown.
 const CLASSES = [
-    Error, TypeError, RangeError, SyntaxError, ReferenceError, EvalError, URIError,
-    HttpError, BodyTooLargeError, BodyTimeoutError,
-    BadRequestError, ForbiddenError, NotFoundError, ConflictError, RejectedValueError, ScopeForbiddenError, RawAppendOnlyError,
-    SqliteBlockedError, StoreNotPortedError, OtherStoreFolderError,
-    StoreBusyError, IncompatibleBinaryError,
+    Error,
+    TypeError,
+    RangeError,
+    SyntaxError,
+    ReferenceError,
+    EvalError,
+    URIError,
+    HttpError,
+    BodyTooLargeError,
+    BodyTimeoutError,
+    BadRequestError,
+    ForbiddenError,
+    NotFoundError,
+    ConflictError,
+    RejectedValueError,
+    ScopeForbiddenError,
+    RawAppendOnlyError,
+    SqliteBlockedError,
+    StoreNotPortedError,
+    OtherStoreFolderError,
+    StoreBusyError,
+    IncompatibleBinaryError,
 ];
 const PROTOTYPES = new Map(CLASSES.map((known) => [known.name, known.prototype]));
 // A chain of causes deeper than this is cut, so a cycle cannot recurse for ever.
@@ -37,19 +55,23 @@ function ownFields(err) {
 }
 /** Worker side. A thrown value that is not an Error carries its text and no class. */
 export function encodeError(err, depth = 0) {
-    if (!(err instanceof Error))
+    if (!(err instanceof Error)) {
         return { classes: [], message: errorMessage(err), stack: undefined, fields: {}, cause: undefined };
+    }
     const cause = err.cause === undefined || depth >= MAX_CAUSES ? undefined : encodeError(err.cause, depth + 1);
     return { classes: classNames(err), message: err.message, stack: err.stack, fields: ownFields(err), cause };
 }
-/** Server side: an instance of the thrown class, or of its nearest ancestor in the table, with the worker's stack, cause and fields. */
+/** Server side: an instance of the thrown class, or of its nearest ancestor in the table, with the worker's stack,
+ * cause and fields. */
 export function decodeError(wire) {
     const thrown = wire.classes[0];
     const known = wire.classes.find((name) => PROTOTYPES.has(name)) ?? 'Error';
     const unlisted = thrown !== undefined && thrown !== known;
-    if (unlisted)
+    if (unlisted) {
         log.once(`store-worker-error:${thrown}`, 'warn', `a store worker threw ${thrown}, which the error codec does not list; it arrives as ${known}`);
-    // A listed ancestor still maps to its status, so its text stays as thrown; under plain Error the class survives only in the message.
+    }
+    // A listed ancestor still maps to its status, so its text stays as thrown; under plain Error the class survives only
+    // in the message.
     const message = unlisted && known === 'Error' ? `${thrown}: ${wire.message}` : wire.message;
     const rebuilt = wire.cause === undefined ? new Error(message) : new Error(message, { cause: decodeError(wire.cause) });
     // The constructor is not run again: its arguments did not cross, and the fields below are what it set.

package/dist/store/sqlite/executor-counts.js

@@ -1,4 +1,5 @@
-// What the store workers refused, timed out and replaced since the process started; /health reports them beside the audit failure count.
+// What the store workers refused, timed out and replaced since the process started; /health reports them beside the
+// audit failure count.
 /** Counted on the server thread, across every executor of the process. */
 export const workerCounts = {
     /** Calls refused because a thread's queue was full. */

package/dist/store/sqlite/executor.d.ts

@@ -2,8 +2,11 @@ import { type OpMode } from './worker-ops.js';
 export interface CallOptions {
     readonly mode: OpMode;
     readonly requestId: string | undefined;
-    /** Epoch milliseconds by which the call's request must be answered; absent means the call waits as long as it takes. */
+    /** Epoch milliseconds by which the call's request must be answered; absent means the call waits as long as it
+     * takes. */
     readonly deadlineAt?: number | undefined;
+    /** Aborts when the request is abandoned; a call still queued then is dropped and never runs. */
+    readonly signal?: AbortSignal | undefined;
 }
 export interface ExecutorOptions {
     /** Lock wait of each thread's connection; defaults to the server's. */
@@ -14,13 +17,15 @@ export interface ExecutorOptions {
     readonly writeGraceMs?: number;
 }
 export interface SqliteExecutor {
-    /** Runs `op` of the synchronous store on a worker thread. A throw there rejects here as an instance of its own class. */
+    /** Runs `op` of the synchronous store on a worker thread. A throw there rejects here as an instance of its own
+     * class. */
     call<T>(op: string, args: readonly unknown[], opts: CallOptions): Promise<T>;
     /** Resolves once every thread has exited: Windows cannot delete a store folder while a thread holds its files. */
     close(): Promise<void>;
     /** Threads started and not yet exited. */
     liveThreads(): number;
-    /** Stops the writer thread as a crash would: its running and queued calls reject, and the next write starts a fresh thread. */
+    /** Stops the writer thread as a crash would: its running and queued calls reject, and the next write starts a fresh
+     * thread. */
     terminateWriter(): void;
 }
 /** Threads for the hippo.db under `hippoRoot`: one writer and two readers. The first

package/dist/store/sqlite/executor.js

@@ -1,4 +1,5 @@
-// The server thread's side of the store workers: SQLite's synchronous statements and lock waits run on their threads, so the event loop keeps answering.
+// The server thread's side of the store workers: SQLite's synchronous statements and lock waits run on their threads,
+// so the event loop keeps answering.
 import { fileURLToPath } from 'node:url';
 import { SHARE_ENV, Worker } from 'node:worker_threads';
 import { addAuditWriteFailures } from '../audit.js';
@@ -66,7 +67,7 @@ class WorkerPool {
         this.#queueMax = opts.queueMax ?? envStoreQueueMax() ?? DEFAULT_QUEUE_MAX;
         this.#writeGraceMs = opts.writeGraceMs ?? DEFAULT_WRITE_GRACE_MS;
     }
-    call(op, args, { mode, requestId, deadlineAt }) {
+    call(op, args, { mode, requestId, deadlineAt, signal }) {
         return new Promise((resolve, reject) => {
             if (this.#closed) {
                 reject(new StoreBusyError(EXECUTOR_CLOSED));
@@ -77,16 +78,27 @@ class WorkerPool {
                     reject(decodeError(reply.error));
                     return;
                 }
-                // SAFETY: the worker ran `op` of the synchronous store, whose result is the T the caller's port method declares.
+                // SAFETY: the worker ran `op` of the synchronous store, whose result is the T the caller's port method
+                // declares.
                 resolve(reply.value);
             };
-            const lane = mode === 'write' ? this.#writer : this.#readers.reduce((least, next) => (load(next) < load(least) ? next : least));
+            const lane = mode === 'write'
+                ? this.#writer
+                : this.#readers.reduce((least, next) => (load(next) < load(least) ? next : least));
             const refusal = this.#refusal(lane, deadlineAt);
             if (refusal !== undefined) {
                 reject(refusal);
                 return;
             }
-            const pending = { job: { id: this.#nextId++, op, args, requestId }, settle, fail: reject, deadlineAt, timer: undefined, answered: false };
+            const pending = {
+                job: { id: this.#nextId++, op, args, requestId },
+                settle,
+                fail: reject,
+                deadlineAt,
+                signal,
+                timer: undefined,
+                answered: false,
+            };
             this.#watchDeadline(lane, pending);
             lane.queue.push(pending);
             this.#ensureSetup();
@@ -109,13 +121,15 @@ class WorkerPool {
         this.#writer.queue.unshift(pending);
         this.#pump(this.#writer);
     }
-    // A failed setup fails the reads that waited for it with its own error, as each read's own open would have, and the next call tries it again.
+    // A failed setup fails the reads that waited for it with its own error, as each read's own open would have, and the
+    // next call tries it again.
     #setupEnded(failure) {
         this.#setup = failure === undefined ? 'done' : 'none';
         for (const lane of this.#readers) {
-            if (failure !== undefined)
+            if (failure !== undefined) {
                 for (const waiting of lane.queue.splice(0))
                     finish(waiting, () => waiting.fail(failure));
+            }
             this.#pump(lane);
         }
     }
@@ -148,7 +162,9 @@ class WorkerPool {
         }
         if (lane.running !== pending || lane.worker === undefined)
             return;
-        log.warn(`the store's ${lane.mode} worker ran '${pending.job.op}' past its request's deadline`, { requestId: pending.job.requestId });
+        log.warn(`the store's ${lane.mode} worker ran '${pending.job.op}' past its request's deadline`, {
+            requestId: pending.job.requestId,
+        });
         if (lane.mode === 'read')
             this.#stopReader(lane, lane.worker, pending);
         else
@@ -160,13 +176,15 @@ class WorkerPool {
         lane.stopping = worker;
         terminateLogged(worker);
     }
-    // Before its commit flag a stopped write is a known rollback; after it the thread is left to finish, since stopping it could not undo the write.
+    // Before its commit flag a stopped write is a known rollback; after it the thread is left to finish, since stopping
+    // it could not undo the write.
     #stopWriter(lane, worker, pending) {
         if (!mayHaveCommitted(lane, pending)) {
             lane.stopping = worker;
             this.terminateWriter();
         }
-        // A statement in flight runs to its end even after the stop, so the caller waits for the thread's own word only this long.
+        // A statement in flight runs to its end even after the stop, so the caller waits for the thread's own word only
+        // this long.
         pending.timer = setTimeout(() => finish(pending, () => pending.fail(new DeadlineExceededError(WRITE_UNKNOWN))), this.#writeGraceMs);
         pending.timer.unref();
     }
@@ -187,8 +205,9 @@ class WorkerPool {
     async close() {
         this.#closed = true;
         for (const lane of [this.#writer, ...this.#readers]) {
-            for (const pending of lane.queue.splice(0))
+            for (const pending of lane.queue.splice(0)) {
                 finish(pending, () => pending.fail(new StoreBusyError(EXECUTOR_CLOSED)));
+            }
             // An idle thread is unreferenced, and the process must not end before the thread has closed its connection.
             lane.worker?.ref();
             // Read after the reply of a job still running; the thread then closes its connection and ends.
@@ -209,7 +228,14 @@ class WorkerPool {
         // Setup comes first: a reader sent a job before it would open a store whose setup it cannot write.
         if (lane.mode === 'read' && this.#setup !== 'done')
             return;
-        const next = lane.queue.shift();
+        let next = lane.queue.shift();
+        // Its request was abandoned while it waited, so no one is left to read what it would do.
+        while (next?.signal?.aborted) {
+            workerCounts.jobsExpired += 1;
+            const dropped = next;
+            finish(dropped, () => dropped.fail(new StoreBusyError(EXPIRED_WAITING)));
+            next = lane.queue.shift();
+        }
         if (next === undefined)
             return;
         // Started by the first call and never at boot, so a server that only answers /health opens no thread.
@@ -219,7 +245,10 @@ class WorkerPool {
         // An idle thread never keeps the process alive; one with a call in flight does.
         lane.worker.ref();
         try {
-            lane.worker.postMessage({ ...next.job, walPages: autoCheckpointPages(getHippoDbPath(this.#hippoRoot)) });
+            lane.worker.postMessage({
+                ...next.job,
+                walPages: autoCheckpointPages(getHippoDbPath(this.#hippoRoot)),
+            });
         }
         catch (err) {
             // Arguments that cannot be copied to the thread fail this call alone.
@@ -233,11 +262,18 @@ class WorkerPool {
         worker.unref();
     }
     #start(lane) {
-        // A fresh flag per thread: a job id left by the thread before it could match no later job, but a shared buffer would outlive its writer.
+        // A fresh flag per thread: a job id left by the thread before it could match no later job, but a shared buffer
+        // would outlive its writer.
         const shared = lane.mode === 'write' ? new SharedArrayBuffer(4) : undefined;
         lane.commitFlag = shared && new Int32Array(shared);
-        const init = { hippoRoot: this.#hippoRoot, mode: lane.mode, busyWaitMs: this.#busyWaitMs, ...(shared && { commitFlag: shared }) };
-        // An explicit execArgv keeps the parent's loaders out of the thread and silences its repeat of the node:sqlite warning.
+        const init = {
+            hippoRoot: this.#hippoRoot,
+            mode: lane.mode,
+            busyWaitMs: this.#busyWaitMs,
+            ...(shared && { commitFlag: shared }),
+        };
+        // An explicit execArgv keeps the parent's loaders out of the thread and silences its repeat of the node:sqlite
+        // warning.
         const worker = new Worker(WORKER_ENTRY, { env: SHARE_ENV, execArgv: ['--no-warnings'], workerData: init });
         worker.unref();
         worker.on('message', (reply) => this.#settle(lane, worker, reply));
@@ -265,7 +301,8 @@ class WorkerPool {
         this.#idle(lane, worker);
         this.#pump(lane);
     }
-    // The lane keeps a stopped thread until it has exited, so a new thread never starts while the old one may still hold the write lock.
+    // The lane keeps a stopped thread until it has exited, so a new thread never starts while the old one may still hold
+    // the write lock.
     #retire(lane, worker, cause) {
         if (lane.worker !== worker)
             return;
@@ -278,7 +315,8 @@ class WorkerPool {
         const lost = lane.running === undefined ? lane.queue.splice(0) : [lane.running, ...lane.queue.splice(0)];
         lane.running = undefined;
         if (lost.length > 0 || cause !== undefined) {
-            log.warn(`the store's ${lane.mode} worker stopped with ${lost.length} call(s) unanswered${cause === undefined ? '' : `: ${cause.message}`}`);
+            log.warn(`the store's ${lane.mode} worker stopped with ${lost.length} call(s) ` +
+                `unanswered${cause === undefined ? '' : `: ${cause.message}`}`);
         }
         // The server answers this class as its retryable 503.
         for (const pending of lost)

package/dist/store/sqlite/global-promote.d.ts

@@ -0,0 +1,5 @@
+import { MemoryEntry } from '../../core/memory.js';
+import type { PromoteOptions } from '../port/promotion.js';
+/** Copies a local memory to the global store and returns the copy, which gets a new `g_` id so it cannot collide. */
+export declare function copyToGlobal(localRoot: string, id: string, opts?: PromoteOptions): MemoryEntry;
+//# sourceMappingURL=global-promote.d.ts.map

package/dist/store/sqlite/global-promote.js

@@ -0,0 +1,48 @@
+// Copies a local memory into the global store; the caller embeds the copy.
+import { BadRequestError, NotFoundError } from '../../core/api-errors.js';
+import { generateId } from '../../core/memory.js';
+import { isPersonalScope } from '../../core/recall-scope.js';
+import { fallbackOrigin, resolveGlobalRootDir } from '../../core/project-identity.js';
+import { isSharedStore } from '../../core/config.js';
+import { detectSecret } from '../../util/secret-detect.js';
+import { initStore } from '../open.js';
+import { writePromotedEntry } from '../entry-writes.js';
+import { readEntry } from '../entry-reads.js';
+import { isQuarantineScope } from '../quarantine.js';
+function assertPromotable(id, entry) {
+    // Same quarantine veto as shareMemory; a promoted copy would have no quarantine record to review.
+    if (isQuarantineScope(entry.scope)) {
+        throw new BadRequestError(`Refusing to promote ${id}: it is quarantined pending review. Approve it first via 'hippo quarantine approve ` +
+            `${id}'.`);
+    }
+    if (isPersonalScope(entry.scope ?? null)) {
+        throw new BadRequestError(`Refusing to promote ${id}: it is a personal memory and stays with its owner on this server.`);
+    }
+    // Secret producer veto: promote is a producer path to the global store
+    // exactly like shareMemory - same hard rule.
+    const promoteSecret = detectSecret(entry);
+    if (promoteSecret.flagged) {
+        throw new BadRequestError(`Refusing to promote ${id} to the global store: content matches secret material (${promoteSecret.reason}). ` +
+            `Secrets stay in their owning project's store.`);
+    }
+}
+/** Copies a local memory to the global store and returns the copy, which gets a new `g_` id so it cannot collide. */
+export function copyToGlobal(localRoot, id, opts) {
+    const entry = readEntry(localRoot, id, opts?.tenantId);
+    if (!entry)
+        throw new NotFoundError(`Memory not found: ${id}`);
+    assertPromotable(id, entry);
+    const globalRoot = resolveGlobalRootDir();
+    initStore(globalRoot);
+    // A project store's NULL row gets its folder back; a shared store's folder is no caller's project, so NULL stays and
+    // the label names no path.
+    const globalEntry = {
+        ...entry,
+        id: generateId('g'),
+        source: isSharedStore(localRoot) ? `shared::${new Date().toISOString()}` : `promoted:${localRoot}`,
+        origin_project: entry.origin_project ?? fallbackOrigin(localRoot),
+    };
+    writePromotedEntry(globalRoot, globalEntry, { actor: opts?.actor, sourceId: id, auditAs: opts?.auditAs });
+    return globalEntry;
+}
+//# sourceMappingURL=global-promote.js.map

package/dist/store/sqlite/goals-group.d.ts

@@ -0,0 +1,6 @@
+import type { Goals } from '../port-groups.js';
+import type { Sync } from '../port.js';
+export declare function sqliteGoals(hippoRoot: string): Sync<Goals>;
+/** The group as a served store answers it: a throw rejects as another store's would. */
+export declare function servedGoals(sync: Sync<Goals>): Goals;
+//# sourceMappingURL=goals-group.d.ts.map

package/dist/store/sqlite/goals-group.js

@@ -0,0 +1,23 @@
+// hippo.db's Goals group: the goal stack's writes and the every-status listing.
+import { completeGoal, getSessionGoals, pushGoal, resumeGoal, suspendGoal } from '../goals.js';
+export function sqliteGoals(hippoRoot) {
+    return {
+        push: (tenantId, goal) => pushGoal(hippoRoot, { ...goal, tenantId }),
+        sessionGoals: (tenantId, sessionId) => getSessionGoals(hippoRoot, { sessionId, tenantId }),
+        // Goal ids are not tenant-scoped in hippo.db, so these ignore the tenant; the api checks the host admin.
+        complete: (_tenantId, goalId, opts) => completeGoal(hippoRoot, goalId, opts),
+        suspend: (_tenantId, goalId) => suspendGoal(hippoRoot, goalId),
+        resume: (_tenantId, goalId) => resumeGoal(hippoRoot, goalId),
+    };
+}
+/** The group as a served store answers it: a throw rejects as another store's would. */
+export function servedGoals(sync) {
+    return {
+        push: async (tenantId, goal) => sync.push(tenantId, goal),
+        sessionGoals: async (tenantId, sessionId) => sync.sessionGoals(tenantId, sessionId),
+        complete: async (tenantId, goalId, opts) => sync.complete(tenantId, goalId, opts),
+        suspend: async (tenantId, goalId) => sync.suspend(tenantId, goalId),
+        resume: async (tenantId, goalId) => sync.resume(tenantId, goalId),
+    };
+}
+//# sourceMappingURL=goals-group.js.map

package/dist/store/sqlite/graph-reads-group.d.ts

@@ -1,5 +1,6 @@
 import type { GraphReads, Sync } from '../port.js';
 export declare function sqliteGraphReads(hippoRoot: string): Sync<GraphReads>;
-/** The group as a served store answers it: the call runs at once and resolves through a Promise, so a throw rejects as another store's would. */
+/** The group as a served store answers it: the call runs at once and resolves through a Promise, so a throw rejects as
+ * another store's would. */
 export declare function servedGraphReads(sync: Sync<GraphReads>): GraphReads;
 //# sourceMappingURL=graph-reads-group.d.ts.map

package/dist/store/sqlite/graph-reads-group.js

@@ -11,7 +11,8 @@ export function sqliteGraphReads(hippoRoot) {
         })),
     };
 }
-/** The group as a served store answers it: the call runs at once and resolves through a Promise, so a throw rejects as another store's would. */
+/** The group as a served store answers it: the call runs at once and resolves through a Promise, so a throw rejects as
+ * another store's would. */
 export function servedGraphReads(sync) {
     return { graphRows: async (tenantId, query) => sync.graphRows(tenantId, query) };
 }

package/dist/store/sqlite/held-connection.d.ts

@@ -1,11 +1,17 @@
+import { type HippoStore } from '../port.js';
 /** What the server calls around its responses to keep its store connection. */
 export interface StoreHolder {
     hold: () => void;
     afterResponse: () => void;
     release: () => Promise<void>;
-    /** Runs one request, inside the fence that keeps hippo.db shut when the store is not it. */
+    /** Runs one request in the server's scope, inside the fence that keeps hippo.db shut when the store is not it. */
     runRequest: (run: () => Promise<void>) => Promise<void>;
 }
 /** Holds a connection to the hippo.db under `hippoRoot` once it exists, so serving never creates one. */
 export declare function holdSqliteConnection(hippoRoot: string): StoreHolder;
+/** The holder for the store a server serves: hippo.db's held connection, else a fence that keeps hippo.db shut. */
+export declare function createStoreHolder(hippoRoot: string, store: HippoStore): StoreHolder;
+/** Runs a route's store work off the event loop when the store has a worker, else in place. */
+export declare function offLoopFor(store: HippoStore): <T>(run: () => T) => T;
+export declare function outsideRouteBlock<A extends readonly unknown[], R>(resolver: ((...args: A) => R) | undefined): ((...args: A) => R) | undefined;
 //# sourceMappingURL=held-connection.d.ts.map

package/dist/store/sqlite/held-connection.js

@@ -1,8 +1,11 @@
 // A served hippo.db keeps one connection open for the life of the server, beside the worker that checkpoints its WAL.
 import { existsSync } from 'node:fs';
-import { closeHippoDb, getHippoDbPath, openHippoDb, outsideRequestStores, outsideSqliteOffLoop, SERVER_DB_WAIT_MS, } from '../../db/index.js';
+import { closeHippoDb, getHippoDbPath, openHippoDb, outsideRequestStores, outsideSqliteOffLoop, SERVER_DB_WAIT_MS, withSqliteBlocked, withSqliteOffLoop, } from '../../db/index.js';
+import { hasGroup } from '../port.js';
+import { runSqliteRequest } from './request-scope.js';
+import { runsOffLoop } from './worker-store.js';
 import { startWalCheckpointer } from '../../db/wal-checkpointer.js';
-import { errorMessage, log } from '../../util/log.js';
+import { errorMessage, log, errorFields } from '../../util/log.js';
 /** Holds a connection to the hippo.db under `hippoRoot` once it exists, so serving never creates one. */
 export function holdSqliteConnection(hippoRoot) {
     // Handlers open and close their own connections; while this one is held, none of those closes is SQLite's last,
@@ -14,14 +17,15 @@ export function holdSqliteConnection(hippoRoot) {
         if (heldDb || stopHolding || !existsSync(getHippoDbPath(hippoRoot)))
             return;
         try {
-            // The 'finish' listener can fire inside a request scope (closing this connection with the request) and inside a `loop: 'off'` block (refusing the open).
-            // The server's lock wait: this open runs on the event loop, where SQLite's 5 s default and the 30 s journal-mode retry would stall every request.
+            // The 'finish' listener can fire inside a request scope (closing this connection with the request) and inside a
+            // `loop: 'off'` block (refusing the open). The server's lock wait: this open runs on the event loop, where
+            // SQLite's 5 s default and the 30 s journal-mode retry would stall every request.
             heldDb = outsideSqliteOffLoop(() => outsideRequestStores(() => openHippoDb(hippoRoot, { busyWaitMs: SERVER_DB_WAIT_MS })));
             checkpointer = startWalCheckpointer(getHippoDbPath(hippoRoot));
         }
         catch (err) {
             stopHolding = true;
-            log.warn(`serve: could not hold a store connection; requests still work, only slower: ${errorMessage(err)}`);
+            log.warn(`serve: could not hold a store connection; requests still work, only slower: ${errorMessage(err)}`, errorFields(err));
         }
     };
     const afterResponse = () => {
@@ -30,12 +34,35 @@ export function holdSqliteConnection(hippoRoot) {
     };
     const release = async () => {
         stopHolding = true;
-        // The worker's connection closes first, so the held one is SQLite's last and its close checkpoints and deletes the WAL.
+        // The worker's connection closes first, so the held one is SQLite's last and its close checkpoints and deletes the
+        // WAL.
         await checkpointer?.stop();
         if (heldDb)
             closeHippoDb(heldDb);
         heldDb = undefined;
     };
-    return { hold, afterResponse, release, runRequest: (run) => run() };
+    return { hold, afterResponse, release, runRequest: (run) => runSqliteRequest(run, 'server') };
+}
+/** The holder for the store a server serves: hippo.db's held connection, else a fence that keeps hippo.db shut. */
+export function createStoreHolder(hippoRoot, store) {
+    if (hasGroup(store, 'localFiles'))
+        return holdSqliteConnection(hippoRoot);
+    log.info(`serve: the '${store.kind}' store serves ${hippoRoot}, so no hippo.db connection is held`);
+    // A missed port under another store would otherwise create and write a hippo.db that store never reads.
+    return {
+        hold: () => { },
+        afterResponse: () => { },
+        release: async () => { },
+        runRequest: (run) => runSqliteRequest(() => withSqliteBlocked(store.kind, run), 'server'),
+    };
+}
+/** Runs a route's store work off the event loop when the store has a worker, else in place. */
+export function offLoopFor(store) {
+    return runsOffLoop(store) ? withSqliteOffLoop : (run) => run();
+}
+// A plugin's resolver may read hippo.db through this package's synchronous functions, so it runs outside the block of a
+// `loop: 'off'` route.
+export function outsideRouteBlock(resolver) {
+    return resolver && ((...args) => outsideSqliteOffLoop(() => resolver(...args)));
 }
 //# sourceMappingURL=held-connection.js.map

package/dist/store/sqlite/last-recall-group.d.ts

@@ -1,5 +1,6 @@
 import type { LastRecall, RecallWrites, Sync } from '../port.js';
-/** What a finished recall wrote after its audit rows: the trace's id, null when none was asked or its write failed, and the ids strengthened. */
+/** What a finished recall wrote after its audit rows: the trace's id, null when none was asked or its write failed, and
+ * the ids strengthened. */
 interface RecallFinish {
     readonly traceId: number | null;
     readonly strengthened: ReadonlySet<string>;
@@ -7,7 +8,8 @@ interface RecallFinish {
 /** sqliteStore's finishRecall, for the synchronous recall that cannot await the port. */
 export declare function finishRecallAt(hippoRoot: string, writes: RecallWrites): RecallFinish;
 export declare function sqliteLastRecall(hippoRoot: string): Sync<LastRecall>;
-/** The group as a served store answers it: the call runs at once and resolves through a Promise, so a throw rejects as another store's would. */
+/** The group as a served store answers it: the call runs at once and resolves through a Promise, so a throw rejects as
+ * another store's would. */
 export declare function servedLastRecall(sync: Sync<LastRecall>): LastRecall;
 export {};
 //# sourceMappingURL=last-recall-group.d.ts.map

package/dist/store/sqlite/last-recall-group.js

@@ -1,4 +1,5 @@
-// hippo.db's LastRecall group: the last recall sits in its meta table, and a traced outcome links on the outcome's own handle.
+// hippo.db's LastRecall group: the last recall sits in its meta table, and a traced outcome links on the outcome's own
+// handle.
 import { withWriteScope } from '../../db/index.js';
 import { appendAuditEvent } from '../audit.js';
 import { strengthenRetrieved, strengthenRetrievedInOwnTx } from '../entry-writes.js';
@@ -12,12 +13,15 @@ export function finishRecallAt(hippoRoot, writes) {
     return onHandle(hippoRoot, (db) => {
         const traceAndStrengthen = () => ({
             traceId: writes.trace ? writeRecallTrace(db, writes.trace) : null,
-            strengthened: writes.strengthen ? strengthenRetrievedInOwnTx(db, writes.strengthen.ids, writes.strengthen.opts) : new Set(),
+            strengthened: writes.strengthen
+                ? strengthenRetrievedInOwnTx(db, writes.strengthen.ids, writes.strengthen.opts)
+                : new Set(),
         });
         // Alone, the fail-soft trace and strengthen keep their own scopes so a busy lock loses them, never the read.
         if (writes.goalLog.length === 0 && writes.audit.length === 0)
             return traceAndStrengthen();
-        // Inside this scope both run as savepoints, so one recall commits once and a failed trace or strengthen still unwinds alone.
+        // Inside this scope both run as savepoints, so one recall commits once and a failed trace or strengthen still
+        // unwinds alone.
         return withWriteScope(db, 'finish_recall', () => {
             writeGoalRecallLog(db, localGoalRecallRows(db, writes.goalLog));
             for (const event of writes.audit)
@@ -46,7 +50,8 @@ export function sqliteLastRecall(hippoRoot) {
         },
     };
 }
-/** The group as a served store answers it: the call runs at once and resolves through a Promise, so a throw rejects as another store's would. */
+/** The group as a served store answers it: the call runs at once and resolves through a Promise, so a throw rejects as
+ * another store's would. */
 export function servedLastRecall(sync) {
     return {
         applyTracedOutcome: async (outcome, traceId) => sync.applyTracedOutcome(outcome, traceId),

package/dist/store/sqlite/learning-group.d.ts

@@ -0,0 +1,4 @@
+import type { Learning } from '../port/learning.js';
+/** The learn passes' store work on the hippo.db under `hippoRoot`, each call on its own short-lived handle. */
+export declare function sqliteLearning(hippoRoot: string): Learning;
+//# sourceMappingURL=learning-group.d.ts.map

package/dist/store/sqlite/learning-group.js

@@ -0,0 +1,17 @@
+import { confirmedOutcomeTimes } from '../audit.js';
+import { loadAllEntries, loadCurrentEntriesFromOrigins, loadEntriesMentioning, readEntry } from '../entry-reads.js';
+import { addTagToEntries, writeEntriesTogether, writeEntry } from '../entry-writes.js';
+/** The learn passes' store work on the hippo.db under `hippoRoot`, each call on its own short-lived handle. */
+export function sqliteLearning(hippoRoot) {
+    return {
+        allEntries: (tenantId) => loadAllEntries(hippoRoot, tenantId),
+        entriesMentioning: (tokens, tag, tenantId) => loadEntriesMentioning(hippoRoot, tokens, tag, tenantId),
+        readEntry: (id, tenantId) => readEntry(hippoRoot, id, tenantId),
+        currentEntriesFromOrigins: (tenantId, origins) => loadCurrentEntriesFromOrigins(hippoRoot, tenantId, origins),
+        writeEntry: (entry) => writeEntry(hippoRoot, entry),
+        writeEntriesTogether: (entries) => writeEntriesTogether(hippoRoot, entries),
+        addTagToEntries: (tenantId, ids, tag) => addTagToEntries(hippoRoot, tenantId, ids, tag),
+        confirmedOutcomeTimes: (tenantId) => confirmedOutcomeTimes(hippoRoot, tenantId),
+    };
+}
+//# sourceMappingURL=learning-group.js.map

package/dist/store/sqlite/maintenance-groups.js

@@ -1,4 +1,5 @@
-// hippo.db's half of the AuditMaintenance and LessonWrites store groups: the quality audit, audit prune and git learn's batch.
+// hippo.db's half of the AuditMaintenance and LessonWrites store groups: the quality audit, audit prune and git learn's
+// batch.
 import { pruneAuditRows } from '../audit.js';
 import { loadTextsHoldingWords } from '../candidates.js';
 import { deleteEntriesAutomatically, memoriesBackingObjects } from '../delete-and-batch.js';

package/dist/store/sqlite/object-rows.d.ts

@@ -78,7 +78,8 @@ interface RowSpec<K extends ObjectKind> {
     readonly closeOp: AuditOp;
     /** The one column a list may filter by equality. */
     readonly filterColumn?: string;
-    /** Set for the kinds the graph extracts, so a save marks the graph stale and a close drops the object's graph rows. */
+    /** Set for the kinds the graph extracts, so a save marks the graph stale and a close drops the object's graph
+     * rows. */
     readonly graphType?: SourceObjectType;
 }
 /** What one column of a new row can hold. */
@@ -86,12 +87,14 @@ export type ColumnValue = string | number | null;
 interface InsertSpec<K extends SavableKind> {
     readonly createOp: AuditOp;
     readonly supersedeOp: AuditOp;
-    /** A versioned table has `version` and `change_summary`: a successor takes its predecessor's version plus one and the caller's change note. */
+    /** A versioned table has `version` and `change_summary`: a successor takes its predecessor's version plus one and the
+     * caller's change note. */
     readonly versioned: boolean;
     /** The kind's own columns, in the order `values` fills them. */
     readonly columns: readonly string[];
     readonly values: (w: ObjectFields[K]) => readonly ColumnValue[];
-    /** The create audit's keys after the id, in the order they are stored: ids, counts and flags, never the object's text. */
+    /** The create audit's keys after the id, in the order they are stored: ids, counts and flags, never the object's
+     * text. */
     readonly createMeta: (w: ObjectFields[K], version: number) => JsonObject;
     /** Keys the supersede audit stores after its own. */
     readonly supersedeMeta?: (w: ObjectFields[K]) => JsonObject;

package/dist/store/sqlite/object-rows.js

@@ -69,11 +69,40 @@ function parseSteps(raw, id) {
         return [];
     }
 }
-const rowToProcess = (row) => ({ ...head(row), processName: row.process_name, description: row.description, steps: parseSteps(row.steps, row.id), ...versionedTail(row) });
-const rowToPolicy = (row) => ({ ...head(row), policyName: row.policy_name, policyText: row.policy_text, validFrom: row.valid_from, validTo: row.valid_to, ...versionedTail(row) });
-const rowToSkill = (row) => ({ ...head(row), skillName: row.skill_name, instructions: row.instructions, trigger: row.trigger_text, ...versionedTail(row) });
-const rowToProjectBrief = (row) => ({ ...head(row), repo: row.repo, summary: row.summary, ...versionedTail(row) });
-const rowToCustomerNote = (row) => ({ ...head(row), customer: row.customer, note: row.note, ...versionedTail(row) });
+const rowToProcess = (row) => ({
+    ...head(row),
+    processName: row.process_name,
+    description: row.description,
+    steps: parseSteps(row.steps, row.id),
+    ...versionedTail(row),
+});
+const rowToPolicy = (row) => ({
+    ...head(row),
+    policyName: row.policy_name,
+    policyText: row.policy_text,
+    validFrom: row.valid_from,
+    validTo: row.valid_to,
+    ...versionedTail(row),
+});
+const rowToSkill = (row) => ({
+    ...head(row),
+    skillName: row.skill_name,
+    instructions: row.instructions,
+    trigger: row.trigger_text,
+    ...versionedTail(row),
+});
+const rowToProjectBrief = (row) => ({
+    ...head(row),
+    repo: row.repo,
+    summary: row.summary,
+    ...versionedTail(row),
+});
+const rowToCustomerNote = (row) => ({
+    ...head(row),
+    customer: row.customer,
+    note: row.note,
+    ...versionedTail(row),
+});
 /** Tells an auto-refresh from a manual write in the audit log without a fourth audit op. */
 function refreshMeta(w) {
     return w.receiptCount === undefined ? { refreshed: false } : { refreshed: true, receipt_count: w.receiptCount };