@north-light/crouter 0.3.311 → 0.3.313

package/dist/daemon/api/handlers/human.js

@@ -1,148 +1,3 @@
-// Human bridge and ticket-work routes owned by crtrd. Ticket directories are
-// derived from bridge node ids; callers never supply a filesystem path, root,
-// handler, or claim binding.
-import { existsSync } from 'node:fs';
-import { ApiError } from '../../../api/index.js';
-import { isSafeNodeId } from '../../../core/canvas/paths.js';
-import { pageManifestPath, readTicketReplyRoute, reviewPath } from '../../../core/human/convention.js';
-import { ticketDir } from '../../../core/human/root.js';
-import { readTicketResult, validatePageTicketResponses } from '../../../core/human/tickets.js';
-import { getReviewByBridge } from '../../../core/review/store.js';
-import { ReviewOperationError } from '../../../core/review/types.js';
-import { spawnNode } from '../../../core/runtime/nodes.js';
-import { cancelHumanTicket, resolvePageTicket } from '../../human/finish.js';
-import { cancelReview } from '../../review/finish.js';
-function requireInteractionTicketId(ctx) {
-    const ticketId = ctx.params['ticket_id'];
-    if (ticketId === undefined || !isSafeNodeId(ticketId)) {
-        throw new ApiError(400, 'invalid_request', 'invalid interaction ticket id');
-    }
-    return ticketId;
-}
-// POST /v1/human/bridge — create a terminal bridge without a broker
-function handleCreateBridge(ctx) {
-    const req = ctx.body;
-    if (req === undefined || typeof req !== 'object') {
-        throw new ApiError(400, 'invalid_request', 'bridge body is required');
-    }
-    const { kind, cwd, name } = req;
-    if (kind !== 'human')
-        throw new ApiError(400, 'invalid_request', 'bridge kind must be "human"');
-    if (typeof cwd !== 'string' || cwd === '')
-        throw new ApiError(400, 'invalid_request', 'bridge body requires `cwd`');
-    if (typeof name !== 'string' || name === '')
-        throw new ApiError(400, 'invalid_request', 'bridge body requires `name`');
-    const parent = req.parent ?? null;
-    if (parent !== null && (typeof parent !== 'string' || parent === '')) {
-        throw new ApiError(400, 'invalid_request', 'bridge `parent` must be a node id or null');
-    }
-    try {
-        const node = spawnNode({ kind: 'human', parent, creator: parent, cwd, name, lifecycle: 'terminal' });
-        return { status: 200, body: { node_id: node.node_id, name: node.name } };
-    }
-    catch (error) {
-        throw new ApiError(400, 'invalid_request', String(error));
-    }
-}
-// POST /v1/human/tickets/:ticket_id/resolve and /cancel
-function reviewSubmitGuidance() {
-    return new ApiError(400, 'invalid_request', 'review approvals use POST /v1/human/reviews/:review_id/submit');
-}
-/** The ticket resolve route accepts only a page response body. */
-function requireResolveRequest(ctx) {
-    const request = ctx.body;
-    if (request === undefined || request === null || typeof request !== 'object' || Array.isArray(request)) {
-        throw new ApiError(400, 'invalid_request', 'ticket resolve body is required');
-    }
-    const body = request;
-    const fields = Object.keys(body);
-    if (fields.length === 1 && fields[0] === 'responses')
-        return { responses: body['responses'] };
-    if ('feedback' in body)
-        throw reviewSubmitGuidance();
-    throw new ApiError(400, 'invalid_request', 'ticket resolve body requires exactly `responses`');
-}
-function requirePageTicket(dir) {
-    const page = existsSync(pageManifestPath(dir));
-    const review = existsSync(reviewPath(dir));
-    if (review && !page)
-        throw reviewSubmitGuidance();
-    if (!page || review) {
-        throw new ApiError(400, 'invalid_request', 'ticket has no unambiguous page kind');
-    }
-}
-function invalidResolveRequest(error) {
-    const detail = error instanceof Error ? error.message : String(error);
-    if (detail === 'page_has_no_response_lifecycle')
-        return new ApiError(409, 'page_has_no_response_lifecycle', 'this page has no response lifecycle');
-    return new ApiError(400, 'invalid_request', `invalid ticket resolve body: ${detail}`);
-}
-function preflightResolve(validate) {
-    try {
-        return validate();
-    }
-    catch (error) {
-        throw invalidResolveRequest(error);
-    }
-}
-async function handleResolve(ctx) {
-    const ticketId = requireInteractionTicketId(ctx);
-    const request = requireResolveRequest(ctx);
-    const dir = ticketDir(ticketId);
-    requirePageTicket(dir);
-    const responses = preflightResolve(() => validatePageTicketResponses(dir, request.responses));
-    const replyExpected = readTicketReplyRoute(dir) !== null;
-    await resolvePageTicket(ticketId, responses);
-    return { status: 200, body: { completed: true, reply_delivered: replyExpected, kind: 'page' } };
-}
-function hasPublishedTicket(dir) {
-    return existsSync(pageManifestPath(dir)) || readTicketResult(dir) !== null;
-}
-async function handleCancel(ctx) {
-    const ticketId = requireInteractionTicketId(ctx);
-    const request = ctx.body;
-    if (request !== undefined && (typeof request !== 'object' || request === null)) {
-        throw new ApiError(400, 'invalid_request', 'ticket cancel body must be an object');
-    }
-    if (request?.disposition !== undefined && request.disposition !== 'canceled' && request.disposition !== 'dismissed') {
-        throw new ApiError(400, 'invalid_request', '`disposition` must be "canceled" or "dismissed"');
-    }
-    const dir = ticketDir(ticketId);
-    const review = getReviewByBridge(ticketId);
-    try {
-        if (review !== null) {
-            if (review.state === 'approved') {
-                throw new ApiError(409, 'ticket_already_resolved', 'ticket already resolved');
-            }
-            const finished = await cancelReview(review.review_id, request ?? {});
-            if (finished.outcome === 'already_settled') {
-                throw new ApiError(409, 'ticket_already_resolved', 'ticket already resolved');
-            }
-            return { status: 200, body: { canceled: true } };
-        }
-        // A binding row has no published ticket. It is intentionally
-        // indistinguishable from an unknown node id on this ticket surface.
-        if (!hasPublishedTicket(dir)) {
-            throw new ApiError(404, 'ticket_not_found', 'no matching ticket');
-        }
-        await cancelHumanTicket(ticketId, request ?? {});
-        return { status: 200, body: { canceled: true } };
-    }
-    catch (error) {
-        if (error instanceof ApiError)
-            throw error;
-        if (error instanceof Error && error.message === 'page_has_no_response_lifecycle') {
-            throw new ApiError(409, 'page_has_no_response_lifecycle', 'this page has no response lifecycle');
-        }
-        // Review errors are not part of the retained ticket route's vocabulary.
-        if (error instanceof ReviewOperationError) {
-            throw new ApiError(409, 'ticket_already_resolved', 'ticket already resolved');
-        }
-        throw new ApiError(500, 'internal', 'the ticket could not be canceled');
-    }
-}
-export const humanRoutes = [
-    { method: 'POST', pattern: '/v1/human/bridge', handler: handleCreateBridge },
-    { method: 'POST', pattern: '/v1/human/tickets/:ticket_id/resolve', handler: handleResolve },
-    { method: 'POST', pattern: '/v1/human/tickets/:ticket_id/cancel', handler: handleCancel },
-];
+// Human page and review lifecycle routes live on request identity. The former
+// bridge-creation and ticket resolve/cancel routes are intentionally absent.
+export const humanRoutes = [];

package/dist/daemon/api/handlers/inbox-page.d.ts

@@ -0,0 +1,4 @@
+import type { InboxPageDTO } from '../../../api/index.js';
+import { type HumanRequestRecord } from '../../../core/human/requests.js';
+/** Project the one SQL-selected page revision for every page reader. */
+export declare function inboxPageProjection(request: HumanRequestRecord): InboxPageDTO;

package/dist/daemon/api/handlers/inbox-page.js

@@ -0,0 +1,89 @@
+import { readFileSync } from 'node:fs';
+import { readPageFeedback } from '../../../core/human/feedback.js';
+import { pageModulePath, pagePath } from '../../../core/human/convention.js';
+import { parsePage } from '../../../core/human/page.js';
+import { presentationDir } from '../../../core/human/requests.js';
+import { readPageProgress, readTicketResult } from '../../../core/human/tickets.js';
+import { toPageFeedbackDTO } from '../map.js';
+function pageSlotToDTO(slot) {
+    const dto = {
+        kind: slot.kind,
+        step: slot.step,
+        config: slot.config,
+    };
+    if (slot.id !== undefined)
+        dto.id = slot.id;
+    if (slot.unvalidated === true)
+        dto.unvalidated = true;
+    if (slot.display === true)
+        dto.display = true;
+    return dto;
+}
+function pageManifestToDTO(manifest) {
+    const dto = {
+        schema: 'crtr.page/v2',
+        dialect: manifest.dialect,
+        title: manifest.title,
+        delivery: manifest.delivery,
+        document: manifest.document,
+        steps: manifest.steps,
+        slots: manifest.slots.map(pageSlotToDTO),
+    };
+    if (manifest.subtitle !== undefined)
+        dto.subtitle = manifest.subtitle;
+    if (manifest.source !== undefined) {
+        const source = {};
+        if (manifest.source.sessionName !== undefined)
+            source.sessionName = manifest.source.sessionName;
+        if (manifest.source.askedBy !== undefined)
+            source.askedBy = manifest.source.askedBy;
+        if (manifest.source.emittedAt !== undefined)
+            source.emittedAt = manifest.source.emittedAt;
+        if (manifest.source.profileName !== undefined)
+            source.profileName = manifest.source.profileName;
+        if (manifest.source.nodeId !== undefined)
+            source.nodeId = manifest.source.nodeId;
+        if (Object.keys(source).length > 0)
+            dto.source = source;
+    }
+    return dto;
+}
+function state(request) {
+    if (!request.settleable)
+        return 'passive';
+    if (request.state !== 'settled')
+        return 'pending';
+    return request.outcome === 'canceled' || request.outcome === 'dismissed' ? 'canceled' : 'resolved';
+}
+function result(request) {
+    const terminal = readTicketResult(request.request_dir);
+    if (terminal === null)
+        return null;
+    if (terminal.kind === 'page' || terminal.kind === 'canceled') {
+        return terminal;
+    }
+    throw new Error(`page request has an invalid terminal result: ${request.request_id}`);
+}
+/** Project the one SQL-selected page revision for every page reader. */
+export function inboxPageProjection(request) {
+    if (request.kind !== 'page')
+        throw new Error(`request is not a page: ${request.request_id}`);
+    const revision = presentationDir(request);
+    const manifest = parsePage(revision);
+    const sourceDocument = readFileSync(pagePath(revision, manifest.dialect), 'utf8');
+    const document = manifest.dialect === 'jsx' ? readFileSync(pageModulePath(revision), 'utf8') : sourceDocument;
+    const progress = request.settleable ? readPageProgress(request.request_dir) : null;
+    return {
+        ticket_id: request.inbox_ticket_id,
+        kind: 'page',
+        state: state(request),
+        revision,
+        page: pageManifestToDTO(manifest),
+        document,
+        source_document: sourceDocument,
+        document_media_type: manifest.dialect === 'jsx' ? 'text/jsx' : 'text/html',
+        progress: progress === null ? null : { responses: progress },
+        result: result(request),
+        feedback: toPageFeedbackDTO(readPageFeedback(request.request_dir)),
+    };
+}

package/dist/daemon/api/handlers/inbox.js

@@ -1,65 +1,22 @@
 // Ticket inbox handlers — crtrd `/v1/human/inbox` (Northlight crouter-inbox
 // v1, inbox-contract.md §A). This public ticket-serving resource enumerates,
 // reads, responds to, and cancels tickets while preserving its product DTOs.
-import { createHash } from 'node:crypto';
-import { existsSync, readdirSync, realpathSync, statSync } from 'node:fs';
-import { basename, resolve } from 'node:path';
 import { ApiError } from '../../../api/index.js';
-import { readPageFeedback } from '../../../core/human/feedback.js';
-import { toPageFeedbackDTO } from '../map.js';
-import { pageManifestPath, reviewPath } from '../../../core/human/convention.js';
+import { inboxPageProjection } from './inbox-page.js';
+import { getRequestByInboxTicket } from '../../../core/human/requests.js';
 import { parsePage } from '../../../core/human/page.js';
-import { ticketsRoot } from '../../../core/human/root.js';
 import { scanInbox, scanPageHistory } from '../../../core/human/scan.js';
-import { readPageTicket, readTicketResult, validatePageTicketResponses, writePageProgress, } from '../../../core/human/tickets.js';
+import { readPageTicket, readTicketResult, selectedPageDir, validatePageTicketResponses, writePageProgress, } from '../../../core/human/tickets.js';
 import { describePageAnswer } from '../../../core/human/answer.js';
 import { cancelHumanTicket, resolvePageTicket } from '../../human/finish.js';
-import { filterTerminalReviewTickets } from '../../../core/review/ticket-filter.js';
 const DEFAULT_CANCEL_REASON = 'Canceled from the inbox.';
 const CANCEL_REASON_MAX = 1000;
 const TICKET_ID_PATTERN = /^[a-f0-9]{64}$/;
-// Opaque ticket id resolution
-function ticketHash(canonicalRoot, ticketBasename) {
-    return createHash('sha256').update(`${canonicalRoot}\0${ticketBasename}`, 'utf8').digest('hex');
-}
 /** Resolve one opaque inbox ticket id to its canonical directory. Shared with
  * the feedback-comment routes, which address tickets by the same ids. */
 export function resolveTicket(ticketId) {
-    let canonicalRoot;
-    try {
-        canonicalRoot = realpathSync(ticketsRoot());
-    }
-    catch {
-        return null;
-    }
-    let entries;
-    try {
-        entries = readdirSync(canonicalRoot);
-    }
-    catch {
-        return null;
-    }
-    for (const entry of entries) {
-        if (ticketHash(canonicalRoot, entry) !== ticketId)
-            continue;
-        const candidate = resolve(canonicalRoot, entry);
-        let canonicalDir;
-        try {
-            if (!statSync(candidate).isDirectory())
-                continue;
-            canonicalDir = realpathSync(candidate);
-        }
-        catch {
-            continue;
-        }
-        if (resolve(canonicalDir, '..') !== canonicalRoot || basename(canonicalDir) !== entry)
-            continue;
-        if (existsSync(pageManifestPath(canonicalDir)))
-            return { ticketId: entry, dir: canonicalDir, kind: 'page' };
-        if (existsSync(reviewPath(canonicalDir)))
-            return { ticketId: entry, dir: canonicalDir, kind: 'review' };
-    }
-    return null;
+    const request = getRequestByInboxTicket(ticketId);
+    return request === null ? null : { ticketId: request.request_id, dir: request.request_dir, kind: request.kind };
 }
 export function requireTicketId(params) {
     const ticketId = params['ticket_id'];
@@ -69,49 +26,6 @@ export function requireTicketId(params) {
     return ticketId;
 }
 // Projections — humanloop canonical shapes → wire DTOs
-function pageSlotToDTO(slot) {
-    const dto = {
-        kind: slot.kind,
-        step: slot.step,
-        config: slot.config,
-    };
-    if (slot.id !== undefined)
-        dto.id = slot.id;
-    if (slot.unvalidated === true)
-        dto.unvalidated = true;
-    if (slot.display === true)
-        dto.display = true;
-    return dto;
-}
-function pageManifestToDTO(manifest) {
-    const dto = {
-        schema: 'crtr.page/v2',
-        dialect: manifest.dialect,
-        title: manifest.title,
-        delivery: manifest.delivery,
-        document: manifest.document,
-        steps: manifest.steps,
-        slots: manifest.slots.map(pageSlotToDTO),
-    };
-    if (manifest.subtitle !== undefined)
-        dto.subtitle = manifest.subtitle;
-    if (manifest.source !== undefined) {
-        const source = {};
-        if (manifest.source.sessionName !== undefined)
-            source.sessionName = manifest.source.sessionName;
-        if (manifest.source.askedBy !== undefined)
-            source.askedBy = manifest.source.askedBy;
-        if (manifest.source.emittedAt !== undefined)
-            source.emittedAt = manifest.source.emittedAt;
-        if (manifest.source.profileName !== undefined)
-            source.profileName = manifest.source.profileName;
-        if (manifest.source.nodeId !== undefined)
-            source.nodeId = manifest.source.nodeId;
-        if (Object.keys(source).length > 0)
-            dto.source = source;
-    }
-    return dto;
-}
 function isPlainObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -164,9 +78,11 @@ function isSlotValidationError(err) {
 }
 // GET /v1/human/inbox — enumerate
 /** The one page-summary projection: the pending list and the per-node history differ only in which tickets they walk. */
-function pageSummaryToDTO(item, canonicalRoot) {
+function pageSummaryToDTO(item) {
     const dto = {
-        ticket_id: createHash('sha256').update(`${canonicalRoot}\0${item.id}`, 'utf8').digest('hex'),
+        request_id: item.id,
+        request_dir: item.dir,
+        ticket_id: item.inboxTicketId,
         kind: 'page',
         title: item.title,
         placement: item.placement,
@@ -191,16 +107,15 @@ function pageSummaryToDTO(item, canonicalRoot) {
     return dto;
 }
 function handleList() {
-    const allItems = scanInbox();
-    const filtered = filterTerminalReviewTickets(allItems);
-    const canonicalRoot = realpathSync(ticketsRoot());
-    const tickets = filtered.map((item) => {
+    const tickets = scanInbox().map((item) => {
         if (item.kind === 'page') {
-            return pageSummaryToDTO(item, canonicalRoot);
+            return pageSummaryToDTO(item);
         }
         else if (item.kind === 'review') {
             return {
-                ticket_id: createHash('sha256').update(`${canonicalRoot}\0${item.id}`, 'utf8').digest('hex'),
+                request_id: item.id,
+                request_dir: item.dir,
+                ticket_id: item.inboxTicketId,
                 kind: 'review',
                 title: item.title,
                 subtitle: item.subtitle,
@@ -224,8 +139,7 @@ function handleHistory(ctx) {
         throw new ApiError(400, 'invalid_request', 'node_id must be nonempty when present');
     }
     const history = scanPageHistory(nodeId ?? undefined);
-    const canonicalRoot = realpathSync(ticketsRoot());
-    const tickets = history.map((item) => pageSummaryToDTO(item, canonicalRoot));
+    const tickets = history.map(pageSummaryToDTO);
     return { status: 200, body: { tickets } };
 }
 // GET /v1/human/inbox/:ticket_id — read a page ticket
@@ -237,28 +151,15 @@ function handleGetPage(ctx) {
     if (resolved.kind === 'review') {
         throw new ApiError(409, 'ticket_kind_unsupported', 'review tickets have no page read operation');
     }
-    let ticket;
+    const request = getRequestByInboxTicket(ticketId);
+    if (request === null || request.kind !== 'page')
+        throw new ApiError(404, 'ticket_not_found', 'no matching ticket');
     try {
-        ticket = readPageTicket(resolved.dir);
+        return { status: 200, body: inboxPageProjection(request) };
     }
-    catch (err) {
+    catch {
         throw new ApiError(500, 'internal', 'the ticket could not be read');
     }
-    const progress = ticket.progress;
-    const progressDTO = progress === null ? null : { responses: progress };
-    return {
-        status: 200,
-        body: {
-            ticket_id: ticketId,
-            kind: 'page',
-            state: ticket.state,
-            page: pageManifestToDTO(ticket.manifest),
-            document: ticket.manifest.dialect === 'jsx' ? ticket.module : ticket.document,
-            document_media_type: ticket.manifest.dialect === 'jsx' ? 'text/jsx' : 'text/html',
-            progress: progressDTO,
-            feedback: toPageFeedbackDTO(readPageFeedback(resolved.dir)),
-        },
-    };
 }
 // POST /v1/human/inbox/:ticket_id/respond — submit
 async function handleRespond(ctx) {
@@ -382,7 +283,7 @@ function handleGetResponse(ctx) {
         throw new ApiError(409, 'ticket_kind_mismatch', 'unexpected result kind');
     }
     try {
-        const manifest = parsePage(resolved.dir);
+        const manifest = parsePage(selectedPageDir(resolved.dir));
         return { status: 200, body: { ...result, answer: describePageAnswer(manifest, result.responses, { completedAt: result.completedAt }) } };
     }
     catch {

package/dist/daemon/api/handlers/messages.d.ts

@@ -1,2 +1,3 @@
 import type { RouteTable } from '../router.js';
+export declare const brokerMailRoutes: RouteTable;
 export declare const messageRoutes: RouteTable;

package/dist/daemon/api/handlers/messages.js

@@ -2,7 +2,9 @@
 // inbox message now (201) or fresh-revives with no inbox entry. `{id}` is the
 // target node.
 import { join } from 'node:path';
-import { appendInbox, cancelPendingHumanMessages } from '../../../core/feed/inbox.js';
+import { claimNodeMail, acknowledgeNodeMail } from '../../../core/canvas/deliveries.js';
+import { nodeMailEntry } from '../../../core/feed/inbox.js';
+import { enqueueNodeMail, cancelPendingNodeMail } from '../../../core/feed/messages.js';
 import { reviveNode } from '../../../core/runtime/revive.js';
 import { BrokerUnreachableError } from '../../../core/runtime/broker-request.js';
 import { isBrokerLive } from '../../../core/runtime/model-swap.js';
@@ -319,23 +321,25 @@ async function handleMessage(ctx) {
             const messageBody = hasBody
                 ? req.body
                 : 'A one-off structured-output request has been granted. Submit a result matching the requested schema with `crtr push result` before you stop; after it is accepted, continue normally.';
-            return appendInbox(id, {
-                from,
-                tier,
+            return enqueueNodeMail(id, {
+                senderNodeId: from,
+                urgency: tier,
+                wake: 1,
                 kind: 'message',
                 label: label(messageBody),
-                data: { body: messageBody, ...(hasSidecar ? { situational: true } : {}), ...cardData },
+                bodyJson: { body: messageBody, ...(hasSidecar ? { situational: true } : {}), ...cardData },
             });
         }
         // Context-only: a hidden wake marker excluded from the visible digest. Its
         // one-shot cards have no visible delivery to ride, so the watcher's context
         // channel carries them.
-        return appendInbox(id, {
-            from,
-            tier,
+        return enqueueNodeMail(id, {
+            senderNodeId: from,
+            urgency: tier,
+            wake: 1,
             kind: 'message',
             label: hasSidecar ? '(ambient context updated)' : '(context delivered)',
-            data: { ...(hasSidecar ? { situational: true } : {}), situationalOnly: true, ...cardData },
+            bodyJson: { ...(hasSidecar ? { situational: true } : {}), situationalOnly: true, ...cardData },
         });
     };
     // Deferred guard: a done/canceled/finalized target has no natural
@@ -364,14 +368,14 @@ async function handleMessage(ctx) {
     // Wake-capable durable mail wins the same park-completion boundary as a live
     // broker input. A completion that won before this append is handled by the
     // fresh row read below, which revives the now-parked node.
-    if (entry.tier !== 'deferred')
+    if (entry.urgency !== 'deferred')
         withCanvasWrite(() => recordPendingParkActivity(id));
     const current = getNode(id);
     if (current === null)
         throw notFound(`unknown node: ${id}`, { received: id });
     // Deferred mail normally waits for a natural cycle, but a frozen row already
     // owes a thaw; consume its deadline when that durable future wake arrives.
-    if (entry.tier !== 'deferred' || meta.frozen_at !== null)
+    if (meta.frozen_at !== null)
         cancelCronsOnWake(id);
     // A wake-capable entry for an active or idle target is admitted by the
     // lifecycle tick. Reopen delivery preserves this handler's synchronous wake
@@ -380,7 +384,7 @@ async function handleMessage(ctx) {
     let revived = false;
     let frozen = false;
     const needsSynchronousWake = req.reopen || current.lifecycle === 'terminal' || !wantsExecution(current);
-    if (needsSynchronousWake && entry.tier !== 'deferred' && !paused && !isBrokerLive(current)) {
+    if (needsSynchronousWake && entry.urgency !== 'deferred' && !paused && !isBrokerLive(current)) {
         try {
             // The entry is already durable, so a wake denied for capacity is only
             // delayed: the row freezes and the tick relaunches it — at which point
@@ -398,8 +402,8 @@ async function handleMessage(ctx) {
         delivered: true,
         revived,
         ...(frozen ? { not_revived_reason: 'capacity_frozen' } : {}),
-        delivered_at: entry.ts,
-        ...(entry.tier === tier ? {} : { delivered_tier: entry.tier }),
+        delivered_at: entry.createdAt,
+        ...(entry.urgency === tier ? {} : { delivered_tier: entry.urgency }),
         ...(req.delivery === 'interactive' ? { delivered_via: 'inbox' } : {}),
     };
     return { status: 201, body };
@@ -417,7 +421,7 @@ async function handleInterrupt(ctx) {
     // 1. Boot-window close: mark undelivered human-send inbox entries canceled so
     //    a send riding the durable path (dormant target / mid-revive fallback) is
     //    never injected after the Esc — the watcher skips canceled entries.
-    const canceled = cancelPendingHumanMessages(id);
+    const canceled = cancelPendingNodeMail(id, { senderNodeId: 'human', kind: 'message' });
     // 2. Abort whatever is live. The broker acks once processed; on its single
     //    frame loop that ack also implies every earlier-accepted deliver was
     //    already routed, so a just-started turn is caught, not missed.
@@ -442,6 +446,60 @@ async function handleInterrupt(ctx) {
     };
     return { status: 200, body };
 }
+function mailBody(ctx) {
+    if (typeof ctx.body !== 'object' || ctx.body === null || Array.isArray(ctx.body))
+        throw usage('mail requires an object body');
+    const body = ctx.body;
+    if (typeof body['execution_id'] !== 'string' || body['execution_id'].trim() === '')
+        throw usage('execution_id is required');
+    return body;
+}
+function handleMailClaim(ctx) {
+    const body = mailBody(ctx);
+    const channel = body['channel'];
+    if (channel !== 'wake' && channel !== 'passive')
+        throw usage('channel must be wake or passive');
+    const result = claimNodeMail(ctx.params['id'], body['execution_id'], channel);
+    const projected = {
+        action: result.action,
+        deliveries: result.deliveries.map((delivery) => ({
+            delivery_id: delivery.deliveryId,
+            attempts: delivery.attempts,
+            handoff: delivery.handoff,
+            entry: nodeMailEntry(delivery),
+        })),
+    };
+    return { status: 200, body: projected };
+}
+function handleMailAcknowledge(ctx) {
+    const body = mailBody(ctx);
+    if (!Array.isArray(body['deliveries']))
+        throw usage('deliveries must be an array');
+    const receipts = body['deliveries'].map((value) => {
+        if (typeof value !== 'object' || value === null || Array.isArray(value))
+            throw usage('each delivery must be an object');
+        const receipt = value;
+        if (typeof receipt['delivery_id'] !== 'string' || receipt['delivery_id'] === '')
+            throw usage('delivery_id is required');
+        if (!Number.isSafeInteger(receipt['attempts']) || receipt['attempts'] < 1)
+            throw usage('attempts must be a positive integer');
+        if (receipt['disposition'] !== 'acknowledged' && receipt['disposition'] !== 'released')
+            throw usage('disposition must be acknowledged or released');
+        return { delivery_id: receipt['delivery_id'], attempts: receipt['attempts'], disposition: receipt['disposition'] };
+    });
+    const result = acknowledgeNodeMail(ctx.params['id'], body['execution_id'], receipts.map((receipt) => ({
+        deliveryId: receipt.delivery_id, attempts: receipt.attempts, disposition: receipt.disposition,
+    })));
+    const projected = {
+        action: result.action,
+        results: result.results.map((result) => ({ delivery_id: result.deliveryId, outcome: result.outcome })),
+    };
+    return { status: 200, body: projected };
+}
+export const brokerMailRoutes = [
+    { method: 'POST', pattern: '/v1/nodes/:id/mail/claim', handler: handleMailClaim },
+    { method: 'POST', pattern: '/v1/nodes/:id/mail/acknowledge', handler: handleMailAcknowledge },
+];
 export const messageRoutes = [
     { method: 'POST', pattern: '/v1/nodes/:id/messages', handler: handleMessage },
     { method: 'POST', pattern: '/v1/nodes/:id/interrupt', handler: handleInterrupt },