@kungfu-tech/buildchain 2.8.2 → 2.8.3-alpha.1

package/bin/buildchain.mjs

@@ -81,6 +81,7 @@ function usage() {
                                     [--kfd-3-prebuild-witness-json <json-or-path>]...
                                     [--kfd-3-artifact-witness-json <json-or-path>]...
                                     [--kfd-3-artifact-verify-cmd <command>]
+                                    [--base-passport-json <json-or-path>] [--require-base-kfd]
                                     [--release-extra-json <json-or-path>]
                                     [--publish-json <json-or-path>] [--output-dir <dir>] [--json]
   buildchain verify release-passport <file-or-url> [--json]
@@ -744,6 +745,8 @@ async function main(argv = process.argv.slice(2)) {
       kfd3PrebuildWitnessJsons: readRepeatedFlag(collectArgs, "kfd-3-prebuild-witness-json"),
       kfd3ArtifactWitnessJsons: readRepeatedFlag(collectArgs, "kfd-3-artifact-witness-json"),
       kfd3ArtifactVerifyCommand: readFlag(collectArgs, "kfd-3-artifact-verify-cmd", ""),
+      basePassportJson: readFlag(collectArgs, "base-passport-json", ""),
+      requireBaseKfd: readBooleanFlag(collectArgs, "require-base-kfd"),
       releaseJsonExtra: readFlag(collectArgs, "release-extra-json", ""),
       publishJson: readFlag(collectArgs, "publish-json", ""),
       workflow,

package/dist/site/buildchain-contract.json

@@ -4,7 +4,7 @@
   "product": {
     "name": "Buildchain",
     "package": "@kungfu-tech/buildchain",
-    "version": "2.8.2",
+    "version": "2.8.3-alpha.1",
     "repository": "https://github.com/kungfu-systems/buildchain"
   },
   "majorLine": "v2",
@@ -193,7 +193,7 @@
         "release-state SHA is recorded as a durable audit entrance"
       ],
       "breakingDigest": "sha256:b627e1b2ece9b6049517a942c5139e342e6077cdd3d8962d61cef8481b1f70ad",
-      "auditDigest": "sha256:22017d4cbe0d89aecfcada7b93f5cdf2935837b2236ae4aeff23f19dbf3d26cb"
+      "auditDigest": "sha256:40c556f7df33a3c07ba6009c4cd283fad97b82db7026f2dc6db9394efbc1431c"
     },
     {
       "contractVersion": 1,
@@ -242,7 +242,7 @@
         "prose-only public claims downgrade the release trust passport audit"
       ],
       "breakingDigest": "sha256:f0b636eb925ddbf45ff1a8872454ab7b4dd98857cac12bb75217830130e62a16",
-      "auditDigest": "sha256:22017d4cbe0d89aecfcada7b93f5cdf2935837b2236ae4aeff23f19dbf3d26cb"
+      "auditDigest": "sha256:40c556f7df33a3c07ba6009c4cd283fad97b82db7026f2dc6db9394efbc1431c"
     },
     {
       "contractVersion": 1,
@@ -298,7 +298,7 @@
         "CLI commands are stable within the major line unless the contract major changes"
       ],
       "breakingDigest": "sha256:097db3e67509bedda8c6548bf1edfbfcf57f7b5510520b6a7b7e078d7ec087c8",
-      "auditDigest": "sha256:478e656104272675d3be3391158251472e0c2515b3113376ef0e52757b47ace0"
+      "auditDigest": "sha256:1f4b07ac623517209dbdee2992f94d95f7ee96e8f35f13ef620dad8da9d2a6e0"
     },
     {
       "contractVersion": 1,
@@ -320,7 +320,7 @@
         "manual entries carry source file digests so downstream sites and agents can detect stale hand-written documentation"
       ],
       "breakingDigest": "sha256:7d0d2819e3a3e72989d9c57b5efe9d0bc0a79bc0f2c82a0c7b9d6c5a211a91f2",
-      "auditDigest": "sha256:7fbde28193df754afda019e218defb5d08aa2c64298382d277927faba5468240"
+      "auditDigest": "sha256:6f4d02f7852b46b293bbb3fb63c678a57dffdcb93598fd3bac5298796e624b63"
     },
     {
       "contractVersion": 1,
@@ -342,9 +342,9 @@
         "agents can discover supported Node APIs without importing internal file paths"
       ],
       "breakingDigest": "sha256:48f925608d3e2131d90936b07dc2a30341204cae3e6e785c0f77d61ad755c945",
-      "auditDigest": "sha256:f3ba17b4a48e7d0f2996fb9f39d5ff7f16f1e2de1958fc07718b04bdf8af5533"
+      "auditDigest": "sha256:c3745538a9b17829bf07db485247f8e86245736798b9e631a935e53073a382d0"
     }
   ],
   "compatibilityDigest": "sha256:36421b592a782decbfe31a7d8d42d70ce1100a56a2c4f4a0ccc21f0617dc72bf",
-  "contractDigest": "sha256:12d39a2256bc4b93c81aa3ba1ce62ccc35fbb5054fca395815d77d8902aa42fe"
+  "contractDigest": "sha256:5e122a3c90f0c025377d684a804871d49050f2138bb18ec2f70cadbcf442cc52"
 }

package/dist/site/buildchain-site.json

@@ -145,7 +145,7 @@
       "path": "docs/web-surface-deployments.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:614aea65d745e8978d8329545753adf13b8914f84fe35b0148abbd1aff0c0dc2"
+      "digest": "sha256:796e891819f03f0a7ac91f56f1bb74d9e3443d8bb0bee33a3cd053d70bde6a62"
     },
     {
       "id": "infra-contract",

package/dist/site/manual-registry.json

@@ -107,7 +107,7 @@
       "title": "Web surface deployments",
       "path": "docs/web-surface-deployments.md",
       "plane": "use",
-      "digest": "sha256:614aea65d745e8978d8329545753adf13b8914f84fe35b0148abbd1aff0c0dc2"
+      "digest": "sha256:796e891819f03f0a7ac91f56f1bb74d9e3443d8bb0bee33a3cd053d70bde6a62"
     },
     {
       "id": "infra-contract",

package/dist/site/node-api-registry.json

@@ -62,7 +62,7 @@
       "specifier": "@kungfu-tech/buildchain/release-passport",
       "export": "./release-passport",
       "target": "./packages/core/release-passport.js",
-      "digest": "sha256:22017d4cbe0d89aecfcada7b93f5cdf2935837b2236ae4aeff23f19dbf3d26cb"
+      "digest": "sha256:40c556f7df33a3c07ba6009c4cd283fad97b82db7026f2dc6db9394efbc1431c"
     },
     {
       "specifier": "@kungfu-tech/buildchain/release-propagation",

package/dist/site/site-manifest.json

@@ -130,7 +130,7 @@
       "path": "docs/web-surface-deployments.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:614aea65d745e8978d8329545753adf13b8914f84fe35b0148abbd1aff0c0dc2"
+      "digest": "sha256:796e891819f03f0a7ac91f56f1bb74d9e3443d8bb0bee33a3cd053d70bde6a62"
     },
     {
       "id": "infra-contract",

package/docs/web-surface-deployments.md

@@ -64,10 +64,10 @@ secret_refs = ["AWS_ROLE_ARN"]
 ### Multi-Surface Host Mapping
 
 Some site repositories publish more than one first-class web surface from the
-same artifact. For example, a developer substrate site may have a hub plus
-separate hostnames for core and Buildchain documentation. These are not just
-navigation paths; staging and preview should be able to verify host-level
-behavior for each surface.
+same artifact. For example, `site-libkungfu-dev` has a hub plus separate
+hostnames for core, Buildchain, and Kung Fu Decisions. These are not just
+navigation paths; staging, production preflight, and post-deploy health checks
+must verify host-level behavior for each surface.
 
 Declare named surfaces with per-channel URLs:
 
@@ -89,6 +89,12 @@ path = "/buildchain/"
 production_url = "https://buildchain.libkungfu.dev"
 staging_url = "https://buildchain.staging.libkungfu.dev"
 preview_url_pattern = "https://buildchain-{alias}.preview.libkungfu.dev"
+
+[surfaces.kfd]
+path = "/kfd/"
+production_url = "https://kfd.libkungfu.dev"
+staging_url = "https://kfd.staging.libkungfu.dev"
+preview_url_pattern = "https://kfd-{alias}.preview.libkungfu.dev"
 ```
 
 Buildchain resolves every `(channel, surface)` pair. A preview alias such as
@@ -98,6 +104,7 @@ Buildchain resolves every `(channel, surface)` pair. A preview alias such as
 hub:        https://pr-12.preview.libkungfu.dev
 core:       https://core-pr-12.preview.libkungfu.dev
 buildchain: https://buildchain-pr-12.preview.libkungfu.dev
+kfd:        https://kfd-pr-12.preview.libkungfu.dev
 ```
 
 When `surfaces` is omitted, Buildchain preserves the legacy single-surface
@@ -325,6 +332,48 @@ and exits non-zero after writing the result JSON. Buildchain records secret
 reference names only; the runner must provide the AWS CLI and credentials
 outside Buildchain, typically through OIDC and the declared `secret_refs`.
 
+## Production Preflight And Health
+
+Production promotion is not just `deploy-apply --channel production`. Before a
+live production apply, the reusable workflow runs:
+
+```bash
+node scripts/web-surface.mjs \
+  --mode production-preflight \
+  --cwd fixtures/web-surface-shaped \
+  --plan .buildchain/web-surface-production-plan.json \
+  --execute true \
+  --output .buildchain/web-surface-production-preflight.json
+```
+
+The production preflight checks that:
+
+- `channels.production` is canonical and indexable;
+- every surface has concrete production bucket and CloudFront targets;
+- every production surface URL is HTTPS;
+- the production AWS role can inspect the declared bucket and distribution;
+- CloudFront aliases cover every surface host, including product hosts such as
+  `kfd.libkungfu.dev`;
+- DNS resolves for every surface host.
+
+After production apply, the workflow runs:
+
+```bash
+node scripts/web-surface.mjs \
+  --mode health-check \
+  --cwd fixtures/web-surface-shaped \
+  --result .buildchain/web-surface-production-apply.json \
+  --output .buildchain/web-surface-production-health.json
+```
+
+The health check fetches every surface URL from the apply result and fails
+production if a response is unreachable, returns an unexpected status, or still
+sends `x-robots-tag: noindex`. It also verifies that each surface binding
+recorded a deployment manifest pointer. The production release passport embeds
+the deploy plan, apply result, production preflight, and health check so a
+reviewer or agent can audit why the production site changed and whether every
+declared host was actually covered.
+
 ## Cleanup Plans
 
 Preview cleanup is an auditable cleanup contract. It can run as a dry-run plan,

package/fixtures/web-surface-shaped/README.md

@@ -7,13 +7,14 @@ It proves that `project.type = "web-surface"` can declare preview, staging, and
 production channels, named surface host mappings, deterministic deployment
 manifests, and dry-run deploy and cleanup plans without touching AWS.
 
-The fixture is shaped like a `site-libkungfu-dev` repository with three
+The fixture is shaped like a `site-libkungfu-dev` repository with four
 first-class surfaces:
 
 ```text
 hub        https://libkungfu.dev
 core       https://core.libkungfu.dev
 buildchain https://buildchain.libkungfu.dev
+kfd        https://kfd.libkungfu.dev
 ```
 
 For preview and staging, Buildchain resolves the same surface names to the

package/package.json

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

package/packages/core/release-passport.js

@@ -281,6 +281,73 @@ function parseJsonInputWithMeta(value, fallback = undefined) {
   };
 }
 
+function mergeAuthoritativePassportBase(passport, basePassport = undefined, { requireKfd = false } = {}) {
+  if (!basePassport) {
+    if (requireKfd) {
+      throw new Error("release passport base with KFD evidence is required");
+    }
+    return passport;
+  }
+  if (typeof basePassport !== "object" || Array.isArray(basePassport)) {
+    throw new Error("release passport base must be a JSON object");
+  }
+  const kfdKeys = ["kfd-1", "kfd-2", "kfd-3"];
+  const missingKfd = kfdKeys.filter((key) => (
+    !basePassport[key] ||
+    typeof basePassport[key] !== "object" ||
+    Array.isArray(basePassport[key])
+  ));
+  if (requireKfd && missingKfd.length > 0) {
+    throw new Error(`release passport base is missing required KFD sections: ${missingKfd.join(", ")}`);
+  }
+  const merged = {
+    ...passport,
+    release: {
+      ...(passport.release && typeof passport.release === "object" && !Array.isArray(passport.release) ? passport.release : {}),
+      ...(basePassport.release && typeof basePassport.release === "object" && !Array.isArray(basePassport.release) ? basePassport.release : {}),
+    },
+    evidence: {
+      ...(passport.evidence && typeof passport.evidence === "object" && !Array.isArray(passport.evidence) ? passport.evidence : {}),
+      kfd1: basePassport.evidence?.kfd1 || passport.evidence?.kfd1 || "",
+      kfd2: basePassport.evidence?.kfd2 || passport.evidence?.kfd2 || "",
+      kfd3: basePassport.evidence?.kfd3 || passport.evidence?.kfd3 || "",
+    },
+  };
+  for (const key of ["versionImpact", "surfaceImpacts"]) {
+    if (basePassport[key] !== undefined) {
+      merged[key] = basePassport[key];
+    }
+  }
+  for (const key of kfdKeys) {
+    if (basePassport[key] && typeof basePassport[key] === "object" && !Array.isArray(basePassport[key])) {
+      merged[key] = basePassport[key];
+    }
+  }
+  return merged;
+}
+
+function mergeAuthoritativeImpactBase(impact, basePassport = undefined) {
+  if (!basePassport || typeof basePassport !== "object" || Array.isArray(basePassport)) {
+    return impact;
+  }
+  const merged = { ...impact };
+  if (basePassport.versionImpact && typeof basePassport.versionImpact === "object" && !Array.isArray(basePassport.versionImpact)) {
+    merged.versionImpact = {
+      ...(impact.versionImpact && typeof impact.versionImpact === "object" && !Array.isArray(impact.versionImpact) ? impact.versionImpact : {}),
+      ...basePassport.versionImpact,
+    };
+  }
+  if (Array.isArray(basePassport.surfaceImpacts)) {
+    merged.surfaceImpacts = basePassport.surfaceImpacts;
+  }
+  for (const key of ["classification", "breaking", "security", "migrationRequired", "summary"]) {
+    if (basePassport[key] !== undefined) {
+      merged[key] = basePassport[key];
+    }
+  }
+  return merged;
+}
+
 function parseJsonCommandOutput({ command = "", cwd = process.cwd(), label = "command" } = {}) {
   const normalized = String(command || "").trim();
   if (!normalized) {
@@ -1054,6 +1121,8 @@ export function collectGitHubReleasePassport({
   kfd3PrebuildWitnessJsons = [],
   kfd3ArtifactWitnessJsons = [],
   kfd3ArtifactVerifyCommand = "",
+  basePassportJson = "",
+  requireBaseKfd = false,
   releaseJsonExtra = "",
   publishJson = "",
   workflow = {},
@@ -1088,6 +1157,7 @@ export function collectGitHubReleasePassport({
     .filter(Boolean)
     .map((witnessJson) => parseJsonInputWithMeta(witnessJson, undefined))
     .filter((meta) => meta.value);
+  const basePassportMeta = parseJsonInputWithMeta(basePassportJson, undefined);
   const kfd3ArtifactCommandMeta = parseJsonCommandOutput({
     command: kfd3ArtifactVerifyCommand,
     cwd,
@@ -1107,7 +1177,10 @@ export function collectGitHubReleasePassport({
   const resolvedOutputDir = path.resolve(cwd, outputDir);
   const productMechanism = defaultProductMechanism({ repository, productName });
   const artifactEvidence = createArtifactEvidence({ assets, repository, tag: resolvedTag, sourceSha, workflow });
-  const impact = normalizeImpactLedger(impactMeta.value, { tag: resolvedTag, line, decision: "unknown" });
+  const impact = mergeAuthoritativeImpactBase(
+    normalizeImpactLedger(impactMeta.value, { tag: resolvedTag, line, decision: "unknown" }),
+    basePassportMeta.value,
+  );
   const agentIndex = defaultAgentIndex({ tag: resolvedTag });
   const kfd1 = createKfd1ReleaseGateEvidence({
     cwd,
@@ -1122,7 +1195,7 @@ export function collectGitHubReleasePassport({
     artifactWitnessMetas: kfd3ArtifactWitnessMetas,
     artifactCommandMeta: kfd3ArtifactCommandMeta.value ? kfd3ArtifactCommandMeta : undefined,
   });
-  const passport = createReleasePassport({
+  const passport = mergeAuthoritativePassportBase(createReleasePassport({
     cwd,
     repository,
     tag: resolvedTag,
@@ -1164,7 +1237,7 @@ export function collectGitHubReleasePassport({
     publishEvidencePath: publishEvidenceMeta.path ? path.relative(resolvedOutputDir, publishEvidenceMeta.path).split(path.sep).join("/") : "",
     transactionStatePath: transactionMeta.path ? path.relative(resolvedOutputDir, transactionMeta.path).split(path.sep).join("/") : "",
     workflow,
-  });
+  }), basePassportMeta.value, { requireKfd: requireBaseKfd });
   const checkReport = createReleaseCheckReport({
     passport,
     artifactEvidence,

package/scripts/web-surface-core.mjs

@@ -1,5 +1,6 @@
 import crypto from "node:crypto";
 import { spawnSync } from "node:child_process";
+import dns from "node:dns/promises";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -229,6 +230,14 @@ function cdnWildcardPath(value) {
   return normalized ? `/${normalized}/*` : "/*";
 }
 
+function viewerWildcardPath(binding) {
+  try {
+    return cdnWildcardPath(new URL(binding.url).pathname);
+  } catch {
+    return cdnWildcardPath(binding.objectPrefix);
+  }
+}
+
 function syncStaticArtifactArgs({ artifactRoot, bucket, objectPrefix }) {
   const args = ["s3", "sync", artifactRoot, s3Uri(bucket, objectPrefix), "--delete"];
   if (!objectPrefix) {
@@ -337,6 +346,66 @@ function assertConcreteAwsDeployConfig({ deployConfig, channel, operation }) {
   }
 }
 
+function urlHost(value = "") {
+  try {
+    return new URL(value).hostname.toLowerCase();
+  } catch {
+    return "";
+  }
+}
+
+function wildcardHostMatches(alias = "", host = "") {
+  const normalizedAlias = String(alias || "").toLowerCase();
+  const normalizedHost = String(host || "").toLowerCase();
+  if (!normalizedAlias.startsWith("*.")) return false;
+  const suffix = normalizedAlias.slice(1);
+  return normalizedHost.endsWith(suffix) && normalizedHost.slice(0, -suffix.length).indexOf(".") === -1;
+}
+
+function aliasMatchesHost(aliases = [], host = "") {
+  const normalizedHost = String(host || "").toLowerCase();
+  return aliases.some((alias) => {
+    const normalizedAlias = String(alias || "").toLowerCase();
+    return normalizedAlias === normalizedHost || wildcardHostMatches(normalizedAlias, normalizedHost);
+  });
+}
+
+function parseCloudFrontAliases(stdout = "") {
+  if (!stdout) return [];
+  try {
+    const parsed = JSON.parse(stdout);
+    const aliases = parsed?.Distribution?.DistributionConfig?.Aliases?.Items ||
+      parsed?.DistributionConfig?.Aliases?.Items ||
+      parsed?.Aliases?.Items ||
+      parsed?.Aliases ||
+      [];
+    return Array.isArray(aliases) ? aliases : [];
+  } catch {
+    return [];
+  }
+}
+
+async function defaultDnsResolver(host) {
+  try {
+    const answers = await dns.resolve(host);
+    return answers.map((address) => ({ type: "A", value: address }));
+  } catch (error) {
+    if (error?.code === "ENODATA" || error?.code === "ENOTFOUND") {
+      const answers = await dns.resolve6(host);
+      return answers.map((address) => ({ type: "AAAA", value: address }));
+    }
+    throw error;
+  }
+}
+
+function preflightCheck({ name, status = "pass", details = {}, message = "" }) {
+  return { name, status, message, details };
+}
+
+function preflightStatus(checks) {
+  return checks.some((check) => check.status === "fail") ? "failed" : "passed";
+}
+
 function deployManifestKey(deployConfig, manifest) {
   return joinS3Key(manifestPrefixFor(deployConfig), `${manifest.alias || manifest.channel}.json`);
 }
@@ -694,7 +763,7 @@ export function applyWebSurfaceDeploy({
   const primaryBinding = bindings[0] || {};
   const objectPrefix = primaryBinding.objectPrefix || objectPrefixFor(deployConfig, resolvedPlan.manifest.alias || resolvedPlan.manifest.channel);
   const manifestKey = primaryBinding.manifestKey || deployManifestKey(deployConfig, resolvedPlan.manifest);
-  const invalidationPaths = bindings.flatMap((binding) => [cdnWildcardPath(binding.objectPrefix), cdnPath(binding.manifestKey)]);
+  const invalidationPaths = bindings.flatMap((binding) => [viewerWildcardPath(binding), cdnPath(binding.manifestKey)]);
   const operationResults = runAdapterOperations({ operations, dryRun, commandRunner });
   return {
     schemaVersion: 1,
@@ -722,6 +791,365 @@ export function applyWebSurfaceDeploy({
   };
 }
 
+export async function preflightWebSurfaceProduction({
+  cwd = process.cwd(),
+  plan = null,
+  execute = false,
+  commandRunner = defaultCommandRunner,
+  dnsResolver = defaultDnsResolver,
+  checkedAt = new Date().toISOString(),
+} = {}) {
+  const resolvedPlan = plan ? assertDeployPlan(plan) : planWebSurfaceDeploy({
+    cwd,
+    channel: "production",
+    sourceSha: "0".repeat(40),
+    artifactHash: "0".repeat(64),
+    dryRun: true,
+    deployedAt: checkedAt,
+  });
+  if (resolvedPlan.channel !== "production") {
+    throw new Error("web-surface production preflight requires a production deploy plan");
+  }
+  const loadedConfig = loadBuildchainConfig(cwd);
+  const config = assertWebSurfaceConfig(loadedConfig);
+  const channel = config.channels?.production || {};
+  const deployConfig = config.deploy?.production;
+  if (!deployConfig) {
+    throw new Error("missing deploy.production");
+  }
+  const checks = [];
+  const configuredProductionBindings = resolveSurfaceBindings({
+    config,
+    channelName: "production",
+    alias: "",
+    deployConfig,
+  });
+  const bindings = resolvedPlan.manifest?.surfaceBindings || resolveSurfaceBindings({
+    config,
+    channelName: "production",
+    alias: "",
+    deployConfig,
+  });
+
+  checks.push(preflightCheck({
+    name: "production-channel",
+    status: channel.canonical === true && channel.noindex === false ? "pass" : "fail",
+    details: {
+      canonical: channel.canonical,
+      noindex: channel.noindex,
+    },
+    message: channel.canonical === true && channel.noindex === false
+      ? "production channel is canonical and indexable"
+      : "channels.production must be canonical=true and noindex=false",
+  }));
+
+  const configuredSurfaceNames = configuredProductionBindings.map((binding) => binding.surface).sort();
+  const plannedSurfaceNames = bindings.map((binding) => binding.surface).sort();
+  const missingSurfaces = configuredSurfaceNames.filter((surface) => !plannedSurfaceNames.includes(surface));
+  const extraSurfaces = plannedSurfaceNames.filter((surface) => !configuredSurfaceNames.includes(surface));
+  checks.push(preflightCheck({
+    name: "production-surface-set",
+    status: missingSurfaces.length === 0 && extraSurfaces.length === 0 ? "pass" : "fail",
+    details: {
+      configured: configuredSurfaceNames,
+      planned: plannedSurfaceNames,
+      missing: missingSurfaces,
+      extra: extraSurfaces,
+    },
+    message: missingSurfaces.length === 0 && extraSurfaces.length === 0
+      ? "production plan covers every configured surface"
+      : `production plan surface mismatch: missing=${missingSurfaces.join(",") || "-"} extra=${extraSurfaces.join(",") || "-"}`,
+  }));
+
+  const concreteFailures = [];
+  for (const binding of bindings) {
+    const effectiveDeploy = surfaceDeployConfig(deployConfig, binding.surface);
+    try {
+      assertConcreteAwsDeployConfig({
+        deployConfig: effectiveDeploy,
+        channel: `production.surfaces.${binding.surface}`,
+        operation: "deploy",
+      });
+    } catch (error) {
+      concreteFailures.push(String(error.message || error));
+    }
+  }
+  checks.push(preflightCheck({
+    name: "production-targets",
+    status: concreteFailures.length === 0 ? "pass" : "fail",
+    details: {
+      bindings: bindings.map((binding) => ({
+        surface: binding.surface,
+        bucket: binding.bucket,
+        distributionId: binding.distributionId,
+        objectPrefix: binding.objectPrefix,
+        manifestKey: binding.manifestKey,
+      })),
+      failures: concreteFailures,
+    },
+    message: concreteFailures.length === 0
+      ? "production bucket and CloudFront distribution values are concrete"
+      : concreteFailures.join("; "),
+  }));
+
+  const hosts = bindings.map((binding) => ({
+    surface: binding.surface,
+    url: binding.url,
+    host: urlHost(binding.url),
+    distributionId: binding.distributionId,
+  }));
+  const invalidHosts = hosts.filter((entry) => !entry.host || !entry.url.startsWith("https://"));
+  checks.push(preflightCheck({
+    name: "production-surface-hosts",
+    status: invalidHosts.length === 0 ? "pass" : "fail",
+    details: { hosts, invalidHosts },
+    message: invalidHosts.length === 0
+      ? "all production surfaces declare HTTPS hosts"
+      : `invalid production surface hosts: ${invalidHosts.map((entry) => entry.surface).join(", ")}`,
+  }));
+
+  const awsResults = [];
+  if (execute) {
+    const checkedBuckets = new Set();
+    for (const binding of bindings) {
+      const effectiveDeploy = surfaceDeployConfig(deployConfig, binding.surface);
+      const bucket = binding.bucket || effectiveDeploy.bucket || effectiveDeploy.target || "";
+      if (bucket && !checkedBuckets.has(bucket)) {
+        checkedBuckets.add(bucket);
+        const operation = {
+          action: "preflight-head-bucket",
+          surface: binding.surface,
+          command: "aws",
+          args: ["s3api", "head-bucket", "--bucket", bucket],
+        };
+        awsResults.push(runAdapterOperation({ operation, dryRun: false, commandRunner }));
+      }
+    }
+
+    const checkedDistributions = new Set();
+    for (const binding of bindings) {
+      const distributionId = binding.distributionId || "";
+      if (distributionId && !checkedDistributions.has(distributionId)) {
+        checkedDistributions.add(distributionId);
+        const operation = {
+          action: "preflight-get-distribution",
+          surface: binding.surface,
+          command: "aws",
+          args: ["cloudfront", "get-distribution", "--id", distributionId, "--output", "json"],
+        };
+        awsResults.push(runAdapterOperation({ operation, dryRun: false, commandRunner }));
+      }
+    }
+  }
+
+  const failedAws = awsResults.filter((result) => result.status === "failed");
+  checks.push(preflightCheck({
+    name: "production-aws-access",
+    status: !execute || failedAws.length === 0 ? "pass" : "fail",
+    details: {
+      execute,
+      operations: awsResults.map((result) => ({
+        action: result.action,
+        surface: result.surface,
+        status: result.status,
+        stderr: result.stderr,
+      })),
+    },
+    message: !execute
+      ? "AWS access check planned but not executed"
+      : failedAws.length === 0
+        ? "production role can inspect buckets and CloudFront distributions"
+        : `production AWS access failed: ${failedAws.map((result) => `${result.action}:${result.surface}`).join(", ")}`,
+  }));
+
+  const aliasChecks = [];
+  if (execute) {
+    const aliasesByDistribution = new Map();
+    for (const result of awsResults.filter((entry) => entry.action === "preflight-get-distribution" && entry.status !== "failed")) {
+      const aliases = parseCloudFrontAliases(result.stdout);
+      aliasesByDistribution.set(result.args[result.args.indexOf("--id") + 1], aliases);
+    }
+    for (const host of hosts) {
+      const aliases = aliasesByDistribution.get(host.distributionId) || [];
+      aliasChecks.push({
+        ...host,
+        aliases,
+        matched: aliasMatchesHost(aliases, host.host),
+      });
+    }
+  }
+  const missingAliases = aliasChecks.filter((entry) => !entry.matched);
+  checks.push(preflightCheck({
+    name: "production-cloudfront-aliases",
+    status: !execute || missingAliases.length === 0 ? "pass" : "fail",
+    details: {
+      execute,
+      aliases: aliasChecks,
+    },
+    message: !execute
+      ? "CloudFront alias check planned but not executed"
+      : missingAliases.length === 0
+        ? "production CloudFront aliases cover every surface host"
+        : `missing CloudFront aliases: ${missingAliases.map((entry) => entry.host).join(", ")}`,
+  }));
+
+  const dnsChecks = [];
+  if (execute) {
+    for (const host of hosts) {
+      try {
+        const answers = await dnsResolver(host.host);
+        dnsChecks.push({ ...host, status: "pass", answers });
+      } catch (error) {
+        dnsChecks.push({ ...host, status: "fail", error: String(error.message || error) });
+      }
+    }
+  }
+  const failedDns = dnsChecks.filter((entry) => entry.status === "fail");
+  checks.push(preflightCheck({
+    name: "production-dns",
+    status: !execute || failedDns.length === 0 ? "pass" : "fail",
+    details: {
+      execute,
+      hosts: dnsChecks,
+    },
+    message: !execute
+      ? "DNS check planned but not executed"
+      : failedDns.length === 0
+        ? "production DNS resolves for every surface host"
+        : `production DNS failed: ${failedDns.map((entry) => entry.host).join(", ")}`,
+  }));
+
+  return {
+    schemaVersion: 1,
+    contract: "kungfu-buildchain-web-surface-production-preflight",
+    checkedAt,
+    execute,
+    channel: "production",
+    status: preflightStatus(checks),
+    url: resolvedPlan.url,
+    urls: resolvedPlan.urls,
+    sourceSha: resolvedPlan.manifest.sourceSha,
+    artifactHash: resolvedPlan.artifact.hash,
+    surfaceBindings: bindings,
+    checks,
+  };
+}
+
+function healthStatus(checks) {
+  return checks.some((check) => check.status === "fail") ? "failed" : "passed";
+}
+
+function noindexHeader(headers) {
+  const value = headers?.get?.("x-robots-tag") || "";
+  return String(value).toLowerCase().includes("noindex");
+}
+
+function noindexMeta(html = "") {
+  const source = String(html || "").toLowerCase();
+  return /<meta\s+[^>]*name=["']robots["'][^>]*content=["'][^"']*noindex/.test(source) ||
+    /<meta\s+[^>]*content=["'][^"']*noindex[^"']*["'][^>]*name=["']robots["']/.test(source);
+}
+
+function htmlLikeResponse(response, url = "") {
+  const contentType = response.headers?.get?.("content-type") || "";
+  return String(contentType).toLowerCase().includes("text/html") || /\/$|\.html(?:$|[?#])/.test(String(url || ""));
+}
+
+export async function checkWebSurfaceHealth({
+  result = null,
+  plan = null,
+  cwd = process.cwd(),
+  fetchImpl = fetch,
+  checkedAt = new Date().toISOString(),
+  allowedStatuses = [200],
+} = {}) {
+  const loadedConfig = loadBuildchainConfig(cwd);
+  const config = assertWebSurfaceConfig(loadedConfig);
+  const manifest = result?.manifest || plan?.manifest;
+  const channel = result?.channel || plan?.channel || manifest?.channel || "production";
+  const urls = result?.urls || plan?.urls || (manifest?.surfaceBindings
+    ? Object.fromEntries(manifest.surfaceBindings.map((binding) => [binding.surface, binding.url]))
+    : {});
+  const bindings = manifest?.surfaceBindings || [];
+  const checks = [];
+  if (Object.keys(urls).length === 0) {
+    checks.push({
+      surface: "__urls__",
+      url: "",
+      status: "fail",
+      httpStatus: 0,
+      finalUrl: "",
+      noindexHeader: false,
+      message: "web-surface health check requires at least one surface URL from an apply result or deploy plan",
+    });
+  }
+
+  for (const [surface, url] of Object.entries(urls)) {
+    try {
+      const response = await fetchImpl(url, { redirect: "follow" });
+      const expectedNoindex = Boolean(config.channels?.[channel]?.noindex);
+      const headerNoindex = noindexHeader(response.headers);
+      const body = htmlLikeResponse(response, url) && typeof response.text === "function"
+        ? await response.text()
+        : "";
+      const metaNoindex = noindexMeta(body);
+      const noindex = headerNoindex || metaNoindex;
+      const statusOk = allowedStatuses.includes(response.status);
+      const noindexOk = channel !== "production" || expectedNoindex || !noindex;
+      checks.push({
+        surface,
+        url,
+        status: statusOk && noindexOk ? "pass" : "fail",
+        httpStatus: response.status,
+        finalUrl: response.url || url,
+        noindexHeader: noindex,
+        noindexHeaderValue: headerNoindex,
+        noindexMeta: metaNoindex,
+        message: statusOk && noindexOk
+          ? "surface is reachable"
+          : `surface health failed: http=${response.status}, noindex=${noindex}`,
+      });
+    } catch (error) {
+      checks.push({
+        surface,
+        url,
+        status: "fail",
+        httpStatus: 0,
+        finalUrl: "",
+        noindexHeader: false,
+        message: String(error.message || error),
+      });
+    }
+  }
+
+  const manifestChecks = bindings.map((binding) => ({
+    surface: binding.surface,
+    manifestKey: binding.manifestKey,
+    bucket: binding.bucket,
+    distributionId: binding.distributionId,
+    status: binding.manifestKey ? "pass" : "fail",
+  }));
+  checks.push({
+    surface: "__manifest__",
+    url: "",
+    status: manifestChecks.length > 0 && manifestChecks.every((entry) => entry.status === "pass") ? "pass" : "fail",
+    manifests: manifestChecks,
+    message: "deployment manifest pointers are recorded for every surface",
+  });
+
+  return {
+    schemaVersion: 1,
+    contract: "kungfu-buildchain-web-surface-health-check",
+    checkedAt,
+    channel,
+    status: healthStatus(checks),
+    sourceSha: manifest?.sourceSha || result?.sourceSha || "",
+    artifactHash: manifest?.artifactHash || result?.artifactHash || "",
+    urls,
+    checks,
+  };
+}
+
 function deployBindingOperations({ artifactRoot, deployConfig, manifest, binding }) {
   const effectiveDeploy = surfaceDeployConfig(deployConfig, binding.surface);
   const bucket = binding.bucket || effectiveDeploy.bucket || effectiveDeploy.target || "";
@@ -757,7 +1185,7 @@ function deployBindingOperations({ artifactRoot, deployConfig, manifest, binding
         "--distribution-id",
         distribution,
         "--paths",
-        cdnWildcardPath(binding.objectPrefix),
+        viewerWildcardPath(binding),
         cdnPath(binding.manifestKey),
       ],
     });
@@ -994,7 +1422,7 @@ function cleanupEntryOperations({ deployConfig, entry, bucket }) {
           "--distribution-id",
           distribution,
           "--paths",
-          `${cdnPath(binding.objectPrefix)}/*`,
+          viewerWildcardPath(binding),
           cdnPath(binding.manifestKey),
         ],
       });

package/scripts/web-surface-release-feedback.mjs

@@ -169,6 +169,8 @@ export function createWebSurfaceReleasePassport({
   triggeringActor = "",
   runnerActor = "",
   oidcDeployIdentity = "",
+  productionPreflight = undefined,
+  healthCheck = undefined,
 } = {}) {
   const normalizedStatus = inferStatus({ result, applyOutcome, jobStatus }) || status;
   const decisionType = channel === "production" ? "release-pr-merge-or-manual-approval" : "main-merge-staging";
@@ -222,6 +224,8 @@ export function createWebSurfaceReleasePassport({
     evidence: {
       applyResultBound: Boolean(result),
       failureContext: normalizedStatus === "success" ? "" : optionalString(applyOutcome || jobStatus || "missing-apply-result"),
+      productionPreflight,
+      healthCheck,
     },
   };
 }
@@ -240,6 +244,12 @@ export function renderWebSurfaceReleaseFeedbackComment({
   const title = channel === "production" ? "Buildchain production deploy" : "Buildchain staging deploy";
   const failure = passport.evidence?.failureContext ? [`- Failure context: \`${passport.evidence.failureContext}\``] : [];
   const targetLine = target.pullNumber ? `- Comment target: PR #${target.pullNumber}` : "";
+  const preflight = passport.evidence?.productionPreflight?.status
+    ? `- Production preflight: \`${passport.evidence.productionPreflight.status}\``
+    : "";
+  const health = passport.evidence?.healthCheck?.status
+    ? `- Health check: \`${passport.evidence.healthCheck.status}\``
+    : "";
   return [
     marker,
     `## ${title}`,
@@ -250,6 +260,8 @@ export function renderWebSurfaceReleaseFeedbackComment({
     `- Artifact: \`${release.artifactHash || ""}\``,
     `- Target: \`${release.target || ""}\``,
     `- Rollback pointer: \`${release.rollbackPointer || ""}\``,
+    preflight,
+    health,
     `- Run: ${passport.workflow?.url || ""}`,
     `- Passport artifact: \`${passportArtifact || "buildchain-web-surface-release-passport"}\``,
     targetLine,
@@ -263,6 +275,8 @@ export async function webSurfaceReleaseFeedbackCli(env = process.env, { fetchImp
   const payload = JSON.parse(fs.readFileSync(eventPath, "utf8"));
   const channel = optionalString(env.BUILDCHAIN_WEB_SURFACE_CHANNEL || "staging");
   const result = readJsonIfExists(env.APPLY_RESULT_PATH || "");
+  const productionPreflight = readJsonIfExists(env.PREFLIGHT_RESULT_PATH || "");
+  const healthCheck = readJsonIfExists(env.HEALTH_RESULT_PATH || "");
   const repository = optionalString(env.GITHUB_REPOSITORY);
   const sourceSha = optionalString(result?.sourceSha || env.GITHUB_SHA);
   const workflowRunUrl = runUrl({
@@ -305,6 +319,8 @@ export async function webSurfaceReleaseFeedbackCli(env = process.env, { fetchImp
     triggeringActor: env.GITHUB_TRIGGERING_ACTOR,
     runnerActor: env.RUNNER_NAME || env.GITHUB_ACTOR,
     oidcDeployIdentity: env.DEPLOY_IDENTITY_REF || env.AWS_ROLE_ARN,
+    productionPreflight,
+    healthCheck,
   });
   const outputPath = env.OUTPUT_PATH || `.buildchain/web-surface-${channel}-release-passport.json`;
   fs.mkdirSync(path.dirname(outputPath), { recursive: true });

package/scripts/web-surface.mjs

@@ -5,9 +5,11 @@ import { pathToFileURL } from "node:url";
 import {
   applyWebSurfaceCleanup,
   applyWebSurfaceDeploy,
+  checkWebSurfaceHealth,
   defaultWebSurfaceAlias,
   planWebSurfaceCleanup,
   planWebSurfaceDeploy,
+  preflightWebSurfaceProduction,
   validateWebSurfaceProject,
 } from "./web-surface-core.mjs";
 import { writeGitHubOutputs } from "./build-contract-core.mjs";
@@ -138,6 +140,50 @@ export function webSurfaceCli() {
     return result;
   }
 
+  if (mode === "production-preflight") {
+    const plan = readJsonFileArg("plan");
+    const result = preflightWebSurfaceProduction({
+      cwd,
+      plan,
+      execute: readBooleanArg("execute", false),
+    });
+    return Promise.resolve(result).then((resolved) => {
+      writeJson(resolved, output);
+      writeGitHubOutputs({
+        "web-surface-production-preflight-status": resolved.status,
+        "web-surface-production-preflight-json": JSON.stringify(resolved),
+      });
+      if (resolved.status !== "passed") {
+        throw new Error(`web-surface production preflight failed: ${resolved.checks
+          .filter((check) => check.status === "fail")
+          .map((check) => check.message || check.name)
+          .join("; ")}`);
+      }
+      return resolved;
+    });
+  }
+
+  if (mode === "health-check") {
+    const resultFile = readArg("result", process.env.BUILDCHAIN_WEB_SURFACE_APPLY_RESULT || "");
+    const result = resultFile ? JSON.parse(fs.readFileSync(path.resolve(resultFile), "utf8")) : null;
+    const plan = readJsonFileArg("plan");
+    const health = checkWebSurfaceHealth({ cwd, result, plan });
+    return Promise.resolve(health).then((resolved) => {
+      writeJson(resolved, output);
+      writeGitHubOutputs({
+        "web-surface-health-status": resolved.status,
+        "web-surface-health-json": JSON.stringify(resolved),
+      });
+      if (resolved.status !== "passed") {
+        throw new Error(`web-surface health check failed: ${resolved.checks
+          .filter((check) => check.status === "fail")
+          .map((check) => check.message || check.surface)
+          .join("; ")}`);
+      }
+      return resolved;
+    });
+  }
+
   if (mode === "cleanup-plan") {
     const aliases = readArg("aliases", process.env.BUILDCHAIN_WEB_SURFACE_ALIASES || "")
       .split(",")
@@ -198,7 +244,7 @@ export function webSurfaceCli() {
 
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
   try {
-    webSurfaceCli();
+    await Promise.resolve(webSurfaceCli());
   } catch (error) {
     console.error(`::error::${String(error.message || error).replace(/\r?\n/g, "%0A")}`);
     process.exitCode = 1;