@kungfu-tech/buildchain 2.14.18 → 2.14.19-alpha.1

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

@@ -0,0 +1,325 @@
+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 };
+}

package/packages/core/self-dogfood-version.js

@@ -0,0 +1,85 @@
+function parsePackageVersion(version) {
+  const match = String(version || "").match(
+    /^(\d+)\.(\d+)\.(\d+)(?:-alpha\.(\d+))?$/,
+  );
+  if (!match) {
+    throw new Error(
+      "root package version must expose a numeric semver version for self-dogfood",
+    );
+  }
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    alpha: match[4] === undefined ? undefined : Number(match[4]),
+  };
+}
+
+function parseAlphaRef(ref) {
+  const match = String(ref || "").match(/^v(\d+)-alpha$/);
+  if (!match) {
+    throw new Error(
+      "Buildchain self-dogfood alpha lock must target a major alpha ref",
+    );
+  }
+  return Number(match[1]);
+}
+
+export function resolveSelfDogfoodMajor({
+  packageVersion,
+  alphaRef,
+  majorBootstrap = false,
+} = {}) {
+  const version = parsePackageVersion(packageVersion);
+  const acceptedMajor = parseAlphaRef(alphaRef);
+  if (acceptedMajor === version.major) {
+    return {
+      packageMajor: version.major,
+      workflowMajor: acceptedMajor,
+      bootstrap: false,
+    };
+  }
+
+  const stableBootstrap =
+    version.minor === 0 && version.patch === 0 && version.alpha === undefined;
+  const nextAlphaBootstrap =
+    version.minor === 0 && version.patch === 1 && version.alpha !== undefined;
+  if (
+    majorBootstrap === true &&
+    acceptedMajor + 1 === version.major &&
+    (stableBootstrap || nextAlphaBootstrap)
+  ) {
+    return {
+      packageMajor: version.major,
+      workflowMajor: acceptedMajor,
+      bootstrap: true,
+    };
+  }
+
+  throw new Error(
+    "Buildchain self-dogfood alpha lock must target the current major alpha ref",
+  );
+}
+
+export function contractForSelfDogfoodEvaluation({
+  currentContract,
+  majorResolution,
+} = {}) {
+  if (!currentContract || typeof currentContract !== "object") {
+    throw new Error("Buildchain self-dogfood requires a current contract");
+  }
+  if (!majorResolution?.bootstrap) {
+    return currentContract;
+  }
+  return {
+    ...currentContract,
+    majorLine: `v${majorResolution.workflowMajor}`,
+  };
+}
+
+export function canAdmitSelfDogfoodLockEvaluation({
+  evaluation,
+  majorResolution,
+} = {}) {
+  return evaluation?.compatible === true || majorResolution?.bootstrap === true;
+}

package/scripts/check-inventory.mjs

@@ -5,6 +5,11 @@ import {
   collectPublicSurfaceReverseAudit,
 } from "../packages/core/public-surface-audit.js";
 import { evaluateBuildchainContractLock } from "../packages/core/buildchain-contract.js";
+import {
+  canAdmitSelfDogfoodLockEvaluation,
+  contractForSelfDogfoodEvaluation,
+  resolveSelfDogfoodMajor,
+} from "../packages/core/self-dogfood-version.js";
 import { generateChannelBuildWorkflow } from "./generate-channel-build-workflow.mjs";
 import {
   generateChannelPromotionWorkflow,
@@ -138,13 +143,12 @@ const selfDogfoodAlphaLock = JSON.parse(
 const currentBuildchainContract = JSON.parse(
   fs.readFileSync(path.join(root, "dist/site/buildchain-contract.json"), "utf8"),
 );
-const selfDogfoodMajor = String(rootPackage.version || "").match(/^(\d+)\./)?.[1];
-if (!selfDogfoodMajor) {
-  throw new Error("root package version must expose a numeric major for self-dogfood");
-}
-if (selfDogfoodAlphaLock.buildchain?.ref !== `v${selfDogfoodMajor}-alpha`) {
-  throw new Error("Buildchain self-dogfood alpha lock must target the current major alpha ref");
-}
+const selfDogfoodMajorResolution = resolveSelfDogfoodMajor({
+  packageVersion: rootPackage.version,
+  alphaRef: selfDogfoodAlphaLock.buildchain?.ref,
+  majorBootstrap: process.env.BUILDCHAIN_MAJOR_VERSION_BOOTSTRAP === "true",
+});
+const selfDogfoodMajor = String(selfDogfoodMajorResolution.workflowMajor);
 if (!/^[0-9a-f]{40}$/.test(selfDogfoodAlphaLock.buildchain?.resolvedSha || "")) {
   throw new Error("Buildchain self-dogfood alpha lock must record an exact accepted SHA");
 }
@@ -153,12 +157,20 @@ if (selfDogfoodAlphaLock.buildchain?.compatibilityPolicy !== "major-compatible")
 }
 const selfDogfoodAlphaEvaluation = evaluateBuildchainContractLock({
   lock: selfDogfoodAlphaLock,
-  current: currentBuildchainContract,
+  current: contractForSelfDogfoodEvaluation({
+    currentContract: currentBuildchainContract,
+    majorResolution: selfDogfoodMajorResolution,
+  }),
   runtimeRef: `v${selfDogfoodMajor}-alpha`,
   runtimeSha: "current-development-contract",
   runtimeClass: "alpha",
 });
-if (!selfDogfoodAlphaEvaluation.compatible) {
+if (
+  !canAdmitSelfDogfoodLockEvaluation({
+    evaluation: selfDogfoodAlphaEvaluation,
+    majorResolution: selfDogfoodMajorResolution,
+  })
+) {
   throw new Error("Buildchain self-dogfood alpha lock requires review after a breaking contract change");
 }
 for (const requiredSnippet of [

package/scripts/generate-site-bundle.mjs

@@ -329,6 +329,7 @@ const manualMetaById = new Map(Object.entries({
   "controller-evidence": { capabilityGroup: "reusable-build", audience: ["consumer", "release-operator", "agent"], maturity: "draft", order: 205 },
   "binary-distribution": { capabilityGroup: "release-passport-trust", audience: ["release-operator", "agent"], maturity: "stable", order: 110 },
   "publish-transaction": { capabilityGroup: "release-passport-trust", audience: ["release-operator"], maturity: "stable", order: 120 },
+  "release-activation-transaction": { capabilityGroup: "release-passport-trust", audience: ["release-operator", "agent"], maturity: "preview", order: 125 },
   "release-candidate": { capabilityGroup: "reusable-build", audience: ["release-operator", "consumer"], maturity: "stable", order: 130 },
   "stable-candidate-patrol": { capabilityGroup: "governance-versioning", audience: ["release-operator", "consumer"], maturity: "preview", order: 135 },
   "observed-evidence-patrol": { capabilityGroup: "governance-versioning", audience: ["release-operator", "consumer", "agent"], maturity: "preview", order: 140 },
@@ -519,6 +520,7 @@ function nodeApiMeta(exportName) {
     "./release-candidate": { group: "reusable-build", summary: "PR-stage release-candidate artifact, passport, and promote-only resolver APIs." },
     "./stable-candidate-ledger": { group: "governance-versioning", summary: "Immutable alpha candidate ledger, qualification, revocation, selection, and exact stable source-lock APIs." },
     "./release-propagation": { group: "site-and-propagation", summary: "Release propagation graph, plan, and exact upstream lock APIs." },
+    "./release-activation-transaction": { group: "release-passport-trust", summary: "Ordered cross-repository activation, exact receipt-set binding, retry, abort, rollback, and shadow-rehearsal APIs." },
     "./release-line-bootstrap": { group: "governance-versioning", summary: "Semver release-line bootstrap planning and version-state APIs." },
     "./buildchain-contract": { group: "governance-versioning", summary: "Runtime contract world and compatibility digest APIs for floating-ref drift checks." },
     "./controller-evidence": { group: "reusable-build", summary: "Project-independent controller descriptors, source/runtime-bound plans, receipts, aggregates, and validation APIs." },

package/scripts/installer-publication.mjs

@@ -77,11 +77,14 @@ function readAsset(artifactRoot, relativePath, expected) {
   const safePath = safeRelative(relativePath, "installer asset path");
   const absolute = path.resolve(artifactRoot, safePath);
   const rootPath = path.resolve(artifactRoot);
-  if (
-    !absolute.startsWith(`${rootPath}${path.sep}`) ||
-    !fs.statSync(absolute).isFile()
-  ) {
-    throw new Error(`installer asset is missing: ${safePath}`);
+  if (!absolute.startsWith(`${rootPath}${path.sep}`)) {
+    throw new Error(`installer asset escapes artifact root: ${safePath}`);
+  }
+  const stat = fs.lstatSync(absolute);
+  if (!stat.isFile() || stat.isSymbolicLink()) {
+    throw new Error(
+      `installer asset must be a regular non-symlink file: ${safePath}`,
+    );
   }
   const bytes = fs.readFileSync(absolute);
   const observed = {
@@ -164,6 +167,13 @@ export function validateInstallerPublication({ publication, artifactRoot }) {
       if (!Number.isSafeInteger(asset.size) || asset.size < 1) {
         throw new Error(`${asset.name}.size is invalid`);
       }
+      const expectedContentType =
+        asset.name === "install.sh"
+          ? "text/x-shellscript; charset=utf-8"
+          : "text/plain; charset=utf-8";
+      if (asset.contentType !== expectedContentType) {
+        throw new Error(`${asset.name}.contentType is invalid`);
+      }
       const immutable = readAsset(
         artifactRoot,
         `${immutablePath}/${asset.name}`,