@kungfu-tech/buildchain 2.14.18-alpha.1 → 2.14.18-alpha.11

package/docs/publish-transaction.md

@@ -363,6 +363,73 @@ When publish transactions are enabled, promotion order is:
 7. move floating tags and channel refs;
 8. mark the transaction `complete`.
 
+When a protected channel requires a generated version-state pull request, the
+first run can stop at `finalizing` after registry publication. If the reviewed
+merge commit later contains that exact transaction release material but the
+exact tag is still absent, a retry performs finalization only: it reloads the
+same durable source, release material, tooling, evidence, version, and target
+bindings; creates the exact and floating tags at the transaction release SHA;
+and completes the passport from the transaction source tree. It does not rerun
+the provider mutation and does not authorize the newer composite channel tree
+as published material. A different source tree still requires a new version and
+a fresh release candidate.
+
+Deferred binary dispatch, controller-evidence bundling, and any consumer
+publication commit are skipped while `finalization-needed=true`. They run only
+after the exact public tag and complete release passport exist.
+
+Consumer products that expose a signed well-known channel can opt into one
+additional, deliberately final step with `publication-commit-command`. Before
+that command runs, Buildchain has already completed the transaction, created
+the public GitHub Release, and uploaded every release-passport file plus the
+explicit PR-stage payload files selected by
+`github-release-payload-patterns`. The command is therefore a commit point for
+discovery authority, not another artifact publisher.
+
+The command receives the exact version, source SHA, release SHA, release tag,
+release passport path, and downloaded payload directory through
+`BUILDCHAIN_PUBLICATION_COMMIT_*`. Optional consumer-owned dispatch/API
+credentials and private signing material are exposed separately as
+`BUILDCHAIN_PUBLICATION_COMMIT_TOKEN` and
+`BUILDCHAIN_PUBLICATION_COMMIT_SIGNING_KEY`; Buildchain never logs, persists,
+or interprets either value. The command must write
+`.buildchain/publication-commit/evidence.json` (or another declared path below
+`.buildchain/`) with this contract:
+
+```json
+{
+  "schema": "kungfu-buildchain-publication-commit-evidence/v1",
+  "status": "passed",
+  "identity": {
+    "version": "4.0.0-alpha.2",
+    "sourceSha": "<source-sha>",
+    "releaseSha": "<release-sha>",
+    "releaseTag": "v4.0.0-alpha.2"
+  },
+  "publication": {
+    "url": "https://example.test/.well-known/product/alpha.json",
+    "payloadRoot": "sha256:<64-lowercase-hex>"
+  },
+  "readback": {
+    "status": "passed",
+    "url": "https://example.test/.well-known/product/alpha.json",
+    "payloadRoot": "sha256:<same-root>"
+  },
+  "recovery": {
+    "previousAuthority": "preserved",
+    "rollbackReference": "sha256:<previous-root>"
+  }
+}
+```
+
+Buildchain rejects stale evidence, identity drift, non-public or mutable URLs,
+read-back root drift, and missing recovery evidence. It also rejects
+`standalone-binary-distribution=true` with a final commit command because that
+would queue product mutations after the authority moved. On any command or
+read-back failure, the consumer must leave the previous well-known document
+authoritative; Buildchain does not retry the command behind a successful
+receipt.
+
 If protected branch finalization is interrupted after publish evidence is
 valid, the transaction can stop in `finalizing` and output
 `finalization-needed=true`. A later run resumes from the same transaction state
@@ -374,10 +441,12 @@ the exact generated version-state commit so branch protection can
 validate the automation path without a second build, then uses the generated
 ref update token for the protected ref PATCH. If release finalization
 bookkeeping is still rejected, Buildchain creates or reuses a same-repository
-`buildchain/version-state/*` PR based on the current target channel head and
-leaves the transaction resumable with `finalization-needed=true`. Strict alpha
-bookkeeping remains fail-fast. The reusable wrapper defaults that token to
-`secrets.BUILDCHAIN_PROMOTION_TOKEN || github.token`.
+`buildchain/version-state/*` PR and leaves the transaction resumable with
+`finalization-needed=true`. Strict alpha uses the same protected PR fallback
+for both its target channel and subsequent dev reconciliation. A later
+idempotent run continues only after the provider shows that the PR reached the
+protected branch. The reusable wrapper binds that token to the run-scoped
+`github.token` and rejects user, team, or alternate App bypass actors.
 
 If finalization fails after an exact Git tag, a channel branch, or dev/alpha
 sync ref has already moved, the next run reads the durable `finalizing` state

package/docs/release-governance.md

@@ -703,29 +703,28 @@ same material binding.
 Protected release-line branches keep their normal human review gate. Managed
 `dev/vN/vN.M`, `alpha/vN/vN.M`, and `release/vN/vN.M` branches are configured
 with one required approving review, required GitHub Actions checks, administrator
-enforcement, conversation resolution, no force pushes, and no deletions. Dev
-keeps its repository-selected strict or merge-queue policy. Alpha and release
-require both `check` and the pair-specific `verify` aggregate without requiring
-the source branch to contain the target's generated bookkeeping history. The
+enforcement, conversation resolution, no force pushes, and no deletions. Each
+target uses the exact check set, GitHub App identity, and strictness declared by
+the governance authority descriptor. The
 reusable `release-candidate-promote.yml` wrapper defaults
 `branch-protection-bypass-apps` to `github-actions`, which lets the workflow's
 automation identity apply generated version-state or post-publish channel
 bookkeeping after the reviewed channel PR has merged. Direct
-`promote-buildchain-ref` callers must opt into the same controlled bypass with
-`branch-protection-bypass-apps`, `branch-protection-bypass-users`, or
-`branch-protection-bypass-teams`; the action also adds the current promotion
-token's authenticated user or app to the managed bypass allowlist. Before
+`promote-buildchain-ref` callers may opt into that one controlled bypass with
+`branch-protection-bypass-apps: github-actions`; every other App slug and all
+user or team bypass actors are rejected. Before
 patching a protected generated bookkeeping ref, the action creates the
 full configured required-check set on the exact generated version-state commit, so strict
 status checks are satisfied by machine-verifiable Buildchain evidence rather
 than a human PR. The protected ref PATCH itself uses the generated ref update
-token; the reusable wrapper defaults it to
-`secrets.BUILDCHAIN_PROMOTION_TOKEN || github.token`. If direct generated
+token; the reusable wrapper binds it to the run-scoped `github.token`. If direct generated
 release finalization bookkeeping is still rejected, Buildchain creates or
-reuses a same-repository `buildchain/version-state/*` PR based on the current
-target channel head and records `finalization-needed=true` in the durable
-transaction output. Strict alpha bookkeeping still fails with a
-token/protection diagnostic instead of creating a post-publish PR.
+reuses a same-repository `buildchain/version-state/*` PR and records
+`finalization-needed=true` in the durable transaction output. Strict alpha
+follows the same provider-enforced PR path for its alpha and dev bookkeeping.
+The PR remains subject to the declared review, required checks, and merge-queue
+policy; publication resumes idempotently after that protected transaction
+lands.
 
 For a stable release, the wrapper also checks out the exact current development
 channel into `.buildchain/reconciliation/dev`. When the prepared next-alpha
@@ -734,16 +733,14 @@ promotion action applies the next version to that checkout, regenerates every
 declared derived version-state file, reruns the verification lifecycle, and
 only then creates the two-parent reconciliation commit. A checkout/current-ref
 SHA mismatch blocks reconciliation instead of committing stale projections.
-Buildchain's own promotion workflow reads `BUILDCHAIN_PROMOTION_BYPASS_APPS`,
-`BUILDCHAIN_PROMOTION_BYPASS_USERS`, and
-`BUILDCHAIN_PROMOTION_BYPASS_TEAMS` repository variables so the declared bypass
-identity can match the actual `BUILDCHAIN_PROMOTION_TOKEN` actor, but consumers
-do not need to duplicate that actor manually when the token identity is
-discoverable. Buildchain's release-line bootstrap applies the same declared
-allowances when it creates new `dev`, `alpha`, and `release` branch protection,
-and fails closed before changing protection when no promotion authority is
-declared. This keeps a new minor line publishable without weakening its normal
-human review gate.
+Buildchain's own promotion workflow accepts only
+`BUILDCHAIN_PROMOTION_BYPASS_APPS=github-actions`, defaulting to that exact App
+when the variable is absent. Buildchain's release-line bootstrap uses the
+administrator-scoped promotion token only to configure protection; branch
+creation and generated ref updates use the run-scoped token. New channel
+protection binds required checks to GitHub Actions App id `15368`, enables Code
+Owner, stale-review, and latest-push review gates, and admits no user or team
+bypass actor.
 
 ## What This Guarantees
 
@@ -830,6 +827,23 @@ bytes, uploads only missing assets, and fails with an immutable-release
 collision when a same-name asset has different bytes. It never deletes and
 replaces an existing asset during retry or duplicate workflow delivery.
 
+Product payloads are included only through the explicit
+`github-release-payload-patterns` input. Patterns match basenames inside the
+downloaded PR-stage RC payload bundle; zero matches or duplicate public
+basenames fail closed. This preserves the exact PR-built bytes instead of
+rebuilding archives during promotion.
+
+Consumers with a signed well-known discovery document can additionally provide
+`publication-commit-command`. The advanced promotion workflow validates its
+topology before any publish-gate or release mutation, then runs it only after
+the GitHub Release and its immutable payload/passport assets exist. The command
+must publicly read back the exact new payload root and emit
+`kungfu-buildchain-publication-commit-evidence/v1`; that evidence is copied
+into the controller artifact and exposed as workflow outputs. The previous
+authority must remain valid on every failure. Deferred standalone binary
+distribution is incompatible with this mode because the discovery authority
+must be the final product mutation.
+
 Buildchain also does not maintain bare exact tags such as `1.0.0`. The supported
 exact release and alpha refs are v-prefixed:
 

package/docs/reusable-build-surface.md

@@ -519,7 +519,9 @@ diagnostics artifacts first.
 ## macOS Credential Island
 
 Alpha consumers can ask the build controller to seal one exact macOS app and
-hand it to a separate protected signing job:
+hand it to a separate protected signing job. The built-in mode is suitable
+when the protected environment belongs to the repository that defines the
+reusable workflow:
 
 ```yaml
 with:
@@ -528,14 +530,31 @@ with:
   credential-island-macos-platform-id: macos-arm64
 ```
 
+For a cross-repository reusable workflow, keep the credentials in the consumer
+repository and select caller-owned mode:
+
+```yaml
+with:
+  credential-island-macos-app-path: product/dist/desktop/mac-arm64/Kungfu Episodes.app
+  credential-island-caller-owned: true
+  credential-island-macos-platform-id: macos-arm64
+```
+
+The caller then runs its own no-checkout macOS job after the reusable build,
+binds the consumer-owned protected environment on that job, and downloads the
+source-bound input plus immutable action runtime from the same workflow run.
+This is required for cross-repository callers because environment credentials
+must never be widened into repository secrets merely to cross a reusable
+workflow boundary.
+
 The ordinary matrix uploads
 `credential-island-input-<platform>-<source-sha>`, containing a `ditto`
 archive and a manifest bound to the caller repository, source commit, source
 tree, bundle identity, version, size, and digest. The pinned reusable workflow
-then starts a separate GitHub-hosted macOS job that names the caller
-environment. That job has no source checkout or package-manager step: it
-downloads the immutable Buildchain action runtime plus the sealed app and never
-invokes consumer code.
+either starts its built-in GitHub-hosted macOS job or leaves that job to the
+caller. In both modes the credential-bearing job has no source checkout or
+package-manager step: it downloads the immutable Buildchain action runtime plus
+the sealed app and never invokes consumer code.
 
 The protected environment supplies these non-secret variables:
 
@@ -781,12 +800,11 @@ floating `@v2` consumers receive publish-side source-lock drift protection by
 default. It also defaults `branch-protection-bypass-apps` to `github-actions`
 so the workflow automation can apply generated version-state and channel
 bookkeeping on protected `dev`/`alpha`/`release` branches after the reviewed
-channel PR has merged; consumers using a different promotion identity can pass
-`branch-protection-bypass-users`, `branch-protection-bypass-teams`, or a
-different app slug declaratively. The wrapper uses
-`secrets.BUILDCHAIN_PROMOTION_TOKEN || github.token` as the generated ref update
-token for protected bookkeeping PATCH calls, so a bypass-capable promotion token
-can sync dev immediately after alpha/release publish without a post-publish PR.
+channel PR has merged. Other App slugs and all user or team bypass actors are
+rejected. The wrapper uses the run-scoped `github.token` as the generated ref
+update token for protected bookkeeping PATCH calls, so the exact GitHub Actions
+App authority can sync dev immediately after alpha/release publish without a
+post-publish PR.
 It does not call `.build.yml`, does not create a matrix, and must fail before
 publish if the RC evidence, payload set, or source-lock ref is missing or
 ambiguous.

package/docs/web-surface-deployments.md

@@ -944,6 +944,52 @@ The project may use pnpm, npm, yarn, Vite, Astro, Next static export, Sphinx,
 MkDocs, CMake-generated docs, or another lifecycle command source. Buildchain
 only needs a deterministic artifact path and the manifest facts.
 
+## Signed bootstrap installer publications
+
+A web-surface artifact that contains `installer-publication.json` opts into the
+`kungfu.bootstrap-installer-publication/v1` seam. During planning, Buildchain
+fails closed unless the manifest binds:
+
+- one signed-channel payload root and exact channel-file digest;
+- one source SHA and Release Passport;
+- unique platform/architecture entries with manifest, artifact, and archive
+  digest roots; and
+- byte-identical friendly and immutable `install.sh` / `install.ps1` assets.
+
+The resulting `kungfu-buildchain-installer-publication-evidence/v1` object and
+root are welded into the deployment manifest. This does not make Buildchain the
+product installer authority: Kungfu generates the installer from its signed
+release channel, while the site owns only routes and presentation.
+
+The site artifact should also declare the existing
+`kungfu-buildchain-publication-archive-policy` in its root `manifest.json`, with
+the versioned installer directory as `immutablePath`. Buildchain then performs
+pre-upload object digest checks, `--no-overwrite` upload, post-upload checks, and
+excludes the immutable root from mutable deletion.
+
+Local verification:
+
+```sh
+node scripts/installer-publication.mjs \
+  --manifest dist/installer-publication.json \
+  --artifact-root dist
+```
+
+After preview, staging, or production apply, public read-back verifies exact
+bytes plus route semantics. Friendly routes require a revalidated cache policy
+with `max-age` no greater than 300 seconds; immutable routes require at least
+one year and the `immutable` directive:
+
+```sh
+node scripts/installer-publication.mjs \
+  --manifest dist/installer-publication.json \
+  --public-readback
+```
+
+Redirects are not accepted as successful read-back. The evidence retains
+content type, cache control, ETag, object version id when exposed, size, digest,
+URL, channel root, source SHA, and Release Passport coordinates.
+
 ## Boundaries
 
 Buildchain only performs live AWS mutations in explicit apply modes with

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "2.14.18-alpha.1",
+  "version": "2.14.18-alpha.11",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",
@@ -37,6 +37,7 @@
     "./publication-authority": "./packages/core/publication-authority.js",
     "./publication-control-plane-audit": "./packages/core/publication-control-plane-audit.js",
     "./buildchain-publication-authority": "./packages/core/buildchain-publication-authority.js",
+    "./github-governance-authority": "./packages/core/github-governance-authority.js",
     "./kfd-gate": "./packages/core/kfd-gate.js",
     "./release-candidate": "./packages/core/release-candidate.js",
     "./stable-candidate-ledger": "./packages/core/stable-candidate-ledger.js",

package/packages/core/buildchain-kfd-claims.js

@@ -17,6 +17,7 @@ export const BUILDCHAIN_AGENT_MANUALS = Object.freeze([
   { id: "release-passport", title: "Release Passport protocol", path: "docs/release-passport.md", plane: "verify" },
   { id: "controller-evidence", title: "Controller evidence contract", path: "docs/controller-evidence.md", plane: "verify" },
   { id: "publication-authority", title: "Sealed publication authority", path: "docs/publication-authority.md", plane: "verify" },
+  { id: "github-governance-authority", title: "GitHub governance authority", path: "docs/github-governance-authority.md", plane: "verify" },
   { id: "release-candidate", title: "Release Candidate Passport", path: "docs/release-candidate.md", plane: "verify" },
   { id: "release-propagation", title: "Release propagation", path: "docs/release-propagation.md", plane: "use" },
   { id: "readme-badges", title: "README badge blocks", path: "docs/readme-badges.md", plane: "use" },
@@ -74,6 +75,7 @@ const SCHEMA_AND_STANDARD_FILES = Object.freeze([
   "packages/core/publication-authority.js",
   "packages/core/publication-control-plane-audit.js",
   "packages/core/buildchain-publication-authority.js",
+  "packages/core/github-governance-authority.js",
   "packages/core/buildchain-kfd-claims.js",
   "packages/core/kfd3-surface-register.js",
   "packages/core/public-surface-audit.js",

package/packages/core/buildchain-publication-authority.js

@@ -28,6 +28,7 @@ const DESCRIPTORS = Object.freeze([
   [".github/workflows/buildchain-stable-candidate-patrol.yml", "governance-write"],
   [".github/workflows/dev-merge-queue-governance.yml", "governance-write"],
   [".github/workflows/dev-pr-auto-merge.yml", "governance-write"],
+  [".github/workflows/github-governance-audit.yml", "governance-write"],
   [".github/workflows/npm-publish.yml", "dry-run-only"],
   [".github/workflows/paper-release-sealed.yml", "product-publication", true, ["npm-publish", "github-release"], "trusted-publishing", "none", "fixed", "caller-bound"],
   [".github/workflows/paper-release.yml", "product-publication", true, ["npm-publish", "github-release"], "trusted-publishing", "none", "fixed", "caller-bound"],

package/packages/core/controller-evidence.js

@@ -7,7 +7,7 @@ export const BUILDCHAIN_CONTROLLER_AGGREGATE_CONTRACT = "buildchain.controller-e
 
 const SHA256_PATTERN = /^sha256:[0-9a-f]{64}$/;
 const GIT_SHA_PATTERN = /^[0-9a-f]{40}$/;
-const STAGE_STATUSES = new Set(["passed", "failed", "skipped", "cancelled", "missing"]);
+const STAGE_STATUSES = new Set(["passed", "failed", "skipped", "cancelled", "missing", "partial"]);
 
 const CONTROLLER_SPECS = [
   {