@kungfu-tech/buildchain 2.2.6-alpha.0 → 2.3.0-alpha.0

package/docs/lifecycle-protocol.md

@@ -307,16 +307,16 @@ schema = 1
 
 [project]
 type = "web-surface"
-name = "site-kungfu-tech"
-site = "kungfu-tech"
+name = "site-libkungfu-dev"
+site = "libkungfu-dev"
 
 [channels.preview]
-url_pattern = "https://{alias}.preview.kungfu.tech"
+url_pattern = "https://{alias}.preview.libkungfu.dev"
 visibility = "ephemeral"
 noindex = true
 
 [channels.staging]
-url = "https://staging.kungfu.tech"
+url = "https://staging.libkungfu.dev"
 visibility = "protected"
 access_control = "managed-network"
 edge_auth = "none"
@@ -324,20 +324,33 @@ noindex = true
 promotable = true
 
 [channels.production]
-url = "https://kungfu.tech"
+url = "https://libkungfu.dev"
 visibility = "public"
 canonical = true
 noindex = false
 
+[surfaces.hub]
+path = "/"
+production_url = "https://libkungfu.dev"
+staging_url = "https://staging.libkungfu.dev"
+preview_url_pattern = "https://{alias}.preview.libkungfu.dev"
+
+[surfaces.core]
+path = "/core/"
+production_url = "https://core.libkungfu.dev"
+staging_url = "https://core.staging.libkungfu.dev"
+preview_url_pattern = "https://core-{alias}.preview.libkungfu.dev"
+
 [deploy.production]
 adapter = "aws-s3-cloudfront"
-bucket = "kungfu-tech-production"
+bucket = "libkungfu-dev-production"
 artifact_path = "dist"
 secret_refs = ["AWS_ROLE_ARN"]
 ```
 
-See [Web-surface deployments](web-surface-deployments.md) for the manifest,
-preview alias, retention, cleanup, and dry-run deploy contract.
+See [Web-surface deployments](web-surface-deployments.md) for named surface host
+mappings, the manifest, preview alias, retention, cleanup, and dry-run deploy
+contract.
 
 ## Examples
 

package/docs/versioning.md

@@ -42,6 +42,7 @@ expected ref flow requires a major bump.
 | --- | --- | --- | --- |
 | 2026-07-02 | Buildchain toolkit observability is a minor surface. | `v2.1` | It adds the public logging SDK, CLI observability commands, and package subpaths that consumers can import. |
 | 2026-07-02 | Release passport and binary distribution are a minor surface. | `v2.2` | They add agent-readable release passport files, artifact evidence, impact ledger, agent index, GitHub Release collection and verification commands, and standalone binary assets. |
+| 2026-07-02 | Web surface host mapping is a minor surface. | `v2.3` | It adds first-class multi-host surface bindings, reusable workflow URL outputs, per-surface deployment overrides, and an agent-readable fixture contract. |
 
 ## Runner Policy
 

package/docs/web-surface-deployments.md

@@ -61,6 +61,72 @@ artifact_path = "dist"
 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.
+
+Declare named surfaces with per-channel URLs:
+
+```toml
+[surfaces.hub]
+path = "/"
+production_url = "https://libkungfu.dev"
+staging_url = "https://staging.libkungfu.dev"
+preview_url_pattern = "https://{alias}.preview.libkungfu.dev"
+
+[surfaces.core]
+path = "/core/"
+production_url = "https://core.libkungfu.dev"
+staging_url = "https://core.staging.libkungfu.dev"
+preview_url_pattern = "https://core-{alias}.preview.libkungfu.dev"
+
+[surfaces.buildchain]
+path = "/buildchain/"
+production_url = "https://buildchain.libkungfu.dev"
+staging_url = "https://buildchain.staging.libkungfu.dev"
+preview_url_pattern = "https://buildchain-{alias}.preview.libkungfu.dev"
+```
+
+Buildchain resolves every `(channel, surface)` pair. A preview alias such as
+`pr-12` becomes:
+
+```text
+hub:        https://pr-12.preview.libkungfu.dev
+core:       https://core-pr-12.preview.libkungfu.dev
+buildchain: https://buildchain-pr-12.preview.libkungfu.dev
+```
+
+When `surfaces` is omitted, Buildchain preserves the legacy single-surface
+contract by creating an implicit `default` surface from the channel URL. When a
+surface is intentionally path-only, declare it explicitly:
+
+```toml
+[surfaces.docs]
+path = "/docs/"
+path_only = true
+```
+
+`path_only = true` is an exception, not the default. Without it, every named
+surface must declare `preview_url_pattern`, `staging_url`, and
+`production_url`. This makes staging/production mismatches fail during
+validation instead of becoming invisible deploy drift.
+
+Adapter strategy remains explicit. The default `aws-s3-cloudfront` plan uses the
+channel deploy target for every surface, and each binding records its own
+bucket, distribution id, object prefix, manifest key, source path, and URL. A
+channel can override target details per surface:
+
+```toml
+[deploy.staging.surfaces.core]
+bucket = "libkungfu-dev-core-staging"
+cloudfront_distribution = "E-CORE-STAGING"
+origin_path = "/core"
+```
+
 Buildchain validates these hard constraints:
 
 - `channels.preview.url_pattern` is required and must contain the alias shape
@@ -73,6 +139,8 @@ Buildchain validates these hard constraints:
 - `channels.staging.noindex = true` is required.
 - `channels.production.url` is required.
 - deploy adapters must be declared per channel.
+- named surfaces must declare first-class URLs for every channel unless
+  `path_only = true` is explicitly set.
 - secret material must be declared as reference names, such as
   `secret_refs = ["AWS_ROLE_ARN"]`; inline secret-like deploy keys are rejected.
 
@@ -116,13 +184,13 @@ rollback:
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-web-surface-deployment",
-  "site": "kungfu-tech",
+  "site": "libkungfu-dev",
   "channel": "preview",
   "alias": "sha-abcdef123456",
-  "url": "https://sha-abcdef123456.preview.kungfu.tech",
+  "url": "https://sha-abcdef123456.preview.libkungfu.dev",
   "sourceSha": "...",
   "artifactHash": "...",
-  "deployTarget": "kungfu-tech-preview",
+  "deployTarget": "libkungfu-dev-preview",
   "adapter": "aws-s3-cloudfront",
   "deployedAt": "2026-07-01T00:00:00.000Z",
   "retentionClass": "preview-sha-immutable",
@@ -130,7 +198,24 @@ rollback:
   "accessControl": "none",
   "edgeAuth": "none",
   "noindex": true,
-  "secretRefs": ["AWS_ROLE_ARN"]
+  "secretRefs": ["AWS_ROLE_ARN"],
+  "surfaceBindings": [
+    {
+      "surface": "hub",
+      "channel": "preview",
+      "alias": "sha-abcdef123456",
+      "url": "https://sha-abcdef123456.preview.libkungfu.dev",
+      "sourcePath": "/",
+      "canonicalUrl": "https://libkungfu.dev",
+      "bucket": "libkungfu-dev-preview",
+      "distributionId": "E-PREVIEW",
+      "originPath": "",
+      "objectPrefix": "sha-abcdef123456",
+      "manifestKey": ".buildchain/deployments/sha-abcdef123456/hub.json",
+      "noindex": true,
+      "accessControl": "none"
+    }
+  ]
 }
 ```
 
@@ -169,6 +254,7 @@ The CLI emits GitHub outputs when `GITHUB_OUTPUT` is present:
 - `web-surface-channel`
 - `web-surface-alias`
 - `web-surface-url`
+- `web-surface-urls-json`
 - `web-surface-artifact-hash`
 - `web-surface-manifest-json`
 
@@ -231,13 +317,13 @@ node scripts/web-surface.mjs \
 ```
 
 Apply output records the channel, alias, source SHA, artifact hash, target
-bucket, object prefix, manifest key, CDN invalidation paths, actor/run metadata,
-and every adapter operation with `executed`, `exitCode`, `stdout`, and `stderr`.
-If an operation fails, Buildchain records the failed operation, stops subsequent
-adapter operations, 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`.
+bucket, object prefix, manifest key, all surface URLs, all surface bindings, CDN
+invalidation paths, actor/run metadata, and every adapter operation with
+`executed`, `exitCode`, `stdout`, and `stderr`. If an operation fails,
+Buildchain records the failed operation, stops subsequent adapter operations,
+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`.
 
 ## Cleanup Plans
 

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

@@ -4,6 +4,20 @@ This fixture models a static site repository that wants Buildchain deployment
 semantics without opting into package release lines.
 
 It proves that `project.type = "web-surface"` can declare preview, staging, and
-production channels, generate deterministic deployment manifests, and create
-dry-run deploy and cleanup plans without touching AWS.
+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
+first-class surfaces:
+
+```text
+hub        https://libkungfu.dev
+core       https://core.libkungfu.dev
+buildchain https://buildchain.libkungfu.dev
+```
+
+For preview and staging, Buildchain resolves the same surface names to the
+channel-specific hosts and records them in `surfaceBindings`. Path-only pages
+can still be declared with `path_only = true`, but this fixture intentionally
+uses first-class hosts for every surface so validation can catch missing
+channel mappings.

package/package.json

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

package/packages/core/buildchain-config.js

@@ -116,6 +116,9 @@ export function normalizeBuildchainConfig(config) {
   if (normalized.deploy !== undefined) {
     normalized.deploy = normalizeDeploySection(normalized.deploy, normalized.project);
   }
+  if (normalized.surfaces !== undefined) {
+    normalized.surfaces = normalizeSurfacesSection(normalized.surfaces);
+  }
   if (normalized.retention !== undefined) {
     normalized.retention = normalizeRetentionSection(normalized.retention);
   }
@@ -291,20 +294,113 @@ function normalizeDeployConfig(name, config) {
       ? undefined
       : posixPath(assertString(config.artifact_path, `deploy.${name}.artifact_path`)),
     secretRefs: normalizeStringArray(config.secret_refs, `deploy.${name}.secret_refs`),
+    surfaces: config.surfaces === undefined
+      ? undefined
+      : normalizeDeploySurfaceOverrides(name, config.surfaces),
+  };
+  delete normalized.artifact_path;
+  delete normalized.secret_refs;
+  if (normalized.surfaces === undefined) {
+    delete normalized.surfaces;
+  }
+  assertNoInlineSecretValues(config, `deploy.${name}`, new Set(["secret_refs", "surfaces"]));
+  return normalized;
+}
+
+function normalizeDeploySurfaceOverrides(channelName, surfaces) {
+  assertPlainObject(surfaces, `deploy.${channelName}.surfaces`);
+  return Object.fromEntries(
+    Object.entries(surfaces).map(([surfaceName, override]) => [
+      surfaceName,
+      normalizeDeploySurfaceOverride(channelName, surfaceName, override),
+    ]),
+  );
+}
+
+function normalizeDeploySurfaceOverride(channelName, surfaceName, override) {
+  assertPlainObject(override, `deploy.${channelName}.surfaces.${surfaceName}`);
+  const label = `deploy.${channelName}.surfaces.${surfaceName}`;
+  const normalized = {
+    ...override,
+    artifactPath: override.artifact_path === undefined
+      ? undefined
+      : posixPath(assertString(override.artifact_path, `${label}.artifact_path`)),
+    originPath: override.origin_path === undefined
+      ? undefined
+      : assertString(override.origin_path, `${label}.origin_path`),
+    secretRefs: normalizeStringArray(override.secret_refs, `${label}.secret_refs`),
   };
   delete normalized.artifact_path;
+  delete normalized.origin_path;
   delete normalized.secret_refs;
+  if (normalized.artifactPath === undefined) {
+    delete normalized.artifactPath;
+  }
+  if (normalized.originPath === undefined) {
+    delete normalized.originPath;
+  }
+  if (normalized.secretRefs.length === 0) {
+    delete normalized.secretRefs;
+  }
+  assertNoInlineSecretValues(override, label, new Set(["secret_refs"]));
+  return normalized;
+}
+
+function assertNoInlineSecretValues(config, label, ignoredKeys = new Set()) {
   for (const [key, value] of Object.entries(config)) {
-    if (key === "secret_refs" || key.endsWith("_ref") || key.endsWith("_refs")) {
+    if (ignoredKeys.has(key) || key.endsWith("_ref") || key.endsWith("_refs")) {
       continue;
     }
     if (/(secret|token|password)/i.test(key) && value !== undefined) {
-      throw new Error(`deploy.${name}.${key} must be declared as a secret reference, not a secret value`);
+      throw new Error(`${label}.${key} must be declared as a secret reference, not a secret value`);
     }
   }
+}
+
+function normalizeSurfacesSection(surfaces) {
+  assertPlainObject(surfaces, "surfaces");
+  const entries = Object.entries(surfaces);
+  if (entries.length === 0) {
+    throw new Error("surfaces must declare at least one surface");
+  }
+  return Object.fromEntries(
+    entries.map(([name, surface]) => [
+      name,
+      normalizeSurfaceConfig(name, surface),
+    ]),
+  );
+}
+
+function normalizeSurfaceConfig(name, surface) {
+  assertPlainObject(surface, `surfaces.${name}`);
+  const normalized = {
+    name,
+    path: surface.path === undefined
+      ? "/"
+      : normalizeSurfacePath(assertString(surface.path, `surfaces.${name}.path`)),
+    pathOnly: optionalBoolean(surface.path_only, false),
+    canonical: optionalBoolean(surface.canonical, name === "default" || name === "hub"),
+  };
+  if (surface.preview_url_pattern !== undefined) {
+    normalized.previewUrlPattern = assertString(surface.preview_url_pattern, `surfaces.${name}.preview_url_pattern`);
+  }
+  if (surface.staging_url !== undefined) {
+    normalized.stagingUrl = assertString(surface.staging_url, `surfaces.${name}.staging_url`);
+  }
+  if (surface.production_url !== undefined) {
+    normalized.productionUrl = assertString(surface.production_url, `surfaces.${name}.production_url`);
+  }
   return normalized;
 }
 
+function normalizeSurfacePath(value) {
+  const normalized = `/${String(value).replace(/^\/+/, "")}`.replace(/\/{2,}/g, "/");
+  if (normalized === "/") {
+    return normalized;
+  }
+  return normalized.endsWith("/") ? normalized : `${normalized}/`;
+}
+
 function normalizeRetentionSection(retention) {
   assertPlainObject(retention, "retention");
   return Object.fromEntries(
@@ -390,6 +486,25 @@ function validateWebSurfaceConfig(config) {
       throw new Error("security.staging.isolated_providers must not be false for web-surface");
     }
   }
+  validateWebSurfaceSurfaces(config);
+}
+
+function validateWebSurfaceSurfaces(config) {
+  const surfaces = config.surfaces || {};
+  for (const [name, surface] of Object.entries(surfaces)) {
+    if (!surface.pathOnly && !surface.previewUrlPattern) {
+      throw new Error(`surfaces.${name}.preview_url_pattern is required unless path_only = true`);
+    }
+    if (!surface.pathOnly && !surface.stagingUrl) {
+      throw new Error(`surfaces.${name}.staging_url is required unless path_only = true`);
+    }
+    if (!surface.pathOnly && !surface.productionUrl) {
+      throw new Error(`surfaces.${name}.production_url is required unless path_only = true`);
+    }
+    if (surface.productionUrl && !surface.pathOnly && !surface.stagingUrl) {
+      throw new Error(`surfaces.${name}.staging_url is required when production_url declares a first-class host`);
+    }
+  }
 }
 
 function normalizeVersionSection(version) {
@@ -734,6 +849,21 @@ export function validateBuildchainConfig(
           ]),
         )
       : undefined,
+    surfaces: loadedConfig.config.surfaces
+      ? Object.fromEntries(
+          Object.entries(loadedConfig.config.surfaces).map(([name, surface]) => [
+            name,
+            {
+              path: surface.path,
+              pathOnly: surface.pathOnly,
+              canonical: surface.canonical,
+              previewUrlPattern: surface.previewUrlPattern,
+              stagingUrl: surface.stagingUrl,
+              productionUrl: surface.productionUrl,
+            },
+          ]),
+        )
+      : undefined,
     retention: loadedConfig.config.retention,
     security: loadedConfig.config.security,
     version: loadedConfig.config.version

package/scripts/web-surface-core.mjs

@@ -117,6 +117,38 @@ function resolveChannelUrl(channel, alias) {
   return channel.url;
 }
 
+function resolvePathOnlyUrl(channel, sourcePath, alias) {
+  const base = resolveChannelUrl(channel, alias);
+  const url = new URL(base);
+  const normalizedPath = normalizeSurfacePath(sourcePath);
+  if (normalizedPath === "/") {
+    return `${url.origin}/`;
+  }
+  return new URL(normalizedPath.replace(/^\//, ""), `${url.origin}/`).toString();
+}
+
+function resolveSurfaceUrl({ surface, channel, channelName, alias }) {
+  if (channelName === "preview" && surface.previewUrlPattern) {
+    if (!alias) {
+      throw new Error(`surface ${surface.name} requires alias for preview_url_pattern`);
+    }
+    return surface.previewUrlPattern.replaceAll("{alias}", alias);
+  }
+  if (channelName === "staging" && surface.stagingUrl) {
+    return surface.stagingUrl;
+  }
+  if (channelName === "production" && surface.productionUrl) {
+    return surface.productionUrl;
+  }
+  if (surface.pathOnly) {
+    return resolvePathOnlyUrl(channel, surface.path, alias);
+  }
+  const key = channelName === "preview"
+    ? "preview_url_pattern"
+    : `${channelName}_url`;
+  throw new Error(`surfaces.${surface.name}.${key} is required for channel ${channelName}`);
+}
+
 function manifestPrefixFor(deployConfig) {
   return deployConfig.manifest_prefix || ".buildchain/deployments";
 }
@@ -128,10 +160,51 @@ function objectPrefixFor(deployConfig, alias) {
   return alias || "preview";
 }
 
+function normalizeSurfacePath(value) {
+  const normalized = `/${String(value || "/").replace(/^\/+/, "")}`.replace(/\/{2,}/g, "/");
+  if (normalized === "/") {
+    return normalized;
+  }
+  return normalized.endsWith("/") ? normalized : `${normalized}/`;
+}
+
+function surfaceDeployConfig(deployConfig, surfaceName) {
+  const overrides = deployConfig.surfaces?.[surfaceName];
+  if (!overrides || typeof overrides !== "object" || Array.isArray(overrides)) {
+    return deployConfig;
+  }
+  return {
+    ...deployConfig,
+    ...overrides,
+    surfaces: deployConfig.surfaces,
+    secretRefs: [
+      ...new Set([
+        ...(deployConfig.secretRefs || []),
+        ...(Array.isArray(overrides.secretRefs) ? overrides.secretRefs : []),
+      ]),
+    ],
+    artifactPath: overrides.artifactPath || deployConfig.artifactPath,
+  };
+}
+
+function surfaceObjectPrefixFor({ deployConfig, surface, alias }) {
+  const effective = surfaceDeployConfig(deployConfig, surface.name);
+  if (Object.hasOwn(effective, "prefix")) {
+    return normalizeS3Key(effective.prefix);
+  }
+  const root = objectPrefixFor(deployConfig, alias);
+  const surfacePath = normalizeS3Key(surface.path);
+  if (!surfacePath) {
+    return root;
+  }
+  return joinS3Key(root, surfacePath);
+}
+
 function normalizeS3Key(value) {
   return String(value || "")
     .replace(/^\/+/, "")
-    .replace(/\/{2,}/g, "/");
+    .replace(/\/{2,}/g, "/")
+    .replace(/\/+$/, "");
 }
 
 function joinS3Key(...parts) {
@@ -268,6 +341,13 @@ function deployManifestKey(deployConfig, manifest) {
   return joinS3Key(manifestPrefixFor(deployConfig), `${manifest.alias || manifest.channel}.json`);
 }
 
+function deploySurfaceManifestKey(deployConfig, binding) {
+  const suffix = binding.surface === "default"
+    ? `${binding.alias || binding.channel}.json`
+    : `${binding.alias || binding.channel}/${binding.surface}.json`;
+  return joinS3Key(manifestPrefixFor(deployConfig), suffix);
+}
+
 function assertDeployPlan(plan) {
   if (plan?.contract !== "kungfu-buildchain-web-surface-deploy-plan") {
     throw new Error("web-surface deploy apply requires a deploy plan");
@@ -345,6 +425,55 @@ function retentionFor({ config, channelName, alias, deployedAt }) {
   };
 }
 
+function configuredSurfaces(config) {
+  if (config.surfaces && Object.keys(config.surfaces).length > 0) {
+    return Object.values(config.surfaces);
+  }
+  return [{
+    name: "default",
+    path: "/",
+    pathOnly: false,
+    canonical: true,
+  }];
+}
+
+function resolveSurfaceBindings({ config, channelName, alias, deployConfig }) {
+  const channel = config.channels?.[channelName];
+  if (!channel) {
+    throw new Error(`unknown web-surface channel: ${channelName}`);
+  }
+  return configuredSurfaces(config).map((surface) => {
+    const effectiveDeploy = surfaceDeployConfig(deployConfig, surface.name);
+    const url = surface.name === "default" && !config.surfaces
+      ? resolveChannelUrl(channel, alias)
+      : resolveSurfaceUrl({ surface, channel, channelName, alias });
+    const objectPrefix = surface.name === "default" && !config.surfaces
+      ? objectPrefixFor(deployConfig, alias || channelName)
+      : surfaceObjectPrefixFor({ deployConfig, surface, alias: alias || channelName });
+    const bucket = effectiveDeploy.bucket || effectiveDeploy.target || "";
+    const distributionId = effectiveDeploy.cloudfront_distribution || effectiveDeploy.distribution || "";
+    return {
+      surface: surface.name,
+      channel: channelName,
+      alias,
+      url,
+      sourcePath: normalizeSurfacePath(surface.path),
+      canonicalUrl: surface.productionUrl || (channelName === "production" ? url : ""),
+      pathOnly: Boolean(surface.pathOnly),
+      bucket,
+      distributionId,
+      originPath: effectiveDeploy.origin_path || effectiveDeploy.originPath || "",
+      objectPrefix,
+      manifestKey: "",
+      noindex: channel.noindex,
+      accessControl: channel.accessControl,
+    };
+  }).map((binding) => ({
+    ...binding,
+    manifestKey: deploySurfaceManifestKey(deployConfig, binding),
+  }));
+}
+
 export function validateWebSurfaceProject(cwd = process.cwd()) {
   const summary = validateBuildchainConfig(cwd, {
     requireConfig: true,
@@ -404,13 +533,20 @@ export function createWebSurfaceDeploymentManifest({
     throw new Error(`missing deploy.${channel}`);
   }
   const retention = retentionFor({ config, channelName: channel, alias, deployedAt });
+  const surfaceBindings = resolveSurfaceBindings({
+    config,
+    channelName: channel,
+    alias,
+    deployConfig,
+  });
+  const primaryBinding = surfaceBindings[0];
   return {
     schemaVersion: 1,
     contract: "kungfu-buildchain-web-surface-deployment",
     site: config.project.site || config.project.name || "",
     channel,
     alias,
-    url: resolveChannelUrl(channelConfig, alias),
+    url: primaryBinding.url,
     sourceSha: assertSha(sourceSha, "sourceSha"),
     artifactHash: assertHash(artifactHash, "artifactHash"),
     deployTarget: deployConfig.target || deployConfig.bucket || deployConfig.environment || deployConfig.service || "",
@@ -437,6 +573,7 @@ export function createWebSurfaceDeploymentManifest({
     migrationState,
     rollbackPointer,
     rollbackLimitations,
+    surfaceBindings,
   };
 }
 
@@ -481,12 +618,14 @@ export function planWebSurfaceDeploy({
     channel,
     alias,
     url: manifest.url,
+    urls: Object.fromEntries(manifest.surfaceBindings.map((binding) => [binding.surface, binding.url])),
     artifact: {
       path: artifactPath || deployConfig.artifactPath || ".",
       hash: resolvedArtifact.artifactHash,
       files: resolvedArtifact.files,
     },
     manifest,
+    surfaceBindings: manifest.surfaceBindings,
     steps: planAdapterSteps(deployConfig.adapter, deployConfig, manifest),
   };
 }
@@ -526,39 +665,28 @@ export function applyWebSurfaceDeploy({
   if (resolvedPlan.adapter !== "aws-s3-cloudfront") {
     throw new Error(`web-surface deploy apply does not support adapter: ${resolvedPlan.adapter}`);
   }
-  if (!dryRun) {
-    assertConcreteAwsDeployConfig({
-      deployConfig,
-      channel: resolvedPlan.channel,
-      operation: "deploy",
-    });
-  }
   const bucket = deployConfig.bucket || deployConfig.target || "";
   const artifactRoot = path.resolve(cwd, resolvedPlan.artifact.path);
-  const objectPrefix = objectPrefixFor(deployConfig, resolvedPlan.manifest.alias || resolvedPlan.manifest.channel);
-  const manifestKey = deployManifestKey(deployConfig, resolvedPlan.manifest);
-  const invalidationPaths = [cdnWildcardPath(objectPrefix), cdnPath(manifestKey)];
-  const operations = [
-    {
-      action: "sync-static-artifact",
-      command: "aws",
-      args: syncStaticArtifactArgs({ artifactRoot, bucket, objectPrefix }),
-    },
-    {
-      action: "write-deployment-manifest",
-      command: "aws",
-      args: ["s3", "cp", "-", s3Uri(bucket, manifestKey), "--content-type", "application/json"],
-      stdin: `${JSON.stringify(resolvedPlan.manifest, null, 2)}\n`,
-    },
-  ];
-  const distribution = deployConfig.cloudfront_distribution || deployConfig.distribution || "";
-  if (distribution) {
-    operations.push({
-      action: "invalidate-cdn",
-      command: "aws",
-      args: ["cloudfront", "create-invalidation", "--distribution-id", distribution, "--paths", ...invalidationPaths],
-    });
+  const bindings = resolvedPlan.manifest.surfaceBindings || [];
+  if (!dryRun) {
+    for (const binding of bindings) {
+      assertConcreteAwsDeployConfig({
+        deployConfig: surfaceDeployConfig(deployConfig, binding.surface),
+        channel: `${resolvedPlan.channel}.surfaces.${binding.surface}`,
+        operation: "deploy",
+      });
+    }
   }
+  const operations = bindings.flatMap((binding) => deployBindingOperations({
+    artifactRoot,
+    deployConfig,
+    manifest: resolvedPlan.manifest,
+    binding,
+  }));
+  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 operationResults = runAdapterOperations({ operations, dryRun, commandRunner });
   return {
     schemaVersion: 1,
@@ -572,6 +700,7 @@ export function applyWebSurfaceDeploy({
     channel: resolvedPlan.channel,
     alias: resolvedPlan.alias,
     url: resolvedPlan.url,
+    urls: resolvedPlan.urls || Object.fromEntries(bindings.map((binding) => [binding.surface, binding.url])),
     sourceSha: resolvedPlan.manifest.sourceSha,
     artifactHash: resolvedPlan.artifact.hash,
     adapter: resolvedPlan.adapter,
@@ -580,26 +709,76 @@ export function applyWebSurfaceDeploy({
     manifestKey,
     invalidationPaths,
     manifest: resolvedPlan.manifest,
+    surfaceBindings: bindings,
     operations: operationResults,
   };
 }
 
+function deployBindingOperations({ artifactRoot, deployConfig, manifest, binding }) {
+  const effectiveDeploy = surfaceDeployConfig(deployConfig, binding.surface);
+  const bucket = binding.bucket || effectiveDeploy.bucket || effectiveDeploy.target || "";
+  const distribution = binding.distributionId || effectiveDeploy.cloudfront_distribution || effectiveDeploy.distribution || "";
+  const operations = [
+    {
+      action: "sync-static-artifact",
+      surface: binding.surface,
+      command: "aws",
+      args: syncStaticArtifactArgs({ artifactRoot, bucket, objectPrefix: binding.objectPrefix }),
+    },
+    {
+      action: "write-deployment-manifest",
+      surface: binding.surface,
+      command: "aws",
+      args: ["s3", "cp", "-", s3Uri(bucket, binding.manifestKey), "--content-type", "application/json"],
+      stdin: `${JSON.stringify({
+        ...manifest,
+        surface: binding.surface,
+        url: binding.url,
+        surfaceBinding: binding,
+      }, null, 2)}\n`,
+    },
+  ];
+  if (distribution) {
+    operations.push({
+      action: "invalidate-cdn",
+      surface: binding.surface,
+      command: "aws",
+      args: [
+        "cloudfront",
+        "create-invalidation",
+        "--distribution-id",
+        distribution,
+        "--paths",
+        cdnWildcardPath(binding.objectPrefix),
+        cdnPath(binding.manifestKey),
+      ],
+    });
+  }
+  return operations;
+}
+
 function planAdapterSteps(adapter, deployConfig, manifest) {
   if (adapter === "aws-s3-cloudfront") {
     return [
-      {
-        action: "sync-static-artifact",
-        target: deployConfig.bucket || deployConfig.target || "",
-        prefix: objectPrefixFor(deployConfig, manifest.alias || manifest.channel),
-      },
-      {
-        action: "write-deployment-manifest",
-        target: manifestPrefixFor(deployConfig),
-      },
-      {
-        action: "invalidate-cdn",
-        distribution: deployConfig.cloudfront_distribution || deployConfig.distribution || "",
-      },
+      ...manifest.surfaceBindings.flatMap((binding) => [
+        {
+          action: "sync-static-artifact",
+          surface: binding.surface,
+          target: binding.bucket,
+          prefix: binding.objectPrefix,
+        },
+        {
+          action: "write-deployment-manifest",
+          surface: binding.surface,
+          target: manifestPrefixFor(deployConfig),
+          key: binding.manifestKey,
+        },
+        {
+          action: "invalidate-cdn",
+          surface: binding.surface,
+          distribution: binding.distributionId,
+        },
+      ]),
     ];
   }
   return [
@@ -640,6 +819,10 @@ export function planWebSurfaceCleanup({
     requestedAliases.push(`pr-${pullNumber}`);
   }
   const manifestPrefix = manifestPrefixFor(deployConfig);
+  const bindingsByAlias = new Map(requestedAliases.map((alias) => [
+    alias,
+    resolveSurfaceBindings({ config, channelName: channel, alias, deployConfig }),
+  ]));
   return {
     schemaVersion: 1,
     contract: "kungfu-buildchain-web-surface-cleanup-plan",
@@ -660,7 +843,9 @@ export function planWebSurfaceCleanup({
     entries: requestedAliases.map((alias) => {
       const classified = classifyPreviewAlias(alias);
       const retention = retentionConfig(config, "preview");
-      const objectPrefix = objectPrefixFor(deployConfig, alias);
+      const surfaceBindings = bindingsByAlias.get(alias) || [];
+      const primaryBinding = surfaceBindings[0] || {};
+      const objectPrefix = primaryBinding.objectPrefix || objectPrefixFor(deployConfig, alias);
       return {
         alias,
         aliasKind: classified.kind,
@@ -669,11 +854,13 @@ export function planWebSurfaceCleanup({
         retentionDays: retention[classified.retentionKey],
         action: "delete-preview-alias",
         objectPrefix,
-        manifestKey: `${manifestPrefix.replace(/\/$/, "")}/${alias}.json`,
+        manifestKey: primaryBinding.manifestKey || `${manifestPrefix.replace(/\/$/, "")}/${alias}.json`,
+        surfaceBindings,
         steps: cleanupAdapterSteps(deployConfig.adapter, deployConfig, {
           alias,
           objectPrefix,
           manifestPrefix,
+          surfaceBindings,
         }),
       };
     }),
@@ -718,33 +905,80 @@ export function applyWebSurfaceCleanup({
     throw new Error(`web-surface cleanup apply does not support adapter: ${cleanup.adapter}`);
   }
   if (!dryRun) {
-    assertConcreteAwsDeployConfig({
-      deployConfig,
-      channel: cleanup.channel,
-      operation: "cleanup",
-    });
+    for (const entry of cleanup.entries) {
+      const bindings = entry.surfaceBindings?.length
+        ? entry.surfaceBindings
+        : [{
+            surface: "default",
+          }];
+      for (const binding of bindings) {
+        assertConcreteAwsDeployConfig({
+          deployConfig: surfaceDeployConfig(deployConfig, binding.surface),
+          channel: `${cleanup.channel}.surfaces.${binding.surface}`,
+          operation: "cleanup",
+        });
+      }
+    }
   }
   const bucket = deployConfig.bucket || deployConfig.target || "";
-  const operations = cleanup.entries.flatMap((entry) => {
+  const operations = cleanup.entries.flatMap((entry) => cleanupEntryOperations({ deployConfig, entry, bucket }));
+  const operationResults = runAdapterOperations({ operations, dryRun, commandRunner });
+  return {
+    schemaVersion: 1,
+    contract: "kungfu-buildchain-web-surface-cleanup-apply",
+    dryRun,
+    applyMode: dryRun ? "dry-run" : "apply",
+    status: appliedStatus({ dryRun, operations: operationResults, noOp: cleanup.status === "no-op" }),
+    event,
+    channel,
+    now,
+    sourceSha: cleanup.sourceSha,
+    pullNumber: cleanup.pullNumber,
+    actor,
+    runId,
+    adapter: cleanup.adapter,
+    target: bucket,
+    manifestPrefix: cleanup.manifestPrefix,
+    entries: cleanup.entries,
+    operations: operationResults,
+  };
+}
+
+function cleanupEntryOperations({ deployConfig, entry, bucket }) {
+  const bindings = entry.surfaceBindings?.length
+    ? entry.surfaceBindings
+    : [{
+        surface: "default",
+        objectPrefix: entry.objectPrefix,
+        manifestKey: entry.manifestKey,
+        bucket,
+        distributionId: deployConfig.cloudfront_distribution || deployConfig.distribution || "",
+      }];
+  return bindings.flatMap((binding) => {
+    const effectiveDeploy = surfaceDeployConfig(deployConfig, binding.surface);
+    const bindingBucket = binding.bucket || effectiveDeploy.bucket || effectiveDeploy.target || bucket;
+    const distribution = binding.distributionId || effectiveDeploy.cloudfront_distribution || effectiveDeploy.distribution || "";
     const entryOperations = [
       {
         action: "delete-static-prefix",
         alias: entry.alias,
+        surface: binding.surface,
         command: "aws",
-        args: ["s3", "rm", s3Uri(bucket, entry.objectPrefix), "--recursive"],
+        args: ["s3", "rm", s3Uri(bindingBucket, binding.objectPrefix), "--recursive"],
       },
       {
         action: "delete-deployment-manifest",
         alias: entry.alias,
+        surface: binding.surface,
         command: "aws",
-        args: ["s3", "rm", s3Uri(bucket, entry.manifestKey)],
+        args: ["s3", "rm", s3Uri(bindingBucket, binding.manifestKey)],
       },
     ];
-    const distribution = deployConfig.cloudfront_distribution || deployConfig.distribution || "";
     if (distribution) {
       entryOperations.push({
         action: "invalidate-cdn",
         alias: entry.alias,
+        surface: binding.surface,
         command: "aws",
         args: [
           "cloudfront",
@@ -752,53 +986,45 @@ export function applyWebSurfaceCleanup({
           "--distribution-id",
           distribution,
           "--paths",
-          `${cdnPath(entry.objectPrefix)}/*`,
-          cdnPath(entry.manifestKey),
+          `${cdnPath(binding.objectPrefix)}/*`,
+          cdnPath(binding.manifestKey),
         ],
       });
     }
     return entryOperations;
   });
-  const operationResults = runAdapterOperations({ operations, dryRun, commandRunner });
-  return {
-    schemaVersion: 1,
-    contract: "kungfu-buildchain-web-surface-cleanup-apply",
-    dryRun,
-    applyMode: dryRun ? "dry-run" : "apply",
-    status: appliedStatus({ dryRun, operations: operationResults, noOp: cleanup.status === "no-op" }),
-    event,
-    channel,
-    now,
-    sourceSha: cleanup.sourceSha,
-    pullNumber: cleanup.pullNumber,
-    actor,
-    runId,
-    adapter: cleanup.adapter,
-    target: bucket,
-    manifestPrefix: cleanup.manifestPrefix,
-    entries: cleanup.entries,
-    operations: operationResults,
-  };
 }
 
 function cleanupAdapterSteps(adapter, deployConfig, entry) {
   if (adapter === "aws-s3-cloudfront") {
-    return [
-      {
-        action: "delete-static-prefix",
-        target: deployConfig.bucket || deployConfig.target || "",
-        prefix: entry.objectPrefix,
-      },
-      {
-        action: "delete-deployment-manifest",
-        target: entry.manifestPrefix,
-        key: `${entry.manifestPrefix.replace(/\/$/, "")}/${entry.alias}.json`,
-      },
-      {
-        action: "invalidate-cdn",
-        distribution: deployConfig.cloudfront_distribution || deployConfig.distribution || "",
-      },
-    ];
+    const bindings = entry.surfaceBindings?.length
+      ? entry.surfaceBindings
+      : [{
+          surface: "default",
+          objectPrefix: entry.objectPrefix,
+          manifestKey: `${entry.manifestPrefix.replace(/\/$/, "")}/${entry.alias}.json`,
+          bucket: deployConfig.bucket || deployConfig.target || "",
+          distributionId: deployConfig.cloudfront_distribution || deployConfig.distribution || "",
+        }];
+    return bindings.flatMap((binding) => [
+        {
+          action: "delete-static-prefix",
+          surface: binding.surface,
+          target: binding.bucket,
+          prefix: binding.objectPrefix,
+        },
+        {
+          action: "delete-deployment-manifest",
+          surface: binding.surface,
+          target: entry.manifestPrefix,
+          key: binding.manifestKey,
+        },
+        {
+          action: "invalidate-cdn",
+          surface: binding.surface,
+          distribution: binding.distributionId,
+        },
+      ]);
   }
   return [
     {

package/scripts/web-surface.mjs

@@ -90,6 +90,7 @@ export function webSurfaceCli() {
       "web-surface-channel": result.channel,
       "web-surface-alias": result.alias,
       "web-surface-url": result.url,
+      "web-surface-urls-json": JSON.stringify(result.urls || {}),
       "web-surface-artifact-hash": result.artifact.hash,
       "web-surface-manifest-json": JSON.stringify(result.manifest),
     });
@@ -121,10 +122,12 @@ export function webSurfaceCli() {
       "web-surface-channel": result.channel,
       "web-surface-alias": result.alias,
       "web-surface-url": result.url,
+      "web-surface-urls-json": JSON.stringify(result.urls || {}),
       "web-surface-artifact-hash": result.artifactHash,
       "web-surface-apply-mode": result.applyMode,
       "web-surface-apply-status": result.status,
       "web-surface-manifest-json": JSON.stringify(result.manifest),
+      "web-surface-bindings-json": JSON.stringify(result.surfaceBindings || []),
       "web-surface-apply-result-json": JSON.stringify(result),
     });
     assertApplySucceeded(result);