@kungfu-tech/buildchain 2.14.13 → 2.14.14-alpha.1

package/dist/site/public-surface-audit.json

@@ -3690,7 +3690,7 @@
     "pageRegistryPath": "dist/site/page-registry.json",
     "cliRegistryDigest": "90c8650f870c350ca187c612c37f2459dcbfe265aa9b1d5b375ee5c4fb31fab6",
     "workflowRegistryDigest": "02950eef2769b1bd2d899099ef23c7b9ae716b18d602e25aef169d788bc6ece0",
-    "pageRegistryDigest": "01c3418ba850dcf1bc678be943f60082c609c0984c5101cc2181bb9803cd6aa4"
+    "pageRegistryDigest": "2121b86c6c11ad27c69b5b00bda989c1203ddb3f7cb4a864df375a62e13fced6"
   },
   "comparison": {
     "missingCliRegistry": [],

package/dist/site/publication-registry.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-publication-release-registry",
-  "generatedAt": "2026-07-21T20:06:36.670Z",
-  "publishedAt": "2026-07-21T20:06:36.670Z",
+  "generatedAt": "2026-07-21T22:45:53.347Z",
+  "publishedAt": "2026-07-21T22:45:53.347Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "d82f8d214b48af62d41cb47d8c3b25838e16d6f1",
+  "sourceRevision": "b72c725311d1e37adc98b25a4555bb61ca8023ca",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -32,7 +32,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "2.14.13",
+    "version": "2.14.14-alpha.1",
     "versionSource": "package.json#version"
   },
   "sourceKind": "package-site-bundle",

package/dist/site/site-manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-site-manifest",
-  "generatedAt": "2026-07-21T20:06:36.670Z",
-  "publishedAt": "2026-07-21T20:06:36.670Z",
+  "generatedAt": "2026-07-21T22:45:53.347Z",
+  "publishedAt": "2026-07-21T22:45:53.347Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "d82f8d214b48af62d41cb47d8c3b25838e16d6f1",
+  "sourceRevision": "b72c725311d1e37adc98b25a4555bb61ca8023ca",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -37,7 +37,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "2.14.13",
+    "version": "2.14.14-alpha.1",
     "versionSource": "package.json#version"
   },
   "entrypoint": "buildchain-site.json",
@@ -165,7 +165,7 @@
       "path": "docs/migration-inventory.md",
       "plane": "verify",
       "exists": true,
-      "digest": "sha256:a5f7271a065544f7ac525dbddfe3d4b9f621b5284c730089f086dd9f961e883c"
+      "digest": "sha256:18f98635bb16a4e43cac2d46443b3e812c305f708f071929dc6a46a8cd5dccd5"
     },
     {
       "id": "ownership",
@@ -221,7 +221,7 @@
       "path": "docs/reusable-build-surface.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:dea8ec2f1f2ea75e569a989988e9d6f76067e1d0ae496dadc34ef1dcfbfa35dd"
+      "digest": "sha256:9c125f6d2b519c96718f45da62ac1a891ab618bcb331d3b14c4b88b5158fc4a9"
     },
     {
       "id": "publish-transaction",
@@ -269,7 +269,7 @@
       "path": "docs/web-surface-deployments.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:856a7602cf1c2d3a0a540cdf0d64566914f79dde24417c92089f0466bee25df1"
+      "digest": "sha256:efbfc97a947978e61c79dac9d67f87050b1bef2297617303340af8aa499703c9"
     }
   ],
   "facts": [

package/docs/migration-inventory.md

@@ -46,7 +46,7 @@ do not duplicate alpha and stable jobs or call
 `.release-candidate-promote.yml` directly.
 
 Buildchain also keeps the workflow-file layout transition declarative in
-`.buildchain/promotion-shell-routing.json`. Stable `v2.14.12` contains the hidden
+`.buildchain/promotion-shell-routing.json`. Stable `v2.14.13` contains the hidden
 advanced workflow, so the stable lane is pinned to that implementation's
 immutable release SHA and forwards the full internal identity surface. This is
 provider-owned compatibility state; consumers still keep the same single public

package/docs/reusable-build-surface.md

@@ -754,7 +754,7 @@ promotion starts:
   `vN`, and `buildchain-stable-contract-lock-path`.
 
 The generated router also owns the stable-shell layout transition through
-`.buildchain/promotion-shell-routing.json`. Stable `v2.14.12` contains the hidden
+`.buildchain/promotion-shell-routing.json`. Stable `v2.14.13` contains the hidden
 advanced workflow, so the stable lane calls that workflow at the exact immutable
 SHA behind the released `v2` state and forwards the complete internal promotion
 identity surface. The logical shell identity remains `vN`, and the router

package/docs/web-surface-deployments.md

@@ -456,7 +456,12 @@ compatibility evidence, but root correctness comes from the viewer-request
 rewrite contract, not from extensionless S3 keys. If Buildchain-managed mode
 finds a distribution with a different viewer-request function, apply fails
 closed and records that conflict in the apply result instead of silently serving
-403s. The reusable workflow uploads `buildchain-web-surface-*-diagnostics`
+403s. If CloudFront rejects `UpdateDistribution` because its optimistic-lock
+ETag became stale, Buildchain re-reads the distribution and retries with the
+new ETag at most twice. A concurrent update that already attached the intended
+function is accepted as converged; a different viewer-request function or any
+non-ETag AWS error still fails immediately. The reusable workflow uploads
+`buildchain-web-surface-*-diagnostics`
 artifacts containing the apply and health JSON so the failing AWS operation or
 HTTP check is visible from the consumer run.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "2.14.13",
+  "version": "2.14.14-alpha.1",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",

package/scripts/web-surface-cloudfront-rewrite.mjs

@@ -15,6 +15,9 @@ const FUNCTION_CODE = `function handler(event) {
 }
 `;
 
+const DISTRIBUTION_UPDATE_MAX_ATTEMPTS = 3;
+const DISTRIBUTION_UPDATE_RETRY_DELAY_MS = 250;
+
 function readArg(name, fallback = "") {
   const flag = `--${name}`;
   const index = process.argv.indexOf(flag);
@@ -31,7 +34,7 @@ function runAws(args, { allowFailure = false } = {}) {
   });
   if (result.error) {
     if (allowFailure) {
-      return { ok: false, stdout: "", stderr: String(result.error.message || result.error) };
+      return { ok: false, status: null, stdout: "", stderr: String(result.error.message || result.error) };
     }
     throw result.error;
   }
@@ -39,11 +42,11 @@ function runAws(args, { allowFailure = false } = {}) {
   const stderr = String(result.stderr || "");
   if (result.status !== 0) {
     if (allowFailure) {
-      return { ok: false, stdout, stderr };
+      return { ok: false, status: result.status, stdout, stderr };
     }
     throw new Error(`aws ${args.join(" ")} failed with exit code ${result.status}${stderr.trim() ? `: ${stderr.trim()}` : ""}`);
   }
-  return { ok: true, stdout, stderr };
+  return { ok: true, status: result.status, stdout, stderr };
 }
 
 function runAwsJson(args, options = {}) {
@@ -58,6 +61,22 @@ function functionConfig(comment) {
   return `Comment=${comment.replace(/,/g, " ")},Runtime=cloudfront-js-2.0`;
 }
 
+function awsFailureMessage(args, result) {
+  const status = result.status === null || result.status === undefined
+    ? ""
+    : ` with exit code ${result.status}`;
+  const stderr = String(result.stderr || "").trim();
+  return `aws ${args.join(" ")} failed${status}${stderr ? `: ${stderr}` : ""}`;
+}
+
+function isStaleDistributionEtag(result) {
+  return result.ok === false && /\bPreconditionFailed\b/.test(String(result.stderr || ""));
+}
+
+function sleepSync(milliseconds) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, milliseconds);
+}
+
 function writeFunctionCode(tmpDir) {
   const file = path.join(tmpDir, "directory-index-rewrite.js");
   fs.writeFileSync(file, FUNCTION_CODE);
@@ -130,57 +149,85 @@ function publishFunction({ name, etag }) {
 }
 
 function attachFunction({ distributionId, functionArn }) {
-  const current = runAwsJson(["cloudfront", "get-distribution-config", "--id", distributionId]);
-  const etag = current.data?.ETag || "";
-  const config = current.data?.DistributionConfig;
-  if (!etag || !config) {
-    throw new Error(`cloudfront get-distribution-config did not return ETag and DistributionConfig for ${distributionId}`);
-  }
-  const defaultBehavior = config.DefaultCacheBehavior || {};
-  const existing = defaultBehavior.FunctionAssociations || { Quantity: 0, Items: [] };
-  const items = Array.isArray(existing.Items) ? [...existing.Items] : [];
-  const currentViewer = items.find((item) => item.EventType === "viewer-request");
-  if (currentViewer && currentViewer.FunctionARN && currentViewer.FunctionARN !== functionArn) {
-    throw new Error(
-      `CloudFront distribution ${distributionId} already has a different viewer-request function ${currentViewer.FunctionARN}; ` +
-      "remove or migrate it before Buildchain can manage directory-index rewrites",
-    );
-  }
-  const nextItems = [
-    ...items.filter((item) => item.EventType !== "viewer-request"),
-    {
-      EventType: "viewer-request",
-      FunctionARN: functionArn,
-    },
-  ];
-  config.DefaultCacheBehavior = {
-    ...defaultBehavior,
-    FunctionAssociations: {
-      Quantity: nextItems.length,
-      Items: nextItems,
-    },
-  };
-  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "buildchain-cloudfront-distribution-"));
-  try {
-    const configFile = path.join(tmpDir, "distribution-config.json");
-    fs.writeFileSync(configFile, `${JSON.stringify(config, null, 2)}\n`);
-    runAws([
-      "cloudfront",
-      "update-distribution",
-      "--id",
-      distributionId,
-      "--if-match",
-      etag,
-      "--distribution-config",
-      `file://${configFile}`,
-    ]);
-  } finally {
-    fs.rmSync(tmpDir, { recursive: true, force: true });
+  let previousViewerRequestFunction;
+  for (let attempt = 1; attempt <= DISTRIBUTION_UPDATE_MAX_ATTEMPTS; attempt += 1) {
+    const current = runAwsJson(["cloudfront", "get-distribution-config", "--id", distributionId]);
+    const etag = current.data?.ETag || "";
+    const config = current.data?.DistributionConfig;
+    if (!etag || !config) {
+      throw new Error(`cloudfront get-distribution-config did not return ETag and DistributionConfig for ${distributionId}`);
+    }
+    const defaultBehavior = config.DefaultCacheBehavior || {};
+    const existing = defaultBehavior.FunctionAssociations || { Quantity: 0, Items: [] };
+    const items = Array.isArray(existing.Items) ? [...existing.Items] : [];
+    const currentViewer = items.find((item) => item.EventType === "viewer-request");
+    if (previousViewerRequestFunction === undefined) {
+      previousViewerRequestFunction = currentViewer?.FunctionARN || "";
+    }
+    if (currentViewer && currentViewer.FunctionARN && currentViewer.FunctionARN !== functionArn) {
+      throw new Error(
+        `CloudFront distribution ${distributionId} already has a different viewer-request function ${currentViewer.FunctionARN}; ` +
+        "remove or migrate it before Buildchain can manage directory-index rewrites",
+      );
+    }
+    if (currentViewer?.FunctionARN === functionArn) {
+      return {
+        previousViewerRequestFunction,
+        nextViewerRequestFunction: functionArn,
+      };
+    }
+
+    const nextItems = [
+      ...items.filter((item) => item.EventType !== "viewer-request"),
+      {
+        EventType: "viewer-request",
+        FunctionARN: functionArn,
+      },
+    ];
+    config.DefaultCacheBehavior = {
+      ...defaultBehavior,
+      FunctionAssociations: {
+        Quantity: nextItems.length,
+        Items: nextItems,
+      },
+    };
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "buildchain-cloudfront-distribution-"));
+    let args;
+    let updated;
+    try {
+      const configFile = path.join(tmpDir, "distribution-config.json");
+      fs.writeFileSync(configFile, `${JSON.stringify(config, null, 2)}\n`);
+      args = [
+        "cloudfront",
+        "update-distribution",
+        "--id",
+        distributionId,
+        "--if-match",
+        etag,
+        "--distribution-config",
+        `file://${configFile}`,
+      ];
+      updated = runAws(args, { allowFailure: true });
+    } finally {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+    if (updated.ok) {
+      return {
+        previousViewerRequestFunction,
+        nextViewerRequestFunction: functionArn,
+      };
+    }
+    if (!isStaleDistributionEtag(updated)) {
+      throw new Error(awsFailureMessage(args, updated));
+    }
+    if (attempt === DISTRIBUTION_UPDATE_MAX_ATTEMPTS) {
+      throw new Error(
+        `CloudFront update-distribution still failed after ${attempt} attempts: ${awsFailureMessage(args, updated)}`,
+      );
+    }
+    sleepSync(DISTRIBUTION_UPDATE_RETRY_DELAY_MS * attempt);
   }
-  return {
-    previousViewerRequestFunction: currentViewer?.FunctionARN || "",
-    nextViewerRequestFunction: functionArn,
-  };
+  throw new Error(`CloudFront update-distribution retry loop ended unexpectedly for ${distributionId}`);
 }
 
 export function ensureCloudFrontDirectoryIndexRewrite({