@kungfu-tech/buildchain 2.12.2 → 2.12.3-alpha.2

package/dist/site/public-surface-audit.json

@@ -1203,6 +1203,7 @@
           "publish-tooling-sha",
           "publish-transaction",
           "publish-transaction-override",
+          "reconciliation-workspace",
           "release-candidate-build-summary-path",
           "release-candidate-passport-path",
           "release-candidate-version",
@@ -1230,7 +1231,7 @@
           "transaction-state-path",
           "verification-command"
         ],
-        "inputCount": 51
+        "inputCount": 52
       },
       {
         "id": "report-buildchain-issue",
@@ -2723,8 +2724,8 @@
     "workflowRegistryPath": "dist/site/workflow-registry.json",
     "pageRegistryPath": "dist/site/page-registry.json",
     "cliRegistryDigest": "ab57fec294efb9dde1612787bfd0d532b5bb95298b5da14a2b51a5e71b9c7dcc",
-    "workflowRegistryDigest": "ccc8ab882a30d8c180c109aa484c619d34a5e889c571757f11e555f113c4d338",
-    "pageRegistryDigest": "394ef34331be95e72b6c2c875ce138ea0b3344e539793291dc8126d168a2c1f9"
+    "workflowRegistryDigest": "967e63f8539a9d0c35473efba0538990304d00c14d0bbeba58783072855ec540",
+    "pageRegistryDigest": "a14e95f2f81cd81c07541f0d7da75d40fdd62e3ce69e0a861f7558ae23d73af4"
   },
   "comparison": {
     "missingCliRegistry": [],

package/dist/site/publication-registry.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-publication-release-registry",
-  "generatedAt": "2026-07-13T12:43:26.201Z",
-  "publishedAt": "2026-07-13T12:43:26.201Z",
+  "generatedAt": "2026-07-13T13:40:03.654Z",
+  "publishedAt": "2026-07-13T13:40:03.654Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "d61a8cfd6d147aadc73306dbc97bf2ce6b825895",
+  "sourceRevision": "4d203ebe153c8a4481b4b5febb0dd88be935a7b8",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -32,7 +32,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "2.12.2",
+    "version": "2.12.3-alpha.2",
     "versionSource": "package.json#version"
   },
   "sourceKind": "package-site-bundle",

package/dist/site/site-manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-site-manifest",
-  "generatedAt": "2026-07-13T12:43:26.201Z",
-  "publishedAt": "2026-07-13T12:43:26.201Z",
+  "generatedAt": "2026-07-13T13:40:03.654Z",
+  "publishedAt": "2026-07-13T13:40:03.654Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "d61a8cfd6d147aadc73306dbc97bf2ce6b825895",
+  "sourceRevision": "4d203ebe153c8a4481b4b5febb0dd88be935a7b8",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -37,7 +37,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "2.12.2",
+    "version": "2.12.3-alpha.2",
     "versionSource": "package.json#version"
   },
   "entrypoint": "buildchain-site.json",
@@ -69,7 +69,7 @@
       "path": "docs/release-passport.md",
       "plane": "verify",
       "exists": true,
-      "digest": "sha256:f278f148e36f508f7217ad0e41501fa1cf5fe4d0a54d81dfbab867b3d35465c7"
+      "digest": "sha256:b339c4de0a19a58507bb0aa3efb57c63e4bb4e8002891b9fcc1d73223a8e2c7f"
     },
     {
       "id": "release-candidate",
@@ -205,7 +205,7 @@
       "path": "docs/reusable-build-surface.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:fbc74dee3a6f2283ea69a2a9a31945ac82ccaf1d270995539f5d80235ab74614"
+      "digest": "sha256:6916d88ae0f25fa129308354b04d339552b72796d4d7d7938015e0e2f4dcaa6a"
     },
     {
       "id": "publish-transaction",
@@ -213,7 +213,7 @@
       "path": "docs/publish-transaction.md",
       "plane": "verify",
       "exists": true,
-      "digest": "sha256:2523dd9a81e837918afae30c203349a7b29f00fdf953962a6db360fd95e0c6cb"
+      "digest": "sha256:8d5d7075cf8b4280a4c5097726f5c51ae40db83e2652eafefe4fa5e487794f57"
     },
     {
       "id": "release-governance",
@@ -221,7 +221,7 @@
       "path": "docs/release-governance.md",
       "plane": "why",
       "exists": true,
-      "digest": "sha256:3ae2bbc2df394726f350e58be1a71dd0379b99b19cd6ccf15fbe3b843f3890b6"
+      "digest": "sha256:beba38634bfdde032bb2ff85dc98dd8d755f942dabe227bf9b7aba8127ab7ce9"
     },
     {
       "id": "release-flow",

package/dist/site/workflow-registry.json

@@ -942,6 +942,7 @@
         "publish-tooling-sha",
         "publish-transaction",
         "publish-transaction-override",
+        "reconciliation-workspace",
         "release-candidate-build-summary-path",
         "release-candidate-passport-path",
         "release-candidate-version",
@@ -969,7 +970,7 @@
         "transaction-state-path",
         "verification-command"
       ],
-      "inputCount": 51,
+      "inputCount": 52,
       "capabilityGroup": "release-passport-trust",
       "status": "active"
     },

package/docs/publish-transaction.md

@@ -103,6 +103,7 @@ BUILDCHAIN_RELEASE_SHA
 BUILDCHAIN_RELEASE_MATERIAL_SHA
 BUILDCHAIN_PUBLISH_TOOLING_SHA
 BUILDCHAIN_PUBLISH_EVIDENCE
+BUILDCHAIN_REQUIRED_ARTIFACTS
 BUILDCHAIN_PUBLISH_MODE
 BUILDCHAIN_PUBLISH_AUTH
 BUILDCHAIN_NPM_DIST_TAG
@@ -126,6 +127,83 @@ public refs.
 match. `BUILDCHAIN_PUBLISH_TOOLING_SHA` identifies the publishing code. A repair
 run may change tooling, but material drift fails closed.
 
+## Post-Publish Requirements And Artifact Provenance
+
+`publish-required-artifacts-json` is a pre-publish family declaration, not a
+request to guess registry digests. A descriptor must include `kind + name`; it
+may omit `ref` and `digest`. The action resolves a missing `ref` to the exact
+`BUILDCHAIN_VERSION`. Registries whose exact refs add a stable prefix or suffix
+may instead declare a `ref_template` containing exactly one `{version}`, such
+as `v{version}`. The template is expanded only after exact version selection,
+so a resumed alpha transaction receives the newly selected prerelease rather
+than the checked-out version. Declaring both `ref` and `ref_template`, using
+another placeholder, or leaving unmatched braces fails before
+`lifecycle.publish`. The action exports the normalized exact refs as
+`BUILDCHAIN_REQUIRED_ARTIFACTS`, runs `lifecycle.publish`, and then requires the
+final evidence to contain every exact member with a non-empty digest. Existing
+callers may continue supplying exact refs and digests.
+
+OCI publishers can opt into strict per-artifact provenance by adding
+`action: built` or `action: reused`. Those artifacts carry two separate
+coordinates:
+
+- `content`: the version, ref, source SHA, and material SHA that produced the
+  immutable content;
+- `release`: the exact current version/ref, target ref, source SHA, and release
+  material SHA that bind that content into this release.
+
+This distinction permits truthful cross-version reuse without claiming that an
+old OCI config was rebuilt from current material. For an OCI artifact with an
+action, final evidence also requires `platform`, positive `contract_major`, and
+`verification` containing a public manifest result, exact ref and digest,
+platform, contract major, optional parent digest, evidence location, and a
+passed named smoke policy. Buildchain cross-checks those values against the
+artifact and current transaction. Missing family members and ref, digest,
+content, release, or verification conflicts enter `repair_required` before
+public refs move.
+
+Example reused OCI evidence entry (the pre-publish requirement may omit
+`ref`, `digest`, `release`, and the observed verification values):
+
+```json
+{
+  "group": "image",
+  "kind": "oci",
+  "name": "ghcr.io/kungfu-systems/base-linux",
+  "ref": "1.2.0-alpha.3",
+  "digest": "sha256:...",
+  "action": "reused",
+  "platform": "linux/amd64",
+  "contract_major": 1,
+  "content": {
+    "version": "1.1.9",
+    "ref": "1.1.9",
+    "source_sha": "<source-sha>",
+    "material_sha": "<material-sha>"
+  },
+  "release": {
+    "version": "1.2.0-alpha.3",
+    "ref": "1.2.0-alpha.3",
+    "target_ref": "alpha/v1/v1.2",
+    "source_sha": "<current-source-sha>",
+    "material_sha": "<current-material-sha>"
+  },
+  "verification": {
+    "public_manifest": true,
+    "ref": "1.2.0-alpha.3",
+    "digest": "sha256:...",
+    "platform": "linux/amd64",
+    "contract_major": 1,
+    "evidence": "registry-inspect.json",
+    "smoke": {
+      "policy": "manifest-contract",
+      "passed": true,
+      "evidence": "smoke.json"
+    }
+  }
+}
+```
+
 ## Release Modes And Auth
 
 Buildchain distinguishes two npm release modes:
@@ -357,7 +435,10 @@ When no state file exists, creation commands also require:
 workflow rule. The expected integration shape is:
 
 - image build writes OCI digests into publish evidence;
-- required image families are passed through `publish-required-artifacts-json`;
+- required image families are passed through `publish-required-artifacts-json`
+  before their final digests are known;
+- mixed built/reused evidence preserves content provenance separately from the
+  current release binding;
 - reruns check GHCR or the target registry and accept existing images only when
   tag and digest match;
 - preview or alpha image tags remain non-stable until the transaction evidence

package/docs/release-governance.md

@@ -570,6 +570,14 @@ reuses a same-repository `buildchain/version-state/*` PR based on the current
 target channel head and records `finalization-needed=true` in the durable
 transaction output. Strict alpha bookkeeping still fails with a
 token/protection diagnostic instead of creating a post-publish PR.
+
+For a stable release, the wrapper also checks out the exact current development
+channel into `.buildchain/reconciliation/dev`. When the prepared next-alpha
+commit cannot fast-forward dev because reviewed work landed concurrently, the
+promotion action applies the next version to that checkout, regenerates every
+declared derived version-state file, reruns the verification lifecycle, and
+only then creates the two-parent reconciliation commit. A checkout/current-ref
+SHA mismatch blocks reconciliation instead of committing stale projections.
 Buildchain's own promotion workflow reads `BUILDCHAIN_PROMOTION_BYPASS_APPS`,
 `BUILDCHAIN_PROMOTION_BYPASS_USERS`, and
 `BUILDCHAIN_PROMOTION_BYPASS_TEAMS` repository variables so the declared bypass

package/docs/release-passport.md

@@ -58,7 +58,9 @@ Additive passport sections:
   version sources, lifecycle invocations, platforms, outputs, product
   artifacts, and verification results to the release.
 - `artifacts`: release assets and registry artifacts in one list, each pointing
-  back to the evidence file that proves its digest.
+  back to the evidence file that proves its digest. Registry artifacts retain
+  optional built/reused action, content and current-release coordinates,
+  platform/contract/parent metadata, and fail-closed verification evidence.
 
 Buildchain's own binary lane also publishes observability artifacts generated by
 the Buildchain logging API and CLI:

package/docs/reusable-build-surface.md

@@ -784,7 +784,10 @@ workflow's `github.token`; the last fallback can only report issues when it has
 write access to the target Buildchain repository.
 
 `publish-required-artifacts-json` can still be passed explicitly for custom
-publish targets. For the default `publish-artifact-kind: npm` path, consumers do
+publish targets. Custom OCI requirements may omit pre-publish refs and digests;
+the action resolves the exact version ref and validates final digests and any
+built/reused provenance after `lifecycle.publish`. For the default
+`publish-artifact-kind: npm` path, consumers do
 not download artifacts or run repository scripts to build publish evidence. The
 wrapper downloads the PR-stage payload artifacts, finds the downloaded `.tgz`
 packages, reads each tarball's `package/package.json` for the real scoped

package/package.json

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

package/packages/core/buildchain-contract.js

@@ -168,6 +168,23 @@ export function createBuildchainContractWorld({ root = process.cwd(), packageJso
         "github-release-title",
         "github-release-notes",
       ],
+      publishArtifactSchema: {
+        requirementDigest: "optional-before-publish-required-after-publish",
+        exactRefResolution: "missing requirement refs resolve to the promoted exact version",
+        exactRefTemplate: "optional ref_template expands one {version} after exact version selection",
+        provenanceActions: ["built", "reused"],
+        provenanceCoordinates: ["content", "release"],
+        verificationFields: [
+          "public_manifest",
+          "ref",
+          "digest",
+          "platform",
+          "contract_major",
+          "parent_digest",
+          "smoke",
+          "evidence",
+        ],
+      },
       guarantees: [
         "promotion reuses PR-stage release-candidate artifacts",
         "promotion does not run the heavy native build matrix",
@@ -241,6 +258,23 @@ export function createBuildchainContractWorld({ root = process.cwd(), packageJso
         "github-release-title",
         "github-release-notes",
       ],
+      publishArtifactSchema: {
+        requirementDigest: "optional-before-publish-required-after-publish",
+        exactRefResolution: "missing requirement refs resolve to the promoted exact version",
+        exactRefTemplate: "optional ref_template expands one {version} after exact version selection",
+        provenanceActions: ["built", "reused"],
+        provenanceCoordinates: ["content", "release"],
+        verificationFields: [
+          "public_manifest",
+          "ref",
+          "digest",
+          "platform",
+          "contract_major",
+          "parent_digest",
+          "smoke",
+          "evidence",
+        ],
+      },
       guarantees: [
         "protected release refs and durable release-state are finalized by Buildchain",
         "release passport finalization is idempotent after publish side effects",