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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (68) hide show
  1. package/README.md +4 -4
  2. package/actions/promote-buildchain-ref/README.md +8 -0
  3. package/bin/buildchain.mjs +13 -1
  4. package/contracts/auditable-demo-scenario-v1.schema.json +52 -0
  5. package/dist/site/buildchain-contract.json +47 -27
  6. package/dist/site/buildchain-site.json +158 -42
  7. package/dist/site/capability-registry.json +3 -3
  8. package/dist/site/cli-registry.json +40 -4
  9. package/dist/site/controller-registry.json +20 -4
  10. package/dist/site/kfd-claims.json +139 -19
  11. package/dist/site/kfd-upstream-aggregate.json +1 -1
  12. package/dist/site/manual-registry.json +9 -9
  13. package/dist/site/node-api-registry.json +1161 -180
  14. package/dist/site/page-registry.json +145 -29
  15. package/dist/site/public-surface-audit.json +385 -19
  16. package/dist/site/publication-authority-registry.json +61 -1
  17. package/dist/site/publication-registry.json +4 -4
  18. package/dist/site/release-provenance.json +1 -0
  19. package/dist/site/site-manifest.json +13 -13
  20. package/dist/site/workflow-registry.json +150 -13
  21. package/docs/MAP.md +1 -0
  22. package/docs/auditable-demo.md +58 -11
  23. package/docs/aws-us-elastic-runner-burst-plane.md +23 -19
  24. package/docs/cli-reference.md +154 -0
  25. package/docs/dev-alpha-candidate-patrol.md +13 -5
  26. package/docs/dev-delivery-warrant.md +158 -0
  27. package/docs/node-api-reference.md +54 -15
  28. package/docs/publication-authority.md +11 -0
  29. package/docs/release-candidate.md +19 -2
  30. package/docs/release-governance.md +52 -0
  31. package/docs/reusable-build-surface.md +11 -1
  32. package/docs/shifu-gate-profiles.md +12 -1
  33. package/docs/versioning.md +2 -0
  34. package/package.json +2 -1
  35. package/packages/core/buildchain-publication-authority.js +3 -1
  36. package/packages/core/channel-candidate.js +2 -21
  37. package/packages/core/channel-promotion-baseline.js +199 -0
  38. package/packages/core/dev-delivery-candidate-identity.js +94 -0
  39. package/packages/core/dev-delivery-common.js +73 -0
  40. package/packages/core/dev-delivery-proof.js +252 -0
  41. package/packages/core/dev-delivery-warrant-cancellation.js +94 -0
  42. package/packages/core/dev-delivery-warrant-settlement.js +73 -0
  43. package/packages/core/dev-delivery-warrant.js +591 -0
  44. package/scripts/auditable-demo-bundle-verification.mjs +148 -0
  45. package/scripts/auditable-demo-platform.mjs +86 -50
  46. package/scripts/auditable-demo-presentation.mjs +83 -0
  47. package/scripts/auditable-demo-renditions.mjs +264 -0
  48. package/scripts/auditable-demo.mjs +24 -30
  49. package/scripts/build-contract-core.mjs +58 -3
  50. package/scripts/buildchain-cli-help.mjs +8 -0
  51. package/scripts/buildchain-patrol.mjs +9 -0
  52. package/scripts/check-inventory.mjs +1 -0
  53. package/scripts/dev-alpha-candidate-patrol.mjs +45 -48
  54. package/scripts/dev-delivery-proof.mjs +193 -0
  55. package/scripts/dev-delivery-warrant.mjs +426 -0
  56. package/scripts/dev-pr-auto-merge.mjs +488 -46
  57. package/scripts/dev-pr-delivery-warrant.mjs +209 -0
  58. package/scripts/gate-profile-core.mjs +24 -0
  59. package/scripts/generate-site-bundle.mjs +2 -2
  60. package/scripts/git-fetch-process-tree.mjs +142 -0
  61. package/scripts/lifecycle-substage-evidence.mjs +274 -0
  62. package/scripts/locked-source-checkout.mjs +6 -3
  63. package/scripts/resolve-artifact-transfer-mode.mjs +9 -0
  64. package/scripts/resolve-build-contract.mjs +7 -0
  65. package/scripts/route-offline-runners.mjs +1 -0
  66. package/scripts/run-lifecycle-core.mjs +9 -9
  67. package/scripts/shifu-gate-profile.mjs +10 -16
  68. package/scripts/site-capability-metadata.mjs +14 -0
@@ -1,8 +1,8 @@
1
1
  {
2
2
  "schemaVersion": 1,
3
3
  "contract": "kungfu-buildchain-publication-release-registry",
4
- "generatedAt": "2026-08-03T09:35:55.854Z",
5
- "publishedAt": "2026-08-03T09:35:55.854Z",
4
+ "generatedAt": "2026-08-05T21:38:24.130Z",
5
+ "publishedAt": "2026-08-05T21:38:24.130Z",
6
6
  "reproducible": true,
7
7
  "timestampPolicy": "ci-injected",
8
8
  "deterministicInputs": [
@@ -19,7 +19,7 @@
19
19
  "declared Buildchain surface manifest contract"
20
20
  ],
21
21
  "sourceDateEpoch": "0",
22
- "sourceRevision": "88a8b532ce69ee3def5926a42c9cd75e4809ae88",
22
+ "sourceRevision": "931e1a448f3460a29d6b6765c1f1e3e3e26f19cc",
23
23
  "timestampPolicyDetails": {
24
24
  "contract": "kungfu-buildchain-surface-timestamp-policy",
25
25
  "timestampFields": [
@@ -32,7 +32,7 @@
32
32
  },
33
33
  "package": {
34
34
  "name": "@kungfu-tech/buildchain",
35
- "version": "3.0.6-alpha.1",
35
+ "version": "3.0.6-alpha.2",
36
36
  "versionSource": "package.json#version"
37
37
  },
38
38
  "sourceKind": "package-site-bundle",
@@ -25,6 +25,7 @@
25
25
  "./cache-evidence": "./packages/core/cache-evidence.js",
26
26
  "./controller-evidence": "./packages/core/controller-evidence.js",
27
27
  "./diagnostics": "./packages/core/diagnostics.js",
28
+ "./dev-delivery-warrant": "./packages/core/dev-delivery-warrant.js",
28
29
  "./homebrew": "./packages/core/homebrew.js",
29
30
  "./issue-reporting": "./packages/core/issue-reporting.js",
30
31
  "./kfd": "./packages/core/kfd.js",
@@ -1,8 +1,8 @@
1
1
  {
2
2
  "schemaVersion": 1,
3
3
  "contract": "kungfu-buildchain-site-manifest",
4
- "generatedAt": "2026-08-03T09:35:55.854Z",
5
- "publishedAt": "2026-08-03T09:35:55.854Z",
4
+ "generatedAt": "2026-08-05T21:38:24.130Z",
5
+ "publishedAt": "2026-08-05T21:38:24.130Z",
6
6
  "reproducible": true,
7
7
  "timestampPolicy": "ci-injected",
8
8
  "deterministicInputs": [
@@ -19,7 +19,7 @@
19
19
  "declared Buildchain surface manifest contract"
20
20
  ],
21
21
  "sourceDateEpoch": "0",
22
- "sourceRevision": "88a8b532ce69ee3def5926a42c9cd75e4809ae88",
22
+ "sourceRevision": "931e1a448f3460a29d6b6765c1f1e3e3e26f19cc",
23
23
  "timestampPolicyDetails": {
24
24
  "contract": "kungfu-buildchain-surface-timestamp-policy",
25
25
  "timestampFields": [
@@ -37,7 +37,7 @@
37
37
  },
38
38
  "package": {
39
39
  "name": "@kungfu-tech/buildchain",
40
- "version": "3.0.6-alpha.1",
40
+ "version": "3.0.6-alpha.2",
41
41
  "versionSource": "package.json#version"
42
42
  },
43
43
  "entrypoint": "buildchain-site.json",
@@ -53,7 +53,7 @@
53
53
  "path": "docs/MAP.md",
54
54
  "plane": "use",
55
55
  "exists": true,
56
- "digest": "sha256:0ea7f59030e5a087e3ff7e9eb591fec8d92c64399799e554aa1fa7ecb6a263ae"
56
+ "digest": "sha256:d76416d8cd04dcdb560b7d06fef287fa22d6b186a729cb92cd4cf71cebbac1e9"
57
57
  },
58
58
  {
59
59
  "id": "getting-started",
@@ -69,7 +69,7 @@
69
69
  "path": "docs/auditable-demo.md",
70
70
  "plane": "verify",
71
71
  "exists": true,
72
- "digest": "sha256:7e1426d8200bd4e7a7e6684c872f47075cd37d0bddbb262ea3263eaad846b540"
72
+ "digest": "sha256:c49e734fdfe3b74d317e23a523e198f1194b2c7cd16cca87e8e3a3ffc7bf589f"
73
73
  },
74
74
  {
75
75
  "id": "install",
@@ -109,7 +109,7 @@
109
109
  "path": "docs/publication-authority.md",
110
110
  "plane": "verify",
111
111
  "exists": true,
112
- "digest": "sha256:6c91ee89d1ed5c0c570806684738916876556b2f1bcbf4be4f73f30ff89e98a4"
112
+ "digest": "sha256:a1650158943d95b979d164ca98a73d7919fda577d648e4a4a9d04588ec698796"
113
113
  },
114
114
  {
115
115
  "id": "github-governance-authority",
@@ -125,7 +125,7 @@
125
125
  "path": "docs/release-candidate.md",
126
126
  "plane": "verify",
127
127
  "exists": true,
128
- "digest": "sha256:fbcffddf1e2c50502186b7ba557e29f96be59a1da6d438aabd4d1f9ce32b5915"
128
+ "digest": "sha256:48e42e92174b1091e8ff32e876099f092ca12ce886d3382f019f0ccd907f1c9b"
129
129
  },
130
130
  {
131
131
  "id": "release-propagation",
@@ -229,7 +229,7 @@
229
229
  "path": "docs/cli-reference.md",
230
230
  "plane": "use",
231
231
  "exists": true,
232
- "digest": "sha256:73d34a3b46ecfb772b806f0d79754772446fcc13d7f349b508a0c0212e97fcec"
232
+ "digest": "sha256:2365e125d38e43b68a4af277a91be7aca708a8bf785954ed4589dbd9a5d8db97"
233
233
  },
234
234
  {
235
235
  "id": "node-api-reference",
@@ -237,7 +237,7 @@
237
237
  "path": "docs/node-api-reference.md",
238
238
  "plane": "use",
239
239
  "exists": true,
240
- "digest": "sha256:ae49a589091d1ab91d29f2d6ac52cf2551a9d0b1f78350965b408f40fd219e29"
240
+ "digest": "sha256:e0e720eeacfa61a1ca235142858f544e18d3f7a000e300a4311e246fe738ff81"
241
241
  },
242
242
  {
243
243
  "id": "build-facts",
@@ -277,7 +277,7 @@
277
277
  "path": "docs/reusable-build-surface.md",
278
278
  "plane": "use",
279
279
  "exists": true,
280
- "digest": "sha256:fe06637d604101269b013163be558c1ecc842276e27f2b5abfb6eea39e98feb0"
280
+ "digest": "sha256:7bc04f658d7e298872756278c60143d8edf5dfb841d0b0d3ea62af8028735b54"
281
281
  },
282
282
  {
283
283
  "id": "publish-transaction",
@@ -293,7 +293,7 @@
293
293
  "path": "docs/release-governance.md",
294
294
  "plane": "why",
295
295
  "exists": true,
296
- "digest": "sha256:fc7f0add1afce775c327d50a1e269a7040865e65ca2441dbeb8d0373c5f8d5aa"
296
+ "digest": "sha256:481640f398d966dca4f1f2e29a8100f0f479315ee19e65b0e259720f2b61213f"
297
297
  },
298
298
  {
299
299
  "id": "release-flow",
@@ -317,7 +317,7 @@
317
317
  "path": "docs/versioning.md",
318
318
  "plane": "why",
319
319
  "exists": true,
320
- "digest": "sha256:bdb155e873f9c2ea5cd40bdde057d2c2f90322f0d4575de77fe1670bd040e643"
320
+ "digest": "sha256:793db9414d11aeb314ff2d37a52481826ca5f636d08eaf93772d37962a51484f"
321
321
  },
322
322
  {
323
323
  "id": "web-surface-deployments",
@@ -176,9 +176,10 @@
176
176
  "shifu-cache-profile-ref",
177
177
  "untrusted-policy",
178
178
  "verify-command",
179
+ "verify-substage-evidence-path",
179
180
  "working-directory"
180
181
  ],
181
- "inputCount": 85,
182
+ "inputCount": 86,
182
183
  "secrets": [
183
184
  "BUILDCHAIN_ARTIFACT_RELAY_S3_DOWNLOAD_ROLE_ARN",
184
185
  "BUILDCHAIN_ARTIFACT_RELAY_S3_ROLE_ARN",
@@ -283,12 +284,13 @@
283
284
  "materialize",
284
285
  "materialize-base-ref",
285
286
  "media-profile",
287
+ "render-failure-advisory",
286
288
  "render-media",
287
289
  "renderer-image",
288
290
  "scenario-path",
289
291
  "source-ref"
290
292
  ],
291
- "inputCount": 11,
293
+ "inputCount": 12,
292
294
  "secrets": [
293
295
  "DEMO_UPDATE_TOKEN"
294
296
  ],
@@ -299,9 +301,10 @@
299
301
  "evidence-artifact-digest",
300
302
  "evidence-artifact-name",
301
303
  "publication-pr-url",
304
+ "render-result",
302
305
  "source-sha"
303
306
  ],
304
- "outputCount": 6,
307
+ "outputCount": 7,
305
308
  "surface": "declarative-auditable-demo",
306
309
  "capabilityGroup": "api-cli-reference",
307
310
  "status": "preview",
@@ -392,6 +395,7 @@
392
395
  "auto-no-gate",
393
396
  "buildchain-ref",
394
397
  "buildchain-repository",
398
+ "consumer-gate-command",
395
399
  "consumer-predicate-digest",
396
400
  "consumer-predicate-id",
397
401
  "consumer-qualification-required",
@@ -419,7 +423,7 @@
419
423
  "target-ref",
420
424
  "used-nonces-json"
421
425
  ],
422
- "inputCount": 33,
426
+ "inputCount": 34,
423
427
  "secrets": [
424
428
  "KUNGFU_GOVERNANCE_AUDITOR_APP_PRIVATE_KEY"
425
429
  ],
@@ -491,6 +495,7 @@
491
495
  "publication-control-plane-audit-json",
492
496
  "publication-expected-json",
493
497
  "publication-gate-aggregate-json",
498
+ "publication-gate-command",
494
499
  "publication-package-name",
495
500
  "publication-product",
496
501
  "publication-publisher-workflow-path",
@@ -514,6 +519,7 @@
514
519
  "release-candidate-family-evidence-required",
515
520
  "release-candidate-family-evidence-root",
516
521
  "release-candidate-family-initiative-id",
522
+ "release-candidate-wait-seconds",
517
523
  "release-candidate-workflow-file",
518
524
  "release-candidate-workflow-name",
519
525
  "release-passport",
@@ -544,7 +550,7 @@
544
550
  "target-sha",
545
551
  "trusted-publishing"
546
552
  ],
547
- "inputCount": 95,
553
+ "inputCount": 97,
548
554
  "secrets": [
549
555
  "BUILDCHAIN_ISSUE_APP_ID",
550
556
  "BUILDCHAIN_ISSUE_APP_PRIVATE_KEY",
@@ -1271,9 +1277,10 @@
1271
1277
  "shifu-cache-profile-ref",
1272
1278
  "untrusted-policy",
1273
1279
  "verify-command",
1280
+ "verify-substage-evidence-path",
1274
1281
  "working-directory"
1275
1282
  ],
1276
- "inputCount": 88,
1283
+ "inputCount": 89,
1277
1284
  "secrets": [
1278
1285
  "BUILDCHAIN_ARTIFACT_RELAY_S3_DOWNLOAD_ROLE_ARN",
1279
1286
  "BUILDCHAIN_ARTIFACT_RELAY_S3_ROLE_ARN",
@@ -1367,6 +1374,27 @@
1367
1374
  "sunsetCondition": "explicit-breaking-change-review-in-a-future-major-line",
1368
1375
  "nonDuplicationRationale": "Existing workflow identity retained for caller compatibility and repository orchestration."
1369
1376
  },
1377
+ {
1378
+ "id": "buildchain-dev-delivery",
1379
+ "path": ".github/workflows/buildchain-dev-delivery.yml",
1380
+ "reusable": false,
1381
+ "inputs": [],
1382
+ "inputCount": 0,
1383
+ "secrets": [],
1384
+ "secretCount": 0,
1385
+ "outputs": [],
1386
+ "outputCount": 0,
1387
+ "surface": "dev-governance",
1388
+ "capabilityGroup": "governance-versioning",
1389
+ "status": "active",
1390
+ "owner": "buildchain-workflows",
1391
+ "maturity": "active",
1392
+ "introducedVersion": "pre-3.0.2-alpha.4",
1393
+ "compatibilityPromise": "preserved-through-the-v3-major-line",
1394
+ "deprecationReplacement": "",
1395
+ "sunsetCondition": "explicit-breaking-change-review-in-a-future-major-line",
1396
+ "nonDuplicationRationale": "Existing workflow identity retained for caller compatibility and repository orchestration."
1397
+ },
1370
1398
  {
1371
1399
  "id": "buildchain-patrol-daily",
1372
1400
  "path": ".github/workflows/buildchain-patrol-daily.yml",
@@ -1647,6 +1675,87 @@
1647
1675
  "sunsetCondition": "explicit-breaking-change-review-in-a-future-major-line",
1648
1676
  "nonDuplicationRationale": "Existing workflow identity retained for caller compatibility and repository orchestration."
1649
1677
  },
1678
+ {
1679
+ "id": "dev-delivery-warrant-cancel",
1680
+ "path": ".github/workflows/dev-delivery-warrant-cancel.yml",
1681
+ "reusable": true,
1682
+ "inputs": [
1683
+ "buildchain-ref",
1684
+ "buildchain-repository",
1685
+ "event-action",
1686
+ "expected-candidate-id",
1687
+ "expected-old-state-root",
1688
+ "expected-pr-number",
1689
+ "expected-source-head-sha",
1690
+ "observed-source-head-sha",
1691
+ "outcome",
1692
+ "reason",
1693
+ "target-branch",
1694
+ "terminal-evidence-root"
1695
+ ],
1696
+ "inputCount": 12,
1697
+ "secrets": [
1698
+ "github-token"
1699
+ ],
1700
+ "secretCount": 1,
1701
+ "outputs": [
1702
+ "cancellation-action",
1703
+ "cancellation-receipt-root",
1704
+ "final-state-root"
1705
+ ],
1706
+ "outputCount": 3,
1707
+ "surface": "repository-workflow",
1708
+ "capabilityGroup": "governance-versioning",
1709
+ "status": "active",
1710
+ "owner": "buildchain-workflows",
1711
+ "maturity": "active",
1712
+ "introducedVersion": "pre-3.0.2-alpha.4",
1713
+ "compatibilityPromise": "preserved-through-the-v3-major-line",
1714
+ "deprecationReplacement": "",
1715
+ "sunsetCondition": "explicit-breaking-change-review-in-a-future-major-line",
1716
+ "nonDuplicationRationale": "Existing workflow identity retained for caller compatibility and repository orchestration."
1717
+ },
1718
+ {
1719
+ "id": "dev-delivery-warrant-close",
1720
+ "path": ".github/workflows/dev-delivery-warrant-close.yml",
1721
+ "reusable": true,
1722
+ "inputs": [
1723
+ "buildchain-ref",
1724
+ "buildchain-repository",
1725
+ "current-base-sha",
1726
+ "expected-head-sha",
1727
+ "expected-pr-number",
1728
+ "merge-group-head-sha",
1729
+ "merge-group-tree-sha",
1730
+ "outcome",
1731
+ "reason",
1732
+ "replay-tree-sha",
1733
+ "required-context-roots-json",
1734
+ "target-branch",
1735
+ "terminal-evidence-root"
1736
+ ],
1737
+ "inputCount": 13,
1738
+ "secrets": [
1739
+ "github-token"
1740
+ ],
1741
+ "secretCount": 1,
1742
+ "outputs": [
1743
+ "close-receipt-root",
1744
+ "final-state-root",
1745
+ "integration-proof-root"
1746
+ ],
1747
+ "outputCount": 3,
1748
+ "surface": "repository-workflow",
1749
+ "capabilityGroup": "governance-versioning",
1750
+ "status": "active",
1751
+ "owner": "buildchain-workflows",
1752
+ "maturity": "active",
1753
+ "introducedVersion": "pre-3.0.2-alpha.4",
1754
+ "compatibilityPromise": "preserved-through-the-v3-major-line",
1755
+ "deprecationReplacement": "",
1756
+ "sunsetCondition": "explicit-breaking-change-review-in-a-future-major-line",
1757
+ "nonDuplicationRationale": "Existing workflow identity retained for caller compatibility and repository orchestration."
1758
+ },
1650
1759
  {
1651
1760
  "id": "dev-merge-queue-governance",
1652
1761
  "path": ".github/workflows/dev-merge-queue-governance.yml",
@@ -1673,35 +1782,60 @@
1673
1782
  "path": ".github/workflows/dev-pr-auto-merge.yml",
1674
1783
  "reusable": true,
1675
1784
  "inputs": [
1785
+ "affected-paths-json",
1676
1786
  "allowed-head-prefixes",
1787
+ "assignment-root",
1677
1788
  "block-labels",
1678
1789
  "buildchain-ref",
1679
1790
  "buildchain-repository",
1791
+ "closure-root",
1792
+ "delivery-class",
1793
+ "delivery-priority",
1794
+ "delivery-warrant-mode",
1795
+ "dependency-root",
1796
+ "diagnostic-context",
1680
1797
  "dry-run",
1798
+ "expected-head-sha",
1799
+ "expected-pr-number",
1800
+ "initiative-root",
1681
1801
  "landing-mode",
1682
1802
  "max-merges",
1683
1803
  "merge-method",
1804
+ "plan-root",
1805
+ "project-cut-proof-json",
1684
1806
  "queue-admission-context",
1685
1807
  "ready-label",
1686
1808
  "require-approval",
1687
1809
  "required-status-checks",
1688
1810
  "same-repository-only",
1689
- "target-branch"
1690
- ],
1691
- "inputCount": 14,
1811
+ "shard-evidence-roots-json",
1812
+ "source-identity-root",
1813
+ "source-patch-root",
1814
+ "target-branch",
1815
+ "toolchain-root",
1816
+ "warrant-lease-seconds"
1817
+ ],
1818
+ "inputCount": 32,
1692
1819
  "secrets": [
1693
1820
  "github-token"
1694
1821
  ],
1695
1822
  "secretCount": 1,
1696
1823
  "outputs": [
1697
1824
  "action-count",
1825
+ "admission-receipt-root",
1826
+ "admission-state",
1698
1827
  "enqueued-count",
1699
1828
  "evaluated-count",
1700
1829
  "final-base-sha",
1701
1830
  "merged-count",
1702
- "skipped-count"
1831
+ "project-cut-proof-root",
1832
+ "skipped-count",
1833
+ "source-proof-root",
1834
+ "warrant-receipt-root",
1835
+ "warrant-state-commit",
1836
+ "warrant-state-root"
1703
1837
  ],
1704
- "outputCount": 6,
1838
+ "outputCount": 13,
1705
1839
  "surface": "dev-governance",
1706
1840
  "capabilityGroup": "governance-versioning",
1707
1841
  "status": "active",
@@ -2220,6 +2354,7 @@
2220
2354
  "publication-control-plane-audit-json",
2221
2355
  "publication-expected-json",
2222
2356
  "publication-gate-aggregate-json",
2357
+ "publication-gate-command",
2223
2358
  "publication-package-name",
2224
2359
  "publication-product",
2225
2360
  "publication-publisher-workflow-path",
@@ -2243,6 +2378,7 @@
2243
2378
  "release-candidate-family-evidence-required",
2244
2379
  "release-candidate-family-evidence-root",
2245
2380
  "release-candidate-family-initiative-id",
2381
+ "release-candidate-wait-seconds",
2246
2382
  "release-candidate-workflow-file",
2247
2383
  "release-candidate-workflow-name",
2248
2384
  "release-passport",
@@ -2273,7 +2409,7 @@
2273
2409
  "target-sha",
2274
2410
  "trusted-publishing"
2275
2411
  ],
2276
- "inputCount": 87,
2412
+ "inputCount": 89,
2277
2413
  "secrets": [
2278
2414
  "BUILDCHAIN_ISSUE_APP_ID",
2279
2415
  "BUILDCHAIN_ISSUE_APP_PRIVATE_KEY",
@@ -2836,10 +2972,11 @@
2836
2972
  "required",
2837
2973
  "sample-process-tree",
2838
2974
  "stage",
2975
+ "substage-evidence-path",
2839
2976
  "summary-path",
2840
2977
  "timeout-minutes"
2841
2978
  ],
2842
- "inputCount": 21,
2979
+ "inputCount": 22,
2843
2980
  "capabilityGroup": "reusable-build",
2844
2981
  "status": "active",
2845
2982
  "owner": "buildchain-actions",
package/docs/MAP.md CHANGED
@@ -111,6 +111,7 @@ replace them.
111
111
  | Why does Buildchain use branch-driven release governance? | [`release-governance.md`](release-governance.md) | why | stable |
112
112
  | How do protected dev branches and scheduled ready-PR merging work? | [`release-governance.md`](release-governance.md#protected-dev-branches) | use | stable |
113
113
  | How do slow required checks land reliably on a busy dev channel? | [`release-governance.md`](release-governance.md#protected-dev-branches) + [`cli.md`](cli.md#commands) | use | preview |
114
+ | How does the durable fair Dev Delivery Warrant Queue prevent slow-candidate starvation? | [`dev-delivery-warrant.md`](dev-delivery-warrant.md) | use/verify | preview |
114
115
  | How do I coalesce rapid Dev changes, preserve release runner priority, and retry only transient failed jobs? | [`dev-qualification-patrol.md`](dev-qualification-patrol.md) | use/verify | preview |
115
116
  | How do I run daily, weekly, or monthly repository patrols? | [`release-governance.md`](release-governance.md#buildchain-patrol) | use | stable |
116
117
  | How does Buildchain decide patch, minor, and major release lines? | [`versioning.md`](versioning.md) | why | stable |
@@ -8,7 +8,7 @@ confidence: high
8
8
  sensitivity: public
9
9
  evidence_grade: A
10
10
  review_state: self-reviewed
11
- last_reviewed: 2026-08-02
11
+ last_reviewed: 2026-08-05
12
12
  ai_provenance:
13
13
  model_family: GPT-5
14
14
  product: Codex
@@ -52,6 +52,39 @@ the default. Both classes retain 4 MiB per step, a clean Home/XDG environment,
52
52
  no inherited credentials, and a network-disabled read-only container with
53
53
  bounded tmpfs.
54
54
 
55
+ Consumers may optionally add a
56
+ `buildchain.declarative-demo-presentation/v1` presentation. This contract
57
+ binds one consumer-owned proof label, question, summary, and optional
58
+ transition to every demo in declared order. Buildchain verifies that each
59
+ question is the same title used by capture and media; it does not invent or
60
+ reinterpret the product argument.
61
+
62
+ The presentation also chooses one of two README materialization modes. The
63
+ default, when no presentation is declared, remains the original full generated
64
+ block with commands, renditions, evidence, and claim boundary. `media-only`
65
+ updates only the image inside each existing README marker so consumer-authored
66
+ narrative and transitions survive regeneration. The generated technical
67
+ details move to a separately declared Markdown specification, where stable
68
+ per-demo markers preserve proof order and idempotent updates. The publication
69
+ pull request stages that specification together with the README and
70
+ content-addressed evidence. No presentation field grants publication or Work
71
+ authority.
72
+
73
+ The optional top-level `compositionMode` is an explicit visual contract.
74
+ Omitting it preserves `presentation-framed`; declaring `terminal-fill` makes
75
+ the bounded PTY replay the complete pixel surface without renderer-owned
76
+ window chrome. Buildchain carries that choice into both native scenes. It does
77
+ not infer full-frame intent from output resolution.
78
+
79
+ The optional `buildchain.declarative-demo-playback/v1` contract separates
80
+ observed command latency from presentation timing. Its
81
+ `deterministic-readable` mode preserves the captured terminal event payloads
82
+ and their order, records the observed final-event time as non-authoritative
83
+ evidence, and maps event ordinals onto the declared `activeDurationMs` before a
84
+ bounded `finalHoldMs`. Both native renditions therefore replay at the same
85
+ readable pace even when an identical command runs faster or slower. Omitting
86
+ the contract preserves the original PTY timestamp behavior.
87
+
55
88
  The uploaded metadata must bind the executable SHA-256, declare an empty
56
89
  runtime dependency set, and provide a bounded `executableFiles` array of exact
57
90
  artifact-relative paths and SHA-256 digests. GitHub Artifact transport does not
@@ -97,6 +130,7 @@ jobs:
97
130
  scenario-path: .buildchain/auditable-demo.json
98
131
  renderer-image: ghcr.io/kungfu-systems/build-images/demo-renderer@sha256:RENDERER_DIGEST
99
132
  render-media: true
133
+ render-failure-advisory: false
100
134
  media-profile: responsive-web-delivery-v1
101
135
  materialize: true
102
136
  materialize-base-ref: dev/v1/v1.0
@@ -193,6 +227,10 @@ The Gate:
193
227
  bounded tmpfs;
194
228
  - verifies the renderer manifest, media probe, exact input roots, exact output
195
229
  member set, and complete checksums;
230
+ - independently verifies the requested composition mode, browser-observed
231
+ content viewport, PTY rows and columns, and deterministic cell geometry for
232
+ every frame set; `terminal-fill` is rejected unless the viewport and cell
233
+ grid resolve to the complete declared frame;
196
234
  - uploads a content-addressed qualified bundle plus an independent GitHub
197
235
  Artifact id, URL, archive digest, and expiry-bearing source coordinate.
198
236
 
@@ -202,9 +240,9 @@ passed gate receipt, and checksums covering every member exactly once.
202
240
 
203
241
  ## Selective Render
204
242
 
205
- `render-media: true` enables the second job. It downloads the just-uploaded Gate
206
- bundle by its content-addressed name, recomputes the Gate member root, verifies
207
- the exact source SHA and renderer digest, and only then renders the complete
243
+ `render-media: true` enables the full-media step only after every declared demo
244
+ has passed the required Gate. It recomputes each Gate member root, verifies the
245
+ exact source SHA and renderer digest, and only then renders the complete
208
246
  qualified scene.
209
247
 
210
248
  The media bundle contains MP4, WebM, GIF, poster, probe, renderer manifest,
@@ -213,10 +251,19 @@ distribution checksums. A web-delivery profile also retains
213
251
  `media-inspection.json`, whose content root is bound into the receipt.
214
252
  `render-media: false` does not weaken or skip the Gate.
215
253
 
254
+ `render-failure-advisory: true` makes only the full-media step advisory. A
255
+ render failure remains visible as a failed step and workflow warning, while the
256
+ required Gate keeps its normal failure semantics. Failed or partial media can
257
+ never open a materialization PR. Use this for an Alpha lane whose binary
258
+ publication must not depend on animation capacity; keep the default `false`
259
+ for explicit media refreshes and other workflows that require complete media.
260
+
216
261
  When the Gate bundle contains a qualified terminal capture, the render job
217
262
  passes it read-only to the immutable renderer. The renderer manifest binds the
218
263
  capture root and terminal-state-machine version, but raw capture bytes remain
219
264
  in the Gate bundle rather than being copied into the public media bundle.
265
+ Missing, malformed, out-of-bounds, non-full-frame, rendition-mismatched, or
266
+ internally drifted composition evidence fails before media finalization.
220
267
 
221
268
  ## Media Qualification Profiles
222
269
 
@@ -225,13 +272,13 @@ The single machine-readable source is
225
272
  profile through `media-profile`; they cannot pass ffmpeg commands, codec flags,
226
273
  shell fragments, arbitrary profile paths, or transcoding instructions.
227
274
 
228
- | Profile | Meaning |
229
- | --- | --- |
230
- | `archive-v1` | Default compatibility contract. Retains the exact renderer outputs and classifies GIF as README compatibility evidence without making a browser-delivery claim. |
231
- | `web-delivery-v1` | Independently qualifies H.264 MP4 and VP9 WebM playback sources, forbids audio, requires exact scene dimensions and bounded duration/frame-rate drift, checks per-rendition byte ceilings, and proves MP4 `moov` precedes `mdat`. PNG remains the lossless evidence poster. |
232
- | `responsive-web-delivery-v1` | Extends `web-delivery-v1` with exact 1280x720 H.264 MP4 and VP9 WebM responsive sources plus a 1280x720 README GIF while keeping the primary MP4/WebM and evidence poster at the source scene dimensions. Every declared downscale must preserve the scene aspect ratio and may never upscale. |
233
- | `responsive-long-form-web-delivery-v1` | Extends the responsive profile for explicitly admitted long-form scenes. Its measured-baseline multipliers raise only the GIF ceiling to 8 MiB and the four video ceilings to 4 MiB; all codec, native-resolution, no-audio, duration, and authority checks remain unchanged. |
234
- | `site-hero-v1` | Extends `web-delivery-v1` and additionally requires a qualified WebP browser poster. The current Build Images v1 renderer does not emit that member, so selecting this profile fails closed until the producer adds it. |
275
+ | Profile | Meaning |
276
+ | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
277
+ | `archive-v1` | Default compatibility contract. Retains the exact renderer outputs and classifies GIF as README compatibility evidence without making a browser-delivery claim. |
278
+ | `web-delivery-v1` | Independently qualifies H.264 MP4 and VP9 WebM playback sources, forbids audio, requires exact scene dimensions and bounded duration/frame-rate drift, checks per-rendition byte ceilings, and proves MP4 `moov` precedes `mdat`. PNG remains the lossless evidence poster. |
279
+ | `responsive-web-delivery-v1` | Extends `web-delivery-v1` with exact 1280x720 H.264 MP4 and VP9 WebM responsive sources plus a 1280x720 README GIF while keeping the primary MP4/WebM and evidence poster at the source scene dimensions. Every declared downscale must preserve the scene aspect ratio and may never upscale. |
280
+ | `responsive-long-form-web-delivery-v1` | Extends the responsive profile for explicitly admitted long-form scenes. Its measured-baseline multipliers raise only the GIF ceiling to 8 MiB and the four video ceilings to 4 MiB; all codec, native-resolution, no-audio, duration, and authority checks remain unchanged. |
281
+ | `site-hero-v1` | Extends `web-delivery-v1` and additionally requires a qualified WebP browser poster. The current Build Images v1 renderer does not emit that member, so selecting this profile fails closed until the producer adds it. |
235
282
 
236
283
  For web-delivery profiles, Buildchain runs its own fixed `ffprobe` invocation
237
284
  inside the same immutable, network-disabled renderer image. That command is
@@ -210,21 +210,25 @@ Each stack owns a stack-scoped reaper log group, so an independent retained
210
210
  one-shot campaign stack can be created without colliding with another
211
211
  campaign's audit log resource.
212
212
 
213
- The tag-filtered AWS Budget is defense in depth, not the authoritative launch
213
+ The account-native AWS Budget is defense in depth, not the authoritative launch
214
214
  gate. It is owned by the singleton
215
215
  `kungfu-buildchain-windows-jit-budget-guard` stack rather than any retained
216
216
  campaign stack. This prevents Budget-name collisions and prevents a stale
217
217
  campaign reaper from becoming the provider-wide cost authority. The Budget
218
- filters exactly `user:kungfu:provider$windows-ec2-jit`; its 80% and 95% actual
219
- notifications persist the provider kill sentinel, terminate every tagged
220
- Windows JIT instance, and delete scoped JIT parameters. Every launch controller
221
- refuses to proceed when the sentinel exists or when the Budget identity or tag
222
- filter does not match.
223
-
224
- Budget installation fails closed until the AWS Organizations management
225
- account activates `kungfu:provider` and Cost Explorer returns
226
- `windows-ec2-jit` for that key. A linked account cannot activate the tag. Do not
227
- create an unfiltered fallback Budget or treat a tag-filtered zero as evidence.
218
+ filters exactly `USAGE_TYPE=BoxUsage:c7i.4xlarge`,
219
+ `OPERATION=RunInstances:0002` (Windows), and `REGION=us-east-1`; its 80% and
220
+ 95% actual notifications persist the provider kill sentinel, terminate every
221
+ tagged Windows JIT instance, and delete scoped JIT parameters. Every launch
222
+ controller refuses to proceed when the sentinel exists or when the Budget
223
+ identity or dimension filter does not match.
224
+
225
+ Budget installation is intentionally deployable by the workload account without
226
+ AWS Organizations management-account access. It fails closed unless Cost
227
+ Explorer exposes all three AWS-owned billing dimensions in the requested phase
228
+ window. The `kungfu:provider=windows-ec2-jit` resource tag remains mandatory for
229
+ ownership, cleanup, and IAM scoping, but it is not a billing filter. Do not
230
+ create an unfiltered fallback Budget or treat an incomplete dimension readback
231
+ as evidence.
228
232
  The DynamoDB campaign reservation remains the atomic launch authority because
229
233
  Cost Explorer and AWS Budgets can lag provider activity.
230
234
 
@@ -250,12 +254,12 @@ The modes are deliberately separated:
250
254
  provider kill sentinel, campaign stack, and zero EC2/EBS/SSM/JIT/runner
251
255
  residue.
252
256
  - `install-budget --execute` deploys or updates only the singleton Budget guard.
253
- It refuses to mutate unless the provider tag value is visible, the Windows
254
- workflow is disabled, and the account, campaign, source, Budget, and plan
255
- digest confirmations match.
257
+ It refuses to mutate unless all exact Windows billing dimensions are visible,
258
+ the Windows workflow is disabled, and the account, campaign, source, Budget,
259
+ and plan digest confirmations match.
256
260
  - `prepare --execute` requires the installed Budget guard, absent kill
257
- sentinel, fresh Cost Explorer readback filtered by both
258
- `kungfu:provider=windows-ec2-jit` and `BoxUsage:c7i.4xlarge`, zero residue, a
261
+ sentinel, fresh Cost Explorer readback filtered by `BoxUsage:c7i.4xlarge`,
262
+ `RunInstances:0002`, and `us-east-1`, zero residue, a
259
263
  never-used campaign stack name, and the disabled workflow. The receipt binds
260
264
  the query timestamp and exact filter identity. Preparation deploys the
261
265
  campaign stack and atomically arms the ledger with that provider-spend
@@ -310,9 +314,9 @@ clear or re-arm operation.
310
314
  Every `scripts/aws-windows-jit-controller.mjs --execute` call must provide the
311
315
  same `--account-id`, `--campaign-id`, `--confirm-campaign-id`, `--state-table`,
312
316
  and `--confirm-state-table`. Before GitHub JIT material is created, the
313
- controller verifies the exact provider Budget/tag filter and proves the global
314
- Budget kill sentinel absent. After the GitHub, AMI, active-instance, SSM, and
315
- EC2 DryRun checks pass, the controller
317
+ controller verifies the exact provider Budget/dimension filter and proves the
318
+ global Budget kill sentinel absent. After the GitHub, AMI, active-instance,
319
+ SSM, and EC2 DryRun checks pass, the controller
316
320
  atomically reserves one run. Duplicate run-attempt-qualification identities,
317
321
  source mismatch, expiry, `KILLED`, the sixth accepted instance, or a
318
322
  reservation that would exceed the USD 110 ceiling after combining the persisted