@kungfu-tech/buildchain 3.0.0 → 3.0.1-alpha.1

package/docs/versioning.md

@@ -61,6 +61,7 @@ repository changes are patch".
 
 | Date | Action | Line | Faces | Class | Rationale | PR |
 | --- | --- | --- | --- | --- | --- | --- |
+| 2026-07-26 | extend-minor | `v3.0` | auditable-demo-workflow, auditable-demo-evidence | additive | Forward-port the consumer-neutral reusable Gate that binds exact same-run GitHub Artifacts to checked-in adapters and immutable renderer evidence, with optional media rendering only from the exact passing Gate bundle. | #1862 |
 | 2026-07-23 | extend-minor | `v2.14` | credential-island-macos-input, protected-signer-job, macos-signing-evidence, action-subpaths | additive | The reusable build surface can seal an exact source-bound macOS app and hand it to a protected caller environment, where an immutable Buildchain action signs, notarizes, staples, Gatekeeper-assesses, and returns an auditable additional release-candidate platform without exposing credentials to consumer lifecycle jobs. | |
 | 2026-07-20 | extend-minor | `v2.14` | anchored-derived-version-material, build-controller-evidence, release-passport, package-subpaths, release-propagation-controller | additive | Anchored/manual consumers can declare derived version witnesses that Buildchain regenerates and verifies before heavy builds, binds to exact alpha/release trees and passports, and admits during protected promotion; propagation receipts now model their existing optional consumer stages. | |
 | 2026-07-17 | extend-minor | `v2.14` | merge-queue-config, release-line-governance-inheritance | additive | Buildchain config can explicitly enable, inherit, or disable exact dev-channel merge queues, and release-line bootstrap reconciles the declared or inherited policy before moving the repository default branch. | |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "3.0.0",
+  "version": "3.0.1-alpha.1",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",
@@ -44,6 +44,7 @@
     "./release-passport": "./packages/core/release-passport.js",
     "./release-passport-contract": "./packages/core/release-passport-contract.js",
     "./release-propagation": "./packages/core/release-propagation.js",
+    "./release-activation-transaction": "./packages/core/release-activation-transaction.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",

package/packages/core/buildchain-config.js

@@ -511,6 +511,20 @@ function normalizePublishSection(publish) {
       ? ""
       : assertString(publish.main_package, "publish.main_package"),
   };
+  if (publish.shared_alpha_authority_major !== undefined) {
+    const sharedAlphaAuthorityMajor = Number(
+      publish.shared_alpha_authority_major,
+    );
+    if (
+      !Number.isSafeInteger(sharedAlphaAuthorityMajor) ||
+      sharedAlphaAuthorityMajor < 1
+    ) {
+      throw new Error(
+        "publish.shared_alpha_authority_major must be a positive integer",
+      );
+    }
+    normalized.sharedAlphaAuthorityMajor = sharedAlphaAuthorityMajor;
+  }
   if (publish.kind !== undefined) {
     normalized.kind = kind;
   }

package/packages/core/buildchain-contract.js

@@ -301,6 +301,51 @@ export function createBuildchainContractWorld({
         "channel-aware artifact host facts are checked against the deploy plan before adapter side effects",
       ],
     }),
+    surface(root, {
+      id: "auditable-demo",
+      kind: "workflow",
+      path: ".github/workflows/.auditable-demo.yml",
+      publicRef: `${pkg.repository ? "kungfu-systems/buildchain" : "buildchain"}/.github/workflows/.auditable-demo.yml@${majorLine}`,
+      requiredInputs: [
+        "source-artifact-name",
+        "source-artifact-digest",
+        "adapter-path",
+        "renderer-image",
+      ],
+      requiredOutputs: [
+        "source-sha",
+        "gate-artifact-name",
+        "gate-artifact-id",
+        "gate-artifact-digest",
+        "gate-artifact-url",
+        "gate-root",
+        "media-artifact-name",
+        "media-artifact-id",
+        "media-artifact-digest",
+        "media-artifact-url",
+        "media-root",
+      ],
+      breakingDefaults: {
+        trustedEventRequired: true,
+        renderMediaDefault: false,
+        artifactRetentionDaysDefault: 14,
+        gatePolicy: "required-before-selective-render",
+      },
+      optionalInputs: [
+        "buildchain-repository",
+        "source-ref",
+        "render-media",
+        "artifact-retention-days",
+        "require-trusted-event",
+      ],
+      guarantees: [
+        "the source GitHub Artifact is admitted by exact same-run name and archive digest",
+        "the checked-in consumer adapter runs from the exact consumer source with a disposable home and reduced environment",
+        "every invocation runs an immutable network-disabled renderer smoke before emitting a qualified Gate bundle",
+        "complete media rendering is optional and consumes only an exact passing Gate bundle",
+        "Gate and media bundles expose both GitHub Artifact archive coordinates and deterministic member roots",
+      ],
+    }),
     surface(root, {
       id: "promote-buildchain-ref-action",
       kind: "action",

package/packages/core/buildchain-kfd-claims.js

@@ -13,6 +13,7 @@ export const BUILDCHAIN_KFD_COLLABORATION_INTERFACE_CONTRACT = "kungfu-buildchai
 
 export const BUILDCHAIN_AGENT_MANUALS = Object.freeze([
   { id: "map", title: "Buildchain documentation map", path: "docs/MAP.md", plane: "use" },
+  { id: "auditable-demo", title: "Auditable demo artifact pipeline", path: "docs/auditable-demo.md", plane: "verify" },
   { id: "install", title: "Install and verify Buildchain", path: "docs/install.md", plane: "use" },
   { id: "release-passport", title: "Release Passport protocol", path: "docs/release-passport.md", plane: "verify" },
   { id: "controller-evidence", title: "Controller evidence contract", path: "docs/controller-evidence.md", plane: "verify" },

package/packages/core/buildchain-publication-authority.js

@@ -4,6 +4,7 @@ import path from "node:path";
 import { createPublicationAuthorityRegistry } from "./publication-authority.js";
 
 const DESCRIPTORS = Object.freeze([
+  [".github/workflows/.auditable-demo.yml", "non-publication-oidc"],
   [".github/workflows/.build.yml", "non-publication-oidc"],
   [".github/workflows/.release-candidate-promote.yml", "product-publication", true, ["npm-publish", "github-release", "channel-ref"], "trusted-publishing", "none", "fixed", "caller-bound"],
   [".github/workflows/.publication-authority.yml", "evidence-publication"],

package/packages/core/github-governance-authority.js

@@ -46,9 +46,9 @@ const PUBLIC_REPOSITORY_TARGETS = Object.freeze({
     target("publish-gate/major", [check("check")], true),
   ],
   buildchain: [
-    target("dev/v2/v2.14", [check("check")], false),
-    target("alpha/v2/v2.14", [check("check"), check("verify")], false),
-    target("release/v2/v2.14", [check("check")], true),
+    target("dev/v3/v3.0", [check("check")], false),
+    target("alpha/v3/v3.0", [check("check"), check("verify")], false),
+    target("release/v3/v3.0", [check("check")], true),
     target("publish-gate/major", [check("check")], true),
   ],
   "homebrew-tap": [

package/packages/core/index.js

@@ -521,6 +521,20 @@ export {
   writeReleasePropagationLock,
 } from "./release-propagation.js";
 
+export {
+  RELEASE_ACTIVATION_CONTRACT,
+  RELEASE_ACTIVATION_PHASES,
+  RELEASE_ACTIVATION_RECEIPT_SET_CONTRACT,
+  abortReleaseActivationTransaction,
+  createReleaseActivationReceiptSet,
+  createReleaseActivationTransaction,
+  recordReleaseActivationPhase,
+  releaseActivationRoot,
+  rollbackReleaseActivationTransaction,
+  validateReleaseActivationReceiptSet,
+  validateReleaseActivationTransaction,
+} from "./release-activation-transaction.js";
+
 export {
   SURFACE_TIMESTAMP_POLICY_CONTRACT,
   applySurfaceTimestampPolicy,

package/packages/core/release-activation-transaction.js

@@ -0,0 +1,421 @@
+import crypto from "node:crypto";
+
+export const RELEASE_ACTIVATION_CONTRACT =
+  "kungfu-buildchain-release-activation-transaction/v1";
+export const RELEASE_ACTIVATION_RECEIPT_SET_CONTRACT =
+  "kungfu-buildchain-release-activation-receipt-set/v1";
+
+export const RELEASE_ACTIVATION_PHASES = Object.freeze([
+  "candidate-qualified",
+  "artifacts-published",
+  "passport-sealed",
+  "site-published",
+  "public-readback",
+  "evidence-synthesized",
+]);
+
+const ROOT = /^sha256:[0-9a-f]{64}$/;
+const SHA = /^[0-9a-f]{40}$/;
+const RECEIPT_KINDS = Object.freeze([
+  "artifact-publication",
+  "release-passport",
+  "site-publication",
+  "public-readback",
+  "product-qualification",
+]);
+
+function stableJson(value) {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.keys(value)
+      .sort()
+      .map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`)
+      .join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+export function releaseActivationRoot(value) {
+  const copy = structuredClone(value);
+  delete copy.transactionRoot;
+  delete copy.receiptSetRoot;
+  return `sha256:${crypto.createHash("sha256").update(stableJson(copy)).digest("hex")}`;
+}
+
+function requiredString(value, label) {
+  const normalized = String(value || "").trim();
+  if (!normalized) throw new Error(`${label} must be a non-empty string`);
+  return normalized;
+}
+
+function exactRoot(value, label) {
+  const normalized = requiredString(value, label).toLowerCase();
+  if (!ROOT.test(normalized))
+    throw new Error(`${label} must be a sha256 content root`);
+  return normalized;
+}
+
+function exactSha(value, label) {
+  const normalized = requiredString(value, label).toLowerCase();
+  if (!SHA.test(normalized))
+    throw new Error(`${label} must be an exact 40-character Git SHA`);
+  return normalized;
+}
+
+function normalizeBindings(bindings = {}) {
+  const version = requiredString(bindings.version, "bindings.version");
+  const tag = requiredString(bindings.tag, "bindings.tag");
+  if (tag !== `v${version}`)
+    throw new Error("bindings.tag must exactly match bindings.version");
+  const channel = requiredString(bindings.channel, "bindings.channel");
+  if (!["alpha", "release"].includes(channel)) {
+    throw new Error("bindings.channel must be alpha or release");
+  }
+  const environment = requiredString(
+    bindings.environment,
+    "bindings.environment",
+  );
+  if (!["shadow", "production"].includes(environment)) {
+    throw new Error("bindings.environment must be shadow or production");
+  }
+  return {
+    sourceSha: exactSha(bindings.sourceSha, "bindings.sourceSha"),
+    siteSourceSha: exactSha(bindings.siteSourceSha, "bindings.siteSourceSha"),
+    tag,
+    channel,
+    version,
+    environment,
+    artifactSetRoot: exactRoot(
+      bindings.artifactSetRoot,
+      "bindings.artifactSetRoot",
+    ),
+  };
+}
+
+function normalizeOwners(owners = {}) {
+  return {
+    product: requiredString(owners.product, "owners.product"),
+    transaction: requiredString(owners.transaction, "owners.transaction"),
+    site: requiredString(owners.site, "owners.site"),
+  };
+}
+
+export function createReleaseActivationTransaction({
+  transactionId,
+  mode = "shadow",
+  bindings,
+  owners,
+} = {}) {
+  if (!["shadow", "activation"].includes(mode)) {
+    throw new Error("mode must be shadow or activation");
+  }
+  const normalizedBindings = normalizeBindings(bindings);
+  if (mode === "shadow" && normalizedBindings.environment !== "shadow") {
+    throw new Error("shadow transactions must use the shadow environment");
+  }
+  if (
+    mode === "activation" &&
+    normalizedBindings.environment !== "production"
+  ) {
+    throw new Error(
+      "activation transactions must use the production environment",
+    );
+  }
+  const transaction = {
+    schema: RELEASE_ACTIVATION_CONTRACT,
+    transactionId: requiredString(transactionId, "transactionId"),
+    mode,
+    state: "open",
+    releasedUseClaim: false,
+    bindings: normalizedBindings,
+    owners: normalizeOwners(owners),
+    phases: RELEASE_ACTIVATION_PHASES.map((id) => ({
+      id,
+      status: "pending",
+      attempts: 0,
+      receiptRoots: [],
+    })),
+    retainedReceiptRoots: [],
+    failure: null,
+    rollback: null,
+  };
+  transaction.transactionRoot = releaseActivationRoot(transaction);
+  return transaction;
+}
+
+export function validateReleaseActivationTransaction(transaction) {
+  const issues = [];
+  if (transaction?.schema !== RELEASE_ACTIVATION_CONTRACT) {
+    issues.push(`schema must be ${RELEASE_ACTIVATION_CONTRACT}`);
+  }
+  try {
+    normalizeBindings(transaction?.bindings);
+    normalizeOwners(transaction?.owners);
+  } catch (error) {
+    issues.push(error.message);
+  }
+  if (!["shadow", "activation"].includes(transaction?.mode))
+    issues.push("mode is invalid");
+  if (
+    !["open", "complete", "aborted", "rolled-back"].includes(
+      transaction?.state,
+    )
+  ) {
+    issues.push("state is invalid");
+  }
+  if (
+    !Array.isArray(transaction?.phases) ||
+    transaction.phases.map((phase) => phase.id).join(",") !==
+      RELEASE_ACTIVATION_PHASES.join(",")
+  ) {
+    issues.push("phases must preserve the canonical activation order");
+  } else {
+    let pendingSeen = false;
+    for (const phase of transaction.phases) {
+      if (!["pending", "passed", "failed", "rolled-back"].includes(phase.status)) {
+        issues.push(`phase ${phase.id} has invalid status`);
+      }
+      if (phase.status === "pending") pendingSeen = true;
+      if (pendingSeen && phase.status === "passed") {
+        issues.push(`phase ${phase.id} passed after an incomplete predecessor`);
+      }
+      if (!Number.isSafeInteger(phase.attempts) || phase.attempts < 0) {
+        issues.push(
+          `phase ${phase.id} attempts must be a non-negative integer`,
+        );
+      }
+      if (
+        !Array.isArray(phase.receiptRoots) ||
+        phase.receiptRoots.some((root) => !ROOT.test(root))
+      ) {
+        issues.push(`phase ${phase.id} receipt roots are invalid`);
+      }
+    }
+  }
+  if (
+    transaction?.mode === "shadow" &&
+    transaction?.releasedUseClaim !== false
+  ) {
+    issues.push("shadow transactions must never make a released-use claim");
+  }
+  if (
+    transaction?.transactionRoot !== releaseActivationRoot(transaction || {})
+  ) {
+    issues.push("transactionRoot mismatch");
+  }
+  return { valid: issues.length === 0, issues };
+}
+
+function refresh(transaction) {
+  transaction.retainedReceiptRoots = [
+    ...new Set(transaction.phases.flatMap((phase) => phase.receiptRoots)),
+  ].sort();
+  transaction.transactionRoot = releaseActivationRoot(transaction);
+  return transaction;
+}
+
+export function recordReleaseActivationPhase(
+  transaction,
+  phaseId,
+  { receiptRoots = [], failure = "" } = {},
+) {
+  const validation = validateReleaseActivationTransaction(transaction);
+  if (!validation.valid)
+    throw new Error(
+      `invalid activation transaction: ${validation.issues.join("; ")}`,
+    );
+  if (transaction.state !== "open") {
+    if (transaction.state === "complete" && !failure)
+      return structuredClone(transaction);
+    throw new Error(
+      `cannot record a phase while transaction state is ${transaction.state}`,
+    );
+  }
+  const next = structuredClone(transaction);
+  const index = RELEASE_ACTIVATION_PHASES.indexOf(phaseId);
+  if (index < 0) throw new Error(`unknown activation phase: ${phaseId}`);
+  if (
+    next.phases.slice(0, index).some((phase) => phase.status !== "passed")
+  ) {
+    throw new Error(
+      `activation phase ${phaseId} cannot skip an incomplete predecessor`,
+    );
+  }
+  const phase = next.phases[index];
+  const normalizedRoots = [
+    ...new Set(
+      receiptRoots.map((root, receiptIndex) =>
+        exactRoot(root, `receiptRoots[${receiptIndex}]`),
+      ),
+    ),
+  ].sort();
+  if (phase.status === "passed") {
+    if (stableJson(phase.receiptRoots) !== stableJson(normalizedRoots)) {
+      throw new Error(
+        `activation phase ${phaseId} replay changed receipt roots`,
+      );
+    }
+    return next;
+  }
+  phase.attempts += 1;
+  phase.receiptRoots = normalizedRoots;
+  if (failure) {
+    phase.status = "failed";
+    next.failure = {
+      phase: phaseId,
+      reason: requiredString(failure, "failure"),
+    };
+    return refresh(next);
+  }
+  phase.status = "passed";
+  next.failure = null;
+  if (index === RELEASE_ACTIVATION_PHASES.length - 1)
+    next.state = "complete";
+  return refresh(next);
+}
+
+export function abortReleaseActivationTransaction(transaction, reason) {
+  if (transaction.state === "complete")
+    throw new Error("completed activation transactions cannot be aborted");
+  const next = structuredClone(transaction);
+  next.state = "aborted";
+  next.failure = {
+    phase:
+      next.phases.find((phase) => phase.status !== "passed")?.id || "",
+    reason: requiredString(reason, "reason"),
+  };
+  return refresh(next);
+}
+
+export function rollbackReleaseActivationTransaction(
+  transaction,
+  { toSiteSourceSha, reason } = {},
+) {
+  if (!["complete", "aborted"].includes(transaction.state)) {
+    throw new Error(
+      "rollback requires a complete or aborted activation transaction",
+    );
+  }
+  const next = structuredClone(transaction);
+  next.state = "rolled-back";
+  next.rollback = {
+    toSiteSourceSha: exactSha(toSiteSourceSha, "toSiteSourceSha"),
+    reason: requiredString(reason, "reason"),
+  };
+  for (const phase of next.phases.slice(3).reverse()) {
+    if (phase.status === "passed") phase.status = "rolled-back";
+  }
+  return refresh(next);
+}
+
+export function createReleaseActivationReceiptSet({
+  transaction,
+  receipts = [],
+} = {}) {
+  const validation = validateReleaseActivationTransaction(transaction);
+  if (!validation.valid)
+    throw new Error(
+      `invalid activation transaction: ${validation.issues.join("; ")}`,
+    );
+  if (transaction.state !== "complete")
+    throw new Error(
+      "receipt synthesis requires a complete activation transaction",
+    );
+  const byKind = new Map();
+  for (const [index, receipt] of receipts.entries()) {
+    const kind = requiredString(receipt?.kind, `receipts[${index}].kind`);
+    if (!RECEIPT_KINDS.includes(kind))
+      throw new Error(`unsupported activation receipt kind: ${kind}`);
+    if (byKind.has(kind))
+      throw new Error(`duplicate activation receipt kind: ${kind}`);
+    byKind.set(kind, {
+      kind,
+      root: exactRoot(receipt.root, `receipts[${index}].root`),
+      bindingRoot: exactRoot(
+        receipt.bindingRoot,
+        `receipts[${index}].bindingRoot`,
+      ),
+      locator: requiredString(
+        receipt.locator,
+        `receipts[${index}].locator`,
+      ),
+    });
+  }
+  for (const kind of RECEIPT_KINDS) {
+    if (!byKind.has(kind))
+      throw new Error(`activation receipt set is missing ${kind}`);
+  }
+  const bindingRoot = releaseActivationRoot(transaction.bindings);
+  if (
+    [...byKind.values()].some(
+      (receipt) => receipt.bindingRoot !== bindingRoot,
+    )
+  ) {
+    throw new Error(
+      "activation receipts do not bind the exact transaction inputs",
+    );
+  }
+  const receiptSet = {
+    schema: RELEASE_ACTIVATION_RECEIPT_SET_CONTRACT,
+    transactionId: transaction.transactionId,
+    transactionRoot: transaction.transactionRoot,
+    mode: transaction.mode,
+    releasedUseClaim: transaction.mode === "activation",
+    bindings: structuredClone(transaction.bindings),
+    receipts: RECEIPT_KINDS.map((kind) => byKind.get(kind)),
+    legalBoundary: {
+      firstUseDateClaim: null,
+      legalConclusion: "not-made",
+      registrationStatusClaim: "none",
+    },
+  };
+  receiptSet.receiptSetRoot = releaseActivationRoot(receiptSet);
+  return receiptSet;
+}
+
+export function validateReleaseActivationReceiptSet(
+  receiptSet,
+  { allowShadow = true } = {},
+) {
+  const issues = [];
+  if (receiptSet?.schema !== RELEASE_ACTIVATION_RECEIPT_SET_CONTRACT) {
+    issues.push(`schema must be ${RELEASE_ACTIVATION_RECEIPT_SET_CONTRACT}`);
+  }
+  try {
+    normalizeBindings(receiptSet?.bindings);
+  } catch (error) {
+    issues.push(error.message);
+  }
+  if (!allowShadow && receiptSet?.mode !== "activation")
+    issues.push("released evidence requires activation mode");
+  if (
+    receiptSet?.mode === "shadow" &&
+    receiptSet?.releasedUseClaim !== false
+  ) {
+    issues.push("shadow receipt sets must not claim released use");
+  }
+  const receipts = Array.isArray(receiptSet?.receipts)
+    ? receiptSet.receipts
+    : [];
+  if (
+    receipts.map((receipt) => receipt.kind).join(",") !==
+    RECEIPT_KINDS.join(",")
+  ) {
+    issues.push(
+      "receipt kinds are missing, duplicated, or out of canonical order",
+    );
+  }
+  const bindingRoot = releaseActivationRoot(receiptSet?.bindings || {});
+  for (const receipt of receipts) {
+    if (!ROOT.test(receipt?.root || ""))
+      issues.push(`${receipt?.kind || "receipt"} root is invalid`);
+    if (receipt?.bindingRoot !== bindingRoot)
+      issues.push(`${receipt?.kind || "receipt"} binding root mismatch`);
+    if (!String(receipt?.locator || "").trim())
+      issues.push(`${receipt?.kind || "receipt"} locator is missing`);
+  }
+  if (receiptSet?.receiptSetRoot !== releaseActivationRoot(receiptSet || {})) {
+    issues.push("receiptSetRoot mismatch");
+  }
+  return { valid: issues.length === 0, issues };
+}