toolroll 0.9.47 → 0.9.48

package/dist/read-executor.js

@@ -0,0 +1,119 @@
+import { Worker } from 'node:worker_threads';
+import { availableParallelism } from 'node:os';
+import { WorkIndexCursorError } from './work-index.js';
+/** More queued reads than this fail at once instead of growing without bound. */
+export const READ_QUEUE_MAX = 1_000;
+export class ReadExecutorError extends Error {
+    constructor(message) { super(message); this.name = 'ReadExecutorError'; }
+}
+export class ReadExecutor {
+    #file;
+    #size;
+    #slots = [];
+    #queue = [];
+    #next = 1;
+    #closed = false;
+    constructor(file, size = defaultReadWorkers()) {
+        this.#file = file;
+        this.#size = Math.max(1, Math.floor(size));
+    }
+    get size() { return this.#size; }
+    /** workIndexPage(store, now, access, options) on a worker's read-only connection: same rows, same errors. */
+    async workIndexPage(now, access, options) {
+        try {
+            return await this.#run({ kind: 'work-index-page', now: now.toISOString(), access, options });
+        }
+        catch (error) {
+            if (error instanceof Error && error.name === 'WorkIndexCursorError')
+                throw new WorkIndexCursorError();
+            throw error;
+        }
+    }
+    #run(job) {
+        if (this.#closed)
+            return Promise.reject(new ReadExecutorError('The server is closing.'));
+        if (this.#queue.length >= READ_QUEUE_MAX)
+            return Promise.reject(new ReadExecutorError('The server is too busy to read this now; try again shortly.'));
+        return new Promise((resolve, reject) => {
+            this.#queue.push({ id: this.#next++, job, resolve, reject });
+            this.#pump();
+        });
+    }
+    #pump() {
+        while (this.#queue.length > 0) {
+            let slot = this.#slots.find(one => one.busy === null);
+            if (slot === undefined && this.#slots.length < this.#size)
+                slot = this.#spawn();
+            if (slot === undefined)
+                return;
+            const pending = this.#queue.shift();
+            slot.busy = pending;
+            slot.worker.postMessage({ id: pending.id, job: pending.job });
+        }
+    }
+    #spawn() {
+        // The installed server runs the built sibling; tests run the TypeScript source through tsx.
+        const worker = import.meta.url.endsWith('.ts')
+            ? new Worker(`import('tsx/esm/api').then(tsx => { tsx.register(); return import(${JSON.stringify(new URL('./read-executor-worker.ts', import.meta.url).href)}); });`, { eval: true, workerData: { file: this.#file } })
+            : new Worker(new URL('./read-executor-worker.js', import.meta.url), { workerData: { file: this.#file } });
+        const slot = { worker, busy: null };
+        this.#slots.push(slot);
+        worker.on('message', (reply) => {
+            const pending = slot.busy;
+            if (pending === null || pending.id !== reply.id)
+                return;
+            slot.busy = null;
+            if (reply.ok)
+                pending.resolve(reply.value);
+            else
+                pending.reject(Object.assign(new Error(reply.error.message), { name: reply.error.name }));
+            this.#pump();
+        });
+        // A crashed worker fails only the read it held; the next read starts a fresh one.
+        const lost = (error) => {
+            const at = this.#slots.indexOf(slot);
+            if (at < 0)
+                return;
+            this.#slots.splice(at, 1);
+            const pending = slot.busy;
+            slot.busy = null;
+            pending?.reject(error);
+            if (!this.#closed)
+                this.#pump();
+        };
+        worker.on('error', error => lost(error instanceof Error ? error : new ReadExecutorError(String(error))));
+        worker.on('exit', code => lost(new ReadExecutorError(`The read worker stopped (exit ${code}).`)));
+        worker.unref();
+        return slot;
+    }
+    /** Fails every queued and running read once, then stops the workers. */
+    async close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        const stopped = new ReadExecutorError('The server is closing.');
+        for (const pending of this.#queue.splice(0))
+            pending.reject(stopped);
+        const slots = this.#slots.splice(0);
+        for (const slot of slots) {
+            slot.busy?.reject(stopped);
+            slot.busy = null;
+        }
+        await Promise.all(slots.map(slot => slot.worker.terminate().catch(() => 0)));
+    }
+}
+/** Half the cores, at most eight: the measured 20-engineer load needs over four (docs/server-performance.md),
+ * and the rest stay with the event loop and local agents. Workers start only when reads arrive. */
+export function defaultReadWorkers() {
+    return Math.max(1, Math.min(8, Math.floor(availableParallelism() / 2)));
+}
+const attached = new WeakMap();
+/** The server attaches its executor to its own Store; a command run on that Store reads through it. */
+export function attachReadExecutor(store, executor) {
+    attached.set(store, executor);
+    return () => { if (attached.get(store) === executor)
+        attached.delete(store); };
+}
+export function readExecutorOf(store) {
+    return attached.get(store) ?? null;
+}

package/dist/request-budget.d.ts

@@ -88,6 +88,7 @@ export declare class RequestBudget {
      * read. Anything unreadable refuses with 503 and nothing runs.
      */
     admit(tokenId: string, route: BudgetRoute): Admission;
+    private check;
     /** Save every changed entry. A server calls this on a timer and when it closes. */
     flush(): void;
     private save;

package/dist/request-budget.js

@@ -123,6 +123,12 @@ export class RequestBudget {
      * read. Anything unreadable refuses with 503 and nothing runs.
      */
     admit(tokenId, route) {
+        const result = this.check(tokenId, route);
+        if (!result.ok)
+            this.store.telemetry.budgetRefused(route, result.status === 429 ? result.limit : 'unavailable');
+        return result;
+    }
+    check(tokenId, route) {
         try {
             const now = this.clock();
             const token = this.store.apiTokenSecret(tokenId)?.row;

package/dist/serve.d.ts

@@ -33,6 +33,8 @@ export type ServeOptions = {
     installBin?: string;
     /** Native coding workspace injection for isolated integration tests. */
     codingWorkspace?: CodingWorkspace;
+    /** Read-only worker connections for heavy reads (read-executor.ts); 0 reads in-process. Default: off under tests. */
+    readWorkers?: number;
     store: Store;
     evidenceRoot: string;
     clock?: () => Date;

package/dist/serve.js

@@ -44,6 +44,7 @@ import { addRoutine, removeRoutine, runRoutine } from "./teammate-desk.js";
 import { sendTeammateWeeklies, undoCall } from "./teammate-week.js";
 import { answerTeammateQuestion } from "./teammate-work.js";
 import { createFlowRooms, flowFingerprint } from "./flow-live.js";
+import { createLiveBus, followWorkspace } from "./live-bus.js";
 import { createTaskRooms, taskFingerprint } from "./task-live.js";
 import { runActivityOf } from "./task-activity.js";
 import { disconnectGoogle, finishGoogleConsent, GOOGLE_CALLBACK, googleConnected, googleConsent, readGoogleMail, saveGoogleClient } from "./google-mail.js";
@@ -242,6 +243,7 @@ import { createIntegrationMonitor } from "./integrations.js";
 import { BACKUP_CSS, backupHtml } from "./backup-ui.js";
 import { BACKUP_EVERY_HOURS, MAX_KEEP, backupFolderOf, backupNow, checkBackupFolder, defaultBackupFolder } from "./backup.js";
 import { prometheusMetrics } from "./metrics.js";
+import { healthWords, instrumentRequest } from "./server-telemetry.js";
 import { SPEND_CSS, spendCsv, spendHtml } from "./spend-ui.js";
 import { RETENTION_CSS, retentionHtml } from "./retention-ui.js";
 import { STORAGE_CSS, storageHtml } from "./storage-ui.js";
@@ -291,6 +293,7 @@ import { installMethod } from "./install-method.js";
 import { PACKAGE_VERSION } from "./version.js";
 import { updateNoticeWords } from "./update-notice.js";
 import { whenHtml } from "./when-html.js";
+import { ReadExecutor, attachReadExecutor, defaultReadWorkers } from "./read-executor.js";
 const SESSION_COOKIE = "standing-orders_session";
 /** Stands in for "no project" in a ceiling: no folder resolves to it, so it admits nothing. */
 const NO_PROJECT = "/\0no-project";
@@ -460,6 +463,11 @@ export function createDecisionServer(options) {
         }
     }
     const clock = options.clock ?? (() => new Date());
+    // Heavy reads (the work index behind `task list`) run on read-only worker connections, off the request loop.
+    const readFile = store.isDemo() ? null : store.databaseFile();
+    const readWorkers = options.readWorkers ?? (process.env["VITEST"] !== undefined ? 0 : defaultReadWorkers());
+    const reads = readFile === null || readWorkers < 1 ? null : new ReadExecutor(readFile, readWorkers);
+    const detachReads = reads === null ? () => { } : attachReadExecutor(store, reads);
     /** Task checkouts, for Settings → Storage: the pool's own root, or the folder beside the database. */
     const storagePool = (databaseFile) => new WorktreePool(store, { root: options.poolRoot ?? join(dirname(databaseFile), "worktrees") });
     const install = installMethod(options.installBin);
@@ -750,8 +758,11 @@ export function createDecisionServer(options) {
     /** One-click connections on their way: the service's sign-in page and back, 15 minutes at most. */
     const connectVisits = new Map();
     /** Flows open in a browser (v88): who's here, and a nudge when one changes. */
-    const flowRooms = createFlowRooms(flow => flowFingerprint(store, flow));
-    const taskRooms = createTaskRooms(root => taskFingerprint(store, root, clock()));
+    // Live views push on write (live-bus.ts): the revision triggers move, the rooms hear it.
+    const liveBus = createLiveBus();
+    const liveFollower = followWorkspace(store, () => workspaceRevision.current(), liveBus, { file: store.databaseFile() });
+    const flowRooms = createFlowRooms(flow => flowFingerprint(store, flow), { bus: liveBus });
+    const taskRooms = createTaskRooms(root => taskFingerprint(store, root, clock()), { bus: liveBus });
     const teamChatProvider = () => { const enabled = chatEnablement(); return enabled.ok ? { config: enabled.config, key: enabled.key } : null; };
     const team = createTeamRuntime({ store, repos: codingProjects, evidenceRoot, clock, workspaceRevision,
         ...(options.chatFetcher ? { fetcher: options.chatFetcher } : {}),
@@ -841,6 +852,7 @@ export function createDecisionServer(options) {
     /** The task behind a resource, for the ceiling check; null = no ref (visible). */
     const taskRepoOf = (taskRef) => store.refForId(taskRef)?.repo ?? null;
     const server = createServer((request, response) => {
+        instrumentRequest(store.telemetry, request, response);
         void handle(request, response).catch(error => {
             // Every unhandled error is logged (v99): the path and the message, never the request's body or query.
             logEvent("error", "serve.error", { method: request.method, path: redactedPath(new URL(request.url ?? "/", "http://placeholder").pathname), error: error instanceof Error ? error.message : String(error) });
@@ -857,6 +869,8 @@ export function createDecisionServer(options) {
             }
         });
     });
+    server.once('listening', () => store.telemetry.start());
+    server.once('close', () => store.telemetry.stop());
     // --public-url (arc 3): validated to EXACTLY an https origin. Its host
     // joins the allowed set, its origin authorizes POSTs, and cookies turn
     // Secure. Anything malformed refuses at startup, loudly.
@@ -2000,7 +2014,7 @@ export function createDecisionServer(options) {
             url.pathname !== "/lead/status" && url.pathname !== "/onboarding/phone/dismiss" &&
             !url.pathname.startsWith("/chat/demo/") &&
             !/^\/chat\/action\/[0-9]{1,15}$/.test(url.pathname) &&
-            !url.pathname.startsWith("/settings") && url.pathname !== "/logout" && url.pathname !== "/people" && url.pathname !== "/ledger" && url.pathname !== "/ledger/export" && url.pathname !== "/metrics" && url.pathname !== "/spend" && url.pathname !== "/spend/budget" &&
+            !url.pathname.startsWith("/settings") && url.pathname !== "/logout" && url.pathname !== "/people" && url.pathname !== "/ledger" && url.pathname !== "/ledger/export" && url.pathname !== "/metrics" && url.pathname !== "/health" && url.pathname !== "/spend" && url.pathname !== "/spend/budget" &&
             !(url.pathname === "/board" && url.searchParams.get("scope") === "all");
         if (needsProject)
             return redirect(response, `/projects?return=${encodeURIComponent(safeReturn(url.pathname + url.search))}`);
@@ -4226,6 +4240,14 @@ export function createDecisionServer(options) {
             return sendScreen(response, 200, screen("Data", `<p><a href="/settings">Settings</a></p><h1>Data</h1>${dataExportHtml(who.session.csrf, { problem: url.searchParams.get("problem") })}`, { chrome: chromeFor(project, "settings") }));
         }
         // v104: Prometheus metrics, for an instance operator (a scraper sends one's API token).
+        if (url.pathname === "/health") {
+            if (!store.isInstanceOperator(who.name))
+                return refuse(response, who, 403, "An instance operator reads server health.", "/");
+            const health = store.telemetry.snapshot();
+            return request.headers.accept?.includes('application/json')
+                ? respond(response, 200, 'application/json; charset=utf-8', JSON.stringify(health))
+                : respond(response, 200, 'text/plain; charset=utf-8', `${healthWords(health)}\n`);
+        }
         if (url.pathname === "/metrics") {
             if (!store.isInstanceOperator(who.name))
                 return refuse(response, who, 403, "An instance operator reads metrics.", "/");
@@ -12559,7 +12581,9 @@ export function createDecisionServer(options) {
         chatStreams.clear();
         flowRooms.close();
         taskRooms.close();
-        void Promise.all([closeCoding(), bounded(team.close()), bounded(leadMaintenance?.stop())]).then(() => closeServer(callback)).catch(error => {
+        detachReads();
+        liveFollower.close();
+        void Promise.all([closeCoding(), bounded(team.close()), bounded(leadMaintenance?.stop()), bounded(reads?.close())]).then(() => closeServer(callback)).catch(error => {
             if (callback)
                 callback(error instanceof Error ? error : Error('Coding session shutdown failed.'));
             else

package/dist/server-telemetry.d.ts

@@ -0,0 +1,86 @@
+import type { BudgetLimit } from './request-budget.js';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+export declare const TELEMETRY_WINDOW_MS = 300000;
+export declare const LATENCY_BUCKETS: number[];
+export declare const ROUTE_FAMILIES: readonly ['cli', 'mcp', 'team', 'team-stream', 'chat', 'chat-stream', 'flows', 'flow-stream', 'tasks', 'results', 'decisions', 'sessions', 'settings', 'projects', 'assets', 'auth', 'metrics', 'health', 'console', 'other'];
+export type RouteFamily = typeof ROUTE_FAMILIES[number];
+export type StreamFamily = 'team-stream' | 'chat-stream' | 'flow-stream' | 'other';
+export declare const STREAM_FAMILIES: readonly StreamFamily[];
+export declare const QUEUE_BUCKETS: number[];
+/** Only literals from the allowlist can become labels, including for unknown or malformed paths. */
+export declare function routeFamily(raw: string): RouteFamily;
+type Counts = {
+    bins: number[];
+    count: number;
+    sum: number;
+    max: number;
+};
+export type LatencySummary = {
+    count: number;
+    p50Ms: number | null;
+    p99Ms: number | null;
+    maxMs: number | null;
+    totalMs: number;
+};
+/** Lifetime histogram plus a ring of ten-second slices. Cost and memory do not grow with traffic. */
+export declare class TimingHistogram {
+    private readonly clock;
+    readonly total: Counts;
+    private readonly slices;
+    constructor(clock: () => number);
+    observe(seconds: number, weight?: number): void;
+    private prune;
+    recent(): LatencySummary;
+}
+export type HealthSnapshot = {
+    version: 1;
+    windowSeconds: number;
+    uptimeSeconds: number;
+    requests: LatencySummary;
+    routes: Partial<Record<RouteFamily, LatencySummary>>;
+    eventLoop: LatencySummary;
+    writes: {
+        wait: LatencySummary;
+        hold: LatencySummary;
+        statement: LatencySummary;
+    };
+    streams: {
+        open: number;
+        queuedBytes: number;
+        maxQueuedBytes: number;
+    };
+    budgetRefusals: number;
+};
+export declare class ServerTelemetry {
+    readonly clock: () => number;
+    readonly requests: TimingHistogram;
+    readonly routes: Map<"assets" | "auth" | "chat" | "chat-stream" | "cli" | "console" | "decisions" | "flow-stream" | "flows" | "health" | "mcp" | "metrics" | "other" | "projects" | "results" | "sessions" | "settings" | "tasks" | "team" | "team-stream", TimingHistogram>;
+    readonly eventLoop: TimingHistogram;
+    readonly writeWait: TimingHistogram;
+    readonly writeHold: TimingHistogram;
+    readonly writeStatement: TimingHistogram;
+    readonly refusals: Map<string, number>;
+    private readonly recentRefusals;
+    private readonly streams;
+    private monitor;
+    private timer;
+    private readonly started;
+    constructor(clock?: () => number);
+    start(): void;
+    stop(): void;
+    /**
+     * Native nanosecond samples, folded into bounded buckets once a second, never one retained object per tick.
+     * Each raw sample includes the sampling timer's own interval, so it is subtracted: an idle loop reads near zero.
+     */
+    sampleEventLoop(): void;
+    budgetRefused(route: 'api' | 'mcp', reason: BudgetLimit | 'unavailable'): void;
+    private pruneRefusals;
+    observeRequest(family: RouteFamily, milliseconds: number): void;
+    openStream(response: ServerResponse, family: StreamFamily): void;
+    streamQueues(family?: StreamFamily): number[];
+    snapshot(): HealthSnapshot;
+}
+/** SSE latency is time to opening headers; a live view's lifetime is not request work. */
+export declare function instrumentRequest(telemetry: ServerTelemetry, request: IncomingMessage, response: ServerResponse): void;
+export declare function healthWords(health: HealthSnapshot): string;
+export {};

package/dist/server-telemetry.js

@@ -0,0 +1,263 @@
+/** Bounded, in-memory performance measurements. Never retain URLs, SQL, or identities. */
+import { monitorEventLoopDelay } from 'node:perf_hooks';
+export const TELEMETRY_WINDOW_MS = 300_000;
+const SLICE_MS = 10_000;
+/** monitorEventLoopDelay samples by sleeping this long, so every raw sample includes it. */
+const EVENT_LOOP_RESOLUTION_MS = 20;
+export const LATENCY_BUCKETS = [0.0001, 0.00025, 0.0005, 0.001, 0.0025, 0.005, 0.01, 0.015, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 15, 30, 60];
+export const ROUTE_FAMILIES = ['cli', 'mcp', 'team', 'team-stream', 'chat', 'chat-stream', 'flows', 'flow-stream', 'tasks', 'results', 'decisions', 'sessions', 'settings', 'projects', 'assets', 'auth', 'metrics', 'health', 'console', 'other'];
+export const STREAM_FAMILIES = ['team-stream', 'chat-stream', 'flow-stream', 'other'];
+export const QUEUE_BUCKETS = [0, 1024, 4096, 16384, 65536, 262144, 1048576];
+/** Only literals from the allowlist can become labels, including for unknown or malformed paths. */
+export function routeFamily(raw) {
+    let path;
+    try {
+        path = new URL(raw, 'http://localhost').pathname;
+    }
+    catch {
+        return 'other';
+    }
+    if (path === '/api/cli')
+        return 'cli';
+    if (path === '/mcp' || path.startsWith('/mcp/'))
+        return 'mcp';
+    if (path === '/api/team/events')
+        return 'team-stream';
+    if (path === '/api/team')
+        return 'team';
+    if (path === '/chat/stream')
+        return 'chat-stream';
+    if (/^\/flows\/[^/]+\/live$/.test(path))
+        return 'flow-stream';
+    if (path === '/metrics')
+        return 'metrics';
+    if (path === '/health')
+        return 'health';
+    const first = path.split('/')[1];
+    switch (first) {
+        case 'chat':
+        case 'lead': return 'chat';
+        case 'flows':
+        case 'recipes': return 'flows';
+        case 't':
+        case 'tasks':
+        case 'queue': return 'tasks';
+        case 'r':
+        case 'runs':
+        case 'review': return 'results';
+        case 'd':
+        case 'i': return 'decisions';
+        case 'code':
+        case 'session': return 'sessions';
+        case 'settings':
+        case 'people':
+        case 'spend': return 'settings';
+        case 'projects': return 'projects';
+        case 'assets': return 'assets';
+        case 'login':
+        case 'logout':
+        case 'auth': return 'auth';
+        case '':
+        case 'work':
+        case 'inbox':
+        case 'board':
+        case 'fleet':
+        case 'menu':
+        case 'done': return 'console';
+        default: return 'other';
+    }
+}
+const counts = () => ({ bins: Array.from({ length: LATENCY_BUCKETS.length + 1 }, () => 0), count: 0, sum: 0, max: 0 });
+const summary = (value) => {
+    const percentile = (fraction) => {
+        if (value.count === 0)
+            return null;
+        const rank = Math.ceil(value.count * fraction);
+        let n = 0;
+        for (const [i, count] of value.bins.entries()) {
+            n += count;
+            if (n >= rank)
+                return Math.min(LATENCY_BUCKETS[i] ?? value.max, value.max) * 1000;
+        }
+        return value.max * 1000;
+    };
+    return { count: value.count, p50Ms: percentile(0.5), p99Ms: percentile(0.99), maxMs: value.count ? value.max * 1000 : null, totalMs: value.sum * 1000 };
+};
+/** Lifetime histogram plus a ring of ten-second slices. Cost and memory do not grow with traffic. */
+export class TimingHistogram {
+    clock;
+    total = counts();
+    slices = new Map();
+    constructor(clock) {
+        this.clock = clock;
+    }
+    observe(seconds, weight = 1) {
+        if (!Number.isFinite(seconds) || seconds < 0 || weight <= 0)
+            return;
+        const at = Math.floor(this.clock() / SLICE_MS);
+        this.prune(at);
+        let slice = this.slices.get(at);
+        if (!slice) {
+            slice = counts();
+            this.slices.set(at, slice);
+        }
+        let bin = LATENCY_BUCKETS.findIndex(bound => seconds <= bound);
+        if (bin < 0)
+            bin = LATENCY_BUCKETS.length;
+        for (const value of [this.total, slice]) {
+            value.bins[bin] += weight;
+            value.count += weight;
+            value.sum += seconds * weight;
+            value.max = Math.max(value.max, seconds);
+        }
+    }
+    prune(at) {
+        for (const key of this.slices.keys())
+            if (key <= at - TELEMETRY_WINDOW_MS / SLICE_MS)
+                this.slices.delete(key);
+    }
+    recent() {
+        this.prune(Math.floor(this.clock() / SLICE_MS));
+        const merged = counts();
+        for (const value of this.slices.values()) {
+            value.bins.forEach((n, i) => { merged.bins[i] += n; });
+            merged.count += value.count;
+            merged.sum += value.sum;
+            merged.max = Math.max(merged.max, value.max);
+        }
+        return summary(merged);
+    }
+}
+export class ServerTelemetry {
+    clock;
+    requests;
+    routes = new Map();
+    eventLoop;
+    writeWait;
+    writeHold;
+    writeStatement;
+    refusals = new Map();
+    recentRefusals = new Map();
+    streams = new Map();
+    monitor;
+    timer;
+    started;
+    constructor(clock = () => performance.now()) {
+        this.clock = clock;
+        this.started = clock();
+        this.requests = new TimingHistogram(clock);
+        this.eventLoop = new TimingHistogram(clock);
+        this.writeWait = new TimingHistogram(clock);
+        this.writeHold = new TimingHistogram(clock);
+        this.writeStatement = new TimingHistogram(clock);
+        for (const family of ROUTE_FAMILIES)
+            this.routes.set(family, new TimingHistogram(clock));
+    }
+    start() {
+        if (this.monitor)
+            return;
+        this.monitor = monitorEventLoopDelay({ resolution: EVENT_LOOP_RESOLUTION_MS });
+        this.monitor.enable();
+        this.timer = setInterval(() => this.sampleEventLoop(), 1000);
+        this.timer.unref();
+    }
+    stop() {
+        if (this.timer)
+            clearInterval(this.timer);
+        this.sampleEventLoop();
+        this.monitor?.disable();
+        this.monitor = undefined;
+        this.timer = undefined;
+    }
+    /**
+     * Native nanosecond samples, folded into bounded buckets once a second, never one retained object per tick.
+     * Each raw sample includes the sampling timer's own interval, so it is subtracted: an idle loop reads near zero.
+     */
+    sampleEventLoop() {
+        const h = this.monitor;
+        if (!h || !h.count)
+            return;
+        const count = h.count, steps = Math.min(count, 1000);
+        let previous = 0;
+        for (let i = 1; i <= steps; i++) {
+            const rank = Math.floor(i * count / steps);
+            this.eventLoop.observe(Math.max(0, h.percentile(100 * rank / count) / 1e6 - EVENT_LOOP_RESOLUTION_MS) / 1000, rank - previous);
+            previous = rank;
+        }
+        h.reset();
+    }
+    budgetRefused(route, reason) {
+        const key = `${route}:${reason}`;
+        this.refusals.set(key, (this.refusals.get(key) ?? 0) + 1);
+        const at = Math.floor(this.clock() / SLICE_MS);
+        this.pruneRefusals(at);
+        this.recentRefusals.set(at, (this.recentRefusals.get(at) ?? 0) + 1);
+    }
+    pruneRefusals(at) {
+        for (const key of this.recentRefusals.keys())
+            if (key <= at - TELEMETRY_WINDOW_MS / SLICE_MS)
+                this.recentRefusals.delete(key);
+    }
+    observeRequest(family, milliseconds) {
+        this.requests.observe(milliseconds / 1000);
+        this.routes.get(family).observe(milliseconds / 1000);
+    }
+    openStream(response, family) {
+        this.streams.set(response, family);
+        const closed = () => this.streams.delete(response);
+        response.once('close', closed);
+        response.once('finish', closed);
+    }
+    streamQueues(family) {
+        return [...this.streams].filter(([response, kind]) => !response.destroyed && !response.writableEnded && (family === undefined || family === kind)).map(([response]) => response.writableLength);
+    }
+    snapshot() {
+        this.sampleEventLoop();
+        this.pruneRefusals(Math.floor(this.clock() / SLICE_MS));
+        const queues = this.streamQueues();
+        return {
+            version: 1, windowSeconds: TELEMETRY_WINDOW_MS / 1000, uptimeSeconds: (this.clock() - this.started) / 1000,
+            requests: this.requests.recent(), routes: Object.fromEntries([...this.routes].map(([route, histogram]) => [route, histogram.recent()]).filter(([, value]) => value.count > 0)),
+            eventLoop: this.eventLoop.recent(), writes: { wait: this.writeWait.recent(), hold: this.writeHold.recent(), statement: this.writeStatement.recent() },
+            streams: { open: queues.length, queuedBytes: queues.reduce((sum, bytes) => sum + bytes, 0), maxQueuedBytes: queues.reduce((max, bytes) => Math.max(max, bytes), 0) },
+            budgetRefusals: [...this.recentRefusals.values()].reduce((sum, n) => sum + n, 0),
+        };
+    }
+}
+/** SSE latency is time to opening headers; a live view's lifetime is not request work. */
+export function instrumentRequest(telemetry, request, response) {
+    const family = routeFamily(request.url ?? '/'), started = telemetry.clock();
+    let recorded = false;
+    const record = () => { if (!recorded) {
+        recorded = true;
+        telemetry.observeRequest(family, telemetry.clock() - started);
+    } };
+    const writeHead = response.writeHead;
+    response.writeHead = function (...args) {
+        const result = Reflect.apply(writeHead, this, args);
+        const headers = typeof args[1] === 'object' ? args[1] : args[2];
+        const contentType = this.getHeader('content-type') ?? (headers && !Array.isArray(headers) ? Object.entries(headers).find(([name]) => name.toLowerCase() === 'content-type')?.[1] : undefined);
+        if (String(contentType).startsWith('text/event-stream') && !recorded) {
+            record();
+            telemetry.openStream(this, STREAM_FAMILIES.includes(family) ? family : 'other');
+        }
+        return result;
+    };
+    response.once('finish', record);
+    response.once('close', record);
+}
+export function healthWords(health) {
+    const ms = (n) => n === null ? 'no samples' : `${n.toFixed(2)} ms`;
+    const timing = (value) => value.count ? `p50 ${ms(value.p50Ms)}, p99 ${ms(value.p99Ms)} (${value.count} samples)` : 'no samples yet';
+    return [
+        `Server health — last 5 minutes (up ${Math.floor(health.uptimeSeconds)} seconds; approximate percentiles)`,
+        `Requests: ${timing(health.requests)}.`,
+        ...Object.entries(health.routes).map(([route, value]) => `  ${route}: ${timing(value)}.`),
+        `Event-loop delay: ${timing(health.eventLoop)}; 20 ms sampling interval.`,
+        `SQLite write-lock waits: ${timing(health.writes.wait)}.`,
+        `SQLite time holding a write transaction: ${timing(health.writes.hold)}.`,
+        `SQLite standalone writes, including lock waits: ${timing(health.writes.statement)}.`,
+        `Live streams: ${health.streams.open} open; ${health.streams.queuedBytes} bytes waiting to send, largest queue ${health.streams.maxQueuedBytes} bytes.`,
+        `Request-budget refusals: ${health.budgetRefusals}.`,
+    ].join('\n');
+}

package/dist/sqlite-telemetry.d.ts

@@ -0,0 +1,9 @@
+import type { Database } from './store.js';
+import type { ServerTelemetry } from './server-telemetry.js';
+/** One observation for the entire bounded BEGIN retry, including a failed acquisition. */
+export declare function measureWriteWait<T>(db: Database, body: () => T): T;
+/** Preserve SQLite calls, timeouts and transaction semantics. No SQL or parameters leave this wrapper.
+ * Native SQLite does not expose busy-handler time for autocommit writes: report their whole duration separately.
+ * Runtime explicit IMMEDIATE/EXCLUSIVE transactions report acquisition and hold; startup migrations are excluded.
+ */
+export declare function instrumentDatabase(db: Database, telemetry: ServerTelemetry): Database;