@north-light/crouter 0.3.312 → 0.3.314

package/dist/daemon/human/finish.js

@@ -1,304 +1,107 @@
-import { ApiError } from '../../api/index.js';
-import { getRow, subscribersOf } from '../../core/canvas/canvas.js';
-import { cancelCronsOnWake } from '../../core/canvas/crons.js';
-import { opaqueInboxTicketId, ticketDir } from '../../core/human/root.js';
-import { readTicketActionBinding } from '../../core/human/action-binding.js';
-import { completionEventFor, composeHumanCompletion } from '../../core/human/completion.js';
-import { enqueueActionDelivery } from '../../core/canvas/human-deliveries.js';
-import { parsePage } from '../../core/human/page.js';
-import { cancelTicket, projectReviewOutput, readTicketResult, takeoverAndCompletePage, } from '../../core/human/tickets.js';
-import { describePageAnswer } from '../../core/human/answer.js';
-import { renderAnswerText } from '../../core/human/answer-text.js';
-import { pagePath, readTicketReplyRoute, responsePath } from '../../core/human/convention.js';
-import { readPageFeedback } from '../../core/human/feedback.js';
-import { pageDocumentSha256 } from '../../core/human/feedback-companion.js';
-import { appendInbox } from '../../core/feed/inbox.js';
-import { FinalDeliveryError, pushFinal, pushUpdate } from '../../core/feed/feed.js';
-import { transition } from '../../core/runtime/lifecycle.js';
-import { emitEvent } from '../../core/events/emit.js';
+import { getRequest, getRequestByInboxTicket } from '../../core/human/requests.js';
+import { buildPageSummary } from '../../core/human/summary.js';
+import { validateFinalPageResponses } from '../../core/human/tickets.js';
+import { composeHumanCompletion } from '../../core/human/completion.js';
 import { retireCompanion } from '../companion-retire.js';
-/** Every ticket-ending action retires the ticket's feedback companion — done
- * with a canonical final when approved, never left resident. Idempotent and replay-safe; a
- * corrupt feedback file must not block result publication. Exported for the
- * daemon-start sweep, which must settle terminal tickets whether or not a
- * reply bridge exists. */
-export async function settleFeedbackCompanion(ticketId, outcome) {
-    try {
-        const companionNodeId = readPageFeedback(ticketDir(ticketId)).companionNodeId;
-        if (companionNodeId !== undefined)
-            await retireCompanion(companionNodeId, outcome);
-    }
-    catch (error) {
-        emitEvent({ level: 'warn', event: 'human.feedback_companion.retire_failed', error });
-    }
+import { settleHumanRequest } from './settle.js';
+function requestForTicket(ticketId) {
+    const request = getRequest(ticketId) ?? getRequestByInboxTicket(ticketId);
+    if (request === null || request.kind !== 'page')
+        throw new Error(`unknown page request: ${ticketId}`);
+    return request;
 }
-/** The settle-time feedback addendum to a page completion — answer and
- * cancellation alike: a change notice when the final page differs from the
- * version first commented on, and each still-open item's quote and note.
- * Silent when the page is unchanged and no feedback remains open; never a
- * manufactured prose diff. */
-function feedbackAddendum(dir) {
-    let sections;
+function manifest(request) {
     try {
-        const feedback = readPageFeedback(dir);
-        if (feedback.companionNodeId === undefined)
-            return '';
-        sections = [];
-        if (feedback.firstCommentedSha256 !== undefined && pageDocumentSha256(dir) !== feedback.firstCommentedSha256) {
-            sections.push(`The page changed during feedback: the person commented on it and its companion conversation (node ${feedback.companionNodeId}) revised it in place. ` +
-                `Reread the final page at ${pagePath(dir, 'jsx')} before interpreting this outcome.`);
-        }
-        const open = feedback.comments.filter((comment) => comment.status === 'open');
-        if (open.length > 0) {
-            const items = open.map((comment) => [
-                ...comment.quote.split('\n').map((line) => `> ${line}`),
-                comment.note,
-            ].join('\n'));
-            sections.push([
-                `Feedback left unresolved at settlement — the companion conversation (node ${feedback.companionNodeId}) had not dealt with these items:`,
-                ...items,
-            ].join('\n\n'));
-        }
+        const value = JSON.parse(request.specification_json);
+        if (typeof value !== 'object' || value === null)
+            throw new Error('not an object');
+        return value;
     }
-    catch {
-        // The answer itself is the deliverable; a broken feedback record adds nothing.
-        return '';
+    catch (error) {
+        throw new Error(`corrupt page specification: ${request.request_id}`, { cause: error });
     }
-    return sections.length === 0 ? '' : `\n\n${sections.join('\n\n')}`;
 }
-/** A corrupt manifest must not strand the asking node: the raw response remains its escape hatch. */
-function renderCorruptPageAnswer(result, resultPath) {
-    return [
-        'The page manifest could not be read, so the raw response is provided.',
-        '',
-        JSON.stringify(result.responses),
-        '',
-        `Response record: ${resultPath}`,
-    ].join('\n');
-}
-function pageTitle(dir) {
-    try {
-        return parsePage(dir).title;
-    }
-    catch {
+function completionAction(request, result) {
+    if (request.action_json === null)
         return undefined;
-    }
-}
-/** Person-authored response values, derived from the structured answer rather
- * than display prose. Empty values have no words to attribute. */
-function personWords(answer) {
-    if (answer.kind === 'acknowledgement')
-        return '';
-    const words = [];
-    for (const slot of answer.slots) {
-        if (slot.state !== 'answered')
-            continue;
-        if (slot.raw !== undefined) {
-            words.push(JSON.stringify(slot.raw));
-            continue;
-        }
-        if (slot.text !== undefined) {
-            if (slot.text.edited || slot.text.singleLine === true)
-                words.push(slot.text.value);
-            continue;
-        }
-        for (const group of slot.groups)
-            words.push(...group.picked.map((item) => item.label));
-        if (slot.freetext !== undefined)
-            words.push(slot.freetext);
-        words.push(...slot.comments.map((comment) => comment.text));
-    }
-    return words.filter((word) => word !== '').join('\n\n');
-}
-/** The answer push: the person's words alone when the page captured any, tagged
- * so every reader attributes them to the person without re-deriving it from
- * prose. A page that captured nothing stays an ordinary report carrying the
- * full record, because there is nothing of the person's to attribute. */
-function renderPageAnswer(dir, result, resultPath) {
-    let manifest;
     try {
-        manifest = parsePage(dir);
+        const binding = JSON.parse(request.action_json);
+        if (binding.schema !== 'crtr.human-action-binding/v1' || !Array.isArray(binding.argv) || typeof binding.cwd !== 'string')
+            throw new Error('invalid binding');
+        return {
+            destinationId: binding.name,
+            adapter: { adapter: 'subprocess', argv: binding.argv, cwd: binding.cwd },
+            bodyJson: composeHumanCompletion({ requestId: request.request_id, result: result, binding, source: manifest(request).source ?? {} }),
+        };
     }
-    catch {
-        return { body: renderCorruptPageAnswer(result, resultPath) };
+    catch (error) {
+        throw new Error(`corrupt frozen completion action: ${request.request_id}`, { cause: error });
     }
-    const answer = describePageAnswer(manifest, result.responses, { completedAt: result.completedAt });
-    const rendered = renderAnswerText(answer, resultPath);
-    const addendum = feedbackAddendum(dir);
-    const words = personWords(answer);
-    return words === ''
-        ? { body: rendered + addendum }
-        : { body: words, disposition: 'human-answer', ...(addendum === '' ? {} : { feedback: addendum.trim() }) };
 }
-function deliveryFailed(error) {
-    // A canonical final is committed inside its own write boundary and can never
-    // be replayed (`already_finalized`), so a subscriber that missed the fanout
-    // stays missed. Say that rather than promising a retry that cannot happen.
-    if (error instanceof FinalDeliveryError) {
-        return new ApiError(500, 'delivery_failed', `The answer is recorded and the bridge node is finalized; its report is at ${error.reportPath}. Notifying ${error.failedTo.join(', ')} failed and will not be retried.`);
-    }
-    const detail = error instanceof Error ? error.message : String(error);
-    return new ApiError(500, 'delivery_failed', `The answer is recorded and delivery will be retried: ${detail}`);
+function notification(request, disposition, bodyJson) {
+    if (request.requester_node_id === null)
+        return undefined;
+    return { label: disposition === 'human-answer' ? 'human request answered' : 'human request canceled', disposition, body_json: bodyJson };
 }
-async function deliverOrConflict(ticketId) {
-    try {
-        await deliverTerminalResult(ticketId);
-    }
-    catch (error) {
-        throw deliveryFailed(error);
-    }
-    throw new ApiError(409, 'ticket_already_resolved', 'ticket already resolved');
+function retire(request) {
+    return request.companion_node_id === null ? undefined : { retire: async (nodeId, outcome) => { await retireCompanion(nodeId, outcome); } };
 }
-/**
- * The one completion path for a page ticket: claim takeover, exclusive result
- * publication, then optional reply delivery. Every addressing surface routes
- * through this function, so the reply-route descriptor is the sole authority
- * on whether completion reaches a bridge.
- */
+/** Settle a page request directly in human_requests; result files and bridge nodes are not part of this path. */
 export async function resolvePageTicket(ticketId, responses, opts = {}) {
-    const completed = takeoverAndCompletePage(ticketDir(ticketId), responses, { host: 'crtrd', pid: process.pid }, opts);
-    if (!completed.won)
-        return deliverOrConflict(ticketId);
-    releaseActionDelivery(ticketId);
-    try {
-        await deliverTerminalResult(ticketId);
-    }
-    catch (error) {
-        throw deliveryFailed(error);
-    }
-    return completed.result;
+    const request = requestForTicket(ticketId);
+    const page = manifest(request);
+    const parsedResponses = validateFinalPageResponses(page, responses);
+    const result = {
+        schema: 'crtr.page-response/v1', kind: 'page', responses: parsedResponses,
+        summary: buildPageSummary(page, parsedResponses), completedAt: opts.completedAt ?? new Date().toISOString(),
+        ...(opts.actor === undefined ? {} : { actor: opts.actor }),
+    };
+    const settled = await settleHumanRequest({
+        request_id: request.request_id,
+        outcome: 'answered',
+        result_json: JSON.stringify(result),
+        ...(notification(request, 'human-answer', result) === undefined ? {} : { notification: notification(request, 'human-answer', result) }),
+        ...(completionAction(request, result) === undefined ? {} : { completion_action: completionAction(request, result) }),
+        ...(retire(request) === undefined ? {} : { post_commit: retire(request) }),
+    });
+    if (settled.outcome === 'already_settled') {
+        if (settled.request.result_json === null)
+            throw new Error(`settled page request lacks a result: ${request.request_id}`);
+        return JSON.parse(settled.request.result_json);
+    }
+    return result;
 }
-/** Cancel a ticket with the store's first-writer-wins publication. */
 export async function cancelHumanTicket(ticketId, opts) {
-    const canceled = cancelTicket(ticketDir(ticketId), opts);
-    if (canceled.status === 'already_resolved')
-        return deliverOrConflict(ticketId);
-    releaseActionDelivery(ticketId);
-    try {
-        await deliverTerminalResult(ticketId);
-    }
-    catch (error) {
-        throw deliveryFailed(error);
-    }
-    return canceled.result;
+    const request = requestForTicket(ticketId);
+    const at = new Date().toISOString();
+    const result = {
+        schema: 'humanloop.cancel/v1', kind: 'canceled', canceledAt: at,
+        ...(opts.reason === undefined ? {} : { reason: opts.reason }),
+        ...(opts.actor === undefined ? {} : { actor: opts.actor }),
+        ...(opts.disposition === undefined ? {} : { disposition: opts.disposition }),
+    };
+    const settled = await settleHumanRequest({
+        request_id: request.request_id,
+        outcome: opts.disposition === 'dismissed' ? 'dismissed' : 'canceled',
+        result_json: JSON.stringify(result),
+        ...(notification(request, 'human-canceled', result) === undefined ? {} : { notification: notification(request, 'human-canceled', result) }),
+        ...(completionAction(request, result) === undefined ? {} : { completion_action: completionAction(request, result) }),
+        ...(retire(request) === undefined ? {} : { post_commit: retire(request) }),
+    });
+    if (settled.outcome === 'already_settled') {
+        if (settled.request.result_json === null)
+            throw new Error(`settled page request lacks a result: ${request.request_id}`);
+        return JSON.parse(settled.request.result_json);
+    }
+    return result;
 }
-/** Schedule the settled request's completion action, if it bound one. Only the
- * settlement winner calls this; the daemon-start sweep replays it for a
- * settlement that died before enqueueing, and the insert is idempotent on the
- * request id so neither path can create a second delivery. */
-export function releaseActionDelivery(ticketId) {
-    try {
-        const dir = ticketDir(ticketId);
-        const binding = readTicketActionBinding(dir);
-        if (binding === null)
-            return;
-        const result = readTicketResult(dir);
-        if (result === null || result.kind === 'review')
-            return;
-        const requestId = opaqueInboxTicketId(ticketId);
-        enqueueActionDelivery({
-            requestId,
-            argv: binding.argv,
-            cwd: binding.cwd,
-            completion: composeHumanCompletion({ requestId, result, binding, source: pageSource(dir) }),
-        });
-    }
-    catch (error) {
-        // The canonical outcome is already durable; the sweep replays this.
-        emitEvent({ level: 'error', event: 'human.action_delivery.enqueue_failed', node_id: ticketId, error });
-    }
-}
-function pageSource(dir) {
-    try {
-        return parsePage(dir).source ?? {};
-    }
-    catch {
-        return {};
-    }
-}
-/**
- * Deliver a terminal ticket result to its bridge. The canonical response is the
- * receipt: every action below is replay-safe, so lost delivery can be retried
- * by a later resolve/cancel attempt or the daemon-start sweep.
- */
+/** Legacy callers use this as a replay hook. Settlement effects are repaired by sweepHumanRequests. */
 export async function deliverTerminalResult(ticketId) {
-    const dir = ticketDir(ticketId);
-    const result = readTicketResult(dir);
-    if (result === null)
-        return false;
-    // Companion retirement rides the committed result, BEFORE the reply-route
-    // gate: every ticket-ending path (resolve, cancel, conflict replay) funnels
-    // through here, and an inbox-only page with no reply bridge still settles
-    // its companion. The daemon-start sweep settles the tickets that die before
-    // reaching this call.
-    await settleFeedbackCompanion(ticketId, result.kind === 'canceled' ? 'canceled' : 'approved');
-    const replyRoute = readTicketReplyRoute(dir);
-    if (replyRoute === null)
-        return false;
-    const bridgeNodeId = replyRoute.bridge_node_id;
-    projectReviewOutput(dir);
-    // The ROW, not node metadata: a bridge whose row has been pruned may retain
-    // its ticket files, but no lifecycle target remains. No row means nothing is
-    // left to deliver to.
-    const node = getRow(bridgeNodeId);
-    if (node === null || node.status === 'dead' || node.status === 'canceled' || (node.status === 'done' && node.final_report !== null)) {
-        return true;
-    }
-    if (result.kind === 'canceled') {
-        const title = pageTitle(dir);
-        const reason = result.reason !== undefined && result.reason !== '' ? result.reason : 'no reason was given';
-        // A dismissal is a rejection, not a routing event: say so plainly so the
-        // agent acts on the "no" instead of re-raising the same ask.
-        const dismissed = completionEventFor(result) === 'dismissed';
-        const subject = dismissed
-            ? (title === undefined ? `human interaction ${ticketId} dismissed without answering` : `human interaction ${ticketId} — “${title}” dismissed without answering`)
-            : (title === undefined ? `human interaction ${ticketId} canceled — no answer is coming` : `human interaction ${ticketId} — “${title}” canceled, no answer is coming`);
-        // Dismissal and withdrawal are settlement paths too: the sender still
-        // needs any unresolved feedback and the exceptional page-change notice.
-        const body = (dismissed
-            ? `The user dismissed ${title === undefined ? `the human interaction ${ticketId}` : `“${title}”`} without answering — a deliberate “no, I'm not answering this.” Treat it as a rejection: no response will arrive, no partial answer exists, and the same ask must not be raised again.`
-            : (title === undefined ? `The human interaction ${ticketId} was canceled — ${reason}. No response will arrive, and any partial answers the user had entered were discarded unsent.` : `The page “${title}” was canceled — ${reason}. No response will arrive, and any partial answers the user had entered were discarded unsent.`)) + feedbackAddendum(dir);
-        // One failing subscriber must not silence the rest, and the bridge stays
-        // live until every notice lands: a partial fanout leaves the ticket for the
-        // next resolve/cancel attempt or the daemon-start sweep to replay. A
-        // subscriber notified twice reads the same idempotent "no answer is coming";
-        // a subscriber never notified waits forever.
-        const failedTo = [];
-        for (const subscriber of subscribersOf(bridgeNodeId)) {
-            if (result.actor !== undefined && subscriber.node_id === result.actor)
-                continue;
-            try {
-                appendInbox(subscriber.node_id, {
-                    from: bridgeNodeId,
-                    tier: 'normal',
-                    kind: 'message',
-                    label: subject,
-                    data: { body },
-                    disposition: 'human-canceled',
-                });
-                cancelCronsOnWake(subscriber.node_id);
-            }
-            catch {
-                failedTo.push(subscriber.node_id);
-            }
-        }
-        if (failedTo.length > 0)
-            throw new Error(`cancellation notice failed for ${failedTo.join(', ')}`);
-        // Parking the bridge done is the cancellation's END STATE, not a step it
-        // owes: a bridge already done — parked by an earlier cancel replay, or by a
-        // close that finished it while the page was still pending — is already
-        // there, and `finish` is illegal from done. Re-running it would turn a
-        // recorded, delivered cancellation into delivery_failed and make every
-        // retry repeat that error.
-        if (node.status !== 'done')
-            transition(bridgeNodeId, 'finish');
-        return true;
-    }
-    if (result.kind === 'page') {
-        const answer = renderPageAnswer(dir, result, responsePath(dir));
-        if (answer.feedback !== undefined)
-            await pushUpdate(bridgeNodeId, answer.feedback);
-        await pushFinal(bridgeNodeId, answer.body, answer.disposition === undefined ? undefined : { disposition: answer.disposition });
-    }
-    return true;
+    const request = requestForTicket(ticketId);
+    return request.state === 'settled';
+}
+export async function settleFeedbackCompanion(ticketId, outcome) {
+    const request = requestForTicket(ticketId);
+    if (request.companion_node_id !== null)
+        await retireCompanion(request.companion_node_id, outcome);
 }

package/dist/daemon/human/settle.d.ts

@@ -0,0 +1,40 @@
+import { type ExternalActionAdapter } from '../../core/feed/messages.js';
+import { type HumanRequestOutcome, type HumanRequestRecord } from '../../core/human/requests.js';
+export interface SettleHumanRequestInput {
+    request_id: string;
+    outcome: HumanRequestOutcome;
+    result_json: string;
+    settled_at?: string;
+    notification?: {
+        label: string;
+        disposition: string;
+        body_ref?: string;
+        body_json?: unknown;
+    };
+    completion_action?: {
+        destinationId: string;
+        adapter: ExternalActionAdapter;
+        bodyJson: unknown;
+    };
+    post_commit?: {
+        project?: (request: HumanRequestRecord) => Promise<void> | void;
+        retire?: (companionNodeId: string, outcome: 'approved' | 'canceled') => Promise<void>;
+    };
+}
+export type SettleHumanRequestOutcome = {
+    outcome: 'settled';
+    request: HumanRequestRecord;
+} | {
+    outcome: 'already_settled';
+    request: HumanRequestRecord;
+};
+/**
+ * The only terminal transition. The conditional update is first-writer-wins;
+ * the winner's result and every obligation are committed in the same canvas write.
+ */
+export declare function settleHumanRequest(input: SettleHumanRequestInput): Promise<SettleHumanRequestOutcome>;
+/** Projection and companion retirement happen after settlement because filesystem and node lifecycle cannot join SQLite. */
+export declare function projectAndRetire(request: HumanRequestRecord, effects: {
+    project?: (request: HumanRequestRecord) => Promise<void> | void;
+    retire?: (companionNodeId: string, outcome: 'approved' | 'canceled') => Promise<void>;
+}): Promise<void>;

package/dist/daemon/human/settle.js

@@ -0,0 +1,89 @@
+import { withCanvasWrite } from '../../core/canvas/db.js';
+import { cancelDelivery, enqueueExternalAction, enqueueNodeMail, } from '../../core/feed/messages.js';
+import { getRequest, markCompanionRetired, markProjected, markProjectionError, setSettlementDeliveryMarksLocked, settleRequestLocked, } from '../../core/human/requests.js';
+/**
+ * The only terminal transition. The conditional update is first-writer-wins;
+ * the winner's result and every obligation are committed in the same canvas write.
+ */
+export async function settleHumanRequest(input) {
+    const committed = withCanvasWrite((db) => {
+        const settledAt = input.settled_at ?? new Date().toISOString();
+        const won = settleRequestLocked(db, {
+            request_id: input.request_id,
+            outcome: input.outcome,
+            result_json: input.result_json,
+            settled_at: settledAt,
+        });
+        if (won === null) {
+            const winner = getRequest(input.request_id);
+            if (winner === null)
+                throw new Error(`human request disappeared while settling: ${input.request_id}`);
+            return { outcome: 'already_settled', request: winner };
+        }
+        if (won.requester_node_id !== null && input.notification === undefined) {
+            throw new Error(`request ${won.request_id} needs a requester notification`);
+        }
+        if (won.action_json !== null && won.kind === 'page' && input.completion_action === undefined) {
+            throw new Error(`request ${won.request_id} needs its frozen completion action`);
+        }
+        if (won.kind === 'review' && won.projected_at === null && input.post_commit?.project === undefined) {
+            throw new Error(`review ${won.request_id} needs a projection effect`);
+        }
+        if (won.companion_node_id !== null && won.companion_retired_at === null && input.post_commit?.retire === undefined) {
+            throw new Error(`request ${won.request_id} needs a companion retirement effect`);
+        }
+        let settlementDeliveryId = null;
+        let actionDeliveryId = null;
+        if (won.requester_node_id !== null) {
+            const notification = input.notification;
+            if (notification === undefined)
+                throw new Error(`request ${won.request_id} needs a requester notification`);
+            settlementDeliveryId = enqueueNodeMail(won.requester_node_id, {
+                kind: 'completed', label: notification.label, senderName: 'crtrd',
+                ...(notification.body_ref === undefined ? {} : { bodyRef: notification.body_ref }),
+                ...(notification.body_json === undefined ? {} : { bodyJson: notification.body_json }),
+                disposition: notification.disposition === 'human-answer' ? 'human-answer' : 'human-canceled', urgency: 'normal', wake: 1,
+            }).deliveryId;
+        }
+        if (won.action_json !== null && input.completion_action !== undefined && won.kind === 'page') {
+            actionDeliveryId = enqueueExternalAction({
+                ...input.completion_action,
+                idempotencyKey: `human-action:${won.inbox_ticket_id}`,
+            }).deliveryId;
+        }
+        if (won.submit_note_delivery_id !== null)
+            cancelDelivery(won.submit_note_delivery_id);
+        setSettlementDeliveryMarksLocked(db, won.request_id, {
+            settlement_delivery_id: settlementDeliveryId,
+            action_delivery_id: actionDeliveryId,
+        });
+        const request = getRequest(won.request_id);
+        if (request === null)
+            throw new Error(`settled human request disappeared: ${won.request_id}`);
+        return { outcome: 'settled', request };
+    });
+    if (committed.outcome === 'settled' && input.post_commit !== undefined)
+        await projectAndRetire(committed.request, input.post_commit);
+    return committed;
+}
+/** Projection and companion retirement happen after settlement because filesystem and node lifecycle cannot join SQLite. */
+export async function projectAndRetire(request, effects) {
+    if (request.kind === 'review' && request.projected_at === null && effects.project !== undefined) {
+        try {
+            await effects.project(request);
+            markProjected(request.request_id, new Date().toISOString());
+        }
+        catch (error) {
+            markProjectionError(request.request_id, error instanceof Error ? error.message : String(error));
+        }
+    }
+    if (request.companion_node_id !== null && request.companion_retired_at === null && effects.retire !== undefined) {
+        try {
+            await effects.retire(request.companion_node_id, request.outcome === 'canceled' || request.outcome === 'dismissed' ? 'canceled' : 'approved');
+            markCompanionRetired(request.request_id, new Date().toISOString());
+        }
+        catch {
+            // The durable NULL mark is the authoritative retry obligation for the sweep.
+        }
+    }
+}

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

@@ -1,6 +1,21 @@
-/** Deliver terminal ticket results left behind before their bridge could finish. */
-export declare function reconcileUndeliveredTickets(): Promise<{
-    scanned: number;
-    delivered: number;
+import { type HumanRequestRecord } from '../../core/human/requests.js';
+export interface HumanRequestSweepEffects {
+    realizeReview(requestId: string): Promise<HumanRequestRecord>;
+    projectReview(request: HumanRequestRecord): Promise<void> | void;
+    retireCompanion(nodeId: string, outcome: 'approved' | 'canceled'): Promise<void>;
+}
+export interface HumanRequestSweepResult {
+    realized: number;
+    collected: number;
+    reprojected: number;
+    retired: number;
     failed: number;
-}>;
+}
+/**
+ * The one startup repair pass for SQL-authoritative pages and reviews. It does
+ * not infer a missing notification or action delivery: settlement created both
+ * atomically. The two remaining filesystem effects retain their durable marks.
+ */
+/** Direct outbox rows are created in the settlement transaction; there is no separate ticket-delivery repair pass. */
+export declare function reconcileUndeliveredTickets(): Promise<void>;
+export declare function sweepHumanRequests(effects: HumanRequestSweepEffects): Promise<HumanRequestSweepResult>;