@north-light/crouter 0.3.312 → 0.3.313

package/dist/core/feed/inbox.js

@@ -1,23 +1,5 @@
-// Per-node inbox.jsonl primitive for the pi-native canvas runtime.
-//
-// An inbox entry is a lightweight pointer for a push (~30 tokens, body lives
-// in nodes/<id>/reports/) or carries a direct message inline. A direct
-// message short enough to inline stays entirely in the jsonl line; one that
-// would clip spills its full body to nodes/<id>/messages/ and the entry
-// carries `ref` to it alongside a bounded inline preview.
-//
-// Layout:
-//   nodes/<id>/inbox.jsonl          — one JSON line per entry, append-only
-//   nodes/<id>/inbox.jsonl.cursor   — exact identity of the last successfully
-//                                      settled/covered entry (sidecar), distinct from the in-memory read position
-import { appendFileSync, existsSync, readFileSync, writeFileSync, renameSync, mkdirSync, } from 'node:fs';
-import { dirname, join } from 'node:path';
-import { randomBytes, randomUUID } from 'node:crypto';
-import { deliverAndSettleMessageWait, getRow, inboxPath, messagesDir, settleDeadMessageWait } from '../canvas/index.js';
 import { resolveRef } from '../canvas/history.js';
-import { emitEvent } from '../events/emit.js';
-import { errorClassFromError } from '../events/errors.js';
-import { generateOperationId, operationIdContext, validateOperationId } from '../events/operation-id.js';
+import { validateOperationId } from '../events/operation-id.js';
 import { formatInboxCard, formatInboxRefInstruction } from '../../shared/generated-context.js';
 import { renderBirthAnnouncementBody } from '../../shared/birth-announcement.js';
 const INBOX_ENTRY_ID = /^(?!0{32}$)[0-9a-f]{32}$/;
@@ -26,321 +8,27 @@ function validateInboxEntryId(value) {
         throw new TypeError('entry_id must be 32 lowercase non-zero hexadecimal characters');
     return value;
 }
-function generateInboxEntryId() {
-    let value;
-    do
-        value = randomBytes(16).toString('hex');
-    while (value === '00000000000000000000000000000000');
-    return validateInboxEntryId(value);
-}
-/** Complete an entry exactly once before any spill or append work. */
-export function finalizeInboxEntry(input) {
-    const operationId = input.operation_id === undefined
-        ? operationIdContext.current() ?? generateOperationId()
-        : validateOperationId(input.operation_id);
+/** Project the immutable message body and destination-specific urgency into the canonical inbox rendering shape. */
+export function nodeMailEntry(delivery) {
+    const message = delivery.message;
     return {
-        ...input,
-        entry_id: generateInboxEntryId(),
-        operation_id: operationId,
-        ts: new Date().toISOString(),
+        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 }),
     };
 }
-// Cursor sidecar path
-function cursorPath(nodeId) {
-    return `${inboxPath(nodeId)}.cursor`;
-}
-// Append
-/** Spill an oversized inline body to a durable file — the SAME atomic
- *  tmp+rename pattern a push report uses — and return its absolute path.
- *  Called only when the body would clip in the digest; short bodies never
- *  touch disk beyond the jsonl line itself. */
-function writeMessageBody(nodeId, ts, body) {
-    const dir = messagesDir(nodeId);
-    if (!existsSync(dir))
-        mkdirSync(dir, { recursive: true });
-    const stamp = ts.replace(/[^0-9]/g, '');
-    const finalPath = join(dir, `${stamp}-${randomUUID().slice(0, 6)}.md`);
-    const tmpPath = `${finalPath}.tmp`;
-    writeFileSync(tmpPath, body, 'utf8');
-    renameSync(tmpPath, finalPath);
-    return finalPath;
-}
-/** The tier a live watcher injects into the turn a node is ALREADY running
- *  (`visibleRoute`, canvas-inbox-watcher). `normal` and `deferred` both wait
- *  for a later cycle instead. */
-const STEERING_TIER = 'urgent';
-/** The tier an entry is actually appended at. A terminal node owes one final
- *  result and reaps on it, so the later cycle `normal` and `deferred` wait for
- *  is one it may never take — mail handed to such a node is raised to the
- *  steering tier so the turn it is running now carries it, and so a dormant one
- *  is woken for it rather than holding it forever. */
-function effectiveTier(nodeId, tier) {
-    if (tier !== 'normal' && tier !== 'deferred')
-        return tier;
-    return getRow(nodeId)?.lifecycle === 'terminal' ? STEERING_TIER : tier;
-}
-/** Atomically append one finalized inbox entry to `nodes/<nodeId>/inbox.jsonl`,
- *  at the tier `effectiveTier` resolves for this target. */
-export function appendInbox(nodeId, entry) {
-    const full = finalizeInboxEntry({ ...entry, tier: effectiveTier(nodeId, entry.tier) });
-    try {
-        // A push pointer already carries its canonical history `ref` — its body
-        // lives in the report file, never inline. A direct message / system notice has no ref yet: when
-        // its inline body would clip in the digest, spill the FULL text to a durable
-        // file (same atomic tmp+rename as a report) and point `ref` at it, exactly
-        // like a push, then keep only the bounded preview inline. A short body is
-        // left fully inline, untouched — uniform with how a push's body always
-        // lives in a file, never inline, dereferenced by reading `ref`.
-        if (full.ref === undefined) {
-            const body = inlineBody(full);
-            const { text, clipped } = clipBody(body);
-            if (clipped) {
-                full.ref = writeMessageBody(nodeId, full.ts, body);
-                full.data = { ...full.data, body: text };
-            }
-        }
-        const line = JSON.stringify(full) + '\n';
-        // Ensure the parent directory exists (inbox.jsonl lives directly under the
-        // node dir, which ensureNodeDirs creates — but guard anyway for callers that
-        // haven't yet scaffolded the node).
-        const dir = dirname(inboxPath(nodeId));
-        if (!existsSync(dir))
-            mkdirSync(dir, { recursive: true });
-        // The append and matching wait settlement share SQLite's write boundary.
-        // A re-arm therefore cannot land between this delivery and its clear.
-        return deliverAndSettleMessageWait(nodeId, entry.from, () => {
-            // appendFileSync is atomic within a single process (a single write(2) call for
-            // a short line is atomic on POSIX). For multi-process safety we rely on the
-            // OS-level append guarantee (O_APPEND) which Node honours via 'a' flag.
-            appendFileSync(inboxPath(nodeId), line, { encoding: 'utf8', flag: 'a' });
-            return full;
-        });
-    }
-    catch (error) {
-        emitActiveAppendFailure(nodeId, full, error);
-        throw error;
-    }
-}
-function emitActiveAppendFailure(nodeId, entry, error) {
-    try {
-        emitEvent({
-            level: 'error',
-            event: 'inbox.delivery.failed',
-            operation_id: entry.operation_id,
-            outcome: 'failed',
-            error,
-            error_class: errorClassFromError(error),
-            fields: { stage: 'append', channel: 'active', target_node_id: nodeId },
-        });
-    }
-    catch {
-        // Event emission is observational; the original append failure remains authoritative.
-    }
-}
-/** Deliver the one system notice for a controller that can no longer satisfy a
- * wait. Returns null when another durable operation already settled or re-armed
- * that wait. */
-export function appendControllerDeathNotice(nodeId, controller) {
-    const full = finalizeInboxEntry({
-        from: null,
-        tier: 'urgent',
-        kind: 'urgent',
-        label: 'declared controller is no longer live',
-        data: { body: `Controller ${controller} is no longer live; the declared message wait was cleared.` },
-    });
-    try {
-        const line = JSON.stringify(full) + '\n';
-        const dir = dirname(inboxPath(nodeId));
-        if (!existsSync(dir))
-            mkdirSync(dir, { recursive: true });
-        return settleDeadMessageWait(nodeId, controller, () => {
-            appendFileSync(inboxPath(nodeId), line, { encoding: 'utf8', flag: 'a' });
-            return full;
-        });
-    }
-    catch (error) {
-        emitActiveAppendFailure(nodeId, full, error);
-        throw error;
-    }
-}
-// Read
-function readPhysicalInbox(nodeId) {
-    const p = inboxPath(nodeId);
-    if (!existsSync(p))
-        return [];
-    const raw = readFileSync(p, 'utf8');
-    if (raw === '')
-        return [];
-    const lines = raw.split('\n');
-    if (lines.at(-1) === '')
-        lines.pop();
-    if (lines.some((line) => line.trim() === ''))
-        throw new Error('inbox contains a blank physical line');
-    const entries = lines.map((line) => {
-        const entry = JSON.parse(line);
-        entry.entry_id = validateInboxEntryId(entry.entry_id);
-        entry.operation_id = validateOperationId(entry.operation_id);
-        return entry;
-    });
-    const seen = new Set();
-    for (const entry of entries) {
-        if (seen.has(entry.entry_id))
-            throw new Error(`duplicate inbox entry_id: ${entry.entry_id}`);
-        seen.add(entry.entry_id);
-    }
-    return entries;
-}
-function cursorIndex(entries, rawCursor) {
-    const cursor = validateInboxEntryId(rawCursor);
-    return entries.findIndex((entry) => entry.entry_id === cursor);
-}
-/** Return the physical suffix strictly after the exact cursor identity. */
-export function readInboxSince(nodeId, cursorEntryId) {
-    const entries = readPhysicalInbox(nodeId);
-    if (cursorEntryId === undefined)
-        return entries;
-    const index = cursorIndex(entries, cursorEntryId);
-    if (index < 0) {
-        throw new Error(`inbox cursor entry_id not found: ${validateInboxEntryId(cursorEntryId)}`);
-    }
-    return entries.slice(index + 1);
-}
-/** Read one exact contiguous physical range after an exclusive boundary through an inclusive boundary. */
-export function readInboxRange(nodeId, afterEntryId, throughEntryId) {
-    const after = afterEntryId === undefined ? undefined : validateInboxEntryId(afterEntryId);
-    const through = validateInboxEntryId(throughEntryId);
-    const entries = readPhysicalInbox(nodeId);
-    const throughIndex = entries.findIndex((entry) => entry.entry_id === through);
-    if (throughIndex < 0)
-        throw new Error(`inbox range through entry_id not found: ${through}`);
-    if (after === undefined)
-        return entries.slice(0, throughIndex + 1);
-    const afterIndex = entries.findIndex((entry) => entry.entry_id === after);
-    if (afterIndex < 0)
-        throw new Error(`inbox range after entry_id not found: ${after}`);
-    if (afterIndex >= throughIndex)
-        throw new Error(`inbox range is reversed: ${after} through ${through}`);
-    return entries.slice(afterIndex + 1, throughIndex + 1);
-}
-// Cancel set (interrupt-canceled entries)
-function canceledPath(nodeId) {
-    return `${inboxPath(nodeId)}.canceled`;
-}
-/** Entry ids a human interrupt canceled before delivery. Append-only sidecar
- *  (the inbox itself is append-only — never mutated in place): one entry_id
- *  per line. The watcher skips canceled entries at plan time; a missing file
- *  is an empty set. */
-export function readCanceledEntryIds(nodeId) {
-    const p = canceledPath(nodeId);
-    if (!existsSync(p))
-        return new Set();
-    const out = new Set();
-    for (const line of readFileSync(p, 'utf8').split('\n')) {
-        const trimmed = line.trim();
-        if (trimmed === '')
-            continue;
-        out.add(validateInboxEntryId(trimmed));
-    }
-    return out;
-}
-/** Mark every not-yet-settled HUMAN message entry canceled — the boot-window
- *  half of a first-class interrupt (`POST /v1/nodes/{id}/interrupt`): a send
- *  that rode the durable inbox (dormant target, or the mid-revive fallback)
- *  must not be injected after the human pressed Esc. Scope: `from === 'human'`
- *  `kind: 'message'` entries ONLY — a human Esc never cancels spine/agent
- *  messages or system notices. Entries past the durable cursor that a live
- *  watcher already handed to the engine may be over-canceled; that is safe —
- *  the interrupt's abort lands right behind, and covered handoffs are never
- *  re-delivered anyway. Returns the newly canceled entry ids. */
-export function cancelPendingHumanMessages(nodeId) {
-    return cancelPendingEntries(nodeId, (e) => e.from === 'human' && e.kind === 'message');
-}
-/** Cancel every not-yet-settled entry the predicate selects. Retraction, not
- *  deletion: the append-only inbox is untouched and the sidecar grows. Safe to
- *  call late — an entry already past the cursor is not pending, and the watcher
- *  re-reads the set at plan time so a cancel racing a buffered entry still
- *  lands. */
-export function cancelPendingEntries(nodeId, select) {
-    const cursor = readCursor(nodeId);
-    const pending = readInboxSince(nodeId, cursor);
-    const already = readCanceledEntryIds(nodeId);
-    const targets = pending
-        .filter((e) => !already.has(e.entry_id) && select(e))
-        .map((e) => e.entry_id);
-    if (targets.length === 0)
-        return [];
-    const dir = dirname(inboxPath(nodeId));
-    if (!existsSync(dir))
-        mkdirSync(dir, { recursive: true });
-    appendFileSync(canceledPath(nodeId), targets.join('\n') + '\n', { encoding: 'utf8', flag: 'a' });
-    return targets;
-}
-// Cursor persistence
-/** Read and validate the persisted exact cursor identity. */
-export function readCursor(nodeId) {
-    const p = cursorPath(nodeId);
-    if (!existsSync(p))
-        return undefined;
-    const raw = readFileSync(p, 'utf8').trim();
-    if (raw === '')
-        return undefined;
-    return validateInboxEntryId(raw);
-}
-/** Persist one validated exact cursor identity (atomic tmp+rename). */
-export function writeCursor(nodeId, entryId) {
-    const value = validateInboxEntryId(entryId);
-    const p = cursorPath(nodeId);
-    const tmp = `${p}.tmp`;
-    const dir = dirname(p);
-    if (!existsSync(dir))
-        mkdirSync(dir, { recursive: true });
-    writeFileSync(tmp, value, 'utf8');
-    renameSync(tmp, p);
-}
-/** Is there mail this node has not seen that would drive a turn? The one
- *  authority for "wake-worthy inbox state", read by the park clock, the
- *  settlement policy, the review-companion guard, and reviveNode's parked
- *  re-entry rule. Deferred entries are excluded everywhere for the same
- *  reason: a deferred entry rides the next natural cycle and never starts one.
- *  A cursor that no longer resolves against the physical inbox is a fault, not
- *  an answer — every caller's conservative reading of this predicate is `true`
- *  (do not park, do not shut down, do not resume quietly), so report it and
- *  return that. */
-export function hasUnseenWakeMail(nodeId) {
-    try {
-        return readInboxSince(nodeId, readCursor(nodeId)).some((entry) => entry.tier !== 'deferred');
-    }
-    catch (error) {
-        emitEvent({ level: 'warn', event: 'inbox.wake_scan.failed', node_id: nodeId, error });
-        return true;
-    }
-}
-/** Whether wake-capable mail arrived at or after a parking turn began. Unlike
- * `hasUnseenWakeMail`, this deliberately includes mail the main engine already
- * consumed: a shadow completion must not undo activity that occurred while it
- * ran. A failed scan conservatively keeps the node live. */
-export function hasWakeMailSince(nodeId, sinceMs) {
-    try {
-        return readPhysicalInbox(nodeId).some((entry) => entry.tier !== 'deferred' && Date.parse(entry.ts) >= sinceMs);
-    }
-    catch (error) {
-        emitEvent({ level: 'warn', event: 'inbox.wake_scan.failed', node_id: nodeId, error });
-        return true;
-    }
-}
-// Coalesce
-/** Bounds for inlining a message body's preview in the digest. */
 const BODY_MAX_LINES = 12;
 const BODY_MAX_CHARS = 1000;
 const INLINE_REPORT_MAX_CHARS = 1000;
-/** The inline body an entry carries (a direct msg / system alert), trimmed.
- *  Empty for a push pointer (whose body lives at `ref`) or a one-line entry
- *  whose `label` already IS the whole message. */
-function inlineBody(e) {
-    const body = typeof e.data?.['body'] === 'string' ? e.data['body'].trim() : '';
-    return body === '' || body === e.label ? '' : body;
-}
-/** Clip a body to a bounded preview, reporting whether anything was dropped. */
+/** Clip a body to the bounded preview stored beside a spilled message body. */
 export function clipBody(body) {
     let text = body;
     let clipped = false;
@@ -355,83 +43,65 @@ export function clipBody(body) {
     }
     return { text: text.trimEnd(), clipped };
 }
-/** Resolve a short pushed report body for inlining. Larger reports stay
- * pointers, carried by the entry's `ref` attribute alone. */
-function inlineReport(e) {
-    if (e.ref === undefined || e.ref.startsWith('/'))
+function inlineBody(entry) {
+    const body = typeof entry.data?.['body'] === 'string' ? entry.data['body'].trim() : '';
+    return body === '' || body === entry.label ? '' : body;
+}
+function inlineReport(entry) {
+    if (entry.ref === undefined || entry.ref.startsWith('/'))
         return null;
     try {
-        const report = resolveRef(e.ref);
+        const report = resolveRef(entry.ref);
         if (report?.source !== 'report' || report.path === null || report.body.length >= INLINE_REPORT_MAX_CHARS)
             return null;
         return report.body;
     }
     catch {
-        // A malformed or unavailable history ref remains a pointer in the digest.
         return null;
     }
 }
-/**
- * One entry's card body.
- *
- * A short pushed report is inlined as its own body; the label is NOT repeated
- * above it, because a report's label is just its first line (feed.ts
- * `firstLine`), so carrying both reads as a truncated preview stacked on the
- * full text it previews. A larger report has only its label, with `ref`
- * carrying the pointer. Direct messages keep their bounded inline-body/spill
- * behavior.
- */
-function entryBody(e) {
-    const birth = renderBirthAnnouncementBody(e.data, e.ts);
+function entryBody(entry) {
+    const birth = renderBirthAnnouncementBody(entry.data, entry.ts);
     if (birth !== null)
         return birth;
-    const report = inlineReport(e);
+    const report = inlineReport(entry);
     if (report !== null)
-        return `${report.trimEnd()}\n\n${formatInboxRefInstruction(e.ref)}`;
-    const body = inlineBody(e);
+        return `${report.trimEnd()}\n\n${formatInboxRefInstruction(entry.ref)}`;
+    const body = inlineBody(entry);
     if (body === '')
-        return e.ref === undefined ? e.label : `${e.label}\n\n${formatInboxRefInstruction(e.ref)}`;
+        return entry.ref === undefined ? entry.label : `${entry.label}\n\n${formatInboxRefInstruction(entry.ref)}`;
     const { text, clipped } = clipBody(body);
-    if (e.ref !== undefined)
-        return `${text}\n\n${formatInboxRefInstruction(e.ref)}`;
+    if (entry.ref !== undefined)
+        return `${text}\n\n${formatInboxRefInstruction(entry.ref)}`;
     return clipped ? `${text}\n… (body clipped)` : text;
 }
-function cardEntry(e) {
+function cardEntry(entry) {
     return {
-        kind: e.kind,
-        body: entryBody(e),
-        ...(e.ref === undefined ? {} : { ref: e.ref }),
-        ...(e.disposition === undefined ? {} : { disposition: e.disposition }),
+        kind: entry.kind,
+        body: entryBody(entry),
+        ...(entry.ref === undefined ? {} : { ref: entry.ref }),
+        ...(entry.disposition === undefined ? {} : { disposition: entry.disposition }),
     };
 }
-/** Split unread inbox pointers into ordered deliveries: each human entry
- *  verbatim, and every other sender in one `<runtime kind="inbox">` card. */
+/** Split delivered entries into verbatim human messages and sender-grouped inbox cards. */
 export function coalesce(entries) {
     if (entries.length === 0)
         return [];
-    // Group by `from` (null → 'system').
     const groups = new Map();
-    for (const e of entries) {
-        const key = e.from ?? 'system';
-        if (!groups.has(key))
-            groups.set(key, []);
-        groups.get(key).push(e);
+    for (const entry of entries) {
+        const sender = entry.from ?? 'system';
+        if (!groups.has(sender))
+            groups.set(sender, []);
+        groups.get(sender).push(entry);
     }
-    // Human words stay outside the card, so a batch mixing both keeps the card
-    // where the first node sender fell rather than reordering the digest.
     const deliveries = [];
     const sections = [];
     let cardSlot = -1;
     for (const [sender, items] of groups) {
-        // A human typing directly into a node's box is a CONVERSATION TURN, not a
-        // notification the node is being woken to triage. Deliver those words
-        // verbatim as the woken turn's user message — no card, no `<from>` section.
-        // This makes the dormant path identical to the live path (type "hi" → the
-        // node just reads "hi"). Every other sender is digest content.
         if (sender === 'human') {
-            for (const e of items) {
-                const body = inlineBody(e);
-                deliveries.push({ kind: 'human', text: body === '' ? e.label : body, entries: [e] });
+            for (const entry of items) {
+                const body = inlineBody(entry);
+                deliveries.push({ kind: 'human', text: body === '' ? entry.label : body, entries: [entry] });
             }
             continue;
         }
@@ -442,12 +112,10 @@ export function coalesce(entries) {
         sections.push({ id: sender, entries: items.map(cardEntry) });
     }
     if (cardSlot >= 0) {
-        // Card sections group by sender, so its entry list comes from the input
-        // array instead, keeping physical inbox order.
         deliveries[cardSlot] = {
             kind: 'card',
             text: formatInboxCard(sections),
-            entries: entries.filter((e) => (e.from ?? 'system') !== 'human'),
+            entries: entries.filter((entry) => (entry.from ?? 'system') !== 'human'),
         };
     }
     return deliveries;

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

@@ -0,0 +1,58 @@
+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;
+    /** Optional caller-owned obligation identity, used by cron settlement replay. */
+    idempotencyKey?: string;
+}
+export interface ExternalActionAdapter {
+    adapter: 'subprocess' | 'cron_spawn' | 'cron_human';
+    [key: string]: unknown;
+}
+export interface ExternalActionInput {
+    destinationId: string;
+    adapter: ExternalActionAdapter;
+    bodyJson: unknown;
+    idempotencyKey: string;
+    label?: string;
+    kind?: InboxKind;
+}
+export interface EnqueuedNodeMail {
+    messageId: string;
+    deliveryId: string;
+    urgency: InboxTier;
+    createdAt: string;
+}
+export interface EnqueuedExternalAction {
+    messageId: string;
+    deliveryId: string;
+}
+type Subscriber = {
+    node_id: string;
+    active: boolean;
+};
+/** Insert one immutable message and one node-inbox obligation into the caller's write transaction. */
+export declare function enqueueNodeMail(destinationNodeId: string, input: NodeMailInput): EnqueuedNodeMail;
+/** Fan out one immutable report message to the supplied subscriber snapshot. */
+export declare function enqueueSubscriberMail(subscribers: readonly Subscriber[], input: Omit<NodeMailInput, 'wake'>): Array<EnqueuedNodeMail & {
+    destinationNodeId: string;
+}>;
+/** Insert one frozen external-action obligation. A duplicate idempotency key returns its original identity. */
+export declare function enqueueExternalAction(input: ExternalActionInput): EnqueuedExternalAction;
+/** Retract an obligation without fabricating a terminal receipt. */
+export declare function cancelDelivery(deliveryId: string, now?: number): boolean;
+export declare function cancelPendingNodeMail(nodeId: string, select?: {
+    senderNodeId?: string | null;
+    kind?: InboxKind;
+}): string[];
+/** Enqueue the one notice only if the same live controller wait is still dead. */
+export declare function enqueueControllerDeathNotice(nodeId: string, controllerId: string): EnqueuedNodeMail | null;