@kungfu-tech/buildchain 2.11.14-alpha.6 → 2.12.0-alpha.0
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.
- package/AGENTS.md +17 -6
- package/README.md +3 -1
- package/dist/site/buildchain-contract.json +46 -7
- package/dist/site/buildchain-site.json +34 -24
- package/dist/site/capability-registry.json +2 -2
- package/dist/site/kfd-claims.json +88 -6
- package/dist/site/kfd-upstream-aggregate.json +1 -1
- package/dist/site/manual-registry.json +5 -5
- package/dist/site/node-api-registry.json +1 -1
- package/dist/site/page-registry.json +24 -14
- package/dist/site/public-surface-audit.json +69 -3
- package/dist/site/publication-registry.json +4 -4
- package/dist/site/site-manifest.json +9 -9
- package/dist/site/workflow-registry.json +73 -1
- package/docs/MAP.md +3 -0
- package/docs/release-governance.md +38 -0
- package/docs/reusable-build-surface.md +78 -3
- package/docs/runtime-train-validation.md +14 -4
- package/docs/versioning.md +1 -0
- package/package.json +1 -1
- package/packages/core/buildchain-contract.js +30 -0
- package/scripts/buildchain-channel-router.mjs +223 -0
- package/scripts/check-inventory.mjs +102 -0
- package/scripts/generate-channel-build-workflow.mjs +101 -0
- package/scripts/generate-site-bundle.mjs +2 -1
- package/scripts/runtime-ref-core.mjs +32 -5
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
"status": "passed",
|
|
5
5
|
"summary": {
|
|
6
6
|
"cliCommandCount": 75,
|
|
7
|
-
"workflowCount":
|
|
7
|
+
"workflowCount": 39,
|
|
8
8
|
"actionCount": 4,
|
|
9
9
|
"sitePageCount": 45,
|
|
10
10
|
"docCommandRefCount": 237,
|
|
@@ -684,6 +684,72 @@
|
|
|
684
684
|
],
|
|
685
685
|
"inputCount": 1
|
|
686
686
|
},
|
|
687
|
+
{
|
|
688
|
+
"id": "build",
|
|
689
|
+
"path": ".github/workflows/build.yml",
|
|
690
|
+
"inputs": [
|
|
691
|
+
"artifact-name",
|
|
692
|
+
"artifact-name-template",
|
|
693
|
+
"artifact-paths",
|
|
694
|
+
"artifact-relay-s3-bucket",
|
|
695
|
+
"artifact-relay-s3-download-role-arn",
|
|
696
|
+
"artifact-relay-s3-oidc-audience",
|
|
697
|
+
"artifact-relay-s3-prefix",
|
|
698
|
+
"artifact-relay-s3-region",
|
|
699
|
+
"artifact-relay-s3-role-arn",
|
|
700
|
+
"artifact-relay-s3-upload-role-arn",
|
|
701
|
+
"artifact-retention-days",
|
|
702
|
+
"artifact-transfer-mode",
|
|
703
|
+
"build-command",
|
|
704
|
+
"buildchain-alpha-contract-lock-path",
|
|
705
|
+
"buildchain-channel",
|
|
706
|
+
"buildchain-contract-compatibility-policy",
|
|
707
|
+
"buildchain-contract-drift-issue-mode",
|
|
708
|
+
"buildchain-contract-lock-path",
|
|
709
|
+
"buildchain-ref",
|
|
710
|
+
"buildchain-repository",
|
|
711
|
+
"buildchain-stable-contract-lock-path",
|
|
712
|
+
"checkout-cache-fallback",
|
|
713
|
+
"checkout-cache-fetch-attempts",
|
|
714
|
+
"checkout-cache-github-timeout-seconds",
|
|
715
|
+
"checkout-cache-mirror-url-template",
|
|
716
|
+
"checkout-cache-mode",
|
|
717
|
+
"checkout-cache-reference-repository-template",
|
|
718
|
+
"checkout-cache-timeout-seconds",
|
|
719
|
+
"expected-artifacts-json",
|
|
720
|
+
"install-command",
|
|
721
|
+
"linux-container-image",
|
|
722
|
+
"linux-container-preset",
|
|
723
|
+
"node-version",
|
|
724
|
+
"platforms-json",
|
|
725
|
+
"process-sample-interval-ms",
|
|
726
|
+
"process-summary-path",
|
|
727
|
+
"publish-anchor-request-json",
|
|
728
|
+
"publish-channel",
|
|
729
|
+
"publish-refs-json",
|
|
730
|
+
"publish-registry",
|
|
731
|
+
"publish-source-ref",
|
|
732
|
+
"release-candidate",
|
|
733
|
+
"requested-parallelism",
|
|
734
|
+
"require-build",
|
|
735
|
+
"require-install",
|
|
736
|
+
"require-trusted-event",
|
|
737
|
+
"require-verify",
|
|
738
|
+
"runner-preset",
|
|
739
|
+
"sample-process-tree",
|
|
740
|
+
"setup-node",
|
|
741
|
+
"untrusted-policy",
|
|
742
|
+
"verify-command",
|
|
743
|
+
"working-directory"
|
|
744
|
+
],
|
|
745
|
+
"inputCount": 53
|
|
746
|
+
},
|
|
747
|
+
{
|
|
748
|
+
"id": "buildchain-alpha-self-dogfood",
|
|
749
|
+
"path": ".github/workflows/buildchain-alpha-self-dogfood.yml",
|
|
750
|
+
"inputs": [],
|
|
751
|
+
"inputCount": 0
|
|
752
|
+
},
|
|
687
753
|
{
|
|
688
754
|
"id": "buildchain-patrol-daily",
|
|
689
755
|
"path": ".github/workflows/buildchain-patrol-daily.yml",
|
|
@@ -2540,8 +2606,8 @@
|
|
|
2540
2606
|
"workflowRegistryPath": "dist/site/workflow-registry.json",
|
|
2541
2607
|
"pageRegistryPath": "dist/site/page-registry.json",
|
|
2542
2608
|
"cliRegistryDigest": "3c0729f5351eb82fe26625fa5aabf30903f45f68af2431e02860f85ada468ac9",
|
|
2543
|
-
"workflowRegistryDigest": "
|
|
2544
|
-
"pageRegistryDigest": "
|
|
2609
|
+
"workflowRegistryDigest": "2bd177fe6e3cbcd382ba30d90c96f35865ef17fc29e451715696cb076d7da933",
|
|
2610
|
+
"pageRegistryDigest": "e496f039ccd56f2be611433c075b5150a4ede2b04682bb7af0ee4716b1f5eb6a"
|
|
2545
2611
|
},
|
|
2546
2612
|
"comparison": {
|
|
2547
2613
|
"missingCliRegistry": [],
|
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
{
|
|
2
2
|
"schemaVersion": 1,
|
|
3
3
|
"contract": "kungfu-buildchain-publication-release-registry",
|
|
4
|
-
"generatedAt": "2026-07-
|
|
5
|
-
"publishedAt": "2026-07-
|
|
4
|
+
"generatedAt": "2026-07-11T01:35:09.048Z",
|
|
5
|
+
"publishedAt": "2026-07-11T01:35:09.048Z",
|
|
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": "
|
|
22
|
+
"sourceRevision": "3dde1345af4880782c221385158a8a9f3674fcad",
|
|
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": "2.
|
|
35
|
+
"version": "2.12.0-alpha.0",
|
|
36
36
|
"versionSource": "package.json#version"
|
|
37
37
|
},
|
|
38
38
|
"sourceKind": "package-site-bundle",
|
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
{
|
|
2
2
|
"schemaVersion": 1,
|
|
3
3
|
"contract": "kungfu-buildchain-site-manifest",
|
|
4
|
-
"generatedAt": "2026-07-
|
|
5
|
-
"publishedAt": "2026-07-
|
|
4
|
+
"generatedAt": "2026-07-11T01:35:09.048Z",
|
|
5
|
+
"publishedAt": "2026-07-11T01:35:09.048Z",
|
|
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": "
|
|
22
|
+
"sourceRevision": "3dde1345af4880782c221385158a8a9f3674fcad",
|
|
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": "2.
|
|
40
|
+
"version": "2.12.0-alpha.0",
|
|
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:
|
|
56
|
+
"digest": "sha256:bad18d05d3d03b77bf64d8697fc351d58b1372a355a4f25c6719bf08984a79a2"
|
|
57
57
|
},
|
|
58
58
|
{
|
|
59
59
|
"id": "install",
|
|
@@ -205,7 +205,7 @@
|
|
|
205
205
|
"path": "docs/reusable-build-surface.md",
|
|
206
206
|
"plane": "use",
|
|
207
207
|
"exists": true,
|
|
208
|
-
"digest": "sha256:
|
|
208
|
+
"digest": "sha256:670528f1710001a488b2c544db7c104a4770c0ce7d62afa6c6017e473677fd03"
|
|
209
209
|
},
|
|
210
210
|
{
|
|
211
211
|
"id": "publish-transaction",
|
|
@@ -221,7 +221,7 @@
|
|
|
221
221
|
"path": "docs/release-governance.md",
|
|
222
222
|
"plane": "why",
|
|
223
223
|
"exists": true,
|
|
224
|
-
"digest": "sha256:
|
|
224
|
+
"digest": "sha256:db9077f3748954dee3d28cd1e418dd537fec498df31155c560f7929b622888cb"
|
|
225
225
|
},
|
|
226
226
|
{
|
|
227
227
|
"id": "release-flow",
|
|
@@ -237,7 +237,7 @@
|
|
|
237
237
|
"path": "docs/runtime-train-validation.md",
|
|
238
238
|
"plane": "verify",
|
|
239
239
|
"exists": true,
|
|
240
|
-
"digest": "sha256:
|
|
240
|
+
"digest": "sha256:1872e511b31c04ba75fc3a005c7a4f857c8b06ecadfedb75bc35b2ce70e7764a"
|
|
241
241
|
},
|
|
242
242
|
{
|
|
243
243
|
"id": "versioning",
|
|
@@ -245,7 +245,7 @@
|
|
|
245
245
|
"path": "docs/versioning.md",
|
|
246
246
|
"plane": "why",
|
|
247
247
|
"exists": true,
|
|
248
|
-
"digest": "sha256:
|
|
248
|
+
"digest": "sha256:400027d5e34d5c22752f7664bb9ca9ce99c04e7be298183d0303f3fb04fa7747"
|
|
249
249
|
},
|
|
250
250
|
{
|
|
251
251
|
"id": "web-surface-deployments",
|
|
@@ -59,7 +59,7 @@
|
|
|
59
59
|
"working-directory"
|
|
60
60
|
],
|
|
61
61
|
"inputCount": 50,
|
|
62
|
-
"surface": "reusable-
|
|
62
|
+
"surface": "reusable-build",
|
|
63
63
|
"capabilityGroup": "api-cli-reference",
|
|
64
64
|
"status": "active"
|
|
65
65
|
},
|
|
@@ -343,6 +343,78 @@
|
|
|
343
343
|
"capabilityGroup": "api-cli-reference",
|
|
344
344
|
"status": "repository-internal"
|
|
345
345
|
},
|
|
346
|
+
{
|
|
347
|
+
"id": "build",
|
|
348
|
+
"path": ".github/workflows/build.yml",
|
|
349
|
+
"inputs": [
|
|
350
|
+
"artifact-name",
|
|
351
|
+
"artifact-name-template",
|
|
352
|
+
"artifact-paths",
|
|
353
|
+
"artifact-relay-s3-bucket",
|
|
354
|
+
"artifact-relay-s3-download-role-arn",
|
|
355
|
+
"artifact-relay-s3-oidc-audience",
|
|
356
|
+
"artifact-relay-s3-prefix",
|
|
357
|
+
"artifact-relay-s3-region",
|
|
358
|
+
"artifact-relay-s3-role-arn",
|
|
359
|
+
"artifact-relay-s3-upload-role-arn",
|
|
360
|
+
"artifact-retention-days",
|
|
361
|
+
"artifact-transfer-mode",
|
|
362
|
+
"build-command",
|
|
363
|
+
"buildchain-alpha-contract-lock-path",
|
|
364
|
+
"buildchain-channel",
|
|
365
|
+
"buildchain-contract-compatibility-policy",
|
|
366
|
+
"buildchain-contract-drift-issue-mode",
|
|
367
|
+
"buildchain-contract-lock-path",
|
|
368
|
+
"buildchain-ref",
|
|
369
|
+
"buildchain-repository",
|
|
370
|
+
"buildchain-stable-contract-lock-path",
|
|
371
|
+
"checkout-cache-fallback",
|
|
372
|
+
"checkout-cache-fetch-attempts",
|
|
373
|
+
"checkout-cache-github-timeout-seconds",
|
|
374
|
+
"checkout-cache-mirror-url-template",
|
|
375
|
+
"checkout-cache-mode",
|
|
376
|
+
"checkout-cache-reference-repository-template",
|
|
377
|
+
"checkout-cache-timeout-seconds",
|
|
378
|
+
"expected-artifacts-json",
|
|
379
|
+
"install-command",
|
|
380
|
+
"linux-container-image",
|
|
381
|
+
"linux-container-preset",
|
|
382
|
+
"node-version",
|
|
383
|
+
"platforms-json",
|
|
384
|
+
"process-sample-interval-ms",
|
|
385
|
+
"process-summary-path",
|
|
386
|
+
"publish-anchor-request-json",
|
|
387
|
+
"publish-channel",
|
|
388
|
+
"publish-refs-json",
|
|
389
|
+
"publish-registry",
|
|
390
|
+
"publish-source-ref",
|
|
391
|
+
"release-candidate",
|
|
392
|
+
"requested-parallelism",
|
|
393
|
+
"require-build",
|
|
394
|
+
"require-install",
|
|
395
|
+
"require-trusted-event",
|
|
396
|
+
"require-verify",
|
|
397
|
+
"runner-preset",
|
|
398
|
+
"sample-process-tree",
|
|
399
|
+
"setup-node",
|
|
400
|
+
"untrusted-policy",
|
|
401
|
+
"verify-command",
|
|
402
|
+
"working-directory"
|
|
403
|
+
],
|
|
404
|
+
"inputCount": 53,
|
|
405
|
+
"surface": "channel-build-router",
|
|
406
|
+
"capabilityGroup": "reusable-build",
|
|
407
|
+
"status": "active"
|
|
408
|
+
},
|
|
409
|
+
{
|
|
410
|
+
"id": "buildchain-alpha-self-dogfood",
|
|
411
|
+
"path": ".github/workflows/buildchain-alpha-self-dogfood.yml",
|
|
412
|
+
"inputs": [],
|
|
413
|
+
"inputCount": 0,
|
|
414
|
+
"surface": "repository-workflow",
|
|
415
|
+
"capabilityGroup": "api-cli-reference",
|
|
416
|
+
"status": "active"
|
|
417
|
+
},
|
|
346
418
|
{
|
|
347
419
|
"id": "buildchain-patrol-daily",
|
|
348
420
|
"path": ".github/workflows/buildchain-patrol-daily.yml",
|
package/docs/MAP.md
CHANGED
|
@@ -95,6 +95,7 @@ replace them.
|
|
|
95
95
|
| How do I add timestamped logs inside build scripts? | [`toolkit-observability.md`](toolkit-observability.md) | use | stable |
|
|
96
96
|
| What package-owned facts should buildchain.libkungfu.dev render? | [`site-bundle-contract.md`](site-bundle-contract.md) | use | stable |
|
|
97
97
|
| How do I call the reusable build workflow? | [`reusable-build-surface.md`](reusable-build-surface.md) | use | stable |
|
|
98
|
+
| How do I use one build job that follows alpha during development and stable for releases? | [`reusable-build-surface.md`](reusable-build-surface.md#automatic-channel-router) | use | preview |
|
|
98
99
|
| How do self-hosted runners relay large artifacts through S3 before GitHub artifacts? | [`reusable-build-surface.md`](reusable-build-surface.md#artifact-transfer-relay) | use | stable |
|
|
99
100
|
| How do self-hosted runners reuse local Git checkout caches without weakening source locks? | [`reusable-build-surface.md`](reusable-build-surface.md#locked-source-checkout-cache) | use | stable |
|
|
100
101
|
| How do I validate an unreleased Buildchain runtime train while keeping `@v2`? | [`runtime-train-validation.md`](runtime-train-validation.md) | use | stable |
|
|
@@ -114,6 +115,8 @@ replace them.
|
|
|
114
115
|
- **v2 / v2-alpha / v2.0 / v2.0-alpha / exact tags / floating tags** ->
|
|
115
116
|
[`release-governance.md`](release-governance.md) and
|
|
116
117
|
[`release-flow.md`](release-flow.md).
|
|
118
|
+
- **Buildchain self-dogfood / released alpha canary / stable compatibility lane** ->
|
|
119
|
+
[`release-governance.md`](release-governance.md#buildchain-alpha-self-dogfood).
|
|
117
120
|
- **v2.1 vs v2.2 / when to open a new minor line** ->
|
|
118
121
|
[`versioning.md`](versioning.md).
|
|
119
122
|
- **dry-run / what would happen if this channel PR merges** -> [`cli.md`](cli.md)
|
|
@@ -167,6 +167,44 @@ This keeps the test channel self-describing. If a consumer checks out
|
|
|
167
167
|
alpha ref removes routine consumer edits when Buildchain opens a newer minor,
|
|
168
168
|
while exact tags and SHAs remain the reproducible audit choice.
|
|
169
169
|
|
|
170
|
+
### Buildchain Alpha Self-Dogfood
|
|
171
|
+
|
|
172
|
+
Buildchain continuously consumes its own current major alpha through
|
|
173
|
+
`.github/workflows/buildchain-alpha-self-dogfood.yml`. Both lanes call the
|
|
174
|
+
released channel router at `build.yml@v2-alpha`. The auto lane must resolve
|
|
175
|
+
`v2-alpha`; the explicit stable lane must resolve `v2`. Both execute the same
|
|
176
|
+
declared install, build, and verify fixture, proving that a single consumer
|
|
177
|
+
surface routes to distinct released runtimes without duplicating lifecycle
|
|
178
|
+
configuration in the consumer.
|
|
179
|
+
|
|
180
|
+
The reusable build trust gate reads `job.workflow_ref`, which identifies the
|
|
181
|
+
called workflow and its selected ref. It does not infer the runtime from
|
|
182
|
+
`github.workflow_ref`, because GitHub defines that context as the caller
|
|
183
|
+
workflow identity during a reusable call.
|
|
184
|
+
|
|
185
|
+
The router selects `.buildchain/alpha-contract-lock.json` for alpha and
|
|
186
|
+
`.buildchain/contract-lock.json` for stable. The alpha lock records the exact
|
|
187
|
+
reviewed alpha SHA and compatibility digest; it does not replace the stable
|
|
188
|
+
consumer lock. A later alpha with only compatible additive drift continues,
|
|
189
|
+
while a changed breaking digest fails until the new alpha contract is reviewed.
|
|
190
|
+
|
|
191
|
+
The evidence job resolves `v2-alpha` and `v2` through the GitHub refs API,
|
|
192
|
+
compares those immutable SHAs with the reusable workflow outputs, verifies the
|
|
193
|
+
`alpha` and `stable` classifications, and uploads a JSON evidence artifact.
|
|
194
|
+
The canary runs after successful Buildchain ref promotion, on a daily fallback
|
|
195
|
+
schedule, and on manual dispatch. It shares the release-promotion concurrency
|
|
196
|
+
group, so another promotion cannot move the floating refs between runtime
|
|
197
|
+
resolution and evidence comparison.
|
|
198
|
+
|
|
199
|
+
This is a post-publication consumer canary, not a release bootstrap. Source
|
|
200
|
+
verification still runs the current commit, and
|
|
201
|
+
`buildchain-ref-promotion.yml` still passes the verified exact SHA into the
|
|
202
|
+
promotion workflow. Patrol, dev-merge, repair, and promotion defaults remain on
|
|
203
|
+
stable or exact refs so a broken alpha cannot prevent Buildchain from publishing
|
|
204
|
+
its fix. When Buildchain opens a new major, inventory validation requires this
|
|
205
|
+
workflow's fixed GitHub `uses` refs to move from `vN`/`vN-alpha` to the new
|
|
206
|
+
major; GitHub does not allow expressions in a reusable-workflow `uses` ref.
|
|
207
|
+
|
|
170
208
|
If `dev/vX/vX.Y` has already advanced before generated alpha version-state
|
|
171
209
|
bookkeeping can sync back, Buildchain records `skipped-non-fast-forward` for the
|
|
172
210
|
dev sync and still completes the exact and floating alpha tags for the reviewed
|
|
@@ -5,9 +5,69 @@ Buildchain's release semantics but cannot be described as a simple Node package.
|
|
|
5
5
|
The first target shape is `libnode`: expensive native builds, multiple operating
|
|
6
6
|
systems, self-hosted runner labels, and release artifacts that must be auditable.
|
|
7
7
|
|
|
8
|
-
##
|
|
8
|
+
## Automatic Channel Router
|
|
9
9
|
|
|
10
|
-
|
|
10
|
+
The preferred consumer surface is one reusable workflow call. After v2.12
|
|
11
|
+
reaches the stable major ref, consumers keep this configuration for both alpha
|
|
12
|
+
development and stable release work:
|
|
13
|
+
|
|
14
|
+
```yaml
|
|
15
|
+
jobs:
|
|
16
|
+
build:
|
|
17
|
+
uses: kungfu-systems/buildchain/.github/workflows/build.yml@v2
|
|
18
|
+
permissions:
|
|
19
|
+
contents: read
|
|
20
|
+
issues: write
|
|
21
|
+
id-token: write
|
|
22
|
+
with:
|
|
23
|
+
working-directory: .
|
|
24
|
+
artifact-name: libnode
|
|
25
|
+
runner-preset: kungfu-v4-self-hosted
|
|
26
|
+
publish-channel: none
|
|
27
|
+
secrets: inherit
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
`buildchain-channel` defaults to `auto`. Selection uses this precedence:
|
|
31
|
+
|
|
32
|
+
1. an explicit `buildchain-ref` train, SHA, or official channel;
|
|
33
|
+
2. an explicit `buildchain-channel: alpha|stable`;
|
|
34
|
+
3. `publish-channel: alpha|release|major`;
|
|
35
|
+
4. GitHub release prerelease metadata;
|
|
36
|
+
5. a canonical semver tag;
|
|
37
|
+
6. non-release PR, push, dispatch, schedule, and workflow-run events default to
|
|
38
|
+
alpha.
|
|
39
|
+
|
|
40
|
+
The resolved runtime is `vN-alpha` for development and prerelease intent and
|
|
41
|
+
`vN` for stable release intent. Unknown custom publish channels, malformed
|
|
42
|
+
release events, and non-semver release-like tags fail before the build matrix;
|
|
43
|
+
they never guess alpha for a stable release.
|
|
44
|
+
|
|
45
|
+
The router automatically selects `.buildchain/alpha-contract-lock.json` for
|
|
46
|
+
alpha and `.buildchain/contract-lock.json` for stable. A repository can override
|
|
47
|
+
the common path with `buildchain-contract-lock-path`, or override one channel
|
|
48
|
+
with `buildchain-alpha-contract-lock-path` /
|
|
49
|
+
`buildchain-stable-contract-lock-path`.
|
|
50
|
+
|
|
51
|
+
Only repositories changing the default policy need extra routing input:
|
|
52
|
+
|
|
53
|
+
```yaml
|
|
54
|
+
with:
|
|
55
|
+
buildchain-channel: stable
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
During the v2.12 prerelease evaluation window, canaries use
|
|
59
|
+
`build.yml@v2-alpha`. The same router then selects `v2-alpha` or stable `v2` as
|
|
60
|
+
the runtime. Production consumers should adopt `build.yml@v2` after the router
|
|
61
|
+
has reached stable; this keeps the routing shell itself on a stable ref.
|
|
62
|
+
|
|
63
|
+
The router is generated from `.build.yml`'s input/output surface. Run
|
|
64
|
+
`node scripts/generate-channel-build-workflow.mjs` after changing the advanced
|
|
65
|
+
build workflow; inventory and unit tests reject a stale generated router.
|
|
66
|
+
|
|
67
|
+
## Advanced Workflow
|
|
68
|
+
|
|
69
|
+
Consumers that need direct workflow-shell or runtime control call the advanced
|
|
70
|
+
surface:
|
|
11
71
|
|
|
12
72
|
```yaml
|
|
13
73
|
jobs:
|
|
@@ -214,6 +274,21 @@ The lock is intentionally small. It does not copy the full contract. The full
|
|
|
214
274
|
contract remains in the Buildchain ref and package; the consumer records only
|
|
215
275
|
what it accepted and the policy used to compare future floating-ref movement.
|
|
216
276
|
|
|
277
|
+
Advanced alpha-channel consumers select the matching workflow shell:
|
|
278
|
+
|
|
279
|
+
```yaml
|
|
280
|
+
jobs:
|
|
281
|
+
build:
|
|
282
|
+
uses: kungfu-systems/buildchain/.github/workflows/.build.yml@v2-alpha
|
|
283
|
+
with:
|
|
284
|
+
buildchain-contract-lock-path: .buildchain/contract-lock.json
|
|
285
|
+
```
|
|
286
|
+
|
|
287
|
+
The runtime follows the called workflow through `job.workflow_ref`. Callers may
|
|
288
|
+
also pass `buildchain-ref: v2-alpha` explicitly; official floating refs are
|
|
289
|
+
ordinary channel selections and are allowed on pull requests and pushes. Train
|
|
290
|
+
refs and exact SHAs remain trusted manual overrides.
|
|
291
|
+
|
|
217
292
|
## Locked Source Checkout Cache
|
|
218
293
|
|
|
219
294
|
Self-hosted runners that build large repositories can opt into a locked source
|
|
@@ -309,7 +384,7 @@ The reusable workflow exposes the resolved contract:
|
|
|
309
384
|
| `buildchain-runtime-ref` | Runtime ref selected after applying the empty-default or override policy |
|
|
310
385
|
| `buildchain-runtime-sha` | Immutable Buildchain runtime commit used by all runtime checkouts |
|
|
311
386
|
| `buildchain-runtime-class` | `stable`, `alpha`, `train`, `exact-sha`, or `development` |
|
|
312
|
-
| `buildchain-runtime-override` | `true` when a
|
|
387
|
+
| `buildchain-runtime-override` | `true` when a train or exact-SHA `buildchain-ref` override was accepted |
|
|
313
388
|
| `buildchain-runtime-trust-decision` | Runtime override trust decision |
|
|
314
389
|
| `buildchain-contract-lock-status` | `unchanged`, `compatible-drift`, `breaking-drift`, `missing-lock`, `non-floating-runtime`, or first-release `runtime-contract-unavailable` |
|
|
315
390
|
| `buildchain-contract-lock-drift` | `true` when the floating runtime SHA or contract digest changed |
|
|
@@ -5,6 +5,14 @@ committed workflow YAML. Runtime trains provide a temporary validation pointer
|
|
|
5
5
|
for Buildchain changes that are ready for downstream testing but not yet
|
|
6
6
|
promoted through the normal `dev -> alpha -> release` chain.
|
|
7
7
|
|
|
8
|
+
Official floating channels are not runtime overrides. A consumer that
|
|
9
|
+
deliberately follows `@v2-alpha` gets the matching runtime on pull requests and
|
|
10
|
+
pushes because the reusable workflow reads the called workflow identity from
|
|
11
|
+
`job.workflow_ref`. Passing `buildchain-ref: v2-alpha` explicitly is also
|
|
12
|
+
accepted when the caller wants the channel binding visible in its input set.
|
|
13
|
+
The caller's `github.workflow_ref` is not used for this inference because it
|
|
14
|
+
identifies the caller workflow during reusable calls.
|
|
15
|
+
|
|
8
16
|
## Train refs
|
|
9
17
|
|
|
10
18
|
A train ref is a branch in the Buildchain repository:
|
|
@@ -111,10 +119,12 @@ summary. The evidence should include:
|
|
|
111
119
|
|
|
112
120
|
## Trust and limitation
|
|
113
121
|
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
122
|
+
Official floating channel refs such as `v2` and `v2-alpha` may be selected on
|
|
123
|
+
pull requests and pushes. Train refs and arbitrary exact-SHA overrides still
|
|
124
|
+
fail closed unless the event is `workflow_dispatch` and the actor has write,
|
|
125
|
+
maintain, or admin permission on the caller repository. Pull requests,
|
|
126
|
+
including fork-originated pull requests, cannot use train or exact-SHA
|
|
127
|
+
overrides.
|
|
118
128
|
|
|
119
129
|
Runtime train validation covers Buildchain runtime scripts, CLI code, local
|
|
120
130
|
actions, configuration parsing, and lifecycle behavior. It cannot validate
|
package/docs/versioning.md
CHANGED
|
@@ -61,6 +61,7 @@ repository changes are patch".
|
|
|
61
61
|
|
|
62
62
|
| Date | Action | Line | Faces | Class | Rationale | PR |
|
|
63
63
|
| --- | --- | --- | --- | --- | --- | --- |
|
|
64
|
+
| 2026-07-11 | open-minor | `v2.12` | channel-build-router, channel-selection-protocol | additive | The public `build.yml` reusable workflow lets consumers declare one build job while Buildchain selects generic major alpha for development/prerelease intent and stable major for production release intent, with explicit overrides, separate locks, and fail-closed ambiguity handling. | |
|
|
64
65
|
| 2026-07-08 | open-minor | `v2.9` | build-facts-contract | additive | Build Facts add a public CLI command family, Node API export, config protocol, module/product fact contracts, release-passport evidence section, and Kungfu legacy buildinfo projection from the same source facts. | |
|
|
65
66
|
| 2026-07-06 | open-minor | `v2.8` | kfd-1-contract-world-release-gate, kfd-2-release-trust-passport-audit, kfd-3-collaboration-interface-trust-proof, publish-source-lock-enforcement, required-check-protection | additive | KFD release gates add KFD-1 self contract verification, KFD-2 public release trust claim audit, KFD-3 collaboration-interface trust proofs, publish-side source-lock enforcement for promote-only wrappers, and protected channel required checks repaired to bind GitHub Actions check runs instead of legacy commit status contexts. | |
|
|
66
67
|
| 2026-07-04 | open-minor | `v2.5` | scheduled-integration-governance | additive | Scheduled integration governance adds scheduled feature-branch discovery, conflict-free integration, reporting, and agent-visible governance automation for dev-line maintenance. | |
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@kungfu-tech/buildchain",
|
|
3
|
-
"version": "2.
|
|
3
|
+
"version": "2.12.0-alpha.0",
|
|
4
4
|
"private": false,
|
|
5
5
|
"description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
|
|
6
6
|
"repository": "https://github.com/kungfu-systems/buildchain",
|
|
@@ -111,6 +111,36 @@ export function createBuildchainContractWorld({ root = process.cwd(), packageJso
|
|
|
111
111
|
"retryable GitHub fallback fetches use a bounded attempt budget before exact source SHA and tree verification",
|
|
112
112
|
],
|
|
113
113
|
}),
|
|
114
|
+
surface(root, {
|
|
115
|
+
id: "channel-build-router",
|
|
116
|
+
kind: "workflow",
|
|
117
|
+
path: ".github/workflows/build.yml",
|
|
118
|
+
publicRef: `${pkg.repository ? "kungfu-systems/buildchain" : "buildchain"}/.github/workflows/build.yml@${majorLine}`,
|
|
119
|
+
requiredInputs: [],
|
|
120
|
+
requiredOutputs: ["buildchain-channel", "buildchain-runtime-sha", "build-summary-artifact"],
|
|
121
|
+
breakingDefaults: {
|
|
122
|
+
channelDefault: "auto",
|
|
123
|
+
developmentDefault: "alpha",
|
|
124
|
+
prereleaseDefault: "alpha",
|
|
125
|
+
stableReleaseDefault: "stable",
|
|
126
|
+
ambiguousReleasePolicy: "fail-closed",
|
|
127
|
+
},
|
|
128
|
+
optionalInputs: [
|
|
129
|
+
"buildchain-channel",
|
|
130
|
+
"buildchain-ref",
|
|
131
|
+
"buildchain-alpha-contract-lock-path",
|
|
132
|
+
"buildchain-stable-contract-lock-path",
|
|
133
|
+
"buildchain-contract-lock-path",
|
|
134
|
+
],
|
|
135
|
+
guarantees: [
|
|
136
|
+
"consumers declare one build job while Buildchain selects the matching generic major channel",
|
|
137
|
+
"development and prerelease intent select vN-alpha",
|
|
138
|
+
"stable release intent selects vN",
|
|
139
|
+
"ambiguous release-like intent fails before build jobs",
|
|
140
|
+
"explicit train and exact-SHA overrides retain the reusable build trust gate",
|
|
141
|
+
"alpha and stable channel selections use separate consumer contract locks by default",
|
|
142
|
+
],
|
|
143
|
+
}),
|
|
114
144
|
surface(root, {
|
|
115
145
|
id: "release-candidate-promote",
|
|
116
146
|
kind: "workflow",
|