@north-light/api 0.3.579 → 0.3.587

package/dist/core/fault-classifier.d.ts

@@ -0,0 +1,36 @@
+import type { ErrorClass, OperationId } from './events/types.js';
+import { type ProviderFailureDetails } from './provider-failure.js';
+export type FaultLink = 'pi→provider' | 'viewer↔broker' | 'relay↔broker' | 'viewer↔crtrd' | 'broker↔crtrd' | 'daemon→node' | 'crtr→pi';
+export type FaultKind = 'rate-limit' | 'overloaded' | 'connection' | 'auth' | 'protocol' | 'context-overflow' | 'other' | 'wedged' | 'model-not-found';
+export type FaultRetryDisposition = 'auto' | 'manual' | 'fatal';
+export type FaultRetryOwner = 'sdk' | 'daemon' | 'client';
+export interface FaultRetry {
+    disposition: FaultRetryDisposition;
+    by?: FaultRetryOwner;
+    attempt?: number;
+    max?: number;
+    nextAt?: string;
+}
+export interface FaultProviderError extends ProviderFailureDetails {
+    provider: string;
+    model: string;
+}
+export interface Fault {
+    link: FaultLink;
+    op: string;
+    kind: FaultKind;
+    retry: FaultRetry;
+    message: string;
+    since: string;
+    operation_id: OperationId;
+    anchorEntryId?: string;
+    providerError?: FaultProviderError;
+}
+export interface FaultClassification {
+    kind: FaultKind;
+    disposition: FaultRetryDisposition;
+}
+export declare function errorClassFromFault(fault: Pick<Fault, 'kind' | 'retry'>): ErrorClass;
+/** The daemon `llm` refusal code for a transient failure of the model behind it (the endpoint, its vendor, or the directory mint). */
+export declare const UPSTREAM_MODEL_UNAVAILABLE = "upstream_model_unavailable";
+export declare function classify(link: FaultLink, raw: unknown): FaultClassification;

package/dist/core/fault-classifier.js

@@ -0,0 +1,101 @@
+import { hasManagedProviderCoolingDiagnostic } from './runtime/managed-provider-cooling.js';
+import { recognizeProviderError } from './provider-error-recognition.js';
+import { extractProviderFailureDetails } from './provider-failure.js';
+import { isRecord } from '../shared/predicates.js';
+const errorClassByFaultKind = {
+    'rate-limit': 'rate_limit',
+    overloaded: 'overloaded',
+    connection: 'connection',
+    auth: 'auth',
+    protocol: 'protocol',
+    'context-overflow': 'context_overflow',
+    wedged: 'wedged',
+    'model-not-found': 'model_not_found',
+    other: 'unknown',
+};
+export function errorClassFromFault(fault) {
+    return {
+        class: errorClassByFaultKind[fault.kind],
+        retry_disposition: fault.retry.disposition,
+    };
+}
+function faultKindFromProviderSignal(signal) {
+    switch (signal.kind) {
+        case 'rate-limit': return 'rate-limit';
+        case 'auth': return 'auth';
+        case 'protocol': return 'protocol';
+        case 'context-overflow': return 'context-overflow';
+        case 'overloaded':
+        case 'overloaded-only':
+        case 'transient-http': return 'overloaded';
+        case 'connection':
+        case 'connection-only': return 'connection';
+        case 'socket':
+        case 'service-unavailable':
+        case 'other': return 'other';
+    }
+}
+function classifyDisposition(link, kind) {
+    if (kind === 'auth' || kind === 'protocol' || kind === 'context-overflow')
+        return 'fatal';
+    if (link === 'pi→provider') {
+        if (kind === 'connection' || kind === 'rate-limit' || kind === 'overloaded')
+            return 'auto';
+        return 'fatal';
+    }
+    return 'manual';
+}
+function rawText(raw) {
+    if (typeof raw === 'string')
+        return raw;
+    if (!isRecord(raw))
+        return '';
+    const candidates = [
+        raw['message'],
+        raw['errorMessage'],
+        raw['reason'],
+        raw['body'],
+        raw['statusText'],
+    ];
+    for (const candidate of candidates) {
+        if (typeof candidate === 'string' && candidate !== '')
+            return candidate;
+    }
+    const nested = raw['error'];
+    if (isRecord(nested)) {
+        const nestedMessage = nested['message'];
+        if (typeof nestedMessage === 'string' && nestedMessage !== '')
+            return nestedMessage;
+        const nestedReason = nested['reason'];
+        if (typeof nestedReason === 'string' && nestedReason !== '')
+            return nestedReason;
+    }
+    return '';
+}
+/** The daemon `llm` refusal code for a transient failure of the model behind it (the endpoint, its vendor, or the directory mint). */
+export const UPSTREAM_MODEL_UNAVAILABLE = 'upstream_model_unavailable';
+export function classify(link, raw) {
+    // This diagnostic is the stable machine carrier for an all-managed-pools
+    // cooldown. Do not make its retryability depend on explanatory error prose.
+    if (link === 'pi→provider' && hasManagedProviderCoolingDiagnostic(raw)) {
+        return { kind: 'rate-limit', disposition: 'auto' };
+    }
+    const value = isRecord(raw) ? raw : {};
+    const failure = extractProviderFailureDetails(raw);
+    const nested = failure?.causes ?? [];
+    // The daemon's `upstream_model_unavailable` is a connection fault whatever its message says (RT-LLM-65).
+    if (failure?.code === UPSTREAM_MODEL_UNAVAILABLE)
+        return { kind: 'connection', disposition: classifyDisposition(link, 'connection') };
+    const signal = recognizeProviderError({
+        code: value['code'] ?? failure?.code ?? nested.find((cause) => cause.code !== undefined)?.code,
+        errno: value['errno'] ?? failure?.errno ?? nested.find((cause) => cause.errno !== undefined)?.errno,
+        status: value['status'] ?? failure?.status,
+        wsCloseCode: value['code'],
+        wsCloseReason: value['reason'],
+        message: [rawText(raw), failure?.body, ...nested.flatMap((cause) => [cause.message, cause.body])]
+            .filter((part) => typeof part === 'string' && part !== '')
+            .join(' '),
+    });
+    const kind = faultKindFromProviderSignal(signal);
+    return { kind, disposition: classifyDisposition(link, kind) };
+}

package/dist/core/feed/feed.d.ts

@@ -0,0 +1,63 @@
+import type { InboxDisposition } from './inbox.js';
+export type PushKind = 'update' | 'urgent' | 'final';
+export type PushDeliveryTier = 'deferred' | 'normal' | 'urgent';
+export interface PushOpts {
+    kind: PushKind;
+    /** Update-only subscriber delivery urgency; report kind remains `kind`. */
+    deliveryTier?: PushDeliveryTier;
+    body: string;
+    from?: string;
+    /** Attribution snapshotted by the human-ticket settlement paths; absent means an ordinary report. */
+    disposition?: InboxDisposition;
+    /** Final only. The outcome the canonical final records; absent means `result`/`finalized`. */
+    outcome?: FinalOutcome;
+    /** Update only: this report answers a one-off structured-output request (`report.result`). */
+    result?: {
+        requestMessageId: string | null;
+    };
+}
+/** A declined structured result: the node finishes, but its latch records a failure. */
+export interface FinalOutcome {
+    /** Present only when the canonical final is a declined structured result. */
+    kind?: 'failure';
+    reason?: 'declined';
+    detailJson?: string | null;
+    /** Present only for `push result`; settlement and the canonical final share one transaction. */
+    structured?: {
+        requestId: string;
+        value?: unknown;
+        declined?: {
+            reason: string;
+            code: string;
+            retryable: boolean;
+        };
+        skipEffects?: boolean;
+    };
+}
+export interface PushResult {
+    /** `<nodeId>/reports/<name>` — the report document's ref. */
+    report: string;
+    reportId: string;
+    deliveredTo: string[];
+}
+export declare class StructuredRequestFinalizationError extends Error {
+    readonly state: string;
+    constructor(state: string);
+}
+export declare class FinalizationError extends Error {
+    readonly code: 'already_finalized' | 'finalization_forbidden' | 'unknown_node';
+    readonly report?: string | undefined;
+    constructor(code: 'already_finalized' | 'finalization_forbidden' | 'unknown_node', report?: string | undefined);
+}
+export declare function push(nodeId: string, opts: PushOpts): Promise<PushResult>;
+export declare function pushUpdate(nodeId: string, body: string, opts?: {
+    from?: string;
+    deliveryTier?: PushDeliveryTier;
+}): Promise<PushResult>;
+export declare function pushUrgent(nodeId: string, body: string, opts?: {
+    from?: string;
+}): Promise<PushResult>;
+export declare function pushFinal(nodeId: string, body: string, opts?: {
+    from?: string;
+    disposition?: InboxDisposition;
+}): Promise<PushResult>;

package/dist/core/feed/feed.js

@@ -0,0 +1,190 @@
+// Push engine for the canvas report spine: a push writes a report document under the node
+// and publishes `report.*` on the node in one transaction.
+import { cancelCronsOnWake, getNode } from '../canvas/index.js';
+import { runStructuredRequestEffects, settleStructuredRequestIn } from '../canvas/structured-requests.js';
+import { afterCommit, openDb, withCanvasWrite } from '../canvas/db.js';
+import { brokerRelayGeneration, recordBrokerRelease } from '../runtime/lifecycle.js';
+import { randomUUID } from 'node:crypto';
+import { composeNodeOutcomeDocument } from '../runtime/outcome-document.js';
+import { closeNode } from '../runtime/close.js';
+import { writeDocument } from '../graph/documents.js';
+import { asRuntimeWriter } from '../permissions/ceiling.js';
+import { publish } from '../graph/events.js';
+import { nodeObject } from '../graph/objects.js';
+import { readerForNode } from '../graph/reader.js';
+import { endMessageSubscriptions } from '../graph/watches.js';
+import { operationIdContext } from '../events/operation-id.js';
+export class StructuredRequestFinalizationError extends Error {
+    state;
+    constructor(state) {
+        super(state === 'expired' ? 'structured_request_expired' : 'structured_request_settled');
+        this.state = state;
+    }
+}
+export class FinalizationError extends Error {
+    code;
+    report;
+    constructor(code, report) {
+        super(code);
+        this.code = code;
+        this.report = report;
+    }
+}
+function compactTs(d) {
+    const pad = (n, w = 2) => String(n).padStart(w, '0');
+    return `${d.getUTCFullYear()}${pad(d.getUTCMonth() + 1)}${pad(d.getUTCDate())}T${pad(d.getUTCHours())}${pad(d.getUTCMinutes())}${pad(d.getUTCSeconds())}${pad(d.getUTCMilliseconds(), 3)}`;
+}
+function firstLine(text, maxLen = 80) {
+    const line = text.split('\n')[0] ?? '';
+    return line.length > maxLen ? `${line.slice(0, maxLen - 1)}…` : line;
+}
+/** The push's event, and for an update its chosen level: its delivery tier (deferred 3, normal 5,
+ *  urgent 7), the legacy urgent kind at 7. A final or a result publishes at its declared level. */
+function eventFor(opts) {
+    if (opts.kind === 'final')
+        return { event: 'report.final' };
+    if (opts.result !== undefined)
+        return { event: 'report.result' };
+    if (opts.kind === 'urgent')
+        return { event: 'report.update', level: 7 };
+    return { event: 'report.update', level: opts.deliveryTier === 'deferred' ? 3 : opts.deliveryTier === 'urgent' ? 7 : 5 };
+}
+/** Write the report document and publish its event, inside the caller's write transaction. */
+async function writeReport(db, nodeId, opts) {
+    const from = opts.from ?? nodeId;
+    const name = `reports/${compactTs(new Date())}-${randomUUID().slice(-8)}-${opts.kind}`;
+    const node = await nodeObject(db, nodeId);
+    const actor = await nodeObject(db, from);
+    const { object: doc } = await writeDocument(db, asRuntimeWriter(await readerForNode(db, from, async () => [])), {
+        owner: node, kind: 'report', name, preview: firstLine(opts.body) || opts.kind, privacy: 'public',
+    }, opts.body);
+    const ref = `${nodeId}/${name}`;
+    const { event, level } = eventFor(opts);
+    await publish(db, {
+        event, object: node, actor, ...(level === undefined ? {} : { level }), attrs: {}, pointer: doc.id,
+        messageBody: { kind: opts.kind, label: firstLine(opts.body), bodyRef: ref, ...(opts.disposition === undefined ? {} : { disposition: opts.disposition }) },
+    });
+    const deliveredTo = (await db.prepare(`SELECT d.destination_id FROM deliveries d JOIN messages m ON m.message_id = d.message_id
+    JOIN objects receiver ON receiver.id = d.destination_id
+    WHERE m.body_ref = ? AND receiver.type = 'node' ORDER BY d.destination_id`).all(ref)).map((r) => r.destination_id);
+    if (opts.kind === 'final')
+        await endMessageSubscriptions(db, node, 'final');
+    else if (opts.result?.requestMessageId)
+        await endMessageSubscriptions(db, node, { result: opts.result.requestMessageId });
+    return { name, ref, doc, createdAt: doc.created_at, deliveredTo };
+}
+/** Claim the one canonical final while holding SQLite's write lock: the report document, its
+ *  publish and the latch commit together or not at all. */
+async function commitCanonicalFinal(nodeId, opts) {
+    return withCanvasWrite(async (db) => {
+        const row = await db.prepare('SELECT status, final_report FROM nodes WHERE node_id = ?').get(nodeId);
+        if (row === undefined)
+            throw new FinalizationError('unknown_node');
+        const outcomeIn = opts.outcome;
+        let structured;
+        if (outcomeIn?.structured !== undefined) {
+            const settlement = await settleStructuredRequestIn(db, outcomeIn.structured.requestId, outcomeIn.structured.declined === undefined
+                ? { intended: 'completed', result: outcomeIn.structured.value }
+                : { intended: 'declined', declined: outcomeIn.structured.declined });
+            if (!settlement.changed || settlement.row === null || (settlement.row.state !== 'completed' && settlement.row.state !== 'declined')) {
+                return { written: undefined, ...(settlement.row === null ? {} : { structured: settlement.row }), structuredRefused: true };
+            }
+            structured = settlement.row;
+        }
+        else {
+            const pending = await db.prepareUncached("SELECT request_id FROM structured_requests WHERE node_id = ? AND state = 'pending'").get(nodeId);
+            if (pending !== undefined) {
+                const settlement = await settleStructuredRequestIn(db, pending.request_id, { intended: 'failed', failureReason: 'finalized' });
+                if (!settlement.changed || settlement.row === null || settlement.row.state !== 'failed') {
+                    return { written: undefined, ...(settlement.row === null ? {} : { structured: settlement.row }), structuredRefused: true };
+                }
+                structured = settlement.row;
+            }
+        }
+        if (row.final_report !== null)
+            throw new FinalizationError('already_finalized', `${nodeId}/${row.final_report}`);
+        if (row.status !== 'active' && row.status !== 'idle' && row.status !== 'done')
+            throw new FinalizationError('finalization_forbidden');
+        const written = await writeReport(db, nodeId, opts);
+        const node = await getNode(nodeId);
+        const recordsOutcome = node?.kind !== 'human';
+        const revision = (node?.outcome_revision ?? 0) + 1;
+        const outcomeKind = opts.outcome?.kind ?? 'result';
+        const outcomeReason = opts.outcome?.reason ?? 'finalized';
+        const outcomeDetailJson = opts.outcome?.detailJson ?? null;
+        const at = written.createdAt;
+        if (recordsOutcome) {
+            const document = node === null ? null : await composeNodeOutcomeDocument({
+                node: { ...node, status: 'done', intent: 'done', terminal_reason: outcomeReason },
+                outcome: { kind: outcomeKind, reason: outcomeReason, at, revision, detailJson: outcomeDetailJson },
+                finalReport: written.name,
+                ...(structured?.state === 'completed' ? { structuredResult: structured.result } : {}),
+            });
+            await db.prepare("UPDATE nodes SET status = 'done', intent = 'done', terminal_reason = ?, final_report = ?, finalized_at = ?, outcome_kind = ?, outcome_reason = ?, outcome_at = ?, outcome_revision = outcome_revision + 1, outcome_detail_json = ? WHERE node_id = ? AND final_report IS NULL").run(outcomeReason, written.name, at, outcomeKind, outcomeReason, at, outcomeDetailJson, nodeId);
+            if (document !== null)
+                await publish(db, { event: 'outcome', object: await nodeObject(db, nodeId), actor: null,
+                    attrs: { revision }, messageBody: document });
+        }
+        else {
+            await db.prepare("UPDATE nodes SET status = 'done', intent = 'done', terminal_reason = 'finalized', final_report = ?, finalized_at = ? WHERE node_id = ? AND final_report IS NULL").run(written.name, at, nodeId);
+        }
+        const relay = brokerRelayGeneration(nodeId);
+        afterCommit(() => recordBrokerRelease(nodeId, relay));
+        return { written, ...(structured === undefined ? {} : { structured }) };
+    });
+}
+async function pushWithContext(nodeId, opts) {
+    if (!nodeId)
+        throw new Error(`push: empty nodeId (kind=${opts.kind}) — a report must belong to a node`);
+    if (opts.kind === 'final' && opts.deliveryTier !== undefined)
+        throw new Error('push final does not accept a delivery tier');
+    if (opts.kind !== 'final' && opts.outcome !== undefined)
+        throw new Error('push outcome is final-only');
+    if (opts.kind !== 'update' && opts.result !== undefined)
+        throw new Error('a one-off result is an update report');
+    if (opts.kind === 'final') {
+        const final = await commitCanonicalFinal(nodeId, opts);
+        if (final.structuredRefused === true) {
+            if (final.structured !== undefined)
+                runStructuredRequestEffects(final.structured);
+            throw new StructuredRequestFinalizationError(final.structured?.state ?? 'failed');
+        }
+        if (final.structured !== undefined && opts.outcome?.structured?.skipEffects !== true)
+            runStructuredRequestEffects(final.structured);
+        const { written } = final;
+        // The finalization latch ends every wait this node was holding. It flips the
+        // row to done DIRECTLY (not through lifecycle's `finish` event), so the
+        // deadline cleanup must ride here too: an armed deadline outliving the final
+        // fires an urgent self-message at a finalized node, is refused, and its
+        // on-failure disposition spawns a spurious escalation agent. Only
+        // cancel-on-wake rows anchored here go; standing crons survive. Outside
+        // commitCanonicalFinal's transaction — it takes its own write boundary.
+        await cancelCronsOnWake(nodeId);
+        const node = await getNode(nodeId);
+        if (node?.run_id === nodeId) {
+            const children = await (await openDb()).prepare('SELECT node_id FROM nodes WHERE run_id = ? AND node_id != ? ORDER BY created DESC').all(nodeId, nodeId);
+            for (const child of children) {
+                const current = await getNode(child.node_id);
+                if (current && current.status !== 'done' && current.status !== 'canceled' && current.status !== 'dead')
+                    await closeNode(child.node_id, { preserveEmpty: true });
+            }
+        }
+        return { report: written.ref, reportId: written.doc.id, deliveredTo: written.deliveredTo };
+    }
+    const written = await withCanvasWrite(async (db) => await writeReport(db, nodeId, opts));
+    return { report: written.ref, reportId: written.doc.id, deliveredTo: written.deliveredTo };
+}
+export function push(nodeId, opts) {
+    return operationIdContext.current() === undefined
+        ? operationIdContext.fresh(() => pushWithContext(nodeId, opts))
+        : pushWithContext(nodeId, opts);
+}
+export async function pushUpdate(nodeId, body, opts) {
+    return push(nodeId, { kind: 'update', body, ...opts });
+}
+export async function pushUrgent(nodeId, body, opts) {
+    return push(nodeId, { kind: 'urgent', body, ...opts });
+}
+export async function pushFinal(nodeId, body, opts) {
+    return push(nodeId, { kind: 'final', body, ...opts });
+}

package/dist/core/feed/inbox.d.ts

@@ -0,0 +1,34 @@
+import type { OperationId } from '../events/types.js';
+import type { ClaimedNodeMail } from '../canvas/deliveries.js';
+export type InboxTier = 'critical' | 'urgent' | 'normal' | 'deferred';
+export type InboxKind = 'update' | 'urgent' | 'final' | 'message' | 'completed';
+export type InboxDisposition = 'human-answer' | 'human-canceled';
+export type InboxEntryId = string & {
+    readonly __inboxEntryId: unique symbol;
+};
+/** The rendering projection of one immutable SQL message and its delivery. */
+export interface InboxEntry {
+    entry_id: InboxEntryId;
+    operation_id: OperationId;
+    ts: string;
+    from: string | null;
+    from_name?: string;
+    tier: InboxTier;
+    kind: InboxKind;
+    ref?: string;
+    label: string;
+    data?: Record<string, unknown>;
+    disposition?: InboxDisposition;
+}
+/** Project the immutable message body and destination-specific urgency into the canonical inbox rendering shape. */
+export declare function nodeMailEntry(delivery: ClaimedNodeMail): InboxEntry;
+/** The newest head body of the report document a message points at, or null when the entry
+ *  is not a report or the document is gone. */
+export declare function reportDocumentBody(objectId: string): Promise<string | null>;
+export interface InboxDelivery {
+    kind: 'human' | 'card';
+    text: string;
+    entries: readonly InboxEntry[];
+}
+/** Split delivered entries into verbatim human messages and sender-grouped inbox cards. */
+export declare function coalesce(entries: readonly InboxEntry[]): Promise<readonly InboxDelivery[]>;

package/dist/core/feed/inbox.js

@@ -0,0 +1,93 @@
+import { openDb } from '../canvas/db.js';
+import { heads } from '../graph/documents.js';
+import { getById } from '../graph/objects.js';
+import { get as getBody } from '../graph/bodies.js';
+import { validateOperationId } from '../events/operation-id.js';
+import { formatInboxCard, machineOfEntries } from '../../shared/generated-context.js';
+import { inlineBody, renderEntryBody, reportRefNodeId } from '../../shared/inbox-entry-body.js';
+import { mapAsync } from '../async-array.js';
+const INBOX_ENTRY_ID = /^(?!0{32}$)[0-9a-f]{32}$/;
+function validateInboxEntryId(value) {
+    if (typeof value !== 'string' || !INBOX_ENTRY_ID.test(value))
+        throw new TypeError('entry_id must be 32 lowercase non-zero hexadecimal characters');
+    return value;
+}
+/** Project the immutable message body and destination-specific urgency into the canonical inbox rendering shape. */
+export function nodeMailEntry(delivery) {
+    const message = delivery.message;
+    return {
+        entry_id: validateInboxEntryId(message.messageId),
+        operation_id: validateOperationId(message.operationId),
+        ts: message.createdAt,
+        from: message.senderNodeId,
+        ...(message.senderName === null ? {} : { from_name: message.senderName }),
+        tier: delivery.urgency,
+        kind: message.kind,
+        ...(message.bodyRef === null ? {} : { ref: message.bodyRef }),
+        label: message.label,
+        ...(message.bodyJson === null ? {} : { data: message.bodyJson }),
+        ...(message.disposition === null ? {} : { disposition: message.disposition }),
+    };
+}
+/** The newest head body of the report document a message points at, or null when the entry
+ *  is not a report or the document is gone. */
+export async function reportDocumentBody(objectId) {
+    const db = await openDb();
+    const doc = await getById(db, objectId);
+    if (doc === null || doc.type !== 'document' || doc.deleted_at !== null)
+        return null;
+    const head = (await heads(db, doc))[0];
+    if (head === undefined)
+        return null;
+    return await getBody(db, head.body_hash);
+}
+async function entryBody(entry) {
+    const objectId = entry.data?.['push']?.object?.id;
+    const report = reportRefNodeId(entry.ref) !== undefined && objectId !== undefined ? await reportDocumentBody(objectId) : null;
+    return renderEntryBody(entry, report);
+}
+async function cardEntry(entry) {
+    return {
+        kind: entry.kind,
+        body: await entryBody(entry),
+        ...(entry.ref === undefined ? {} : { ref: entry.ref }),
+        ...(entry.disposition === undefined ? {} : { disposition: entry.disposition }),
+    };
+}
+/** Split delivered entries into verbatim human messages and sender-grouped inbox cards. */
+export async function coalesce(entries) {
+    if (entries.length === 0)
+        return [];
+    const groups = new Map();
+    for (const entry of entries) {
+        const sender = entry.from ?? 'system';
+        if (!groups.has(sender))
+            groups.set(sender, []);
+        groups.get(sender).push(entry);
+    }
+    const deliveries = [];
+    const sections = [];
+    let cardSlot = -1;
+    for (const [sender, items] of groups) {
+        if (sender === 'human') {
+            for (const entry of items) {
+                const body = inlineBody(entry);
+                deliveries.push({ kind: 'human', text: body === '' ? entry.label : body, entries: [entry] });
+            }
+            continue;
+        }
+        if (cardSlot < 0) {
+            cardSlot = deliveries.length;
+            deliveries.push({ kind: 'card', text: '', entries: [] });
+        }
+        sections.push({ id: sender, ...machineOfEntries(items), entries: (await mapAsync(items, cardEntry)) });
+    }
+    if (cardSlot >= 0) {
+        deliveries[cardSlot] = {
+            kind: 'card',
+            text: formatInboxCard(sections),
+            entries: entries.filter((entry) => (entry.from ?? 'system') !== 'human'),
+        };
+    }
+    return deliveries;
+}

package/dist/core/feed/messages.d.ts

@@ -0,0 +1,88 @@
+import { type CanvasDb } from '../canvas/db.js';
+import type { OperationId } from '../events/types.js';
+import type { Level, ListenDelivery } from '../graph/types.js';
+import { type InboxDisposition, type InboxKind, type InboxTier } from './inbox.js';
+export type { InboxDisposition, InboxKind, InboxTier } from './inbox.js';
+export interface NodeMailInput {
+    kind: InboxKind;
+    label: string;
+    senderNodeId?: string | null;
+    senderName?: string | null;
+    bodyRef?: string | null;
+    bodyJson?: unknown;
+    disposition?: InboxDisposition | null;
+    urgency: InboxTier;
+    wake: 0 | 1;
+    operationId?: string;
+    /** Caller-chosen message id, so a request can know its id before the insert. */
+    messageId?: string;
+    /** Optional caller-owned obligation identity, used by cron settlement replay. */
+    idempotencyKey?: string;
+    /** Runs with the mail insert, before the transaction commits. */
+    withinEnqueue?: (db: CanvasDb, messageId: string) => Promise<void>;
+}
+export interface EnqueuedNodeMail {
+    messageId: string;
+    deliveryId: string;
+    urgency: InboxTier;
+    createdAt: string;
+}
+export declare function newId(): string;
+/** A terminal-lifecycle destination's normal or deferred mail is raised to urgent. */
+export declare function effectiveTier(nodeId: string, urgency: InboxTier): Promise<InboxTier>;
+export declare function insertMessage(db: CanvasDb, input: {
+    messageId?: string;
+    operationId: OperationId;
+    createdAt: string;
+    senderNodeId: string | null;
+    senderName: string | null;
+    kind: InboxKind;
+    label: string;
+    bodyRef: string | null;
+    bodyJson: unknown | undefined;
+    disposition: InboxDisposition | null;
+    event?: {
+        event: string;
+        objectId: string;
+        level: Level;
+        actorId: string | null;
+    };
+    causeMessageId?: string | null;
+    depth?: number;
+}): Promise<string>;
+/** The message's creation time, operation id and body — an oversized inline body is clipped
+ *  into `destinationNodeId`'s messages dir and referenced; with no destination it stays inline. */
+export declare function finalizeNodeMail(input: Omit<NodeMailInput, 'wake'>, destinationNodeId: string | null): {
+    createdAt: string;
+    operationId: OperationId;
+    bodyRef: string | null;
+    bodyJson: unknown | undefined;
+};
+/** Insert one immutable message and one node-inbox obligation into the caller's write transaction. */
+export declare function enqueueNodeMail(destinationNodeId: string, input: NodeMailInput): Promise<EnqueuedNodeMail>;
+/** Contract §1: a listening delivery maps 1:1 onto an inbox tier; only `next-turn` does not wake. */
+export declare function listenDeliveryTier(delivery: ListenDelivery): {
+    urgency: InboxTier;
+    wake: 0 | 1;
+};
+/** A wake reached `nodeId`: delete its cancel-on-wake deadline and, in the same write, queue a
+ *  notice naming each deleted deadline so the node knows its timer is gone. The notice is inserted
+ *  directly rather than through `queueNodeNotice`, so it cancels nothing and a deadline the node
+ *  arms afterwards survives it. A deadline that fires on its own deletes its row first, so finds
+ *  nothing here and no notice is queued. */
+export declare function consumeDeadlineOnWake(nodeId: string): Promise<void>;
+/** Queue one runtime notice to a node's inbox inside the caller's write transaction (no sender). */
+export declare function queueNodeNotice(db: CanvasDb, nodeId: string, notice: {
+    body: string;
+    label?: string;
+    tier: InboxTier;
+    wake: 0 | 1;
+}): Promise<EnqueuedNodeMail>;
+/** Retract an obligation without fabricating a terminal receipt. */
+export declare function cancelDelivery(deliveryId: string, now?: number): Promise<boolean>;
+export declare function cancelPendingNodeMail(nodeId: string, select?: {
+    senderNodeId?: string | null;
+    kind?: InboxKind;
+}): Promise<string[]>;
+/** Enqueue the one notice only if the same live controller wait is still dead. */
+export declare function enqueueControllerDeathNotice(nodeId: string, controllerId: string): Promise<EnqueuedNodeMail | null>;