@kungfu-tech/buildchain 4.0.2-alpha.0 → 4.0.2-alpha.4

package/packages/core/v4-release-invocation.js

@@ -0,0 +1,425 @@
+import {
+  V4ContractFault,
+  v4CanonicalBytes,
+  v4ContentRoot,
+  validateV4Root,
+} from "./v4-canonical-contracts.js";
+
+export const V4_RELEASE_INVOCATION_CONTRACT =
+  "kungfu-buildchain-v4-release-invocation/v1";
+export const V4_RELEASE_INVOCATION_ADAPTER_CONTRACT =
+  "kungfu-buildchain-v4-release-invocation-adapter/v1";
+export const V4_RELEASE_TRANSACTION_CONTRACT =
+  "kungfu-buildchain-v4-release-transaction/v1";
+export const V4_RELEASE_RECEIPT_CONTRACT =
+  "kungfu-buildchain-v4-release-receipt/v1";
+export const V4_RELEASE_PROVIDER_CONTRACT =
+  "kungfu-buildchain-release-tail-provider/v1";
+
+const SHA_PATTERN = /^[0-9a-f]{40}$/u;
+const TAG_PATTERN = /^v[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)?$/u;
+const ROUTE_SURFACES = new Set([
+  "alpha",
+  "stable",
+  "public",
+  "private",
+  "declarative",
+  "legacy-compatible",
+]);
+const EXECUTION_MODES = new Set(["fresh", "resume"]);
+const COMPARISON_STATES = new Set(["identical", "ahead", "behind", "diverged"]);
+
+function fault(code, path, message) {
+  throw new V4ContractFault(code, path, message);
+}
+
+function exactKeys(value, keys, path) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    fault("invalid-release-invocation", path, `${path} must be an object`);
+  const actual = Object.keys(value).sort();
+  const expected = [...keys].sort();
+  if (
+    actual.length !== expected.length ||
+    actual.some((key, index) => key !== expected[index])
+  )
+    fault(
+      "invalid-release-invocation-shape",
+      path,
+      `${path} keys are not canonical`,
+    );
+}
+
+function sha(value, path, nullable = false) {
+  if (nullable && value === null) return value;
+  if (typeof value !== "string" || !SHA_PATTERN.test(value))
+    fault("invalid-release-sha", path, `${path} must be an exact Git SHA`);
+  return value;
+}
+
+function text(value, path) {
+  if (
+    typeof value !== "string" ||
+    value.length === 0 ||
+    /[^\x20-\x7e]/u.test(value)
+  )
+    fault("invalid-release-text", path, `${path} must be printable ASCII`);
+  return value;
+}
+
+function validatePublisher(value) {
+  exactKeys(
+    value,
+    ["repository", "workflow", "workflowSha", "job"],
+    "$/publisher",
+  );
+  if (
+    value.repository !== "kungfu-systems/buildchain" ||
+    value.workflow !== ".github/workflows/.release-candidate-promote.yml" ||
+    value.job !== "apply"
+  )
+    fault(
+      "invalid-publisher-identity",
+      "$/publisher",
+      "publisher identity is not the canonical v4 APPLY job",
+    );
+  sha(value.workflowSha, "$/publisher/workflowSha");
+}
+
+function validateRuntime(value) {
+  exactKeys(value, ["repository", "commit", "tree"], "$/runtime");
+  if (value.repository !== "kungfu-systems/buildchain")
+    fault(
+      "invalid-runtime-identity",
+      "$/runtime/repository",
+      "runtime repository is not canonical",
+    );
+  sha(value.commit, "$/runtime/commit");
+  sha(value.tree, "$/runtime/tree");
+}
+
+function validateCandidate(value) {
+  exactKeys(value, ["repository", "commit", "tree", "version"], "$/candidate");
+  text(value.repository, "$/candidate/repository");
+  sha(value.commit, "$/candidate/commit");
+  sha(value.tree, "$/candidate/tree");
+  text(value.version, "$/candidate/version");
+}
+
+function validateTarget(value) {
+  exactKeys(value, ["channel", "tag", "expectedOldSha"], "$/target");
+  if (
+    !["alpha", "stable"].includes(value.channel) ||
+    !TAG_PATTERN.test(value.tag)
+  )
+    fault(
+      "invalid-release-target",
+      "$/target",
+      "release channel and exact tag are not canonical",
+    );
+  sha(value.expectedOldSha, "$/target/expectedOldSha", true);
+}
+
+function validateAuthority(value) {
+  exactKeys(
+    value,
+    ["policyRoot", "qualificationRoot", "warrantRoot"],
+    "$/authority",
+  );
+  for (const name of ["policyRoot", "qualificationRoot", "warrantRoot"])
+    validateV4Root(value[name], `$/authority/${name}`);
+}
+
+function validateProvider(value, candidate) {
+  exactKeys(value, ["adapter", "contract", "repository"], "$/provider");
+  if (
+    value.adapter !== "built-in-provider-plane" ||
+    value.contract !== V4_RELEASE_PROVIDER_CONTRACT ||
+    value.repository !== candidate.repository
+  )
+    fault(
+      "invalid-release-provider",
+      "$/provider",
+      "provider identity must bind the built-in Provider Plane and candidate repository",
+    );
+}
+
+function validateParent(value) {
+  exactKeys(
+    value,
+    ["invocationRoot", "transactionRoot", "receiptRoot"],
+    "$/parent",
+  );
+  const roots = [
+    value.invocationRoot,
+    value.transactionRoot,
+    value.receiptRoot,
+  ];
+  if (roots.every((root) => root === null)) return;
+  if (roots.some((root) => root === null))
+    fault(
+      "invalid-release-parent-lineage",
+      "$/parent",
+      "parent lineage roots must be either all null or all present",
+    );
+  roots.forEach((root, index) =>
+    validateV4Root(
+      root,
+      `$/parent/${["invocationRoot", "transactionRoot", "receiptRoot"][index]}`,
+    ),
+  );
+}
+
+export function createV4ReleaseInvocation(value) {
+  exactKeys(
+    value,
+    [
+      "schema",
+      "publisher",
+      "runtime",
+      "candidate",
+      "target",
+      "authority",
+      "provider",
+      "parent",
+    ],
+    "$",
+  );
+  if (value.schema !== V4_RELEASE_INVOCATION_CONTRACT)
+    fault(
+      "invalid-release-invocation",
+      "$/schema",
+      "unsupported invocation schema",
+    );
+  validatePublisher(value.publisher);
+  validateRuntime(value.runtime);
+  validateCandidate(value.candidate);
+  validateTarget(value.target);
+  validateAuthority(value.authority);
+  validateProvider(value.provider, value.candidate);
+  validateParent(value.parent);
+  v4CanonicalBytes(value);
+  const roots = {
+    publisherRoot: v4ContentRoot(
+      "release-invocation-publisher",
+      value.publisher,
+    ),
+    runtimeRoot: v4ContentRoot("release-invocation-runtime", value.runtime),
+    candidateRoot: v4ContentRoot(
+      "release-invocation-candidate",
+      value.candidate,
+    ),
+    targetRoot: v4ContentRoot("release-invocation-target", value.target),
+    authorityRoot: v4ContentRoot(
+      "release-invocation-authority",
+      value.authority,
+    ),
+    providerRoot: v4ContentRoot("release-invocation-provider", value.provider),
+    parentRoot: v4ContentRoot("release-invocation-parent", value.parent),
+  };
+  const invocationRoot = v4ContentRoot("release-invocation", {
+    schema: V4_RELEASE_INVOCATION_CONTRACT,
+    ...roots,
+  });
+  return { invocation: value, roots: { ...roots, invocationRoot } };
+}
+
+export function adaptV4ReleaseInvocation(value) {
+  exactKeys(value, ["schema", "route", "invocation"], "$adapter");
+  if (value.schema !== V4_RELEASE_INVOCATION_ADAPTER_CONTRACT)
+    fault(
+      "invalid-release-adapter",
+      "$adapter/schema",
+      "unsupported adapter schema",
+    );
+  exactKeys(value.route, ["surface", "execution"], "$adapter/route");
+  if (!ROUTE_SURFACES.has(value.route.surface))
+    fault(
+      "invalid-release-adapter",
+      "$adapter/route/surface",
+      "unsupported route surface",
+    );
+  if (!EXECUTION_MODES.has(value.route.execution))
+    fault(
+      "invalid-release-adapter",
+      "$adapter/route/execution",
+      "unsupported execution mode",
+    );
+  return createV4ReleaseInvocation(value.invocation);
+}
+
+export function planV4ReleaseRoute({
+  requestedSha,
+  observedSha,
+  comparisonStatus,
+  requestedChannel = "",
+  targetRef,
+  dryRun = false,
+  resume = false,
+}) {
+  sha(requestedSha, "$route/requestedSha");
+  sha(observedSha, "$route/observedSha");
+  if (!COMPARISON_STATES.has(comparisonStatus))
+    fault(
+      "invalid-release-route",
+      "$route/comparisonStatus",
+      "unsupported source comparison state",
+    );
+  text(targetRef, "$route/targetRef");
+  const alphaLane = /^alpha\/v[0-9]+\/v[0-9]+\.[0-9]+$/u.test(targetRef);
+  const stableLane =
+    /^release\/v[0-9]+\/v[0-9]+\.[0-9]+$/u.test(targetRef) ||
+    ["publish-gate/major", "major-gate"].includes(targetRef);
+  if (!alphaLane && !stableLane)
+    fault(
+      "invalid-release-route",
+      "$route/targetRef",
+      "source lane is not a supported v4 release lane",
+    );
+  const derivedChannel = alphaLane ? "alpha" : "stable";
+  const normalizedRequested =
+    requestedChannel === "alpha"
+      ? "alpha"
+      : ["release", "stable", "major"].includes(requestedChannel)
+        ? "stable"
+        : requestedChannel === ""
+          ? derivedChannel
+          : "";
+  if (!normalizedRequested || normalizedRequested !== derivedChannel)
+    fault(
+      "invalid-release-route",
+      "$route/channel",
+      "requested channel does not match the source lane",
+    );
+  let decision = resume ? "Resume" : "Fresh";
+  let reason = resume ? "resume" : "fresh";
+  if (comparisonStatus === "ahead" && !resume && !dryRun) {
+    decision = "NoOp";
+    reason = "source-advanced";
+  } else if (
+    requestedSha !== observedSha &&
+    !(resume && comparisonStatus === "ahead") &&
+    !(dryRun && comparisonStatus === "ahead")
+  ) {
+    decision = "Blocked";
+    reason = `source-${comparisonStatus}`;
+  }
+  return Object.freeze({
+    decision,
+    reason,
+    channel: normalizedRequested,
+    targetRef,
+    requestedSha,
+    observedSha,
+  });
+}
+
+export function createV4ReleaseTransaction(value) {
+  exactKeys(
+    value,
+    [
+      "invocationRoot",
+      "publisherRoot",
+      "runtimeRoot",
+      "providerRoot",
+      "parentRoot",
+    ],
+    "$transaction",
+  );
+  for (const name of [
+    "invocationRoot",
+    "publisherRoot",
+    "runtimeRoot",
+    "providerRoot",
+    "parentRoot",
+  ])
+    validateV4Root(value[name], `$transaction/${name}`);
+  const transaction = {
+    schema: V4_RELEASE_TRANSACTION_CONTRACT,
+    invocationRoot: value.invocationRoot,
+    publisherRoot: value.publisherRoot,
+    runtimeRoot: value.runtimeRoot,
+    providerRoot: value.providerRoot,
+    parentRoot: value.parentRoot,
+    phases: ["QUALIFY", "APPLY", "SETTLE"],
+    writer: "canonical-v4-apply",
+  };
+  return {
+    transaction,
+    transactionRoot: v4ContentRoot("release-transaction", transaction),
+  };
+}
+
+export function createV4ReleaseReceipt(value) {
+  exactKeys(
+    value,
+    [
+      "schema",
+      "transactionRoot",
+      "outcome",
+      "releasePassportRoot",
+      "providerTransactionRoot",
+      "providerStateRoot",
+      "providerReceiptRoots",
+    ],
+    "$receipt",
+  );
+  if (value.schema !== V4_RELEASE_RECEIPT_CONTRACT)
+    fault(
+      "invalid-release-receipt",
+      "$receipt/schema",
+      "unsupported receipt schema",
+    );
+  validateV4Root(value.transactionRoot, "$receipt/transactionRoot");
+  if (!["complete", "blocked"].includes(value.outcome))
+    fault(
+      "invalid-release-receipt",
+      "$receipt/outcome",
+      "unsupported receipt outcome",
+    );
+  for (const name of [
+    "releasePassportRoot",
+    "providerTransactionRoot",
+    "providerStateRoot",
+  ]) {
+    if (value[name] !== null) validateV4Root(value[name], `$receipt/${name}`);
+  }
+  if (!Array.isArray(value.providerReceiptRoots))
+    fault(
+      "invalid-release-receipt",
+      "$receipt/providerReceiptRoots",
+      "receipt roots must be an array",
+    );
+  value.providerReceiptRoots.forEach((root, index) =>
+    validateV4Root(root, `$receipt/providerReceiptRoots/${index}`),
+  );
+  const canonicalRoots = [...new Set(value.providerReceiptRoots)].sort();
+  if (
+    canonicalRoots.length !== value.providerReceiptRoots.length ||
+    canonicalRoots.some(
+      (root, index) => root !== value.providerReceiptRoots[index],
+    )
+  )
+    fault(
+      "invalid-release-receipt",
+      "$receipt/providerReceiptRoots",
+      "provider receipt roots must be sorted and unique",
+    );
+  if (
+    value.outcome === "complete" &&
+    [
+      value.releasePassportRoot,
+      value.providerTransactionRoot,
+      value.providerStateRoot,
+    ].some((root) => root === null)
+  )
+    fault(
+      "invalid-release-receipt",
+      "$receipt/outcome",
+      "complete receipt requires every terminal root",
+    );
+  v4CanonicalBytes(value);
+  return {
+    receipt: value,
+    receiptRoot: v4ContentRoot("release-receipt", value),
+  };
+}

package/scripts/audit-publication-control-plane.mjs

@@ -196,7 +196,6 @@ function normalizeNpmPublisher(value, { packageName, repository, workflowFilenam
     configurationRead: true,
   };
 }
-
 function main() {
   const repository = flag("repository");
   const workflowRepository = flag("workflow-repository", repository);

package/scripts/check-inventory.mjs

@@ -127,7 +127,6 @@ const requiredPaths = [
   "scripts/npm-publish-transaction.mjs",
   "scripts/paper.mjs",
   "scripts/publication-package.mjs",
-  "scripts/publication-commit-evidence.mjs",
   "scripts/publication-reproducibility.mjs",
   "scripts/release-candidate-resolver.mjs",
   "scripts/resume-from-candidate-run.mjs",
@@ -300,8 +299,8 @@ if (channelPromotionWorkflow !== generateChannelPromotionWorkflow(advancedPromot
   throw new Error("generated channel promotion workflow is stale");
 }
 for (const requiredSnippet of [
-  "uses: kungfu-systems/buildchain/.github/workflows/.release-candidate-promote.yml@alpha/v4/v4.0",
-  "promotion-shell-ref: ${{ needs.consumer-admission.outputs.shell-call-ref }}",
+  "name: Adapt recovery inputs into the canonical v4 publisher",
+  "uses: kungfu-systems/buildchain/.github/workflows/release-candidate-promote.yml@v4-alpha",
   "declarative-release-tail: true",
 ]) {
   if (!boundedAlphaRecoveryWorkflow.includes(requiredSnippet)) {
@@ -316,8 +315,8 @@ for (const workflowSource of [boundedAlphaRecoveryWorkflow, channelPromotionWork
 for (const requiredSnippet of [
   "buildchain-channel:",
   `/${promotionShellRouting.alpha.workflowPath}@${promotionShellRouting.alpha.callRef}`,
-  `/${promotionShellRouting.stable.workflowPath}@${promotionShellRouting.stable.callRef}`,
-  `STABLE_SHELL_REF: v${selfDogfoodMajor}`,
+  `SELECTED_SHELL_REF: v${selfDogfoodMajor}-alpha`,
+  "name: Invoke the single v4 publisher adapter",
   "promotion-contract-lock-digest:",
   "authorize-promotion-runtime-override.cjs",
   "BUILDCHAIN_ROUTER_REPOSITORY: ${{ inputs.buildchain-repository }}",
@@ -329,6 +328,9 @@ for (const requiredSnippet of [
     throw new Error(`channel promotion workflow missing routing contract: ${requiredSnippet}`);
   }
 }
+if (channelPromotionWorkflow.includes("Promote with stable workflow shell")) {
+  throw new Error("channel promotion workflow retains a parallel stable publisher");
+}
 for (const forbiddenSnippet of ["job.workflow_repository", "job.workflow_sha"]) {
   if (channelPromotionWorkflow.includes(forbiddenSnippet)) {
     throw new Error(`channel promotion workflow uses unsupported GitHub context: ${forbiddenSnippet}`);
@@ -1046,7 +1048,6 @@ for (const requiredSnippet of [
   "resume-candidate-run-id:",
   "resume-expected-source-tree:",
   "resume-buildchain-runtime-ref:",
-  "uses: kungfu-systems/buildchain/.github/workflows/release-candidate-promote.yml@v4",
   "release-passport-buildchain-self-kfd: true",
   "declarative-release-tail: true",
   "release-passport-impact-json: .buildchain/release-impact.json",
@@ -1057,61 +1058,28 @@ for (const requiredSnippet of [
 }
 const releaseCandidatePromoteWorkflow = fs.readFileSync(path.join(root, ".github/workflows/.release-candidate-promote.yml"), "utf8");
 for (const requiredSnippet of [
-  "release-passport-kfd-1-witness-jsons:",
-  "release-passport-kfd-1-witness-jsons: ${{ inputs.release-passport-kfd-1-witness-jsons }}",
-  "release-passport-kfd-2-claim-jsons:",
-  "release-passport-kfd-2-claim-jsons: ${{ inputs.release-passport-kfd-2-claim-jsons }}",
-  "release-passport-kfd-3-prebuild-witness-jsons:",
-  "release-passport-kfd-3-prebuild-witness-jsons: ${{ inputs.release-passport-kfd-3-prebuild-witness-jsons }}",
-  "release-passport-kfd-3-artifact-witness-jsons:",
-  "release-passport-kfd-3-artifact-witness-jsons: ${{ inputs.release-passport-kfd-3-artifact-witness-jsons }}",
-  "release-passport-kfd-3-artifact-verify-command:",
-  "release-passport-kfd-adopter-manifest-json:", "release-passport-kfd-adopter-manifest-json: ${{ inputs.release-passport-kfd-adopter-manifest-json }}",
-  "release-passport-kfd-support-matrix-json:", "release-passport-kfd-support-matrix-json: ${{ inputs.release-passport-kfd-support-matrix-json }}",
-  "release-passport-kfd-product-gate-jsons:",
-  "release-passport-kfd-product-gate-jsons: ${{ inputs.release-passport-kfd-product-gate-jsons }}",
-  "release-passport-invariant-passport-jsons:",
-  "release-passport-invariant-passport-jsons: ${{ inputs.release-passport-invariant-passport-jsons }}",
-  "release-passport-invariant-passport-command:",
-  "release-passport-invariant-passport-command: ${{ inputs.release-passport-invariant-passport-command }}",
-  "release-passport-buildchain-self-kfd:",
-  "release-passport-buildchain-self-kfd: ${{ inputs.release-passport-buildchain-self-kfd }}",
-  "github-release:",
-  "default: true",
-  "github-release: ${{ inputs.github-release }}",
-  "github-release-payload-patterns:",
-  "github-release-artifact-paths: ${{ steps.rc.outputs.release-candidate-github-release-artifact-paths }}",
-  "github-release-title: ${{ inputs.github-release-title }}",
-  "github-release-notes: ${{ inputs.github-release-notes }}",
-  "publication-commit-command:",
-  "BUILDCHAIN_PUBLICATION_COMMIT_SIGNING_KEY:",
-  "KUNGFU_GOVERNANCE_AUDITOR_APP_PRIVATE_KEY:",
-  "Commit consumer publication authority last",
-  "node .buildchain/runtime/scripts/publication-commit-evidence.mjs",
-  "require-publish-source-lock: \"true\"",
-  "publish-source-ref: ${{ steps.publish-gate.outputs.ref }}",
-  "publish-source-sha: ${{ steps.publish-gate.outputs.sha }}",
-  "publish-source-locked: ${{ steps.publish-gate.outputs.locked }}",
-  "expected-publication-version: ${{ needs.publication-plan.outputs.version }}",
-  "publication-version: ${{ needs.publication-plan.outputs.version }}",
-  "name: Plan exact publication version",
-  "name: Install exact publication planning dependencies",
-  "DRY_RUN: ${{ inputs.dry-run }}",
-  "if (dryRun) {",
-  "Enforce Buildchain stable release canary gate",
-  "BUILDCHAIN_STABLE_RELEASE_POLICY: .buildchain/stable-release-policy.json",
-  "Consumer has no binary-distribution.yml; standalone binary dispatch is not applicable.",
-  "gh workflow view binary-distribution.yml",
-  "resume-candidate-run-id:",
-  "node .buildchain/runtime/scripts/resume-from-candidate-run.mjs",
-  "publish-sealed-bundle-root: ${{ steps.rc.outputs.publish-sealed-bundle-root }}",
-  "BUILDCHAIN_EXPECTED_TRANSACTION_ID: ${{ inputs.resume-transaction-id }}",
-  "if: ${{ inputs.resume-candidate-run-id == '' }}",
-  "Bridge Buildchain self-runtime dependencies",
-  "ln -s .buildchain/runtime/node_modules node_modules",
+  "name: QUALIFY canonical v4 release invocation inputs",
+  "name: APPLY one rooted provider transaction",
+  "name: SETTLE terminal ReleaseReceipt projection",
+  "uses: ./.buildchain/runtime/actions/v4-release-candidate-promote",
+  "publisher-workflow-sha:",
+  "runtime-commit:",
+  "runtime-tree:",
+  "release-invocation-root:",
+  "release-transaction-root:",
+  "release-receipt-root:",
 ]) {
   if (!releaseCandidatePromoteWorkflow.includes(requiredSnippet)) {
-    throw new Error(`release candidate promote workflow missing KFD gate pass-through: ${requiredSnippet}`);
+    throw new Error(`release candidate promote workflow missing canonical v4 boundary: ${requiredSnippet}`);
+  }
+}
+for (const retiredSnippet of [
+  "Commit consumer publication authority last",
+  "publish-github-artifact-attestation-evidence.mjs",
+  "capture-package-release-propagation.mjs",
+]) {
+  if (releaseCandidatePromoteWorkflow.includes(retiredSnippet)) {
+    throw new Error(`release candidate promote workflow retains parallel publication authority: ${retiredSnippet}`);
   }
 }
 const workflowDir = path.join(root, ".github/workflows");

package/scripts/check-maintainability.mjs

@@ -20,17 +20,25 @@ import {
   evaluateWorkflowBudgets,
 } from "./maintainability-governance.mjs";
 
-function collectHotspots(root, current, limit = 20, shallowFallback = []) {
+function collectHotspots(
+  root,
+  current,
+  limit = 20,
+  shallowFallback = [],
+  {
+    baseRef = process.env.GITHUB_BASE_REF || process.env.GITHUB_REF_NAME || "",
+  } = {},
+) {
   const maintained = new Set([
     ...Object.keys(current.files || {}),
     ...Object.keys(current.tests || {}),
     ...Object.keys(current.workflows || {}),
   ]);
-  // Shallow consumers cannot reproduce repository-wide churn ranking.
-  // Reuse the audited routes; full clones still re-rank them below.
-  // This keeps consumer verification deterministic without inventing history.
+  // Release-line reconciliation reuses audited routes across equivalent-tree DAG shapes.
   if (
-    gitOutput(root, ["rev-parse", "--is-shallow-repository"]).trim() === "true"
+    gitOutput(root, ["rev-parse", "--is-shallow-repository"]).trim() ===
+      "true" ||
+    /^(?:alpha|release|publish-gate)\//u.test(baseRef)
   ) {
     return shallowFallback.slice(0, limit);
   }

package/scripts/check-v3-v4-capability-inventory.mjs

@@ -8,6 +8,7 @@ import {
   collectHistoryRows,
   collectRevisionCatalog,
   countsBy,
+  ensureCapabilityCutLineage,
   git,
   sha256,
 } from "./v3-v4-capability-catalog.mjs";
@@ -17,9 +18,8 @@ export const V3_V4_CAPABILITY_INVENTORY_CONTRACT =
 export const V3_V4_CAPABILITY_CUTS = Object.freeze({
   priorFamilyV3: "6b96bdad8d9f8ccf9275f27d9370a226a9c78465",
   liveV3: "8493bf140a7f567e76aff3119f3d39ff026afc84",
-  liveV4: "11b4ab21405cdffcc9d6dc10cd947618d9d1bf9c",
+  liveV4: "97edd5b93eb67e5bf36ad55726e08231b47b70c0",
 });
-
 const INVENTORY_PATH = "architecture/v3-v4-live-capability-inventory.json";
 const ALLOWED_DISPOSITIONS = new Set([
   "v4-native",
@@ -92,64 +92,6 @@ function capabilityCutAvailable(root, revision) {
   }
 }
 
-export function assertCapabilityCutAncestor({
-  root = process.cwd(),
-  revision,
-  descendant = "HEAD",
-  label = "capability cut",
-} = {}) {
-  try {
-    execFileSync("git", ["merge-base", "--is-ancestor", revision, descendant], {
-      cwd: root,
-      stdio: "ignore",
-    });
-  } catch {
-    throw new Error(
-      `${label} ${revision} must be an ancestor of ${descendant}; regenerate the cut after rebasing instead of relying on a retained local object`,
-    );
-  }
-}
-
-function repositoryIsShallow(root) {
-  return (
-    execFileSync("git", ["rev-parse", "--is-shallow-repository"], {
-      cwd: root,
-      encoding: "utf8",
-    }).trim() === "true"
-  );
-}
-
-export function ensureCapabilityCutAncestor({
-  root = process.cwd(),
-  revision,
-  descendant = "HEAD",
-  label = "capability cut",
-} = {}) {
-  try {
-    assertCapabilityCutAncestor({ root, revision, descendant, label });
-    return;
-  } catch (error) {
-    if (!repositoryIsShallow(root)) throw error;
-  }
-  const descendantCommit = execFileSync(
-    "git",
-    ["rev-parse", `${descendant}^{commit}`],
-    { cwd: root, encoding: "utf8" },
-  ).trim();
-  try {
-    execFileSync(
-      "git",
-      ["fetch", "--no-tags", "--depth=128", "origin", descendantCommit],
-      { cwd: root, stdio: "ignore" },
-    );
-  } catch {
-    throw new Error(
-      `${label} ${revision} ancestry could not be hydrated from ${descendantCommit} through a bounded origin fetch`,
-    );
-  }
-  assertCapabilityCutAncestor({ root, revision, descendant, label });
-}
-
 function ensureCapabilityCutsAvailable(root) {
   const revisions = Object.values(V3_V4_CAPABILITY_CUTS);
   const missing = revisions.filter(
@@ -170,7 +112,7 @@ function ensureCapabilityCutsAvailable(root) {
       `v3/v4 capability cuts are unavailable after a bounded origin fetch: ${unavailable.join(", ")}`,
     );
   }
-  ensureCapabilityCutAncestor({
+  ensureCapabilityCutLineage({
     root,
     revision: V3_V4_CAPABILITY_CUTS.liveV4,
     label: "live v4 capability cut",