@kungfu-tech/buildchain 3.0.7 → 3.0.8

package/packages/core/buildchain-contract.js

@@ -1,14 +1,34 @@
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
+import {
+  assertBuildchainCompatibilityProjection,
+  createBuildchainCompatibilityProofRegistry,
+  createHistoricalBuildchainCompatibilityProofs,
+} from "./buildchain-compatibility-proof.js";
 import { createControllerRegistry } from "./controller-evidence.js";
 import { enumerateWorkflowInputs } from "./public-surface-audit.js";
 
+export {
+  BUILDCHAIN_COMPATIBILITY_PROOF_REGISTRY_SCHEMA,
+  BUILDCHAIN_COMPATIBILITY_PROOF_SCHEMA,
+  BUILDCHAIN_COMPATIBILITY_VERIFICATION_RECEIPT_SCHEMA,
+  assertBuildchainCompatibilityProjection,
+  contractSummary,
+  createBuildchainCompatibilityProof,
+  createBuildchainCompatibilityProofRegistry,
+  createBuildchainCompatibilityVerificationReceipt,
+  createHistoricalBuildchainCompatibilityProofs,
+  evaluateBuildchainContractLock,
+  renderBuildchainContractDriftIssueBody,
+  verifyBuildchainCompatibilityProof,
+  verifyBuildchainCompatibilityVerificationReceipt,
+} from "./buildchain-compatibility-proof.js";
+
 export const BUILDCHAIN_RUNTIME_CONTRACT_WORLD = "kungfu-buildchain-runtime-contract-world";
 export const BUILDCHAIN_CONTRACT_LOCK = "kungfu-buildchain-contract-lock";
 
 const DEFAULT_POLICY = "major-compatible";
-const FLOATING_CLASSES = new Set(["stable", "alpha"]);
 
 function optionalString(value) {
   return value === undefined || value === null ? "" : String(value);
@@ -284,9 +304,6 @@ export function createBuildchainContractWorld({
         "publish-gate source locks are created by the wrapper and enforced by promote-buildchain-ref before publish side effects",
         "GitHub Release passport and evidence publication is delegated to promote-buildchain-ref after the semver release transaction completes",
       ],
-      compatibleBreakingDigests: [
-        "sha256:acd401cfc46450115a3763fd4b679d85f185e8757ebd52510d6262e1533df4cf",
-      ],
     }),
     surface(root, {
       id: "advanced-release-candidate-promote",
@@ -328,9 +345,6 @@ export function createBuildchainContractWorld({
         "promotion reuses PR-stage release-candidate artifacts and does not run the heavy native build matrix",
         "resume-from-candidate-run is fail-closed and uses a fresh caller event instead of rerunning a frozen startup graph",
       ],
-      compatibleBreakingDigests: [
-        "sha256:aa30f22e3af0a89841310bdbdc900844dd95a66974db173fa140a71bbd7e82c0",
-      ],
     }),
     surface(root, {
       id: "web-surface",
@@ -477,9 +491,6 @@ export function createBuildchainContractWorld({
         "publish transactions can require a resolved publish-gate source lock to prevent floating-ref drift",
         "semver GitHub Releases are created or updated only after transaction completion, with prerelease/latest metadata bound to the authoritative publication channel and tag syntax retained as the fallback for ordinary callers",
       ],
-      compatibleBreakingDigests: [
-        "sha256:a59f0910e6df842e7699139472e5dd69ac2fdd7f7213bf2cb346d1d622556874",
-      ],
     }),
     surface(root, {
       id: "macos-credential-island-action",
@@ -755,14 +766,6 @@ export function createBuildchainContractWorld({
         registryDigest: resolvedControllerRegistry.digest,
         inputClassifications: descriptor.inputs,
       },
-      ...(descriptor.id === "build-lifecycle"
-        ? {
-            compatibleBreakingDigests: [
-              "sha256:e264a79f9f399038c2fcfd21e4168c68c2e1485ee5c651c02242a02b622ac2be",
-              "sha256:30745921541e9b0f70475bb2178c2559f6aef248f6680670ccd44d8c5a69a6b1",
-            ],
-          }
-        : {}),
       guarantees: [
         "plans bind exact consumer source SHA, exact Buildchain runtime SHA, and the runtime contract digest",
         "receipts bind the plan digest and preserve pass, fail, skip, and partial stage outcomes",
@@ -782,24 +785,45 @@ export function createBuildchainContractWorld({
     },
     majorLine,
     compatibilityPolicy: DEFAULT_POLICY,
+    compatibilityProofs: createHistoricalBuildchainCompatibilityProofs(),
     surfaces,
   };
   return finalizeBuildchainContractWorld(base);
 }
 
 export function finalizeBuildchainContractWorld(contractWorld) {
+  const sourceSurfaces = (contractWorld.surfaces || []).map((entry) => ({ ...entry }));
+  const proofRegistry = createBuildchainCompatibilityProofRegistry({
+    proofs: contractWorld.compatibilityProofs || createHistoricalBuildchainCompatibilityProofs(),
+    surfaces: sourceSurfaces,
+    majorLine: contractWorld.majorLine,
+  });
   const world = {
     ...contractWorld,
-    surfaces: (contractWorld.surfaces || []).map((entry) => ({ ...entry })),
+    compatibilityProofs: proofRegistry.proofs,
+    compatibilityProofRegistryRoot: proofRegistry.registryRoot,
+    surfaces: sourceSurfaces.map((entry) => {
+      const surfaceEntry = { ...entry };
+      delete surfaceEntry.compatibleBreakingDigests;
+      delete surfaceEntry.compatibilityProofRoots;
+      const projection = proofRegistry.projections[entry.id] || [];
+      if (projection.length > 0) {
+        surfaceEntry.compatibleBreakingDigests = projection.map((item) => item.breakingDigest);
+        surfaceEntry.compatibilityProofRoots = projection.map((item) => item.proofRoot);
+      }
+      return surfaceEntry;
+    }),
   };
   const compatibilityModel = {
     schemaVersion: world.schemaVersion,
     contract: world.contract,
     majorLine: world.majorLine,
+    compatibilityProofRegistryRoot: world.compatibilityProofRegistryRoot,
     surfaces: world.surfaces.map((entry) => ({
       id: entry.id,
       kind: entry.kind,
       breakingDigest: entry.breakingDigest,
+      compatibilityProofRoots: entry.compatibilityProofRoots || [],
     })),
   };
   const digestModel = {
@@ -831,6 +855,7 @@ export function createBuildchainContractLock({
       contract: contractWorld.contract,
       contractDigest: contractWorld.contractDigest,
       compatibilityDigest: contractWorld.compatibilityDigest,
+      compatibilityProofRegistryRoot: contractWorld.compatibilityProofRegistryRoot,
       majorLine: contractWorld.majorLine,
       compatibilityPolicy,
       acceptedAt,
@@ -838,6 +863,7 @@ export function createBuildchainContractLock({
         id: entry.id,
         kind: entry.kind,
         breakingDigest: entry.breakingDigest,
+        compatibilityProofRoots: entry.compatibilityProofRoots || [],
       })),
     },
   };
@@ -848,6 +874,7 @@ export function readBuildchainContractWorld(filePath) {
   if (!value || value.contract !== BUILDCHAIN_RUNTIME_CONTRACT_WORLD) {
     throw new Error(`Buildchain contract world is missing or invalid: ${filePath}`);
   }
+  assertBuildchainCompatibilityProjection(value);
   const computed = finalizeBuildchainContractWorld(value);
   for (const digestName of ["compatibilityDigest", "contractDigest"]) {
     const published = String(value[digestName] || "").trim();
@@ -873,165 +900,3 @@ export function readBuildchainContractLock(filePath) {
   }
   return value;
 }
-
-function surfaceMap(surfaces = []) {
-  return new Map(surfaces.map((entry) => [entry.id, entry]));
-}
-
-export function evaluateBuildchainContractLock({
-  lock,
-  current,
-  runtimeRef = "",
-  runtimeSha = "",
-  runtimeClass = "",
-  compatibilityPolicy = "",
-} = {}) {
-  if (!current || current.contract !== BUILDCHAIN_RUNTIME_CONTRACT_WORLD) {
-    throw new Error("current must be a Buildchain runtime contract world");
-  }
-  const floatingRuntime = FLOATING_CLASSES.has(runtimeClass);
-  if (!floatingRuntime) {
-    return {
-      ok: true,
-      status: "non-floating-runtime",
-      drift: false,
-      compatible: true,
-      issueRecommended: false,
-      reason: `runtime class ${runtimeClass || "unknown"} is not a stable floating ref`,
-    };
-  }
-  if (!lock) {
-    return {
-      ok: true,
-      status: "missing-lock",
-      drift: false,
-      compatible: true,
-      issueRecommended: false,
-      reason: "consumer repository has no Buildchain contract lock",
-    };
-  }
-  const accepted = lock.buildchain || {};
-  const policy = compatibilityPolicy || accepted.compatibilityPolicy || DEFAULT_POLICY;
-  const shaDrift = !!accepted.resolvedSha && !!runtimeSha && accepted.resolvedSha !== runtimeSha;
-  const contractDrift = !!accepted.contractDigest && accepted.contractDigest !== current.contractDigest;
-  if (!shaDrift && !contractDrift) {
-    return {
-      ok: true,
-      status: "unchanged",
-      drift: false,
-      compatible: true,
-      issueRecommended: false,
-      policy,
-      accepted,
-      current: contractSummary(current, runtimeRef, runtimeSha),
-    };
-  }
-  const reasons = [];
-  if (accepted.contract !== current.contract) {
-    reasons.push(`contract changed from ${accepted.contract || "(unknown)"} to ${current.contract}`);
-  }
-  if (accepted.majorLine && accepted.majorLine !== current.majorLine) {
-    reasons.push(`major line changed from ${accepted.majorLine} to ${current.majorLine}`);
-  }
-  if (policy === "exact" && accepted.contractDigest !== current.contractDigest) {
-    reasons.push("exact policy requires the contract digest to remain unchanged");
-  }
-  if (!["major-compatible", "allow-additive", "exact"].includes(policy)) {
-    reasons.push(`unsupported compatibility policy: ${policy}`);
-  }
-  const currentSurfaces = surfaceMap(current.surfaces);
-  for (const oldSurface of accepted.surfaces || []) {
-    const nextSurface = currentSurfaces.get(oldSurface.id);
-    if (!nextSurface) {
-      reasons.push(`surface removed: ${oldSurface.id}`);
-      continue;
-    }
-    const compatibleBreakingDigests = new Set(nextSurface.compatibleBreakingDigests || []);
-    if (
-      nextSurface.breakingDigest !== oldSurface.breakingDigest
-      && !compatibleBreakingDigests.has(oldSurface.breakingDigest)
-    ) {
-      reasons.push(`surface breaking digest changed: ${oldSurface.id}`);
-    }
-  }
-  const compatible = reasons.length === 0;
-  return {
-    ok: compatible,
-    status: compatible ? "compatible-drift" : "breaking-drift",
-    drift: shaDrift || contractDrift,
-    shaDrift,
-    contractDrift,
-    compatible,
-    issueRecommended: true,
-    policy,
-    reasons,
-    accepted,
-    current: contractSummary(current, runtimeRef, runtimeSha),
-  };
-}
-
-export function contractSummary(contractWorld, runtimeRef = "", runtimeSha = "") {
-  return {
-    ref: runtimeRef,
-    resolvedSha: runtimeSha,
-    contract: contractWorld.contract,
-    contractDigest: contractWorld.contractDigest,
-    compatibilityDigest: contractWorld.compatibilityDigest,
-    majorLine: contractWorld.majorLine,
-    surfaceCount: Array.isArray(contractWorld.surfaces) ? contractWorld.surfaces.length : 0,
-  };
-}
-
-export function renderBuildchainContractDriftIssueBody({
-  repository = "",
-  workflow = "",
-  runUrl = "",
-  lockPath = "",
-  evaluation,
-} = {}) {
-  const accepted = evaluation.accepted || {};
-  const current = evaluation.current || {};
-  const severity = evaluation.compatible ? "compatible" : "breaking";
-  return [
-    "# Buildchain contract drift",
-    "",
-    "## Summary",
-    "",
-    `Buildchain detected ${severity} contract drift for a floating runtime ref before expensive Buildchain work continued.`,
-    "",
-    "## Consumer",
-    "",
-    `- Repository: ${repository || "(unknown)"}`,
-    `- Workflow: ${workflow || "(unknown)"}`,
-    `- Run: ${runUrl || "(unknown)"}`,
-    `- Lock path: ${lockPath || "(unknown)"}`,
-    "",
-    "## Accepted Buildchain contract",
-    "",
-    `- Ref: ${accepted.ref || "(unknown)"}`,
-    `- SHA: ${accepted.resolvedSha || "(unknown)"}`,
-    `- Contract digest: ${accepted.contractDigest || "(unknown)"}`,
-    `- Compatibility digest: ${accepted.compatibilityDigest || "(unknown)"}`,
-    `- Policy: ${evaluation.policy || accepted.compatibilityPolicy || "(unknown)"}`,
-    "",
-    "## Current Buildchain contract",
-    "",
-    `- Ref: ${current.ref || "(unknown)"}`,
-    `- SHA: ${current.resolvedSha || "(unknown)"}`,
-    `- Contract digest: ${current.contractDigest || "(unknown)"}`,
-    `- Compatibility digest: ${current.compatibilityDigest || "(unknown)"}`,
-    `- Major line: ${current.majorLine || "(unknown)"}`,
-    "",
-    "## Compatibility",
-    "",
-    `- Status: ${evaluation.status || "(unknown)"}`,
-    `- Compatible: ${evaluation.compatible ? "yes" : "no"}`,
-    evaluation.reasons?.length ? evaluation.reasons.map((reason) => `- ${reason}`).join("\n") : "- No breaking drift detected.",
-    "",
-    "## Suggested next action",
-    "",
-    evaluation.compatible
-      ? "Review the Buildchain release notes, then update the consumer contract lock to the current SHA and contract digest."
-      : "Failing before heavy build is intentional. Review the Buildchain contract change, update the consumer workflow/configuration, or pin the previous Buildchain SHA.",
-  ].join("\n");
-}

package/packages/core/engineering-housekeeper-github-client.js

@@ -7,7 +7,8 @@ function requiredString(value, field) {
 function normalizeRepository(value) {
   const normalized = requiredString(value?.fullName || value, "repository");
   const match = normalized.match(/^([^/\s]+)\/([^/\s]+)$/);
-  if (!match) throw new Error(`repository must be owner/repo, got: ${normalized}`);
+  if (!match)
+    throw new Error(`repository must be owner/repo, got: ${normalized}`);
   return { owner: match[1], repo: match[2], fullName: normalized };
 }
 
@@ -162,6 +163,22 @@ export class GitHubHousekeeperClient {
     );
   }
 
+  async listClosedPullRequests(repository) {
+    const coordinate = normalizeRepository(repository);
+    return this.paginate(
+      `/repos/${coordinate.owner}/${coordinate.repo}/pulls?state=closed&sort=updated&direction=asc&per_page=100`,
+    );
+  }
+
+  async listPullRequestsForCommit(repository, commitOid) {
+    const coordinate = normalizeRepository(repository);
+    return this.paginate(
+      `/repos/${coordinate.owner}/${coordinate.repo}/commits/${encodeURIComponent(
+        requiredString(commitOid, "commit OID"),
+      )}/pulls?per_page=100`,
+    );
+  }
+
   async getBranch(repository, name) {
     const coordinate = normalizeRepository(repository);
     return (

package/packages/core/engineering-housekeeper-github.js

@@ -1,5 +1,6 @@
 import {
   HOUSEKEEPER_REASON_CODES,
+  classifyHousekeeperBranch,
   classifyHousekeeperReplay,
   createEngineeringHousekeeperPlan,
   createEngineeringHousekeeperReceipt,
@@ -15,6 +16,7 @@ export {
 
 const DEFAULT_STALE_DAYS = 30;
 const DEFAULT_MAX_ACTIONS = 20;
+const DEFAULT_INVENTORY_CONCURRENCY = 8;
 function requiredString(value, field) {
   const normalized = String(value || "").trim();
   if (!normalized) throw new Error(`${field} is required`);
@@ -40,6 +42,23 @@ function normalizePositiveInteger(value, fallback, field) {
   }
   return selected;
 }
+async function mapConcurrently(values, concurrency, operation) {
+  const results = new Array(values.length);
+  let nextIndex = 0;
+  async function worker() {
+    while (nextIndex < values.length) {
+      const index = nextIndex;
+      nextIndex += 1;
+      results[index] = await operation(values[index], index);
+    }
+  }
+  await Promise.all(
+    Array.from({ length: Math.min(concurrency, values.length) }, () =>
+      worker(),
+    ),
+  );
+  return results;
+}
 function providerError(error, operation) {
   if (error instanceof GitHubHousekeeperProviderError) return error;
   return new GitHubHousekeeperProviderError(
@@ -94,6 +113,123 @@ function openPullRequestNumbers(pullRequests, repository, branchName) {
     .sort((left, right) => left - right);
 }
 
+function normalizeOptionalBranchName(value) {
+  return String(value || "")
+    .trim()
+    .replace(/^refs\/heads\//, "");
+}
+
+function branchObservation({
+  branchState,
+  repository,
+  repositoryState,
+  pullRequests,
+  target,
+  ancestry,
+}) {
+  return {
+    repository,
+    sourceRepository: repository,
+    name: String(branchState.name),
+    headOid: headOid(branchState),
+    target,
+    isDefault:
+      String(repositoryState.default_branch) === String(branchState.name),
+    isProtected: branchState.protected === true,
+    ancestry,
+    openPullRequestNumbers: openPullRequestNumbers(
+      pullRequests,
+      repository,
+      String(branchState.name),
+    ),
+  };
+}
+
+function mainlineTargetNames({
+  branchStates,
+  repository,
+  repositoryState,
+  requestedTarget,
+  policy,
+}) {
+  const protectedTargets = branchStates
+    .filter((branchState) => {
+      const classification = classifyHousekeeperBranch(
+        branchObservation({
+          branchState,
+          repository,
+          repositoryState,
+          pullRequests: [],
+          target: { name: "__housekeeper_target__", headOid: "0".repeat(40) },
+          ancestry: "ancestor",
+        }),
+        policy,
+      );
+      return classification.reasonCodes.includes(
+        HOUSEKEEPER_REASON_CODES.PROTECTED_BRANCH,
+      );
+    })
+    .map((branchState) => String(branchState.name));
+  return [
+    ...new Set(
+      [
+        requestedTarget,
+        repositoryState.default_branch,
+        ...protectedTargets,
+      ].filter(Boolean),
+    ),
+  ].sort((left, right) => {
+    const priority = (name) =>
+      name === requestedTarget
+        ? 0
+        : name === repositoryState.default_branch
+          ? 1
+          : name.startsWith("dev/")
+            ? 2
+            : name.startsWith("alpha/")
+              ? 3
+              : name.startsWith("release/")
+                ? 4
+                : name.startsWith("publish-gate/")
+                  ? 5
+                  : 6;
+    return priority(left) - priority(right) || left.localeCompare(right);
+  });
+}
+
+async function branchCandidateTargets({
+  repository,
+  branchName,
+  branchOid,
+  targets,
+  associatedPullRequests,
+}) {
+  const mergedTargetNames = new Set(
+    associatedPullRequests
+      .filter(
+        (pullRequest) =>
+          Boolean(pullRequest.merged_at || pullRequest.mergedAt) &&
+          pullRequestHeadRepository(pullRequest) === repository &&
+          String(pullRequest?.head?.ref || pullRequest.headRef || "") ===
+            branchName &&
+          String(
+            pullRequest?.head?.sha || pullRequest.headOid || "",
+          ).toLowerCase() === branchOid,
+      )
+      .map((pullRequest) =>
+        String(pullRequest?.base?.ref || pullRequest.baseRef || ""),
+      )
+      .filter(Boolean),
+  );
+  return targets
+    .filter((target) => mergedTargetNames.has(target.name))
+    .sort((left, right) => {
+      const associated = (target) =>
+        mergedTargetNames.has(target.name) ? 0 : 1;
+      return associated(left) - associated(right);
+    });
+}
+
 async function branchAncestry(client, repository, branchOid, targetOid) {
   if (branchOid === targetOid) return "ancestor";
   const comparison = await client.compareCommits(
@@ -116,10 +252,7 @@ export async function collectGitHubHousekeeperInventory({
   policy = {},
 }) {
   const coordinate = normalizeRepository(repository);
-  const targetName = requiredString(targetBranch, "targetBranch").replace(
-    /^refs\/heads\//,
-    "",
-  );
+  const requestedTarget = normalizeOptionalBranchName(targetBranch);
   const observation = normalizeDate(observedAt, "observedAt");
   const staleWindow = normalizePositiveInteger(
     staleDays,
@@ -127,16 +260,42 @@ export async function collectGitHubHousekeeperInventory({
     "staleDays",
   );
   try {
-    const [repositoryState, branchStates, pullRequestStates, targetState] =
-      await Promise.all([
-        client.getRepository(coordinate.fullName),
-        client.listBranches(coordinate.fullName),
-        client.listOpenPullRequests(coordinate.fullName),
-        client.getBranch(coordinate.fullName, targetName),
-      ]);
-    const target = { name: targetName, headOid: headOid(targetState) };
-    if (!target.headOid)
-      throw new Error(`target branch ${targetName} has no head OID`);
+    const [
+      repositoryState,
+      branchStates,
+      pullRequestStates,
+      closedPullRequestStates,
+    ] = await Promise.all([
+      client.getRepository(coordinate.fullName),
+      client.listBranches(coordinate.fullName),
+      client.listOpenPullRequests(coordinate.fullName),
+      client.listClosedPullRequests(coordinate.fullName),
+    ]);
+    const branchStatesByName = new Map(
+      branchStates.map((branchState) => [
+        String(branchState.name),
+        branchState,
+      ]),
+    );
+    const targetNames = mainlineTargetNames({
+      branchStates,
+      repository: coordinate.fullName,
+      repositoryState,
+      requestedTarget,
+      policy,
+    });
+    const targets = targetNames.map((name) => {
+      const state = branchStatesByName.get(name);
+      if (!state)
+        throw new Error(`mainline target branch ${name} was not found`);
+      const target = { name, headOid: headOid(state) };
+      if (!target.headOid)
+        throw new Error(`mainline target branch ${name} has no head OID`);
+      return target;
+    });
+    const target = targets[0];
+    if (!target)
+      throw new Error("repository has no discoverable mainline target");
     const pullRequests = pullRequestStates
       .map((entry) =>
         normalizePullRequest(
@@ -147,35 +306,82 @@ export async function collectGitHubHousekeeperInventory({
         ),
       )
       .sort((left, right) => left.number - right.number);
-    const branches = [];
-    for (const branchState of [...branchStates].sort((left, right) =>
+    const mergedPullRequestsByExactHead = new Map();
+    for (const pullRequest of closedPullRequestStates) {
+      if (
+        !Boolean(pullRequest.merged_at || pullRequest.mergedAt) ||
+        pullRequestHeadRepository(pullRequest) !== coordinate.fullName
+      )
+        continue;
+      const key = `${String(
+        pullRequest?.head?.ref || pullRequest.headRef || "",
+      )}\0${String(
+        pullRequest?.head?.sha || pullRequest.headOid || "",
+      ).toLowerCase()}`;
+      const existing = mergedPullRequestsByExactHead.get(key) || [];
+      existing.push(pullRequest);
+      mergedPullRequestsByExactHead.set(key, existing);
+    }
+    const sortedBranchStates = [...branchStates].sort((left, right) =>
       String(left.name).localeCompare(String(right.name)),
-    )) {
-      const branchOid = headOid(branchState);
-      if (!branchOid)
-        throw new Error(`branch ${branchState.name} has no head OID`);
-      branches.push({
-        repository: coordinate.fullName,
-        sourceRepository: coordinate.fullName,
-        name: String(branchState.name),
-        headOid: branchOid,
-        target,
-        isDefault:
-          String(repositoryState.default_branch) === String(branchState.name),
-        isProtected: branchState.protected === true,
-        ancestry: await branchAncestry(
-          client,
-          coordinate.fullName,
-          branchOid,
-          target.headOid,
-        ),
-        openPullRequestNumbers: openPullRequestNumbers(
+    );
+    const branches = await mapConcurrently(
+      sortedBranchStates,
+      DEFAULT_INVENTORY_CONCURRENCY,
+      async (branchState) => {
+        const branchOid = headOid(branchState);
+        if (!branchOid)
+          throw new Error(`branch ${branchState.name} has no head OID`);
+        const staticObservation = branchObservation({
+          branchState,
+          repository: coordinate.fullName,
+          repositoryState,
           pullRequests,
-          coordinate.fullName,
-          String(branchState.name),
-        ),
-      });
-    }
+          target,
+          ancestry: "ancestor",
+        });
+        const staticallyEligible = classifyHousekeeperBranch(
+          staticObservation,
+          policy,
+        ).eligible;
+        let selectedTarget = target;
+        let ancestry = "ambiguous";
+        if (staticallyEligible) {
+          const candidateTargets = await branchCandidateTargets({
+            repository: coordinate.fullName,
+            branchName: String(branchState.name),
+            branchOid,
+            targets,
+            associatedPullRequests:
+              mergedPullRequestsByExactHead.get(
+                `${String(branchState.name)}\0${branchOid}`,
+              ) || [],
+          });
+          for (const candidateTarget of candidateTargets) {
+            if (String(branchState.name) === candidateTarget.name) continue;
+            const candidateAncestry = await branchAncestry(
+              client,
+              coordinate.fullName,
+              branchOid,
+              candidateTarget.headOid,
+            );
+            if (candidateAncestry === "ancestor") {
+              selectedTarget = candidateTarget;
+              ancestry = candidateAncestry;
+              break;
+            }
+          }
+        }
+        return branchObservation({
+          branchState,
+          repository: coordinate.fullName,
+          repositoryState,
+          pullRequests,
+          target: selectedTarget,
+          ancestry,
+        });
+      },
+    );
     return createEngineeringHousekeeperPlan({
       repository: coordinate.fullName,
       target,