@kungfu-tech/buildchain 2.12.6 → 2.12.7-alpha.10

package/docs/publication-authority.md

@@ -0,0 +1,213 @@
+---
+status: draft
+period: ongoing
+theme: sealed-publication-authority
+doc_type: protocol
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: B
+review_state: unreviewed
+last_reviewed: 2026-07-15
+ai_provenance:
+  model_family: GPT-5
+  product: Codex
+  generated_at: 2026-07-15
+  limits: Live provider configuration must be re-audited; no credential values are represented.
+---
+
+# Sealed Publication Authority
+
+Buildchain publication authority is a closed-world, fail-closed protocol. It does
+not mint registry or cloud credentials. It independently verifies whether an
+already protected publication job is allowed to request a short-lived provider
+credential for one exact product, target, version, channel, and artifact digest.
+
+The machine-readable authority inventory is
+`dist/site/publication-authority-registry.json`. Any workflow with a write,
+environment, OIDC, cloud credential, registry publish, release, or Git push
+signal must have an explicit descriptor. A new authority-bearing workflow that
+is absent from the inventory fails site generation. Unknown workflows and every
+descriptor not marked `product-publication` are denied product publication.
+
+## Evidence chain
+
+A qualifying admission binds exact source and runtime SHAs; contract, consumer
+policy, qualifying controller receipt, Shifu/Gate aggregate, artifact, runner,
+and control-plane digests; repository, authority workflow, provider publisher
+workflow, Environment policy,
+product, target, version, and channel; plus a unique nonce and a lifetime of no
+more than 15 minutes. Every expected binding is mandatory at verification time;
+an omitted expected field is not a wildcard.
+
+The independent verifier recomputes every digest and ignores a producer's own
+allow/deny conclusion. It fetches the exact evidence run, validates the actual
+release-candidate passport and referenced qualifying controller receipt,
+recomputes the Shifu Gate aggregate or explicit consumer-owned no-Gate policy,
+recomputes the downloaded artifact manifests, and hashes every declared product
+payload file against those manifests. The `.buildchain/` diagnostics envelope is
+bound by the manifest digest but excluded from the product-byte set because it can
+be finalized after the lifecycle scan. The verifier also compares the PR evidence tree to the
+admitted post-merge source commit tree. It rejects an unknown
+workflow, stale or replayed nonce, runner downgrade, control-plane drift,
+source/runtime mismatch, and artifact substitution. A successful result is a
+scoped capability receipt, not a bearer credential.
+
+## Runner and control-plane evidence
+
+Runner evidence uses exactly four classes: `ephemeral`, `reimaged`,
+`persistent-measured`, and `unqualified`. Ephemeral runners also record their
+job-isolation boundary. Reimaged and persistent runners qualify only when a
+clean baseline is proven and baseline, toolchain, cache-contract, and task-
+isolation digests are all present. Otherwise they still emit diagnostic
+evidence with `qualificationStatus = unqualified`, but cannot receive a product
+capability.
+
+The external audit records digests and pass/fail status for repository Actions
+defaults, classic branch protection or an active matching repository ruleset,
+declared protected Environment policy or an explicit no-Environment binding,
+job-scoped credentials,
+absence of long-lived workflow publication credentials, provider authority,
+and authorized runner class. Provider modes are `npm-trusted-publisher`,
+`github-token`, and `oidc-role`. The OIDC-role mode consumes only a sanitized
+provider audit containing a role digest and qualifying decision; raw IAM policy,
+tokens, or credentials are rejected. Package-owner, cloud-root, GitHub
+administrator, and registry-root credentials remain outside Buildchain's trust
+boundary. Missing or unreadable facts fail closed.
+
+An unauthenticated local npm CLI is not evidence that Trusted Publishing is
+missing. `npm whoami` reports only the local CLI session and does not report the
+OIDC identity that npm creates during `npm publish`. The default read-only audit
+therefore binds the exact provider, repository, caller workflow, optional
+Environment, job-scoped OIDC permission, and absence of long-lived credentials,
+then records `provider-at-transaction`: npm makes the final authorization
+decision when `npm publish` exchanges the job's OIDC token. A missing or drifted
+trusted-publisher configuration consequently denies the transaction safely; it
+is not preflighted through an unrelated long-lived npm login.
+
+An authenticated external auditor can add stronger point-in-time evidence by
+supplying sanitized `npm trust list --json` output with `--npm-trust-json`. This
+changes the publisher fact to `audited-control-plane`; the workflow never runs
+`npm trust list` itself and never receives that auditor's npm credential.
+
+The credential-free collector proves effective Actions and runner scope from
+the publication workflow fetched at `--workflow-ref`: explicit read-only
+workflow defaults, job-scoped write/OIDC permissions, and an exact GitHub-hosted
+runner label. It does not call repository Actions-default or self-hosted-runner
+administration endpoints. Branch/ruleset and OIDC subject facts remain live
+read-only provider queries. When the detailed branch-protection endpoint is not
+readable with the workflow token, `--source-sha` binds the provider's public
+protected-branch summary to the exact merged PR, independent approval, required
+successful check, same-repository lineage, and current branch head. This records
+provider-enforced transaction evidence without treating an unavailable
+administration endpoint as an unprotected branch. It avoids turning a
+repository-admin token into a publication prerequisite.
+
+For non-dry-run workflows, missing admission, runner, control-plane, Gate, or
+expected-binding evidence is rejected before Buildchain downloads candidate
+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,
+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
+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.
+
+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.
+
+## API and CLI
+
+Use `@kungfu-tech/buildchain/publication-authority` or run:
+
+```bash
+buildchain verify publication-admission admission.json \
+  --registry-json publication-authority-registry.json \
+  --runner-json runner.json \
+  --control-plane-audit-json control-plane.json \
+  --publication-evidence-json publication-evidence.json \
+  --expected-json expected.json \
+  --used-nonce previous-run-nonce \
+  --json
+```
+
+The read-only live collector defaults to npm trusted publishing. Other product
+providers select an explicit adapter:
+
+```bash
+buildchain audit publication-control-plane \
+  --repository kungfu-systems/buildchain \
+  --branch dev/v2/v2.12 \
+  --source-sha <exact-merged-branch-sha> \
+  --workflow .github/workflows/release-candidate-promote.yml \
+  --workflow-ref <exact-buildchain-sha> \
+  --publisher-workflow .github/workflows/buildchain-ref-promotion.yml \
+  --job promote \
+  --environment none
+
+# Optional stronger external evidence; generate the JSON outside the workflow.
+buildchain audit publication-control-plane \
+  --repository kungfu-systems/buildchain \
+  --branch dev/v2/v2.12 \
+  --workflow .github/workflows/release-candidate-promote.yml \
+  --publisher-workflow .github/workflows/buildchain-ref-promotion.yml \
+  --job promote \
+  --environment none \
+  --npm-trust-json sanitized-npm-trust.json
+
+buildchain audit publication-control-plane \
+  --repository kungfu-systems/buildchain \
+  --branch release/v2/v2.12 \
+  --workflow .github/workflows/.binary-release-assets.yml \
+  --job publish \
+  --environment buildchain-release-assets \
+  --publisher-mode github-token
+
+buildchain audit publication-control-plane \
+  --repository OWNER/CONSUMER \
+  --workflow-repository kungfu-systems/buildchain \
+  --branch main \
+  --workflow .github/workflows/.web-surface.yml \
+  --job production-apply \
+  --environment production \
+  --publisher-mode oidc-role \
+  --provider-audit-json sanitized-oidc-role-audit.json
+```
+
+The authority workflow identifies the reusable implementation that performs the
+publication job. The publisher workflow identifies the caller filename bound by
+the provider's trusted-publisher policy; these identities are deliberately
+separate. `--environment none` is an explicit assertion that the job declares no
+GitHub Environment and the provider policy has no Environment restriction. A
+named Environment must exist, be protected, and be declared by the job. The
+Buildchain receipt alone is never sufficient authorization.
+
+## Publication lanes
+
+`Binary Distribution` is evidence-only. It builds platform archives and a
+release evidence bundle with read-only repository permissions. GitHub Release
+asset writes live in `Binary Release Assets`, which downloads an exact prior
+evidence run, verifies its bundle digest against the sealed capability, and is
+the only binary job with `contents: write` in the protected
+`buildchain-release-assets` Environment.
+
+The npm/promotion, paper, binary-release, and web-production lanes all depend on
+the independent verifier. Preview, staging, build, source-check, controller,
+and failure-evidence lanes do not inherit product publication capability.

package/docs/release-governance.md

@@ -627,7 +627,9 @@ passes `require-publish-source-lock`, `publish-source-ref`,
 `promote-buildchain-ref`. Direct action callers must pass the same four inputs
 from the reusable build outputs. Workflows that only collect passports or run
 dry-run package checks do not move publish refs and are not publish-gate
-publication models.
+publication models. A dry-run of `release-candidate-promote.yml` computes and
+reports the exact `publish-gate/*` source lock that a real promotion would use,
+but does not read, create, or move that ref.
 
 Semver GitHub Release publication is owned by `promote-buildchain-ref`, not by
 consumer shell glue. Consumers normally use the `release-candidate-promote.yml`

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.6",
+  "version": "2.12.7-alpha.10",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",
@@ -29,6 +29,9 @@
     "./logging": "./packages/core/logging.js",
     "./publication-artifact": "./packages/core/publication-artifact.js",
     "./publication-package": "./packages/core/publication-package.js",
+    "./publication-authority": "./packages/core/publication-authority.js",
+    "./publication-control-plane-audit": "./packages/core/publication-control-plane-audit.js",
+    "./buildchain-publication-authority": "./packages/core/buildchain-publication-authority.js",
     "./kfd-gate": "./packages/core/kfd-gate.js",
     "./release-candidate": "./packages/core/release-candidate.js",
     "./stable-candidate-ledger": "./packages/core/stable-candidate-ledger.js",
@@ -47,6 +50,7 @@
     "./site/kfd-claims.json": "./dist/site/kfd-claims.json",
     "./site/workflow-registry.json": "./dist/site/workflow-registry.json",
     "./site/controller-registry.json": "./dist/site/controller-registry.json",
+    "./site/publication-authority-registry.json": "./dist/site/publication-authority-registry.json",
     "./site/public-surface-audit.json": "./dist/site/public-surface-audit.json",
     "./site/kfd-upstream-aggregate.json": "./dist/site/kfd-upstream-aggregate.json",
     "./site/release-model.json": "./dist/site/release-model.json",

package/packages/core/buildchain-kfd-claims.js

@@ -16,6 +16,7 @@ export const BUILDCHAIN_AGENT_MANUALS = Object.freeze([
   { id: "install", title: "Install and verify Buildchain", path: "docs/install.md", plane: "use" },
   { id: "release-passport", title: "Release Passport protocol", path: "docs/release-passport.md", plane: "verify" },
   { id: "controller-evidence", title: "Controller evidence contract", path: "docs/controller-evidence.md", plane: "verify" },
+  { id: "publication-authority", title: "Sealed publication authority", path: "docs/publication-authority.md", plane: "verify" },
   { id: "release-candidate", title: "Release Candidate Passport", path: "docs/release-candidate.md", plane: "verify" },
   { id: "release-propagation", title: "Release propagation", path: "docs/release-propagation.md", plane: "use" },
   { id: "readme-badges", title: "README badge blocks", path: "docs/readme-badges.md", plane: "use" },
@@ -52,6 +53,7 @@ const SITE_CONTRACT_FILES = Object.freeze([
   "dist/site/node-api-registry.json",
   "dist/site/workflow-registry.json",
   "dist/site/controller-registry.json",
+  "dist/site/publication-authority-registry.json",
   "dist/site/public-surface-audit.json",
   "dist/site/release-model.json",
   "dist/site/artifact-schemas.json",
@@ -68,6 +70,9 @@ const SCHEMA_AND_STANDARD_FILES = Object.freeze([
   "packages/core/release-passport.js",
   "packages/core/buildchain-contract.js",
   "packages/core/controller-evidence.js",
+  "packages/core/publication-authority.js",
+  "packages/core/publication-control-plane-audit.js",
+  "packages/core/buildchain-publication-authority.js",
   "packages/core/buildchain-kfd-claims.js",
   "packages/core/kfd3-surface-register.js",
   "packages/core/public-surface-audit.js",

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

@@ -0,0 +1,80 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { createPublicationAuthorityRegistry } from "./publication-authority.js";
+
+const DESCRIPTORS = Object.freeze([
+  [".github/workflows/.build.yml", "non-publication-oidc"],
+  [".github/workflows/.publication-authority.yml", "evidence-publication"],
+  [".github/workflows/.release-verify.yml", "governance-write"],
+  [".github/workflows/.sam-release.yml", "retired-deny"],
+  [".github/workflows/.sam-verify.yml", "retired-deny"],
+  [".github/workflows/.sync-remote-git.yml", "governance-write"],
+  [".github/workflows/.web-surface.yml", "product-publication", true, ["web-production"], "oidc", "consumer-defined", "caller-bound", "caller-bound"],
+  [".github/workflows/.wheel-release.yml", "retired-deny"],
+  [".github/workflows/.wheel-verify.yml", "retired-deny"],
+  [".github/workflows/.binary-release-assets.yml", "product-publication", true, ["github-release"], "github-token", "buildchain-release-assets"],
+  [".github/workflows/binary-distribution.yml", "evidence-publication"],
+  [".github/workflows/binary-release-assets.yml", "governance-write"],
+  [".github/workflows/build-surface-fixture.yml", "non-publication-oidc"],
+  [".github/workflows/build.yml", "non-publication-oidc"],
+  [".github/workflows/buildchain-alpha-self-dogfood.yml", "non-publication-oidc"],
+  [".github/workflows/buildchain-patrol-daily.yml", "governance-write"],
+  [".github/workflows/buildchain-patrol-monthly.yml", "governance-write"],
+  [".github/workflows/buildchain-patrol-weekly.yml", "governance-write"],
+  [".github/workflows/buildchain-patrol.yml", "governance-write"],
+  [".github/workflows/buildchain-ref-promotion.yml", "governance-write"],
+  [".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"],
+  [".github/workflows/patrol-weekly.yml", "governance-write"],
+  [".github/workflows/publication-artifact.yml", "evidence-publication"],
+  [".github/workflows/release-candidate-promote.yml", "product-publication", true, ["npm-publish", "github-release", "channel-ref"], "trusted-publishing", "none", "fixed", "caller-bound"],
+  [".github/workflows/release-line-bootstrap.yml", "governance-write"],
+  [".github/workflows/release-propagation.yml", "governance-write"],
+  [".github/workflows/release-verify.yml", "governance-write"],
+  [".github/workflows/stable-candidate-patrol.yml", "governance-write"],
+]);
+
+export function buildchainPublicationAuthorityDescriptors() {
+  return DESCRIPTORS.map(([
+    workflowPath,
+    authorityClass,
+    publicationCapable = false,
+    capabilityIds = [],
+    credentialMode = "none",
+    environment = "",
+    environmentMode = "fixed",
+    publisherWorkflowMode = "fixed",
+    publisherWorkflowPath = workflowPath,
+  ]) => ({
+    workflowPath,
+    authorityClass,
+    publicationCapable,
+    capabilityIds,
+    credentialMode,
+    publisherWorkflowMode,
+    publisherWorkflowPath,
+    environment,
+    environmentMode,
+    runnerPolicy: publicationCapable ? "qualified-measured" : "unqualified",
+  }));
+}
+
+export function createBuildchainPublicationAuthorityRegistry({ root = process.cwd() } = {}) {
+  const workflowsDir = path.join(root, ".github", "workflows");
+  const workflows = fs.readdirSync(workflowsDir)
+    .filter((name) => name.endsWith(".yml") || name.endsWith(".yaml"))
+    .map((name) => ({
+      path: `.github/workflows/${name}`,
+      text: fs.readFileSync(path.join(workflowsDir, name), "utf8"),
+    }));
+  return createPublicationAuthorityRegistry({
+    descriptors: buildchainPublicationAuthorityDescriptors(),
+    workflows,
+  });
+}

package/packages/core/controller-evidence.js

@@ -47,9 +47,9 @@ const CONTROLLER_SPECS = [
     id: "web-surface",
     workflowId: ".web-surface",
     version: 1,
-    capabilities: ["web-build", "web-verify", "deployment-plan", "deployment-apply"],
-    stages: ["resolve-runtime", "plan", "build", "verify", "apply", "aggregate"],
-    optionalStages: ["build", "verify", "apply"],
+    capabilities: ["web-build", "web-verify", "deployment-plan", "deployment-apply", "publication-authority"],
+    stages: ["resolve-runtime", "plan", "build", "verify", "publication-authority", "apply", "aggregate"],
+    optionalStages: ["build", "verify", "publication-authority", "apply"],
     evidence: ["web-surface-plan", "controller-receipt"],
   },
   {
@@ -65,8 +65,8 @@ const CONTROLLER_SPECS = [
     id: "paper-release",
     workflowId: "paper-release",
     version: 1,
-    capabilities: ["publication-build", "artifact-admission", "release-publish", "release-passport"],
-    stages: ["resolve-runtime", "build", "verify", "collect", "publish", "passport", "aggregate"],
+    capabilities: ["publication-build", "artifact-admission", "publication-authority", "release-publish", "release-passport"],
+    stages: ["resolve-runtime", "build", "verify", "collect", "publication-authority", "publish", "passport", "aggregate"],
     optionalStages: ["verify"],
     evidence: ["publication-manifest", "release-passport", "controller-receipt"],
   },
@@ -74,8 +74,8 @@ const CONTROLLER_SPECS = [
     id: "release-candidate-promotion",
     workflowId: "release-candidate-promote",
     version: 1,
-    capabilities: ["promotion-preflight", "artifact-admission", "publish-transaction", "release-passport"],
-    stages: ["preflight", "admit-release-candidate", "publish", "passport", "aggregate"],
+    capabilities: ["promotion-preflight", "artifact-admission", "publication-authority", "publish-transaction", "release-passport"],
+    stages: ["preflight", "admit-release-candidate", "publication-authority", "publish", "passport", "aggregate"],
     evidence: ["release-candidate-passport", "publish-evidence", "release-passport", "controller-receipt"],
   },
   {
@@ -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

@@ -132,6 +132,41 @@ export {
   preparePublicationNpmPackage,
 } from "./publication-package.js";
 
+export {
+  PUBLICATION_ADMISSION_CONTRACT,
+  PUBLICATION_ARTIFACT_MANIFEST_SET_CONTRACT,
+  PUBLICATION_AUTHORITY_CLASSES,
+  PUBLICATION_AUTHORITY_REGISTRY_CONTRACT,
+  PUBLICATION_CAPABILITY_CONTRACT,
+  PUBLICATION_CONTROL_PLANE_AUDIT_CONTRACT,
+  PUBLICATION_GATE_DECISION_CONTRACT,
+  RUNNER_PROVENANCE_CLASSES,
+  RUNNER_PROVENANCE_CONTRACT,
+  createPublicationAuthorityRegistry,
+  createPublicationAdmission,
+  createPublicationArtifactManifestSet,
+  createPublicationControlPlaneAudit,
+  createPublicationGateDecision,
+  createRunnerProvenance,
+  detectPublicationAuthoritySignals,
+  publicationAuthorityDigest,
+  verifyPublicationAdmission,
+} from "./publication-authority.js";
+
+export {
+  PUBLICATION_ARTIFACT_CANDIDATE_CONTRACT,
+  createPublicationArtifactCandidate,
+  publicationArtifactCandidateDigest,
+  resolvePublicationCandidateFile,
+} from "./publication-artifact-candidate.js";
+
+export {
+  buildchainPublicationAuthorityDescriptors,
+  createBuildchainPublicationAuthorityRegistry,
+} from "./buildchain-publication-authority.js";
+
+export { evaluatePublicationControlPlaneSnapshot } from "./publication-control-plane-audit.js";
+
 export {
   ARTIFACT_PASSPORT_LOCATOR_CONTRACT,
   ARTIFACT_PASSPORT_POINTER_CONTRACT,

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) };
+}