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

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                                                                                                      |
@@ -520,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
@@ -624,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
@@ -677,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-alpha.8",
+  "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-publication-authority.js

@@ -30,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/release-propagation-agent-entry.js

@@ -0,0 +1,185 @@
+import {
+  assertPlainObject,
+  assertString,
+  normalizeChannel,
+  sha256Json,
+} from "./release-propagation-common.js";
+import { verifyReleasePropagationWork } from "./release-propagation-work.js";
+
+export const SITE_UPSTREAM_AGENT_ENTRY_CONTRACT =
+  "kungfu-buildchain-site-upstream-agent-entry";
+export const RELEASE_PROPAGATION_FAILURE_MATRIX_CONTRACT =
+  "kungfu-buildchain-release-propagation-failure-matrix";
+
+const SOURCE_ALIASES = new Map([
+  ["buildchain", "buildchain"],
+  ["core", "kungfu-core"],
+  ["kfd", "kfd"],
+  ["kungfu", "kungfu-core"],
+  ["kungfu-core", "kungfu-core"],
+  ["paper", "paper"],
+  ["papers", "paper"],
+]);
+
+const POLICIES = Object.freeze({
+  buildchain: Object.freeze({
+    mode: "downstream-manual",
+    trigger: "explicit-site-intent",
+    package: "@kungfu-tech/buildchain",
+  }),
+  "kungfu-core": Object.freeze({
+    mode: "downstream-manual",
+    trigger: "explicit-site-intent",
+    package: "@kungfu-tech/site",
+  }),
+  kfd: Object.freeze({
+    mode: "automatic-release-handoff",
+    trigger: "upstream-release-capture",
+    package: "@kungfu-tech/kfd",
+  }),
+  paper: Object.freeze({
+    mode: "automatic-release-handoff",
+    trigger: "upstream-release-capture",
+    packagePrefix: "@kungfu-tech/paper-",
+  }),
+});
+
+const FAILURE_ROWS = Object.freeze([
+  ["current", "no-op", "none", "retain-current-cut"],
+  ["duplicate-work", "no-op", "reuse", "resume-exact-work"],
+  ["superseded-work", "stop", "needs-decision", "follow-declared-successor"],
+  ["stale-downstream-base", "failure", "retry", "refresh-and-recapture"],
+  ["stale-expected-old", "failure", "retry", "refresh-and-recapture"],
+  [
+    "package-schema-mismatch",
+    "failure",
+    "hard-safety-gate",
+    "repair-upstream-release",
+  ],
+  ["pull-request-conflict", "failure", "retry", "refresh-and-recapture"],
+  ["verification-failure", "failure", "retry", "repair-same-work"],
+  ["release-race", "failure", "retry", "read-authoritative-release-and-resume"],
+  ["deployment-failure", "failure", "retry", "repair-same-work"],
+  ["online-readback-failure", "failure", "retry", "repair-same-work"],
+]);
+
+export const RELEASE_PROPAGATION_FAILURE_MATRIX = Object.freeze({
+  schemaVersion: 1,
+  contract: RELEASE_PROPAGATION_FAILURE_MATRIX_CONTRACT,
+  rows: FAILURE_ROWS.map(([condition, outcome, disposition, recovery]) => ({
+    condition,
+    outcome,
+    disposition,
+    recovery,
+  })),
+});
+
+export function normalizeSiteUpstreamIntent(value) {
+  const raw = assertString(value, "site upstream intent").toLowerCase();
+  if (raw.startsWith("@kungfu-tech/paper-")) return "paper";
+  const normalized = SOURCE_ALIASES.get(raw);
+  if (!normalized) {
+    throw new Error(
+      "site upstream intent must identify paper, kfd, buildchain, or kungfu-core",
+    );
+  }
+  return normalized;
+}
+
+function automaticHandoff(sourceId, policy, handoffWork) {
+  if (handoffWork === null || handoffWork === undefined) {
+    return {
+      status: "handoff-required",
+      exactRelease: null,
+      work: null,
+      nextAction: {
+        action: "consume-release-handoff",
+        command:
+          "buildchain release-propagation entry plan --source-id <source> --handoff-work <work.json> --json",
+      },
+    };
+  }
+  const status = verifyReleasePropagationWork(
+    assertPlainObject(handoffWork, "automatic release handoff Work"),
+  );
+  const packageFact = status.work.upstream.release.package;
+  const packageMatches =
+    packageFact?.name === policy.package ||
+    (policy.packagePrefix &&
+      packageFact?.name?.startsWith(policy.packagePrefix));
+  if (!packageMatches) {
+    throw new Error(
+      `automatic ${sourceId} handoff package disagrees with the selected policy`,
+    );
+  }
+  return {
+    status: status.lifecycle === "complete" ? "complete" : "handoff-ready",
+    exactRelease: {
+      repository: status.work.upstream.release.repository,
+      package: packageFact,
+      releaseRoot: status.work.upstream.releaseRoot,
+    },
+    work: {
+      workId: status.workId,
+      workRoot: status.contentRoot,
+      lifecycle: status.lifecycle,
+      currentStage: status.currentStage,
+      expectedBaseSha: status.work.downstream.expectedBaseSha,
+      branch: status.work.downstream.branch,
+    },
+    nextAction: status.nextAction,
+  };
+}
+
+export function planSiteUpstreamAgentEntry({
+  sourceId: sourceInput,
+  channel = "",
+  handoffWork = null,
+} = {}) {
+  const sourceId = normalizeSiteUpstreamIntent(sourceInput);
+  const policy = POLICIES[sourceId];
+  const normalizedChannel = channel
+    ? normalizeChannel(channel, "site upstream channel")
+    : sourceId === "paper" || sourceId === "kfd"
+      ? ""
+      : "release";
+  const route =
+    policy.mode === "automatic-release-handoff"
+      ? automaticHandoff(sourceId, policy, handoffWork)
+      : {
+          status: "manual-resolution-required",
+          exactRelease: null,
+          work: null,
+          nextAction: {
+            action: "resolve-published-release",
+            command: `buildchain release-propagation pickup plan --config <config.json> --source-id ${sourceId} --channel ${normalizedChannel} --current-version <exact-version> --json`,
+          },
+        };
+  const body = {
+    schemaVersion: 1,
+    contract: SITE_UPSTREAM_AGENT_ENTRY_CONTRACT,
+    sourceId,
+    channel: normalizedChannel,
+    policy,
+    automaticTrigger: policy.mode === "automatic-release-handoff",
+    ...route,
+    faultMatrixRoot: sha256Json(RELEASE_PROPAGATION_FAILURE_MATRIX),
+  };
+  return { ...body, entryRoot: sha256Json(body) };
+}
+
+export function classifyReleasePropagationCondition(condition) {
+  const normalized = assertString(condition, "release propagation condition");
+  const row = RELEASE_PROPAGATION_FAILURE_MATRIX.rows.find(
+    (entry) => entry.condition === normalized,
+  );
+  if (!row) {
+    throw new Error(`unsupported release propagation condition: ${normalized}`);
+  }
+  return {
+    schemaVersion: 1,
+    contract: "kungfu-buildchain-release-propagation-condition",
+    ...row,
+    matrixRoot: sha256Json(RELEASE_PROPAGATION_FAILURE_MATRIX),
+  };
+}