@kungfu-tech/buildchain 3.0.2-alpha.0 → 3.0.2-alpha.10

package/docs/dev-alpha-candidate-patrol.md

@@ -0,0 +1,111 @@
+---
+status: preview
+period: ongoing
+theme: dev-alpha-candidate-patrol
+doc_type: architecture-and-usage
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: A
+review_state: self-reviewed
+last_reviewed: 2026-07-27
+ai_provenance:
+  model_family: GPT-5
+  product: Codex
+  generated_at: 2026-07-27
+  visible_context: Existing Buildchain stable-candidate source locks, Kungfu exact-source Alpha preflight, Dev Patrol, and repository release governance.
+  invisible_context_boundary: No credentials, private logs, or private configuration were used.
+---
+
+# Dev to Alpha Candidate Patrol
+
+Buildchain provides a reusable observation and single-flight PR controller for
+repositories that promote a development branch into a protected Alpha branch.
+It does not publish Alpha. The read-only observer reads the exact heads of both
+branches, walks the
+bounded development history from newest to oldest (stopping early at the Alpha
+head), and selects the newest commit that satisfies all of these conditions:
+
+- the source is strictly ahead of the recorded target head;
+- the latest completed Dev Patrol for that exact commit SHA succeeded;
+- the latest completed Alpha preflight for the same commit SHA succeeded; and
+- both runs are within the caller's evidence age limit.
+
+The selected commit can be behind the observed development head when newer
+commits have not completed both workflows yet. The decision binds the observed
+head, selected SHA, and count of skipped newer commits. This makes a slow native
+verification lane live under continuous development without silently treating
+an unqualified head as releasable.
+
+History discovery is bounded to the newest 1000 development commits. The
+controller then compares the selected SHA to the exact Alpha head before it can
+be eligible, so a bounded scan cannot turn a commit outside the promotion
+ancestry into a candidate.
+
+The decision is `kungfu-buildchain-channel-candidate-decision/v1`. It records the
+source and target branches and SHAs, comparison distance, workflow paths, run
+identities and attempts, completion times, URLs, policy, and a canonical decision
+root. Missing, stale, failed, duplicate, or source-mismatched evidence fails
+closed as an auditable `blocked` or `stale` observation and cannot enter
+settlement.
+
+The companion state is
+`kungfu-buildchain-dev-alpha-candidate-state/v1`. Its current state is one of:
+
+- `observed`: no exact candidate is currently settleable;
+- `eligible-for-settlement`: a qualified candidate exists and no managed Alpha
+  candidate PR is active;
+- `active`: exactly one managed candidate PR is open;
+- `retained-next`: an active PR remains authoritative and the newest different
+  qualified SHA is retained as `nextCandidate`;
+- `stale`: the available exact-SHA evidence pair is outside policy age; or
+- `blocked`: qualification or reconciliation failed closed.
+
+When a newer qualified SHA replaces an earlier `nextCandidate`, the state also
+records that earlier SHA as `supersededCandidate`. Every state carries exact
+repository, source/target refs and SHAs, workflow-run evidence through the
+candidate decision, and canonical decision/state roots.
+
+## Reusable workflow
+
+Call `.github/workflows/dev-alpha-candidate-patrol.yml` from a thin repository
+workflow. Start with `dry-run: true`. The reusable workflow always runs an
+`observe` job with only Actions/content/pull-request read permissions. Once the
+repository has proven that its two workflow names and branch topology produce
+exact same-SHA evidence, it may set `settlement-authorized: true` and
+`dry-run: false`. The older `create-pull-request` input remains a compatibility
+alias for settlement authorization.
+
+Repositories whose promotion policy requires a machine-readable PR declaration
+can pass it through `pull-request-body-prefix`. Buildchain prepends that trusted,
+repository-owned text only when it creates the candidate PR and preserves it
+when later controller observations update the managed state marker. Keep the
+declaration source-controlled in the caller workflow and update it whenever the
+qualified development delta changes its release or architecture settlement.
+Buildchain rejects a prefix that attempts to inject its managed controller
+marker.
+
+The separately permissioned `settle` job re-runs the exact observation before
+any write. With no active managed candidate, it creates one branch named from
+the target branch and the first 12 characters of the full source SHA. An
+existing branch must point to the same full SHA or the run fails. With one
+active managed candidate, it only updates the machine-readable state marker in
+that PR body so repeated events and rapid dev progress cannot create another
+candidate PR or another heavy candidate build. Foreign human-authored Alpha PRs
+are ignored. More than one open Buildchain-managed candidate fails closed.
+
+The PR body is the bounded durable controller state: it preserves the active
+candidate and newest retained `nextCandidate` without introducing an always-on
+service. Once the active PR settles or is abandoned, the next execution
+recomputes current exact-SHA qualification and creates only the newest still
+fresh candidate. It never trusts a `workflow_run` trigger SHA as evidence.
+
+Consumers should invoke this workflow after relevant qualification workflow
+completion and from an offset periodic fallback. GitHub may delay scheduled
+runs, so the event path supplies low latency while the fallback supplies
+recovery. Workflow concurrency plus the server-side open-PR reconciliation
+makes duplicate or delayed events idempotent.
+
+The workflow never moves the Alpha ref directly, merges or auto-merges the pull
+request, publishes npm, creates a Git tag or GitHub Release, or changes branch
+protection. Those remain repository-owned protected settlement actions.

package/docs/github-artifact-attestation.md

@@ -0,0 +1,219 @@
+---
+status: draft
+period: 2026-07
+theme: buildchain-linux-artifact-provenance
+doc_type: protocol
+source_level: code-and-official-docs
+confidence: high
+sensitivity: public
+evidence_grade: A
+review_state: unreviewed
+last_reviewed: 2026-07-24
+ai_provenance:
+  model_family: GPT-5
+  product: Codex
+  generated_at: 2026-07-24
+  visible_context: Buildchain source, tests, GitHub Actions documentation, and actions/attest documentation
+  invisible_context: Model internals and provider-side implementation details are not visible
+---
+
+# GitHub-native Linux Artifact Attestation
+
+Buildchain can bind a Linux release artifact to its original compiler run, exact
+source revision, platform manifest, Release Passport, and an immutable
+Buildchain attester workflow. GitHub's OIDC identity and artifact attestation
+service provide the keyless signature; Buildchain provides the release contract
+and fail-closed local verification.
+
+This capability proves provenance and integrity. It does not prove that source
+code is safe, that a compiler was uncompromised, or that a self-hosted build
+runner had no privileged observer.
+
+## Trust Boundary
+
+The original Linux runner remains the compiler identity. The reusable attester
+runs on `ubuntu-24.04` only after the artifact, platform manifest, and Release
+Passport have been sealed and uploaded. It downloads those files as data and
+never checks out or executes consumer source.
+
+The attester checks out only
+`actions/github-artifact-attestation` from an exact Buildchain commit. It
+rejects a floating Buildchain ref, a different caller repository, a different
+source SHA, a different workflow run, a non-Linux platform manifest, or a
+subject digest absent from the Release Passport.
+
+The protected Environment defaults to `buildchain-artifact-attestation`.
+Consumer repositories should require review or restrict deployment branches on
+that Environment when their release policy requires an independent gate.
+
+## Non-circular Passport Binding
+
+The Release Passport first records
+`githubArtifactAttestations[]`, an immutable expected-attestation policy:
+
+- artifact name, relative path, byte size, and SHA-256;
+- caller repository, source commit, and source tree;
+- original Linux platform and platform-manifest digest; the initial v3 contract
+  requires the runner receipt root to equal that exact manifest digest;
+- Buildchain signer workflow path and exact signer-bootstrap commit;
+- exact Buildchain runtime commit used to build and release the artifact;
+- exact GitHub permission set.
+
+The GitHub attestation predicate then records the completed Release Passport
+file digest. The returned attestation id, URL, Sigstore bundle digest, and
+predicate root are written to a separate
+`buildchain.github-artifact-attestation-evidence/v1` document. Keeping dynamic
+provider evidence outside the Passport avoids a self-referential hash while
+still binding both directions.
+
+## GitHub Permissions and Runtime Pins
+
+Both caller and reusable workflow grant only:
+
+```yaml
+permissions:
+  actions: read
+  artifact-metadata: write
+  attestations: write
+  contents: read
+  id-token: write
+```
+
+The reusable workflow pins `actions/checkout`, `actions/download-artifact`,
+`actions/upload-artifact`, and `actions/attest` by full commit SHA. The workflow
+itself must also be called at its exact signer-bootstrap commit. The signer
+commit and the later Buildchain runtime commit are separately bound so the
+first v3 integration never relies on a mutable or self-referential workflow ref.
+
+## Prepare the Release Passport
+
+Create one input document for each Linux artifact and seal it as a policy:
+
+```bash
+buildchain create github-artifact-attestation-policy \
+  --input-json .buildchain/github-artifact-attestation/policy-input.json \
+  --output .buildchain/github-artifact-attestation/policy.json
+```
+
+The input object contains `subject`, `caller`, `signer`, and `build` objects.
+The CLI computes no trusted values implicitly: the caller supplies the already
+measured subject size/digest, source commit/tree, platform-manifest digest,
+runner receipt root, and exact Buildchain workflow commit.
+
+Pass the policy into Release Passport collection:
+
+```bash
+buildchain collect github-release \
+  --github-artifact-attestation-policy-json \
+    .buildchain/github-artifact-attestation/policy.json \
+  --output-dir .buildchain/release-passport \
+  # ...the existing release inputs
+```
+
+The build, Passport, and attestation jobs must stay in the same workflow run.
+The release-candidate build declares both the subject and the already-merged
+signer bootstrap commit. The Buildchain runtime remains the exact runtime ref
+used by the build workflow and may be a later commit:
+
+```yaml
+with:
+  github-artifact-attestation-subject-path: dist/kungfu-linux-x64.tar.gz
+  github-artifact-attestation-signer-sha: <exact-signer-bootstrap-sha>
+  github-artifact-attestation-platform-id: linux-x64
+```
+
+For release promotion, prefer the integrated v3 route. The policy must already
+be present in the downloaded release-candidate payload:
+
+```yaml
+permissions:
+  actions: write
+  artifact-metadata: write
+  attestations: write
+  checks: write
+  contents: write
+  id-token: write
+  issues: write
+
+jobs:
+  promote:
+    uses: kungfu-systems/buildchain/.github/workflows/release-candidate-promote.yml@<exact-buildchain-v3-runtime-sha>
+    with:
+      buildchain-ref: <exact-buildchain-v3-runtime-sha>
+      github-release: true
+      release-passport: true
+      github-artifact-attestation-policy-json: .buildchain/release-candidate/payload/<artifact>/policy.json
+      github-artifact-attestation-environment: buildchain-artifact-attestation
+```
+
+Promotion binds the policy into the Passport, stages only digest-matching data,
+calls the exact v3 signer, verifies the provider identity a second time, and
+publishes immutable bundle, predicate, verification, evidence, and receipt
+assets beside the release artifact. A same-name Release asset with different
+bytes is rejected instead of overwritten.
+
+Low-level callers may call the reusable attester directly after their Passport
+job. Both the reusable workflow ref and `buildchain-ref` use the same exact
+40-hex signer-bootstrap commit and fail closed if the provider identity differs:
+
+```yaml
+jobs:
+  attest-linux:
+    needs: [build-linux, release-passport]
+    permissions:
+      actions: read
+      artifact-metadata: write
+      attestations: write
+      contents: read
+      id-token: write
+    uses: kungfu-systems/buildchain/.github/workflows/github-artifact-attestation.yml@<exact-signer-bootstrap-sha>
+    with:
+      buildchain-ref: <exact-signer-bootstrap-sha>
+      evidence-run-id: ${{ github.run_id }}
+      source-sha: ${{ github.sha }}
+      subject-artifact-name: linux-release
+      subject-relative-path: libnode-linux-x64.tar.gz
+      platform-manifest-artifact-name: linux-platform-manifest
+      platform-manifest-relative-path: manifest.json
+      release-passport-artifact-name: release-passport
+      release-passport-relative-path: buildchain.release.json
+      policy-json: ${{ needs.release-passport.outputs.github-attestation-policy-json }}
+      evidence-artifact-name: linux-attestation-evidence
+```
+
+## Verify Online and Offline
+
+The Buildchain verifier reconstructs exact `gh attestation verify` arguments
+from the policy, including repository, signer workflow, signer digest, source
+digest, predicate type, and self-hosted-runner denial. It then verifies the
+local artifact, platform manifest, Release Passport, retained Sigstore bundle,
+custom predicate, and Buildchain evidence root:
+
+The reusable workflow runs that same exact signer/source verification
+immediately after `actions/attest` and before it finalizes or uploads evidence.
+Passing a different `buildchain-ref` than the commit used to invoke the reusable
+workflow therefore fails in the signer job, not only during later consumption.
+The policy additionally retains the distinct Buildchain runtime SHA that
+created the build and release evidence.
+
+```bash
+buildchain verify github-artifact-attestation \
+  libnode-linux-x64.tar.gz \
+  --platform-manifest manifest.json \
+  --release-passport buildchain.release.json \
+  --bundle attestation.sigstore.json \
+  --evidence github-artifact-attestation.evidence.json
+```
+
+Verification fails if a single artifact byte changes, the source commit or
+repository differs, the signer workflow or Buildchain commit differs, the
+Passport was replaced, the platform manifest drifts, the bundle omits the
+expected statement, or GitHub reports a self-hosted signer.
+
+## Qualification Policy
+
+New protocol work qualifies on the Buildchain v3 alpha line first. The v2
+development branch is not a supported landing target. Production
+adoption waits for the exact v3 implementation commit to pass the repository
+suite and a real GitHub OIDC/Sigstore qualification run, including the negative
+cases above. A successful local fixture is necessary but not sufficient.

package/docs/release-governance.md

@@ -1,3 +1,21 @@
+---
+status: draft
+period: ongoing
+theme: buildchain-release-governance
+doc_type: technical-reference
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: A
+review_state: unreviewed
+last_reviewed: 2026-07-27
+ai_provenance:
+  model_family: GPT-5
+  product: Codex
+  generated_at: 2026-07-27
+  invisible_context: not asserted
+---
+
 # Release Governance
 
 Buildchain v2 preserves the release semantics of the older ABV workflow while
@@ -235,6 +253,20 @@ declared install, build, and verify fixture, proving that a single consumer
 surface routes to distinct released runtimes without duplicating lifecycle
 configuration in the consumer.
 
+Buildchain's generic artifact-signing contract seals source-, tree-, runtime-,
+platform-, and digest-bound requests from ordinary credential-free build jobs.
+Provider-specific authority jobs consume only those sealed payloads. Apple
+Developer ID, Windows Authenticode, and detached cryptographic signatures share
+the request/receipt model, while each profile retains its honest platform
+semantics and fail-closed verification requirements.
+
+The central `buildchain-artifact-signing` environment reuses the established
+macOS Credential Island names (`BUILDCHAIN_MACOS_CERTIFICATE_*`,
+`BUILDCHAIN_MACOS_NOTARY_API_*`, and
+`BUILDCHAIN_MACOS_EXPECTED_TEAM_ID`). Those authority-only values are never
+declared by or forwarded through a consumer repository. Windows and detached
+providers follow the same central-environment boundary.
+
 The reusable build trust gate reads `job.workflow_ref`, which identifies the
 called workflow and its selected ref. It does not infer the runtime from
 `github.workflow_ref`, because GitHub defines that context as the caller

package/docs/release-passport.md

@@ -8,6 +8,14 @@ promotion PRs, exact tags, GitHub Releases, npm Trusted Publishing, and
 machine-readable evidence. A project can keep its existing build system and use
 Buildchain to make the release record auditable.
 
+Linux release artifacts can additionally carry a GitHub keyless attestation
+policy in `githubArtifactAttestations[]`. The policy binds the exact subject,
+consumer source, original Linux build evidence, immutable Buildchain signer
+workflow, and minimum permissions before the provider attestation exists. The
+completed provider bundle and attestation identifier remain separate evidence,
+avoiding a Passport hash cycle. See
+[`github-artifact-attestation.md`](github-artifact-attestation.md).
+
 Release-candidate and final passports may also include compact
 `controllerReceipts[]` references. These bind a real reusable-workflow receipt
 to its plan digest, consumer source SHA, and exact Buildchain runtime SHA; they
@@ -91,6 +99,10 @@ Additive passport sections:
   semantic Passport root, exact clean source revision, complete platform
   coverage, verdict, and residual risk. Buildchain owns release admission, not
   the meaning of the product invariants.
+- `githubArtifactAttestations`: expected GitHub keyless attestation identities
+  for Linux release artifacts, including subject, caller source, original build
+  evidence, exact Buildchain signer workflow digest, and least-privilege
+  permissions. Dynamic provider evidence is stored beside the Passport.
 
 Buildchain's own binary lane also publishes observability artifacts generated by
 the Buildchain logging API and CLI:
@@ -144,6 +156,7 @@ buildchain collect github-release \
   --kfd-1-witness-json .buildchain/kfd/kfd-1/contract-world.witness.json \
   --kfd-2-claim-json .buildchain/kfd/kfd-2/release-claims.json \
   --invariant-passport-json product/release/qualification/invariant-passport.json \
+  --github-artifact-attestation-policy-json .buildchain/github-artifact-attestation/policy.json \
   --output-dir .buildchain/release-passport
 ```
 

package/docs/reusable-build-surface.md

@@ -1,3 +1,21 @@
+---
+status: draft
+period: ongoing
+theme: buildchain-reusable-build
+doc_type: technical-reference
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: A
+review_state: unreviewed
+last_reviewed: 2026-07-27
+ai_provenance:
+  model_family: GPT-5
+  product: Codex
+  generated_at: 2026-07-27
+  invisible_context: not asserted
+---
+
 # Reusable Build Surface
 
 Buildchain v2 provides a reusable build workflow for repositories that need
@@ -5,6 +23,12 @@ Buildchain's release semantics but cannot be described as a simple Node package.
 The first target shape is `libnode`: expensive native builds, multiple operating
 systems, self-hosted runner labels, and release artifacts that must be auditable.
 
+For Linux release artifacts, the build workflow can hand the sealed artifact,
+platform manifest, and Release Passport to the separate GitHub-hosted keyless
+attester. The compiler runner remains the recorded build identity; the attester
+only signs and verifies immutable data. See
+[`github-artifact-attestation.md`](github-artifact-attestation.md).
+
 ## Automatic Channel Router
 
 The preferred consumer surface is one reusable workflow call. After v2.12
@@ -29,7 +53,7 @@ jobs:
 
 `buildchain-channel` defaults to `auto`. Selection uses this precedence:
 
-1. an explicit `buildchain-ref` train, SHA, or official channel;
+1. an explicit `buildchain-ref` protected authority, train, SHA, or official channel;
 2. an explicit `buildchain-channel: alpha|stable`;
 3. `publish-channel: alpha|release|major`;
 4. GitHub release prerelease metadata;
@@ -94,9 +118,10 @@ jobs:
 
 | Preset                  | Platforms                                                                |
 | ----------------------- | ------------------------------------------------------------------------ |
-| `github-hosted`         | `ubuntu-24.04`, `macos-latest`, `windows-2022`                           |
-| `kungfu-v4-self-hosted` | Kungfu Linux x64, macOS ARM64, and Windows x64 self-hosted runner labels |
-| `custom`                | Requires `platforms-json`                                                |
+| `github-hosted`         | `ubuntu-24.04`, `macos-latest`, `windows-2022`                                                              |
+| `kungfu-v4-self-hosted` | Kungfu Linux x64, macOS ARM64, and Windows x64 self-hosted runner labels                                    |
+| `kungfu-v4-native`      | Kungfu Linux x64, Linux ARM64, macOS ARM64, and Windows x64; Linux ARM64 uses GitHub-hosted `ubuntu-24.04-arm` |
+| `custom`                | Requires `platforms-json`                                                                                   |
 
 Callers can still provide a custom matrix with `platforms-json`. Each platform
 object has:
@@ -475,8 +500,8 @@ The reusable workflow exposes the resolved contract:
 | `trusted-event`                   | `true` when the event is trusted enough to reach build runners                  |
 | `buildchain-runtime-ref`          | Runtime ref selected after applying the empty-default or override policy        |
 | `buildchain-runtime-sha`          | Immutable Buildchain runtime commit used by all runtime checkouts               |
-| `buildchain-runtime-class`        | `stable`, `alpha`, `train`, `exact-sha`, or `development`                       |
-| `buildchain-runtime-override`     | `true` when a train or exact-SHA `buildchain-ref` override was accepted          |
+| `buildchain-runtime-class`        | `stable`, `alpha`, `authority`, `train`, `exact-sha`, or `development`          |
+| `buildchain-runtime-override`     | `true` when an authority, train, or exact-SHA `buildchain-ref` override was accepted |
 | `buildchain-runtime-trust-decision` | Runtime override trust decision                                               |
 | `buildchain-contract-lock-status` | `unchanged`, `compatible-drift`, `breaking-drift`, `missing-lock`, `non-floating-runtime`, or first-release `runtime-contract-unavailable` |
 | `buildchain-contract-lock-drift`  | `true` when the floating runtime SHA or contract digest changed                 |
@@ -516,65 +541,62 @@ release jobs can detect drifting diagnostics JSON contracts and missing or
 drifting diagnostics sidecar manifests without downloading the per-platform
 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. The built-in mode is suitable
-when the protected environment belongs to the repository that defines the
-reusable workflow:
-
-```yaml
-with:
-  credential-island-macos-app-path: product/dist/desktop/mac-arm64/Kungfu Episodes.app
-  credential-island-environment: alpha-macos-signing
-  credential-island-macos-platform-id: macos-arm64
-```
+## Artifact Signing Authority
 
-For a cross-repository reusable workflow, keep the credentials in the consumer
-repository and select caller-owned mode:
+Artifact signing is a Buildchain capability, not a macOS application workflow.
+Consumers declare desired signature state next to their artifact facts; they do
+not configure certificates, Team IDs, notary credentials, protected
+environments, authority roles, or signing jobs:
 
-```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
+```toml
+[[signing.artifacts]]
+id = "native-engine"
+path = "dist/kungfu-engine"
+profile = "auto"
+kind = "mach-o"
+platforms = ["macos-arm64", "macos-x64"]
 ```
 
-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
-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:
-
-- `BUILDCHAIN_MACOS_EXPECTED_BUNDLE_ID`
-- `BUILDCHAIN_MACOS_EXPECTED_TEAM_ID`
-- `BUILDCHAIN_MACOS_CERTIFICATE_SHA1`
-
-and these secrets:
-
-- `BUILDCHAIN_MACOS_CERTIFICATE_P12_BASE64`
-- `BUILDCHAIN_MACOS_CERTIFICATE_PASSWORD`
-- `BUILDCHAIN_MACOS_NOTARY_API_KEY_P8_BASE64`
-- `BUILDCHAIN_MACOS_NOTARY_API_KEY_ID`
-- `BUILDCHAIN_MACOS_NOTARY_API_ISSUER`
-
-The signed DMG, signed app ZIP, credential evidence, and their source-bound
-platform manifest form one additional release-candidate platform. Reviewers can
-therefore verify the exact caller source and immutable Buildchain runtime that
-entered the credential island before admitting or publishing the signed
-artifacts.
+Every native and container build lane reads this declaration after the build
+lifecycle and before verification. Buildchain binds the exact artifact bytes or directory tree to
+the caller repository, source commit, source tree, immutable runtime, platform,
+and requested signature semantics, then publishes a deterministic
+`<artifact>-signing-request-<platform>-<source-sha>` request. No consumer
+workflow step is required.
+
+`profile = "auto"` resolves signable Apple artifacts such as Mach-O files,
+`.dylib`, `.framework`, `.app`, `.xpc`, `.plugin`, `.pkg`, and `.dmg` to the
+native `apple-developer-id` provider. Windows `pe` and `binary` artifacts
+resolve to timestamped native `windows-authenticode`; Windows PE never falls
+back to a detached signature. Linux and other non-native binary files,
+archives, blobs, and directories resolve to `detached-signature-v1`. Buildchain records that as a
+detached cryptographic signature and never misrepresents it as an operating
+system code signature. Explicit incompatible provider/kind/platform
+combinations fail closed.
+
+The request schema rejects credential and authority-infrastructure fields. The
+Buildchain-owned signing authority is responsible for credential selection,
+native signing, notarization where applicable, immutable result delivery, and a
+receipt bound to the request digest, runtime SHA, output digest, and signature
+evidence. Consumer repositories neither receive nor duplicate credential-island
+material. The reusable workflow dispatches the sealed request to the
+Buildchain repository, waits for its protected authority workflow, verifies the
+immutable result, replaces only the declared artifact with the returned final
+bytes, and then runs the consumer's normal verification. Platform manifests,
+KFD evidence, checksums, and Release Passport inputs therefore observe the
+final signed artifact rather than the pre-signing build output.
+
+The durable v3 authority runtime is
+`authority/v3/v3.0/artifact-signing`. It is channel-neutral: alpha and stable
+release work use the same protected `buildchain-artifact-signing` environment
+and provider identities. The authority ref is protected independently from
+release channels and can advance only through reviewed, checked changes; the
+temporary `train/v3/v3.0/artifact-signing-authority` ref is retained only as a
+bounded migration rollback.
+
+The older `credential-island-macos-*` reusable-workflow inputs remain a
+compatibility surface while existing callers migrate. They are not the target
+consumer contract and must not be used to design new integrations.
 
 ## Artifact Transfer Relay
 

package/docs/runtime-train-validation.md

@@ -64,6 +64,27 @@ item that still needs to be merged; it is only a temporary fast-use,
 diagnostic, and rollback channel for initiating repositories. Retained trains
 are cleaned up by a separate periodic Buildchain cleanup task.
 
+## Formal artifact-signing authority ref
+
+Artifact signing uses a durable, channel-neutral authority ref after its
+runtime has passed downstream validation:
+
+```text
+authority/v3/v3.0/artifact-signing
+```
+
+Unlike a train, this ref is a protected execution boundary. Alpha and stable
+release intent use the same authority ref and the same
+`buildchain-artifact-signing` environment; channel promotion never selects a
+different certificate environment. Updates to the authority ref require a
+reviewed pull request, the normal `check` and `verify` status contexts, and a
+fast-forward-safe protected branch policy. Deletion and non-fast-forward
+updates are forbidden.
+
+The temporary `train/v3/v3.0/artifact-signing-authority` ref remains a bounded
+rollback and diagnostic pointer during migration. It is not the production
+identity and must not regain credential ownership.
+
 ## Consumer workflow requirement
 
 Consumers keep their reusable workflow pinned to the stable shell:

package/docs/versioning.md

@@ -61,6 +61,7 @@ repository changes are patch".
 
 | Date | Action | Line | Faces | Class | Rationale | PR |
 | --- | --- | --- | --- | --- | --- | --- |
+| 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. | |
 | 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 |
 | 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. | |
 | 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. | |