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

package/dist/site/public-surface-audit.json

@@ -677,6 +677,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",
@@ -726,7 +727,7 @@
           "verify-command",
           "working-directory"
         ],
-        "inputCount": 82,
+        "inputCount": 83,
         "secrets": [
           "BUILDCHAIN_ARTIFACT_RELAY_S3_DOWNLOAD_ROLE_ARN",
           "BUILDCHAIN_ARTIFACT_RELAY_S3_ROLE_ARN",
@@ -1496,6 +1497,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",
@@ -1545,7 +1547,7 @@
           "verify-command",
           "working-directory"
         ],
-        "inputCount": 85,
+        "inputCount": 86,
         "secrets": [
           "BUILDCHAIN_ARTIFACT_RELAY_S3_DOWNLOAD_ROLE_ARN",
           "BUILDCHAIN_ARTIFACT_RELAY_S3_ROLE_ARN",
@@ -7028,8 +7030,8 @@
     "workflowRegistryPath": "dist/site/workflow-registry.json",
     "pageRegistryPath": "dist/site/page-registry.json",
     "cliRegistryDigest": "0db010925d1c60209c3dac8bc2797537f307ab21bc68084263e79004c5c16ff7",
-    "workflowRegistryDigest": "b5b860965abf645e1618d7840db544d638fd8ea3d0ee04ed00ccd4c8f8ccaabb",
-    "pageRegistryDigest": "fda54ffd3528f81630f0fabf91ab777a471f9d6bbd89f5f995d1dc383e077264"
+    "workflowRegistryDigest": "4f1b9a933e117abc5fc4212241c83a35609f23477dac98d6cd37c4b40b57ba29",
+    "pageRegistryDigest": "ae6076b33246fc76a7d9ce4a54ae65b9eb3a11a9772a8ea937e6f5e93bda13d1"
   },
   "comparison": {
     "missingCliRegistry": [],

package/dist/site/publication-registry.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-publication-release-registry",
-  "generatedAt": "2026-08-02T01:14:59.679Z",
-  "publishedAt": "2026-08-02T01:14:59.679Z",
+  "generatedAt": "2026-08-02T03:31:24.457Z",
+  "publishedAt": "2026-08-02T03:31:24.457Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "99ce7a8de4cd35f81d743b63d723bee2d4c26f80",
+  "sourceRevision": "1d2c6f6f9571f0417063c9814e5ad0e6fd61bb81",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -32,7 +32,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "3.0.5-alpha.0",
+    "version": "3.0.5-alpha.2",
     "versionSource": "package.json#version"
   },
   "sourceKind": "package-site-bundle",

package/dist/site/site-manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-site-manifest",
-  "generatedAt": "2026-08-02T01:14:59.679Z",
-  "publishedAt": "2026-08-02T01:14:59.679Z",
+  "generatedAt": "2026-08-02T03:31:24.457Z",
+  "publishedAt": "2026-08-02T03:31:24.457Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "99ce7a8de4cd35f81d743b63d723bee2d4c26f80",
+  "sourceRevision": "1d2c6f6f9571f0417063c9814e5ad0e6fd61bb81",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -37,7 +37,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "3.0.5-alpha.0",
+    "version": "3.0.5-alpha.2",
     "versionSource": "package.json#version"
   },
   "entrypoint": "buildchain-site.json",
@@ -277,7 +277,7 @@
       "path": "docs/reusable-build-surface.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:8908e1f1589537ac8ef82ee1dacdd24072ca871e3e245825669e7cfbdebd2e3d"
+      "digest": "sha256:baadd0c0ef61d877b409d2bdf0e696e218971eb541c5f51a1a8e88e75af4904d"
     },
     {
       "id": "publish-transaction",
@@ -285,7 +285,7 @@
       "path": "docs/publish-transaction.md",
       "plane": "verify",
       "exists": true,
-      "digest": "sha256:9b830727e5b0d2192c937f19106c11ea5064dde77e30d290825f343df47f291b"
+      "digest": "sha256:3a9ef099d5d93d9b558c7b6a0aa4403dfcce1479ce5d6fc36ecb3e34cdd5bb6d"
     },
     {
       "id": "release-governance",
@@ -293,7 +293,7 @@
       "path": "docs/release-governance.md",
       "plane": "why",
       "exists": true,
-      "digest": "sha256:60ec90d3294818d3c53e403312801a8ab47be7c0f34810002676fbfcdbceaa60"
+      "digest": "sha256:96d78f800cd7d43d3a47a11863d4813711e360418ba33a4284688389c7e4b70c"
     },
     {
       "id": "release-flow",
@@ -301,7 +301,7 @@
       "path": "docs/release-flow.md",
       "plane": "verify",
       "exists": true,
-      "digest": "sha256:bac959565c36cf39c3cd30dfce00dbbb59b73ed21b852a8f24a6cae281cb5f05"
+      "digest": "sha256:dc54b8a264489341984ca6157b07d1956e934366f937b7412a21df7f025d2d8d"
     },
     {
       "id": "runtime-train-validation",

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,12 @@ confidence: high
 sensitivity: public
 evidence_grade: A
 review_state: unreviewed
-last_reviewed: 2026-07-30
+last_reviewed: 2026-08-02
+ai_provenance:
+  model_family: GPT-5
+  product: Codex
+  generated_at: 2026-08-01
+  invisible_information: No hidden model checkpoint, parameters, or private training data were available.
 ---
 
 # AWS US elastic runner burst plane
@@ -138,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
@@ -168,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.
+`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):
 
-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.
+```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
 
@@ -226,6 +316,32 @@ host, including at least one full run, plus proof that:
 - AWS has no active campaign instance or allocated campaign host;
 - actual incremental spend remained below USD 25.
 
+### Phase 3 lifecycle controller
+
+`scripts/aws-macos-jit-controller.mjs` is the operator boundary for the paid
+campaign. It has three explicit mutation modes:
+
+- `launch-campaign` binds the exact repository source, AMI, availability zone,
+  tagged Dedicated Host, and reusable instance. It rejects pre-existing Mac
+  capacity and requires successful `AllocateHosts` and `RunInstances` DryRuns
+  before either real call.
+- `run-job` binds one queued exact-source GitHub job to the existing campaign
+  host and instance. It writes the repository JIT configuration through a
+  mode-0600 temporary file into a distinct SSM SecureString, sends only the
+  credential-free bootstrap through SSM, and removes the parameter plus runner
+  registration if command delivery fails.
+- `close-campaign` refuses execution before the provider's 24-hour minimum,
+  verifies the encrypted delete-on-termination root volume, removes scoped JIT
+  residue, terminates the exact instance, and requires a `ReleaseHosts` DryRun
+  before release. If Apple host scrubbing is still in progress, it reports
+  `release-pending`; the ten-minute card-scoped reaper remains the bounded
+  retry path.
+
+Every execute mode requires the exact source SHA and campaign id to be repeated
+through `--confirm-source-sha` and `--confirm-campaign-id`. `run-job` also
+requires `--confirm-run-id`. Omitting `--execute` emits a deterministic plan
+without changing AWS or GitHub state.
+
 ## Provider lifecycle
 
 The three infrastructure templates live under

package/docs/publish-transaction.md

@@ -415,9 +415,10 @@ first run can stop at `finalizing` after registry publication. If the reviewed
 merge commit later contains that exact transaction release material but the
 exact tag is still absent, a retry performs finalization only: it reloads the
 same durable source, release material, tooling, evidence, version, and target
-bindings; creates the exact and floating tags at the transaction release SHA;
-and completes the passport from the transaction source tree. It does not rerun
-the provider mutation and does not authorize the newer composite channel tree
+bindings; creates the exact tag at the transaction source SHA; moves floating
+refs to the transaction release SHA; and completes the passport from the
+transaction source tree. It does not rerun the provider mutation and does not
+authorize the newer composite channel tree
 as published material. A different source tree still requires a new version and
 a fresh release candidate.
 
@@ -536,8 +537,9 @@ inside the mutation boundary.
 
 If finalization fails after an exact Git tag is created, the next run reads the
 durable `finalizing` state, verifies the exact tag points at the recorded
-release SHA, and retries the remaining floating refs. An exact tag at a
-different SHA is a material conflict and blocks recovery.
+source SHA (while accepting legacy release/material targets for recovery), and
+retries the remaining floating refs. An exact tag at an unrelated SHA is a
+material conflict and blocks recovery.
 
 ## CLI Recovery
 

package/docs/release-flow.md

@@ -96,6 +96,10 @@ published artifacts are already durable.
 The intended governance split is:
 
 - exact tags such as `v3.0.2` and `v3.0.3-alpha.0` are immutable audit refs;
+- for publish transactions, the exact tag points to the transaction
+  `source_sha`, matching package-registry source metadata such as npm
+  `gitHead`; generated version-state commits remain on protected branches and
+  floating channel refs;
 - floating tags such as `v3`, `v3.0`, `v3.0-alpha`, and `v3-alpha` are mutable channel refs
   owned by the Buildchain promotion token;
 - protected branches still require reviewed channel PRs before Buildchain can

package/docs/release-governance.md

@@ -831,6 +831,13 @@ must be absent or already point at accepted release material. This preserves an
 immutable tag that represents a completed transaction while allowing a tag
 collision discovered after registry publication to recover without republishing.
 
+For package publish transactions, the immutable public version tag points to
+the transaction `source_sha`, so registry source metadata such as npm `gitHead`
+and the Git tag identify the same source commit. Protected branches and mutable
+channel tags continue to point to the generated `release_sha`. Recovery accepts
+older completed transactions whose exact tags already point to recorded release
+or release-material SHAs, but new tags are source-bound.
+
 Every Buildchain publish model that can run registry side effects must bind the
 publish entrypoint to an immutable `publish-gate/*` source lock. The reusable
 `release-candidate-promote.yml@v3` wrapper creates or updates that gate ref and

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.0",
+  "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",