@kungfu-tech/buildchain 2.12.9-alpha.1 → 2.13.0-alpha.1

package/docs/publication-authority.md

@@ -136,6 +136,32 @@ publication capability.
 Evidence publication is a separate authority class and never grants product
 publication.
 
+## Consumer qualification handoff
+
+Consumers may explicitly opt in to a final, consumer-owned qualification
+predicate. Buildchain then transports the complete Gate aggregate alongside the
+sealed capability instead of reducing it to a summary. The capability binds the
+authority registry, consumer Gate registry and policy, exact source and runtime,
+controller, runner, control-plane, artifact, provider target, channel, version,
+freshness window, nonce, and exact predicate command digest.
+
+The predicate runs in a separate job with read-only source access, no inherited
+secrets, no OIDC permission, and no provider write permission. It receives only
+paths to `capability.json` and `gate-aggregate.json` plus the exact predicate id
+and digest. The consumer writes a
+`kungfu-buildchain-consumer-publication-decision`; Buildchain seals that result
+as a deterministic
+`kungfu-buildchain-publication-qualification-receipt`. Buildchain does not parse
+product-specific Gate meanings.
+
+The provider action revalidates the capability, full aggregate, receipt,
+predicate identity, freshness, nonce, source, version, channel, target, and all
+sealed digests immediately before the publish transaction. Missing, denied,
+stale, replayed, substituted, or drifted receipts fail before provider mutation.
+Direct calls to the provider action cannot bypass the receipt when
+`require-publication-qualification` is enabled. Consumers that do not opt in
+retain the existing publication contract.
+
 ## API and CLI
 
 Use `@kungfu-tech/buildchain/publication-authority` or run:

package/docs/publish-transaction.md

@@ -210,7 +210,7 @@ Buildchain distinguishes two npm release modes:
 
 | Mode | Use | Auth | npm operation |
 | --- | --- | --- | --- |
-| `publish-final-version` | normal alpha or stable publication | `trusted-publishing` | `npm publish --tag <alpha|vX.Y-alpha|latest>` |
+| `publish-final-version` | normal alpha or stable publication | `trusted-publishing` | `npm publish --tag <alpha|latest>` |
 | `promote-existing-version` | same-version alpha-to-latest recovery | `npm-token` | `npm dist-tag add <pkg>@<version> latest` |
 
 The normal libnode path is `publish-final-version`: publish an alpha package set

package/docs/release-candidate.md

@@ -82,6 +82,11 @@ other package as `role: platform`. Consumer workflows therefore stay
 declarative and do not need their own artifact download or publish-evidence
 generation scripts.
 
+Because a channel merge can trigger promotion before its PR-stage matrix has
+finished uploading evidence, the resolver waits up to ten minutes for the exact
+merged PR's successful workflow run and paired artifacts. Polling remains bound
+to the PR/head identity; timeout or a sibling run still fails closed.
+
 By default, the wrapper forwards GitHub Release publication to the underlying
 `promote-buildchain-ref` semver model. Once the release transaction is complete,
 the action creates or updates the public GitHub Release, applies
@@ -135,3 +140,22 @@ 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.
+
+A consumer that owns additional product qualification semantics can opt in to
+the sealed handoff without teaching Buildchain those semantics:
+
+```yaml
+      publication-consumer-predicate-id: kungfu.release-admission/v1
+      publication-consumer-qualification-command: node scripts/qualify-release.mjs
+```
+
+The command reads `BUILDCHAIN_PUBLICATION_CAPABILITY_PATH` and
+`BUILDCHAIN_PUBLICATION_GATE_AGGREGATE_PATH`, evaluates the complete aggregate,
+and writes a decision JSON document to
+`BUILDCHAIN_PUBLICATION_QUALIFICATION_RESULT_PATH`. It also receives
+`BUILDCHAIN_PUBLICATION_PREDICATE_ID` and
+`BUILDCHAIN_PUBLICATION_PREDICATE_DIGEST`. The separate qualification job has
+no write or OIDC permission and does not inherit publication secrets. A
+successful deterministic receipt is rechecked by the provider action
+immediately before mutation. Omitting both inputs preserves the existing
+consumer contract; supplying only one fails closed.

package/docs/release-governance.md

@@ -94,6 +94,13 @@ The implementation is intentionally stricter than a local release script:
   release source tree against that tested alpha tree;
 - generated version-state commits are verified before refs move.
 
+Exact publication planning installs the checked-out promotion source's declared
+dependencies before version-state verification. This keeps the pre-authority
+version plan on the same package-manager boundary as the later promotion job,
+including repositories whose verification commands import production packages.
+The planning pass may materialize and verify declared derived files locally,
+but dry-run never creates Git blobs, trees, commits, refs, or tags.
+
 Promotion intents are serialized globally per caller repository with
 `cancel-in-progress: false`. A queued intent re-reads its protected target ref
 before checkout, dependency installation, release-candidate resolution, or any
@@ -162,11 +169,6 @@ Buildchain then:
 7. Moves `vX.Y-alpha` to the same generated alpha commit.
 8. Moves `vX-alpha` only when `X.Y` is the highest minor in major `X` with a published alpha; older minor alpha work records a skip and cannot move the major channel backwards.
 
-The npm channel follows the same ownership rule. The highest alpha minor publishes
-with dist-tag `alpha`; maintenance alphas on an older minor publish with the
-line-specific dist-tag `vX.Y-alpha` so they cannot roll the global `alpha`
-channel backward. Exact prerelease versions remain installable directly.
-
 This keeps the test channel self-describing. If a consumer checks out
 `v2.0-alpha` or `v2-alpha`, the manifests and exact alpha tag agree. The major
 alpha ref removes routine consumer edits when Buildchain opens a newer minor,
@@ -588,7 +590,11 @@ Buildchain's own promotion workflow reads `BUILDCHAIN_PROMOTION_BYPASS_APPS`,
 `BUILDCHAIN_PROMOTION_BYPASS_TEAMS` repository variables so the declared bypass
 identity can match the actual `BUILDCHAIN_PROMOTION_TOKEN` actor, but consumers
 do not need to duplicate that actor manually when the token identity is
-discoverable.
+discoverable. Buildchain's release-line bootstrap applies the same declared
+allowances when it creates new `dev`, `alpha`, and `release` branch protection,
+and fails closed before changing protection when no promotion authority is
+declared. This keeps a new minor line publishable without weakening its normal
+human review gate.
 
 ## What This Guarantees
 

package/docs/release-propagation.md

@@ -194,6 +194,9 @@ downstream repository, writes the exact lock, and opens or updates a PR. It does
 not publish the downstream release directly. The downstream repository keeps its
 normal Buildchain governance: the PR updates source-of-truth facts, then
 downstream alpha or release publication runs through its own protected channel.
+The workflow stages the declared lock path before checking the index, so the
+first propagation creates a PR even when the lock did not previously exist; a
+byte-identical rerun is an explicit successful no-op.
 For unreleased runtime validation, keep the caller's reusable workflow reference
 on `@v2` and pass a temporary train ref through `buildchain-ref`.
 

package/docs/reusable-build-surface.md

@@ -903,6 +903,18 @@ with:
   verify-command: ctest --test-dir build --output-on-failure
 ```
 
+Every native and container matrix job is bounded by
+`lifecycle-timeout-minutes`, which defaults to 120 minutes. The same input is
+the fallback deadline for each install, build, and verify action, so a hung
+command fails with the lifecycle name and matrix platform before it can occupy
+a self-hosted runner indefinitely. A stage-level `timeout_minutes` in
+`buildchain.toml` remains the more specific override for that stage.
+
+```yaml
+with:
+  lifecycle-timeout-minutes: 90
+```
+
 The reusable build workflow samples the build lifecycle by default and carries
 the generated summary into the final verify diagnostics. Callers can override
 the sidecar path or disable sampling:
@@ -932,6 +944,7 @@ For custom workflows, use the action directly:
   with:
     stage: build
     required: "true"
+    timeout-minutes: "90"
     artifact-name: libnode-linux-x64-${{ github.sha }}
     artifact-paths: |
       dist

package/docs/versioning.md

@@ -61,6 +61,7 @@ repository changes are patch".
 
 | Date | Action | Line | Faces | Class | Rationale | PR |
 | --- | --- | --- | --- | --- | --- | --- |
+| 2026-07-15 | open-minor | `v2.13` | artifact-verification-envelope, package-subpaths | additive | The public envelope seals exact artifact, provenance, identity, lifecycle, revocation, and existing KFD assessment roots into one consumer-ready KFX admission input, with a dedicated Node API export and fail-closed verifier. | |
 | 2026-07-11 | open-minor | `v2.12` | channel-build-router, channel-selection-protocol | additive | The public `build.yml` reusable workflow lets consumers declare one build job while Buildchain selects generic major alpha for development/prerelease intent and stable major for production release intent, with explicit overrides, separate locks, and fail-closed ambiguity handling. | |
 | 2026-07-08 | open-minor | `v2.9` | build-facts-contract | additive | Build Facts add a public CLI command family, Node API export, config protocol, module/product fact contracts, release-passport evidence section, and Kungfu legacy buildinfo projection from the same source facts. | |
 | 2026-07-06 | open-minor | `v2.8` | kfd-1-contract-world-release-gate, kfd-2-release-trust-passport-audit, kfd-3-collaboration-interface-trust-proof, publish-source-lock-enforcement, required-check-protection | additive | KFD release gates add KFD-1 self contract verification, KFD-2 public release trust claim audit, KFD-3 collaboration-interface trust proofs, publish-side source-lock enforcement for promote-only wrappers, and protected channel required checks repaired to bind GitHub Actions check runs instead of legacy commit status contexts. | |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "2.12.9-alpha.1",
+  "version": "2.13.0-alpha.1",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",
@@ -16,6 +16,7 @@
     "./build-facts": "./packages/core/build-facts.js",
     "./core": "./packages/core/index.js",
     "./artifact-passport": "./packages/core/artifact-passport.js",
+    "./artifact-verification-envelope": "./packages/core/artifact-verification-envelope.js",
     "./buildchain-contract": "./packages/core/buildchain-contract.js",
     "./controller-evidence": "./packages/core/controller-evidence.js",
     "./diagnostics": "./packages/core/diagnostics.js",

package/packages/core/README.md

@@ -16,6 +16,8 @@ Current shared surfaces:
   `@kungfu-tech/buildchain/build-facts`;
 - release passport creation and verification through
   `@kungfu-tech/buildchain/release-passport`.
+- sealed exact-root and KFD assessment inputs for KFX admission through
+  `@kungfu-tech/buildchain/artifact-verification-envelope`.
 - managed KFD / Release Passport badge bundle facts and README marker blocks
   through `@kungfu-tech/buildchain/badges`.
 - publication artifact manifests, source bundles, and publication artifact
@@ -66,6 +68,17 @@ const fact = collectModuleBuildFacts({ moduleId: "native-core" });
 writeBuildFacts({ fact, output: ".buildchain/facts/native-core.json" });
 ```
 
+KFX producers can seal one passing artifact verification with exact roots,
+identity, lifecycle, revocation, and an existing ADR-0052 assessment. Consumers
+verify or project the same envelope instead of reconstructing bindings:
+
+```js
+import {
+  projectArtifactVerificationEnvelopeToKfx,
+  verifyArtifactVerificationEnvelope,
+} from "@kungfu-tech/buildchain/artifact-verification-envelope";
+```
+
 Publication repositories can produce site-consumable paper/report facts without
 becoming web-surface repositories. When `[publication.archive]` is configured,
 the same API also maintains the append-only publication registry used by site

package/packages/core/artifact-passport.js

@@ -3,6 +3,7 @@ import fs from "node:fs";
 import http from "node:http";
 import https from "node:https";
 import path from "node:path";
+import { sealArtifactVerificationReport } from "./artifact-verification-envelope.js";
 import { readJsonFromLocation, sha256File, verifyReleasePassport } from "./release-passport.js";
 
 export const ARTIFACT_VERIFICATION_CONTRACT = "kungfu-buildchain-artifact-verification";
@@ -708,6 +709,7 @@ export async function verifyArtifactPassport({
   subjectDigest = "",
   subjectKind = "",
   npmRegistryBaseUrl = "",
+  verificationEnvelope = undefined,
 } = {}) {
   const resolvedSubject = await resolveArtifactSubject(subject, { cwd, subjectDigest, subjectKind, npmRegistryBaseUrl });
   const issues = [];
@@ -789,7 +791,7 @@ export async function verifyArtifactPassport({
   }
   const ok = passportReport.ok && Boolean(match);
   const outcome = ok ? "pass" : "fail";
-  return {
+  const report = {
     schemaVersion: 1,
     contract: ARTIFACT_VERIFICATION_CONTRACT,
     outcome,
@@ -817,6 +819,9 @@ export async function verifyArtifactPassport({
       : undefined,
     issues,
   };
+  return verificationEnvelope
+    ? sealArtifactVerificationReport({ report, ...verificationEnvelope })
+    : report;
 }
 
 export async function explainArtifactPassport(options = {}) {

package/packages/core/artifact-verification-envelope.js

@@ -0,0 +1,386 @@
+import crypto from "node:crypto";
+
+export const ARTIFACT_VERIFICATION_ENVELOPE_CONTRACT =
+  "kungfu-buildchain-artifact-verification-envelope";
+export const ARTIFACT_VERIFICATION_ENVELOPE_CHECK_CONTRACT =
+  "kungfu-buildchain-artifact-verification-envelope-check";
+export const KFX_ADMISSION_INPUTS_CONTRACT =
+  "kungfu-buildchain-kfx-admission-inputs";
+
+const ARTIFACT_VERIFICATION_CONTRACT =
+  "kungfu-buildchain-artifact-verification";
+const KFX_TRUST_INPUTS_SCHEMA = "kungfu.kfx-trust-inputs/v1";
+const KFD_ASSESSMENT_SCHEMA = "kungfu.trust.assessment/v1";
+const SHA256_PATTERN = /^sha256:[0-9a-f]{64}$/;
+const ROOT_FIELDS = Object.freeze([
+  "packageRoot",
+  "sourceRoot",
+  "dependencyRoot",
+  "buildPlanRoot",
+  "toolchainRoot",
+  "artifactRoot",
+  "qualificationRoot",
+  "verifierRoot",
+]);
+const BINDING_FIELDS = Object.freeze([
+  "schema",
+  ...ROOT_FIELDS,
+  "issuer",
+  "publisher",
+  "contractVersion",
+]);
+
+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);
+}
+
+function jsonClone(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
+export function artifactVerificationEnvelopeDigest(value) {
+  return `sha256:${crypto.createHash("sha256").update(stableJson(value)).digest("hex")}`;
+}
+
+function issue(code, message, details = {}) {
+  return { level: "error", code, message, details };
+}
+
+function isObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function isRoot(value) {
+  return SHA256_PATTERN.test(String(value || ""));
+}
+
+function nonEmptyString(value, label) {
+  const normalized = String(value || "").trim();
+  if (!normalized) {
+    throw new Error(`${label} must be a non-empty string`);
+  }
+  return normalized;
+}
+
+function nonNegativeInteger(value, label) {
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw new Error(`${label} must be a non-negative safe integer`);
+  }
+  return value;
+}
+
+function normalizeBindings(value = {}) {
+  if (!isObject(value)) {
+    throw new Error("bindings must be an object");
+  }
+  const supplied = Object.keys(value).sort();
+  const expected = [...BINDING_FIELDS].sort();
+  if (stableJson(supplied) !== stableJson(expected)) {
+    throw new Error(`bindings must contain exactly: ${BINDING_FIELDS.join(", ")}`);
+  }
+  if (value.schema !== KFX_TRUST_INPUTS_SCHEMA) {
+    throw new Error(`bindings.schema must be ${KFX_TRUST_INPUTS_SCHEMA}`);
+  }
+  const normalized = { schema: KFX_TRUST_INPUTS_SCHEMA };
+  for (const field of ROOT_FIELDS) {
+    const root = String(value[field] || "");
+    if (!isRoot(root)) {
+      throw new Error(`bindings.${field} must be a canonical lowercase sha256 root`);
+    }
+    normalized[field] = root;
+  }
+  normalized.issuer = nonEmptyString(value.issuer, "bindings.issuer");
+  normalized.publisher = nonEmptyString(value.publisher, "bindings.publisher");
+  normalized.contractVersion = nonEmptyString(value.contractVersion, "bindings.contractVersion");
+  return normalized;
+}
+
+function normalizeRevocation(value = {}, { issuedAt } = {}) {
+  if (!isObject(value)) {
+    throw new Error("revocation must be an object");
+  }
+  const revoked = value.revoked === true;
+  const status = nonEmptyString(value.status || (revoked ? "revoked" : "active"), "revocation.status");
+  if (!new Set(["active", "revoked"]).has(status) || revoked !== (status === "revoked")) {
+    throw new Error("revocation.status must agree with revocation.revoked");
+  }
+  const checkedAt = nonNegativeInteger(value.checkedAt ?? issuedAt, "revocation.checkedAt");
+  const root = String(value.root || "");
+  if (!isRoot(root)) {
+    throw new Error("revocation.root must be a canonical lowercase sha256 root");
+  }
+  return {
+    status,
+    revoked,
+    checkedAt,
+    source: nonEmptyString(value.source, "revocation.source"),
+    root,
+  };
+}
+
+function envelopeRoot(value) {
+  const basis = jsonClone(value);
+  if (isObject(basis.envelope)) {
+    delete basis.envelope.root;
+  }
+  return artifactVerificationEnvelopeDigest(basis);
+}
+
+function recomputeKfdReportRoot(report) {
+  const basis = jsonClone(report);
+  delete basis.report_hash;
+  return artifactVerificationEnvelopeDigest(basis);
+}
+
+export function verifyArtifactVerificationEnvelope({
+  envelope,
+  assessmentTime = Math.floor(Date.now() / 1000),
+  expectedEnvelopeRoot = "",
+  expectedIssuer = "",
+  expectedPublisher = "",
+  expectedContractVersion = "",
+} = {}) {
+  const issues = [];
+  const at = Number.isSafeInteger(assessmentTime) && assessmentTime >= 0
+    ? assessmentTime
+    : -1;
+  if (!isObject(envelope)) {
+    issues.push(issue("envelope.object", "artifact verification envelope must be an object"));
+    return {
+      schemaVersion: 1,
+      contract: ARTIFACT_VERIFICATION_ENVELOPE_CHECK_CONTRACT,
+      ok: false,
+      outcome: "fail",
+      assessmentTime,
+      issues,
+    };
+  }
+
+  const metadata = isObject(envelope.envelope) ? envelope.envelope : {};
+  if (
+    metadata.contract !== ARTIFACT_VERIFICATION_ENVELOPE_CONTRACT ||
+    metadata.schemaVersion !== 1 ||
+    metadata.canonicalization !== "buildchain-stable-json/v1"
+  ) {
+    issues.push(issue("envelope.contract", "artifact verification envelope contract metadata is invalid"));
+  }
+  const computedEnvelopeRoot = envelopeRoot(envelope);
+  if (!isRoot(metadata.root) || metadata.root !== computedEnvelopeRoot) {
+    issues.push(issue("envelope.root", "artifact verification envelope root does not match canonical content", {
+      expected: computedEnvelopeRoot,
+      actual: metadata.root || "",
+    }));
+  }
+  if (expectedEnvelopeRoot && metadata.root !== expectedEnvelopeRoot) {
+    issues.push(issue("envelope.root.expected", "artifact verification envelope root does not match the pinned root"));
+  }
+
+  const verificationOk =
+    envelope.contract === ARTIFACT_VERIFICATION_CONTRACT &&
+    envelope.schemaVersion === 1 &&
+    envelope.outcome === "pass" &&
+    envelope.ok === true &&
+    envelope.trust === "pass" &&
+    envelope.passport?.verification?.ok === true &&
+    envelope.passport?.verification?.trust === "pass";
+  if (!verificationOk) {
+    issues.push(issue("verification.invalid", "base artifact verification must be a passing v1 report"));
+  }
+
+  let bindings;
+  try {
+    bindings = normalizeBindings(envelope.bindings);
+  } catch (error) {
+    issues.push(issue("bindings.invalid", error.message));
+  }
+  if (bindings) {
+    const subjectRoot = String(envelope.subject?.digest || "");
+    const matchedRoot = String(envelope.match?.artifact?.digest || "");
+    if (
+      !isRoot(subjectRoot) ||
+      subjectRoot !== matchedRoot ||
+      bindings.artifactRoot !== subjectRoot
+    ) {
+      issues.push(issue("bindings.artifactRoot", "artifact root must match the exact verified subject and passport artifact"));
+    }
+    if (expectedIssuer && bindings.issuer !== expectedIssuer) {
+      issues.push(issue("bindings.issuer", "issuer does not match the expected authority"));
+    }
+    if (expectedPublisher && bindings.publisher !== expectedPublisher) {
+      issues.push(issue("bindings.publisher", "publisher does not match the expected identity"));
+    }
+    if (expectedContractVersion && bindings.contractVersion !== expectedContractVersion) {
+      issues.push(issue("bindings.contractVersion", "verification contract version does not match the expected version"));
+    }
+  }
+
+  const issuedAt = envelope.issuedAt;
+  const expiresAt = envelope.expiresAt;
+  if (
+    at < 0 ||
+    !Number.isSafeInteger(issuedAt) ||
+    issuedAt < 0 ||
+    !Number.isSafeInteger(expiresAt) ||
+    expiresAt <= issuedAt ||
+    at < issuedAt ||
+    at >= expiresAt
+  ) {
+    issues.push(issue("lifecycle.invalid", "envelope must be active at assessmentTime with valid issuedAt/expiresAt bounds"));
+  }
+  const revocation = envelope.revocation;
+  if (
+    !isObject(revocation) ||
+    !isRoot(revocation.root) ||
+    !Number.isSafeInteger(revocation.checkedAt) ||
+    revocation.checkedAt < issuedAt ||
+    (at >= 0 && revocation.checkedAt > at) ||
+    !["active", "revoked"].includes(revocation.status) ||
+    revocation.revoked !== (revocation.status === "revoked") ||
+    envelope.revoked !== revocation.revoked
+  ) {
+    issues.push(issue("lifecycle.revocation", "revocation binding is invalid or inconsistent"));
+  }
+  if (envelope.revoked === true) {
+    issues.push(issue("lifecycle.revoked", "artifact verification envelope has been revoked"));
+  }
+
+  const assessment = envelope.kfdAssessment;
+  const report = isObject(assessment?.report) ? assessment.report : {};
+  if (
+    !isObject(assessment) ||
+    assessment.schema !== KFD_ASSESSMENT_SCHEMA ||
+    assessment.state !== "fresh" ||
+    report.state !== "fresh"
+  ) {
+    issues.push(issue("kfd.assessment.state", "KFD assessment must be a fresh ADR-0052 assessment"));
+  }
+  if (
+    !isRoot(assessment?.assessment_key) ||
+    report.assessment_key !== assessment?.assessment_key
+  ) {
+    issues.push(issue("kfd.assessment.key", "KFD assessment key must be canonical and match the report"));
+  }
+  const computedReportRoot = isObject(report) ? recomputeKfdReportRoot(report) : "";
+  if (!isRoot(report.report_hash) || report.report_hash !== computedReportRoot) {
+    issues.push(issue("kfd.report.root", "KFD report hash does not match canonical report content", {
+      expected: computedReportRoot,
+      actual: report.report_hash || "",
+    }));
+  }
+  if (
+    !String(report.purpose || "").trim() ||
+    !isRoot(report.query_proof_root) ||
+    !isRoot(report.contract_world?.root) ||
+    !isRoot(report.policy?.root) ||
+    !Array.isArray(report.fact_surfaces) ||
+    report.fact_surfaces.length === 0 ||
+    report.fact_surfaces.some((surface) => !isRoot(surface?.root))
+  ) {
+    issues.push(issue("kfd.report.bindings", "KFD report must bind purpose, query proof, contract world, policy, and fact-surface roots"));
+  }
+  if (bindings && bindings.qualificationRoot !== report.report_hash) {
+    issues.push(issue("bindings.qualificationRoot", "qualification root must equal the KFD report hash"));
+  }
+
+  const ok = issues.length === 0;
+  return {
+    schemaVersion: 1,
+    contract: ARTIFACT_VERIFICATION_ENVELOPE_CHECK_CONTRACT,
+    ok,
+    outcome: ok ? "pass" : "fail",
+    assessmentTime,
+    envelopeRoot: metadata.root || "",
+    bindings: bindings || undefined,
+    kfdAssessment: isObject(assessment)
+      ? {
+          state: assessment.state || "",
+          assessmentKey: assessment.assessment_key || "",
+          reportRoot: report.report_hash || "",
+        }
+      : undefined,
+    issues,
+  };
+}
+
+export function sealArtifactVerificationReport({
+  report,
+  bindings,
+  kfdAssessment,
+  issuedAt,
+  expiresAt,
+  revocation,
+} = {}) {
+  if (!isObject(report)) {
+    throw new Error("report must be an artifact verification object");
+  }
+  const normalizedIssuedAt = nonNegativeInteger(issuedAt, "issuedAt");
+  const normalizedExpiresAt = nonNegativeInteger(expiresAt, "expiresAt");
+  if (normalizedExpiresAt <= normalizedIssuedAt) {
+    throw new Error("expiresAt must be greater than issuedAt");
+  }
+  const normalizedRevocation = normalizeRevocation(revocation, {
+    issuedAt: normalizedIssuedAt,
+  });
+  const result = {
+    ...jsonClone(report),
+    issuedAt: normalizedIssuedAt,
+    expiresAt: normalizedExpiresAt,
+    revoked: normalizedRevocation.revoked,
+    revocation: normalizedRevocation,
+    bindings: normalizeBindings(bindings),
+    kfdAssessment: jsonClone(kfdAssessment),
+    envelope: {
+      schemaVersion: 1,
+      contract: ARTIFACT_VERIFICATION_ENVELOPE_CONTRACT,
+      canonicalization: "buildchain-stable-json/v1",
+      root: "",
+    },
+  };
+  result.envelope.root = envelopeRoot(result);
+  const check = verifyArtifactVerificationEnvelope({
+    envelope: result,
+    assessmentTime: normalizedRevocation.checkedAt,
+  });
+  if (!check.ok) {
+    throw new Error(`artifact verification envelope is invalid: ${check.issues.map((entry) => entry.code).join(", ")}`);
+  }
+  return result;
+}
+
+export function projectArtifactVerificationEnvelopeToKfx({
+  envelope,
+  assessmentTime = Math.floor(Date.now() / 1000),
+  expectedEnvelopeRoot = "",
+  expectedIssuer = "",
+  expectedPublisher = "",
+  expectedContractVersion = "",
+} = {}) {
+  const check = verifyArtifactVerificationEnvelope({
+    envelope,
+    assessmentTime,
+    expectedEnvelopeRoot,
+    expectedIssuer,
+    expectedPublisher,
+    expectedContractVersion,
+  });
+  if (!check.ok) {
+    throw new Error(`artifact verification envelope failed closed: ${check.issues.map((entry) => entry.code).join(", ")}`);
+  }
+  return {
+    schemaVersion: 1,
+    contract: KFX_ADMISSION_INPUTS_CONTRACT,
+    envelopeRoot: envelope.envelope.root,
+    attestation: jsonClone(envelope),
+    trustInputs: jsonClone(envelope.bindings),
+    kfdAssessment: jsonClone(envelope.kfdAssessment),
+  };
+}

package/packages/core/buildchain-config.js

@@ -1181,7 +1181,7 @@ export function getPublishContract(loadedConfig) {
   return loadedConfig?.config?.publish;
 }
 
-export function runLifecycleStage({ cwd = process.cwd(), loadedConfig, name, stage, env: extraEnv }) {
+export function runLifecycleStage({ cwd = process.cwd(), loadedConfig, name, stage, env: extraEnv, timeoutMinutes }) {
   const lifecycle = loadedConfig?.config?.lifecycle || {};
   const selected = stage || getLifecycleStage(loadedConfig, name);
   if (!selected) {
@@ -1193,7 +1193,11 @@ export function runLifecycleStage({ cwd = process.cwd(), loadedConfig, name, sta
     ...(selected.env || {}),
     ...(extraEnv || {}),
   };
-  const timeout = selected.timeoutMinutes ? selected.timeoutMinutes * 60_000 : undefined;
+  const effectiveTimeoutMinutes = selected.timeoutMinutes ?? timeoutMinutes;
+  if (effectiveTimeoutMinutes !== undefined && (!Number.isFinite(effectiveTimeoutMinutes) || effectiveTimeoutMinutes <= 0)) {
+    throw new Error("lifecycle timeoutMinutes must be a positive number");
+  }
+  const timeout = effectiveTimeoutMinutes ? effectiveTimeoutMinutes * 60_000 : undefined;
   const execOptions = {
     cwd,
     env,

package/packages/core/controller-evidence.js

@@ -344,7 +344,6 @@ export function createControllerReceipt({ plan, stages = [], evidence = [], reas
   const issues = status === "passed"
     ? missingEvidence.map((kind) => `required controller evidence is missing: ${kind}`)
     : [];
-  const qualifying = status === "passed" && plan.qualifying === true && issues.length === 0;
   const receipt = {
     schemaVersion: 1,
     contract: BUILDCHAIN_CONTROLLER_EVIDENCE_CONTRACT,
@@ -354,11 +353,11 @@ export function createControllerReceipt({ plan, stages = [], evidence = [], reas
     runtime: { ...plan.runtime },
     planDigest: plan.digest,
     status,
-    qualifying,
+    qualifying: status === "passed" && plan.qualifying === true && issues.length === 0,
     stages: normalizedStages,
     evidence: normalizedEvidence,
     issues,
-    ...(reason && !qualifying ? {
+    ...(reason ? {
       reason: {
         code: nonEmptyString(reason.code, "reason.code"),
         summary: nonEmptyString(reason.summary, "reason.summary"),