balladeer 1.0.19 → 1.0.21

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" };
+            },
+        },
+    };
+}

package/dist/push-operation.d.ts

@@ -0,0 +1,61 @@
+import { type HookCommandResult } from "./judge-hook.js";
+/** Local metadata only. Neither shell commands nor tool outputs are persisted. */
+export declare const PUSH_OPERATION_SCHEMA = "balladeer-push-operation/v1";
+export declare const PUSH_OPERATION_TTL_MS: number;
+export type PushTarget = Readonly<{
+    source: string;
+    sourceRef: string;
+    head: string | null;
+    destination: string;
+    /** False for an explicit short destination whose namespace Git resolves remotely. */
+    destinationExact?: boolean;
+    /** Previously observed local tracking tip, never proof of this push's outcome. */
+    base?: string;
+    baseSource?: "local-tracking" | "push-output" | "new-branch-comparison";
+}>;
+export type PushOperation = Readonly<{
+    schemaVersion: typeof PUSH_OPERATION_SCHEMA;
+    root: string;
+    commandDigest: string;
+    identityDigest: string;
+    capturedAt: number;
+    remote: string;
+    remoteDigest: string;
+    targets: readonly PushTarget[];
+}>;
+export type PushOperationOptions = Readonly<{
+    root: string;
+    command: string;
+    /** The shell's starting folder, when git -C or cd names another checkout. */
+    cwd?: string;
+    sessionId?: string;
+    toolUseId?: string;
+    environment?: NodeJS.ProcessEnv;
+    now?: Date;
+}>;
+export type PushCapture = Readonly<{
+    status: "captured";
+    operation: PushOperation;
+}> | Readonly<{
+    status: "unknown";
+    reason: string;
+}>;
+export type ReconciledPushTarget = PushTarget & Readonly<{
+    status: "pushed" | "deleted" | "unchanged" | "rejected" | "unknown";
+}>;
+export type PushConsumption = Readonly<{
+    status: "reconciled";
+    operation: PushOperation;
+    targets: readonly ReconciledPushTarget[];
+}> | Readonly<{
+    status: "unknown";
+    reason: string;
+}>;
+/** Hash the repository destination, never a login, credential, query or fragment. */
+export declare function remoteDestinationDigest(reference: string, root: string): string | undefined;
+/** No remote calls: capture source commits and destinations before the observed command runs. */
+export declare function capturePushOperation(options: PushOperationOptions): PushCapture;
+/** Consume once. Existing remote-tracking state is never an outcome signal. */
+export declare function consumePushOperation(options: PushOperationOptions & Readonly<{
+    result?: HookCommandResult;
+}>): PushConsumption;