@kungfu-tech/buildchain 3.0.3-alpha.0 → 3.0.3-alpha.2

package/docs/release-propagation.md

@@ -132,6 +132,13 @@ This lets a site repository render the latest reader page and historical
 version index from release facts while keeping old PDFs, source bundles,
 manifests, and passports immutable.
 
+When the downstream consumer is expected to update an exact npm paper pin, the
+upstream envelope must carry both `package` and `publicationArtifact`. The
+consumer can then prove that package name, version, sha512 integrity,
+publication URLs, and immutable artifact digests all describe the same release.
+`publicationArtifact` without `package` remains valid for evidence-only
+propagation, but it cannot qualify a package-pin fast path.
+
 ## CLI
 
 Generate a propagation plan:
@@ -164,7 +171,34 @@ The written lock has contract
 - release passport URL and SHA-256;
 - optional site bundle manifest SHA-256;
 - downstream repository, channel, base ref, lock path;
-- edge id and channel policy.
+- edge id and channel policy;
+- a deterministic propagation key and branch derived from the exact upstream
+  repository/version/channel plus downstream repository.
+
+Repeated runs for the same release identity reuse that branch and lock. A
+different release version or channel receives a different branch, so concurrent
+releases cannot collapse into one mutable propagation PR.
+
+Create the exact propagation receipt after the lock/PR outcome is known:
+
+```bash
+buildchain release-propagation receipt \
+  --plan .buildchain/release-propagation-plan.json \
+  --lock-result .buildchain/release-propagation-write-lock.json \
+  --pr-outcome .buildchain/release-propagation-pr-outcome.json \
+  --target site-libkungfu-dev \
+  --output .buildchain/release-propagation-receipt.json \
+  --json
+```
+
+The receipt keeps four machine states separate:
+
+- `package-published`: exact npm name/version/integrity exists;
+- `alpha-complete`: the upstream alpha passport/tag is complete;
+- `staging-visible`: the downstream staging surface is actually visible;
+- `production-visible`: the production surface is actually visible.
+
+Package publication or alpha completion never implies either visibility state.
 
 ## Reusable Workflow
 
@@ -181,7 +215,11 @@ jobs:
       upstream-release-json: ${{ needs.release.outputs.upstream-release-json }}
       downstream-target: site-libkungfu-dev
       downstream-repository: kungfu-systems/site-libkungfu-dev
-      downstream-base-ref: main
+      downstream-base-ref: dev/v2/v2.7
+      downstream-update-command: >-
+        node scripts/paper-propagation.cjs consume
+        --lock "$BUILDCHAIN_PROPAGATION_LOCK_PATH"
+        && corepack pnpm install --lockfile-only --ignore-scripts
       downstream-prepare-command: pnpm install --frozen-lockfile --ignore-scripts
       downstream-verify-command: pnpm run check
       dry-run: false
@@ -201,8 +239,14 @@ open PR.
 The workflow checks out the Buildchain runtime selected by
 `buildchain-repository` and `buildchain-ref` into `.buildchain/runtime`, invokes
 that runtime for the propagation plan and lock write, then checks out the
-downstream repository and writes the exact lock. A consumer that must pin the
-exact upstream package or regenerate deterministic files declares
+downstream repository and writes the exact lock. If
+`downstream-update-command` is set, Buildchain runs that consumer-owned command
+after writing the lock and exposes the exact lock path, lock SHA-256,
+propagation key, branch, and upstream release JSON as
+`BUILDCHAIN_PROPAGATION_*` environment variables. The command is part of the
+downstream PR diff; it is not a deployment hook.
+
+A consumer that must perform further deterministic preparation can declare
 `downstream-prepare-command`. The command receives
 `BUILDCHAIN_UPSTREAM_PACKAGE_NAME`, `BUILDCHAIN_UPSTREAM_PACKAGE_VERSION`, and
 `BUILDCHAIN_UPSTREAM_RELEASE_LOCK`. After preparation, Buildchain refreshes an
@@ -210,14 +254,15 @@ existing `<!-- buildchain:badges:start -->` README block by default. Consumers
 can disable that step with `refresh-managed-readme-badges: false`.
 
 `downstream-verify-command` runs against the final tree before any commit or
-push, so consumers can use the same check as their PR workflow. Preparation,
-badge refresh, and verification failures all fail closed. The workflow stages
-the complete deterministic result, signs the propagation commit with DCO, and
-then opens or updates the PR. It does not publish the downstream release
-directly. The downstream repository keeps its normal Buildchain governance: the
-PR updates source-of-truth facts, then downstream alpha or release publication
-runs through its own protected channel. A byte-identical rerun is an explicit
-successful no-op.
+push, so consumers can use the same check as their PR workflow. Update,
+preparation, badge refresh, and verification failures all fail closed. The
+workflow stages the complete deterministic result, signs the propagation
+commit with DCO, and then opens or updates the PR. It does not publish the
+downstream release directly. The downstream repository keeps its normal
+Buildchain governance: the PR updates source-of-truth facts, then downstream
+alpha or release publication runs through its own protected channel. A
+byte-identical rerun is an explicit successful no-op.
+
 For unreleased runtime validation, keep the caller's reusable workflow reference
 on `@v3` and pass a temporary train ref through `buildchain-ref`.
 

package/docs/reusable-build-surface.md

@@ -8,7 +8,7 @@ confidence: high
 sensitivity: public
 evidence_grade: A
 review_state: unreviewed
-last_reviewed: 2026-07-30
+last_reviewed: 2026-07-31
 ai_provenance:
   model_family: GPT-5
   product: Codex
@@ -18,7 +18,7 @@ ai_provenance:
 
 # Reusable Build Surface
 
-Buildchain v2 provides a reusable build workflow for repositories that need
+Buildchain v3 provides a reusable build workflow for repositories that need
 Buildchain's release semantics but cannot be described as a simple Node package.
 The first target shape is `libnode`: expensive native builds, multiple operating
 systems, self-hosted runner labels, and release artifacts that must be auditable.
@@ -31,9 +31,8 @@ only signs and verifies immutable data. See
 
 ## Automatic Channel Router
 
-The preferred consumer surface is one reusable workflow call. After v2.12
-reaches the stable major ref, consumers keep this configuration for both alpha
-development and stable release work:
+The preferred consumer surface is one reusable workflow call. Consumers keep
+this configuration for both alpha development and stable release work:
 
 ```yaml
 jobs:
@@ -79,10 +78,10 @@ with:
   buildchain-channel: stable
 ```
 
-During the v2.12 prerelease evaluation window, canaries use
-`build.yml@v3-alpha`. The same router then selects `v3-alpha` or stable `v2` as
-the runtime. Production consumers should adopt `build.yml@v3` after the router
-has reached stable; this keeps the routing shell itself on a stable ref.
+During v3 prerelease evaluation windows, canaries use `build.yml@v3-alpha`.
+The same router then selects `v3-alpha` or stable `v3` as the runtime.
+Production consumers use `build.yml@v3`; this keeps the routing shell itself on
+a stable ref.
 
 The router is generated from `.build.yml`'s input/output surface. Run
 `node scripts/generate-channel-build-workflow.mjs` after changing the advanced
@@ -123,6 +122,27 @@ jobs:
 | `kungfu-v4-native`      | Kungfu Linux x64, Linux ARM64, macOS ARM64, and Windows x64; Linux ARM64 uses GitHub-hosted `ubuntu-24.04-arm` |
 | `custom`                | Requires `platforms-json`                                                                                      |
 
+Set `self-hosted-offline-fallback: true` to inspect every exact-label
+self-hosted lane from the trusted Buildchain workflow shell before the matrix
+starts. A lane with no matching online runner is replaced independently by its
+supported GitHub-hosted runner: Kungfu Linux x64 uses `ubuntu-24.04`, macOS ARM64
+uses `macos-15`, and Windows x64 uses `windows-2022`. Online-but-busy runners
+remain online and keep their declared self-hosted route. Organization-owned
+repositories inspect organization runner inventory so selected-repository runner
+groups are not mistaken for an empty repository runner inventory. If the
+inventory token, permission, or API is unavailable, Buildchain preserves the
+original matrix instead of guessing that the fleet is offline. The public
+workflow output `runner-routing-json` records only de-identified counts,
+inventory scope, and routing decisions.
+
+```yaml
+with:
+  runner-preset: kungfu-v4-native
+  self-hosted-offline-fallback: true
+secrets:
+  BUILDCHAIN_PROMOTION_TOKEN: ${{ secrets.KUNGFU_GITHUB_TOKEN }}
+```
+
 Callers can still provide a custom matrix with `platforms-json`. Each platform
 object has:
 
@@ -275,16 +295,23 @@ Allowed override refs are deliberately narrow:
 | `<40-character SHA>`                    | Exact immutable Buildchain runtime commit              |
 
 Override requests fail closed unless the event is `workflow_dispatch` and the
-actor has write, maintain, or admin permission on the caller repository.
+actor has write, maintain, or admin permission on the caller repository. One
+non-override exact-pin case is also admitted: when the reusable workflow itself
+is invoked from an exact Buildchain SHA and `buildchain-ref` names that identical
+SHA, the run records `pinned-self`. The input cannot select code other than the
+already-running workflow shell, so protected push and pull-request publication
+jobs can retain one immutable runtime root. Different SHA and train requests
+still fail closed outside trusted manual dispatch.
+
 Pull requests, including same-repository pull requests and fork-originated pull
-requests, cannot use `buildchain-ref` override. This keeps automated PR builds on
-the stable runtime surface.
+requests, cannot select an independent `buildchain-ref` override. This keeps
+automated PR builds on the stable or exact pinned-self runtime surface.
 
 Every run resolves the runtime ref to an immutable SHA before checkout. The job
 summary and aggregate build summary record the workflow shell ref, requested
 runtime ref, resolved runtime ref, runtime SHA, stability class, trust decision,
 and rollback ref. Train refs are development validation refs: they do not move
-`v2`, `vX.Y`, `vX.Y-alpha`, npm dist-tags, or production release refs, and they
+`v3`, `vX.Y`, `vX.Y-alpha`, npm dist-tags, or production release refs, and they
 must not be pinned as long-term production dependencies.
 
 Runtime override validates Buildchain runtime scripts, CLI code, local actions,
@@ -304,13 +331,13 @@ major line, and compatibility policy they reviewed.
 
 The reusable build trust gate checks this lock before any heavy matrix job:
 
-1. resolve the Buildchain runtime ref, for example `v2`, to an immutable SHA;
+1. resolve the Buildchain runtime ref, for example `v3`, to an immutable SHA;
 2. read `dist/site/buildchain-contract.json` from that checked-out Buildchain
    ref;
 3. read the consumer's `.buildchain/contract-lock.json`;
 4. compare the accepted contract with the current contract.
 
-SHA drift alone is not a failure. `v2` is expected to advance. Buildchain only
+SHA drift alone is not a failure. `v3` is expected to advance. Buildchain only
 fails fast when the accepted contract is no longer compatible, for example a
 required input is removed, a required output disappears, a protected behavior
 promise changes, or the major line changes. Additive changes such as optional
@@ -466,6 +493,33 @@ Runtime checkout evidence is uploaded separately as `runtime-checkout.json`,
 including cache transport, fallback attempts, and exact runtime `HEAD`
 verification, even when a later lifecycle step fails.
 
+## Auditable Compiler Cache
+
+Consumers can prepare `sccache` on selected platforms after the install
+lifecycle and before compilation:
+
+```yaml
+with:
+  compiler-cache-provider: sccache
+  compiler-cache-platforms-json: '["windows-x64"]'
+  compiler-cache-required: true
+```
+
+The consumer remains responsible for installing and pinning the tool before
+the preparation step. Buildchain probes its version, runs `sccache
+--zero-stats`, and writes
+`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.
+
+Final diagnostics admit sccache hit/miss outcomes as current-run evidence only
+when that preparation receipt is present and valid. A bare `sccache
+--show-stats` result without the reset receipt remains cumulative and is
+reported as unavailable for the current run. The preparation receipt is copied
+into the small diagnostics artifact and sealed by
+`diagnostics-manifest.json`.
+
 When a Buildchain maintainer asks for downstream validation, the expected
 request is:
 
@@ -562,7 +616,11 @@ lifecycle and before verification. Buildchain binds the exact artifact bytes or
 the caller repository, source commit, source tree, immutable runtime, platform,
 and requested signature semantics, then publishes a deterministic
 `<artifact>-signing-request-<platform>-<source-sha>` request. No consumer
-workflow step is required.
+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
+evidence preimage without silently adding those subjects to the ordinary
+artifact upload.
 
 The request root is a Buildchain-owned generated output. After the declaration,
 lifecycle manifest, and source paths pass validation, sealing replaces that root
@@ -637,6 +695,17 @@ archive container cannot carry a stapled ticket and is not itself a Gatekeeper
 execution target; Gatekeeper evaluates the extracted signed code. Archive path
 and symlink validation fail closed before any payload is signed.
 
+For a declared `app-bundle`, the same protected authority extracts the sealed
+application, derives and verifies its bundle identity, signs nested native code,
+submits both the application and disk image for notarization, staples and
+Gatekeeper-assesses both deliverables, and returns a ZIP, DMG, evidence document,
+and source-bound manifest. The reusable workflow verifies those returned bytes
+on GitHub-hosted infrastructure, adds them to the normal macOS platform payload,
+and publishes a separate `<artifact>-macos-credential-<source-sha>` projection
+for release pipelines that consume the credential-island evidence contract.
+Consumers declare the `.app` under `[[signing.artifacts]]`; they do not configure
+an environment, certificate, notary credential, or authority workflow.
+
 The durable v3 authority runtime is
 `authority/v3/v3.0/artifact-signing`. It is channel-neutral: alpha and stable
 release work use the same protected `buildchain-artifact-signing` environment
@@ -902,15 +971,14 @@ promotion starts:
   `vN`, and `buildchain-stable-contract-lock-path`.
 
 The generated router also owns the stable-shell layout transition through
-`.buildchain/promotion-shell-routing.json`. Stable `v2.14.13` contains the hidden
-advanced workflow, so the stable lane calls that workflow at the exact immutable
-SHA behind the released `v2` state and forwards the complete internal promotion
-identity surface. The logical shell identity remains `vN`, and the router
-retains it in the public audit outputs. The internal advanced-shell call receives
-the exact call ref selected by the routing configuration, so its called-workflow
-ref check and checkout SHA both bind to the same immutable identity. Updating the
-routing pin after a stable release does not require any consumer declaration
-change.
+`.buildchain/promotion-shell-routing.json`. The v3 stable and alpha lanes call
+the hidden advanced workflow at the exact immutable SHA behind their selected
+v3 channel state and forward the complete internal promotion identity surface.
+The logical shell identity remains `vN`, and the router retains it in the public
+audit outputs. The internal advanced-shell call receives the exact call ref
+selected by the routing configuration, so its called-workflow ref check and
+checkout SHA both bind to the same immutable identity. Updating a routing pin
+after a release does not require any consumer declaration change.
 
 The router resolves immutable SHAs and the selected lock digest before candidate
 download. The advanced shell verifies the same router, shell, runtime, lock,
@@ -982,7 +1050,7 @@ main`, marks the rest as `role: platform`, and passes the generated
 side effect. Downloaded platform manifests are still passed into the release
 passport unless `release-passport-platform-manifest-paths` is set explicitly.
 The same Buildchain contract lock check runs before release-candidate
-resolution and before publish. A compatible `v2` drift leaves an issue in the
+resolution and before publish. A compatible `v3` drift leaves an issue in the
 consumer repository but does not trigger a second heavy build; an incompatible
 drift fails before publish side effects.
 
@@ -1147,7 +1215,7 @@ Supported placeholders are `{artifact}`, `{artifactName}`, `{platform}`,
 `{platformId}`, `{platformName}`, `{sha}`, `{shortSha}`, `{ref}`, `{runId}`,
 and `{runAttempt}`. Invalid GitHub artifact name characters are normalized to
 `-`, so `{ref}` remains deterministic even for refs such as
-`refs/heads/dev/v2/v2.0`.
+`refs/heads/dev/v3/v3.0`.
 
 Each platform also writes and uploads:
 

package/docs/runtime-train-validation.md

@@ -1,3 +1,21 @@
+---
+status: active
+period: ongoing
+theme: buildchain-runtime-train-validation
+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
+---
+
 # Runtime Train Validation
 
 Buildchain consumers should keep stable workflow refs such as `@v3` in
@@ -23,7 +41,7 @@ train/v3/v3.0/<capability>
 
 It is a validation pointer, not a release channel:
 
-- it does not move `v2`, `vX.Y`, `vX.Y-alpha`, exact tags, npm dist-tags, or
+- it does not move `v3`, `vX.Y`, `vX.Y-alpha`, exact tags, npm dist-tags, or
   production refs;
 - it must not be pinned as a long-term production dependency;
 - it should point at the Buildchain commit that downstream maintainers are
@@ -140,7 +158,7 @@ summary. The evidence should include:
 
 ## Trust and limitation
 
-Official floating channel refs such as `v2` and `v3-alpha` may be selected on
+Official floating channel refs such as `v3` and `v3-alpha` may be selected on
 pull requests and pushes. Train refs and arbitrary exact-SHA overrides still
 fail closed unless the event is `workflow_dispatch` and the actor has write,
 maintain, or admin permission on the caller repository. Pull requests,

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-11
+last_reviewed: 2026-07-31
 ai_provenance:
   model_family: GPT-5
   product: Codex
@@ -162,15 +162,15 @@ returned a GraphQL error in the response body.
 
 ## Exact-source stable promotion
 
-For a selected `2.12.0-alpha.4`, Patrol creates the immutable source branch:
+For a selected `3.0.2-alpha.4`, Patrol creates the immutable source branch:
 
 ```text
-publish-gate/release/v2/v2.12/2.12.0-alpha.4
+publish-gate/release/v3/v3.0/3.0.2-alpha.4
 ```
 
-and opens it against `release/v2/v2.12`. This is an existing strict Buildchain
-governance path. The PR freezes the qualified candidate even if `v2.12-alpha`
-or `alpha/v2/v2.12` has already moved to alpha.5. Normal Verify,
+and opens it against `release/v3/v3.0`. This is an existing strict Buildchain
+governance path. The PR freezes the qualified candidate even if `v3.0-alpha`
+or `alpha/v3/v3.0` has already moved to alpha.5. Normal Verify,
 release-candidate resolution, source-tree equivalence, publish transaction,
 passport, registry, tag, and floating-ref checks still run.
 

package/docs/toolkit-observability.md

@@ -1,3 +1,21 @@
+---
+status: draft
+period: ongoing
+theme: buildchain-observability
+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
+---
+
 # Toolkit Observability
 
 Buildchain ships a small logging toolkit for repository workflows and project
@@ -232,6 +250,10 @@ are recorded as unavailable instead of failing the diagnostics artifact. Call
 compiler cache data. Native diagnostics also expose `compilerCaches` and
 `nativeCacheDirs` as top-level fields in each diagnostics artifact and aggregate
 summary, so reviewers do not have to dig through nested cache sections first.
+For reusable builds, sccache outcomes enter structured current-run evidence only
+when a sibling `compiler-cache-preparation.json` proves the counters were reset
+after install and before build; cumulative stats without that receipt remain
+explicitly unavailable.
 
 Process samples are intentionally summarized before they become long-lived
 artifacts. The summary records requested parallelism, the source of that value

package/docs/versioning.md

@@ -8,7 +8,7 @@ confidence: high
 sensitivity: public
 evidence_grade: A
 review_state: unreviewed
-last_reviewed: 2026-07-30
+last_reviewed: 2026-07-31
 ai_provenance:
   model_family: GPT-5
   product: Codex
@@ -31,9 +31,9 @@ on.
 | Minor | New compatible welded surface: reusable workflow output, CLI command family, config protocol, published subpath, evidence file, runner contract, or agent-readable artifact. |
 | Major | Breaking semantic change, removed stable surface, changed branch/tag governance, or incompatible protocol rewrite.                                                           |
 
-Kungfu minor lines are long-lived trains. `v2.0`, `v2.1`, and `v2.2` can each
-receive many patch releases. The major ref, such as `v2`, points at the
-selected stable major entrypoint; the minor ref, such as `v2.2`, points at the
+Kungfu minor lines are long-lived trains. `v3.0`, `v3.1`, and `v3.2` can each
+receive many patch releases. The major ref, such as `v3`, points at the
+selected stable major entrypoint; the minor ref, such as `v3.2`, points at the
 latest stable production patch for that minor line.
 
 ## Welded Surfaces
@@ -79,6 +79,8 @@ repository changes are patch".
 
 | Date       | Action       | Line    | Faces                                                                                                                                                                        | Class    | Rationale                                                                                                                                                                                                                                                                                                                              | PR    |
 | ---------- | ------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
+| 2026-07-31 | extend-minor | `v3.0`  | auditable-demo-workflow, auditable-demo-media-profile, auditable-demo-media-receipt                                                                                          | additive | Add an opt-in responsive profile that binds source-resolution and exact 1280x720 MP4/WebM/GIF renditions to one Gate and receipt while rejecting upscales, aspect-ratio drift, and profile changes between Gate-only and full-render paths.                                                                                              |       |
+| 2026-07-31 | extend-minor | `v3.0`  | release-candidate-family-evidence, release-passport-evidence-attachment, promotion-action, release-passport-cli                                                             | additive | Restore all-ref v2 parity for optional Initiative-family candidate binding and typed product-owned release evidence attachments while retaining Kungfu native Family State authority and the newer v3 post-activation released-evidence stage.                                                                                         | #2089 |
 | 2026-07-30 | extend-minor | `v3.0`  | reusable-build-workflow, observed-evidence-bundle, release-passport-json-reader, web-surface-release-governance                                                               | additive | Add bounded artifact compression and remote-read controls plus transactional derived evidence projections while repairing release-PR runtime handoff so production remains protected-main-only.                                                                                                                                       |       |
 | 2026-07-29 | extend-minor | `v3.0`  | artifact-signing-config, apple-developer-id-authority, artifact-signing-evidence                                                                                             | additive | Extend the consumer-neutral signing declaration to macOS compound archives, including nested wheel Mach-O signing, PEP 427 RECORD repair, safe archive reconstruction, and whole-product notarization under the same protected authority.                                                                                              |       |
 | 2026-07-28 | extend-minor | `v3.0`  | auditable-demo-workflow, auditable-demo-media-profile, auditable-demo-media-receipt                                                                                          | additive | Add opt-in archive, web-delivery, and site-hero profiles; independently bind codec, container, audio, layout, byte-budget, role, and fast-start facts into a v2 media receipt while preserving the existing archive default.                                                                                                           |       |

package/docs/web-surface-deployments.md

@@ -459,6 +459,68 @@ the owning and parent surface syncs carried their required delete exclusions.
 The runner must provide an AWS CLI version whose `s3 sync` supports
 `--no-overwrite`.
 
+### Qualified publication package-pin fast path
+
+A consumer may narrow one deployment to the exact paper version introduced by
+a package-pin-only PR. The artifact root `manifest.json` must carry a
+consumer-owned qualification envelope:
+
+```json
+{
+  "publicationFastPath": {
+    "contract": "kungfu-buildchain-publication-package-pin-fast-path",
+    "mode": "package-pin-only",
+    "targetSurface": "papers",
+    "qualificationRoot": "sha256:...",
+    "immutablePrefixes": [
+      "archive/observer-declared-timelines/v0.1.0-alpha.10"
+    ],
+    "mutableFiles": [
+      "archive/index.html",
+      "index.html",
+      "manifest.json",
+      "observer-declared-timelines/index.html",
+      "observer-declared-timelines/latest/index.html",
+      "registry.json"
+    ],
+    "invalidationPaths": [
+      "/",
+      "/archive/",
+      "/archive/observer-declared-timelines/v0.1.0-alpha.10*",
+      "/observer-declared-timelines/",
+      "/observer-declared-timelines/latest/",
+      "/manifest.json",
+      "/registry.json"
+    ]
+  }
+}
+```
+
+Buildchain validates that the target surface exists, every immutable prefix is
+declared by that surface's archive manifest, every mutable file exists outside
+those prefixes, and the qualification root is exact. A qualified plan:
+
+- selects only `targetSurface`;
+- verifies/uploads only the declared immutable prefixes with the normal
+  no-overwrite digest safeguards;
+- copies only the declared mutable files;
+- skips full `sync --delete` and directory-index alias writes;
+- invalidates only the declared viewer paths plus the deployment manifest.
+
+Any missing, malformed, or unqualified envelope keeps the normal full-surface
+plan. The fast path narrows bytes; it does not weaken channel controls.
+`package-published`, `alpha-complete`, `staging-visible`, and
+`production-visible` remain separate facts, and a package qualification never
+authorizes production by itself.
+
+Publication manifests may retain release history without rematerializing every
+historical package into the current site artifact. When at least one version
+declares `immutableIndex`, Buildchain treats that field as the materialization
+envelope: all declared version prefixes remain protected from deletion, while
+only prefixes with `immutableIndex` must exist locally and are eligible for
+upload. Manifests without the envelope retain the legacy rule that every
+declared prefix must exist.
+
 For multi-surface sites, each surface host is treated as a root-relative view
 of that surface's artifact path prefix. For example, a `buildchain` surface with
 `path = "/buildchain/"` and preview URL

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "3.0.3-alpha.0",
+  "version": "3.0.3-alpha.2",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",
@@ -41,6 +41,9 @@
     "./portable-dev-cache": "./packages/core/portable-dev-cache.js",
     "./publication-artifact": "./packages/core/publication-artifact.js",
     "./publication-package": "./packages/core/publication-package.js",
+    "./publication-reproducibility": "./packages/core/publication-reproducibility.js",
+    "./publication-sealed-bundle": "./packages/core/publication-sealed-bundle.js",
+    "./paper": "./packages/core/paper.js",
     "./publication-authority": "./packages/core/publication-authority.js",
     "./publication-control-plane-audit": "./packages/core/publication-control-plane-audit.js",
     "./buildchain-publication-authority": "./packages/core/buildchain-publication-authority.js",
@@ -105,7 +108,8 @@
   },
   "packageManager": "pnpm@11.7.0",
   "scripts": {
-    "check": "node scripts/check-internal-architecture.mjs && node scripts/check-inventory.mjs && pnpm run check:site && pnpm run check:workflows && pnpm run test:unit && node scripts/check-action-bundles.mjs",
+    "check": "pnpm run check:static && node scripts/check-maintainability.mjs && node scripts/check-internal-architecture.mjs && node scripts/check-inventory.mjs && pnpm run check:site && pnpm run check:workflows && pnpm run test:unit && node scripts/check-action-bundles.mjs",
+    "check:static": "node scripts/check-javascript-syntax.mjs && prettier --check architecture/*.json bin/internal/command-registry.mjs scripts/authorize-promotion-runtime-override.cjs scripts/check-javascript-syntax.mjs scripts/check-maintainability.mjs scripts/maintainability-metrics.mjs tests/authorize-promotion-runtime-override.test.mjs tests/command-registry.test.mjs tests/maintainability.test.mjs tests/promotion-responsibilities.test.mjs",
     "check:workflows": "bash scripts/check-workflows.sh",
     "generate:site": "node scripts/generate-site-bundle.mjs",
     "check:site": "node scripts/generate-site-bundle.mjs --check",
@@ -116,11 +120,9 @@
     "pack:check": "npm pack --dry-run --json --registry=https://registry.npmjs.org/"
   },
   "devDependencies": {
-    "@types/node": "^24.0.0",
     "prettier": "^3.9.0",
     "tsup": "^8.5.0",
-    "typescript": "^5.9.0",
-    "vitest": "^4.1.9"
+    "typescript": "^5.9.0"
   },
   "dependencies": {
     "@kungfu-tech/kfd": "1.0.0-alpha.47",