@north-light/crouter 0.3.312 → 0.3.313

package/dist/core/human/requests.d.ts

@@ -0,0 +1,136 @@
+import type { DatabaseSync } from 'node:sqlite';
+import { type PreparedPage } from './page-authoring.js';
+import { type PageResponses } from './page-schema.js';
+export type HumanRequestKind = 'page' | 'review';
+export type HumanRequestState = 'binding' | 'open' | 'settled';
+export type HumanRequestOutcome = 'approved' | 'answered' | 'canceled' | 'dismissed';
+export interface HumanRequestRecord {
+    request_id: string;
+    kind: HumanRequestKind;
+    inbox_ticket_id: string;
+    request_dir: string;
+    /** The immutable complete page revision selected by SQL. Null for reviews. */
+    presentation_dir: string | null;
+    requester_node_id: string | null;
+    companion_node_id: string | null;
+    idempotency_key: string | null;
+    state: HumanRequestState;
+    outcome: HumanRequestOutcome | null;
+    inbox_listed: boolean;
+    settleable: boolean;
+    title: string;
+    subtitle: string | null;
+    file: string | null;
+    specification_json: string;
+    action_json: string | null;
+    progress_json: string | null;
+    feedback_json: string | null;
+    result_json: string | null;
+    anchor_base_sha256: string | null;
+    anchor_base_bytes: Buffer | null;
+    created_at: string;
+    opened_at: string | null;
+    submit_requested_at: string | null;
+    settled_at: string | null;
+    settlement_delivery_id: string | null;
+    action_delivery_id: string | null;
+    submit_note_delivery_id: string | null;
+    projected_at: string | null;
+    projection_error: string | null;
+    companion_retired_at: string | null;
+    updated_at: string;
+}
+export interface NewReviewRequest {
+    request_id: string;
+    idempotency_key: string;
+    requester_node_id: string;
+    companion_node_id: string;
+    request_dir: string;
+    file: string;
+    specification: Record<string, unknown>;
+    anchor_base_sha256: string;
+    anchor_base_bytes: Buffer;
+    created_at: string;
+    subtitle?: string | null;
+    inbox_listed: boolean;
+}
+export interface CreatePageRequestInput {
+    /** Frozen by a cron obligation when creation must be idempotent across a daemon death. */
+    request_id?: string;
+    inbox_ticket_id?: string;
+    prepared: PreparedPage;
+    requester_node_id?: string | null;
+    action_json?: string | null;
+}
+export interface SettleRequestArgs {
+    request_id: string;
+    outcome: HumanRequestOutcome;
+    result_json: string;
+    settled_at: string;
+}
+export interface RequestSettlementMarks {
+    settlement_delivery_id?: string | null;
+    action_delivery_id?: string | null;
+}
+export declare function humanRequestsRoot(): string;
+export declare function requestDir(requestId: string): string;
+export interface PageRevisionStorage {
+    writeFile(path: string, content: string): void;
+    syncFile(path: string): void;
+    syncDirectory(path: string): void;
+}
+/** Publish a complete, immutable revision before a request can select it. */
+export declare function publishPageRevision(dir: string, prepared: PreparedPage, storage?: PageRevisionStorage): string;
+/** The SQL-selected page revision. There is no path-based fallback for page reads. */
+export declare function presentationDir(request: HumanRequestRecord): string;
+/** Creates one SQL-authoritative page request. `request_id` is optional for ordinary callers and frozen by cron creation. */
+export declare function createPageRequest(input: CreatePageRequestInput): HumanRequestRecord;
+/** Claims a review idempotency key before companion realization. */
+export declare function commitBindingRequest(input: NewReviewRequest): {
+    request_id: string;
+    won: boolean;
+};
+export declare function getRequest(requestId: string): HumanRequestRecord | null;
+export declare function getRequestByInboxTicket(ticketId: string): HumanRequestRecord | null;
+export declare function getRequestByDirectory(dir: string): HumanRequestRecord | null;
+export declare function getRequestByCompanion(nodeId: string): HumanRequestRecord | null;
+export declare function getRequestByIdempotencyKey(key: string): HumanRequestRecord | null;
+export declare function listOpenInboxRequests(): HumanRequestRecord[];
+export declare function openRequestsByRequester(nodeId: string): HumanRequestRecord[];
+/** Indexed attention projection: only open inbox-listed requests with a reply target keep a node wakeable. */
+export declare function listOpenReplyBearingRequests(): HumanRequestRecord[];
+export declare function listBindingRequests(): HumanRequestRecord[];
+export declare function listSubmitRequestedRequests(): HumanRequestRecord[];
+export declare function listUnprojectedReviews(): HumanRequestRecord[];
+export declare function listRequests(filter?: {
+    kind?: HumanRequestKind;
+    state?: HumanRequestState;
+    requester_node_id?: string;
+    file?: string;
+}): HumanRequestRecord[];
+export declare function openRequest(requestId: string, openedAt: string): boolean;
+/** A binding whose immutable branch disappeared never recaptures a new origin. */
+export declare function cancelBindingRequest(requestId: string, at: string, reason: string): boolean;
+export declare function requestSubmit(requestId: string, at: string): boolean;
+/** The first-writer-wins terminal transition. Callers add obligations in this same `withCanvasWrite` boundary. */
+export declare function settleRequestLocked(db: DatabaseSync, args: SettleRequestArgs): HumanRequestRecord | null;
+export declare function setSettlementDeliveryMarksLocked(db: DatabaseSync, requestId: string, marks: RequestSettlementMarks): void;
+export declare function setSubmitNoteDeliveryLocked(db: DatabaseSync, requestId: string, deliveryId: string): boolean;
+export declare function revisePageRequest(requestId: string, values: {
+    presentation_dir: string;
+    specification_json: string;
+    title: string;
+    subtitle: string | null;
+    inbox_listed: boolean;
+    settleable: boolean;
+}): boolean;
+export declare function writeProgress(ticketId: string, responses: PageResponses): boolean;
+export declare function markProjected(requestId: string, at: string): void;
+export declare function markProjectionError(requestId: string, error: string): void;
+export declare function markCompanionRetired(requestId: string, at: string): void;
+export declare function readAnchorBase(requestId: string): {
+    bytes: Buffer;
+    sha256: string;
+} | null;
+export declare function replaceAnchorBaseLocked(db: DatabaseSync, requestId: string, bytes: Buffer, sha256: string): void;
+export declare function migrateHumanRequestsState(db: DatabaseSync): void;

package/dist/core/human/requests.js

@@ -0,0 +1,515 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, statSync, writeFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { z } from 'zod';
+import { crtrHome, isSafeNodeId, nodesRoot } from '../canvas/paths.js';
+import { openDb, withCanvasWrite } from '../canvas/db.js';
+import { syncDirectory, syncFile } from '../fs-utils.js';
+import { newNodeId } from '../runtime/nodes.js';
+import { pageManifestPath, pageModulePath, pagePath } from './convention.js';
+import { preparePageSource } from './page-authoring.js';
+import { pageDeliverySchema, validatePageManifest } from './page-schema.js';
+function bool(value) { return value === 1 || value === true; }
+function recordFromRow(raw) {
+    return {
+        request_id: raw['request_id'],
+        kind: raw['kind'],
+        inbox_ticket_id: raw['inbox_ticket_id'],
+        request_dir: raw['request_dir'],
+        presentation_dir: raw['presentation_dir'],
+        requester_node_id: raw['requester_node_id'],
+        companion_node_id: raw['companion_node_id'],
+        idempotency_key: raw['idempotency_key'],
+        state: raw['state'],
+        outcome: raw['outcome'],
+        inbox_listed: bool(raw['inbox_listed']),
+        settleable: bool(raw['settleable']),
+        title: raw['title'],
+        subtitle: raw['subtitle'],
+        file: raw['file'],
+        specification_json: raw['specification_json'],
+        action_json: raw['action_json'],
+        progress_json: raw['progress_json'],
+        feedback_json: raw['feedback_json'],
+        result_json: raw['result_json'],
+        anchor_base_sha256: raw['anchor_base_sha256'],
+        anchor_base_bytes: raw['anchor_base_bytes'] === null ? null : Buffer.from(raw['anchor_base_bytes']),
+        created_at: raw['created_at'],
+        opened_at: raw['opened_at'],
+        submit_requested_at: raw['submit_requested_at'],
+        settled_at: raw['settled_at'],
+        settlement_delivery_id: raw['settlement_delivery_id'],
+        action_delivery_id: raw['action_delivery_id'],
+        submit_note_delivery_id: raw['submit_note_delivery_id'],
+        projected_at: raw['projected_at'],
+        projection_error: raw['projection_error'],
+        companion_retired_at: raw['companion_retired_at'],
+        updated_at: raw['updated_at'],
+    };
+}
+function one(db, where, ...params) {
+    const raw = db.prepare(`SELECT * FROM human_requests WHERE ${where}`).get(...params);
+    return raw === undefined ? null : recordFromRow(raw);
+}
+function many(db, where, params = [], order = 'created_at ASC, request_id ASC') {
+    return db.prepare(`SELECT * FROM human_requests WHERE ${where} ORDER BY ${order}`).all(...params).map(recordFromRow);
+}
+export function humanRequestsRoot() { return join(crtrHome(), 'requests'); }
+export function requestDir(requestId) {
+    if (!isSafeNodeId(requestId))
+        throw new TypeError(`request_id must be a safe path segment: ${requestId}`);
+    const root = humanRequestsRoot();
+    mkdirSync(root, { recursive: true, mode: 0o700 });
+    return join(realpathSync(root), requestId);
+}
+function randomTicketId() { return randomBytes(32).toString('hex'); }
+function legacyTicketId(root, name) {
+    return createHash('sha256').update(`${realpathSync(root)}\0${name}`, 'utf8').digest('hex');
+}
+const durablePageRevisionStorage = {
+    writeFile(path, content) { writeFileSync(path, content, { flag: 'wx', mode: 0o600 }); },
+    syncFile,
+    syncDirectory,
+};
+function revisionRoot(dir) { return join(dir, 'revisions'); }
+/** Publish a complete, immutable revision before a request can select it. */
+export function publishPageRevision(dir, prepared, storage = durablePageRevisionStorage) {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const revisions = revisionRoot(dir);
+    mkdirSync(revisions, { recursive: true, mode: 0o700 });
+    const revision = join(revisions, randomBytes(16).toString('hex'));
+    mkdirSync(revision, { mode: 0o700 });
+    const document = pagePath(revision, prepared.manifest.dialect);
+    storage.writeFile(document, prepared.document);
+    storage.syncFile(document);
+    if (prepared.manifest.dialect === 'jsx') {
+        const module = pageModulePath(revision);
+        storage.writeFile(module, prepared.module);
+        storage.syncFile(module);
+    }
+    const manifest = pageManifestPath(revision);
+    storage.writeFile(manifest, `${JSON.stringify(prepared.manifest, null, 2)}\n`);
+    storage.syncFile(manifest);
+    storage.syncDirectory(revision);
+    storage.syncDirectory(revisions);
+    storage.syncDirectory(dir);
+    storage.syncDirectory(humanRequestsRoot());
+    return revision;
+}
+/** The SQL-selected page revision. There is no path-based fallback for page reads. */
+export function presentationDir(request) {
+    if (request.kind !== 'page' || request.presentation_dir === null)
+        throw new Error(`page request has no selected presentation: ${request.request_id}`);
+    return request.presentation_dir;
+}
+/** Creates one SQL-authoritative page request. `request_id` is optional for ordinary callers and frozen by cron creation. */
+export function createPageRequest(input) {
+    const requestId = input.request_id ?? newNodeId();
+    const dir = requestDir(requestId);
+    const selectedPresentation = publishPageRevision(dir, input.prepared);
+    const at = new Date().toISOString();
+    const manifest = input.prepared.manifest;
+    return withCanvasWrite((db) => {
+        db.prepare(`
+      INSERT INTO human_requests (
+        request_id, kind, inbox_ticket_id, request_dir, presentation_dir, requester_node_id, state, inbox_listed,
+        settleable, title, subtitle, specification_json, action_json, created_at, updated_at
+      ) VALUES (?, 'page', ?, ?, ?, ?, 'open', ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(requestId, input.inbox_ticket_id ?? randomTicketId(), dir, selectedPresentation, input.requester_node_id ?? null, manifest.delivery.inbox ? 1 : 0, manifest.delivery.inbox || manifest.delivery.reply ? 1 : 0, manifest.title, manifest.subtitle ?? null, JSON.stringify(manifest), input.action_json ?? null, at, at);
+        const request = one(db, 'request_id = ?', requestId);
+        if (request === null)
+            throw new Error(`page request insert did not produce a row: ${requestId}`);
+        return request;
+    });
+}
+/** Claims a review idempotency key before companion realization. */
+export function commitBindingRequest(input) {
+    return withCanvasWrite((db) => {
+        const inserted = db.prepare(`
+      INSERT INTO human_requests (
+        request_id, kind, inbox_ticket_id, request_dir, requester_node_id, companion_node_id,
+        idempotency_key, state, inbox_listed, settleable, title, subtitle, file,
+        specification_json, anchor_base_sha256, anchor_base_bytes, created_at, updated_at
+      ) VALUES (?, 'review', ?, ?, ?, ?, ?, 'binding', ?, 1, ?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(idempotency_key) DO NOTHING
+    `).run(input.request_id, randomTicketId(), input.request_dir, input.requester_node_id, input.companion_node_id, input.idempotency_key, input.inbox_listed ? 1 : 0, basename(input.file), input.subtitle ?? null, input.file, JSON.stringify(input.specification), input.anchor_base_sha256, input.anchor_base_bytes, input.created_at, input.created_at);
+        const winner = one(db, 'idempotency_key = ?', input.idempotency_key);
+        if (winner === null)
+            throw new Error(`review binding insert did not produce a row: ${input.idempotency_key}`);
+        return { request_id: winner.request_id, won: inserted.changes > 0 };
+    });
+}
+export function getRequest(requestId) { return one(openDb(), 'request_id = ?', requestId); }
+export function getRequestByInboxTicket(ticketId) { return one(openDb(), 'inbox_ticket_id = ?', ticketId); }
+export function getRequestByDirectory(dir) {
+    let canonical = dir;
+    try {
+        canonical = realpathSync(dir);
+    }
+    catch { /* A caller may name a request directory before it exists. */ }
+    return one(openDb(), 'request_dir = ?', canonical);
+}
+export function getRequestByCompanion(nodeId) { return one(openDb(), "companion_node_id = ? AND state <> 'binding'", nodeId); }
+export function getRequestByIdempotencyKey(key) { return one(openDb(), 'idempotency_key = ?', key); }
+export function listOpenInboxRequests() {
+    return many(openDb(), "state = 'open' AND inbox_listed = 1", [], 'created_at DESC, request_id DESC');
+}
+export function openRequestsByRequester(nodeId) {
+    return many(openDb(), "state = 'open' AND requester_node_id = ?", [nodeId], 'created_at DESC, request_id DESC');
+}
+/** Indexed attention projection: only open inbox-listed requests with a reply target keep a node wakeable. */
+export function listOpenReplyBearingRequests() {
+    return many(openDb(), "state = 'open' AND inbox_listed = 1 AND requester_node_id IS NOT NULL", [], 'created_at DESC, request_id DESC');
+}
+export function listBindingRequests() { return many(openDb(), "kind = 'review' AND state = 'binding'"); }
+export function listSubmitRequestedRequests() { return many(openDb(), "kind = 'review' AND state = 'open' AND submit_requested_at IS NOT NULL"); }
+export function listUnprojectedReviews() { return many(openDb(), "kind = 'review' AND state = 'settled' AND projected_at IS NULL"); }
+export function listRequests(filter = {}) {
+    const clauses = ['1'];
+    const params = [];
+    for (const [column, value] of Object.entries(filter)) {
+        if (value !== undefined) {
+            clauses.push(`${column} = ?`);
+            params.push(value);
+        }
+    }
+    return many(openDb(), clauses.join(' AND '), params);
+}
+export function openRequest(requestId, openedAt) {
+    return withCanvasWrite((db) => db.prepare("UPDATE human_requests SET state = 'open', opened_at = ?, updated_at = ? WHERE request_id = ? AND state = 'binding'").run(openedAt, openedAt, requestId).changes > 0);
+}
+/** A binding whose immutable branch disappeared never recaptures a new origin. */
+export function cancelBindingRequest(requestId, at, reason) {
+    return withCanvasWrite((db) => db.prepare(`
+    UPDATE human_requests SET state = 'settled', outcome = 'canceled', result_json = ?, settled_at = ?, updated_at = ?
+    WHERE request_id = ? AND kind = 'review' AND state = 'binding'
+  `).run(JSON.stringify({ schema: 'humanloop.cancel/v1', kind: 'canceled', canceledAt: at, reason }), at, at, requestId).changes > 0);
+}
+export function requestSubmit(requestId, at) {
+    return withCanvasWrite((db) => db.prepare("UPDATE human_requests SET submit_requested_at = ?, updated_at = ? WHERE request_id = ? AND kind = 'review' AND state = 'open' AND submit_requested_at IS NULL").run(at, at, requestId).changes > 0);
+}
+/** The first-writer-wins terminal transition. Callers add obligations in this same `withCanvasWrite` boundary. */
+export function settleRequestLocked(db, args) {
+    const changed = db.prepare(`
+    UPDATE human_requests SET state = 'settled', outcome = ?, result_json = ?, settled_at = ?,
+      progress_json = NULL, updated_at = ?
+    WHERE request_id = ? AND state = 'open'
+  `).run(args.outcome, args.result_json, args.settled_at, args.settled_at, args.request_id).changes;
+    return changed === 0 ? null : one(db, 'request_id = ?', args.request_id);
+}
+export function setSettlementDeliveryMarksLocked(db, requestId, marks) {
+    db.prepare(`UPDATE human_requests SET settlement_delivery_id = ?, action_delivery_id = ?, updated_at = ? WHERE request_id = ?`).run(marks.settlement_delivery_id ?? null, marks.action_delivery_id ?? null, new Date().toISOString(), requestId);
+}
+export function setSubmitNoteDeliveryLocked(db, requestId, deliveryId) {
+    return db.prepare(`UPDATE human_requests SET submit_note_delivery_id = ?, updated_at = ? WHERE request_id = ? AND state = 'open' AND submit_note_delivery_id IS NULL`).run(deliveryId, new Date().toISOString(), requestId).changes > 0;
+}
+export function revisePageRequest(requestId, values) {
+    return withCanvasWrite((db) => db.prepare(`
+    UPDATE human_requests SET presentation_dir = ?, specification_json = ?, title = ?, subtitle = ?, inbox_listed = ?, settleable = ?, updated_at = ?
+    WHERE request_id = ? AND kind = 'page' AND state = 'open'
+  `).run(values.presentation_dir, values.specification_json, values.title, values.subtitle, values.inbox_listed ? 1 : 0, values.settleable ? 1 : 0, new Date().toISOString(), requestId).changes > 0);
+}
+export function writeProgress(ticketId, responses) {
+    return withCanvasWrite((db) => db.prepare(`
+    UPDATE human_requests SET progress_json = ?, updated_at = ?
+    WHERE inbox_ticket_id = ? AND kind = 'page' AND state = 'open' AND settleable = 1
+  `).run(JSON.stringify({ kind: 'page', responses, savedAt: new Date().toISOString() }), new Date().toISOString(), ticketId).changes > 0);
+}
+export function markProjected(requestId, at) {
+    withCanvasWrite((db) => db.prepare(`UPDATE human_requests SET projected_at = ?, projection_error = NULL, updated_at = ? WHERE request_id = ?`).run(at, at, requestId));
+}
+export function markProjectionError(requestId, error) {
+    withCanvasWrite((db) => db.prepare(`UPDATE human_requests SET projection_error = ?, updated_at = ? WHERE request_id = ? AND projected_at IS NULL`).run(error, new Date().toISOString(), requestId));
+}
+export function markCompanionRetired(requestId, at) {
+    withCanvasWrite((db) => db.prepare(`UPDATE human_requests SET companion_retired_at = ?, updated_at = ? WHERE request_id = ? AND companion_retired_at IS NULL`).run(at, at, requestId));
+}
+export function readAnchorBase(requestId) {
+    const row = openDb().prepare('SELECT anchor_base_bytes, anchor_base_sha256 FROM human_requests WHERE request_id = ?').get(requestId);
+    return row === undefined || row.anchor_base_bytes === null || row.anchor_base_sha256 === null ? null : { bytes: Buffer.from(row.anchor_base_bytes), sha256: row.anchor_base_sha256 };
+}
+export function replaceAnchorBaseLocked(db, requestId, bytes, sha256) {
+    db.prepare('UPDATE human_requests SET anchor_base_bytes = ?, anchor_base_sha256 = ?, updated_at = ? WHERE request_id = ?').run(bytes, sha256, new Date().toISOString(), requestId);
+}
+function legacyPageResult(result) {
+    if (typeof result !== 'object' || result === null)
+        throw new Error('result is not an object');
+    const row = result;
+    if (row['kind'] === 'canceled')
+        return { outcome: row['disposition'] === 'dismissed' ? 'dismissed' : 'canceled', settledAt: String(row['canceledAt']) };
+    return { outcome: 'answered', settledAt: String(row['completedAt']) };
+}
+function readJson(path) {
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch (error) {
+        throw new Error(`corrupt required input: ${path}`, { cause: error });
+    }
+}
+function migrationId() { return randomBytes(16).toString('hex'); }
+function nextMessageSeq(db) {
+    return Number(db.prepare('SELECT COALESCE(MAX(seq), 0) AS seq FROM messages').get().seq) + 1;
+}
+function importedTerminalDelivery(db, requestId, requesterNodeId, kind) {
+    const row = kind === 'page'
+        ? db.prepare(`SELECT d.delivery_id FROM deliveries d JOIN messages m ON m.message_id = d.message_id
+        WHERE d.destination_kind = 'node_inbox' AND d.destination_id = ? AND m.sender_node_id = ?
+          AND m.disposition IN ('human-answer', 'human-canceled') LIMIT 1`).get(requesterNodeId, requestId)
+        : db.prepare(`SELECT d.delivery_id FROM deliveries d JOIN messages m ON m.message_id = d.message_id
+        WHERE d.destination_kind = 'node_inbox' AND d.destination_id = ? AND m.body_json LIKE ? LIMIT 1`).get(requesterNodeId, `%\"review_id\":\"${requestId}\"%`);
+    return row?.delivery_id ?? null;
+}
+function companionRetirementProven(db, companionNodeId, outcome) {
+    if (companionNodeId === null || outcome === null)
+        return false;
+    const row = db.prepare('SELECT status, final_report FROM nodes WHERE node_id = ?').get(companionNodeId);
+    return row?.status === 'canceled' || (outcome === 'approved' && row?.status === 'done' && row.final_report !== null);
+}
+function createMigratedTerminalDelivery(db, input) {
+    const messageId = migrationId();
+    const deliveryId = migrationId();
+    const now = Date.parse(input.settledAt);
+    const createdAt = Number.isFinite(now) ? now : 0;
+    const disposition = input.outcome === 'answered' || input.outcome === 'approved' ? 'human-answer' : 'human-canceled';
+    db.prepare(`INSERT INTO messages
+    (message_id, seq, operation_id, created_at, sender_node_id, sender_name, kind, label, body_ref, body_json, disposition)
+    VALUES (?, ?, ?, ?, NULL, 'crtrd', 'completed', ?, NULL, ?, ?)`)
+        .run(messageId, nextMessageSeq(db), migrationId(), input.settledAt, input.kind === 'review' ? (input.outcome === 'approved' ? 'review approved by the user' : 'review canceled') : (input.outcome === 'answered' ? 'human request answered' : 'human request canceled'), JSON.stringify(input.kind === 'review'
+        ? { review_id: input.requestId, result_path: `${input.requestDir}/result.json`, result: JSON.parse(input.resultJson) }
+        : { request_id: input.requestId, result: JSON.parse(input.resultJson) }), disposition);
+    db.prepare(`INSERT INTO deliveries
+    (delivery_id, message_id, destination_kind, destination_id, urgency, wake, state, attempts, created_at, updated_at)
+    VALUES (?, ?, 'node_inbox', ?, 'normal', 1, 'pending', 0, ?, ?)`)
+        .run(deliveryId, messageId, input.requesterNodeId, createdAt, createdAt);
+    return deliveryId;
+}
+function terminalDeliveryMark(db, input) {
+    if (input.requesterNodeId === null || input.outcome === null || input.resultJson === null || input.settledAt === null)
+        return null;
+    const imported = importedTerminalDelivery(db, input.requestId, input.requesterNodeId, input.kind);
+    if (imported !== null)
+        return imported;
+    if (input.deliveredAt !== null && input.deliveredAt !== undefined)
+        return null;
+    return createMigratedTerminalDelivery(db, {
+        requestId: input.requestId, requesterNodeId: input.requesterNodeId, kind: input.kind,
+        outcome: input.outcome, resultJson: input.resultJson, settledAt: input.settledAt, requestDir: input.requestDir,
+    });
+}
+/** Imports every legacy page and review inside the caller's already-open migration transaction. */
+const legacyPageSourceSchema = z.object({
+    sessionName: z.string().optional(),
+    askedBy: z.string().optional(),
+    blockedSince: z.string().optional(),
+    profileName: z.string().optional(),
+    nodeId: z.string().optional(),
+}).strict();
+const legacyPageSlotSchema = z.object({
+    id: z.string().regex(/^[A-Za-z0-9_-]{1,64}$/).optional(),
+    kind: z.string().min(1),
+    step: z.number().int().nonnegative(),
+    config: z.record(z.string(), z.unknown()),
+    unvalidated: z.literal(true).optional(),
+    display: z.literal(true).optional(),
+}).strict();
+const legacyPageManifestSchema = z.object({
+    schema: z.literal('crtr.page/v1'),
+    dialect: z.enum(['md', 'html', 'jsx']),
+    title: z.string().trim().min(1),
+    subtitle: z.string().optional(),
+    placement: z.enum(['inline', 'panel']),
+    document: z.enum(['page.md', 'page.html', 'page.tsx']),
+    steps: z.number().int().positive(),
+    slots: z.array(legacyPageSlotSchema),
+    source: legacyPageSourceSchema.optional(),
+}).strict().superRefine((manifest, ctx) => {
+    const document = manifest.dialect === 'md' ? 'page.md' : manifest.dialect === 'html' ? 'page.html' : 'page.tsx';
+    if (manifest.document !== document)
+        ctx.addIssue({ code: 'custom', path: ['document'], message: 'document must agree with dialect' });
+    if (manifest.dialect === 'md' && manifest.steps !== 1)
+        ctx.addIssue({ code: 'custom', path: ['steps'], message: 'md pages have exactly one step' });
+});
+function legacyPresentationSource(manifest) {
+    if (manifest.source === undefined)
+        return undefined;
+    const { blockedSince, ...source } = manifest.source;
+    const normalized = { ...source, ...(blockedSince !== undefined && z.string().datetime({ offset: true }).safeParse(blockedSince).success ? { emittedAt: blockedSince } : {}) };
+    return Object.keys(normalized).length === 0 ? undefined : normalized;
+}
+/** A discontinued v1 page is replayed as a static JSX page so current readers retain its authored bytes without reviving the retired dialect. */
+function legacyReplayDocument(title, subtitle, document) {
+    return `export default function LegacyPage() { return <Page title={${JSON.stringify(title)}}${subtitle === undefined ? '' : ` subtitle={${JSON.stringify(subtitle)}}`}><pre>{${JSON.stringify(document)}}</pre></Page>; }\n`;
+}
+function migrateLegacyPage(dir, raw) {
+    const manifestPath = join(dir, 'page.json');
+    const parsed = legacyPageManifestSchema.safeParse(raw);
+    if (!parsed.success)
+        throw new Error(`corrupt required input: ${manifestPath}`);
+    const manifest = parsed.data;
+    const source = legacyPresentationSource(manifest);
+    const delivery = {
+        placement: manifest.placement,
+        inbox: true,
+        reply: manifest.source?.blockedSince !== undefined,
+    };
+    try {
+        validatePageManifest({
+            schema: 'crtr.page/v2', dialect: 'jsx', title: manifest.title,
+            ...(manifest.subtitle === undefined ? {} : { subtitle: manifest.subtitle }),
+            delivery, document: 'page.tsx', steps: manifest.steps, slots: manifest.slots,
+            ...(source === undefined ? {} : { source }),
+        });
+    }
+    catch {
+        throw new Error(`corrupt required input: ${manifestPath}`);
+    }
+    const sourcePath = join(dir, manifest.document);
+    if (!existsSync(sourcePath))
+        throw new Error(`corrupt required input: ${sourcePath}`);
+    const sourceDocument = readFileSync(sourcePath, 'utf8');
+    const prepared = preparePageSource({ dialect: 'jsx', document: legacyReplayDocument(manifest.title, manifest.subtitle, sourceDocument), source, delivery });
+    if (source !== undefined)
+        return prepared;
+    const { source: _source, ...manifestWithoutSource } = prepared.manifest;
+    return { ...prepared, manifest: manifestWithoutSource };
+}
+export function migrateHumanRequestsState(db) {
+    db.exec(`
+    CREATE TABLE human_requests (
+      request_id TEXT PRIMARY KEY, kind TEXT NOT NULL CHECK (kind IN ('page','review')),
+      inbox_ticket_id TEXT NOT NULL UNIQUE, request_dir TEXT NOT NULL, presentation_dir TEXT,
+      requester_node_id TEXT,
+      companion_node_id TEXT UNIQUE, idempotency_key TEXT UNIQUE,
+      state TEXT NOT NULL CHECK (state IN ('binding','open','settled')),
+      outcome TEXT CHECK (outcome IN ('approved','answered','canceled','dismissed')),
+      inbox_listed INTEGER NOT NULL, settleable INTEGER NOT NULL, title TEXT NOT NULL, subtitle TEXT,
+      file TEXT, specification_json TEXT NOT NULL, action_json TEXT, progress_json TEXT, feedback_json TEXT,
+      result_json TEXT, anchor_base_sha256 TEXT, anchor_base_bytes BLOB, created_at TEXT NOT NULL,
+      opened_at TEXT, submit_requested_at TEXT, settled_at TEXT, settlement_delivery_id TEXT,
+      action_delivery_id TEXT, submit_note_delivery_id TEXT, projected_at TEXT, projection_error TEXT,
+      companion_retired_at TEXT, updated_at TEXT NOT NULL,
+      CHECK ((state = 'settled') = (outcome IS NOT NULL)),
+      CHECK ((state = 'settled') = (result_json IS NOT NULL)),
+      CHECK (kind <> 'page' OR presentation_dir IS NOT NULL)
+    );
+    CREATE INDEX idx_human_requests_inbox ON human_requests(state, inbox_listed);
+    CREATE INDEX idx_human_requests_kind_state ON human_requests(kind, state);
+    CREATE INDEX idx_human_requests_submit ON human_requests(state, submit_requested_at);
+    CREATE INDEX idx_human_requests_file ON human_requests(file);
+    CREATE INDEX idx_human_requests_requester ON human_requests(requester_node_id);
+  `);
+    const insert = db.prepare(`INSERT INTO human_requests (
+    request_id, kind, inbox_ticket_id, request_dir, presentation_dir, requester_node_id, companion_node_id, idempotency_key,
+    state, outcome, inbox_listed, settleable, title, subtitle, file, specification_json, action_json,
+    progress_json, feedback_json, result_json, anchor_base_sha256, anchor_base_bytes, created_at, opened_at,
+    submit_requested_at, settled_at, settlement_delivery_id, action_delivery_id, projected_at, projection_error,
+    companion_retired_at, updated_at
+  ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+    if (db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'reviews'").get() !== undefined) {
+        const rows = db.prepare('SELECT * FROM reviews').all();
+        for (const row of rows) {
+            const legacyState = row['state'];
+            const settled = legacyState === 'approved' || legacyState === 'canceled';
+            const result = legacyState === 'canceled' && row['result_json'] === null
+                ? JSON.stringify({ schema: 'humanloop.cancel/v1', kind: 'canceled', canceledAt: row['canceled_at'], ...(row['cancel_reason'] === '' || row['cancel_reason'] === null ? {} : { reason: row['cancel_reason'] }), ...(row['cancel_actor'] === null ? {} : { actor: row['cancel_actor'] }) })
+                : row['result_json'];
+            if (settled && result === null)
+                throw new Error(`corrupt required input: reviews/${row['review_id']} has no terminal result`);
+            const requestDirectory = row['bridge_node_id'] === null ? join(crtrHome(), 'reviews', row['review_id']) : join(nodesRoot(), row['bridge_node_id']);
+            const spec = {
+                origin_kind: row['origin_kind'], bridge_node_id: row['bridge_node_id'],
+                origin_session_file: row['origin_session_file'], origin_session_id: row['origin_session_id'], origin_leaf_id: row['origin_leaf_id'],
+                model_spec: row['model_spec'], branch_file: row['branch_file'], baseline_sha256: row['baseline_sha256'], baseline_bytes: row['baseline_bytes'],
+                captured_at: row['captured_at'], output_path: row['output_path'],
+            };
+            const outcome = settled ? (legacyState === 'approved' ? 'approved' : 'canceled') : null;
+            const settledAt = settled ? (legacyState === 'approved' ? row['approved_at'] : row['canceled_at']) : null;
+            const settlementDeliveryId = terminalDeliveryMark(db, {
+                requestId: row['review_id'], requesterNodeId: row['origin_node_id'], kind: 'review', outcome, resultJson: result,
+                settledAt, requestDir: requestDirectory, deliveredAt: row['delivered_at'],
+            });
+            const companionRetiredAt = companionRetirementProven(db, row['companion_node_id'], outcome) ? settledAt : null;
+            insert.run(row['review_id'], 'review', row['origin_kind'] === 'ticket' ? legacyTicketId(nodesRoot(), basename(requestDirectory)) : randomTicketId(), requestDirectory, null, row['origin_node_id'], row['companion_node_id'], row['idempotency_key'], settled ? 'settled' : legacyState, outcome, row['origin_kind'] === 'ticket' ? 1 : 0, 1, basename(row['file']), row['subtitle'], row['file'], JSON.stringify(spec), null, null, null, result, row['anchor_base_sha256'], row['anchor_base_bytes'], row['created'], row['opened_at'], row['submit_requested_at'], settledAt, settlementDeliveryId, null, row['projected_at'], row['projection_error'], companionRetiredAt, row['created']);
+        }
+        db.exec('DROP TABLE reviews');
+    }
+    for (const entry of existsSync(nodesRoot()) ? readdirSync(nodesRoot(), { withFileTypes: true }) : []) {
+        if (!entry.isDirectory())
+            continue;
+        const dir = join(nodesRoot(), entry.name);
+        const manifestPath = join(dir, 'page.json');
+        const reviewPath = join(dir, 'review.json');
+        if (!existsSync(manifestPath)) {
+            if (existsSync(reviewPath))
+                continue;
+            continue;
+        }
+        if (db.prepare('SELECT 1 FROM human_requests WHERE request_id = ?').get(entry.name) !== undefined)
+            continue;
+        const rawManifest = readJson(manifestPath);
+        if (typeof rawManifest !== 'object' || rawManifest === null || Array.isArray(rawManifest))
+            throw new Error(`corrupt required input: ${manifestPath}`);
+        let manifest = rawManifest;
+        let retainedPresentationDirectory = realpathSync(dir);
+        if (manifest['schema'] === 'crtr.page/v1') {
+            const prepared = migrateLegacyPage(dir, rawManifest);
+            const stableRequestDirectory = requestDir(entry.name);
+            retainedPresentationDirectory = publishPageRevision(stableRequestDirectory, prepared);
+            manifest = prepared.manifest;
+        }
+        const delivery = pageDeliverySchema.safeParse(manifest['delivery']);
+        if (typeof manifest['title'] !== 'string' || !delivery.success)
+            throw new Error(`corrupt required input: ${manifestPath}`);
+        let canonicalManifest;
+        try {
+            canonicalManifest = validatePageManifest(manifest);
+        }
+        catch {
+            throw new Error(`corrupt required input: ${manifestPath}`);
+        }
+        const source = canonicalManifest.source;
+        const resultPath = join(dir, 'response.json');
+        const result = existsSync(resultPath) ? readJson(resultPath) : null;
+        const terminal = result === null ? null : legacyPageResult(result);
+        const actionDelivery = db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'deliveries'").get() === undefined
+            ? null
+            : db.prepare("SELECT delivery_id FROM deliveries WHERE idempotency_key = ?").get(`human-action:${legacyTicketId(nodesRoot(), entry.name)}`);
+        const actionPath = join(dir, 'action.json');
+        const progressPath = join(dir, 'progress.json');
+        const feedbackPath = join(dir, 'feedback-comments.json');
+        const replyRoutePath = join(dir, 'reply-route.json');
+        const feedback = existsSync(feedbackPath) ? readJson(feedbackPath) : null;
+        if (feedback !== null && (typeof feedback !== 'object' || typeof feedback['companionNodeId'] !== 'undefined' && typeof feedback['companionNodeId'] !== 'string')) {
+            throw new Error(`corrupt required input: ${feedbackPath}`);
+        }
+        const replyRoute = existsSync(replyRoutePath) ? readJson(replyRoutePath) : null;
+        if (replyRoute !== null && (typeof replyRoute !== 'object' || typeof replyRoute['bridge_node_id'] !== 'string')) {
+            throw new Error(`corrupt required input: ${replyRoutePath}`);
+        }
+        const bridgeNodeId = replyRoute?.['bridge_node_id'];
+        const bridgeRequester = typeof bridgeNodeId !== 'string' || db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'nodes'").get() === undefined
+            ? null
+            : db.prepare('SELECT parent FROM nodes WHERE node_id = ?').get(bridgeNodeId);
+        const requesterNodeId = bridgeRequester?.parent ?? (typeof source?.['nodeId'] === 'string' ? source['nodeId'] : null);
+        const companionNodeId = feedback?.['companionNodeId'];
+        const createdAt = typeof source?.['emittedAt'] === 'string' ? source['emittedAt'] : statSync(manifestPath).mtime.toISOString();
+        const resultJson = result === null ? null : JSON.stringify(result);
+        const settlementDeliveryId = terminalDeliveryMark(db, {
+            requestId: entry.name, requesterNodeId, kind: 'page', outcome: terminal?.outcome ?? null, resultJson,
+            settledAt: terminal?.settledAt ?? null, requestDir: dir,
+        });
+        const companionRetiredAt = companionRetirementProven(db, companionNodeId ?? null, terminal?.outcome ?? null) ? terminal?.settledAt ?? null : null;
+        const stableRequestDirectory = requestDir(entry.name);
+        mkdirSync(stableRequestDirectory, { recursive: true, mode: 0o700 });
+        insert.run(entry.name, 'page', legacyTicketId(nodesRoot(), entry.name), stableRequestDirectory, retainedPresentationDirectory, requesterNodeId, companionNodeId ?? null, null, terminal === null ? 'open' : 'settled', terminal?.outcome ?? null, delivery.data.inbox ? 1 : 0, delivery.data.inbox || delivery.data.reply ? 1 : 0, canonicalManifest.title, canonicalManifest.subtitle ?? null, null, JSON.stringify(canonicalManifest), existsSync(actionPath) ? JSON.stringify(readJson(actionPath)) : null, existsSync(progressPath) && terminal === null ? JSON.stringify(readJson(progressPath)) : null, feedback === null ? null : JSON.stringify(feedback), resultJson, null, null, createdAt, null, null, terminal?.settledAt ?? null, settlementDeliveryId, actionDelivery?.delivery_id ?? null, null, null, companionRetiredAt, createdAt);
+    }
+    const invalid = db.prepare("SELECT request_id FROM human_requests WHERE state = 'settled' AND result_json IS NULL").get();
+    if (invalid !== undefined)
+        throw new Error(`human request migration produced terminal row without result: ${invalid.request_id}`);
+    if (db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'review_comments'").get() !== undefined) {
+        const orphan = db.prepare("SELECT review_id FROM review_comments WHERE review_id NOT IN (SELECT request_id FROM human_requests WHERE kind = 'review') LIMIT 1").get();
+        if (orphan !== undefined)
+            throw new Error(`review comment has no migrated review request: ${orphan.review_id}`);
+    }
+}