@kungfu-tech/buildchain 4.1.3-alpha.0 → 4.1.3-alpha.2

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,7 +6,12 @@ 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,
+  authorityDescription = "The associated Discussion owns transaction state.",
+}) {
   const [owner, repo] = repository.split("/");
   const tag = `buildchain-records/${intentId.replace("sha256:", "")}`;
   const repos = octokit.rest.repos;
@@ -40,7 +45,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,
           })
@@ -72,11 +77,13 @@ export function discussionMaterials({ octokit, repository, intentId }) {
       );
     return bytes;
   }
-  async function put(bytes) {
+  async function put(bytes, descriptor = {}) {
+    const extension =
+      descriptor.name?.match(/\.([a-zA-Z0-9]{1,8})$/u)?.[1] || "";
     if (bytes.length > 256 * 1024 * 1024)
       throw new Error("Transaction material exceeds the supported file bound");
     const digest = materialDigest(bytes),
-      name = digest.replace(":", "-");
+      name = digest.replace(":", "-") + (extension ? `.${extension}` : "");
     const release = await archive();
     const find = async () => {
       const assets = await octokit.paginate(repos.listReleaseAssets, {
@@ -101,7 +108,8 @@ export function discussionMaterials({ octokit, repository, intentId }) {
             name,
             data: bytes,
             headers: {
-              "content-type": "application/octet-stream",
+              "content-type":
+                descriptor.mediaType || "application/octet-stream",
             },
           })
         ).data;
@@ -113,7 +121,15 @@ export function discussionMaterials({ octokit, repository, intentId }) {
           });
       }
     }
-    const handle = { id: asset.id, digest, size: bytes.length };
+    const handle = {
+      id: asset.id,
+      digest,
+      size: bytes.length,
+      ...(asset.browser_download_url
+        ? { downloadUrl: asset.browser_download_url }
+        : {}),
+      ...(release.html_url ? { archiveUrl: release.html_url } : {}),
+    };
     await read(handle);
     return handle;
   }
@@ -140,7 +156,7 @@ export function discussionMaterials({ octokit, repository, intentId }) {
     }
   }
   return {
-    put: (bytes) => diagnose("put", () => put(bytes)),
+    put: (bytes, descriptor) => diagnose("put", () => put(bytes, descriptor)),
     read: (handle) => diagnose("read", () => read(handle)),
   };
 }

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

@@ -1,7 +1,7 @@
 const fields =
   "id number url body author { __typename login ... on Node { id } } lastEditedAt repository { nameWithOwner }";
 const commentFields =
-  "id url body author { __typename login ... on Node { id } } lastEditedAt";
+  "id url body author { __typename login ... on Node { id } } lastEditedAt replyTo { id }";
 
 export function discussionTransport(graphql) {
   async function request(query, variables) {
@@ -66,13 +66,22 @@ export function discussionTransport(graphql) {
   }
   async function comments(id, after = null) {
     const result = await request(
-      `query($id:ID!,$after:String){node(id:$id){... on Discussion{comments(first:100,after:$after){nodes{${commentFields}} pageInfo{hasNextPage endCursor}}}}}`,
+      `query($id:ID!,$after:String){node(id:$id){... on Discussion{comments(first:100,after:$after){nodes{${commentFields} replies{totalCount}} pageInfo{hasNextPage endCursor}}}}}`,
       { id, after },
     );
     if (!result.node?.comments)
       throw new Error("Release Discussion comments are unavailable");
     return result.node.comments;
   }
+  async function replies(id, after = null) {
+    const result = await request(
+      `query($id:ID!,$after:String){node(id:$id){... on DiscussionComment{replies(first:100,after:$after){nodes{${commentFields}} pageInfo{hasNextPage endCursor}}}}}`,
+      { id, after },
+    );
+    if (!result.node?.replies)
+      throw new Error("Release Discussion replies are unavailable");
+    return result.node.replies;
+  }
   async function create({ repositoryId, categoryId, title, body }) {
     const result = await request(
       `mutation($input:CreateDiscussionInput!){createDiscussion(input:$input){discussion{${fields}}}}`,
@@ -80,14 +89,16 @@ export function discussionTransport(graphql) {
     );
     return result.createDiscussion.discussion;
   }
-  async function append(id, body) {
+  async function append(id, body, replyToId = null) {
     const result = await request(
       `mutation($input:AddDiscussionCommentInput!){addDiscussionComment(input:$input){comment{${commentFields}}}}`,
-      { input: { discussionId: id, body } },
+      {
+        input: { discussionId: id, body, ...(replyToId ? { replyToId } : {}) },
+      },
     );
     return result.addDiscussionComment.comment;
   }
-  return { repository, list, get, comments, create, append };
+  return { repository, list, get, comments, replies, create, append };
 }
 
 export async function collectDiscussionPages(readPage, limit = 100) {

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-events.js

@@ -0,0 +1,52 @@
+import { readBusinessAttempt } from "../../workflow/attempt/reader.js";
+
+// 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 };
+}

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

@@ -0,0 +1,213 @@
+import { recordDigest } from "../../release/discussion/envelope.js";
+
+const QUERY = `query PipelinePolicy($owner:String!,$name:String!,$number:Int!){repository(owner:$owner,name:$name){pullRequest(number:$number){id number headRefOid baseRefName isDraft reviewDecision author{login}}}}`;
+const BRANCH_QUERY = `query PipelineBranchPolicy($owner:String!,$name:String!,$branch:String!,$ref:String!){repository(owner:$owner,name:$name){ref(qualifiedName:$ref){branchProtectionRule{requiresApprovingReviews requiredApprovingReviewCount requiresCodeOwnerReviews requiresStatusChecks requiredStatusChecks{context app{databaseId}}}}mergeQueue(branch:$branch){id}}}`;
+
+async function classicPolicy(request, owner, name, branch) {
+  // REST /branches/:branch/protection requires Administration:read. Ordinary
+  // workflow credentials instead read effective rules and GraphQL metadata.
+  const result = await request("/graphql", {
+    method: "POST",
+    body: {
+      query: BRANCH_QUERY,
+      variables: { owner, name, branch, ref: `refs/heads/${branch}` },
+    },
+  });
+  const repository = result.data?.repository;
+  if (!repository) throw new Error("Protected branch metadata is unavailable");
+  const rule = repository.ref?.branchProtectionRule;
+  return {
+    required_merge_queue: Boolean(repository.mergeQueue?.id),
+    required_pull_request_reviews: rule?.requiresApprovingReviews
+      ? {
+          require_code_owner_reviews: rule.requiresCodeOwnerReviews,
+          required_approving_review_count: rule.requiredApprovingReviewCount,
+        }
+      : null,
+    required_status_checks: {
+      checks: rule?.requiresStatusChecks
+        ? (rule.requiredStatusChecks || []).map((check) => ({
+            context: check.context,
+            app_id: check.app?.databaseId || null,
+          }))
+        : [],
+    },
+  };
+}
+
+async function inventory(request, url, key = "") {
+  const rows = [];
+  for (let page = 1; page <= 100; page++) {
+    const response = await request(
+      `${url}${url.includes("?") ? "&" : "?"}per_page=100&page=${page}`,
+    );
+    const entries = key ? response[key] : response;
+    if (!Array.isArray(entries))
+      throw new Error("Missing protected policy inventory");
+    rows.push(...entries);
+    if (entries.length < 100) return rows;
+  }
+  throw new Error("Protected policy inventory exceeds its bound");
+}
+
+function protections(rules, classic, policy) {
+  const reviews = rules
+    .filter((rule) => rule.type === "pull_request")
+    .map((rule) => rule.parameters);
+  if (classic?.required_pull_request_reviews)
+    reviews.push({
+      ...classic.required_pull_request_reviews,
+      require_code_owner_review:
+        classic.required_pull_request_reviews.require_code_owner_reviews,
+    });
+  if (
+    !reviews.some((rule) => rule?.require_code_owner_review === true) ||
+    !reviews.some(
+      (rule) =>
+        rule?.required_approving_review_count >= policy.minimum_approvals,
+    ) ||
+    !(
+      classic?.required_merge_queue ||
+      rules.some((rule) => rule.type === "merge_queue")
+    )
+  )
+    throw new Error(
+      "Protected branch must enforce declared approvals, code owners and merge queue",
+    );
+  const contexts = rules
+    .filter((rule) => rule.type === "required_status_checks")
+    .flatMap((rule) => rule.parameters?.required_status_checks || []);
+  for (const check of classic?.required_status_checks?.checks || [])
+    contexts.push({ context: check.context, integration_id: check.app_id });
+  if (!contexts.length || contexts.some((check) => !check.context))
+    throw new Error(
+      "Protected pipeline requires provider-enforced status checks",
+    );
+  return contexts;
+}
+
+function approved(pr, reviews, minimum) {
+  const latest = new Map();
+  for (const review of [...reviews].sort((a, b) => a.id - b.id)) {
+    if (
+      review.user?.login &&
+      ["APPROVED", "CHANGES_REQUESTED", "DISMISSED"].includes(review.state)
+    )
+      latest.set(review.user.login, review);
+  }
+  const independent = [...latest.values()].filter(
+    (review) => review.user.login !== pr.author?.login,
+  );
+  return (
+    pr.reviewDecision === "APPROVED" &&
+    !independent.some((review) => review.state === "CHANGES_REQUESTED") &&
+    independent.filter(
+      (review) =>
+        review.state === "APPROVED" && review.commit_id === pr.headRefOid,
+    ).length >= minimum
+  );
+}
+
+function checksPass(contexts, checks, statuses) {
+  return contexts.every(({ context, integration_id: app }) => {
+    const candidates = checks.filter(
+      (check) =>
+        check.name === context && (!app || app === -1 || check.app?.id === app),
+    );
+    const latest = candidates.sort((a, b) => b.id - a.id)[0];
+    if (latest)
+      return (
+        latest.status === "completed" &&
+        ["success", "neutral", "skipped"].includes(latest.conclusion)
+      );
+    if (app && app !== -1) return false;
+    return (
+      statuses
+        .filter((status) => status.context === context)
+        .sort((a, b) => b.id - a.id)[0]?.state === "success"
+    );
+  });
+}
+
+export function githubPipelinePolicy(request, repository) {
+  const [owner, name] = repository.split("/");
+  const base = `/repos/${repository}`;
+  async function pull(number) {
+    const response = await request("/graphql", {
+      method: "POST",
+      body: { query: QUERY, variables: { owner, name, number } },
+    });
+    const pr = response.data?.repository?.pullRequest;
+    if (!pr?.id || pr.number !== number)
+      throw new Error("Protected PR policy identity is unavailable");
+    return pr;
+  }
+  async function observe(current, policy, integratedHead) {
+    const { source, baseCommit } = current.generation;
+    const number = current.intent.source.pullRequest,
+      branch = current.intent.source.targetBranch;
+    const pr = await pull(number);
+    if (pr.headRefOid !== source.commit || pr.baseRefName !== branch)
+      throw new Error("Protected PR policy source drift");
+    const branchPath = encodeURIComponent(branch);
+    const rules = await inventory(
+      request,
+      `${base}/rules/branches/${branchPath}`,
+    );
+    const classic = await classicPolicy(request, owner, name, branch);
+    const contexts = protections(rules, classic, policy);
+    const reviews = await inventory(request, `${base}/pulls/${number}/reviews`);
+    const checks = await inventory(
+      request,
+      `${base}/commits/${source.commit}/check-runs?filter=latest`,
+      "check_runs",
+    );
+    const statuses = await inventory(
+      request,
+      `${base}/commits/${source.commit}/statuses`,
+    );
+    const again = await pull(number);
+    const ref = await request(`${base}/git/ref/heads/${branch}`);
+    if (
+      recordDigest(pr) !== recordDigest(again) ||
+      ref.object?.sha !== (integratedHead || baseCommit)
+    )
+      throw new Error("Protected policy changed during readback");
+    const body = {
+      schema: "buildchain.pipeline-policy-readback/v1",
+      source,
+      baseCommit,
+      pr,
+      rules,
+      classic: classic || null,
+      reviews,
+      checks,
+      statuses,
+      contexts,
+      review: !pr.isDraft && approved(pr, reviews, policy.minimum_approvals),
+      checksPassing: checksPass(contexts, checks, statuses),
+      ...(integratedHead ? { integratedHead } : {}),
+    };
+    return { ...body, root: recordDigest(body) };
+  }
+  async function observeMerged(current, policy, integration) {
+    const { root, ...body } = integration;
+    if (
+      root !== recordDigest(body) ||
+      body.schema !== "buildchain.pipeline-integration-readback/v1" ||
+      body.repository !== repository ||
+      body.sourceHead !== current.generation.source.commit ||
+      body.branch !== current.intent.source.targetBranch ||
+      body.pullRequest !== current.intent.source.pullRequest ||
+      !/^[0-9a-f]{40}$/u.test(body.protectedHead || "")
+    )
+      throw new Error(
+        "Merged review qualification requires exact protected integration evidence",
+      );
+    return observe(current, policy, body.protectedHead);
+  }
+  return {
+    observe: (current, policy) => observe(current, policy),
+    observeMerged,
+  };
+}