@kungfu-tech/buildchain 3.0.6-alpha.1 → 3.0.6-alpha.2

package/docs/release-governance.md

@@ -487,6 +487,15 @@ same slow checks. Buildchain supports GitHub merge queues for that channel
 shape. The queue validates the projected merged result and serializes the final
 ref update, so concurrent channel movement no longer invalidates the candidate.
 
+GitHub Merge Queue does not by itself decide which candidate may spend a long
+native proof before enqueue. Repositories with that workload use the
+[Dev Delivery Warrant Queue](dev-delivery-warrant.md) as the durable,
+FIFO-aging scheduling and fencing authority before native queue admission. A
+selected Warrant owns one complete delivery attempt and later candidates remain
+visibly queued; GitHub still owns the exact `merge_group` proof and final ref
+mutation. Workflow concurrency remains only a process critical section and is
+not fairness or ownership authority.
+
 Every required workflow must handle both `pull_request` and `merge_group`
 before the queue is enabled. Queue runs do not provide
 `github.event.pull_request`; required workflows must use the checked-out
@@ -545,6 +554,33 @@ inputs: target dev branch, required status/check names, ready and block labels,
 allowed work-branch prefixes, review requirements, maximum merges per run,
 merge method, and dry-run mode.
 
+Agent delivery uses the targeted Buildchain command instead of relying on a
+scheduled scan:
+
+```sh
+buildchain dev pr-admit \
+  --repository kungfu-systems/example \
+  --branch dev/v3/v3.0 \
+  --pull-request 123 \
+  --expected-head 0123456789abcdef0123456789abcdef01234567
+```
+
+The default is a mutation-free plan. After reviewing it, add `--execute` to
+establish the configured readiness label for only that PR and exact head, read
+the state back, and attempt native queue admission. Repeating execute is
+idempotent: an exact matching queue entry is adopted, not submitted again. A
+stale head or base, fork, draft, block label, missing approval, failed check,
+active predecessor, or rejected enqueue exits nonzero. Execute mode also
+creates or updates an exact-head PR comment and named commit status containing
+the current state, reason, receipt root, and copyable next action. The JSON
+receipt remains the complete content-addressed evidence.
+
+GitHub auto-merge is observed but is never readiness or admission authority.
+Approval plus green checks plus auto-merge enabled does not qualify a PR that
+lacks explicit Buildchain delivery intent. The targeted workflow interface
+exposes the same contract through `expected-pr-number` and
+`expected-head-sha`; cadence patrol runs leave those inputs empty.
+
 The workflow defaults are conservative. A PR is skipped unless it targets the
 configured dev line, is not a draft, has the ready label, has no block label,
 comes from the same repository, uses an allowed work-branch prefix, has a
@@ -565,6 +601,15 @@ admission runs; GitHub still owns the atomic queue and protected-ref update.
 Repositories may explicitly select `landing-mode: direct` only when the target
 branch has no native queue. Queue presence always disables the direct path.
 
+For slow candidates on a frequently advancing dev line, the optional
+[Dev Delivery Warrant Queue](dev-delivery-warrant.md) adds durable FIFO plus
+aging scheduling before native queue admission. It separates reusable source
+qualification from exact merge-group integration, uses expected-old Git-ref
+updates and fenced leases, and keeps the PR head unchanged when only dev moves.
+The reusable caller supports `off`, read-only `shadow`, and fail-closed
+`required` rollout modes. GitHub Merge Queue remains the final protected-ref
+authority in every mode.
+
 The canonical consumer required check context is `check / check`, matching the
 reusable workflow call plus its `check` job. Buildchain's own `Verify` workflow
 emits the repository-local context `check`, so Buildchain self-promotion,
@@ -687,6 +732,13 @@ The cadence names describe patrol intensity, not release cadence:
 - monthly patrol is for structural drift checks that should not block ordinary
   development velocity.
 
+Every cadence result is typed `runKind: cadence-patrol` with
+`qualification: false`. A run with no open candidates reports
+`no-op-no-candidates`; a run where every candidate is skipped reports
+`no-op-all-skipped`. Either no-op can keep maintenance green, but neither is a
+delivery qualification, a targeted admission receipt, or evidence that an
+expected PR entered the merge queue.
+
 Stable Candidate Patrol is separate from those maintenance cadences because its
 caller-owned cron is a release-intent window. Its candidate ledger and selection
 remain generic; registry-specific side effects still run through the normal

package/docs/reusable-build-surface.md

@@ -774,6 +774,9 @@ Direct GitHub Artifact payloads default to compression level `0`. Buildchain
 artifacts are commonly already-compressed archives; storing them without a
 second compression pass shortens the upload window while preserving the same
 artifact name, run/id/digest binding, retention, and no-overwrite behavior.
+Direct build and signed-finalization payload uploads include hidden files under
+the caller-declared artifact paths, matching the relay path so manifest-bound
+dotfiles are not silently removed in transit.
 Callers may select `1` through `9` for payloads that materially benefit from
 compression. Manifests and diagnostics retain their existing small-artifact
 behavior.
@@ -792,7 +795,14 @@ jobs:
       artifact-relay-s3-prefix: ${{ vars.BUILDCHAIN_ARTIFACT_RELAY_S3_PREFIX }}
 ```
 
-In relay mode, each self-hosted platform job uploads the heavy payload files to
+The mode is a policy for platforms that run outside GitHub. GitHub-hosted
+platforms always upload directly with `actions/upload-artifact`, even when a
+mixed matrix requests `s3-to-github-artifacts`; they never send their payloads
+through S3 or the replay job. Buildchain recognizes its hosted presets and the
+standard hosted runner labels. Custom matrices with non-standard hosted labels
+must declare `"githubHosted": true` on those platform rows.
+
+For remaining relay-mode platforms, each job uploads the heavy payload files to
 S3 and uploads only a small `relay-manifest.json` to GitHub. A GitHub-hosted
 `relay-artifacts` job then assumes the configured download role, downloads the
 payloads from S3, verifies every file by SHA256, and re-uploads the normal

package/docs/shifu-gate-profiles.md

@@ -135,7 +135,18 @@ a shell string.
 
 Projects may also pass non-sensitive scalar environment through
 `gate-environment-json`; Buildchain validates the JSON shape and forwards it
-without interpreting names or values. Cache profile references use the same
+without interpreting names or values. A custom `platforms-json` entry may add
+an `environment` object when a value is platform-specific; those scalars
+override the shared environment only for that matrix job. For example, a
+GitHub-hosted Linux lane can select an installed compiler without leaking the
+same setting into macOS or Windows:
+
+```yaml
+platforms-json: >-
+  [{"id":"linux-x64","name":"Linux x64","platform":"linux","runner":"[\"ubuntu-24.04\"]","capabilities":["node","native-toolchain"],"environment":{"CC":"gcc-14","CXX":"g++-14"}}]
+```
+
+Cache profile references use the same
 opaque `shifu-cache-profile-ref` and `shifu-cache-profile-digest` inputs as the
 reusable build. Do not place tokens, credentials, or other secrets in workflow
 inputs or Gate receipts.

package/docs/versioning.md

@@ -79,6 +79,8 @@ repository changes are patch".
 
 | Date       | Action       | Line    | Faces                                                                                                                                                                        | Class    | Rationale                                                                                                                                                                                                                                                                                                                              | PR    |
 | ---------- | ------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
+| 2026-08-05 | extend-minor | `v3.0`  | auditable-demo-scenario, auditable-demo-capture, auditable-demo-adapter                                                                                                      | additive | Add an opt-in deterministic readable-playback declaration that preserves captured terminal payloads and order while normalizing only presentation timing; omitted playback continues to use observed PTY timestamps, and existing composition modes remain unchanged.                                                                 |       |
+| 2026-08-04 | extend-minor | `v3.0`  | dev-delivery-warrant-queue, source-qualification-proof, integration-delivery-proof, dev-delivery-cli, reusable-dev-delivery-workflows                                        | additive | Add durable fair and fenced protected-dev scheduling plus split source/integration proof contracts. Existing PR admission remains available through explicit `off` and `shadow` rollout modes; no existing command, export, or release flow is removed.                                                                                |       |
 | 2026-08-01 | extend-minor | `v3.0`  | cli-reference-registry, node-api-symbol-registry, golden-path-manual                                                                                                         | additive | Add generated, drift-checked CLI and Node API reference registries to the public site bundle, plus a package-tested first-user Golden Path; existing command execution and import semantics remain unchanged.                                                                                                                          |       |
 | 2026-07-31 | extend-minor | `v3.0`  | auditable-demo-workflow, auditable-demo-media-profile, auditable-demo-media-receipt                                                                                          | additive | Add an opt-in responsive profile that binds source-resolution and exact 1280x720 MP4/WebM/GIF renditions to one Gate and receipt while rejecting upscales, aspect-ratio drift, and profile changes between Gate-only and full-render paths.                                                                                            |       |
 | 2026-07-31 | extend-minor | `v3.0`  | release-candidate-family-evidence, release-passport-evidence-attachment, promotion-action, release-passport-cli                                                              | additive | Restore all-ref v2 parity for optional Initiative-family candidate binding and typed product-owned release evidence attachments while retaining Kungfu native Family State authority and the newer v3 post-activation released-evidence stage.                                                                                         | #2089 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "3.0.6-alpha.1",
+  "version": "3.0.6-alpha.2",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",
@@ -28,6 +28,7 @@
     "./cache-evidence": "./packages/core/cache-evidence.js",
     "./controller-evidence": "./packages/core/controller-evidence.js",
     "./diagnostics": "./packages/core/diagnostics.js",
+    "./dev-delivery-warrant": "./packages/core/dev-delivery-warrant.js",
     "./homebrew": "./packages/core/homebrew.js",
     "./issue-reporting": "./packages/core/issue-reporting.js",
     "./kfd": "./packages/core/kfd.js",

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

@@ -24,6 +24,7 @@ const DESCRIPTORS = Object.freeze([
   [".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-dev-delivery.yml", "governance-write"],
   [".github/workflows/buildchain-patrol-daily.yml", "governance-write"],
   [".github/workflows/buildchain-patrol-monthly.yml", "governance-write"],
   [".github/workflows/buildchain-patrol-weekly.yml", "governance-write"],
@@ -32,6 +33,8 @@ const DESCRIPTORS = Object.freeze([
   [".github/workflows/buildchain-stable-candidate-patrol.yml", "governance-write"],
   [".github/workflows/dev-qualification-patrol.yml", "governance-write"],
   [".github/workflows/dev-alpha-candidate-patrol.yml", "governance-write"],
+  [".github/workflows/dev-delivery-warrant-close.yml", "governance-write"],
+  [".github/workflows/dev-delivery-warrant-cancel.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"],
@@ -75,7 +78,6 @@ export function buildchainPublicationAuthorityDescriptors() {
     runnerPolicy: publicationCapable ? "qualified-measured" : "unqualified",
   }));
 }
-
 export function createBuildchainPublicationAuthorityRegistry({ root = process.cwd() } = {}) {
   const workflowsDir = path.join(root, ".github", "workflows");
   const workflows = fs.readdirSync(workflowsDir)

package/packages/core/channel-candidate.js

@@ -1,6 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0
 
 import crypto from "node:crypto";
+import { normalizeChannelCandidateSelection } from "./channel-promotion-baseline.js";
 
 export const CHANNEL_CANDIDATE_DECISION_SCHEMA =
   "kungfu-buildchain-channel-candidate-decision/v1";
@@ -95,27 +96,7 @@ export function decideChannelCandidate(input) {
     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 selection = normalizeChannelCandidateSelection(input.selection);
   const now = required(input.now || new Date().toISOString(), "now");
   const maxAgeSeconds = Number(input.maxAgeSeconds ?? 7 * 24 * 60 * 60);
   if (!Number.isSafeInteger(maxAgeSeconds) || maxAgeSeconds <= 0) {

package/packages/core/channel-promotion-baseline.js

@@ -0,0 +1,199 @@
+// SPDX-License-Identifier: Apache-2.0
+
+const SHA = /^[0-9a-f]{40}$/;
+
+function text(value = "") {
+  return String(value ?? "").trim();
+}
+
+function exactSha(value, name) {
+  const normalized = text(value).toLowerCase();
+  if (!SHA.test(normalized))
+    throw new Error(`${name} must be an exact 40-character SHA`);
+  return normalized;
+}
+
+export function normalizeManagedPromotionBaseline(input) {
+  const pullRequestNumber = Number(input?.pullRequestNumber);
+  if (!Number.isSafeInteger(pullRequestNumber) || pullRequestNumber <= 0) {
+    throw new Error(
+      "targetBaseline.pullRequestNumber must be a positive integer",
+    );
+  }
+  const pullRequestUrl = text(input?.pullRequestUrl);
+  if (!pullRequestUrl)
+    throw new Error("targetBaseline.pullRequestUrl is required");
+  return {
+    mode: text(input?.mode) || "managed-candidate-merge-source",
+    targetSha: exactSha(input?.targetSha, "targetBaseline.targetSha"),
+    sourceSha: exactSha(input?.sourceSha, "targetBaseline.sourceSha"),
+    pullRequestNumber,
+    pullRequestUrl,
+  };
+}
+
+export function normalizeChannelCandidateSelection(input) {
+  if (!input) return undefined;
+  const mode = text(input.mode);
+  if (!mode) throw new Error("selection.mode is required");
+  const skippedNewerCommitCount = Number(input.skippedNewerCommitCount || 0);
+  if (
+    !Number.isSafeInteger(skippedNewerCommitCount) ||
+    skippedNewerCommitCount < 0
+  ) {
+    throw new Error(
+      "selection.skippedNewerCommitCount must be a non-negative integer",
+    );
+  }
+  return {
+    mode,
+    observedSourceHeadSha: exactSha(
+      input.observedSourceHeadSha,
+      "selection.observedSourceHeadSha",
+    ),
+    skippedNewerCommitCount,
+    ...(input.targetBaseline
+      ? {
+          targetBaseline: normalizeManagedPromotionBaseline(
+            input.targetBaseline,
+          ),
+        }
+      : {}),
+  };
+}
+
+export async function resolveChannelComparisonBaseline({
+  client,
+  targetSha,
+  targetBranch,
+  sourceSha,
+  directComparison,
+}) {
+  if (
+    directComparison.status !== "diverged" ||
+    !client.resolveManagedPromotionBaseline
+  ) {
+    return { comparison: directComparison, targetBaseline: undefined };
+  }
+  const promoted = await client.resolveManagedPromotionBaseline(
+    targetSha,
+    targetBranch,
+  );
+  if (!promoted)
+    return { comparison: directComparison, targetBaseline: undefined };
+  const comparison = await client.compare(promoted.sourceSha, sourceSha);
+  if (!["ahead", "identical"].includes(comparison.status)) {
+    return { comparison: directComparison, targetBaseline: undefined };
+  }
+  return {
+    comparison,
+    targetBaseline: normalizeManagedPromotionBaseline(promoted),
+  };
+}
+
+export async function resolvePatrolSourceInputs({
+  client,
+  options,
+  requiredWorkflowPaths,
+  selectQualifiedSource,
+}) {
+  const [observedSourceHeadSha, targetSha] = await Promise.all([
+    client.resolveBranch(options.sourceBranch),
+    client.resolveBranch(options.targetBranch),
+  ]);
+  const directComparison = await client.compare(
+    targetSha,
+    observedSourceHeadSha,
+  );
+  const { comparison: headComparison, targetBaseline } =
+    await resolveChannelComparisonBaseline({
+      client,
+      targetSha,
+      targetBranch: options.targetBranch,
+      sourceSha: observedSourceHeadSha,
+      directComparison,
+    });
+  let sourceSha = observedSourceHeadSha;
+  let comparison = headComparison;
+  let workflowEvidence = [];
+  let skippedNewerCommitCount = 0;
+  let qualificationError;
+  if (
+    headComparison.status === "ahead" &&
+    Number(headComparison.ahead_by) > 0
+  ) {
+    const boundarySha = targetBaseline?.sourceSha || targetSha;
+    const [sourceHistory, ...workflowRunSets] = await Promise.all([
+      client.listBranchHistory(options.sourceBranch, boundarySha),
+      ...requiredWorkflowPaths.map((workflow) =>
+        client.listCompletedWorkflowRuns(workflow, options.sourceBranch),
+      ),
+    ]);
+    try {
+      const selected = selectQualifiedSource({
+        sourceHistory,
+        workflowRunsByPath: new Map(
+          requiredWorkflowPaths.map((workflow, index) => [
+            workflow,
+            workflowRunSets[index],
+          ]),
+        ),
+        requiredWorkflowPaths,
+        now: options.now,
+        maxAgeSeconds: options.maxAgeSeconds,
+      });
+      ({ sourceSha, skippedNewerCommitCount, workflowEvidence } = selected);
+      if (sourceSha !== observedSourceHeadSha)
+        comparison = await client.compare(boundarySha, sourceSha);
+    } catch (error) {
+      qualificationError = error;
+    }
+  }
+  return {
+    observedSourceHeadSha,
+    targetSha,
+    headComparison,
+    targetBaseline,
+    sourceSha,
+    comparison,
+    workflowEvidence,
+    skippedNewerCommitCount,
+    qualificationError,
+  };
+}
+
+export async function resolveManagedPromotionBaseline({
+  api,
+  targetSha,
+  targetBranch,
+  parseCandidate,
+}) {
+  const commit = await api(`/git/commits/${targetSha}`);
+  const parents = Array.isArray(commit.parents) ? commit.parents : [];
+  if (text(commit.sha) !== targetSha || parents.length !== 2) return null;
+  const sourceSha = text(parents[1]?.sha);
+  if (!SHA.test(sourceSha)) return null;
+  const associated = await api(`/commits/${targetSha}/pulls`);
+  const managed = associated
+    .filter(
+      (pullRequest) =>
+        text(pullRequest.merged_at) &&
+        text(pullRequest.merge_commit_sha) === targetSha &&
+        text(pullRequest.base?.ref) === targetBranch &&
+        text(pullRequest.head?.sha) === sourceSha,
+    )
+    .map((pullRequest) => ({
+      pullRequest,
+      candidate: parseCandidate(pullRequest, targetBranch),
+    }))
+    .filter(({ candidate }) => candidate?.sourceSha === sourceSha);
+  if (managed.length > 1)
+    throw new Error(`multiple managed promotion PRs bind target ${targetSha}`);
+  if (managed.length === 0) return null;
+  return normalizeManagedPromotionBaseline({
+    targetSha,
+    sourceSha,
+    pullRequestNumber: managed[0].pullRequest.number,
+    pullRequestUrl: managed[0].pullRequest.html_url,
+  });
+}

package/packages/core/dev-delivery-candidate-identity.js

@@ -0,0 +1,94 @@
+import {
+  devDeliveryContentRoot,
+  devDeliveryExactRoot as exactRoot,
+  devDeliveryPositiveInteger as positiveInteger,
+  devDeliveryText as text,
+} from "./dev-delivery-common.js";
+
+export const CHAINED_ATTEMPT_IDENTITY = "chained-attempt-v2";
+
+export function createDevDeliveryCandidateIdentity(
+  input,
+  expected,
+  deliveryClass,
+) {
+  const identity = {
+    repository: expected.repository,
+    protectedBase: expected.protectedBase,
+    pullRequestNumber: positiveInteger(
+      input.pullRequestNumber,
+      "pullRequestNumber",
+    ),
+    assignmentRoot: exactRoot(input.assignmentRoot, "assignmentRoot"),
+    initiativeRoot: exactRoot(input.initiativeRoot, "initiativeRoot"),
+    sourceIdentityRoot: exactRoot(
+      input.sourceIdentityRoot,
+      "sourceIdentityRoot",
+    ),
+    deliveryClass: deliveryClass(input.deliveryClass),
+  };
+  if (input.identitySemantics) {
+    if (text(input.identitySemantics) !== CHAINED_ATTEMPT_IDENTITY) {
+      throw new Error(
+        `unsupported candidate identity semantics ${input.identitySemantics}`,
+      );
+    }
+    identity.identitySemantics = CHAINED_ATTEMPT_IDENTITY;
+    identity.predecessorCandidateId = exactRoot(
+      input.predecessorCandidateId,
+      "predecessorCandidateId",
+    );
+  }
+  return { ...identity, candidateId: devDeliveryContentRoot(identity) };
+}
+
+export function validateDevDeliveryCandidateChain(candidates, terminalStates) {
+  const precedingCandidates = new Map();
+  for (const candidate of candidates) {
+    if (candidate.identitySemantics === CHAINED_ATTEMPT_IDENTITY) {
+      const predecessor = precedingCandidates.get(
+        candidate.predecessorCandidateId,
+      );
+      if (!predecessor)
+        throw new Error(
+          "chained candidate predecessor must appear earlier in the queue",
+        );
+      if (predecessor.pullRequestNumber !== candidate.pullRequestNumber) {
+        throw new Error(
+          "chained candidate predecessor must belong to the same pull request",
+        );
+      }
+      if (!terminalStates.has(predecessor.status)) {
+        throw new Error("chained candidate predecessor must be terminal");
+      }
+    }
+    precedingCandidates.set(candidate.candidateId, candidate);
+  }
+}
+
+export function chainedDevDeliveryAttemptInput({
+  queue,
+  candidate,
+  input,
+  currentTime,
+  terminalStates,
+}) {
+  const predecessor = [...queue.candidates]
+    .reverse()
+    .find(
+      (entry) =>
+        entry.pullRequestNumber === candidate.pullRequestNumber &&
+        terminalStates.has(entry.status),
+    );
+  if (!predecessor) return null;
+  return {
+    ...input,
+    identitySemantics: CHAINED_ATTEMPT_IDENTITY,
+    predecessorCandidateId: predecessor.candidateId,
+    enqueuedAt: input.enqueuedAt || currentTime,
+    updatedAt: currentTime,
+    attempts: input.attempts || 1,
+    recoveries: input.recoveries || 0,
+    status: "queued",
+  };
+}

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

@@ -0,0 +1,73 @@
+import crypto from "node:crypto";
+
+const SHA_PATTERN = /^[0-9a-f]{40}$/;
+const ROOT_PATTERN = /^sha256:[0-9a-f]{64}$/;
+
+export function devDeliveryText(value = "") {
+  return String(value ?? "").trim();
+}
+
+export function devDeliveryClone(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
+function stableValue(value) {
+  if (Array.isArray(value)) return value.map(stableValue);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value)
+        .filter(([, entry]) => entry !== undefined)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, entry]) => [key, stableValue(entry)]),
+    );
+  }
+  return value;
+}
+
+export function devDeliveryContentRoot(value) {
+  return `sha256:${crypto
+    .createHash("sha256")
+    .update(`${JSON.stringify(stableValue(value))}\n`)
+    .digest("hex")}`;
+}
+
+export function devDeliveryExactRoot(value, label) {
+  const normalized = devDeliveryText(value).toLowerCase();
+  if (!ROOT_PATTERN.test(normalized)) throw new Error(`${label} must be a sha256 content root`);
+  return normalized;
+}
+
+export function devDeliveryExactSha(value, label) {
+  const normalized = devDeliveryText(value).toLowerCase();
+  if (!SHA_PATTERN.test(normalized)) throw new Error(`${label} must be a 40-character Git SHA`);
+  return normalized;
+}
+
+export function devDeliveryPositiveInteger(value, label, fallback) {
+  const parsed = Number(value ?? fallback);
+  if (!Number.isInteger(parsed) || parsed < 1) throw new Error(`${label} must be a positive integer`);
+  return parsed;
+}
+
+export function devDeliveryTimestamp(value, label) {
+  const normalized = devDeliveryText(value);
+  const milliseconds = Date.parse(normalized);
+  if (!normalized || !Number.isFinite(milliseconds)) throw new Error(`${label} must be an ISO-8601 timestamp`);
+  return new Date(milliseconds).toISOString();
+}
+
+export function devDeliveryRepository(value) {
+  const normalized = devDeliveryText(value);
+  if (!/^[^/\s]+\/[^/\s]+$/.test(normalized)) {
+    throw new Error(`repository must be owner/repo, got ${normalized || "<empty>"}`);
+  }
+  return normalized;
+}
+
+export function devDeliveryProtectedBase(value) {
+  const normalized = devDeliveryText(value).replace(/^refs\/heads\//, "");
+  if (!/^dev\/v\d+\/v\d+\.\d+$/.test(normalized)) {
+    throw new Error(`protectedBase must be dev/vN/vN.M, got ${normalized || "<empty>"}`);
+  }
+  return normalized;
+}