@kungfu-tech/buildchain 3.0.7 → 3.0.8

package/packages/core/engineering-housekeeper.js

@@ -8,6 +8,7 @@ export const HOUSEKEEPER_REASON_CODES = Object.freeze({
   ELIGIBLE_MERGED_BRANCH: "eligible.merged-branch",
   PROTECTED_BRANCH: "branch.protected",
   RETAINED_BRANCH: "branch.retained",
+  NOT_TEMPORARY_DEVELOPMENT: "branch.not-temporary-development",
   DEFAULT_BRANCH: "branch.default",
   TARGET_BRANCH: "branch.target",
   OPEN_PR_HEAD: "branch.open-pr-head",
@@ -28,6 +29,14 @@ export const HOUSEKEEPER_REASON_CODES = Object.freeze({
 export const DEFAULT_HOUSEKEEPER_POLICY = Object.freeze({
   protectedPatterns: ["dev/**", "alpha/**", "release/**", "publish-gate/**"],
   retainedPatterns: ["train/**", "authority/**"],
+  temporaryBranchPatterns: [
+    "feature/**",
+    "fix/**",
+    "chore/**",
+    "docs/**",
+    "ci/**",
+    "refactor/**",
+  ],
   pullRequests: Object.freeze({
     reportStale: true,
     label: "",
@@ -77,6 +86,10 @@ function normalizePolicy(policy = {}) {
       ...(policy.retainedPatterns ||
         DEFAULT_HOUSEKEEPER_POLICY.retainedPatterns),
     ].sort(),
+    temporaryBranchPatterns: [
+      ...(policy.temporaryBranchPatterns ||
+        DEFAULT_HOUSEKEEPER_POLICY.temporaryBranchPatterns),
+    ].sort(),
     pullRequests: {
       reportStale: policy.pullRequests?.reportStale !== false,
       label: String(policy.pullRequests?.label || ""),
@@ -102,6 +115,8 @@ export function classifyHousekeeperBranch(branch, policyInput = {}) {
     reasons.push(HOUSEKEEPER_REASON_CODES.PROTECTED_BRANCH);
   if (matchesAny(policy.retainedPatterns, branch.name))
     reasons.push(HOUSEKEEPER_REASON_CODES.RETAINED_BRANCH);
+  if (!matchesAny(policy.temporaryBranchPatterns, branch.name))
+    reasons.push(HOUSEKEEPER_REASON_CODES.NOT_TEMPORARY_DEVELOPMENT);
   if (branch.sourceRepository && branch.sourceRepository !== branch.repository)
     reasons.push(HOUSEKEEPER_REASON_CODES.CROSS_REPOSITORY);
   if ((branch.openPullRequestNumbers || []).length > 0)

package/packages/core/release-train.js

@@ -0,0 +1,520 @@
+// SPDX-License-Identifier: Apache-2.0
+
+import crypto from "node:crypto";
+
+export const RELEASE_CUT_CONTRACT = "kungfu-buildchain-release-cut/v1";
+export const RELEASE_TRAIN_CONTRACT = "kungfu-buildchain-release-train/v1";
+export const RELEASE_TRAIN_TRANSITION_CONTRACT =
+  "kungfu-buildchain-release-train-transition/v1";
+export const RELEASE_TRAIN_OBSERVATION_CONTRACT =
+  "kungfu-buildchain-release-train-observation/v1";
+export const LEGACY_DEV_ALPHA_CANDIDATE_STATE_SCHEMA =
+  "kungfu-buildchain-dev-alpha-candidate-state/v1";
+
+export const RELEASE_TRAIN_STATES = Object.freeze([
+  "preparing",
+  "building",
+  "repair-required",
+  "publication-blocked",
+  "publishable",
+  "superseded",
+  "terminal",
+]);
+
+export const RELEASE_TRAIN_SUPERSESSION_CAUSES = Object.freeze([
+  "incompatible-semantics",
+  "alpha-base-incompatibility",
+  "invalid-authority",
+  "severe-security",
+]);
+
+const SHA = /^[0-9a-f]{40}$/u;
+const ROOT = /^sha256:[0-9a-f]{64}$/u;
+const ABSENT_ROOT = `sha256:${"0".repeat(64)}`;
+const SUPERSESSION_CAUSES = new Set(RELEASE_TRAIN_SUPERSESSION_CAUSES);
+const TRANSITIONS = new Map([
+  ["preparing", new Set(["building", "repair-required", "superseded"])],
+  [
+    "building",
+    new Set([
+      "repair-required",
+      "publication-blocked",
+      "publishable",
+      "superseded",
+    ]),
+  ],
+  [
+    "repair-required",
+    new Set(["building", "publication-blocked", "superseded"]),
+  ],
+  [
+    "publication-blocked",
+    new Set(["repair-required", "publishable", "superseded"]),
+  ],
+  ["publishable", new Set(["terminal", "repair-required", "superseded"])],
+  ["superseded", new Set()],
+  ["terminal", new Set()],
+]);
+
+function canonical(value) {
+  if (Array.isArray(value)) return value.map(canonical);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, item]) => [key, canonical(item)]),
+    );
+  }
+  return value;
+}
+
+export function releaseTrainRoot(value) {
+  return `sha256:${crypto
+    .createHash("sha256")
+    .update(JSON.stringify(canonical(value)))
+    .digest("hex")}`;
+}
+
+function clone(value) {
+  return structuredClone(value);
+}
+
+function text(value, label) {
+  const normalized = String(value ?? "").trim();
+  if (!normalized) throw new Error(`${label} is required`);
+  return normalized;
+}
+
+function exactSha(value, label) {
+  const normalized = text(value, label).toLowerCase();
+  if (!SHA.test(normalized))
+    throw new Error(`${label} must be an exact 40-character Git SHA`);
+  return normalized;
+}
+
+function contentRoot(value, label) {
+  const normalized = text(value, label).toLowerCase();
+  if (!ROOT.test(normalized))
+    throw new Error(`${label} must be a sha256 content root`);
+  return normalized;
+}
+
+function positiveInteger(value, label) {
+  const normalized = Number(value);
+  if (!Number.isSafeInteger(normalized) || normalized < 1)
+    throw new Error(`${label} must be a positive integer`);
+  return normalized;
+}
+
+function timestamp(value, label) {
+  const normalized = text(value, label);
+  const milliseconds = Date.parse(normalized);
+  if (!Number.isFinite(milliseconds))
+    throw new Error(`${label} must be an ISO-8601 timestamp`);
+  const canonicalTimestamp = new Date(milliseconds).toISOString();
+  if (normalized !== canonicalTimestamp)
+    throw new Error(`${label} must be a canonical ISO-8601 timestamp`);
+  return normalized;
+}
+
+function repository(value) {
+  const normalized = text(value, "repository");
+  if (!/^[^/\s]+\/[^/\s]+$/u.test(normalized))
+    throw new Error("repository must be owner/repo");
+  return normalized;
+}
+
+function branch(value, label) {
+  const normalized = text(value, label).replace(/^refs\/heads\//u, "");
+  if (/\s/u.test(normalized))
+    throw new Error(`${label} must not contain spaces`);
+  return normalized;
+}
+
+function sortedRoots(values, label) {
+  if (!Array.isArray(values) || values.length === 0)
+    throw new Error(`${label} must be a non-empty array`);
+  const normalized = values.map((value, index) =>
+    contentRoot(value, `${label}[${index}]`),
+  );
+  const expected = [...new Set(normalized)].sort();
+  if (
+    normalized.length !== expected.length ||
+    normalized.some((value, index) => value !== expected[index])
+  ) {
+    throw new Error(`${label} must be sorted and duplicate-free`);
+  }
+  return normalized;
+}
+
+function assertExactFields(value, expected, label) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new Error(`${label} must be an object`);
+  const actual = Object.keys(value).sort();
+  const keys = [...expected].sort();
+  if (
+    actual.length !== keys.length ||
+    actual.some((key, index) => key !== keys[index])
+  ) {
+    throw new Error(`${label} has an invalid field set`);
+  }
+}
+
+function normalizeSupersession(value, generation) {
+  if (generation === 1) {
+    if (value !== null && value !== undefined)
+      throw new Error("generation 1 cannot supersede a prior Release Cut");
+    return null;
+  }
+  assertExactFields(value, ["cause", "priorCutRoot"], "supersession");
+  const cause = text(value.cause, "supersession.cause");
+  if (!SUPERSESSION_CAUSES.has(cause))
+    throw new Error(`unsupported Release Cut supersession cause: ${cause}`);
+  return {
+    cause,
+    priorCutRoot: contentRoot(value.priorCutRoot, "supersession.priorCutRoot"),
+  };
+}
+
+export function createReleaseCut(input = {}) {
+  const generation = positiveInteger(input.generation ?? 1, "generation");
+  const body = {
+    schemaVersion: 1,
+    contract: RELEASE_CUT_CONTRACT,
+    repository: repository(input.repository),
+    sourceBranch: branch(input.sourceBranch, "sourceBranch"),
+    targetBranch: branch(input.targetBranch, "targetBranch"),
+    originDevSha: exactSha(input.originDevSha, "originDevSha"),
+    candidateSha: exactSha(input.candidateSha, "candidateSha"),
+    candidateTreeSha: exactSha(input.candidateTreeSha, "candidateTreeSha"),
+    alphaBaseSha: exactSha(input.alphaBaseSha, "alphaBaseSha"),
+    buildchainRuntimeSha: exactSha(
+      input.buildchainRuntimeSha,
+      "buildchainRuntimeSha",
+    ),
+    generation,
+    authorityRoots: sortedRoots(input.authorityRoots, "authorityRoots"),
+    supersession: normalizeSupersession(input.supersession, generation),
+    createdAt: timestamp(input.createdAt, "createdAt"),
+  };
+  return { ...body, cutRoot: releaseTrainRoot(body) };
+}
+
+function initialState(releaseCut) {
+  const body = {
+    status: "preparing",
+    generation: releaseCut.generation,
+    priorStateRoot: ABSENT_ROOT,
+    transitionRoot: ABSENT_ROOT,
+  };
+  return { ...body, stateRoot: releaseTrainRoot(body) };
+}
+
+export function createReleaseTrain(input = {}) {
+  const releaseCut = createReleaseCut(input.releaseCut || input);
+  const identity = {
+    schemaVersion: 1,
+    contract: RELEASE_TRAIN_CONTRACT,
+    releaseCut,
+  };
+  return {
+    ...identity,
+    trainRoot: releaseTrainRoot(identity),
+    state: initialState(releaseCut),
+    transitions: [],
+    observations: [],
+  };
+}
+
+export function validateReleaseCut(cut) {
+  assertExactFields(
+    cut,
+    [
+      "schemaVersion",
+      "contract",
+      "repository",
+      "sourceBranch",
+      "targetBranch",
+      "originDevSha",
+      "candidateSha",
+      "candidateTreeSha",
+      "alphaBaseSha",
+      "buildchainRuntimeSha",
+      "generation",
+      "authorityRoots",
+      "supersession",
+      "createdAt",
+      "cutRoot",
+    ],
+    "Release Cut",
+  );
+  const normalized = createReleaseCut(cut);
+  if (cut.cutRoot !== normalized.cutRoot)
+    throw new Error("Release Cut root does not match its content");
+  return normalized;
+}
+
+function transitionRequest(input, train) {
+  const to = text(input.to, "transition.to");
+  if (!RELEASE_TRAIN_STATES.includes(to))
+    throw new Error(`unsupported Release Train state: ${to}`);
+  const expectedStateRoot = contentRoot(
+    input.expectedStateRoot,
+    "transition.expectedStateRoot",
+  );
+  const superseding = to === "superseded";
+  const cause = input.supersessionCause
+    ? text(input.supersessionCause, "transition.supersessionCause")
+    : "";
+  if (superseding && !SUPERSESSION_CAUSES.has(cause))
+    throw new Error("superseded transitions require an enumerated cause");
+  if (
+    !superseding &&
+    (cause || input.replacementCutRoot || input.replacementCandidateSha)
+  )
+    throw new Error(
+      "supersession fields are only valid for superseded transitions",
+    );
+  return {
+    contract: RELEASE_TRAIN_TRANSITION_CONTRACT,
+    trainRoot: train.trainRoot,
+    expectedStateRoot,
+    to,
+    event: text(input.event, "transition.event"),
+    reason: text(input.reason, "transition.reason"),
+    authorityRoots: sortedRoots(
+      input.authorityRoots,
+      "transition.authorityRoots",
+    ),
+    ...(superseding
+      ? {
+          supersessionCause: cause,
+          replacementCutRoot: contentRoot(
+            input.replacementCutRoot,
+            "transition.replacementCutRoot",
+          ),
+          replacementCandidateSha: exactSha(
+            input.replacementCandidateSha,
+            "transition.replacementCandidateSha",
+          ),
+        }
+      : {}),
+    recordedAt: timestamp(input.recordedAt, "transition.recordedAt"),
+  };
+}
+
+function applyTransition(train, input) {
+  const request = transitionRequest(input, train);
+  const requestRoot = releaseTrainRoot(request);
+  const last = train.transitions.at(-1);
+  if (last?.requestRoot === requestRoot) return train;
+  if (request.expectedStateRoot !== train.state.stateRoot)
+    throw new Error("Release Train transition compare-and-swap failed");
+  if (!TRANSITIONS.get(train.state.status)?.has(request.to))
+    throw new Error(
+      `invalid Release Train transition: ${train.state.status} -> ${request.to}`,
+    );
+  const transition = {
+    ...request,
+    from: train.state.status,
+    requestRoot,
+  };
+  transition.transitionRoot = releaseTrainRoot(transition);
+  const stateBody = {
+    status: request.to,
+    generation: train.releaseCut.generation,
+    priorStateRoot: train.state.stateRoot,
+    transitionRoot: transition.transitionRoot,
+  };
+  return {
+    ...train,
+    state: { ...stateBody, stateRoot: releaseTrainRoot(stateBody) },
+    transitions: [...train.transitions, transition],
+  };
+}
+
+export function transitionReleaseTrain(trainInput, input = {}) {
+  return applyTransition(validateReleaseTrain(trainInput), input);
+}
+
+function applyObservation(train, input) {
+  const body = {
+    contract: RELEASE_TRAIN_OBSERVATION_CONTRACT,
+    trainRoot: train.trainRoot,
+    observedDevSha: exactSha(input.observedDevSha, "observedDevSha"),
+    observedAt: timestamp(input.observedAt, "observedAt"),
+  };
+  const observation = { ...body, observationRoot: releaseTrainRoot(body) };
+  if (
+    train.observations.some(
+      (entry) => entry.observationRoot === observation.observationRoot,
+    )
+  ) {
+    return train;
+  }
+  return { ...train, observations: [...train.observations, observation] };
+}
+
+export function observeReleaseTrain(trainInput, input = {}) {
+  return applyObservation(validateReleaseTrain(trainInput), input);
+}
+
+export function validateReleaseTrain(input) {
+  if (!input || typeof input !== "object" || Array.isArray(input))
+    throw new Error("Release Train must be an object");
+  if (
+    input.contract !== RELEASE_TRAIN_CONTRACT ||
+    Number(input.schemaVersion) !== 1
+  ) {
+    throw new Error(`Release Train must use ${RELEASE_TRAIN_CONTRACT}`);
+  }
+  assertExactFields(
+    input,
+    [
+      "schemaVersion",
+      "contract",
+      "releaseCut",
+      "trainRoot",
+      "state",
+      "transitions",
+      "observations",
+    ],
+    "Release Train",
+  );
+  const releaseCut = validateReleaseCut(input.releaseCut);
+  const identity = {
+    schemaVersion: 1,
+    contract: RELEASE_TRAIN_CONTRACT,
+    releaseCut,
+  };
+  if (input.trainRoot !== releaseTrainRoot(identity))
+    throw new Error("Release Train root does not match its frozen Release Cut");
+  if (!RELEASE_TRAIN_STATES.includes(input.state?.status))
+    throw new Error("Release Train state is invalid");
+  assertExactFields(
+    input.state,
+    ["status", "generation", "priorStateRoot", "transitionRoot", "stateRoot"],
+    "Release Train state",
+  );
+  if (input.state.generation !== releaseCut.generation)
+    throw new Error(
+      "Release Train state generation drifted from its Release Cut",
+    );
+  const stateBody = {
+    status: input.state.status,
+    generation: input.state.generation,
+    priorStateRoot: contentRoot(
+      input.state.priorStateRoot,
+      "state.priorStateRoot",
+    ),
+    transitionRoot: contentRoot(
+      input.state.transitionRoot,
+      "state.transitionRoot",
+    ),
+  };
+  if (input.state.stateRoot !== releaseTrainRoot(stateBody))
+    throw new Error("Release Train state root does not match its content");
+  if (!Array.isArray(input.transitions) || !Array.isArray(input.observations))
+    throw new Error(
+      "Release Train transitions and observations must be arrays",
+    );
+  const replay = createReleaseTrain({ releaseCut });
+  let rebuilt = replay;
+  for (const [index, transition] of input.transitions.entries()) {
+    assertExactFields(
+      transition,
+      [
+        "contract",
+        "trainRoot",
+        "expectedStateRoot",
+        "to",
+        "event",
+        "reason",
+        "authorityRoots",
+        ...(transition.to === "superseded"
+          ? [
+              "supersessionCause",
+              "replacementCutRoot",
+              "replacementCandidateSha",
+            ]
+          : []),
+        "recordedAt",
+        "from",
+        "requestRoot",
+        "transitionRoot",
+      ],
+      `Release Train transition ${index}`,
+    );
+    rebuilt = applyTransition(rebuilt, transition);
+    const replayed = rebuilt.transitions.at(-1);
+    if (
+      rebuilt.transitions.length !== index + 1 ||
+      releaseTrainRoot(replayed) !== releaseTrainRoot(transition)
+    ) {
+      throw new Error(
+        "Release Train transition root does not match its content",
+      );
+    }
+  }
+  if (rebuilt.state.stateRoot !== input.state.stateRoot)
+    throw new Error(
+      "Release Train state chain does not replay to the current state",
+    );
+  for (const [index, observation] of input.observations.entries()) {
+    assertExactFields(
+      observation,
+      [
+        "contract",
+        "trainRoot",
+        "observedDevSha",
+        "observedAt",
+        "observationRoot",
+      ],
+      `Release Train observation ${index}`,
+    );
+    rebuilt = applyObservation(rebuilt, observation);
+    const replayed = rebuilt.observations.at(-1);
+    if (
+      rebuilt.observations.length !== index + 1 ||
+      releaseTrainRoot(replayed) !== releaseTrainRoot(observation)
+    ) {
+      throw new Error(
+        "Release Train observation root does not match its content",
+      );
+    }
+  }
+  if (rebuilt.observations.length !== input.observations.length)
+    throw new Error("Release Train observations must be unique");
+  return clone(input);
+}
+
+export function readReleaseTrain(input) {
+  if (input?.contract === RELEASE_TRAIN_CONTRACT) {
+    return {
+      format: "release-train-v1",
+      authoritative: true,
+      train: validateReleaseTrain(input),
+    };
+  }
+  if (input?.schema === LEGACY_DEV_ALPHA_CANDIDATE_STATE_SCHEMA) {
+    const generation = positiveInteger(input.generation, "legacy generation");
+    const candidate = input.activeCandidate || input.nextCandidate;
+    return {
+      format: "legacy-dev-alpha-candidate-state-v1",
+      authoritative: false,
+      train: null,
+      legacy: {
+        generation,
+        candidateSha: candidate
+          ? exactSha(candidate.sourceSha, "legacy candidate sourceSha")
+          : "",
+        stateRoot: ROOT.test(String(input.stateRoot || ""))
+          ? String(input.stateRoot)
+          : "",
+      },
+      reason:
+        "legacy candidate state can be read but cannot manufacture Release Cut authority roots",
+    };
+  }
+  throw new Error("unsupported Release Train record");
+}

package/scripts/aws-macos-jit-controller-core.mjs

@@ -3,6 +3,7 @@
 import { digest } from "./aws-runner-burst-core.mjs";
 import {
   MACOS_EC2_JIT,
+  macosJitRegionConfig,
   macosJitRunnerLabel,
   macosJitRunnerLabels,
 } from "./aws-macos-jit-core.mjs";
@@ -69,9 +70,7 @@ function commonAws(values) {
     /^us-[a-z]+-\d$/,
     "region",
   );
-  if (region !== MACOS_EC2_JIT.region) {
-    throw new Error(`region must be ${MACOS_EC2_JIT.region}`);
-  }
+  const regionConfig = macosJitRegionConfig(region);
   const instanceType = exact(
     values.instanceType || MACOS_EC2_JIT.instanceType,
     /^mac2\.metal$/,
@@ -80,13 +79,18 @@ function commonAws(values) {
   if (instanceType !== MACOS_EC2_JIT.instanceType) {
     throw new Error(`instanceType must be ${MACOS_EC2_JIT.instanceType}`);
   }
+  const availabilityZone = exact(
+    values.availabilityZone,
+    /^us-[a-z]+-\d[a-z]$/,
+    "availabilityZone",
+  );
+  if (!availabilityZone.startsWith(region)) {
+    throw new Error(`availabilityZone must belong to ${region}`);
+  }
   return {
     region,
-    availabilityZone: exact(
-      values.availabilityZone,
-      /^us-[a-z]+-\d[a-z]$/,
-      "availabilityZone",
-    ),
+    availabilityZone,
+    controlPlaneStack: regionConfig.stack,
     instanceType,
     amiId: exact(values.amiId, /^ami-[0-9a-f]+$/, "amiId"),
     amiName: exact(values.amiName, /^[A-Za-z0-9._-]+$/, "amiName"),
@@ -123,6 +127,7 @@ export function createMacosJitCampaignPlan(values = {}) {
   const id = campaignId(values.campaignId);
   const boundSource = source(values);
   const aws = commonAws(values);
+  const regionConfig = macosJitRegionConfig(aws.region);
   const tags = ownershipTags({ id, sourceSha: boundSource.sha });
   const createdAt = iso(values.createdAt, "createdAt");
   const plan = {
@@ -130,6 +135,13 @@ export function createMacosJitCampaignPlan(values = {}) {
     contract: AWS_MACOS_JIT_CONTROLLER_CONTRACT,
     kind: "campaign-launch-plan",
     repository: repository(values.repository),
+    account: {
+      id: exact(values.accountId, /^\d{12}$/, "accountId"),
+    },
+    github: {
+      workflowId: MACOS_EC2_JIT.workflowId,
+      requiredState: "disabled_manually",
+    },
     campaign: { id, createdAt },
     source: boundSource,
     aws: {
@@ -158,18 +170,29 @@ export function createMacosJitCampaignPlan(values = {}) {
       exactSourceRequired: true,
       activeHostCeiling: MACOS_EC2_JIT.maxAcceptedHosts,
       activeInstanceCeiling: 1,
-      awsDryRunRequiredBeforeAllocation: true,
+      awsPermissionSimulationRequiredBeforeAllocation: true,
       awsDryRunRequiredBeforeLaunch: true,
       retainHostOnInstanceLaunchFailure: true,
       minimumHostAllocationHours: MACOS_EC2_JIT.minimumHostAllocationHours,
       maximumHostAllocationHours: MACOS_EC2_JIT.maximumHostAllocationHours,
       cleanupOwner: "scheduled-card-scoped-reaper",
+      budget: {
+        name: regionConfig.budgetName,
+        limitUsd: MACOS_EC2_JIT.budgetLimitUsd,
+        metrics: ["UnblendedCost"],
+        dimensionFilter: {
+          usageTypes: regionConfig.budgetUsageTypes,
+          operation: MACOS_EC2_JIT.budgetOperation,
+          regions: regionConfig.budgetRegions,
+        },
+        requiredActualThresholds: [80, 95],
+      },
     },
   };
   return { ...plan, digest: digest(plan) };
 }
 
-export function macosAllocateHostsArgs(plan, { dryRun = false } = {}) {
+export function macosAllocateHostsArgs(plan) {
   if (
     plan?.contract !== AWS_MACOS_JIT_CONTROLLER_CONTRACT ||
     plan.kind !== "campaign-launch-plan"
@@ -196,7 +219,6 @@ export function macosAllocateHostsArgs(plan, { dryRun = false } = {}) {
     "--output",
     "json",
   ];
-  if (dryRun) args.splice(2, 0, "--dry-run");
   return args;
 }