hippo-memory 1.69.0 → 1.71.0

package/dist/{dashboard-snapshot.js → dashboard/dashboard-snapshot.js}

@@ -1,13 +1,11 @@
 // The dashboard's read model: one in-memory snapshot of a tenant's live memories, grouped by origin project.
 // Pure build functions plus one cache; the queries over it live in dashboard-queries.ts.
-import * as fs from 'fs';
-import { calculateStrength, confidenceFacets, netWrong, Layer as MemoryLayer } from './memory.js';
-import { isQuarantineScope } from './quarantine.js';
-import { listMemoryConflicts } from './store/conflicts.js';
-import { loadAllEntries } from './store/entry-reads.js';
-import { closeHippoDb, getHippoDbPath, openHippoDbReadOnly } from './db.js';
-import { storedVectorIds } from './vector-store.js';
-export const DAY_MS = 86_400_000;
+import { calculateStrength, facetsOf, netWrong, Layer as MemoryLayer } from '../core/memory.js';
+import { isQuarantineScope } from '../trust/quarantine.js';
+import { listMemoryConflicts } from '../store/conflicts.js';
+import { DashboardConnection, loadDashboardRows } from '../store/dashboard-reads.js';
+import { DAY_MS } from '../util/time.js';
+export { DAY_MS };
 export const LAYERS = ['buffer', 'episodic', 'semantic', 'trace'];
 // Wire order of `Band`, and the order the mockup sorts bands in.
 export const BANDS = ['pinned', 'strong', 'fading', 'atRisk'];
@@ -18,9 +16,9 @@ const BAND_AT_RISK = 3;
 const CONFIDENCE_ORDER = ['verified', 'observed', 'inferred', 'stale'];
 const HEAD_CHARS = 240;
 /** An outside commit rebuilds the snapshot at most this often. */
-export const COALESCE_MS = 10_000;
+const COALESCE_MS = 10_000;
 /** Projected strengths track the clock, so the snapshot is rebuilt at least this often. */
-export const TTL_MS = 5 * 60_000;
+const TTL_MS = 5 * 60_000;
 /** The one predicate for "shown on the dashboard": not superseded, not archived, not quarantined. */
 export function isLiveMemory(entry) {
     return !entry.superseded_by && (entry.kind === 'raw' || entry.kind === 'distilled') && !isQuarantineScope(entry.scope);
@@ -52,7 +50,7 @@ export function memoryFacts(entry, nowMs) {
     const strength = calculateStrength(entry, now);
     const strength7d = calculateStrength(entry, new Date(nowMs + 7 * DAY_MS));
     const strength30d = calculateStrength(entry, new Date(nowMs + 30 * DAY_MS));
-    const facets = confidenceFacets(entry, now);
+    const facets = facetsOf(entry, now);
     const band = entry.pinned ? BAND_PINNED : strength30d < 0.2 ? BAND_AT_RISK : strength >= 0.5 ? BAND_STRONG : BAND_FADING;
     return {
         strength,
@@ -144,30 +142,42 @@ function toFact(entry, f, project, embedded, createdMs) {
         createdMs,
     };
 }
+function tallyExcluded(entry, excluded) {
+    if (isQuarantineScope(entry.scope))
+        excluded.quarantined++;
+    else if (entry.superseded_by || entry.kind === 'superseded')
+        excluded.superseded++;
+    else if (entry.kind === 'archived')
+        excluded.archived++;
+}
+function draftIndexFor(identity, projectIndex, drafts) {
+    let p = projectIndex.get(identity.key);
+    if (p === undefined) {
+        p = drafts.length;
+        projectIndex.set(identity.key, p);
+        drafts.push(newDraft(identity));
+    }
+    return p;
+}
+function finishProject(d) {
+    d.summary.atRisk = d.summary.bands.atRisk;
+    d.summary.share = d.summary.live > 0 ? d.summary.atRisk / d.summary.live : 0;
+    d.summary.lastRetrievedDays = d.summary.live > 0 ? round1(d.lastDays) : null;
+    return { summary: d.summary, members: Int32Array.from(d.members), firstCreatedMs: d.firstCreatedMs };
+}
 /** Builds the snapshot from already-loaded rows; it touches no store, so tests can feed it directly. */
 export function buildSnapshot(input) {
     const { entries, embeddedIds, nowMs } = input;
-    const excluded = { superseded: 0, archived: 0, quarantined: 0 };
+    const excluded = { superseded: 0, archived: 0, quarantined: 0, ...input.excluded };
     const facts = [];
     const projectIndex = new Map();
     const drafts = [];
     for (const entry of entries) {
         if (!isLiveMemory(entry)) {
-            if (isQuarantineScope(entry.scope))
-                excluded.quarantined++;
-            else if (entry.superseded_by || entry.kind === 'superseded')
-                excluded.superseded++;
-            else if (entry.kind === 'archived')
-                excluded.archived++;
+            tallyExcluded(entry, excluded);
             continue;
         }
-        const identity = projectIdentity(entry.origin_project);
-        let p = projectIndex.get(identity.key);
-        if (p === undefined) {
-            p = drafts.length;
-            projectIndex.set(identity.key, p);
-            drafts.push(newDraft(identity));
-        }
+        const p = draftIndexFor(projectIdentity(entry.origin_project), projectIndex, drafts);
         const f = memoryFacts(entry, nowMs);
         const embedded = embeddedIds !== null && embeddedIds.has(entry.id);
         const parsedCreated = Date.parse(entry.created);
@@ -187,12 +197,7 @@ export function buildSnapshot(input) {
         facts.push(toFact(entry, f, p, embedded, Number.isFinite(parsedCreated) ? parsedCreated : nowMs));
     }
     const openConflicts = countOpenConflicts(facts, drafts.map((d) => d.summary), input.openConflicts);
-    const projects = drafts.map((d) => {
-        d.summary.atRisk = d.summary.bands.atRisk;
-        d.summary.share = d.summary.live > 0 ? d.summary.atRisk / d.summary.live : 0;
-        d.summary.lastRetrievedDays = d.summary.live > 0 ? round1(d.lastDays) : null;
-        return { summary: d.summary, members: Int32Array.from(d.members), firstCreatedMs: d.firstCreatedMs };
-    });
+    const projects = drafts.map(finishProject);
     const embeddedTotal = projects.reduce((sum, p) => sum + p.summary.embedded, 0);
     return {
         id: input.id,
@@ -227,82 +232,83 @@ function countOpenConflicts(facts, summaries, conflicts) {
     }
     return total;
 }
+function cacheStillServes(hit, want, wallMs) {
+    const age = wallMs - hit.builtAtMs;
+    return hit.snapshot.tenantId === want.tenantId
+        && (hit.dataVersion !== null || want.dataVersion === null)
+        && age < TTL_MS
+        && (hit.dataVersion === want.dataVersion || age < COALESCE_MS);
+}
 // Keeps ids rising between two services created in the same millisecond of one process.
 let highestIssuedId = 0;
-/** Holds one read-only connection for its commit signal (`PRAGMA data_version`) and the snapshot cache; `now` dates the strength projections, `cacheClock` ages the cache. */
-export function createSnapshotService(hippoRoot, now, cacheClock = Date.now) {
-    let db = null;
-    let cached = null;
+class SnapshotCacheService {
+    hippoRoot;
+    now;
+    cacheClock;
+    connection;
+    cached = null;
     // Wall clock, not `now`, so ids keep rising across server restarts and a client holding an old tab never sees a lower one.
-    let lastId = Math.max(Date.now(), highestIssuedId);
-    let lastEmbeddedIds;
-    const dataVersion = () => {
-        if (db === null) {
-            if (!fs.existsSync(getHippoDbPath(hippoRoot)))
-                return null;
-            db = openHippoDbReadOnly(hippoRoot);
+    lastId = Math.max(Date.now(), highestIssuedId);
+    lastEmbeddedIds;
+    constructor(hippoRoot, now, cacheClock) {
+        this.hippoRoot = hippoRoot;
+        this.now = now;
+        this.cacheClock = cacheClock;
+        this.connection = new DashboardConnection(hippoRoot);
+    }
+    build(tenantId, dv, nowMs) {
+        const rows = dv === null ? null : loadDashboardRows(this.hippoRoot, tenantId);
+        const openConflicts = dv === null ? [] : listMemoryConflicts(this.hippoRoot, 'open', tenantId);
+        this.lastId += 1;
+        highestIssuedId = Math.max(highestIssuedId, this.lastId);
+        // After loadDashboardRows, whose writable open has run any pending migration and legacy embeddings.json import.
+        this.lastEmbeddedIds = this.connection.embeddedIds();
+        return buildSnapshot({
+            id: this.lastId,
+            tenantId,
+            nowMs,
+            entries: rows?.live ?? [],
+            excluded: rows?.excluded,
+            openConflicts,
+            embeddedIds: this.lastEmbeddedIds
+        });
+    }
+    get(tenantId, fresh = false) {
+        const nowMs = this.now();
+        // A frozen eval clock (HIPPO_FAKE_NOW) would never age the cache, so reuse is timed on its own clock.
+        const wallMs = this.cacheClock();
+        // Read before the build, so a commit that lands during it shows on the next read.
+        const dv = this.connection.dataVersion();
+        const hit = this.cached;
+        if (hit !== null && !fresh) {
+            if (cacheStillServes(hit, { tenantId, dataVersion: dv }, wallMs))
+                return hit.snapshot;
         }
-        // SAFETY: PRAGMA data_version returns one row with that single integer column.
-        const row = db.prepare('PRAGMA data_version').get();
-        return row.data_version;
-    };
-    // No database means no vectors; a store not yet on schema v52 has no table to count, so coverage is unknown.
-    const readEmbeddedIds = () => {
-        if (db === null)
-            return new Set();
-        // SAFETY: sqlite_master rows carry a text name; the query only tests presence.
-        const table = db.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'memory_vectors'").get();
-        return table === undefined ? null : storedVectorIds(db);
-    };
-    const build = (tenantId, dv, nowMs) => {
-        const entries = dv === null ? [] : loadAllEntries(hippoRoot, tenantId);
-        const openConflicts = dv === null ? [] : listMemoryConflicts(hippoRoot, 'open', tenantId);
-        lastId += 1;
-        highestIssuedId = Math.max(highestIssuedId, lastId);
-        // After loadAllEntries, whose writable open has run any pending migration and legacy embeddings.json import.
-        lastEmbeddedIds = readEmbeddedIds();
-        return buildSnapshot({ id: lastId, tenantId, nowMs, entries, openConflicts, embeddedIds: lastEmbeddedIds });
-    };
-    return {
-        get(tenantId, fresh = false) {
-            const nowMs = now();
-            // A frozen eval clock (HIPPO_FAKE_NOW) would never age the cache, so reuse is timed on its own clock.
-            const wallMs = cacheClock();
-            // Read before the build, so a commit that lands during it shows on the next read.
-            const dv = dataVersion();
-            const hit = cached;
-            if (hit !== null && !fresh) {
-                const age = wallMs - hit.builtAtMs;
-                const reusable = hit.snapshot.tenantId === tenantId
-                    && (hit.dataVersion !== null || dv === null)
-                    && age < TTL_MS
-                    && (hit.dataVersion === dv || age < COALESCE_MS);
-                if (reusable)
-                    return hit.snapshot;
-            }
-            const snapshot = build(tenantId, dv, nowMs);
-            cached = { snapshot, dataVersion: dv, builtAtMs: wallMs };
-            return snapshot;
-        },
-        invalidate() {
-            cached = null;
-        },
-        currentId() {
-            return lastId;
-        },
-        embeddedIds() {
-            if (lastEmbeddedIds !== undefined)
-                return lastEmbeddedIds;
-            dataVersion();
-            return readEmbeddedIds();
-        },
-        close() {
-            if (db !== null)
-                closeHippoDb(db);
-            db = null;
-            cached = null;
-            lastEmbeddedIds = undefined;
-        },
-    };
+        const snapshot = this.build(tenantId, dv, nowMs);
+        this.cached = { snapshot, dataVersion: dv, builtAtMs: wallMs };
+        return snapshot;
+    }
+    invalidate() {
+        this.cached = null;
+    }
+    currentId() {
+        return this.lastId;
+    }
+    embeddedIds() {
+        if (this.lastEmbeddedIds !== undefined)
+            return this.lastEmbeddedIds;
+        this.connection.dataVersion();
+        return this.connection.embeddedIds();
+    }
+    close() {
+        this.connection.close();
+        this.cached = null;
+        this.lastEmbeddedIds = undefined;
+    }
+}
+/** Holds one read-only connection for its commit signal (`PRAGMA data_version`) and the
+ * snapshot cache; `now` dates the strength projections, `cacheClock` ages the cache. */
+export function createSnapshotService(hippoRoot, now, cacheClock = Date.now) {
+    return new SnapshotCacheService(hippoRoot, now, cacheClock);
 }
 //# sourceMappingURL=dashboard-snapshot.js.map

package/dist/{dashboard-types.d.ts → dashboard/dashboard-types.d.ts}

@@ -17,7 +17,8 @@ export interface ProjectSummary {
     bands: Record<Band, number>;
     layers: Record<Layer, number>;
 }
-/** One KPI card; `series` is 91 daily cumulative points, oldest first (point 0 is the base at the window start, point 90 is now) so `last - first` over any range plus one points is exact; null when hippo recorded no history. */
+/** One KPI card; `series` is 91 daily cumulative points, oldest first (point 0 is the base at the window start,
+ * point 90 is now) so `last - first` over any range plus one points is exact; null when hippo recorded no history. */
 export interface Kpi {
     id: 'total' | 'projects' | 'atRiskShare' | 'openConflicts' | 'embeddingCoverage';
     label: string;

package/dist/{dashboard.d.ts → dashboard/dashboard.d.ts}

@@ -4,5 +4,6 @@ import * as http from 'http';
 export declare function serveDashboard(hippoRoot: string, port?: number, token?: string, opts?: {
     now?: () => number;
     cacheClock?: () => number;
+    handleSignals?: boolean;
 }): http.Server;
 //# sourceMappingURL=dashboard.d.ts.map

package/dist/{dashboard.js → dashboard/dashboard.js}

@@ -2,18 +2,23 @@
 import * as http from 'http';
 import * as path from 'path';
 import * as fs from 'fs';
-import { randomBytes, timingSafeEqual } from 'crypto';
-import { evalNow } from './ablation.js';
-import { readEntry } from './store/entry-reads.js';
-import { listCards } from './store-cards.js';
-import { resolveTenantId } from './tenant.js';
-import { loadCardDetail } from './card-detail.js';
-import { closeAfterReply, isCrossSite, LOOPBACK_HOST_HEADER } from './http-util.js';
-import { log } from './log.js';
+import { createHash, randomBytes, randomUUID, timingSafeEqual } from 'crypto';
+import { evalNow } from '../core/ablation.js';
+import { readEntry } from '../store/entry-reads.js';
+import { listCards } from '../store/cards.js';
+import { resolveTenantId } from '../store/tenant.js';
+import { loadCardDetail } from '../store/card-detail.js';
+import { bodyDeadlineMs, BodyTimeoutError, closeAfterReply, isCrossSite, LOOPBACK_HOST_HEADER } from '../util/http-util.js';
+import { errorFields, errorMessage, log } from '../util/log.js';
 import { createSnapshotService, isLiveMemory } from './dashboard-snapshot.js';
 import { buildMemoryDetail, buildMemoryPage, buildOverview, buildProjectDetail, buildSearch, } from './dashboard-queries.js';
 import { forgetMemory, markWrong, pinMemory, resolveOpenConflict, } from './dashboard-actions.js';
 import { ParamError, parseActionBody, parseConflictId, parseMemoryId, parseMemoryQuery, parseSearchText, } from './dashboard-params.js';
+import { runWithRequestId } from '../util/request-scope.js';
+import { installSignalHandlers } from '../util/crash-handlers.js';
+import { DEFAULT_SHUTDOWN_DRAIN_MS, drainAndClose, setKeepAliveTimeouts, shutdownBoundMs } from '../server/lifecycle.js';
+import { printError } from '../cli/output.js';
+import { PACKAGE_ROOT } from '../core/package-root.js';
 const MIME_TYPES = {
     '.html': 'text/html; charset=utf-8',
     '.js': 'application/javascript; charset=utf-8',
@@ -72,6 +77,10 @@ function readActionBody(req) {
         const chunks = [];
         let size = 0;
         let aborted = false;
+        const deadlineMs = bodyDeadlineMs();
+        const timer = setTimeout(() => reject(new BodyTimeoutError(`request body not received within ${deadlineMs} ms`)), deadlineMs);
+        // Unref: a request that already failed another way must not hold the process open for the rest of the deadline.
+        timer.unref();
         req.on('data', (chunk) => {
             size += chunk.length;
             if (size <= BODY_MAX_BYTES)
@@ -83,6 +92,7 @@ function readActionBody(req) {
         });
         req.on('error', reject);
         req.on('end', () => {
+            clearTimeout(timer);
             if (size > BODY_MAX_BYTES)
                 return reject(new ParamError(`Body must be at most ${BODY_MAX_BYTES} bytes`));
             try {
@@ -123,7 +133,7 @@ function handleRead(ctx, segments) {
             return sendOrNotFound(res, null);
         const snapshotId = snapshots.get(tenantId, fresh).id;
         const embedded = snapshots.embeddedIds()?.has(entry.id) ?? false;
-        return sendOrNotFound(res, buildMemoryDetail(hippoRoot, tenantId, entry, snapshotId, ctx.now(), embedded));
+        return sendOrNotFound(res, buildMemoryDetail(hippoRoot, tenantId, entry, { snapshotId, nowMs: ctx.now(), embedded }));
     }
     if (head === 'search' && segments.length === 2) {
         return sendOrNotFound(res, buildSearch(snapshots.get(tenantId, fresh), parseSearchText(url.searchParams)));
@@ -175,7 +185,7 @@ async function handlePost(ctx, segments) {
     if (result.entry) {
         // The write is committed, so a rebuild failure must not turn it into a 500: the next read rebuilds.
         const embedded = snapshots.embeddedIds()?.has(result.entry.id) ?? false;
-        const detail = buildMemoryDetail(hippoRoot, tenantId, result.entry, snapshots.currentId(), ctx.now(), embedded);
+        const detail = buildMemoryDetail(hippoRoot, tenantId, result.entry, { snapshotId: snapshots.currentId(), nowMs: ctx.now(), embedded });
         jsonResponse(res, detail, result.status);
     }
     else {
@@ -183,21 +193,43 @@ async function handlePost(ctx, segments) {
     }
     return true;
 }
+// One style block, not style attributes, so the policy below can name its hash and allow no other inline style.
+const NOT_BUILT_CSS = "body{font-family:Georgia,'Palatino Linotype',serif;max-width:640px;margin:60px auto;padding:24px;line-height:1.6;background:#f4efe6;color:#3a3228}" +
+    'h1{color:#c45c3c}' +
+    'pre{background:#faf7f2;padding:16px;border:1px solid #c4b9a8;border-radius:3px;font-family:Consolas,monospace}';
+// Memory text is written by other tools and people, so every reply tells the browser to load code only from this server and never to frame, sniff or name the page elsewhere.
+const SECURITY_HEADERS = {
+    'Content-Security-Policy': [
+        "default-src 'none'",
+        "script-src 'self'",
+        `style-src 'self' 'sha256-${createHash('sha256').update(NOT_BUILT_CSS).digest('base64')}'`,
+        "img-src 'self' data:",
+        "font-src 'self'",
+        "connect-src 'self'",
+        "base-uri 'none'",
+        "form-action 'none'",
+        "frame-ancestors 'none'",
+    ].join('; '),
+    'X-Content-Type-Options': 'nosniff',
+    'Referrer-Policy': 'no-referrer',
+    'X-Frame-Options': 'DENY',
+};
 function notBuilt(res) {
     res.writeHead(404, { 'Content-Type': 'text/html; charset=utf-8' });
     res.end(`<!doctype html>
-<html lang="en"><head><title>Hippo Dashboard</title><meta charset="utf-8"></head>
-<body style="font-family:Georgia,'Palatino Linotype',serif;max-width:640px;margin:60px auto;padding:24px;line-height:1.6;background:#f4efe6;color:#3a3228">
-<h1 style="color:#c45c3c">Hippo Dashboard</h1>
+<html lang="en"><head><title>Hippo Dashboard</title><meta charset="utf-8"><style>${NOT_BUILT_CSS}</style></head>
+<body>
+<h1>Hippo Dashboard</h1>
 <p>The React UI bundle is not built yet. Run:</p>
-<pre style="background:#faf7f2;padding:16px;border:1px solid #c4b9a8;border-radius:3px;font-family:Consolas,monospace">cd ui && npm install && npm run build</pre>
+<pre>cd ui && npm install && npm run build</pre>
 <p>Then refresh this page. The dashboard server will serve <code>dist-ui/index.html</code> automatically once present.</p>
 </body></html>`);
 }
 function serveSpa(res, distUiDir, pathname) {
     const safePath = path.normalize(pathname).replace(/^(\.\.[/\\])+/, '');
     const filePath = path.join(distUiDir, safePath);
-    if (!filePath.startsWith(distUiDir))
+    // The separator matters: a bare prefix also admits a sibling folder whose name starts with this one.
+    if (filePath !== distUiDir && !filePath.startsWith(distUiDir + path.sep))
         return forbidden(res);
     if (fs.existsSync(filePath) && fs.statSync(filePath).isFile() && serveStaticFile(res, filePath))
         return;
@@ -221,9 +253,123 @@ function cookieValue(header, name) {
     }
     return undefined;
 }
+/** Where a page load that carried the token goes next, without it; null for an API call or a write, which is answered in place. */
+function tokenFreeLocation(req, url) {
+    if ((req.method !== 'GET' && req.method !== 'HEAD') || url.pathname.startsWith('/api/'))
+        return null;
+    const query = new URLSearchParams(url.searchParams);
+    query.delete('token');
+    const rest = query.toString();
+    // One leading slash only: `//host` would send the browser to another site.
+    return `${url.pathname.replace(/^\/+/, '/')}${rest ? `?${rest}` : ''}`;
+}
+/** Moves the browser off the URL that carries the token, so the token stays out of history, bookmarks and copied links; false when the request is answered in place. */
+function leaveTokenUrl(req, res, url) {
+    const location = tokenFreeLocation(req, url);
+    if (location === null)
+        return false;
+    if (req.headers['sec-fetch-site'] !== 'cross-site') {
+        res.writeHead(303, { Location: location });
+        res.end();
+        return true;
+    }
+    // A browser withholds a SameSite=Strict cookie from a redirect another site started; a refresh from this page is same-site.
+    const target = location.replace(/&/g, '&amp;').replace(/"/g, '&quot;');
+    res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+    res.end(`<!doctype html>\n<html lang="en"><head><meta charset="utf-8"><meta http-equiv="refresh" content="0;url=${target}"><title>Hippo Dashboard</title></head><body></body></html>`);
+    return true;
+}
+/** True when the request may proceed; false when this already answered it (redirect off the token URL, or 401). */
+function admitDashboardRequest(req, res, url, access) {
+    const { token, port } = access;
+    // Cookies ignore the port, so the name carries it: two dashboards on one host keep separate tokens.
+    const cookieName = `hippo_dashboard_${req.socket.localPort ?? port}`;
+    if (sameToken(url.searchParams.get('token') ?? undefined, token)) {
+        res.setHeader('Set-Cookie', `${cookieName}=${token}; HttpOnly; SameSite=Strict; Path=/`);
+        if (leaveTokenUrl(req, res, url))
+            return false;
+    }
+    else if (!sameToken(cookieValue(req.headers.cookie, cookieName), token)) {
+        res.writeHead(401, { 'Content-Type': 'text/plain' });
+        res.end('Unauthorized: open the dashboard with the URL `hippo dashboard` printed; it carries the access token.');
+        return false;
+    }
+    return true;
+}
+function answerDashboardFailure(req, res, err) {
+    const clientFault = err instanceof ParamError || err instanceof URIError || err instanceof BodyTimeoutError;
+    // A cut-short response is logged even for a client fault; a bare 400 is not.
+    if (res.headersSent || !clientFault) {
+        log.error('dashboard request failed', { ...errorFields(err), error: errorMessage(err), path: req.url });
+    }
+    if (res.headersSent) {
+        res.end();
+        return;
+    }
+    if (err instanceof BodyDrainExceeded || err instanceof BodyTimeoutError) {
+        // No `Connection: close` header: Node then destroys the socket as soon as the reply is written.
+        res.writeHead(err instanceof BodyTimeoutError ? 408 : 400, { 'Content-Type': 'application/json; charset=utf-8' });
+        res.end(JSON.stringify({ error: err.message }), () => closeAfterReply(req));
+        return;
+    }
+    if (err instanceof ParamError)
+        return jsonResponse(res, { error: err.message }, 400);
+    if (err instanceof URIError)
+        return jsonResponse(res, { error: 'Malformed URL path' }, 400);
+    jsonResponse(res, { error: 'Internal error' }, 500);
+}
+function printDashboardBanner(boundPort, token, distUiDir) {
+    // The banner is the `hippo dashboard` command's printed result, so it stays on stdout.
+    console.log(`Hippo Dashboard running at http://localhost:${boundPort}/?token=${token}`);
+    if (distUiDir !== null)
+        console.log(`Serving React UI from ${distUiDir}`);
+    console.log('Press Ctrl+C to stop.');
+}
+/** A port that will not open is the user's to fix, so it gets one plain line and a failure exit code, not an uncaught error's stack. */
+function reportListenFailure(port, err) {
+    const inUse = 'code' in err && err.code === 'EADDRINUSE';
+    printError(inUse
+        ? `hippo dashboard: port ${port} is already in use. Stop the program that holds it, or choose another port with --port <number>.`
+        : `hippo dashboard: could not listen on port ${port}: ${err.message}. Choose another port with --port <number>.`);
+    process.exitCode = 1;
+}
+/** Ctrl+C or a stop signal: stop listening, give open requests the API server's drain, and leave within its shutdown bound. */
+function stopOnSignal(server) {
+    const inflight = new Set();
+    server.on('request', (_req, res) => {
+        inflight.add(res);
+        res.once('close', () => inflight.delete(res));
+    });
+    installSignalHandlers('dashboard', {
+        run: () => drainAndClose(server, inflight, DEFAULT_SHUTDOWN_DRAIN_MS),
+        boundMs: shutdownBoundMs(DEFAULT_SHUTDOWN_DRAIN_MS),
+    });
+}
+/** Gives the listener the API server's socket deadlines and one close of the store's connection; with `handleSignals`, a signal stops it too. */
+function superviseListener(server, snapshots, port, handleSignals) {
+    setKeepAliveTimeouts(server);
+    let storeClosed = false;
+    const closeStore = () => {
+        if (storeClosed)
+            return;
+        storeClosed = true;
+        snapshots.close();
+    };
+    server.on('close', closeStore);
+    server.on('error', (err) => {
+        // Once it listens, an 'error' is a failed accept: logged, as the API server does, and the dashboard keeps serving.
+        if (server.listening)
+            return log.error(`dashboard: listener error: ${err.message}`, errorFields(err));
+        reportListenFailure(port, err);
+        // A failed listen emits no 'close', so the store closes here.
+        closeStore();
+    });
+    if (handleSignals)
+        stopOnSignal(server);
+}
 /** Serves the dashboard on 127.0.0.1 behind a per-start `token` (tests pass one), since loopback alone lets any local process read every memory; `opts` sets the projection and cache clocks. */
 export function serveDashboard(hippoRoot, port = 3333, token = randomBytes(32).toString('base64url'), opts) {
-    const distUiDir = path.resolve(import.meta.dirname, '..', 'dist-ui');
+    const distUiDir = path.join(PACKAGE_ROOT, 'dist-ui');
     const hasDistUi = fs.existsSync(path.join(distUiDir, 'index.html'));
     const now = opts?.now ?? (() => evalNow().getTime());
     const snapshots = createSnapshotService(hippoRoot, now, opts?.cacheClock);
@@ -232,16 +378,8 @@ export function serveDashboard(hippoRoot, port = 3333, token = randomBytes(32).t
         if (host !== undefined && !LOOPBACK_HOST_HEADER.test(host))
             return forbidden(res);
         const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);
-        // Cookies ignore the port, so the name carries it: two dashboards on one host keep separate tokens.
-        const cookieName = `hippo_dashboard_${req.socket.localPort ?? port}`;
-        if (sameToken(url.searchParams.get('token') ?? undefined, token)) {
-            res.setHeader('Set-Cookie', `${cookieName}=${token}; HttpOnly; SameSite=Strict; Path=/`);
-        }
-        else if (!sameToken(cookieValue(req.headers.cookie, cookieName), token)) {
-            res.writeHead(401, { 'Content-Type': 'text/plain' });
-            res.end('Unauthorized: open the dashboard with the URL `hippo dashboard` printed; it carries the access token.');
+        if (!admitDashboardRequest(req, res, url, { token, port }))
             return;
-        }
         if (url.pathname.startsWith('/api/')) {
             // A malformed % sequence throws URIError here; the caller answers 400.
             const segments = url.pathname.split('/').filter((s) => s !== '').map((s) => decodeURIComponent(s));
@@ -257,39 +395,18 @@ export function serveDashboard(hippoRoot, port = 3333, token = randomBytes(32).t
             return serveSpa(res, distUiDir, url.pathname);
         notBuilt(res);
     };
-    const server = http.createServer((req, res) => {
-        handleRequest(req, res).catch((err) => {
-            const clientFault = err instanceof ParamError || err instanceof URIError;
-            // A cut-short response is logged even for a client fault; a bare 400 is not.
-            if (res.headersSent || !clientFault) {
-                log.error('dashboard request failed', { error: err instanceof Error ? err.message : String(err), path: req.url });
-            }
-            if (res.headersSent) {
-                res.end();
-                return;
-            }
-            if (err instanceof BodyDrainExceeded) {
-                // No `Connection: close` header: Node then destroys the socket as soon as the reply is written.
-                res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
-                res.end(JSON.stringify({ error: err.message }), () => closeAfterReply(req));
-                return;
-            }
-            if (err instanceof ParamError)
-                return jsonResponse(res, { error: err.message }, 400);
-            if (err instanceof URIError)
-                return jsonResponse(res, { error: 'Malformed URL path' }, 400);
-            jsonResponse(res, { error: 'Internal error' }, 500);
-        });
-    });
-    server.on('close', () => snapshots.close());
+    const onRequest = (req, res) => {
+        for (const [name, value] of Object.entries(SECURITY_HEADERS))
+            res.setHeader(name, value);
+        handleRequest(req, res).catch((err) => answerDashboardFailure(req, res, err));
+    };
+    // One id per request, so the lines it logs can be told apart from a concurrent request's.
+    const server = http.createServer((req, res) => runWithRequestId(randomUUID(), () => onRequest(req, res)));
+    superviseListener(server, snapshots, port, opts?.handleSignals === true);
     server.listen(port, '127.0.0.1', () => {
         // SAFETY: listen() was given a TCP port, so address() is AddressInfo, never a pipe name.
         const boundPort = server.address().port;
-        // The banner is the `hippo dashboard` command's printed result, so it stays on stdout.
-        console.log(`Hippo Dashboard running at http://localhost:${boundPort}/?token=${token}`);
-        if (hasDistUi)
-            console.log(`Serving React UI from ${distUiDir}`);
-        console.log('Press Ctrl+C to stop.');
+        printDashboardBanner(boundPort, token, hasDistUi ? distUiDir : null);
     });
     return server;
 }

package/dist/db/backup.js

@@ -1,6 +1,6 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { log } from '../log.js';
+import { log } from '../util/log.js';
 /** Copies the database before a repair writes, so the audit ids plus this file are the way back. */
 export function backupStore(db, hippoRoot, label, now = new Date()) {
     const dir = path.join(hippoRoot, 'backups');

package/dist/db/busy.d.ts

@@ -1,5 +1,5 @@
 import type { DatabaseSyncLike } from './sqlite.js';
-export declare function isSqliteBusy(error: unknown): boolean;
+export declare function isSqliteBusy(cause: unknown): boolean;
 export declare const STORE_BUSY_MESSAGE = "store busy (another hippo process holds the write lock); retry shortly";
 /** A store behind the port throws this when its lock wait runs out, so the server answers 503 as it does for a busy hippo.db. */
 export declare class StoreBusyError extends Error {
@@ -8,7 +8,24 @@ export declare class StoreBusyError extends Error {
 /** A held lock in any store: SQLite's busy codes or a port's StoreBusyError. */
 export declare function isStoreBusy<E>(error: E): boolean;
 export declare function execWithBusyRetry(db: DatabaseSyncLike, sql: string, timeoutMs?: number): void;
+/** Waits for the lock past busy_timeout when given; ignored inside a caller's transaction, which already holds it. */
+export interface WriteScopeOptions {
+    readonly busyWaitMs?: number;
+}
 /** Runs `fn` as one write: BEGIN IMMEDIATE on an idle handle, else SAVEPOINT `name` inside the caller's transaction.
  *  A deferred scope that reads first cannot wait out another writer, while BEGIN IMMEDIATE waits the open's busy_timeout. */
-export declare function withWriteScope<T>(db: DatabaseSyncLike, name: string, fn: () => T): T;
+export declare function withWriteScope<T>(db: DatabaseSyncLike, name: string, fn: () => T, opts?: WriteScopeOptions): T;
+/** Runs the reads in `fn` against one snapshot, so two statements cannot straddle another process's write. */
+export declare function withReadSnapshot<T>(db: DatabaseSyncLike, fn: () => T): T;
+/** Runs `fn` and undoes every write it made, throw or not: a dry run that reports what a real run would do. Takes no write lock up front. */
+export declare function withTrialScope<T>(db: DatabaseSyncLike, name: string, fn: () => T): T;
+/** What `withWriteScopeOr` hands its callback's `rollback(value)`; a class so no stored value can pass for one. */
+declare class RolledBack<V> {
+    readonly value: V;
+    constructor(value: V);
+}
+/** `withWriteScope` for a write that can refuse: a callback that returns `rollback(value)` gets the scope's writes undone
+ *  and `value` back, with no throw. Any other return commits. */
+export declare function withWriteScopeOr<T, R>(db: DatabaseSyncLike, name: string, fn: (rollback: <V>(value: V) => RolledBack<V>) => T | RolledBack<R>): T | R;
+export {};
 //# sourceMappingURL=busy.d.ts.map