balladeer 1.0.18 → 1.0.20

package/dist/judge-hook.d.ts

@@ -15,8 +15,10 @@
  */
 export type HookHost = "claude" | "codex" | "git";
 /** The two host events the judge is installed on, in the order a command meets them. */
-export type HookEvent = "PreToolUse" | "PostToolUse";
+export type HookEvent = "PreToolUse" | "PostToolUse" | "PostToolUseFailure";
 export declare const JUDGE_HOOK_EVENTS: readonly HookEvent[];
+/** Claude has a distinct event for failed tools; Codex sends their PostToolUse. */
+export declare function judgeHookEvents(host: HookHost): readonly HookEvent[];
 export type HookInput = Readonly<{
     eventName?: string;
     toolName?: string;
@@ -25,6 +27,15 @@ export type HookInput = Readonly<{
     model?: string;
     /** The host's session, from `session_id`, which both Claude Code and Codex send. */
     sessionId?: string;
+    toolUseId?: string;
+    /** Only the bounded local shell result; never sent to Balladeer. */
+    result?: HookCommandResult;
+}>;
+export type HookCommandResult = Readonly<{
+    exitCode?: number;
+    stdout?: string;
+    stderr?: string;
+    interrupted?: boolean;
 }>;
 /** A coding host's hook payload, or nothing when the text is not one. */
 export declare function parseHookInput(text: string): HookInput | undefined;
@@ -117,6 +128,8 @@ export declare function pushPlace(line: string, cwd: string): PushPlace;
 export declare function repositoryName(reference: string): string | undefined;
 /** The repositories a checkout's remotes point at, from what `git remote -v` prints. */
 export declare function remoteRepositoryNames(listing: string): Set<string>;
+/** The command's words with leading assignments and wrappers like `env` and `sudo` removed. */
+export declare function shellProgram(words: readonly string[]): string[];
 /** Whether a shell line pushes: `git push`, `gh pr create`, or `gh pr merge`, anywhere in it. */
 export declare function isPushCommand(line: string): boolean;
 /**

package/dist/judge-hook.js

@@ -6,6 +6,26 @@ import { runCommand } from "./gh.js";
 import { resolveCommit } from "./scratch-worktree.js";
 import { configHome } from "./store.js";
 export const JUDGE_HOOK_EVENTS = ["PreToolUse", "PostToolUse"];
+/** Claude has a distinct event for failed tools; Codex sends their PostToolUse. */
+export function judgeHookEvents(host) {
+    return host === "claude" ? [...JUDGE_HOOK_EVENTS, "PostToolUseFailure"] : JUDGE_HOOK_EVENTS;
+}
+function commandResult(value) {
+    // Codex 0.144.5 sends the shell's combined output as a string, including
+    // successful remote ref updates followed by local tracking-lock failures.
+    if (typeof value === "string")
+        return { stdout: value.slice(0, 131072) };
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const row = value;
+    const code = row.exit_code ?? row.exitCode;
+    return {
+        ...(typeof code === "number" && Number.isInteger(code) ? { exitCode: code } : {}),
+        ...(typeof row.stdout === "string" ? { stdout: row.stdout.slice(0, 131072) } : {}),
+        ...(typeof row.stderr === "string" ? { stderr: row.stderr.slice(0, 131072) } : {}),
+        ...(typeof row.interrupted === "boolean" ? { interrupted: row.interrupted } : {}),
+    };
+}
 /** A session id as the hook keeps it: a bounded name, never a path or a sentence. */
 const SESSION_ID = /^[A-Za-z0-9._:-]{1,128}$/;
 /** A coding host's hook payload, or nothing when the text is not one. */
@@ -22,6 +42,11 @@ export function parseHookInput(text) {
     const input = value;
     const toolInput = input.tool_input;
     const command = commandText(toolInput?.command);
+    const result = commandResult(input.tool_response ??
+        input.tool_output ??
+        (typeof input.error === "string"
+            ? { stderr: input.error, interrupted: input.is_interrupt === true }
+            : undefined));
     return {
         ...(typeof input.hook_event_name === "string" ? { eventName: input.hook_event_name } : {}),
         ...(typeof input.tool_name === "string" ? { toolName: input.tool_name } : {}),
@@ -31,6 +56,10 @@ export function parseHookInput(text) {
         ...(typeof input.session_id === "string" && SESSION_ID.test(input.session_id)
             ? { sessionId: input.session_id }
             : {}),
+        ...(typeof input.tool_use_id === "string" && SESSION_ID.test(input.tool_use_id)
+            ? { toolUseId: input.tool_use_id }
+            : {}),
+        ...(result === undefined ? {} : { result }),
     };
 }
 const SHELLS = new Set(["bash", "sh", "zsh", "dash", "ksh"]);
@@ -45,14 +74,13 @@ function commandText(value) {
         return words[2];
     return words.join(" ");
 }
-const ZERO = /^0{40}$/;
 export function parsePrePushInput(text) {
     const refs = [];
     for (const line of text.split("\n")) {
         const [localRef, localSha, remoteRef, remoteSha] = line.trim().split(/\s+/);
         if (!localRef || !localSha || !remoteRef || !remoteSha)
             continue;
-        if (!/^[0-9a-f]{40}$/.test(localSha) || ZERO.test(localSha))
+        if (!/^[0-9a-f]{40}$/.test(localSha) || !/^[0-9a-f]{40}$/.test(remoteSha))
             continue;
         refs.push({ localRef, localSha, remoteRef, remoteSha });
     }
@@ -670,7 +698,7 @@ export function remoteRepositoryNames(listing) {
 const ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/;
 const WRAPPERS = new Set(["env", "command", "exec", "time", "nohup", "nice", "sudo", "builtin"]);
 /** The command's words with leading assignments and wrappers like `env` and `sudo` removed. */
-function program(words) {
+export function shellProgram(words) {
     let at = 0;
     while (at < words.length) {
         const word = words[at];
@@ -686,6 +714,7 @@ function program(words) {
     }
     return words.slice(at);
 }
+const program = shellProgram;
 /** git's global options that take the next word as their value. */
 const GIT_VALUE_OPTIONS = new Set([
     "-C",
@@ -1005,7 +1034,7 @@ export function hasJudgeEntry(root, host, event) {
  * installed has only the entry before the push, and it keeps judging there.
  */
 export function hasProjectJudgeHook(root, host) {
-    return JUDGE_HOOK_EVENTS.some((event) => hasJudgeEntry(root, host, event));
+    return judgeHookEvents(host).some((event) => hasJudgeEntry(root, host, event));
 }
 /**
  * The checkout that holds a folder, found by walking up to its `.git` entry (a
@@ -1091,7 +1120,7 @@ function installJsonHook(root, host) {
         const events = hooks;
         const expected = expectedEntry(host);
         const missing = [];
-        for (const event of JUDGE_HOOK_EVENTS) {
+        for (const event of judgeHookEvents(host)) {
             const rows = events[event] === undefined ? [] : events[event];
             if (!Array.isArray(rows))
                 return {

package/dist/judge-review.d.ts

@@ -0,0 +1,10 @@
+/** Source-grounded findings stay on the customer's machine, alongside the verdict. */
+export type CodeReview = Readonly<{
+    summary: string;
+    inspectedFiles: readonly string[];
+    risks: readonly string[];
+    limitations: readonly string[];
+}>;
+export declare function readCodeReview(raw: unknown): CodeReview | undefined;
+/** A review is reasoning, not verified evidence. Keep that distinction visible at the host. */
+export declare function codeReviewLines(review: CodeReview | undefined): string;

package/dist/judge-review.js

@@ -0,0 +1,36 @@
+export function readCodeReview(raw) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        return undefined;
+    const value = raw;
+    const strings = (input, max, length) => Array.isArray(input) && input.length <= max && input.every((v) => typeof v === "string")
+        ? [...new Set(input.map((v) => v.trim().slice(0, length)).filter(Boolean))]
+        : undefined;
+    const files = strings(value.inspectedFiles, 300, 500);
+    const risks = strings(value.risks, 8, 1000);
+    const limitations = strings(value.limitations, 8, 1000);
+    if (typeof value.summary !== "string" ||
+        !value.summary.trim() ||
+        files === undefined ||
+        files.length === 0 ||
+        risks === undefined ||
+        limitations === undefined ||
+        files.some((file) => file.startsWith("/") || file.includes("\\") || file.split("/").includes("..")))
+        return undefined;
+    return {
+        summary: value.summary.trim().slice(0, 2000),
+        inspectedFiles: files,
+        risks,
+        limitations,
+    };
+}
+/** A review is reasoning, not verified evidence. Keep that distinction visible at the host. */
+export function codeReviewLines(review) {
+    if (review === undefined)
+        return "";
+    return [
+        `    Review: ${review.summary}`,
+        `    Inspected: ${review.inspectedFiles.join(", ")}`,
+        ...review.risks.map((risk) => `    Review concern (not independently established): ${risk}`),
+        ...review.limitations.map((limit) => `    Review limit: ${limit}`),
+    ].join("\n");
+}

package/dist/judge-said.d.ts

@@ -24,6 +24,7 @@ export type SaidVerdict = Readonly<{
     notes: string;
     reproductionRejected: string | null;
     nextStep?: string;
+    review?: import("./judge-review.js").CodeReview;
 }>;
 /**
  * The gist of why a promise could not be judged, stable across the different

package/dist/judge-said.js

@@ -66,6 +66,9 @@ const NEEDS = [
  * the judge's notes with numbers and hashes set aside.
  */
 export function reasonGist(verdict) {
+    // A new concern must reach the session even if the same dependency is missing.
+    if (verdict.review !== undefined)
+        return `review:${fingerprint(JSON.stringify({ review: verdict.review, notes: verdict.notes, rejected: verdict.reproductionRejected, nextStep: verdict.nextStep }))}`;
     if (verdict.reproductionRejected)
         return `rejected:${fingerprint(verdict.reproductionRejected)}`;
     for (const [gist, pattern] of RUNNER_REASONS) {

package/dist/promise-meaning.d.ts

@@ -1,5 +1,6 @@
 import { type BehaviorMapMeaning } from "./behavior-map-schema.js";
 import { type StoredAgent } from "./store.js";
+import type { ReviewSubject } from "./promise-review-client.js";
 /**
  * One promise's agreed meaning, the way the map builder and the judge read it.
  *
@@ -34,6 +35,9 @@ export type PromiseDocument = Readonly<{
     title: string;
     semanticDigest: string;
     meaning: PromiseMeaning;
+    /** Present only when a current catalog has established the meaning's standing. */
+    standing?: "recorded" | "agreed";
+    subject?: ReviewSubject;
     /**
      * Whether a Balladeer check is bound to this promise, as `get_promise`
      * answered through this repository's connection. Absent means unknown: a

package/dist/promise-review-client.d.ts

@@ -0,0 +1,84 @@
+import { type PromiseAnchors } from "./anchors-schema.js";
+import type { AnchorsClient } from "./anchors-client.js";
+import { connectionAgent, type PromiseDocument, type PromiseReader } from "./promise-meaning.js";
+import type { StoredAgent } from "./store.js";
+import { type ReviewSettings } from "./review-settings.js";
+export type ReviewSubject = Readonly<{
+    kind: "agreed";
+    promiseId: string;
+    revisionId: string;
+}> | Readonly<{
+    kind: "recorded";
+    proposalId: string;
+    candidateRevision: number;
+    candidateEventId: string;
+}>;
+export declare const reviewSubjectId: (s: ReviewSubject) => string;
+export type ReviewTarget = PromiseDocument & Readonly<{
+    subject: ReviewSubject;
+    standing: "recorded" | "agreed";
+    anchors: PromiseAnchors | null;
+    openFindings?: readonly Readonly<{
+        reportId: string;
+        sourceSha: string;
+        baseSha: string;
+        destinationRef: string;
+        destinationDigest?: string;
+    }>[];
+}>;
+export type ReviewCatalog = Readonly<{
+    ok: true;
+    targets: readonly ReviewTarget[];
+    reviewSettings?: ReviewSettings;
+}> | Readonly<{
+    ok: false;
+    reason: string;
+    unsupported?: boolean;
+    reviewSettings?: ReviewSettings;
+}>;
+export type ReviewReceipt = Readonly<{
+    schemaVersion: "balladeer-review-receipt/v1";
+    subject: ReviewSubject;
+    semanticDigest: string;
+    baseSha: string;
+    sourceSha: string;
+    destinationRef: string;
+    destinationDigest?: string;
+    verdict: "kept" | "broken" | "could_not_tell";
+    reproductionDigest?: string;
+    briefRevision: string;
+    client: "codex" | "claude";
+    resolvesReportIds?: readonly string[];
+    ancestryVerified?: true;
+}>;
+export type ReviewsClient = Readonly<{
+    list(): Promise<ReviewCatalog>;
+    record(receipt: ReviewReceipt, options?: {
+        signal?: AbortSignal;
+        timeoutMs?: number;
+    }): Promise<{
+        ok: true;
+        reportId: string;
+    } | {
+        ok: false;
+        reason: string;
+    }>;
+    recordAnchors(target: ReviewTarget, anchors: PromiseAnchors): ReturnType<AnchorsClient["record"]>;
+}>;
+/** Read current meaning once per push. Customer code and test output never enter this client. */
+export declare function reviewsClientFor(agent: StoredAgent, options?: {
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+}): ReviewsClient;
+export declare function connectionReviewsClient(input: Parameters<typeof connectionAgent>[0]): {
+    ok: true;
+    client: ReviewsClient;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Adapt the existing local anchor builder without rereading each meaning through MCP. */
+export declare function catalogReaders(client: ReviewsClient, targets: readonly ReviewTarget[]): {
+    reader: PromiseReader;
+    anchors: AnchorsClient;
+};

package/dist/promise-review-client.js

@@ -0,0 +1,357 @@
+import { checkPromiseAnchors } from "./anchors-schema.js";
+import { noteServerVersion } from "./currency.js";
+import { agentEndpoint } from "./guidance.js";
+import { connectionAgent, normalizePromise, } from "./promise-meaning.js";
+import { CLIENT_HEADER, CLIENT_HEADER_VALUE } from "./wire.js";
+import { readReviewSettings } from "./review-settings.js";
+export const reviewSubjectId = (s) => s.kind === "agreed" ? s.promiseId : s.proposalId;
+const ID = /^[A-Za-z0-9_.-]{1,128}$/;
+const DIGEST = /^sha256:[0-9a-f]{64}$/;
+const MAX_BYTES = 8 * 1024 * 1024;
+const PATH = "/api/promise-reviews";
+const SHA = /^[0-9a-f]{40}$/;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const REF = /^refs\/heads\/(?!.*(?:\.\.|@\{|\/\/|[\x00-\x20\x7f~^:?*\[\\]))(?!.*(?:\.lock|\.)$)[A-Za-z0-9_./-]+$/;
+function exactKeys(value, allowed) {
+    return Object.keys(value).every((key) => allowed.includes(key));
+}
+/** Runtime checks precede upload: a server refusal cannot undo leaked customer material. */
+function receiptSafe(receipt) {
+    const subjectKeys = receipt.subject?.kind === "agreed"
+        ? ["kind", "promiseId", "revisionId"]
+        : ["kind", "proposalId", "candidateRevision", "candidateEventId"];
+    return (exactKeys(receipt, [
+        "schemaVersion",
+        "subject",
+        "semanticDigest",
+        "baseSha",
+        "sourceSha",
+        "destinationRef",
+        "destinationDigest",
+        "verdict",
+        "reproductionDigest",
+        "briefRevision",
+        "client",
+        "resolvesReportIds",
+        "ancestryVerified",
+    ]) &&
+        receipt.subject !== null &&
+        typeof receipt.subject === "object" &&
+        exactKeys(receipt.subject, subjectKeys) &&
+        subject(receipt.subject) !== undefined &&
+        receipt.schemaVersion === "balladeer-review-receipt/v1" &&
+        DIGEST.test(receipt.semanticDigest) &&
+        SHA.test(receipt.baseSha) &&
+        SHA.test(receipt.sourceSha) &&
+        receipt.baseSha !== receipt.sourceSha &&
+        receipt.destinationRef.length <= 255 &&
+        REF.test(receipt.destinationRef) &&
+        (receipt.destinationDigest === undefined || DIGEST.test(receipt.destinationDigest)) &&
+        ["kept", "broken", "could_not_tell"].includes(receipt.verdict) &&
+        (receipt.reproductionDigest === undefined || DIGEST.test(receipt.reproductionDigest)) &&
+        (receipt.verdict !== "broken" || receipt.reproductionDigest !== undefined) &&
+        /^[a-z][a-z0-9-]{0,47}\/v[1-9][0-9]{0,5}$/.test(receipt.briefRevision) &&
+        ["claude", "codex"].includes(receipt.client) &&
+        (receipt.ancestryVerified === undefined || receipt.ancestryVerified === true) &&
+        (receipt.resolvesReportIds === undefined ||
+            (Array.isArray(receipt.resolvesReportIds) &&
+                receipt.resolvesReportIds.length <= 100 &&
+                new Set(receipt.resolvesReportIds).size === receipt.resolvesReportIds.length &&
+                receipt.resolvesReportIds.every((id) => UUID.test(id)) &&
+                receipt.verdict === "kept" &&
+                receipt.ancestryVerified === true &&
+                receipt.destinationDigest !== undefined)));
+}
+function subject(value) {
+    if (value === null || typeof value !== "object")
+        return undefined;
+    const s = value;
+    const id = (v) => typeof v === "string" && ID.test(v);
+    if (s.kind === "agreed" && id(s.promiseId) && id(s.revisionId))
+        return { kind: "agreed", promiseId: s.promiseId, revisionId: s.revisionId };
+    if (s.kind === "recorded" &&
+        id(s.proposalId) &&
+        id(s.candidateEventId) &&
+        typeof s.candidateRevision === "number" &&
+        Number.isSafeInteger(s.candidateRevision) &&
+        s.candidateRevision > 0)
+        return {
+            kind: "recorded",
+            proposalId: s.proposalId,
+            candidateRevision: s.candidateRevision,
+            candidateEventId: s.candidateEventId,
+        };
+    return undefined;
+}
+/** Read current meaning once per push. Customer code and test output never enter this client. */
+export function reviewsClientFor(agent, options = {}) {
+    const send = async (body, cursor, timeoutMs = options.timeoutMs ?? 10_000, parentSignal) => {
+        const abort = new AbortController();
+        const timer = setTimeout(() => abort.abort(), timeoutMs);
+        try {
+            const url = agentEndpoint(agent, PATH);
+            if (cursor !== undefined)
+                url.searchParams.set("cursor", cursor);
+            const response = await (options.fetchImpl ?? fetch)(url, {
+                method: body === undefined ? "GET" : "POST",
+                redirect: "manual",
+                signal: parentSignal === undefined ? abort.signal : AbortSignal.any([abort.signal, parentSignal]),
+                headers: {
+                    authorization: `Bearer ${agent.token}`,
+                    [CLIENT_HEADER]: CLIENT_HEADER_VALUE,
+                    accept: "application/json",
+                    ...(body === undefined ? {} : { "content-type": "application/json" }),
+                },
+                ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+            });
+            noteServerVersion(response.headers);
+            const parts = [];
+            let size = 0;
+            const reader = response.body?.getReader();
+            try {
+                if (reader)
+                    for (;;) {
+                        const part = await reader.read();
+                        if (part.done)
+                            break;
+                        size += part.value.byteLength;
+                        if (size > MAX_BYTES)
+                            throw new Error("oversized");
+                        parts.push(part.value);
+                    }
+            }
+            finally {
+                await reader?.cancel().catch(() => undefined);
+            }
+            return {
+                status: response.status,
+                body: JSON.parse(Buffer.concat(parts).toString("utf8")),
+                bytes: size,
+            };
+        }
+        catch {
+            return {
+                error: abort.signal.aborted || parentSignal?.aborted
+                    ? "Balladeer's review catalog timed out"
+                    : "Balladeer's review response could not be read",
+            };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    };
+    return {
+        async list() {
+            const targets = [];
+            const seen = new Set();
+            const cursors = new Set();
+            let cursor;
+            let bytes = 0;
+            let reviewSettings;
+            const started = Date.now();
+            let deadline = started + (options.timeoutMs ?? 10_000);
+            const failed = (reason, unsupported = false) => ({
+                ok: false,
+                reason,
+                ...(unsupported ? { unsupported: true } : {}),
+                ...(reviewSettings === undefined ? {} : { reviewSettings }),
+            });
+            for (let page = 0; page < 100; page++) {
+                if (Date.now() >= deadline)
+                    return failed("Balladeer’s complete review catalog timed out");
+                const reply = await send(undefined, cursor, Math.max(1, deadline - Date.now()));
+                if ("error" in reply)
+                    return failed(reply.error);
+                bytes += reply.bytes;
+                if (bytes > MAX_BYTES)
+                    return failed("Balladeer’s complete review catalog exceeded the local size limit");
+                if (reply.status !== 200)
+                    return failed(`Balladeer could not provide the complete review catalog (${reply.status})`, reply.status === 404 || reply.status === 405);
+                const body = reply.body;
+                if (body?.schemaVersion !== "balladeer-promise-reviews/v1" || !Array.isArray(body.targets))
+                    return failed("Balladeer's review catalog is invalid");
+                // One snapshot for the whole operation, even if settings change during pagination.
+                if (page === 0) {
+                    reviewSettings = readReviewSettings(body.reviewSettings);
+                    if (reviewSettings !== undefined)
+                        deadline = Math.min(deadline, started + reviewSettings.budgetSeconds * 1000);
+                }
+                for (const raw of body.targets) {
+                    const row = raw;
+                    const s = subject(row?.subject);
+                    if (!s ||
+                        row?.standing !== s.kind ||
+                        typeof row.semanticDigest !== "string" ||
+                        !DIGEST.test(row.semanticDigest))
+                        return failed("Balladeer's catalog contains an invalid current meaning");
+                    const id = reviewSubjectId(s);
+                    const normalized = normalizePromise({ ...row, promiseId: id });
+                    if (!normalized.ok || seen.has(id))
+                        return failed("Balladeer's catalog contains an unreadable or duplicate meaning");
+                    seen.add(id);
+                    let anchors = null;
+                    if (row.anchors !== null && row.anchors !== undefined) {
+                        const checked = checkPromiseAnchors(row.anchors, { allowRecordedId: true });
+                        if (checked.ok &&
+                            checked.value.promiseId === id &&
+                            checked.value.semanticDigest === row.semanticDigest)
+                            anchors = checked.value;
+                    }
+                    const openFindings = Array.isArray(row.openFindings)
+                        ? row.openFindings.flatMap((item) => {
+                            const finding = item;
+                            return finding !== null &&
+                                typeof finding?.reportId === "string" &&
+                                UUID.test(finding.reportId) &&
+                                typeof finding.sourceSha === "string" &&
+                                SHA.test(finding.sourceSha) &&
+                                typeof finding.baseSha === "string" &&
+                                SHA.test(finding.baseSha) &&
+                                typeof finding.destinationRef === "string" &&
+                                REF.test(finding.destinationRef) &&
+                                (finding.destinationDigest === undefined ||
+                                    (typeof finding.destinationDigest === "string" &&
+                                        DIGEST.test(finding.destinationDigest)))
+                                ? [
+                                    {
+                                        reportId: finding.reportId,
+                                        sourceSha: finding.sourceSha,
+                                        baseSha: finding.baseSha,
+                                        destinationRef: finding.destinationRef,
+                                        ...(typeof finding.destinationDigest === "string"
+                                            ? { destinationDigest: finding.destinationDigest }
+                                            : {}),
+                                    },
+                                ]
+                                : [];
+                        })
+                        : [];
+                    targets.push({
+                        ...normalized.promise,
+                        subject: s,
+                        standing: s.kind,
+                        anchors,
+                        openFindings,
+                    });
+                }
+                if (body.nextCursor === undefined || body.nextCursor === null)
+                    return { ok: true, targets, ...(reviewSettings === undefined ? {} : { reviewSettings }) };
+                if (typeof body.nextCursor !== "string" ||
+                    body.nextCursor.length > 2048 ||
+                    cursors.has(body.nextCursor))
+                    return failed("Balladeer's catalog pagination did not complete");
+                cursors.add(body.nextCursor);
+                cursor = body.nextCursor;
+            }
+            return failed("Balladeer's catalog exceeded the review limit");
+        },
+        async record(receipt, sendOptions) {
+            // Validate the serialized representation too: inherited toJSON/getters
+            // must not add unbounded material between validation and upload.
+            try {
+                const serialized = JSON.stringify(receipt);
+                if (serialized.length > 16_384)
+                    throw new Error("large receipt");
+                receipt = JSON.parse(serialized);
+            }
+            catch {
+                return { ok: false, reason: "The receipt failed the local data boundary and was not sent" };
+            }
+            try {
+                if (!receiptSafe(receipt))
+                    return {
+                        ok: false,
+                        reason: "The receipt failed the local data boundary and was not sent",
+                    };
+            }
+            catch {
+                return { ok: false, reason: "The receipt failed the local data boundary and was not sent" };
+            }
+            const reply = await send(receipt, undefined, sendOptions?.timeoutMs, sendOptions?.signal);
+            if ("error" in reply)
+                return { ok: false, reason: reply.error };
+            const body = reply.body;
+            if ((reply.status !== 200 && reply.status !== 201) ||
+                body?.recorded !== true ||
+                typeof body.reportId !== "string")
+                return {
+                    ok: false,
+                    reason: `Balladeer did not record the review receipt (${reply.status})`,
+                };
+            return { ok: true, reportId: body.reportId };
+        },
+        async recordAnchors(target, anchors) {
+            let boundedSubject;
+            try {
+                const serialized = JSON.stringify(anchors);
+                if (serialized.length > 64 * 1024)
+                    throw new Error("large anchors");
+                anchors = JSON.parse(serialized);
+                boundedSubject = JSON.parse(JSON.stringify(target.subject));
+            }
+            catch {
+                return { ok: false, reason: "The anchors failed the local data boundary" };
+            }
+            const currentSubject = subject(boundedSubject);
+            if (currentSubject === undefined ||
+                !exactKeys(boundedSubject, currentSubject.kind === "agreed"
+                    ? ["kind", "promiseId", "revisionId"]
+                    : ["kind", "proposalId", "candidateRevision", "candidateEventId"]))
+                return { ok: false, reason: "The subject failed the local data boundary" };
+            const checked = checkPromiseAnchors(anchors, { allowRecordedId: true });
+            if (!checked.ok ||
+                anchors.promiseId !== target.promiseId ||
+                anchors.semanticDigest !== target.semanticDigest)
+                return { ok: false, reason: "The anchors do not match this current meaning" };
+            const reply = await send({
+                schemaVersion: "balladeer-review-anchors/v1",
+                subject: currentSubject,
+                semanticDigest: target.semanticDigest,
+                anchors,
+            });
+            if ("error" in reply)
+                return { ok: false, reason: reply.error };
+            const body = reply.body;
+            return (reply.status === 200 || reply.status === 201) && body?.recorded === true
+                ? { ok: true, alreadyRecorded: body.alreadyRecorded === true }
+                : { ok: false, reason: `Balladeer did not record the anchors (${reply.status})` };
+        },
+    };
+}
+export function connectionReviewsClient(input) {
+    const connection = connectionAgent(input);
+    return connection.ok ? { ok: true, client: reviewsClientFor(connection.agent) } : connection;
+}
+/** Adapt the existing local anchor builder without rereading each meaning through MCP. */
+export function catalogReaders(client, targets) {
+    const byId = new Map(targets.map((target) => [target.promiseId, target]));
+    return {
+        reader: {
+            async get(id) {
+                const promise = byId.get(id);
+                return promise
+                    ? { ok: true, promise }
+                    : { ok: false, reason: "No current review target by that id" };
+            },
+            async list(options) {
+                const ids = [...byId.keys()];
+                return {
+                    ok: true,
+                    ids: options?.max === undefined ? ids : ids.slice(0, options.max),
+                    ...(options?.max !== undefined && ids.length > options.max ? { more: true } : {}),
+                };
+            },
+        },
+        anchors: {
+            async list() {
+                return { ok: true, promises: targets, refused: 0 };
+            },
+            async record(anchors) {
+                const target = byId.get(anchors.promiseId);
+                return target
+                    ? client.recordAnchors(target, anchors)
+                    : { ok: false, reason: "The target is no longer current" };
+            },
+        },
+    };
+}