@north-light/crouter 0.3.311 → 0.3.313

package/dist/core/feed/messages.js

@@ -0,0 +1,217 @@
+import { existsSync, mkdirSync, renameSync, writeFileSync } from 'node:fs';
+import { randomBytes, randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+import { cancelCronsOnWake } from '../canvas/crons.js';
+import { withCanvasWrite } from '../canvas/db.js';
+import { getRow } from '../canvas/canvas.js';
+import { messagesDir } from '../canvas/paths.js';
+import { syncDirectory, syncFile } from '../fs-utils.js';
+import { settleDeadControllerWait, settleMatchingControllerWait } from '../canvas/waits.js';
+import { generateOperationId, operationIdContext, validateOperationId } from '../events/operation-id.js';
+import { clipBody } from './inbox.js';
+function newId() {
+    let id;
+    do
+        id = randomBytes(16).toString('hex');
+    while (id === '00000000000000000000000000000000');
+    return id;
+}
+function stringify(value, name) {
+    const json = JSON.stringify(value);
+    if (json === undefined)
+        throw new TypeError(`${name} must be JSON-serializable`);
+    return json;
+}
+function effectiveTier(nodeId, urgency) {
+    if (urgency !== 'normal' && urgency !== 'deferred')
+        return urgency;
+    return getRow(nodeId)?.lifecycle === 'terminal' ? 'urgent' : urgency;
+}
+function writeMessageBody(nodeId, createdAt, body) {
+    const dir = messagesDir(nodeId);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    const stamp = createdAt.replace(/[^0-9]/g, '');
+    const finalPath = join(dir, `${stamp}-${randomUUID().slice(0, 6)}.md`);
+    const temporaryPath = `${finalPath}.tmp`;
+    writeFileSync(temporaryPath, body, 'utf8');
+    syncFile(temporaryPath);
+    renameSync(temporaryPath, finalPath);
+    syncDirectory(dir);
+    return finalPath;
+}
+function inlineBody(bodyJson) {
+    if (typeof bodyJson !== 'object' || bodyJson === null)
+        return '';
+    const body = bodyJson['body'];
+    return typeof body === 'string' ? body.trim() : '';
+}
+function insertMessage(db, input) {
+    const messageId = input.messageId ?? newId();
+    const seq = Number(db.prepare('SELECT COALESCE(MAX(seq), 0) AS seq FROM messages').get().seq) + 1;
+    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 (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(messageId, seq, input.operationId, input.createdAt, input.senderNodeId, input.senderName, input.kind, input.label, input.bodyRef, input.bodyJson === undefined ? null : stringify(input.bodyJson, 'message body'), input.disposition);
+    return messageId;
+}
+function insertNodeDelivery(db, messageId, destinationId, urgency, wake, now, idempotencyKey) {
+    const deliveryId = newId();
+    db.prepare(`INSERT INTO deliveries
+       (delivery_id, message_id, destination_kind, destination_id, urgency, wake, state, idempotency_key, created_at, updated_at)
+     VALUES (?, ?, 'node_inbox', ?, ?, ?, 'pending', ?, ?, ?)`).run(deliveryId, messageId, destinationId, urgency, wake, idempotencyKey ?? null, now, now);
+    return deliveryId;
+}
+function finalizeNodeMail(input, destinationNodeId) {
+    const createdAt = new Date().toISOString();
+    const operationId = input.operationId === undefined
+        ? operationIdContext.current() ?? generateOperationId()
+        : validateOperationId(input.operationId);
+    let bodyRef = input.bodyRef ?? null;
+    let bodyJson = input.bodyJson;
+    if (bodyRef === null) {
+        const body = inlineBody(bodyJson);
+        const clipped = clipBody(body);
+        if (clipped.clipped) {
+            // The destination owns the referenced body. Publish the file before its reference enters the transaction.
+            bodyRef = writeMessageBody(destinationNodeId, createdAt, body);
+            bodyJson = { ...bodyJson, body: clipped.text };
+        }
+    }
+    return { createdAt, operationId, bodyRef, bodyJson };
+}
+/** Insert one immutable message and one node-inbox obligation into the caller's write transaction. */
+export function enqueueNodeMail(destinationNodeId, input) {
+    const prepared = finalizeNodeMail(input, destinationNodeId);
+    return withCanvasWrite((db) => {
+        if (input.idempotencyKey !== undefined) {
+            const existing = db.prepare(`SELECT d.delivery_id, d.message_id, d.urgency, m.created_at
+        FROM deliveries d JOIN messages m ON m.message_id = d.message_id WHERE d.idempotency_key = ?`).get(input.idempotencyKey);
+            if (existing !== undefined)
+                return { messageId: existing.message_id, deliveryId: existing.delivery_id, urgency: existing.urgency, createdAt: existing.created_at };
+        }
+        const now = Date.now();
+        const urgency = effectiveTier(destinationNodeId, input.urgency);
+        const messageId = insertMessage(db, {
+            operationId: prepared.operationId,
+            createdAt: prepared.createdAt,
+            senderNodeId: input.senderNodeId ?? null,
+            senderName: input.senderName ?? null,
+            kind: input.kind,
+            label: input.label,
+            bodyRef: prepared.bodyRef,
+            bodyJson: prepared.bodyJson,
+            disposition: input.disposition ?? null,
+        });
+        const deliveryId = insertNodeDelivery(db, messageId, destinationNodeId, urgency, input.wake, now, input.idempotencyKey);
+        settleMatchingControllerWait(destinationNodeId, input.senderNodeId ?? null, now, db);
+        if (input.wake === 1 && urgency !== 'deferred')
+            cancelCronsOnWake(destinationNodeId);
+        return { messageId, deliveryId, urgency, createdAt: prepared.createdAt };
+    });
+}
+/** Fan out one immutable report message to the supplied subscriber snapshot. */
+export function enqueueSubscriberMail(subscribers, input) {
+    if (subscribers.length === 0)
+        return [];
+    const prepared = finalizeNodeMail(input, subscribers[0].node_id);
+    return withCanvasWrite((db) => {
+        const now = Date.now();
+        const messageId = insertMessage(db, {
+            operationId: prepared.operationId,
+            createdAt: prepared.createdAt,
+            senderNodeId: input.senderNodeId ?? null,
+            senderName: input.senderName ?? null,
+            kind: input.kind,
+            label: input.label,
+            bodyRef: prepared.bodyRef,
+            bodyJson: prepared.bodyJson,
+            disposition: input.disposition ?? null,
+        });
+        return subscribers.map((subscriber) => {
+            const urgency = effectiveTier(subscriber.node_id, input.urgency);
+            const wake = subscriber.active ? 1 : 0;
+            const deliveryId = insertNodeDelivery(db, messageId, subscriber.node_id, urgency, wake, now);
+            settleMatchingControllerWait(subscriber.node_id, input.senderNodeId ?? null, now, db);
+            if (wake === 1 && urgency !== 'deferred')
+                cancelCronsOnWake(subscriber.node_id);
+            return { destinationNodeId: subscriber.node_id, messageId, deliveryId, urgency, createdAt: prepared.createdAt };
+        });
+    });
+}
+/** Insert one frozen external-action obligation. A duplicate idempotency key returns its original identity. */
+export function enqueueExternalAction(input) {
+    return withCanvasWrite((db) => {
+        const existing = db.prepare('SELECT delivery_id, message_id FROM deliveries WHERE idempotency_key = ?').get(input.idempotencyKey);
+        if (existing !== undefined)
+            return { messageId: existing.message_id, deliveryId: existing.delivery_id };
+        const now = Date.now();
+        const messageId = insertMessage(db, {
+            operationId: operationIdContext.current() ?? generateOperationId(),
+            createdAt: new Date(now).toISOString(),
+            senderNodeId: null,
+            senderName: null,
+            kind: input.kind ?? 'completed',
+            label: input.label ?? input.destinationId,
+            bodyRef: null,
+            bodyJson: input.bodyJson,
+            disposition: null,
+        });
+        const deliveryId = newId();
+        const inserted = db.prepare(`INSERT INTO deliveries
+         (delivery_id, message_id, destination_kind, destination_id, urgency, wake, state, next_attempt_at,
+          adapter_json, idempotency_key, created_at, updated_at)
+       VALUES (?, ?, 'external_action', ?, 'normal', 0, 'pending', ?, ?, ?, ?, ?)
+       ON CONFLICT(idempotency_key) WHERE idempotency_key IS NOT NULL DO NOTHING`).run(deliveryId, messageId, input.destinationId, now, stringify(input.adapter, 'external action adapter'), input.idempotencyKey, now, now);
+        if (Number(inserted.changes) === 1)
+            return { messageId, deliveryId };
+        const winner = db.prepare('SELECT delivery_id, message_id FROM deliveries WHERE idempotency_key = ?').get(input.idempotencyKey);
+        if (winner === undefined)
+            throw new Error(`external action idempotency winner disappeared: ${input.idempotencyKey}`);
+        return { messageId: winner.message_id, deliveryId: winner.delivery_id };
+    });
+}
+/** Retract an obligation without fabricating a terminal receipt. */
+export function cancelDelivery(deliveryId, now = Date.now()) {
+    return withCanvasWrite((db) => Number(db.prepare('UPDATE deliveries SET canceled_at = ?, updated_at = ? WHERE delivery_id = ? AND canceled_at IS NULL').run(now, now, deliveryId).changes) === 1);
+}
+export function cancelPendingNodeMail(nodeId, select = {}) {
+    return withCanvasWrite((db) => {
+        const clauses = ["d.destination_kind = 'node_inbox'", 'd.destination_id = ?', 'd.canceled_at IS NULL', "d.state IN ('pending', 'handed_off')"];
+        const params = [nodeId];
+        if (select.senderNodeId !== undefined) {
+            clauses.push('m.sender_node_id IS ?');
+            params.push(select.senderNodeId);
+        }
+        if (select.kind !== undefined) {
+            clauses.push('m.kind = ?');
+            params.push(select.kind);
+        }
+        const rows = db.prepare(`SELECT d.delivery_id FROM deliveries d JOIN messages m ON m.message_id = d.message_id WHERE ${clauses.join(' AND ')}`).all(...params);
+        if (rows.length === 0)
+            return [];
+        const now = Date.now();
+        db.prepare(`UPDATE deliveries SET canceled_at = ?, updated_at = ? WHERE delivery_id IN (${rows.map(() => '?').join(',')})`)
+            .run(now, now, ...rows.map((row) => row.delivery_id));
+        return rows.map((row) => row.delivery_id);
+    });
+}
+/** Enqueue the one notice only if the same live controller wait is still dead. */
+export function enqueueControllerDeathNotice(nodeId, controllerId) {
+    return withCanvasWrite((db) => {
+        const now = Date.now();
+        const row = db.prepare(`SELECT target.status AS controller_status FROM waits w LEFT JOIN nodes target ON target.node_id = w.target_id
+        WHERE w.node_id = ? AND w.kind = 'controller' AND w.target_id = ? AND w.satisfied_at IS NULL`).get(nodeId, controllerId);
+        if (row === undefined || row.controller_status === 'active' || row.controller_status === 'idle')
+            return null;
+        const result = enqueueNodeMail(nodeId, {
+            kind: 'urgent',
+            label: 'declared controller is no longer live',
+            bodyJson: { body: `Controller ${controllerId} is no longer live; the declared message wait was cleared.` },
+            urgency: 'urgent',
+            wake: 1,
+        });
+        if (!settleDeadControllerWait(nodeId, controllerId, now, db))
+            throw new Error(`controller wait changed while notifying ${nodeId}`);
+        return result;
+    });
+}

package/dist/core/fs-utils.d.ts

@@ -13,6 +13,10 @@ export interface AtomicWriteOptions {
     mode?: number;
 }
 export declare function atomicWriteJson(path: string, data: unknown, opts?: AtomicWriteOptions): void;
+/** Force a file's written bytes to stable storage. */
+export declare function syncFile(path: string): void;
+/** Force a directory's entry changes to stable storage. */
+export declare function syncDirectory(path: string): void;
 /** Replace one file's contents in a single rename, so a concurrent reader — the
  *  tmux inbox watcher, or crtrd serving a ticket read — sees either the old
  *  bytes or the new ones and never a truncated file mid-write. */

package/dist/core/fs-utils.js

@@ -1,4 +1,4 @@
-import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, symlinkSync, writeFileSync, cpSync, readlinkSync, renameSync, chmodSync, realpathSync, } from 'node:fs';
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, symlinkSync, writeFileSync, cpSync, readlinkSync, renameSync, chmodSync, realpathSync, closeSync, fsyncSync, openSync, } from 'node:fs';
 import { dirname, join, relative, sep } from 'node:path';
 import { homedir, platform } from 'node:os';
 /** `realpathSync`, tolerant of a path that doesn't exist or can't be resolved. */
@@ -38,6 +38,26 @@ export function writeJson(path, data) {
 export function atomicWriteJson(path, data, opts) {
     atomicWriteText(path, JSON.stringify(data, null, 2) + '\n', opts);
 }
+/** Force a file's written bytes to stable storage. */
+export function syncFile(path) {
+    const fd = openSync(path, 'r');
+    try {
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/** Force a directory's entry changes to stable storage. */
+export function syncDirectory(path) {
+    const fd = openSync(path, 'r');
+    try {
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
 /** Replace one file's contents in a single rename, so a concurrent reader — the
  *  tmux inbox watcher, or crtrd serving a ticket read — sees either the old
  *  bytes or the new ones and never a truncated file mid-write. */

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

@@ -49,5 +49,5 @@ export declare function answerCommentAnchorLabel(slot: PageSlot, anchor: LegacyC
 /** Derive the one shared answer model from the immutable page manifest and a response map. */
 /** `manifest` is unknown deliberately: this boundary validates persisted JSON before deriving. */
 export declare function describePageAnswer(manifest: unknown, responses: PageResponses, opts: DescribePageAnswerOptions): PageAnswer;
-/** The stable one-line digest stored in response.json and shown in history. */
+/** The stable one-line digest stored in the terminal request result and shown in history. */
 export declare function buildAnswerDigest(slots: PageAnswerSlot[]): string;

package/dist/core/human/answer.js

@@ -100,7 +100,7 @@ function groupDigest(group) {
         return group.picked.map((item) => item.label).join(', ');
     return group.total > 0 ? `${group.picked.length} of ${group.total} ${group.group}s` : `${group.picked.length} ${group.group}${group.picked.length === 1 ? '' : 's'}`;
 }
-/** The stable one-line digest stored in response.json and shown in history. */
+/** The stable one-line digest stored in the terminal request result and shown in history. */
 export function buildAnswerDigest(slots) {
     return slots.map((slot) => {
         if (slot.raw !== undefined)

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

@@ -14,7 +14,7 @@ export interface ClaimOptions {
 }
 export declare function readTicketClaim(dir: string): TicketClaim | null;
 export declare function isStaleClaim(claim: TicketClaim, now?: number, localHost?: string): boolean;
-/** Acquire a visible claim only for a still-pending ticket. Malformed crash artifacts are stale claims. */
+/** Exclude another live presenter; the daemon owns whether the request can settle. */
 export declare function claimTicket(dir: string, opts?: ClaimOptions): TicketClaim | null;
 export declare function heartbeatClaim(dir: string, token: string, now?: Date): boolean;
 export declare function releaseClaimLocked(dir: string, token: string): boolean;

package/dist/core/human/claim.js

@@ -1,7 +1,7 @@
 import { existsSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
 import { hostname } from 'node:os';
 import { randomUUID } from 'node:crypto';
-import { claimPath, pageManifestPath, responsePath, reviewPath } from './convention.js';
+import { claimPath } from './convention.js';
 import { readJsonOrNull } from '../fs-utils.js';
 import { withExclusiveDirectoryLock } from '../exclusive-lock.js';
 const REMOTE_STALE_MS = 30_000;
@@ -27,11 +27,9 @@ export function isStaleClaim(claim, now = Date.now(), localHost = hostname()) {
     const heartbeat = Date.parse(claim.heartbeatAt);
     return !Number.isFinite(heartbeat) || now - heartbeat > REMOTE_STALE_MS;
 }
-/** Acquire a visible claim only for a still-pending ticket. Malformed crash artifacts are stale claims. */
+/** Exclude another live presenter; the daemon owns whether the request can settle. */
 export function claimTicket(dir, opts = {}) {
     return withExclusiveDirectoryLock(`${dir}/.ticket-lock`, () => {
-        if (existsSync(responsePath(dir)) || (!existsSync(pageManifestPath(dir)) && !existsSync(reviewPath(dir))))
-            return null;
         const path = claimPath(dir);
         const existing = readTicketClaim(dir);
         if (existing !== null && !isStaleClaim(existing, Date.now(), opts.host ?? hostname()))

package/dist/core/human/component-docs.js

@@ -10,7 +10,7 @@ const SLOT_RULES = `Component contract
 - When a page has two or more response-bearing components, every one needs a nonempty \`label\`.
 - Config objects and every documented nested object reject unknown fields.
 - A quoted JSX attribute does not interpret escape sequences, so \`body="one.\\n\\ntwo."\` reaches the reader as one run-on paragraph with a literal backslash-n in the middle of it. Write any markdown body that has a line or paragraph break as a braced string — \`body={"one.\\n\\ntwo."}\` — where the escape is real.
-- The page is rendered once at submit to build the ticket manifest, so every prop reaches it whatever its shape — mapped data, a helper component, a value from \`useState\`. Event handlers are dropped, because a manifest is JSON. The user's answer lands in \`response.json\` keyed by this \`id\`.`;
+- The page is rendered once at submit to build the ticket manifest, so every prop reaches it whatever its shape — mapped data, a helper component, a value from \`useState\`. Event handlers are dropped, because a manifest is JSON. The user's answer is stored in the request's terminal result under this \`id\`.`;
 const COMMENT_SHAPE = `Comments are \`{id:string (nonempty), text:string, anchor:Anchor}\` and qualify the answer itself. \`Anchor\` is \`{kind:"option",optionId:string}\` or \`{kind:"row",rowId:string}\`; each component accepts only the anchors named next. The reader writes one against a specific option or row in whatever host they read in — in the terminal inbox, \`c\` on the selected one — so every option and row needs a label that reads on its own. Feedback on the page's own prose is a separate channel, offered only by hosts that render the page, and never part of a response.`;
 const DISPLAY_RULES = `Display-only: it is not recorded in the page manifest and contributes nothing to the response. Every display component also takes \`className\` for Tailwind utilities, and standard shadcn props otherwise.`;
 export const BUILTIN_COMPONENT_DOCS = [

package/dist/core/human/feedback-companion.js

@@ -18,11 +18,12 @@ import { reviveNode } from '../runtime/revive.js';
 import { materializeSessionBranchAt } from '../runtime/session-branch.js';
 import { initializeForkContextExposure } from '../substrate/injected-store.js';
 import { pagePath } from './convention.js';
+import { selectedPageDir } from './tickets.js';
 export function feedbackCompanionBranchPath(dir) { return `${dir}/companion-branch.jsonl`; }
 /** Hex sha256 of the ticket's page document, recorded at first comment so the
  * settle-time completion can say whether the page changed during feedback. */
 export function pageDocumentSha256(dir) {
-    return createHash('sha256').update(readFileSync(pagePath(dir, 'jsx'))).digest('hex');
+    return createHash('sha256').update(readFileSync(pagePath(selectedPageDir(dir), 'jsx'))).digest('hex');
 }
 /** Materialize the companion's fork branch, reusing only an already-valid one. */
 function materializeFeedbackBranch(dir, capture) {
@@ -65,7 +66,7 @@ export async function realizeFeedbackCompanion(args) {
         cwd: origin.cwd,
         profileId: origin.profile_id ?? null,
     });
-    const node = spawnNode({
+    const node = await spawnNode({
         kind: origin.kind,
         mode: origin.mode,
         lifecycle: 'resident',
@@ -82,7 +83,7 @@ export async function realizeFeedbackCompanion(args) {
             review_id: args.ticketId,
             origin_node_id: args.senderNodeId,
             branch_file: branchFile,
-            target_file: pagePath(args.dir, 'jsx'),
+            target_file: pagePath(selectedPageDir(args.dir), 'jsx'),
         },
         name: `Feedback · ${args.title}`,
         launch,

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

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 export declare const PAGE_FEEDBACK_SCHEMA: "crtr.page-feedback/v1";
+/** The path is a presentation projection, not the feedback authority. */
 export declare function pageFeedbackPath(dir: string): string;
 declare const pageFeedbackCommentSchema: z.ZodObject<{
     id: z.ZodString;
@@ -32,24 +33,19 @@ declare const pageFeedbackSchema: z.ZodObject<{
 }, z.core.$strict>;
 export type PageFeedbackComment = z.infer<typeof pageFeedbackCommentSchema>;
 export type PageFeedback = z.infer<typeof pageFeedbackSchema>;
-/** Read a ticket's feedback comments; a ticket without any has an empty record. */
+/** Read page feedback from the request row. */
 export declare function readPageFeedback(dir: string): PageFeedback;
 export interface CreatePageFeedbackCommentInput {
     quote: string;
     context?: string;
     note: string;
-    /** Bound as the ticket's companion when none is recorded yet. An already
-     * recorded companion wins; the first writer's companion stays the target. */
     companionNodeId?: string;
-    /** Recorded with the companion binding; ignored once one is recorded. */
     firstCommentedSha256?: string;
 }
 export interface PageFeedbackMutation {
     comment: PageFeedbackComment;
     feedback: PageFeedback;
 }
-/** Append one open feedback comment under the ticket lock. */
-export declare function createPageFeedbackComment(dir: string, input: CreatePageFeedbackCommentInput): PageFeedbackMutation;
 export declare class PageTicketTerminalError extends Error {
     constructor();
 }
@@ -59,7 +55,8 @@ export declare class UnknownPageFeedbackCommentError extends Error {
 export declare class PageFeedbackCommentAlreadyResolvedError extends Error {
     constructor(commentId: string);
 }
-/** Mark one open comment resolved under the ticket lock. Terminal: a resolved
- * comment never reopens; a renewed concern is a new comment. */
+/** Append feedback in the request transaction; terminal rows reject it. */
+export declare function createPageFeedbackComment(dir: string, input: CreatePageFeedbackCommentInput): PageFeedbackMutation;
+/** Resolve one feedback comment in the request transaction. */
 export declare function resolvePageFeedbackComment(dir: string, commentId: string): PageFeedbackMutation;
 export {};

package/dist/core/human/feedback.js

@@ -1,116 +1,88 @@
-// Page feedback comments — ticket-attached notes on highlighted page content.
-// Feedback is about the agent's WORK, never part of the page answer: it lives
-// in its own file beside the page, delivers immediately to the ticket's
-// companion conversation, and reaches the response the sender reads at settle
-// only as the unresolved-item addendum. A sent comment is immutable — it is
-// either open or resolved, and only the companion resolves it. The file name
-// is `feedback-comments.json` — `feedback.json` is the review subsystem's
-// output file and must not be shadowed.
-import { existsSync, readFileSync } from 'node:fs';
 import { randomUUID } from 'node:crypto';
 import { z } from 'zod';
-import { atomicWriteJson } from './convention.js';
-import { withTicketLock } from './claim.js';
-import { pageTicketState } from './tickets.js';
+import { withCanvasWrite } from '../canvas/db.js';
+import { getRequestByDirectory } from './requests.js';
 export const PAGE_FEEDBACK_SCHEMA = 'crtr.page-feedback/v1';
+/** The path is a presentation projection, not the feedback authority. */
 export function pageFeedbackPath(dir) { return `${dir}/feedback-comments.json`; }
 const pageFeedbackCommentSchema = z.object({
-    id: z.string().min(1),
-    /** The highlighted text the note is about; for a chart, its title. */
-    quote: z.string().min(1),
-    /** Surrounding text that locates the quote on the page. */
-    context: z.string().optional(),
-    note: z.string().min(1),
-    /** Open until the companion has dealt with it; resolution is terminal. */
-    status: z.enum(['open', 'resolved']),
-    createdAt: z.string().datetime({ offset: true }),
-    resolvedAt: z.string().datetime({ offset: true }).optional(),
+    id: z.string().min(1), quote: z.string().min(1), context: z.string().optional(), note: z.string().min(1),
+    status: z.enum(['open', 'resolved']), createdAt: z.string().datetime({ offset: true }), resolvedAt: z.string().datetime({ offset: true }).optional(),
 }).strict();
 const pageFeedbackSchema = z.object({
-    schema: z.literal(PAGE_FEEDBACK_SCHEMA),
-    /** The ticket-bound companion conversation every comment delivers to;
-     * recorded by the first comment and never replaced. */
-    companionNodeId: z.string().min(1).optional(),
-    /** Hex sha256 of the page document at first comment, for the settle-time
-     * change notice to the sender. */
-    firstCommentedSha256: z.string().min(1).optional(),
-    comments: z.array(pageFeedbackCommentSchema),
+    schema: z.literal(PAGE_FEEDBACK_SCHEMA), companionNodeId: z.string().min(1).optional(),
+    firstCommentedSha256: z.string().min(1).optional(), comments: z.array(pageFeedbackCommentSchema),
 }).strict();
-function emptyFeedback() {
-    return { schema: PAGE_FEEDBACK_SCHEMA, comments: [] };
+function emptyFeedback() { return { schema: PAGE_FEEDBACK_SCHEMA, comments: [] }; }
+function requestForDirectory(dir) {
+    const request = getRequestByDirectory(dir);
+    if (request === null || request.kind !== 'page')
+        throw new Error(`unknown page request directory: ${dir}`);
+    return request;
 }
-/** Read a ticket's feedback comments; a ticket without any has an empty record. */
-export function readPageFeedback(dir) {
-    const path = pageFeedbackPath(dir);
-    if (!existsSync(path))
-        return emptyFeedback();
-    let raw;
+function feedback(request) {
+    if (request.feedback_json === null)
+        return request.companion_node_id === null ? emptyFeedback() : { ...emptyFeedback(), companionNodeId: request.companion_node_id };
     try {
-        raw = JSON.parse(readFileSync(path, 'utf8'));
+        return pageFeedbackSchema.parse(JSON.parse(request.feedback_json));
     }
-    catch {
-        throw new Error(`page feedback is not valid JSON: ${path}`);
+    catch (error) {
+        throw new Error(`page feedback is malformed for ${request.request_id}`, { cause: error });
     }
-    const parsed = pageFeedbackSchema.safeParse(raw);
-    if (!parsed.success)
-        throw new Error(`page feedback is malformed: ${path}`);
-    return parsed.data;
-}
-/** Append one open feedback comment under the ticket lock. */
-export function createPageFeedbackComment(dir, input) {
-    return withTicketLock(dir, () => {
-        requirePendingTicket(dir);
-        const feedback = readPageFeedback(dir);
-        if (feedback.companionNodeId === undefined && input.companionNodeId !== undefined) {
-            feedback.companionNodeId = input.companionNodeId;
-            if (input.firstCommentedSha256 !== undefined)
-                feedback.firstCommentedSha256 = input.firstCommentedSha256;
-        }
-        const comment = {
-            id: randomUUID(),
-            quote: input.quote,
-            ...(input.context === undefined ? {} : { context: input.context }),
-            note: input.note,
-            status: 'open',
-            createdAt: new Date().toISOString(),
-        };
-        feedback.comments.push(comment);
-        atomicWriteJson(pageFeedbackPath(dir), feedback);
-        return { comment, feedback };
-    });
 }
+/** Read page feedback from the request row. */
+export function readPageFeedback(dir) { return feedback(requestForDirectory(dir)); }
 export class PageTicketTerminalError extends Error {
     constructor() { super('ticket already has a terminal outcome'); }
 }
-/** Settlement commits its terminal outcome under this same ticket lock, so an
- * in-lock pending check is the race-free gate: no feedback mutation may land
- * after the first ticket-ending action, however long the caller's own
- * pre-lock work (a companion fork await) took. */
-function requirePendingTicket(dir) {
-    const state = pageTicketState(dir);
-    if (state === 'resolved' || state === 'canceled')
-        throw new PageTicketTerminalError();
-}
 export class UnknownPageFeedbackCommentError extends Error {
     constructor(commentId) { super(`no feedback comment ${commentId} on this ticket`); }
 }
 export class PageFeedbackCommentAlreadyResolvedError extends Error {
     constructor(commentId) { super(`feedback comment ${commentId} is already resolved`); }
 }
-/** Mark one open comment resolved under the ticket lock. Terminal: a resolved
- * comment never reopens; a renewed concern is a new comment. */
+/** Append feedback in the request transaction; terminal rows reject it. */
+export function createPageFeedbackComment(dir, input) {
+    const request = requestForDirectory(dir);
+    return withCanvasWrite((db) => {
+        const current = db.prepare('SELECT * FROM human_requests WHERE request_id = ?').get(request.request_id);
+        if (current === undefined)
+            throw new Error(`human request disappeared: ${request.request_id}`);
+        if (current['state'] !== 'open')
+            throw new PageTicketTerminalError();
+        const row = { ...request, feedback_json: current['feedback_json'], companion_node_id: current['companion_node_id'] };
+        const next = feedback(row);
+        if (next.companionNodeId === undefined && input.companionNodeId !== undefined) {
+            next.companionNodeId = input.companionNodeId;
+            if (input.firstCommentedSha256 !== undefined)
+                next.firstCommentedSha256 = input.firstCommentedSha256;
+        }
+        const comment = { id: randomUUID(), quote: input.quote, ...(input.context === undefined ? {} : { context: input.context }), note: input.note, status: 'open', createdAt: new Date().toISOString() };
+        next.comments.push(comment);
+        pageFeedbackSchema.parse(next);
+        db.prepare('UPDATE human_requests SET feedback_json = ?, companion_node_id = COALESCE(companion_node_id, ?), updated_at = ? WHERE request_id = ?').run(JSON.stringify(next), next.companionNodeId ?? null, new Date().toISOString(), request.request_id);
+        return { comment, feedback: next };
+    });
+}
+/** Resolve one feedback comment in the request transaction. */
 export function resolvePageFeedbackComment(dir, commentId) {
-    return withTicketLock(dir, () => {
-        requirePendingTicket(dir);
-        const feedback = readPageFeedback(dir);
-        const comment = feedback.comments.find((entry) => entry.id === commentId);
+    const request = requestForDirectory(dir);
+    return withCanvasWrite((db) => {
+        const current = db.prepare('SELECT * FROM human_requests WHERE request_id = ?').get(request.request_id);
+        if (current === undefined)
+            throw new Error(`human request disappeared: ${request.request_id}`);
+        if (current['state'] !== 'open')
+            throw new PageTicketTerminalError();
+        const row = { ...request, feedback_json: current['feedback_json'], companion_node_id: current['companion_node_id'] };
+        const next = feedback(row);
+        const comment = next.comments.find((entry) => entry.id === commentId);
         if (comment === undefined)
             throw new UnknownPageFeedbackCommentError(commentId);
         if (comment.status === 'resolved')
             throw new PageFeedbackCommentAlreadyResolvedError(commentId);
         comment.status = 'resolved';
         comment.resolvedAt = new Date().toISOString();
-        atomicWriteJson(pageFeedbackPath(dir), feedback);
-        return { comment, feedback };
+        db.prepare('UPDATE human_requests SET feedback_json = ?, updated_at = ? WHERE request_id = ?').run(JSON.stringify(next), new Date().toISOString(), request.request_id);
+        return { comment, feedback: next };
     });
 }

package/dist/core/human/page-authoring.d.ts

@@ -0,0 +1,30 @@
+import type { ProductPageComponents } from '../../types.js';
+import type { PageDelivery, PageManifest, PageSource } from './page-schema.js';
+/** One validated page, ready for the daemon to publish. */
+export interface PreparedPage {
+    /** The authored source, verbatim, as the request's `document`. */
+    document: string;
+    /** The compiled CommonJS module the Gateway evaluates for JSX pages. */
+    module?: string;
+    manifest: PageManifest;
+}
+export interface PreparePageSourceOptions {
+    /** `jsx` carries .tsx semantics; `html` is a complete document. */
+    dialect: 'jsx' | 'html';
+    /** The complete authored page text, inline. */
+    document: string;
+    source?: PageSource;
+    productKinds?: ProductPageComponents;
+    delivery?: PageDelivery;
+}
+export interface PreparePageOptions {
+    /** The authored page source. */
+    sourceFile: string;
+    source?: PageSource;
+    productKinds?: ProductPageComponents;
+    delivery?: PageDelivery;
+}
+/** Validate one authored page document into a transportable request. */
+export declare function preparePageSource(opts: PreparePageSourceOptions): PreparedPage;
+/** Validate one authored page source file without reading or writing canvas state. */
+export declare function preparePage(opts: PreparePageOptions): PreparedPage;

package/dist/core/human/page-authoring.js

@@ -0,0 +1,19 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { compilePage, deriveHtmlPageManifest, derivePageManifestFromDocument, PageAuthoringError } from './page.js';
+/** Validate one authored page document into a transportable request. */
+export function preparePageSource(opts) {
+    const stamped = { ...(opts.source ?? {}), emittedAt: opts.source?.emittedAt ?? new Date().toISOString() };
+    const delivery = opts.delivery ?? { placement: 'inline', inbox: false, reply: false };
+    if (opts.dialect === 'html')
+        return { document: opts.document, manifest: deriveHtmlPageManifest(opts.document, stamped, delivery) };
+    return { document: opts.document, module: compilePage(opts.document), manifest: derivePageManifestFromDocument(opts.document, opts.productKinds ?? [], stamped, delivery) };
+}
+/** Validate one authored page source file without reading or writing canvas state. */
+export function preparePage(opts) {
+    const html = /\.html?$/i.test(opts.sourceFile);
+    if (!html && !opts.sourceFile.endsWith('.tsx'))
+        throw new PageAuthoringError(`page source file must be .tsx, .html, or .htm: ${opts.sourceFile}`);
+    if (!existsSync(opts.sourceFile))
+        throw new PageAuthoringError(`page source file does not exist: ${opts.sourceFile}`);
+    return preparePageSource({ ...opts, dialect: html ? 'html' : 'jsx', document: readFileSync(opts.sourceFile, 'utf8') });
+}