@kungfu-tech/buildchain 4.0.1-alpha.6 → 4.0.1-alpha.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "4.0.1-alpha.6",
+  "version": "4.0.1-alpha.9",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",
@@ -25,6 +25,7 @@
     "./buildchain-contract": "./packages/core/buildchain-contract.js",
     "./compatibility-fact-authority": "./packages/core/buildchain-compatibility-proof.js",
     "./candidate-timeline": "./packages/core/candidate-timeline.js",
+    "./ci-lane-change-budget": "./packages/core/ci-lane-change-budget.js",
     "./channel-candidate": "./packages/core/channel-candidate.js",
     "./cache-evidence": "./packages/core/cache-evidence.js",
     "./controller-evidence": "./packages/core/controller-evidence.js",
@@ -150,7 +151,7 @@
   "scripts": {
     "precheck:static": "prettier --check architecture/decisions/0003-two-phase-delivery-warrant.md architecture/v4-delivery-authority-parity.json contracts/dev-delivery-authority-v2.schema.json dist/site/schemas/dev-delivery-authority-v2.schema.json docs/dev-delivery-qualification-landing-adr.md packages/core/dev-delivery-authority-candidate.js packages/core/dev-delivery-authority-evidence.js packages/core/dev-delivery-authority-landing.js packages/core/dev-delivery-authority-observation.js packages/core/dev-delivery-authority-qualification.js packages/core/dev-delivery-authority-settlement.js packages/core/dev-delivery-authority-state.js packages/core/dev-delivery-execution-failure.js packages/core/dev-delivery-execution-transfer.js packages/core/dev-delivery-landing-readback.js packages/core/dev-delivery-landing-terminal-evidence.js packages/core/dev-delivery-landing-testing-port.js packages/core/dev-delivery-native-execution.js packages/core/dev-delivery-native-proof.js packages/core/dev-delivery-process-boundary.js packages/core/dev-delivery-warrant-qualification.js packages/core/dev-delivery-warrant-state.js scripts/dev-delivery-authority-command-adapters.mjs scripts/dev-delivery-authority-provider.mjs scripts/dev-delivery-authority.mjs scripts/dev-delivery-native-run.mjs scripts/dev-delivery-process-boundary.mjs scripts/dev-delivery-two-phase-resume.mjs scripts/dev-delivery-two-phase.mjs scripts/dev-delivery-warrant-options.mjs scripts/dev-delivery-warrant-store.mjs templates/native-dev-delivery.yml",
     "operator:windows-jit": "bash scripts/aws-windows-jit-operator.sh",
-    "check": "pnpm run check:static && node scripts/check-v4-public-dogfood-contract.mjs && node scripts/check-v4-floating-consumer-policy-contract.mjs && pnpm run check:v4-bridge && pnpm run check:v4-contracts && node scripts/check-maintainability.mjs && node scripts/check-internal-architecture.mjs && node scripts/check-inventory.mjs && node scripts/check-core-mechanism-inventory.mjs && node scripts/check-release-tail-contract.mjs && node scripts/v4-publication-rehearsal-fixture.mjs --check && node scripts/v4-architecture.mjs validate && node scripts/v4-warrant-shadow-plan.mjs validate && pnpm run check:site && pnpm run check:workflows && pnpm run test:unit && pnpm run check:golden-path && node scripts/check-action-bundles.mjs",
+    "check": "pnpm run check:static && node scripts/check-ci-lane-change-budget.mjs && node scripts/check-v4-public-dogfood-contract.mjs && node scripts/check-v4-floating-consumer-policy-contract.mjs && pnpm run check:v4-bridge && pnpm run check:v4-contracts && node scripts/check-maintainability.mjs && node scripts/check-internal-architecture.mjs && node scripts/check-inventory.mjs && node scripts/check-core-mechanism-inventory.mjs && node scripts/check-release-tail-contract.mjs && node scripts/v4-publication-rehearsal-fixture.mjs --check && node scripts/v4-architecture.mjs validate && node scripts/v4-warrant-shadow-plan.mjs validate && pnpm run check:site && pnpm run check:workflows && pnpm run test:unit && pnpm run check:golden-path && node scripts/check-action-bundles.mjs",
     "check:static": "node scripts/check-javascript-syntax.mjs && prettier --check architecture/*.json contracts/release-tail-provider-bindings-v1.schema.json contracts/v4-canonical-contracts-v1.schema.json contracts/v4-compatibility-facts-v1.schema.json contracts/v4-delivery-warrant-semantic-diff-report-v1.schema.json contracts/v4-delivery-warrant-trace-v1.schema.json contracts/v4-floating-consumer-policy-receipt-v1.schema.json contracts/v4-runtime-ref-resume-authority-v1.schema.json contracts/v4-tail-reseal-v1.schema.json contracts/v4-host-contract-v1.schema.json contracts/v4-provider-operation-journal-v1.schema.json contracts/v4-release-activation-shadow-v1.schema.json contracts/v4-stable-publication-fence-v1.schema.json contracts/v4-partial-mutation-recovery-v1.schema.json contracts/v4-stage-capsule-v1.schema.json contracts/v4-stage-capsule-store-v1.schema.json contracts/v4-stage-capsule-resume-v1.schema.json contracts/release-tail-capabilities-v1.schema.json contracts/fixtures/release-tail-capabilities-v1/*.json contracts/fixtures/v4-delivery-warrant-trace-v1/*.json contracts/fixtures/v4-floating-consumer-policy-v1/*.json contracts/fixtures/v4-runtime-ref-resume-authority-v1/*.json contracts/fixtures/v4-tail-reseal-v1/*.json contracts/fixtures/v4-compatibility-facts-v1/*.json contracts/fixtures/v4-provider-operation-journal-v1/*.json contracts/fixtures/v4-provider-readback-idempotency-v1/*.json contracts/fixtures/v4-release-activation-shadow-v1/*.json contracts/fixtures/v4-stable-publication-fence-v1/*.json contracts/fixtures/v4-partial-mutation-recovery-v1/*.json contracts/fixtures/v4-stage-capsule-v1/*.json contracts/fixtures/v4-stage-capsule-store-v1/*.json contracts/fixtures/v4-stage-capsule-resume-v1/*.json bin/internal/command-registry.mjs bin/internal/compatibility-facts-cli.mjs packages/core/v4-canonical-contracts.js packages/core/kungfu-temporal-fact.js packages/core/buildchain-compatibility-fact.js packages/core/buildchain-compatibility-authority.js packages/core/buildchain-compatibility-proof.js packages/core/v4-floating-consumer-evidence.js packages/core/v4-floating-consumer-policy.js packages/core/v4-floating-consumer-release-passport.js packages/core/v4-runtime-ref-resume-authority.js packages/core/v4-tail-reseal-contract.js packages/core/v4-tail-reseal-github.js packages/core/v4-tail-reseal-receipt.js packages/core/v4-tail-reseal.js packages/core/v4-runtime-selector-persistence.js packages/core/v4-provider-operation-journal.js packages/core/v4-provider-readback-idempotency.js packages/core/v4-release-activation-shadow.js packages/core/v4-stable-publication-fence.js packages/core/v4-partial-mutation-recovery-qualification.js packages/core/v4-stage-capsule.js packages/core/v4-stage-capsule-store.js packages/core/v4-stage-capsule-local-store.js packages/core/v4-platform-stage-checkpoints.js packages/core/v4-stage-capsule-resume-planner.js packages/core/v4-stage-capsule-qualification.js packages/core/v4-stage-capsule-qualification-campaign.js packages/core/v4-delivery-warrant-fixture-runner.js packages/core/v4-delivery-warrant-read-candidate.js packages/core/v4-delivery-warrant-semantic-diff-gate.js packages/core/v4-delivery-warrant-shadow-adapter.js scripts/authorize-promotion-runtime-override.cjs scripts/check-core-mechanism-inventory.mjs scripts/check-release-tail-contract.mjs scripts/check-javascript-syntax.mjs scripts/check-maintainability.mjs scripts/dev-pr-prequeue-guard.mjs scripts/check-v4-public-dogfood-contract.mjs scripts/maintainability-metrics.mjs scripts/public-reference.mjs scripts/site-reference-registry.mjs scripts/generate-public-reference.mjs scripts/v4-architecture.mjs scripts/v4-bridge-bootstrap.mjs scripts/v4-bridge-evidence.mjs scripts/v4-consumer-policy.mjs scripts/v4-host-adapter.mjs scripts/v4-platform-stage-checkpoint-rehearsal.mjs scripts/v4-stage-capsule-resume-rehearsal.mjs scripts/v4-stage-capsule-qualification.mjs scripts/v4-tail-reseal-macos-rehearsal.mjs scripts/v4-tail-reseal.mjs scripts/v4-warrant-shadow-plan.mjs scripts/verify-golden-path.mjs tests/authorize-promotion-runtime-override.test.mjs tests/command-registry.test.mjs tests/core-mechanism-inventory.test.mjs tests/release-tail-contract.test.mjs tests/maintainability.test.mjs tests/promotion-responsibilities.test.mjs tests/public-reference.test.mjs tests/v4-architecture.test.mjs tests/v4-bridge.test.mjs tests/v4-canonical-contracts.test.mjs tests/v4-delivery-warrant-fixture-runner.test.mjs tests/v4-delivery-warrant-read-candidate.test.mjs tests/v4-floating-consumer-policy.test.mjs tests/v4-runtime-ref-resume-authority.test.mjs tests/v4-tail-reseal.test.mjs tests/v4-tail-reseal-parity.test.mjs tests/v4-compatibility-facts.test.mjs tests/v4-platform-stage-checkpoints.test.mjs tests/v4-provider-operation-journal.test.mjs tests/v4-provider-readback-idempotency.test.mjs tests/v4-public-dogfood-contract.test.mjs tests/v4-release-activation-shadow.test.mjs tests/v4-stable-publication-fence.test.mjs tests/v4-partial-mutation-recovery-qualification.test.mjs tests/v4-stage-capsule.test.mjs tests/v4-stage-capsule-store.test.mjs tests/v4-stage-capsule-resume-planner.test.mjs tests/v4-stage-capsule-qualification.test.mjs tests/v4-warrant-shadow-plan.test.mjs",
     "check:v4-bridge": "cargo fmt --manifest-path crates/buildchain-v4-bridge/Cargo.toml -- --check && cargo clippy --locked --manifest-path crates/buildchain-v4-bridge/Cargo.toml -- -D warnings && cargo test --locked --manifest-path crates/buildchain-v4-bridge/Cargo.toml",
     "check:v4-contracts": "cargo fmt --manifest-path crates/buildchain-v4-contracts/Cargo.toml -- --check && cargo clippy --locked --manifest-path crates/buildchain-v4-contracts/Cargo.toml -- -D warnings && cargo test --locked --manifest-path crates/buildchain-v4-contracts/Cargo.toml && node --test tests/v4-canonical-contracts.test.mjs tests/v4-delivery-warrant-fixture-runner.test.mjs tests/v4-delivery-warrant-read-candidate.test.mjs tests/v4-floating-consumer-policy-contract.test.mjs tests/v4-floating-consumer-policy.test.mjs tests/v4-runtime-ref-resume-authority.test.mjs tests/v4-tail-reseal.test.mjs tests/v4-tail-reseal-parity.test.mjs tests/v4-compatibility-facts.test.mjs tests/v4-publication-rehearsal.test.mjs tests/v4-platform-stage-checkpoints.test.mjs tests/v4-provider-operation-journal.test.mjs tests/v4-provider-readback-idempotency.test.mjs tests/v4-public-dogfood-contract.test.mjs tests/v4-release-activation-shadow.test.mjs tests/v4-stable-publication-fence.test.mjs tests/v4-partial-mutation-recovery-qualification.test.mjs tests/v4-stage-capsule.test.mjs tests/v4-stage-capsule-store.test.mjs tests/v4-stage-capsule-resume-planner.test.mjs tests/v4-stage-capsule-qualification.test.mjs",

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

@@ -29,6 +29,7 @@ const DESCRIPTORS = Object.freeze([
   [".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-recovery.yml", "governance-write"],
   [".github/workflows/buildchain-ref-promotion.yml", "governance-write"],
   [".github/workflows/buildchain-stable-candidate-patrol.yml", "governance-write"],
   [".github/workflows/dev-qualification-patrol.yml", "governance-write"],

package/packages/core/ci-lane-change-budget.js

@@ -0,0 +1,247 @@
+import crypto from "node:crypto";
+import { parseWorkflowDocument } from "./workflow-yaml-contract.js";
+
+export const CI_LANE_CHANGE_BUDGET_CONTRACT =
+  "buildchain.ci-lane-change-budget/v1";
+
+const AUTHORITY_CLASSES = new Set([
+  "merge-critical-required",
+  "merge-critical-admission",
+  "post-merge-advisory",
+  "diagnostic",
+  "evidence",
+  "release",
+]);
+const TRIGGER_CLASSES = new Set([
+  "merge-group",
+  "pull-request",
+  "push",
+  "scheduled",
+  "manual",
+  "reusable",
+  "release",
+  "mixed",
+]);
+const CONCURRENCY_MODES = new Set([
+  "none",
+  "ref-scoped",
+  "workflow-scoped",
+  "serialized",
+]);
+const CANCELLATION_BEHAVIORS = new Set([
+  "cancel-stale",
+  "finish-started",
+  "provider-default",
+  "not-applicable",
+]);
+
+function canonical(value) {
+  if (Array.isArray(value)) return value.map(canonical);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.keys(value)
+        .sort()
+        .map((key) => [key, canonical(value[key])]),
+    );
+  }
+  return value;
+}
+
+function root(value) {
+  return `sha256:${crypto
+    .createHash("sha256")
+    .update(JSON.stringify(canonical(value)))
+    .digest("hex")}`;
+}
+
+function triggerClass(triggers) {
+  const classes = new Set();
+  for (const trigger of triggers) {
+    if (trigger === "merge_group") classes.add("merge-group");
+    else if (trigger.startsWith("pull_request")) classes.add("pull-request");
+    else if (trigger === "push") classes.add("push");
+    else if (trigger === "schedule") classes.add("scheduled");
+    else if (trigger === "workflow_dispatch") classes.add("manual");
+    else if (trigger === "workflow_call") classes.add("reusable");
+    else if (trigger === "release") classes.add("release");
+    else classes.add("mixed");
+  }
+  return classes.size === 1 ? [...classes][0] : "mixed";
+}
+
+function diagnostic(code, laneId, message) {
+  return { code, laneId, message };
+}
+
+function validateDeclaration(declaration, observed) {
+  const laneId = String(declaration?.laneId || "");
+  const diagnostics = [];
+  if (!AUTHORITY_CLASSES.has(declaration?.authorityClass)) {
+    diagnostics.push(
+      diagnostic(
+        "invalid-authority-class",
+        laneId,
+        "authorityClass must identify the lane's merge or non-merge authority",
+      ),
+    );
+  }
+  if (!TRIGGER_CLASSES.has(declaration?.triggerClass)) {
+    diagnostics.push(
+      diagnostic(
+        "invalid-trigger-class",
+        laneId,
+        "triggerClass must identify the workflow trigger class",
+      ),
+    );
+  } else if (observed && declaration.triggerClass !== observed.triggerClass) {
+    diagnostics.push(
+      diagnostic(
+        "trigger-class-mismatch",
+        laneId,
+        `declared ${declaration.triggerClass}, observed ${observed.triggerClass}`,
+      ),
+    );
+  }
+  const concurrency = declaration?.concurrencyPolicy;
+  if (
+    !concurrency ||
+    !CONCURRENCY_MODES.has(concurrency.mode) ||
+    typeof concurrency.cancelInProgress !== "boolean"
+  ) {
+    diagnostics.push(
+      diagnostic(
+        "invalid-concurrency-policy",
+        laneId,
+        "concurrencyPolicy requires a known mode and boolean cancelInProgress",
+      ),
+    );
+  }
+  if (
+    !Number.isFinite(declaration?.expectedRunnerMinutes) ||
+    declaration.expectedRunnerMinutes <= 0
+  ) {
+    diagnostics.push(
+      diagnostic(
+        "invalid-runner-budget",
+        laneId,
+        "expectedRunnerMinutes must be greater than zero",
+      ),
+    );
+  }
+  if (!CANCELLATION_BEHAVIORS.has(declaration?.cancellationBehavior)) {
+    diagnostics.push(
+      diagnostic(
+        "invalid-cancellation-behavior",
+        laneId,
+        "cancellationBehavior must describe how stale or started work settles",
+      ),
+    );
+  }
+  const impact = declaration?.sloImpact;
+  if (
+    !impact ||
+    typeof impact.mergeCritical !== "boolean" ||
+    !String(impact.metric || "").trim() ||
+    !Number.isFinite(impact.expectedContributionSeconds) ||
+    impact.expectedContributionSeconds < 0 ||
+    !String(impact.rationale || "").trim()
+  ) {
+    diagnostics.push(
+      diagnostic(
+        "invalid-slo-impact",
+        laneId,
+        "sloImpact requires mergeCritical, metric, expectedContributionSeconds, and rationale",
+      ),
+    );
+  }
+  return diagnostics;
+}
+
+function collectLanes(workflows) {
+  const lanes = new Map();
+  for (const workflow of workflows) {
+    const workflowPath = String(workflow?.path || "").trim();
+    if (!workflowPath) throw new Error("workflow path is required");
+    const document = parseWorkflowDocument(workflow.text);
+    for (const job of document.jobs) {
+      const laneId = `${workflowPath}#${job.id}`;
+      if (lanes.has(laneId)) throw new Error(`duplicate CI lane: ${laneId}`);
+      lanes.set(laneId, {
+        laneId,
+        workflowPath,
+        jobId: job.id,
+        triggerClass: triggerClass(document.triggers),
+      });
+    }
+  }
+  return lanes;
+}
+
+export function evaluateCiLaneChangeBudget({
+  policy,
+  workflows,
+  baselineWorkflows = null,
+} = {}) {
+  if (policy?.schema !== CI_LANE_CHANGE_BUDGET_CONTRACT) {
+    throw new Error(`expected ${CI_LANE_CHANGE_BUDGET_CONTRACT}`);
+  }
+  if (!Array.isArray(workflows)) throw new Error("workflows must be an array");
+  const observed = collectLanes(workflows);
+  const baselineLaneIds = baselineWorkflows
+    ? [...collectLanes(baselineWorkflows).keys()]
+    : policy.baseline?.lanes || [];
+  const baseline = new Set(baselineLaneIds);
+  if (baseline.size !== baselineLaneIds.length) {
+    throw new Error("baseline CI lanes must be unique");
+  }
+  const declarations = new Map();
+  const diagnostics = [];
+  for (const declaration of policy.declarations || []) {
+    const laneId = String(declaration?.laneId || "").trim();
+    if (!laneId) throw new Error("CI lane declaration laneId is required");
+    if (declarations.has(laneId))
+      throw new Error(`duplicate CI lane declaration: ${laneId}`);
+    declarations.set(laneId, declaration);
+    if (!observed.has(laneId)) {
+      diagnostics.push(
+        diagnostic(
+          "stale-declaration",
+          laneId,
+          "declared CI lane is absent from the current workflow cut",
+        ),
+      );
+    }
+    diagnostics.push(
+      ...validateDeclaration(declaration, observed.get(laneId) || null),
+    );
+  }
+  const newLanes = [...observed.keys()]
+    .filter((laneId) => !baseline.has(laneId))
+    .sort();
+  for (const laneId of newLanes) {
+    if (!declarations.has(laneId)) {
+      diagnostics.push(
+        diagnostic(
+          "undeclared-new-lane",
+          laneId,
+          "new CI lane must declare authority, trigger, concurrency, runner, cancellation, and SLO budgets",
+        ),
+      );
+    }
+  }
+  const result = {
+    schema: "buildchain.ci-lane-change-budget.evaluation/v1",
+    ok: diagnostics.length === 0,
+    observedLaneCount: observed.size,
+    baselineLaneCount: baseline.size,
+    newLaneCount: newLanes.length,
+    declaredLaneCount: declarations.size,
+    newLanes,
+    diagnostics: diagnostics.sort((left, right) =>
+      `${left.laneId}:${left.code}`.localeCompare(
+        `${right.laneId}:${right.code}`,
+      ),
+    ),
+  };
+  return { ...result, evaluationRoot: root(result) };
+}

package/packages/core/dev-delivery-native-proof.js

@@ -43,7 +43,39 @@ export const DEV_DELIVERY_QUALIFICATION_RECEIPT_SCHEMA =
 export const NATIVE_PROOF_BASE_DELTA_SCHEMA =
   "kungfu.buildchain.native-proof-base-delta/v1";
 const NATIVE_QUALIFICATION_ROOT_SEMANTICS = "semantic-native-identity-v1";
-export function validateActiveDevDeliveryWarrant(queue) {
+
+function normalizeQualifiedWarrant(warrant, candidate, allowLegacyV3Readback) {
+  const qualifiedV3Readback =
+    allowLegacyV3Readback &&
+    !warrant.nativeCommandContract &&
+    !candidate.nativeCommandContract &&
+    !warrant.nativeExecutionReceiptRoot &&
+    !warrant.qualificationReceiptRoot;
+  warrant.nativeProofRoot = exactRoot(
+    warrant.nativeProofRoot,
+    "Warrant nativeProofRoot",
+  );
+  warrant.nativeProofReuseRoot = exactRoot(
+    warrant.nativeProofReuseRoot,
+    "Warrant nativeProofReuseRoot",
+  );
+  if (!qualifiedV3Readback) {
+    warrant.nativeExecutionReceiptRoot = exactRoot(
+      warrant.nativeExecutionReceiptRoot,
+      "Warrant nativeExecutionReceiptRoot",
+    );
+    warrant.qualificationReceiptRoot = exactRoot(
+      warrant.qualificationReceiptRoot,
+      "Warrant qualificationReceiptRoot",
+    );
+  }
+  warrant.qualifiedAt = timestamp(warrant.qualifiedAt, "Warrant qualifiedAt");
+}
+
+export function validateActiveDevDeliveryWarrant(
+  queue,
+  { allowLegacyV3Readback = false } = {},
+) {
   const warrant = queue.activeWarrant;
   if (warrant.schema !== "kungfu.buildchain.dev-delivery-warrant/v1")
     throw new Error("active Warrant schema is unsupported");
@@ -68,24 +100,17 @@ export function validateActiveDevDeliveryWarrant(queue) {
   const phase = historicalPhaseLess ? "legacy-active" : warrant.phase;
   if (!["legacy-active", "provisional", "qualified"].includes(phase))
     throw new Error("active Warrant phase is unsupported");
-  if (warrant.phase === "qualified") {
-    warrant.nativeProofRoot = exactRoot(
-      warrant.nativeProofRoot,
-      "Warrant nativeProofRoot",
-    );
-    warrant.nativeProofReuseRoot = exactRoot(
-      warrant.nativeProofReuseRoot,
-      "Warrant nativeProofReuseRoot",
-    );
-    warrant.nativeExecutionReceiptRoot = exactRoot(
-      warrant.nativeExecutionReceiptRoot,
-      "Warrant nativeExecutionReceiptRoot",
-    );
-    warrant.qualificationReceiptRoot = exactRoot(
-      warrant.qualificationReceiptRoot,
-      "Warrant qualificationReceiptRoot",
+  const active = queue.candidates.filter((candidate) =>
+    ["selected", "proving", "waiting", "blocked", "qualified"].includes(
+      candidate.status,
+    ),
+  );
+  if (active.length !== 1 || active[0].candidateId !== warrant.candidateId)
+    throw new Error(
+      "exactly one active candidate must match the active Warrant",
     );
-    warrant.qualifiedAt = timestamp(warrant.qualifiedAt, "Warrant qualifiedAt");
+  if (warrant.phase === "qualified") {
+    normalizeQualifiedWarrant(warrant, active[0], allowLegacyV3Readback);
   } else if (
     warrant.phase === "provisional" &&
     (warrant.nativeProofRoot ||
@@ -98,15 +123,6 @@ export function validateActiveDevDeliveryWarrant(queue) {
       "provisional Warrant cannot carry qualified native evidence",
     );
   }
-  const active = queue.candidates.filter((candidate) =>
-    ["selected", "proving", "waiting", "blocked", "qualified"].includes(
-      candidate.status,
-    ),
-  );
-  if (active.length !== 1 || active[0].candidateId !== warrant.candidateId)
-    throw new Error(
-      "exactly one active candidate must match the active Warrant",
-    );
   if (
     historicalPhaseLess &&
     (active[0].environmentRoot ||

package/packages/core/dev-delivery-warrant-state.js

@@ -51,8 +51,8 @@ export const TERMINAL_STATES = new Set([
   "terminal-failure",
   "dequeued",
   "cancelled",
+  "superseded",
 ]);
-
 export function issueDevDeliveryWarrant(
   queue,
   before,
@@ -158,6 +158,21 @@ function normalizePolicy(policy = {}) {
     emergencyPolicy: text(policy.emergencyPolicy || "reviewed-explicit-only"),
   };
 }
+
+function lacksLiveNativeProof(candidate, status, allowLegacyV3Readback) {
+  const { environmentRoot, nativeCommandContract } = candidate;
+  const native =
+    candidate.deliveryClass !== "non-native-fast" ||
+    environmentRoot ||
+    nativeCommandContract;
+  return (
+    native &&
+    (!environmentRoot ||
+      (!nativeCommandContract && allowLegacyV3Readback !== true)) &&
+    !TERMINAL_STATES.has(status)
+  );
+}
+
 function normalizeCandidate(input, expected) {
   const identity = createDevDeliveryCandidateIdentity(
     input,
@@ -246,9 +261,7 @@ function normalizeCandidate(input, expected) {
       "candidate shardEvidenceRoots",
     );
   }
-  const { environmentRoot: env, nativeCommandContract: cmd } = candidate;
-  const native = candidate.deliveryClass !== "non-native-fast" || env || cmd;
-  if (native && (!env || !cmd) && !TERMINAL_STATES.has(status))
+  if (lacksLiveNativeProof(candidate, status, expected.allowLegacyV3Readback))
     throw new Error("live native candidate requires exact native proof");
   if (Object.hasOwn(input, "releaseBlockerPriority"))
     candidate.releaseBlockerPriority = normalizeReleaseBlockerPriorityClaim(
@@ -318,13 +331,21 @@ export function normalizeDevDeliveryQueue(input, expected = {}) {
     "queue fencingCounter",
   );
   queue.policy = normalizePolicy(queue.policy);
+  const allowLegacyV3Readback =
+    expected.allowLegacyV3Readback === true &&
+    !(queue.candidates || []).some(
+      (candidate) => candidate?.nativeCommandContract,
+    ) &&
+    !queue.activeWarrant?.nativeCommandContract &&
+    !queue.activeWarrant?.nativeExecutionReceiptRoot &&
+    !queue.activeWarrant?.qualificationReceiptRoot;
   queue.candidates = (queue.candidates || []).map((candidate) =>
-    normalizeCandidate(candidate, queue),
+    normalizeCandidate(candidate, { ...queue, allowLegacyV3Readback }),
   );
   validateDevDeliveryCandidateChain(queue.candidates, TERMINAL_STATES);
   queue.updatedAt = timestamp(queue.updatedAt, "queue updatedAt");
   if (queue.activeWarrant) {
-    validateActiveDevDeliveryWarrant(queue);
+    validateActiveDevDeliveryWarrant(queue, { allowLegacyV3Readback });
   } else if (
     queue.candidates.some((candidate) =>
       ["selected", "proving", "waiting", "blocked", "qualified"].includes(
@@ -544,9 +565,11 @@ function effectivePriority(candidate, policy, now) {
 }
 export function rankDevDeliveryCandidates(
   queueInput,
-  { now = new Date().toISOString() } = {},
+  { now = new Date().toISOString(), allowLegacyV3Readback = false } = {},
 ) {
-  const queue = normalizeDevDeliveryQueue(queueInput);
+  const queue = normalizeDevDeliveryQueue(queueInput, {
+    allowLegacyV3Readback,
+  });
   const currentTime = timestamp(now, "now");
   return queue.candidates
     .filter((candidate) => candidate.status === "queued")

package/packages/core/dev-delivery-warrant.js

@@ -516,14 +516,19 @@ export const settleDevDeliveryTerminalEvent = createDevDeliveryTerminalSettler({
 });
 export function observeDevDeliveryQueue(
   queueInput,
-  { now = new Date().toISOString() } = {},
+  { now = new Date().toISOString(), allowLegacyV3Readback = false } = {},
 ) {
-  const queue = normalizeDevDeliveryQueue(queueInput);
+  const queue = normalizeDevDeliveryQueue(queueInput, {
+    allowLegacyV3Readback,
+  });
   const currentTime = timestamp(now, "now");
   const states = {};
   for (const candidate of queue.candidates)
     states[candidate.status] = (states[candidate.status] || 0) + 1;
-  const queued = rankDevDeliveryCandidates(queue, { now: currentTime });
+  const queued = rankDevDeliveryCandidates(queue, {
+    now: currentTime,
+    allowLegacyV3Readback,
+  });
   return {
     schema: "kungfu.buildchain.dev-delivery-queue-observation/v1",
     repository: queue.repository,

package/packages/core/github-governance-authority.js

@@ -116,6 +116,7 @@ const PROTECTED_AUTHORITY_PATHS = Object.freeze([
   ".github/CODEOWNERS",
   ".github/workflows/.publication-authority.yml",
   ".github/workflows/.release-candidate-promote.yml",
+  ".github/workflows/buildchain-ref-promotion-recovery.yml",
   ".github/workflows/buildchain-ref-promotion.yml",
   ".github/workflows/github-governance-audit.yml",
   ".github/workflows/paper-release-sealed.yml",

package/packages/core/index.js

@@ -139,6 +139,11 @@ export {
   normalizeCandidateTimelineEvent,
 } from "./candidate-timeline.js";
 
+export {
+  CI_LANE_CHANGE_BUDGET_CONTRACT,
+  evaluateCiLaneChangeBudget,
+} from "./ci-lane-change-budget.js";
+
 export {
   CHANNEL_CANDIDATE_DECISION_SCHEMA,
   channelCandidateSourceLockRef,