@haverstack/server 0.8.0 → 0.9.0

package/{src/lib/queryLimit.ts → dist/lib/queryLimit.js}

@@ -1,11 +1,10 @@
-import type { StackQuery } from '@haverstack/core';
-
 // core's parsers (@haverstack/core/wire) report `limit` as requested and
 // never clamp it — a ceiling is deployment policy, not wire contract. This
 // server's ceiling, applied at the call site in records.ts.
 export const MAX_QUERY_LIMIT = 1000;
-
-export function clampLimit(query: StackQuery): StackQuery {
-  if (query.limit === undefined) return query;
-  return { ...query, limit: Math.min(query.limit, MAX_QUERY_LIMIT) };
+export function clampLimit(query) {
+    if (query.limit === undefined)
+        return query;
+    return { ...query, limit: Math.min(query.limit, MAX_QUERY_LIMIT) };
 }
+//# sourceMappingURL=queryLimit.js.map

package/dist/lib/queryLimit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queryLimit.js","sourceRoot":"","sources":["../../src/lib/queryLimit.ts"],"names":[],"mappings":"AAEA,yEAAyE;AACzE,2EAA2E;AAC3E,4DAA4D;AAC5D,MAAM,CAAC,MAAM,eAAe,GAAG,IAAI,CAAC;AAEpC,MAAM,UAAU,UAAU,CAAC,KAAiB;IAC1C,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IAC5C,OAAO,EAAE,GAAG,KAAK,EAAE,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,EAAE,eAAe,CAAC,EAAE,CAAC;AACrE,CAAC"}

package/dist/lib/queryWorker/pool.d.ts

@@ -0,0 +1,60 @@
+import type { StackQuery, QueryResult, TokenSession } from '@haverstack/core';
+import type { Logger } from 'pino';
+import type { QueryWorkerInit } from './protocol.js';
+export type QueryWorkerPoolOptions = {
+    init: QueryWorkerInit;
+    poolSize: number;
+    /** Maximum requests waiting for a slot before the pool sheds load. */
+    queueLimit: number;
+    logger: Logger;
+    /**
+     * Worker entry point. Defaults to this directory's worker; overridable
+     * so tests can drive the pool with a fixture worker whose timing they
+     * control, rather than inferring pool behavior from real query latency.
+     */
+    workerUrl?: URL;
+};
+export declare class QueryWorkerPool {
+    private readonly slots;
+    private readonly pending;
+    /** FIFO of requests waiting for a slot to free up. */
+    private readonly waiting;
+    private nextId;
+    private closed;
+    private consecutiveFailures;
+    private lastFailure;
+    private readonly init;
+    private readonly queueLimit;
+    private readonly logger;
+    private readonly workerUrl;
+    constructor(opts: QueryWorkerPoolOptions);
+    /**
+     * True once every recent spawn attempt has failed — a standing fault
+     * (bad DB_PATH, unreadable file) rather than one unlucky crash.
+     */
+    private get unhealthy();
+    private startWorker;
+    private handleMessage;
+    /**
+     * A worker crashed or exited on its own — not a deadline recycle, which
+     * is deliberate and handled by recycleSlot() without backoff.
+     */
+    private handleWorkerDeath;
+    /** Deliberate recycle after a deadline: capacity is restored at once, no backoff. */
+    private recycleSlot;
+    private teardown;
+    private scheduleRespawn;
+    private failQueued;
+    private drainWaiting;
+    /** Hand a request to a worker and start its execution clock — see the module doc. */
+    private startExecution;
+    private onDeadline;
+    /**
+     * Run a query on the pool. `deadlineMs` bounds execution only; a request
+     * that waits for a slot waits without penalty, until the queue itself is
+     * full.
+     */
+    query(session: TokenSession | null, stackQuery: StackQuery, deadlineMs: number): Promise<QueryResult>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=pool.d.ts.map

package/dist/lib/queryWorker/pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pool.d.ts","sourceRoot":"","sources":["../../../src/lib/queryWorker/pool.ts"],"names":[],"mappings":"AA0CA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAG9E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AACnC,OAAO,KAAK,EAA+B,eAAe,EAAE,MAAM,eAAe,CAAC;AAgClF,MAAM,MAAM,sBAAsB,GAAG;IACnC,IAAI,EAAE,eAAe,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,sEAAsE;IACtE,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,SAAS,CAAC,EAAE,GAAG,CAAC;CACjB,CAAC;AAEF,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAc;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA8B;IACtD,sDAAsD;IACtD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgD;IACxE,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,mBAAmB,CAAK;IAChC,OAAO,CAAC,WAAW,CAAsB;IAEzC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAkB;IACvC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAM;gBAEpB,IAAI,EAAE,sBAAsB;IAYxC;;;OAGG;IACH,OAAO,KAAK,SAAS,GAEpB;IAED,OAAO,CAAC,WAAW;IAqBnB,OAAO,CAAC,aAAa;IAmBrB;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IA4BzB,qFAAqF;IACrF,OAAO,CAAC,WAAW;IAMnB,OAAO,CAAC,QAAQ;IAShB,OAAO,CAAC,eAAe;IAQvB,OAAO,CAAC,UAAU;IAUlB,OAAO,CAAC,YAAY;IAepB,qFAAqF;IACrF,OAAO,CAAC,cAAc;IAMtB,OAAO,CAAC,UAAU;IAWlB;;;;OAIG;IACH,KAAK,CACH,OAAO,EAAE,YAAY,GAAG,IAAI,EAC5B,UAAU,EAAE,UAAU,EACtB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,WAAW,CAAC;IAyBjB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAuB7B"}

package/dist/lib/queryWorker/pool.js

@@ -0,0 +1,278 @@
+/**
+ * Main-thread side of the query worker boundary. Owns a small, fixed-size
+ * pool of workers (src/lib/queryWorker/worker.ts), each with its own
+ * LocalAdapter connection to the same stack.db, and dispatches
+ * ScopedStack.query() calls to them. The operator-facing account of why
+ * this exists is docs/deployment.md § Bounding query cost.
+ *
+ * Two bounds, deliberately not one:
+ *
+ *   - `deadlineMs` bounds **execution**, and its clock starts when a
+ *     request reaches a worker, not when it was accepted here. Execution
+ *     is the only part that needs bounding: node:sqlite exposes no
+ *     `sqlite3_interrupt` equivalent, so a query already inside the engine
+ *     cannot be cancelled in place. Queueing makes a request slow, never
+ *     failed.
+ *
+ *   - `queueLimit` bounds **the wait**, so "slow" cannot quietly become
+ *     unbounded in latency or retained memory. Past it the pool sheds load
+ *     with StackTimeoutError — a retryable 503, which is honest about
+ *     overload in a way a silently growing queue is not.
+ *
+ * Past its deadline the only lever left is termination: the caller is
+ * answered at once and the worker is terminated and replaced, so a stuck
+ * query costs one slot rather than wedging the pool. That recycle needs no
+ * backoff, being rate-limited by construction at `poolSize` terminations
+ * per `deadlineMs`.
+ *
+ * An *unexpected* death is the opposite case and does back off: respawning
+ * a worker that can't boot — an unreadable DB_PATH, say — as fast as the
+ * loop allows would spin threads and flood logs. After
+ * MAX_CONSECUTIVE_SPAWN_FAILURES the pool reports itself unhealthy and
+ * fails queries with the underlying spawn error, so a fatal
+ * misconfiguration surfaces as itself rather than as a pile of timeouts.
+ * Respawns continue at the capped interval, so the pool heals once the
+ * cause clears.
+ *
+ * Terminating mid-write is safe: WAL journaling leaves an uncommitted
+ * transaction simply absent once the file is reopened. Only query() routes
+ * through this pool — src/routes/records.ts holds the reason writes and
+ * by-id reads stay on the main thread.
+ */
+import { Worker } from 'node:worker_threads';
+import { StackTimeoutError } from '@haverstack/core';
+import { deserializeError } from '@haverstack/wire-types';
+// import.meta.url ends in .ts under tsx (dev) and vitest (test), and in
+// .js once tsc has compiled this file into dist/ — so which worker file
+// and loader to use falls out of how *this* module was loaded, with no
+// separate NODE_ENV check to keep in sync.
+const RUNNING_FROM_SOURCE = import.meta.url.endsWith('.ts');
+const WORKER_URL = new URL(RUNNING_FROM_SOURCE ? './worker.ts' : './worker.js', import.meta.url);
+const WORKER_EXEC_ARGV = RUNNING_FROM_SOURCE ? ['--import', 'tsx'] : [];
+/** Backoff schedule for respawning a worker that died unexpectedly. */
+const RESPAWN_BASE_DELAY_MS = 100;
+const RESPAWN_MAX_DELAY_MS = 30_000;
+/** Consecutive unexpected deaths after which the pool reports itself unhealthy. */
+const MAX_CONSECUTIVE_SPAWN_FAILURES = 5;
+export class QueryWorkerPool {
+    slots = [];
+    pending = new Map();
+    /** FIFO of requests waiting for a slot to free up. */
+    waiting = [];
+    nextId = 1;
+    closed = false;
+    consecutiveFailures = 0;
+    lastFailure = null;
+    init;
+    queueLimit;
+    logger;
+    workerUrl;
+    constructor(opts) {
+        this.init = opts.init;
+        this.queueLimit = opts.queueLimit;
+        this.logger = opts.logger;
+        this.workerUrl = opts.workerUrl ?? WORKER_URL;
+        for (let i = 0; i < opts.poolSize; i++) {
+            const slot = { worker: null, busyWith: null, respawnTimer: null };
+            this.slots.push(slot);
+            this.startWorker(slot);
+        }
+    }
+    /**
+     * True once every recent spawn attempt has failed — a standing fault
+     * (bad DB_PATH, unreadable file) rather than one unlucky crash.
+     */
+    get unhealthy() {
+        return this.consecutiveFailures >= MAX_CONSECUTIVE_SPAWN_FAILURES;
+    }
+    startWorker(slot) {
+        if (this.closed)
+            return;
+        slot.respawnTimer = null;
+        const worker = new Worker(this.workerUrl, {
+            workerData: this.init,
+            execArgv: WORKER_EXEC_ARGV,
+        });
+        slot.worker = worker;
+        slot.busyWith = null;
+        worker.on('message', (msg) => this.handleMessage(slot, msg));
+        worker.on('error', (err) => this.handleWorkerDeath(slot, err));
+        worker.on('exit', (code) => {
+            if (!this.closed && code !== 0) {
+                this.handleWorkerDeath(slot, new Error(`query worker exited with code ${code}`));
+            }
+        });
+        // postMessage before a worker finishes booting is fine — worker_threads
+        // queues it until the thread installs its listener.
+        this.drainWaiting(slot);
+    }
+    handleMessage(slot, msg) {
+        // A worker that answers is a working worker: clear any standing
+        // failure state so an earlier rough patch can't leave the pool
+        // permanently marked unhealthy.
+        this.consecutiveFailures = 0;
+        this.lastFailure = null;
+        slot.busyWith = null;
+        const pending = this.pending.get(msg.id);
+        // Already timed out (and rejected) before the worker answered — the
+        // late reply just frees the slot, above.
+        if (pending) {
+            this.pending.delete(msg.id);
+            if (pending.timer)
+                clearTimeout(pending.timer);
+            if (msg.ok)
+                pending.resolve(msg.result);
+            else
+                pending.reject(msg.wire ? deserializeError(msg.wire.body) : new Error(msg.message));
+        }
+        this.drainWaiting(slot);
+    }
+    /**
+     * A worker crashed or exited on its own — not a deadline recycle, which
+     * is deliberate and handled by recycleSlot() without backoff.
+     */
+    handleWorkerDeath(slot, err) {
+        const failedId = slot.busyWith;
+        if (failedId !== null) {
+            const pending = this.pending.get(failedId);
+            if (pending) {
+                this.pending.delete(failedId);
+                if (pending.timer)
+                    clearTimeout(pending.timer);
+                pending.reject(err);
+            }
+        }
+        this.teardown(slot);
+        this.consecutiveFailures++;
+        this.lastFailure = err;
+        const delay = Math.min(RESPAWN_BASE_DELAY_MS * 2 ** (this.consecutiveFailures - 1), RESPAWN_MAX_DELAY_MS);
+        this.logger.error({ err, consecutiveFailures: this.consecutiveFailures, retryInMs: delay }, 'Query worker died unexpectedly; respawning after backoff');
+        // Nothing is going to serve the queue any time soon — answer it with
+        // the real cause instead of letting it wait out a fault that isn't
+        // going to clear on its own.
+        if (this.unhealthy)
+            this.failQueued(err);
+        this.scheduleRespawn(slot, delay);
+    }
+    /** Deliberate recycle after a deadline: capacity is restored at once, no backoff. */
+    recycleSlot(slot) {
+        if (this.closed)
+            return;
+        this.teardown(slot);
+        this.startWorker(slot);
+    }
+    teardown(slot) {
+        const worker = slot.worker;
+        slot.worker = null;
+        slot.busyWith = null;
+        if (!worker)
+            return;
+        worker.removeAllListeners();
+        void worker.terminate().catch(() => { });
+    }
+    scheduleRespawn(slot, delay) {
+        if (this.closed)
+            return;
+        if (slot.respawnTimer)
+            clearTimeout(slot.respawnTimer);
+        slot.respawnTimer = setTimeout(() => this.startWorker(slot), delay);
+        // A pending respawn must not by itself keep the process alive.
+        slot.respawnTimer.unref();
+    }
+    failQueued(err) {
+        for (const { id } of this.waiting.splice(0)) {
+            const pending = this.pending.get(id);
+            if (!pending)
+                continue;
+            this.pending.delete(id);
+            if (pending.timer)
+                clearTimeout(pending.timer);
+            pending.reject(err);
+        }
+    }
+    drainWaiting(slot) {
+        if (this.closed || !slot.worker || slot.busyWith !== null)
+            return;
+        // Looped, not recursive: a long run of already-abandoned queue entries
+        // shouldn't cost stack depth.
+        for (;;) {
+            const next = this.waiting.shift();
+            if (!next)
+                return;
+            const pending = this.pending.get(next.id);
+            // Abandoned while queued (pool went unhealthy, or close()).
+            if (!pending)
+                continue;
+            this.startExecution(slot, next.id, next.req, pending);
+            return;
+        }
+    }
+    /** Hand a request to a worker and start its execution clock — see the module doc. */
+    startExecution(slot, id, req, pending) {
+        pending.timer = setTimeout(() => this.onDeadline(id), pending.deadlineMs);
+        slot.busyWith = id;
+        slot.worker.postMessage(req);
+    }
+    onDeadline(id) {
+        const pending = this.pending.get(id);
+        if (!pending)
+            return;
+        this.pending.delete(id);
+        pending.reject(new StackTimeoutError(`Query exceeded the ${pending.deadlineMs}ms execution deadline`));
+        const slot = this.slots.find((s) => s.busyWith === id);
+        if (slot)
+            this.recycleSlot(slot);
+    }
+    /**
+     * Run a query on the pool. `deadlineMs` bounds execution only; a request
+     * that waits for a slot waits without penalty, until the queue itself is
+     * full.
+     */
+    query(session, stackQuery, deadlineMs) {
+        if (this.closed)
+            return Promise.reject(new Error('Query worker pool is closed'));
+        // A standing spawn fault is a server fault, not a slow query: report
+        // the cause rather than making every caller wait out a deadline.
+        if (this.unhealthy) {
+            return Promise.reject(this.lastFailure ?? new Error('Query worker pool is unavailable'));
+        }
+        if (this.waiting.length >= this.queueLimit) {
+            return Promise.reject(new StackTimeoutError(`Query queue is full (${this.queueLimit} waiting); the server is shedding load rather than queueing further`));
+        }
+        const id = this.nextId++;
+        const req = { id, session, query: stackQuery };
+        return new Promise((resolve, reject) => {
+            const pending = { resolve, reject, deadlineMs, timer: null };
+            this.pending.set(id, pending);
+            const idle = this.slots.find((s) => s.worker !== null && s.busyWith === null);
+            if (idle)
+                this.startExecution(idle, id, req, pending);
+            else
+                this.waiting.push({ id, req });
+        });
+    }
+    async close() {
+        this.closed = true;
+        for (const pending of this.pending.values()) {
+            if (pending.timer)
+                clearTimeout(pending.timer);
+            pending.reject(new Error('Query worker pool is closing'));
+        }
+        this.pending.clear();
+        this.waiting.length = 0;
+        await Promise.all(this.slots.map(async (slot) => {
+            if (slot.respawnTimer) {
+                clearTimeout(slot.respawnTimer);
+                slot.respawnTimer = null;
+            }
+            const worker = slot.worker;
+            slot.worker = null;
+            slot.busyWith = null;
+            if (!worker)
+                return;
+            worker.removeAllListeners();
+            await worker.terminate();
+        }));
+    }
+}
+//# sourceMappingURL=pool.js.map

package/dist/lib/queryWorker/pool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pool.js","sourceRoot":"","sources":["../../../src/lib/queryWorker/pool.ts"],"names":[],"mappings":"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"}

package/{src/lib/queryWorker/protocol.ts → dist/lib/queryWorker/protocol.d.ts}

@@ -9,7 +9,6 @@
  */
 import type { StackQuery, QueryResult, TokenSession } from '@haverstack/core';
 import type { WireError } from '@haverstack/wire-types';
-
 /**
  * Passed as `workerData` when a query worker is spawned. dbPath is the
  * whole of it: a worker calls LocalAdapter.open(), which reads timezone
@@ -17,23 +16,27 @@ import type { WireError } from '@haverstack/wire-types';
  * the initialize path takes one as input, and workers never initialize.
  */
 export type QueryWorkerInit = {
-  dbPath: string;
+    dbPath: string;
 };
-
 export type QueryRequest = {
-  id: number;
-  /** null = anonymous (Stack.asEntity(null)), matching records.ts's scopeFor(). */
-  session: TokenSession | null;
-  query: StackQuery;
+    id: number;
+    /** null = anonymous (Stack.asEntity(null)), matching records.ts's scopeFor(). */
+    session: TokenSession | null;
+    query: StackQuery;
 };
-
-export type QueryResponse =
-  | { id: number; ok: true; result: QueryResult }
-  | {
-      id: number;
-      ok: false;
-      /** Set when the failure is a StackError with a wire mapping; reconstructed via deserializeError(). */
-      wire: { status: number; body: WireError } | null;
-      /** Always set, for logging — the only signal left when `wire` is null (an unanticipated bug). */
-      message: string;
-    };
+export type QueryResponse = {
+    id: number;
+    ok: true;
+    result: QueryResult;
+} | {
+    id: number;
+    ok: false;
+    /** Set when the failure is a StackError with a wire mapping; reconstructed via deserializeError(). */
+    wire: {
+        status: number;
+        body: WireError;
+    } | null;
+    /** Always set, for logging — the only signal left when `wire` is null (an unanticipated bug). */
+    message: string;
+};
+//# sourceMappingURL=protocol.d.ts.map

package/dist/lib/queryWorker/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../../../src/lib/queryWorker/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAC9E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAExD;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,iFAAiF;IACjF,OAAO,EAAE,YAAY,GAAG,IAAI,CAAC;IAC7B,KAAK,EAAE,UAAU,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,aAAa,GACrB;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,WAAW,CAAA;CAAE,GAC7C;IACE,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,KAAK,CAAC;IACV,sGAAsG;IACtG,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,SAAS,CAAA;KAAE,GAAG,IAAI,CAAC;IACjD,iGAAiG;IACjG,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC"}

package/dist/lib/queryWorker/protocol.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=protocol.js.map

package/dist/lib/queryWorker/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../../src/lib/queryWorker/protocol.ts"],"names":[],"mappings":""}

package/dist/lib/queryWorker/worker.d.ts

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

package/dist/lib/queryWorker/worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../../../src/lib/queryWorker/worker.ts"],"names":[],"mappings":""}

package/{src/lib/queryWorker/worker.ts → dist/lib/queryWorker/worker.js}

@@ -18,34 +18,31 @@ import { parentPort, workerData } from 'node:worker_threads';
 import { LocalAdapter } from '@haverstack/adapter-local';
 import { Stack } from '@haverstack/core';
 import { serializeError } from '@haverstack/wire-types';
-import type { QueryRequest, QueryResponse, QueryWorkerInit } from './protocol.js';
-
 if (!parentPort) {
-  throw new Error('query worker must be run as a worker_thread, not the main thread');
+    throw new Error('query worker must be run as a worker_thread, not the main thread');
 }
-
-const init = workerData as QueryWorkerInit;
-
+const init = workerData;
 // The database already exists — the main thread's initStack() created or
 // opened it, and seeded system types, before any worker is spawned (see
 // pool.ts). open() (not openOrInitialize()) reflects that: there is no
 // first-run path to handle here.
 const adapter = await LocalAdapter.open({ path: init.dbPath });
 const stack = await Stack.create(adapter);
-
-parentPort.on('message', async (req: QueryRequest) => {
-  const port = parentPort!;
-  try {
-    const scoped = req.session ? stack.forSession(req.session) : stack.asEntity(null);
-    const result = await scoped.query(req.query);
-    port.postMessage({ id: req.id, ok: true, result } satisfies QueryResponse);
-  } catch (err) {
-    const wire = serializeError(err);
-    port.postMessage({
-      id: req.id,
-      ok: false,
-      wire,
-      message: err instanceof Error ? err.message : String(err),
-    } satisfies QueryResponse);
-  }
+parentPort.on('message', async (req) => {
+    const port = parentPort;
+    try {
+        const scoped = req.session ? stack.forSession(req.session) : stack.asEntity(null);
+        const result = await scoped.query(req.query);
+        port.postMessage({ id: req.id, ok: true, result });
+    }
+    catch (err) {
+        const wire = serializeError(err);
+        port.postMessage({
+            id: req.id,
+            ok: false,
+            wire,
+            message: err instanceof Error ? err.message : String(err),
+        });
+    }
 });
+//# sourceMappingURL=worker.js.map

package/dist/lib/queryWorker/worker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.js","sourceRoot":"","sources":["../../../src/lib/queryWorker/worker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAGxD,IAAI,CAAC,UAAU,EAAE,CAAC;IAChB,MAAM,IAAI,KAAK,CAAC,kEAAkE,CAAC,CAAC;AACtF,CAAC;AAED,MAAM,IAAI,GAAG,UAA6B,CAAC;AAE3C,yEAAyE;AACzE,wEAAwE;AACxE,uEAAuE;AACvE,iCAAiC;AACjC,MAAM,OAAO,GAAG,MAAM,YAAY,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;AAC/D,MAAM,KAAK,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;AAE1C,UAAU,CAAC,EAAE,CAAC,SAAS,EAAE,KAAK,EAAE,GAAiB,EAAE,EAAE;IACnD,MAAM,IAAI,GAAG,UAAW,CAAC;IACzB,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QAClF,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAC7C,IAAI,CAAC,WAAW,CAAC,EAAE,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAA0B,CAAC,CAAC;IAC7E,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,GAAG,cAAc,CAAC,GAAG,CAAC,CAAC;QACjC,IAAI,CAAC,WAAW,CAAC;YACf,EAAE,EAAE,GAAG,CAAC,EAAE;YACV,EAAE,EAAE,KAAK;YACT,IAAI;YACJ,OAAO,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;SAClC,CAAC,CAAC;IAC7B,CAAC;AACH,CAAC,CAAC,CAAC"}

package/dist/lib/resumeBuffer.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Per-(session, filter) resume buffers for GET /changes. Sits downstream
+ * of each connection's `ScopedStack.subscribe()`, so every entry here is a
+ * frame that subscription already delivered — something this session was
+ * cleared to see at the moment it happened. That is what keeps replay a
+ * pure re-send needing nothing from core, where a single server-wide
+ * buffer would owe a permission check per frame per reader.
+ *
+ * A buffer mints its own cursors (its position is a private counter, not a
+ * slice of some global sequence) and is fed independently of any one HTTP
+ * connection: it keeps collecting for a bounded window *after* the last
+ * connection using it disconnects, which is what lets a reconnect learn
+ * about changes made while nobody was listening. Depth-bounded on top of
+ * that: a session that stays away long enough to overflow the ring gets
+ * `overflow` rather than a silently incomplete replay.
+ */
+import type { ChangeFilter, RecordChange, Unsubscribe } from '@haverstack/core';
+import type { WireRecordChange } from '@haverstack/wire-types';
+export type ResumeEntry = {
+    n: number;
+    recordId: string;
+    isPurge: boolean;
+    /** Wire-ready, seq already attached. */
+    frame: WireRecordChange;
+};
+export type EntriesAfterResult = {
+    status: 'ok';
+    entries: ResumeEntry[];
+}
+/** The buffer is the right one, but depth eviction already dropped what would be needed. */
+ | {
+    status: 'overflow';
+}
+/** A position this buffer never held, or no longer holds any record of. */
+ | {
+    status: 'cursor_expired';
+};
+/** One session+filter's resume buffer. Data and notification only — lifecycle lives in the registry. */
+export declare class ResumeBuffer {
+    private readonly depth;
+    readonly id: string;
+    private readonly entries;
+    private currentN;
+    private evictedUpTo;
+    private readonly listeners;
+    /** Connections currently holding this buffer open. Registry-managed. */
+    liveCount: number;
+    /** Set by the registry when liveCount drops to 0; cleared on reacquire. */
+    disconnectedAt: number | null;
+    constructor(depth: number);
+    /** The cursor naming this buffer's current position — what `ready` reports. */
+    headCursor(): string;
+    /**
+     * Record one already-permission-filtered change, minting its cursor.
+     * Notifies every currently attached live connection with the same frame
+     * a replay would later produce.
+     */
+    append(change: RecordChange): ResumeEntry;
+    /** Attach a live connection. Returns the detach function. */
+    subscribeLive(listener: (entry: ResumeEntry) => void): () => void;
+    /**
+     * Everything after position `n`, or why that can't be answered. `n` is
+     * this server's own minted position, already decoded and matched to
+     * this buffer's id by the caller.
+     */
+    entriesAfter(n: number): EntriesAfterResult;
+}
+export type ResumeBufferKeyParts = {
+    /** Both null for an anonymous connection. */
+    principalId: string | null;
+    subjectId: string | null;
+    filter: ChangeFilter;
+    includeRecords: boolean;
+    includeUnlisted: boolean;
+};
+/**
+ * Reproducible across a reconnect that re-sends the same query params —
+ * order-independent on the parts of `filter` that don't carry order of
+ * their own (`typeId`/`kinds` are matched as sets, not sequences, so
+ * re-sending them in a different order must key the same buffer).
+ *
+ * Two filters that mean different things must never key the same buffer.
+ * A buffer opens exactly one `ScopedStack.subscribe()`, carrying the
+ * filter of whichever connection minted it, so a collision hands one of
+ * the two colliding connections the *other's* filter: either a silent gap
+ * (events it asked for and never hears about, with no `reset` to tell it
+ * so) or frames outside its filter, which "filtering is exact, not
+ * advisory" forbids. See docs/spec/wire-format.md § Change feed.
+ *
+ * Hence an object rather than a positional array: `JSON.stringify` drops
+ * an undefined *property* but renders an undefined *array element* as
+ * `null`, which would collapse "no parentId filter" onto `parentId: null`
+ * — "root records only", a filter the wire format defines. An absent part
+ * is an absent key, which no present value can imitate. Key order is fixed
+ * by construction below.
+ */
+export declare function resumeBufferKey(parts: ResumeBufferKeyParts): string;
+export type ResumeBufferRegistryOptions = {
+    /** Max entries retained per buffer before the oldest is dropped. */
+    depth: number;
+    /** How long a buffer keeps being fed after its last connection disconnects, before it's dropped entirely. */
+    retentionMs: number;
+};
+/**
+ * Owns every live resume buffer, keyed by (session, filter, includeRecords).
+ * A buffer's underlying `ScopedStack.subscribe()` is opened once, when the
+ * buffer is first minted, and kept open — including across a gap with zero
+ * live connections — until the buffer itself is evicted.
+ */
+export declare class ResumeBufferRegistry {
+    private readonly opts;
+    private readonly buffers;
+    private readonly unsubscribes;
+    private readonly evictionTimers;
+    /**
+     * Buffers whose subscription is still opening. A key lands in `buffers`
+     * only once its `ScopedStack.subscribe()` has resolved, so this is what
+     * keeps two connections arriving in the same tick from opening two
+     * subscriptions for one key — they await the same attempt and share
+     * whichever way it settles.
+     */
+    private readonly acquiring;
+    constructor(opts: ResumeBufferRegistryOptions);
+    /**
+     * Get this key's buffer, creating one and opening its scoped subscription
+     * if none is currently retained. `subscribeToStack` is called at most
+     * once per buffer instance.
+     *
+     * A failed subscription registers nothing: the next connection on this
+     * key retries it. Registering a buffer that nothing is feeding would
+     * hand every later connection on that key a `ready` frame followed by
+     * permanent silence — a gap with no `reset` to announce it, which is
+     * the one failure the feed contract calls untrustworthy.
+     */
+    acquire(key: string, subscribeToStack: (onChange: (change: RecordChange) => void) => Promise<Unsubscribe>): Promise<ResumeBuffer>;
+    /** Detach one connection from this key's buffer, starting its retention countdown once none remain. */
+    release(key: string): void;
+    private cancelEviction;
+    private evict;
+    /** Tear down every retained buffer immediately — for shutdown. */
+    closeAll(): void;
+}
+//# sourceMappingURL=resumeBuffer.d.ts.map