@kungfu-tech/buildchain 3.0.2-alpha.0 → 3.0.2-alpha.10

package/packages/core/buildchain-config.js

@@ -55,6 +55,17 @@ const SUPPORTED_INFRA_APPLY_MODES = new Set(["disabled", "manual-approval", "env
 const SUPPORTED_FACT_VERSION_SOURCE_TYPES = new Set(["static", "json", "toml", "regex", "command"]);
 const SUPPORTED_FACT_LEGACY_PROJECTIONS = new Set(["kungfu-buildinfo"]);
 const SUPPORTED_PUBLICATION_TOOLCHAINS = new Set(["custom-command", "latex-docker"]);
+const SUPPORTED_SIGNING_PROFILES = new Set([
+  "auto",
+  "apple-developer-id",
+  "windows-authenticode",
+  "detached-signature-v1",
+]);
+const SUPPORTED_SIGNING_ARTIFACT_KINDS = new Set([
+  "auto", "binary", "archive", "blob", "directory", "mach-o", "app-bundle",
+  "framework-bundle", "plugin-bundle", "xpc-bundle", "dylib", "pkg", "dmg",
+  "pe",
+]);
 
 function posixPath(value) {
   return String(value || "").split(path.sep).join("/");
@@ -218,6 +229,9 @@ export function normalizeBuildchainConfig(config) {
   if (normalized.facts !== undefined) {
     normalized.facts = normalizeFactsSection(normalized.facts);
   }
+  if (normalized.signing !== undefined) {
+    normalized.signing = normalizeSigningSection(normalized.signing);
+  }
   validateWebSurfaceConfig(normalized);
   validateInfraContractConfig(normalized);
   validateAnchoredDerivedVersionMaterialConfig(normalized);
@@ -335,6 +349,49 @@ function normalizeFactsSection(facts) {
   };
 }
 
+function normalizeSigningSection(signing) {
+  assertPlainObject(signing, "signing");
+  for (const key of Object.keys(signing)) {
+    if (key !== "artifacts") {
+      throw new Error(`signing.${key} is not supported; consumer signing declarations cannot configure credentials or authority infrastructure`);
+    }
+  }
+  if (!Array.isArray(signing.artifacts) || signing.artifacts.length === 0) {
+    throw new Error("signing.artifacts must declare at least one artifact");
+  }
+  const artifacts = signing.artifacts.map((artifact, index) => {
+    const label = `signing.artifacts[${index}]`;
+    assertPlainObject(artifact, label);
+    const allowedKeys = new Set(["id", "path", "profile", "kind", "platforms", "required"]);
+    for (const key of Object.keys(artifact)) {
+      if (!allowedKeys.has(key)) {
+        throw new Error(`${label}.${key} is not supported; declare desired signature state only`);
+      }
+    }
+    const artifactPath = posixPath(assertString(artifact.path, `${label}.path`));
+    const profile = artifact.profile === undefined ? "auto" : assertString(artifact.profile, `${label}.profile`);
+    if (!SUPPORTED_SIGNING_PROFILES.has(profile)) {
+      throw new Error(`${label}.profile must be one of auto, apple-developer-id, windows-authenticode, or detached-signature-v1`);
+    }
+    const kind = artifact.kind === undefined ? "auto" : assertString(artifact.kind, `${label}.kind`);
+    if (!SUPPORTED_SIGNING_ARTIFACT_KINDS.has(kind)) {
+      throw new Error(`${label}.kind is not a supported signing artifact kind`);
+    }
+    return {
+      id: artifact.id === undefined ? artifactPath : assertString(artifact.id, `${label}.id`),
+      path: artifactPath,
+      profile,
+      kind,
+      platforms: normalizeStringArray(artifact.platforms, `${label}.platforms`),
+      required: optionalBoolean(artifact.required, true),
+    };
+  });
+  if (new Set(artifacts.map((artifact) => artifact.id)).size !== artifacts.length) {
+    throw new Error("signing.artifacts must use unique ids");
+  }
+  return { artifacts };
+}
+
 function normalizeFactVersionSources(sources = []) {
   if (sources === undefined) {
     return [];
@@ -1615,6 +1672,7 @@ export function validateBuildchainConfig(
     release: loadedConfig.config.release,
     governance: loadedConfig.config.governance,
     facts: loadedConfig.config.facts,
+    signing: loadedConfig.config.signing,
     publication: loadedConfig.config.publication,
   };
 }

package/packages/core/buildchain-contract.js

@@ -121,6 +121,8 @@ export function createBuildchainContractWorld({
         "runner-preset",
         "platforms-json",
         "release-candidate",
+        "github-artifact-attestation-subject-path",
+        "github-artifact-attestation-platform-id",
         "artifact-transfer-mode",
         "checkout-cache-mode",
         "checkout-cache-fallback",
@@ -196,6 +198,9 @@ export function createBuildchainContractWorld({
         "release-passport-kfd-3-artifact-verify-command",
         "release-passport-invariant-passport-jsons",
         "release-passport-invariant-passport-command",
+        "github-artifact-attestation-policy-json",
+        "github-artifact-attestation-environment",
+        "github-artifact-attestation-retention-days",
         "buildchain-contract-lock-path",
         "buildchain-contract-drift-issue-mode",
         "github-release",
@@ -324,10 +329,13 @@ export function createBuildchainContractWorld({
         "media-artifact-digest",
         "media-artifact-url",
         "media-root",
+        "media-profile",
+        "media-qualification-root",
       ],
       breakingDefaults: {
         trustedEventRequired: true,
         renderMediaDefault: false,
+        mediaProfileDefault: "archive-v1",
         artifactRetentionDaysDefault: 14,
         gatePolicy: "required-before-selective-render",
       },
@@ -335,6 +343,7 @@ export function createBuildchainContractWorld({
         "buildchain-repository",
         "source-ref",
         "render-media",
+        "media-profile",
         "artifact-retention-days",
         "require-trusted-event",
       ],
@@ -344,6 +353,10 @@ export function createBuildchainContractWorld({
         "every invocation runs an immutable network-disabled renderer smoke before emitting a qualified Gate bundle",
         "complete media rendering is optional and consumes only an exact passing Gate bundle",
         "Gate and media bundles expose both GitHub Artifact archive coordinates and deterministic member roots",
+        "explicit web-delivery profiles independently verify codec, container, audio, dimensions, duration, byte budgets, rendition roles, and MP4 fast-start evidence",
+        "media receipts expose content-addressed rendition facts without requiring consumers to infer roles from filenames",
+        "Build Images owns encoding, Buildchain owns qualification and receipts, and site repositories own browser loading and accessibility behavior",
+        "media qualification does not claim browser playback, responsive layout, reduced-motion behavior, accessibility, or production deployment",
       ],
     }),
     surface(root, {
@@ -369,6 +382,7 @@ export function createBuildchainContractWorld({
         "release-passport-kfd-3-artifact-verify-command",
         "release-passport-invariant-passport-jsons",
         "release-passport-invariant-passport-command",
+        "release-passport-github-artifact-attestation-policy-jsons",
         "github-release",
         "github-release-title",
         "github-release-notes",

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

@@ -16,6 +16,7 @@ export const BUILDCHAIN_AGENT_MANUALS = Object.freeze([
   { id: "auditable-demo", title: "Auditable demo artifact pipeline", path: "docs/auditable-demo.md", plane: "verify" },
   { 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: "github-artifact-attestation", title: "GitHub-native Linux artifact attestation", path: "docs/github-artifact-attestation.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: "github-governance-authority", title: "GitHub governance authority", path: "docs/github-governance-authority.md", plane: "verify" },
@@ -71,6 +72,7 @@ const SITE_CONTRACT_FILES = Object.freeze([
 const SCHEMA_AND_STANDARD_FILES = Object.freeze([
   "packages/core/kfd-gate.js",
   "packages/core/release-passport.js",
+  "packages/core/github-artifact-attestation.js",
   "packages/core/buildchain-contract.js",
   "packages/core/controller-evidence.js",
   "packages/core/publication-authority.js",
@@ -89,6 +91,9 @@ const WORKFLOW_AND_ACTION_FILES = Object.freeze([
   ".github/workflows/.release-candidate-promote.yml",
   ".github/workflows/release-candidate-promote.yml",
   ".github/workflows/buildchain-ref-promotion.yml",
+  ".github/workflows/github-artifact-attestation.yml",
+  "actions/github-artifact-attestation/action.yml",
+  "actions/github-artifact-attestation/index.js",
   ".github/workflows/release-propagation.yml",
   "actions/macos-credential-island/action.yml",
   "actions/macos-credential-island/index.js",

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

@@ -18,6 +18,7 @@ const DESCRIPTORS = Object.freeze([
   [".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/artifact-signing-authority.yml", "evidence-publication"],
   [".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"],
@@ -27,9 +28,11 @@ const DESCRIPTORS = Object.freeze([
   [".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-alpha-candidate-patrol.yml", "governance-write"],
   [".github/workflows/dev-merge-queue-governance.yml", "governance-write"],
   [".github/workflows/dev-pr-auto-merge.yml", "governance-write"],
   [".github/workflows/github-governance-audit.yml", "governance-write"],
+  [".github/workflows/github-artifact-attestation.yml", "evidence-publication", true, ["github-artifact-attestation"], "oidc", "consumer-defined", "caller-bound", "caller-bound"],
   [".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"],

package/packages/core/cache-evidence.js

@@ -0,0 +1,288 @@
+import crypto from "node:crypto";
+
+export const BUILDCHAIN_CACHE_OPERATION_RECEIPT_CONTRACT =
+  "buildchain.cache-operation-receipt/v1";
+export const BUILDCHAIN_CACHE_EVIDENCE_SET_CONTRACT =
+  "buildchain.cache-evidence-set/v1";
+
+const DIGEST_RE = /^sha256:[0-9a-f]{64}$/;
+const OUTCOMES = new Set([
+  "hit",
+  "miss",
+  "partial",
+  "bypassed",
+  "poisoned",
+  "unavailable",
+]);
+const METRIC_UNITS = Object.freeze({
+  lookupDuration: "ms",
+  restoreDuration: "ms",
+  saveDuration: "ms",
+  restoredBytes: "bytes",
+  writtenBytes: "bytes",
+  savedTime: "ms",
+});
+const METRIC_STATUSES = new Set(["observed", "unavailable", "not-applicable"]);
+const SAVED_TIME_METHODS = new Set(["producer-measured", "provider-reported"]);
+
+function assert(condition, message) {
+  if (!condition) throw new Error(message);
+}
+
+function ordered(value) {
+  if (Array.isArray(value)) return value.map(ordered);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.keys(value)
+        .sort()
+        .map((key) => [key, ordered(value[key])]),
+    );
+  }
+  return value;
+}
+
+function stableJson(value) {
+  return JSON.stringify(ordered(value));
+}
+
+export function cacheEvidenceDigest(value) {
+  return `sha256:${crypto
+    .createHash("sha256")
+    .update(typeof value === "string" ? value : stableJson(value))
+    .digest("hex")}`;
+}
+
+function exactKeys(value, allowed, label) {
+  assert(
+    value && typeof value === "object" && !Array.isArray(value),
+    `${label} must be an object`,
+  );
+  for (const key of Object.keys(value)) {
+    assert(allowed.has(key), `${label}.${key} is not allowed`);
+  }
+}
+
+function text(value, label) {
+  assert(
+    typeof value === "string" && value.trim() === value && value.length > 0,
+    `${label} is required`,
+  );
+  assert(!/[\r\n\0]/.test(value), `${label} contains control characters`);
+  return value;
+}
+
+function digest(value, label) {
+  assert(DIGEST_RE.test(value), `${label} must be a sha256 digest`);
+  return value;
+}
+
+function normalizeBindings(bindings = {}) {
+  exactKeys(
+    bindings,
+    new Set([
+      "sourceCommit",
+      "sourceTree",
+      "runtimeCommit",
+      "dependencyLockRoot",
+      "toolchainRoot",
+      "policyRoot",
+      "platformRoot",
+      "cacheProfileRoot",
+    ]),
+    "bindings",
+  );
+  return Object.fromEntries(
+    Object.entries(bindings)
+      .filter(([, value]) => value !== null && value !== undefined && value !== "")
+      .map(([key, value]) => [key, text(value, `bindings.${key}`)]),
+  );
+}
+
+function normalizeMetric(metric, name) {
+  exactKeys(
+    metric,
+    new Set([
+      "status",
+      "unit",
+      "value",
+      "source",
+      "reason",
+      "evidenceRoot",
+      "method",
+    ]),
+    `metrics.${name}`,
+  );
+  const status = text(metric.status, `metrics.${name}.status`);
+  assert(
+    METRIC_STATUSES.has(status),
+    `metrics.${name}.status must be observed, unavailable, or not-applicable`,
+  );
+  assert(
+    metric.unit === METRIC_UNITS[name],
+    `metrics.${name}.unit must be ${METRIC_UNITS[name]}`,
+  );
+  if (status === "observed") {
+    assert(
+      Number.isFinite(metric.value) && metric.value >= 0,
+      `metrics.${name}.value must be a non-negative finite number`,
+    );
+    const normalized = {
+      status,
+      unit: metric.unit,
+      value: metric.value,
+      source: text(metric.source, `metrics.${name}.source`),
+      reason: null,
+      evidenceRoot: digest(
+        metric.evidenceRoot,
+        `metrics.${name}.evidenceRoot`,
+      ),
+    };
+    if (name === "savedTime") {
+      assert(
+        typeof metric.method === "string" &&
+          SAVED_TIME_METHODS.has(metric.method),
+        "observed saved time requires producer-measured or provider-reported evidence",
+      );
+      normalized.method = metric.method;
+    } else if (metric.method) {
+      normalized.method = text(metric.method, `metrics.${name}.method`);
+    }
+    return normalized;
+  }
+  assert(
+    metric.value === null || metric.value === undefined,
+    `metrics.${name}.value must be null when ${status}`,
+  );
+  return {
+    status,
+    unit: metric.unit,
+    value: null,
+    source: metric.source ? text(metric.source, `metrics.${name}.source`) : null,
+    reason: text(metric.reason, `metrics.${name}.reason`),
+    evidenceRoot: metric.evidenceRoot
+      ? digest(metric.evidenceRoot, `metrics.${name}.evidenceRoot`)
+      : null,
+  };
+}
+
+export function createCacheOperationReceipt({
+  operationId,
+  operation,
+  provider,
+  producer,
+  platform,
+  cacheKey,
+  cacheRoot,
+  outcome,
+  bindings = {},
+  metrics,
+  evidence,
+} = {}) {
+  assert(
+    ["restore", "save", "lookup"].includes(operation),
+    "operation must be restore, save, or lookup",
+  );
+  assert(OUTCOMES.has(outcome), "unsupported cache outcome");
+  exactKeys(
+    metrics,
+    new Set(Object.keys(METRIC_UNITS)),
+    "metrics",
+  );
+  for (const name of Object.keys(METRIC_UNITS)) {
+    assert(metrics[name], `metrics.${name} is required`);
+  }
+  exactKeys(
+    evidence,
+    new Set(["kind", "root", "locator"]),
+    "evidence",
+  );
+  const receipt = {
+    schema: BUILDCHAIN_CACHE_OPERATION_RECEIPT_CONTRACT,
+    operationId: text(operationId, "operationId"),
+    operation,
+    provider: text(provider, "provider"),
+    producer: text(producer, "producer"),
+    platform: text(platform, "platform"),
+    cacheKey: cacheKey ? text(cacheKey, "cacheKey") : null,
+    cacheRoot: cacheRoot ? text(cacheRoot, "cacheRoot") : null,
+    outcome,
+    bindings: normalizeBindings(bindings),
+    metrics: Object.fromEntries(
+      Object.keys(METRIC_UNITS).map((name) => [
+        name,
+        normalizeMetric(metrics[name], name),
+      ]),
+    ),
+    evidence: {
+      kind: text(evidence.kind, "evidence.kind"),
+      root: digest(evidence.root, "evidence.root"),
+      locator: text(evidence.locator, "evidence.locator"),
+    },
+  };
+  return { ...receipt, receiptRoot: cacheEvidenceDigest(receipt) };
+}
+
+export function verifyCacheOperationReceipt(receipt) {
+  assert(
+    receipt?.schema === BUILDCHAIN_CACHE_OPERATION_RECEIPT_CONTRACT,
+    "cache operation receipt schema mismatch",
+  );
+  const { receiptRoot, ...body } = receipt;
+  assert(
+    receiptRoot === cacheEvidenceDigest(body),
+    "cache operation receipt root mismatch",
+  );
+  const rebuilt = createCacheOperationReceipt(body);
+  assert(
+    stableJson(rebuilt) === stableJson(receipt),
+    "cache operation receipt normalization drift",
+  );
+  return true;
+}
+
+export function createCacheEvidenceSet({
+  repository,
+  sourceCommit,
+  sourceTree = "",
+  runtimeCommit = "",
+  platform,
+  operations = [],
+} = {}) {
+  assert(Array.isArray(operations), "cache evidence operations must be an array");
+  operations.forEach(verifyCacheOperationReceipt);
+  const operationIds = operations.map(({ operationId }) => operationId);
+  assert(
+    operationIds.length === new Set(operationIds).size,
+    "cache evidence operation ids must be unique",
+  );
+  const value = {
+    schema: BUILDCHAIN_CACHE_EVIDENCE_SET_CONTRACT,
+    repository: text(repository, "repository"),
+    sourceCommit: text(sourceCommit, "sourceCommit"),
+    sourceTree: sourceTree ? text(sourceTree, "sourceTree") : null,
+    runtimeCommit: runtimeCommit ? text(runtimeCommit, "runtimeCommit") : null,
+    platform: text(platform, "platform"),
+    operations: [...operations].sort((left, right) =>
+      left.operationId.localeCompare(right.operationId),
+    ),
+  };
+  return { ...value, evidenceRoot: cacheEvidenceDigest(value) };
+}
+
+export function verifyCacheEvidenceSet(receipt) {
+  assert(
+    receipt?.schema === BUILDCHAIN_CACHE_EVIDENCE_SET_CONTRACT,
+    "cache evidence set schema mismatch",
+  );
+  const { evidenceRoot, ...body } = receipt;
+  assert(
+    evidenceRoot === cacheEvidenceDigest(body),
+    "cache evidence set root mismatch",
+  );
+  const rebuilt = createCacheEvidenceSet(body);
+  assert(
+    stableJson(rebuilt) === stableJson(receipt),
+    "cache evidence set normalization drift",
+  );
+  return true;
+}

package/packages/core/channel-candidate.js

@@ -0,0 +1,186 @@
+// SPDX-License-Identifier: Apache-2.0
+
+import crypto from "node:crypto";
+
+export const CHANNEL_CANDIDATE_DECISION_SCHEMA =
+  "kungfu-buildchain-channel-candidate-decision/v1";
+
+const SHA = /^[0-9a-f]{40}$/;
+
+function canonical(value) {
+  if (Array.isArray(value)) return value.map(canonical);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, item]) => [key, canonical(item)]),
+    );
+  }
+  return value;
+}
+
+function root(value) {
+  return `sha256:${crypto
+    .createHash("sha256")
+    .update(JSON.stringify(canonical(value)))
+    .digest("hex")}`;
+}
+
+function required(value, name) {
+  const normalized = String(value || "").trim();
+  if (!normalized) throw new Error(`${name} is required`);
+  return normalized;
+}
+
+function sha(value, name) {
+  const normalized = required(value, name).toLowerCase();
+  if (!SHA.test(normalized))
+    throw new Error(`${name} must be an exact 40-character SHA`);
+  return normalized;
+}
+
+function qualifyWorkflow(row, { sourceSha, now, maxAgeSeconds }) {
+  if (!row || typeof row !== "object")
+    throw new Error("workflow evidence is required");
+  const workflowPath = required(row.workflowPath, "workflowPath");
+  if (sha(row.headSha, `${workflowPath} headSha`) !== sourceSha) {
+    throw new Error(
+      `${workflowPath} evidence does not bind source SHA ${sourceSha}`,
+    );
+  }
+  if (row.status !== "completed" || row.conclusion !== "success") {
+    throw new Error(`${workflowPath} is not a completed successful run`);
+  }
+  const completedAt = required(row.completedAt, `${workflowPath} completedAt`);
+  const ageSeconds = (Date.parse(now) - Date.parse(completedAt)) / 1000;
+  if (
+    !Number.isFinite(ageSeconds) ||
+    ageSeconds < 0 ||
+    ageSeconds > maxAgeSeconds
+  ) {
+    throw new Error(
+      `${workflowPath} evidence is stale or has an invalid completion time`,
+    );
+  }
+  const runId = Number(row.runId);
+  const runAttempt = Number(row.runAttempt || 1);
+  if (!Number.isSafeInteger(runId) || runId <= 0)
+    throw new Error(`${workflowPath} runId is invalid`);
+  if (!Number.isSafeInteger(runAttempt) || runAttempt <= 0)
+    throw new Error(`${workflowPath} runAttempt is invalid`);
+  return {
+    workflowPath,
+    workflowName: required(row.workflowName, `${workflowPath} workflowName`),
+    runId,
+    runAttempt,
+    headSha: sourceSha,
+    status: "completed",
+    conclusion: "success",
+    completedAt,
+    url: required(row.url, `${workflowPath} url`),
+  };
+}
+
+export function channelCandidateSourceLockRef(targetBranch, sourceSha) {
+  const target = required(targetBranch, "targetBranch");
+  const exactSha = sha(sourceSha, "sourceSha");
+  return `buildchain/candidate/${target.replace(/[^A-Za-z0-9._-]+/g, "-")}/${exactSha.slice(0, 12)}`;
+}
+
+export function decideChannelCandidate(input) {
+  const repository = required(input.repository, "repository");
+  const sourceBranch = required(input.sourceBranch, "sourceBranch");
+  const targetBranch = required(input.targetBranch, "targetBranch");
+  if (sourceBranch === targetBranch)
+    throw new Error("sourceBranch and targetBranch must differ");
+  const sourceSha = sha(input.sourceSha, "sourceSha");
+  const targetSha = sha(input.targetSha, "targetSha");
+  const selection = input.selection
+    ? {
+        mode: required(input.selection.mode, "selection.mode"),
+        observedSourceHeadSha: sha(
+          input.selection.observedSourceHeadSha,
+          "selection.observedSourceHeadSha",
+        ),
+        skippedNewerCommitCount: Number(
+          input.selection.skippedNewerCommitCount || 0,
+        ),
+      }
+    : undefined;
+  if (
+    selection &&
+    (!Number.isSafeInteger(selection.skippedNewerCommitCount) ||
+      selection.skippedNewerCommitCount < 0)
+  ) {
+    throw new Error(
+      "selection.skippedNewerCommitCount must be a non-negative integer",
+    );
+  }
+  const now = required(input.now || new Date().toISOString(), "now");
+  const maxAgeSeconds = Number(input.maxAgeSeconds ?? 7 * 24 * 60 * 60);
+  if (!Number.isSafeInteger(maxAgeSeconds) || maxAgeSeconds <= 0) {
+    throw new Error("maxAgeSeconds must be a positive integer");
+  }
+  const comparison = input.comparison || {};
+  if (comparison.status !== "ahead" || Number(comparison.aheadBy) <= 0) {
+    const reason =
+      comparison.status === "identical"
+        ? "target-already-current"
+        : "source-does-not-lead-target";
+    return {
+      schema: CHANNEL_CANDIDATE_DECISION_SCHEMA,
+      eligible: false,
+      reason,
+      repository,
+      source: { branch: sourceBranch, sha: sourceSha },
+      target: { branch: targetBranch, sha: targetSha },
+      comparison: {
+        status: String(comparison.status || "unknown"),
+        aheadBy: Number(comparison.aheadBy || 0),
+      },
+      decidedAt: now,
+    };
+  }
+  const rows = Array.isArray(input.workflowEvidence)
+    ? input.workflowEvidence
+    : [];
+  const expectedPaths = [
+    ...new Set((input.requiredWorkflowPaths || []).map(String)),
+  ];
+  if (expectedPaths.length === 0)
+    throw new Error("requiredWorkflowPaths must not be empty");
+  if (rows.length !== expectedPaths.length) {
+    throw new Error(
+      `expected exactly ${expectedPaths.length} workflow evidence rows, got ${rows.length}`,
+    );
+  }
+  const byPath = new Map();
+  for (const row of rows) {
+    const qualified = qualifyWorkflow(row, { sourceSha, now, maxAgeSeconds });
+    if (byPath.has(qualified.workflowPath)) {
+      throw new Error(`duplicate workflow evidence: ${qualified.workflowPath}`);
+    }
+    byPath.set(qualified.workflowPath, qualified);
+  }
+  for (const workflowPath of expectedPaths) {
+    if (!byPath.has(workflowPath))
+      throw new Error(`missing workflow evidence: ${workflowPath}`);
+  }
+  const body = {
+    schema: CHANNEL_CANDIDATE_DECISION_SCHEMA,
+    eligible: true,
+    reason: "same-source-qualified",
+    repository,
+    source: { branch: sourceBranch, sha: sourceSha },
+    target: { branch: targetBranch, sha: targetSha },
+    comparison: { status: "ahead", aheadBy: Number(comparison.aheadBy) },
+    ...(selection ? { selection } : {}),
+    sourceLockRef: channelCandidateSourceLockRef(targetBranch, sourceSha),
+    workflowEvidence: expectedPaths.map((workflowPath) =>
+      byPath.get(workflowPath),
+    ),
+    policy: { maxAgeSeconds, requiredWorkflowPaths: expectedPaths },
+    decidedAt: now,
+  };
+  return { ...body, decisionRoot: root(body) };
+}