@north-light/crouter 0.3.311 → 0.3.313

package/dist/core/feed/feed.js

@@ -1,10 +1,13 @@
 // Push engine for the canvas report spine.
 import { existsSync, linkSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
 import { randomUUID } from 'node:crypto';
-import { openDb, reportsDir, subscribersOf, cancelCronsOnWake, composeOutcomeDeliveryDocument, getNode, readOutcomeDelivery, resetOutcomeDeliveryForSupersede } from '../canvas/index.js';
-import { appendInbox } from './inbox.js';
-import { appendPassive } from './passive.js';
+import { reportsDir, cancelCronsOnWake, getNode } from '../canvas/index.js';
+import { openDb, withCanvasWrite } from '../canvas/db.js';
+import { activateArmedExternalActionDelivery, readExternalActionDelivery } from '../canvas/deliveries.js';
+import { composeNodeOutcomeDocument } from '../runtime/outcome-document.js';
+import { syncDirectory, syncFile } from '../fs-utils.js';
+import { enqueueSubscriberMail } from './messages.js';
 import { operationIdContext } from '../events/operation-id.js';
 export class FinalizationError extends Error {
     code;
@@ -15,17 +18,6 @@ export class FinalizationError extends Error {
         this.reportPath = reportPath;
     }
 }
-export class FinalDeliveryError extends Error {
-    reportPath;
-    deliveredTo;
-    failedTo;
-    constructor(reportPath, deliveredTo, failedTo) {
-        super(`canonical final committed at ${reportPath}; delivery failed for ${failedTo.join(', ')}`);
-        this.reportPath = reportPath;
-        this.deliveredTo = deliveredTo;
-        this.failedTo = failedTo;
-    }
-}
 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)}`;
@@ -40,12 +32,23 @@ function stageReport(nodeId, kind, body) {
     const stagedPath = join(dir, `.${basename}.${randomUUID()}.tmp`);
     const ts = now.toISOString();
     writeFileSync(stagedPath, `---\nnode: ${nodeId}\nkind: ${kind}\nts: ${ts}\n---\n${body}`, 'utf8');
+    syncFile(stagedPath);
     return { finalPath, stagedPath, basename, ts };
 }
 /** Install without replacement. link(2) fails if another writer already owns the name. */
 function install(staged) {
-    linkSync(staged.stagedPath, staged.finalPath);
-    rmSync(staged.stagedPath, { force: true });
+    let linked = false;
+    try {
+        linkSync(staged.stagedPath, staged.finalPath);
+        linked = true;
+        rmSync(staged.stagedPath, { force: true });
+        syncDirectory(dirname(staged.finalPath));
+    }
+    catch (error) {
+        if (linked)
+            rmSync(staged.finalPath, { force: true });
+        throw error;
+    }
 }
 function firstLine(text, maxLen = 80) {
     const line = text.split('\n')[0] ?? '';
@@ -55,29 +58,29 @@ function firstLine(text, maxLen = 80) {
 function tierFor(kind, requestedTier) {
     return requestedTier ?? (kind === 'urgent' ? 'urgent' : 'normal');
 }
-function deliver(subscribers, from, fromName, kind, requestedTier, reportRef, body, disposition) {
-    const deliveredTo = [];
-    const failedTo = [];
-    const label = firstLine(body);
-    for (const sub of subscribers) {
-        try {
-            const entry = { from, ...(fromName === undefined ? {} : { from_name: fromName }), tier: tierFor(kind, requestedTier), kind, ref: reportRef, label, ...(disposition === undefined ? {} : { disposition }) };
-            if (sub.active) {
-                appendInbox(sub.node_id, entry);
-                cancelCronsOnWake(sub.node_id);
-            }
-            else
-                appendPassive(sub.node_id, entry);
-            deliveredTo.push(sub.node_id);
-        }
-        catch {
-            failedTo.push(sub.node_id);
-        }
+function outcomeAction(nodeId) {
+    const delivery = readExternalActionDelivery(`node-outcome:${nodeId}`);
+    if (delivery === null)
+        return null;
+    const adapter = delivery.adapter;
+    if (adapter?.adapter !== 'subprocess' || !Array.isArray(adapter.argv) || !adapter.argv.every((entry) => typeof entry === 'string') || typeof adapter.cwd !== 'string') {
+        throw new Error(`outcome delivery ${delivery.deliveryId} has an invalid subprocess adapter`);
     }
-    return { deliveredTo, failedTo };
+    return { name: delivery.destinationId, payload: adapter.payload ?? null };
+}
+function enqueueReport(subscribers, from, fromName, kind, requestedTier, reportRef, body, disposition) {
+    return enqueueSubscriberMail(subscribers, {
+        kind,
+        label: firstLine(body),
+        senderNodeId: from,
+        senderName: fromName,
+        bodyRef: reportRef,
+        urgency: tierFor(kind, requestedTier),
+        ...(disposition === undefined ? {} : { disposition }),
+    }).map((delivery) => delivery.destinationNodeId);
 }
 /** Claim the one canonical final while holding SQLite's write lock. */
-function commitCanonicalFinal(nodeId, staged, outcome) {
+function commitCanonicalFinal(nodeId, staged, body, from, fromName, disposition, outcome) {
     const db = openDb();
     let installed = false;
     db.exec('BEGIN IMMEDIATE');
@@ -92,30 +95,37 @@ function commitCanonicalFinal(nodeId, staged, outcome) {
         if (row.status !== 'active' && row.status !== 'idle' && row.status !== 'done')
             throw new FinalizationError('finalization_forbidden');
         const subscribers = db.prepare(`SELECT from_id AS node_id, active, created FROM edges WHERE type = 'subscribes_to' AND to_id = ? ORDER BY created`).all(nodeId).map((row) => ({ node_id: row['node_id'], active: row['active'] === 1, created: row['created'] }));
-        const delivery = readOutcomeDelivery(nodeId);
         const node = getNode(nodeId);
         const recordsOutcome = node?.kind !== 'human';
         const revision = (node?.outcome_revision ?? 0) + 1;
         const outcomeKind = outcome?.kind ?? 'result';
         const outcomeReason = outcome?.reason ?? 'finalized';
         const outcomeDetailJson = outcome?.detailJson ?? null;
-        const documentJson = !recordsOutcome || delivery === null || node === null ? null : composeOutcomeDeliveryDocument({
-            nodeId,
+        const action = node === null ? null : outcomeAction(nodeId);
+        const documentJson = !recordsOutcome || action === null || node === null ? null : JSON.stringify(composeNodeOutcomeDocument({
+            node: { ...node, status: 'done', intent: 'done', terminal_reason: outcomeReason },
             outcome: { kind: outcomeKind, reason: outcomeReason, at: staged.ts, revision, detailJson: outcomeDetailJson },
-            action: { name: delivery.actionName, payload: delivery.payload },
+            action,
             finalReport: staged.basename,
-        });
+        }));
         install(staged);
         installed = true;
         if (recordsOutcome) {
             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, staged.basename, staged.ts, outcomeKind, outcomeReason, staged.ts, outcomeDetailJson, nodeId);
-            resetOutcomeDeliveryForSupersede(nodeId, documentJson, Date.now());
+            if (documentJson !== null)
+                activateArmedExternalActionDelivery(db, {
+                    idempotencyKey: `node-outcome:${nodeId}`,
+                    label: nodeId,
+                    bodyJson: documentJson,
+                    supersede: true,
+                }, Date.now());
         }
         else {
             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(staged.basename, staged.ts, nodeId);
         }
+        const deliveredTo = enqueueReport(subscribers, from, fromName, 'final', undefined, `${nodeId}:reports/${staged.basename}`, body, disposition);
         db.exec('COMMIT');
-        return { subscribers };
+        return { deliveredTo };
     }
     catch (err) {
         db.exec('ROLLBACK');
@@ -138,7 +148,7 @@ async function pushWithContext(nodeId, opts) {
     const from = opts.from ?? nodeId;
     const fromName = getNode(from)?.name;
     if (opts.kind === 'final') {
-        const { subscribers } = commitCanonicalFinal(nodeId, staged, opts.outcome);
+        const { deliveredTo } = commitCanonicalFinal(nodeId, staged, opts.body, from, fromName, opts.disposition, opts.outcome);
         // 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
@@ -147,18 +157,23 @@ async function pushWithContext(nodeId, opts) {
         // cancel-on-wake rows anchored here go; standing crons survive. Outside
         // commitCanonicalFinal's transaction — it takes its own write boundary.
         cancelCronsOnWake(nodeId);
-        const { deliveredTo, failedTo } = deliver(subscribers, from, fromName, opts.kind, undefined, `${nodeId}:reports/${staged.basename}`, opts.body, opts.disposition);
-        if (failedTo.length > 0)
-            throw new FinalDeliveryError(staged.finalPath, deliveredTo, failedTo);
         return { reportPath: staged.finalPath, deliveredTo };
     }
+    let installed = false;
     try {
         install(staged);
-        const { deliveredTo, failedTo } = deliver(subscribersOf(nodeId), from, fromName, opts.kind, opts.deliveryTier, `${nodeId}:reports/${staged.basename}`, opts.body, opts.disposition);
-        if (failedTo.length > 0)
-            throw new Error(`report published at ${staged.finalPath}; delivery failed for ${failedTo.join(', ')}`);
+        installed = true;
+        const deliveredTo = withCanvasWrite((db) => {
+            const subscribers = db.prepare(`SELECT from_id AS node_id, active, created FROM edges WHERE type = 'subscribes_to' AND to_id = ? ORDER BY created`).all(nodeId).map((row) => ({ node_id: row['node_id'], active: row['active'] === 1, created: row['created'] }));
+            return enqueueReport(subscribers, from, fromName, opts.kind, opts.deliveryTier, `${nodeId}:reports/${staged.basename}`, opts.body, opts.disposition);
+        });
         return { reportPath: staged.finalPath, deliveredTo };
     }
+    catch (error) {
+        if (installed)
+            rmSync(staged.finalPath, { force: true });
+        throw error;
+    }
     finally {
         rmSync(staged.stagedPath, { force: true });
     }
@@ -182,9 +197,6 @@ export function redeliverFinalReport(nodeId, originNodeId, reportBasename, body,
     if (reportBasename === '' || reportBasename.includes('/') || reportBasename.includes('\\')) {
         throw new Error(`invalid canonical final report basename: ${reportBasename}`);
     }
-    const { deliveredTo, failedTo } = deliver([{ node_id: originNodeId, active: true, created: '' }], nodeId, getNode(nodeId)?.name, 'final', undefined, `${nodeId}:reports/${reportBasename}`, body, opts?.disposition);
-    const reportPath = join(reportsDir(nodeId), reportBasename);
-    if (failedTo.length > 0)
-        throw new FinalDeliveryError(reportPath, deliveredTo, failedTo);
-    return { reportPath, deliveredTo };
+    const deliveredTo = enqueueReport([{ node_id: originNodeId, active: true, created: '' }], nodeId, getNode(nodeId)?.name, 'final', undefined, `${nodeId}:reports/${reportBasename}`, body, opts?.disposition);
+    return { reportPath: join(reportsDir(nodeId), reportBasename), deliveredTo };
 }

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

@@ -1,110 +1,36 @@
 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;
 };
-/** A single inbox entry: a push pointer (`ref` as a canonical
- *  `<node-id>:reports/<basename>` history handle, no inline body), or a direct
- *  message/system notice (short bodies inline via `data.body`; bodies too long
- *  to inline spill to `messages/` and carry an absolute filesystem `ref` plus
- *  a bounded inline preview). */
+/** The rendering projection of one immutable SQL message and its delivery. */
 export interface InboxEntry {
-    /** Unique physical-entry identity. It is opaque and never sortable. */
     entry_id: InboxEntryId;
-    /** Correlation identity inherited from the producing operation. */
     operation_id: OperationId;
-    /** ISO 8601 timestamp of delivery (display only). */
     ts: string;
-    /** Node id of the sender, or null for system-generated entries. */
     from: string | null;
-    /** Display-name snapshot captured when a node created the entry. */
     from_name?: string;
-    /** Priority band for the receiver's attention. */
     tier: InboxTier;
-    /** Semantic kind of the push event. */
     kind: InboxKind;
-    /** Canonical `<node-id>:reports/<basename>` history ref for a push, or an
-     *  absolute path to the spilled body file under `messages/` for an oversized
-     *  direct message/system notice. */
     ref?: string;
-    /** First ~80 chars of the body's first line — enough to decide if it matters. */
     label: string;
-    /** Arbitrary structured payload for non-push message entries. */
     data?: Record<string, unknown>;
-    /** Set only by the human-ticket settlement paths; absent means an ordinary report. */
     disposition?: InboxDisposition;
 }
-export type InboxEntryInput = Omit<InboxEntry, 'entry_id' | 'ts' | 'operation_id'> & {
-    operation_id?: string;
-};
-/** Complete an entry exactly once before any spill or append work. */
-export declare function finalizeInboxEntry(input: InboxEntryInput): InboxEntry;
-/** Atomically append one finalized inbox entry to `nodes/<nodeId>/inbox.jsonl`,
- *  at the tier `effectiveTier` resolves for this target. */
-export declare function appendInbox(nodeId: string, entry: InboxEntryInput): InboxEntry;
-/** 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 declare function appendControllerDeathNotice(nodeId: string, controller: string): InboxEntry | null;
-/** Return the physical suffix strictly after the exact cursor identity. */
-export declare function readInboxSince(nodeId: string, cursorEntryId?: string): InboxEntry[];
-/** Read one exact contiguous physical range after an exclusive boundary through an inclusive boundary. */
-export declare function readInboxRange(nodeId: string, afterEntryId: string | undefined, throughEntryId: string): InboxEntry[];
-/** 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 declare function readCanceledEntryIds(nodeId: string): Set<InboxEntryId>;
-/** 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 declare function cancelPendingHumanMessages(nodeId: string): InboxEntryId[];
-/** 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 declare function cancelPendingEntries(nodeId: string, select: (entry: InboxEntry) => boolean): InboxEntryId[];
-/** Read and validate the persisted exact cursor identity. */
-export declare function readCursor(nodeId: string): InboxEntryId | undefined;
-/** Persist one validated exact cursor identity (atomic tmp+rename). */
-export declare function writeCursor(nodeId: string, entryId: string): void;
-/** 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 declare function hasUnseenWakeMail(nodeId: string): boolean;
-/** 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 declare function hasWakeMailSince(nodeId: string, sinceMs: number): boolean;
-/** Clip a body to a bounded preview, reporting whether anything was dropped. */
+/** Project the immutable message body and destination-specific urgency into the canonical inbox rendering shape. */
+export declare function nodeMailEntry(delivery: ClaimedNodeMail): InboxEntry;
+/** Clip a body to the bounded preview stored beside a spilled message body. */
 export declare function clipBody(body: string): {
     text: string;
     clipped: boolean;
 };
-/** One deliverable user message: either a person's verbatim words or the whole
- *  `<runtime kind="inbox">` envelope. Never both — a reader parses an envelope
- *  only as a whole message, so mixing them attributes the card to the person. */
 export interface InboxDelivery {
     kind: 'human' | 'card';
     text: string;
     entries: readonly InboxEntry[];
 }
-/** Split unread inbox pointers into ordered deliveries: each human entry
- *  verbatim, and every other sender in one `<runtime kind="inbox">` card. */
-export declare function coalesce(entries: InboxEntry[]): readonly InboxDelivery[];
+/** Split delivered entries into verbatim human messages and sender-grouped inbox cards. */
+export declare function coalesce(entries: readonly InboxEntry[]): readonly InboxDelivery[];