@kungfu-tech/buildchain 3.0.2 → 3.0.3-alpha.1

package/docs/publication-artifacts.md

@@ -106,6 +106,37 @@ for compatibility, but the passport records it as lower trust because
 Buildchain can record the command boundary without proving the compiler or
 LaTeX distribution digest.
 
+## Reproducibility Gate
+
+Alpha and release admission require
+`.buildchain/publication/reproducibility-receipt.json`. Buildchain creates the
+receipt by cloning the exact checked-out Git commit into two independent local
+repositories, assigning each build a separate home and npm cache, and deriving
+`SOURCE_DATE_EPOCH` from the source commit. A pinned `latex-docker` build runs
+with UTC, `C.UTF-8`, no build-time network, and the exact image digest declared
+in `[publication.toolchain]`.
+
+Each clean build independently creates the PDF set, source bundle, publication
+manifest and passport, append-only registry, synthesized npm package directory,
+and an actual npm tarball. After qualification, Buildchain copies the first
+qualifying tarball into the promoted publication candidate instead of deleting
+it with the temporary clean build. The receipt compares exact bytes and records:
+
+- source repository, commit, tree, and `SOURCE_DATE_EPOCH`;
+- toolchain image, digest, command, and toolchain identity root;
+- every artifact and evidence path with byte size and SHA-256;
+- npm tarball SHA-256, SHA-1 shasum, and `sha512` integrity;
+- per-build output-set roots and the first differing field or artifact.
+
+The gate is fail-closed. A build-only `custom-command` run can diagnose byte
+drift and promote its byte-identical local output with
+`--allow-unpinned-toolchain`, but it is never a qualifying publication receipt.
+Any workflow that prepares a publishable paper package accepts only a
+digest-pinned toolchain and promotes the first clean build into the publication
+candidate only after both builds are byte-identical. The receipt remains
+outside the npm tarball to avoid a circular digest; it binds the tarball bytes
+from the surrounding sealed publication evidence.
+
 `publish.kind = "npm-paper-package"` declares that Buildchain, not the consumer
 repository, owns the standard paper npm package shape and release transaction
 mechanics. `publish.package` is the public npm package that contains the PDF,
@@ -134,14 +165,18 @@ The build-only workflow:
   any paper build runs;
 - resolves the declared publication toolchain from `[publication.toolchain]` or
   workflow inputs;
+- hydrates authenticated registry history before building so both clean
+  candidates include the same append-only history;
 - for `latex-docker`, pulls the pinned build-images LaTeX builder digest and
-  runs the declared command in the container;
+  runs two independent clean builds with the reproducibility policy above;
 - for `custom-command`, runs the declared command and records the lower-trust
-  boundary in the passport;
+  boundary in the passport, but refuses publication qualification;
 - runs the verify command;
 - creates a source bundle from `publication.source_paths`;
 - writes `.buildchain/publication/publication-artifact.json`;
 - writes `.buildchain/publication/publication-artifact-passport.json`;
+- writes a qualifying
+  `.buildchain/publication/reproducibility-receipt.json`;
 - when `[publication.archive]` is configured, writes
   `.buildchain/publication/publication-registry.json` and verifies same-version
   immutability;
@@ -174,36 +209,36 @@ on:
       - alpha/v1/v1.0
       - release/v1/v1.0
   workflow_dispatch:
-    inputs:
-      buildchain-ref:
-        description: "Temporary Buildchain runtime ref"
-        required: false
-        default: ""
 
 jobs:
   paper-release:
-    uses: kungfu-systems/buildchain/.github/workflows/paper-release-sealed.yml@v3
+    uses: kungfu-systems/buildchain/.github/workflows/paper-release-sealed.yml@<exact-buildchain-sha>
     permissions:
       actions: read
       checks: write
-      contents: write
+      contents: read
       id-token: write
       issues: write
     with:
-      buildchain-ref: ${{ inputs.buildchain-ref || '' }}
+      buildchain-ref: <exact-buildchain-sha>
       publisher-workflow-path: .github/workflows/paper-release.yml
       toolchain-type: config
       verify-command: make check
       artifact-paths: _build/paper-name.pdf
       buildchain-contract-lock-path: .buildchain/contract-lock.json
     secrets:
-      BUILDCHAIN_PROMOTION_TOKEN: ${{ secrets.BUILDCHAIN_PROMOTION_TOKEN }}
+      BUILDCHAIN_GENERATED_WRITE_APP_CLIENT_ID: ${{ secrets.BUILDCHAIN_GENERATED_WRITE_APP_CLIENT_ID }}
+      BUILDCHAIN_GENERATED_WRITE_APP_PRIVATE_KEY: ${{ secrets.BUILDCHAIN_GENERATED_WRITE_APP_PRIVATE_KEY }}
+      BUILDCHAIN_GENERATED_WRITE_TOKEN: ${{ secrets.BUILDCHAIN_GENERATED_WRITE_TOKEN }}
 ```
 
-The sealed preset does not use a long-lived token for npm publication. It may
-accept an optional `BUILDCHAIN_PROMOTION_TOKEN` only for machine-generated
-version-state updates on protected channel branches; npm publication remains
-bound to GitHub OIDC trusted publishing. The preset builds and packages the
+The sealed preset does not use a long-lived token for npm publication. It
+prefers a repository-scoped GitHub App installation token for generated
+repository writes and accepts `BUILDCHAIN_GENERATED_WRITE_TOKEN` as an
+equivalent narrow compatibility authority. The deprecated
+`BUILDCHAIN_PROMOTION_TOKEN` name remains accepted for existing consumers, but
+there is no `github.token` fallback for generated writes. npm publication
+remains bound to GitHub OIDC trusted publishing. The preset builds and packages the
 paper in a read-only job, then a credential-free authority job downloads that
 exact candidate, audits the external control plane, and seals a capability over
 the source tree, Buildchain runtime, controller receipt, PDF, and npm package
@@ -214,8 +249,9 @@ workflow named by `publisher-workflow-path`.
 
 The preset:
 
-- resolves the floating Buildchain runtime once and binds the exact SHA into the
-  publication candidate and authority capability;
+- uses the exact Buildchain SHA admitted by the provisioning authority and
+  binds it into the caller bytes, contract lock, publication candidate, and
+  authority capability;
 - builds the PDF through the declared pinned LaTeX Docker toolchain or custom
   command in a read-only job;
 - verifies the paper repository;
@@ -229,7 +265,13 @@ The preset:
   channel commit and requires `promote-buildchain-ref` to verify that lock
   before any publish side effect;
 - verifies the complete candidate again after authority and publishes the
-  package through npm Trusted Publishing without rebuilding it;
+  package through npm Trusted Publishing without rebuilding or repacking it;
+- writes a typed sealed-bundle manifest that binds the candidate root, exact
+  npm tarball, every GitHub Release asset, durable storage path, and resume
+  command;
+- persists the complete binary bundle to the transaction's durable release-state
+  ref before npm receives credentials, allowing an empty runner to restore and
+  verify the same bytes after interruption;
 - writes Buildchain release/passport evidence; and
 - creates or updates the exact-version GitHub Release by default, uploading
   every file declared by `publication.primary_artifact` and
@@ -239,6 +281,17 @@ Consumers can opt out of the GitHub Release with `github-release: false`, but
 the default is on so downstream release propagation can observe
 `release.published` without hand-written `gh release` steps.
 
+The transaction exposes a stable publication progression:
+
+```text
+prepared -> sealed -> package-published -> alpha-complete
+```
+
+Stable publication ends at `release-complete`. If a run stops after npm but
+before GitHub Release completion, the next run starts from
+`package-published`, restores the sealed PDF and companion assets, and finishes
+the release without invoking the paper build or `npm pack` again.
+
 Declared publication artifacts are resolved from the generated publication
 manifest rather than repeated in consumer workflow YAML. Publication fails
 before upload if a declared artifact is missing or if its basename would
@@ -256,12 +309,92 @@ Buildchain rather than forking the mechanics into each paper repository.
 
 ## CLI And Node API
 
+### Unified paper operator surface
+
+The `buildchain paper` command family assembles the existing publication
+primitives into a resumable operator flow:
+
+```text
+scaffold/new or migrate/existing -> preflight -> bootstrap npm -> build -> alpha -> status -> resume
+```
+
+Each command emits a typed JSON envelope with `--json`. Dry-run is the default
+for every external mutation. `scaffold --write` is limited to no-overwrite
+local file creation. `migrate --write` is limited to the Buildchain-owned
+contract lock, version pin, thin workflows, and provisioning authority; paper
+content and publication configuration are preserved. `bootstrap npm --execute`, `alpha --execute`, and
+`resume --execute` cross external authority boundaries and therefore require
+explicit execution.
+
+The evidence model is intentionally non-inferential:
+
+| State                | Required evidence                                        |
+| -------------------- | -------------------------------------------------------- |
+| `scaffolded`         | Complete managed scaffold inventory                      |
+| `governed`           | Compatible Buildchain contract lock                      |
+| `admitted`           | Repository admission receipt                             |
+| `bootstrapped`       | Successful public npm bootstrap receipt or registry fact |
+| `trust-bound`        | Trusted publisher binding receipt                        |
+| `content-ready`      | Declared source paths present                            |
+| `artifact-sealed`    | Verified sealed publication bundle                       |
+| `package-published`  | Exact package version visible in npm                     |
+| `alpha-complete`     | Protected Alpha PR completion evidence                   |
+| `staging-visible`    | Staging route evidence                                   |
+| `production-visible` | Production route evidence                                |
+
+`paper status` reports `satisfied`, `not-reached`, `blocked`, or `unknown` for
+each state. It does not promote a state merely because a prior state is
+complete. This makes a later `paper resume` safe: the command dispatches the
+thin repository release workflow, while the workflow re-verifies durable
+evidence and remains the publication authority.
+
+Operationally, responsibility remains split:
+
+- the paper repository owns content, declared metadata, and its thin
+  build/release workflow;
+- Buildchain owns scaffold shape, evidence contracts, reproducibility, sealed
+  bundle mechanics, npm transaction mechanics, and resumption planning;
+- GitHub branch protection and trusted publishing own authority transitions;
+- the papers site consumes publication evidence and owns reader-facing
+  rendering.
+
+Run a local readiness check without network observations:
+
+```sh
+buildchain paper preflight --offline --json
+buildchain paper status --json
+```
+
+Before real npm bootstrap, first inspect the default dry-run result:
+
+```sh
+buildchain paper bootstrap npm --json
+```
+
+Only after reviewing the package, repository, workflow, and dry-run evidence:
+
+```sh
+buildchain paper bootstrap npm \
+  --execute \
+  --confirm-public-package @kungfu-tech/paper-example \
+  --json
+```
+
 Generate the publication manifest locally or in CI:
 
 ```sh
 buildchain publication-artifact manifest --source-sha "$(git rev-parse HEAD)" --json
 ```
 
+Prove the complete candidate from two clean builds:
+
+```sh
+buildchain publication-artifact reproducibility \
+  --source-sha "$(git rev-parse HEAD)" \
+  --promote \
+  --json
+```
+
 Generate the npm package contents after the manifest exists:
 
 ```sh
@@ -280,6 +413,13 @@ import {
   collectPublicationPackageFacts,
   preparePublicationNpmPackage,
 } from "@kungfu-tech/buildchain/publication-package";
+
+import { verifyPublicationReproducibility } from "@kungfu-tech/buildchain/publication-reproducibility";
+
+import {
+  createPublicationSealedBundle,
+  verifyPublicationSealedBundle,
+} from "@kungfu-tech/buildchain/publication-sealed-bundle";
 ```
 
 `writePublicationArtifact()` is the single implementation used by the CLI and

package/docs/publication-authority.md

@@ -8,7 +8,7 @@ confidence: high
 sensitivity: public
 evidence_grade: B
 review_state: unreviewed
-last_reviewed: 2026-07-15
+last_reviewed: 2026-07-31
 ai_provenance:
   model_family: GPT-5
   product: Codex
@@ -212,7 +212,7 @@ providers select an explicit adapter:
 ```bash
 buildchain audit publication-control-plane \
   --repository kungfu-systems/buildchain \
-  --branch dev/v2/v2.12 \
+  --branch dev/v3/v3.0 \
   --source-sha <exact-merged-branch-sha> \
   --workflow .github/workflows/release-candidate-promote.yml \
   --workflow-ref <exact-buildchain-sha> \
@@ -223,7 +223,7 @@ buildchain audit publication-control-plane \
 # Optional stronger external evidence; generate the JSON outside the workflow.
 buildchain audit publication-control-plane \
   --repository kungfu-systems/buildchain \
-  --branch dev/v2/v2.12 \
+  --branch dev/v3/v3.0 \
   --workflow .github/workflows/release-candidate-promote.yml \
   --publisher-workflow .github/workflows/buildchain-ref-promotion.yml \
   --job promote \
@@ -232,7 +232,7 @@ buildchain audit publication-control-plane \
 
 buildchain audit publication-control-plane \
   --repository kungfu-systems/buildchain \
-  --branch release/v2/v2.12 \
+  --branch release/v3/v3.0 \
   --workflow .github/workflows/.binary-release-assets.yml \
   --job publish \
   --environment buildchain-release-assets \

package/docs/publish-transaction.md

@@ -1,3 +1,21 @@
+---
+status: active
+period: ongoing
+theme: buildchain-publish-transaction
+doc_type: technical-reference
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: A
+review_state: unreviewed
+last_reviewed: 2026-07-31
+ai_provenance:
+  model_family: GPT-5
+  product: Codex
+  generated_at: 2026-07-31
+  invisible_context: not asserted
+---
+
 # Publish Transaction
 
 Buildchain release promotion is not just tag movement. A release can also publish
@@ -7,7 +25,7 @@ than Git refs because most registries are append-only: a failed rerun must know
 which artifacts already exist, which are still missing, and whether any existing
 artifact conflicts with the release material.
 
-Buildchain v2 models that work as a release transaction.
+Buildchain v3 models that work as a release transaction.
 
 ## Why This Exists
 
@@ -47,6 +65,7 @@ The branch contains:
 ```text
 state.json
 evidence.json   # present after publish evidence exists
+sealed-bundle/<candidate-root>/files/**  # present for build-once publication
 ```
 
 The local `.buildchain/release-state/...` and
@@ -62,6 +81,16 @@ for transient service failures such as HTTP 5xx responses, connection resets,
 timeouts, and "other side closed" socket failures. If the durable write still
 cannot be persisted after retries, the action fails closed.
 
+For a sealed publication, `state.json` also carries the typed sealed-bundle
+manifest, its candidate root, publication milestones, stable
+`publication_state`, and an exact resume command. The durable ref stores every
+declared bundle file as binary Git blobs before the publish lifecycle starts.
+A fresh runner restores those blobs into
+`.buildchain/recovered-publication/<version>/`, verifies every size and SHA-256
+against the manifest, and only then supplies the recovered paths to the publish
+lifecycle. A missing or changed tarball, PDF, source bundle, or manifest fails
+before registry publication.
+
 Durable release-state refs reserve their exact version even when the public exact
 tag was never created. If a later machine run sees a failed or repair-required
 state for `vX.Y.Z-alpha.N` and cannot resume it with the same transaction
@@ -103,6 +132,10 @@ BUILDCHAIN_RELEASE_SHA
 BUILDCHAIN_RELEASE_MATERIAL_SHA
 BUILDCHAIN_PUBLISH_TOOLING_SHA
 BUILDCHAIN_PUBLISH_EVIDENCE
+BUILDCHAIN_SEALED_BUNDLE_ROOT
+BUILDCHAIN_SEALED_NPM_TARBALL
+BUILDCHAIN_SEALED_NPM_INTEGRITY
+BUILDCHAIN_SEALED_NPM_SHA256
 BUILDCHAIN_REQUIRED_ARTIFACTS
 BUILDCHAIN_PUBLISH_MODE
 BUILDCHAIN_PUBLISH_AUTH
@@ -121,7 +154,8 @@ command = "node scripts/npm-publish-transaction.mjs"
 That script validates that `package.json` matches `BUILDCHAIN_VERSION`, runs
 `npm publish --access public --tag <BUILDCHAIN_NPM_DIST_TAG>` through npm Trusted
 Publishing, and writes npm artifact evidence before the promotion action moves
-public refs.
+public refs. When the sealed npm variables are present, the script verifies and
+publishes that exact `.tgz` file. It does not run `npm pack` again.
 
 `BUILDCHAIN_RELEASE_MATERIAL_SHA` is the source material whose artifacts must
 match. `BUILDCHAIN_PUBLISH_TOOLING_SHA` identifies the publishing code. A repair
@@ -253,7 +287,7 @@ fields and required artifact identities before final refs move.
   "channel": "release",
   "source_sha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
   "release_sha": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
-  "target_ref": "release/v2/v2.0",
+  "target_ref": "release/v3/v3.0",
   "release_material_sha": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
   "publish_tooling_sha": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
   "artifacts": [
@@ -323,33 +357,42 @@ however they need, as long as they emit the common evidence contract.
 The state machine is:
 
 ```text
-prepared -> publishing -> published -> finalizing -> complete
-                    |            |            |
-                    v            v            v
-              publish_failed  repair_required failed_permanently
-                    |
-                    v
-                abandoned
+prepared -> sealed -> publishing -> published -> finalizing -> complete
+                          |            |            |
+                          v            v            v
+                    publish_failed  repair_required failed_permanently
+                          |
+                          v
+                      abandoned
 ```
 
 Supported states:
 
-| State | Meaning |
-| --- | --- |
-| `prepared` | Transaction identity was created, but publish has not started. |
-| `publishing` | Publish lifecycle is running or may have been interrupted. |
-| `publish_failed` | Publish command failed before valid evidence was produced. |
-| `published` | Evidence is valid; refs have not necessarily finalized. |
-| `finalizing` | Buildchain is moving exact/floating refs or needs a later run to do it. |
-| `complete` | Required evidence is valid and refs have finalized. |
-| `repair_required` | Existing evidence or artifact state conflicts with expected release material. |
-| `abandoned` | A human or controlled process abandoned this transaction, usually because a newer version supersedes it. |
-| `failed_permanently` | Recovery should not continue without explicit override. |
+| State                | Meaning                                                                                                  |
+| -------------------- | -------------------------------------------------------------------------------------------------------- |
+| `prepared`           | Transaction identity was created, but publish has not started.                                           |
+| `sealed`             | Exact candidate bytes and manifest are verified and durable; registry publication has not started.       |
+| `publishing`         | Publish lifecycle is running or may have been interrupted.                                               |
+| `publish_failed`     | Publish command failed before valid evidence was produced.                                               |
+| `published`          | Evidence is valid; refs have not necessarily finalized.                                                  |
+| `finalizing`         | Buildchain is moving exact/floating refs or needs a later run to do it.                                  |
+| `complete`           | Required evidence is valid and refs have finalized.                                                      |
+| `repair_required`    | Existing evidence or artifact state conflicts with expected release material.                            |
+| `abandoned`          | A human or controlled process abandoned this transaction, usually because a newer version supersedes it. |
+| `failed_permanently` | Recovery should not continue without explicit override.                                                  |
 
 `repair_required`, `abandoned`, and `failed_permanently` fail closed unless the
 operator passes an explicit override. That override is for controlled repair
 runs, not normal retry behavior.
 
+`publication_state` is a stable operator-facing projection over the detailed
+transaction state. Its successful progression is
+`prepared -> sealed -> package-published -> alpha-complete` for Alpha or
+`release-complete` for stable release. If npm succeeds but GitHub Release work
+is interrupted, the durable record remains `package-published`; the next run
+reuses the exact npm evidence and sealed release assets instead of rebuilding
+or republishing them.
+
 ## Ref Ordering
 
 When publish transactions are enabled, promotion order is:
@@ -357,11 +400,15 @@ When publish transactions are enabled, promotion order is:
 1. verify target source and governance;
 2. create or reuse the version-state release commit;
 3. acquire or resume the release transaction;
-4. run `lifecycle.publish` or accept already-valid evidence;
-5. validate evidence and required artifacts;
-6. move exact release/prerelease tag;
-7. move floating tags and channel refs;
-8. mark the transaction `complete`.
+4. for build-once publication, verify and persist the complete sealed bundle;
+5. run `lifecycle.publish` from the exact sealed tarball or accept already-valid
+   evidence;
+6. validate evidence and required artifacts;
+7. move exact release/prerelease tag;
+8. move floating tags and channel refs;
+9. mark the transaction `complete`;
+10. create or update the GitHub Release from restored sealed assets and record
+    the `github_release` milestone.
 
 When a protected channel requires a generated version-state pull request, the
 first run can stop at `finalizing` after registry publication. If the reviewed
@@ -497,10 +544,10 @@ different SHA is a material conflict and blocks recovery.
 Local recovery commands operate on the same state/evidence files:
 
 ```bash
-node scripts/release-transaction.mjs inspect --version v2.0.11
-node scripts/release-transaction.mjs recover --version v2.0.11
-node scripts/release-transaction.mjs finalize --version v2.0.11
-node scripts/release-transaction.mjs abort --version v2.0.11 --superseded-by v2.0.12
+node scripts/release-transaction.mjs inspect --version v3.0.2
+node scripts/release-transaction.mjs recover --version v3.0.2
+node scripts/release-transaction.mjs finalize --version v3.0.2
+node scripts/release-transaction.mjs abort --version v3.0.2 --superseded-by v3.0.3
 ```
 
 The CLI is a diagnostic and local repair surface. It reports the durable
@@ -517,7 +564,7 @@ When no state file exists, creation commands also require:
 --repository kungfu-systems/buildchain \
 --source-sha <sha> \
 --release-sha <sha> \
---target-ref release/v2/v2.0 \
+--target-ref release/v3/v3.0 \
 --channel release
 ```
 

package/docs/release-candidate.md

@@ -41,6 +41,21 @@ contains:
 - normalized platform matrix and artifact summaries;
 - the hash of the aggregate `build-summary.json`.
 
+## 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
@@ -52,6 +67,10 @@ Promotion workflows that should not rebuild artifacts can enable:
     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
 ```
 
 With `promote-only-release-candidate: "true"`, promotion fails before
@@ -82,6 +101,11 @@ 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