@kungfu-tech/buildchain 4.1.3 → 4.1.4

package/docs/publication-authority.md

@@ -8,16 +8,23 @@ confidence: high
 sensitivity: public
 evidence_grade: B
 review_state: unreviewed
-last_reviewed: 2026-09-11
+last_reviewed: 2026-09-20
 ai_provenance:
-  model_family: GPT-5
+  model_family: GPT-6
   product: Codex
-  generated_at: 2026-07-15
+  generated_at: 2026-09-20
   limits: Live provider configuration must be re-audited; no credential values are represented.
+  visible_context: Current two-entry consumer contract and retained internal implementation references.
 ---
 
 # Sealed Publication Authority
 
+This is an internal publication-authority reference. The shared pipeline owns
+these admission envelopes, nonces, provider observations and independent verifier
+calls. Consumers do not generate these records or add authority-audit workflows.
+Configured npm Trusted Publishing remains provider setup; it does not introduce
+a recurring npm login or token step into the consumer release flow.
+
 Buildchain publication authority is a closed-world, fail-closed protocol. It does
 not mint registry or cloud credentials. It independently verifies whether an
 already protected publication job is allowed to request a short-lived provider
@@ -217,48 +224,11 @@ buildchain verify publication-admission admission.json \
   --json
 ```
 
-The read-only live collector defaults to npm trusted publishing. Other product
-providers select an explicit adapter:
-
-```bash
-buildchain audit publication-control-plane \
-  --repository kungfu-systems/buildchain \
-  --branch dev/v3/v3.0 \
-  --source-sha <exact-merged-branch-sha> \
-  --workflow .github/workflows/public-release-promote.yml \
-  --workflow-ref <exact-buildchain-sha> \
-  --publisher-workflow .github/workflows/self-release-promote.yml \
-  --job promote \
-  --environment none
-
-# Optional stronger external evidence; generate the JSON outside the workflow.
-buildchain audit publication-control-plane \
-  --repository kungfu-systems/buildchain \
-  --branch dev/v3/v3.0 \
-  --workflow .github/workflows/public-release-promote.yml \
-  --publisher-workflow .github/workflows/self-release-promote.yml \
-  --job promote \
-  --environment none \
-  --npm-trust-json sanitized-npm-trust.json
-
-buildchain audit publication-control-plane \
-  --repository kungfu-systems/buildchain \
-  --branch release/v3/v3.0 \
-  --workflow .github/workflows/.release-binary-assets.yml \
-  --job publish \
-  --environment buildchain-release-assets \
-  --publisher-mode github-token
-
-buildchain audit publication-control-plane \
-  --repository OWNER/CONSUMER \
-  --workflow-repository kungfu-systems/buildchain \
-  --branch main \
-  --workflow .github/workflows/public-release-web.yml \
-  --job production-apply \
-  --environment production \
-  --publisher-mode oidc-role \
-  --provider-audit-json sanitized-oidc-role-audit.json
-```
+The read-only control-plane collector is internal diagnostic tooling. Its workflow,
+publisher, job and provider coordinates must come from the exact admitted runtime
+and configured provider policy. For the current product publisher, inspect
+`.release-pipeline-products.yml`; the generated consumer caller is `buildchain.yml`.
+Do not substitute the retired standalone promotion or web workflow identities.
 
 The authority workflow identifies the reusable implementation that performs the
 publication job. The publisher workflow identifies the caller filename bound by

package/docs/publish-transaction.md

@@ -8,12 +8,13 @@ confidence: high
 sensitivity: public
 evidence_grade: A
 review_state: unreviewed
-last_reviewed: 2026-09-06
+last_reviewed: 2026-09-20
 ai_provenance:
   model_family: GPT-6
   product: Codex
-  generated_at: 2026-09-06
-  invisible_context: not asserted
+  generated_at: 2026-09-20
+  visible_context: Current transaction documentation and the schema-2 normal and attempt recovery contracts.
+  invisible_context_boundary: No provider mutation or new publication is implied by this documentation update.
 ---
 
 # Publish Transaction
@@ -104,14 +105,15 @@ the next version; it never rebinds or overwrites the earlier source lock. The
 same source SHA reuses its own lock so authority planning and mutation stay on
 one exact version.
 
-`public-release-promote.yml` can establish or restore this state from an
-older successful candidate run through the documented fresh-event recovery
-inputs. The recovery receipt and sealed bundle are verified before the action
-reads or creates transaction state. If `resume-transaction-id` is supplied,
-the restored durable/local transaction must already exist with that exact id;
-a missing or different id fails before provider mutation. An absent transaction
-is created only when no expected existing identity was requested. See
-[Release Candidate: Resume from an existing candidate run](release-candidate.md#resume-from-an-existing-candidate-run).
+The public recovery boundary is `public-ops-recover.yml`, reached through the
+generated `buildchain-recover.yml` caller. It accepts an exact attempt and an
+optional transient repaired runtime. The retained attempt identifies the
+original candidate, sealed bundle and transaction; consumers do not supply run,
+root, discussion or transaction selector combinations. Internal recovery still
+verifies the immutable receipt and sealed material before reading or creating
+transaction state. An expected existing transaction must retain its exact
+identity; missing or different state fails before provider mutation. See the
+[Golden Path](getting-started.md) for the consumer recovery contract.
 
 ## V4 sealed npm package sets
 

package/docs/release-candidate.md

@@ -1,364 +1,135 @@
-# Release Candidate Passport
-
-The release-candidate passport is the pre-promotion evidence contract produced
-after a reusable build matrix succeeds and before any publish-gate side effects
-run. It is different from the release passport:
-
-- `release-candidate-passport.json` proves which source SHA, channel, runtime,
-  workflow run, and platform artifacts were verified before promotion.
-- `buildchain.release.json` is generated after publish finalization and remains
-  the durable audit entrypoint for the published release.
-
-Enable it on the reusable build workflow:
-
-```yaml
-jobs:
-  build:
-    uses: kungfu-systems/buildchain/.github/workflows/.build.yml@v3
-    with:
-      artifact-name: libnode
-      release-candidate: true
-      publish-channel: alpha
-      publish-source-ref: publish-gate/alpha/v22/v22.22/22.22.3-kf.3-alpha.7
-```
-
-When the platform matrix and aggregate summaries complete, Buildchain uploads:
+---
+status: draft
+period: ongoing
+theme: internal-release-candidate-evidence
+doc_type: technical-reference
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: B
+review_state: unreviewed
+last_reviewed: 2026-09-20
+ai_provenance:
+  model_family: GPT-6
+  product: Codex
+  generated_at: 2026-09-20
+  visible_context: Current consumer contract, workflow taxonomy, and retained candidate and recovery implementation contracts.
+  invisible_context_boundary: No historical receipt, published payload, or external consumer is rewritten by this documentation change.
+---
 
-```text
-<artifact-name>-release-candidate-<publish-source-sha>
-```
-
-The passport contract is `kungfu-buildchain-release-candidate-passport`. It
-contains:
+# Release Candidate Passport
 
-- repository and pull request context;
-- target channel, target ref, and product version or a non-publish
-  `source-<shortSha>` candidate label;
-- source head SHA, merge ref SHA, and the Git `HEAD^{tree}` SHA for PR merge
-  equivalence after the channel PR lands;
-- Buildchain runtime ref/SHA and workflow shell ref;
-- workflow run id/attempt/url;
-- normalized platform matrix and artifact summaries;
-- the hash of the aggregate `build-summary.json`.
+Release candidates and their Passports are runtime-owned evidence. A consumer
+maintains its schema-2 TOML and the generated normal/recovery workflow pair.
+The normal pipeline binds and qualifies source, builds the declared products,
+and manages publication. No consumer workflow downloads candidate artifacts,
+constructs proofs, chooses a publication transaction, or prepares provider
+requests. Start with the [Golden Path](getting-started.md).
+
+This reference describes the retained candidate evidence mechanisms used by
+internal promotion and historical receipt readers. It does not add another
+consumer API. The internal [promotion request](release-promotion-request.md)
+schemas and component workflows must not be copied into consumer wiring.
+
+## Candidate and publication evidence
+
+`release-candidate-passport.json` records evidence collected before promotion:
+source identity, channel, runtime, workflow execution and verified platform
+artifacts. `buildchain.release.json` is the durable published Release Passport.
+These records have different purposes and retain their established schema and
+hash identities.
+
+The `kungfu-buildchain-release-candidate-passport` contract includes:
+
+- repository and PR context;
+- target channel/ref and version, or a non-publishing source candidate label;
+- source head, merge ref and Git tree identities;
+- Buildchain runtime and workflow entry identities;
+- exact workflow run and attempt;
+- platform matrix, artifact summaries and aggregate build-summary hash.
+
+Internal admission checks the repository, channel, source, platform matrix,
+summary and payload inventory before version, transaction, tag or branch
+mutation. Accepted source equivalence must retain the complete proof; matching
+a Git tree alone does not admit a candidate. Artifact names, source selectors
+and roots are runtime transport fields, not TOML extensions.
+
+The candidate resolver remains bound to the exact source and matching trusted
+PR execution. A partial green status, sibling run, incomplete upload or timeout
+cannot replace successful complete candidate evidence.
 
 ## Initiative-family release evidence
 
-A consumer may pass `release-candidate-family-evidence-json` to the reusable
-build. Buildchain normalizes that value as
-`kungfu-buildchain-initiative-family-release-evidence/v1`, binds it into the
-candidate hash, and carries it unchanged into publication authority. The
-envelope can identify one Initiative family root plus the exact Initiative and
-Assignment responsible for the release; continuation evidence can also bind
-the previous family root.
-
-This is an adapter-edge release contract, not a second Work Control authority.
-The immutable native Family State v1 projection and the additive Family State
-v2 typed envelope remain owned by Kungfu. Buildchain only proves that the
-release candidate consumed the caller-supplied family evidence exactly.
-
-Promotion workflows that should not rebuild artifacts can enable:
-
-```yaml
-- uses: kungfu-systems/buildchain/actions/release/promotion/ref@v3
-  with:
-    token: ${{ secrets.BUILDCHAIN_PROMOTION_TOKEN }}
-    sha: ${{ needs.build.outputs.publish-source-sha }}
-    target-ref: alpha/v22/v22.22
-    promote-only-release-candidate: "true"
-    release-candidate-passport-path: .buildchain/artifacts/release-candidate-passport.json
-    release-candidate-build-summary-path: .buildchain/artifacts/build-summary.json
-    release-candidate-family-evidence-required: "true"
-    release-candidate-family-evidence-root: sha256:<initiative-family-root>
-    release-candidate-family-initiative-id: 2026-07-30-example-initiative
-    release-candidate-family-assignment-id: 2026-07-30-example-release
-```
+The retained adapter can normalize
+`kungfu-buildchain-initiative-family-release-evidence/v1` into the candidate
+hash and publication authority. It can identify the family root, Initiative,
+Assignment and previous family root. Required evidence must match these exact
+identities before mutation.
 
-With `promote-only-release-candidate: "true"`, promotion fails before
-version-state, publish transaction, tag, or branch side effects when the
-passport does not match the repository, channel, source identity, platform
-matrix, or build-summary hash. Source identity accepts the exact PR source SHA,
-the PR merge ref SHA, or an exact Git tree match with the promoted channel HEAD;
-this keeps post-merge channel commits strict without forcing a rebuild. The
-Buildchain-owned promotion workflow resolves the matching same-repository
-merged channel PR and downloads its PR-stage RC passport automatically before
-promotion starts. The consumer wrapper defaults to a PR-stage workflow file
-named `build.yml` with display name `Build`, and filters the RC passport and
-build summary by the configured `artifact-name` before promotion. It also
-downloads payload artifacts from the same PR-stage run, validates the required
-payload count, passes downloaded platform manifests into the release passport,
-and either forwards an explicit `publish-required-artifacts-json` value or
-generates one before calling `promote-buildchain-ref`. Before that call, the
-wrapper creates or updates `publish-gate/{alpha,release,major}` to the
-promotion channel commit and passes that ref, target SHA, and `locked=true` to
-the promote action with `require-publish-source-lock: "true"`. Consumers using
-floating `@v3` therefore get publish-side source-lock drift protection without
-copying resolver or promote YAML. The default npm path
-generates that requirement list from the downloaded `.tgz` payloads themselves:
-Buildchain reads `package/package.json` inside each tarball for the real scoped
-package name and version, computes npm-style `sha512-...` integrity over the
-tarball bytes, marks `publish-package-main` as `role: main`, and marks every
-other package as `role: platform`. Consumer workflows therefore stay
-declarative and do not need their own artifact download or publish-evidence
-generation scripts.
-
-When `release-candidate-family-evidence-required` is true, the promotion
-boundary additionally requires the exact family root and may require the
-Initiative and Assignment ids. Missing, mismatched, or source-drifted family
-evidence fails before version-state, release-state, tag, or branch mutation.
-
-Because a channel merge can trigger promotion before its PR-stage matrix has
-finished uploading evidence, the resolver waits up to ten minutes for the exact
-merged PR's successful workflow run and paired artifacts. Polling remains bound
-to the PR/head identity; timeout or a sibling run still fails closed.
-
-The public promotion entry selects one execution runtime through the shared
-[Runtime entry contract](runtime-entry.md). Entry and execution commits may differ.
-Every later job prepares that selection without resolving another Buildchain ref
-or checking entry/runtime SHA equality.
+Kungfu owns native Family State and Work Control. Buildchain proves only that
+its candidate consumed the bound evidence exactly. Consumers do not add a
+family-evidence JSON transport to the shared workflow callers.
 
 ## Resume from an existing candidate run
 
-Do not rely on `gh run rerun` after a reusable-workflow startup or router
-failure. GitHub documents two different rerun behaviors: a full rerun may use a
-called workflow from the currently specified ref, while a failed-job rerun uses
-the same called-workflow commit as the original attempt. Neither operation is a
-supported way to create a job graph that GitHub failed to resolve at startup.
-See GitHub's [reusable workflow rerun behavior](https://docs.github.com/en/actions/reference/workflows-and-actions/reusing-workflow-configurations#behavior-of-reusable-workflows-when-re-running-jobs)
-and [workflow rerun identity rules](https://docs.github.com/en/actions/how-tos/manage-workflow-runs/re-run-workflows-and-jobs).
-
-The supported recovery boundary is a new `workflow_dispatch` (or another new
-caller event) that invokes `public-release-promote.yml` and supplies the old
-candidate run explicitly:
-
-```yaml
-name: Resume release candidate
-on:
-  workflow_dispatch:
-    inputs:
-      candidate-run-id: { required: true, type: string }
-      target-sha: { required: true, type: string }
-      expected-tree: { required: true, type: string }
-      runtime-ref: { required: true, type: string }
-jobs:
-  resume:
-    uses: kungfu-systems/buildchain/.github/workflows/public-release-promote.yml@v4
-    permissions:
-      actions: write
-      checks: write
-      contents: write
-      id-token: write
-      pull-requests: write
-    secrets: inherit
-    with:
-      runtime-ref: ${{ inputs.runtime-ref }}
-      request-json: >-
-        {"schema":"buildchain.promotion-request/v1",
-        "channel":"alpha", "target-ref":"alpha/v4/v4.1",
-        "target-sha":${{ toJSON(inputs.target-sha) }},
-        "artifact-name":"product", "artifact-patterns":"product-package-*",
-        "release-candidate-workflow-file":"build.yml",
-        "release-candidate-workflow-name":"Build",
-        "resume-candidate-repository":${{ toJSON(github.repository) }},
-        "resume-candidate-run-id":${{ toJSON(inputs.candidate-run-id) }},
-        "resume-expected-workflow-file":"build.yml",
-        "resume-expected-workflow-name":"Build",
-        "resume-expected-source-tree":${{ toJSON(inputs.expected-tree) }},
-        "publish-transaction-override":true}
-```
-
-`resume-expected-candidate-root` may replace `resume-expected-source-tree`, or
-callers may provide both. `resume-transaction-id` is optional; when supplied it
-must identify an already durable transaction before any provider mutation.
-
-Recovery downloads and checks the successful `pull_request` run, active
-workflow file and name, same-repository merged PR, trusted repository
-association, target ancestry, promotion tree, Passport candidate root,
-build-summary root, controller receipts, platform matrix, artifact archive
-size/digest, every manifest file, and every product payload byte. Tree equality
-alone is never admission. A different promotion commit is allowed only when all
-of those identities still agree.
-
-The recovery path conditionally skips consumer dependency installation and all
-product `install`, `build`, `verify`, and platform-matrix jobs. It restores the
-downloaded bytes as a content-addressed sealed bundle, so npm publication uses
-the original `.tgz`. The explicit recovery entry binds the bundle identity to
-the original candidate runtime recorded in the Passport; a newer recovery
-tooling SHA is recorded only in the recovery evidence and cannot perturb the
-durable payload root. A transaction-only re-resolution remains a narrower
-finalization path and is not a substitute for the candidate-run entry when the
-original complete artifact inventory must be reconstructed. Recovery may
-regenerate only Buildchain-owned receipts,
-attestations, signatures, Release Passport data, publication, and readback.
-
-Success emits `kungfu-buildchain-release-candidate-recovery/v1` with
-`action: reused`, the original run/source/tree, candidate and artifact roots,
-the skipped stages, current tooling SHA, transaction identity/state, and an
-exact receipt root. The receipt is uploaded as an Actions artifact and staged
-with immutable GitHub Release Passport assets.
-
-The original candidate Passport is never rewritten when a reusable fixture or
-consumer build records a product version different from the sealed publication
-package. In that case the promote action validates the Passport without
-discarding its original target, then requires the immutable recovery receipt to
-bind the original candidate root and source/tree to the exact version read from
-the sealed payload. Without that receipt, the existing direct Passport version
-check remains mandatory; receipt, candidate-root, target, or version drift fails
-before publication side effects.
-
-Missing or expired artifacts, archive or payload digest drift, tree/root,
-repository/workflow/channel/target mismatch, untrusted run/PR provenance,
-incomplete controller evidence, and transaction conflict fail closed with an
-error code and next action. Buildchain never converts recovery failure into a
-hidden full rebuild. A repository owner must choose a new candidate build
-explicitly.
-
-When a durable transaction is absent, recovery seals one from the verified
-candidate. Existing `sealed`, `publishing`, `package-published`, `finalizing`,
-and `complete` transactions use the normal idempotent state machine. Matching
-registry and GitHub bytes are preserved, only missing publication work is
-performed, and conflicting public digests enter `repair_required`.
-
-When the immutable recovery receipt proves that the transaction was already
-`complete` before the recovery run began, Buildchain verifies the existing
-public Release Passport bundle in place and reports the GitHub Release action
-as `reused`. Buildchain-owned evidence regenerated by newer recovery tooling is
-kept in the new recovery artifact; it does not replace same-name evidence that
-was sealed by the original completed publication. Every declared product
-payload is still compared byte-for-byte, a missing payload is uploaded from the
-restored sealed bundle, and a conflicting payload digest fails closed. Ordinary
-duplicate publication without a complete recovery receipt retains the stricter
-same-name/same-digest rule for all assets.
-
-If that explicit complete recovery finds that the public Release Passport is
-absent, it may restore the complete locally verified evidence closure. Before
-the first upload, Buildchain rejects undeclared remote assets and compares every
-same-name remote asset byte-for-byte; any unknown name or digest conflict fails
-closed without mutation. Ordinary duplicate publication cannot enter this
-repair path.
-
-After a transaction finalizes, the target branch can legitimately advance from
-the original promotion SHA. Repeating explicit recovery accepts that movement
-only when the caller supplies the exact durable transaction identity, the
-transaction remains resumable, and GitHub proves the observed target head is a
-descendant of the original transaction source. The recovery receipt records
-both the immutable transaction SHA and the observed ref SHA. Missing identity,
-unrelated advancement, or a repair state fails closed.
-
-By default, the wrapper forwards GitHub Release publication to the underlying
-`promote-buildchain-ref` semver model. Once the release transaction is complete,
-the action creates or updates the public GitHub Release, applies
-prerelease/latest metadata from the authoritative publication channel (falling
-back to semver tag syntax only for ordinary callers without that intent), and
-uploads the publish evidence file together with the generated release passport
-assets. This keeps
-npm/registry publication, Buildchain release passport persistence, and
-`release.published` propagation in one declarative reusable workflow. Consumers
-that do not publish GitHub Releases can opt out with `github-release: false`.
-For anchored/manual package releases, the public GitHub Release tag defaults to
-`v<publishedVersion>` while the internal transaction exact tag remains recorded
-in the release passport.
-
-Standalone binary publication is a separate consumer capability. The promotion
-wrapper does not assume that an npm-only repository provides
-`.github/workflows/self-build-binary-distribution.yml`. Repositories that own that workflow
-opt in with `standalone-binary-distribution: true`; Buildchain's self-promotion
-does so explicitly. Once enabled, a missing or invalid binary workflow remains a
-hard failure rather than being silently skipped.
-
-Products that publish KFD release trust evidence can keep that path declarative
-too. Pass KFD-1 self contract witnesses, KFD-2 public claim files, and KFD-3
-pre-build/artifact evidence into the wrapper:
-
-```yaml
-jobs:
-  promote:
-    uses: kungfu-systems/buildchain/.github/workflows/public-release-promote.yml@v3
-    with:
-      buildchain-channel: auto
-      buildchain-alpha-contract-lock-path: .buildchain/alpha-contract-lock.json
-      buildchain-stable-contract-lock-path: .buildchain/contract-lock.json
-      channel: alpha
-      artifact-name: libnode
-      release-passport-kfd-1-witness-jsons: .buildchain/kfd/kfd-1/standard-contract.witness.json
-      release-passport-kfd-2-claim-jsons: .buildchain/kfd/kfd-2/release-claims.json
-      release-passport-kfd-3-prebuild-witness-jsons: .buildchain/kfd/kfd-3/collaboration-interface.prebuild.json
-      release-passport-kfd-3-artifact-verify-command: kungfu agent verify --json
-```
-
-Buildchain forwards those declarations into `promote-buildchain-ref`, verifies
-KFD-1 source/artifact contract surfaces, audits KFD-2 public release claims, and
-compares KFD-3 declared shipped public surfaces with artifact-exposed public
-surfaces. The release passport records the results under `kfd-1`, `kfd-2`, and
-the KFD-provided `kfd-3` section.
-
-Managed consumers may also ask the promotion wrapper to assemble sealed
-publication evidence from the exact release candidate instead of producing
-short-lived admission JSON in repository-specific workflow code:
-
-```yaml
-      publication-auto-admission: true
-      publication-auto-no-gate: true
-      publication-publisher-workflow-path: .github/workflows/self-release-promote.yml
-      publication-product: Example Product
-      publication-target: npm:@example/product
-      publication-package-name: "@example/product"
-```
-
-`publication-auto-no-gate` is an explicit consumer decision, not a default. A
-consumer with a Shifu Gate registry either supplies
-`publication-gate-aggregate-json`, or supplies a source-controlled
-`publication-gate-command` that writes the aggregate to
-`BUILDCHAIN_PUBLICATION_GATE_RESULT_PATH`. The command runs from the exact
-consumer source in the credential-free sealed-authority job, after Buildchain
-has downloaded the exact RC passport, summary, controller receipt, manifests,
-and payload bytes. It can read those inputs through
-`BUILDCHAIN_PUBLICATION_EVIDENCE_ROOT`; it receives no publication token, OIDC
-permission, or provider write permission. Buildchain validates the aggregate
-digest and exact source binding before it seals a capability. Exactly one of
-the supplied aggregate, consumer command, or explicit no-Gate decision is
-allowed. Buildchain still requires caller-owned RC evidence, an exact source SHA and prepared execution runtime, a repository-local publisher workflow, matching npm
-target/package identity or exact caller-bound GitHub Release target, and a
-qualifying control-plane audit.
-
-Promotion resolves the complete PR-stage workflow, not only the first required
-status job that becomes green. `release-candidate-wait-seconds` bounds that
-wait and defaults to three hours so long native builds can finish controller,
-publication-tail, and retained-evidence jobs without racing a merged promotion.
-An incomplete or failed workflow still fails closed; the longer bound does not
-turn a partial required-check result into candidate evidence.
-
-GitHub-Release-only consumers use the same managed admission without inventing
-an npm package identity:
-
-```yaml
-      publication-auto-admission: true
-      publication-auto-no-gate: true
-      publication-publisher-workflow-path: .github/workflows/self-release-promote.yml
-      publication-product: Example Binary
-      publication-target: github-release:example/example-binary
-      publication-package-name: ""
-```
-
-The target must exactly match the caller repository. Buildchain audits the
-job-scoped GitHub token, exact release-candidate payloads and manifests,
-protected channel lineage, and public release transaction before allowing the
-GitHub Release mutation.
-
-A consumer that owns additional product qualification semantics can opt in to
-the sealed handoff without teaching Buildchain those semantics:
-
-```yaml
-      publication-consumer-predicate-id: kungfu.release-admission/v1
-      publication-consumer-qualification-command: node scripts/qualify-release.mjs
-```
-
-The command reads `BUILDCHAIN_PUBLICATION_CAPABILITY_PATH` and
-`BUILDCHAIN_PUBLICATION_GATE_AGGREGATE_PATH`, evaluates the complete aggregate,
-and writes a decision JSON document to
-`BUILDCHAIN_PUBLICATION_QUALIFICATION_RESULT_PATH`. It also receives
-`BUILDCHAIN_PUBLICATION_PREDICATE_ID` and
-`BUILDCHAIN_PUBLICATION_PREDICATE_DIGEST`. The separate qualification job has
-no write or OIDC permission and does not inherit publication secrets. A
-successful deterministic receipt is rechecked by the provider action
-immediately before mutation. Omitting both inputs preserves the existing
-consumer contract; supplying only one fails closed.
+For current consumers, dispatch the generated `buildchain-recover.yml` with
+an exact `attempt`. An optional `runtime-ref` can identify repaired tooling.
+`public-ops-recover.yml` resolves the retained attempt and determines what can
+be resumed. Consumers do not supply candidate run IDs, replacement source,
+expected trees, roots, discussion IDs, transaction overrides or an extra
+recovery workflow.
+
+Internal recovery retains the original source and material identities. The
+retained candidate recovery mechanism validates trusted repository/PR/run
+provenance, workflow identity, target ancestry, candidate and summary roots,
+controller receipts, platform inventory, archive sizes/digests, manifests and
+product payload bytes. Its existing receipt schema remains
+`kungfu-buildchain-release-candidate-recovery/v1`.
+
+Reusing a qualified sealed candidate preserves its product bytes, including the
+original npm tarball. A newer repair runtime is recorded as tooling; it cannot
+change the original payload root or substitute new product source. Recovery
+skips only stages justified by the retained attempt and evidence. It never
+turns missing or conflicting material into a hidden fresh build.
+
+An expected durable transaction must already exist with the same identity.
+When internal admission permits creating missing transaction state, the state
+is sealed from the verified original material. Existing phases use the normal
+idempotent state machine. Missing publication work may continue; conflicting
+public digests remain a repair failure.
+
+## Completed publication and immutable history
+
+Completed-publication recovery first verifies the retained transaction and
+provider state. Same-name published evidence and payloads retain their original
+bytes. Fresh recovery evidence belongs to the new recovery observation; it does
+not silently replace the completed publication's evidence.
+
+The retained recovery implementation may restore missing product bytes from
+the verified sealed bundle. Restoring an absent Release Passport requires its
+complete locally verified evidence closure, a check for undeclared remote
+assets, and byte comparison of existing same-name assets before mutation.
+Conflicting names or digests fail closed.
+
+A protected target may advance after publication. Recovery must still bind the
+original transaction and prove permitted ancestry from that immutable source;
+it records both the transaction source and observed target. It cannot retarget
+an old transaction to a newer candidate.
+
+A new release uses a new legal candidate/version. Abandoning a failed alpha
+leaves its historical attempts, source locks, receipts, tags and any published
+bytes intact. See [Publish Transaction](publish-transaction.md).
+
+## Product differences
+
+npm packages, binary assets and Paper PDFs use the same generated callers.
+Their install/build/verify commands, platform declarations, artifact paths and
+publication targets belong in TOML. There is no separate consumer binary
+workflow, Paper publication wrapper, credential-bearing publish command,
+custom qualification handoff, or public request-JSON wrapper.
+
+Runtime components retain separate credential and permission boundaries for
+source qualification, sealed evidence, provider publication and readback. The
+smaller consumer API does not collapse those internal boundaries. Legacy
+receipt fields remain readable where required; they do not become accepted
+fields in the closed schema-2 consumer plan.