@north-light/crouter 0.3.170 → 0.3.172

package/dist/daemon/api/handlers/inbox.js

@@ -1,99 +1,72 @@
-// Humanloop inbox handlers — crtrd `/v1/human/inbox` (Northlight crouter-inbox
-// v1, inbox-contract.md §A). Separate from `handlers/human.ts`: that file owns
-// bridge creation and completion-handler forwarding (`_deliver`/`_consult`/
-// `_visual`), while this table is a public ticket-serving resource with
-// different DTOs and error behavior — enumerate, read, respond, cancel.
+// Ticket inbox handlers — crtrd `/v1/human/inbox` (Northlight crouter-inbox
+// v1, inbox-contract.md §A). This public ticket-serving resource enumerates,
+// reads, responds to, and cancels tickets while preserving its product DTOs.
 //
-// Only `listInboxRoots()` entries with `owner === 'crouter'` and
-// `available === true` are ever exposed. Every ticket is addressed on the wire
-// by an opaque, stable id: lowercase SHA-256 hex of
-// `canonicalRoot + "\0" + ticketBasename` — never a `TicketSummary.dir`, review
-// `file`/`output`, claim owner/heartbeat, or any other host path/process
-// metadata. Humanloop remains authoritative for validation, persistence,
-// claims, terminal results, and completion delivery: submit composes
-// `claimTicket` + `completeDeck`; cancel composes `cancelTicket`. Neither is
-// reimplemented here.
+// Every ticket is addressed on the wire by an opaque, stable id: lowercase
+// SHA-256 hex of `canonicalRoot + "\0" + ticketBasename`. The wire never exposes
+// a ticket directory, review file/output, claim owner/heartbeat, or other host
+// path or process metadata. The daemon's shared ticket finish path owns claims,
+// terminal publication, and bridge delivery.
 import { createHash } from 'node:crypto';
 import { existsSync, readdirSync, realpathSync, statSync } from 'node:fs';
-import { basename, dirname, resolve } from 'node:path';
+import { basename, resolve } from 'node:path';
 import { ApiError } from '../../../api/index.js';
-import { cancelTicket, claimTicket, completeDeck, deckPath, listInboxRoots, parseDeck, readTicketResult, releaseClaim, reviewPath, scanInbox, } from '@crouton-kit/humanloop';
+import { deckPath, readJson, reviewPath } from '../../../core/human/convention.js';
+import { parseDeck } from '../../../core/human/deck-schema.js';
+import { ticketsRoot } from '../../../core/human/root.js';
+import { scanInbox } from '../../../core/human/scan.js';
+import { readTicketResult } from '../../../core/human/tickets.js';
+import { getReviewByBridge } from '../../../core/review/store.js';
+import { ReviewOperationError } from '../../../core/review/types.js';
+import { cancelHumanTicket, resolveDeckTicket } from '../../human/finish.js';
+import { cancelReview } from '../../review/finish.js';
+import { filterTerminalReviewTickets } from '../../../core/review/ticket-filter.js';
 const DEFAULT_CANCEL_REASON = 'Canceled from the inbox.';
 const CANCEL_REASON_MAX = 1000;
 const TICKET_ID_PATTERN = /^[a-f0-9]{64}$/;
 // ===========================================================================
 // Opaque ticket id resolution
 // ===========================================================================
-/** Every currently available crouter-owned humanloop root, canonical. A
- *  registered root's pathname can be replaced out from under it (removed,
- *  then recreated as a symlink to an unrelated directory) after registration.
- *  `available` only checks `existsSync(record.root)`, which follows a
- *  symlink and is satisfied by whatever the new target is — so it alone is
- *  not proof the pathname still names the same canonical directory that was
- *  registered. Require `realpathSync(record.root) === record.root`: since
- *  `record.root` was itself produced by `realpathSync` at registration time,
- *  this only holds while the pathname's canonical identity is unchanged. A
- *  replaced/symlinked registered pathname therefore confers no authority. */
-function crouterRoots() {
-    return listInboxRoots()
-        .filter((r) => r.owner === 'crouter' && r.available)
-        .map((r) => r.root)
-        .filter((root) => {
-        try {
-            return realpathSync(root) === root;
-        }
-        catch {
-            return false;
-        }
-    });
-}
+/** Opaque ids hash the canonical derived tickets root and ticket basename. */
 function ticketHash(canonicalRoot, ticketBasename) {
     return createHash('sha256').update(`${canonicalRoot}\0${ticketBasename}`, 'utf8').digest('hex');
 }
-/** Resolve an opaque `ticket_id` against canonical direct-child directories of
- *  currently available crouter-owned roots ONLY. Includes already-resolved
- *  directories (so a stale client gets `ticket_already_resolved`, not an
- *  ambiguous not-found) but never a symlink or directory outside a canonical
- *  registered root, and never a directory with no deck/review protocol state
- *  at all (not a real ticket). */
+/** Resolve an opaque id against the single tickets root. Includes terminal
+ * tickets so a stale client receives the stable already-resolved response. */
 function resolveTicket(ticketId) {
-    for (const rawRoot of crouterRoots()) {
-        let canonicalRoot;
-        try {
-            canonicalRoot = realpathSync(rawRoot);
-        }
-        catch {
+    let canonicalRoot;
+    try {
+        canonicalRoot = realpathSync(ticketsRoot());
+    }
+    catch {
+        return null;
+    }
+    let entries;
+    try {
+        entries = readdirSync(canonicalRoot);
+    }
+    catch {
+        return null;
+    }
+    for (const entry of entries) {
+        if (ticketHash(canonicalRoot, entry) !== ticketId)
             continue;
-        }
-        let entries;
+        const candidate = resolve(canonicalRoot, entry);
+        let canonicalDir;
         try {
-            entries = readdirSync(canonicalRoot);
+            if (!statSync(candidate).isDirectory())
+                continue;
+            canonicalDir = realpathSync(candidate);
         }
         catch {
             continue;
         }
-        for (const entry of entries) {
-            if (ticketHash(canonicalRoot, entry) !== ticketId)
-                continue;
-            const candidate = resolve(canonicalRoot, entry);
-            let canonicalDir;
-            try {
-                if (!statSync(candidate).isDirectory())
-                    continue;
-                canonicalDir = realpathSync(candidate);
-            }
-            catch {
-                continue;
-            }
-            if (resolve(canonicalDir, '..') !== canonicalRoot)
-                continue;
-            if (basename(canonicalDir) !== entry)
-                continue;
-            if (existsSync(deckPath(canonicalDir)))
-                return { dir: canonicalDir, kind: 'deck' };
-            if (existsSync(reviewPath(canonicalDir)))
-                return { dir: canonicalDir, kind: 'review' };
-        }
+        if (resolve(canonicalDir, '..') !== canonicalRoot || basename(canonicalDir) !== entry)
+            continue;
+        if (existsSync(deckPath(canonicalDir)))
+            return { nodeId: entry, dir: canonicalDir, kind: 'deck' };
+        if (existsSync(reviewPath(canonicalDir)))
+            return { nodeId: entry, dir: canonicalDir, kind: 'review' };
     }
     return null;
 }
@@ -115,8 +88,6 @@ function toDeckSourceDTO(source) {
         dto.askedBy = source.askedBy;
     if (source.blockedSince !== undefined)
         dto.blockedSince = source.blockedSince;
-    if (source.visual !== undefined)
-        dto.visual = source.visual;
     return dto;
 }
 function toOptionDTO(option) {
@@ -153,8 +124,7 @@ function toDeckDTO(deck) {
     return dto;
 }
 function toTicketSummaryDTO(item) {
-    const root = dirname(item.dir);
-    const ticket_id = ticketHash(root, item.id);
+    const ticket_id = ticketHash(realpathSync(ticketsRoot()), item.id);
     const source = toDeckSourceDTO(item.source);
     if (item.kind === 'review') {
         const dto = {
@@ -182,8 +152,8 @@ function toTicketSummaryDTO(item) {
 // ===========================================================================
 // Request-body validation — structural only. Semantic response↔deck
 // validation (option ids, single/multi-select shape, freetext permission,
-// option comments, required notify acknowledgement) is humanloop's via
-// `completeDeck`/`finalizeDeck`; a structural violation here is
+// option comments, required notify acknowledgement) belongs to the ticket
+// store via the daemon finish path; a structural violation here is
 // `invalid_request`, a semantic rejection there is `invalid_ticket_response`.
 // ===========================================================================
 function isPlainObject(value) {
@@ -258,7 +228,7 @@ function validateCancelRequest(raw) {
 // GET /v1/human/inbox — enumerate
 // ===========================================================================
 function handleList() {
-    const items = scanInbox(crouterRoots());
+    const items = filterTerminalReviewTickets(scanInbox());
     // `blocked_since` is an RFC 3339 timestamp that may carry a non-`Z` offset;
     // two offsets are not lexically comparable (`+14:00` can sort after `Z`
     // while naming an earlier instant), so sort by parsed instant and use the
@@ -303,8 +273,8 @@ function handleGetDeck(ctx) {
 // ===========================================================================
 // POST /v1/human/inbox/:ticket_id/respond — submit
 // ===========================================================================
-// The exhaustive set of messages humanloop's `validateDeckResponses`
-// (`finalizeDeck` → `completeDeck`) throws for a genuine response-shape
+// The exhaustive set of messages the ticket store's response validator throws
+// for a genuine response-shape
 // rejection — duplicate/unknown interaction id, invalid single/multi-select
 // shape, disallowed freetext, invalid option comments, or a missing required
 // notify acknowledgement. None of these ever carry a filesystem path (only
@@ -324,6 +294,18 @@ const RESPONSE_VALIDATION_MESSAGE_PATTERNS = [
 function isResponseValidationError(err) {
     return err instanceof Error && RESPONSE_VALIDATION_MESSAGE_PATTERNS.some((pattern) => pattern.test(err.message));
 }
+function coerceSingleSelect(responses, dir) {
+    const deck = readJson(deckPath(dir));
+    if (deck === null)
+        return responses;
+    const multiSelect = new Map(deck.interactions.map((interaction) => [interaction.id, interaction.multiSelect === true]));
+    return responses.map((response) => {
+        if (multiSelect.get(response.id) === true || response.selectedOptionId !== undefined || response.selectedOptionIds?.length !== 1)
+            return response;
+        const { selectedOptionIds: _selectedOptionIds, ...rest } = response;
+        return { ...rest, selectedOptionId: response.selectedOptionIds[0] };
+    });
+}
 async function handleRespond(ctx) {
     const ticketId = requireTicketId(ctx.params);
     const request = validateRespondRequest(ctx.body);
@@ -331,57 +313,28 @@ async function handleRespond(ctx) {
     if (resolved === null)
         throw new ApiError(404, 'ticket_not_found', 'no matching ticket');
     if (resolved.kind === 'review') {
-        throw new ApiError(409, 'ticket_kind_unsupported', 'review tickets have no v1 response operation');
+        throw new ApiError(409, 'ticket_kind_unsupported', 'review tickets submit through POST /v1/human/reviews/:id/submit');
     }
     if (readTicketResult(resolved.dir) !== null) {
         throw new ApiError(409, 'ticket_already_resolved', 'ticket was already resolved');
     }
-    // Short-lived server-owned claim, exactly across this synchronous
-    // validate/finalize call — never exposed, persisted separately, or
-    // heartbeated (inbox-contract.md §A).
-    const claim = claimTicket(resolved.dir, { host: 'crtrd' });
-    if (claim === null) {
-        // `claimTicket` returns null both when a live foreign claim already owns
-        // the ticket AND when the ticket resolved between the precheck above and
-        // this call (a real cross-process race: another actor's cancel/respond
-        // won in that window). Reread the terminal result to disambiguate — a
-        // resolution in that window must report `ticket_already_resolved`, never
-        // the foreign-claim code.
-        if (readTicketResult(resolved.dir) !== null) {
-            throw new ApiError(409, 'ticket_already_resolved', 'ticket was already resolved');
-        }
-        throw new ApiError(409, 'ticket_unavailable', 'ticket is claimed by another live session');
-    }
-    let completed;
     try {
-        completed = await completeDeck(resolved.dir, request.responses, claim.token);
+        const result = await resolveDeckTicket(resolved.nodeId, coerceSingleSelect(request.responses, resolved.dir));
+        if (result.kind !== 'deck')
+            throw new ApiError(409, 'ticket_already_resolved', 'ticket was already resolved');
+        return { status: 200, body: result };
     }
-    catch (err) {
-        // `finalizeDeck` only releases the claim once validation succeeds
-        // (`clearOwnedWork` runs after `validateDeckResponses`); a throw here
-        // leaves it held under a `host:'crtrd'` claim that this same live daemon
-        // process would otherwise treat as non-stale forever. Release it
-        // explicitly so the ticket remains claimable by the next attempt.
-        try {
-            releaseClaim(resolved.dir, claim.token);
-        }
-        catch {
-            /* best-effort cleanup */
-        }
-        // Only a demonstrated response-shape rejection becomes 400
-        // `invalid_ticket_response` with its message forwarded. Everything else
-        // (a malformed stored deck re-read during finalize, a lock/dispatch/
-        // filesystem error) is sanitized to 500 `internal` — its raw cause,
-        // which can carry a host path, must never reach the wire.
-        if (isResponseValidationError(err)) {
-            throw new ApiError(400, 'invalid_ticket_response', err.message);
+    catch (error) {
+        // The daemon's terminal errors are public protocol outcomes: preserve both
+        // their code and message so Northlight can distinguish conflict from a
+        // recorded-but-undelivered answer.
+        if (error instanceof ApiError)
+            throw error;
+        if (isResponseValidationError(error)) {
+            throw new ApiError(400, 'invalid_ticket_response', error.message);
         }
         throw new ApiError(500, 'internal', 'the ticket could not be finalized');
     }
-    if (!completed.won || completed.result.kind !== 'deck') {
-        throw new ApiError(409, 'ticket_already_resolved', 'ticket was already resolved');
-    }
-    return { status: 200, body: completed.result };
 }
 // ===========================================================================
 // POST /v1/human/inbox/:ticket_id/cancel — cancel
@@ -392,28 +345,46 @@ async function handleCancel(ctx) {
     const resolved = resolveTicket(ticketId);
     if (resolved === null)
         throw new ApiError(404, 'ticket_not_found', 'no matching ticket');
-    if (resolved.kind === 'review') {
-        throw new ApiError(409, 'ticket_kind_unsupported', 'review tickets have no v1 cancel operation');
-    }
-    // Cancel never requires, steals, or clears another humanloop claim — this
-    // is the existing humanloop cancellation convention (first-writer-wins).
-    let canceled;
     try {
-        canceled = await cancelTicket(resolved.dir, {
+        if (resolved.kind === 'review') {
+            const review = getReviewByBridge(resolved.nodeId);
+            if (review !== null) {
+                if (review.state === 'approved') {
+                    throw new ApiError(409, 'ticket_already_resolved', 'ticket was already resolved');
+                }
+                const finished = await cancelReview(review.review_id, {
+                    reason: request.reason ?? DEFAULT_CANCEL_REASON,
+                    actor: 'human',
+                });
+                if (finished.outcome === 'already_settled') {
+                    throw new ApiError(409, 'ticket_already_resolved', 'ticket was already resolved');
+                }
+                if (finished.ticket_result?.kind !== 'canceled') {
+                    throw new Error('canonical review cancellation did not produce a ticket result');
+                }
+                return { status: 200, body: finished.ticket_result };
+            }
+        }
+        const result = await cancelHumanTicket(resolved.nodeId, {
             reason: request.reason ?? DEFAULT_CANCEL_REASON,
             actor: 'human',
         });
+        if (result.kind !== 'canceled')
+            throw new ApiError(409, 'ticket_already_resolved', 'ticket was already resolved');
+        return { status: 200, body: result };
     }
-    catch {
-        // A lock/filesystem/dispatch failure here is not a request-shape problem;
-        // sanitize it rather than letting its raw cause (which can carry a host
-        // path) reach the wire through the router's generic mapper.
+    catch (error) {
+        if (error instanceof ApiError)
+            throw error;
+        // Review errors are canonical lifecycle vocabulary, not ticket protocol.
+        // A concurrent terminal winner is the same public ticket conflict.
+        if (error instanceof ReviewOperationError) {
+            throw new ApiError(409, 'ticket_already_resolved', 'ticket was already resolved');
+        }
+        // A lock/filesystem/delivery failure is not a request-shape problem; do
+        // not leak its cause through the generic router mapper.
         throw new ApiError(500, 'internal', 'the ticket could not be canceled');
     }
-    if (canceled.status === 'already_resolved' || canceled.result.kind !== 'canceled') {
-        throw new ApiError(409, 'ticket_already_resolved', 'ticket was already resolved');
-    }
-    return { status: 200, body: canceled.result };
 }
 export const inboxRoutes = [
     { method: 'GET', pattern: '/v1/human/inbox', handler: handleList },

package/dist/daemon/api/handlers/review-comments.d.ts

@@ -0,0 +1,2 @@
+import type { RouteTable } from '../router.js';
+export declare const reviewCommentRoutes: RouteTable;