@kungfu-tech/buildchain 4.1.3-alpha.1 → 4.1.3-alpha.10

package/packages/core/providers/github/attempt-journal.js

@@ -0,0 +1,154 @@
+import { createHash } from "node:crypto";
+import {
+  canonicalJson,
+  recordDigest,
+} from "../../release/discussion/envelope.js";
+import { validateJournal } from "../../workflow/attempt/journal.js";
+
+const PATH = "attempt.json";
+const LIMIT = 34 * 1024 * 1024;
+
+function exactSha(value) {
+  if (!/^[0-9a-f]{40}$/u.test(value || ""))
+    throw new Error("Attempt journal requires an exact Git SHA");
+  return value;
+}
+
+export function githubAttemptJournal(request) {
+  function coordinates(intent) {
+    if (
+      !/^[\w.-]+\/[\w.-]+$/u.test(intent.repository) ||
+      !/^sha256:[0-9a-f]{64}$/u.test(intent.id)
+    )
+      throw new Error("Invalid attempt journal coordinates");
+    return {
+      base: `/repos/${intent.repository}`,
+      ref: `buildchain/attempts/${intent.id.slice(7)}`,
+    };
+  }
+  async function verifyRepository(intent, base) {
+    const repository = await request(base);
+    if (repository.node_id !== intent.source.repositoryId)
+      throw new Error("Attempt repository identity changed");
+  }
+  async function read(intent) {
+    const { base, ref } = coordinates(intent);
+    await verifyRepository(intent, base);
+    const pointer = await request(`${base}/git/ref/heads/${ref}`, {
+      allow404: true,
+    });
+    if (!pointer) return null;
+    if (pointer.object?.type !== "commit")
+      throw new Error("Attempt journal ref is not a commit");
+    const result = await readCommit(intent.repository, pointer.object.sha);
+    validateJournal(result.snapshot, intent);
+    return result;
+  }
+  async function readCommit(repository, commitSha) {
+    if (!/^[\w.-]+\/[\w.-]+$/u.test(repository || ""))
+      throw new Error("Invalid attempt journal repository");
+    const base = `/repos/${repository}`;
+    const sha = exactSha(commitSha);
+    const commit = await request(`${base}/git/commits/${sha}`);
+    const tree = await request(
+      `${base}/git/trees/${exactSha(commit.tree?.sha)}`,
+    );
+    if (
+      tree.truncated ||
+      tree.tree?.length !== 1 ||
+      tree.tree[0].path !== PATH ||
+      tree.tree[0].type !== "blob" ||
+      tree.tree[0].mode !== "100644"
+    )
+      throw new Error("Invalid attempt journal tree");
+    const blobSha = exactSha(tree.tree[0].sha);
+    const blob = await request(`${base}/git/blobs/${blobSha}`);
+    if (
+      blob.encoding !== "base64" ||
+      !Number.isSafeInteger(blob.size) ||
+      blob.size < 0 ||
+      blob.size > LIMIT ||
+      typeof blob.content !== "string" ||
+      blob.content.length > LIMIT * 2
+    )
+      throw new Error("Invalid or oversized attempt journal blob");
+    const bytes = Buffer.from(blob.content, "base64");
+    const digest = createHash("sha1")
+      .update(`blob ${bytes.length}\0`)
+      .update(bytes)
+      .digest("hex");
+    if (bytes.length !== blob.size || digest !== blobSha)
+      throw new Error("Attempt journal blob integrity mismatch");
+    const snapshot = JSON.parse(bytes.toString("utf8"));
+    if (snapshot.intent?.repository !== repository)
+      throw new Error("Attempt journal snapshot belongs to another repository");
+    validateJournal(snapshot, snapshot.intent);
+    await verifyRepository(snapshot.intent, base);
+    return { commit: sha, snapshot };
+  }
+  async function append({ intent, snapshot, expectedCommit }) {
+    validateJournal(snapshot, intent);
+    const { base, ref } = coordinates(intent);
+    await verifyRepository(intent, base);
+    const bytes = `${canonicalJson(snapshot)}\n`;
+    if (Buffer.byteLength(bytes) > LIMIT)
+      throw new Error("Attempt journal byte bound exceeded");
+    const blob = await request(`${base}/git/blobs`, {
+      method: "POST",
+      body: { content: bytes, encoding: "utf-8" },
+    });
+    const tree = await request(`${base}/git/trees`, {
+      method: "POST",
+      body: {
+        tree: [
+          { path: PATH, mode: "100644", type: "blob", sha: exactSha(blob.sha) },
+        ],
+      },
+    });
+    const commit = await request(`${base}/git/commits`, {
+      method: "POST",
+      body: {
+        message: `chore(attempt): append ${snapshot.root}`,
+        tree: exactSha(tree.sha),
+        parents: expectedCommit ? [exactSha(expectedCommit)] : [],
+      },
+    });
+    const sha = exactSha(commit.sha);
+    if (expectedCommit)
+      await request(`${base}/git/refs/heads/${ref}`, {
+        method: "PATCH",
+        body: { sha, force: false },
+      });
+    else
+      await request(`${base}/git/refs`, {
+        method: "POST",
+        body: { ref: `refs/heads/${ref}`, sha },
+      });
+    return { commit: sha };
+  }
+  async function lookup(repository, pullRequest, targetBranch) {
+    if (
+      !Number.isSafeInteger(pullRequest) ||
+      pullRequest < 1 ||
+      !/^(?:dev|alpha|release|publish-gate)\/[A-Za-z0-9/._-]+$/u.test(
+        targetBranch || "",
+      ) ||
+      targetBranch.includes("..")
+    )
+      throw new Error("Invalid pipeline intent lookup");
+    const id = recordDigest({
+      repository,
+      key: `pr-${pullRequest}:${targetBranch}`,
+    });
+    const { base, ref } = coordinates({ repository, id });
+    const pointer = await request(`${base}/git/ref/heads/${ref}`, {
+      allow404: true,
+    });
+    if (!pointer) return null;
+    const result = await readCommit(repository, pointer.object?.sha);
+    if (result.snapshot.intent.id !== id)
+      throw new Error("Pipeline intent lookup drift");
+    return result;
+  }
+  return { read, append, readCommit, lookup };
+}

package/packages/core/providers/github/discussions/materials.js

@@ -6,9 +6,17 @@ export function materialDigest(bytes) {
 
 // Draft release assets retain immutable recovery bytes outside the source Git
 // object database. Only the Discussion record selects a committed manifest.
-export function discussionMaterials({ octokit, repository, intentId }) {
+export function discussionMaterials({
+  octokit,
+  repository,
+  intentId,
+  partition = "",
+  authorityDescription = "The associated Discussion owns transaction state.",
+}) {
   const [owner, repo] = repository.split("/");
-  const tag = `buildchain-records/${intentId.replace("sha256:", "")}`;
+  if (partition && !/^[1-9][0-9]*-[1-9][0-9]*-[1-9][0-9]*$/u.test(partition))
+    throw new Error("Invalid material archive writer partition");
+  const tag = `buildchain-records/${intentId.replace("sha256:", "")}${partition ? `/${partition}` : ""}`;
   const repos = octokit.rest.repos;
   let retainedArchive;
   async function findArchive() {
@@ -27,8 +35,7 @@ export function discussionMaterials({ octokit, repository, intentId }) {
       throw new Error("Ambiguous transaction material archive");
     return matches[0];
   }
-  async function archive() {
-    if (retainedArchive) return retainedArchive;
+  async function createArchive() {
     let release = await findArchive();
     if (!release) {
       try {
@@ -40,7 +47,7 @@ export function discussionMaterials({ octokit, repository, intentId }) {
             // Storage archives use the repository default; candidate identity is
             // retained in the material manifest, never in a storage Git ref.
             name: `Buildchain transaction materials ${intentId}`,
-            body: "Immutable recovery material. The associated Discussion owns transaction state.",
+            body: `Immutable recovery material. ${authorityDescription}`,
             draft: true,
             prerelease: true,
           })
@@ -55,9 +62,15 @@ export function discussionMaterials({ octokit, repository, intentId }) {
     }
     if (!release.draft || release.tag_name !== tag)
       throw new Error("Transaction material archive identity mismatch");
-    retainedArchive = release;
     return release;
   }
+  function archive() {
+    // Concurrent puts in one writer share the same creation, including readback.
+    return (retainedArchive ||= createArchive().catch((error) => {
+      retainedArchive = undefined;
+      throw error;
+    }));
+  }
   async function read(handle) {
     const response = await repos.getReleaseAsset({
       owner,

package/packages/core/providers/github/pipeline-checkout.js

@@ -0,0 +1,49 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { githubAuthEnv } from "../source-checkout/auth.js";
+import { createNativeChildEnvironment } from "../../dev-delivery/native/execution.js";
+
+// Read-only Git object access for credentialed source qualification. This is a
+// bare repository: no consumer checkout, hooks or build scripts are executed.
+export async function withPipelineSourceObjects(
+  { repository, sourceHead, baseCommit, token },
+  operation,
+) {
+  if (
+    !/^[\w.-]+\/[\w.-]+$/u.test(repository || "") ||
+    ![sourceHead, baseCommit].every((sha) => /^[0-9a-f]{40}$/u.test(sha || ""))
+  )
+    throw new Error(
+      "Pipeline qualification requires exact repository source coordinates",
+    );
+  const directory = fs.mkdtempSync(
+    path.join(os.tmpdir(), "buildchain-pipeline-source-"),
+  );
+  const environment = {
+    ...createNativeChildEnvironment(process.env),
+    GIT_TERMINAL_PROMPT: "0",
+    ...githubAuthEnv(token),
+  };
+  const git = (args) =>
+    execFileSync("git", ["-C", directory, ...args], {
+      env: environment,
+      stdio: ["ignore", "pipe", "pipe"],
+      maxBuffer: 32 * 1024 * 1024,
+    });
+  try {
+    git(["init", "--bare", "--quiet"]);
+    git([
+      "fetch",
+      "--quiet",
+      "--no-tags",
+      `https://github.com/${repository}.git`,
+      sourceHead,
+      baseCommit,
+    ]);
+    return await operation(directory);
+  } finally {
+    fs.rmSync(directory, { recursive: true, force: true });
+  }
+}

package/packages/core/providers/github/pipeline-entry-runs.js

@@ -0,0 +1,210 @@
+import { createHash } from "node:crypto";
+import { runtimeSelector } from "../../runtime/entry/selection.js";
+import { pipelineRunEntry, readPipelineCaller } from "./pipeline-run-entry.js";
+import { recordDigest } from "../../release/discussion/envelope.js";
+
+export async function pipelineEntryRuns(host, publishedAt) {
+  const created = encodeURIComponent(
+    `>=${new Date(publishedAt).toISOString()}`,
+  );
+  const prefix = `/repos/${host.repository}/actions/workflows/buildchain.yml/runs`;
+  const runs = [],
+    ids = new Set();
+  for (let page = 1; page <= 10; page++) {
+    const result = await host.request(
+      `${prefix}?event=pull_request&status=completed&created=${created}&per_page=100&page=${page}`,
+      { allow404: true },
+    );
+    if (!result && page === 1) return [];
+    if (
+      !Array.isArray(result?.workflow_runs) ||
+      result.workflow_runs.length > 100
+    )
+      throw new Error("Published entry run inventory is incomplete");
+    for (const run of result.workflow_runs) {
+      if (
+        !Number.isSafeInteger(run.id) ||
+        run.id < 1 ||
+        ids.has(run.id) ||
+        !Number.isSafeInteger(run.run_attempt) ||
+        run.run_attempt < 1 ||
+        !Number.isFinite(Date.parse(run.created_at))
+      )
+        throw new Error(
+          "Published entry run inventory has ambiguous coordinates",
+        );
+      ids.add(run.id);
+      runs.push(run);
+    }
+    if (result.workflow_runs.length < 100)
+      return runs.sort(
+        (a, b) =>
+          Date.parse(b.created_at) - Date.parse(a.created_at) || b.id - a.id,
+      );
+  }
+  throw new Error(
+    "Published entry run inventory exceeds its complete-read bound",
+  );
+}
+
+async function sourceLock(host, source, channel) {
+  const pathname =
+    channel === "v4-alpha"
+      ? ".buildchain/alpha-contract-lock.json"
+      : ".buildchain/contract-lock.json";
+  const file = await host.request(
+    `/repos/${host.repository}/contents/${pathname}?ref=${source.commit}`,
+    { allow404: true },
+  );
+  if (!file) return { value: undefined, evidence: null };
+  if (
+    file.type !== "file" ||
+    file.encoding !== "base64" ||
+    !Number.isSafeInteger(file.size) ||
+    file.size < 1 ||
+    file.size > 1024 * 1024 ||
+    typeof file.content !== "string" ||
+    file.content.length > 2 * 1024 * 1024
+  )
+    throw new Error("Published entry runtime lock exceeds its source boundary");
+  const bytes = Buffer.from(file.content, "base64");
+  const blob = createHash("sha1")
+    .update(`blob ${bytes.length}\0`)
+    .update(bytes)
+    .digest("hex");
+  if (bytes.length !== file.size || blob !== file.sha)
+    throw new Error("Published entry runtime lock bytes changed");
+  const value = JSON.parse(
+    new TextDecoder("utf-8", { fatal: true }).decode(bytes),
+  );
+  if (
+    value.schema === "buildchain.consumer-contract-lock/v2" &&
+    value.configDigest !== source.configDigest
+  )
+    throw new Error(
+      "Published entry runtime lock belongs to another consumer configuration",
+    );
+  return {
+    value,
+    evidence: {
+      path: pathname,
+      blob,
+      digest: `sha256:${createHash("sha256").update(bytes).digest("hex")}`,
+    },
+  };
+}
+
+export async function pipelineEntryRun(run, plan, source, host) {
+  if (
+    run.event !== "pull_request" ||
+    run.status !== "completed" ||
+    run.repository?.full_name !== host.repository ||
+    run.head_repository?.full_name !== host.repository ||
+    run.path?.split("@")[0] !== ".github/workflows/buildchain.yml" ||
+    !Number.isFinite(Date.parse(run.created_at)) ||
+    Date.parse(run.created_at) < Date.parse(source.candidate.publishedAt)
+  )
+    return null;
+  const entry = pipelineRunEntry(run);
+  if (entry.recovery || entry.definition.sha !== source.candidate.sha)
+    return null;
+  const consumer = await host.source.source(
+    run.head_sha,
+    plan.source.configPath,
+  );
+  if (recordDigest(consumer.plan) !== plan.contractRoot) return null;
+  if (
+    consumer.identity.commit !== run.head_sha ||
+    consumer.identity.configPath !== plan.source.configPath ||
+    consumer.identity.repository !== host.repository
+  )
+    throw new Error("Published entry consumer source changed during readback");
+  await readPipelineCaller(
+    run,
+    consumer.identity.configPath,
+    host.request,
+    host.repository,
+  );
+  const lock = await sourceLock(host, consumer.identity, entry.channel);
+  const selection = runtimeSelector({
+    lock: lock.value,
+    workflowSha: entry.definition.sha,
+  });
+  if (selection.ref !== source.candidate.sha) return null;
+  return {
+    source: consumer.identity,
+    entry: entry.definition,
+    selection,
+    lock: lock.evidence,
+  };
+}
+
+export async function pipelineEntryCheck(run, host) {
+  const checks = [],
+    ids = new Set();
+  const prefix = `/repos/${host.repository}/commits/${run.head_sha}/check-runs`;
+  for (let page = 1; page <= 10; page++) {
+    const result = await host.request(
+      `${prefix}?check_name=check&filter=all&per_page=100&page=${page}`,
+    );
+    if (!Array.isArray(result?.check_runs) || result.check_runs.length > 100)
+      throw new Error("Published entry check inventory is incomplete");
+    for (const check of result.check_runs) {
+      if (!Number.isSafeInteger(check.id) || check.id < 1 || ids.has(check.id))
+        throw new Error(
+          "Published entry check inventory has ambiguous identities",
+        );
+      ids.add(check.id);
+      checks.push(check);
+    }
+    if (result.check_runs.length < 100)
+      return exactCheck(checks, run, host.repository);
+  }
+  throw new Error(
+    "Published entry check inventory exceeds its complete-read bound",
+  );
+}
+
+function exactCheck(checks, run, repository) {
+  const url = `https://github.com/${repository}/actions/runs/${run.id}/attempts/${run.run_attempt}`;
+  // Actions may replace details_url with the check's own provider URL. Its
+  // exact external execution identity still binds the original native receipt.
+  const matches = checks.filter(
+    (check) =>
+      check.name === "check" &&
+      (check.details_url === url ||
+        (check.details_url ===
+          `https://github.com/${repository}/runs/${check.id}` &&
+          check.external_id?.endsWith(`:${run.id}:${run.run_attempt}`))),
+  );
+  if (!matches.length) return null;
+  const values = matches.map((check) => {
+    const parsed =
+      /^buildchain:(attempt-[0-9a-f]{64}):([1-9][0-9]*):([1-9][0-9]*)$/u.exec(
+        check.external_id || "",
+      );
+    if (
+      !parsed ||
+      Number(parsed[2]) !== run.id ||
+      Number(parsed[3]) !== run.run_attempt ||
+      check.head_sha !== run.head_sha ||
+      check.status !== "completed" ||
+      !["success", "failure"].includes(check.conclusion) ||
+      check.app?.slug !== "github-actions"
+    )
+      throw new Error(
+        "Published entry check does not bind its exact native attempt",
+      );
+    return {
+      attempt: parsed[1],
+      outcome: check.conclusion,
+      summary: check.output?.summary || "",
+    };
+  });
+  if (values.some((value) => recordDigest(value) !== recordDigest(values[0])))
+    throw new Error("Published entry checks disagree about the same execution");
+  return {
+    ...values[0],
+    ids: matches.map(({ id }) => id).sort((a, b) => a - b),
+  };
+}

package/packages/core/providers/github/pipeline-events.js

@@ -0,0 +1,131 @@
+import { readBusinessAttempt } from "../../workflow/attempt/reader.js";
+
+// The current provider timeline survives webhook/runtime handoff. Compare it
+// with this candidate's lifetime so an earlier removal cannot cancel recovery.
+export function githubPipelineQueueExit(graphql, repository) {
+  if (!/^[\w.-]+\/[\w.-]+$/u.test(repository || ""))
+    throw new Error("Invalid pipeline queue repository");
+  const [owner, repo] = repository.split("/");
+  return async (current, candidate) => {
+    if (!candidate || candidate.terminal) return null;
+    const started = Date.parse(candidate.enqueuedAt);
+    if (!Number.isFinite(started))
+      throw new Error("Queue candidate timestamp is missing");
+    const number = current.intent.source.pullRequest;
+    const result = await graphql(
+      `
+        query ($owner: String!, $repo: String!, $number: Int!) {
+          repository(owner: $owner, name: $repo) {
+            pullRequest(number: $number) {
+              number
+              headRefOid
+              baseRefName
+              state
+              mergeQueueEntry {
+                id
+              }
+              timelineItems(
+                last: 2
+                itemTypes: [
+                  ADDED_TO_MERGE_QUEUE_EVENT
+                  REMOVED_FROM_MERGE_QUEUE_EVENT
+                ]
+              ) {
+                nodes {
+                  __typename
+                  ... on AddedToMergeQueueEvent {
+                    id
+                    createdAt
+                  }
+                  ... on RemovedFromMergeQueueEvent {
+                    id
+                    createdAt
+                  }
+                }
+              }
+            }
+          }
+        }
+      `,
+      { owner, repo, number },
+    );
+    const pr = result.repository?.pullRequest;
+    if (
+      pr?.number !== number ||
+      pr.headRefOid !== current.generation.source.commit ||
+      pr.baseRefName !== current.intent.source.targetBranch
+    )
+      throw new Error("Queue exit source identity changed; reobserve");
+    if (pr.state !== "OPEN" || pr.mergeQueueEntry) return null;
+    const nodes = pr.timelineItems?.nodes;
+    if (!Array.isArray(nodes) || nodes.length > 2)
+      throw new Error("Queue exit timeline readback is missing or ambiguous");
+    const event = nodes.at(-1);
+    if (event?.__typename !== "RemovedFromMergeQueueEvent") return null;
+    const queued = nodes.at(-2);
+    if (queued?.__typename !== "AddedToMergeQueueEvent")
+      throw new Error("Queue removal has no matching admission readback");
+    const removed = Date.parse(event.createdAt);
+    const entered = Date.parse(queued.createdAt);
+    if (
+      !event.id ||
+      !queued.id ||
+      !Number.isFinite(removed) ||
+      !Number.isFinite(entered) ||
+      entered > removed
+    )
+      throw new Error("Queue removal identity or timestamp is missing");
+    return entered > started ? event : null;
+  };
+}
+
+// Branch/terminal notifications wake existing intents only. They cannot create
+// historical releases or infer an execution request from an untracked old PR.
+export function githubPipelineEvents(request, journal, repository) {
+  if (!/^[\w.-]+\/[\w.-]+$/u.test(repository || ""))
+    throw new Error("Invalid pipeline event repository");
+  const base = `/repos/${repository}`;
+  async function list(url) {
+    const rows = [];
+    for (let page = 1; page <= 100; page++) {
+      const entries = await request(
+        `${url}${url.includes("?") ? "&" : "?"}per_page=100&page=${page}`,
+      );
+      if (!Array.isArray(entries))
+        throw new Error("Invalid pipeline PR event readback");
+      rows.push(...entries);
+      if (entries.length < 100) return rows;
+    }
+    throw new Error("Pipeline PR event readback exceeds its bound");
+  }
+  async function branch(branch, commit = "") {
+    if (
+      !/^(?:dev|alpha|release|publish-gate)\/[A-Za-z0-9/._-]+$/u.test(
+        branch || "",
+      ) ||
+      branch.includes("..")
+    )
+      throw new Error("Invalid pipeline branch event");
+    const pulls = await list(
+      `${base}/pulls?state=open&base=${encodeURIComponent(branch)}`,
+    );
+    if (commit) {
+      if (!/^[0-9a-f]{40}$/u.test(commit))
+        throw new Error("Branch wake requires exact source commit");
+      pulls.push(...(await list(`${base}/commits/${commit}/pulls`)));
+    }
+    const result = new Set();
+    for (const number of [
+      ...new Set(
+        pulls.filter((pr) => pr.base?.ref === branch).map((pr) => pr.number),
+      ),
+    ]) {
+      const retained = await journal.lookup(repository, number, branch);
+      if (!retained) continue;
+      const state = readBusinessAttempt(retained.snapshot);
+      if (state.attempt) result.add(state.attempt);
+    }
+    return [...result];
+  }
+  return { branch };
+}

package/packages/core/providers/github/pipeline-integration.js

@@ -0,0 +1,95 @@
+import { recordDigest } from "../../release/discussion/envelope.js";
+import { pipelinePlatforms } from "../../workflow/pipeline/platforms.js";
+
+export function githubPipelineIntegration(request, repository, source, runs) {
+  const base = `/repos/${repository}`;
+  async function observe(current) {
+    const number = current.intent.source.pullRequest;
+    const branch = current.intent.source.targetBranch;
+    const pr = await request(`${base}/pulls/${number}`);
+    if (
+      !pr.merged ||
+      pr.head?.sha !== current.generation.source.commit ||
+      pr.base?.ref !== branch ||
+      pr.head?.repo?.full_name !== repository ||
+      pr.base?.repo?.full_name !== repository ||
+      !/^[0-9a-f]{40}$/u.test(pr.merge_commit_sha || "")
+    )
+      throw new Error(
+        "Integration needs the exact source PR merged into its protected target",
+      );
+    const mergeCommit = pr.merge_commit_sha;
+    const protectedHead = await source.branchHead(branch);
+    const ancestry = await request(
+      `${base}/compare/${mergeCommit}...${protectedHead}`,
+    );
+    if (
+      !["identical", "ahead"].includes(ancestry.status) ||
+      ancestry.merge_base_commit?.sha !== mergeCommit
+    )
+      throw new Error(
+        "Exact merge commit is not contained in the protected branch",
+      );
+    const commits = await source.source(
+      mergeCommit,
+      current.generation.source.configPath,
+    );
+    const response = await request(
+      `${base}/actions/runs?event=merge_group&head_sha=${mergeCommit}&per_page=100`,
+    );
+    if (!Array.isArray(response.workflow_runs) || response.total_count > 100)
+      throw new Error(
+        "Exact merge-group run inventory is unavailable or ambiguous",
+      );
+    const candidates = response.workflow_runs.filter(
+      (run) =>
+        run.status === "completed" &&
+        run.conclusion === "success" &&
+        run.path?.split("@")[0] === ".github/workflows/buildchain.yml",
+    );
+    if (!candidates.length)
+      throw new Error(
+        "Exact merged commit has no successful normal pipeline merge-group run",
+      );
+    const chosen = candidates.sort((a, b) => b.id - a.id)[0];
+    const { run } = await runs.read(chosen.id, chosen.run_attempt);
+    if (
+      run.status !== "completed" ||
+      run.conclusion !== "success" ||
+      run.event !== "merge_group" ||
+      run.head_sha !== mergeCommit
+    )
+      throw new Error("Integration merge-group execution changed");
+    const build = await runs.build(
+      run.id,
+      run.run_attempt,
+      commits.identity,
+      pipelinePlatforms(commits.plan).map((item) => item.platform),
+    );
+    if (build.outcome !== "success")
+      throw new Error("Exact merged tree product verification failed");
+    const again = await request(`${base}/pulls/${number}`);
+    if (
+      !again.merged ||
+      again.merge_commit_sha !== mergeCommit ||
+      again.head.sha !== pr.head.sha ||
+      again.base.ref !== branch
+    )
+      throw new Error("Integration provider source changed during readback");
+    const body = {
+      schema: "buildchain.pipeline-integration-readback/v1",
+      repository,
+      pullRequest: number,
+      sourceHead: pr.head.sha,
+      branch,
+      protectedHead,
+      mergeCommit,
+      mergeTree: commits.identity.tree,
+      run,
+      build,
+      ancestry,
+    };
+    return { ...body, root: recordDigest(body) };
+  }
+  return { observe };
+}