@north-light/crouter 0.3.170 → 0.3.172

package/dist/daemon/review/deliver.js

@@ -0,0 +1,56 @@
+import { FinalizationError, pushFinal, redeliverFinalReport } from '../../core/feed/feed.js';
+import { deliverNodeMessage } from '../messaging/node-message.js';
+function approvalBody(review, resultPath) {
+    const summary = review.changed
+        ? `The human reviewed and approved \`${review.file}\`. The document changed during review; re-read it before continuing. Review conversation: node \`${review.companion_node_id}\`.`
+        : `The human reviewed and approved \`${review.file}\`. The document was not modified.`;
+    return `${summary}\n\nDurable review result: ${resultPath}`;
+}
+/** Render the immutable approval fact without replaying comment text. */
+export function renderApprovalMessage(review, resultPath) {
+    return approvalBody(review, resultPath);
+}
+function recordedFailedFanout(review, reportBasename) {
+    const error = review.delivery_error;
+    if (error === null || !error.includes(reportBasename))
+        return false;
+    const failed = /delivery failed for (.+)$/.exec(error)?.[1]?.split(', ') ?? [];
+    return failed.includes(review.origin_node_id);
+}
+/** Deliver an approval through its origin-specific canonical route. */
+export async function deliverApproval(review, resultPath) {
+    const body = renderApprovalMessage(review, resultPath);
+    if (review.origin_kind === 'inline') {
+        const delivery = await deliverNodeMessage({
+            node_id: review.origin_node_id,
+            body,
+            label: 'human review approved',
+            from: 'crtrd',
+            mode: 'interactive',
+            data: { review_id: review.review_id, result_path: resultPath },
+        });
+        return { receipt: delivery.entry_id };
+    }
+    if (review.bridge_node_id === null) {
+        throw new Error(`ticket review ${review.review_id} has no bridge node`);
+    }
+    try {
+        const result = await pushFinal(review.bridge_node_id, body);
+        return { receipt: result.reportPath.split('/').at(-1) ?? null };
+    }
+    catch (error) {
+        if (!(error instanceof FinalizationError) || error.code !== 'already_finalized')
+            throw error;
+        const reportBasename = error.reportPath;
+        if (reportBasename === undefined)
+            throw error;
+        // A committed final with no failed-delivery ledger is the crash window
+        // after a successful fanout and before the review ledger was marked.
+        if (review.delivery_error === null)
+            return { receipt: reportBasename };
+        if (!recordedFailedFanout(review, reportBasename))
+            throw error;
+        const result = redeliverFinalReport(review.bridge_node_id, review.origin_node_id, reportBasename, body);
+        return { receipt: result.reportPath.split('/').at(-1) ?? null };
+    }
+}

package/dist/daemon/review/finish.d.ts

@@ -0,0 +1,22 @@
+import type { TicketResult } from '../../core/human/types.js';
+import { type ReviewRecord, type ReviewResult } from '../../core/review/types.js';
+export interface ReviewApprovalFinishOutcome {
+    outcome: 'settled' | 'already_settled';
+    record: ReviewRecord;
+    result: ReviewResult;
+}
+export interface ReviewCancellationFinishOutcome {
+    outcome: 'settled' | 'already_settled';
+    record: ReviewRecord;
+    ticket_result?: TicketResult;
+}
+export type ReviewFinishOutcome = ReviewApprovalFinishOutcome | ReviewCancellationFinishOutcome;
+/** Retire a companion only through a lifecycle transition legal for its current status. */
+export declare function retireCompanion(nodeId: string, outcome: 'approved' | 'canceled'): 'retired' | 'already' | 'missing';
+/** Commit approval once, then independently finish its projection, delivery, and companion retirement ledgers. */
+export declare function submitReviewApproval(reviewId: string): Promise<ReviewApprovalFinishOutcome>;
+/** Cancel an open review once; ticket cancellation remains owned by the retained human-ticket finisher. */
+export declare function cancelReview(reviewId: string, args: {
+    reason?: string;
+    actor?: string;
+}): Promise<ReviewCancellationFinishOutcome>;

package/dist/daemon/review/finish.js

@@ -0,0 +1,254 @@
+import { withCanvasWrite } from '../../core/canvas/db.js';
+import { getNode } from '../../core/canvas/canvas.js';
+import { responsePath } from '../../core/human/convention.js';
+import { ticketDir } from '../../core/human/root.js';
+import { readTicketResult } from '../../core/human/tickets.js';
+import { projectReviewResult, buildReviewResult } from '../../core/review/project.js';
+import { reviewResultPath } from '../../core/canvas/paths.js';
+import { snapshotCommentsLocked } from '../../core/review/comments.js';
+import { readReviewSource } from '../../core/review/document.js';
+import { signalReviewActivity } from '../../core/review/signal.js';
+import { approveReviewLocked, cancelReviewRow, getReview, markDelivered, markDeliveryError, markProjected, markProjectionError, } from '../../core/review/store.js';
+import { ReviewOperationError } from '../../core/review/types.js';
+import { transition } from '../../core/runtime/lifecycle.js';
+import { headlessBrokerHost } from '../../core/runtime/host.js';
+import { cancelHumanTicket, deliverTerminalResult } from '../human/finish.js';
+import { deliverApproval } from './deliver.js';
+/** One daemon serializes terminal side effects for each immutable review row. */
+const finishChains = new Map();
+function now() {
+    return new Date().toISOString();
+}
+function errorText(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function unknownReview(reviewId) {
+    throw new ReviewOperationError('unknown_review', 'review was not found', { received: reviewId });
+}
+function requireVisibleReview(reviewId) {
+    const review = getReview(reviewId);
+    if (review === null || review.state === 'binding')
+        return unknownReview(reviewId);
+    return review;
+}
+function terminalConflict(review, requested) {
+    throw new ReviewOperationError('review_terminal', 'review already has a terminal outcome', {
+        state: review.state,
+        requested,
+        review,
+    });
+}
+function approvedResult(review) {
+    if (review.result_json === null)
+        throw new Error(`approved review lacks its immutable result: ${review.review_id}`);
+    return JSON.parse(review.result_json);
+}
+function resultPath(review) {
+    if (review.origin_kind === 'inline')
+        return reviewResultPath(review.review_id);
+    if (review.bridge_node_id === null)
+        throw new Error(`ticket review lacks its bridge node: ${review.review_id}`);
+    return responsePath(ticketDir(review.bridge_node_id));
+}
+function ticketResult(review) {
+    return review.origin_kind === 'ticket' && review.bridge_node_id !== null
+        ? readTicketResult(ticketDir(review.bridge_node_id)) ?? undefined
+        : undefined;
+}
+function isPostReplayAlreadyResolved(error) {
+    return error instanceof Error
+        && 'status' in error
+        && error.status === 409
+        && 'code' in error
+        && error.code === 'ticket_already_resolved';
+}
+async function serializedFinish(reviewId, work) {
+    const prior = finishChains.get(reviewId) ?? Promise.resolve();
+    const run = prior.catch(() => { }).then(work);
+    const tail = run.then(() => { }, () => { });
+    finishChains.set(reviewId, tail);
+    try {
+        return await run;
+    }
+    finally {
+        if (finishChains.get(reviewId) === tail)
+            finishChains.delete(reviewId);
+    }
+}
+/** Retire a companion only through a lifecycle transition legal for its current status. */
+export function retireCompanion(nodeId, outcome) {
+    const node = getNode(nodeId);
+    if (node === null)
+        return 'missing';
+    if (node.status === 'done' || node.status === 'canceled')
+        return 'already';
+    if (outcome === 'approved' && (node.status === 'active' || node.status === 'idle')) {
+        transition(nodeId, 'finish');
+        try {
+            headlessBrokerHost.teardown(nodeId);
+        }
+        catch { /* the terminal transition is authoritative */ }
+        return 'retired';
+    }
+    // Cancellation is legal from every status. An already-dead companion cannot
+    // be finished, so it is retired as canceled even when approval won.
+    transition(nodeId, 'cancel');
+    if (node.status === 'active' || node.status === 'idle') {
+        try {
+            headlessBrokerHost.teardown(nodeId);
+        }
+        catch { /* the terminal transition is authoritative */ }
+    }
+    return 'retired';
+}
+async function finishApproved(review, result) {
+    let current = requireVisibleReview(review.review_id);
+    if (current.projected_at === null) {
+        try {
+            projectReviewResult(current, result);
+            markProjected(current.review_id, now());
+        }
+        catch (error) {
+            markProjectionError(current.review_id, errorText(error));
+        }
+    }
+    current = requireVisibleReview(review.review_id);
+    if (current.delivered_at === null) {
+        try {
+            const delivery = await deliverApproval(current, resultPath(current));
+            markDelivered(current.review_id, delivery.receipt, now());
+        }
+        catch (error) {
+            markDeliveryError(current.review_id, errorText(error));
+        }
+    }
+    current = requireVisibleReview(review.review_id);
+    retireCompanion(current.companion_node_id, 'approved');
+    return requireVisibleReview(review.review_id);
+}
+async function finishCanceled(review, winningWrite, args) {
+    let current = requireVisibleReview(review.review_id);
+    let canceledTicket;
+    if (current.origin_kind === 'inline') {
+        if (current.projected_at === null)
+            markProjected(current.review_id, now());
+        current = requireVisibleReview(review.review_id);
+        if (current.delivered_at === null)
+            markDelivered(current.review_id, null, now());
+    }
+    else if (current.bridge_node_id === null) {
+        markProjectionError(current.review_id, `ticket review lacks its bridge node: ${current.review_id}`);
+        markDeliveryError(current.review_id, `ticket review lacks its bridge node: ${current.review_id}`);
+    }
+    else if (current.delivered_at === null) {
+        try {
+            if (winningWrite) {
+                canceledTicket = await cancelHumanTicket(current.bridge_node_id, args);
+            }
+            else {
+                const delivered = await deliverTerminalResult(current.bridge_node_id);
+                if (!delivered)
+                    throw new Error(`ticket cancellation is not available for delivery: ${current.bridge_node_id}`);
+                canceledTicket = ticketResult(current);
+            }
+            if (canceledTicket === undefined)
+                throw new Error(`ticket cancellation result is missing: ${current.bridge_node_id}`);
+            markProjected(current.review_id, now());
+            markDelivered(current.review_id, null, now());
+        }
+        catch (error) {
+            if (winningWrite && isPostReplayAlreadyResolved(error)) {
+                try {
+                    const delivered = await deliverTerminalResult(current.bridge_node_id);
+                    if (!delivered)
+                        throw new Error(`ticket cancellation is not available for delivery: ${current.bridge_node_id}`);
+                    canceledTicket = ticketResult(current);
+                    if (canceledTicket === undefined)
+                        throw new Error(`ticket cancellation result is missing: ${current.bridge_node_id}`);
+                    markProjected(current.review_id, now());
+                    markDelivered(current.review_id, null, now());
+                }
+                catch (replayError) {
+                    markDeliveryError(current.review_id, errorText(replayError));
+                }
+            }
+            else {
+                // cancelHumanTicket publishes response.json before fanout. Preserve that
+                // publication ledger even when the retained delivery path reports a failure.
+                if (ticketResult(current) !== undefined)
+                    markProjected(current.review_id, now());
+                markDeliveryError(current.review_id, errorText(error));
+            }
+        }
+    }
+    current = requireVisibleReview(review.review_id);
+    if (canceledTicket === undefined)
+        canceledTicket = ticketResult(current);
+    retireCompanion(current.companion_node_id, 'canceled');
+    return { record: requireVisibleReview(review.review_id), ...(canceledTicket === undefined ? {} : { ticket_result: canceledTicket }) };
+}
+/** Commit approval once, then independently finish its projection, delivery, and companion retirement ledgers. */
+export async function submitReviewApproval(reviewId) {
+    const initial = requireVisibleReview(reviewId);
+    if (initial.state === 'canceled')
+        return terminalConflict(initial, 'submit');
+    if (initial.state === 'approved') {
+        const result = approvedResult(initial);
+        const record = await serializedFinish(reviewId, () => finishApproved(initial, result));
+        return { outcome: 'already_settled', record, result };
+    }
+    const source = readReviewSource(initial.file, 'submit');
+    const committed = withCanvasWrite((db) => {
+        const review = requireVisibleReview(reviewId);
+        if (review.state === 'canceled')
+            return terminalConflict(review, 'submit');
+        if (review.state === 'approved')
+            return { outcome: 'already_settled', review, result: approvedResult(review) };
+        if (review.state !== 'open')
+            throw new ReviewOperationError('review_not_open', 'review is not open', { review_id: reviewId, state: review.state });
+        const snapshot = snapshotCommentsLocked(db, reviewId);
+        const at = now();
+        const result = buildReviewResult(review, snapshot, source.sha256, at);
+        if (!approveReviewLocked(db, {
+            review_id: reviewId,
+            approved_at: at,
+            approved_sha256: source.sha256,
+            changed: result.changed,
+            comments_total: snapshot.total,
+            comments_unresolved: snapshot.unresolved,
+            result_json: JSON.stringify(result),
+        })) {
+            const winner = requireVisibleReview(reviewId);
+            if (winner.state === 'approved')
+                return { outcome: 'already_settled', review: winner, result: approvedResult(winner) };
+            return terminalConflict(winner, 'submit');
+        }
+        return { outcome: 'settled', review: requireVisibleReview(reviewId), result };
+    });
+    if (committed.outcome === 'settled')
+        signalReviewActivity();
+    const record = await serializedFinish(reviewId, () => finishApproved(committed.review, committed.result));
+    return { outcome: committed.outcome, record, result: committed.result };
+}
+/** Cancel an open review once; ticket cancellation remains owned by the retained human-ticket finisher. */
+export async function cancelReview(reviewId, args) {
+    const initial = requireVisibleReview(reviewId);
+    if (initial.state === 'approved')
+        return terminalConflict(initial, 'cancel');
+    const winningWrite = initial.state === 'open'
+        && cancelReviewRow(reviewId, { at: now(), reason: args.reason ?? '', actor: args.actor ?? null });
+    const review = requireVisibleReview(reviewId);
+    if (review.state === 'approved')
+        return terminalConflict(review, 'cancel');
+    if (review.state !== 'canceled') {
+        throw new ReviewOperationError('review_not_open', 'review is not open', { review_id: reviewId, state: review.state });
+    }
+    if (winningWrite)
+        signalReviewActivity();
+    const finished = await serializedFinish(reviewId, () => finishCanceled(review, winningWrite, args));
+    return {
+        outcome: winningWrite ? 'settled' : 'already_settled',
+        record: finished.record,
+        ...(finished.ticket_result === undefined ? {} : { ticket_result: finished.ticket_result }),
+    };
+}

package/dist/daemon/review/sweep.d.ts

@@ -0,0 +1,11 @@
+export interface ReviewSweepResult {
+    realized: number;
+    collected: number;
+    reprojected: number;
+    failed: number;
+}
+/**
+ * Recover only pre-exposure review work at daemon startup. Terminal delivery and
+ * retirement are intentionally outside this pass and require an explicit repeat.
+ */
+export declare function sweepReviews(): Promise<ReviewSweepResult>;

package/dist/daemon/review/sweep.js

@@ -0,0 +1,120 @@
+import { existsSync, readdirSync, rmSync } from 'node:fs';
+import { basename } from 'node:path';
+import { reviewPath } from '../../core/human/convention.js';
+import { ticketDir } from '../../core/human/root.js';
+import { submitReview } from '../../core/human/tickets.js';
+import { reviewsRoot } from '../../core/canvas/paths.js';
+import { projectReviewResult } from '../../core/review/project.js';
+import { realizeReview } from '../../core/review/realize.js';
+import { listBindingReviews, listReviews, markProjected, markProjectionError, } from '../../core/review/store.js';
+import { ReviewOperationError } from '../../core/review/types.js';
+function errorText(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function isMissingPath(error) {
+    return error?.code === 'ENOENT';
+}
+/** Republish the ticket projection only after its canonical review is already open. */
+function republishTicketReview(review) {
+    if (review.bridge_node_id === null)
+        throw new Error(`ticket review has no bridge node: ${review.review_id}`);
+    if (review.subtitle === null)
+        throw new Error(`ticket review has no subtitle: ${review.review_id}`);
+    const dir = ticketDir(review.bridge_node_id);
+    if (existsSync(reviewPath(dir)))
+        return;
+    submitReview({
+        dir,
+        review: {
+            file: review.file,
+            ...(review.output_path === null ? {} : { output: review.output_path }),
+            title: basename(review.file),
+            subtitle: review.subtitle,
+            source: { nodeId: review.origin_node_id },
+            blockedSince: review.created,
+        },
+    });
+}
+/** Reproject only an immutable, already-approved canonical result. */
+function reprojectApprovedReview(review) {
+    if (review.result_json === null)
+        throw new Error(`approved review lacks its immutable result: ${review.review_id}`);
+    projectReviewResult(review, JSON.parse(review.result_json));
+    markProjected(review.review_id, new Date().toISOString());
+}
+/** Remove only direct review directories that are no longer referenced by a row. */
+function collectOrphanReviewDirectories(reviewIds) {
+    let entries;
+    try {
+        entries = readdirSync(reviewsRoot(), { withFileTypes: true });
+    }
+    catch (error) {
+        if (isMissingPath(error))
+            return 0;
+        throw error;
+    }
+    let collected = 0;
+    for (const entry of entries) {
+        if (!entry.isDirectory() || reviewIds.has(entry.name))
+            continue;
+        rmSync(`${reviewsRoot()}/${entry.name}`, { recursive: true, force: true });
+        collected += 1;
+    }
+    return collected;
+}
+/**
+ * Recover only pre-exposure review work at daemon startup. Terminal delivery and
+ * retirement are intentionally outside this pass and require an explicit repeat.
+ */
+export async function sweepReviews() {
+    let realized = 0;
+    let collected = 0;
+    let reprojected = 0;
+    let failed = 0;
+    const bindings = listBindingReviews();
+    for (const review of bindings) {
+        try {
+            await realizeReview(review.review_id);
+            realized += 1;
+        }
+        catch (error) {
+            // A missing immutable branch is an expected recovery outcome: realization
+            // cancels the binding and never captures a replacement branch.
+            if (!(error instanceof ReviewOperationError && error.code === 'branch_lost'))
+                failed += 1;
+        }
+    }
+    try {
+        const reviewIds = new Set([
+            ...listBindingReviews().map((review) => review.review_id),
+            ...listReviews({}).map((review) => review.review_id),
+        ]);
+        collected = collectOrphanReviewDirectories(reviewIds);
+    }
+    catch {
+        failed += 1;
+    }
+    for (const review of listReviews({ state: 'approved' })) {
+        if (review.projected_at !== null)
+            continue;
+        try {
+            reprojectApprovedReview(review);
+            reprojected += 1;
+        }
+        catch (error) {
+            markProjectionError(review.review_id, errorText(error));
+            failed += 1;
+        }
+    }
+    for (const review of listReviews({ state: 'open' })) {
+        if (review.origin_kind !== 'ticket')
+            continue;
+        try {
+            republishTicketReview(review);
+        }
+        catch {
+            failed += 1;
+        }
+    }
+    return { realized, collected, reprojected, failed };
+}

package/dist/index.d.ts

@@ -24,4 +24,6 @@ export type { BuildEnvelopeInput, ErrorClass, ErrorClassCode, ErrorClassHints, E
 export { validateCommandManifest } from './core/command-manifests/manifest.js';
 export type { CommandManifestValidation, ValidatedCommandManifest } from './core/command-manifests/manifest.js';
 export type { CommandManifestIssue, TransportKind } from './core/command-manifests/schema.js';
+export { validatePluginBundle } from './core/command-plugins/bundle.js';
+export type { BundleIssue, PluginBundleValidation, ValidatedBundle } from './core/command-plugins/bundle.js';
 export { SUBTREE_NAMES } from './build-root.js';

package/dist/index.js

@@ -2,8 +2,7 @@
 //
 // This barrel is the ONLY supported way to import crouter as a library; the
 // `exports` map gates off deep subpath imports, so consumers depend on exactly
-// the symbols re-exported here — notably the in-tree web client, which reaches
-// the runtime through the `@north-light/crouter/web` seam.
+// the symbols re-exported here.
 // Everything below is a stable, server-facing surface: runtime control that
 // keeps the canvas-row ⇄ pi-session lockstep guarantees, read-only canvas/
 // telemetry queries, and the broker socket client + wire protocol. Nothing
@@ -44,4 +43,5 @@ export { nowIso } from './core/fs-utils.js';
 export { validateOperationId, buildEnvelope, operationIdContext, errorClassCodes, serializeEventRecord, errorClassFromError, } from './core/events/index.js';
 // ── Command-manifest compatibility ───────────────────────────────────────
 export { validateCommandManifest } from './core/command-manifests/manifest.js';
+export { validatePluginBundle } from './core/command-plugins/bundle.js';
 export { SUBTREE_NAMES } from './build-root.js';