hippo-memory 1.70.0 → 1.71.0

package/dist/dashboard/dashboard-snapshot.d.ts

@@ -133,6 +133,7 @@ export interface SnapshotService {
     embeddedIds(): ReadonlySet<string> | null;
     close(): void;
 }
-/** 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. */
+/** 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 declare function createSnapshotService(hippoRoot: string, now: () => number, cacheClock?: () => number): SnapshotService;
 //# sourceMappingURL=dashboard-snapshot.d.ts.map

package/dist/dashboard/dashboard-snapshot.js

@@ -263,7 +263,15 @@ class SnapshotCacheService {
         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 });
+        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();
@@ -298,7 +306,8 @@ class SnapshotCacheService {
         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. */
+/** 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);
 }

package/dist/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/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/dashboard.js

@@ -9,12 +9,16 @@ 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 { errorMessage, log } from '../util/log.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',
@@ -296,7 +300,7 @@ 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', { error: errorMessage(err), path: req.url });
+        log.error('dashboard request failed', { ...errorFields(err), error: errorMessage(err), path: req.url });
     }
     if (res.headersSent) {
         res.end();
@@ -321,9 +325,51 @@ function printDashboardBanner(boundPort, token, distUiDir) {
         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);
@@ -356,7 +402,7 @@ export function serveDashboard(hippoRoot, port = 3333, token = randomBytes(32).t
     };
     // 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)));
-    server.on('close', () => snapshots.close());
+    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;

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 {

package/dist/db/busy.js

@@ -1,5 +1,8 @@
-export function isSqliteBusy(error) {
-    const code = error?.errcode;
+function carriesErrcode(cause) {
+    return typeof cause === 'object' && cause !== null && 'errcode' in cause;
+}
+export function isSqliteBusy(cause) {
+    const code = carriesErrcode(cause) ? cause.errcode : undefined;
     return code === 5 || code === 6 || code === 517;
 }
 export const STORE_BUSY_MESSAGE = 'store busy (another hippo process holds the write lock); retry shortly';
@@ -14,9 +17,8 @@ export class StoreBusyError extends Error {
 export function isStoreBusy(error) {
     return error instanceof StoreBusyError || isSqliteBusy(error);
 }
-// busy_timeout covers neither of this file's two contended statements: SQLite
-// skips the busy handler for `PRAGMA journal_mode` and for a write that upgrades
-// a deferred read snapshot. Both need an explicit wait instead.
+// busy_timeout covers neither contended statement here: SQLite skips the busy handler for `PRAGMA journal_mode` and for a write
+// that upgrades a deferred read snapshot, so both need an explicit wait.
 export function execWithBusyRetry(db, sql, timeoutMs = 30000) {
     const deadline = Date.now() + timeoutMs;
     const idle = new Int32Array(new SharedArrayBuffer(4));
@@ -67,12 +69,19 @@ export function withReadSnapshot(db, fn) {
     if (db.isTransaction !== false)
         return fn();
     db.exec('BEGIN');
+    let result;
     try {
-        return fn();
+        result = fn();
     }
-    finally {
-        db.exec('COMMIT');
+    catch (error) {
+        try {
+            db.exec('COMMIT');
+        }
+        catch { /* snapshot already gone; keep the original error */ }
+        throw error;
     }
+    db.exec('COMMIT');
+    return result;
 }
 /** 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 function withTrialScope(db, name, fn) {

package/dist/db/connect.d.ts

@@ -1,5 +1,6 @@
 import { type DatabaseSyncLike } from './sqlite.js';
 import { type OpenFacts } from './migrate.js';
+export declare const DEFAULT_BUSY_WAIT_MS = 5000;
 export declare function getHippoDbPath(hippoRoot: string): string;
 /** Runs `step` on this store unless it already ran to the end in this process; a throw leaves it due. */
 export declare function oncePerStore(hippoRoot: string, name: string, step: () => void): void;

package/dist/db/connect.js

@@ -1,12 +1,12 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { cleanupArchivedMirrors } from './raw-archive-mirror-cleanup.js';
-import { errorMessage, log } from '../util/log.js';
+import { errorFields, errorMessage, log } from '../util/log.js';
 import { DatabaseSync } from './sqlite.js';
 import { execWithBusyRetry } from './busy.js';
 import { runMigrations } from './migrate.js';
 import { autoCheckpointPages } from './wal-checkpointer.js';
-const DEFAULT_BUSY_WAIT_MS = 5000;
+export const DEFAULT_BUSY_WAIT_MS = 5000;
 export function getHippoDbPath(hippoRoot) {
     return path.join(hippoRoot, 'hippo.db');
 }
@@ -68,7 +68,7 @@ export function connectWithFacts(hippoRoot, busyWaitMs) {
             sweepArchivedMirrorsIfDue(hippoRoot, db, facts?.archiveTop);
         }
         catch (cleanupErr) {
-            log.error(`openHippoDb: cleanupArchivedMirrors failed (non-fatal): ${errorMessage(cleanupErr)}`);
+            log.error(`openHippoDb: cleanupArchivedMirrors failed (non-fatal): ${errorMessage(cleanupErr)}`, errorFields(cleanupErr));
         }
         return { db, facts };
     }

package/dist/db/migrate.js

@@ -125,10 +125,10 @@ function importLegacyVectors(db, hippoRoot) {
     }
 }
 function ensureMetaDefaults(db) {
-    // Read-first: an already-current store has all 7 keys, so this is one
-    // SELECT and zero writes instead of 7 no-op INSERT OR IGNOREs, each of
-    // which takes a RESERVED lock even when nothing changes.
+    // Read-first: an already-current store has all 7 keys, so this is one SELECT and zero writes instead of 7 no-op
+    // INSERT OR IGNOREs, each of which takes a RESERVED lock even when nothing changes.
     const keys = META_DEFAULTS.map(([key]) => key);
+    // SAFETY: the statement selects only the `key` column of `meta`, which is TEXT NOT NULL, so each row is { key: string }.
     const present = new Set(db
         .prepare(`SELECT key FROM meta WHERE key IN (${keys.map(() => '?').join(',')})`)
         .all(...keys)

package/dist/db/migrations/types.d.ts

@@ -1,9 +1,6 @@
 import type { DatabaseSyncLike } from '../sqlite.js';
-/**
- * Context passed to migrations that need to know WHERE the store lives.
- * hippoRoot is the store directory (e.g. `<project>/.hippo`); undefined only
- * for callers that open a DB without a filesystem store notion (none today).
- */
+/** Context for migrations that need to know where the store lives. hippoRoot is the store directory (e.g. `<project>/.hippo`);
+ * undefined only for callers that open a DB without a filesystem store. */
 export type MigrationContext = {
     hippoRoot?: string;
 };

package/dist/db/migrations/v14.js

@@ -36,9 +36,8 @@ const CREATE_TRIGGER_TRG_MEMORIES_KIND_CHECK_UPDATE_SQL = `
 export const v14 = {
     version: 14,
     up: (db) => {
-        // Provenance envelope: kind, scope, owner, artifact_ref.
-        // SQLite ALTER TABLE ADD COLUMN cannot add CHECK; CHECK enforcement lives
-        // in INSERT/UPDATE triggers added later in this migration.
+        // Provenance envelope: kind, scope, owner, artifact_ref. ALTER TABLE ADD COLUMN cannot add CHECK,
+        // so enforcement lives in the INSERT/UPDATE triggers added later in this migration.
         if (!tableHasColumn(db, 'memories', 'kind')) {
             db.exec(`ALTER TABLE memories ADD COLUMN kind TEXT DEFAULT 'distilled'`);
         }

package/dist/db/migrations/v15.js

@@ -1,14 +1,8 @@
 export const v15 = {
     version: 15,
     up: (db) => {
-        // Close the NULL-kind bypass and add raw_archive dedup safety.
-        //
-        // (1) Original v14 triggers used `WHEN NEW.kind IS NOT NULL AND NEW.kind NOT IN (...)`.
-        //     A direct INSERT/UPDATE setting kind=NULL bypassed the CHECK substitute. Replace
-        //     with `WHEN NEW.kind IS NULL OR NEW.kind NOT IN (...)` so NULL is rejected too.
-        // (2) Add UNIQUE(memory_id, archived_at) to raw_archive so re-archiving the same id
-        //     in the same instant cannot produce ambiguous audit rows. Per-id history is still
-        //     allowed (different timestamps).
+        // Close the NULL-kind bypass: v14 triggers used `WHEN NEW.kind IS NOT NULL AND ...`, so kind=NULL slipped past; now `IS NULL OR NOT IN (...)` rejects it.
+        // Add UNIQUE(memory_id, archived_at) to raw_archive so re-archiving in the same instant cannot yield ambiguous audit rows (per-id history stays allowed).
         db.exec(`DROP TRIGGER IF EXISTS trg_memories_kind_check_insert`);
         db.exec(`DROP TRIGGER IF EXISTS trg_memories_kind_check_update`);
         db.exec(`

package/dist/db/migrations/v16.js

@@ -51,9 +51,8 @@ export const v16 = {
         db.exec(`CREATE INDEX IF NOT EXISTS idx_working_memory_tenant ON working_memory(tenant_id, importance DESC, created_at DESC)`);
         db.exec(`CREATE INDEX IF NOT EXISTS idx_consolidation_runs_tenant_ts ON consolidation_runs(tenant_id, timestamp DESC)`);
         db.exec(`CREATE INDEX IF NOT EXISTS idx_task_snapshots_tenant_status ON task_snapshots(tenant_id, status, updated_at DESC)`);
-        // Stub auth: api_keys (scrypt-hashed; plaintext returned to caller exactly once)
-        // and audit_log (append-only mutation trail). Both carry tenant_id from day 1 so
-        // future multi-tenant enforcement is a config flip, not a re-migration.
+        // Stub auth: api_keys (scrypt-hashed; plaintext returned once) and audit_log (append-only mutation trail), both with tenant_id from day 1
+        // so future multi-tenant enforcement is a config flip, not a re-migration.
         db.exec(CREATE_TABLE_API_KEYS_SQL);
         db.exec(CREATE_INDEX_IDX_API_KEYS_TENANT_ACTIVE_SQL);
         db.exec(CREATE_TABLE_AUDIT_LOG_SQL);

package/dist/db/migrations/v17.js

@@ -30,9 +30,8 @@ export const v17 = {
         )
       `);
         db.exec(`CREATE INDEX IF NOT EXISTS idx_slack_dlq_tenant_received ON slack_dlq(tenant_id, received_at)`);
-        // Multi-tenant routing seam. Empty by default: single-
-        // tenant deployments resolve via HIPPO_TENANT fallback. Multi-workspace
-        // deployments populate this table to map team_id → tenant_id.
+        // Multi-tenant routing seam, empty by default: single-tenant deployments resolve via the HIPPO_TENANT fallback;
+        // multi-workspace deployments populate it to map team_id -> tenant_id.
         db.exec(`
         CREATE TABLE IF NOT EXISTS slack_workspaces (
           team_id TEXT PRIMARY KEY,

package/dist/db/migrations/v19.js

@@ -2,11 +2,8 @@ import { tableHasColumn } from '../tables.js';
 export const v19 = {
     version: 19,
     up: (db) => {
-        // Slack hardening: widen slack_dlq with bucketing,
-        // retry tracking, and the signature/timestamp pair that lets `hippo
-        // slack dlq replay` re-verify before re-running ingest. ALTER ADD
-        // COLUMN with DEFAULT is non-destructive — legacy rows take the
-        // default values. Idempotent via tableHasColumn().
+        // Widen slack_dlq with bucketing, retry tracking and the signature/timestamp pair `hippo slack dlq replay` re-verifies;
+        // ALTER ADD COLUMN with DEFAULT is non-destructive, so legacy rows take the defaults. Idempotent via tableHasColumn().
         if (!tableHasColumn(db, 'slack_dlq', 'team_id')) {
             db.exec(`ALTER TABLE slack_dlq ADD COLUMN team_id TEXT`);
         }

package/dist/db/migrations/v20.js

@@ -2,13 +2,8 @@ import { warnDamagedColumn } from '../../util/stored-json.js';
 export const v20 = {
     version: 20,
     up: (db) => {
-        // GDPR Path A backfill: redact every existing
-        // raw_archive.payload_json so historical archives match the new
-        // metadata-only contract from src/store/raw-archive.ts. Read each row, parse
-        // the existing JSON to extract tenant_id and kind (best effort), then
-        // UPDATE with the redacted shape. Rows with unparseable legacy JSON get
-        // redacted with tenant_id='unknown', kind='unknown'. The audit_log
-        // remains the compliance record.
+        // GDPR Path A backfill: redact every existing raw_archive.payload_json to the metadata-only shape (store/raw-archive.ts); unparseable legacy JSON
+        // gets tenant_id='unknown', kind='unknown'. The audit_log remains the compliance record.
         // SAFETY: rows' shape matches the four columns named in the SELECT above.
         const rows = db
             .prepare(`SELECT id, archived_at, reason, payload_json FROM raw_archive`)

package/dist/db/migrations/v22.js

@@ -44,17 +44,8 @@ const BACKFILL_SESSION_HANDOFFS_TENANT_SQL = `
 export const v22 = {
     version: 22,
     up: (db) => {
-        // session_events and session_handoffs predate the v16 tenant migration and were
-        // never added to it: a cross-tenant leak whenever continuity primitives are used.
-        // Adds tenant_id (NOT NULL DEFAULT 'default') with smart backfill from
-        // task_snapshots.session_id when unambiguous, plus an optional scope
-        // column so a private-channel-derived handoff can default-deny via the
-        // same rule recall already enforces.
-        //
-        // Self-heal partial-init stores: re-run the v4/v5 CREATE TABLE IF NOT
-        // EXISTS bodies before ALTERing. A silent skip would otherwise stamp
-        // schema_version=22 on a DB missing the underlying tables, leaving
-        // them permanently absent.
+        // session_events and session_handoffs missed the v16 tenant migration (cross-tenant leak): add tenant_id (NOT NULL DEFAULT 'default') backfilled from
+        // task_snapshots when unambiguous, plus a scope column. Re-run v4/v5 CREATE IF NOT EXISTS first so a partial-init store isn't stamped v22 without tables.
         db.exec(CREATE_TABLE_SESSION_EVENTS_SQL);
         if (!tableHasColumn(db, 'session_events', 'tenant_id')) {
             db.exec(`ALTER TABLE session_events ADD COLUMN tenant_id TEXT NOT NULL DEFAULT 'default'`);
@@ -68,12 +59,8 @@ export const v22 = {
         if (!tableHasColumn(db, 'session_handoffs', 'scope')) {
             db.exec(`ALTER TABLE session_handoffs ADD COLUMN scope TEXT`);
         }
-        // Smart backfill: rows whose session_id maps to exactly one tenant in
-        // task_snapshots inherit that tenant. Ambiguous or unmapped rows stay
-        // at the column default ('default'). Conservative: never crosses
-        // tenant boundaries on guesses. The COUNT(DISTINCT) gate is the load-
-        // bearing check; without it, rows with multiple tenants under the same
-        // session_id would silently pick whichever group came first.
+        // Smart backfill: a row whose session_id maps to exactly one tenant in task_snapshots inherits it; ambiguous or unmapped rows keep 'default'.
+        // The COUNT(DISTINCT) gate is load-bearing: without it a session_id spanning tenants would silently pick whichever group came first.
         db.exec(BACKFILL_SESSION_EVENTS_TENANT_SQL);
         db.exec(BACKFILL_SESSION_HANDOFFS_TENANT_SQL);
         db.exec(`CREATE INDEX IF NOT EXISTS idx_session_events_tenant_session ON session_events(tenant_id, session_id, created_at DESC, id DESC)`);

package/dist/db/migrations/v23.js

@@ -2,9 +2,7 @@ import { tableHasColumn, tableExists } from '../tables.js';
 export const v23 = {
     version: 23,
     up: (db) => {
-        // task_snapshots: add scope so all three continuity tables carry it.
-        // Self-heal partial-init stores via CREATE TABLE IF NOT EXISTS (the v22
-        // session_events / session_handoffs healing is upstream).
+        // task_snapshots: add scope so all three continuity tables carry it; self-heal partial-init stores via CREATE TABLE IF NOT EXISTS.
         db.exec(`
         CREATE TABLE IF NOT EXISTS task_snapshots (
           id INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -22,17 +20,8 @@ export const v23 = {
         if (!tableHasColumn(db, 'task_snapshots', 'scope')) {
             db.exec(`ALTER TABLE task_snapshots ADD COLUMN scope TEXT`);
         }
-        // Quarantine policy: pre-existing continuity rows
-        // with NULL scope cannot be safely classified as public after the fact.
-        // Mark them 'unknown:legacy' so the api.recall + cmdRecall default-deny
-        // filter excludes them for no-scope callers. Fresh rows from new
-        // writers carry NULL when scope is unspecified (legitimate non-Slack
-        // writes); the 'unknown:legacy' marker is a v23-only one-shot for
-        // pre-upgrade rows.
-        //
-        // Run UPDATEs only on tables that exist (some test paths and edge stores
-        // skip v22's table healing). The UPDATEs are themselves idempotent via
-        // the WHERE scope IS NULL clause, so re-running is a no-op.
+        // Quarantine pre-existing continuity rows with NULL scope as 'unknown:legacy' so the recall default-deny filter excludes them for no-scope callers;
+        // new rows legitimately carry NULL. UPDATE only tables that exist (v22 healing is skipped on some paths); WHERE scope IS NULL keeps it idempotent.
         if (tableExists(db, 'task_snapshots')) {
             db.exec(`UPDATE task_snapshots SET scope = 'unknown:legacy' WHERE scope IS NULL`);
         }

package/dist/db/migrations/v24.js

@@ -62,10 +62,8 @@ export const v24 = {
         db.exec(CREATE_TABLE_GITHUB_DLQ_SQL);
         db.exec(`CREATE INDEX IF NOT EXISTS idx_github_dlq_tenant_received ON github_dlq(tenant_id, received_at)`);
         db.exec(CREATE_TABLE_GITHUB_INSTALLATIONS_SQL);
-        // PAT-mode multi-tenant routing. Maps repo_full_name to
-        // tenant when the webhook envelope has no `installation` field. Composite
-        // PK so the same repo can intentionally be visible to multiple tenants
-        // (e.g., shared tooling accounts) — collision is on (repo, tenant) pair.
+        // PAT-mode multi-tenant routing: maps repo_full_name to a tenant when the webhook envelope has no `installation` field.
+        // Composite PK so one repo can be visible to several tenants; the collision is on the (repo, tenant) pair.
         db.exec(CREATE_TABLE_GITHUB_REPOSITORIES_SQL);
         // Rollback-safety guard: an older binary lacks the *:private:* default-deny and would leak
         // github:private:* rows; the startup guard refuses a DB whose min_compatible_binary is newer.

package/dist/db/migrations/v25.js

@@ -2,11 +2,8 @@ import { tableHasColumn } from '../tables.js';
 export const v25 = {
     version: 25,
     up: (db) => {
-        // DAG-aware recall: cache summary metadata so the assembler can
-        // reason about scope without re-walking the DAG. Three additive,
-        // optional columns. No min_compatible_binary bump: these columns are
-        // pure metadata; older binaries opening this DB will see them as NULL
-        // / 0 and behave as before.
+        // DAG-aware recall: three additive optional columns cache summary metadata so the assembler need not re-walk the DAG.
+        // No min_compatible_binary bump: older binaries see them as NULL / 0 and behave as before.
         if (!tableHasColumn(db, 'memories', 'descendant_count')) {
             db.exec(`ALTER TABLE memories ADD COLUMN descendant_count INTEGER NOT NULL DEFAULT 0`);
         }
@@ -16,9 +13,7 @@ export const v25 = {
         if (!tableHasColumn(db, 'memories', 'latest_at')) {
             db.exec(`ALTER TABLE memories ADD COLUMN latest_at TEXT`);
         }
-        // Backfill descendant_count for existing level-2 summary rows. Use
-        // dag_parent_id pointing at the summary id. Level-3 (entity profiles)
-        // not built today; their descendant_count stays at default 0.
+        // Backfill descendant_count for existing level-2 summary rows via dag_parent_id = summary id; level-3 (entity profiles) is not built, so it stays 0.
         db.exec(`
         UPDATE memories
            SET descendant_count = (

package/dist/db/migrations/v26.js

@@ -2,19 +2,8 @@ import { tableHasColumn, tableExists } from '../tables.js';
 export const v26 = {
     version: 26,
     up: (db) => {
-        // Add role column to api_keys for the admin/member
-        // distinction that gates /v1/sleep. Additive — existing keys backfill to
-        // 'admin' via DEFAULT (single-tenant operator = admin by definition).
-        // No min_compatible_binary bump: old binaries ignore the
-        // column on SELECTs that don't name it; new binaries on old data run
-        // this migration at openHippoDb time before any createApiKey call.
-        //
-        // Defensive: also guard on tableExists. If a DB landed in the
-        // partial-v16-state (api_keys table missing despite schema_version >= 16),
-        // running ALTER TABLE here would crash and block all later migrations.
-        // The v27 heal below recreates api_keys with the role column already
-        // present, so this ALTER becomes a no-op anyway for that path. Defense
-        // in depth: guard so v26 never crashes on the partial-apply state.
+        // Add api_keys.role for the admin/member split gating /v1/sleep; existing keys backfill to 'admin' via DEFAULT. No min_compatible_binary bump.
+        // Guard on tableExists: a partial-v16 DB without api_keys would crash this ALTER and block later migrations (v27 heals it with role present).
         if (tableExists(db, 'api_keys') && !tableHasColumn(db, 'api_keys', 'role')) {
             db.exec(`ALTER TABLE api_keys ADD COLUMN role TEXT NOT NULL DEFAULT 'admin'`);
         }

package/dist/db/migrations/v27.js

@@ -2,13 +2,8 @@ import { tableHasColumn, tableExists } from '../tables.js';
 export const v27 = {
     version: 27,
     up: (db) => {
-        // Self-heal: re-assert the v16 schema (api_keys + audit_log) on stores stamped past
-        // v16 whose tables are missing anyway (a dropped table or an old-backup restore).
-        //
-        // All CREATE IF NOT EXISTS — zero-cost no-op for users without the
-        // bug, fixes anyone who has it. Includes the role column from the
-        // start so it matches v26's intent without needing v26 to ALTER on
-        // this heal path.
+        // Self-heal: re-assert the v16 schema (api_keys + audit_log) on stores stamped past v16 whose tables are missing (dropped table or old-backup restore).
+        // All CREATE IF NOT EXISTS, so a no-op for healthy stores; includes the role column so v26's ALTER is not needed on this path.
         db.exec(`
         CREATE TABLE IF NOT EXISTS api_keys (
           id INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -37,10 +32,7 @@ export const v27 = {
         )
       `);
         db.exec(`CREATE INDEX IF NOT EXISTS idx_audit_log_tenant_ts ON audit_log(tenant_id, ts DESC)`);
-        // Belt-and-braces: if api_keys existed before this migration WITHOUT
-        // the role column (i.e. v16-shape table that v26's ALTER skipped due
-        // to tableExists=false on an earlier broken run, then someone manually
-        // CREATEd it without role), backfill role.
+        // Belt-and-braces: backfill role on an api_keys table that exists without it (v16-shape table that v26's ALTER skipped on an earlier broken run).
         if (tableExists(db, 'api_keys') && !tableHasColumn(db, 'api_keys', 'role')) {
             db.exec(`ALTER TABLE api_keys ADD COLUMN role TEXT NOT NULL DEFAULT 'admin'`);
         }

package/dist/db/migrations/v28.js

@@ -2,20 +2,8 @@ import { tableHasColumn } from '../tables.js';
 export const v28 = {
     version: 28,
     up: (db) => {
-        // Dirty-flag persistence for level-2 DAG summaries, so child-write propagation and the
-        // sleep-cycle rebuild can write + read the staleness signal. dag_level_3_built_at lands
-        // now so the entity-profile build path needs no second migration.
-        //
-        // All columns are additive + DEFAULTed/nullable, so backfill is
-        // automatic for existing rows. No min_compatible_binary bump: old
-        // binaries ignore the columns on SELECTs that don't name
-        // them; new binaries on old data hit this migration at openHippoDb
-        // time before any DAG path touches summary_dirty.
-        //
-        // Precedent for column-only guards on memories: v25 (db.ts:827),
-        // which added the DAG cache columns the same way. memories table
-        // itself comes from v1 and is always present, so the tableExists
-        // half of the v26/v27 guard pattern isn't load-bearing here.
+        // Dirty-flag persistence for level-2 DAG summaries; dag_level_3_built_at lands now so the entity-profile path needs no second migration.
+        // Columns are additive and DEFAULTed/nullable, so no min_compatible_binary bump. Column-only guard: memories comes from v1 and always exists.
         if (!tableHasColumn(db, 'memories', 'summary_dirty')) {
             db.exec(`ALTER TABLE memories ADD COLUMN summary_dirty INTEGER NOT NULL DEFAULT 0`);
         }

package/dist/db/migrations/v29.js

@@ -52,28 +52,14 @@ const CREATE_TRIGGER_TRG_PREDICTIONS_TENANT_MATCH_UPDATE_SQL = `
 export const v29 = {
     version: 29,
     up: (db) => {
-        // Prediction first-class object: a predictions table for the reference-class /
-        // planning-fallacy detector. Predictions
-        // duplicate claim_text in the table itself so memory deletion
-        // (forget/consolidate/archive) does not lose prediction data; FK
-        // memory_id is NULLABLE with ON DELETE SET NULL.
-        //
-        // Cross-tenant safety: BEFORE INSERT + BEFORE UPDATE triggers
-        // enforce tenant_id match against the referenced memory. SQLite's
-        // ON DELETE SET NULL is incompatible with composite FK where one
-        // side is NOT NULL, so the trigger pattern replaces a composite
-        // FK target. Precedent: v14 memories.kind trigger pair at db.ts:298-322.
-        //
-        // CHECK constraint pins closure_state to (open|closed|closed-unknown).
-        // Accuracy (clean vs regressed) is computed from (estimate_value,
-        // actual_value) at query time.
+        // Prediction first-class object: claim_text is duplicated so deleting the memory loses nothing; memory_id is NULLABLE ON DELETE SET NULL.
+        // Tenant-match triggers replace a composite FK, which is incompatible with ON DELETE SET NULL; closure_state is CHECKed to open|closed|closed-unknown.
         if (!tableExists(db, 'predictions')) {
             db.exec(CREATE_TABLE_PREDICTIONS_SQL);
             db.exec(CREATE_INDEX_IDX_PREDICTIONS_TENANT_CLASS_SQL);
             db.exec(CREATE_INDEX_IDX_PREDICTIONS_MEMORY_SQL);
-            // Cross-tenant safety: tenant_id must match the referenced memory's
-            // tenant_id when memory_id IS NOT NULL. INSERT + UPDATE pair, mirroring
-            // v14 memories.kind enforcement (db.ts:298-322).
+            // Cross-tenant safety: tenant_id must match the referenced memory's tenant_id when memory_id IS NOT NULL;
+            // INSERT + UPDATE pair, mirroring the v14 memories.kind enforcement.
             db.exec(CREATE_TRIGGER_TRG_PREDICTIONS_TENANT_MATCH_INSERT_SQL);
             db.exec(CREATE_TRIGGER_TRG_PREDICTIONS_TENANT_MATCH_UPDATE_SQL);
         }

package/dist/db/migrations/v30.js

@@ -48,10 +48,8 @@ const TRG_DECISIONS_TENANT_MATCH_UPDATE = `
             END;
           END
         `;
-// Cross-tenant safety vs the successor decision (self-FK). superseded_by
-// is set only via UPDATE (the supersede path); the successor must share
-// the tenant. The successor row already exists in the same transaction
-// when this fires, so the subquery resolves.
+// Cross-tenant safety vs the successor decision (self-FK): superseded_by is set only via the supersede UPDATE and the successor,
+// which already exists in the same transaction when this fires, must share the tenant.
 const TRG_DECISIONS_SUPERSEDE_TENANT_MATCH_UPDATE = `
           CREATE TRIGGER IF NOT EXISTS trg_decisions_supersede_tenant_match_update
           BEFORE UPDATE ON decisions
@@ -67,18 +65,8 @@ const TRG_DECISIONS_SUPERSEDE_TENANT_MATCH_UPDATE = `
 export const v30 = {
     version: 30,
     up: (db) => {
-        // Decision first-class object.
-        // Promotes `hippo decide` from a tagged memory (which decayed on a 90-day
-        // half-life even while the decision was still in force) to a dedicated
-        // decisions table that is the source of truth. The memory mirror is kept
-        // for recall but is no longer authoritative; memory_id is NULLABLE with
-        // ON DELETE SET NULL so forget/consolidate/archive does not lose a
-        // decision. Mirrors the v29 predictions tenant-match trigger pattern.
-        //
-        // status (active|superseded|closed): superseded carries a self-FK
-        // superseded_by to the successor decision; closed is a terminal
-        // retire-without-successor. A superseded_by same-tenant trigger makes
-        // cross-tenant supersession unrepresentable at the schema level.
+        // Decision first-class object, the source of truth for `hippo decide`; the memory mirror serves recall only, memory_id NULLABLE ON DELETE SET NULL.
+        // status active|superseded|closed (closed = retired without successor); a same-tenant trigger on superseded_by blocks cross-tenant supersession.
         if (!tableExists(db, 'decisions')) {
             db.exec(DECISIONS_TABLE);
             db.exec(IDX_DECISIONS_TENANT_STATUS);