@kungfu-tech/buildchain 3.0.5 → 3.0.6-alpha.0

package/docs/publish-transaction.md

@@ -415,9 +415,10 @@ 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
+bindings; creates the exact tag at the transaction source SHA; moves floating
+refs to 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.
 
@@ -536,8 +537,9 @@ inside the mutation boundary.
 
 If finalization fails after an exact Git tag is created, the next run reads the
 durable `finalizing` state, verifies the exact tag points at the recorded
-release SHA, and retries the remaining floating refs. An exact tag at a
-different SHA is a material conflict and blocks recovery.
+source SHA (while accepting legacy release/material targets for recovery), and
+retries the remaining floating refs. An exact tag at an unrelated SHA is a
+material conflict and blocks recovery.
 
 ## CLI Recovery
 

package/docs/release-flow.md

@@ -96,6 +96,10 @@ published artifacts are already durable.
 The intended governance split is:
 
 - exact tags such as `v3.0.2` and `v3.0.3-alpha.0` are immutable audit refs;
+- for publish transactions, the exact tag points to the transaction
+  `source_sha`, matching package-registry source metadata such as npm
+  `gitHead`; generated version-state commits remain on protected branches and
+  floating channel refs;
 - floating tags such as `v3`, `v3.0`, `v3.0-alpha`, and `v3-alpha` are mutable channel refs
   owned by the Buildchain promotion token;
 - protected branches still require reviewed channel PRs before Buildchain can

package/docs/release-governance.md

@@ -575,6 +575,38 @@ context shape into the other. Consumer repositories can keep their context
 stable while changing the actual verification command declaratively in
 `buildchain.toml`:
 
+Before a release caller is merged, consumers should also verify its exact
+reusable-workflow call contract. The checker reads the caller and an already
+checked-out exact Buildchain commit; it never resolves a floating ref or starts
+a release. It rejects unknown or missing inputs and secrets, literal type
+drift, insufficient permissions, untrusted event classes, and a caller pin that
+does not equal the checked callee commit. Defaults, workflow bytes, and the
+complete interface are bound into `contractRoot`; the receipt additionally
+binds the caller commit/tree and both workflow digests.
+
+```sh
+node .buildchain/workflow-contract-runtime/scripts/workflow-call-contract.mjs check \
+  --caller-root . \
+  --caller-workflow .github/workflows/release-new-version.yml \
+  --caller-repository kungfu-systems/example \
+  --job promote \
+  --callee-root .buildchain/workflow-contract-runtime \
+  --callee-workflow .github/workflows/release-candidate-promote.yml \
+  --callee-repository kungfu-systems/buildchain \
+  --trusted-event workflow_dispatch \
+  --trusted-event pull_request:closed \
+  --expected-contract-root "$(cat .buildchain/release-call-contract-root)" \
+  --output .buildchain/workflow-call-receipts/release-new-version.json
+```
+
+The checkout at `.buildchain/workflow-contract-runtime` must use the same
+40-character SHA written in the caller's `uses:` edge. To accept an intentional
+contract change, first run without `--expected-contract-root`, review the full
+diagnostic and exact coordinates, then replace only the committed root. The
+ordinary PR check runs this command before any candidate or promotion dispatch.
+Local pre-commit rehearsal may add `--allow-dirty`; that result is marked
+`receiptReusable: false` and cannot replace the clean exact-source receipt.
+
 ```toml
 [lifecycle.install]
 command = "cargo fetch --locked"
@@ -831,6 +863,13 @@ must be absent or already point at accepted release material. This preserves an
 immutable tag that represents a completed transaction while allowing a tag
 collision discovered after registry publication to recover without republishing.
 
+For package publish transactions, the immutable public version tag points to
+the transaction `source_sha`, so registry source metadata such as npm `gitHead`
+and the Git tag identify the same source commit. Protected branches and mutable
+channel tags continue to point to the generated `release_sha`. Recovery accepts
+older completed transactions whose exact tags already point to recorded release
+or release-material SHAs, but new tags are source-bound.
+
 Every Buildchain publish model that can run registry side effects must bind the
 publish entrypoint to an immutable `publish-gate/*` source lock. The reusable
 `release-candidate-promote.yml@v3` wrapper creates or updates that gate ref and

package/docs/release-propagation.md

@@ -1,3 +1,21 @@
+---
+status: active
+period: ongoing
+theme: buildchain-release-propagation
+doc_type: technical-reference
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: A
+review_state: unreviewed
+last_reviewed: 2026-08-03
+ai_provenance:
+  model_family: GPT-5
+  product: Codex
+  generated_at: 2026-08-03
+  invisible_context: not asserted
+---
+
 # Release Propagation
 
 Release propagation lets a finalized upstream release open a downstream update
@@ -205,6 +223,53 @@ The receipt keeps four machine states separate:
 
 Package publication or alpha completion never implies either visibility state.
 
+## Unified Site agent entry
+
+An Agent begins every Site upstream update through one policy-reporting entry:
+
+```bash
+buildchain release-propagation entry plan \
+  --source-id <paper|kfd|buildchain|kungfu-core> \
+  --channel <alpha|release> \
+  --json
+```
+
+The entry does not blur content and code release policies:
+
+| Upstream    | Trigger policy            | Entry result                                       |
+| ----------- | ------------------------- | -------------------------------------------------- |
+| Paper       | automatic release handoff | requires or resumes the exact captured Work        |
+| KFD         | automatic release handoff | requires or resumes the exact captured Work        |
+| Buildchain  | explicit Site intent      | resolves an exact published package before capture |
+| Kungfu Core | explicit Site intent      | resolves an exact published package before capture |
+
+Paper and KFD releases keep automatic capture-only handoff. Buildchain and
+Kungfu Core releases remain inert until a downstream Agent receives explicit
+Site-update intent. In all four cases, the entry reports the selected policy,
+exact release coordinate when one has been admitted, Work root and recovery
+cursor when one exists, and one machine-readable next action. A GitHub PR is a
+delivery stage inside that Work; it is not the handoff unit.
+
+For an automatic handoff, bind the exact artifact rather than resolving a
+floating tag again:
+
+```bash
+buildchain release-propagation entry plan \
+  --source-id kfd \
+  --handoff-work work.json \
+  --json
+```
+
+The deterministic recovery table is available without repository mutation:
+
+```bash
+buildchain release-propagation entry fault-matrix --json
+```
+
+It classifies current and duplicate Work as successful no-ops, supersession as
+an explicit decision boundary, stale base/expected-old and operational failures
+as retryable, and package/schema disagreement as a hard safety gate.
+
 ## Agent-native work envelope
 
 Setting `agent-work-mode: capture-only` makes a finalized release emit a
@@ -372,6 +437,34 @@ buildchain release-propagation work repair ... --output successor.json --json
 buildchain release-propagation work complete ... --output successor.json --json
 ```
 
+The `push-branch` stage has an executable, fail-closed entrypoint:
+
+```bash
+buildchain release-propagation work push-plan \
+  --work work.json \
+  --expected-work-root sha256:<64-hex> \
+  --cwd downstream-worktree \
+  --remote origin \
+  --json
+
+buildchain release-propagation work push-branch \
+  --work work.json \
+  --expected-work-root sha256:<64-hex> \
+  --cwd downstream-worktree \
+  --remote origin \
+  --execute \
+  --json
+```
+
+The executor checks the exact GitHub repository, current managed branch,
+captured downstream base, and expected-old Work root. It pushes only the current
+commit with `HEAD:refs/heads/<managed-branch>`, never a bare branch or wildcard,
+never a force option, then reads that exact remote ref back. Its typed branch
+reconciliation evidence records the argv, source SHA, destination ref, prior
+remote SHA, observed remote SHA, and whether a mutation occurred. A wrong
+repository, unrelated branch, stale base, concurrent writer, or non-fast-forward
+target fails closed without mutating another branch.
+
 Known operational races (`stale-branch`, `expected-old-mismatch`,
 `lockfile-drift`, `failed-check`, `interrupted-execution`, and `ci-delay`) return
 a retryable repair action. Semantic ambiguity, missing credentials, policy

package/docs/reusable-build-surface.md

@@ -8,11 +8,11 @@ confidence: high
 sensitivity: public
 evidence_grade: A
 review_state: unreviewed
-last_reviewed: 2026-07-31
+last_reviewed: 2026-08-03
 ai_provenance:
   model_family: GPT-5
   product: Codex
-  generated_at: 2026-07-30
+  generated_at: 2026-08-03
   invisible_context: not asserted
 ---
 
@@ -105,6 +105,8 @@ jobs:
       artifact-paths: |
         dist
         build/stage
+      pre-upload-transport-smoke-scenario-path: .buildchain/auditable-demo.json
+      pre-upload-transport-smoke-artifact-root: .
       expected-artifacts-json: >-
         {"minFiles":2,"requiredPaths":["dist/libnode.tar.gz","dist/checksums.txt"]}
       process-summary-path: .buildchain/diagnostics/process-summary.json
@@ -113,6 +115,15 @@ jobs:
       publish-source-ref: publish-gate/release/v22/v22.22/22.22.3-kf.0
 ```
 
+For a standalone Linux binary demo, the optional pre-upload transport smoke
+uses the same declarative scenario as the later capture workflow. Buildchain
+copies the distribution containing the scenario metadata, strips file execute
+bits to model GitHub Artifact transport, restores only the declared
+digest-bound executable closure, and runs `transportSmoke` before either the
+GitHub Artifact or S3 relay upload step. The smoke must be non-interactive and
+is hard-capped at 60 seconds. Omitting the input preserves the ordinary build
+surface; enabling it requires a scenario with `transportSmoke`.
+
 `runner-preset` is the stable first-class surface for known runner fleets:
 
 | Preset                  | Platforms                                                                                                      |
@@ -439,6 +450,7 @@ jobs:
       checkout-cache-timeout-seconds: 60
       checkout-cache-github-timeout-seconds: 600
       checkout-cache-fetch-attempts: 3
+      checkout-history-mode: shallow
 ```
 
 `checkout-cache-mode` accepts:
@@ -449,6 +461,14 @@ jobs:
 | `auto`    | Try the trusted cache first; on miss, record the miss and fall back according to `checkout-cache-fallback`. |
 | `require` | Require the cache to provide the locked commit and fail before lifecycle work if unavailable.               |
 
+`checkout-history-mode` defaults to `shallow`, preserving the bounded single-
+commit transport used by ordinary builds. Set it to `full` only when a
+consumer gate must inspect source ancestry, for example when an Alpha pull
+request qualifies GitHub's synthetic merge ref while retained evidence is
+bound to an ancestor of the source-lock head. Full mode still verifies the
+resolved immutable `HEAD` and tree; it changes only whether the advertised
+source ref is fetched with depth one or with its reachable history.
+
 The cache can be a local/LAN mirror URL template or a runner-local bare
 reference repository template. Templates support `{owner}`, `{repo}`,
 `{repository}`, `{repositorySlug}`, and `{sha}`. The workflow also reads
@@ -511,7 +531,14 @@ the preparation step. Buildchain probes its version, runs `sccache
 `compiler-cache-preparation.json`. The receipt binds the source commit/tree,
 Buildchain runtime, platform, cache profile, and any declared dependency,
 toolchain, or policy roots. It resets counters only; it does not delete cached
-compiler outputs.
+compiler outputs. The same preparation exports `RUSTC_WRAPPER`,
+`CMAKE_C_COMPILER_LAUNCHER`, and `CMAKE_CXX_COMPILER_LAUNCHER` so Cargo and
+CMake/Ninja compilation actually passes through the audited tool.
+
+After the build lifecycle, Buildchain probes the reset counter set again. When
+`compiler-cache-required` is true, the build fails closed if sccache observed
+zero compiler requests or zero cacheable requests. This prevents an installed
+but unbound sccache binary from being reported as an active compiler cache.
 
 Final diagnostics admit sccache hit/miss outcomes as current-run evidence only
 when that preparation receipt is present and valid. A bare `sccache
@@ -615,7 +642,8 @@ 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
+`<artifact>-signing-request-<platform>-<source-sha>-<run-id>-<run-attempt>`
+request. No consumer
 workflow step is required. The lifecycle runner automatically adds declarations
 selected for the current platform to the `build` manifest scan, including
 subjects outside the caller's ordinary `artifact-paths`; this extends the
@@ -668,14 +696,27 @@ 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. The ordinary platform lane completes the consumer's functional
-verification before delegation. A GitHub-hosted finalization lane then verifies
-the authority result against the sealed request, imports the exact signed bytes,
-and recomputes the final manifest before replacing the deterministic artifact.
-The signing result is never downloaded back to a self-hosted native runner.
+material. Each platform lane seals and uploads the unsigned request plus a
+run-attempt-bound control request, completes functional verification, and exits.
+It does not dispatch or poll the authority. A separate `ubuntu-24.04` controller
+starts only after the build matrices complete, validates the exact source,
+tree, runtime, request-set root, platform, run attempt, and correlation, then
+dispatches and awaits the protected authority workflow. Its retained receipt
+records two independent immutable identities: the consumer Buildchain runtime
+SHA carried by the control request and the exact authority-ref commit resolved
+immediately before dispatch. The former validates the request-producing
+runtime; the latter must equal the authority workflow run's `head_sha` and is
+retained with the exact authority run and result artifact. If the protected ref
+moves between resolution and dispatch, settlement fails closed. Failure, timeout, or
+cancellation produces a non-qualifying receipt and no finalization delegation.
+
+A second GitHub-hosted finalization lane downloads the original control request,
+controller receipt, and delegation, verifies their roots and coordinates agree,
+then verifies the authority result against the sealed request, imports the exact
+signed bytes, and recomputes the final manifest before replacing the
+deterministic artifact. The signing result is never downloaded back to a
+self-hosted native runner, so a macOS caller is released before credential-island
+signing and notarization complete.
 Platform manifests, KFD evidence, checksums, and Release Passport inputs
 therefore observe the final signed artifact rather than the pre-signing build
 output.

package/docs/stable-candidate-patrol.md

@@ -8,7 +8,7 @@ confidence: high
 sensitivity: public
 evidence_grade: A
 review_state: self-reviewed
-last_reviewed: 2026-07-31
+last_reviewed: 2026-08-03
 ai_provenance:
   model_family: GPT-5
   product: Codex
@@ -141,7 +141,10 @@ bot, or human service-account token as `approval-token`. The approval identity
 must differ from the promotion token identity that opens the PR. When no
 `approval-token` is passed, `auto-approve: true` falls back to the caller
 `github.token` and therefore requires GitHub Actions approval permission. The
-generated PR may use auto-merge, but it never bypasses the target branch checks.
+generated PR may use auto-merge, but it never bypasses the target branch
+checks. Callers can select `merge-method: merge`, `squash`, or `rebase`; the
+default is `merge` for compatibility. Unsupported values fail closed before
+GitHub is called.
 
 Before enabling `auto-approve` and `auto-merge`, the caller repository must
 provide one approval path and enable auto-merge:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "3.0.5",
+  "version": "3.0.6-alpha.0",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",

package/packages/core/buildchain-contract.js

@@ -72,6 +72,41 @@ function majorLineFromPackageVersion(version = "") {
   return match ? `v${match[1]}` : "v3";
 }
 
+function declarativeAuditableDemoSurface(root, pkg, majorLine) {
+  return surface(root, {
+    id: "declarative-auditable-demo",
+    kind: "workflow",
+    path: ".github/workflows/.declarative-auditable-demo.yml",
+    publicRef: `${pkg.repository ? "kungfu-systems/buildchain" : "buildchain"}/.github/workflows/.declarative-auditable-demo.yml@${majorLine}`,
+    requiredInputs: ["binary-artifact-name", "binary-artifact-digest", "renderer-image"],
+    requiredOutputs: [
+      "source-sha", "capture-artifact-name", "capture-artifact-digest",
+      "evidence-artifact-name", "evidence-artifact-digest", "publication-pr-url",
+    ],
+    breakingDefaults: {
+      scenarioPathDefault: ".buildchain/auditable-demo.json",
+      renderMediaDefault: false,
+      materializeDefault: false,
+      mediaProfileDefault: "responsive-web-delivery-v1",
+      artifactRetentionDaysDefault: 14,
+      executionBoundary: "exact-binary-network-none-secret-free-60-seconds",
+    },
+    optionalInputs: [
+      "buildchain-repository", "source-ref", "scenario-path", "render-media",
+      "media-profile", "materialize", "materialize-base-ref", "artifact-retention-days",
+    ],
+    guarantees: [
+      "one versioned declaration can contain multiple demos with multiple ordered literal argv steps",
+      "every demo uses the exact same-run standalone binary admitted by producer-owned artifact name and digest",
+      "capture runs without network or inherited secrets and retains independent native 1080p and 720p terminal dimensions",
+      "the generic adapter feeds the required auditable demo Gate and immutable renderer without product-specific glue",
+      "full rendering emits a content-addressed Release Passport and idempotent protected README update pull request",
+      "manual, alpha, and release callers use the same capture, Gate, renderer, passport, and materializer implementation",
+      "identity, compliance, Product System metadata, package metadata, registry history, scans, and generation grant no authority",
+    ],
+  });
+}
+
 export function createBuildchainContractWorld({
   root = process.cwd(),
   packageJson = undefined,
@@ -360,7 +395,7 @@ export function createBuildchainContractWorld({
         "Build Images owns encoding, Buildchain owns qualification and receipts, and site repositories own browser loading and accessibility behavior",
         "media qualification does not claim browser playback, responsive layout, reduced-motion behavior, accessibility, or production deployment",
       ],
-    }),
+    }), declarativeAuditableDemoSurface(root, pkg, majorLine),
     surface(root, {
       id: "promote-buildchain-ref-action",
       kind: "action",

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

@@ -5,6 +5,7 @@ import { createPublicationAuthorityRegistry } from "./publication-authority.js";
 
 const DESCRIPTORS = Object.freeze([
   [".github/workflows/.auditable-demo.yml", "non-publication-oidc"],
+  [".github/workflows/.declarative-auditable-demo.yml", "governance-write"],
   [".github/workflows/.build.yml", "non-publication-oidc"],
   [".github/workflows/.release-candidate-promote.yml", "product-publication", true, ["npm-publish", "github-release", "channel-ref"], "trusted-publishing", "none", "fixed", "caller-bound"],
   [".github/workflows/.publication-authority.yml", "evidence-publication"],
@@ -19,6 +20,7 @@ const DESCRIPTORS = Object.freeze([
   [".github/workflows/binary-distribution.yml", "evidence-publication"],
   [".github/workflows/binary-release-assets.yml", "governance-write"],
   [".github/workflows/artifact-signing-authority.yml", "evidence-publication"],
+  [".github/workflows/auditable-demo.yml", "governance-write"],
   [".github/workflows/build-surface-fixture.yml", "non-publication-oidc"],
   [".github/workflows/build.yml", "non-publication-oidc"],
   [".github/workflows/buildchain-alpha-self-dogfood.yml", "non-publication-oidc"],
@@ -28,6 +30,7 @@ const DESCRIPTORS = Object.freeze([
   [".github/workflows/buildchain-patrol.yml", "governance-write"],
   [".github/workflows/buildchain-ref-promotion.yml", "governance-write"],
   [".github/workflows/buildchain-stable-candidate-patrol.yml", "governance-write"],
+  [".github/workflows/dev-qualification-patrol.yml", "governance-write"],
   [".github/workflows/dev-alpha-candidate-patrol.yml", "governance-write"],
   [".github/workflows/dev-merge-queue-governance.yml", "governance-write"],
   [".github/workflows/dev-pr-auto-merge.yml", "governance-write"],

package/packages/core/public-surface-audit.js

@@ -5,6 +5,7 @@ import {
   commandId,
   enumerateCliCommandsFromBin,
 } from "./public-surface-cli.js";
+import { parseReusableWorkflowInterface } from "./workflow-yaml-contract.js";
 
 export { enumerateCliCommandsFromBin } from "./public-surface-cli.js";
 
@@ -46,38 +47,6 @@ function listDirectories(root, dir) {
     .sort();
 }
 
-function parseYamlWorkflowCall(text) {
-  const lines = text.split(/\r?\n/);
-  const result = { reusable: false, inputs: [], secrets: [], outputs: [] };
-  const workflowCallIndex = lines.findIndex((line) => /^(\s*)workflow_call:\s*$/.test(line));
-  if (workflowCallIndex === -1) return result;
-  result.reusable = true;
-  const workflowCallIndent = lines[workflowCallIndex].match(/^(\s*)/)?.[1].length || 0;
-  let section = "";
-  for (const line of lines.slice(workflowCallIndex + 1)) {
-    const currentIndent = line.match(/^(\s*)/)?.[1].length || 0;
-    if (line.trim() && currentIndent <= workflowCallIndent) break;
-    const sectionMatch = line.match(new RegExp(`^\\s{${workflowCallIndent + 2}}(inputs|secrets|outputs):\\s*$`));
-    if (sectionMatch) {
-      section = sectionMatch[1];
-      continue;
-    }
-    if (line.trim() && currentIndent <= workflowCallIndent + 2) {
-      section = "";
-      continue;
-    }
-    if (!section) continue;
-    const fieldMatch = line.match(new RegExp(`^\\s{${workflowCallIndent + 4}}([A-Za-z0-9_-]+):\\s*$`));
-    if (fieldMatch) result[section].push(fieldMatch[1]);
-  }
-  return {
-    reusable: result.reusable,
-    inputs: uniqueSorted(result.inputs),
-    secrets: uniqueSorted(result.secrets),
-    outputs: uniqueSorted(result.outputs),
-  };
-}
-
 function parseYamlTopLevelInputs(text) {
   const lines = text.split(/\r?\n/);
   const inputs = [];
@@ -104,14 +73,14 @@ function parseYamlTopLevelInputs(text) {
 
 export function enumerateWorkflowInputs({ root = process.cwd() } = {}) {
   return listFiles(root, ".github/workflows", (name) => /\.ya?ml$/.test(name)).map((relPath) => {
-    const contract = parseYamlWorkflowCall(readText(root, relPath));
+    const contract = parseReusableWorkflowInterface(readText(root, relPath));
     return {
       id: relPath.replace(/^\.github\/workflows\//, "").replace(/\.ya?ml$/, ""),
       path: relPath,
       reusable: contract.reusable,
-      inputs: contract.inputs,
+      inputs: contract.inputs.map((entry) => entry.name),
       inputCount: contract.inputs.length,
-      secrets: contract.secrets,
+      secrets: contract.secrets.map((entry) => entry.name),
       secretCount: contract.secrets.length,
       outputs: contract.outputs,
       outputCount: contract.outputs.length,