oh-my-super-agent 0.1.0

package/dist/src/github/review.js

@@ -0,0 +1,1450 @@
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { assertActorId, assertOpaqueId, assertRecordId, assertTransitionNonce, } from "../domain/records.js";
+import { assertFileInside, openStableDirectory, readImmutableFile, writeImmutableFile, } from "../evidence/immutable-file.js";
+import { discloseLiveContact, listLiveContacts, readLiveContact, readLiveDeliveryAuthorization, } from "../live/contact-journal.js";
+import { runProcess } from "../providers/process.js";
+import { canonicalTimestamp } from "../queue/model.js";
+import { createRecordStore } from "../runtime/record-store.js";
+import { assertSchema, loadJsonSchema } from "../runtime/schema.js";
+import { createStableId } from "../runtime/stable-id.js";
+import { runSecretScan, readSecretScan, } from "../security/secret-scan.js";
+import { readJsonFileNoFollow, isRecord, validateExistingDirectory } from "../utils/fs.js";
+import { createResultGateStore } from "../verification/result-gate-store.js";
+import { createRuntimeWorkerAuthorities } from "../workers/runtime.js";
+import { deriveWorktreeId } from "../dispatch/authority.js";
+import { readGoal } from "../goals/authority.js";
+import { parseTicketWorktreeRecord } from "../worktrees/manager.js";
+import { normalizeGithubRemoteRepository, normalizeGithubSyncTarget } from "./adapter.js";
+const BASE_BRANCH = "main";
+const MAX_GITHUB_BYTES = 2 * 1024 * 1024;
+const MAX_PROOF_BYTES = 512 * 1024;
+const SHA_PATTERN = /^[a-f0-9]{40}(?:[a-f0-9]{24})?$/u;
+const SHA256_PATTERN = /^[a-f0-9]{64}$/u;
+const BRANCH_PATTERN = /^oms-ticket-[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/u;
+const REQUIRED_CHECK_PATTERN = /^[A-Za-z0-9][A-Za-z0-9 ._:/-]{0,127}$/u;
+export const OMS_REVIEW_REQUIRED_CHECK = "OMS deterministic verification";
+const REVIEW_QUERY = `query OmsReviewRead($owner: String!, $name: String!, $branchRef: String!) {
+  repository(owner: $owner, name: $name) {
+    id
+    ref(qualifiedName: $branchRef) { target { oid } }
+    pullRequests(first: 100, states: [OPEN], orderBy: {field: UPDATED_AT, direction: DESC}) {
+      nodes {
+        id number url state isDraft headRefName baseRefName
+        commits(last: 1) { totalCount nodes { commit { oid } } }
+      }
+    }
+  }
+  rateLimit { remaining resetAt }
+}`;
+const CREATE_PR_MUTATION = `mutation OmsCreateDraftPullRequest(
+  $repositoryId: ID!, $baseRefName: String!, $headRefName: String!, $title: String!, $body: String!
+) {
+  createPullRequest(input: {
+    repositoryId: $repositoryId,
+    baseRefName: $baseRefName,
+    headRefName: $headRefName,
+    title: $title,
+    body: $body,
+    draft: true
+  }) {
+    pullRequest {
+      id number url state isDraft headRefName baseRefName
+      commits(last: 1) { totalCount nodes { commit { oid } } }
+    }
+  }
+}`;
+const LEGAL_EDGES = Object.freeze({
+    planned: ["push-pending", "pushed", "blocked"],
+    "push-pending": ["push-pending", "pushed", "blocked"],
+    pushed: ["pr-pending", "awaiting-check", "blocked"],
+    "pr-pending": ["pr-pending", "awaiting-check", "blocked"],
+    "awaiting-check": ["ready", "blocked"],
+    ready: [],
+    blocked: [],
+});
+export function createReviewDeliveryService(options) {
+    const packageRoot = validateExistingDirectory(options.packageRoot, "review package root");
+    const configRoot = validateExistingDirectory(options.configRoot ?? packageRoot, "review configuration root");
+    const workspaceRoot = validateExistingDirectory(options.workspaceRoot, "review workspace root");
+    const stateRoot = validateExistingDirectory(options.stateRoot, "review state root");
+    const requiredCheck = validateRequiredCheck(options.requiredCheckName);
+    const clock = options.clock ?? (() => new Date().toISOString());
+    const env = options.env ?? process.env;
+    const runner = options.runner ?? runProcess;
+    const secretScanner = options.secretScanner ?? runSecretScan;
+    const runtime = options.runtime ?? createRuntimeWorkerAuthorities({
+        packageRoot,
+        configRoot,
+        workspaceRoot,
+        stateRoot,
+        actorId: "oms-conductor",
+        clock,
+    });
+    const gates = createResultGateStore({ packageRoot, stateRoot });
+    const deliveries = createReviewDeliveryStore({ packageRoot, stateRoot, clock });
+    function advance(dispatchId, result) {
+        if (runtime.tickets.lifecycle.read(result.ticket_id).payload.source !== "github")
+            return null;
+        const canonical = captureCanonicalSubject(dispatchId, result);
+        const deliveryId = createStableId("review", canonical.subject.dispatch_id, canonical.subject.expected_commit);
+        let delivery = deliveries.readIfExists(deliveryId);
+        if (!delivery)
+            delivery = planDelivery(deliveryId, canonical);
+        assertReplayBinding(delivery, canonical);
+        for (let step = 0; step < 8; step += 1) {
+            if (delivery.state === "ready") {
+                assertReadyAttachments(delivery);
+                return toProgress(delivery);
+            }
+            if (delivery.state === "blocked")
+                return toProgress(delivery);
+            if (delivery.state === "planned") {
+                const advanced = advancePush(delivery);
+                delivery = advanced.record;
+                if (advanced.waiting)
+                    return toProgress(delivery);
+            }
+            else if (delivery.state === "push-pending")
+                delivery = recoverPush(delivery);
+            else if (delivery.state === "pushed") {
+                const advanced = advancePullRequest(delivery);
+                delivery = advanced.record;
+                if (advanced.waiting)
+                    return toProgress(delivery);
+            }
+            else if (delivery.state === "pr-pending")
+                delivery = recoverPullRequest(delivery);
+            else if (delivery.state === "awaiting-check") {
+                const completed = finishAfterTypedEvents(delivery, canonical.issueScanContent);
+                if (!completed)
+                    return toProgress(delivery);
+                delivery = completed;
+            }
+        }
+        return toProgress(delivery);
+    }
+    function captureCanonicalSubject(dispatchId, supplied) {
+        const dispatch = runtime.dispatch.read(assertRecordId(dispatchId, "review dispatch id"));
+        const gate = gates.read(assertRecordId(supplied.gate_id, "review result-gate id"));
+        const ticket = runtime.tickets.lifecycle.read(gate.payload.subject.ticket_id);
+        if (supplied.status !== "completed"
+            || supplied.gate_state !== "finalized"
+            || supplied.ticket_state !== "completed"
+            || supplied.reason !== null
+            || gate.state !== "finalized"
+            || gate.payload.outcome !== "completed"
+            || gate.payload.subject.dispatch_id !== dispatch.record_id
+            || supplied.ticket_id !== ticket.record_id
+            || supplied.deterministic_evidence === null
+            || supplied.grade_evidence === null
+            || !sameReference(supplied.deterministic_evidence, gate.payload.deterministic_evidence)
+            || !sameReference(supplied.grade_evidence, gate.payload.grade_evidence))
+            throw new Error("review delivery requires the canonical completed protected result");
+        const subject = gate.payload.subject;
+        const goal = readGoal(runtime.goals.authority, subject.goal_id);
+        const worker = runtime.workers.read(subject.dispatch_id);
+        const session = runtime.sessions.read(subject.session_id);
+        const worktree = parseTicketWorktreeRecord(readJsonFileNoFollow(join(stateRoot, "worktree-records", `${subject.ticket_id}.json`), 64 * 1024), "review worktree record");
+        const deterministic = runtime.tickets.evidenceStore.read(supplied.deterministic_evidence);
+        const grade = runtime.tickets.evidenceStore.read(supplied.grade_evidence);
+        if (dispatch.state !== "resolved"
+            || dispatch.payload.resolution !== "done"
+            || dispatch.payload.result?.status !== "done"
+            || dispatch.version !== subject.dispatch_version
+            || dispatch.payload.goal_id !== subject.goal_id
+            || dispatch.payload.goal_version !== subject.goal_version
+            || dispatch.payload.ticket_id !== subject.ticket_id
+            || dispatch.payload.attempt !== subject.attempt
+            || dispatch.payload.lease_token !== subject.lease_token
+            || dispatch.payload.worker_record_id !== subject.worker_record_id
+            || dispatch.payload.worker_id !== subject.worker_id
+            || dispatch.payload.session_id !== subject.session_id
+            || dispatch.payload.worktree_id !== subject.worktree_id
+            || dispatch.payload.worktree_path !== subject.worktree_root
+            || dispatch.payload.worktree_branch !== subject.worktree_branch
+            || dispatch.payload.worktree_base_commit !== subject.worktree_base_commit
+            || dispatch.payload.result.worktree_commit !== subject.expected_commit
+            || ticket.state !== "completed"
+            || ticket.attempt !== subject.attempt
+            || ticket.payload.source !== "github"
+            || !sameReference(ticket.payload.verification_evidence, supplied.deterministic_evidence)
+            || !sameReference(ticket.payload.grade_evidence, supplied.grade_evidence)
+            || goal.version !== subject.goal_version
+            || !["active", "completed"].includes(goal.state)
+            || goal.payload.repository_scope !== workspaceRoot
+            || worker.state !== "done"
+            || worker.record_id !== subject.worker_record_id
+            || worker.payload.external_worker_id !== subject.worker_id
+            || worker.payload.session_id !== subject.session_id
+            || worker.payload.ticket_id !== subject.ticket_id
+            || session.payload.ticket_id !== subject.ticket_id
+            || session.payload.native_session_ref !== subject.session_id
+            || worktree.ticket_id !== subject.ticket_id
+            || worktree.repository_root !== workspaceRoot
+            || worktree.worktree_root !== subject.worktree_root
+            || worktree.branch !== subject.worktree_branch
+            || worktree.base_commit !== subject.worktree_base_commit
+            || deriveWorktreeId(worktree) !== subject.worktree_id
+            || worktree.requested_base !== BASE_BRANCH
+            || !BRANCH_PATTERN.test(worktree.branch)
+            || deterministic.evidence_kind !== "deterministic-check"
+            || deterministic.ticket_id !== subject.ticket_id
+            || deterministic.payload.certification !== "live"
+            || deterministic.payload.passed !== true
+            || grade.evidence_kind !== "grader-output"
+            || grade.ticket_id !== subject.ticket_id
+            || grade.payload.verdict !== "pass"
+            || !sameReference(grade.payload.deterministic_evidence, supplied.deterministic_evidence))
+            throw new Error("review delivery authority binding no longer matches the protected result chain");
+        if (!isDeepStrictEqual(deterministic.payload.binding, protectedBinding(subject))) {
+            throw new Error("deterministic evidence binding does not match the result-gate subject");
+        }
+        const content = runtime.tickets.materializer.readContent({
+            ticket_id: ticket.record_id,
+            sha256: ticket.payload.content_sha256,
+            file_name: ticket.payload.content_file,
+        });
+        if (content.repository === null || content.issue_node_id === null || content.url === null) {
+            throw new Error("review delivery requires one canonical GitHub ticket");
+        }
+        const repository = normalizeGithubSyncTarget(content.repository).repository;
+        const issueNumber = parseIssueNumber(content.url, repository);
+        const authorization = readLiveDeliveryAuthorization(stateRoot);
+        if (!authorization || authorization.repository !== repository) {
+            throw new Error("review delivery lacks matching human live authorization");
+        }
+        return {
+            subject: Object.freeze({
+                goal_id: subject.goal_id,
+                goal_version: subject.goal_version,
+                dispatch_id: subject.dispatch_id,
+                dispatch_version: subject.dispatch_version,
+                ticket_id: subject.ticket_id,
+                attempt: subject.attempt,
+                lease_token: subject.lease_token,
+                worker_record_id: subject.worker_record_id,
+                worker_id: subject.worker_id,
+                session_id: subject.session_id,
+                worktree_id: subject.worktree_id,
+                worktree_root: subject.worktree_root,
+                worktree_branch: subject.worktree_branch,
+                worktree_base_commit: subject.worktree_base_commit,
+                expected_commit: subject.expected_commit,
+                deterministic_evidence: supplied.deterministic_evidence,
+                grade_evidence: supplied.grade_evidence,
+            }),
+            gate,
+            repository,
+            issueNumber,
+            issueNodeId: content.issue_node_id,
+            issueUrlSha256: sha256(content.url),
+            sourceRefSha256: ticket.payload.source_ref_sha256,
+            issueScanContent: Object.freeze({
+                title: content.title,
+                body: content.body,
+                labels: Object.freeze([...content.labels]),
+                url: content.url,
+            }),
+            authorizationId: authorization.authorization_id,
+            conductorSessionId: authorization.conductor_session_id,
+        };
+    }
+    function planDelivery(deliveryId, canonical) {
+        const createdAt = canonicalTimestamp(clock(), "review delivery timestamp");
+        assertAuthorizedOrigin(canonical.repository, canonical.subject.worktree_root, env, runner);
+        assertCommitAncestry(canonical.subject, env, runner);
+        const outbound = outboundPlan(canonical.repository, canonical.issueNumber, canonical.issueNodeId, canonical.issueScanContent, canonical.subject, requiredCheck);
+        const scan = secretScanner({
+            packageRoot,
+            stateRoot,
+            ticketId: canonical.subject.ticket_id,
+            phase: "preflight",
+            worktreeRoot: canonical.subject.worktree_root,
+            baseCommit: canonical.subject.worktree_base_commit,
+            verifiedCommit: canonical.subject.expected_commit,
+            outbound,
+            env,
+            runner,
+            clock: () => createdAt,
+        });
+        assertSecretScan(scan.result, "preflight", canonical.subject);
+        return deliveries.create({
+            deliveryId,
+            at: createdAt,
+            payload: {
+                delivery_id: deliveryId,
+                repository: canonical.repository,
+                issue_number: canonical.issueNumber,
+                issue_node_id: canonical.issueNodeId,
+                issue_url_sha256: canonical.issueUrlSha256,
+                source_ref_sha256: canonical.sourceRefSha256,
+                subject: canonical.subject,
+                result_gate_id: canonical.gate.record_id,
+                authorization_id: canonical.authorizationId,
+                conductor_session_id: canonical.conductorSessionId,
+                base_branch: BASE_BRANCH,
+                review_branch: canonical.subject.worktree_branch,
+                required_check: requiredCheck,
+                created_at: createdAt,
+                updated_at: createdAt,
+                preflight_secret_scan: scan.reference,
+                final_secret_scan: null,
+                contacts: [],
+                pull_request: null,
+                pull_request_event: null,
+                check_event: null,
+                proof: null,
+                blocked_reason: null,
+            },
+        });
+    }
+    function advancePush(record) {
+        const readback = readRemote(record, "before-push");
+        if (readback.snapshot.branch_head_oid !== null) {
+            if (readback.snapshot.branch_head_oid !== record.payload.subject.expected_commit) {
+                return { record: block(record, "remote review branch does not match the verified commit", readback.receipt), waiting: false };
+            }
+            return { record: deliveries.transition(record, "branch-already-pushed", "pushed", [readback.receipt]), waiting: false };
+        }
+        const request = pushRequest(record, env);
+        const contact = disclose(record, "git-branch-push", "git-origin", "push", request);
+        const claimed = deliveries.claim(record, "push-intent", "push-pending", [
+            readback.receipt,
+            { phase: "push", operation: "git-branch-push", contact, response_sha256: null },
+        ]);
+        if (claimed.status === "replayed")
+            return { record: claimed.record, waiting: true };
+        let pending = claimed.record;
+        const result = safeRun(runner, request);
+        const responseSha256 = processResultDigest(result);
+        pending = deliveries.transition(pending, `push-result-${responseSha256.slice(0, 12)}`, "push-pending", [], (payload) => ({
+            ...payload,
+            contacts: replacePendingReceipt(payload.contacts, contact, responseSha256),
+        }));
+        if (processSucceeded(result)) {
+            return { record: deliveries.transition(pending, "push-confirmed", "pushed"), waiting: false };
+        }
+        const recovered = readRemote(pending, "after-ambiguous-push");
+        if (recovered.snapshot.branch_head_oid === pending.payload.subject.expected_commit) {
+            return { record: deliveries.transition(pending, "push-readback-confirmed", "pushed", [recovered.receipt]), waiting: false };
+        }
+        if (recovered.snapshot.branch_head_oid !== null) {
+            return { record: block(pending, "ambiguous push resolved to a different remote commit", recovered.receipt), waiting: false };
+        }
+        return { record: pending, waiting: true };
+    }
+    function recoverPush(record) {
+        const readback = readRemote(record, "recover-push");
+        if (readback.snapshot.branch_head_oid === record.payload.subject.expected_commit) {
+            return deliveries.transition(record, "recovered-push", "pushed", [readback.receipt]);
+        }
+        if (readback.snapshot.branch_head_oid !== null) {
+            return block(record, "recovered push points at a different remote commit", readback.receipt);
+        }
+        return block(record, "push contact is ambiguous and remote readback found no branch", readback.receipt);
+    }
+    function advancePullRequest(record) {
+        const readback = readRemote(record, "before-pr");
+        if (readback.snapshot.branch_head_oid !== record.payload.subject.expected_commit) {
+            return { record: block(record, "verified review branch disappeared or changed before PR creation", readback.receipt), waiting: false };
+        }
+        if (readback.snapshot.pull_request) {
+            return { record: deliveries.transition(record, "existing-draft-pr", "awaiting-check", [readback.receipt], (payload) => ({
+                    ...payload,
+                    pull_request: readback.snapshot.pull_request,
+                })), waiting: false };
+        }
+        const request = createPullRequestRequest(record, readback.snapshot.repository_node_id, env);
+        const contact = disclose(record, "github-pr-create", "github-api-via-gh", "create-pr", request);
+        const claimed = deliveries.claim(record, "pr-create-intent", "pr-pending", [
+            readback.receipt,
+            { phase: "create-pr", operation: "github-pr-create", contact, response_sha256: null },
+        ]);
+        if (claimed.status === "replayed")
+            return { record: claimed.record, waiting: true };
+        let pending = claimed.record;
+        const result = safeRun(runner, request);
+        const responseSha256 = processResultDigest(result);
+        pending = deliveries.transition(pending, `pr-result-${responseSha256.slice(0, 12)}`, "pr-pending", [], (payload) => ({
+            ...payload,
+            contacts: replacePendingReceipt(payload.contacts, contact, responseSha256),
+        }));
+        if (processSucceeded(result))
+            parseCreatedPullRequest(result, pending);
+        const recovered = recoverPullRequest(pending);
+        return { record: recovered, waiting: recovered.state === "pr-pending" };
+    }
+    function recoverPullRequest(record) {
+        const readback = readRemote(record, "recover-pr");
+        if (readback.snapshot.branch_head_oid !== record.payload.subject.expected_commit) {
+            return block(record, "review branch changed while recovering draft PR", readback.receipt);
+        }
+        if (!readback.snapshot.pull_request) {
+            return block(record, "ambiguous draft PR creation found no matching remote PR", readback.receipt);
+        }
+        return deliveries.transition(record, "pr-readback-confirmed", "awaiting-check", [readback.receipt], (payload) => ({
+            ...payload,
+            pull_request: readback.snapshot.pull_request,
+        }));
+    }
+    function finishAfterTypedEvents(record, issueScanContent) {
+        const events = findRequiredEvents(record);
+        if (!events)
+            return undefined;
+        if (events.outcome === "blocked")
+            return block(record, events.reason);
+        const readback = readRemote(record, "final-review-read");
+        if (readback.snapshot.branch_head_oid !== record.payload.subject.expected_commit
+            || !readback.snapshot.pull_request
+            || !samePullRequest(readback.snapshot.pull_request, record.payload.pull_request))
+            return block(record, "final GitHub readback no longer matches the verified draft PR", readback.receipt);
+        const finalReadDisclosure = readLiveContact(stateRoot, readback.receipt.contact);
+        const issueEvent = findIssueEvent(record, issueScanContent);
+        const contactEvidence = requiredContactEvidence(record, issueEvent.observed_at, events, finalReadDisclosure.disclosed_at);
+        const finalizedAt = timestampAfter(record.payload.updated_at, issueEvent.observed_at, events.pull_request_observed_at, events.check_observed_at, finalReadDisclosure.disclosed_at, ...contactEvidence.contacts.map((contact) => contact.disclosed_at));
+        const proofCandidate = buildProof(record, events, readback, issueEvent, contactEvidence, finalizedAt);
+        const scan = secretScanner({
+            packageRoot,
+            stateRoot,
+            ticketId: record.payload.subject.ticket_id,
+            phase: "final",
+            worktreeRoot: record.payload.subject.worktree_root,
+            baseCommit: record.payload.subject.worktree_base_commit,
+            verifiedCommit: record.payload.subject.expected_commit,
+            outbound: {
+                delivery: outboundPlan(record.payload.repository, record.payload.issue_number, record.payload.issue_node_id, issueScanContent, record.payload.subject, record.payload.required_check),
+                proof: proofCandidate,
+            },
+            env,
+            runner,
+            clock: () => finalizedAt,
+        });
+        assertSecretScan(scan.result, "final", record.payload.subject);
+        const proof = writeProof(proofCandidate, scan.reference);
+        return deliveries.transition(record, "review-ready", "ready", [readback.receipt], (payload) => ({
+            ...payload,
+            final_secret_scan: scan.reference,
+            pull_request_event: events.pullRequest,
+            check_event: events.check,
+            proof,
+        }));
+    }
+    function readRemote(record, phase) {
+        const request = reviewReadRequest(record, env);
+        const contact = disclose(record, "github-review-read", "github-api-via-gh", phase, request);
+        const result = safeRun(runner, request);
+        if (!processSucceeded(result))
+            throw new Error("GitHub review read failed");
+        return {
+            snapshot: parseReviewRead(result, record),
+            receipt: {
+                phase,
+                operation: "github-review-read",
+                contact,
+                response_sha256: processResultDigest(result),
+            },
+        };
+    }
+    function disclose(record, operation, contactSurface, phase, request) {
+        const authorization = readLiveDeliveryAuthorization(stateRoot);
+        if (!authorization
+            || authorization.authorization_id !== record.payload.authorization_id
+            || authorization.conductor_session_id !== record.payload.conductor_session_id
+            || authorization.repository !== record.payload.repository)
+            throw new Error("review delivery live authorization changed");
+        return discloseLiveContact({
+            stateRoot,
+            authorization,
+            operation,
+            contactSurface,
+            subjectId: createStableId("review-contact", record.record_id, phase, String(record.version)),
+            request: publicProcessRequest(request),
+            disclosedAt: nextTimestamp(record.payload.updated_at, clock),
+        });
+    }
+    function findRequiredEvents(record) {
+        if (!record.payload.pull_request)
+            throw new Error("awaiting-check delivery lacks its draft PR");
+        let pullRequest;
+        let check;
+        const removals = [];
+        for (const event of runtime.outbox.listEvents()) {
+            if (event.event_kind !== "github-observed" || event.payload.repository !== record.payload.repository)
+                continue;
+            if (typeof event.payload.payload_sha256 !== "string")
+                continue;
+            const digest = event.payload.payload_sha256;
+            const fileName = event.payload.snapshot_file;
+            if (!SHA256_PATTERN.test(digest) || fileName !== `${digest}.json`)
+                continue;
+            const snapshot = readJsonFileNoFollow(join(stateRoot, "github-snapshots", fileName), MAX_GITHUB_BYTES);
+            if (sha256(canonicalJson(snapshot)) !== digest || !isRecord(snapshot))
+                continue;
+            const baseCandidate = {
+                reference: { event_id: event.event_id, payload_sha256: digest },
+                observationKey: String(event.payload.observation_key),
+                observedAt: canonicalTimestamp(event.occurred_at, "review GitHub event timestamp"),
+                eventId: event.event_id,
+                change: event.payload.change,
+                snapshot,
+                ambiguous: false,
+            };
+            if (event.payload.change === "removed") {
+                const candidate = { ...baseCandidate, effectiveAt: baseCandidate.observedAt };
+                removals.push(candidate);
+                continue;
+            }
+            if (event.payload.observation_kind === "pull_request"
+                && snapshot.number === record.payload.pull_request.number
+                && snapshot.head_ref_name === record.payload.review_branch
+                && snapshot.base_ref_name === BASE_BRANCH) {
+                const candidate = {
+                    ...baseCandidate,
+                    effectiveAt: eventEffectiveTimestamp(snapshot.updated_at, baseCandidate.observedAt),
+                };
+                pullRequest = selectLatestCandidate(pullRequest, candidate);
+            }
+            if (event.payload.observation_kind === "check"
+                && snapshot.pull_request_number === record.payload.pull_request.number
+                && snapshot.commit_oid === record.payload.subject.expected_commit
+                && snapshot.name === record.payload.required_check) {
+                const candidate = {
+                    ...baseCandidate,
+                    effectiveAt: eventEffectiveTimestamp(snapshot.updated_at ?? snapshot.completed_at ?? snapshot.started_at, baseCandidate.observedAt),
+                };
+                check = selectLatestCandidate(check, candidate);
+            }
+        }
+        for (const removal of removals) {
+            if (pullRequest?.observationKey === removal.observationKey) {
+                pullRequest = selectLatestCandidate(pullRequest, removal);
+            }
+            if (check?.observationKey === removal.observationKey)
+                check = selectLatestCandidate(check, removal);
+        }
+        if (!pullRequest || !check)
+            return undefined;
+        if (pullRequest.ambiguous || check.ambiguous) {
+            return { outcome: "blocked", reason: "required GitHub review evidence is chronologically ambiguous" };
+        }
+        if (pullRequest.change !== "present"
+            || pullRequest.snapshot.state !== "OPEN"
+            || pullRequest.snapshot.is_draft !== true
+            || pullRequest.snapshot.head_oid !== record.payload.subject.expected_commit)
+            return { outcome: "blocked", reason: "required draft PR event is no longer current" };
+        const checkPassed = (check.snapshot.status === "COMPLETED" && check.snapshot.conclusion === "SUCCESS")
+            || (check.snapshot.check_type === "status_context" && check.snapshot.status === "SUCCESS");
+        if (!checkPassed) {
+            const checkTerminal = check.change !== "present"
+                || check.snapshot.status === "COMPLETED"
+                || (check.snapshot.check_type === "status_context"
+                    && ["ERROR", "FAILURE"].includes(String(check.snapshot.status)));
+            return checkTerminal
+                ? { outcome: "blocked", reason: "latest required GitHub check did not pass" }
+                : undefined;
+        }
+        return {
+            outcome: "ready",
+            pullRequest: pullRequest.reference,
+            check: check.reference,
+            pull_request_observed_at: pullRequest.observedAt,
+            check_observed_at: check.observedAt,
+        };
+    }
+    function assertReadyAttachments(record) {
+        const finalScan = record.payload.final_secret_scan;
+        const proofRef = record.payload.proof;
+        if (!finalScan || !proofRef || !record.payload.pull_request_event || !record.payload.check_event) {
+            throw new Error("ready review delivery is missing its evidence attachments");
+        }
+        validateStoredScan(record.payload.preflight_secret_scan, record.payload, stateRoot, "preflight");
+        const finalScanResult = validateStoredScan(finalScan, record.payload, stateRoot, "final");
+        const currentEvents = findRequiredEvents(record);
+        if (!currentEvents
+            || currentEvents.outcome !== "ready"
+            || canonicalJson(currentEvents.pullRequest) !== canonicalJson(record.payload.pull_request_event)
+            || canonicalJson(currentEvents.check) !== canonicalJson(record.payload.check_event))
+            throw new Error("ready review delivery typed-event evidence is missing or stale");
+        const proof = readJsonFileNoFollow(join(stateRoot, "review-proofs", proofRef.file_name), MAX_PROOF_BYTES);
+        if (!isRecord(proof) || !isRecord(proof.contact_journal) || !Array.isArray(proof.contact_journal.contacts)) {
+            throw new Error("ready review proof lacks its contact-journal snapshot");
+        }
+        const ticket = runtime.tickets.lifecycle.read(record.payload.subject.ticket_id);
+        const issueContent = runtime.tickets.materializer.readContent({
+            ticket_id: ticket.record_id,
+            sha256: ticket.payload.content_sha256,
+            file_name: ticket.payload.content_file,
+        });
+        const issueEvent = findIssueEvent(record, {
+            title: issueContent.title,
+            body: issueContent.body,
+            labels: issueContent.labels,
+            url: issueContent.url ?? "",
+        });
+        if (!isRecord(proof.issue) || canonicalJson(proof.issue.event) !== canonicalJson(issueEvent.reference)) {
+            throw new Error("ready review proof issue event is missing or stale");
+        }
+        if (proof.contact_journal.authorization_id !== record.payload.authorization_id) {
+            throw new Error("ready review proof contact authorization changed");
+        }
+        const finalReadReceipts = record.payload.contacts.filter((receipt) => receipt.phase === "final-review-read");
+        if (finalReadReceipts.length !== 1)
+            throw new Error("ready review proof lacks its final GitHub read contact");
+        const finalReadDisclosure = readLiveContact(stateRoot, finalReadReceipts[0].contact);
+        const contactEvidence = requiredContactEvidence(record, issueEvent.observed_at, currentEvents, finalReadDisclosure.disclosed_at);
+        if (proof.contact_journal.cutoff_at !== contactEvidence.cutoffAt
+            || canonicalJson(proof.contact_journal.sync_event_times) !== canonicalJson(contactEvidence.syncEventTimes)
+            || canonicalJson(proof.contact_journal.contacts) !== canonicalJson(contactEvidence.contacts))
+            throw new Error("ready review proof contact evidence changed");
+        const proofCreatedAt = canonicalTimestamp(String(proof.created_at), "review proof timestamp");
+        const latestBoundTimestamp = Math.max(Date.parse(issueEvent.observed_at), Date.parse(currentEvents.pull_request_observed_at), Date.parse(currentEvents.check_observed_at), Date.parse(finalReadDisclosure.disclosed_at), ...contactEvidence.contacts.map((contact) => Date.parse(contact.disclosed_at)));
+        if (proofCreatedAt !== finalScanResult.created_at
+            || Date.parse(proofCreatedAt) <= latestBoundTimestamp)
+            throw new Error("ready review proof chronology changed");
+    }
+    function findIssueEvent(record, issue) {
+        let selected;
+        for (const event of runtime.outbox.listEvents()) {
+            if (event.event_kind !== "github-observed"
+                || event.payload.repository !== record.payload.repository
+                || event.payload.observation_kind !== "issue"
+                || event.payload.change !== "present"
+                || typeof event.payload.payload_sha256 !== "string")
+                continue;
+            const digest = event.payload.payload_sha256;
+            const fileName = event.payload.snapshot_file;
+            if (!SHA256_PATTERN.test(digest) || fileName !== `${digest}.json`)
+                continue;
+            const snapshot = readJsonFileNoFollow(join(stateRoot, "github-snapshots", fileName), MAX_GITHUB_BYTES);
+            if (sha256(canonicalJson(snapshot)) !== digest
+                || !isRecord(snapshot)
+                || snapshot.issue_node_id !== record.payload.issue_node_id
+                || snapshot.title !== issue.title
+                || snapshot.body !== issue.body
+                || canonicalJson(snapshot.labels) !== canonicalJson(issue.labels)
+                || snapshot.url !== issue.url)
+                continue;
+            const candidate = {
+                reference: { event_id: event.event_id, payload_sha256: digest },
+                observed_at: canonicalTimestamp(event.occurred_at, "review issue event timestamp"),
+                effective_at: eventEffectiveTimestamp(snapshot.updated_at, event.occurred_at),
+                event_id: event.event_id,
+            };
+            if (!selected
+                || Date.parse(candidate.effective_at) > Date.parse(selected.effective_at)
+                || (candidate.effective_at === selected.effective_at && candidate.event_id.localeCompare(selected.event_id) > 0))
+                selected = candidate;
+        }
+        if (!selected)
+            throw new Error("review proof lacks the typed issue event for its canonical ticket content");
+        return { reference: selected.reference, observed_at: selected.observed_at };
+    }
+    function buildProof(record, events, readback, issueEvent, contactEvidence, finalizedAt) {
+        const pullRequest = readback.snapshot.pull_request;
+        const finalReadReceipt = {
+            ...readback.receipt,
+            response_sha256: sha256(canonicalJson(readback.snapshot)),
+        };
+        return {
+            schema_version: 1,
+            proof_id: createStableId("review-proof", record.record_id, record.payload.subject.expected_commit),
+            delivery_id: record.record_id,
+            repository: record.payload.repository,
+            issue: {
+                number: record.payload.issue_number,
+                node_id: record.payload.issue_node_id,
+                url_sha256: record.payload.issue_url_sha256,
+                ticket_id: record.payload.subject.ticket_id,
+                source_ref_sha256: record.payload.source_ref_sha256,
+                event: issueEvent.reference,
+            },
+            goal: { id: record.payload.subject.goal_id, version: record.payload.subject.goal_version },
+            dispatch: { id: record.payload.subject.dispatch_id, version: record.payload.subject.dispatch_version },
+            session: { id: record.payload.subject.session_id },
+            worker: { record_id: record.payload.subject.worker_record_id, id: record.payload.subject.worker_id },
+            worktree: {
+                id: record.payload.subject.worktree_id,
+                root_sha256: sha256(record.payload.subject.worktree_root),
+                branch: record.payload.review_branch,
+                base_commit: record.payload.subject.worktree_base_commit,
+                verified_commit: record.payload.subject.expected_commit,
+            },
+            checks: {
+                deterministic_evidence: record.payload.subject.deterministic_evidence,
+                grade_evidence: record.payload.subject.grade_evidence,
+                required_remote_check: { name: record.payload.required_check, event: events.check },
+            },
+            github: {
+                base_branch: BASE_BRANCH,
+                branch: record.payload.review_branch,
+                pull_request: { ...pullRequest, event: events.pullRequest },
+                contacts: [...record.payload.contacts, finalReadReceipt],
+            },
+            contact_journal: {
+                authorization_id: record.payload.authorization_id,
+                cutoff_at: contactEvidence.cutoffAt,
+                sync_event_times: contactEvidence.syncEventTimes,
+                contacts: contactEvidence.contacts,
+            },
+            secret_scans: { preflight: record.payload.preflight_secret_scan },
+            release: { status: "not_stable", merge_disposition: "human_hold", automatic_merge: false },
+            created_at: finalizedAt,
+        };
+    }
+    function requiredContactEvidence(record, issueObservedAt, events, cutoffAt) {
+        const gradeRequestId = gates.read(record.payload.result_gate_id).payload.grade_request?.request_id;
+        if (!gradeRequestId)
+            throw new Error("review proof lacks its opposite-engine grade request identity");
+        const syncEventTimes = [...new Set([
+                issueObservedAt,
+                events.pull_request_observed_at,
+                events.check_observed_at,
+            ])].sort();
+        const canonicalCutoff = canonicalTimestamp(cutoffAt, "review contact evidence cutoff");
+        const providerBindings = [
+            { operation: "conductor-session", subjectId: record.payload.conductor_session_id },
+            { operation: "worker-session", subjectId: record.payload.subject.session_id },
+            { operation: "opposite-engine-grade", subjectId: gradeRequestId },
+        ];
+        const selected = listLiveContacts(stateRoot)
+            .filter(({ disclosure }) => (disclosure.authorization_id === record.payload.authorization_id
+            && disclosure.repository === record.payload.repository
+            && Date.parse(disclosure.disclosed_at) <= Date.parse(canonicalCutoff)
+            && (providerBindings.some((binding) => (disclosure.operation === binding.operation
+                && disclosure.subject_id === binding.subjectId))
+                || (disclosure.operation === "github-event-sync"
+                    && syncEventTimes.includes(disclosure.disclosed_at)))));
+        for (const binding of providerBindings) {
+            const matching = selected.filter(({ disclosure }) => (disclosure.operation === binding.operation
+                && disclosure.subject_id === binding.subjectId));
+            if (matching.length === 0) {
+                throw new Error(`review contact journal lacks ${binding.operation} evidence`);
+            }
+        }
+        for (const eventTime of syncEventTimes) {
+            if (!selected.some(({ disclosure }) => (disclosure.operation === "github-event-sync"
+                && disclosure.disclosed_at === eventTime)))
+                throw new Error(`review contact journal lacks github-event-sync evidence for ${eventTime}`);
+        }
+        const contacts = selected
+            .map(({ reference, disclosure }) => ({
+            reference,
+            operation: disclosure.operation,
+            subject_id: disclosure.subject_id,
+            disclosed_at: disclosure.disclosed_at,
+        }))
+            .sort((left, right) => left.reference.contact_id.localeCompare(right.reference.contact_id));
+        return Object.freeze({
+            cutoffAt: canonicalCutoff,
+            syncEventTimes: Object.freeze(syncEventTimes),
+            contacts: Object.freeze(contacts),
+        });
+    }
+    function writeProof(candidate, finalScan) {
+        const proof = {
+            ...candidate,
+            secret_scans: { ...candidate.secret_scans, final: finalScan },
+        };
+        const bytes = canonicalBytes(proof);
+        if (bytes.byteLength > MAX_PROOF_BYTES)
+            throw new Error("review proof exceeds its size limit");
+        const proofId = String(proof.proof_id);
+        const root = openStableDirectory(join(stateRoot, "review-proofs"), "review proof root");
+        try {
+            const fileName = `${proofId}.json`;
+            const path = join(root.path, fileName);
+            assertFileInside(root, path);
+            writeImmutableFile(path, bytes);
+            const stored = readImmutableFile(path, MAX_PROOF_BYTES);
+            if (!stored.equals(bytes))
+                throw new Error("review proof replay changed content");
+            return Object.freeze({ proof_id: proofId, sha256: sha256(stored), file_name: fileName });
+        }
+        finally {
+            root.close();
+        }
+    }
+    function block(record, reason, receipt) {
+        return deliveries.transition(record, `blocked-${sha256(reason).slice(0, 12)}`, "blocked", receipt ? [receipt] : [], (payload) => ({
+            ...payload,
+            blocked_reason: reason,
+        }));
+    }
+    return Object.freeze({ advance });
+}
+function createReviewDeliveryStore(options) {
+    const payloadSchema = loadJsonSchema(join(options.packageRoot, "schemas", "review-delivery-payload.schema.json"));
+    const actor = assertActorId("oms-system");
+    const store = createRecordStore({
+        recordsRoot: join(options.stateRoot, "review-deliveries"),
+        locksRoot: join(options.stateRoot, "locks"),
+        recordValidator(raw) {
+            if (raw.record_kind !== "review-delivery" || !Object.hasOwn(LEGAL_EDGES, raw.state)) {
+                throw new Error("invalid review-delivery runtime record");
+            }
+            assertSchema(raw.payload, payloadSchema, "review-delivery payload");
+            validateReviewRecord(raw, options.stateRoot);
+        },
+        createValidator(raw) {
+            if (raw.version !== 0 || raw.state !== "planned" || raw.actor !== actor) {
+                throw new Error("review delivery must begin planned under OMS system authority");
+            }
+        },
+        transitionValidator(current, next) {
+            const before = current;
+            const after = next;
+            if (!LEGAL_EDGES[before.state].includes(after.state)) {
+                throw new Error(`illegal review-delivery transition: ${before.state} -> ${after.state}`);
+            }
+            for (const field of [
+                "delivery_id", "repository", "issue_number", "issue_node_id", "issue_url_sha256", "source_ref_sha256",
+                "subject", "result_gate_id", "authorization_id", "conductor_session_id", "base_branch", "review_branch",
+                "required_check", "created_at", "preflight_secret_scan",
+            ]) {
+                if (canonicalJson(before.payload[field]) !== canonicalJson(after.payload[field])) {
+                    throw new Error(`review-delivery ${field} is immutable`);
+                }
+            }
+            if (Date.parse(after.payload.updated_at) <= Date.parse(before.payload.updated_at)) {
+                throw new Error("review-delivery update time must advance");
+            }
+            if (after.payload.contacts.length < before.payload.contacts.length)
+                throw new Error("review contacts cannot be removed");
+            for (let index = 0; index < before.payload.contacts.length; index += 1) {
+                const oldReceipt = before.payload.contacts[index];
+                const newReceipt = after.payload.contacts[index];
+                const pendingCompletion = oldReceipt.response_sha256 === null
+                    && newReceipt.response_sha256 !== null
+                    && canonicalJson({ ...oldReceipt, response_sha256: null }) === canonicalJson({ ...newReceipt, response_sha256: null });
+                if (!pendingCompletion && canonicalJson(oldReceipt) !== canonicalJson(newReceipt)) {
+                    throw new Error("review contact receipts are append-only");
+                }
+            }
+            monotonicObject("pull request", before.payload.pull_request, after.payload.pull_request);
+            monotonicObject("pull request event", before.payload.pull_request_event, after.payload.pull_request_event);
+            monotonicObject("check event", before.payload.check_event, after.payload.check_event);
+            monotonicObject("final secret scan", before.payload.final_secret_scan, after.payload.final_secret_scan);
+            monotonicObject("proof", before.payload.proof, after.payload.proof);
+        },
+    });
+    function applyTransition(record, step, toState, receipts, update) {
+        return store.transition({
+            recordId: record.record_id,
+            ownerId: actor,
+            expectedVersion: record.version,
+            nonce: createStableId("review-step", record.record_id, step),
+            expectedActor: record.actor,
+            expectedAttempt: record.attempt,
+            expectedLeaseToken: record.lease_token,
+            fromStates: [record.state],
+            toState,
+            updatePayload: (current) => {
+                const changed = update(current.payload);
+                return {
+                    ...changed,
+                    updated_at: nextTimestamp(current.payload.updated_at, options.clock),
+                    contacts: [...changed.contacts, ...receipts],
+                };
+            },
+        });
+    }
+    return {
+        create(input) {
+            const id = assertRecordId(input.deliveryId, "review delivery id");
+            const record = {
+                schema_version: 1,
+                record_id: id,
+                record_kind: assertOpaqueId("review-delivery"),
+                version: 0,
+                state: "planned",
+                attempt: 1,
+                max_attempts: 1,
+                actor,
+                lease_token: null,
+                transition_nonce: assertTransitionNonce(createStableId("review-create", id)),
+                payload: input.payload,
+                transition_outcomes: [],
+            };
+            record.transition_outcomes.push({
+                nonce: record.transition_nonce,
+                version: 0,
+                state: record.state,
+                attempt: 1,
+                actor,
+                lease_token: null,
+            });
+            return store.create(record);
+        },
+        readIfExists(deliveryId) {
+            return store.readIfExists(deliveryId);
+        },
+        transition(record, step, toState, receipts = [], update = (payload) => payload) {
+            return applyTransition(record, step, toState, receipts, update).record;
+        },
+        claim(record, step, toState, receipts) {
+            const result = applyTransition(record, step, toState, receipts, (payload) => payload);
+            return { status: result.status, record: result.record };
+        },
+    };
+}
+function validateReviewRecord(record, stateRoot) {
+    const payload = record.payload;
+    if (payload.delivery_id !== record.record_id
+        || record.actor !== "oms-system"
+        || record.lease_token !== null
+        || record.attempt !== 1
+        || record.max_attempts !== 1
+        || payload.base_branch !== BASE_BRANCH
+        || !BRANCH_PATTERN.test(payload.review_branch)
+        || payload.review_branch !== payload.subject.worktree_branch
+        || payload.subject.dispatch_id === payload.subject.ticket_id
+        || payload.subject.deterministic_evidence === null
+        || payload.subject.grade_evidence === null)
+        throw new Error("review-delivery identity mismatch");
+    assertOpaqueId(payload.result_gate_id, "review result-gate id");
+    assertOpaqueId(payload.authorization_id, "review authorization id");
+    validateRequiredCheck(payload.required_check);
+    canonicalTimestamp(payload.created_at, "review creation timestamp");
+    canonicalTimestamp(payload.updated_at, "review update timestamp");
+    if (Date.parse(payload.updated_at) < Date.parse(payload.created_at))
+        throw new Error("review update predates creation");
+    validateReviewSubject(payload.subject);
+    validateStoredScan(payload.preflight_secret_scan, payload, stateRoot, "preflight");
+    if (payload.final_secret_scan)
+        validateStoredScan(payload.final_secret_scan, payload, stateRoot, "final");
+    for (const receipt of payload.contacts)
+        validateContactReceipt(receipt, payload, stateRoot);
+    if (payload.pull_request)
+        validatePullRequest(payload.pull_request);
+    if (payload.pull_request_event)
+        validateEventReference(payload.pull_request_event);
+    if (payload.check_event)
+        validateEventReference(payload.check_event);
+    if (payload.proof)
+        validateProofReference(payload.proof, stateRoot);
+    if (record.state === "ready" && (payload.proof === null
+        || payload.final_secret_scan === null
+        || payload.pull_request === null
+        || payload.pull_request_event === null
+        || payload.check_event === null
+        || payload.blocked_reason !== null))
+        throw new Error("ready review delivery lacks final proof evidence");
+    if (record.state === "blocked" && payload.blocked_reason === null) {
+        throw new Error("blocked review delivery lacks a reason");
+    }
+}
+function validateReviewSubject(subject) {
+    exactRecord(subject, [
+        "attempt", "deterministic_evidence", "dispatch_id", "dispatch_version", "expected_commit",
+        "goal_id", "goal_version", "grade_evidence", "lease_token", "session_id", "ticket_id",
+        "worker_id", "worker_record_id", "worktree_base_commit", "worktree_branch", "worktree_id", "worktree_root",
+    ], "review subject");
+    for (const [label, value] of [
+        ["goal id", subject.goal_id], ["dispatch id", subject.dispatch_id], ["ticket id", subject.ticket_id],
+        ["lease token", subject.lease_token], ["worker record id", subject.worker_record_id],
+        ["worker id", subject.worker_id], ["session id", subject.session_id], ["worktree id", subject.worktree_id],
+    ])
+        assertOpaqueId(value, `review ${label}`);
+    if (!Number.isSafeInteger(subject.goal_version) || subject.goal_version < 0)
+        throw new Error("invalid review goal version");
+    if (!Number.isSafeInteger(subject.dispatch_version) || subject.dispatch_version < 0)
+        throw new Error("invalid review dispatch version");
+    positiveInteger(subject.attempt, "review attempt");
+    if (!BRANCH_PATTERN.test(subject.worktree_branch) || !subject.worktree_root.startsWith("/"))
+        throw new Error("invalid review worktree");
+    commit(subject.worktree_base_commit, "review base commit");
+    commit(subject.expected_commit, "review verified commit");
+    validateEvidenceReference(subject.deterministic_evidence);
+    validateEvidenceReference(subject.grade_evidence);
+}
+function validateEvidenceReference(reference) {
+    exactRecord(reference, ["evidence_id", "file_name", "sha256"], "review evidence reference");
+    assertOpaqueId(reference.evidence_id, "review evidence id");
+    if (!SHA256_PATTERN.test(reference.sha256) || reference.file_name !== `${reference.evidence_id}.json`) {
+        throw new Error("invalid review evidence reference");
+    }
+}
+function validateScanReference(reference) {
+    exactRecord(reference, ["file_name", "scan_id", "sha256"], "review secret scan reference");
+    assertOpaqueId(reference.scan_id, "review secret scan id");
+    if (!SHA256_PATTERN.test(reference.sha256) || reference.file_name !== `${reference.scan_id}.json`) {
+        throw new Error("invalid review secret scan reference");
+    }
+}
+function validateStoredScan(reference, payload, stateRoot, phase) {
+    validateScanReference(reference);
+    const scan = readSecretScan(stateRoot, reference);
+    if (scan.phase !== phase
+        || scan.ticket_id !== payload.subject.ticket_id
+        || scan.base_commit !== payload.subject.worktree_base_commit
+        || scan.verified_commit !== payload.subject.expected_commit
+        || scan.passed !== true)
+        throw new Error(`review ${phase} secret scan binding is invalid`);
+    return scan;
+}
+function validateContactReceipt(receipt, payload, stateRoot) {
+    exactRecord(receipt, ["contact", "operation", "phase", "response_sha256"], "review contact receipt");
+    if (!/^[a-z0-9-]{1,64}$/u.test(receipt.phase) || !["git-branch-push", "github-review-read", "github-pr-create"].includes(receipt.operation)) {
+        throw new Error("invalid review contact receipt");
+    }
+    exactRecord(receipt.contact, ["contact_id", "file_name", "sha256"], "review contact reference");
+    assertOpaqueId(receipt.contact.contact_id, "review contact id");
+    if (!SHA256_PATTERN.test(receipt.contact.sha256)
+        || receipt.contact.file_name !== `${receipt.contact.contact_id}.json`
+        || (receipt.response_sha256 !== null && !SHA256_PATTERN.test(receipt.response_sha256)))
+        throw new Error("invalid review contact reference");
+    const disclosure = readLiveContact(stateRoot, receipt.contact);
+    if (disclosure.operation !== receipt.operation
+        || disclosure.authorization_id !== payload.authorization_id
+        || disclosure.conductor_session_id !== payload.conductor_session_id
+        || disclosure.repository !== payload.repository)
+        throw new Error("review contact disclosure does not match its delivery authority");
+}
+function validatePullRequest(pullRequest) {
+    exactRecord(pullRequest, ["head_oid", "node_id", "number", "url_sha256"], "review pull request reference");
+    nodeId(pullRequest.node_id, "review PR node id");
+    positiveInteger(pullRequest.number, "review PR number");
+    commit(pullRequest.head_oid, "review PR head");
+    if (!SHA256_PATTERN.test(pullRequest.url_sha256))
+        throw new Error("invalid review PR URL digest");
+}
+function validateEventReference(reference) {
+    exactRecord(reference, ["event_id", "payload_sha256"], "review event reference");
+    assertOpaqueId(reference.event_id, "review event id");
+    if (!SHA256_PATTERN.test(reference.payload_sha256))
+        throw new Error("invalid review event digest");
+}
+function validateProofReference(reference, stateRoot) {
+    exactRecord(reference, ["file_name", "proof_id", "sha256"], "review proof reference");
+    assertOpaqueId(reference.proof_id, "review proof id");
+    if (!SHA256_PATTERN.test(reference.sha256) || reference.file_name !== `${reference.proof_id}.json`) {
+        throw new Error("invalid review proof reference");
+    }
+    const path = join(stateRoot, "review-proofs", reference.file_name);
+    if (sha256(readImmutableFile(path, MAX_PROOF_BYTES)) !== reference.sha256)
+        throw new Error("review proof digest mismatch");
+}
+function assertReplayBinding(record, canonical) {
+    if (canonicalJson(record.payload.subject) !== canonicalJson(canonical.subject)
+        || record.payload.repository !== canonical.repository
+        || record.payload.issue_number !== canonical.issueNumber
+        || record.payload.issue_node_id !== canonical.issueNodeId
+        || record.payload.issue_url_sha256 !== canonical.issueUrlSha256
+        || record.payload.source_ref_sha256 !== canonical.sourceRefSha256
+        || record.payload.authorization_id !== canonical.authorizationId
+        || record.payload.conductor_session_id !== canonical.conductorSessionId)
+        throw new Error("review delivery replay changed its protected authority binding");
+}
+function reviewReadRequest(record, env) {
+    const target = normalizeGithubSyncTarget(record.payload.repository);
+    return githubRequest(record.payload.subject.worktree_root, {
+        query: REVIEW_QUERY,
+        variables: { owner: target.owner, name: target.name, branchRef: `refs/heads/${record.payload.review_branch}` },
+    }, env);
+}
+function createPullRequestRequest(record, repositoryId, env) {
+    return githubRequest(record.payload.subject.worktree_root, {
+        query: CREATE_PR_MUTATION,
+        variables: {
+            repositoryId,
+            baseRefName: BASE_BRANCH,
+            headRefName: record.payload.review_branch,
+            title: draftPullRequestTitle(record.payload.issue_number),
+            body: draftPullRequestBody(record.payload.issue_number, record.payload.subject),
+        },
+    }, env);
+}
+function pushRequest(record, env) {
+    const sshTarget = `git@github.com:${record.payload.repository}.git`;
+    return {
+        command: "git",
+        args: [
+            "push",
+            "--porcelain",
+            "--no-verify",
+            sshTarget,
+            `${record.payload.subject.expected_commit}:refs/heads/${record.payload.review_branch}`,
+        ],
+        cwd: record.payload.subject.worktree_root,
+        env: gitEnvironment(env),
+        timeoutMs: 60_000,
+        maxBufferBytes: 512 * 1024,
+    };
+}
+function githubRequest(cwd, input, env) {
+    return {
+        command: "gh",
+        args: ["api", "graphql", "--input", "-"],
+        cwd,
+        env: githubEnvironment(env),
+        input: JSON.stringify(input),
+        timeoutMs: 30_000,
+        maxBufferBytes: MAX_GITHUB_BYTES,
+    };
+}
+function parseReviewRead(result, record) {
+    const root = parseGraphql(result.stdout, "review read");
+    const data = exactRecord(root.data, ["repository", "rateLimit"], "review read data");
+    assertRateLimit(data.rateLimit);
+    const repository = exactRecord(data.repository, ["id", "pullRequests", "ref"], "review repository");
+    const repositoryNodeId = nodeId(repository.id, "review repository id");
+    let branchHead = null;
+    if (repository.ref !== null) {
+        const ref = exactRecord(repository.ref, ["target"], "review ref");
+        const target = exactRecord(ref.target, ["oid"], "review ref target");
+        branchHead = commit(target.oid, "review branch head");
+    }
+    const pullRequestsConnection = exactRecord(repository.pullRequests, ["nodes"], "review pull requests");
+    if (!Array.isArray(pullRequestsConnection.nodes))
+        throw new Error("review pull request nodes are invalid");
+    let pullRequest = null;
+    for (const value of pullRequestsConnection.nodes) {
+        const candidate = parsePullRequest(value, record);
+        if (!candidate)
+            continue;
+        if (pullRequest)
+            throw new Error("multiple open draft PRs match the OMS review branch");
+        pullRequest = candidate;
+    }
+    return {
+        repository_node_id: repositoryNodeId,
+        branch_head_oid: branchHead,
+        pull_request: pullRequest,
+    };
+}
+function parseCreatedPullRequest(result, record) {
+    const root = parseGraphql(result.stdout, "draft PR create");
+    const data = exactRecord(root.data, ["createPullRequest"], "draft PR data");
+    const created = exactRecord(data.createPullRequest, ["pullRequest"], "draft PR mutation");
+    const candidate = parsePullRequest(created.pullRequest, record);
+    if (!candidate)
+        throw new Error("created PR does not match the protected review delivery");
+    return candidate;
+}
+function parsePullRequest(value, record) {
+    const pr = exactRecord(value, [
+        "baseRefName", "commits", "headRefName", "id", "isDraft", "number", "state", "url",
+    ], "review pull request");
+    if (pr.headRefName !== record.payload.review_branch || pr.baseRefName !== BASE_BRANCH || pr.state !== "OPEN")
+        return null;
+    if (pr.isDraft !== true)
+        throw new Error("matching review PR must remain draft");
+    const commits = exactRecord(pr.commits, ["nodes", "totalCount"], "review PR commits");
+    if (!Number.isSafeInteger(commits.totalCount) || Number(commits.totalCount) < 1 || !Array.isArray(commits.nodes) || commits.nodes.length !== 1) {
+        throw new Error("review PR head commit is ambiguous");
+    }
+    const node = exactRecord(commits.nodes[0], ["commit"], "review PR commit node");
+    const commitNode = exactRecord(node.commit, ["oid"], "review PR commit");
+    const headOid = commit(commitNode.oid, "review PR head");
+    if (headOid !== record.payload.subject.expected_commit)
+        throw new Error("review PR head differs from the verified commit");
+    const number = positiveInteger(pr.number, "review PR number");
+    const url = githubUrl(pr.url, "review PR URL");
+    return {
+        node_id: nodeId(pr.id, "review PR id"),
+        number,
+        url_sha256: sha256(url),
+        head_oid: headOid,
+    };
+}
+function parseGraphql(stdout, label) {
+    if (Buffer.byteLength(stdout, "utf8") > MAX_GITHUB_BYTES)
+        throw new Error(`${label} exceeds its output limit`);
+    let value;
+    try {
+        value = JSON.parse(stdout);
+    }
+    catch {
+        throw new Error(`${label} returned malformed JSON`);
+    }
+    const root = exactRecord(value, ["data"], label);
+    return root;
+}
+function assertRateLimit(value) {
+    const rate = exactRecord(value, ["remaining", "resetAt"], "GitHub rate limit");
+    if (!Number.isSafeInteger(rate.remaining) || Number(rate.remaining) < 1)
+        throw new Error("GitHub rate limit is exhausted");
+    canonicalTimestamp(String(rate.resetAt), "GitHub rate reset timestamp");
+}
+function outboundPlan(repository, issueNumber, issueNodeId, issueScanContent, subject, requiredCheck) {
+    const target = normalizeGithubSyncTarget(repository);
+    const branch = subject.worktree_branch;
+    const title = draftPullRequestTitle(issueNumber);
+    const body = draftPullRequestBody(issueNumber, subject);
+    return {
+        repository,
+        issue: {
+            number: issueNumber,
+            node_id: issueNodeId,
+            title: issueScanContent.title,
+            body: issueScanContent.body,
+            labels: issueScanContent.labels,
+            url: issueScanContent.url,
+        },
+        branch,
+        base_branch: BASE_BRANCH,
+        expected_commit: subject.expected_commit,
+        required_check: requiredCheck,
+        process_argv: [
+            ["git", "remote", "get-url", "--push", "origin"],
+            ["git", "merge-base", "--is-ancestor", subject.worktree_base_commit, subject.expected_commit],
+            ["git", "push", "--porcelain", "--no-verify", `git@github.com:${repository}.git`, `${subject.expected_commit}:refs/heads/${branch}`],
+            ["gh", "api", "graphql", "--input", "-"],
+        ],
+        github_inputs: [
+            { query: REVIEW_QUERY, variables: { owner: target.owner, name: target.name, branchRef: `refs/heads/${branch}` } },
+            {
+                query: CREATE_PR_MUTATION,
+                variables: {
+                    repositoryId: "<read-back-node-id>", baseRefName: BASE_BRANCH, headRefName: branch, title, body,
+                },
+            },
+        ],
+        release: { status: "not_stable", merge_disposition: "human_hold", automatic_merge: false },
+    };
+}
+function draftPullRequestTitle(issueNumber) {
+    return `OMS ticket #${issueNumber}`;
+}
+function draftPullRequestBody(issueNumber, subject) {
+    return [
+        `Automated draft for issue #${issueNumber}.`,
+        `Verified commit: ${subject.expected_commit}`,
+        `Deterministic evidence: ${subject.deterministic_evidence.evidence_id} (${subject.deterministic_evidence.sha256})`,
+        `Opposite-engine grade: ${subject.grade_evidence.evidence_id} (${subject.grade_evidence.sha256})`,
+        "Status: READY_FOR_HUMAN after required checks are observed.",
+        "Merge, ready-for-review, tag, publish, and release remain human actions.",
+    ].join("\n\n");
+}
+function protectedBinding(subject) {
+    return {
+        goal_id: subject.goal_id,
+        goal_version: subject.goal_version,
+        dispatch_id: subject.dispatch_id,
+        dispatch_version: subject.dispatch_version,
+        ticket_id: subject.ticket_id,
+        attempt: subject.attempt,
+        lease_token: subject.lease_token,
+        session_id: subject.session_id,
+        worker_record_id: subject.worker_record_id,
+        worker_id: subject.worker_id,
+        worktree_id: subject.worktree_id,
+        worktree_root: subject.worktree_root,
+        worktree_branch: subject.worktree_branch,
+        worktree_base_commit: subject.worktree_base_commit,
+        expected_commit: subject.expected_commit,
+        executor_role: subject.executor_role,
+        executor_engine: subject.executor_engine,
+        executor_evidence: subject.executor_evidence,
+    };
+}
+function assertAuthorizedOrigin(repository, cwd, env, runner) {
+    const result = runner({
+        command: "git",
+        args: ["remote", "get-url", "--push", "origin"],
+        cwd,
+        env: gitEnvironment(env),
+        timeoutMs: 10_000,
+        maxBufferBytes: 64 * 1024,
+    });
+    if (!processSucceeded(result))
+        throw new Error("unable to verify the review push remote");
+    const normalized = normalizeGithubRemoteRepository(result.stdout.trim());
+    if (normalized !== repository)
+        throw new Error("review push remote does not match the authorized GitHub repository");
+}
+function assertCommitAncestry(subject, env, runner) {
+    const result = runner({
+        command: "git",
+        args: ["merge-base", "--is-ancestor", subject.worktree_base_commit, subject.expected_commit],
+        cwd: subject.worktree_root,
+        env: gitEnvironment(env),
+        timeoutMs: 10_000,
+        maxBufferBytes: 64 * 1024,
+    });
+    if (!processSucceeded(result))
+        throw new Error("verified review commit does not descend from its frozen base");
+}
+function assertSecretScan(result, phase, subject) {
+    if (result.phase !== phase
+        || result.ticket_id !== subject.ticket_id
+        || result.base_commit !== subject.worktree_base_commit
+        || result.verified_commit !== subject.expected_commit
+        || result.passed !== true)
+        throw new Error(`${phase} secret scan does not match the protected review delivery`);
+}
+function toProgress(record) {
+    return Object.freeze({
+        status: record.state === "ready" ? "ready" : record.state === "blocked" ? "blocked" : record.state === "awaiting-check" || record.state === "pr-pending" ? "waiting" : "working",
+        delivery_id: record.record_id,
+        state: record.state,
+        ticket_id: record.payload.subject.ticket_id,
+        branch: record.payload.review_branch,
+        pull_request_number: record.payload.pull_request?.number ?? null,
+        proof: record.payload.proof,
+        reason: record.payload.blocked_reason,
+    });
+}
+function parseIssueNumber(url, repository) {
+    const escaped = repository.split("/").map(escapeRegExp).join("/");
+    const match = new RegExp(`^https://github\\.com/${escaped}/issues/([1-9][0-9]*)$`, "u").exec(url.toLowerCase());
+    if (!match)
+        throw new Error("GitHub ticket URL does not match its authorized repository");
+    return positiveInteger(Number(match[1]), "GitHub issue number");
+}
+function replacePendingReceipt(receipts, contact, responseSha256) {
+    let replaced = false;
+    const next = receipts.map((receipt) => {
+        if (receipt.contact.contact_id !== contact.contact_id || receipt.response_sha256 !== null)
+            return receipt;
+        replaced = true;
+        return { ...receipt, response_sha256: responseSha256 };
+    });
+    if (!replaced)
+        throw new Error("review contact result lacks its pending intent");
+    return next;
+}
+function sameReference(left, right) {
+    return canonicalJson(left) === canonicalJson(right);
+}
+function samePullRequest(left, right) {
+    return left !== null && right !== null && canonicalJson(left) === canonicalJson(right);
+}
+function selectLatestCandidate(current, candidate) {
+    if (!current)
+        return candidate;
+    const timeDelta = Date.parse(candidate.effectiveAt) - Date.parse(current.effectiveAt);
+    if (timeDelta > 0)
+        return candidate;
+    if (timeDelta < 0)
+        return current;
+    if (candidate.change === current.change && canonicalJson(candidate.snapshot) === canonicalJson(current.snapshot)) {
+        return candidate.eventId.localeCompare(current.eventId) > 0 ? candidate : current;
+    }
+    return { ...current, ambiguous: true };
+}
+function eventEffectiveTimestamp(value, fallback) {
+    return value === null || value === undefined
+        ? fallback
+        : canonicalTimestamp(String(value), "review GitHub snapshot timestamp");
+}
+function monotonicObject(label, before, after) {
+    if (before !== null && canonicalJson(before) !== canonicalJson(after))
+        throw new Error(`${label} is immutable once attached`);
+}
+function safeRun(runner, request) {
+    try {
+        return runner(request);
+    }
+    catch (error) {
+        return { status: null, signal: null, stdout: "", stderr: "", error: error instanceof Error ? error : new Error("process runner threw") };
+    }
+}
+function processSucceeded(result) {
+    return result.error === undefined && result.status === 0 && result.signal === null;
+}
+function processResultDigest(result) {
+    return sha256(canonicalJson({
+        status: result.status,
+        signal: result.signal,
+        stdout_sha256: sha256(result.stdout),
+        stderr_sha256: sha256(result.stderr),
+        error_name: result.error?.name ?? null,
+    }));
+}
+function publicProcessRequest(request) {
+    return {
+        command: request.command,
+        args: request.args,
+        cwd_sha256: sha256(request.cwd),
+        input_sha256: request.input === undefined ? null : sha256(request.input),
+        timeout_ms: request.timeoutMs,
+        max_buffer_bytes: request.maxBufferBytes,
+    };
+}
+function githubEnvironment(source) {
+    if (source.GH_HOST && source.GH_HOST !== "github.com")
+        throw new Error("review delivery supports github.com only");
+    const env = {};
+    for (const key of ["PATH", "HOME", "GH_TOKEN", "GITHUB_TOKEN", "GH_HOST", "NO_COLOR"]) {
+        if (source[key] !== undefined)
+            env[key] = source[key];
+    }
+    return env;
+}
+function gitEnvironment(source) {
+    const env = {};
+    for (const key of ["PATH", "HOME", "TMPDIR", "TMP", "TEMP", "LANG", "LC_ALL", "SYSTEMROOT", "SSH_AUTH_SOCK", "SSH_AGENT_PID"]) {
+        if (source[key] !== undefined)
+            env[key] = source[key];
+    }
+    env.GIT_TERMINAL_PROMPT = "0";
+    env.GIT_CONFIG_NOSYSTEM = "1";
+    env.GIT_CONFIG_GLOBAL = "/dev/null";
+    return env;
+}
+function exactRecord(value, keys, label) {
+    if (!isRecord(value) || Object.keys(value).sort().join("\0") !== [...keys].sort().join("\0")) {
+        throw new Error(`${label} has an invalid shape`);
+    }
+    return value;
+}
+function nodeId(value, label) {
+    if (typeof value !== "string" || !/^[A-Za-z0-9_=-]{1,256}$/u.test(value))
+        throw new Error(`invalid ${label}`);
+    return value;
+}
+function commit(value, label) {
+    if (typeof value !== "string" || !SHA_PATTERN.test(value))
+        throw new Error(`invalid ${label}`);
+    return value;
+}
+function githubUrl(value, label) {
+    if (typeof value !== "string" || !/^https:\/\/github\.com\/[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+\/pull\/[1-9][0-9]*$/u.test(value)) {
+        throw new Error(`invalid ${label}`);
+    }
+    return value;
+}
+function positiveInteger(value, label) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 1)
+        throw new Error(`invalid ${label}`);
+    return value;
+}
+function validateRequiredCheck(value) {
+    if (!REQUIRED_CHECK_PATTERN.test(value))
+        throw new Error("invalid required review check name");
+    return value;
+}
+function nextTimestamp(previous, clock) {
+    const candidate = canonicalTimestamp(clock(), "review timestamp");
+    return new Date(Math.max(Date.parse(candidate), Date.parse(previous) + 1)).toISOString();
+}
+function timestampAfter(...timestamps) {
+    if (timestamps.length === 0)
+        throw new Error("review finalization requires evidence timestamps");
+    const latest = Math.max(...timestamps.map((timestamp) => (Date.parse(canonicalTimestamp(timestamp, "review evidence timestamp")))));
+    return new Date(latest + 1).toISOString();
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+}
+function canonicalBytes(value) {
+    return Buffer.from(`${canonicalJson(value)}\n`, "utf8");
+}
+function canonicalJson(value) {
+    if (value === undefined)
+        throw new Error("review delivery data cannot be undefined");
+    if (value === null || typeof value === "boolean" || typeof value === "number" || typeof value === "string")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    if (!isRecord(value))
+        throw new Error("review delivery data must be JSON");
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`).join(",")}}`;
+}
+function sha256(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+//# sourceMappingURL=review.js.map