@kungfu-tech/buildchain 2.8.8-alpha.6 → 2.8.8-alpha.8

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()
@@ -42,6 +47,26 @@ function existingJson(filePath) {
   return fs.existsSync(filePath) ? fs.readFileSync(filePath, "utf8") : "";
 }
 
+function readExistingSiteTimestampPolicy(packageVersion) {
+  const manifestPath = path.join(outputDir, "site-manifest.json");
+  if (!fs.existsSync(manifestPath)) return null;
+  try {
+    const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+    if (manifest?.package?.version !== packageVersion) return null;
+    if (manifest?.timestampPolicy !== "ci-injected") return null;
+    if (!manifest?.generatedAt || manifest.generatedAt === "1970-01-01T00:00:00.000Z") return null;
+    return {
+      generatedAt: manifest.generatedAt,
+      publishedAt: manifest.publishedAt || manifest.generatedAt,
+      sourceDateEpoch: manifest.sourceDateEpoch,
+      sourceRevision: manifest.sourceRevision,
+      timestampPolicy: manifest.timestampPolicy,
+    };
+  } catch {
+    return null;
+  }
+}
+
 function normalizeMarkdown(value) {
   return String(value || "").replace(/\r\n/g, "\n").trim();
 }
@@ -215,6 +240,38 @@ 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 preservedTimestampPolicy = readExistingSiteTimestampPolicy(packageJson.version);
+  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 sourceRevisionEnv = env("BUILDCHAIN_SOURCE_SHA");
+  const shouldPreserveExistingTimestampPolicy =
+    !generatedAtInput && !publishedAtInput && !timestampPolicyInput && !sourceRevisionEnv;
+  const sourceRevisionInput =
+    sourceRevisionEnv ||
+    (generatedAtInput || publishedAtInput || timestampPolicyInput
+      ? env("GITHUB_SHA")
+      : shouldPreserveExistingTimestampPolicy
+        ? preservedTimestampPolicy?.sourceRevision || ""
+        : "");
+  const timestampPolicy = createSurfaceTimestampPolicy({
+    generatedAt: generatedAtInput || (shouldPreserveExistingTimestampPolicy ? preservedTimestampPolicy?.generatedAt : ""),
+    publishedAt: publishedAtInput || (shouldPreserveExistingTimestampPolicy ? preservedTimestampPolicy?.publishedAt : ""),
+    sourceDateEpoch: env("SOURCE_DATE_EPOCH") || (shouldPreserveExistingTimestampPolicy ? preservedTimestampPolicy?.sourceDateEpoch : "") || "0",
+    sourceRevision: sourceRevisionInput,
+    timestampPolicy: timestampPolicyInput || (shouldPreserveExistingTimestampPolicy ? preservedTimestampPolicy?.timestampPolicy : ""),
+    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 +495,7 @@ function buildSiteBundle() {
   const siteManifest = {
     schemaVersion: 1,
     contract: "kungfu-buildchain-site-manifest",
+    ...timestampPolicy,
     product: {
       name: "Buildchain",
       formalName: "Buildchain by Kungfu",
@@ -445,6 +503,7 @@ function buildSiteBundle() {
     },
     package: {
       name: packageJson.name,
+      version: packageJson.version,
       versionSource: "package.json#version",
     },
     entrypoint: "buildchain-site.json",
@@ -549,6 +608,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({