@kungfu-tech/buildchain 4.0.2-alpha.7 → 4.0.2-alpha.9

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

@@ -3308,6 +3308,7 @@
           "candidate-passport-path",
           "failure-after-capability",
           "mutation-token",
+          "product-publication-intent-path",
           "publication-qualification-path",
           "publish-auth",
           "publish-command",
@@ -3333,7 +3334,7 @@
           "target-sha",
           "token"
         ],
-        "inputCount": 29
+        "inputCount": 30
       },
       {
         "id": "validate-config",
@@ -8942,8 +8943,8 @@
     "workflowRegistryPath": "dist/site/workflow-registry.json",
     "pageRegistryPath": "dist/site/page-registry.json",
     "cliRegistryDigest": "fbc23073bbae240489a2f826b2c26daadc58e704050c5f8df366509f5c5a1c3e",
-    "workflowRegistryDigest": "8b9714376d8bf8b7d7e5db1545d63a0ba6a3e2b4322ccdebedfdb63cc9a646b4",
-    "pageRegistryDigest": "c81347e800ca7ded1b69a8480e562e67dc46671deb39ec27ca4376e7c8a77afd"
+    "workflowRegistryDigest": "1f0ea5e5d2cb7af7855f14f04177f3250ff93cdab84e57a1d72f411b686adf42",
+    "pageRegistryDigest": "225249f141d3242a46c66de72f005f119235b7e13b873594f1c503185d7a285e"
   },
   "comparison": {
     "missingCliRegistry": [],

package/dist/site/publication-registry.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-publication-release-registry",
-  "generatedAt": "2026-08-30T14:46:02.120Z",
-  "publishedAt": "2026-08-30T14:46:02.120Z",
+  "generatedAt": "2026-08-31T02:59:43.000Z",
+  "publishedAt": "2026-08-31T02:59:43.000Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "87aa58cb619ffcaf2b14e4ee4e35f8c3cbe87a7f",
+  "sourceRevision": "e113193be5efb13eb5a47f7f51f2d59989e4d969",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -32,7 +32,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "4.0.2-alpha.7",
+    "version": "4.0.2-alpha.9",
     "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-08-30T14:46:02.120Z",
-  "publishedAt": "2026-08-30T14:46:02.120Z",
+  "generatedAt": "2026-08-31T02:59:43.000Z",
+  "publishedAt": "2026-08-31T02:59:43.000Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "87aa58cb619ffcaf2b14e4ee4e35f8c3cbe87a7f",
+  "sourceRevision": "e113193be5efb13eb5a47f7f51f2d59989e4d969",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -37,7 +37,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "4.0.2-alpha.7",
+    "version": "4.0.2-alpha.9",
     "versionSource": "package.json#version"
   },
   "entrypoint": "buildchain-site.json",
@@ -253,7 +253,7 @@
       "path": "docs/node-api-reference.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:afc6f959491ea0360ee308ee476613a9b42ab37dc5755dc66d3edb484d5e81d3"
+      "digest": "sha256:1f50b0f7a45632b6e08b492687818ccbd3e0f00d7f189a21e1512e1a61df7df8"
     },
     {
       "id": "build-facts",

package/dist/site/workflow-registry.json

@@ -2041,7 +2041,7 @@
       "status": "preview",
       "owner": "buildchain-workflows",
       "maturity": "preview",
-      "introducedVersion": "4.0.2-alpha.7",
+      "introducedVersion": "4.0.2-alpha.9",
       "compatibilityPromise": "preserved-through-the-v3-major-line",
       "deprecationReplacement": "",
       "sunsetCondition": "explicit-breaking-change-review-in-a-future-major-line",
@@ -2062,7 +2062,7 @@
       "status": "preview",
       "owner": "buildchain-workflows",
       "maturity": "preview",
-      "introducedVersion": "4.0.2-alpha.7",
+      "introducedVersion": "4.0.2-alpha.9",
       "compatibilityPromise": "preserved-through-the-v3-major-line",
       "deprecationReplacement": "",
       "sunsetCondition": "explicit-breaking-change-review-in-a-future-major-line",
@@ -2083,7 +2083,7 @@
       "status": "preview",
       "owner": "buildchain-workflows",
       "maturity": "preview",
-      "introducedVersion": "4.0.2-alpha.7",
+      "introducedVersion": "4.0.2-alpha.9",
       "compatibilityPromise": "preserved-through-the-v3-major-line",
       "deprecationReplacement": "",
       "sunsetCondition": "explicit-breaking-change-review-in-a-future-major-line",
@@ -2133,7 +2133,7 @@
       "status": "preview",
       "owner": "buildchain-workflows",
       "maturity": "preview",
-      "introducedVersion": "4.0.2-alpha.7",
+      "introducedVersion": "4.0.2-alpha.9",
       "compatibilityPromise": "preserved-through-the-v3-major-line",
       "deprecationReplacement": "",
       "sunsetCondition": "explicit-breaking-change-review-in-a-future-major-line",
@@ -3537,6 +3537,7 @@
         "candidate-passport-path",
         "failure-after-capability",
         "mutation-token",
+        "product-publication-intent-path",
         "publication-qualification-path",
         "publish-auth",
         "publish-command",
@@ -3562,7 +3563,7 @@
         "target-sha",
         "token"
       ],
-      "inputCount": 29,
+      "inputCount": 30,
       "capabilityGroup": "api-cli-reference",
       "status": "active",
       "owner": "buildchain-actions",

package/docs/node-api-reference.md

@@ -510,7 +510,7 @@ Target: `./packages/core/index.js`. Public symbols: 636.
 | `RELEASE_PROPAGATION_STAGE_RECEIPT_CONTRACT` | constant: const RELEASE_PROPAGATION_STAGE_RECEIPT_CONTRACT | none | value | Import does not declare a throw contract. | none-on-import | `import { RELEASE_PROPAGATION_STAGE_RECEIPT_CONTRACT } from "@kungfu-tech/buildchain";` | `packages/core/release-propagation-work-constants.js:2` |
 | `RELEASE_PROPAGATION_WORK_CONTRACT` | constant: const RELEASE_PROPAGATION_WORK_CONTRACT | none | value | Import does not declare a throw contract. | none-on-import | `import { RELEASE_PROPAGATION_WORK_CONTRACT } from "@kungfu-tech/buildchain";` | `packages/core/release-propagation-work-constants.js:1` |
 | `RELEASE_PROPAGATION_WORK_STAGES` | constant: const RELEASE_PROPAGATION_WORK_STAGES | none | value | Import does not declare a throw contract. | none-on-import | `import { RELEASE_PROPAGATION_WORK_STAGES } from "@kungfu-tech/buildchain";` | `packages/core/release-propagation-work-constants.js:4` |
-| `RELEASE_TAIL_CAPABILITY_REGISTRY` | constant: const RELEASE_TAIL_CAPABILITY_REGISTRY | none | value | Import does not declare a throw contract. | none-on-import | `import { RELEASE_TAIL_CAPABILITY_REGISTRY } from "@kungfu-tech/buildchain";` | `packages/core/release-tail-provider-plane.js:31` |
+| `RELEASE_TAIL_CAPABILITY_REGISTRY` | constant: const RELEASE_TAIL_CAPABILITY_REGISTRY | none | value | Import does not declare a throw contract. | none-on-import | `import { RELEASE_TAIL_CAPABILITY_REGISTRY } from "@kungfu-tech/buildchain";` | `packages/core/release-tail-provider-plane.js:30` |
 | `RELEASE_TAIL_COMPATIBILITY_CONTRACT` | constant: const RELEASE_TAIL_COMPATIBILITY_CONTRACT | none | value | Import does not declare a throw contract. | none-on-import | `import { RELEASE_TAIL_COMPATIBILITY_CONTRACT } from "@kungfu-tech/buildchain";` | `packages/core/release-tail-compatibility.js:1` |
 | `RELEASE_TAIL_DECLARATION_CONTRACT` | constant: const RELEASE_TAIL_DECLARATION_CONTRACT | none | value | Import does not declare a throw contract. | none-on-import | `import { RELEASE_TAIL_DECLARATION_CONTRACT } from "@kungfu-tech/buildchain";` | `packages/core/release-tail-provider-plane.js:5` |
 | `RELEASE_TAIL_EFFECT_SCHEMA` | constant: const RELEASE_TAIL_EFFECT_SCHEMA | none | value | Import does not declare a throw contract. | none-on-import | `import { RELEASE_TAIL_EFFECT_SCHEMA } from "@kungfu-tech/buildchain";` | `packages/core/release-tail-provider-plane.js:10` |
@@ -1199,7 +1199,7 @@ Target: `./packages/core/index.js`. Public symbols: 636.
 | `RELEASE_PROPAGATION_STAGE_RECEIPT_CONTRACT` | constant: const RELEASE_PROPAGATION_STAGE_RECEIPT_CONTRACT | none | value | Import does not declare a throw contract. | none-on-import | `import { RELEASE_PROPAGATION_STAGE_RECEIPT_CONTRACT } from "@kungfu-tech/buildchain/core";` | `packages/core/release-propagation-work-constants.js:2` |
 | `RELEASE_PROPAGATION_WORK_CONTRACT` | constant: const RELEASE_PROPAGATION_WORK_CONTRACT | none | value | Import does not declare a throw contract. | none-on-import | `import { RELEASE_PROPAGATION_WORK_CONTRACT } from "@kungfu-tech/buildchain/core";` | `packages/core/release-propagation-work-constants.js:1` |
 | `RELEASE_PROPAGATION_WORK_STAGES` | constant: const RELEASE_PROPAGATION_WORK_STAGES | none | value | Import does not declare a throw contract. | none-on-import | `import { RELEASE_PROPAGATION_WORK_STAGES } from "@kungfu-tech/buildchain/core";` | `packages/core/release-propagation-work-constants.js:4` |
-| `RELEASE_TAIL_CAPABILITY_REGISTRY` | constant: const RELEASE_TAIL_CAPABILITY_REGISTRY | none | value | Import does not declare a throw contract. | none-on-import | `import { RELEASE_TAIL_CAPABILITY_REGISTRY } from "@kungfu-tech/buildchain/core";` | `packages/core/release-tail-provider-plane.js:31` |
+| `RELEASE_TAIL_CAPABILITY_REGISTRY` | constant: const RELEASE_TAIL_CAPABILITY_REGISTRY | none | value | Import does not declare a throw contract. | none-on-import | `import { RELEASE_TAIL_CAPABILITY_REGISTRY } from "@kungfu-tech/buildchain/core";` | `packages/core/release-tail-provider-plane.js:30` |
 | `RELEASE_TAIL_COMPATIBILITY_CONTRACT` | constant: const RELEASE_TAIL_COMPATIBILITY_CONTRACT | none | value | Import does not declare a throw contract. | none-on-import | `import { RELEASE_TAIL_COMPATIBILITY_CONTRACT } from "@kungfu-tech/buildchain/core";` | `packages/core/release-tail-compatibility.js:1` |
 | `RELEASE_TAIL_DECLARATION_CONTRACT` | constant: const RELEASE_TAIL_DECLARATION_CONTRACT | none | value | Import does not declare a throw contract. | none-on-import | `import { RELEASE_TAIL_DECLARATION_CONTRACT } from "@kungfu-tech/buildchain/core";` | `packages/core/release-tail-provider-plane.js:5` |
 | `RELEASE_TAIL_EFFECT_SCHEMA` | constant: const RELEASE_TAIL_EFFECT_SCHEMA | none | value | Import does not declare a throw contract. | none-on-import | `import { RELEASE_TAIL_EFFECT_SCHEMA } from "@kungfu-tech/buildchain/core";` | `packages/core/release-tail-provider-plane.js:10` |
@@ -2767,7 +2767,7 @@ Target: `./packages/core/release-tail-provider-plane.js`. Public symbols: 20.
 | `executeReleaseTailTransaction` | function: async function executeReleaseTailTransaction(transaction, { adapters, checkpoint: checkpointCallback } = {}) | transaction, { adapters, checkpoint: checkpointCallback } = {} | Promise<unknown> | May throw an Error on rejected input or failed operations; follow the linked source contract. | may-write-or-invoke-external-actions | `import { executeReleaseTailTransaction } from "@kungfu-tech/buildchain/release-tail-provider-plane";` | `packages/core/release-tail-provider-plane.js:1016` |
 | `parseReleaseTailDeclaration` | function: function parseReleaseTailDeclaration(input) | input | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { parseReleaseTailDeclaration } from "@kungfu-tech/buildchain/release-tail-provider-plane";` | `packages/core/release-tail-provider-plane.js:491` |
 | `readReleaseTailTransaction` | function: function readReleaseTailTransaction(filePath) | filePath | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { readReleaseTailTransaction } from "@kungfu-tech/buildchain/release-tail-provider-plane";` | `packages/core/release-tail-provider-plane.js:830` |
-| `RELEASE_TAIL_CAPABILITY_REGISTRY` | constant: const RELEASE_TAIL_CAPABILITY_REGISTRY | none | value | Import does not declare a throw contract. | none-on-import | `import { RELEASE_TAIL_CAPABILITY_REGISTRY } from "@kungfu-tech/buildchain/release-tail-provider-plane";` | `packages/core/release-tail-provider-plane.js:31` |
+| `RELEASE_TAIL_CAPABILITY_REGISTRY` | constant: const RELEASE_TAIL_CAPABILITY_REGISTRY | none | value | Import does not declare a throw contract. | none-on-import | `import { RELEASE_TAIL_CAPABILITY_REGISTRY } from "@kungfu-tech/buildchain/release-tail-provider-plane";` | `packages/core/release-tail-provider-plane.js:30` |
 | `RELEASE_TAIL_DECLARATION_CONTRACT` | constant: const RELEASE_TAIL_DECLARATION_CONTRACT | none | value | Import does not declare a throw contract. | none-on-import | `import { RELEASE_TAIL_DECLARATION_CONTRACT } from "@kungfu-tech/buildchain/release-tail-provider-plane";` | `packages/core/release-tail-provider-plane.js:5` |
 | `RELEASE_TAIL_EFFECT_SCHEMA` | constant: const RELEASE_TAIL_EFFECT_SCHEMA | none | value | Import does not declare a throw contract. | none-on-import | `import { RELEASE_TAIL_EFFECT_SCHEMA } from "@kungfu-tech/buildchain/release-tail-provider-plane";` | `packages/core/release-tail-provider-plane.js:10` |
 | `RELEASE_TAIL_OBSERVATION_SCHEMA` | constant: const RELEASE_TAIL_OBSERVATION_SCHEMA | none | value | Import does not declare a throw contract. | none-on-import | `import { RELEASE_TAIL_OBSERVATION_SCHEMA } from "@kungfu-tech/buildchain/release-tail-provider-plane";` | `packages/core/release-tail-provider-plane.js:12` |

package/package.json

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

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

@@ -0,0 +1,29 @@
+export const RELEASE_TAIL_PRODUCT_CAPABILITIES = Object.freeze([
+  Object.freeze({
+    id: "product.version-state.materialize",
+    executor: "provider-adapter",
+    adapter: "github-version-state",
+    effectKind: "product-version-state-materialization",
+    observationKind: "product-version-state-readback",
+    receiptKind: "product-version-state",
+    transactionState: "preparing",
+  }),
+  Object.freeze({
+    id: "product.package.publish",
+    executor: "provider-adapter",
+    adapter: "npm-trusted-publishing",
+    effectKind: "product-package-publication",
+    observationKind: "product-package-readback",
+    receiptKind: "product-package-publication",
+    transactionState: "publishing",
+  }),
+  Object.freeze({
+    id: "product.release-refs.converge",
+    executor: "provider-adapter",
+    adapter: "github-release-refs",
+    effectKind: "product-release-ref-convergence",
+    observationKind: "product-release-ref-readback",
+    receiptKind: "product-release-ref-convergence",
+    transactionState: "committing",
+  }),
+]);

package/packages/core/release-tail-provider-plane.js

@@ -1,7 +1,7 @@
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
-
+import { RELEASE_TAIL_PRODUCT_CAPABILITIES } from "./release-tail-product-capabilities.js";
 export const RELEASE_TAIL_DECLARATION_CONTRACT =
   "kungfu-buildchain-release-tail-capabilities";
 export const RELEASE_TAIL_TRANSACTION_POLICY = "buildchain.release-tail/v1";
@@ -27,8 +27,8 @@ export const RELEASE_TAIL_STATES = Object.freeze([
   "repair-required",
   "terminal-failure",
 ]);
-
 export const RELEASE_TAIL_CAPABILITY_REGISTRY = Object.freeze([
+  ...RELEASE_TAIL_PRODUCT_CAPABILITIES,
   Object.freeze({
     id: "artifact.publish",
     executor: "provider-adapter",

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

@@ -56,6 +56,10 @@ const ROOT_DOMAINS = new Set([
   "stable-publication-fence",
   "partial-mutation-recovery-checkpoint",
   "partial-mutation-recovery-plan",
+  "v4-product-required-artifacts",
+  "v4-product-publication-intent",
+  "v4-product-publication-operation",
+  "v4-product-publication-plan",
   "tail-reseal-plan",
   "tail-reseal-admission",
   "tail-reseal-artifact-files",

package/packages/core/v4-product-publication.js

@@ -0,0 +1,387 @@
+import { v4ContentRoot, validateV4Root } from "./v4-canonical-contracts.js";
+import {
+  RELEASE_TAIL_DECLARATION_CONTRACT,
+  RELEASE_TAIL_EFFECT_SCHEMA,
+  RELEASE_TAIL_OBSERVATION_SCHEMA,
+  RELEASE_TAIL_RECEIPT_SCHEMA,
+  RELEASE_TAIL_TRANSACTION_POLICY,
+} from "./release-tail-provider-plane.js";
+import { RELEASE_TAIL_PRODUCT_CAPABILITIES } from "./release-tail-product-capabilities.js";
+
+export const V4_PRODUCT_PUBLICATION_INTENT_CONTRACT =
+  "kungfu-buildchain-v4-product-publication-intent/v1";
+export const V4_PRODUCT_PUBLICATION_PLAN_CONTRACT =
+  "kungfu-buildchain-v4-product-publication-plan/v1";
+
+const VERSION = /^(\d+)\.(\d+)\.(\d+)(?:-alpha\.(\d+))?$/u;
+const SHA = /^[0-9a-f]{40}$/u;
+const ROOT = /^sha256:[0-9a-f]{64}$/u;
+const REPOSITORY = /^[^/\s]+\/[^/\s]+$/u;
+
+function fail(message) {
+  throw new Error(`invalid v4 product publication: ${message}`);
+}
+
+function parseVersion(value, label) {
+  const normalized = String(value || "").trim();
+  const match = normalized.match(VERSION);
+  if (!match) fail(`${label} must be an exact stable or alpha version`);
+  return {
+    value: normalized,
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    alpha: match[4] === undefined ? null : Number(match[4]),
+  };
+}
+
+function channelName(value) {
+  if (value === "alpha") return "alpha";
+  if (["release", "stable", "major"].includes(value)) return "stable";
+  fail(`unsupported channel '${value}'`);
+}
+
+function assertLane({ channel, targetRef, version }) {
+  const expression =
+    channel === "alpha"
+      ? /^alpha\/v(\d+)\/v(\d+)\.(\d+)$/u
+      : /^release\/v(\d+)\/v(\d+)\.(\d+)$/u;
+  const match = String(targetRef || "").match(expression);
+  if (!match) fail(`target ref '${targetRef}' is not a ${channel} lane`);
+  if (
+    Number(match[1]) !== version.major ||
+    Number(match[2]) !== version.major ||
+    Number(match[3]) !== version.minor
+  )
+    fail("target ref does not match the publication version line");
+}
+
+function observedAlphaNumber(version, expected) {
+  const parsed = parseVersion(version, "observed version");
+  return parsed.major === expected.major &&
+    parsed.minor === expected.minor &&
+    parsed.patch === expected.patch
+    ? parsed.alpha
+    : null;
+}
+
+function requiredString(value, label) {
+  const normalized = String(value || "").trim();
+  if (!normalized) fail(`${label} must be a non-empty string`);
+  return normalized;
+}
+
+function requiredRoot(value, label) {
+  const normalized = requiredString(value, label).toLowerCase();
+  if (!ROOT.test(normalized)) fail(`${label} must be a sha256 content root`);
+  return normalized;
+}
+
+export function selectV4ProductPublicationIntent({
+  channel,
+  targetRef,
+  sourceSha,
+  sourceTimestamp,
+  repository,
+  packageName,
+  distTag,
+  sealedBundleRoot,
+  requiredArtifactsRoot,
+  candidateVersion,
+  recoveredVersion = "",
+  observedVersions = [],
+}) {
+  const normalizedChannel = channelName(channel);
+  if (!SHA.test(String(sourceSha || "")))
+    fail("sourceSha must be an exact Git SHA");
+  if (!REPOSITORY.test(String(repository || "")))
+    fail("repository must be owner/repo");
+  const normalizedTimestamp = requiredString(
+    sourceTimestamp,
+    "sourceTimestamp",
+  );
+  if (Number.isNaN(Date.parse(normalizedTimestamp)))
+    fail("sourceTimestamp must be an ISO timestamp");
+  const normalizedPackageName = requiredString(packageName, "packageName");
+  const normalizedDistTag = requiredString(distTag, "distTag");
+  if (!/^[a-z0-9][a-z0-9._-]*$/u.test(normalizedDistTag))
+    fail("distTag must be an npm dist-tag");
+  if (!Array.isArray(observedVersions))
+    fail("observedVersions must be an array");
+  const candidate = parseVersion(candidateVersion, "candidateVersion");
+  assertLane({ channel: normalizedChannel, targetRef, version: candidate });
+  const observed = [...new Set(observedVersions.map(String))].sort();
+  let version;
+  let mode = "fresh";
+  if (String(recoveredVersion || "").trim()) {
+    const recovered = parseVersion(recoveredVersion, "recoveredVersion");
+    if (
+      recovered.major !== candidate.major ||
+      recovered.minor !== candidate.minor ||
+      recovered.patch !== candidate.patch ||
+      (normalizedChannel === "alpha" && recovered.alpha === null) ||
+      (normalizedChannel === "stable" && recovered.alpha !== null)
+    )
+      fail("recoveredVersion is incompatible with the candidate release line");
+    version = recovered.value;
+    mode = "resume";
+  } else if (normalizedChannel === "alpha") {
+    if (candidate.alpha === null)
+      fail("fresh alpha publication requires an alpha candidate version");
+    const highest = observed.reduce(
+      (current, entry) =>
+        Math.max(current, observedAlphaNumber(entry, candidate) ?? -1),
+      candidate.alpha,
+    );
+    version = `${candidate.major}.${candidate.minor}.${candidate.patch}-alpha.${highest + 1}`;
+  } else {
+    version = `${candidate.major}.${candidate.minor}.${candidate.patch}`;
+  }
+  const intent = {
+    schema: V4_PRODUCT_PUBLICATION_INTENT_CONTRACT,
+    mode,
+    channel: normalizedChannel,
+    targetRef,
+    sourceSha,
+    sourceTimestamp: new Date(normalizedTimestamp).toISOString(),
+    repository,
+    packageName: normalizedPackageName,
+    distTag: normalizedDistTag,
+    sealedBundleRoot: requiredRoot(sealedBundleRoot, "sealedBundleRoot"),
+    requiredArtifactsRoot: requiredRoot(
+      requiredArtifactsRoot,
+      "requiredArtifactsRoot",
+    ),
+    candidateVersion: candidate.value,
+    version,
+    exactTag: `v${version}`,
+    observedVersions: observed,
+  };
+  return {
+    ...intent,
+    intentRoot: v4ContentRoot("v4-product-publication-intent", intent),
+  };
+}
+
+function alphaReferences(intent, version) {
+  const line = `v${version.major}.${version.minor}`;
+  return [
+    { ref: `refs/tags/${intent.exactTag}`, target: "source" },
+    { ref: `refs/heads/${intent.targetRef}`, target: "version-state" },
+    {
+      ref: `refs/heads/dev/v${version.major}/${line}`,
+      target: "version-state",
+    },
+    { ref: `refs/tags/${line}-alpha`, target: "version-state" },
+    { ref: `refs/tags/v${version.major}-alpha`, target: "version-state" },
+  ];
+}
+
+function stableReferences(intent, version) {
+  return [
+    { ref: `refs/tags/${intent.exactTag}`, target: "source" },
+    { ref: `refs/heads/${intent.targetRef}`, target: "version-state" },
+    {
+      ref: `refs/tags/v${version.major}.${version.minor}`,
+      target: "version-state",
+    },
+    { ref: `refs/tags/v${version.major}`, target: "version-state" },
+  ];
+}
+
+export function createV4ProductPublicationPlan({
+  intent,
+  invocationRoot,
+  transactionRoot,
+}) {
+  validateV4Root(invocationRoot, "$/productPlan/invocationRoot");
+  validateV4Root(transactionRoot, "$/productPlan/transactionRoot");
+  const selected = selectV4ProductPublicationIntent({
+    channel: intent.channel,
+    targetRef: intent.targetRef,
+    sourceSha: intent.sourceSha,
+    sourceTimestamp: intent.sourceTimestamp,
+    repository: intent.repository,
+    packageName: intent.packageName,
+    distTag: intent.distTag,
+    sealedBundleRoot: intent.sealedBundleRoot,
+    requiredArtifactsRoot: intent.requiredArtifactsRoot,
+    candidateVersion: intent.candidateVersion,
+    recoveredVersion: intent.mode === "resume" ? intent.version : "",
+    observedVersions: intent.observedVersions,
+  });
+  if (selected.intentRoot !== intent.intentRoot)
+    fail("intentRoot does not match the canonical publication intent");
+  const parsed = parseVersion(intent.version, "intent.version");
+  const references =
+    intent.channel === "alpha"
+      ? alphaReferences(intent, parsed)
+      : stableReferences(intent, parsed);
+  const stateRef = `refs/heads/buildchain/v4-product-state/${intent.sourceSha}-${intent.version.replaceAll(".", "-")}`;
+  const operations = [
+    {
+      id: "product.version-state.materialize",
+      adapter: "github-version-state",
+      authority: "contents-write",
+      target: {
+        repository: intent.repository,
+        version: intent.version,
+        sourceSha: intent.sourceSha,
+        sourceTimestamp: intent.sourceTimestamp,
+        stateRef,
+      },
+    },
+    {
+      id: "product.package.publish",
+      adapter: "npm-trusted-publishing",
+      authority: "oidc-provider-mutation",
+      target: {
+        packageName: intent.packageName,
+        version: intent.version,
+        distTag: intent.distTag,
+        sealedBundleRoot: intent.sealedBundleRoot,
+        requiredArtifactsRoot: intent.requiredArtifactsRoot,
+      },
+    },
+    {
+      id: "product.release-refs.converge",
+      adapter: "github-release-refs",
+      authority: "contents-write",
+      target: {
+        repository: intent.repository,
+        sourceSha: intent.sourceSha,
+        stateRef,
+        references,
+      },
+    },
+  ].map((operation) => ({
+    ...operation,
+    operationRoot: v4ContentRoot("v4-product-publication-operation", operation),
+  }));
+  const plan = {
+    schema: V4_PRODUCT_PUBLICATION_PLAN_CONTRACT,
+    intentRoot: intent.intentRoot,
+    invocationRoot,
+    transactionRoot,
+    operationOrder: operations.map(({ id }) => id),
+    operations,
+  };
+  return {
+    ...plan,
+    planRoot: v4ContentRoot("v4-product-publication-plan", plan),
+  };
+}
+
+const PRODUCT_CAPABILITIES = Object.fromEntries(
+  RELEASE_TAIL_PRODUCT_CAPABILITIES.map((capability) => [
+    capability.id,
+    {
+      ...capability,
+      destinationKind:
+        capability.id === "product.package.publish"
+          ? "npm-package"
+          : capability.adapter,
+    },
+  ]),
+);
+
+function exactTagPattern(tag) {
+  return `^${tag.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&")}$`;
+}
+
+export function createV4ProductPublicationDeclaration({ intent, plan }) {
+  const rebuilt = createV4ProductPublicationPlan({
+    intent,
+    invocationRoot: plan.invocationRoot,
+    transactionRoot: plan.transactionRoot,
+  });
+  if (rebuilt.planRoot !== plan.planRoot)
+    fail("planRoot does not match the canonical publication plan");
+  const operationById = new Map(
+    plan.operations.map((operation) => [operation.id, operation]),
+  );
+  return {
+    contract: RELEASE_TAIL_DECLARATION_CONTRACT,
+    schemaVersion: 1,
+    transactionPolicy: RELEASE_TAIL_TRANSACTION_POLICY,
+    subject: {
+      repository: intent.repository,
+      sourceSha: intent.sourceSha,
+      version: intent.version,
+      tag: intent.exactTag,
+      channel: intent.channel,
+    },
+    capabilities: plan.operationOrder.map((id) => {
+      const operation = operationById.get(id);
+      const descriptor = PRODUCT_CAPABILITIES[id];
+      if (!operation || !descriptor)
+        fail(`unsupported product publication operation '${id}'`);
+      return {
+        id,
+        executor: "provider-adapter",
+        adapter: operation.adapter,
+        artifactRoles: [
+          { role: "publication-intent", root: intent.intentRoot },
+          ...(id === "product.package.publish"
+            ? [
+                { role: "sealed-bundle", root: intent.sealedBundleRoot },
+                {
+                  role: "required-artifacts",
+                  root: intent.requiredArtifactsRoot,
+                },
+              ]
+            : []),
+        ],
+        destination: {
+          kind: descriptor.destinationKind,
+          locator: `${operation.adapter}:${operation.operationRoot}`,
+        },
+        channelPolicy: {
+          channel: intent.channel,
+          tagPattern: exactTagPattern(intent.exactTag),
+          authorityMove:
+            id === "product.package.publish" ? "none" : "verified-ref",
+        },
+        activationPolicy: { mode: "none", environment: "none" },
+        readbackPredicates: [
+          {
+            id: `${id}.target-root`,
+            kind: "exact-root",
+            expected: operation.operationRoot,
+          },
+        ],
+        effect: {
+          schema: RELEASE_TAIL_EFFECT_SCHEMA,
+          kind: descriptor.effectKind,
+        },
+        observation: {
+          schema: RELEASE_TAIL_OBSERVATION_SCHEMA,
+          kind: descriptor.observationKind,
+        },
+        receipt: {
+          schema: RELEASE_TAIL_RECEIPT_SCHEMA,
+          kind: descriptor.receiptKind,
+        },
+        operationIdentity: {
+          transactionRoot: plan.transactionRoot,
+          capabilityId: id,
+          subjectRoot: intent.intentRoot,
+          targetRoot: operation.operationRoot,
+          attemptKey: `${plan.planRoot}:${id}`,
+        },
+        idempotency: {
+          scope: "subject-target",
+          duplicate: "readback-before-retry",
+        },
+        retry: {
+          class: "provider-transient",
+          localAttempts: 1,
+          exhausted: "blocked",
+        },
+        evidenceRequirements: [
+          "provider readback must match the rooted publication operation",
+        ],
+      };
+    }),
+  };
+}