@kungfu-tech/buildchain 2.12.7-alpha.2 → 2.12.7-alpha.21

package/dist/site/publication-registry.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-publication-release-registry",
-  "generatedAt": "2026-07-14T16:40:36.563Z",
-  "publishedAt": "2026-07-14T16:40:36.563Z",
+  "generatedAt": "2026-07-15T12:26:57.218Z",
+  "publishedAt": "2026-07-15T12:26:57.218Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "31f70f81cbdd542d9473651cf13cd6e8eb33cd74",
+  "sourceRevision": "97973413b7ba208df42a3ead28d2b80067a3ecc8",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -32,7 +32,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "2.12.7-alpha.2",
+    "version": "2.12.7-alpha.21",
     "versionSource": "package.json#version"
   },
   "sourceKind": "package-site-bundle",

package/dist/site/site-manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-site-manifest",
-  "generatedAt": "2026-07-14T16:40:36.563Z",
-  "publishedAt": "2026-07-14T16:40:36.563Z",
+  "generatedAt": "2026-07-15T12:26:57.218Z",
+  "publishedAt": "2026-07-15T12:26:57.218Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "31f70f81cbdd542d9473651cf13cd6e8eb33cd74",
+  "sourceRevision": "97973413b7ba208df42a3ead28d2b80067a3ecc8",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -37,7 +37,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "2.12.7-alpha.2",
+    "version": "2.12.7-alpha.21",
     "versionSource": "package.json#version"
   },
   "entrypoint": "buildchain-site.json",
@@ -85,7 +85,7 @@
       "path": "docs/publication-authority.md",
       "plane": "verify",
       "exists": true,
-      "digest": "sha256:fc08e6657a1b586b6b8b5618ca4f49dfaa85955687f5bba8e2e69e7513fe6c71"
+      "digest": "sha256:05bc22c7e5885e591bc121fc43f588e5d49ccf0a8de6a642811c1d0d03dcee1e"
     },
     {
       "id": "release-candidate",
@@ -93,7 +93,7 @@
       "path": "docs/release-candidate.md",
       "plane": "verify",
       "exists": true,
-      "digest": "sha256:841d6f3281ba6dfe80527e4f149807bdbd05d41f9e94afe1c446fcd6d29e307c"
+      "digest": "sha256:6a20c6e3e483327d5ccbe70271f7fb4752731bd0523eeddb96f27b2b6ebf1cf8"
     },
     {
       "id": "release-propagation",

package/dist/site/workflow-registry.json

@@ -215,14 +215,19 @@
       "reusable": true,
       "inputs": [
         "admission-json",
+        "authority-workflow-path",
         "auto-admission",
+        "auto-admission-kind",
+        "auto-no-gate",
         "buildchain-ref",
         "buildchain-repository",
         "control-plane-audit-json",
         "dry-run",
+        "evidence-controller-artifact",
         "evidence-manifest-pattern",
         "evidence-passport-artifact",
         "evidence-payload-pattern",
+        "evidence-publication-artifact",
         "evidence-repository",
         "evidence-run-id",
         "evidence-summary-artifact",
@@ -231,13 +236,15 @@
         "package-name",
         "product",
         "publication-target",
+        "publication-version",
         "publisher-workflow-path",
+        "required-status-check",
         "runner-provenance-json",
         "source-sha",
         "target-ref",
         "used-nonces-json"
       ],
-      "inputCount": 22,
+      "inputCount": 29,
       "secrets": [],
       "secretCount": 0,
       "outputs": [
@@ -1024,6 +1031,54 @@
       "capabilityGroup": "api-cli-reference",
       "status": "active"
     },
+    {
+      "id": "paper-release-sealed",
+      "path": ".github/workflows/paper-release-sealed.yml",
+      "reusable": true,
+      "inputs": [
+        "artifact-name",
+        "artifact-paths",
+        "artifact-retention-days",
+        "branch-protection-bypass-apps",
+        "branch-protection-bypass-teams",
+        "branch-protection-bypass-users",
+        "buildchain-contract-lock-path",
+        "buildchain-ref",
+        "buildchain-repository",
+        "dry-run",
+        "github-release",
+        "github-release-notes",
+        "github-release-title",
+        "package-name",
+        "publish-dist-tag",
+        "publisher-workflow-path",
+        "release-passport-impact-json",
+        "release-passport-output-dir",
+        "release-passport-product-name",
+        "required-status-check",
+        "target-ref",
+        "target-sha",
+        "toolchain-type",
+        "verify-command",
+        "working-directory"
+      ],
+      "inputCount": 25,
+      "secrets": [
+        "BUILDCHAIN_PROMOTION_TOKEN"
+      ],
+      "secretCount": 1,
+      "outputs": [
+        "github-release-url",
+        "package-name",
+        "package-version",
+        "public-release-tag",
+        "release-passport-path"
+      ],
+      "outputCount": 5,
+      "surface": "repository-workflow",
+      "capabilityGroup": "api-cli-reference",
+      "status": "active"
+    },
     {
       "id": "paper-release",
       "path": ".github/workflows/paper-release.yml",
@@ -1193,7 +1248,11 @@
         "buildchain-ref",
         "buildchain-repository",
         "node-version",
+        "package-name",
+        "prepare-paper-package",
+        "publish-dist-tag",
         "setup-node",
+        "target-ref",
         "toolchain-command",
         "toolchain-digest",
         "toolchain-image",
@@ -1201,7 +1260,7 @@
         "verify-command",
         "working-directory"
       ],
-      "inputCount": 17,
+      "inputCount": 21,
       "secrets": [],
       "secretCount": 0,
       "outputs": [
@@ -1212,13 +1271,17 @@
         "controller-receipt-digest",
         "controller-receipt-json",
         "controller-receipt-status",
+        "package-name",
+        "package-version",
         "publication-artifact-name",
         "publication-manifest-json",
         "publication-manifest-path",
         "publication-passport-path",
-        "publication-registry-path"
+        "publication-registry-path",
+        "publish-dist-tag",
+        "runtime-sha"
       ],
-      "outputCount": 12,
+      "outputCount": 16,
       "surface": "repository-workflow",
       "capabilityGroup": "reusable-build",
       "status": "active"
@@ -1247,6 +1310,7 @@
         "package-manager",
         "publication-admission-json",
         "publication-auto-admission",
+        "publication-auto-no-gate",
         "publication-control-plane-audit-json",
         "publication-expected-json",
         "publication-gate-aggregate-json",
@@ -1284,16 +1348,17 @@
         "target-sha",
         "trusted-publishing"
       ],
-      "inputCount": 55,
+      "inputCount": 56,
       "secrets": [
         "BUILDCHAIN_ISSUE_APP_ID",
         "BUILDCHAIN_ISSUE_APP_PRIVATE_KEY",
         "BUILDCHAIN_ISSUE_TOKEN",
+        "BUILDCHAIN_PROMOTION_TOKEN",
         "buildchain-issue-app-id",
         "buildchain-issue-app-private-key",
         "buildchain-issue-token"
       ],
-      "secretCount": 6,
+      "secretCount": 7,
       "outputs": [
         "built-source-sha",
         "controller-plan-artifact",
@@ -1486,9 +1551,11 @@
         "branch-protection-bypass-teams",
         "branch-protection-bypass-users",
         "dry-run",
+        "expected-publication-version",
         "generated-ref-update-token",
         "generated-status-check-token",
         "github-release",
+        "github-release-artifact-paths",
         "github-release-notes",
         "github-release-title",
         "promote-only-release-candidate",
@@ -1534,7 +1601,7 @@
         "transaction-state-path",
         "verification-command"
       ],
-      "inputCount": 52,
+      "inputCount": 54,
       "capabilityGroup": "release-passport-trust",
       "status": "active"
     },

package/docs/publication-artifacts.md

@@ -182,40 +182,42 @@ on:
 
 jobs:
   paper-release:
-    uses: kungfu-systems/buildchain/.github/workflows/paper-release.yml@v2
+    uses: kungfu-systems/buildchain/.github/workflows/paper-release-sealed.yml@v2
     permissions:
+      actions: read
       checks: write
       contents: write
       id-token: write
       issues: write
     with:
       buildchain-ref: ${{ inputs.buildchain-ref || '' }}
-      publication-admission-json: ${{ needs.authority.outputs.admission-json }}
-      publication-runner-provenance-json: ${{ needs.authority.outputs.runner-provenance-json }}
-      publication-control-plane-audit-json: ${{ needs.authority.outputs.control-plane-audit-json }}
-      publication-expected-json: ${{ needs.authority.outputs.expected-json }}
+      publisher-workflow-path: .github/workflows/paper-release.yml
       toolchain-type: config
       verify-command: make check
+      artifact-paths: _build/paper-name.pdf
       buildchain-contract-lock-path: .buildchain/contract-lock.json
+    secrets:
+      BUILDCHAIN_PROMOTION_TOKEN: ${{ secrets.BUILDCHAIN_PROMOTION_TOKEN }}
 ```
 
-The publication job does not accept a long-lived promotion token. The caller
-must first produce a fresh sealed admission, runner provenance, external
-control-plane audit, and exact expected bindings. The credential-free verifier
-job checks those receipts; only then can the publication job use its short-lived
-`github.token` and caller-bound OIDC trusted publisher identity. npm binds that
-identity to the consumer workflow filename; an npm Environment restriction is
-optional and must be represented explicitly when configured. The workflow fails
-before the publication build when the target branch protection cannot be read.
+The sealed preset does not use a long-lived token for npm publication. It may
+accept an optional `BUILDCHAIN_PROMOTION_TOKEN` only for machine-generated
+version-state updates on protected channel branches; npm publication remains
+bound to GitHub OIDC trusted publishing. The preset builds and packages the
+paper in a read-only job, then a credential-free authority job downloads that
+exact candidate, audits the external control plane, and seals a capability over
+the source tree, Buildchain runtime, controller receipt, PDF, and npm package
+bytes. Only the final job receives write and OIDC permissions; it downloads the
+admitted candidate, recomputes the capability binding, and publishes without
+executing consumer build commands. npm binds the OIDC identity to the consumer
+workflow named by `publisher-workflow-path`.
 
 The preset:
 
-- resolves the same floating Buildchain runtime and contract lock as the build
-  workflow;
-- verifies that the declared promotion authority can read the protected target
-  channel before starting the publication build;
+- resolves the floating Buildchain runtime once and binds the exact SHA into the
+  publication candidate and authority capability;
 - builds the PDF through the declared pinned LaTeX Docker toolchain or custom
-  command;
+  command in a read-only job;
 - verifies the paper repository;
 - writes the publication manifest, publication passport, optional archive
   registry, and source bundle;
@@ -226,14 +228,22 @@ The preset:
 - creates a `publish-gate/<alpha|release>/.../<version>` source lock for the
   channel commit and requires `promote-buildchain-ref` to verify that lock
   before any publish side effect;
-- publishes the package through npm Trusted Publishing;
+- verifies the complete candidate again after authority and publishes the
+  package through npm Trusted Publishing without rebuilding it;
 - writes Buildchain release/passport evidence; and
-- creates or updates the exact-version GitHub Release by default.
+- creates or updates the exact-version GitHub Release by default, uploading
+  every file declared by `publication.primary_artifact` and
+  `publication.artifact_paths` alongside the release evidence.
 
 Consumers can opt out of the GitHub Release with `github-release: false`, but
 the default is on so downstream release propagation can observe
 `release.published` without hand-written `gh release` steps.
 
+Declared publication artifacts are resolved from the generated publication
+manifest rather than repeated in consumer workflow YAML. Publication fails
+before upload if a declared artifact is missing or if its basename would
+collide with another GitHub Release asset.
+
 For npm Trusted Publishing, register the consumer workflow file that calls this
 preset, for example `.github/workflows/paper-release.yml`, against the declared
 package in npm. The trusted publisher is the consumer repository and workflow

package/docs/publication-authority.md

@@ -8,11 +8,11 @@ confidence: high
 sensitivity: public
 evidence_grade: B
 review_state: unreviewed
-last_reviewed: 2026-07-14
+last_reviewed: 2026-07-15
 ai_provenance:
   model_family: GPT-5
   product: Codex
-  generated_at: 2026-07-14
+  generated_at: 2026-07-15
   limits: Live provider configuration must be re-audited; no credential values are represented.
 ---
 
@@ -109,17 +109,29 @@ artifacts. The denial explicitly records that npm Trusted Publishing and OIDC
 were not evaluated, so downstream diagnostics cannot misclassify an admission
 assembly failure as an npm authentication failure.
 
-Buildchain's own `workflow_run` promotion lane may assemble those inputs only
-for `kungfu-systems/buildchain`. It downloads the exact prior RC passport,
+An explicitly opted-in managed `workflow_run` promotion lane may assemble those
+inputs from evidence owned by its caller repository. It downloads the exact prior RC passport,
 summary, referenced controller receipt, manifests, and product payloads; proves
 the admitted channel commit has the same Git tree as the RC; performs the live
 read-only control-plane audit; records the GitHub-hosted job as ephemeral runner
-provenance; and creates an explicit Buildchain-owned no-Gate decision. The
+provenance; and consumes either a caller-supplied Gate aggregate or an explicit
+caller no-Gate decision. The
 independent verifier then recomputes every receipt and payload digest exactly as
-it does for externally supplied admission. The self-assembly mode rejects other
-repositories, unknown refs, non-exact source SHAs, and any caller other than
-`.github/workflows/buildchain-ref-promotion.yml`. Manual apply and external
-consumer workflows still require their own explicit admission inputs.
+it does for externally supplied admission. Automatic assembly keeps Buildchain
+as the canonical authority repository, requires evidence to belong to the
+caller, binds a repository-local publisher workflow, and rejects unknown refs,
+non-exact source SHAs, package/target mismatches, or an undeclared Gate policy.
+Manual apply and consumers that do not opt in still require their own explicit
+admission inputs.
+
+Before authority verification, the reusable promotion controller runs the same
+release transaction selector in read-only mode. That plan supplies one exact
+publication version and tag to the admission verifier, the publish-gate source
+lock, and the real promotion action. The verifier rejects a capability for a
+different version, and the promotion action rechecks the planned version before
+any publish transaction side effect. Release-candidate fixture versions are
+artifact evidence only; they never name Buildchain's own source-lock or
+publication capability.
 
 Evidence publication is a separate authority class and never grants product
 publication.

package/docs/release-candidate.md

@@ -116,3 +116,22 @@ KFD-1 source/artifact contract surfaces, audits KFD-2 public release claims, and
 compares KFD-3 declared shipped public surfaces with artifact-exposed public
 surfaces. The release passport records the results under `kfd-1`, `kfd-2`, and
 the KFD-provided `kfd-3` section.
+
+Managed consumers may also ask the promotion wrapper to assemble sealed
+publication evidence from the exact release candidate instead of producing
+short-lived admission JSON in repository-specific workflow code:
+
+```yaml
+      publication-auto-admission: true
+      publication-auto-no-gate: true
+      publication-publisher-workflow-path: .github/workflows/buildchain-ref-promotion.yml
+      publication-product: Example Product
+      publication-target: npm:@example/product
+      publication-package-name: "@example/product"
+```
+
+`publication-auto-no-gate` is an explicit consumer decision, not a default. A
+consumer with a Shifu Gate registry supplies `publication-gate-aggregate-json`
+instead. Buildchain still requires caller-owned RC evidence, an exact authority
+runtime and source SHA, a repository-local publisher workflow, matching npm
+target/package identity, and a qualifying control-plane audit.

package/docs/shifu-gate-profiles.md

@@ -78,6 +78,12 @@ Every matrix job checks out the exact source SHA planned by Buildchain, invokes
 then invokes `shifu gate receipt validate`. Buildchain uploads the original
 receipt and validation result even when the run fails.
 
+Before invoking the project-owned command, the workflow adds the runner
+account's `~/.local/bin` directory to `PATH` on Windows, Linux, and macOS. This
+keeps user-scoped tools such as `uv` available to strict Shifu cache profiles
+without assuming an administrator-managed system installation. The consumer or
+runner owner remains responsible for provisioning the declared tools.
+
 The fixed `Gate profile / aggregate` job fails closed for missing receipts,
 invalid or stale Shifu validation, dirty or mismatched source SHA, registry or
 plan drift, missing required results, required failures/skips, or gate action

package/package.json

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

package/packages/core/buildchain-publication-authority.js

@@ -27,6 +27,7 @@ const DESCRIPTORS = Object.freeze([
   [".github/workflows/buildchain-stable-candidate-patrol.yml", "governance-write"],
   [".github/workflows/dev-pr-auto-merge.yml", "governance-write"],
   [".github/workflows/npm-publish.yml", "dry-run-only"],
+  [".github/workflows/paper-release-sealed.yml", "product-publication", true, ["npm-publish", "github-release"], "trusted-publishing", "none", "fixed", "caller-bound"],
   [".github/workflows/paper-release.yml", "product-publication", true, ["npm-publish", "github-release"], "trusted-publishing", "none", "fixed", "caller-bound"],
   [".github/workflows/patrol-daily.yml", "governance-write"],
   [".github/workflows/patrol-monthly.yml", "governance-write"],

package/packages/core/controller-evidence.js

@@ -303,7 +303,7 @@ function normalizeEvidence(entries = []) {
 function receiptStatus(plan, stages) {
   if (stages.some((stage) => stage.status === "failed")) return "failed";
   if (stages.length > 0 && stages.every((stage) => stage.status === "skipped")) return "skipped";
-  if (stages.some((stage) => stage.status === "cancelled" || stage.status === "missing")) return "partial";
+  if (stages.some((stage) => stage.status === "cancelled" || (stage.required && stage.status === "missing"))) return "partial";
   const required = new Set(plan.expected.stages.filter((stage) => stage.required).map((stage) => stage.id));
   if (stages.filter((stage) => required.has(stage.id)).every((stage) => stage.status === "passed")) return "passed";
   return "partial";

package/packages/core/index.js

@@ -153,6 +153,13 @@ export {
   verifyPublicationAdmission,
 } from "./publication-authority.js";
 
+export {
+  PUBLICATION_ARTIFACT_CANDIDATE_CONTRACT,
+  createPublicationArtifactCandidate,
+  publicationArtifactCandidateDigest,
+  resolvePublicationCandidateFile,
+} from "./publication-artifact-candidate.js";
+
 export {
   buildchainPublicationAuthorityDescriptors,
   createBuildchainPublicationAuthorityRegistry,

package/packages/core/publication-artifact-candidate.js

@@ -0,0 +1,128 @@
+import crypto from "node:crypto";
+
+import { validateControllerReceipt } from "./controller-evidence.js";
+
+export const PUBLICATION_ARTIFACT_CANDIDATE_CONTRACT =
+  "kungfu-buildchain-publication-artifact-candidate";
+
+const MANIFEST_CONTRACT = "kungfu-buildchain-publication-artifact-manifest";
+const PASSPORT_CONTRACT = "kungfu-buildchain-publication-artifact-passport";
+
+function stableJson(value) {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+export function publicationArtifactCandidateDigest(value) {
+  return crypto.createHash("sha256").update(stableJson(value)).digest("hex");
+}
+
+export function resolvePublicationCandidateFile(files = [], candidatePath) {
+  const normalizedPath = requiredString(candidatePath, "candidatePath").replaceAll("\\", "/");
+  if (normalizedPath.startsWith("/") || normalizedPath.split("/").includes("..")) {
+    throw new Error(`publication artifact candidate contains an unsafe path: ${normalizedPath}`);
+  }
+  const matches = files.filter((entry) => entry.path === normalizedPath);
+  if (matches.length !== 1) {
+    throw new Error(`expected exactly one publication candidate file at ${normalizedPath}, found ${matches.length}`);
+  }
+  return matches[0].path;
+}
+
+function requiredString(value, label) {
+  const normalized = String(value || "").trim();
+  if (!normalized) throw new Error(`${label} must be a non-empty string`);
+  return normalized;
+}
+
+function normalizeDigest(value, label) {
+  const normalized = requiredString(value, label).replace(/^sha256:/, "").toLowerCase();
+  if (!/^[0-9a-f]{64}$/.test(normalized)) throw new Error(`${label} must be a sha256 digest`);
+  return normalized;
+}
+
+function normalizeGitSha(value, label) {
+  const normalized = requiredString(value, label).toLowerCase();
+  if (!/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(normalized)) {
+    throw new Error(`${label} must be a 40- or 64-character Git SHA`);
+  }
+  return normalized;
+}
+
+export function createPublicationArtifactCandidate({
+  repository,
+  sourceSha,
+  sourceTreeSha,
+  runtimeSha,
+  manifest,
+  passport,
+  controllerReceipt,
+  files = [],
+} = {}) {
+  const normalizedRepository = requiredString(repository, "repository");
+  const normalizedSourceSha = normalizeGitSha(sourceSha, "sourceSha");
+  const normalizedSourceTreeSha = normalizeGitSha(sourceTreeSha, "sourceTreeSha");
+  const normalizedRuntimeSha = normalizeGitSha(runtimeSha, "runtimeSha");
+  if (manifest?.contract !== MANIFEST_CONTRACT) throw new Error("publication artifact manifest contract mismatch");
+  if (passport?.contract !== PASSPORT_CONTRACT || passport.status !== "passed") {
+    throw new Error("publication artifact passport is not qualifying");
+  }
+  if (manifest.source?.sha !== normalizedSourceSha || passport.source?.sha !== normalizedSourceSha) {
+    throw new Error("publication artifact source SHA mismatch");
+  }
+  if (manifest.source?.treeSha !== normalizedSourceTreeSha || passport.source?.treeSha !== normalizedSourceTreeSha) {
+    throw new Error("publication artifact source tree mismatch");
+  }
+  const manifestDigest = crypto.createHash("sha256").update(JSON.stringify(manifest, null, 2)).digest("hex");
+  if (normalizeDigest(passport.manifestDigest, "passport.manifestDigest") !== manifestDigest) {
+    throw new Error("publication artifact passport manifest digest mismatch");
+  }
+  const controllerValidation = validateControllerReceipt(controllerReceipt, {
+    expectedSourceSha: normalizedSourceSha,
+    expectedRuntimeSha: normalizedRuntimeSha,
+  });
+  if (!controllerValidation.ok || !controllerValidation.qualifying) {
+    throw new Error(`publication artifact controller receipt did not qualify: ${controllerValidation.issues.join("; ")}`);
+  }
+  const evidenceKinds = new Set((controllerReceipt.evidence || []).map((entry) => entry.kind));
+  for (const kind of ["publication-manifest", "publication-passport"]) {
+    if (!evidenceKinds.has(kind)) throw new Error(`publication artifact controller receipt is missing ${kind} evidence`);
+  }
+  const normalizedFiles = files.map((entry, index) => {
+    const filePath = requiredString(entry.path, `files[${index}].path`).replaceAll("\\", "/");
+    if (filePath.startsWith("/") || filePath.split("/").includes("..")) {
+      throw new Error(`publication artifact candidate contains an unsafe path: ${filePath}`);
+    }
+    const size = Number(entry.size ?? entry.bytes);
+    if (!Number.isSafeInteger(size) || size < 0) throw new Error(`files[${index}].size must be a non-negative safe integer`);
+    return { path: filePath, size, sha256: normalizeDigest(entry.sha256, `files[${index}].sha256`) };
+  }).sort((left, right) => left.path.localeCompare(right.path));
+  if (new Set(normalizedFiles.map((entry) => entry.path)).size !== normalizedFiles.length) {
+    throw new Error("publication artifact candidate file paths must be unique");
+  }
+  const byPath = new Map(normalizedFiles.map((entry) => [entry.path, entry]));
+  for (const [index, artifact] of (manifest.artifacts || []).entries()) {
+    const artifactPath = requiredString(artifact.path, `manifest.artifacts[${index}].path`);
+    const actual = byPath.get(artifactPath);
+    if (!actual) throw new Error(`publication artifact candidate is missing declared artifact: ${artifactPath}`);
+    if (actual.size !== Number(artifact.bytes) || actual.sha256 !== normalizeDigest(artifact.sha256, `manifest.artifacts[${index}].sha256`)) {
+      throw new Error(`publication artifact candidate bytes do not match manifest: ${artifactPath}`);
+    }
+  }
+  const payload = {
+    schemaVersion: 1,
+    contract: PUBLICATION_ARTIFACT_CANDIDATE_CONTRACT,
+    repository: normalizedRepository,
+    sourceSha: normalizedSourceSha,
+    sourceTreeSha: normalizedSourceTreeSha,
+    runtimeSha: normalizedRuntimeSha,
+    manifestDigest,
+    passportDigest: publicationArtifactCandidateDigest(passport),
+    controllerReceiptDigest: normalizeDigest(controllerReceipt.digest, "controllerReceipt.digest"),
+    files: normalizedFiles,
+  };
+  return { ...payload, candidateDigest: publicationArtifactCandidateDigest(payload) };
+}