hippo-memory 1.72.0 → 2.1.0

package/dist/store/sqlite/entry-writes-group.js

@@ -1,4 +1,5 @@
-// hippo.db's half of the EntryWrites store group: the queries remember, outcome, supersede, archive and forget run today.
+// hippo.db's half of the EntryWrites store group: the queries remember, outcome, supersede, archive and forget run
+// today.
 import { ConflictError, NotFoundError } from '../../core/api-errors.js';
 import { appendAuditEvent } from '../audit.js';
 import { isSqliteBusy, withWriteScope } from '../../db/index.js';
@@ -18,7 +19,8 @@ import { updateStatsUnlessBusy } from '../index-and-stats.js';
 import { purgeMirrorBestEffort, removeEntryMirrors } from '../mirrors.js';
 import { onHandle, openStore } from '../open.js';
 import { selectMemoryReach } from '../tenant-lookup.js';
-/** Each call on its own handle; mirrors and the forgotten counter follow the commit, so a rolled-back write leaves neither. */
+/** Each call on its own handle; mirrors and the forgotten counter follow the commit, so a rolled-back write leaves
+ * neither. */
 export function sqliteEntryWrites(hippoRoot) {
     return {
         writeEntry(write) {
@@ -52,13 +54,19 @@ export function writeEntryAt(hippoRoot, { entry, actor }, afterWrite) {
     onHandle(hippoRoot, (db) => writeInOwnTenant(db, stamped, actor, afterWrite), openStore);
     writeEntryMirrors(hippoRoot, stamped);
 }
-/** A trace link follows the commit on the same handle and names only the ids applied, so a rolled-back outcome leaves none. */
+/** A trace link follows the commit on the same handle and names only the ids applied, so a rolled-back outcome leaves
+ * none. */
 export function applyOutcomeAt(hippoRoot, outcome, traceId) {
     const applied = onHandle(hippoRoot, (db) => {
         const rows = applyOutcomeOn(db, outcome);
         const memoryIds = rows.map((entry) => entry.id);
         if (traceId !== undefined && rows.length > 0) {
-            recordTraceOutcome(db, { traceId, tenantId: outcome.tenantId, outcome: outcome.good ? 'positive' : 'negative', memoryIds });
+            recordTraceOutcome(db, {
+                traceId,
+                tenantId: outcome.tenantId,
+                outcome: outcome.good ? 'positive' : 'negative',
+                memoryIds,
+            });
         }
         return rows;
     }, openStore);
@@ -66,7 +74,8 @@ export function applyOutcomeAt(hippoRoot, outcome, traceId) {
         writeEntryMirrors(hippoRoot, entry);
     return applied.map((entry) => entry.id);
 }
-/** Reach is checked inside the archive's write scope. A store-side hook writes on the same handle inside that scope, so its throw undoes the archive. */
+/** Reach is checked inside the archive's write scope. A store-side hook writes on the same handle inside that scope, so
+ * its throw undoes the archive. */
 export function archiveRawAt(hippoRoot, archive, afterArchive) {
     const archivedAt = onHandle(hippoRoot, (db) => {
         const at = withWriteScope(db, 'archive_raw_in_reach', () => {
@@ -88,11 +97,13 @@ function assertInReach(db, target, id) {
     if (reach?.tenantId !== target.tenantId || !ownScopeTouches(target.ownScope, reach.scope))
         throw notFound(id);
 }
-/** hippo.db's upsert would move the row into the writer's tenant, so a store write refuses an id another tenant holds. */
+/** hippo.db's upsert would move the row into the writer's tenant, so a store write refuses an id another tenant
+ * holds. */
 function assertIdInTenant(db, entry) {
     const holder = selectMemoryReach(db, entry.id)?.tenantId;
-    if (holder !== undefined && holder !== entry.tenantId)
+    if (holder !== undefined && holder !== entry.tenant_id) {
         throw new ConflictError(`Memory ${entry.id} belongs to another tenant`);
+    }
 }
 /** The refusal row lands after `write` has rolled back, in a fresh implicit transaction the aborted one cannot undo. */
 export function auditingRefusal(db, actor, write) {
@@ -112,7 +123,8 @@ export function writeInOwnTenant(db, entry, actor, afterWrite) {
         writeEntryDbOnly(db, entry, { actor, afterWrite });
     }));
 }
-/** The reads, rewrites and outcome rows share one BEGIN IMMEDIATE transaction, hippo.db's form of the port's row lock; the caller writes the mirrors after. */
+/** The reads, rewrites and outcome rows share one BEGIN IMMEDIATE transaction, hippo.db's form of the port's row lock;
+ * the caller writes the mirrors after. */
 function applyOutcomeOn(db, outcome) {
     return auditingRefusal(db, outcome.actor, () => withWriteScope(db, 'apply_outcome', () => {
         const live = selectEntriesByIds(db, outcome.ids, outcome.tenantId);
@@ -124,20 +136,29 @@ function applyOutcomeOn(db, outcome) {
             const updated = entryAfterOutcome(entry, outcome.good);
             writeEntryDbOnly(db, updated, { actor: outcome.actor });
             live.set(id, updated);
-            appendAuditEvent(db, { tenantId: outcome.tenantId, actor: outcome.actor, op: 'outcome', targetId: id, metadata: { good: outcome.good } });
+            appendAuditEvent(db, {
+                tenantId: outcome.tenantId,
+                actor: outcome.actor,
+                op: 'outcome',
+                targetId: id,
+                metadata: { good: outcome.good },
+            });
             applied.push(updated);
         }
         return applied;
     }));
 }
-/** Reach, the CAS on the old row, the successor's insert and the supersede row in one BEGIN IMMEDIATE transaction. Two racing supersedes: one CAS wins. */
+/** Reach, the CAS on the old row, the successor's insert and the supersede row in one BEGIN IMMEDIATE transaction. Two
+ * racing supersedes: one CAS wins. */
 function commitSupersede(db, write) {
     const { tenantId, actor, oldId, successor } = write;
     // The refusal row lands after the scope has rolled back, in a fresh implicit transaction the aborted one cannot undo.
     auditingRefusal(db, actor, () => withWriteScope(db, 'supersede', () => {
         assertInReach(db, write, oldId);
         // SAFETY: RETURNING names one column, dag_parent_id; no row means another writer got there first.
-        const won = db.prepare('UPDATE memories SET superseded_by = ? WHERE id = ? AND tenant_id = ? AND superseded_by IS NULL RETURNING dag_parent_id')
+        const won = db
+            .prepare('UPDATE memories SET superseded_by = ? WHERE id = ? AND tenant_id = ? AND superseded_by IS NULL RETURNING ' +
+            'dag_parent_id')
             .get(successor.id, oldId, tenantId);
         if (!won)
             throw new ConflictError(`Memory ${oldId} already superseded by another writer`);
@@ -149,13 +170,15 @@ function commitSupersede(db, write) {
         appendAuditEvent(db, { tenantId, actor, op: 'supersede', targetId: oldId, metadata: { newId: successor.id } });
     }));
 }
-/** A mirror left on disk would bring the archived row back on the next import; on failure the reaper retries, as mirror_cleaned_at stays NULL. */
+/** A mirror left on disk would bring the archived row back on the next import; on failure the reaper retries, as
+ * mirror_cleaned_at stays NULL. */
 function cleanArchivedMirrors(db, hippoRoot, id) {
     try {
         removeEntryMirrors(hippoRoot, id);
     }
     catch (mirrorErr) {
-        log.error(`archiveRaw: mirror cleanup failed for ${id} (will retry via reaper on next openHippoDb): ${errorMessage(mirrorErr)}`, errorFields(mirrorErr));
+        log.error(`archiveRaw: mirror cleanup failed for ${id} (will retry via reaper on next openHippoDb): ` +
+            `${errorMessage(mirrorErr)}`, errorFields(mirrorErr));
         return;
     }
     try {
@@ -164,7 +187,7 @@ function cleanArchivedMirrors(db, hippoRoot, id) {
     catch (err) {
         if (!isSqliteBusy(err))
             throw err;
-        log.warnThenDebug('archive-mirror-stamp-busy', `archived ${id}; the store was busy, so the mirror reaper will re-check it on the next open`);
+        log.warnThenDebug('archive-mirror-stamp-busy', `archived ${id}; the store was busy, so the mirror reaper will re-check it on the next open`, errorFields(err));
     }
 }
 //# sourceMappingURL=entry-writes-group.js.map

package/dist/store/sqlite/error-codec.d.ts

@@ -1,7 +1,8 @@
 type FieldValue = string | number | boolean | null;
 /** One error as a thread message can carry it. */
 export interface WireError {
-    /** Constructor names from the thrown class up to Error: several classes set no `name`, so a name alone cannot pick the class. */
+    /** Constructor names from the thrown class up to Error: several classes set no `name`, so a name alone cannot pick
+     * the class. */
     readonly classes: readonly string[];
     readonly message: string;
     readonly stack: string | undefined;
@@ -11,7 +12,8 @@ export interface WireError {
 }
 /** Worker side. A thrown value that is not an Error carries its text and no class. */
 export declare function encodeError<E>(err: E, depth?: number): WireError;
-/** 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 declare function decodeError(wire: WireError): Error;
 export {};
 //# sourceMappingURL=error-codec.d.ts.map

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,9 +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 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 };
+    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