@kungfu-tech/buildchain 3.0.7 → 3.0.8

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

@@ -80,3 +80,211 @@ export function assertDryRun(result, label) {
     throw new Error(`${label} did not return DryRunOperation`);
   }
 }
+
+export function assertAllowedPolicySimulation(
+  plan,
+  profile,
+  principalArn,
+  actionName,
+) {
+  if (!/^arn:aws:iam::\d{12}:(?:user|role)\/.+/.test(principalArn || "")) {
+    throw new Error(
+      "AWS allocation policy simulation requires an IAM user or role principal ARN",
+    );
+  }
+  const contextEntries = [
+    `ContextKeyName=aws:RequestedRegion,ContextKeyValues=${plan.aws.region},ContextKeyType=string`,
+    ...plan.aws.hostTags.map(
+      ({ Key, Value }) =>
+        `ContextKeyName=aws:RequestTag/${Key},ContextKeyValues=${Value},ContextKeyType=string`,
+    ),
+  ];
+  const evaluation = awsJson(
+    plan,
+    profile,
+    [
+      "iam",
+      "simulate-principal-policy",
+      "--policy-source-arn",
+      principalArn,
+      "--action-names",
+      actionName,
+      "--resource-arns",
+      "*",
+      "--context-entries",
+      ...contextEntries,
+      "--output",
+      "json",
+    ],
+    `${actionName} IAM policy simulation`,
+  ).EvaluationResults?.[0];
+  if (
+    evaluation?.EvalActionName !== actionName ||
+    evaluation?.EvalDecision !== "allowed" ||
+    (evaluation.MissingContextValues || []).length !== 0
+  ) {
+    throw new Error(`${actionName} IAM policy simulation did not allow allocation`);
+  }
+  return {
+    actionName,
+    decision: evaluation.EvalDecision,
+    principalArn,
+  };
+}
+
+function sameJson(left, right) {
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+
+function sameDimensionSet(observed, expected) {
+  return (
+    Array.isArray(observed) &&
+    observed.length === expected.length &&
+    expected.every((entry) =>
+      observed.some((candidate) => sameJson(candidate, entry)),
+    )
+  );
+}
+
+export function assertMacosBudgetLaunchGate(plan, profile) {
+  const identity = awsJson(
+    plan,
+    profile,
+    ["sts", "get-caller-identity", "--output", "json"],
+    "AWS account identity preflight",
+  );
+  if (identity.Account !== plan.account.id) {
+    throw new Error("AWS account identity mismatch");
+  }
+  const workflow = ghJson(
+    [
+      "api",
+      `repos/${plan.repository}/actions/workflows/${plan.github.workflowId}`,
+    ],
+    undefined,
+    "GitHub macOS workflow preflight",
+  );
+  if (workflow.state !== plan.github.requiredState) {
+    throw new Error(
+      `macOS workflow must be ${plan.github.requiredState}; observed ${workflow.state || "unknown"}`,
+    );
+  }
+  const stack = awsJson(
+    plan,
+    profile,
+    [
+      "cloudformation",
+      "describe-stacks",
+      "--stack-name",
+      plan.aws.controlPlaneStack,
+      "--output",
+      "json",
+    ],
+    "macOS control-plane stack preflight",
+  ).Stacks?.[0];
+  if (!stack || !/(?:CREATE|UPDATE)_COMPLETE$/.test(stack.StackStatus || "")) {
+    throw new Error("macOS control-plane stack is not complete");
+  }
+  const topicArn = (stack.Outputs || []).find(
+    (entry) => entry.OutputKey === "KillSwitchTopic",
+  )?.OutputValue;
+  if (!/^arn:aws:sns:/.test(String(topicArn || ""))) {
+    throw new Error("macOS Budget kill-switch topic readback failed");
+  }
+  const budget = awsJson(
+    plan,
+    profile,
+    [
+      "budgets",
+      "describe-budget",
+      "--account-id",
+      plan.account.id,
+      "--budget-name",
+      plan.safety.budget.name,
+      "--show-filter-expression",
+      "--output",
+      "json",
+    ],
+    "macOS Budget preflight",
+  ).Budget;
+  const expectedDimensions = [
+    ["USAGE_TYPE", plan.safety.budget.dimensionFilter.usageTypes],
+    ["OPERATION", [plan.safety.budget.dimensionFilter.operation]],
+    ["REGION", plan.safety.budget.dimensionFilter.regions],
+  ].map(([Key, Values]) => ({
+    Dimensions: { Key, Values, MatchOptions: ["EQUALS"] },
+  }));
+  if (
+    !budget ||
+    budget.BudgetName !== plan.safety.budget.name ||
+    Number(budget.BudgetLimit?.Amount) !== plan.safety.budget.limitUsd ||
+    budget.BudgetLimit?.Unit !== "USD" ||
+    budget.BudgetType !== "COST" ||
+    !sameJson(budget.Metrics, plan.safety.budget.metrics) ||
+    !sameDimensionSet(budget.FilterExpression?.And, expectedDimensions)
+  ) {
+    throw new Error("macOS Budget identity or dimension filter mismatch");
+  }
+  const notifications = awsJson(
+    plan,
+    profile,
+    [
+      "budgets",
+      "describe-notifications-for-budget",
+      "--account-id",
+      plan.account.id,
+      "--budget-name",
+      plan.safety.budget.name,
+      "--output",
+      "json",
+    ],
+    "macOS Budget notifications preflight",
+  ).Notifications;
+  const thresholds = (notifications || [])
+    .filter(
+      (entry) =>
+        entry.NotificationType === "ACTUAL" &&
+        (entry.ThresholdType || "PERCENTAGE") === "PERCENTAGE",
+    )
+    .map((entry) => Number(entry.Threshold))
+    .sort((left, right) => left - right);
+  if (!sameJson(thresholds, plan.safety.budget.requiredActualThresholds)) {
+    throw new Error("macOS Budget notification thresholds mismatch");
+  }
+  for (const notification of notifications) {
+    const subscribers = awsJson(
+      plan,
+      profile,
+      [
+        "budgets",
+        "describe-subscribers-for-notification",
+        "--account-id",
+        plan.account.id,
+        "--budget-name",
+        plan.safety.budget.name,
+        "--notification",
+        JSON.stringify(notification),
+        "--output",
+        "json",
+      ],
+      `macOS Budget ${notification.Threshold}% subscribers preflight`,
+    ).Subscribers;
+    if (
+      !(subscribers || []).some(
+        (entry) =>
+          entry.SubscriptionType === "SNS" && entry.Address === topicArn,
+      )
+    ) {
+      throw new Error("macOS Budget SNS subscriber mismatch");
+    }
+  }
+  return {
+    accountId: identity.Account,
+    principalArn: identity.Arn,
+    workflowState: workflow.state,
+    stackStatus: stack.StackStatus,
+    budgetName: budget.BudgetName,
+    budgetDimensionFilter: plan.safety.budget.dimensionFilter,
+    budgetThresholds: thresholds,
+  };
+}

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

@@ -11,9 +11,12 @@ import {
   macosReleaseHostsArgs,
   macosRunInstancesArgs,
 } from "./aws-macos-jit-controller-core.mjs";
+import { MACOS_EC2_JIT_REGIONS } from "./aws-macos-jit-core.mjs";
 import { executeMacosJitJob } from "./aws-macos-jit-job-controller.mjs";
 import {
   assertDryRun,
+  assertAllowedPolicySimulation,
+  assertMacosBudgetLaunchGate,
   assertOwnership,
   awsArgs,
   awsJson,
@@ -32,6 +35,7 @@ function flag(name) {
 }
 
 function assertCampaignLaunchPreflight(plan, profile) {
+  const launchGate = assertMacosBudgetLaunchGate(plan, profile);
   const commit = ghJson(
     ["api", `repos/${plan.repository}/commits/${plan.source.sha}`],
     undefined,
@@ -40,43 +44,51 @@ function assertCampaignLaunchPreflight(plan, profile) {
   if (String(commit.sha || "").toLowerCase() !== plan.source.sha) {
     throw new Error("GitHub did not resolve the exact campaign source SHA");
   }
-  const activeHosts =
-    awsJson(
-      plan,
+  const regionalPlans = Object.keys(MACOS_EC2_JIT_REGIONS).map((region) => ({
+    ...plan,
+    aws: { ...plan.aws, region },
+  }));
+  const activeHosts = regionalPlans.flatMap(
+    (regionalPlan) =>
+      awsJson(
+        regionalPlan,
+        profile,
+        [
+          "ec2",
+          "describe-hosts",
+          "--filter",
+          "Name=tag:kungfu:plane,Values=aws-us-elastic-runner-burst",
+          "Name=tag:kungfu:provider,Values=macos-ec2-jit",
+          "Name=state,Values=available,pending,under-assessment",
+          "--output",
+          "json",
+        ],
+        `active macOS JIT host preflight in ${regionalPlan.aws.region}`,
+      ).Hosts || [],
+  );
+  if (activeHosts.length >= plan.safety.activeHostCeiling) {
+    throw new Error("macOS JIT active Dedicated Host ceiling is reached");
+  }
+  const instances = regionalPlans.flatMap((regionalPlan) => {
+    const active = awsJson(
+      regionalPlan,
       profile,
       [
         "ec2",
-        "describe-hosts",
-        "--filter",
+        "describe-instances",
+        "--filters",
         "Name=tag:kungfu:plane,Values=aws-us-elastic-runner-burst",
         "Name=tag:kungfu:provider,Values=macos-ec2-jit",
-        "Name=state,Values=available,pending,under-assessment",
+        "Name=instance-state-name,Values=pending,running,stopping,stopped,shutting-down",
         "--output",
         "json",
       ],
-      "active macOS JIT host preflight",
-    ).Hosts || [];
-  if (activeHosts.length >= plan.safety.activeHostCeiling) {
-    throw new Error("macOS JIT active Dedicated Host ceiling is reached");
-  }
-  const active = awsJson(
-    plan,
-    profile,
-    [
-      "ec2",
-      "describe-instances",
-      "--filters",
-      "Name=tag:kungfu:plane,Values=aws-us-elastic-runner-burst",
-      "Name=tag:kungfu:provider,Values=macos-ec2-jit",
-      "Name=instance-state-name,Values=pending,running,stopping,stopped,shutting-down",
-      "--output",
-      "json",
-    ],
-    "active macOS JIT instance preflight",
-  );
-  const instances = (active.Reservations || []).flatMap(
-    (reservation) => reservation.Instances || [],
-  );
+      `active macOS JIT instance preflight in ${regionalPlan.aws.region}`,
+    );
+    return (active.Reservations || []).flatMap(
+      (reservation) => reservation.Instances || [],
+    );
+  });
   if (instances.length >= plan.safety.activeInstanceCeiling) {
     throw new Error("macOS JIT active instance ceiling is reached");
   }
@@ -120,6 +132,7 @@ function assertCampaignLaunchPreflight(plan, profile) {
     );
   }
   return {
+    ...launchGate,
     exactCommit: plan.source.sha,
     activeHosts: activeHosts.length,
     activeInstances: instances.length,
@@ -136,12 +149,11 @@ export function executeMacosJitCampaignLaunch(plan, { profile = "" } = {}) {
     throw new Error("macOS JIT campaign launch plan contract is invalid");
   }
   const preflight = assertCampaignLaunchPreflight(plan, profile);
-  assertDryRun(
-    commandResult(
-      "aws",
-      awsArgs(plan, profile, macosAllocateHostsArgs(plan, { dryRun: true })),
-    ),
-    "EC2 AllocateHosts DryRun",
+  const allocationPermission = assertAllowedPolicySimulation(
+    plan,
+    profile,
+    preflight.principalArn,
+    "ec2:AllocateHosts",
   );
   const hostId = awsJson(
     plan,
@@ -223,8 +235,8 @@ export function executeMacosJitCampaignLaunch(plan, { profile = "" } = {}) {
       imageId: instance.ImageId,
       launchTime: new Date(instance.LaunchTime).toISOString(),
     },
-    preflight,
-    dryRuns: ["AllocateHosts:DryRunOperation", "RunInstances:DryRunOperation"],
+    preflight: { ...preflight, allocationPermission },
+    dryRuns: ["RunInstances:DryRunOperation"],
     planDigest: plan.digest,
   };
 }
@@ -462,6 +474,7 @@ export function executeMacosJitCampaignClose(plan, { profile = "" } = {}) {
 function commonValues(execute) {
   return {
     execute,
+    accountId: arg("account-id"),
     repository: arg("repository", "kungfu-systems/kungfu"),
     campaignId: arg("campaign-id"),
     sourceSha: arg("source-sha"),

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

@@ -2,13 +2,29 @@ import { digest } from "./aws-runner-burst-core.mjs";
 
 export const AWS_MACOS_JIT_CONTRACT = "kungfu-buildchain-aws-macos-jit/v1";
 
+export const MACOS_EC2_JIT_REGIONS = Object.freeze({
+  "us-east-1": Object.freeze({
+    stack: "kungfu-buildchain-macos-jit",
+  }),
+  "us-east-2": Object.freeze({
+    stack: "kungfu-buildchain-macos-jit-us-east-2",
+  }),
+});
+
 export const MACOS_EC2_JIT = Object.freeze({
   phase: "macos-ec2-jit",
   region: "us-east-1",
   repository: "kungfu-systems/kungfu",
+  workflowId: "323846928",
   stack: "kungfu-buildchain-macos-jit",
+  budgetName: "kungfu-buildchain-macos-jit-actual-spend",
+  budgetUsageTypes: Object.freeze([
+    "HostUsage:mac2",
+    "USE2-HostUsage:mac2",
+  ]),
+  budgetOperation: "RunInstances",
   instanceType: "mac2.metal",
-  pricePerHourUsd: 0.6498,
+  pricePerHourUsd: 0.65,
   minimumHostAllocationHours: 24,
   maximumHostAllocationHours: 30,
   maxAcceptedHosts: 1,
@@ -23,6 +39,22 @@ export const MACOS_EC2_JIT = Object.freeze({
   jitParameterPrefix: "/kungfu/burst/macos/",
 });
 
+export function macosJitRegionConfig(region) {
+  const resolved = String(region || MACOS_EC2_JIT.region).trim();
+  const config = MACOS_EC2_JIT_REGIONS[resolved];
+  if (!config) {
+    throw new Error(
+      `region must be one of ${Object.keys(MACOS_EC2_JIT_REGIONS).join(", ")}`,
+    );
+  }
+  return {
+    ...config,
+    budgetName: MACOS_EC2_JIT.budgetName,
+    budgetUsageTypes: MACOS_EC2_JIT.budgetUsageTypes,
+    budgetRegions: Object.keys(MACOS_EC2_JIT_REGIONS),
+  };
+}
+
 function exactSha(value, label) {
   const normalized = String(value || "")
     .trim()
@@ -323,8 +355,14 @@ export function verifyMacosEc2JitQualification({
   }
   let allocationHours = 0;
   try {
-    const allocatedAt = iso(hostLifecycle.allocatedAt, "hostLifecycle.allocatedAt");
-    const releasedAt = iso(hostLifecycle.releasedAt, "hostLifecycle.releasedAt");
+    const allocatedAt = iso(
+      hostLifecycle.allocatedAt,
+      "hostLifecycle.allocatedAt",
+    );
+    const releasedAt = iso(
+      hostLifecycle.releasedAt,
+      "hostLifecycle.releasedAt",
+    );
     allocationHours = elapsedHours(allocatedAt, releasedAt);
     if (
       hostLifecycle.status !== "passed" ||

package/scripts/buildchain-contract-lock.mjs

@@ -106,6 +106,9 @@ export function checkBuildchainContractLock({
     `- Runtime SHA: \`${runtimeSha || "(unknown)"}\``,
     `- Contract digest: \`${current.contractDigest}\``,
     `- Compatibility digest: \`${current.compatibilityDigest}\``,
+    `- Compatibility proof registry: \`${current.compatibilityProofRegistryRoot || "(legacy)"}\``,
+    `- Verification receipt: \`${evaluation.receiptRoot || "(not-required)"}\``,
+    evaluation.usedProofRoots?.length ? `- Used compatibility proofs: ${evaluation.usedProofRoots.map((root) => `\`${root}\``).join(", ")}` : "",
     evaluation.reasons?.length ? `- Reasons: ${evaluation.reasons.join("; ")}` : "",
     shouldIssue ? `- Drift issue body: \`${issueBodyPath}\`` : "",
   ].filter(Boolean).join("\n"));
@@ -117,6 +120,9 @@ export function checkBuildchainContractLock({
     "contract-lock-issue-body-file": shouldIssue ? issueBodyPath : "",
     "contract-digest": current.contractDigest,
     "contract-compatibility-digest": current.compatibilityDigest,
+    "contract-compatibility-proof-registry-root": current.compatibilityProofRegistryRoot || "",
+    "contract-compatibility-verification-receipt-root": evaluation.receiptRoot || "",
+    "contract-compatibility-proof-roots": (evaluation.usedProofRoots || []).join(","),
     "accepted-contract-digest": evaluation.accepted?.contractDigest || "",
     "accepted-buildchain-sha": evaluation.accepted?.resolvedSha || "",
     "current-buildchain-sha": runtimeSha || "",

package/scripts/dispatch-artifact-signing-authority.mjs

@@ -39,18 +39,15 @@ export async function resolveArtifactSigningAuthorityRuntime({
   const ref = resolveAuthorityDispatchRef(authorityRef);
   const encodedRef = ref.split("/").map(encodeURIComponent).join("/");
   const response = await requestImpl(
-    `/repos/${authorityRepo}/git/ref/heads/${encodedRef}`,
+    `/repos/${authorityRepo}/commits/${encodedRef}`,
     { token: required(token, "Buildchain authority dispatch token") },
   );
-  if (response?.object?.type !== "commit") {
+  const sha = String(response?.sha || "");
+  if (!/^[0-9a-f]{40}$/u.test(sha)) {
     throw new Error(
-      "Buildchain signing authority ref does not resolve to a commit",
+      "Buildchain signing authority ref must resolve to an exact commit SHA",
     );
   }
-  const sha = String(response.object.sha || "");
-  if (!/^[0-9a-f]{40}$/u.test(sha)) {
-    throw new Error("Buildchain signing authority runtime SHA must be exact");
-  }
   return { ref, sha };
 }
 

package/scripts/engineering-housekeeper-workflow.mjs

@@ -86,10 +86,11 @@ export function normalizeHousekeeperWorkflowOptions(options = {}) {
         process.env.HOUSEKEEPER_REPOSITORY ||
         process.env.GITHUB_REPOSITORY,
     ),
-    targetBranch: requiredString(
-      options.targetBranch || process.env.HOUSEKEEPER_TARGET_BRANCH,
-      "target-branch",
-    ).replace(/^refs\/heads\//, ""),
+    targetBranch: String(
+      options.targetBranch || process.env.HOUSEKEEPER_TARGET_BRANCH || "",
+    )
+      .trim()
+      .replace(/^refs\/heads\//, ""),
     staleDays: positiveInteger(
       options.staleDays ?? process.env.HOUSEKEEPER_STALE_DAYS,
       30,
@@ -108,6 +109,11 @@ export function normalizeHousekeeperWorkflowOptions(options = {}) {
       options.retainedPatterns ?? process.env.HOUSEKEEPER_RETAINED_PATTERNS,
       ["train/**", "authority/**"],
     ),
+    temporaryBranchPatterns: splitPatterns(
+      options.temporaryBranchPatterns ??
+        process.env.HOUSEKEEPER_TEMPORARY_BRANCH_PATTERNS,
+      ["feature/**", "fix/**", "chore/**", "docs/**", "ci/**", "refactor/**"],
+    ),
     stalePullRequestLabel: String(
       options.stalePullRequestLabel ??
         process.env.HOUSEKEEPER_STALE_PR_LABEL ??
@@ -137,6 +143,7 @@ function workflowPolicy(options) {
   return {
     protectedPatterns: options.protectedPatterns,
     retainedPatterns: options.retainedPatterns,
+    temporaryBranchPatterns: options.temporaryBranchPatterns,
     pullRequests: {
       reportStale: true,
       label: options.stalePullRequestLabel,
@@ -167,7 +174,7 @@ export function renderHousekeeperWorkflowReport(
     `Mode: \`${mode || "report"}\``,
     `Scope: \`${scope}\``,
     `Repository: \`${plan.repository}\``,
-    `Target ref: \`${plan.target.name}@${plan.target.headOid}\``,
+    `Primary mainline: \`${plan.target.name}@${plan.target.headOid}\``,
     `Observed at: \`${plan.observedAt}\``,
     `Plan root: \`${plan.planRoot}\``,
     `Receipt root: \`${receipt.receiptRoot}\``,
@@ -284,7 +291,7 @@ export async function applyHousekeeperWorkflowScope({
   }
   if (
     plan.repository !== options.repository ||
-    plan.target.name !== options.targetBranch
+    (options.targetBranch && plan.target.name !== options.targetBranch)
   ) {
     throw new Error(
       "plan repository or target branch does not match current workflow inputs",

package/scripts/generate-site-bundle.mjs

@@ -370,6 +370,7 @@ const manualMetaById = new Map(Object.entries({
   "publication-rehearsal": { capabilityGroup: "release-passport-trust", audience: ["release-operator", "agent", "maintainer"], maturity: "preview", order: 124 },
   "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 },
+  "release-train": { capabilityGroup: "governance-versioning", audience: ["release-operator", "consumer", "agent"], maturity: "preview", order: 132 },
   "stable-candidate-patrol": { capabilityGroup: "governance-versioning", audience: ["release-operator", "consumer"], maturity: "preview", order: 135 },
   "dev-qualification-patrol": { capabilityGroup: "governance-versioning", audience: ["release-operator", "consumer", "agent"], maturity: "preview", order: 136 },
   "dev-alpha-candidate-patrol": { capabilityGroup: "governance-versioning", audience: ["release-operator", "consumer", "agent"], maturity: "preview", order: 137 },
@@ -734,6 +735,7 @@ function buildSiteBundle() {
       "docs/kfd-support.md",
       "docs/reusable-build-surface.md",
       "docs/release-candidate.md",
+      "docs/release-train.md",
       "docs/stable-candidate-patrol.md",
       "docs/dev-qualification-patrol.md",
       "docs/dev-alpha-candidate-patrol.md",

package/scripts/site-capability-metadata.mjs

@@ -202,6 +202,7 @@ export function nodeApiMeta(exportName) {
     "./release-passport-contract": { group: "release-passport-trust", summary: "Standalone release passport JSON Schema, ownership/check manifest, and structural validation APIs." },
     "./release-candidate": { group: "reusable-build", summary: "PR-stage release-candidate artifact, passport, and promote-only resolver APIs." },
     "./release-candidate-recovery": { group: "release-passport-trust", summary: "Fail-closed verification and immutable receipts for reusing a successful sealed candidate run without rebuilding product payloads." },
+    "./release-train": { group: "governance-versioning", summary: "Frozen Release Cut identity, rooted Release Train transitions, Dev observations, supersession, replay, and legacy read compatibility 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." },