hippo-memory 1.68.0 → 1.70.0

package/dist/store/sqlite/store.js

@@ -0,0 +1,295 @@
+// The built-in SQLite adapter behind the store port.
+import { loadAmbientTallies } from '../ambient.js';
+import { listApiKeyRows, readApiKeyRecord } from '../auth.js';
+import { existsSync } from 'node:fs';
+import { appendAuditEvent, listAuditEventsAfter, queryAuditEvents } from '../audit.js';
+import { getHippoDbPath, withWriteScope } from '../../db/index.js';
+import { loadStoredVectorViews } from '../embeddings/index.js';
+import { activeGoalsWithPolicies, localGoalRecallRows, writeGoalRecallLog } from '../goals.js';
+import { planningFallacyEvidenceAt } from '../planning-fallacy-evidence.js';
+import { writeRecallTrace } from '../recall-trace.js';
+import { recordTokenUse } from '../token-ledger.js';
+import { loadAmbientCandidates, loadContextCandidates } from '../candidates.js';
+import { loadEntriesByIds, loadFreshRawMemories } from '../entry-reads.js';
+import { strengthenRetrievedInOwnTx } from '../entry-writes.js';
+import { servedConnectorEvents, sqliteConnectorEvents } from './connector-events-group.js';
+import { servedConnectorWrites, sqliteConnectorWrites } from './connector-writes-group.js';
+import { sqliteDagReads } from './dag-reads-group.js';
+import { sqliteEntryWrites } from './entry-writes-group.js';
+import { servedGraphReads, sqliteGraphReads } from './graph-reads-group.js';
+import { servedObjects, sqliteObjects } from './objects-group.js';
+import { servedPredictions, sqlitePredictions } from './predictions-group.js';
+import { servedQuarantine, sqliteQuarantine } from './quarantine-group.js';
+import { sqliteVectorReads } from './vector-reads-group.js';
+import { loadLatestHandoff } from '../handoffs.js';
+import { updateStats } from '../index-and-stats.js';
+import { auditHighIdAt, revokeKeyAt } from '../key-audit.js';
+import { createKeyAt, createSelfKeyAt } from '../key-writes.js';
+import { onHandle } from '../open.js';
+import { loadRecallSearchEntries } from '../search-rows.js';
+import { listSessionEvents, loadActiveTaskSnapshot } from '../sessions.js';
+import { entriesWithoutVectorAt, writeVectorsAt } from '../vector-writes.js';
+/** The store a request runs on: the served one, else hippo.db under its root, as the CLI and SDK callers have it. */
+export function storeFor(ctx) {
+    return ctx.store ?? sqliteStore(ctx.hippoRoot);
+}
+/** The built-in store: hippo.db under the port's own method names, each call on its own short-lived handles, so close has nothing to release. */
+export function sqliteSyncStore(hippoRoot) {
+    return {
+        kind: 'sqlite',
+        ...sqliteBaseReads(hippoRoot),
+        ...sqliteRecallWrites(hippoRoot),
+        keyAudit: sqliteKeyAudit(hippoRoot),
+        keyWrites: sqliteKeyWrites(hippoRoot),
+        vectorViews: sqliteVectorViews(hippoRoot),
+        vectorWrites: sqliteVectorWrites(hippoRoot),
+        entryWrites: sqliteEntryWrites(hippoRoot),
+        contextReads: sqliteContextReads(hippoRoot),
+        predictions: sqlitePredictions(hippoRoot),
+        dagReads: sqliteDagReads(hippoRoot),
+        auditLog: sqliteAuditLog(hippoRoot),
+        quarantine: sqliteQuarantine(hippoRoot),
+        graphReads: sqliteGraphReads(hippoRoot),
+        connectorWrites: sqliteConnectorWrites(hippoRoot),
+        connectorEvents: sqliteConnectorEvents(hippoRoot),
+        objects: sqliteObjects(hippoRoot),
+        readiness: sqliteReadiness(hippoRoot),
+        close() { },
+    };
+}
+function sqliteBaseReads(hippoRoot) {
+    return {
+        findApiKey(keyId) {
+            return onHandle(hippoRoot, (db) => readApiKeyRecord(db, keyId));
+        },
+        searchRecallEntries(query, args) {
+            return loadRecallSearchEntries(hippoRoot, query, args.limit, args.tenantId, args.requestedScope, args.explicitScopeMode, args.includeSuperseded, args.originProjects, args.ownScope);
+        },
+        entriesByIds(ids, tenantId) {
+            return loadEntriesByIds(hippoRoot, ids, tenantId);
+        },
+        activeGoals(opts) {
+            return activeGoalsWithPolicies(hippoRoot, opts);
+        },
+        freshRawEntries(count, tenantId, sessionId, origins) {
+            return loadFreshRawMemories(hippoRoot, count, tenantId, sessionId, origins ?? undefined);
+        },
+        continuity(tenantId, eventLimit, key) {
+            return continuityAt(hippoRoot, tenantId, eventLimit, key);
+        },
+        planningFallacyEvidence(tenantId, classQueryTokens) {
+            return planningFallacyEvidenceAt(hippoRoot, tenantId, classQueryTokens);
+        },
+    };
+}
+function sqliteRecallWrites(hippoRoot) {
+    return {
+        appendAuditEvents(events) {
+            if (events.length === 0)
+                return;
+            onHandle(hippoRoot, (db) => withWriteScope(db, 'append_audit_events', () => {
+                for (const event of events)
+                    appendAuditEvent(db, event);
+            }));
+        },
+        finishRecall(writes) {
+            finishRecallAt(hippoRoot, writes);
+        },
+        bumpRecallStats(recalled) {
+            updateStats(hippoRoot, { recalled });
+        },
+        recordTokens(use) {
+            onHandle(hippoRoot, (db) => recordTokenUse(db, use));
+        },
+    };
+}
+function sqliteVectorViews(hippoRoot) {
+    return {
+        storedVectorViews(ids) {
+            return loadStoredVectorViews(hippoRoot, ids);
+        },
+    };
+}
+function sqliteVectorWrites(hippoRoot) {
+    return {
+        entriesWithoutVector(query) {
+            return onHandle(hippoRoot, (db) => entriesWithoutVectorAt(db, query));
+        },
+        writeVectors(write) {
+            return onHandle(hippoRoot, (db) => writeVectorsAt(db, write));
+        },
+    };
+}
+function sqliteAuditLog(hippoRoot) {
+    return {
+        listAuditEvents(query) {
+            return onHandle(hippoRoot, (db) => queryAuditEvents(db, query));
+        },
+    };
+}
+function sqliteReadiness(hippoRoot) {
+    return {
+        ping() {
+            // A probe must not create the store; the first write does, so a root with none yet is ready.
+            if (!existsSync(getHippoDbPath(hippoRoot)))
+                return;
+            onHandle(hippoRoot, (db) => { db.prepare('SELECT 1').get(); });
+        },
+    };
+}
+/** `sqliteSyncStore` as a served store: each method runs at once and answers through a Promise, so a throw rejects as another store's would. */
+export function sqliteStore(hippoRoot) {
+    const sync = sqliteSyncStore(hippoRoot);
+    return {
+        ...servedBaseMethods(sync),
+        vectors: sqliteVectorReads(hippoRoot),
+        vectorViews: { storedVectorViews: async (ids) => sync.vectorViews.storedVectorViews(ids) },
+        ...servedKeyGroups(sync),
+        ...servedEntryGroups(sync),
+        predictions: servedPredictions(sync.predictions),
+        ...servedDagAndAudit(sync),
+        quarantine: servedQuarantine(sync.quarantine),
+        graphReads: servedGraphReads(sync.graphReads),
+        connectorWrites: servedConnectorWrites(sync.connectorWrites),
+        connectorEvents: servedConnectorEvents(sync.connectorEvents),
+        objects: servedObjects(sqliteObjects(hippoRoot)),
+        readiness: { ping: async () => sync.readiness.ping() },
+        close: async () => sync.close(),
+    };
+}
+function servedBaseMethods(sync) {
+    return {
+        kind: sync.kind,
+        findApiKey: async (keyId) => sync.findApiKey(keyId),
+        searchRecallEntries: async (query, args) => sync.searchRecallEntries(query, args),
+        entriesByIds: async (ids, tenantId) => sync.entriesByIds(ids, tenantId),
+        activeGoals: async (opts) => sync.activeGoals(opts),
+        freshRawEntries: async (count, tenantId, sessionId, origins) => sync.freshRawEntries(count, tenantId, sessionId, origins),
+        continuity: async (tenantId, eventLimit, key) => sync.continuity(tenantId, eventLimit, key),
+        planningFallacyEvidence: async (tenantId, classQueryTokens) => sync.planningFallacyEvidence(tenantId, classQueryTokens),
+        appendAuditEvents: async (events) => sync.appendAuditEvents(events),
+        finishRecall: async (writes) => sync.finishRecall(writes),
+        bumpRecallStats: async (recalled) => sync.bumpRecallStats(recalled),
+        recordTokens: async (use) => sync.recordTokens(use),
+    };
+}
+function servedKeyGroups(sync) {
+    const { keyAudit, keyWrites } = sync;
+    return {
+        keyAudit: {
+            revokeApiKey: async (revoke) => keyAudit.revokeApiKey(revoke),
+            auditEventsAfter: async (opts) => keyAudit.auditEventsAfter(opts),
+            auditHighId: async () => keyAudit.auditHighId(),
+        },
+        keyWrites: {
+            createApiKey: async (mint) => keyWrites.createApiKey(mint),
+            createSelfApiKey: async (mint) => keyWrites.createSelfApiKey(mint),
+            listApiKeys: async (query) => keyWrites.listApiKeys(query),
+        },
+    };
+}
+function servedEntryGroups(sync) {
+    const { vectorWrites, entryWrites, contextReads } = sync;
+    return {
+        vectorWrites: {
+            entriesWithoutVector: async (query) => vectorWrites.entriesWithoutVector(query),
+            writeVectors: async (write) => vectorWrites.writeVectors(write),
+        },
+        entryWrites: {
+            writeEntry: async (write) => entryWrites.writeEntry(write),
+            applyOutcome: async (outcome) => entryWrites.applyOutcome(outcome),
+            supersede: async (write) => entryWrites.supersede(write),
+            archiveRaw: async (archive) => entryWrites.archiveRaw(archive),
+            forget: async (removal) => entryWrites.forget(removal),
+        },
+        contextReads: {
+            unfinishedHandoff: async (tenantId, maxAgeMs, key) => contextReads.unfinishedHandoff(tenantId, maxAgeMs, key),
+            ambientCandidates: async (tenantId, request) => contextReads.ambientCandidates(tenantId, request),
+            contextCandidates: async (tenantId, filter) => contextReads.contextCandidates(tenantId, filter),
+            ambientTallies: async (tenantId, filter) => contextReads.ambientTallies(tenantId, filter),
+        },
+    };
+}
+function servedDagAndAudit(sync) {
+    const { dagReads, auditLog } = sync;
+    return {
+        dagReads: {
+            sessionRawEntries: async (query) => dagReads.sessionRawEntries(query),
+            sessionRawCount: async (query) => dagReads.sessionRawCount(query),
+            summaryWithDescendants: async (tenantId, id, walk) => dagReads.summaryWithDescendants(tenantId, id, walk),
+        },
+        auditLog: {
+            listAuditEvents: async (query) => auditLog.listAuditEvents(query),
+        },
+    };
+}
+function sqliteContextReads(hippoRoot) {
+    return {
+        unfinishedHandoff(tenantId, maxAgeMs, key) {
+            return loadLatestHandoff(hippoRoot, tenantId, undefined, { unfinishedOnly: true, maxAgeMs, scopeFilter: 'default-deny' }, key ?? undefined);
+        },
+        ambientCandidates(tenantId, { recentNeeded, admit, recall, origins }) {
+            return loadAmbientCandidates(hippoRoot, tenantId, recentNeeded, admit, recall, origins);
+        },
+        contextCandidates(tenantId, filter) {
+            return loadContextCandidates(hippoRoot, tenantId, filter);
+        },
+        ambientTallies(tenantId, filter) {
+            return loadAmbientTallies(hippoRoot, tenantId, filter);
+        },
+    };
+}
+function sqliteKeyWrites(hippoRoot) {
+    return {
+        createApiKey(mint) {
+            onHandle(hippoRoot, (db) => createKeyAt(db, mint));
+        },
+        createSelfApiKey(mint) {
+            return onHandle(hippoRoot, (db) => createSelfKeyAt(db, mint));
+        },
+        listApiKeys(query) {
+            return onHandle(hippoRoot, (db) => listApiKeyRows(db, query));
+        },
+    };
+}
+function sqliteKeyAudit(hippoRoot) {
+    return {
+        revokeApiKey(revoke) {
+            return onHandle(hippoRoot, (db) => revokeKeyAt(db, revoke));
+        },
+        auditEventsAfter(opts) {
+            return onHandle(hippoRoot, (db) => listAuditEventsAfter(db, opts));
+        },
+        auditHighId() {
+            return onHandle(hippoRoot, auditHighIdAt);
+        },
+    };
+}
+/** sqliteStore's continuity read, for the synchronous recall that cannot await the port. */
+export function continuityAt(hippoRoot, tenantId, eventLimit, key) {
+    const activeSnapshot = loadActiveTaskSnapshot(hippoRoot, tenantId, key ?? undefined);
+    const sessionId = activeSnapshot?.session_id ?? undefined;
+    return {
+        activeSnapshot,
+        sessionHandoff: sessionId ? loadLatestHandoff(hippoRoot, tenantId, sessionId, {}, key ?? undefined) : null,
+        recentSessionEvents: sessionId ? listSessionEvents(hippoRoot, tenantId, { session_id: sessionId, limit: eventLimit }) : [],
+    };
+}
+/** sqliteStore's finishRecall, for the synchronous recall that cannot await the port. */
+export function finishRecallAt(hippoRoot, writes) {
+    return onHandle(hippoRoot, (db) => {
+        // With no row to write the scope would only take the write lock.
+        if (writes.goalLog.length > 0 || writes.audit.length > 0) {
+            withWriteScope(db, 'finish_recall', () => {
+                writeGoalRecallLog(db, localGoalRecallRows(db, writes.goalLog));
+                for (const event of writes.audit)
+                    appendAuditEvent(db, event);
+            });
+        }
+        // Each opens its own transaction, so neither can share the scope above.
+        const traceId = writes.trace ? writeRecallTrace(db, writes.trace) : null;
+        const strengthened = writes.strengthen ? strengthenRetrievedInOwnTx(db, writes.strengthen.ids, writes.strengthen.opts) : new Set();
+        return { traceId, strengthened };
+    });
+}
+//# sourceMappingURL=store.js.map

package/dist/store/sqlite/vector-pack.d.ts

@@ -0,0 +1,18 @@
+/** Every vector end to end in `buffer` as Float32, `dims[i]` numbers for `ids[i]`. */
+export interface VectorPack {
+    readonly ids: readonly string[];
+    readonly dims: readonly number[];
+    readonly buffer: ArrayBuffer;
+}
+/** A pack on the thread that built it, so the reply that carries it knows which buffer to move. */
+export declare class PackedVectors implements VectorPack {
+    readonly ids: readonly string[];
+    readonly dims: readonly number[];
+    readonly buffer: ArrayBuffer;
+    constructor(ids: readonly string[], dims: readonly number[], buffer: ArrayBuffer);
+}
+export declare function packVectors(vectors: ReadonlyMap<string, Float32Array>): PackedVectors;
+/** Each value views its own stretch of the pack's one buffer. */
+export declare function vectorViewsOf(pack: VectorPack): Map<string, Float32Array>;
+export declare function vectorCopiesOf(pack: VectorPack): Map<string, number[]>;
+//# sourceMappingURL=vector-pack.d.ts.map

package/dist/store/sqlite/vector-pack.js

@@ -0,0 +1,46 @@
+// Vectors from a store worker as one buffer: it moves to the server thread with no copy, where a Map of typed arrays is copied value by value.
+/** A pack on the thread that built it, so the reply that carries it knows which buffer to move. */
+export class PackedVectors {
+    ids;
+    dims;
+    buffer;
+    constructor(ids, dims, buffer) {
+        this.ids = ids;
+        this.dims = dims;
+        this.buffer = buffer;
+    }
+}
+export function packVectors(vectors) {
+    let total = 0;
+    for (const vector of vectors.values())
+        total += vector.length;
+    const buffer = new ArrayBuffer(total * Float32Array.BYTES_PER_ELEMENT);
+    const floats = new Float32Array(buffer);
+    const dims = [];
+    let at = 0;
+    for (const vector of vectors.values()) {
+        floats.set(vector, at);
+        at += vector.length;
+        dims.push(vector.length);
+    }
+    return new PackedVectors([...vectors.keys()], dims, buffer);
+}
+function eachVector(pack, valueOf) {
+    const floats = new Float32Array(pack.buffer);
+    const out = new Map();
+    let at = 0;
+    pack.ids.forEach((id, i) => {
+        const end = at + (pack.dims[i] ?? 0);
+        out.set(id, valueOf(floats.subarray(at, end)));
+        at = end;
+    });
+    return out;
+}
+/** Each value views its own stretch of the pack's one buffer. */
+export function vectorViewsOf(pack) {
+    return eachVector(pack, (view) => view);
+}
+export function vectorCopiesOf(pack) {
+    return eachVector(pack, (view) => Array.from(view));
+}
+//# sourceMappingURL=vector-pack.js.map

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

@@ -0,0 +1,3 @@
+import type { VectorReads } from '../port.js';
+export declare function sqliteVectorReads(hippoRoot: string): VectorReads;
+//# sourceMappingURL=vector-reads-group.d.ts.map

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

@@ -0,0 +1,23 @@
+// hippo.db's vector reads. Async only: the nearest-row scan yields between chunks, so a store worker awaits these where it runs every other method to its end.
+import { loadPhysicsState } from '../../db/physics-state.js';
+import { embeddingIndexStateAt, loadStoredVectors } from '../embeddings/index.js';
+import { onHandle } from '../open.js';
+import { loadVectorCandidateEntries } from '../search-rows.js';
+export function sqliteVectorReads(hippoRoot) {
+    return {
+        async embeddingIndexState() {
+            return embeddingIndexStateAt(hippoRoot);
+        },
+        async storedVectors(ids) {
+            return loadStoredVectors(hippoRoot, ids);
+        },
+        async nearestEntries(queryVector, spec) {
+            return loadVectorCandidateEntries(hippoRoot, queryVector, spec);
+        },
+        async physicsParticles(ids) {
+            // loadPhysicsState reads every row for an empty list.
+            return ids.length === 0 ? new Map() : onHandle(hippoRoot, (db) => loadPhysicsState(db, [...ids]));
+        },
+    };
+}
+//# sourceMappingURL=vector-reads-group.js.map

package/dist/store/sqlite/worker-entry.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=worker-entry.d.ts.map

package/dist/store/sqlite/worker-entry.js

@@ -0,0 +1,8 @@
+// Entry of a store worker thread; executor.ts starts it and nothing imports it. The work is in worker-jobs.ts.
+import { parentPort, workerData } from 'node:worker_threads';
+import { serveJobs } from './worker-jobs.js';
+if (parentPort) {
+    // SAFETY: executor.ts is the only code that starts this file, and it passes a WorkerInit.
+    serveJobs(parentPort, workerData);
+}
+//# sourceMappingURL=worker-entry.js.map

package/dist/store/sqlite/worker-jobs.d.ts

@@ -0,0 +1,5 @@
+import type { MessagePort } from 'node:worker_threads';
+import { type WorkerInit } from './worker-ops.js';
+/** Answers the thread's jobs until 'stop', which closes the connection so the thread ends with no handle on the store's files. */
+export declare function serveJobs(port: MessagePort, init: WorkerInit): void;
+//# sourceMappingURL=worker-jobs.d.ts.map

package/dist/store/sqlite/worker-jobs.js

@@ -0,0 +1,116 @@
+import { auditWriteFailureCount } from '../audit.js';
+import { RequestStores } from '../../db/index.js';
+import { loadStoredVectorViews } from '../embeddings/index.js';
+import { requestScopes } from '../../util/request-scope.js';
+import { initStore } from '../open.js';
+import { watchCommits } from './commit-watch.js';
+import { encodeError } from './error-codec.js';
+import { sqliteSyncStore } from './store.js';
+import { PackedVectors, packVectors } from './vector-pack.js';
+import { sqliteVectorReads } from './vector-reads-group.js';
+import { STORE_SETUP_OP, WORKER_OPS } from './worker-ops.js';
+/** Every method the op table can name: the synchronous store, and the vector reads, which answer only through Promises.
+ *  The two reads that return vectors answer with a pack, which worker-store.ts turns back into the port's Map. */
+function workerOps(hippoRoot) {
+    const packed = (ids) => packVectors(loadStoredVectorViews(hippoRoot, ids));
+    return {
+        ...sqliteSyncStore(hippoRoot),
+        vectors: { ...sqliteVectorReads(hippoRoot), storedVectors: packed },
+        vectorViews: { storedVectorViews: packed },
+    };
+}
+/** The scope every job of a thread runs in, so each open inside a job gets the thread's one connection. */
+class WorkerStores extends RequestStores {
+    requestId = undefined;
+    walPages;
+    jobId = 0;
+    #init;
+    #commitFlag;
+    #prepared = new WeakSet();
+    #walPagesOn = new WeakMap();
+    constructor(init) {
+        // The executor sends a reader its first job only after the writer has run the setup.
+        super({ busyWaitMs: init.busyWaitMs, ...(init.mode === 'read' && { setupDoneFor: init.hippoRoot }) });
+        this.#init = init;
+        this.#commitFlag = init.commitFlag && new Int32Array(init.commitFlag);
+    }
+    // The one path every open of the scope takes: `get` is a wrapper over it.
+    getWithFacts(hippoRoot, opts) {
+        const opened = super.getWithFacts(hippoRoot, opts);
+        const { db } = opened;
+        if (!this.#prepared.has(db)) {
+            this.#prepared.add(db);
+            // A reader that could write would let a method wrongly tagged 'read' take the write lock off the writer thread.
+            if (this.#init.mode === 'read')
+                db.exec('PRAGMA query_only = ON');
+            const flag = this.#commitFlag;
+            if (flag)
+                watchCommits(db, () => Atomics.store(flag, 0, this.jobId));
+        }
+        // The connection set its own value from this thread's state, where no checkpointer ever runs.
+        if (hippoRoot === this.#init.hippoRoot && this.walPages !== undefined && this.#walPagesOn.get(db) !== this.walPages) {
+            db.exec(`PRAGMA wal_autocheckpoint = ${this.walPages}`);
+            this.#walPagesOn.set(db, this.walPages);
+        }
+        return opened;
+    }
+}
+function isWorkerGroup(group) {
+    return Object.hasOwn(WORKER_OPS, group);
+}
+function runsOnWorker(group, method) {
+    const places = WORKER_OPS[group];
+    return Object.hasOwn(places, method) && places[method] !== 'server';
+}
+function methodsOf(ops, group) {
+    // SAFETY: every group is an object of methods, and the server thread sent the arguments the port's own signature for the one called took.
+    return (group === 'base' ? ops : ops[group]);
+}
+/** Runs `op`; only a method the op table places on a worker can run. */
+function runOp(ops, op, args) {
+    const [group = '', method = ''] = op.split('.');
+    const run = isWorkerGroup(group) && runsOnWorker(group, method) ? methodsOf(ops, group)[method] : undefined;
+    if (run === undefined)
+        throw new Error(`the store worker has no op '${op}'`);
+    return run(...args);
+}
+async function answer(ops, stores, hippoRoot, job) {
+    const failuresBefore = auditWriteFailureCount();
+    stores.requestId = job.requestId;
+    stores.walPages = job.walPages;
+    stores.jobId = job.id;
+    try {
+        const value = await requestScopes.run(stores, () => (job.op === STORE_SETUP_OP ? initStore(hippoRoot) : runOp(ops, job.op, job.args)));
+        return { id: job.id, ok: true, value, auditFailures: auditWriteFailureCount() - failuresBefore };
+    }
+    catch (err) {
+        return { id: job.id, ok: false, error: encodeError(err), auditFailures: auditWriteFailureCount() - failuresBefore };
+    }
+}
+function post(port, reply) {
+    try {
+        port.postMessage(reply, reply.ok && reply.value instanceof PackedVectors ? [reply.value.buffer] : []);
+    }
+    catch (err) {
+        // A result that cannot be copied to the server thread must still answer, or its caller would wait for ever.
+        port.postMessage({ id: reply.id, ok: false, error: encodeError(err), auditFailures: reply.auditFailures });
+    }
+}
+/** Answers the thread's jobs until 'stop', which closes the connection so the thread ends with no handle on the store's files. */
+export function serveJobs(port, init) {
+    const ops = workerOps(init.hippoRoot);
+    const stores = new WorkerStores(init);
+    // A thread is sent one job at a time, so only 'stop' can arrive while a vector scan yields, and it waits for that job's reply.
+    let last = Promise.resolve();
+    port.on('message', (message) => {
+        if (message === 'stop') {
+            void last.then(() => {
+                stores.close();
+                port.close();
+            });
+            return;
+        }
+        last = answer(ops, stores, init.hippoRoot, message).then((reply) => post(port, reply));
+    });
+}
+//# sourceMappingURL=worker-jobs.js.map

package/dist/store/sqlite/worker-ops.d.ts

@@ -0,0 +1,124 @@
+import type { HippoStore } from '../port.js';
+import type { WireError } from './error-codec.js';
+/** 'write' runs on the one writer thread; 'read' on a reader, whose connection refuses every write. */
+export type OpMode = 'read' | 'write';
+/** 'server' keeps a method on the calling thread: it takes a function, and a function cannot be copied to a thread. */
+export type OpPlace = OpMode | 'server';
+export type OpPlaces<G> = {
+    readonly [M in keyof G]: OpPlace;
+};
+/** The store methods that answer from a worker, the base ones under `base`. Tagged by effect, not by name: predictionBaserate appends an audit row and
+ *  bumpRecallStats rewrites stats.json, so both are writes. A read that opens through `openStore` is a read: the writer runs that open's setup before any reader serves. */
+export declare const WORKER_OPS: {
+    readonly base: {
+        readonly findApiKey: "read";
+        readonly searchRecallEntries: "read";
+        readonly entriesByIds: "read";
+        readonly activeGoals: "read";
+        readonly freshRawEntries: "read";
+        readonly continuity: "read";
+        readonly planningFallacyEvidence: "read";
+        readonly appendAuditEvents: "write";
+        readonly finishRecall: "write";
+        readonly bumpRecallStats: "write";
+        readonly recordTokens: "write";
+    };
+    readonly vectors: {
+        readonly embeddingIndexState: "read";
+        readonly storedVectors: "read";
+        readonly nearestEntries: "read";
+        readonly physicsParticles: "read";
+    };
+    readonly vectorViews: {
+        readonly storedVectorViews: "read";
+    };
+    readonly keyAudit: {
+        readonly revokeApiKey: "write";
+        readonly auditEventsAfter: "read";
+        readonly auditHighId: "read";
+    };
+    readonly keyWrites: {
+        readonly createApiKey: "write";
+        readonly createSelfApiKey: "write";
+        readonly listApiKeys: "read";
+    };
+    readonly vectorWrites: {
+        readonly entriesWithoutVector: "read";
+        readonly writeVectors: "write";
+    };
+    readonly entryWrites: {
+        readonly writeEntry: "write";
+        readonly applyOutcome: "write";
+        readonly supersede: "write";
+        readonly archiveRaw: "write";
+        readonly forget: "write";
+    };
+    readonly contextReads: {
+        readonly unfinishedHandoff: "read";
+        readonly ambientCandidates: "server";
+        readonly contextCandidates: "read";
+        readonly ambientTallies: "read";
+    };
+    readonly predictions: {
+        readonly savePrediction: "write";
+        readonly closePrediction: "write";
+        readonly predictionById: "read";
+        readonly listPredictions: "read";
+        readonly predictionBaserate: "write";
+    };
+    readonly dagReads: {
+        readonly sessionRawEntries: "read";
+        readonly sessionRawCount: "read";
+        readonly summaryWithDescendants: "server";
+    };
+    readonly auditLog: {
+        readonly listAuditEvents: "read";
+    };
+    readonly quarantine: {
+        readonly listQuarantined: "read";
+        readonly approveQuarantined: "write";
+        readonly rejectQuarantined: "write";
+    };
+    readonly graphReads: {
+        readonly graphRows: "read";
+    };
+    readonly readiness: {
+        readonly ping: "read";
+    };
+};
+/** Sent by the executor itself and by no store method: the writer runs the store's open-time setup once, before any reader is sent a job. */
+export declare const STORE_SETUP_OP = "setup";
+export type WorkerGroup = keyof typeof WORKER_OPS;
+/** The base methods the op table names. */
+export type WorkerBase = Pick<HippoStore, keyof typeof WORKER_OPS.base>;
+export interface WorkerInit {
+    readonly hippoRoot: string;
+    readonly mode: OpMode;
+    /** Lock wait of the thread's connection. */
+    readonly busyWaitMs: number;
+    /** One shared integer the writer sets to a job's id before that job may commit; the server thread reads it when the job passes its deadline. */
+    readonly commitFlag?: SharedArrayBuffer;
+}
+export interface Job {
+    readonly id: number;
+    /** `<group>.<method>` of the synchronous store, `base.<method>` for a base one. */
+    readonly op: string;
+    readonly args: readonly unknown[];
+    /** Of the request the call belongs to, so the thread's log lines carry it. */
+    readonly requestId: string | undefined;
+    /** wal_autocheckpoint as the server thread has it: a worker cannot see the checkpointer start or stop. */
+    readonly walPages: number;
+}
+/** Both kinds carry the audit rows the job failed to write, since the count `/health` reports lives on the server thread. */
+export type Reply = {
+    readonly id: number;
+    readonly ok: true;
+    readonly value: unknown;
+    readonly auditFailures: number;
+} | {
+    readonly id: number;
+    readonly ok: false;
+    readonly error: WireError;
+    readonly auditFailures: number;
+};
+//# sourceMappingURL=worker-ops.d.ts.map