@north-light/api 0.3.580 → 0.3.588

package/dist/core/canvas/render-source.js

@@ -0,0 +1,518 @@
+// render-source.ts — the openDb-FREE half of canvas rendering.
+//
+// Every `*FromSource` variant + the pure/disk helpers they share live here so a
+// CLI process rendering the canvas through a `CanvasSource` (the API-backed
+// `ApiCanvasSource`, or a `RemoteCanvasSource`) NEVER drags in `core/canvas/db.ts`
+// (`openDb`) or the `core/canvas/canvas.ts` accessors. This is the whole module now
+// — the sync, db-backed renderers (`renderTree`/`dashboardRows`/…) that used to live
+// in a separate `render.ts` re-export shim have been retired; their few real callers
+// migrated onto these `*FromSource` variants directly.
+//
+// ALLOWED imports (verified openDb-free): node:fs/path, ./labels.js,
+// ./status-glyph.js, ./node-recap.js, ../frontmatter.js,
+// ./paths.js, ./remote-canvas-source.js, and TYPE-ONLY ./source.js + ./types.js. Do NOT import ./canvas.js, ./attention.js,
+// ./focuses.js, or ./db.js here — that is the whole point of the split.
+import { conversationIdFromPath, conversationStore, ConversationNotFoundError, readConversationAsync } from '../conversation-store/index.js';
+import { dirname, join } from 'node:path';
+import { readFileBeneath, readTextBeneathIfExists } from '../spaces/open-beneath.js';
+import { RemoteCanvasSource } from './remote-canvas-source.js';
+import { fullName } from './labels.js';
+import { nodeRunDir, nodeRunJobDir, contextDir } from './paths.js';
+import { readNodeRecap } from './node-recap.js';
+import { isFrozenRow, resolveNodeVisual, faultSummary } from './status-glyph.js';
+import { parseCard } from '../../shared/generated-context.js';
+/** Format a token count as `Nk` (rounded down to nearest 1 k). */
+export function fmtCtx(tokensIn) {
+    if (tokensIn === undefined || tokensIn === 0)
+        return '0k';
+    return `${Math.floor(tokensIn / 1000)}k`;
+}
+// Source-driven tree builder (openDb-free)
+//
+// Ticket counts are threaded in as a `Record<node_id, count>` fetched ONCE per
+// render via `source.ticketCountsForView(root)` (the API/remote source's
+// attention projection) — never `countTickets()` (openDb). The active fault is a
+// projected row field (the owning daemon already applied the stale-provider
+// overlay), so it renders for a remote node too; `ctx` is likewise projected and
+// stays suppressed when the source is a `RemoteCanvasSource`.
+function nodeLineFromSource(node, nodeId, indent, connector, remote, tickets) {
+    if (node === undefined)
+        return `${indent}${connector}? <missing meta: ${nodeId}>`;
+    const hanging = node.fault ?? null;
+    const glyph = resolveNodeVisual(node.status, { hanging, frozen: isFrozenRow(node) }).glyph;
+    const ctx = remote ? '0k' : fmtCtx(node.telemetry_tokens_in ?? undefined);
+    const asks = tickets[nodeId] ?? 0;
+    const askSuffix = asks > 0 ? ` ⚑${asks}` : '';
+    const faultSuffix = hanging !== null ? ` · ${faultSummary(hanging)}` : '';
+    return `${indent}${connector}${glyph} ${fullName(node)} [${node.kind}/${node.mode}] ctx ${ctx}${askSuffix}${faultSuffix}`;
+}
+async function walkTreeFromSource(source, nodes, nodeId, indent, isLast, visited, out, remote, tickets) {
+    if (visited.has(nodeId))
+        return;
+    visited.add(nodeId);
+    const connector = isLast ? '└─ ' : '├─ ';
+    out.push(nodeLineFromSource(nodes.get(nodeId), nodeId, indent, connector, remote, tickets));
+    const childIndent = indent + (isLast ? '   ' : '│  ');
+    let children;
+    try {
+        children = await source.subscriptionsOf(nodeId);
+    }
+    catch (err) {
+        out.push(`${childIndent}⚠ children unavailable: ${err instanceof Error ? err.message : String(err)}`);
+        return;
+    }
+    for (let i = 0; i < children.length; i++) {
+        const child = children[i];
+        const childIsLast = i === children.length - 1;
+        if (visited.has(child.node_id)) {
+            const cycleConnector = childIsLast ? '└─ ' : '├─ ';
+            out.push(`${childIndent}${cycleConnector}↺ <cycle: ${child.node_id}>`);
+            continue;
+        }
+        await walkTreeFromSource(source, nodes, child.node_id, childIndent, childIsLast, visited, out, remote, tickets);
+    }
+}
+export async function renderTreeFromSource(source, rootId, snapshot, ticketSnapshot, ticketUnavailable) {
+    const remote = source instanceof RemoteCanvasSource;
+    const nodes = new Map((snapshot ?? await source.listNodes()).map((node) => [node.node_id, node]));
+    const node = nodes.get(rootId);
+    if (node === undefined)
+        return `? <missing node: ${rootId}>`;
+    let tickets = ticketSnapshot;
+    let ticketsUnavailable = ticketUnavailable ?? null;
+    if (tickets === undefined) {
+        try {
+            tickets = await source.ticketCountsForView(rootId);
+        }
+        catch (err) {
+            tickets = {};
+            ticketsUnavailable = err instanceof Error ? err.message : String(err);
+        }
+    }
+    const ctx = remote ? '0k' : fmtCtx(node.telemetry_tokens_in ?? undefined);
+    const asks = tickets[rootId] ?? 0;
+    const askSuffix = asks > 0 ? ` ⚑${asks}` : '';
+    const hanging = node.fault ?? null;
+    const glyph = resolveNodeVisual(node.status, { hanging, frozen: isFrozenRow(node) }).glyph;
+    const faultSuffix = hanging !== null ? ` · ${faultSummary(hanging)}` : '';
+    const out = [];
+    out.push(`${glyph} ${fullName(node)} [${node.kind}/${node.mode}] ctx ${ctx}${askSuffix}${faultSuffix}`);
+    const visited = new Set([rootId]);
+    let children;
+    try {
+        children = await source.subscriptionsOf(rootId);
+    }
+    catch (err) {
+        out.push(`⚠ children unavailable: ${err instanceof Error ? err.message : String(err)}`);
+        children = [];
+    }
+    for (let i = 0; i < children.length; i++) {
+        const child = children[i];
+        const isLast = i === children.length - 1;
+        await walkTreeFromSource(source, nodes, child.node_id, '', isLast, visited, out, remote, tickets);
+    }
+    if (ticketsUnavailable !== null)
+        out.push(`Tickets: unavailable (${ticketsUnavailable}).`);
+    return out.join('\n');
+}
+export async function renderForestFromSource(source, snapshot, ticketSnapshot, ticketUnavailable) {
+    const all = snapshot ?? await source.listNodes();
+    if (all.length === 0)
+        return '(canvas is empty)';
+    const roots = all.filter((n) => n.parent === null && (n.status === 'active' || n.status === 'idle'));
+    if (roots.length === 0)
+        return '(no live roots)';
+    const parts = [];
+    for (const r of roots) {
+        parts.push(await renderTreeFromSource(source, r.node_id, all, ticketSnapshot, ticketUnavailable));
+    }
+    return parts.join('\n\n');
+}
+/** The spawn prompt, read straight off disk (canvas-home state) and capped so a
+ *  giant initial-prompt.md can't bloat the snapshot. Mirrors how telemetry is
+ *  read here directly rather than via the runtime layer (which would invert the
+ *  canvas→runtime dependency). Never throws. */
+const GOAL_CAP = 4096;
+export function readGoalText(contextPath) {
+    try {
+        // Beneath the node's agent folder, so a symlinked context or goal is never followed.
+        const body = readTextBeneathIfExists(dirname(contextPath), join(contextPath, 'initial-prompt.md'))?.trim() ?? '';
+        if (body === '')
+            return undefined;
+        return body.length > GOAL_CAP ? body.slice(0, GOAL_CAP) : body;
+    }
+    catch {
+        return undefined;
+    }
+}
+const REPORT_BODY_CAP = 1024;
+/** The node's newest report document, reduced to a preview. Never throws;
+ *  undefined when the node pushed nothing. */
+export function reportPreview(report) {
+    if (report === null || report === undefined)
+        return undefined;
+    const kind = report.tier;
+    const ts = report.created;
+    const body = report.body;
+    // The heading is the report's own headline; everything after it is the detail the
+    // preview shows next, so a panel never repeats the heading twice.
+    const lines = body.split('\n');
+    let heading = '';
+    let rest = body;
+    for (let i = 0; i < lines.length; i++) {
+        const t = (lines[i] ?? '').trim();
+        if (t === '')
+            continue;
+        heading = t.startsWith('#') ? t.replace(/^#+\s*/, '').trim() : t;
+        rest = lines.slice(i + 1).join('\n');
+        break;
+    }
+    const text = rest.replace(/\s+/g, ' ').trim();
+    return { kind, ts, heading, body: text.length > REPORT_BODY_CAP ? text.slice(0, REPORT_BODY_CAP) : text };
+}
+/** Read only the ENDS of a conversation that a preview actually needs.
+ *
+ *  A conversation grows without bound — this canvas holds 2 GB of them across ~2400
+ *  nodes, the largest single file 67 MB — and every reader below wants either the
+ *  FIRST few prompts or the LAST few turns. The panel paints a few dozen lines, so
+ *  the preview reads a small tail and widens it only when that tail landed inside
+ *  one huge record and yielded nothing; search text reads a small head and tail.
+ *
+ *  Reads go through the store asynchronously: a synchronous read parks the browse
+ *  event loop on the store worker for as long as the (busy) daemon takes to answer,
+ *  which froze cursor movement for seconds per row.
+ *
+ *  The store reads a conversation at or under head+tail bytes whole (both windows are
+ *  then the whole conversation); above that, only entries wholly inside each window.
+ *  Returns null when the conversation does not exist. */
+const PREVIEW_TAIL_BUDGETS = [256 << 10, 1 << 20, 4 << 20];
+const PROMPTS_HEAD_BYTES = 64 << 10;
+const PROMPTS_TAIL_BYTES = 64 << 10;
+async function readSessionWindow(sessionFile, headBytes, tailBytes) {
+    if (sessionFile === undefined || sessionFile === null || sessionFile === '')
+        return null;
+    const id = conversationIdFromPath(sessionFile);
+    if (id === null)
+        return null;
+    try {
+        const { entries, tail } = await readConversationAsync(id, { head: headBytes, tail: tailBytes });
+        return { head: entries, tail: tail ?? entries, windowed: tail !== undefined };
+    }
+    catch (error) {
+        if (error instanceof ConversationNotFoundError)
+            return null;
+        throw error;
+    }
+}
+/** Every user prompt across the session (`prompts`), joined and capped — the
+ *  whole-conversation text super-search matches against. Reads the opening and
+ *  closing 64 KB: the spawn prompt and the newest asks, which is what a search for
+ *  a node is almost always after. Undefined when there is no session or no prompt. */
+const CONVO_CAP = 8192;
+const CONVO_MSG_CAP = 2048;
+export async function readSessionPrompts(sessionFile) {
+    const win = await readSessionWindow(sessionFile, PROMPTS_HEAD_BYTES, PROMPTS_TAIL_BYTES);
+    if (win === null)
+        return undefined;
+    const parts = [];
+    let total = 0;
+    for (const entry of win.windowed ? [...win.head, ...win.tail] : win.head) {
+        if (entry.type !== 'message' || entry.message.role !== 'user')
+            continue;
+        const text = extractUserText(entry.message.content);
+        if (text === '')
+            continue;
+        if (parseCard({ role: 'user', content: text }) !== null)
+            continue;
+        const capped = text.length > CONVO_MSG_CAP ? text.slice(0, CONVO_MSG_CAP) : text;
+        parts.push(capped);
+        total += capped.length + 1;
+        if (total >= CONVO_CAP)
+            break;
+    }
+    if (parts.length === 0)
+        return undefined;
+    const joined = parts.join('\n');
+    return joined.length > CONVO_CAP ? joined.slice(0, CONVO_CAP) : joined;
+}
+/** How many trailing turns the transcript keeps. A preview panel can paint a few
+ *  dozen lines, and search only ever windows to a match, so the whole history is
+ *  never needed. */
+const TRANSCRIPT_TURNS = 120;
+const TRANSCRIPT_MSG_CAP = 4096;
+export async function readSessionTail(sessionFile) {
+    let result = { transcript: [] };
+    for (const budget of PREVIEW_TAIL_BUDGETS) {
+        const win = await readSessionWindow(sessionFile, 0, budget);
+        if (win === null)
+            return result;
+        result = sessionTailFrom(win.tail);
+        if (!win.windowed || result.lastAssistant !== undefined)
+            return result;
+    }
+    return result;
+}
+function sessionTailFrom(entries) {
+    const turns = [];
+    let lastAssistant;
+    for (const entry of entries) {
+        if (entry.type !== 'message')
+            continue;
+        const role = entry.message.role;
+        if (role !== 'user' && role !== 'assistant')
+            continue;
+        const text = extractUserText(entry.message.content);
+        if (text === '')
+            continue;
+        if (role === 'assistant')
+            lastAssistant = text.length > CONVO_MSG_CAP ? text.slice(0, CONVO_MSG_CAP) : text;
+        if (parseCard({ role, content: text }) !== null)
+            continue;
+        turns.push({ role, text: text.length > TRANSCRIPT_MSG_CAP ? text.slice(0, TRANSCRIPT_MSG_CAP) : text });
+    }
+    return {
+        transcript: turns.length > TRANSCRIPT_TURNS ? turns.slice(turns.length - TRANSCRIPT_TURNS) : turns,
+        ...(lastAssistant === undefined ? {} : { lastAssistant }),
+    };
+}
+/** Did this node's engine ever PRODUCE something — an assistant message with real
+ *  text, a tool call, or non-empty reasoning? The signal that a node did work and
+ *  is not an empty shell. A never-revived node (no session file) is trivially
+ *  false; an assistant turn that is only an empty/aborted `thinking` stub does NOT
+ *  count (that's a node started and killed before it did anything). CONSERVATIVE
+ *  by design: ANY substance keeps the node, so the reap never deletes real work
+ *  — a tool-call-only turn (no final text) still counts. Drives reap-on-close/
+ *  detach. One file read with an early exit on the first substantive turn. */
+export async function nodeHasAssistantMessage(sessionFile) {
+    if (sessionFile === undefined || sessionFile === null || sessionFile === '')
+        return false;
+    const id = conversationIdFromPath(sessionFile);
+    if (id === null)
+        return false;
+    let entries;
+    try {
+        entries = (await conversationStore().read(id)).entries;
+    }
+    catch (error) {
+        if (error instanceof ConversationNotFoundError)
+            return false;
+        throw error;
+    }
+    for (const entry of entries) {
+        if (entry.type !== 'message' || entry.message.role !== 'assistant')
+            continue;
+        if (assistantContentIsSubstantive(entry.message.content))
+            return true;
+    }
+    return false;
+}
+/** True when an assistant message's content has at least one block that PRODUCED
+ *  something: non-empty text, non-empty thinking, a tool call (`toolCall`/
+ *  `tool_use`/…), or any other non-thinking/text block type. The lone non-case is
+ *  an empty thinking stub (`[{type:'thinking',thinking:''}]`) or empty content —
+ *  what an immediately-aborted first turn leaves behind. */
+function assistantContentIsSubstantive(content) {
+    if (typeof content === 'string')
+        return content.trim() !== '';
+    if (!Array.isArray(content))
+        return false;
+    for (const block of content) {
+        if (block === null || typeof block !== 'object')
+            continue;
+        const b = block;
+        const t = (b.type ?? '').toLowerCase();
+        if (t === 'text') {
+            if (typeof b.text === 'string' && b.text.trim() !== '')
+                return true;
+        }
+        else if (t === 'thinking') {
+            if (typeof b.thinking === 'string' && b.thinking.trim() !== '')
+                return true;
+        }
+        else
+            return true; // toolCall / tool_use / toolResult / any other block = real output
+    }
+    return false;
+}
+/** Concatenate the `text` blocks of one pi user message's content. Content is
+ *  usually an array of `{type,text}` blocks but may be a bare string. */
+function extractUserText(content) {
+    if (typeof content === 'string')
+        return content.trim();
+    if (!Array.isArray(content))
+        return '';
+    const out = [];
+    for (const block of content) {
+        if (block !== null && typeof block === 'object') {
+            const b = block;
+            if (b.type === 'text' && typeof b.text === 'string')
+                out.push(b.text);
+        }
+    }
+    return out.join(' ').trim();
+}
+/** "Most recent activity" sort key from the daemon's telemetry projection. It
+ * falls back to `created` when the broker has never reported telemetry. */
+export function sessionMtime(created, telemetryUpdatedAt, remote = false) {
+    if (!remote && telemetryUpdatedAt !== null && telemetryUpdatedAt !== undefined) {
+        const t = Date.parse(telemetryUpdatedAt);
+        if (!Number.isNaN(t))
+            return t;
+    }
+    const t = Date.parse(created);
+    return Number.isNaN(t) ? 0 : t;
+}
+function hasLiveBrokerViewer(row) {
+    if (row.status !== 'active')
+        return false; // a crashed broker can leave stale attach.json
+    try {
+        const record = JSON.parse(readFileBeneath(nodeRunDir(row.node_id), join(nodeRunJobDir(row.node_id), 'attach.json')).toString('utf8'));
+        return typeof record.viewers === 'number' && record.viewers > 0;
+    }
+    catch {
+        return false;
+    }
+}
+/** Build one cheap-boot row from a raw db/source row. `fault`/`streaming` are
+ *  projected row fields, so they hold for a remote row too; `remote` suppresses the
+ *  LOCAL disk reads (telemetry-mtime/viewers) that are meaningless for a truly
+ *  remote canvas. A local row is viewed when either its tmux focus row exists or
+ *  its live broker reports a terminal/web viewer. */
+export function dashboardRowFromNodeRow(row, focusedNodeIds, remote) {
+    const live = row.status === 'active' || row.status === 'idle';
+    const hanging = row.fault ?? null;
+    return {
+        node_id: row.node_id,
+        name: fullName(row), // description is a row column (v38) — no meta read needed
+        handle: row.name,
+        description: row.description,
+        status: row.status,
+        frozen_at: row.frozen_at ?? null,
+        terminal_reason: row.terminal_reason ?? null,
+        kind: row.kind,
+        mode: row.mode,
+        ctx_tokens: remote ? 0 : (row.telemetry_tokens_in ?? 0),
+        asks: 0, // lazy: enrichRow / enrichRows
+        cwd: row.cwd,
+        profile_id: row.profile_id,
+        created: row.created,
+        lifecycle: row.lifecycle,
+        finalized: row.final_report != null,
+        mtimeMs: sessionMtime(row.created, row.telemetry_updated_at, remote),
+        streaming: hanging === null && live && row.streaming === true,
+        hanging,
+        viewed: remote ? false : focusedNodeIds.has(row.node_id) || hasLiveBrokerViewer(row),
+        srcRow: row,
+    };
+}
+/** One row per node visible in the sub-DAG of `rootId` (including root), read
+ *  entirely through the source — the openDb-free sibling of `dashboardRows`.
+ *  Ticket counts come from ONE `source.ticketCountsForView(rootId)` call (the
+ *  API/remote attention projection), never `countTickets` (openDb). */
+export async function dashboardRowsFromSource(source, rootId, snapshot, ticketSnapshot) {
+    const remote = source instanceof RemoteCanvasSource;
+    const tickets = ticketSnapshot ?? await source.ticketCountsForView(rootId).catch(() => ({}));
+    const nodes = new Map((snapshot ?? await source.listNodes()).map((node) => [node.node_id, node]));
+    const ids = [rootId, ...(await source.view(rootId))];
+    return ids.flatMap((id) => {
+        const node = nodes.get(id);
+        if (node === undefined)
+            return [];
+        return [{
+                node_id: id,
+                name: fullName(node),
+                handle: node.name,
+                description: node.description,
+                status: node.status,
+                frozen_at: node.frozen_at ?? null,
+                terminal_reason: node.terminal_reason ?? null,
+                kind: node.kind,
+                mode: node.mode,
+                ctx_tokens: remote ? 0 : (node.telemetry_tokens_in ?? 0),
+                asks: tickets[id] ?? 0,
+                cwd: node.cwd,
+                profile_id: node.profile_id,
+                created: node.created,
+            }];
+    });
+}
+/** CHEAP boot builder over a source — one row per node across the whole canvas,
+ *  fields that need no per-node meta/session read. Local API callers may supply
+ *  the node ids from one `listFocuses()` query so `viewed` remains visible without
+ *  coupling the canvas source to local viewer state. Remote sources ignore that
+ *  set. Local disk telemetry is likewise suppressed remotely. */
+export async function dashboardRowsAllFromSource(source, localFocusedNodeIds = new Set(), liveOnly = false, snapshot) {
+    const remote = source instanceof RemoteCanvasSource;
+    const focusedNodeIds = remote ? new Set() : localFocusedNodeIds;
+    const rows = snapshot ?? await source.listNodes(liveOnly ? { status: ['active', 'idle'] } : undefined);
+    return rows.map((row) => dashboardRowFromNodeRow(row, focusedNodeIds, remote));
+}
+// Lazy enrichment adds only caller-supplied ticket counts. Labels and telemetry
+// already arrive in the single `listNodes` projection.
+export async function enrichRowsFromSource(_source, rows, asks) {
+    const todo = rows.filter((r) => r.enriched !== true);
+    if (todo.length === 0)
+        return;
+    const askMap = asks ?? {};
+    for (const row of todo) {
+        row.asks = askMap[row.node_id] ?? 0;
+        row.enriched = true;
+    }
+}
+/** The node's app context dir, from the API paths or the row's grantee. */
+async function contextPathOf(source, row, meta) {
+    const apiPaths = meta?.paths;
+    if (apiPaths !== undefined)
+        return apiPaths.context_dir;
+    const grantee = row.srcRow?.grantee ?? (await source.getRow(row.node_id))?.grantee;
+    if (!grantee)
+        throw new Error(`node ${row.node_id} has no app assignment`);
+    return contextDir(row.node_id, grantee);
+}
+/** The selected row's preview: goal, recap, newest report and the session's recent
+ *  end (`lastAssistant`), from one small tail read. `transcript: true` also folds the
+ *  ordered chat turns from that same read — ask for it for the SELECTED row only,
+ *  never across the canvas, where one transcript per node is exactly the memory cost
+ *  the capped fields avoid. goal, recap and session are local disk reads, suppressed
+ *  for a remote source (its transcript stays empty). */
+export async function loadPreviewFromSource(source, row, opts = {}) {
+    const wantTranscript = opts.transcript === true && row.transcriptLoaded !== true;
+    if (row.previewLoaded === true && !wantTranscript)
+        return row;
+    if (source instanceof RemoteCanvasSource) {
+        row.previewLoaded = true;
+        if (wantTranscript) {
+            row.transcript = [];
+            row.transcriptLoaded = true;
+        }
+        return row;
+    }
+    const meta = await source.getNode(row.node_id);
+    const tail = await readSessionTail(meta?.pi_session_file);
+    if (row.previewLoaded !== true) {
+        row.goal ??= readGoalText(await contextPathOf(source, row, meta));
+        row.lastAssistant = tail.lastAssistant;
+        row.recap = readNodeRecap(row.node_id);
+        row.report = reportPreview(await source.newestReport?.(row.node_id).catch(() => null));
+        row.previewLoaded = true;
+    }
+    if (wantTranscript) {
+        row.transcript = tail.transcript;
+        row.transcriptLoaded = true;
+    }
+    return row;
+}
+/** The text super-search matches: the spawn prompt (`goal`) and the session's user
+ *  prompts (`prompts`). Read for every row once a search opens, so it is only the
+ *  small prompt window — never the preview's recap, report or transcript. Local only. */
+export async function loadSearchTextFromSource(source, row) {
+    if (row.promptsLoaded === true)
+        return row;
+    if (!(source instanceof RemoteCanvasSource)) {
+        const meta = await source.getNode(row.node_id);
+        row.goal ??= readGoalText(await contextPathOf(source, row, meta));
+        row.prompts = await readSessionPrompts(meta?.pi_session_file);
+    }
+    row.promptsLoaded = true;
+    return row;
+}

package/dist/core/canvas/schema-chain.d.ts

@@ -0,0 +1,33 @@
+import type pg from 'pg';
+/** The version `schema-pg.sql` writes; every delta number is above it. */
+export declare const BASELINE_VERSION = 1;
+export declare const DEFAULT_STEP_LOCK_TIMEOUT_MS = 5000;
+export declare const DEFAULT_STEP_RETRY_BUDGET_MS = 120000;
+export interface SchemaDelta {
+    version: number;
+    name: string;
+    file: string;
+}
+/** The delta files in `dir`, in number order. They must be numbered contiguously from {@link BASELINE_VERSION} + 1; any other
+ *  entry except `.gitkeep` (which keeps the directory in git while it is empty) is an error. */
+export declare function listDeltas(dir?: string): SchemaDelta[];
+export type SchemaEmit = (level: 'info' | 'warn', event: string, fields: Record<string, string | number>) => void;
+export interface SchemaChainOptions {
+    /** The Postgres schema holding the canvas tables (`CRTR_DATABASE_SCHEMA`, see `canvasDatabaseSchema`). Created when absent and set as the session's `search_path`. Default: the role's own (`public`). */
+    schema?: string;
+    /** The build's schema version. Default {@link CANVAS_SCHEMA_VERSION}; a test passes another to drive fixture deltas. */
+    version?: number;
+    /** The directory of delta files. Default `schema-pg/` beside this module; a test passes a fixture directory. */
+    deltaDir?: string;
+    /** `lock_timeout` of each step. */
+    lockTimeoutMs?: number;
+    /** How long one step keeps retrying after lock timeouts before the open fails. */
+    retryBudgetMs?: number;
+    /** Receives `schema.step.applied` after each committed step and `schema.step.lock_timeout` before each retry. */
+    emit?: SchemaEmit;
+}
+/** Bring the connected database to this build's schema. Takes `pg_advisory_lock` for the session and reads the version under
+ *  it, so processes opening together queue and a late one applies nothing. Refuses a database whose `schema_min_reader` is above
+ *  this build's version; opens one whose `schema_version` is above it when `schema_min_reader` allows. A database with no
+ *  `schema_version` gets `schema-pg.sql`, which runs as one multi-statement simple query, one transaction. */
+export declare function ensureSchema(client: pg.Client, options?: SchemaChainOptions): Promise<void>;

package/dist/core/canvas/schema-chain.js

@@ -0,0 +1,110 @@
+// schema-chain.ts — the only code that changes the canvas schema of a Postgres database. It applies the frozen baseline
+// `schema-pg.sql` (version 1) to an empty schema, then each delta `schema-pg/NNN-<name>.sql` above the stored version in
+// number order, each in its own transaction with its guarded version update. The same runner builds production databases,
+// the test template (`scripts/test-lane.mjs`) and the gate database. It imports only `pg` (types) and node built-ins so a
+// plain-node script can load it. Design: [[design-fleet]] "Schema chain contract".
+import { readdirSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { CANVAS_SCHEMA_VERSION, readStoredVersions } from './schema-version.js';
+const CANVAS_DIR = dirname(fileURLToPath(import.meta.url));
+const SCHEMA_FILE = join(CANVAS_DIR, 'schema-pg.sql');
+const DELTA_DIR = join(CANVAS_DIR, 'schema-pg');
+/** Serializes schema application across processes that open the same database at once (advisory locks are per database). */
+const SCHEMA_LOCK_KEY = 7_427_001;
+/** The version `schema-pg.sql` writes; every delta number is above it. */
+export const BASELINE_VERSION = 1;
+export const DEFAULT_STEP_LOCK_TIMEOUT_MS = 5_000;
+export const DEFAULT_STEP_RETRY_BUDGET_MS = 120_000;
+const LOCK_NOT_AVAILABLE = '55P03';
+/** `NNN-<name>.sql`: the delta that takes a database from version NNN−1 to NNN. */
+const DELTA_FILE = /^(\d{3})-([a-z0-9][a-z0-9-]*)\.sql$/;
+/** The delta files in `dir`, in number order. They must be numbered contiguously from {@link BASELINE_VERSION} + 1; any other
+ *  entry except `.gitkeep` (which keeps the directory in git while it is empty) is an error. */
+export function listDeltas(dir = DELTA_DIR) {
+    const deltas = [];
+    for (const entry of readdirSync(dir).sort()) {
+        if (entry === '.gitkeep')
+            continue;
+        const match = DELTA_FILE.exec(entry);
+        if (match === null)
+            throw new Error(`schema delta directory ${dir}: ${entry} is not named NNN-<name>.sql`);
+        deltas.push({ version: Number(match[1]), name: match[2], file: join(dir, entry) });
+    }
+    deltas.forEach((delta, index) => {
+        if (delta.version !== BASELINE_VERSION + 1 + index) {
+            throw new Error(`schema delta directory ${dir}: expected delta ${BASELINE_VERSION + 1 + index} but found ${delta.version}-${delta.name}.sql; deltas are numbered contiguously from ${BASELINE_VERSION + 1}`);
+        }
+    });
+    return deltas;
+}
+const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+/** One step: `BEGIN; SET LOCAL lock_timeout; <delta>; guarded UPDATE of schema_version; COMMIT`. DDL is transactional, so a
+ *  failure or a kill leaves the schema and the version as they were. A lock timeout rolls back and retries with backoff. */
+async function applyStep(client, delta, options) {
+    const sql = readFileSync(delta.file, 'utf8');
+    const started = Date.now();
+    let backoff = 250;
+    for (let attempt = 1;; attempt++) {
+        try {
+            await client.query('BEGIN');
+            await client.query(`SET LOCAL lock_timeout = '${options.lockTimeoutMs}ms'`);
+            await client.query(sql);
+            const guarded = await client.query(`UPDATE canvas_meta SET value = $1 WHERE key = 'schema_version' AND value = $2`, [String(delta.version), String(delta.version - 1)]);
+            if (guarded.rowCount !== 1)
+                throw new Error(`schema step ${delta.version} (${delta.name}): schema_version was not ${delta.version - 1}; another writer changed the schema outside the chain`);
+            await client.query('COMMIT');
+            options.emit?.('info', 'schema.step.applied', { version: delta.version, name: delta.name, ms: Date.now() - started, attempts: attempt });
+            return;
+        }
+        catch (error) {
+            await client.query('ROLLBACK').catch(() => undefined);
+            if (error.code !== LOCK_NOT_AVAILABLE)
+                throw error;
+            if (Date.now() + backoff - started > options.retryBudgetMs) {
+                throw new Error(`schema step ${delta.version} (${delta.name}) could not get its locks within ${options.retryBudgetMs} ms (${attempt} attempts); a long transaction holds a table it needs`, { cause: error });
+            }
+            options.emit?.('warn', 'schema.step.lock_timeout', { version: delta.version, name: delta.name, attempt, retry_in_ms: backoff });
+            await sleep(backoff);
+            backoff = Math.min(backoff * 2, 10_000);
+        }
+    }
+}
+/** Bring the connected database to this build's schema. Takes `pg_advisory_lock` for the session and reads the version under
+ *  it, so processes opening together queue and a late one applies nothing. Refuses a database whose `schema_min_reader` is above
+ *  this build's version; opens one whose `schema_version` is above it when `schema_min_reader` allows. A database with no
+ *  `schema_version` gets `schema-pg.sql`, which runs as one multi-statement simple query, one transaction. */
+export async function ensureSchema(client, options = {}) {
+    const build = options.version ?? CANVAS_SCHEMA_VERSION;
+    const deltas = listDeltas(options.deltaDir);
+    if (options.schema !== undefined) {
+        const quoted = `"${options.schema.replace(/"/g, '""')}"`;
+        await client.query(`CREATE SCHEMA IF NOT EXISTS ${quoted}`);
+        await client.query(`SET search_path TO ${quoted}`);
+    }
+    await client.query('SELECT pg_advisory_lock($1)', [SCHEMA_LOCK_KEY]);
+    try {
+        let stored = await readStoredVersions(client);
+        if (stored !== undefined && build < stored.minReader) {
+            throw new Error(`unsupported canvas schema: this build is at version ${build} but the database requires readers at version ${stored.minReader} or above (it is at ${stored.version}); this build is older than the database. Select a newer runtime generation.`);
+        }
+        if (stored === undefined) {
+            await client.query(readFileSync(SCHEMA_FILE, 'utf8'));
+            stored = await readStoredVersions(client);
+            if (stored === undefined)
+                throw new Error('schema-pg.sql did not write canvas_meta.schema_version');
+        }
+        let version = stored.version;
+        for (const delta of deltas) {
+            if (delta.version <= version)
+                continue;
+            version = delta.version;
+            await applyStep(client, delta, { lockTimeoutMs: options.lockTimeoutMs ?? DEFAULT_STEP_LOCK_TIMEOUT_MS, retryBudgetMs: options.retryBudgetMs ?? DEFAULT_STEP_RETRY_BUDGET_MS, emit: options.emit });
+        }
+        if (version < build)
+            throw new Error(`canvas schema version ${version} does not match this build's ${build}: no delta reaches it`);
+    }
+    finally {
+        await client.query('SELECT pg_advisory_unlock($1)', [SCHEMA_LOCK_KEY]).catch(() => undefined);
+    }
+}