@kungfu-tech/buildchain 4.0.2-alpha.50 → 4.0.2-alpha.52

package/architecture/agent-change-map.md

@@ -153,6 +153,7 @@ Safe change route: Reduce one owned responsibility behind the stable facade, run
 
 ### Current top twenty maintenance hotspots
 
+- `tests/v4-product-publication-topology.test.mjs`
 - `.github/workflows/.build.yml`
 - `.github/workflows/.publication-authority.yml`
 - `.github/workflows/bootstrap.yml`

package/architecture/maintainability-debt.json

@@ -3124,6 +3124,7 @@
     }
   },
   "hotspots": [
+    "tests/v4-product-publication-topology.test.mjs",
     ".github/workflows/.build.yml",
     ".github/workflows/.publication-authority.yml",
     ".github/workflows/bootstrap.yml",

package/architecture/maintainability-policy.json

@@ -27,11 +27,11 @@
   "repositoryBudgets": {
     "baselineRevision": "9569f69c2cb609372b8a3d65ce5dec8fb7b34a84",
     "maxHandMaintainedSourceFiles": 493,
-    "maxHandMaintainedSourceLines": 174638,
+    "maxHandMaintainedSourceLines": 174652,
     "maxWorkflowFiles": 80,
     "maxWorkflowLines": 26791,
-    "latestTransition": "Verify bounded OCI embedded descriptor content without rewriting manifests.",
-    "latestTransitionRationale": "Charge six measured net production source lines for canonical embedded-content equality against the existing size- and digest-verified local blob, capped at 1 MiB. Reuse existing descriptor traversal and publication paths; split regression fixtures without increasing file, function, complexity, debt or exception limits. Require independent governance review and positive/negative OCI publication tests.",
+    "latestTransition": "Separate Compose preview registry identity from GitHub governance identity.",
+    "latestTransitionRationale": "Charge eleven measured production source lines for explicit scoped registry identity and fail-closed missing-credential checks. Preserve complete settlement, qualification and preview gates without increasing file, function, complexity, debt or exception limits; require independent governance review and credential-routing/write-rejection tests.",
     "rationale": "Bounded modules separate candidate, evidence, native proof and execution, canonical failure verification, closed-set execution transfer, process-boundary verification, Warrant state and qualification, authority state, qualification, Landing acquisition, verified-attempt admission, Landing settlement and fence validation, provider attempt and heartbeat readback, sealed terminal evidence, hosted heartbeat, resume, store, options, command-specific adapters, and CLI orchestration responsibilities. The protected delivery workflow gives candidate and seal jobs no provider write credential, recursively rejects transfer drift, scopes every transfer artifact to the exact provider run attempt, chains every durable heartbeat state and receipt root on a distinct hosted runner domain, and permits qualification or exact failure settlement only after the finalizer verifies live jobs and the latest durable authority state. Public Landing admission and heartbeat always perform non-injectable fresh exact-attempt provider readback, tolerate only a not-yet-materialized seal job while retaining exact native and duplicate-job rejection, and heartbeat-loss coordination never invokes GitHub's run-scoped cancellation API where a successor rerun could race. The hosted process boundary anchors trust in the kernel-resolved versioned Runner.Worker path while accepting an equivalent argv-zero spelling with the same basename; its public boundary marker is allowed only at the one exact non-secret value, so a forged value under the same credential-like name still fails closed. The credentialless transfer seal validates the rooted native reuse decision against the Warrant-bound source, closure, dependency, toolchain, environment and command inputs; qualifiedBase stays in the proof and decision where it is rooted and later independently rechecked, rather than being assumed on the Warrant schema. V2 mutation cannot initialize a second empty authority beside a legacy ref: migration reads and roots the canonical live v1 ref, rechecks it, applies the explicit configured v2 policy, and atomically replaces its bytes through one expected-old non-force update, so old v1 controllers fail closed while the prior commit remains immutable history. Candidate ancestry classifies the GitHub artifact runtime token as credential authority. Every Landing settlement, including an unexpired fence, requires product-owned terminal readback. Terminal cleanup reads the immutable historical attempt, derives workflow and hosted Landing job identity from live run data, reads the exact protected ref head and compares containment against that immutable SHA, and seals merged only when the admitted merge-group head is contained by that protected base; a later different-head merge settles the old attempt as dequeued. Terminal normalization preserves transfer, finalizer boundary, native and seal job, admitted provider attempt, protected-base head, containment result, and terminal readback coordinates. The public reusable workflow truthfully retains its single-flight v1 authority without advertising v2 migration, while bounded v2 remains a separate opt-in CLI, Node API, and schema contract; the tracked self-caller stays on public v4-alpha with matching stable and alpha locks, and transient train selection is dispatch-only. Next-development parity adds one versioned transition authority, one durable controller, one bounded reservation adapter, and pure public-contract recovery evidence while retaining the existing thin floating-channel callers byte-for-byte. The floating-consumer gate reuses the existing contract-world evaluator so SHA drift passes only under the selected lock's compatibility policy, breaking surface drift still fails closed, and external certification reconstructs the receipt from the observed workflow SHA rather than the lock's historical evidence SHA. Tail reseal adds no Stage Capsule effect or general rebuild authority: it verifies the exact retained four-platform bytes, admits one known macOS tail failure through live provider readback, fences signing and finalization to explicit credentials and Warrant identity, and requires standard candidate Passport plus provider and protected readback. Compatibility Facts parity isolates canonical encoding, temporal verification, lifecycle validation, fixture projection, public authority projection, and CLI adaptation into bounded modules; legacy digest and proof arrays are derived only from exact current Fact lineage. Publication Rehearsal adds no production release authority: the content-addressed capsule contract binds source, candidate, manifest, config, canonical data-only provider bindings, provider policy, observations and core version separately from filesystem, runtime and rehearsal-only provider authority; simulate, replay and explicitly authorized provider rehearsal all reuse the release-tail planner, while same-commit local dogfood resolves the new reusable contract and exact current runtime before external callers remain on floating v4-alpha. Cross-runtime candidate recovery preserves original runtime and provider roots and creates resume lineage only after exact public ref, tag, ancestry, npm version and integrity readback. Adopter Delivery restores the reviewed public v3 gate, drivers, Passport binding, N-1 bootstrap and exact archive loader through one public v4 surface while keeping provider and release authority explicit non-claims. Floating Alpha bootstrap uses only the existing exact resolver and protected Alpha private shell to move an otherwise stale floating shell, retains public v4 stable promotion, and removes itself after protected readback. CI lane change-budget enforcement adds a bounded parser, evaluator, guard, and tests without creating another merge authority.",
     "governance": "legacy-debt-sunset-2026q4"
   },

package/dist/site/buildchain-contract.json

@@ -4,7 +4,7 @@
   "product": {
     "name": "Buildchain",
     "package": "@kungfu-tech/buildchain",
-    "version": "4.0.2-alpha.50",
+    "version": "4.0.2-alpha.52",
     "repository": "https://github.com/kungfu-systems/buildchain"
   },
   "majorLine": "v4",
@@ -5444,5 +5444,5 @@
   "compatibilityFactCutRoot": "sha256:f61b975d4a96c921cc4bd37fb3ed9a0596b47004fe34dc7219979d697e3707f9",
   "compatibilityProofRegistryRoot": "sha256:b7194b811e4d3af2df4390bc4d1731e16a86215bd64ee18cb630dd5492f4fb63",
   "compatibilityDigest": "sha256:20411029d83211dff426fb6535a608902129844a5ccb4788db77d3f81becb839",
-  "contractDigest": "sha256:1ffa084654fcf7d8f82f11b15b0fffb6da3a5d5c68ca0e8ea667f3fb08e2b0f6"
+  "contractDigest": "sha256:4fd3bb75ecca81313c2d3cd669dd2e7ec729bb8ba11888ab26a8b6ed9cfc0263"
 }

package/dist/site/buildchain-site.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-site-bundle",
-  "generatedAt": "2026-09-07T02:04:08.000Z",
-  "publishedAt": "2026-09-07T02:04:08.000Z",
+  "generatedAt": "2026-09-07T04:57:43.000Z",
+  "publishedAt": "2026-09-07T04:57:43.000Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "b3481bbba92c6f4905f349a7cba239b32ea1db93",
+  "sourceRevision": "14b13cfc51afcadd251eee71d7e42842c35ce273",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -37,7 +37,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "4.0.2-alpha.50",
+    "version": "4.0.2-alpha.52",
     "versionSource": "package.json#version"
   },
   "source": {
@@ -3562,7 +3562,7 @@
       ],
       "maturity": "stable",
       "sourcePath": "docs/oci-publication.md",
-      "digest": "sha256:261f32b71ac4aedd0b718fc04b7ecd486d8ebf08ccdec475af849b8ffcec5603",
+      "digest": "sha256:daed970a66eb7b7cac87334d09e61449e8662c0655c7a345667bd2ef74f53af8",
       "headings": [
         {
           "level": 1,
@@ -3590,7 +3590,7 @@
           "anchor": "evidence-gated-compose-preview"
         }
       ],
-      "markdown": "---\nstatus: draft\nperiod: ongoing\ntheme: oci-publication\ndoc_type: technical-reference\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: B\nreview_state: unreviewed\nlast_reviewed: 2026-09-07\nai_provenance:\n  model_family: GPT-6\n  product: Codex\n  generated_at: 2026-09-06\n  invisible_context_boundary: No credentials or production registry state inspected.\n---\n\n# OCI image family publication\n\nBuildchain v4 can publish a sealed family of container images to GHCR through\n`publish-artifact-kind: oci` on the public release candidate promotion workflow.\nThe candidate build produces the image bytes and smoke evidence. The built-in\nprovider verifies and uploads those bytes, reads back every public image digest,\nthen allows release references and GitHub Release evidence to converge.\n\n## Candidate contract\n\nPublish exactly one `oci-family.json` alongside OCI layouts and smoke JSON files\nin the Build artifact. Import `sealOciPublicationBundle` from\n`@kungfu-tech/buildchain/oci-publication` to validate and seal the family. Its\n`body` contains:\n\n- `schema: kungfu-buildchain-oci-family/v1`, consumer `repository`, exact Git\n  `sourceSha`, and candidate package `version`.\n- `expectedImages`: the complete set of image names.\n- `images`: one entry for each expected image, with `name`, `repository`,\n  `digest`, `layout`, `platform`, `action`, `content`, and `smoke`.\n\nDestinations must be `ghcr.io/<consumer-owner>/<consumer-repo>/<image-name>`.\n`layout` is a relative OCI layout directory. Each image is a single Linux\namd64 or arm64 manifest; OCI and Docker schema 2 manifests are supported.\nLayouts may share blobs and an index; each shared index entry identifies its\nimage with the `org.opencontainers.image.ref.name` annotation.\n\n`content` records the image's original `sourceSha` and `version`, matching its\nOCI revision/version labels. For `action: built`, both equal the candidate.\nFor `action: reused`, they retain the original content provenance while the\nfamily binds the current candidate. `smoke` records a relative `path` and SHA256\n`sha256`; its JSON must identify the image and record `passed: true`. The\nconsumer owns the actual smoke command and must fail the build if it fails.\n\nSealing verifies all config/layer sizes and digests, platform and provenance\nlabels, smoke bytes, and family completeness. Absolute paths, traversal, and\nsymlinks are rejected. The resolver derives the exact required image artifacts\nfrom this sealed family, including when recovering a previous candidate run.\n\n## Authority and publication\n\nThe thin caller grants `packages: write` in addition to its existing promotion\npermissions. Reusable promotion wrappers inherit that caller envelope; npm\nconsumers do not need to request package registry authority. The provider uses\nthe action token only for GHCR, scoped to each declared consumer image.\nNo consumer publish command is executed.\n\nThe rooted product plan declares version-state materialization, OCI family\npublication, then release reference convergence. Each image uses the exact\n`v<version>` tag. A different existing digest aborts publication; a matching\nexisting image is reused. After a partial failure, recovery validates the same\ncandidate bytes and publishes only missing images. GHCR does not provide tag\ncompare-and-swap: callers must serialize publishers for a version, and external\nwriters must not race the publication workflow.\n\nSuccess requires anonymous readback of every declared image at its expected\ndigest. Existing GHCR packages must permit the repository token to write and\nanonymous clients to pull. The provider does not change package visibility or\naccess policy. It attaches `oci-publication-readback.json` to the GitHub Release;\nthe caller should also include the family and smoke JSON files in\n`github-release-payload-patterns`.\n\nSee [Runtime Train Validation](runtime-train-validation.md) for testing an\nunreleased runtime without persisting a train or exact SHA in the workflow.\n\n## Multi-platform images and Compose applications\n\nUse `schema: kungfu-buildchain-oci-family/v2` when the family includes an OCI\nindex or a Compose application. Existing v1 families keep their published\nsingle-platform contract.\n\nAn index entry declares `platform: multi-platform` and the complete `platforms`\narray, for example `[\"linux/amd64\", \"linux/arm64\"]`. Every runnable child must\nhave matching platform and content labels. Descriptor sizes, digests and media\ntypes are verified recursively; nested manifests are uploaded before their\nparent index. BuildKit attestation manifests must identify a runnable child and\ncontain matching in-toto subjects. Missing platforms, duplicate platforms,\nforeign URLs and broken blob references fail sealing. Embedded descriptor `data`\nis accepted only as canonical Base64 for at most 1 MiB, with the declared size\nand digest matching the required local blob byte for byte. Malformed or\ninconsistent embedded content fails sealing; manifests are never rewritten.\nThis follows the [OCI embedded-content contract](https://github.com/opencontainers/image-spec/blob/main/descriptor.md#embedded-content).\n\nA Compose entry declares `kind: compose`, `platform: compose`, and `targetImage`\npointing to an image in the same family. Its unique family name may differ from\nthat image, but its destination repository must match it. The immutable tag is\n`compose-v<version>`; image entries retain `v<version>`.\n\nThe bounded Compose representation is an OCI 1.1 image manifest with\n`artifactType: application/vnd.docker.compose.project`, an empty JSON config\nand one `application/vnd.docker.compose.file+yaml` layer. That layer contains\nJSON, a YAML subset, so structural verification needs no executable YAML loader.\nEvery service image is pinned to a digest and at least one uses the exact\nfamily image. Environment interpolation inside other fields can remain intact.\nThese media types follow the [Docker Compose publisher](https://github.com/docker/compose/blob/v5.1.2/internal/oci/push.go).\n\nCandidate smoke evidence describes its actual pre-publication checks. It must\nnot claim that an unpublished public Compose reference was installed. Public\ninstallation qualification occurs after immutable publication and before a\npreview alias moves.\n\n## Evidence-gated Compose preview\n\nAn optional Compose `preview` declaration contains exactly the supported alias\n`compose-preview`, the previously accepted `previousDigest` (or `none`), and\n`qualificationWorkflow`, a repository workflow path. The immutable family seals\nthis policy before any publication effect.\n\nAfter v4 publication is complete, dispatch that qualification workflow on the\nexact published alpha tag. It must pull the immutable public image and Compose,\nrun fresh installation, restart, account-isolation, runtime-hardening, upgrade\nand rollback checks, and qualify both Linux architectures. The workflow has no\nregistry write authority. Upload one artifact named\n`oci-compose-qualification-<run-id>-<run-attempt>` containing `qualification.json`\nand its hash-bound JSON evidence files.\n\nThe receipt uses `schema: kungfu-buildchain-compose-qualification/v1` and binds\n`repository`, `tag`, published `sourceSha`, sealed `familyRoot`, `runId`,\n`runAttempt`, exact `image` and `application` repository/digest references,\n`previousDigest`, and `passed: true`. Its `checks` object requires all of\n`freshInstall`, `restartPersistence`, `upgradePersistence`, `rollbackPersistence`,\n`accountIsolation`, and `hardenedRuntime` to be true. Its `platforms` object\nrequires `linux/amd64` and `linux/arm64` entries with `passed: true`; `evidence`\ncontains nonempty `{path, sha256}` bindings to the actual JSON results.\n\nA thin consumer workflow listens to completion of that qualification workflow\nand calls `public-release-oci-compose-preview.yml@v4-alpha`, passing\n`BUILDCHAIN_PROMOTION_TOKEN`. The reusable workflow resolves its own exact\nruntime, enforces the dual floating-channel locks, verifies the public v4\nsettlement, family and provider readback roots, and checks the live GitHub run's\nrepository, source, workflow, event, attempt and successful conclusion. It never\nexecutes the consumer's artifact files. Only then does it copy the exact Compose\nmanifest bytes to the declared alias and verify the public digest.\n\nThe expected-old digest is checked immediately before mutation. An already\nmatching target is an idempotent success; any other drift blocks the move.\nPublishers for this alias share repository-level concurrency. GHCR has no atomic\ntag compare-and-swap, so external writers must also avoid racing this workflow.\nThe immutable release retains the appended\n`buildchain-compose-preview-<run-id>-<run-attempt>.json` receipt. A failed\nqualification leaves the existing preview intact, while the immutable alpha\nand its original publication evidence remain available for diagnosis."
+      "markdown": "---\nstatus: draft\nperiod: ongoing\ntheme: oci-publication\ndoc_type: technical-reference\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: B\nreview_state: unreviewed\nlast_reviewed: 2026-09-07\nai_provenance:\n  model_family: GPT-6\n  product: Codex\n  generated_at: 2026-09-06\n  invisible_context_boundary: No credentials or production registry state inspected.\n---\n\n# OCI image family publication\n\nCompose preview uses the workflow's scoped `packages: write` token for GHCR\nrequests. The separate `BUILDCHAIN_PROMOTION_TOKEN` serves GitHub governance\nand receipt publication; it is never a fallback registry credential. Missing\nregistry identity fails before a write, and an unsuccessful registry response\nreports only its HTTP status while retaining the exact qualification for recovery.\n\nBuildchain v4 can publish a sealed family of container images to GHCR through\n`publish-artifact-kind: oci` on the public release candidate promotion workflow.\nThe candidate build produces the image bytes and smoke evidence. The built-in\nprovider verifies and uploads those bytes, reads back every public image digest,\nthen allows release references and GitHub Release evidence to converge.\n\n## Candidate contract\n\nPublish exactly one `oci-family.json` alongside OCI layouts and smoke JSON files\nin the Build artifact. Import `sealOciPublicationBundle` from\n`@kungfu-tech/buildchain/oci-publication` to validate and seal the family. Its\n`body` contains:\n\n- `schema: kungfu-buildchain-oci-family/v1`, consumer `repository`, exact Git\n  `sourceSha`, and candidate package `version`.\n- `expectedImages`: the complete set of image names.\n- `images`: one entry for each expected image, with `name`, `repository`,\n  `digest`, `layout`, `platform`, `action`, `content`, and `smoke`.\n\nDestinations must be `ghcr.io/<consumer-owner>/<consumer-repo>/<image-name>`.\n`layout` is a relative OCI layout directory. Each image is a single Linux\namd64 or arm64 manifest; OCI and Docker schema 2 manifests are supported.\nLayouts may share blobs and an index; each shared index entry identifies its\nimage with the `org.opencontainers.image.ref.name` annotation.\n\n`content` records the image's original `sourceSha` and `version`, matching its\nOCI revision/version labels. For `action: built`, both equal the candidate.\nFor `action: reused`, they retain the original content provenance while the\nfamily binds the current candidate. `smoke` records a relative `path` and SHA256\n`sha256`; its JSON must identify the image and record `passed: true`. The\nconsumer owns the actual smoke command and must fail the build if it fails.\n\nSealing verifies all config/layer sizes and digests, platform and provenance\nlabels, smoke bytes, and family completeness. Absolute paths, traversal, and\nsymlinks are rejected. The resolver derives the exact required image artifacts\nfrom this sealed family, including when recovering a previous candidate run.\n\n## Authority and publication\n\nThe thin caller grants `packages: write` in addition to its existing promotion\npermissions. Reusable promotion wrappers inherit that caller envelope; npm\nconsumers do not need to request package registry authority. The provider uses\nthe action token only for GHCR, scoped to each declared consumer image.\nNo consumer publish command is executed.\n\nThe rooted product plan declares version-state materialization, OCI family\npublication, then release reference convergence. Each image uses the exact\n`v<version>` tag. A different existing digest aborts publication; a matching\nexisting image is reused. After a partial failure, recovery validates the same\ncandidate bytes and publishes only missing images. GHCR does not provide tag\ncompare-and-swap: callers must serialize publishers for a version, and external\nwriters must not race the publication workflow.\n\nSuccess requires anonymous readback of every declared image at its expected\ndigest. Existing GHCR packages must permit the repository token to write and\nanonymous clients to pull. The provider does not change package visibility or\naccess policy. It attaches `oci-publication-readback.json` to the GitHub Release;\nthe caller should also include the family and smoke JSON files in\n`github-release-payload-patterns`.\n\nSee [Runtime Train Validation](runtime-train-validation.md) for testing an\nunreleased runtime without persisting a train or exact SHA in the workflow.\n\n## Multi-platform images and Compose applications\n\nUse `schema: kungfu-buildchain-oci-family/v2` when the family includes an OCI\nindex or a Compose application. Existing v1 families keep their published\nsingle-platform contract.\n\nAn index entry declares `platform: multi-platform` and the complete `platforms`\narray, for example `[\"linux/amd64\", \"linux/arm64\"]`. Every runnable child must\nhave matching platform and content labels. Descriptor sizes, digests and media\ntypes are verified recursively; nested manifests are uploaded before their\nparent index. BuildKit attestation manifests must identify a runnable child and\ncontain matching in-toto subjects. Missing platforms, duplicate platforms,\nforeign URLs and broken blob references fail sealing. Embedded descriptor `data`\nis accepted only as canonical Base64 for at most 1 MiB, with the declared size\nand digest matching the required local blob byte for byte. Malformed or\ninconsistent embedded content fails sealing; manifests are never rewritten.\nThis follows the [OCI embedded-content contract](https://github.com/opencontainers/image-spec/blob/main/descriptor.md#embedded-content).\n\nA Compose entry declares `kind: compose`, `platform: compose`, and `targetImage`\npointing to an image in the same family. Its unique family name may differ from\nthat image, but its destination repository must match it. The immutable tag is\n`compose-v<version>`; image entries retain `v<version>`.\n\nThe bounded Compose representation is an OCI 1.1 image manifest with\n`artifactType: application/vnd.docker.compose.project`, an empty JSON config\nand one `application/vnd.docker.compose.file+yaml` layer. That layer contains\nJSON, a YAML subset, so structural verification needs no executable YAML loader.\nEvery service image is pinned to a digest and at least one uses the exact\nfamily image. Environment interpolation inside other fields can remain intact.\nThese media types follow the [Docker Compose publisher](https://github.com/docker/compose/blob/v5.1.2/internal/oci/push.go).\n\nCandidate smoke evidence describes its actual pre-publication checks. It must\nnot claim that an unpublished public Compose reference was installed. Public\ninstallation qualification occurs after immutable publication and before a\npreview alias moves.\n\n## Evidence-gated Compose preview\n\nAn optional Compose `preview` declaration contains exactly the supported alias\n`compose-preview`, the previously accepted `previousDigest` (or `none`), and\n`qualificationWorkflow`, a repository workflow path. The immutable family seals\nthis policy before any publication effect.\n\nAfter v4 publication is complete, dispatch that qualification workflow on the\nexact published alpha tag. It must pull the immutable public image and Compose,\nrun fresh installation, restart, account-isolation, runtime-hardening, upgrade\nand rollback checks, and qualify both Linux architectures. The workflow has no\nregistry write authority. Upload one artifact named\n`oci-compose-qualification-<run-id>-<run-attempt>` containing `qualification.json`\nand its hash-bound JSON evidence files.\n\nThe receipt uses `schema: kungfu-buildchain-compose-qualification/v1` and binds\n`repository`, `tag`, published `sourceSha`, sealed `familyRoot`, `runId`,\n`runAttempt`, exact `image` and `application` repository/digest references,\n`previousDigest`, and `passed: true`. Its `checks` object requires all of\n`freshInstall`, `restartPersistence`, `upgradePersistence`, `rollbackPersistence`,\n`accountIsolation`, and `hardenedRuntime` to be true. Its `platforms` object\nrequires `linux/amd64` and `linux/arm64` entries with `passed: true`; `evidence`\ncontains nonempty `{path, sha256}` bindings to the actual JSON results.\n\nA thin consumer workflow listens to completion of that qualification workflow\nand calls `public-release-oci-compose-preview.yml@v4-alpha`, passing\n`BUILDCHAIN_PROMOTION_TOKEN`. The reusable workflow resolves its own exact\nruntime, enforces the dual floating-channel locks, verifies the public v4\nsettlement, family and provider readback roots, and checks the live GitHub run's\nrepository, source, workflow, event, attempt and successful conclusion. It never\nexecutes the consumer's artifact files. Only then does it copy the exact Compose\nmanifest bytes to the declared alias and verify the public digest.\n\nThe expected-old digest is checked immediately before mutation. An already\nmatching target is an idempotent success; any other drift blocks the move.\nPublishers for this alias share repository-level concurrency. GHCR has no atomic\ntag compare-and-swap, so external writers must also avoid racing this workflow.\nThe immutable release retains the appended\n`buildchain-compose-preview-<run-id>-<run-attempt>.json` receipt. A failed\nqualification leaves the existing preview intact, while the immutable alpha\nand its original publication evidence remain available for diagnosis.\n\nThe verified publication Passport distinguishes the built candidate from the\nprotected publication commit. Compose family source identity follows\n`source.builtSourceSha`; `source.builtSourceTreeSha` must equal the admitted\ninvocation tree. Registry readback and qualification runs remain bound to the\nprotected publication SHA. A tree-equivalent protected merge therefore retains\nthe original image identity without accepting a different source tree."
     },
     {
       "id": "manual:ownership",

package/dist/site/kfd-claims.json

@@ -21,7 +21,7 @@
     "contract": "kungfu-buildchain-public-surface-reverse-audit",
     "path": "dist/site/public-surface-audit.json",
     "status": "passed",
-    "sha256": "233f353cc1de6036c90eab889ea673c1887903829810cfa0a7d844e196340c16",
+    "sha256": "30a7781b240c20641b0e9e96aa4e2780708dfec5b3671c5dd532540d9a4d341a",
     "summary": {
       "cliCommandCount": 117,
       "workflowCount": 115,
@@ -246,7 +246,7 @@
       "contract": "kungfu-buildchain-public-surface-reverse-audit",
       "path": "dist/site/public-surface-audit.json",
       "status": "passed",
-      "sha256": "233f353cc1de6036c90eab889ea673c1887903829810cfa0a7d844e196340c16",
+      "sha256": "30a7781b240c20641b0e9e96aa4e2780708dfec5b3671c5dd532540d9a4d341a",
       "summary": {
         "cliCommandCount": 117,
         "workflowCount": 115,

package/dist/site/kfd-upstream-aggregate.json

@@ -4,7 +4,7 @@
   "product": {
     "id": "kungfu-tech-buildchain",
     "name": "@kungfu-tech/buildchain",
-    "version": "4.0.2-alpha.50",
+    "version": "4.0.2-alpha.52",
     "repository": "https://github.com/kungfu-systems/buildchain"
   },
   "source": {

package/dist/site/page-registry.json

@@ -3496,7 +3496,7 @@
       ],
       "maturity": "stable",
       "sourcePath": "docs/oci-publication.md",
-      "digest": "sha256:261f32b71ac4aedd0b718fc04b7ecd486d8ebf08ccdec475af849b8ffcec5603",
+      "digest": "sha256:daed970a66eb7b7cac87334d09e61449e8662c0655c7a345667bd2ef74f53af8",
       "headings": [
         {
           "level": 1,
@@ -3524,7 +3524,7 @@
           "anchor": "evidence-gated-compose-preview"
         }
       ],
-      "markdown": "---\nstatus: draft\nperiod: ongoing\ntheme: oci-publication\ndoc_type: technical-reference\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: B\nreview_state: unreviewed\nlast_reviewed: 2026-09-07\nai_provenance:\n  model_family: GPT-6\n  product: Codex\n  generated_at: 2026-09-06\n  invisible_context_boundary: No credentials or production registry state inspected.\n---\n\n# OCI image family publication\n\nBuildchain v4 can publish a sealed family of container images to GHCR through\n`publish-artifact-kind: oci` on the public release candidate promotion workflow.\nThe candidate build produces the image bytes and smoke evidence. The built-in\nprovider verifies and uploads those bytes, reads back every public image digest,\nthen allows release references and GitHub Release evidence to converge.\n\n## Candidate contract\n\nPublish exactly one `oci-family.json` alongside OCI layouts and smoke JSON files\nin the Build artifact. Import `sealOciPublicationBundle` from\n`@kungfu-tech/buildchain/oci-publication` to validate and seal the family. Its\n`body` contains:\n\n- `schema: kungfu-buildchain-oci-family/v1`, consumer `repository`, exact Git\n  `sourceSha`, and candidate package `version`.\n- `expectedImages`: the complete set of image names.\n- `images`: one entry for each expected image, with `name`, `repository`,\n  `digest`, `layout`, `platform`, `action`, `content`, and `smoke`.\n\nDestinations must be `ghcr.io/<consumer-owner>/<consumer-repo>/<image-name>`.\n`layout` is a relative OCI layout directory. Each image is a single Linux\namd64 or arm64 manifest; OCI and Docker schema 2 manifests are supported.\nLayouts may share blobs and an index; each shared index entry identifies its\nimage with the `org.opencontainers.image.ref.name` annotation.\n\n`content` records the image's original `sourceSha` and `version`, matching its\nOCI revision/version labels. For `action: built`, both equal the candidate.\nFor `action: reused`, they retain the original content provenance while the\nfamily binds the current candidate. `smoke` records a relative `path` and SHA256\n`sha256`; its JSON must identify the image and record `passed: true`. The\nconsumer owns the actual smoke command and must fail the build if it fails.\n\nSealing verifies all config/layer sizes and digests, platform and provenance\nlabels, smoke bytes, and family completeness. Absolute paths, traversal, and\nsymlinks are rejected. The resolver derives the exact required image artifacts\nfrom this sealed family, including when recovering a previous candidate run.\n\n## Authority and publication\n\nThe thin caller grants `packages: write` in addition to its existing promotion\npermissions. Reusable promotion wrappers inherit that caller envelope; npm\nconsumers do not need to request package registry authority. The provider uses\nthe action token only for GHCR, scoped to each declared consumer image.\nNo consumer publish command is executed.\n\nThe rooted product plan declares version-state materialization, OCI family\npublication, then release reference convergence. Each image uses the exact\n`v<version>` tag. A different existing digest aborts publication; a matching\nexisting image is reused. After a partial failure, recovery validates the same\ncandidate bytes and publishes only missing images. GHCR does not provide tag\ncompare-and-swap: callers must serialize publishers for a version, and external\nwriters must not race the publication workflow.\n\nSuccess requires anonymous readback of every declared image at its expected\ndigest. Existing GHCR packages must permit the repository token to write and\nanonymous clients to pull. The provider does not change package visibility or\naccess policy. It attaches `oci-publication-readback.json` to the GitHub Release;\nthe caller should also include the family and smoke JSON files in\n`github-release-payload-patterns`.\n\nSee [Runtime Train Validation](runtime-train-validation.md) for testing an\nunreleased runtime without persisting a train or exact SHA in the workflow.\n\n## Multi-platform images and Compose applications\n\nUse `schema: kungfu-buildchain-oci-family/v2` when the family includes an OCI\nindex or a Compose application. Existing v1 families keep their published\nsingle-platform contract.\n\nAn index entry declares `platform: multi-platform` and the complete `platforms`\narray, for example `[\"linux/amd64\", \"linux/arm64\"]`. Every runnable child must\nhave matching platform and content labels. Descriptor sizes, digests and media\ntypes are verified recursively; nested manifests are uploaded before their\nparent index. BuildKit attestation manifests must identify a runnable child and\ncontain matching in-toto subjects. Missing platforms, duplicate platforms,\nforeign URLs and broken blob references fail sealing. Embedded descriptor `data`\nis accepted only as canonical Base64 for at most 1 MiB, with the declared size\nand digest matching the required local blob byte for byte. Malformed or\ninconsistent embedded content fails sealing; manifests are never rewritten.\nThis follows the [OCI embedded-content contract](https://github.com/opencontainers/image-spec/blob/main/descriptor.md#embedded-content).\n\nA Compose entry declares `kind: compose`, `platform: compose`, and `targetImage`\npointing to an image in the same family. Its unique family name may differ from\nthat image, but its destination repository must match it. The immutable tag is\n`compose-v<version>`; image entries retain `v<version>`.\n\nThe bounded Compose representation is an OCI 1.1 image manifest with\n`artifactType: application/vnd.docker.compose.project`, an empty JSON config\nand one `application/vnd.docker.compose.file+yaml` layer. That layer contains\nJSON, a YAML subset, so structural verification needs no executable YAML loader.\nEvery service image is pinned to a digest and at least one uses the exact\nfamily image. Environment interpolation inside other fields can remain intact.\nThese media types follow the [Docker Compose publisher](https://github.com/docker/compose/blob/v5.1.2/internal/oci/push.go).\n\nCandidate smoke evidence describes its actual pre-publication checks. It must\nnot claim that an unpublished public Compose reference was installed. Public\ninstallation qualification occurs after immutable publication and before a\npreview alias moves.\n\n## Evidence-gated Compose preview\n\nAn optional Compose `preview` declaration contains exactly the supported alias\n`compose-preview`, the previously accepted `previousDigest` (or `none`), and\n`qualificationWorkflow`, a repository workflow path. The immutable family seals\nthis policy before any publication effect.\n\nAfter v4 publication is complete, dispatch that qualification workflow on the\nexact published alpha tag. It must pull the immutable public image and Compose,\nrun fresh installation, restart, account-isolation, runtime-hardening, upgrade\nand rollback checks, and qualify both Linux architectures. The workflow has no\nregistry write authority. Upload one artifact named\n`oci-compose-qualification-<run-id>-<run-attempt>` containing `qualification.json`\nand its hash-bound JSON evidence files.\n\nThe receipt uses `schema: kungfu-buildchain-compose-qualification/v1` and binds\n`repository`, `tag`, published `sourceSha`, sealed `familyRoot`, `runId`,\n`runAttempt`, exact `image` and `application` repository/digest references,\n`previousDigest`, and `passed: true`. Its `checks` object requires all of\n`freshInstall`, `restartPersistence`, `upgradePersistence`, `rollbackPersistence`,\n`accountIsolation`, and `hardenedRuntime` to be true. Its `platforms` object\nrequires `linux/amd64` and `linux/arm64` entries with `passed: true`; `evidence`\ncontains nonempty `{path, sha256}` bindings to the actual JSON results.\n\nA thin consumer workflow listens to completion of that qualification workflow\nand calls `public-release-oci-compose-preview.yml@v4-alpha`, passing\n`BUILDCHAIN_PROMOTION_TOKEN`. The reusable workflow resolves its own exact\nruntime, enforces the dual floating-channel locks, verifies the public v4\nsettlement, family and provider readback roots, and checks the live GitHub run's\nrepository, source, workflow, event, attempt and successful conclusion. It never\nexecutes the consumer's artifact files. Only then does it copy the exact Compose\nmanifest bytes to the declared alias and verify the public digest.\n\nThe expected-old digest is checked immediately before mutation. An already\nmatching target is an idempotent success; any other drift blocks the move.\nPublishers for this alias share repository-level concurrency. GHCR has no atomic\ntag compare-and-swap, so external writers must also avoid racing this workflow.\nThe immutable release retains the appended\n`buildchain-compose-preview-<run-id>-<run-attempt>.json` receipt. A failed\nqualification leaves the existing preview intact, while the immutable alpha\nand its original publication evidence remain available for diagnosis."
+      "markdown": "---\nstatus: draft\nperiod: ongoing\ntheme: oci-publication\ndoc_type: technical-reference\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: B\nreview_state: unreviewed\nlast_reviewed: 2026-09-07\nai_provenance:\n  model_family: GPT-6\n  product: Codex\n  generated_at: 2026-09-06\n  invisible_context_boundary: No credentials or production registry state inspected.\n---\n\n# OCI image family publication\n\nCompose preview uses the workflow's scoped `packages: write` token for GHCR\nrequests. The separate `BUILDCHAIN_PROMOTION_TOKEN` serves GitHub governance\nand receipt publication; it is never a fallback registry credential. Missing\nregistry identity fails before a write, and an unsuccessful registry response\nreports only its HTTP status while retaining the exact qualification for recovery.\n\nBuildchain v4 can publish a sealed family of container images to GHCR through\n`publish-artifact-kind: oci` on the public release candidate promotion workflow.\nThe candidate build produces the image bytes and smoke evidence. The built-in\nprovider verifies and uploads those bytes, reads back every public image digest,\nthen allows release references and GitHub Release evidence to converge.\n\n## Candidate contract\n\nPublish exactly one `oci-family.json` alongside OCI layouts and smoke JSON files\nin the Build artifact. Import `sealOciPublicationBundle` from\n`@kungfu-tech/buildchain/oci-publication` to validate and seal the family. Its\n`body` contains:\n\n- `schema: kungfu-buildchain-oci-family/v1`, consumer `repository`, exact Git\n  `sourceSha`, and candidate package `version`.\n- `expectedImages`: the complete set of image names.\n- `images`: one entry for each expected image, with `name`, `repository`,\n  `digest`, `layout`, `platform`, `action`, `content`, and `smoke`.\n\nDestinations must be `ghcr.io/<consumer-owner>/<consumer-repo>/<image-name>`.\n`layout` is a relative OCI layout directory. Each image is a single Linux\namd64 or arm64 manifest; OCI and Docker schema 2 manifests are supported.\nLayouts may share blobs and an index; each shared index entry identifies its\nimage with the `org.opencontainers.image.ref.name` annotation.\n\n`content` records the image's original `sourceSha` and `version`, matching its\nOCI revision/version labels. For `action: built`, both equal the candidate.\nFor `action: reused`, they retain the original content provenance while the\nfamily binds the current candidate. `smoke` records a relative `path` and SHA256\n`sha256`; its JSON must identify the image and record `passed: true`. The\nconsumer owns the actual smoke command and must fail the build if it fails.\n\nSealing verifies all config/layer sizes and digests, platform and provenance\nlabels, smoke bytes, and family completeness. Absolute paths, traversal, and\nsymlinks are rejected. The resolver derives the exact required image artifacts\nfrom this sealed family, including when recovering a previous candidate run.\n\n## Authority and publication\n\nThe thin caller grants `packages: write` in addition to its existing promotion\npermissions. Reusable promotion wrappers inherit that caller envelope; npm\nconsumers do not need to request package registry authority. The provider uses\nthe action token only for GHCR, scoped to each declared consumer image.\nNo consumer publish command is executed.\n\nThe rooted product plan declares version-state materialization, OCI family\npublication, then release reference convergence. Each image uses the exact\n`v<version>` tag. A different existing digest aborts publication; a matching\nexisting image is reused. After a partial failure, recovery validates the same\ncandidate bytes and publishes only missing images. GHCR does not provide tag\ncompare-and-swap: callers must serialize publishers for a version, and external\nwriters must not race the publication workflow.\n\nSuccess requires anonymous readback of every declared image at its expected\ndigest. Existing GHCR packages must permit the repository token to write and\nanonymous clients to pull. The provider does not change package visibility or\naccess policy. It attaches `oci-publication-readback.json` to the GitHub Release;\nthe caller should also include the family and smoke JSON files in\n`github-release-payload-patterns`.\n\nSee [Runtime Train Validation](runtime-train-validation.md) for testing an\nunreleased runtime without persisting a train or exact SHA in the workflow.\n\n## Multi-platform images and Compose applications\n\nUse `schema: kungfu-buildchain-oci-family/v2` when the family includes an OCI\nindex or a Compose application. Existing v1 families keep their published\nsingle-platform contract.\n\nAn index entry declares `platform: multi-platform` and the complete `platforms`\narray, for example `[\"linux/amd64\", \"linux/arm64\"]`. Every runnable child must\nhave matching platform and content labels. Descriptor sizes, digests and media\ntypes are verified recursively; nested manifests are uploaded before their\nparent index. BuildKit attestation manifests must identify a runnable child and\ncontain matching in-toto subjects. Missing platforms, duplicate platforms,\nforeign URLs and broken blob references fail sealing. Embedded descriptor `data`\nis accepted only as canonical Base64 for at most 1 MiB, with the declared size\nand digest matching the required local blob byte for byte. Malformed or\ninconsistent embedded content fails sealing; manifests are never rewritten.\nThis follows the [OCI embedded-content contract](https://github.com/opencontainers/image-spec/blob/main/descriptor.md#embedded-content).\n\nA Compose entry declares `kind: compose`, `platform: compose`, and `targetImage`\npointing to an image in the same family. Its unique family name may differ from\nthat image, but its destination repository must match it. The immutable tag is\n`compose-v<version>`; image entries retain `v<version>`.\n\nThe bounded Compose representation is an OCI 1.1 image manifest with\n`artifactType: application/vnd.docker.compose.project`, an empty JSON config\nand one `application/vnd.docker.compose.file+yaml` layer. That layer contains\nJSON, a YAML subset, so structural verification needs no executable YAML loader.\nEvery service image is pinned to a digest and at least one uses the exact\nfamily image. Environment interpolation inside other fields can remain intact.\nThese media types follow the [Docker Compose publisher](https://github.com/docker/compose/blob/v5.1.2/internal/oci/push.go).\n\nCandidate smoke evidence describes its actual pre-publication checks. It must\nnot claim that an unpublished public Compose reference was installed. Public\ninstallation qualification occurs after immutable publication and before a\npreview alias moves.\n\n## Evidence-gated Compose preview\n\nAn optional Compose `preview` declaration contains exactly the supported alias\n`compose-preview`, the previously accepted `previousDigest` (or `none`), and\n`qualificationWorkflow`, a repository workflow path. The immutable family seals\nthis policy before any publication effect.\n\nAfter v4 publication is complete, dispatch that qualification workflow on the\nexact published alpha tag. It must pull the immutable public image and Compose,\nrun fresh installation, restart, account-isolation, runtime-hardening, upgrade\nand rollback checks, and qualify both Linux architectures. The workflow has no\nregistry write authority. Upload one artifact named\n`oci-compose-qualification-<run-id>-<run-attempt>` containing `qualification.json`\nand its hash-bound JSON evidence files.\n\nThe receipt uses `schema: kungfu-buildchain-compose-qualification/v1` and binds\n`repository`, `tag`, published `sourceSha`, sealed `familyRoot`, `runId`,\n`runAttempt`, exact `image` and `application` repository/digest references,\n`previousDigest`, and `passed: true`. Its `checks` object requires all of\n`freshInstall`, `restartPersistence`, `upgradePersistence`, `rollbackPersistence`,\n`accountIsolation`, and `hardenedRuntime` to be true. Its `platforms` object\nrequires `linux/amd64` and `linux/arm64` entries with `passed: true`; `evidence`\ncontains nonempty `{path, sha256}` bindings to the actual JSON results.\n\nA thin consumer workflow listens to completion of that qualification workflow\nand calls `public-release-oci-compose-preview.yml@v4-alpha`, passing\n`BUILDCHAIN_PROMOTION_TOKEN`. The reusable workflow resolves its own exact\nruntime, enforces the dual floating-channel locks, verifies the public v4\nsettlement, family and provider readback roots, and checks the live GitHub run's\nrepository, source, workflow, event, attempt and successful conclusion. It never\nexecutes the consumer's artifact files. Only then does it copy the exact Compose\nmanifest bytes to the declared alias and verify the public digest.\n\nThe expected-old digest is checked immediately before mutation. An already\nmatching target is an idempotent success; any other drift blocks the move.\nPublishers for this alias share repository-level concurrency. GHCR has no atomic\ntag compare-and-swap, so external writers must also avoid racing this workflow.\nThe immutable release retains the appended\n`buildchain-compose-preview-<run-id>-<run-attempt>.json` receipt. A failed\nqualification leaves the existing preview intact, while the immutable alpha\nand its original publication evidence remain available for diagnosis.\n\nThe verified publication Passport distinguishes the built candidate from the\nprotected publication commit. Compose family source identity follows\n`source.builtSourceSha`; `source.builtSourceTreeSha` must equal the admitted\ninvocation tree. Registry readback and qualification runs remain bound to the\nprotected publication SHA. A tree-equivalent protected merge therefore retains\nthe original image identity without accepting a different source tree."
     },
     {
       "id": "manual:ownership",

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

@@ -10948,8 +10948,8 @@
     "workflowRegistryPath": "dist/site/workflow-registry.json",
     "pageRegistryPath": "dist/site/page-registry.json",
     "cliRegistryDigest": "fbc23073bbae240489a2f826b2c26daadc58e704050c5f8df366509f5c5a1c3e",
-    "workflowRegistryDigest": "fa9ab9e9e45d7099071563d380eb8b1050cd32e03f30d450b7b763c567fd15e2",
-    "pageRegistryDigest": "545a66bc71a8a2a56589aabf3fb48c9cae13752fddf802b9bdfe7659b4eddc30"
+    "workflowRegistryDigest": "d7f9eddd25a41e892b553b5e070cdcc69c4b1213f1bc6a41bbd89c0c97737c8d",
+    "pageRegistryDigest": "4c9fc70dc2f9989c1b962f43f68ed907864251a594463fa10bf6a9a8bd7e5721"
   },
   "comparison": {
     "missingCliRegistry": [],

package/dist/site/publication-registry.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-publication-release-registry",
-  "generatedAt": "2026-09-07T02:04:08.000Z",
-  "publishedAt": "2026-09-07T02:04:08.000Z",
+  "generatedAt": "2026-09-07T04:57:43.000Z",
+  "publishedAt": "2026-09-07T04:57:43.000Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "b3481bbba92c6f4905f349a7cba239b32ea1db93",
+  "sourceRevision": "14b13cfc51afcadd251eee71d7e42842c35ce273",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -32,7 +32,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "4.0.2-alpha.50",
+    "version": "4.0.2-alpha.52",
     "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-09-07T02:04:08.000Z",
-  "publishedAt": "2026-09-07T02:04:08.000Z",
+  "generatedAt": "2026-09-07T04:57:43.000Z",
+  "publishedAt": "2026-09-07T04:57:43.000Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "b3481bbba92c6f4905f349a7cba239b32ea1db93",
+  "sourceRevision": "14b13cfc51afcadd251eee71d7e42842c35ce273",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -37,7 +37,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "4.0.2-alpha.50",
+    "version": "4.0.2-alpha.52",
     "versionSource": "package.json#version"
   },
   "entrypoint": "buildchain-site.json",

package/dist/site/workflow-registry.json

@@ -2746,7 +2746,7 @@
       "status": "preview",
       "owner": "buildchain-workflows",
       "maturity": "preview",
-      "introducedVersion": "4.0.2-alpha.50",
+      "introducedVersion": "4.0.2-alpha.52",
       "compatibilityPromise": "preserved-through-the-v3-major-line",
       "deprecationReplacement": "",
       "sunsetCondition": "explicit-breaking-change-review-in-a-future-major-line",
@@ -3943,7 +3943,7 @@
       "status": "preview",
       "owner": "buildchain-workflows",
       "maturity": "preview",
-      "introducedVersion": "4.0.2-alpha.50",
+      "introducedVersion": "4.0.2-alpha.52",
       "compatibilityPromise": "preserved-through-the-v3-major-line",
       "deprecationReplacement": "",
       "sunsetCondition": "explicit-breaking-change-review-in-a-future-major-line",
@@ -6004,7 +6004,7 @@
       "status": "preview",
       "owner": "buildchain-workflows",
       "maturity": "preview",
-      "introducedVersion": "4.0.2-alpha.50",
+      "introducedVersion": "4.0.2-alpha.52",
       "compatibilityPromise": "preserved-through-the-v3-major-line",
       "deprecationReplacement": "",
       "sunsetCondition": "explicit-breaking-change-review-in-a-future-major-line",
@@ -6035,7 +6035,7 @@
       "status": "preview",
       "owner": "buildchain-workflows",
       "maturity": "preview",
-      "introducedVersion": "4.0.2-alpha.50",
+      "introducedVersion": "4.0.2-alpha.52",
       "compatibilityPromise": "preserved-through-the-v3-major-line",
       "deprecationReplacement": "",
       "sunsetCondition": "explicit-breaking-change-review-in-a-future-major-line",
@@ -6066,7 +6066,7 @@
       "status": "preview",
       "owner": "buildchain-workflows",
       "maturity": "preview",
-      "introducedVersion": "4.0.2-alpha.50",
+      "introducedVersion": "4.0.2-alpha.52",
       "compatibilityPromise": "preserved-through-the-v3-major-line",
       "deprecationReplacement": "",
       "sunsetCondition": "explicit-breaking-change-review-in-a-future-major-line",

package/docs/oci-publication.md

@@ -18,6 +18,12 @@ ai_provenance:
 
 # OCI image family publication
 
+Compose preview uses the workflow's scoped `packages: write` token for GHCR
+requests. The separate `BUILDCHAIN_PROMOTION_TOKEN` serves GitHub governance
+and receipt publication; it is never a fallback registry credential. Missing
+registry identity fails before a write, and an unsuccessful registry response
+reports only its HTTP status while retaining the exact qualification for recovery.
+
 Buildchain v4 can publish a sealed family of container images to GHCR through
 `publish-artifact-kind: oci` on the public release candidate promotion workflow.
 The candidate build produces the image bytes and smoke evidence. The built-in
@@ -158,3 +164,10 @@ The immutable release retains the appended
 `buildchain-compose-preview-<run-id>-<run-attempt>.json` receipt. A failed
 qualification leaves the existing preview intact, while the immutable alpha
 and its original publication evidence remain available for diagnosis.
+
+The verified publication Passport distinguishes the built candidate from the
+protected publication commit. Compose family source identity follows
+`source.builtSourceSha`; `source.builtSourceTreeSha` must equal the admitted
+invocation tree. Registry readback and qualification runs remain bound to the
+protected publication SHA. A tree-equivalent protected merge therefore retains
+the original image identity without accepting a different source tree.

package/package.json

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

package/packages/core/oci-compose-qualification.js

@@ -23,7 +23,10 @@ export function verifyComposePublication({
       root === v4ContentRoot("oci-publication-family", body) &&
       family.repository === repository &&
       family.version === version &&
-      family.sourceSha === documents.invocation.candidate.commit &&
+      family.sourceSha === documents.passport.source.builtSourceSha &&
+      documents.passport.source.builtSourceTreeSha ===
+        documents.invocation.candidate.tree &&
+      readback.sourceSha === documents.invocation.candidate.commit &&
       readback.familyRoot === root &&
       readback.version === version &&
       readback.candidateSourceSha === family.sourceSha &&

package/scripts/oci-compose-preview.mjs

@@ -25,6 +25,18 @@ function gh(args) {
 }
 const api = (route) => JSON.parse(gh(["api", route]));
 const read = (file) => JSON.parse(fs.readFileSync(file));
+export function createComposePreviewRegistry(environment, fetchImpl = fetch) {
+  const token = environment.BUILDCHAIN_REGISTRY_TOKEN;
+  const actor = environment.GITHUB_ACTOR;
+  check(
+    typeof token === "string" &&
+      token.length > 0 &&
+      typeof actor === "string" &&
+      actor.length > 0,
+    "explicit scoped registry identity required",
+  );
+  return createRegistryClient(token, fetchImpl, actor);
+}
 function output(name, value) {
   fs.appendFileSync(process.env.GITHUB_OUTPUT, `${name}=${value}\n`);
 }
@@ -69,7 +81,7 @@ export async function promoteComposePreview({
     });
     check(
       result.status === 201,
-      "preview write uncertain; retain the original qualification for readback",
+      `preview write uncertain (HTTP ${result.status}); retain the original qualification for readback`,
     );
   }
   const observed = await fetchManifest(policy.alias);
@@ -186,8 +198,7 @@ async function run(mode) {
       "qualification evidence bytes mismatch",
     );
   }
-  const actor = api("user").login;
-  const { registry } = createRegistryClient(process.env.GH_TOKEN, fetch, actor);
+  const { registry } = createComposePreviewRegistry(process.env);
   async function fetchManifest(ref, allowAbsent = false) {
     const response = await registry(context.application, `manifests/${ref}`, {
       headers: {

package/scripts/v3-v4-capability-catalog.mjs

@@ -85,7 +85,7 @@ export function ensureCapabilityCutAncestor({
   try {
     execFileSync(
       "git",
-      ["fetch", "--no-tags", "--depth=128", "origin", descendantCommit],
+      ["fetch", "--no-tags", "--depth=256", "origin", descendantCommit],
       { cwd: root, stdio: "ignore" },
     );
   } catch {