@kungfu-tech/buildchain 3.0.5-alpha.1 → 3.0.5-alpha.2

package/dist/site/workflow-registry.json

@@ -126,6 +126,7 @@
         "checkout-cache-mode",
         "checkout-cache-reference-repository-template",
         "checkout-cache-timeout-seconds",
+        "checkout-history-mode",
         "compiler-cache-platforms-json",
         "compiler-cache-provider",
         "compiler-cache-required",
@@ -175,7 +176,7 @@
         "verify-command",
         "working-directory"
       ],
-      "inputCount": 82,
+      "inputCount": 83,
       "secrets": [
         "BUILDCHAIN_ARTIFACT_RELAY_S3_DOWNLOAD_ROLE_ARN",
         "BUILDCHAIN_ARTIFACT_RELAY_S3_ROLE_ARN",
@@ -1155,6 +1156,7 @@
         "checkout-cache-mode",
         "checkout-cache-reference-repository-template",
         "checkout-cache-timeout-seconds",
+        "checkout-history-mode",
         "compiler-cache-platforms-json",
         "compiler-cache-provider",
         "compiler-cache-required",
@@ -1204,7 +1206,7 @@
         "verify-command",
         "working-directory"
       ],
-      "inputCount": 85,
+      "inputCount": 86,
       "secrets": [
         "BUILDCHAIN_ARTIFACT_RELAY_S3_DOWNLOAD_ROLE_ARN",
         "BUILDCHAIN_ARTIFACT_RELAY_S3_ROLE_ARN",

package/docs/aws-us-elastic-runner-burst-plane.md

@@ -8,7 +8,7 @@ confidence: high
 sensitivity: public
 evidence_grade: A
 review_state: unreviewed
-last_reviewed: 2026-08-01
+last_reviewed: 2026-08-02
 ai_provenance:
   model_family: GPT-5
   product: Codex
@@ -143,14 +143,16 @@ The source-bound evidence and deterministic phase receipt are:
 
 The Windows phase uses the explicit `aws-us-ec2-windows-jit` runner preset.
 Its caller supplies one bounded label under
-`aws-us-ec2-windows-jit-<qualification-id>`, and Buildchain resolves exactly
-one Windows x64 native lane. The reusable trust gate still runs on a
-GitHub-hosted runner before the JIT label can select EC2.
+`aws-us-ec2-windows-jit-<campaign-id>-<qualification-id>`, and Buildchain
+resolves exactly one Windows x64 native lane. The reusable trust gate still
+runs on a GitHub-hosted runner before the JIT label can select EC2.
 
 The provider creates repository-level GitHub JIT configuration for
 `kungfu-systems/kungfu`. Its `labels` request must contain all four scheduling
 labels: `self-hosted`, `Windows`, `X64`, and the card-scoped
-`aws-us-ec2-windows-jit-<qualification-id>` label. GitHub's JIT endpoint does
+`aws-us-ec2-windows-jit-<campaign-id>-<qualification-id>` label. The workflow
+display title also carries both identities, allowing the launch controller to
+verify the queued run against its campaign plan. GitHub's JIT endpoint does
 not infer the default OS and architecture labels when they are omitted. The
 encoded configuration is never placed in EC2 user data, a tag, a command log,
 or an artifact. The operator writes it to a card-scoped SSM SecureString under
@@ -173,21 +175,104 @@ Each runner uses:
   security-group rule, no key pair, and no warm Auto Scaling capacity.
 
 Runner diagnostics and a redacted lifecycle record are uploaded to the
-provider's encrypted, private evidence bucket. The runner process exits after
-one job, Windows shuts down, and EC2's instance-initiated shutdown behavior is
-set to `terminate`. A five-minute reaper terminates card-owned stopped or
+provider's encrypted, private evidence bucket under the exact campaign, run,
+attempt, and instance identity. The runner process exits after one job, Windows
+shuts down, and EC2's instance-initiated shutdown behavior is set to
+`terminate`. A five-minute reaper terminates card-owned stopped or
 three-hour-old instances and deletes only their dedicated JIT parameter.
 
 At the 2026-07-29 AWS Price List rate of USD 1.45 per Windows
-`c7i.4xlarge` hour, six accepted three-hour instances reserve USD 26.10. The
-two-instance race envelope reserves another USD 8.70, producing a USD 34.80
-worst case below the dedicated USD 40 budget. Budget notifications at 80% and
-95% invoke the same card-scoped global kill switch.
-
-Qualification requires one runner-profile smoke, three trusted exact-source
-full Windows jobs, independent cancellation and timeout cleanup exercises, and
-zero repository runner, EC2 instance, disposable volume, min capacity, and
-desired capacity within 15 minutes of the final job.
+`c7i.4xlarge` hour, each accepted instance reserves its complete three-hour
+USD 4.35 fail-closed lifetime before `RunInstances`. A DynamoDB transaction
+binds the exact campaign and source, creates an idempotent run ledger entry,
+and atomically refuses a seventh accepted instance. Six accepted instances
+therefore reserve at most USD 26.10 under the dedicated USD 40 decision.
+
+The campaign starts unarmed and expires within 24 hours. Its `CONTROL` record
+can be created only once: a killed or expired campaign cannot be re-armed by
+the campaign tool. A budget notification or any instance lifetime violation
+persists `KILLED` before cleanup, so later workflow dispatches fail before a
+paid launch. Reservations are never refunded: a controller crash, ambiguous
+launch, or successful launch all remain charged to the campaign, favoring a
+false stop over an accidental budget overrun.
+
+The tag-filtered AWS Budget is defense in depth, not the authoritative launch
+gate. It is disabled by default because a linked account cannot activate a
+cost-allocation tag. Set `EnableTagFilteredBudget=true` only after the AWS
+Organizations management account has activated `kungfu:provider` and a Cost
+Explorer readback proves that `windows-ec2-jit` spend is visible. The DynamoDB
+reservation cap remains mandatory in either mode.
+
+Qualification requires one runner-profile smoke and three trusted exact-source
+full Windows jobs all bound to the same campaign, independent cancellation and
+timeout cleanup exercises, and zero repository runner, EC2 instance,
+disposable volume, min capacity, and desired capacity within 15 minutes of the
+final job.
+
+### Phase 2 campaign controller
+
+`scripts/aws-windows-jit-campaign.mjs` is the one-shot operator boundary.
+Without a mutation mode it emits the arm plan. `arm-campaign` requires the
+campaign id, exact source SHA, and state table to be repeated as confirmations,
+then creates `CONTROL` and `CAMPAIGN#<id>` with `attribute_not_exists`
+conditions. DynamoDB therefore refuses a second campaign in the same retained
+state table. The operator can always use `kill-campaign`; there is deliberately
+no clear or re-arm operation.
+
+Every `scripts/aws-windows-jit-controller.mjs --execute` call must provide the
+same `--campaign-id`, `--confirm-campaign-id`, `--state-table`, and
+`--confirm-state-table`. After the GitHub, AMI, active-instance, SSM, and EC2
+DryRun checks pass, the controller
+atomically reserves one run. Duplicate run-attempt-qualification identities,
+source mismatch, expiry, `KILLED`, the seventh accepted instance, or a
+reservation over the USD 40 ceiling all fail closed before `RunInstances`.
+
+Example dry-run and arm boundary (do not execute without a new campaign budget
+decision):
+
+```bash
+windows_campaign=win-REPLACE_WITH_CAMPAIGN_ID
+windows_source=REPLACE_WITH_EXACT_40_CHARACTER_SHA
+windows_state_table=REPLACE_WITH_CAMPAIGN_STATE_TABLE
+windows_expires_at=REPLACE_WITH_ISO_TIMESTAMP_WITHIN_24_HOURS
+
+node scripts/aws-windows-jit-campaign.mjs plan-arm \
+  --campaign-id "$windows_campaign" \
+  --source-sha "$windows_source" \
+  --state-table "$windows_state_table" \
+  --expires-at "$windows_expires_at"
+
+node scripts/aws-windows-jit-campaign.mjs arm-campaign \
+  --campaign-id "$windows_campaign" \
+  --confirm-campaign-id "$windows_campaign" \
+  --source-sha "$windows_source" \
+  --confirm-source-sha "$windows_source" \
+  --state-table "$windows_state_table" \
+  --confirm-state-table "$windows_state_table" \
+  --expires-at "$windows_expires_at"
+```
+
+Arming creates a permanent one-shot control record and admits up to six paid
+instances. Its rollback is fail-closed, not deletion: `kill-campaign` first
+persists `KILLED`, then publishes to the dedicated SNS topic so the reaper
+terminates active card-owned instances and removes their JIT parameters. The
+command is idempotent, but the operator must read back DynamoDB, EC2, SSM, and
+GitHub runners before treating cleanup as complete:
+
+```bash
+windows_kill_topic=REPLACE_WITH_DEDICATED_KILL_SWITCH_TOPIC_ARN
+
+node scripts/aws-windows-jit-campaign.mjs kill-campaign \
+  --campaign-id "$windows_campaign" \
+  --confirm-campaign-id "$windows_campaign" \
+  --source-sha "$windows_source" \
+  --confirm-source-sha "$windows_source" \
+  --state-table "$windows_state_table" \
+  --confirm-state-table "$windows_state_table" \
+  --kill-switch-topic "$windows_kill_topic" \
+  --confirm-kill-switch-topic "$windows_kill_topic" \
+  --reason operator-kill
+```
 
 ## Phase 3 contract
 

package/docs/reusable-build-surface.md

@@ -439,6 +439,7 @@ jobs:
       checkout-cache-timeout-seconds: 60
       checkout-cache-github-timeout-seconds: 600
       checkout-cache-fetch-attempts: 3
+      checkout-history-mode: shallow
 ```
 
 `checkout-cache-mode` accepts:
@@ -449,6 +450,14 @@ jobs:
 | `auto`    | Try the trusted cache first; on miss, record the miss and fall back according to `checkout-cache-fallback`. |
 | `require` | Require the cache to provide the locked commit and fail before lifecycle work if unavailable.               |
 
+`checkout-history-mode` defaults to `shallow`, preserving the bounded single-
+commit transport used by ordinary builds. Set it to `full` only when a
+consumer gate must inspect source ancestry, for example when an Alpha pull
+request qualifies GitHub's synthetic merge ref while retained evidence is
+bound to an ancestor of the source-lock head. Full mode still verifies the
+resolved immutable `HEAD` and tree; it changes only whether the advertised
+source ref is fetched with depth one or with its reachable history.
+
 The cache can be a local/LAN mirror URL template or a runner-local bare
 reference repository template. Templates support `{owner}`, `{repo}`,
 `{repository}`, `{repositorySlug}`, and `{sha}`. The workflow also reads

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "3.0.5-alpha.1",
+  "version": "3.0.5-alpha.2",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",

package/scripts/aws-windows-jit-campaign-core.mjs

@@ -0,0 +1,241 @@
+// SPDX-License-Identifier: Apache-2.0
+
+import {
+  WINDOWS_EC2_JIT,
+  windowsJitCampaignId,
+} from "./aws-windows-jit-core.mjs";
+
+export const AWS_WINDOWS_JIT_CAMPAIGN_CONTRACT =
+  "kungfu-buildchain-aws-windows-jit-campaign/v1";
+
+function exact(value, pattern, label) {
+  const normalized = String(value || "").trim();
+  if (!pattern.test(normalized)) throw new Error(`${label} is invalid`);
+  return normalized;
+}
+
+function exactSha(value) {
+  return exact(value, /^[0-9a-f]{40}$/i, "sourceSha").toLowerCase();
+}
+
+function epoch(value, label) {
+  const milliseconds = new Date(value || "").getTime();
+  if (!Number.isFinite(milliseconds)) {
+    throw new Error(`${label} must be an ISO timestamp`);
+  }
+  return Math.floor(milliseconds / 1000);
+}
+
+function tableName(value) {
+  return exact(
+    value,
+    /^kungfu-buildchain-windows-jit(?:-[A-Za-z0-9_.-]+)?$/,
+    "stateTable",
+  );
+}
+
+function number(value) {
+  return { N: String(value) };
+}
+
+function string(value) {
+  return { S: String(value) };
+}
+
+function runKey(plan) {
+  return `RUN#${plan.github.runId}#${plan.github.runAttempt}#${plan.github.qualificationId}`;
+}
+
+export function createWindowsJitCampaignArmPlan(values = {}) {
+  const armedAt = epoch(values.armedAt, "armedAt");
+  const expiresAt = epoch(values.expiresAt, "expiresAt");
+  if (expiresAt <= armedAt || expiresAt - armedAt > 86400) {
+    throw new Error("campaign expiry must be within 24 hours after arming");
+  }
+  const reservationUsd =
+    (WINDOWS_EC2_JIT.pricePerHourUsd *
+      WINDOWS_EC2_JIT.maximumInstanceLifetimeMinutes) /
+    60;
+  return {
+    schemaVersion: 1,
+    contract: AWS_WINDOWS_JIT_CAMPAIGN_CONTRACT,
+    kind: "campaign-arm-plan",
+    campaign: {
+      id: windowsJitCampaignId(values.campaignId),
+      armedAt,
+      expiresAt,
+    },
+    source: { sha: exactSha(values.sourceSha) },
+    aws: {
+      region: exact(
+        values.region || WINDOWS_EC2_JIT.region,
+        /^us-[a-z]+-\d$/,
+        "region",
+      ),
+      stateTable: tableName(values.stateTable),
+    },
+    limits: {
+      maxAcceptedInstances: WINDOWS_EC2_JIT.maxAcceptedInstances,
+      reservationUsd,
+      budgetLimitUsd: WINDOWS_EC2_JIT.budgetLimitUsd,
+    },
+  };
+}
+
+export function windowsCampaignArmItems(plan) {
+  if (plan?.contract !== AWS_WINDOWS_JIT_CAMPAIGN_CONTRACT) {
+    throw new Error("Windows JIT campaign arm plan contract is invalid");
+  }
+  const table = plan.aws.stateTable;
+  const campaignPk = `CAMPAIGN#${plan.campaign.id}`;
+  return [
+    {
+      Put: {
+        TableName: table,
+        Item: {
+          pk: string("CONTROL"),
+          state: string("ARMED"),
+          campaign_id: string(plan.campaign.id),
+          source_sha: string(plan.source.sha),
+          armed_at: number(plan.campaign.armedAt),
+          expires_epoch: number(plan.campaign.expiresAt),
+        },
+        ConditionExpression: "attribute_not_exists(pk)",
+      },
+    },
+    {
+      Put: {
+        TableName: table,
+        Item: {
+          pk: string(campaignPk),
+          state: string("ARMED"),
+          source_sha: string(plan.source.sha),
+          accepted_instances: number(0),
+          reserved_usd: number(0),
+          max_accepted_instances: number(plan.limits.maxAcceptedInstances),
+          reservation_usd: number(plan.limits.reservationUsd),
+          budget_limit_usd: number(plan.limits.budgetLimitUsd),
+          armed_at: number(plan.campaign.armedAt),
+          expires_epoch: number(plan.campaign.expiresAt),
+        },
+        ConditionExpression: "attribute_not_exists(pk)",
+      },
+    },
+  ];
+}
+
+export function windowsCampaignReservationItems(plan, observedAt) {
+  const now = epoch(observedAt, "observedAt");
+  const runPk = runKey(plan);
+  const campaignPk = `CAMPAIGN#${plan.campaign.id}`;
+  const maxAccepted = plan.safety.campaignAcceptedInstanceCeiling;
+  const reservation = plan.safety.campaignReservationUsd;
+  return [
+    {
+      ConditionCheck: {
+        TableName: plan.aws.stateTable,
+        Key: { pk: string("CONTROL") },
+        ConditionExpression:
+          "#state = :armed AND campaign_id = :campaign AND source_sha = :source AND expires_epoch >= :now",
+        ExpressionAttributeNames: { "#state": "state" },
+        ExpressionAttributeValues: {
+          ":armed": string("ARMED"),
+          ":campaign": string(plan.campaign.id),
+          ":source": string(plan.source.sha),
+          ":now": number(now),
+        },
+      },
+    },
+    {
+      Put: {
+        TableName: plan.aws.stateTable,
+        Item: {
+          pk: string(runPk),
+          state: string("RESERVED"),
+          campaign_id: string(plan.campaign.id),
+          source_sha: string(plan.source.sha),
+          github_run_id: string(plan.github.runId),
+          github_run_attempt: string(plan.github.runAttempt),
+          qualification_id: string(plan.github.qualificationId),
+          reserved_usd: number(reservation),
+          observed_at: number(now),
+          expires_at: number(now + 1209600),
+        },
+        ConditionExpression: "attribute_not_exists(pk)",
+      },
+    },
+    {
+      Update: {
+        TableName: plan.aws.stateTable,
+        Key: { pk: string(campaignPk) },
+        UpdateExpression:
+          "ADD accepted_instances :one, reserved_usd :reservation SET updated_at = :now",
+        ConditionExpression:
+          "#state = :armed AND source_sha = :source AND accepted_instances < :max AND reserved_usd <= :remaining",
+        ExpressionAttributeNames: { "#state": "state" },
+        ExpressionAttributeValues: {
+          ":armed": string("ARMED"),
+          ":source": string(plan.source.sha),
+          ":one": number(1),
+          ":reservation": number(reservation),
+          ":max": number(maxAccepted),
+          ":remaining": number(
+            plan.safety.campaignBudgetLimitUsd - reservation,
+          ),
+          ":now": number(now),
+        },
+      },
+    },
+  ];
+}
+
+export function windowsCampaignMarkLaunchedArgs(plan, instanceId, observedAt) {
+  return [
+    "dynamodb",
+    "update-item",
+    "--table-name",
+    plan.aws.stateTable,
+    "--key",
+    JSON.stringify({ pk: string(runKey(plan)) }),
+    "--update-expression",
+    "SET #state = :launched, instance_id = :instance, launched_at = :now",
+    "--condition-expression",
+    "#state = :reserved",
+    "--expression-attribute-names",
+    JSON.stringify({ "#state": "state" }),
+    "--expression-attribute-values",
+    JSON.stringify({
+      ":launched": string("LAUNCHED"),
+      ":reserved": string("RESERVED"),
+      ":instance": string(instanceId),
+      ":now": number(epoch(observedAt, "observedAt")),
+    }),
+    "--output",
+    "json",
+  ];
+}
+
+export function windowsCampaignKillArgs(stateTable, reason, observedAt) {
+  return [
+    "dynamodb",
+    "update-item",
+    "--table-name",
+    tableName(stateTable),
+    "--key",
+    JSON.stringify({ pk: string("CONTROL") }),
+    "--update-expression",
+    "SET #state = :killed, reason = :reason, killed_at = :now",
+    "--expression-attribute-names",
+    JSON.stringify({ "#state": "state" }),
+    "--expression-attribute-values",
+    JSON.stringify({
+      ":killed": string("KILLED"),
+      ":reason": string(
+        exact(reason, /^[a-z0-9][a-z0-9-]{2,63}$/, "reason"),
+      ),
+      ":now": number(epoch(observedAt, "observedAt")),
+    }),
+    "--output",
+    "json",
+  ];
+}

package/scripts/aws-windows-jit-campaign.mjs

@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+
+import { spawnSync } from "node:child_process";
+import { pathToFileURL } from "node:url";
+import {
+  createWindowsJitCampaignArmPlan,
+  windowsCampaignArmItems,
+  windowsCampaignKillArgs,
+} from "./aws-windows-jit-campaign-core.mjs";
+
+function arg(name, fallback = "") {
+  const index = process.argv.indexOf(`--${name}`);
+  return index === -1 ? fallback : process.argv[index + 1] || "";
+}
+
+function aws(plan, serviceArgs) {
+  const profile = arg("aws-profile");
+  const result = spawnSync(
+    "aws",
+    [
+      ...(profile ? ["--profile", profile] : []),
+      "--region",
+      plan.aws.region,
+      ...serviceArgs,
+    ],
+    { encoding: "utf8", maxBuffer: 16 * 1024 * 1024 },
+  );
+  if (result.status !== 0) {
+    const detail = String(result.stderr || result.stdout || "")
+      .trim()
+      .slice(0, 2000);
+    throw new Error(`AWS campaign mutation failed${detail ? `: ${detail}` : ""}`);
+  }
+  return result.stdout ? JSON.parse(result.stdout) : {};
+}
+
+function armPlan() {
+  return createWindowsJitCampaignArmPlan({
+    campaignId: arg("campaign-id"),
+    sourceSha: arg("source-sha"),
+    stateTable: arg("state-table"),
+    region: arg("region", "us-east-1"),
+    armedAt: arg("armed-at", new Date().toISOString()),
+    expiresAt: arg("expires-at"),
+  });
+}
+
+function confirm(plan) {
+  if (arg("confirm-campaign-id") !== plan.campaign.id) {
+    throw new Error("--confirm-campaign-id must equal the campaign id");
+  }
+  if (arg("confirm-source-sha") !== plan.source.sha) {
+    throw new Error("--confirm-source-sha must equal the exact source SHA");
+  }
+  if (arg("confirm-state-table") !== plan.aws.stateTable) {
+    throw new Error("--confirm-state-table must equal the campaign state table");
+  }
+}
+
+function killSwitchTopic() {
+  const topic = arg("kill-switch-topic");
+  if (
+    !/^arn:aws:sns:us-east-1:\d{12}:kungfu-buildchain-windows-jit-[A-Za-z0-9_-]+$/.test(
+      topic,
+    )
+  ) {
+    throw new Error("--kill-switch-topic must be the dedicated Windows JIT SNS ARN");
+  }
+  if (arg("confirm-kill-switch-topic") !== topic) {
+    throw new Error(
+      "--confirm-kill-switch-topic must equal the dedicated kill-switch topic",
+    );
+  }
+  return topic;
+}
+
+export function main() {
+  const mode = process.argv[2] || "plan-arm";
+  if (["plan-arm", "arm-campaign"].includes(mode)) {
+    const plan = armPlan();
+    if (mode === "plan-arm") {
+      process.stdout.write(`${JSON.stringify(plan, null, 2)}\n`);
+      return plan;
+    }
+    confirm(plan);
+    aws(plan, [
+      "dynamodb",
+      "transact-write-items",
+      "--transact-items",
+      JSON.stringify(windowsCampaignArmItems(plan)),
+      "--output",
+      "json",
+    ]);
+    const result = {
+      contract: plan.contract,
+      kind: "campaign-arm-result",
+      status: "armed",
+      campaign: plan.campaign,
+      source: plan.source,
+      aws: plan.aws,
+      limits: plan.limits,
+    };
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    return result;
+  }
+  if (mode === "kill-campaign") {
+    const now = new Date();
+    const plan = createWindowsJitCampaignArmPlan({
+      campaignId: arg("campaign-id"),
+      sourceSha: arg("source-sha"),
+      stateTable: arg("state-table"),
+      region: arg("region", "us-east-1"),
+      armedAt: now.toISOString(),
+      expiresAt: new Date(now.getTime() + 1000).toISOString(),
+    });
+    confirm(plan);
+    const topic = killSwitchTopic();
+    aws(
+      plan,
+      windowsCampaignKillArgs(
+        plan.aws.stateTable,
+        arg("reason", "operator-kill"),
+        new Date().toISOString(),
+      ),
+    );
+    const notification = aws(plan, [
+      "sns",
+      "publish",
+      "--topic-arn",
+      topic,
+      "--message",
+      JSON.stringify({
+        contract: plan.contract,
+        action: "kill-campaign",
+        campaignId: plan.campaign.id,
+        sourceSha: plan.source.sha,
+      }),
+      "--output",
+      "json",
+    ]);
+    const result = {
+      contract: plan.contract,
+      kind: "campaign-kill-result",
+      status: "killed",
+      campaign: plan.campaign,
+      source: plan.source,
+      killSwitchTopic: topic,
+      notificationMessageId: notification.MessageId || "",
+    };
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    return result;
+  }
+  throw new Error(`unsupported Windows JIT campaign mode: ${mode}`);
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  try {
+    main();
+  } catch (error) {
+    console.error(`::error::${error.message || error}`);
+    process.exitCode = 1;
+  }
+}