@kungfu-tech/buildchain 4.0.2-alpha.44 → 4.0.2-alpha.45

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

@@ -6,7 +6,7 @@
     "cliCommandCount": 117,
     "workflowCount": 114,
     "actionCount": 8,
-    "sitePageCount": 87,
+    "sitePageCount": 88,
     "docCommandRefCount": 1050,
     "failureCount": 0
   },
@@ -5518,6 +5518,10 @@
         "id": "manual:observed-evidence-patrol",
         "category": "manual"
       },
+      {
+        "id": "manual:oci-publication",
+        "category": "manual"
+      },
       {
         "id": "manual:ownership",
         "category": "manual"
@@ -10929,8 +10933,8 @@
     "workflowRegistryPath": "dist/site/workflow-registry.json",
     "pageRegistryPath": "dist/site/page-registry.json",
     "cliRegistryDigest": "fbc23073bbae240489a2f826b2c26daadc58e704050c5f8df366509f5c5a1c3e",
-    "workflowRegistryDigest": "6391219ad0dae43ff217202a74a7e3d45669799cd142d590e9f0bafecaeb9912",
-    "pageRegistryDigest": "de1ba89591aeb5f0e24f1c5e455c21e8477e1094ec616ffddc2c1163f02c53b9"
+    "workflowRegistryDigest": "e1bacd3ffb652ab8ef5c62986c4048d618e28ff43d4d03b61827adcce0e027be",
+    "pageRegistryDigest": "178bc7609c831a63cecdb5baa817672a53393bb7d40f43b25fc8a736d94e2e9d"
   },
   "comparison": {
     "missingCliRegistry": [],

package/dist/site/publication-authority-registry.json

@@ -1356,10 +1356,7 @@
     },
     {
       "path": ".github/workflows/.release-candidate-promote.yml",
-      "signals": [
-        "write-permission",
-        "oidc"
-      ],
+      "signals": [],
       "classified": true
     },
     {
@@ -1374,10 +1371,7 @@
     },
     {
       "path": ".github/workflows/.release-promote.yml",
-      "signals": [
-        "write-permission",
-        "oidc"
-      ],
+      "signals": [],
       "classified": true
     },
     {
@@ -1723,10 +1717,7 @@
     },
     {
       "path": ".github/workflows/public-release-promote.yml",
-      "signals": [
-        "write-permission",
-        "oidc"
-      ],
+      "signals": [],
       "classified": true
     },
     {
@@ -1768,10 +1759,7 @@
     },
     {
       "path": ".github/workflows/release-candidate-promote.yml",
-      "signals": [
-        "write-permission",
-        "oidc"
-      ],
+      "signals": [],
       "classified": true
     },
     {
@@ -2021,5 +2009,5 @@
       "classified": true
     }
   ],
-  "registryDigest": "894cce314366698d41a3ab20172a0b7a05f03f2167667eae51793537b832c811"
+  "registryDigest": "9c343ae9f9e778b608317d973b02cada327bd31e5149482d7f385b173c20ec14"
 }

package/dist/site/publication-registry.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-publication-release-registry",
-  "generatedAt": "2026-09-06T13:21:07.000Z",
-  "publishedAt": "2026-09-06T13:21:07.000Z",
+  "generatedAt": "2026-09-06T14:38:45.000Z",
+  "publishedAt": "2026-09-06T14:38:45.000Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "cf1b8e029ee3ef8b615cfc3c3814cfc8b7bf3c5c",
+  "sourceRevision": "7f41a21e534d41655d1c956bdc688e3167c2d340",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -32,7 +32,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "4.0.2-alpha.44",
+    "version": "4.0.2-alpha.45",
     "versionSource": "package.json#version"
   },
   "sourceKind": "package-site-bundle",

package/dist/site/release-provenance.json

@@ -120,7 +120,8 @@
       "./site/product-mechanism.json": "./dist/site/product-mechanism.json",
       "./site/release-provenance.json": "./dist/site/release-provenance.json",
       "./site/agent-index.json": "./dist/site/agent-index.json",
-      "./package.json": "./package.json"
+      "./package.json": "./package.json",
+      "./oci-publication": "./packages/core/oci-publication-bundle.js"
     }
   },
   "repository": "https://github.com/kungfu-systems/buildchain",

package/dist/site/site-manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-site-manifest",
-  "generatedAt": "2026-09-06T13:21:07.000Z",
-  "publishedAt": "2026-09-06T13:21:07.000Z",
+  "generatedAt": "2026-09-06T14:38:45.000Z",
+  "publishedAt": "2026-09-06T14:38:45.000Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "cf1b8e029ee3ef8b615cfc3c3814cfc8b7bf3c5c",
+  "sourceRevision": "7f41a21e534d41655d1c956bdc688e3167c2d340",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -37,7 +37,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "4.0.2-alpha.44",
+    "version": "4.0.2-alpha.45",
     "versionSource": "package.json#version"
   },
   "entrypoint": "buildchain-site.json",
@@ -53,7 +53,7 @@
       "path": "docs/MAP.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:aef677bb3e37882f73daf65b7052989fc549e3b40d70bc4036beb2738b608345"
+      "digest": "sha256:af7bee38e21a9ada99e1731f3576733f2897f9d19bdbf39eb2781650095ae419"
     },
     {
       "id": "getting-started",
@@ -253,7 +253,7 @@
       "path": "docs/node-api-reference.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:df073c14c12f15c851eb4507cbeb2919add936ac3079b10f222478138720d092"
+      "digest": "sha256:48232d47023b85063e7f779f053850e38149359ea3b2a5acd5126ff81f423ff4"
     },
     {
       "id": "build-facts",

package/dist/site/workflow-registry.json

@@ -2746,7 +2746,7 @@
       "status": "preview",
       "owner": "buildchain-workflows",
       "maturity": "preview",
-      "introducedVersion": "4.0.2-alpha.44",
+      "introducedVersion": "4.0.2-alpha.45",
       "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.44",
+      "introducedVersion": "4.0.2-alpha.45",
       "compatibilityPromise": "preserved-through-the-v3-major-line",
       "deprecationReplacement": "",
       "sunsetCondition": "explicit-breaking-change-review-in-a-future-major-line",
@@ -5970,7 +5970,7 @@
       "status": "preview",
       "owner": "buildchain-workflows",
       "maturity": "preview",
-      "introducedVersion": "4.0.2-alpha.44",
+      "introducedVersion": "4.0.2-alpha.45",
       "compatibilityPromise": "preserved-through-the-v3-major-line",
       "deprecationReplacement": "",
       "sunsetCondition": "explicit-breaking-change-review-in-a-future-major-line",
@@ -6001,7 +6001,7 @@
       "status": "preview",
       "owner": "buildchain-workflows",
       "maturity": "preview",
-      "introducedVersion": "4.0.2-alpha.44",
+      "introducedVersion": "4.0.2-alpha.45",
       "compatibilityPromise": "preserved-through-the-v3-major-line",
       "deprecationReplacement": "",
       "sunsetCondition": "explicit-breaking-change-review-in-a-future-major-line",
@@ -6032,7 +6032,7 @@
       "status": "preview",
       "owner": "buildchain-workflows",
       "maturity": "preview",
-      "introducedVersion": "4.0.2-alpha.44",
+      "introducedVersion": "4.0.2-alpha.45",
       "compatibilityPromise": "preserved-through-the-v3-major-line",
       "deprecationReplacement": "",
       "sunsetCondition": "explicit-breaking-change-review-in-a-future-major-line",

package/docs/MAP.md

@@ -38,6 +38,7 @@ running artifact), *use* (consume / extend) - and a **status**:
 | CLI operator or agent | [Generated CLI Reference](cli-reference.md) | [CLI guide](cli.md) for concepts and worked examples |
 | Node toolkit developer | [Generated Node API Reference](node-api-reference.md) | [Core package guide](../packages/core/README.md) for recipes |
 | Workflow contributor | [Workflow Catalog](workflow-catalog.md) | [Contribution rules](../CONTRIBUTING.md#workflow-organization) and the [exact registry](../architecture/workflow-taxonomy.json) |
+| Container image publisher | [OCI image family publication](oci-publication.md) | [Release Flow](release-flow.md) and [Runtime Train Validation](runtime-train-validation.md) |
 | Build/release operator | [Reusable Build Surface](reusable-build-surface.md) | [Release Flow](release-flow.md) and [Release Passport](release-passport.md) |
 | Product/trust reviewer | [Product Mechanism](product-mechanism.md) | [Release Passport](release-passport.md) and [KFD Support](kfd-support.md) |
 

package/docs/node-api-reference.md

@@ -2832,3 +2832,14 @@ Target: `./packages/core/buildchain-kfd-claims.js`. Public symbols: 10.
 | `createBuildchainKfdClaimRegistry` | function: function createBuildchainKfdClaimRegistry({ root = process.cwd(), sourceSha = "" } = {}) | { root = process.cwd(), sourceSha = "" } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { createBuildchainKfdClaimRegistry } from "@kungfu-tech/buildchain/buildchain-kfd-claims";` | `packages/core/buildchain-kfd-claims.js:510` |
 | `createBuildchainKfdSurfaceRegistry` | function: function createBuildchainKfdSurfaceRegistry({ root = process.cwd() } = {}) | { root = process.cwd() } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { createBuildchainKfdSurfaceRegistry } from "@kungfu-tech/buildchain/buildchain-kfd-claims";` | `packages/core/buildchain-kfd-claims.js:411` |
 | `createBuildchainPublicClaimDefinitions` | function: function createBuildchainPublicClaimDefinitions() | none | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { createBuildchainPublicClaimDefinitions } from "@kungfu-tech/buildchain/buildchain-kfd-claims";` | `packages/core/buildchain-kfd-claims.js:226` |
+
+## `@kungfu-tech/buildchain/oci-publication`
+
+Target: `./packages/core/oci-publication-bundle.js`. Public symbols: 4.
+
+| Symbol | Kind and signature | Parameters | Return | Errors | Side effects | Example | Source |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| `OCI_FAMILY_SCHEMA` | constant: const OCI_FAMILY_SCHEMA | none | value | Import does not declare a throw contract. | none-on-import | `import { OCI_FAMILY_SCHEMA } from "@kungfu-tech/buildchain/oci-publication";` | `packages/core/oci-publication-bundle.js:6` |
+| `ociBundleFile` | function: function ociBundleFile(root, relative) | root, relative | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { ociBundleFile } from "@kungfu-tech/buildchain/oci-publication";` | `packages/core/oci-publication-bundle.js:29` |
+| `sealOciPublicationBundle` | function: function sealOciPublicationBundle({ bundleRoot, body }) | { bundleRoot, body } | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { sealOciPublicationBundle } from "@kungfu-tech/buildchain/oci-publication";` | `packages/core/oci-publication-bundle.js:10` |
+| `verifyOciPublicationBundle` | function: function verifyOciPublicationBundle({ bundleRoot, manifest, repository, sourceSha, version, }) | { bundleRoot, manifest, repository, sourceSha, version, } | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { verifyOciPublicationBundle } from "@kungfu-tech/buildchain/oci-publication";` | `packages/core/oci-publication-bundle.js:114` |

package/docs/oci-publication.md

@@ -0,0 +1,82 @@
+---
+status: draft
+period: ongoing
+theme: oci-publication
+doc_type: technical-reference
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: B
+review_state: unreviewed
+last_reviewed: 2026-09-06
+ai_provenance:
+  model_family: GPT-6
+  product: Codex
+  generated_at: 2026-09-06
+  invisible_context_boundary: No credentials or production registry state inspected.
+---
+
+# OCI image family publication
+
+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
+provider verifies and uploads those bytes, reads back every public image digest,
+then allows release references and GitHub Release evidence to converge.
+
+## Candidate contract
+
+Publish exactly one `oci-family.json` alongside OCI layouts and smoke JSON files
+in the Build artifact. Import `sealOciPublicationBundle` from
+`@kungfu-tech/buildchain/oci-publication` to validate and seal the family. Its
+`body` contains:
+
+- `schema: kungfu-buildchain-oci-family/v1`, consumer `repository`, exact Git
+  `sourceSha`, and candidate package `version`.
+- `expectedImages`: the complete set of image names.
+- `images`: one entry for each expected image, with `name`, `repository`,
+  `digest`, `layout`, `platform`, `action`, `content`, and `smoke`.
+
+Destinations must be `ghcr.io/<consumer-owner>/<consumer-repo>/<image-name>`.
+`layout` is a relative OCI layout directory. Each image is a single Linux
+amd64 or arm64 manifest; OCI and Docker schema 2 manifests are supported.
+Layouts may share blobs and an index; each shared index entry identifies its
+image with the `org.opencontainers.image.ref.name` annotation.
+
+`content` records the image's original `sourceSha` and `version`, matching its
+OCI revision/version labels. For `action: built`, both equal the candidate.
+For `action: reused`, they retain the original content provenance while the
+family binds the current candidate. `smoke` records a relative `path` and SHA256
+`sha256`; its JSON must identify the image and record `passed: true`. The
+consumer owns the actual smoke command and must fail the build if it fails.
+
+Sealing verifies all config/layer sizes and digests, platform and provenance
+labels, smoke bytes, and family completeness. Absolute paths, traversal, and
+symlinks are rejected. The resolver derives the exact required image artifacts
+from this sealed family, including when recovering a previous candidate run.
+
+## Authority and publication
+
+The thin caller grants `packages: write` in addition to its existing promotion
+permissions. Reusable promotion wrappers inherit that caller envelope; npm
+consumers do not need to request package registry authority. The provider uses
+the action token only for GHCR, scoped to each declared consumer image.
+No consumer publish command is executed.
+
+The rooted product plan declares version-state materialization, OCI family
+publication, then release reference convergence. Each image uses the exact
+`v<version>` tag. A different existing digest aborts publication; a matching
+existing image is reused. After a partial failure, recovery validates the same
+candidate bytes and publishes only missing images. GHCR does not provide tag
+compare-and-swap: callers must serialize publishers for a version, and external
+writers must not race the publication workflow.
+
+Success requires anonymous readback of every declared image at its expected
+digest. Existing GHCR packages must permit the repository token to write and
+anonymous clients to pull. The provider does not change package visibility or
+access policy. It attaches `oci-publication-readback.json` to the GitHub Release;
+the caller should also include the family and smoke JSON files in
+`github-release-payload-patterns`.
+
+See [Runtime Train Validation](runtime-train-validation.md) for testing an
+unreleased runtime without persisting a train or exact SHA in the workflow.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "4.0.2-alpha.44",
+  "version": "4.0.2-alpha.45",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",
@@ -123,7 +123,8 @@
     "./site/product-mechanism.json": "./dist/site/product-mechanism.json",
     "./site/release-provenance.json": "./dist/site/release-provenance.json",
     "./site/agent-index.json": "./dist/site/agent-index.json",
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./oci-publication": "./packages/core/oci-publication-bundle.js"
   },
   "files": [
     "AGENTS.md",

package/packages/core/oci-publication-bundle.js

@@ -0,0 +1,241 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { v4ContentRoot } from "./v4-canonical-contracts.js";
+
+export const OCI_FAMILY_SCHEMA = "kungfu-buildchain-oci-family/v1";
+const digestPattern = /^sha256:[0-9a-f]{64}$/u;
+const namePattern = /^[a-z0-9]+(?:[._-][a-z0-9]+)*$/u;
+
+export function sealOciPublicationBundle({ bundleRoot, body }) {
+  const manifest = {
+    ...body,
+    root: v4ContentRoot("oci-publication-family", body),
+  };
+  verifyOciPublicationBundle({
+    bundleRoot,
+    manifest,
+    repository: body.repository,
+    sourceSha: body.sourceSha,
+    version: body.version,
+  });
+  return manifest;
+}
+
+function requireValue(condition, message) {
+  if (!condition) throw new Error(`OCI bundle: ${message}`);
+}
+
+export function ociBundleFile(root, relative) {
+  requireValue(
+    typeof relative === "string" &&
+      relative.length > 0 &&
+      !relative.includes("\\") &&
+      !path.isAbsolute(relative) &&
+      !relative.split(/[\\/]/u).some((p) => p === ".." || p === "." || !p),
+    "unsafe file path",
+  );
+  const base = fs.realpathSync(root);
+  let current = base;
+  for (const segment of relative.split("/")) {
+    current = path.join(current, segment);
+    requireValue(
+      !fs.lstatSync(current).isSymbolicLink(),
+      "symlinks are forbidden",
+    );
+  }
+  requireValue(
+    fs.statSync(current).isFile() &&
+      fs.realpathSync(current).startsWith(`${base}${path.sep}`),
+    "file escapes bundle",
+  );
+  return current;
+}
+
+function fileDigest(file) {
+  const hash = crypto.createHash("sha256"),
+    buffer = Buffer.alloc(1024 * 1024);
+  const fd = fs.openSync(file, "r");
+  try {
+    for (;;) {
+      const size = fs.readSync(fd, buffer);
+      if (!size) break;
+      hash.update(buffer.subarray(0, size));
+    }
+  } finally {
+    fs.closeSync(fd);
+  }
+  return `sha256:${hash.digest("hex")}`;
+}
+
+function verifyImageProvenance(image, config, sourceSha, version) {
+  const labels = config.config?.Labels || {};
+  requireValue(
+    image.content &&
+      /^[0-9a-f]{40}$/u.test(image.content.sourceSha) &&
+      typeof image.content.version === "string" &&
+      image.content.version.length > 0,
+    "missing image content provenance",
+  );
+  requireValue(
+    labels["org.opencontainers.image.revision"] === image.content.sourceSha &&
+      labels["org.opencontainers.image.version"] === image.content.version,
+    "image content provenance mismatch",
+  );
+  if (image.action === "built")
+    requireValue(
+      image.content.sourceSha === sourceSha &&
+        image.content.version === version,
+      "built image is not from the candidate source",
+    );
+  if (image.contractMajor !== undefined)
+    requireValue(
+      Number.isInteger(image.contractMajor) &&
+        image.contractMajor > 0 &&
+        labels["io.kungfu.image.contract-major"] ===
+          String(image.contractMajor),
+      "image contract major mismatch",
+    );
+  if (image.parentDigest)
+    requireValue(
+      digestPattern.test(image.parentDigest) &&
+        labels["io.kungfu.image.parent-digest"] === image.parentDigest,
+      "image parent digest mismatch",
+    );
+  if (image.content.materialSha)
+    requireValue(
+      /^[0-9a-f]{40}$/u.test(image.content.materialSha) &&
+        labels["io.kungfu.buildchain.release-material-sha"] ===
+          image.content.materialSha,
+      "image material provenance mismatch",
+    );
+}
+
+export function verifyOciPublicationBundle({
+  bundleRoot,
+  manifest,
+  repository,
+  sourceSha,
+  version,
+}) {
+  requireValue(
+    manifest?.schema === OCI_FAMILY_SCHEMA,
+    "unsupported manifest schema",
+  );
+  const { root, ...body } = manifest;
+  const computed = v4ContentRoot("oci-publication-family", body);
+  requireValue(root === computed, "manifest root mismatch");
+  requireValue(
+    manifest.repository === repository &&
+      manifest.sourceSha === sourceSha &&
+      manifest.version === version,
+    "candidate identity mismatch",
+  );
+  requireValue(
+    /^[a-z0-9-]+\/[a-z0-9._-]+$/u.test(repository),
+    "invalid repository",
+  );
+  requireValue(
+    Array.isArray(manifest.images) && manifest.images.length > 0,
+    "empty image family",
+  );
+  const expected = manifest.expectedImages;
+  requireValue(
+    Array.isArray(expected) &&
+      expected.length === new Set(expected).size &&
+      expected.every((n) => namePattern.test(n)),
+    "invalid expected image family",
+  );
+  const actual = manifest.images.map((i) => i.name).sort();
+  requireValue(
+    JSON.stringify(actual) === JSON.stringify([...expected].sort()),
+    "incomplete or duplicate image family",
+  );
+  const files = new Map();
+  for (const image of manifest.images) {
+    requireValue(
+      image.repository === `ghcr.io/${repository}/${image.name}`,
+      "destination must belong to the consumer repository",
+    );
+    requireValue(
+      digestPattern.test(image.digest) &&
+        ["built", "reused"].includes(image.action),
+      "invalid image identity",
+    );
+    requireValue(
+      /^linux\/(amd64|arm64)$/u.test(image.platform),
+      "unsupported image platform",
+    );
+    const prefix = image.layout;
+    const descriptorFile = (descriptor) => {
+      requireValue(
+        digestPattern.test(descriptor.digest) &&
+          Number.isSafeInteger(descriptor.size) &&
+          descriptor.size >= 0,
+        "invalid OCI descriptor",
+      );
+      const relative = `${prefix}/blobs/sha256/${descriptor.digest.slice(7)}`;
+      const file = ociBundleFile(bundleRoot, relative);
+      requireValue(
+        fs.statSync(file).size === descriptor.size,
+        "OCI blob size mismatch",
+      );
+      if (!files.has(file))
+        requireValue(
+          fileDigest(file) === descriptor.digest,
+          "OCI blob digest mismatch",
+        );
+      files.set(file, descriptor);
+      return file;
+    };
+    const layout = JSON.parse(
+      fs.readFileSync(ociBundleFile(bundleRoot, `${prefix}/oci-layout`)),
+    );
+    requireValue(
+      layout.imageLayoutVersion === "1.0.0",
+      "unsupported OCI layout",
+    );
+    const index = JSON.parse(
+      fs.readFileSync(ociBundleFile(bundleRoot, `${prefix}/index.json`)),
+    );
+    const selected = (index.manifests || []).filter(
+      (descriptor) =>
+        descriptor.digest === image.digest &&
+        (descriptor.annotations?.["org.opencontainers.image.ref.name"] ===
+          image.name ||
+          index.manifests.length === 1),
+    );
+    requireValue(
+      index.schemaVersion === 2 && selected.length === 1,
+      "OCI index must select one exact image manifest",
+    );
+    const document = JSON.parse(fs.readFileSync(descriptorFile(selected[0])));
+    requireValue(
+      document.schemaVersion === 2 &&
+        [
+          "application/vnd.oci.image.manifest.v1+json",
+          "application/vnd.docker.distribution.manifest.v2+json",
+        ].includes(document.mediaType) &&
+        Array.isArray(document.layers),
+      "unsupported OCI image manifest",
+    );
+    const config = JSON.parse(fs.readFileSync(descriptorFile(document.config)));
+    requireValue(
+      `${config.os}/${config.architecture}` === image.platform,
+      "OCI platform mismatch",
+    );
+    verifyImageProvenance(image, config, sourceSha, version);
+    for (const layer of document.layers) descriptorFile(layer);
+    const smokeFile = ociBundleFile(bundleRoot, image.smoke.path);
+    requireValue(
+      fileDigest(smokeFile) === image.smoke.sha256,
+      "smoke evidence digest mismatch",
+    );
+    const smoke = JSON.parse(fs.readFileSync(smokeFile));
+    requireValue(
+      smoke.passed === true && smoke.image === image.name,
+      "smoke qualification failed",
+    );
+  }
+  return { root: computed, manifest, bundleRoot: fs.realpathSync(bundleRoot) };
+}

package/packages/core/release-tail-product-capabilities.js

@@ -17,6 +17,15 @@ export const RELEASE_TAIL_PRODUCT_CAPABILITIES = Object.freeze([
     receiptKind: "product-package-publication",
     transactionState: "publishing",
   }),
+  Object.freeze({
+    id: "product.oci.publish",
+    executor: "provider-adapter",
+    adapter: "oci-image-family",
+    effectKind: "oci-family-publication",
+    observationKind: "oci-family-readback",
+    receiptKind: "oci-family-publication",
+    transactionState: "publishing",
+  }),
   Object.freeze({
     id: "product.release-refs.converge",
     executor: "provider-adapter",

package/packages/core/v4-canonical-contracts.js

@@ -58,6 +58,7 @@ const ROOT_DOMAINS = new Set([
   "partial-mutation-recovery-checkpoint",
   "partial-mutation-recovery-plan",
   "v4-product-required-artifacts",
+  "oci-publication-family",
   "v4-product-publication-intent",
   "v4-product-publication-operation",
   "v4-product-publication-plan",

package/packages/core/v4-domain-wasm-artifact.js

@@ -2,6 +2,6 @@
 export const V4_DOMAIN_WASM_ABI_VERSION = 1;
 export const V4_DOMAIN_WASM_RUSTC = "rustc 1.96.0 (ac68faa20 2026-05-25)";
 export const V4_DOMAIN_WASM_SOURCE_SHA256 =
-  "07d45b2767e22007d3d41fa32c8a2dba28d9c88c11a2b28863e82d54be3a2933";
+  "7297279bce5344b8fc58688be5c1933a823306c82dac7dccfabdf07de41d652f";
 export const V4_DOMAIN_WASM_SHA256 =
-  "b37c330e9366b7e9cf9dc4b7573b1e9495212dd9520e8b8ec6cdc3fd0ab7cafd";
+  "3a4909bb4b2bbd2676eac83f259c22faf1ce43479036992c5e53d5e2dcc512ce";

package/scripts/check-v4-release-topology.mjs

@@ -233,13 +233,21 @@ function workflowSnapshot(relative) {
     .map((job) => {
       const block = jobBlock(source, job.id);
       const uses = job.uses || null;
+      // A built-in publisher still requires mutation authority when the caller supplies its envelope.
+      const inheritedPublisher =
+        !/^    permissions:/mu.test(block) &&
+        /uses:.*actions\/v4-release-candidate-promote/u.test(block);
       return {
         id: job.id,
         kind: uses ? "reusable-call" : "runner",
         uses,
         permissions: {
-          contents: permission(block, "contents"),
-          idToken: permission(block, "id-token"),
+          contents:
+            permission(block, "contents") ||
+            (inheritedPublisher ? "inherited" : null),
+          idToken:
+            permission(block, "id-token") ||
+            (inheritedPublisher ? "inherited" : null),
         },
         carriers: {
           artifactDownload: /uses:\s+actions\/download-artifact@/u.test(block),
@@ -247,8 +255,10 @@ function workflowSnapshot(relative) {
           jobOutput: /GITHUB_OUTPUT/u.test(block),
         },
         mutationSignals: [
-          /contents:\s*write/u.test(block) && "contents-write",
-          /id-token:\s*write/u.test(block) && "oidc-write",
+          (/contents:\s*write/u.test(block) || inheritedPublisher) &&
+            "contents-write",
+          (/id-token:\s*write/u.test(block) || inheritedPublisher) &&
+            "oidc-write",
           /(?:promote-buildchain-ref|v4-release-candidate-promote)/u.test(
             block,
           ) && "promotion-runtime",