@kungfu-tech/buildchain 2.8.8-alpha.5 → 2.8.8-alpha.7

package/dist/site/release-provenance.json

@@ -19,6 +19,7 @@
       "./release-candidate": "./packages/core/release-candidate.js",
       "./release-passport": "./packages/core/release-passport.js",
       "./release-propagation": "./packages/core/release-propagation.js",
+      "./surface-manifest": "./packages/core/surface-manifest.js",
       "./buildchain-kfd-claims": "./packages/core/buildchain-kfd-claims.js",
       "./site/buildchain-site.json": "./dist/site/buildchain-site.json",
       "./site/site-manifest.json": "./dist/site/site-manifest.json",

package/dist/site/site-manifest.json

@@ -1,6 +1,35 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-site-manifest",
+  "generatedAt": "2026-07-07T05:58:59.518Z",
+  "publishedAt": "2026-07-07T05:58:59.518Z",
+  "reproducible": true,
+  "timestampPolicy": "ci-injected",
+  "deterministicInputs": [
+    "README.md",
+    "docs/*.md",
+    "actions/*/README.md",
+    "fixtures/*/README.md",
+    "packages/core/README.md",
+    "package.json#exports",
+    "tests/buildchain-inventory.json",
+    "sourceRevision",
+    "sourceDateEpoch",
+    "package content",
+    "declared Buildchain surface manifest contract"
+  ],
+  "sourceDateEpoch": "0",
+  "sourceRevision": "5fdcc9bfde15861e9fd12a29f880bcd3ffc8d719",
+  "timestampPolicyDetails": {
+    "contract": "kungfu-buildchain-surface-timestamp-policy",
+    "timestampFields": [
+      "generatedAt",
+      "publishedAt"
+    ],
+    "timestampFieldsParticipateInArtifactDigest": true,
+    "artifactDigestScope": "npm package dist/site JSON files",
+    "note": "Human-readable timestamps are separate from reproducibility inputs; do not infer reproducibility from epoch timestamps."
+  },
   "product": {
     "name": "Buildchain",
     "formalName": "Buildchain by Kungfu",
@@ -8,6 +37,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
+    "version": "2.8.8-alpha.7",
     "versionSource": "package.json#version"
   },
   "entrypoint": "buildchain-site.json",
@@ -39,7 +69,7 @@
       "path": "docs/release-passport.md",
       "plane": "verify",
       "exists": true,
-      "digest": "sha256:4d69798646adb84c6d193b1f32e7dc50e389db8932e63e9cb71489b6015e0333"
+      "digest": "sha256:56c9000305e9dc23993e6c401568c4063dd496c3586382a44cd44db108a95094"
     },
     {
       "id": "release-propagation",
@@ -87,7 +117,7 @@
       "path": "docs/site-bundle-contract.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:1977091fc18b816208e7af50a177fd15e114498bfa49041573812405b46585aa"
+      "digest": "sha256:466318ea255da5a3c70a260773384341afb91b929135f2253ecd8f4e6dae7f7b"
     },
     {
       "id": "migration-inventory",
@@ -127,7 +157,7 @@
       "path": "docs/lifecycle-protocol.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:ad88ce9f86ccbb7db0225e1baf902f34c7b734b28361d9e616ec3bafb37d906d"
+      "digest": "sha256:43dcaaa53efa8b7e6cdcdaa92a0d39d3ee263b840ed2bfea0a47fe4af922cd59"
     },
     {
       "id": "reusable-build-surface",
@@ -135,7 +165,7 @@
       "path": "docs/reusable-build-surface.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:aae753c7fcf4bcb13c08af7b31cc83d898d36e41248b5f710ecee61035de3e8e"
+      "digest": "sha256:165011e2a932461805925c714c2c1c07f1ee60c4b3a614b6dcdda4b81ec22d68"
     },
     {
       "id": "publish-transaction",
@@ -143,7 +173,7 @@
       "path": "docs/publish-transaction.md",
       "plane": "verify",
       "exists": true,
-      "digest": "sha256:ba45f87893b15c3582a52b3cbecba418f35bf409bc672a0d89842f048788e7f7"
+      "digest": "sha256:94844f7bb38dbd85c02f1bc9d55e34dcebd9fc96585789766e8075ac635bc6c0"
     },
     {
       "id": "release-governance",
@@ -151,7 +181,7 @@
       "path": "docs/release-governance.md",
       "plane": "why",
       "exists": true,
-      "digest": "sha256:85f25aadbadcd8579b3e29204d5ce70dd8831ac3960dfc3d17a547537eb267bd"
+      "digest": "sha256:7fb654a147104125eccbbbcccdeb28c5cad5a6097731e560e72919b9231f985f"
     },
     {
       "id": "release-flow",
@@ -183,7 +213,7 @@
       "path": "docs/web-surface-deployments.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:61891635707e9ed27b8754b83713db61cf9a7a6bdf65beb6a9ac8aa39356e168"
+      "digest": "sha256:5b374e65dc2740748205db597a7cd9779d71daa1b30ad46e542f95b093e56c98"
     }
   ],
   "facts": [

package/docs/lifecycle-protocol.md

@@ -250,10 +250,12 @@ checks, and admin enforcement for human channel changes, but adds the
 authenticated promotion token user or app to the managed bypass allowlist for
 generated release bookkeeping. Buildchain also creates the configured required
 check on the exact generated version-state commit before patching the protected
-ref, so the automated bookkeeping remains compatible with strict required
-checks. If the direct generated update is rejected, promotion fails with a
-token/protection diagnostic instead of asking humans to review a post-publish
-version-state PR.
+ref, then applies the protected ref update with the declared generated ref
+update token. The reusable wrapper uses
+`secrets.BUILDCHAIN_PROMOTION_TOKEN || github.token` for that protected
+bookkeeping update. If the direct generated update is rejected, promotion fails
+with a token/protection diagnostic instead of asking humans to review a
+post-publish version-state PR.
 
 For `version.strategy = "anchored"` with `version.next = "manual"`, release
 promotion does not generate a Buildchain-owned version-state commit. In that

package/docs/publish-transaction.md

@@ -293,7 +293,10 @@ Buildchain-managed promotions must finish generated version-state bookkeeping
 with the promotion token directly; they must not require a post-publish human
 PR. Before patching a protected generated bookkeeping ref, Buildchain emits the
 configured required check on the exact generated version-state commit so strict
-branch protection can validate the automation path without a second build.
+branch protection can validate the automation path without a second build, then
+uses the generated ref update token for the protected ref PATCH. The reusable
+wrapper defaults that token to `secrets.BUILDCHAIN_PROMOTION_TOKEN ||
+github.token`.
 
 If finalization fails after an exact Git tag, a channel branch, or dev/alpha
 sync ref has already moved, the next run reads the durable `finalizing` state

package/docs/release-governance.md

@@ -416,8 +416,11 @@ token's authenticated user or app to the managed bypass allowlist. Before
 patching a protected generated bookkeeping ref, the action creates the
 configured required check on the exact generated version-state commit, so strict
 status checks are satisfied by machine-verifiable Buildchain evidence rather
-than a human PR. If direct generated bookkeeping is still rejected, Buildchain
-fails with a token/protection diagnostic instead of creating a post-publish PR.
+than a human PR. The protected ref PATCH itself uses the generated ref update
+token; the reusable wrapper defaults it to
+`secrets.BUILDCHAIN_PROMOTION_TOKEN || github.token`. If direct generated
+bookkeeping is still rejected, Buildchain fails with a token/protection
+diagnostic instead of creating a post-publish PR.
 Buildchain's own promotion workflow reads `BUILDCHAIN_PROMOTION_BYPASS_APPS`,
 `BUILDCHAIN_PROMOTION_BYPASS_USERS`, and
 `BUILDCHAIN_PROMOTION_BYPASS_TEAMS` repository variables so the declared bypass

package/docs/release-passport.md

@@ -47,6 +47,10 @@ Additive passport sections:
   trusted publishing was enabled.
 - `transaction`: durable Buildchain release transaction id, state, exact tag,
   release SHA, state ref, and state SHA.
+- `surfaceTimestampPolicy`: the common Buildchain surface manifest timestamp
+  policy. It records real CI/release generation and publication times,
+  reproducibility inputs, source revision or source-date-epoch, and whether
+  timestamp fields participate in the release artifact digest.
 - `artifacts`: release assets and registry artifacts in one list, each pointing
   back to the evidence file that proves its digest.
 

package/docs/reusable-build-surface.md

@@ -515,9 +515,13 @@ so the workflow automation can apply generated version-state and channel
 bookkeeping on protected `dev`/`alpha`/`release` branches after the reviewed
 channel PR has merged; consumers using a different promotion identity can pass
 `branch-protection-bypass-users`, `branch-protection-bypass-teams`, or a
-different app slug declaratively. It does not call `.build.yml`, does not create
-a matrix, and must fail before publish if the RC evidence, payload set, or
-source-lock ref is missing or ambiguous.
+different app slug declaratively. The wrapper uses
+`secrets.BUILDCHAIN_PROMOTION_TOKEN || github.token` as the generated ref update
+token for protected bookkeeping PATCH calls, so a bypass-capable promotion token
+can sync dev immediately after alpha/release publish without a post-publish PR.
+It does not call `.build.yml`, does not create a matrix, and must fail before
+publish if the RC evidence, payload set, or source-lock ref is missing or
+ambiguous.
 
 ```yaml
 jobs:

package/docs/site-bundle-contract.md

@@ -52,6 +52,34 @@ from `packages/core/buildchain-kfd-claims.js` and enumerates the public release
 claims plus the KFD-3 collaboration surfaces that Buildchain self-verifies
 during release promotion.
 
+## Timestamp and Reproducibility Policy
+
+Every Buildchain-owned surface manifest uses the same timestamp policy fields:
+
+- `generatedAt`: when the manifest JSON was generated.
+- `publishedAt`: when the surface was published, when known.
+- `reproducible`: whether the manifest declares its reproducibility inputs.
+- `timestampPolicy`: `ci-injected` for release/workflow-generated public
+  artifacts, or `source-date-epoch` for local deterministic source checks.
+- `deterministicInputs`: the source files, revisions, package metadata, and
+  declared Buildchain contracts that determine the manifest bytes.
+- `sourceDateEpoch` / `sourceRevision`: the deterministic time input or source
+  revision used to reproduce the manifest.
+- `timestampPolicyDetails.timestampFieldsParticipateInArtifactDigest`: whether
+  timestamp fields are included in the artifact digest being audited.
+
+The policy is defined by `@kungfu-tech/buildchain/surface-manifest` and applies
+to the root site bundle, `site-manifest.json`, and web-surface deployment
+manifests for named surfaces such as KFD, Buildchain, and Core. Site
+repositories should render these fields; they should not invent their own
+manifest time semantics.
+
+Source checkouts may use `SOURCE_DATE_EPOCH` for deterministic local checks.
+Published CI/release artifacts should inject real timestamps with
+`BUILDCHAIN_SITE_GENERATED_AT` / `BUILDCHAIN_SITE_PUBLISHED_AT` or the matching
+`BUILDCHAIN_SURFACE_*` variables, so public manifests do not expose epoch time
+as if it were a real metadata time.
+
 ## npm Consumption
 
 ```bash

package/docs/web-surface-deployments.md

@@ -195,6 +195,25 @@ rollback:
   "channel": "preview",
   "alias": "sha-abcdef123456",
   "url": "https://sha-abcdef123456.preview.libkungfu.dev",
+  "generatedAt": "2026-07-01T00:00:00.000Z",
+  "publishedAt": "2026-07-01T00:00:00.000Z",
+  "reproducible": true,
+  "timestampPolicy": "ci-injected",
+  "deterministicInputs": [
+    "web-surface artifact content",
+    "buildchain.toml web-surface channels/deploy/surfaces",
+    "sourceSha",
+    "artifactHash",
+    "deployment channel",
+    "deployment alias"
+  ],
+  "sourceRevision": "...",
+  "timestampPolicyDetails": {
+    "contract": "kungfu-buildchain-surface-timestamp-policy",
+    "timestampFields": ["generatedAt", "publishedAt", "deployedAt"],
+    "timestampFieldsParticipateInArtifactDigest": false,
+    "artifactDigestScope": "web-surface artifactHash excludes deployment manifest timestamps"
+  },
   "sourceSha": "...",
   "artifactHash": "...",
   "deployTarget": "libkungfu-dev-preview",
@@ -231,6 +250,13 @@ Dynamic adapters can also fill `runtimeId`, `configFingerprint`,
 `rollbackLimitations`. Buildchain records secret reference names only, never
 secret values.
 
+The timestamp policy is shared with package site bundles. Public deployment
+manifests should expose real workflow generation/publication times while
+separately declaring why the deployed artifact remains reproducible. For
+web-surface deployment manifests, `artifactHash` is the static site artifact
+digest and does not include deployment timestamp fields; the manifest itself
+still records those fields for human and agent audit.
+
 ## Deploy Plans
 
 Deploy planning is the default behavior. It plans the adapter steps and writes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "2.8.8-alpha.5",
+  "version": "2.8.8-alpha.7",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",
@@ -22,6 +22,7 @@
     "./release-candidate": "./packages/core/release-candidate.js",
     "./release-passport": "./packages/core/release-passport.js",
     "./release-propagation": "./packages/core/release-propagation.js",
+    "./surface-manifest": "./packages/core/surface-manifest.js",
     "./buildchain-kfd-claims": "./packages/core/buildchain-kfd-claims.js",
     "./site/buildchain-site.json": "./dist/site/buildchain-site.json",
     "./site/site-manifest.json": "./dist/site/site-manifest.json",

package/packages/core/index.js

@@ -203,3 +203,9 @@ export {
   resolvePropagationChannel,
   writeReleasePropagationLock,
 } from "./release-propagation.js";
+
+export {
+  SURFACE_TIMESTAMP_POLICY_CONTRACT,
+  applySurfaceTimestampPolicy,
+  createSurfaceTimestampPolicy,
+} from "./surface-manifest.js";

package/packages/core/release-passport.js

@@ -14,6 +14,7 @@ import {
   validateKfd1ReleaseGateEvidence,
   validateKfd3CollaborationInterfaceReleaseGateEvidence,
 } from "./kfd-gate.js";
+import { createSurfaceTimestampPolicy } from "./surface-manifest.js";
 
 export const RELEASE_PASSPORT_CONTRACT = "kungfu-buildchain-release-passport";
 export const ARTIFACT_EVIDENCE_CONTRACT = "kungfu-buildchain-artifact-evidence";
@@ -953,6 +954,7 @@ export function createReleasePassport({
     ? normalizeEvidenceDocument(distTagPromotionEvidence, "distTagPromotionEvidence")
     : undefined;
   const normalizedImpact = normalizeImpactLedger(impact, { tag: normalizedTag, line });
+  const generatedAt = nowIso();
   const kfd1Metadata = resolveKfd1Metadata();
   const normalizedKfd1 = kfd1?.passportSection ? kfd1 : undefined;
   const normalizedKfd3 = kfd3?.passportSection ? kfd3 : undefined;
@@ -1001,7 +1003,24 @@ export function createReleasePassport({
   return {
     schemaVersion: 1,
     contract: RELEASE_PASSPORT_CONTRACT,
-    generatedAt: nowIso(),
+    generatedAt,
+    surfaceTimestampPolicy: createSurfaceTimestampPolicy({
+      generatedAt,
+      publishedAt: optionalString(release.publishedAt || release.published_at || normalizedPublishEvidence?.publishedAt),
+      sourceRevision: optionalString(sourceSha || releaseSha || normalizedTransaction?.releaseSha),
+      timestampPolicy: "ci-injected",
+      deterministicInputs: [
+        "release.sourceSha",
+        "release.releaseSha",
+        "release.releaseMaterialSha",
+        "artifact-evidence.json",
+        "publish evidence",
+        "release-state transaction",
+      ],
+      timestampFields: ["generatedAt", "publishedAt", "surfaceTimestampPolicy.generatedAt", "surfaceTimestampPolicy.publishedAt"],
+      timestampFieldsParticipateInArtifactDigest: true,
+      artifactDigestScope: "release passport JSON and release evidence bundle",
+    }),
     product: {
       name: optionalString(productName || "Buildchain"),
       repository: optionalString(repository),

package/packages/core/surface-manifest.js

@@ -0,0 +1,87 @@
+export const SURFACE_TIMESTAMP_POLICY_CONTRACT = "kungfu-buildchain-surface-timestamp-policy";
+
+const DEFAULT_SOURCE_DATE_EPOCH = "0";
+
+function nonEmptyString(value, fallback = "") {
+  const normalized = String(value ?? "").trim();
+  return normalized || fallback;
+}
+
+function isoFromEpochSeconds(value) {
+  const raw = nonEmptyString(value, DEFAULT_SOURCE_DATE_EPOCH);
+  if (!/^-?\d+$/.test(raw)) {
+    throw new Error(`sourceDateEpoch must be integer seconds since Unix epoch: ${value}`);
+  }
+  return new Date(Number(raw) * 1000).toISOString();
+}
+
+function normalizeIso(value, label) {
+  const normalized = nonEmptyString(value);
+  if (!normalized) {
+    return "";
+  }
+  const date = new Date(normalized);
+  if (Number.isNaN(date.getTime())) {
+    throw new Error(`${label} must be an ISO-8601 timestamp`);
+  }
+  return date.toISOString();
+}
+
+function uniqueStrings(values = []) {
+  return [...new Set(values.map((value) => nonEmptyString(value)).filter(Boolean))];
+}
+
+export function createSurfaceTimestampPolicy({
+  generatedAt = "",
+  publishedAt = "",
+  sourceDateEpoch = process.env.SOURCE_DATE_EPOCH || DEFAULT_SOURCE_DATE_EPOCH,
+  sourceRevision = "",
+  deterministicInputs = [],
+  timestampPolicy = "",
+  timestampFields = ["generatedAt", "publishedAt"],
+  timestampFieldsParticipateInArtifactDigest = true,
+  artifactDigestScope = "manifest-and-artifact",
+  reproducible = true,
+} = {}) {
+  const normalizedGeneratedAt = normalizeIso(
+    generatedAt || isoFromEpochSeconds(sourceDateEpoch),
+    "generatedAt",
+  );
+  const normalizedPublishedAt = normalizeIso(publishedAt || generatedAt || "", "publishedAt");
+  const normalizedPolicy = nonEmptyString(
+    timestampPolicy,
+    generatedAt || publishedAt ? "ci-injected" : "source-date-epoch",
+  );
+  return {
+    generatedAt: normalizedGeneratedAt,
+    ...(normalizedPublishedAt ? { publishedAt: normalizedPublishedAt } : {}),
+    reproducible: Boolean(reproducible),
+    timestampPolicy: normalizedPolicy,
+    deterministicInputs: uniqueStrings([
+      ...deterministicInputs,
+      sourceRevision ? "sourceRevision" : "",
+      sourceDateEpoch ? "sourceDateEpoch" : "",
+      "package content",
+      "declared Buildchain surface manifest contract",
+    ]),
+    sourceDateEpoch: nonEmptyString(sourceDateEpoch),
+    ...(sourceRevision ? { sourceRevision: nonEmptyString(sourceRevision) } : {}),
+    timestampPolicyDetails: {
+      contract: SURFACE_TIMESTAMP_POLICY_CONTRACT,
+      timestampFields: uniqueStrings(timestampFields),
+      timestampFieldsParticipateInArtifactDigest: Boolean(timestampFieldsParticipateInArtifactDigest),
+      artifactDigestScope: nonEmptyString(artifactDigestScope, "manifest-and-artifact"),
+      note: "Human-readable timestamps are separate from reproducibility inputs; do not infer reproducibility from epoch timestamps.",
+    },
+  };
+}
+
+export function applySurfaceTimestampPolicy(manifest, options = {}) {
+  if (!manifest || typeof manifest !== "object" || Array.isArray(manifest)) {
+    throw new Error("surface manifest must be a JSON object");
+  }
+  return {
+    ...manifest,
+    ...createSurfaceTimestampPolicy(options),
+  };
+}

package/scripts/check-inventory.mjs

@@ -123,6 +123,9 @@ if (rootPackage.exports?.["./release-passport"] !== "./packages/core/release-pas
 if (rootPackage.exports?.["./release-propagation"] !== "./packages/core/release-propagation.js") {
   throw new Error("root package must export @kungfu-tech/buildchain/release-propagation");
 }
+if (rootPackage.exports?.["./surface-manifest"] !== "./packages/core/surface-manifest.js") {
+  throw new Error("root package must export @kungfu-tech/buildchain/surface-manifest");
+}
 if (rootPackage.exports?.["./buildchain-kfd-claims"] !== "./packages/core/buildchain-kfd-claims.js") {
   throw new Error("root package must export @kungfu-tech/buildchain/buildchain-kfd-claims");
 }
@@ -193,9 +196,18 @@ if (!coreIndexSource.includes("KFD2_RELEASE_TRUST_PASSPORT_CONTRACT")) {
 if (!coreIndexSource.includes("KFD2_TRUST_PROOF_CONTRACT")) {
   throw new Error("packages/core/index.js must export KFD-2 trust proof contract");
 }
+if (!coreIndexSource.includes("createSurfaceTimestampPolicy")) {
+  throw new Error("packages/core/index.js must export surface manifest timestamp policy APIs");
+}
 if (siteBundle.contract !== "kungfu-buildchain-site-bundle") {
   throw new Error("buildchain-site.json must expose the Buildchain site bundle contract");
 }
+if (siteBundle.package?.version !== rootPackage.version) {
+  throw new Error("buildchain-site.json package.version must match package.json version");
+}
+if (siteManifest.package?.version !== rootPackage.version) {
+  throw new Error("site-manifest.json package.version must match package.json version");
+}
 if (siteBundle.source?.homepageTextSource !== "README.md") {
   throw new Error("buildchain-site.json source.homepageTextSource must be README.md");
 }
@@ -241,6 +253,20 @@ if (siteBundle.pageRegistry?.path !== "page-registry.json" || siteBundle.pageReg
 if (!siteManifest.facts?.includes("page-registry.json") || !siteBundle.entrypoints?.includes("page-registry.json")) {
   throw new Error("site bundle entrypoints must include page-registry.json");
 }
+for (const [name, manifest] of [["buildchain-site.json", siteBundle], ["site-manifest.json", siteManifest]]) {
+  if (!manifest.generatedAt) {
+    throw new Error(`${name} must expose generatedAt`);
+  }
+  if (manifest.timestampPolicy === "ci-injected" && manifest.generatedAt === "1970-01-01T00:00:00.000Z") {
+    throw new Error(`${name} must not use epoch generatedAt when timestampPolicy=ci-injected`);
+  }
+  if (!manifest.timestampPolicy || !manifest.reproducible || !Array.isArray(manifest.deterministicInputs)) {
+    throw new Error(`${name} must expose the Buildchain surface timestamp/reproducibility policy`);
+  }
+  if (manifest.timestampPolicyDetails?.contract !== "kungfu-buildchain-surface-timestamp-policy") {
+    throw new Error(`${name} must expose timestampPolicyDetails.contract`);
+  }
+}
 function immediateReadmes(dir) {
   const absoluteDir = path.join(root, dir);
   if (!fs.existsSync(absoluteDir)) return [];

package/scripts/generate-site-bundle.mjs

@@ -8,6 +8,7 @@ import {
   BUILDCHAIN_AGENT_MANUALS,
   createBuildchainKfdClaimRegistry,
 } from "../packages/core/buildchain-kfd-claims.js";
+import { createSurfaceTimestampPolicy } from "../packages/core/surface-manifest.js";
 
 const SITE_BUNDLE_CONTRACT = "kungfu-buildchain-site-bundle";
 const README_PATH = "README.md";
@@ -31,6 +32,10 @@ function stableJson(value) {
   return `${JSON.stringify(value, null, 2)}\n`;
 }
 
+function env(name) {
+  return String(process.env[name] || "").trim();
+}
+
 function sha256File(rel) {
   const filePath = path.join(root, rel);
   return fs.existsSync(filePath) && fs.statSync(filePath).isFile()
@@ -215,6 +220,30 @@ function buildSiteBundle() {
   const readme = parseReadme(readText(README_PATH));
   const docs = BUILDCHAIN_AGENT_MANUALS.map((manual) => docEntry(manual.id, manual.title, manual.path, manual.plane));
   const pages = buildSitePages();
+  const generatedAtInput = env("BUILDCHAIN_SITE_GENERATED_AT") || env("BUILDCHAIN_SURFACE_GENERATED_AT");
+  const publishedAtInput = env("BUILDCHAIN_SITE_PUBLISHED_AT") || env("BUILDCHAIN_SURFACE_PUBLISHED_AT");
+  const timestampPolicyInput = env("BUILDCHAIN_SITE_TIMESTAMP_POLICY") || env("BUILDCHAIN_SURFACE_TIMESTAMP_POLICY");
+  const sourceRevisionInput =
+    env("BUILDCHAIN_SOURCE_SHA") ||
+    (generatedAtInput || publishedAtInput || timestampPolicyInput ? env("GITHUB_SHA") : "");
+  const timestampPolicy = createSurfaceTimestampPolicy({
+    generatedAt: generatedAtInput,
+    publishedAt: publishedAtInput,
+    sourceDateEpoch: env("SOURCE_DATE_EPOCH") || "0",
+    sourceRevision: sourceRevisionInput,
+    timestampPolicy: timestampPolicyInput,
+    deterministicInputs: [
+      "README.md",
+      "docs/*.md",
+      "actions/*/README.md",
+      "fixtures/*/README.md",
+      "packages/core/README.md",
+      "package.json#exports",
+      "tests/buildchain-inventory.json",
+    ],
+    timestampFieldsParticipateInArtifactDigest: true,
+    artifactDigestScope: "npm package dist/site JSON files",
+  });
 
   const cliRegistry = {
     schemaVersion: 1,
@@ -438,6 +467,7 @@ function buildSiteBundle() {
   const siteManifest = {
     schemaVersion: 1,
     contract: "kungfu-buildchain-site-manifest",
+    ...timestampPolicy,
     product: {
       name: "Buildchain",
       formalName: "Buildchain by Kungfu",
@@ -445,6 +475,7 @@ function buildSiteBundle() {
     },
     package: {
       name: packageJson.name,
+      version: packageJson.version,
       versionSource: "package.json#version",
     },
     entrypoint: "buildchain-site.json",
@@ -549,6 +580,7 @@ function buildSiteBundle() {
   const siteBundle = {
     schemaVersion: 1,
     contract: SITE_BUNDLE_CONTRACT,
+    ...timestampPolicy,
     product: siteManifest.product,
     package: siteManifest.package,
     source: {

package/scripts/web-surface-core.mjs

@@ -5,6 +5,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { loadBuildchainConfig, validateBuildchainConfig } from "../packages/core/buildchain-config.js";
+import { createSurfaceTimestampPolicy } from "../packages/core/surface-manifest.js";
 
 const DEFAULT_RETENTION = Object.freeze({
   preview: {
@@ -609,9 +610,27 @@ export function createWebSurfaceDeploymentManifest({
     deployConfig,
   });
   const primaryBinding = surfaceBindings[0];
+  const timestampPolicy = createSurfaceTimestampPolicy({
+    generatedAt: deployedAt,
+    publishedAt: deployedAt,
+    sourceRevision: sourceSha,
+    timestampPolicy: "ci-injected",
+    deterministicInputs: [
+      "web-surface artifact content",
+      "buildchain.toml web-surface channels/deploy/surfaces",
+      "sourceSha",
+      "artifactHash",
+      "deployment channel",
+      "deployment alias",
+    ],
+    timestampFields: ["generatedAt", "publishedAt", "deployedAt"],
+    timestampFieldsParticipateInArtifactDigest: false,
+    artifactDigestScope: "web-surface artifactHash excludes deployment manifest timestamps",
+  });
   return {
     schemaVersion: 1,
     contract: "kungfu-buildchain-web-surface-deployment",
+    ...timestampPolicy,
     site: config.project.site || config.project.name || "",
     channel,
     alias,

package/scripts/web-surface.mjs

@@ -77,6 +77,10 @@ export function webSurfaceCli() {
       "alias",
       process.env.BUILDCHAIN_WEB_SURFACE_ALIAS || defaultWebSurfaceAlias({ channel, sourceSha, pullNumber }),
     );
+    const generatedAt = readArg(
+      "generated-at",
+      process.env.BUILDCHAIN_SITE_GENERATED_AT || process.env.BUILDCHAIN_SURFACE_GENERATED_AT || "",
+    );
     const result = planWebSurfaceDeploy({
       cwd,
       channel,
@@ -89,6 +93,7 @@ export function webSurfaceCli() {
       rollbackPointer: readArg("rollback-pointer", process.env.BUILDCHAIN_ROLLBACK_REF || ""),
       rollbackLimitations: readArg("rollback-limitations", process.env.BUILDCHAIN_ROLLBACK_LIMITATIONS || ""),
       dryRun: readBooleanArg("dry-run", true),
+      ...(generatedAt ? { deployedAt: generatedAt } : {}),
     });
     const outputResult = mode === "manifest" ? result.manifest : result;
     writeJson(outputResult, output);
@@ -111,6 +116,10 @@ export function webSurfaceCli() {
           "alias",
           process.env.BUILDCHAIN_WEB_SURFACE_ALIAS || defaultWebSurfaceAlias({ channel, sourceSha, pullNumber }),
         );
+    const publishedAt = readArg(
+      "published-at",
+      process.env.BUILDCHAIN_SITE_PUBLISHED_AT || process.env.BUILDCHAIN_SURFACE_PUBLISHED_AT || "",
+    );
     const result = applyWebSurfaceDeploy({
       cwd,
       channel,
@@ -122,6 +131,7 @@ export function webSurfaceCli() {
       dryRun: readBooleanArg("dry-run", true),
       actor: readArg("actor", process.env.GITHUB_ACTOR || ""),
       runId: readArg("run-id", process.env.GITHUB_RUN_ID || ""),
+      ...(publishedAt ? { appliedAt: publishedAt } : {}),
     });
     writeJson(result, output);
     writeGitHubOutputs({