@kungfu-tech/buildchain 3.0.2 → 3.0.3-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/actions/report-buildchain-issue/README.md +1 -1
- package/contracts/buildchain-v2-residuals-v1.json +191 -0
- package/dist/site/buildchain-contract.json +58 -35
- package/dist/site/buildchain-site.json +33 -33
- package/dist/site/controller-registry.json +24 -3
- package/dist/site/kfd-claims.json +11 -6
- package/dist/site/kfd-upstream-aggregate.json +1 -1
- package/dist/site/manual-registry.json +7 -7
- package/dist/site/node-api-registry.json +6 -6
- package/dist/site/page-registry.json +22 -22
- package/dist/site/public-surface-audit.json +10 -5
- package/dist/site/publication-registry.json +4 -4
- package/dist/site/site-manifest.json +11 -11
- package/dist/site/workflow-registry.json +8 -3
- package/docs/auditable-demo.md +19 -1
- package/docs/consumer-issue-reporting.md +1 -1
- package/docs/dev-alpha-candidate-patrol.md +24 -10
- package/docs/github-governance-authority.md +23 -30
- package/docs/observed-evidence-patrol.md +28 -12
- package/docs/release-governance.md +8 -1
- package/docs/reusable-build-surface.md +124 -64
- package/docs/shifu-gate-profiles.md +7 -1
- package/docs/versioning.md +41 -21
- package/docs/web-surface-deployments.md +20 -1
- package/package.json +1 -1
- package/packages/core/artifact-signing.js +1 -0
- package/packages/core/buildchain-contract.js +1 -0
- package/packages/core/controller-evidence.js +2 -0
- package/packages/core/github-governance-authority.js +25 -17
- package/packages/core/publication-control-plane-audit.js +28 -0
- package/packages/core/release-passport.js +36 -27
- package/packages/core/stable-release-gate.js +4 -1
- package/scripts/artifact-signing-delegation.mjs +268 -0
- package/scripts/audit-github-governance.mjs +32 -13
- package/scripts/audit-publication-control-plane.mjs +17 -8
- package/scripts/auditable-demo.mjs +147 -2
- package/scripts/buildchain-patrol.mjs +1 -1
- package/scripts/check-inventory.mjs +1 -0
- package/scripts/dev-alpha-candidate-patrol.mjs +20 -0
- package/scripts/dispatch-artifact-signing-authority.mjs +7 -1
- package/scripts/finalize-native-artifact-signing-result.mjs +114 -31
- package/scripts/gate-profile-core.mjs +6 -1
- package/scripts/inspect-artifact-signing-requests.mjs +45 -14
- package/scripts/observed-evidence.mjs +151 -33
- package/scripts/reconcile-github-governance.mjs +8 -1
- package/scripts/resolve-artifact-signing-upload-route.mjs +55 -0
- package/scripts/run-candidate-body-prefix-renderer.mjs +187 -0
- package/scripts/runtime-ref-core.mjs +13 -2
- package/scripts/seal-artifact-signing-requests.mjs +51 -6
- package/scripts/stable-candidate-qualification.mjs +8 -0
- package/scripts/verify-artifact-signing-results.mjs +26 -1
- package/scripts/web-surface-production-decision.mjs +19 -3
|
@@ -8,11 +8,11 @@ confidence: high
|
|
|
8
8
|
sensitivity: public
|
|
9
9
|
evidence_grade: A
|
|
10
10
|
review_state: unreviewed
|
|
11
|
-
last_reviewed: 2026-07-
|
|
11
|
+
last_reviewed: 2026-07-30
|
|
12
12
|
ai_provenance:
|
|
13
13
|
model_family: GPT-5
|
|
14
14
|
product: Codex
|
|
15
|
-
generated_at: 2026-07-
|
|
15
|
+
generated_at: 2026-07-30
|
|
16
16
|
invisible_context: not asserted
|
|
17
17
|
---
|
|
18
18
|
|
|
@@ -116,12 +116,12 @@ jobs:
|
|
|
116
116
|
|
|
117
117
|
`runner-preset` is the stable first-class surface for known runner fleets:
|
|
118
118
|
|
|
119
|
-
| Preset | Platforms
|
|
120
|
-
| ----------------------- |
|
|
121
|
-
| `github-hosted` | `ubuntu-24.04`, `macos-latest`, `windows-2022`
|
|
122
|
-
| `kungfu-v4-self-hosted` | Kungfu Linux x64, macOS ARM64, and Windows x64 self-hosted runner labels
|
|
119
|
+
| Preset | Platforms |
|
|
120
|
+
| ----------------------- | -------------------------------------------------------------------------------------------------------------- |
|
|
121
|
+
| `github-hosted` | `ubuntu-24.04`, `macos-latest`, `windows-2022` |
|
|
122
|
+
| `kungfu-v4-self-hosted` | Kungfu Linux x64, macOS ARM64, and Windows x64 self-hosted runner labels |
|
|
123
123
|
| `kungfu-v4-native` | Kungfu Linux x64, Linux ARM64, macOS ARM64, and Windows x64; Linux ARM64 uses GitHub-hosted `ubuntu-24.04-arm` |
|
|
124
|
-
| `custom` | Requires `platforms-json`
|
|
124
|
+
| `custom` | Requires `platforms-json` |
|
|
125
125
|
|
|
126
126
|
Callers can still provide a custom matrix with `platforms-json`. Each platform
|
|
127
127
|
object has:
|
|
@@ -268,11 +268,11 @@ jobs:
|
|
|
268
268
|
|
|
269
269
|
Allowed override refs are deliberately narrow:
|
|
270
270
|
|
|
271
|
-
| Ref form
|
|
272
|
-
|
|
|
273
|
-
| `train/v3/v3.0/<capability>`
|
|
274
|
-
| `refs/heads/train/v3/v3.0/<capability>` | Explicit branch ref for the same train
|
|
275
|
-
| `<40-character SHA>`
|
|
271
|
+
| Ref form | Meaning |
|
|
272
|
+
| --------------------------------------- | ------------------------------------------------------ |
|
|
273
|
+
| `train/v3/v3.0/<capability>` | Temporary capability train under the active minor line |
|
|
274
|
+
| `refs/heads/train/v3/v3.0/<capability>` | Explicit branch ref for the same train |
|
|
275
|
+
| `<40-character SHA>` | Exact immutable Buildchain runtime commit |
|
|
276
276
|
|
|
277
277
|
Override requests fail closed unless the event is `workflow_dispatch` and the
|
|
278
278
|
actor has write, maintain, or admin permission on the caller repository.
|
|
@@ -416,11 +416,11 @@ jobs:
|
|
|
416
416
|
|
|
417
417
|
`checkout-cache-mode` accepts:
|
|
418
418
|
|
|
419
|
-
| Mode
|
|
420
|
-
|
|
|
421
|
-
| `off`
|
|
422
|
-
| `auto`
|
|
423
|
-
| `require` | Require the cache to provide the locked commit and fail before lifecycle work if unavailable.
|
|
419
|
+
| Mode | Behavior |
|
|
420
|
+
| --------- | ----------------------------------------------------------------------------------------------------------- |
|
|
421
|
+
| `off` | Default. Buildchain fetches the locked commit from GitHub. |
|
|
422
|
+
| `auto` | Try the trusted cache first; on miss, record the miss and fall back according to `checkout-cache-fallback`. |
|
|
423
|
+
| `require` | Require the cache to provide the locked commit and fail before lifecycle work if unavailable. |
|
|
424
424
|
|
|
425
425
|
The cache can be a local/LAN mirror URL template or a runner-local bare
|
|
426
426
|
reference repository template. Templates support `{owner}`, `{repo}`,
|
|
@@ -484,38 +484,38 @@ separate periodic cleanup task.
|
|
|
484
484
|
|
|
485
485
|
The reusable workflow exposes the resolved contract:
|
|
486
486
|
|
|
487
|
-
| Output
|
|
488
|
-
|
|
|
489
|
-
| `runner-preset`
|
|
490
|
-
| `platforms-json`
|
|
491
|
-
| `platform-count`
|
|
492
|
-
| `linux-container-enabled`
|
|
493
|
-
| `linux-container-image`
|
|
494
|
-
| `build-summary-artifact`
|
|
495
|
-
| `build-diagnostics-summary-artifact`
|
|
496
|
-
| `release-candidate-passport-artifact` | Uploaded PR-stage release-candidate passport artifact name when `release-candidate` is enabled
|
|
497
|
-
| `release-candidate-passport-json`
|
|
498
|
-
| `build-summary-json`
|
|
499
|
-
| `build-diagnostics-summary-json`
|
|
500
|
-
| `trusted-event`
|
|
501
|
-
| `buildchain-runtime-ref`
|
|
502
|
-
| `buildchain-runtime-sha`
|
|
503
|
-
| `buildchain-runtime-class`
|
|
504
|
-
| `buildchain-runtime-override`
|
|
505
|
-
| `buildchain-runtime-trust-decision`
|
|
506
|
-
| `buildchain-contract-lock-status`
|
|
507
|
-
| `buildchain-contract-lock-drift`
|
|
508
|
-
| `buildchain-contract-digest`
|
|
509
|
-
| `publish-channel`
|
|
510
|
-
| `publish-allowed`
|
|
511
|
-
| `publish-reason`
|
|
512
|
-
| `publish-source-ref`
|
|
513
|
-
| `publish-source-sha`
|
|
514
|
-
| `publish-source-locked`
|
|
515
|
-
| `publish-source-channel`
|
|
516
|
-
| `publish-source-line`
|
|
517
|
-
| `publish-source-consumer-version`
|
|
518
|
-
| `release-manifest-json`
|
|
487
|
+
| Output | Meaning |
|
|
488
|
+
| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
489
|
+
| `runner-preset` | Resolved preset, or `custom` when `platforms-json` was provided |
|
|
490
|
+
| `platforms-json` | Exact matrix JSON used by the build job |
|
|
491
|
+
| `platform-count` | Number of matrix platforms |
|
|
492
|
+
| `linux-container-enabled` | `true` when Linux platforms are routed through a job container |
|
|
493
|
+
| `linux-container-image` | Resolved digest-pinned Linux job container image |
|
|
494
|
+
| `build-summary-artifact` | Uploaded aggregate summary artifact name |
|
|
495
|
+
| `build-diagnostics-summary-artifact` | Uploaded aggregate diagnostics summary artifact name |
|
|
496
|
+
| `release-candidate-passport-artifact` | Uploaded PR-stage release-candidate passport artifact name when `release-candidate` is enabled |
|
|
497
|
+
| `release-candidate-passport-json` | Compact release-candidate passport JSON when `release-candidate` is enabled |
|
|
498
|
+
| `build-summary-json` | Compact aggregate JSON with platform count, file count, and byte total |
|
|
499
|
+
| `build-diagnostics-summary-json` | Compact aggregate diagnostics JSON with platform, lifecycle warning/error, diagnostics contract warning, and sidecar manifest warning totals |
|
|
500
|
+
| `trusted-event` | `true` when the event is trusted enough to reach build runners |
|
|
501
|
+
| `buildchain-runtime-ref` | Runtime ref selected after applying the empty-default or override policy |
|
|
502
|
+
| `buildchain-runtime-sha` | Immutable Buildchain runtime commit used by all runtime checkouts |
|
|
503
|
+
| `buildchain-runtime-class` | `stable`, `alpha`, `authority`, `train`, `exact-sha`, or `development` |
|
|
504
|
+
| `buildchain-runtime-override` | `true` when an authority, train, or exact-SHA `buildchain-ref` override was accepted |
|
|
505
|
+
| `buildchain-runtime-trust-decision` | Runtime override trust decision |
|
|
506
|
+
| `buildchain-contract-lock-status` | `unchanged`, `compatible-drift`, `breaking-drift`, `missing-lock`, `non-floating-runtime`, or first-release `runtime-contract-unavailable` |
|
|
507
|
+
| `buildchain-contract-lock-drift` | `true` when the floating runtime SHA or contract digest changed |
|
|
508
|
+
| `buildchain-contract-digest` | Current Buildchain runtime contract digest |
|
|
509
|
+
| `publish-channel` | Resolved publish channel requested by the caller |
|
|
510
|
+
| `publish-allowed` | `true` only when this event/ref may publish after verification |
|
|
511
|
+
| `publish-reason` | Human-readable reason for the publish gate decision |
|
|
512
|
+
| `publish-source-ref` | Gate source ref that was resolved before checkout |
|
|
513
|
+
| `publish-source-sha` | Exact source commit used by checkout, build, verify, and artifacts |
|
|
514
|
+
| `publish-source-locked` | `true` when a `publish-gate/*` source ref was explicitly locked |
|
|
515
|
+
| `publish-source-channel` | `alpha`, `release`, `anchor`, or `major` parsed from the source ref |
|
|
516
|
+
| `publish-source-line` | Product line parsed from source refs such as `v22/v22.22` |
|
|
517
|
+
| `publish-source-consumer-version` | Consumer package version parsed from source refs |
|
|
518
|
+
| `release-manifest-json` | Resolved release manifest including source lock, version state, and anchor data |
|
|
519
519
|
|
|
520
520
|
The aggregate summaries are intentionally artifacts as well as outputs. GitHub
|
|
521
521
|
Actions matrix outputs are not a reliable place to carry every platform's full
|
|
@@ -564,9 +564,40 @@ and requested signature semantics, then publishes a deterministic
|
|
|
564
564
|
`<artifact>-signing-request-<platform>-<source-sha>` request. No consumer
|
|
565
565
|
workflow step is required.
|
|
566
566
|
|
|
567
|
+
The request root is a Buildchain-owned generated output. After the declaration,
|
|
568
|
+
lifecycle manifest, and source paths pass validation, sealing replaces that root
|
|
569
|
+
before materializing the current request set. This keeps repeated jobs on a
|
|
570
|
+
self-hosted runner idempotent and prevents stale requests from an earlier run
|
|
571
|
+
from entering the uploaded request artifact. An output root that contains the
|
|
572
|
+
workspace, working directory, lifecycle manifest, or any declared subject is
|
|
573
|
+
rejected before cleanup.
|
|
574
|
+
|
|
575
|
+
Self-hosted runners whose network requires different routes for Artifact upload
|
|
576
|
+
and download can scope an upload-only proxy bypass to the sealed signing request:
|
|
577
|
+
|
|
578
|
+
```yaml
|
|
579
|
+
with:
|
|
580
|
+
artifact-signing-request-upload-no-proxy: ".blob.core.windows.net"
|
|
581
|
+
```
|
|
582
|
+
|
|
583
|
+
The caller repository variable
|
|
584
|
+
`BUILDCHAIN_ARTIFACT_SIGNING_REQUEST_UPLOAD_NO_PROXY` provides the same value
|
|
585
|
+
without changing a consumer workflow; an explicit workflow input takes
|
|
586
|
+
precedence. When neither is set, Buildchain preserves the runner's existing
|
|
587
|
+
`NO_PROXY` and `no_proxy` values. The resolved value applies only to the
|
|
588
|
+
Buildchain-owned signing-request upload. Authority dispatch and immutable
|
|
589
|
+
signed-result download keep the runner's original proxy route. This is a
|
|
590
|
+
transport control only: it does not change request bytes, signing authority,
|
|
591
|
+
artifact identity, or verification policy.
|
|
592
|
+
|
|
567
593
|
`profile = "auto"` resolves signable Apple artifacts such as Mach-O files,
|
|
568
|
-
`.dylib`, `.framework`, `.app`, `.xpc`, `.plugin`, `.pkg`,
|
|
569
|
-
native `apple-developer-id` provider.
|
|
594
|
+
`.dylib`, `.framework`, `.app`, `.xpc`, `.plugin`, `.pkg`, `.dmg`, and macOS
|
|
595
|
+
archives containing native code to the native `apple-developer-id` provider.
|
|
596
|
+
For a declared macOS `archive`, the authority safely extracts the sealed
|
|
597
|
+
container, signs and verifies every Mach-O payload, signs Mach-O payloads inside
|
|
598
|
+
embedded Python wheels, rebuilds each affected wheel's PEP 427 `RECORD`, and
|
|
599
|
+
recreates the original zip or tar.gz before returning the exact final bytes.
|
|
600
|
+
Windows `pe` and `binary` artifacts
|
|
570
601
|
resolve to timestamped native `windows-authenticode`; Windows PE never falls
|
|
571
602
|
back to a detached signature. Linux and other non-native binary files,
|
|
572
603
|
archives, blobs, and directories resolve to `detached-signature-v1`. Buildchain records that as a
|
|
@@ -582,9 +613,29 @@ evidence. Consumer repositories neither receive nor duplicate credential-island
|
|
|
582
613
|
material. The reusable workflow dispatches the sealed request to the
|
|
583
614
|
Buildchain repository, waits for its protected authority workflow, verifies the
|
|
584
615
|
immutable result, replaces only the declared artifact with the returned final
|
|
585
|
-
bytes
|
|
586
|
-
|
|
587
|
-
|
|
616
|
+
bytes. The ordinary platform lane completes the consumer's functional
|
|
617
|
+
verification before delegation. A GitHub-hosted finalization lane then verifies
|
|
618
|
+
the authority result against the sealed request, imports the exact signed bytes,
|
|
619
|
+
and recomputes the final manifest before replacing the deterministic artifact.
|
|
620
|
+
The signing result is never downloaded back to a self-hosted native runner.
|
|
621
|
+
Platform manifests, KFD evidence, checksums, and Release Passport inputs
|
|
622
|
+
therefore observe the final signed artifact rather than the pre-signing build
|
|
623
|
+
output.
|
|
624
|
+
|
|
625
|
+
For a standalone Mach-O request, the authority requires strict Developer ID
|
|
626
|
+
verification, the declared Team ID, hardened runtime, and an `Accepted`
|
|
627
|
+
`notarytool` result for the exact submission. Apple creates the notarization
|
|
628
|
+
ticket for that binary and publishes it online, but
|
|
629
|
+
[standalone binaries do not support stapling](https://developer.apple.com/documentation/security/customizing-the-notarization-workflow).
|
|
630
|
+
Buildchain therefore records
|
|
631
|
+
`standalone-notary-ticket-online` and does not misapply app-bundle
|
|
632
|
+
`spctl --assess --type execute` semantics to the raw executable.
|
|
633
|
+
|
|
634
|
+
For a compound archive request, the authority notarizes the complete extracted
|
|
635
|
+
signed product tree and records `compound-notary-ticket-online`. A generic
|
|
636
|
+
archive container cannot carry a stapled ticket and is not itself a Gatekeeper
|
|
637
|
+
execution target; Gatekeeper evaluates the extracted signed code. Archive path
|
|
638
|
+
and symlink validation fail closed before any payload is signed.
|
|
588
639
|
|
|
589
640
|
The durable v3 authority runtime is
|
|
590
641
|
`authority/v3/v3.0/artifact-signing`. It is channel-neutral: alpha and stable
|
|
@@ -606,8 +657,17 @@ to GitHub artifacts:
|
|
|
606
657
|
```yaml
|
|
607
658
|
with:
|
|
608
659
|
artifact-transfer-mode: github-artifacts
|
|
660
|
+
artifact-compression-level: 0
|
|
609
661
|
```
|
|
610
662
|
|
|
663
|
+
Direct GitHub Artifact payloads default to compression level `0`. Buildchain
|
|
664
|
+
artifacts are commonly already-compressed archives; storing them without a
|
|
665
|
+
second compression pass shortens the upload window while preserving the same
|
|
666
|
+
artifact name, run/id/digest binding, retention, and no-overwrite behavior.
|
|
667
|
+
Callers may select `1` through `9` for payloads that materially benefit from
|
|
668
|
+
compression. Manifests and diagnostics retain their existing small-artifact
|
|
669
|
+
behavior.
|
|
670
|
+
|
|
611
671
|
Large self-hosted native builds can opt into the first-class S3 relay path:
|
|
612
672
|
|
|
613
673
|
```yaml
|
|
@@ -643,15 +703,15 @@ The relay configuration is intentionally generic. Buildchain does not hard-code
|
|
|
643
703
|
organization buckets, regions, or role ARNs. Callers may pass explicit inputs,
|
|
644
704
|
or set repository/organization variables and secrets using these names:
|
|
645
705
|
|
|
646
|
-
| Variable or secret
|
|
647
|
-
|
|
|
648
|
-
| `BUILDCHAIN_ARTIFACT_RELAY_S3_BUCKET`
|
|
649
|
-
| `BUILDCHAIN_ARTIFACT_RELAY_S3_REGION`
|
|
650
|
-
| `BUILDCHAIN_ARTIFACT_RELAY_S3_PREFIX`
|
|
651
|
-
| `BUILDCHAIN_ARTIFACT_RELAY_S3_ROLE_ARN`
|
|
652
|
-
| `BUILDCHAIN_ARTIFACT_RELAY_S3_UPLOAD_ROLE_ARN`
|
|
653
|
-
| `BUILDCHAIN_ARTIFACT_RELAY_S3_DOWNLOAD_ROLE_ARN` | Download OIDC role ARN for the GitHub-hosted relay job
|
|
654
|
-
| `BUILDCHAIN_ARTIFACT_RELAY_S3_OIDC_AUDIENCE`
|
|
706
|
+
| Variable or secret | Meaning |
|
|
707
|
+
| ------------------------------------------------ | ------------------------------------------------------- |
|
|
708
|
+
| `BUILDCHAIN_ARTIFACT_RELAY_S3_BUCKET` | Relay bucket name |
|
|
709
|
+
| `BUILDCHAIN_ARTIFACT_RELAY_S3_REGION` | Relay bucket region |
|
|
710
|
+
| `BUILDCHAIN_ARTIFACT_RELAY_S3_PREFIX` | Relay object prefix; defaults to `buildchain-artifacts` |
|
|
711
|
+
| `BUILDCHAIN_ARTIFACT_RELAY_S3_ROLE_ARN` | Shared OIDC role ARN for upload and download |
|
|
712
|
+
| `BUILDCHAIN_ARTIFACT_RELAY_S3_UPLOAD_ROLE_ARN` | Upload OIDC role ARN for self-hosted build jobs |
|
|
713
|
+
| `BUILDCHAIN_ARTIFACT_RELAY_S3_DOWNLOAD_ROLE_ARN` | Download OIDC role ARN for the GitHub-hosted relay job |
|
|
714
|
+
| `BUILDCHAIN_ARTIFACT_RELAY_S3_OIDC_AUDIENCE` | Optional OIDC audience override |
|
|
655
715
|
|
|
656
716
|
For AWS China regions, Buildchain defaults the OIDC audience to
|
|
657
717
|
`sts.amazonaws.com.cn`; other regions default to `sts.amazonaws.com`. The caller
|
|
@@ -965,7 +1025,7 @@ publish side effect:
|
|
|
965
1025
|
with:
|
|
966
1026
|
sha: ${{ needs.build.outputs.publish-source-sha }}
|
|
967
1027
|
target-ref: release/v22/v22.22
|
|
968
|
-
require-publish-source-lock:
|
|
1028
|
+
require-publish-source-lock: "true"
|
|
969
1029
|
publish-source-ref: ${{ needs.build.outputs.publish-source-ref }}
|
|
970
1030
|
publish-source-sha: ${{ needs.build.outputs.publish-source-sha }}
|
|
971
1031
|
publish-source-locked: ${{ needs.build.outputs.publish-source-locked }}
|
|
@@ -8,7 +8,7 @@ confidence: high
|
|
|
8
8
|
sensitivity: public
|
|
9
9
|
evidence_grade: B
|
|
10
10
|
review_state: self-reviewed
|
|
11
|
-
last_reviewed: 2026-07-
|
|
11
|
+
last_reviewed: 2026-07-29
|
|
12
12
|
ai_provenance:
|
|
13
13
|
model_family: GPT-5
|
|
14
14
|
product: Codex
|
|
@@ -54,6 +54,12 @@ matrix and aggregate. Matrix entries retain the Shifu plan digest, ordered gate
|
|
|
54
54
|
groups, required/advisory modes, action ids, definition digests, skips, and
|
|
55
55
|
unsupported selections.
|
|
56
56
|
|
|
57
|
+
Each matrix job timeout reserves the sum of the selected Gate action budgets
|
|
58
|
+
plus 30 minutes for Buildchain-owned checkout, toolchain setup, plan download,
|
|
59
|
+
receipt validation, and artifact upload. The total remains capped at GitHub's
|
|
60
|
+
six-hour job limit. This control-plane allowance does not enlarge any Shifu
|
|
61
|
+
Gate's own declared action budget or change its definition digest.
|
|
62
|
+
|
|
57
63
|
`github-hosted` declares only the inherent `node` capability. Projects that
|
|
58
64
|
need a native compiler, product artifacts, devices, or other facilities must
|
|
59
65
|
use a suitable preset or declare a custom matrix. Capabilities are scheduling
|
package/docs/versioning.md
CHANGED
|
@@ -1,3 +1,21 @@
|
|
|
1
|
+
---
|
|
2
|
+
status: draft
|
|
3
|
+
period: ongoing
|
|
4
|
+
theme: buildchain-versioning
|
|
5
|
+
doc_type: policy
|
|
6
|
+
source_level: local-files
|
|
7
|
+
confidence: high
|
|
8
|
+
sensitivity: public
|
|
9
|
+
evidence_grade: A
|
|
10
|
+
review_state: unreviewed
|
|
11
|
+
last_reviewed: 2026-07-30
|
|
12
|
+
ai_provenance:
|
|
13
|
+
model_family: GPT-5
|
|
14
|
+
product: Codex
|
|
15
|
+
generated_at: 2026-07-30
|
|
16
|
+
invisible_context_boundary: Live release and provider state must be verified independently.
|
|
17
|
+
---
|
|
18
|
+
|
|
1
19
|
# Buildchain Versioning
|
|
2
20
|
|
|
3
21
|
Buildchain uses semantic version lines to describe public contracts, not only
|
|
@@ -7,11 +25,11 @@ on.
|
|
|
7
25
|
|
|
8
26
|
## Lines
|
|
9
27
|
|
|
10
|
-
| Line
|
|
11
|
-
|
|
|
12
|
-
| Patch | Compatible fix, hardening, documentation correction, or implementation repair inside an existing surface.
|
|
28
|
+
| Line | Meaning |
|
|
29
|
+
| ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
30
|
+
| Patch | Compatible fix, hardening, documentation correction, or implementation repair inside an existing surface. |
|
|
13
31
|
| Minor | New compatible welded surface: reusable workflow output, CLI command family, config protocol, published subpath, evidence file, runner contract, or agent-readable artifact. |
|
|
14
|
-
| Major | Breaking semantic change, removed stable surface, changed branch/tag governance, or incompatible protocol rewrite.
|
|
32
|
+
| Major | Breaking semantic change, removed stable surface, changed branch/tag governance, or incompatible protocol rewrite. |
|
|
15
33
|
|
|
16
34
|
Kungfu minor lines are long-lived trains. `v2.0`, `v2.1`, and `v2.2` can each
|
|
17
35
|
receive many patch releases. The major ref, such as `v2`, points at the
|
|
@@ -59,23 +77,25 @@ repository changes are patch".
|
|
|
59
77
|
|
|
60
78
|
## Decision Log
|
|
61
79
|
|
|
62
|
-
| Date
|
|
63
|
-
|
|
|
64
|
-
| 2026-07-
|
|
65
|
-
| 2026-07-
|
|
66
|
-
| 2026-07-
|
|
67
|
-
| 2026-07-
|
|
68
|
-
| 2026-07-
|
|
69
|
-
| 2026-07-
|
|
70
|
-
| 2026-07-
|
|
71
|
-
| 2026-07-
|
|
72
|
-
| 2026-07-
|
|
73
|
-
| 2026-07-
|
|
74
|
-
| 2026-07-
|
|
75
|
-
| 2026-07-
|
|
76
|
-
| 2026-07-
|
|
77
|
-
| 2026-07-
|
|
78
|
-
| 2026-07-02 | open-minor
|
|
80
|
+
| Date | Action | Line | Faces | Class | Rationale | PR |
|
|
81
|
+
| ---------- | ------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
|
|
82
|
+
| 2026-07-30 | extend-minor | `v3.0` | reusable-build-workflow, observed-evidence-bundle, release-passport-json-reader, web-surface-release-governance | additive | Add bounded artifact compression and remote-read controls plus transactional derived evidence projections while repairing release-PR runtime handoff so production remains protected-main-only. | |
|
|
83
|
+
| 2026-07-29 | extend-minor | `v3.0` | artifact-signing-config, apple-developer-id-authority, artifact-signing-evidence | additive | Extend the consumer-neutral signing declaration to macOS compound archives, including nested wheel Mach-O signing, PEP 427 RECORD repair, safe archive reconstruction, and whole-product notarization under the same protected authority. | |
|
|
84
|
+
| 2026-07-28 | extend-minor | `v3.0` | auditable-demo-workflow, auditable-demo-media-profile, auditable-demo-media-receipt | additive | Add opt-in archive, web-delivery, and site-hero profiles; independently bind codec, container, audio, layout, byte-budget, role, and fast-start facts into a v2 media receipt while preserving the existing archive default. | |
|
|
85
|
+
| 2026-07-26 | extend-minor | `v3.0` | auditable-demo-workflow, auditable-demo-evidence | additive | Forward-port the consumer-neutral reusable Gate that binds exact same-run GitHub Artifacts to checked-in adapters and immutable renderer evidence, with optional media rendering only from the exact passing Gate bundle. | #1862 |
|
|
86
|
+
| 2026-07-23 | extend-minor | `v2.14` | credential-island-macos-input, protected-signer-job, macos-signing-evidence, action-subpaths | additive | The reusable build surface can seal an exact source-bound macOS app and hand it to a protected caller environment, where an immutable Buildchain action signs, notarizes, staples, Gatekeeper-assesses, and returns an auditable additional release-candidate platform without exposing credentials to consumer lifecycle jobs. | |
|
|
87
|
+
| 2026-07-20 | extend-minor | `v2.14` | anchored-derived-version-material, build-controller-evidence, release-passport, package-subpaths, release-propagation-controller | additive | Anchored/manual consumers can declare derived version witnesses that Buildchain regenerates and verifies before heavy builds, binds to exact alpha/release trees and passports, and admits during protected promotion; propagation receipts now model their existing optional consumer stages. | |
|
|
88
|
+
| 2026-07-17 | extend-minor | `v2.14` | merge-queue-config, release-line-governance-inheritance | additive | Buildchain config can explicitly enable, inherit, or disable exact dev-channel merge queues, and release-line bootstrap reconciles the declared or inherited policy before moving the repository default branch. | |
|
|
89
|
+
| 2026-07-16 | open-minor | `v2.14` | dev-merge-queue-governance | additive | The public CLI adds a dry-run-first, idempotent merge-queue governance command that verifies required workflow event compatibility before applying an exact dev-channel ruleset and removing the strict up-to-date race. | |
|
|
90
|
+
| 2026-07-15 | open-minor | `v2.13` | artifact-verification-envelope, package-subpaths | additive | The public envelope seals exact artifact, provenance, identity, lifecycle, revocation, and existing KFD assessment roots into one consumer-ready KFX admission input, with a dedicated Node API export and fail-closed verifier. | |
|
|
91
|
+
| 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. | |
|
|
92
|
+
| 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. | |
|
|
93
|
+
| 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. | |
|
|
94
|
+
| 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. | |
|
|
95
|
+
| 2026-07-03 | open-minor | `v2.4` | infra-contract-lifecycle | additive | Infra contract lifecycle adds the provider-neutral `infra-contract` CLI command family, project type, adapter capability contract, lifecycle evidence bundle, propagation evidence, CI evidence mode, and consumer-facing contract artifacts. | |
|
|
96
|
+
| 2026-07-02 | open-minor | `v2.3` | web-surface-host-mapping | additive | Web surface host mapping adds first-class multi-host surface bindings, reusable workflow URL outputs, per-surface deployment overrides, and an agent-readable fixture contract. | |
|
|
97
|
+
| 2026-07-02 | open-minor | `v2.2` | release-passport, binary-distribution | additive | Release passport and binary distribution add agent-readable release passport files, artifact evidence, impact ledger, agent index, GitHub Release collection and verification commands, and standalone binary assets. | |
|
|
98
|
+
| 2026-07-02 | open-minor | `v2.1` | logging-sdk, cli-observability, package-subpaths | additive | Buildchain toolkit observability adds the public logging SDK, CLI observability commands, and package subpaths that consumers can import. | |
|
|
79
99
|
|
|
80
100
|
## Runner Policy
|
|
81
101
|
|
|
@@ -1,3 +1,21 @@
|
|
|
1
|
+
---
|
|
2
|
+
status: draft
|
|
3
|
+
period: ongoing
|
|
4
|
+
theme: web-surface-deployments
|
|
5
|
+
doc_type: contract
|
|
6
|
+
source_level: local-files
|
|
7
|
+
confidence: high
|
|
8
|
+
sensitivity: public
|
|
9
|
+
evidence_grade: A
|
|
10
|
+
review_state: unreviewed
|
|
11
|
+
last_reviewed: 2026-07-30
|
|
12
|
+
ai_provenance:
|
|
13
|
+
model_family: GPT-5
|
|
14
|
+
product: Codex
|
|
15
|
+
generated_at: 2026-07-30
|
|
16
|
+
invisible_context_boundary: No credentials, private logs, or unpublished deployment values are included.
|
|
17
|
+
---
|
|
18
|
+
|
|
1
19
|
# Web-Surface Deployment Contract
|
|
2
20
|
|
|
3
21
|
Buildchain supports `project.type = "web-surface"` for repositories that publish
|
|
@@ -680,8 +698,9 @@ The reusable workflow maps GitHub events to Buildchain web-surface semantics:
|
|
|
680
698
|
| --- | --- |
|
|
681
699
|
| `pull_request` opened / synchronized / reopened | validate, build, verify, and plan `preview` for `pr-N` |
|
|
682
700
|
| `pull_request` closed | plan apply-mode cleanup for the `pr-N` preview alias and manifest |
|
|
701
|
+
| `pull_request` closed for a matching release PR | verify the release intent and exact workflow-shell runtime, then wait for the protected `main` push; do not plan or apply production from `refs/pull/*/merge` |
|
|
683
702
|
| `push` to `main` | validate, build, verify, plan and apply `staging` from the merged `main` SHA, then optionally open a production release PR |
|
|
684
|
-
| `push` to `main` from a matching release PR merge | validate the associated release PR, plan `production`, and enter the configured GitHub Environment gate |
|
|
703
|
+
| `push` to `main` from a matching release PR merge | validate the associated release PR, plan `production`, and enter the configured GitHub Environment gate from the protected mainline ref |
|
|
685
704
|
| `workflow_dispatch` with `production-approved = true` | plan `production` and enter the configured GitHub Environment gate |
|
|
686
705
|
|
|
687
706
|
The optional `buildchain-ref` input is empty by default. Empty keeps the
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@kungfu-tech/buildchain",
|
|
3
|
-
"version": "3.0.
|
|
3
|
+
"version": "3.0.3-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",
|
|
@@ -692,6 +692,7 @@ export function createBuildchainContractWorld({
|
|
|
692
692
|
? {
|
|
693
693
|
compatibleBreakingDigests: [
|
|
694
694
|
"sha256:e264a79f9f399038c2fcfd21e4168c68c2e1485ee5c651c02242a02b622ac2be",
|
|
695
|
+
"sha256:30745921541e9b0f70475bb2178c2559f6aef248f6680670ccd44d8c5a69a6b1",
|
|
695
696
|
],
|
|
696
697
|
}
|
|
697
698
|
: {}),
|
|
@@ -25,6 +25,7 @@ const CONTROLLER_SPECS = [
|
|
|
25
25
|
capabilities: [
|
|
26
26
|
"source-lock",
|
|
27
27
|
"lifecycle-build",
|
|
28
|
+
"artifact-signing-finalization",
|
|
28
29
|
"credential-island",
|
|
29
30
|
"lifecycle-verify",
|
|
30
31
|
"artifact-admission",
|
|
@@ -34,6 +35,7 @@ const CONTROLLER_SPECS = [
|
|
|
34
35
|
"resolve-source",
|
|
35
36
|
"anchored-release-preflight",
|
|
36
37
|
"build",
|
|
38
|
+
"signing-finalization",
|
|
37
39
|
"credential-island",
|
|
38
40
|
"verify",
|
|
39
41
|
"aggregate",
|
|
@@ -34,6 +34,9 @@ const target = (
|
|
|
34
34
|
allowedBypassActors,
|
|
35
35
|
});
|
|
36
36
|
const PUBLIC_REPOSITORY_TARGETS = Object.freeze({
|
|
37
|
+
".github": [
|
|
38
|
+
target("main", [check("governance")], false),
|
|
39
|
+
],
|
|
37
40
|
"agent-hub-demo": [
|
|
38
41
|
target("dev/v0/v0.2", [check("check / check")], true),
|
|
39
42
|
target("alpha/v0/v0.2", [check("check / check")], false),
|
|
@@ -60,9 +63,13 @@ const PUBLIC_REPOSITORY_TARGETS = Object.freeze({
|
|
|
60
63
|
target("alpha/v1/v1.0", [check("check / check")], true),
|
|
61
64
|
],
|
|
62
65
|
kungfu: [
|
|
63
|
-
target("dev/v4/v4.0", [
|
|
66
|
+
target("dev/v4/v4.0", [
|
|
67
|
+
check("Candidate source acceptance / check"),
|
|
68
|
+
check("Queue admission lease", null),
|
|
69
|
+
check("affected-native / linux"),
|
|
70
|
+
], true),
|
|
64
71
|
target("alpha/v4/v4.0", [
|
|
65
|
-
check("build"
|
|
72
|
+
check("build / Finalize build controller evidence"),
|
|
66
73
|
check("signoff"),
|
|
67
74
|
check("validate"),
|
|
68
75
|
], true),
|
|
@@ -81,6 +88,10 @@ const PUBLIC_REPOSITORY_TARGETS = Object.freeze({
|
|
|
81
88
|
true,
|
|
82
89
|
),
|
|
83
90
|
],
|
|
91
|
+
"runtime-images": [
|
|
92
|
+
target("dev/v1/v1.0", [check("Signed-off commits"), check("check")], true),
|
|
93
|
+
target("alpha/v1/v1.0", [check("Signed-off commits"), check("check")], false),
|
|
94
|
+
],
|
|
84
95
|
"paper-episodes-to-primitives": [
|
|
85
96
|
target("main", [check("governance")], false),
|
|
86
97
|
target("dev/v0/v0.1", [check("check / check")], true),
|
|
@@ -91,6 +102,11 @@ const PUBLIC_REPOSITORY_TARGETS = Object.freeze({
|
|
|
91
102
|
target("dev/v0/v0.1", [check("check / check")], true),
|
|
92
103
|
target("alpha/v0/v0.1", [check("check / check")], true),
|
|
93
104
|
],
|
|
105
|
+
"paper-kfd-machine-life-roadmap": [
|
|
106
|
+
target("main", [check("check / check")], false),
|
|
107
|
+
target("dev/v0/v0.1", [check("check / check")], true),
|
|
108
|
+
target("alpha/v0/v0.1", [check("check / check")], true),
|
|
109
|
+
],
|
|
94
110
|
"paper-kungfu-product-white-paper": [
|
|
95
111
|
target("main", [check("check / check")], false),
|
|
96
112
|
target("dev/v0/v0.1", [check("check / check")], true),
|
|
@@ -109,11 +125,6 @@ const PUBLIC_REPOSITORY_TARGETS = Object.freeze({
|
|
|
109
125
|
],
|
|
110
126
|
});
|
|
111
127
|
const PUBLIC_REPOSITORIES = Object.freeze(Object.keys(PUBLIC_REPOSITORY_TARGETS).sort());
|
|
112
|
-
const PRIVATE_REPOSITORY_IDENTITIES = Object.freeze([
|
|
113
|
-
"sha256:581823ab841e1d9a9025c92d0c47b164c6aaa1ea22112fdbc8d73bd2c862a05f",
|
|
114
|
-
"sha256:b7255e01d10000eb3a2786456b4c558178675ccb6cf28a6e39a74dbfe918df35",
|
|
115
|
-
"sha256:f41bd767e9c4a0ab429ca2a2f456d29ddefab0e996d75000ba36334689eb177e",
|
|
116
|
-
]);
|
|
117
128
|
const PROTECTED_AUTHORITY_PATHS = Object.freeze([
|
|
118
129
|
".github/CODEOWNERS",
|
|
119
130
|
".github/workflows/.publication-authority.yml",
|
|
@@ -477,6 +488,7 @@ export function createBuildchainGithubGovernanceAuthority() {
|
|
|
477
488
|
],
|
|
478
489
|
},
|
|
479
490
|
repositoryAdmission: {
|
|
491
|
+
managedVisibilities: ["public"],
|
|
480
492
|
publicRepositories: [...PUBLIC_REPOSITORIES],
|
|
481
493
|
publicAuthoritativeTargets: Object.fromEntries(
|
|
482
494
|
Object.entries(PUBLIC_REPOSITORY_TARGETS).map(([repository, targets]) => [
|
|
@@ -493,25 +505,21 @@ export function createBuildchainGithubGovernanceAuthority() {
|
|
|
493
505
|
})),
|
|
494
506
|
]),
|
|
495
507
|
),
|
|
496
|
-
privateRepositoryIdentities:
|
|
497
|
-
|
|
498
|
-
targetPolicy: "default-and-current-version-line",
|
|
499
|
-
requiredCheckPolicies: {},
|
|
500
|
-
})),
|
|
501
|
-
privateRepositoryPolicy: "non-authoritative-until-plan-capability-qualifies",
|
|
508
|
+
privateRepositoryIdentities: [],
|
|
509
|
+
privateRepositoryPolicy: "excluded-from-managed-zone",
|
|
502
510
|
unknownRepositoryPolicy: "non-authoritative-until-explicit-admission",
|
|
503
511
|
baseline: {
|
|
504
|
-
observedOn: "2026-07-
|
|
512
|
+
observedOn: "2026-07-30",
|
|
505
513
|
repositoryCount: 16,
|
|
506
|
-
publicCount:
|
|
507
|
-
privateCount:
|
|
514
|
+
publicCount: 16,
|
|
515
|
+
privateCount: 0,
|
|
508
516
|
authoritativePublicTargetCount: Object.values(PUBLIC_REPOSITORY_TARGETS)
|
|
509
517
|
.reduce((count, targets) => count + targets.length, 0),
|
|
510
518
|
},
|
|
511
519
|
},
|
|
512
520
|
planCapability: {
|
|
513
521
|
publicRepositories: ["free", "team", "enterprise"],
|
|
514
|
-
privateRepositories: [
|
|
522
|
+
privateRepositories: [],
|
|
515
523
|
organizationRulesets: ["team", "enterprise"],
|
|
516
524
|
},
|
|
517
525
|
effectivePolicy: {
|