@north-light/crouter 0.3.170 → 0.3.172

package/dist/core/human/deck-schema.d.ts

@@ -0,0 +1,70 @@
+import { z } from 'zod';
+import type { Deck, ReviewDescriptor } from './types.js';
+export declare const interactionOptionSchema: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const preAnswerSchema: z.ZodObject<{
+    selectedOptionId: z.ZodOptional<z.ZodString>;
+    selectedOptionIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    freetext: z.ZodOptional<z.ZodString>;
+    label: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const deckSchema: z.ZodObject<{
+    title: z.ZodString;
+    source: z.ZodOptional<z.ZodObject<{
+        sessionName: z.ZodOptional<z.ZodString>;
+        askedBy: z.ZodOptional<z.ZodString>;
+        blockedSince: z.ZodOptional<z.ZodString>;
+        nodeId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    interactions: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        subtitle: z.ZodString;
+        body: z.ZodOptional<z.ZodString>;
+        bodyPath: z.ZodOptional<z.ZodString>;
+        options: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            label: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        multiSelect: z.ZodOptional<z.ZodBoolean>;
+        allowFreetext: z.ZodOptional<z.ZodBoolean>;
+        freetextLabel: z.ZodOptional<z.ZodString>;
+        kind: z.ZodOptional<z.ZodEnum<{
+            error: "error";
+            context: "context";
+            notify: "notify";
+            review: "review";
+            decision: "decision";
+        }>>;
+        preAnswered: z.ZodOptional<z.ZodObject<{
+            selectedOptionId: z.ZodOptional<z.ZodString>;
+            selectedOptionIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            freetext: z.ZodOptional<z.ZodString>;
+            label: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const reviewDescriptorSchema: z.ZodObject<{
+    schema: z.ZodLiteral<"humanloop.review/v1">;
+    file: z.ZodString;
+    output: z.ZodString;
+    title: z.ZodString;
+    subtitle: z.ZodString;
+    source: z.ZodObject<{
+        sessionName: z.ZodOptional<z.ZodString>;
+        askedBy: z.ZodOptional<z.ZodString>;
+        blockedSince: z.ZodOptional<z.ZodString>;
+        nodeId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    blockedSince: z.ZodString;
+}, z.core.$strict>;
+export declare function resolveDeckBodyPaths(deck: Deck, dir: string): Deck;
+export declare function parseDeck(path: string): Deck;
+export declare function validateDeck(parsed: unknown): Deck;
+export declare function validateReviewDescriptor(parsed: unknown): ReviewDescriptor;
+/** Canonicalize and authorize the one review projection boundary before every write. */
+export declare function validateReviewProjection(dir: string, parsed: unknown): ReviewDescriptor;

package/dist/core/human/deck-schema.js

@@ -0,0 +1,92 @@
+import { existsSync, lstatSync, readFileSync, realpathSync } from 'node:fs';
+import { basename, dirname, isAbsolute, resolve, sep } from 'node:path';
+import { claimPath, deckPath, progressPath, responsePath, reviewPath } from './convention.js';
+import { z } from 'zod';
+import { INTERACTION_KINDS } from './types.js';
+import { checkMarkdown } from '../termrender/termrender.js';
+import { checkReviewableFile } from './visible-paths.js';
+export const interactionOptionSchema = z.object({ id: z.string().min(1), label: z.string().min(1), description: z.string().optional() });
+export const preAnswerSchema = z.object({ selectedOptionId: z.string().optional(), selectedOptionIds: z.array(z.string()).optional(), freetext: z.string().optional(), label: z.string().optional() });
+const interactionSchema = z.object({
+    id: z.string().regex(/^[A-Za-z0-9_-]+$/, { error: 'interaction id must match /^[A-Za-z0-9_-]+$/' }).min(1).max(64),
+    title: z.string().trim().min(1), subtitle: z.string().trim().min(1), body: z.string().optional(), bodyPath: z.string().optional(),
+    options: z.array(interactionOptionSchema), multiSelect: z.boolean().optional(), allowFreetext: z.boolean().optional(), freetextLabel: z.string().optional(), kind: z.enum(INTERACTION_KINDS).optional(), preAnswered: preAnswerSchema.optional(),
+});
+const deckSourceSchema = z.object({ sessionName: z.string().optional(), askedBy: z.string().optional(), blockedSince: z.string().optional(), nodeId: z.string().optional() });
+export const deckSchema = z.object({ title: z.string().trim().min(1), source: deckSourceSchema.optional(), interactions: z.array(interactionSchema).min(1) }).superRefine((input, ctx) => {
+    const seen = new Set();
+    input.interactions.forEach((interaction, index) => {
+        if (interaction.body !== undefined && interaction.bodyPath !== undefined)
+            ctx.addIssue({ code: 'custom', message: 'body and bodyPath are mutually exclusive', path: ['interactions', index] });
+        if (seen.has(interaction.id))
+            ctx.addIssue({ code: 'custom', message: `duplicate interaction id "${interaction.id}"`, path: ['interactions', index, 'id'] });
+        seen.add(interaction.id);
+    });
+});
+const reviewSourceSchema = deckSourceSchema;
+export const reviewDescriptorSchema = z.object({
+    schema: z.literal('humanloop.review/v1'),
+    file: z.string().min(1).refine(isAbsolute, 'file must be absolute'),
+    output: z.string().min(1).refine(isAbsolute, 'output must be absolute'),
+    title: z.string().trim().min(1),
+    subtitle: z.string().trim().min(1),
+    source: reviewSourceSchema,
+    blockedSince: z.string().datetime({ offset: true }),
+}).strict();
+function readBodyPathFile(dir, bodyPath) {
+    const joined = resolve(dir, bodyPath);
+    if (!existsSync(joined))
+        throw new Error(`bodyPath does not exist: '${bodyPath}'`);
+    if (!lstatSync(joined).isFile())
+        throw new Error(`bodyPath must be a regular file: ${bodyPath}`);
+    const realResolved = realpathSync(joined);
+    const realDeckDir = realpathSync(dir);
+    if (!realResolved.startsWith(realDeckDir + sep))
+        throw new Error(`bodyPath '${bodyPath}' escapes the deck directory`);
+    return readFileSync(joined, 'utf8');
+}
+export function resolveDeckBodyPaths(deck, dir) {
+    return { ...deck, interactions: deck.interactions.map((interaction) => {
+            if (interaction.bodyPath === undefined)
+                return interaction;
+            const { bodyPath: _bodyPath, ...rest } = interaction;
+            return { ...rest, body: readBodyPathFile(dir, interaction.bodyPath) };
+        }) };
+}
+export function parseDeck(path) {
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        throw new Error('deck is not valid JSON');
+    }
+    const deck = resolveDeckBodyPaths(deckSchema.parse(raw), dirname(path));
+    for (const interaction of deck.interactions)
+        if (interaction.body !== undefined) {
+            const check = checkMarkdown(interaction.body);
+            if (!check.ok)
+                throw new Error(check.error);
+        }
+    return deck;
+}
+export function validateDeck(parsed) { return deckSchema.parse(parsed); }
+export function validateReviewDescriptor(parsed) { return reviewDescriptorSchema.parse(parsed); }
+/** Canonicalize and authorize the one review projection boundary before every write. */
+export function validateReviewProjection(dir, parsed) {
+    const descriptor = validateReviewDescriptor(parsed);
+    // Any reviewable UTF-8 text file: a .md artifact renders as a document, a
+    // source file as a syntax-highlighted code panel.
+    if (!existsSync(descriptor.file))
+        throw new Error('review file must be an existing absolute path');
+    const reviewable = checkReviewableFile(descriptor.file);
+    if (!reviewable.ok)
+        throw new Error(`review file is not reviewable: ${reviewable.reason}`);
+    const file = realpathSync(descriptor.file);
+    const output = resolve(realpathSync(dirname(descriptor.output)), basename(descriptor.output));
+    const reserved = new Set(['deck.json', 'review.json', 'response.json', 'progress.json', 'claim.json']);
+    const ownProtocolPaths = new Set([deckPath(dir), reviewPath(dir), responsePath(dir), progressPath(dir), claimPath(dir)]);
+    if (output === file || reserved.has(basename(output)) || ownProtocolPaths.has(output))
+        throw new Error('review output must not alias the source or ticket protocol files');
+    return { ...descriptor, file, output };
+}

package/dist/core/human/root.d.ts

@@ -0,0 +1,7 @@
+export declare function ticketsRoot(): string;
+/** A ticket directory is the bridge node's canvas directory, the same path by construction. */
+export declare function ticketDir(nodeId: string): string;
+export declare function inboxActivityPath(): string;
+/** Signal one durable ticket mutation to every open inbox without watching every ticket directory. */
+export declare function signalInboxActivity(): void;
+export declare function watchInboxActivity(onChange: () => void): () => void;

package/dist/core/human/root.js

@@ -0,0 +1,37 @@
+import { mkdirSync, watch, writeFileSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { crtrHome, nodeDir, nodesRoot } from '../canvas/paths.js';
+export function ticketsRoot() {
+    return nodesRoot();
+}
+/** A ticket directory is the bridge node's canvas directory, the same path by construction. */
+export function ticketDir(nodeId) {
+    return nodeDir(nodeId);
+}
+export function inboxActivityPath() {
+    return join(crtrHome(), 'signals', 'inbox-activity');
+}
+/** Signal one durable ticket mutation to every open inbox without watching every ticket directory. */
+export function signalInboxActivity() {
+    try {
+        mkdirSync(dirname(inboxActivityPath()), { recursive: true, mode: 0o700 });
+        writeFileSync(inboxActivityPath(), `${Date.now()}\n`, { mode: 0o600 });
+    }
+    catch {
+        // A later inbox scan is still authoritative.
+    }
+}
+export function watchInboxActivity(onChange) {
+    const activityPath = inboxActivityPath();
+    try {
+        mkdirSync(dirname(activityPath), { recursive: true, mode: 0o700 });
+        const watcher = watch(dirname(activityPath), (_event, filename) => {
+            if (String(filename) === basename(activityPath))
+                onChange();
+        });
+        return () => watcher.close();
+    }
+    catch {
+        return () => { };
+    }
+}

package/dist/core/human/scan.d.ts

@@ -0,0 +1,3 @@
+import type { TicketSummary } from './types.js';
+/** Read all unresolved deck/review tickets, newest first. Progress never affects visibility. */
+export declare function scanInbox(): TicketSummary[];

package/dist/core/human/scan.js

@@ -0,0 +1,76 @@
+import { readdirSync, statSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { claimPath, deckPath, isResolved, readJson, reviewPath } from './convention.js';
+import { validateDeck, validateReviewDescriptor } from './deck-schema.js';
+import { ticketsRoot } from './root.js';
+function claimSummary(dir) {
+    const claim = readJson(claimPath(dir));
+    if (claim === null || typeof claim.host !== 'string' || typeof claim.claimedAt !== 'string' || typeof claim.heartbeatAt !== 'string')
+        return undefined;
+    return { owner: claim.host, claimedAt: claim.claimedAt, heartbeatAt: claim.heartbeatAt };
+}
+function deckSummary(dir, id) {
+    const raw = readJson(deckPath(dir));
+    if (raw === null)
+        return null;
+    let deck;
+    try {
+        deck = validateDeck(raw);
+    }
+    catch {
+        return null;
+    }
+    const first = deck.interactions[0];
+    if (first === undefined)
+        return null;
+    let blockedSince = deck.source?.blockedSince;
+    if (blockedSince === undefined) {
+        try {
+            blockedSince = statSync(deckPath(dir)).mtime.toISOString();
+        }
+        catch {
+            return null;
+        }
+    }
+    return { dir, id, kind: 'deck', title: deck.title, subtitle: first.subtitle, interactionKind: first.kind, interactionCount: deck.interactions.length, source: deck.source ?? {}, blockedSince, claim: claimSummary(dir) };
+}
+function reviewSummary(dir, id) {
+    const raw = readJson(reviewPath(dir));
+    if (raw === null)
+        return null;
+    let review;
+    try {
+        review = validateReviewDescriptor(raw);
+    }
+    catch {
+        return null;
+    }
+    return { dir, id, kind: 'review', title: review.title, subtitle: review.subtitle, file: review.file, output: review.output, source: review.source, blockedSince: review.blockedSince, claim: claimSummary(dir) };
+}
+/** Read all unresolved deck/review tickets, newest first. Progress never affects visibility. */
+export function scanInbox() {
+    let entries;
+    try {
+        entries = readdirSync(ticketsRoot());
+    }
+    catch {
+        return [];
+    }
+    const items = [];
+    for (const entry of entries) {
+        const dir = join(ticketsRoot(), entry);
+        try {
+            if (!statSync(dir).isDirectory())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        if (isResolved(dir))
+            continue;
+        const item = deckSummary(dir, basename(dir)) ?? reviewSummary(dir, basename(dir));
+        if (item !== null)
+            items.push(item);
+    }
+    return items.sort((a, b) => b.blockedSince.localeCompare(a.blockedSince) || a.id.localeCompare(b.id));
+}

package/dist/core/human/summary.d.ts

@@ -0,0 +1,8 @@
+import type { Deck, InteractionResponse } from './types.js';
+/**
+ * Deterministic, no-LLM resolution summary — one line per answered
+ * interaction: `"<title>: <option label>[ — <freetext>]"`. Shared by `ask()`
+ * (envelope summary) and `writeResponse` (persisted into response.json at write
+ * time).
+ */
+export declare function buildSummary(deck: Deck, responses: InteractionResponse[]): string;

package/dist/core/human/summary.js

@@ -0,0 +1,44 @@
+/**
+ * Deterministic, no-LLM resolution summary — one line per answered
+ * interaction: `"<title>: <option label>[ — <freetext>]"`. Shared by `ask()`
+ * (envelope summary) and `writeResponse` (persisted into response.json at write
+ * time).
+ */
+export function buildSummary(deck, responses) {
+    const byId = new Map(responses.map((r) => [r.id, r]));
+    const lines = [];
+    for (const it of deck.interactions) {
+        const r = byId.get(it.id);
+        if (r === undefined)
+            continue;
+        const ft = r.freetext !== undefined && r.freetext !== '' ? r.freetext : undefined;
+        let picked;
+        if (r.selectedOptionIds !== undefined) {
+            const oc = r.optionComments;
+            const parts = r.selectedOptionIds
+                .map((id) => it.options.find((o) => o.id === id))
+                .filter((o) => o !== undefined)
+                .map((o) => {
+                const note = oc !== undefined ? oc[o.id] : undefined;
+                return typeof note === 'string' && note.length > 0
+                    ? `${o.label} ("${note}")`
+                    : o.label;
+            });
+            picked = parts.length > 0 ? parts.join(', ') : undefined;
+        }
+        else if (r.selectedOptionId !== undefined) {
+            picked = it.options.find((o) => o.id === r.selectedOptionId)?.label;
+        }
+        let val;
+        if (picked !== undefined && ft !== undefined)
+            val = `${picked} — ${ft}`;
+        else if (picked !== undefined)
+            val = picked;
+        else if (ft !== undefined)
+            val = ft;
+        else
+            val = '(skipped)';
+        lines.push(`${it.title}: ${val}`);
+    }
+    return lines.join('\n');
+}

package/dist/core/human/tickets.d.ts

@@ -0,0 +1,49 @@
+import type { Deck, DeckTicketResult, ReviewDescriptor, TicketResult } from './types.js';
+/** Strict decoder for the only canonical final marker. */
+export declare function readTicketResult(dir: string): TicketResult | null;
+export interface SubmitDeckOptions {
+    dir: string;
+    deck: Deck;
+}
+export declare function submitDeck(opts: SubmitDeckOptions): {
+    id: string;
+    dir: string;
+    kind: 'deck';
+};
+export interface SubmitReviewOptions {
+    dir: string;
+    review: Omit<ReviewDescriptor, 'schema' | 'file' | 'output' | 'blockedSince'> & {
+        file: string;
+        output?: string;
+        blockedSince?: string;
+    };
+}
+export declare function submitReview(opts: SubmitReviewOptions): {
+    id: string;
+    dir: string;
+    kind: 'review';
+};
+/** Validate a deck resolution against its canonical ticket before claim takeover. */
+export declare function validateDeckTicketResponses(dir: string, responses: unknown): DeckTicketResult['responses'];
+export declare function completeDeck(dir: string, responses: DeckTicketResult['responses'], claimToken: string, completedAt?: string): {
+    won: boolean;
+    result: TicketResult;
+};
+/** Atomically take a ticket's claim over, complete it, and release the takeover claim. */
+export declare function takeoverAndCompleteDeck(dir: string, responses: DeckTicketResult['responses'], owner: {
+    host: string;
+    pid: number;
+}): {
+    won: boolean;
+    result: TicketResult;
+};
+/** Cancellation races finalization but never requires or removes another claim. */
+export declare function cancelTicket(dir: string, opts?: {
+    reason?: string;
+    actor?: string;
+}): {
+    status: 'canceled' | 'already_resolved';
+    result: TicketResult;
+};
+/** Write the validated review output once its review result is published. */
+export declare function projectReviewOutput(dir: string): 'projected' | 'not_a_review' | 'no_result';

package/dist/core/human/tickets.js

@@ -0,0 +1,190 @@
+import { existsSync, mkdirSync, readFileSync, realpathSync, unlinkSync, writeFileSync } from 'node:fs';
+import { basename, isAbsolute, resolve } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { z } from 'zod';
+import { buildSummary } from './summary.js';
+import { atomicWriteJson, clearProgress, claimPath, deckPath, progressPath, publishJsonExclusive, requireTicket, responsePath, reviewPath } from './convention.js';
+import { validateDeck, validateReviewDescriptor, validateReviewProjection, resolveDeckBodyPaths } from './deck-schema.js';
+import { signalInboxActivity } from './root.js';
+import { readTicketClaim, releaseClaimLocked, withTicketLock } from './claim.js';
+import { checkReviewableFile } from './visible-paths.js';
+const responseSchema = z.object({ id: z.string().min(1), selectedOptionId: z.string().optional(), selectedOptionIds: z.array(z.string()).optional(), freetext: z.string().optional(), optionComments: z.record(z.string(), z.string()).optional() }).strict();
+const feedbackCommentSchema = z.object({ id: z.string().min(1), line: z.number().int().positive(), endLine: z.number().int().positive(), quote: z.string().optional(), colStart: z.number().int().nonnegative().optional(), colEnd: z.number().int().nonnegative().optional(), lineText: z.string(), comment: z.string().min(1), createdAt: z.string().min(1) }).strict();
+const iso = z.string().datetime({ offset: true });
+const feedbackSchema = z.object({ file: z.string().min(1).refine(isAbsolute, 'file must be absolute').refine((file) => resolve(file) === file, 'file must be canonical'), submitted: z.literal(true), approved: z.boolean(), comments: z.array(feedbackCommentSchema), submittedAt: iso, savedAt: iso, reviewId: z.string().optional(), changed: z.boolean().optional(), baselineSha256: z.string().optional(), approvedSha256: z.string().optional(), companionNodeId: z.string().optional(), commentsTotal: z.number().int().nonnegative().optional(), commentsUnresolved: z.number().int().nonnegative().optional() }).strict().superRefine((result, ctx) => {
+    result.comments.forEach((comment, index) => {
+        if (comment.endLine < comment.line)
+            ctx.addIssue({ code: 'custom', message: 'endLine must be >= line', path: ['comments', index, 'endLine'] });
+        if ((comment.colStart === undefined) !== (comment.colEnd === undefined))
+            ctx.addIssue({ code: 'custom', message: 'columns must be supplied together', path: ['comments', index] });
+        if (comment.line === comment.endLine && comment.colStart !== undefined && comment.colEnd !== undefined && comment.colEnd <= comment.colStart)
+            ctx.addIssue({ code: 'custom', message: 'colEnd must exceed colStart', path: ['comments', index, 'colEnd'] });
+    });
+});
+const deckResultSchema = z.object({ schema: z.literal('humanloop.response/v2'), kind: z.literal('deck'), responses: z.array(responseSchema), summary: z.string(), completedAt: iso }).strict();
+const reviewResultSchema = z.object({ schema: z.literal('humanloop.review-response/v1'), kind: z.literal('review'), result: feedbackSchema, completedAt: iso }).strict();
+const canceledResultSchema = z.object({ schema: z.literal('humanloop.cancel/v1'), kind: z.literal('canceled'), canceledAt: iso, reason: z.string().optional(), actor: z.string().optional() }).strict();
+/** Strict decoder for the only canonical final marker. */
+export function readTicketResult(dir) {
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(responsePath(dir), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+    const parsed = deckResultSchema.safeParse(raw);
+    if (parsed.success)
+        return parsed.data;
+    const review = reviewResultSchema.safeParse(raw);
+    if (review.success)
+        return review.data;
+    const canceled = canceledResultSchema.safeParse(raw);
+    return canceled.success ? canceled.data : null;
+}
+function hasTicketProtocolState(dir) {
+    return [deckPath(dir), reviewPath(dir), responsePath(dir), progressPath(dir), claimPath(dir)].some(existsSync);
+}
+function publishRequest(path, value) {
+    if (!publishJsonExclusive(path, value))
+        throw new Error(`ticket request already exists: ${path}`);
+}
+export function submitDeck(opts) {
+    // Validate shape before mutating the bridge node's canvas directory.
+    validateDeck(opts.deck);
+    mkdirSync(opts.dir, { recursive: true, mode: 0o700 });
+    const dir = realpathSync(opts.dir);
+    if (hasTicketProtocolState(dir))
+        throw new Error(`ticket protocol state already exists: ${dir}`);
+    const deck = validateDeck(resolveDeckBodyPaths(opts.deck, dir));
+    const stamped = { ...deck, source: { ...(deck.source ?? {}), blockedSince: deck.source?.blockedSince ?? new Date().toISOString() } };
+    publishRequest(deckPath(dir), stamped);
+    signalInboxActivity();
+    return { id: basename(dir), dir, kind: 'deck' };
+}
+export function submitReview(opts) {
+    // A review takes any reviewable text file: a .md artifact renders as a document,
+    // and source code renders as a syntax-highlighted code panel.
+    if (!isAbsolute(opts.review.file) || !existsSync(opts.review.file))
+        throw new Error('review file must be an existing absolute path');
+    const reviewable = checkReviewableFile(opts.review.file);
+    if (!reviewable.ok)
+        throw new Error(`review file is not reviewable: ${reviewable.reason}`);
+    const source = realpathSync(opts.review.file);
+    mkdirSync(opts.dir, { recursive: true, mode: 0o700 });
+    const dir = realpathSync(opts.dir);
+    if (hasTicketProtocolState(dir))
+        throw new Error(`ticket protocol state already exists: ${dir}`);
+    const descriptor = validateReviewProjection(dir, { schema: 'humanloop.review/v1', file: source, output: resolve(opts.review.output ?? `${dir}/feedback.json`), title: opts.review.title, subtitle: opts.review.subtitle, source: opts.review.source, blockedSince: opts.review.blockedSince ?? new Date().toISOString() });
+    publishRequest(reviewPath(dir), descriptor);
+    signalInboxActivity();
+    return { id: basename(dir), dir, kind: 'review' };
+}
+function exclusiveResult(dir, result) {
+    return publishJsonExclusive(responsePath(dir), result);
+}
+function requireDeck(dir) { return validateDeck(JSON.parse(readFileSync(deckPath(dir), 'utf8'))); }
+function requireReview(dir) { return validateReviewDescriptor(JSON.parse(readFileSync(reviewPath(dir), 'utf8'))); }
+function validateDeckResponses(deck, raw) {
+    const responses = z.array(responseSchema).parse(raw);
+    const interactions = new Map(deck.interactions.map((interaction) => [interaction.id, interaction]));
+    const seen = new Set();
+    for (const response of responses) {
+        const interaction = interactions.get(response.id);
+        if (interaction === undefined || seen.has(response.id))
+            throw new Error(`response does not match a unique deck interaction: ${response.id}`);
+        seen.add(response.id);
+        const optionIds = new Set(interaction.options.map((option) => option.id));
+        if (response.selectedOptionId !== undefined && (!optionIds.has(response.selectedOptionId) || interaction.multiSelect === true))
+            throw new Error(`invalid single-select response for ${response.id}`);
+        if (response.selectedOptionIds !== undefined && (interaction.multiSelect !== true || response.selectedOptionIds.some((id) => !optionIds.has(id)) || new Set(response.selectedOptionIds).size !== response.selectedOptionIds.length))
+            throw new Error(`invalid multi-select response for ${response.id}`);
+        if (response.freetext !== undefined && interaction.allowFreetext !== true)
+            throw new Error(`freetext is not allowed for ${response.id}`);
+        if (response.optionComments !== undefined && (interaction.multiSelect !== true || Object.keys(response.optionComments).some((id) => !optionIds.has(id))))
+            throw new Error(`invalid option comments for ${response.id}`);
+    }
+    for (const interaction of deck.interactions.filter((candidate) => candidate.kind === 'notify')) {
+        const response = responses.find((candidate) => candidate.id === interaction.id);
+        if (response === undefined || (response.selectedOptionId === undefined && (response.selectedOptionIds?.length ?? 0) === 0 && (response.freetext?.trim() ?? '') === '')) {
+            throw new Error(`notification requires an explicit acknowledgement: ${interaction.id}`);
+        }
+    }
+    return responses;
+}
+/** Validate a deck resolution against its canonical ticket before claim takeover. */
+export function validateDeckTicketResponses(dir, responses) {
+    const ticket = requireTicket(dir);
+    return validateDeckResponses(requireDeck(ticket), responses);
+}
+function requireClaimOwnership(dir, token) {
+    if (readTicketClaim(dir)?.token !== token)
+        throw new Error('only the current claim holder may submit a result');
+}
+function clearOwnedWork(dir, claimToken) { clearProgress(dir); releaseClaimLocked(dir, claimToken); }
+/** Caller holds `.ticket-lock`. */
+function completeDeckLocked(dir, responses, claimToken, completedAt = new Date().toISOString()) {
+    requireClaimOwnership(dir, claimToken);
+    const deck = requireDeck(dir);
+    const parsedResponses = validateDeckResponses(deck, responses);
+    const result = { schema: 'humanloop.response/v2', kind: 'deck', responses: parsedResponses, summary: buildSummary(deck, parsedResponses), completedAt };
+    const won = exclusiveResult(dir, result);
+    clearOwnedWork(dir, claimToken);
+    return { won, result: won ? result : readTicketResult(dir) ?? result };
+}
+export function completeDeck(dir, responses, claimToken, completedAt) {
+    const ticket = requireTicket(dir);
+    const completed = withTicketLock(ticket, () => completeDeckLocked(ticket, responses, claimToken, completedAt));
+    if (completed.won)
+        signalInboxActivity();
+    return completed;
+}
+function takeoverClaim(dir, owner) {
+    const existing = readTicketClaim(dir);
+    if (existing !== null)
+        unlinkSync(claimPath(dir));
+    const token = randomUUID();
+    const now = new Date().toISOString();
+    writeFileSync(claimPath(dir), `${JSON.stringify({ token, host: owner.host, pid: owner.pid, claimedAt: now, heartbeatAt: now })}\n`, { flag: 'wx', mode: 0o600 });
+    return token;
+}
+/** Atomically take a ticket's claim over, complete it, and release the takeover claim. */
+export function takeoverAndCompleteDeck(dir, responses, owner) {
+    const ticket = requireTicket(dir);
+    const completed = withTicketLock(ticket, () => {
+        const token = takeoverClaim(ticket, owner);
+        try {
+            return completeDeckLocked(ticket, responses, token);
+        }
+        finally {
+            releaseClaimLocked(ticket, token);
+        }
+    });
+    if (completed.won)
+        signalInboxActivity();
+    return completed;
+}
+/** Cancellation races finalization but never requires or removes another claim. */
+export function cancelTicket(dir, opts = {}) {
+    const ticket = requireTicket(dir);
+    const canceled = withTicketLock(ticket, () => {
+        const result = { schema: 'humanloop.cancel/v1', kind: 'canceled', canceledAt: new Date().toISOString(), ...(opts.reason === undefined ? {} : { reason: opts.reason }), ...(opts.actor === undefined ? {} : { actor: opts.actor }) };
+        const won = exclusiveResult(ticket, result);
+        return { status: won ? 'canceled' : 'already_resolved', result: won ? result : readTicketResult(ticket) ?? result };
+    });
+    if (canceled.status === 'canceled')
+        signalInboxActivity();
+    return canceled;
+}
+/** Write the validated review output once its review result is published. */
+export function projectReviewOutput(dir) {
+    const result = readTicketResult(dir);
+    if (result === null)
+        return 'no_result';
+    if (result.kind !== 'review')
+        return 'not_a_review';
+    const ticket = requireTicket(dir);
+    const descriptor = validateReviewProjection(ticket, requireReview(ticket));
+    atomicWriteJson(descriptor.output, result.result);
+    return 'projected';
+}