@north-light/api 0.3.580 → 0.3.587

package/dist/core/canvas/executions.d.ts

@@ -0,0 +1,125 @@
+export interface Execution {
+    executionId: string;
+    nodeId: string;
+    daemonEpoch: string | null;
+    pid: number | null;
+    processIdentity: string | null;
+    state: 'launching' | 'running' | 'exited';
+    startedAt: string;
+    endedAt: string | null;
+    exitReason: string | null;
+    runner: 'process' | 'blaxel' | 'machine';
+    sandboxName: string | null;
+    attempt: number;
+    /** The release the wake accepted. */
+    release: string | null;
+    heartbeatAt: string | null;
+    awakeSince: string | null;
+    idleAt: string | null;
+    exitedAt: string | null;
+    /** The launch recipe the wake wrote: invocation argv and env, config snapshot, system prompt text, scopes. */
+    launchJson: string | null;
+    stopRequestedAt: string | null;
+    stopAfterTurn: boolean;
+    stopReason: string | null;
+}
+/** Reasons that end a launch the broker never reported `running` for; nothing the broker owned needs cleanup. */
+export type ExecutionEndReason = 'launch_lost' | 'launch_timeout' | (string & {});
+export declare function liveExecutionForNode(nodeId: string): Promise<Execution | null>;
+export interface BeginExecutionInput {
+    daemonEpoch: string | null;
+    runner?: Execution['runner'];
+    /** Defaults to one above the node's highest attempt. */
+    attempt?: number;
+    sandboxName?: string | null;
+    release?: string | null;
+    launchJson?: string | null;
+    /** The broker cap. The count of other nodes' live rows and this insert are one step under a database-wide lock,
+     *  so two processes beginning at cap-1 cannot both take the last slot. */
+    cap?: number;
+}
+/** Thrown by `beginExecution` when `cap` other nodes already hold a live execution row. */
+export declare class ExecutionCapReached extends Error {
+    readonly cap: number;
+    readonly live: number;
+    constructor(cap: number, live: number);
+}
+/** Thrown by `beginExecution` when the node already holds a live execution another caller owns: a remote one, or a process
+ *  one this daemon epoch began. The holder keeps its row and token; the caller adopts it or backs off, never replaces it. */
+export declare class ExecutionAlreadyLive extends Error {
+    readonly nodeId: string;
+    readonly executionId: string;
+    constructor(nodeId: string, executionId: string);
+}
+/** Inserts the `launching` row. It mints no token: the runner mints inside `start` (design D74). */
+export declare function beginExecution(nodeId: string, input: BeginExecutionInput): Promise<string>;
+/** Persist the complete launch recipe before handing the execution to a runner. */
+export declare function setExecutionLaunchJson(executionId: string, launchJson: string): Promise<void>;
+/** The broker went idle with nothing holding it (design D18): stamps `idle_at` on its running execution, once per awake period. */
+export declare function recordExecutionIdle(executionId: string): Promise<boolean>;
+/** A thawed resident broker starts a new awake period: `awake_since` is now and `idle_at` is cleared. */
+export declare function recordExecutionAwake(executionId: string): Promise<void>;
+/** Returns shutdown when a late broker references an execution no longer live. */
+export declare function recordExecutionPid(executionId: string, nodeId: string, pid: number): Promise<'recorded' | 'shutdown'>;
+/**
+ * Ends the execution, revokes its token and clears the node's supervision marks in one transaction.
+ * `launch_lost` and `launch_timeout` are the recovery ends of a `launching` row (design, Execution token hand-off).
+ */
+export declare function endExecution(executionId: string, input: {
+    reason: ExecutionEndReason;
+}): Promise<boolean>;
+/** Ends the execution only while it is still `launching`: false when a `session.bound` already made it `running`, so a stale
+ *  timeout decision never kills a broker that bound. The caller stops the external process only on true. */
+export declare function endLaunchingExecution(executionId: string, input: {
+    reason: ExecutionEndReason;
+}): Promise<boolean>;
+export declare function abortExecution(executionId: string, input: {
+    reason: string;
+}): Promise<boolean>;
+export declare function endLiveExecution(nodeId: string, input: {
+    reason: ExecutionEndReason;
+}): Promise<boolean>;
+export declare function migrateLegacyExecutionIdentities(captureIdentity?: (pid: number) => string | undefined): Promise<{
+    migrated: string[];
+}>;
+/** Records a stop request on the node's live execution; the first request's time and reason stand. */
+export declare function requestExecutionStop(nodeId: string, input: {
+    afterTurn: boolean;
+    reason: string;
+}): Promise<boolean>;
+/** Live executions with a stop requested at or before `requestedBefore` (ISO time). A request this old has outlived the
+ *  process that queued it, whose own teardown runs within seconds. */
+export declare function executionsWithStopRequestedBefore(requestedBefore: string): Promise<Execution[]>;
+/** The node's most recent execution row, live or ended. */
+export declare function latestExecutionForNode(nodeId: string): Promise<Execution | null>;
+/** True when the node has a `running` execution on a runner other than the process runner: the row is its only liveness record. */
+export declare function hasRunningRemoteExecution(nodeId: string): Promise<boolean>;
+/** True when a `launching` execution is in flight: any runner's, or a process runner's started by this daemon epoch. */
+export declare function hasLaunchingExecution(nodeId: string, epoch: string): Promise<boolean>;
+/** Node ids with a live process-runner execution begun by this daemon epoch. */
+export declare function liveProcessExecutionNodeIds(epoch: string): Promise<Set<string>>;
+/** Every node with a live (not exited) execution row, whichever process or runner holds it. */
+export declare function liveExecutionNodeIds(): Promise<Set<string>>;
+export declare const PROFILE_PAUSE_STOP_REASON = "profile_pause";
+/** Marks the node's live execution as stopped by a profile pause, so the exit it causes is not read as a crash. */
+export declare function markProfilePauseStop(nodeId: string): Promise<void>;
+export declare function hasProfilePauseStop(nodeId: string): Promise<boolean>;
+/** Consumes the pause stop once: true for the single dead-row pass that must absorb it. */
+export declare function absorbProfilePauseStop(nodeId: string): Promise<boolean>;
+/** Whether the execution's profile-pause stop was absorbed by a policy pass, the exit it caused already forgiven. */
+export declare function hasAbsorbedProfilePauseStop(execution: Execution): boolean;
+/** Records a child's observed exit status on its execution without ending it; the next dead-row pass reads it once. The first recorded reason stands. */
+export declare function recordExecutionExit(executionId: string, status: {
+    code: number | null;
+    signal: string | null;
+    oomKilled?: boolean;
+}): Promise<void>;
+export interface ObservedExit {
+    code: number | null;
+    signal: NodeJS.Signals | null;
+    oomKilled?: boolean;
+}
+/** Whether the execution holds an observed exit no dead-row pass has consumed yet. */
+export declare function hasObservedExit(execution: Execution): boolean;
+/** Reads and consumes the latest execution's unhandled observed exit, once. */
+export declare function takeObservedExit(nodeId: string): Promise<ObservedExit | undefined>;

package/dist/core/canvas/executions.js

@@ -0,0 +1,279 @@
+import { randomUUID } from 'node:crypto';
+import { openDb, withCanvasWrite } from './db.js';
+import { capturePidIdentities, captureLivenessSnapshot, identitiesMatch, isBootScopedIdentity, isLegacyTicksIdentity } from './pid.js';
+import { existsSync, readFileSync } from 'node:fs';
+import { LAUNCHER_SOCKET } from '../../launcher/spec.js';
+import { revokeNodeTokens } from './node-tokens.js';
+import { clearPendingParkIn } from '../../daemon/park-pending.js';
+function now() {
+    return new Date().toISOString();
+}
+function hydrate(row) {
+    return {
+        executionId: row['execution_id'],
+        nodeId: row['node_id'],
+        daemonEpoch: row['daemon_epoch'] ?? null,
+        pid: row['pid'] ?? null,
+        processIdentity: row['process_identity'] ?? null,
+        state: row['state'],
+        startedAt: row['started_at'],
+        endedAt: row['ended_at'] ?? null,
+        exitReason: row['exit_reason'] ?? null,
+        runner: row['runner'],
+        sandboxName: row['sandbox_name'] ?? null,
+        attempt: Number(row['attempt']),
+        release: row['release'] ?? null,
+        heartbeatAt: row['heartbeat_at'] ?? null,
+        awakeSince: row['awake_since'] ?? null,
+        idleAt: row['idle_at'] ?? null,
+        exitedAt: row['exited_at'] ?? null,
+        launchJson: row['launch_json'] ?? null,
+        stopRequestedAt: row['stop_requested_at'] ?? null,
+        stopAfterTurn: Number(row['stop_after_turn']) === 1,
+        stopReason: row['stop_reason'] ?? null,
+    };
+}
+export async function liveExecutionForNode(nodeId) {
+    const row = await (await openDb()).prepare("SELECT * FROM executions WHERE node_id = ? AND state != 'exited'").get(nodeId);
+    return row === undefined ? null : hydrate(row);
+}
+/** Thrown by `beginExecution` when `cap` other nodes already hold a live execution row. */
+export class ExecutionCapReached extends Error {
+    cap;
+    live;
+    constructor(cap, live) {
+        super(`no broker slot is free — ${live} live executions at the cap of ${cap}.`);
+        this.cap = cap;
+        this.live = live;
+        this.name = 'ExecutionCapReached';
+    }
+}
+/** Thrown by `beginExecution` when the node already holds a live execution another caller owns: a remote one, or a process
+ *  one this daemon epoch began. The holder keeps its row and token; the caller adopts it or backs off, never replaces it. */
+export class ExecutionAlreadyLive extends Error {
+    nodeId;
+    executionId;
+    constructor(nodeId, executionId) {
+        super(`${nodeId} already has a live execution ${executionId}.`);
+        this.nodeId = nodeId;
+        this.executionId = executionId;
+        this.name = 'ExecutionAlreadyLive';
+    }
+}
+/** Fixed key for the transaction-scoped lock that serializes cap checks across processes. */
+const EXECUTION_CAP_LOCK_KEY = 7_340_001;
+/** Inserts the `launching` row. It mints no token: the runner mints inside `start` (design D74). */
+export async function beginExecution(nodeId, input) {
+    return await withCanvasWrite(async (db) => {
+        const at = now();
+        // Serialize attempts for one node, including its first execution with no prior row to lock.
+        const owner = await db.prepare('SELECT node_id FROM nodes WHERE node_id = ? FOR UPDATE').get(nodeId);
+        if (!owner)
+            throw new Error(`cannot begin execution: missing node ${nodeId}`);
+        if (input.cap !== undefined) {
+            await db.prepare(`SELECT pg_advisory_xact_lock(${EXECUTION_CAP_LOCK_KEY})`).get();
+            const live = Number((await db.prepare("SELECT COUNT(*) AS n FROM executions WHERE state != 'exited' AND node_id != ?").get(nodeId)).n);
+            if (live >= input.cap)
+                throw new ExecutionCapReached(input.cap, live);
+        }
+        // Under the node lock, a live row another caller is launching or a remote broker owns is refused, not replaced:
+        // replacing it would revoke the token its owner just handed to a broker. A `running` process row is checked by pid
+        // and replaced as before, as is a process row an earlier daemon epoch left behind.
+        const live = await db.prepare("SELECT execution_id, runner, daemon_epoch, state FROM executions WHERE node_id = ? AND state != 'exited'").all(nodeId);
+        const owned = live.find((row) => row.state === 'launching' ? row.runner !== 'process' || (input.daemonEpoch !== null && row.daemon_epoch === input.daemonEpoch) : row.runner !== 'process');
+        if (owned !== undefined)
+            throw new ExecutionAlreadyLive(nodeId, owned.execution_id);
+        const superseded = await db.prepare("UPDATE executions SET state = 'exited', ended_at = ?, exited_at = ?, exit_reason = 'superseded' WHERE node_id = ? AND state != 'exited'").run(at, at, nodeId);
+        if (superseded.changes > 0)
+            await clearPendingParkIn(db, nodeId);
+        await revokeNodeTokens(db, 'node_id', nodeId, at);
+        const executionId = randomUUID();
+        const attempt = input.attempt ?? Number((await db.prepare('SELECT COALESCE(MAX(attempt), 0) + 1 AS next FROM executions WHERE node_id = ?').get(nodeId)).next);
+        await db.prepare("INSERT INTO executions (execution_id, node_id, daemon_epoch, pid, process_identity, state, started_at, ended_at, exit_reason, runner, sandbox_name, attempt, release, launch_json) VALUES (?, ?, ?, NULL, NULL, 'launching', ?, NULL, NULL, ?, ?, ?, ?, ?)")
+            .run(executionId, nodeId, input.daemonEpoch, at, input.runner ?? 'process', input.sandboxName ?? null, attempt, input.release ?? null, input.launchJson ?? null);
+        return executionId;
+    });
+}
+/** Persist the complete launch recipe before handing the execution to a runner. */
+export async function setExecutionLaunchJson(executionId, launchJson) {
+    const updated = await (await openDb()).prepare("UPDATE executions SET launch_json = ? WHERE execution_id = ? AND state = 'launching'").run(launchJson, executionId);
+    if (Number(updated.changes) !== 1)
+        throw new Error(`cannot set launch recipe for execution ${executionId}: no launching execution`);
+}
+/** The broker went idle with nothing holding it (design D18): stamps `idle_at` on its running execution, once per awake period. */
+export async function recordExecutionIdle(executionId) {
+    const updated = await (await openDb()).prepare("UPDATE executions SET idle_at = ? WHERE execution_id = ? AND state = 'running' AND idle_at IS NULL").run(now(), executionId);
+    return Number(updated.changes) === 1;
+}
+/** A thawed resident broker starts a new awake period: `awake_since` is now and `idle_at` is cleared. */
+export async function recordExecutionAwake(executionId) {
+    await (await openDb()).prepare("UPDATE executions SET awake_since = ?, idle_at = NULL WHERE execution_id = ? AND state = 'running'").run(now(), executionId);
+}
+/** Returns shutdown when a late broker references an execution no longer live. */
+export async function recordExecutionPid(executionId, nodeId, pid) {
+    const identity = capturePidIdentities([pid])?.get(pid) ?? null;
+    return await withCanvasWrite(async (db) => {
+        const launching = await db.prepare("UPDATE executions SET pid = ?, process_identity = ?, state = 'running', awake_since = ? WHERE execution_id = ? AND node_id = ? AND state = 'launching'").run(pid, identity, now(), executionId, nodeId);
+        if (launching.changes > 0)
+            return 'recorded';
+        const running = await db.prepare("SELECT pid FROM executions WHERE execution_id = ? AND node_id = ? AND state = 'running'").get(executionId, nodeId);
+        if (running?.pid === pid)
+            return 'recorded';
+        if (process.platform === 'linux' && existsSync(LAUNCHER_SOCKET) && running?.pid != null) {
+            const snapshot = captureLivenessSnapshot();
+            const descendants = [running.pid];
+            for (let i = 0; i < descendants.length; i++)
+                descendants.push(...(snapshot?.childrenOf.get(descendants[i]) ?? []));
+            if (descendants.includes(pid))
+                return 'recorded';
+            for (const descendant of descendants) {
+                try {
+                    const status = readFileSync(`/proc/${descendant}/status`, 'utf8');
+                    const namespacePids = /^NSpid:\s*(.+)$/m.exec(status)?.[1]?.trim().split(/\s+/).map(Number) ?? [];
+                    if (namespacePids.length > 1 && namespacePids.at(-1) === pid)
+                        return 'recorded';
+                }
+                catch {
+                    // A process that exited during the snapshot cannot establish identity.
+                }
+            }
+        }
+        return 'shutdown';
+    });
+}
+/**
+ * Ends the execution, revokes its token and clears the node's supervision marks in one transaction.
+ * `launch_lost` and `launch_timeout` are the recovery ends of a `launching` row (design, Execution token hand-off).
+ */
+export async function endExecution(executionId, input) {
+    return await withCanvasWrite(async (db) => {
+        const at = now();
+        const ended = await db.prepare("UPDATE executions SET state = 'exited', ended_at = ?, exited_at = ?, exit_reason = COALESCE(exit_reason, ?) WHERE execution_id = ? AND state != 'exited' RETURNING node_id").get(at, at, input.reason, executionId);
+        await revokeNodeTokens(db, 'broker_process_id', executionId, at);
+        if (ended !== undefined)
+            await clearPendingParkIn(db, ended.node_id);
+        return ended !== undefined;
+    });
+}
+/** Ends the execution only while it is still `launching`: false when a `session.bound` already made it `running`, so a stale
+ *  timeout decision never kills a broker that bound. The caller stops the external process only on true. */
+export async function endLaunchingExecution(executionId, input) {
+    return await withCanvasWrite(async (db) => {
+        const at = now();
+        const ended = await db.prepare("UPDATE executions SET state = 'exited', ended_at = ?, exited_at = ?, exit_reason = COALESCE(exit_reason, ?) WHERE execution_id = ? AND state = 'launching' RETURNING node_id").get(at, at, input.reason, executionId);
+        if (ended === undefined)
+            return false;
+        await revokeNodeTokens(db, 'broker_process_id', executionId, at);
+        await clearPendingParkIn(db, ended.node_id);
+        return true;
+    });
+}
+export async function abortExecution(executionId, input) {
+    return await endExecution(executionId, input);
+}
+export async function endLiveExecution(nodeId, input) {
+    return await withCanvasWrite(async (db) => {
+        const at = now();
+        const ended = await db.prepare("UPDATE executions SET state = 'exited', ended_at = ?, exited_at = ?, exit_reason = COALESCE(exit_reason, ?) WHERE node_id = ? AND state != 'exited'").run(at, at, input.reason, nodeId);
+        await revokeNodeTokens(db, 'node_id', nodeId, at);
+        if (Number(ended.changes) > 0)
+            await clearPendingParkIn(db, nodeId);
+        return Number(ended.changes) === 1;
+    });
+}
+export async function migrateLegacyExecutionIdentities(captureIdentity = (pid) => capturePidIdentities([pid])?.get(pid)) {
+    const db = await openDb();
+    const rows = await db.prepare("SELECT execution_id, pid, process_identity FROM executions WHERE state = 'running' AND pid IS NOT NULL AND process_identity IS NOT NULL").all();
+    const update = db.prepare("UPDATE executions SET process_identity = ? WHERE execution_id = ? AND pid = ? AND process_identity = ? AND state = 'running'");
+    const migrated = [];
+    for (const row of rows) {
+        if (!isLegacyTicksIdentity(row.process_identity))
+            continue;
+        const current = captureIdentity(row.pid);
+        if (current === undefined || !isBootScopedIdentity(current) || !identitiesMatch(current, row.process_identity))
+            continue;
+        if ((await update.run(current, row.execution_id, row.pid, row.process_identity)).changes > 0)
+            migrated.push(row.execution_id);
+    }
+    return { migrated };
+}
+/** Records a stop request on the node's live execution; the first request's time and reason stand. */
+export async function requestExecutionStop(nodeId, input) {
+    const updated = await (await openDb()).prepare("UPDATE executions SET stop_requested_at = COALESCE(stop_requested_at, ?), stop_after_turn = CASE WHEN stop_requested_at IS NULL THEN ? ELSE stop_after_turn END, stop_reason = COALESCE(stop_reason, ?) WHERE node_id = ? AND state != 'exited'").run(now(), input.afterTurn ? 1 : 0, input.reason, nodeId);
+    return Number(updated.changes) > 0;
+}
+/** Live executions with a stop requested at or before `requestedBefore` (ISO time). A request this old has outlived the
+ *  process that queued it, whose own teardown runs within seconds. */
+export async function executionsWithStopRequestedBefore(requestedBefore) {
+    const rows = await (await openDb()).prepare("SELECT * FROM executions WHERE state != 'exited' AND stop_requested_at IS NOT NULL AND stop_requested_at <= ? ORDER BY stop_requested_at").all(requestedBefore);
+    return rows.map(hydrate);
+}
+/** The node's most recent execution row, live or ended. */
+export async function latestExecutionForNode(nodeId) {
+    const row = await (await openDb()).prepare('SELECT * FROM executions WHERE node_id = ? ORDER BY started_at DESC, attempt DESC LIMIT 1').get(nodeId);
+    return row === undefined ? null : hydrate(row);
+}
+/** True when the node has a `running` execution on a runner other than the process runner: the row is its only liveness record. */
+export async function hasRunningRemoteExecution(nodeId) {
+    return await (await openDb()).prepare("SELECT 1 AS x FROM executions WHERE node_id = ? AND state = 'running' AND runner != 'process'").get(nodeId) !== undefined;
+}
+/** True when a `launching` execution is in flight: any runner's, or a process runner's started by this daemon epoch. */
+export async function hasLaunchingExecution(nodeId, epoch) {
+    return await (await openDb()).prepare("SELECT 1 AS x FROM executions WHERE node_id = ? AND state = 'launching' AND (runner != 'process' OR daemon_epoch = ?)").get(nodeId, epoch) !== undefined;
+}
+/** Node ids with a live process-runner execution begun by this daemon epoch. */
+export async function liveProcessExecutionNodeIds(epoch) {
+    const rows = await (await openDb()).prepare("SELECT node_id FROM executions WHERE state != 'exited' AND runner = 'process' AND daemon_epoch = ?").all(epoch);
+    return new Set(rows.map((row) => row.node_id));
+}
+/** Every node with a live (not exited) execution row, whichever process or runner holds it. */
+export async function liveExecutionNodeIds() {
+    const rows = await (await openDb()).prepare("SELECT node_id FROM executions WHERE state != 'exited'").all();
+    return new Set(rows.map((row) => row.node_id));
+}
+export const PROFILE_PAUSE_STOP_REASON = 'profile_pause';
+const PROFILE_PAUSE_ABSORBED = 'profile_pause_absorbed';
+/** Marks the node's live execution as stopped by a profile pause, so the exit it causes is not read as a crash. */
+export async function markProfilePauseStop(nodeId) {
+    await (await openDb()).prepare("UPDATE executions SET stop_requested_at = COALESCE(stop_requested_at, ?), stop_reason = ? WHERE node_id = ? AND state != 'exited'").run(now(), PROFILE_PAUSE_STOP_REASON, nodeId);
+}
+export async function hasProfilePauseStop(nodeId) {
+    return (await latestExecutionForNode(nodeId))?.stopReason === PROFILE_PAUSE_STOP_REASON;
+}
+/** Consumes the pause stop once: true for the single dead-row pass that must absorb it. */
+export async function absorbProfilePauseStop(nodeId) {
+    const absorbed = await (await openDb()).prepare('UPDATE executions SET stop_reason = ? WHERE execution_id = (SELECT execution_id FROM executions WHERE node_id = ? ORDER BY started_at DESC, attempt DESC LIMIT 1) AND stop_reason = ?').run(PROFILE_PAUSE_ABSORBED, nodeId, PROFILE_PAUSE_STOP_REASON);
+    return Number(absorbed.changes) > 0;
+}
+/** Whether the execution's profile-pause stop was absorbed by a policy pass, the exit it caused already forgiven. */
+export function hasAbsorbedProfilePauseStop(execution) {
+    return execution.stopReason === PROFILE_PAUSE_ABSORBED;
+}
+const EXIT_PREFIX = 'exited:';
+/** Records a child's observed exit status on its execution without ending it; the next dead-row pass reads it once. The first recorded reason stands. */
+export async function recordExecutionExit(executionId, status) {
+    const reason = status.oomKilled === true ? 'out_of_memory' : `${EXIT_PREFIX}${status.code ?? ''}:${status.signal ?? ''}`;
+    await (await openDb()).prepare('UPDATE executions SET exit_reason = ? WHERE execution_id = ? AND exit_reason IS NULL').run(reason, executionId);
+}
+/** Whether the execution holds an observed exit no dead-row pass has consumed yet. */
+export function hasObservedExit(execution) {
+    const reason = execution.exitReason;
+    return reason != null && (reason === 'out_of_memory' || reason.startsWith(EXIT_PREFIX));
+}
+/** Reads and consumes the latest execution's unhandled observed exit, once. */
+export async function takeObservedExit(nodeId) {
+    const latest = await latestExecutionForNode(nodeId);
+    const reason = latest?.exitReason;
+    if (latest === null || reason == null)
+        return undefined;
+    const oom = reason === 'out_of_memory';
+    if (!oom && !reason.startsWith(EXIT_PREFIX))
+        return undefined;
+    const taken = await (await openDb()).prepare("UPDATE executions SET exit_reason = 'exit_handled' WHERE execution_id = ? AND exit_reason = ?").run(latest.executionId, reason);
+    if (Number(taken.changes) === 0)
+        return undefined;
+    if (oom)
+        return { code: null, signal: null, oomKilled: true };
+    const [code, signal] = reason.slice(EXIT_PREFIX.length).split(':');
+    return { code: code === '' ? null : Number(code), signal: signal === '' ? null : signal };
+}

package/dist/core/canvas/extensions.d.ts

@@ -0,0 +1,9 @@
+export declare const CANVAS_EXTENSION_NAMES: readonly ["canvas-inbox-watcher", "canvas-review-boundary", "canvas-stophook", "canvas-recap", "canvas-goal-capture", "canvas-passive-context", "canvas-context-intro", "canvas-tool-guide", "canvas-doc-substrate", "canvas-structured-output", "canvas-bash-valve", "canvas-preview-result", "canvas-prompt-scrub", "canvas-stamp", "canvas-elapsed"];
+/** Structural shipped-hook identity: a canvas-hook stem directly under a
+ * `pi-extensions` directory. A user's own extension elsewhere may share the
+ * stem and is not shipped. */
+export declare function isShippedCanvasExtension(path: string): boolean;
+/** Remove persisted shipped canvas extensions while retaining genuine
+ * caller/kind extras, including a custom extension whose basename happens to
+ * resemble a canvas hook outside a pi-extensions directory. */
+export declare function customExtensionPaths(extensions: readonly string[] | undefined): string[];

package/dist/core/canvas/extensions.js

@@ -0,0 +1,90 @@
+import { extname } from 'node:path';
+// Canvas-extension identity is structural, not basename-based: old runtime roots
+// are recognized only when they carry a complete shipped canvas prefix.
+// canvas-inbox-watcher must load before canvas-stophook: at agent_settled it
+// commits the cursor the stophook then reads to decide idle release.
+export const CANVAS_EXTENSION_NAMES = [
+    'canvas-inbox-watcher', 'canvas-review-boundary', 'canvas-stophook', 'canvas-recap',
+    'canvas-goal-capture', 'canvas-passive-context', 'canvas-context-intro',
+    'canvas-tool-guide', 'canvas-doc-substrate', 'canvas-structured-output',
+    'canvas-bash-valve', 'canvas-preview-result', 'canvas-prompt-scrub', 'canvas-stamp',
+    'canvas-elapsed',
+];
+const HISTORICAL_CANVAS_EXTENSION_PREFIXES = [
+    [
+        'canvas-inbox-watcher', 'canvas-review-boundary', 'canvas-stophook', 'canvas-recap',
+        'canvas-goal-capture', 'canvas-passive-context', 'canvas-context-intro',
+        'canvas-tool-guide', 'canvas-doc-substrate', 'canvas-structured-output',
+        'canvas-bash-valve', 'canvas-preview-result', 'canvas-prompt-scrub', 'canvas-stamp',
+    ],
+    [
+        'canvas-inbox-watcher', 'canvas-review-boundary', 'canvas-stophook', 'canvas-recap',
+        'canvas-goal-capture', 'canvas-passive-context', 'canvas-context-intro',
+        'canvas-tool-guide', 'canvas-doc-substrate', 'canvas-structured-output',
+        'canvas-bash-valve', 'canvas-preview-result', 'canvas-prompt-scrub',
+    ],
+    [
+        'canvas-inbox-watcher', 'canvas-review-boundary', 'canvas-stophook', 'canvas-recap',
+        'canvas-goal-capture', 'canvas-passive-context', 'canvas-context-intro',
+        'canvas-tool-guide', 'canvas-doc-substrate', 'canvas-structured-output',
+        'canvas-bash-valve', 'canvas-preview-result',
+    ],
+    [
+        'canvas-inbox-watcher', 'canvas-review-boundary', 'canvas-stophook', 'canvas-recap',
+        'canvas-goal-capture', 'canvas-passive-context', 'canvas-context-intro',
+        'canvas-tool-guide', 'canvas-doc-substrate', 'canvas-structured-output',
+        'canvas-bash-valve',
+    ],
+    [
+        'canvas-inbox-watcher', 'canvas-stophook', 'canvas-recap',
+        'canvas-goal-capture', 'canvas-passive-context', 'canvas-review-boundary',
+        'canvas-context-intro',
+        'canvas-tool-guide', 'canvas-doc-substrate', 'canvas-structured-output',
+        'canvas-bash-valve',
+    ],
+    [
+        'canvas-inbox-watcher', 'canvas-stophook', 'canvas-recap',
+        'canvas-goal-capture', 'canvas-passive-context', 'canvas-context-intro',
+        'canvas-doc-substrate', 'canvas-structured-output', 'canvas-bash-valve',
+    ],
+    [
+        'canvas-stophook', 'canvas-inbox-watcher', 'canvas-recap',
+        'canvas-goal-capture', 'canvas-passive-context', 'canvas-context-intro',
+        'canvas-doc-substrate', 'canvas-structured-output', 'canvas-bash-valve',
+    ],
+];
+function matchesExtensionPrefix(extensions, names) {
+    if (extensions.length < names.length)
+        return false;
+    const paths = extensions.slice(0, names.length);
+    const first = paths[0].replaceAll('\\', '/');
+    const marker = '/pi-extensions/';
+    const markerIndex = first.lastIndexOf(marker);
+    const suffix = first.endsWith('.js') ? '.js' : first.endsWith('.ts') ? '.ts' : null;
+    if (markerIndex < 1 || suffix === null)
+        return false;
+    const root = first.slice(0, markerIndex + marker.length);
+    return names.every((name, index) => paths[index].replaceAll('\\', '/') === `${root}${name}${suffix}`);
+}
+function extensionPrefixLength(extensions) {
+    const prefixes = [CANVAS_EXTENSION_NAMES, ...HISTORICAL_CANVAS_EXTENSION_PREFIXES];
+    return prefixes.find((names) => matchesExtensionPrefix(extensions, names))?.length ?? 0;
+}
+/** Structural shipped-hook identity: a canvas-hook stem directly under a
+ * `pi-extensions` directory. A user's own extension elsewhere may share the
+ * stem and is not shipped. */
+export function isShippedCanvasExtension(path) {
+    const normalized = path.replaceAll('\\', '/');
+    const lastSlash = normalized.lastIndexOf('/');
+    const parent = normalized.slice(0, lastSlash).split('/').at(-1);
+    const filename = normalized.slice(lastSlash + 1);
+    const name = filename.slice(0, filename.length - extname(filename).length);
+    return parent === 'pi-extensions' && CANVAS_EXTENSION_NAMES.includes(name);
+}
+/** Remove persisted shipped canvas extensions while retaining genuine
+ * caller/kind extras, including a custom extension whose basename happens to
+ * resemble a canvas hook outside a pi-extensions directory. */
+export function customExtensionPaths(extensions) {
+    const paths = extensions ?? [];
+    return paths.slice(extensionPrefixLength(paths)).filter((path) => !isShippedCanvasExtension(path));
+}

package/dist/core/canvas/focuses.d.ts

@@ -0,0 +1,26 @@
+import type { FocusRow } from './types.js';
+/** INSERT a viewport. Throws on UNIQUE(node_id) if `node_id` already occupies
+ *  another focus (or on PK conflict if `focus_id` exists) — by design. */
+export declare function openFocusRow(focus_id: string, pane: string | null, session: string | null, node_id: string): Promise<void>;
+/** Hot-swap a focus's occupant — single-statement UPDATE. Respects
+ *  UNIQUE(node_id): if `node_id` already occupies ANOTHER focus this throws
+ *  (correct — vacate-first is placement.focus()'s job, not this setter's). */
+export declare function setFocusOccupant(focus_id: string, node_id: string): Promise<void>;
+/** Re-point a viewer row's durable pane + its derived session cache after the
+ *  pane moves. Single-statement UPDATE. */
+export declare function setFocusPane(focus_id: string, pane: string | null, session: string | null): Promise<void>;
+/** DELETE a viewport. */
+export declare function closeFocusRow(focus_id: string): Promise<void>;
+/** DELETE a viewport only while it still sits on `pane`: a row re-pointed to another pane since `pane` was probed is kept. */
+export declare function closeFocusRowOnPane(focus_id: string, pane: string): Promise<boolean>;
+/** The focus a node occupies (≤1, UNIQUE node_id), or null. */
+export declare function getFocusByNode(node_id: string): Promise<FocusRow | null>;
+/** {@link getFocusByNode} taking the row's lock: call inside `withCanvasWrite`, where a concurrent re-point or close of the row waits for the commit. */
+export declare function getFocusByNodeForUpdate(node_id: string): Promise<FocusRow | null>;
+/** The focus realized by a given pane (`%id`), or null. */
+export declare function getFocusByPane(pane: string): Promise<FocusRow | null>;
+/** A focus by its stable id, or null. Used by placement to read a row back by id
+ *  after openFocusRow registers a viewer. */
+export declare function getFocusById(focus_id: string): Promise<FocusRow | null>;
+/** Every focus row, ordered by id. */
+export declare function listFocuses(): Promise<FocusRow[]>;

package/dist/core/canvas/focuses.js

@@ -0,0 +1,82 @@
+// focuses.ts — the FOCUS table data-access layer (canvas.db, migration v6).
+//
+// Part of the canvas data-access layer: Q7 widens canvas.db from "topology" to
+// "topology + focuses", so the focus-row SQL lives here beside the node+edge
+// model, never in the runtime layer. A FOCUS is one durable on-screen viewport
+// bound to one node; the table is PLURAL (many focuses across windows/sessions),
+// the generalization of the old single focus pointer. It is the CANONICAL focus
+// store — there is no focus.ptr file and no dual-write bridge.
+//
+// placement.ts COMPOSES over these atomic setters/reads (the same way it calls
+// setPresence) — it never runs raw focus SQL itself.
+//
+// Each setter is a single atomic statement. UNIQUE(node_id) upholds "a node
+// occupies at most one viewer" (Q5): a second focus row (or an occupant UPDATE)
+// for an already-viewed node throws — that is correct, the vacate-first
+// orchestration is placement.focus()'s job, not these setters'.
+import { openDb } from './db.js';
+function focusFrom(r) {
+    return {
+        focus_id: r['focus_id'],
+        pane: r['pane'] ?? null,
+        session: r['session'] ?? null,
+        node_id: r['node_id'],
+    };
+}
+// Atomic setters — each one a single-statement INSERT/UPDATE/DELETE.
+/** INSERT a viewport. Throws on UNIQUE(node_id) if `node_id` already occupies
+ *  another focus (or on PK conflict if `focus_id` exists) — by design. */
+export async function openFocusRow(focus_id, pane, session, node_id) {
+    await (await openDb()).prepare('INSERT INTO focuses (focus_id, pane, session, node_id) VALUES (?, ?, ?, ?)')
+        .run(focus_id, pane, session, node_id);
+}
+/** Hot-swap a focus's occupant — single-statement UPDATE. Respects
+ *  UNIQUE(node_id): if `node_id` already occupies ANOTHER focus this throws
+ *  (correct — vacate-first is placement.focus()'s job, not this setter's). */
+export async function setFocusOccupant(focus_id, node_id) {
+    await (await openDb()).prepare('UPDATE focuses SET node_id = ? WHERE focus_id = ?').run(node_id, focus_id);
+}
+/** Re-point a viewer row's durable pane + its derived session cache after the
+ *  pane moves. Single-statement UPDATE. */
+export async function setFocusPane(focus_id, pane, session) {
+    await (await openDb()).prepare('UPDATE focuses SET pane = ?, session = ? WHERE focus_id = ?')
+        .run(pane, session, focus_id);
+}
+/** DELETE a viewport. */
+export async function closeFocusRow(focus_id) {
+    await (await openDb()).prepare('DELETE FROM focuses WHERE focus_id = ?').run(focus_id);
+}
+/** DELETE a viewport only while it still sits on `pane`: a row re-pointed to another pane since `pane` was probed is kept. */
+export async function closeFocusRowOnPane(focus_id, pane) {
+    return (await (await openDb()).prepare('DELETE FROM focuses WHERE focus_id = ? AND pane = ?').run(focus_id, pane)).changes > 0;
+}
+// Reads.
+/** The focus a node occupies (≤1, UNIQUE node_id), or null. */
+export async function getFocusByNode(node_id) {
+    const r = await (await openDb()).prepare('SELECT * FROM focuses WHERE node_id = ?')
+        .get(node_id);
+    return r ? focusFrom(r) : null;
+}
+/** {@link getFocusByNode} taking the row's lock: call inside `withCanvasWrite`, where a concurrent re-point or close of the row waits for the commit. */
+export async function getFocusByNodeForUpdate(node_id) {
+    const r = await (await openDb()).prepare('SELECT * FROM focuses WHERE node_id = ? FOR UPDATE')
+        .get(node_id);
+    return r ? focusFrom(r) : null;
+}
+/** The focus realized by a given pane (`%id`), or null. */
+export async function getFocusByPane(pane) {
+    const r = await (await openDb()).prepare('SELECT * FROM focuses WHERE pane = ?')
+        .get(pane);
+    return r ? focusFrom(r) : null;
+}
+/** A focus by its stable id, or null. Used by placement to read a row back by id
+ *  after openFocusRow registers a viewer. */
+export async function getFocusById(focus_id) {
+    const r = await (await openDb()).prepare('SELECT * FROM focuses WHERE focus_id = ?')
+        .get(focus_id);
+    return r ? focusFrom(r) : null;
+}
+/** Every focus row, ordered by id. */
+export async function listFocuses() {
+    return (await (await openDb()).prepare('SELECT * FROM focuses ORDER BY focus_id').all()).map(focusFrom);
+}