@kungfu-tech/buildchain 3.0.9-alpha.1 → 3.0.9-alpha.11

package/scripts/dev-alpha-candidate-patrol.mjs

@@ -20,6 +20,7 @@ import {
   candidateFromDecision,
   selectLatestQualifiedSource,
 } from "../packages/core/dev-alpha-candidate-selection.js";
+import { readGitHubNextDevelopmentVersionReservation } from "../packages/core/next-development-candidate-reservation.js";
 
 export { reconcileActiveReleaseTrain, selectLatestQualifiedSource };
 
@@ -617,6 +618,7 @@ export async function runDevAlphaCandidatePatrol(
     comparison,
     workflowEvidence,
     skippedNewerCommitCount,
+    versionReservation,
     qualificationError,
   } = await resolvePatrolSourceInputs({
     client,
@@ -646,6 +648,7 @@ export async function runDevAlphaCandidatePatrol(
           observedSourceHeadSha,
           skippedNewerCommitCount,
           ...(targetBaseline ? { targetBaseline } : {}),
+          ...(versionReservation ? { versionReservation } : {}),
         },
         workflowEvidence,
         requiredWorkflowPaths,
@@ -992,6 +995,20 @@ export function createGitHubChannelCandidateClient({
         targetBranch,
         parseCandidate: managedCandidateFromPullRequest,
       }),
+    async readNextDevelopmentVersionReservation({
+      reservationSha,
+      candidateSha,
+      targetVersion,
+    }) {
+      return readGitHubNextDevelopmentVersionReservation({
+        api,
+        owner,
+        repo,
+        reservationSha,
+        candidateSha,
+        targetVersion,
+      });
+    },
     async listCompletedWorkflowRuns(workflowPathValue, sourceBranch) {
       const runs = [];
       for (let page = 1; page <= 10; page += 1) {
@@ -1015,7 +1032,11 @@ export function createGitHubChannelCandidateClient({
         for (const commit of rows) {
           const commitSha = text(commit.sha);
           if (commitSha === targetSha) return commits;
-          commits.push(commitSha);
+          commits.push({
+            sha: commitSha,
+            message: text(commit.commit?.message),
+            parents: (commit.parents || []).map((parent) => text(parent.sha)),
+          });
         }
         if (rows.length < 100) return commits;
       }

package/scripts/dev-delivery-authority.mjs

@@ -0,0 +1,368 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+
+import {
+  acquireDevDeliveryLandingWarrant,
+  acquireDevDeliveryQualificationLease,
+  admitDevDeliveryMergeGroup,
+  completeDevDeliveryQualification,
+  createDevDeliveryAuthorityState,
+  heartbeatDevDeliveryLandingWarrant,
+  heartbeatDevDeliveryQualificationLease,
+  migrateDevDeliveryAuthorityState,
+  observeDevDeliveryAuthorityState,
+  recoverDevDeliveryAuthority,
+  settleDevDeliveryAuthorityCandidate,
+  submitDevDeliveryAuthorityCandidate,
+} from "../packages/core/dev-delivery-authority.js";
+import { GitHubDevDeliveryStore } from "./dev-delivery-warrant.mjs";
+
+const STATE_REF_PREFIX = "buildchain/dev-delivery-authority/";
+
+function text(value = "") {
+  return String(value ?? "").trim();
+}
+
+function positiveInteger(value, label, fallback = 0) {
+  const parsed = Number(value || fallback);
+  if (!Number.isInteger(parsed) || parsed < 1) {
+    throw new Error(`${label} must be a positive integer`);
+  }
+  return parsed;
+}
+
+function nonNegativeInteger(value, label, fallback = 0) {
+  const parsed = Number(value === undefined || value === "" ? fallback : value);
+  if (!Number.isInteger(parsed) || parsed < 0) throw new Error(`${label} must be a non-negative integer`);
+  return parsed;
+}
+
+function bool(value, fallback = false) {
+  if (value === undefined || value === null || value === "") return fallback;
+  return ["1", "true", "yes", "on"].includes(text(value).toLowerCase());
+}
+
+function repository(value) {
+  const normalized = text(value);
+  if (!/^[^/\s]+\/[^/\s]+$/.test(normalized)) {
+    throw new Error("repository must be owner/repo");
+  }
+  return normalized;
+}
+
+function branch(value) {
+  const normalized = text(value).replace(/^refs\/heads\//, "");
+  if (!/^dev\/v\d+\/v\d+\.\d+$/.test(normalized)) {
+    throw new Error("branch must be dev/vN/vN.M");
+  }
+  return normalized;
+}
+
+export function defaultDevDeliveryAuthorityStateRef(value) {
+  return `${STATE_REF_PREFIX}${branch(value).replaceAll("/", "-")}`;
+}
+
+function stateRef(value, protectedBranch) {
+  const normalized = text(value || defaultDevDeliveryAuthorityStateRef(protectedBranch)).replace(/^refs\/heads\//, "");
+  if (!normalized.startsWith(STATE_REF_PREFIX) || normalized.includes("..")) {
+    throw new Error(`state ref must remain under ${STATE_REF_PREFIX}`);
+  }
+  return normalized;
+}
+
+function identity(state, options) {
+  return {
+    candidateId: options.candidateId,
+    token: options.authorityToken,
+    generation: options.authorityGeneration,
+  };
+}
+
+function rootedList(value) {
+  if (Array.isArray(value)) return value;
+  let parsed;
+  try {
+    parsed = JSON.parse(value || "[]");
+  } catch (cause) {
+    throw new Error(`qualification domains must be a JSON array: ${cause.message}`);
+  }
+  if (!Array.isArray(parsed)) throw new Error("qualification domains must be a JSON array");
+  return parsed;
+}
+
+function transitionFor(command, state, options) {
+  if (command === "migrate") {
+    if (!options.legacyState) {
+      throw new Error("migrate requires --legacy-state <v1-queue.json>");
+    }
+    return migrateDevDeliveryAuthorityState(options.legacyState, {
+      now: options.now,
+      policy: state.policy,
+    });
+  }
+  if (command === "submit") {
+    return submitDevDeliveryAuthorityCandidate(
+      state,
+      {
+        pullRequestNumber: options.pullRequestNumber,
+        sourceHead: options.sourceHead,
+        assignmentRoot: options.assignmentRoot,
+        initiativeRoot: options.initiativeRoot,
+        sourceIdentityRoot: options.sourceIdentityRoot,
+        sourcePatchRoot: options.sourcePatchRoot,
+        sourceProofRoot: options.sourceProofRoot,
+        planRoot: options.planRoot,
+        closureRoot: options.closureRoot,
+        dependencyRoot: options.dependencyRoot,
+        toolchainRoot: options.toolchainRoot,
+        deliveryClass: options.deliveryClass,
+        qualificationDomains: rootedList(options.qualificationDomains),
+      },
+      { now: options.now },
+    );
+  }
+  if (command === "lease-qualification") {
+    return acquireDevDeliveryQualificationLease(state, {
+      now: options.now,
+      leaseSeconds: options.leaseSeconds,
+    });
+  }
+  if (command === "complete-qualification") {
+    return completeDevDeliveryQualification(state, identity(state, options), {
+      evidenceRoot: options.evidenceRoot,
+      now: options.now,
+    });
+  }
+  if (command === "heartbeat-qualification") {
+    return heartbeatDevDeliveryQualificationLease(state, identity(state, options), {
+      now: options.now,
+      leaseSeconds: options.leaseSeconds,
+    });
+  }
+  if (command === "lease-landing") {
+    return acquireDevDeliveryLandingWarrant(state, {
+      now: options.now,
+      leaseSeconds: options.leaseSeconds,
+    });
+  }
+  if (command === "heartbeat-landing") {
+    return heartbeatDevDeliveryLandingWarrant(state, identity(state, options), {
+      now: options.now,
+      leaseSeconds: options.leaseSeconds,
+    });
+  }
+  if (command === "recover") return recoverDevDeliveryAuthority(state, { now: options.now });
+  if (command === "settle") {
+    return settleDevDeliveryAuthorityCandidate(
+      state,
+      {
+        pullRequestNumber: options.pullRequestNumber,
+        sourceHead: options.sourceHead,
+        outcome: options.outcome,
+        evidenceRoot: options.evidenceRoot,
+        reason: options.reason,
+        authorityToken: options.authorityToken,
+        authorityGeneration: options.authorityGeneration,
+      },
+      { now: options.now },
+    );
+  }
+  throw new Error(`unsupported dev authority command ${command || "<empty>"}`);
+}
+
+export async function runDevDeliveryAuthorityCommand(optionsInput = {}, clientInput) {
+  const options = {
+    ...optionsInput,
+    repository: repository(optionsInput.repository),
+    branch: branch(optionsInput.branch),
+    now: new Date(optionsInput.now || Date.now()).toISOString(),
+    execute: bool(optionsInput.execute),
+  };
+  options.stateRef = stateRef(optionsInput.stateRef, options.branch);
+  const store =
+    clientInput ||
+    new GitHubDevDeliveryStore({
+      repository: options.repository,
+      token: options.token || process.env.GITHUB_TOKEN,
+      apiUrl: options.apiUrl || process.env.GITHUB_API_URL || "https://api.github.com",
+      createInitialState: ({ repository: repositoryInput, protectedBase, now }) =>
+        createDevDeliveryAuthorityState({
+          repository: repositoryInput,
+          protectedBase,
+          policy: {
+            maxQualificationLeases: positiveInteger(options.maxQualificationLeases, "maxQualificationLeases", 2),
+            qualificationLeaseSeconds: positiveInteger(options.qualificationLeaseSeconds, "qualificationLeaseSeconds", 3600),
+            landingLeaseSeconds: positiveInteger(options.landingLeaseSeconds, "landingLeaseSeconds", 900),
+            maxLandingOvertakes: nonNegativeInteger(options.maxLandingOvertakes, "maxLandingOvertakes", 2),
+            maxQualificationAttempts: positiveInteger(options.maxQualificationAttempts, "maxQualificationAttempts", 3),
+          },
+          now,
+        }),
+    });
+  const loaded = await store.read({
+    stateRef: options.stateRef,
+    protectedBase: options.branch,
+    now: options.now,
+  });
+  if (options.command === "migrate" && loaded.exists) {
+    throw new Error("migration target state ref already exists");
+  }
+  if (options.expectedOldStateRoot && loaded.queue.stateRoot !== options.expectedOldStateRoot) {
+    throw new Error(`expected-old state drift: ${loaded.queue.stateRoot} != ${options.expectedOldStateRoot}`);
+  }
+  if (options.command === "observe") {
+    return {
+      schema: "kungfu.buildchain.dev-delivery-authority-command-result/v1",
+      ok: true,
+      mode: "observe",
+      stateRef: options.stateRef,
+      stateCommit: loaded.commitSha,
+      observation: observeDevDeliveryAuthorityState(loaded.queue, {
+        now: options.now,
+      }),
+    };
+  }
+  if (options.command === "admit-merge-group") {
+    const admitted = admitDevDeliveryMergeGroup(loaded.queue, identity(loaded.queue, options), { mergeGroupHead: options.mergeGroupHead, now: options.now });
+    return {
+      schema: "kungfu.buildchain.dev-delivery-authority-command-result/v1",
+      ok: true,
+      mode: "admission-check",
+      command: options.command,
+      stateRef: options.stateRef,
+      before: {
+        commitSha: loaded.commitSha,
+        stateRoot: loaded.queue.stateRoot,
+      },
+      after: { commitSha: loaded.commitSha, stateRoot: loaded.queue.stateRoot },
+      mutationAuthorized: false,
+      mutationApplied: false,
+      ...admitted,
+      observation: observeDevDeliveryAuthorityState(loaded.queue, {
+        now: options.now,
+      }),
+    };
+  }
+  if (options.legacyStatePath) {
+    options.legacyState = JSON.parse(fs.readFileSync(path.resolve(options.legacyStatePath), "utf8"));
+  }
+  const changed = transitionFor(options.command, loaded.queue, options);
+  if (changed.state.repository !== options.repository || changed.state.protectedBase !== options.branch) {
+    throw new Error("authority transition repository or protected base drift");
+  }
+  const mutates = changed.state.stateRoot !== loaded.queue.stateRoot;
+  let write = null;
+  if (options.execute && mutates) {
+    if (options.command !== "migrate" && changed.receipt.expectedOldStateRoot !== loaded.queue.stateRoot) {
+      throw new Error("transition expected-old root does not match loaded authority");
+    }
+    write = await store.write({
+      stateRef: options.stateRef,
+      queue: changed.state,
+      expectedCommitSha: loaded.commitSha,
+      expectedStateRoot: loaded.queue.stateRoot,
+      receiptRoot: changed.receiptRoot,
+    });
+  }
+  return {
+    schema: "kungfu.buildchain.dev-delivery-authority-command-result/v1",
+    ok: true,
+    mode: options.execute ? "execute" : "plan",
+    command: options.command,
+    stateRef: options.stateRef,
+    before: { commitSha: loaded.commitSha, stateRoot: loaded.queue.stateRoot },
+    after: {
+      commitSha: write?.commitSha || loaded.commitSha,
+      stateRoot: changed.state.stateRoot,
+    },
+    mutationAuthorized: options.execute,
+    mutationApplied: Boolean(write),
+    receipt: changed.receipt,
+    receiptRoot: changed.receiptRoot,
+    lease: changed.lease || null,
+    warrant: changed.warrant || changed.state.landingWarrant || null,
+    observation: observeDevDeliveryAuthorityState(changed.state, {
+      now: options.now,
+    }),
+  };
+}
+
+function flag(args, name, fallback = "") {
+  const index = args.indexOf(`--${name}`);
+  return index === -1 ? fallback : args[index + 1] || "";
+}
+
+function hasFlag(args, name) {
+  return args.includes(`--${name}`);
+}
+
+export function devDeliveryAuthorityCliOptions(args = [], environment = process.env) {
+  const [command = "", ...rest] = args;
+  return {
+    command,
+    repository: flag(rest, "repository", environment.GITHUB_REPOSITORY),
+    branch: flag(rest, "branch", environment.BUILDCHAIN_DEV_DELIVERY_BRANCH || environment.GITHUB_BASE_REF),
+    stateRef: flag(rest, "state-ref", environment.BUILDCHAIN_DEV_AUTHORITY_STATE_REF),
+    expectedOldStateRoot: flag(rest, "expected-old", environment.BUILDCHAIN_DEV_AUTHORITY_EXPECTED_OLD),
+    pullRequestNumber: flag(rest, "pull-request", environment.BUILDCHAIN_DEV_DELIVERY_PR_NUMBER),
+    candidateId: flag(rest, "candidate-id", environment.BUILDCHAIN_DEV_DELIVERY_CANDIDATE_ID),
+    sourceHead: flag(rest, "source-head", environment.BUILDCHAIN_DEV_DELIVERY_SOURCE_HEAD),
+    assignmentRoot: flag(rest, "assignment-root", environment.BUILDCHAIN_DEV_DELIVERY_ASSIGNMENT_ROOT),
+    initiativeRoot: flag(rest, "initiative-root", environment.BUILDCHAIN_DEV_DELIVERY_INITIATIVE_ROOT),
+    sourceIdentityRoot: flag(rest, "source-identity-root", environment.BUILDCHAIN_DEV_DELIVERY_SOURCE_IDENTITY_ROOT),
+    sourcePatchRoot: flag(rest, "source-patch-root", environment.BUILDCHAIN_DEV_DELIVERY_SOURCE_PATCH_ROOT),
+    sourceProofRoot: flag(rest, "source-proof-root", environment.BUILDCHAIN_DEV_DELIVERY_SOURCE_PROOF_ROOT),
+    planRoot: flag(rest, "plan-root", environment.BUILDCHAIN_DEV_DELIVERY_PLAN_ROOT),
+    closureRoot: flag(rest, "closure-root", environment.BUILDCHAIN_DEV_DELIVERY_CLOSURE_ROOT),
+    dependencyRoot: flag(rest, "dependency-root", environment.BUILDCHAIN_DEV_DELIVERY_DEPENDENCY_ROOT),
+    toolchainRoot: flag(rest, "toolchain-root", environment.BUILDCHAIN_DEV_DELIVERY_TOOLCHAIN_ROOT),
+    legacyStatePath: flag(rest, "legacy-state", environment.BUILDCHAIN_DEV_AUTHORITY_LEGACY_STATE),
+    deliveryClass: flag(rest, "delivery-class", environment.BUILDCHAIN_DEV_DELIVERY_CLASS),
+    qualificationDomains: flag(rest, "qualification-domains", environment.BUILDCHAIN_DEV_QUALIFICATION_DOMAINS || "[]"),
+    authorityToken: flag(rest, "authority-token", environment.BUILDCHAIN_DEV_AUTHORITY_TOKEN),
+    authorityGeneration: flag(rest, "authority-generation", environment.BUILDCHAIN_DEV_AUTHORITY_GENERATION),
+    evidenceRoot: flag(rest, "evidence-root", environment.BUILDCHAIN_DEV_DELIVERY_EVIDENCE_ROOT),
+    mergeGroupHead: flag(rest, "merge-group-head", environment.BUILDCHAIN_DEV_MERGE_GROUP_HEAD),
+    outcome: flag(rest, "outcome", environment.BUILDCHAIN_DEV_DELIVERY_OUTCOME),
+    reason: flag(rest, "reason", environment.BUILDCHAIN_DEV_DELIVERY_REASON),
+    leaseSeconds: flag(rest, "lease-seconds", environment.BUILDCHAIN_DEV_AUTHORITY_LEASE_SECONDS),
+    maxQualificationLeases: flag(rest, "max-qualification-leases", environment.BUILDCHAIN_DEV_MAX_QUALIFICATION_LEASES || "2"),
+    qualificationLeaseSeconds: flag(rest, "qualification-lease-seconds", environment.BUILDCHAIN_DEV_QUALIFICATION_LEASE_SECONDS || "3600"),
+    landingLeaseSeconds: flag(rest, "landing-lease-seconds", environment.BUILDCHAIN_DEV_LANDING_LEASE_SECONDS || "900"),
+    maxLandingOvertakes: flag(rest, "max-landing-overtakes", environment.BUILDCHAIN_DEV_MAX_LANDING_OVERTAKES || "2"),
+    maxQualificationAttempts: flag(rest, "max-qualification-attempts", environment.BUILDCHAIN_DEV_MAX_QUALIFICATION_ATTEMPTS || "3"),
+    now: flag(rest, "now", environment.BUILDCHAIN_DEV_DELIVERY_NOW),
+    outputPath: flag(rest, "output", environment.BUILDCHAIN_DEV_DELIVERY_OUTPUT || ".buildchain/dev-delivery/authority-result.json"),
+    execute: hasFlag(rest, "execute"),
+    json: hasFlag(rest, "json"),
+  };
+}
+
+function usage() {
+  return "Usage: buildchain dev authority <migrate|submit|lease-qualification|heartbeat-qualification|complete-qualification|lease-landing|heartbeat-landing|recover|admit-merge-group|settle|observe> --repository <owner/repo> --branch <dev/vN/vN.M> [--qualification-domains <json>] [--legacy-state <v1-queue.json>] [--execute] [--output <file>] [--json]\n";
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  if (args.length === 0 || hasFlag(args, "help")) {
+    process.stdout.write(usage());
+    return;
+  }
+  const options = devDeliveryAuthorityCliOptions(args);
+  if (!["submit", "migrate", "lease-qualification", "heartbeat-qualification", "complete-qualification", "lease-landing", "heartbeat-landing", "recover", "admit-merge-group", "settle", "observe"].includes(options.command)) {
+    throw new Error(usage().trim());
+  }
+  const result = await runDevDeliveryAuthorityCommand(options);
+  fs.mkdirSync(path.dirname(options.outputPath), { recursive: true });
+  fs.writeFileSync(options.outputPath, `${JSON.stringify(result, null, 2)}\n`);
+  if (options.json) process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  else process.stdout.write(`Buildchain dev authority ${options.command}: ${result.mode}\nResult: ${options.outputPath}\n`);
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch((error) => {
+    console.error(`buildchain dev authority: ${error.message}`);
+    process.exit(1);
+  });
+}

package/scripts/dev-delivery-native-run.mjs

@@ -0,0 +1,235 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+import { devDeliveryContentRoot } from "../packages/core/dev-delivery-warrant.js";
+import { runDevDeliveryCommand } from "./dev-delivery-warrant.mjs";
+
+function flag(args, name, fallback = "") {
+  const index = args.indexOf(`--${name}`);
+  return index === -1 ? fallback : args[index + 1] || "";
+}
+
+function positiveInteger(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;
+}
+
+function exactRoot(value, label) {
+  const normalized = String(value || "")
+    .trim()
+    .toLowerCase();
+  if (!/^sha256:[0-9a-f]{64}$/u.test(normalized)) {
+    throw new Error(`${label} must be a sha256 content root`);
+  }
+  return normalized;
+}
+
+export async function runNativeWithHeartbeat({
+  command,
+  cwd = process.cwd(),
+  heartbeat,
+  executionBinding = {},
+  intervalMs = 30_000,
+  terminationGraceMs = 10_000,
+  terminationKillMs = 5_000,
+  spawnImpl = spawn,
+  now = () => new Date().toISOString(),
+} = {}) {
+  if (!String(command || "").trim()) {
+    throw new Error("native command is required");
+  }
+  if (typeof heartbeat !== "function") {
+    throw new Error("heartbeat callback is required");
+  }
+  const startedAt = now();
+  try {
+    await heartbeat();
+  } catch (error) {
+    throw new Error(`native heartbeat failed: ${error.message}`);
+  }
+  let heartbeatCount = 1;
+  let heartbeatError = null;
+  let heartbeatRunning = false;
+  let childExited = false;
+  let forceKillTimer = null;
+  let terminationTimer = null;
+  let rejectTermination;
+  const terminationFailure = new Promise((_, reject) => {
+    rejectTermination = reject;
+  });
+  const child = spawnImpl("bash", ["-lc", command], {
+    cwd,
+    env: process.env,
+    stdio: "inherit",
+    detached: process.platform !== "win32",
+  });
+
+  const signalChild = (signal) => {
+    if (childExited) return;
+    if (process.platform !== "win32" && Number.isInteger(child.pid)) {
+      try {
+        process.kill(-child.pid, signal);
+        return;
+      } catch {
+        // Fall through to the direct child handle for mocked or already-exiting processes.
+      }
+    }
+    child.kill(signal);
+  };
+
+  const terminateForFenceLoss = () => {
+    signalChild("SIGTERM");
+    forceKillTimer = setTimeout(() => {
+      signalChild("SIGKILL");
+      terminationTimer = setTimeout(() => {
+        if (!childExited)
+          rejectTermination(
+            new Error("native worker did not stop after fencing loss"),
+          );
+      }, terminationKillMs);
+      terminationTimer.unref?.();
+    }, terminationGraceMs);
+    forceKillTimer.unref?.();
+  };
+
+  const beat = async () => {
+    if (heartbeatRunning || heartbeatError) return;
+    heartbeatRunning = true;
+    try {
+      await heartbeat();
+      heartbeatCount += 1;
+    } catch (error) {
+      heartbeatError = error;
+      terminateForFenceLoss();
+    } finally {
+      heartbeatRunning = false;
+    }
+  };
+  const timer = setInterval(beat, intervalMs);
+  const exitPromise = new Promise((resolve, reject) => {
+    child.once("error", reject);
+    child.once("exit", (code, signal) => {
+      childExited = true;
+      resolve({ code, signal });
+    });
+  });
+  const exit = await Promise.race([exitPromise, terminationFailure]).finally(
+    () => {
+      clearInterval(timer);
+      if (forceKillTimer) clearTimeout(forceKillTimer);
+      if (terminationTimer) clearTimeout(terminationTimer);
+    },
+  );
+  while (heartbeatRunning) {
+    await new Promise((resolve) => setTimeout(resolve, 10));
+  }
+  if (heartbeatError) {
+    throw new Error(`native heartbeat failed: ${heartbeatError.message}`);
+  }
+  if (exit.code !== 0) {
+    throw new Error(
+      `native command failed with ${exit.signal || `exit ${exit.code}`}`,
+    );
+  }
+  await beat();
+  const completedAt = now();
+  const receipt = {
+    schema: "kungfu.buildchain.native-heartbeat-run-receipt/v1",
+    outcome: "succeeded",
+    commandRoot: devDeliveryContentRoot({ command }),
+    executionBindingRoot: devDeliveryContentRoot(executionBinding),
+    startedAt,
+    completedAt,
+    heartbeatCount,
+  };
+  return { ...receipt, receiptRoot: devDeliveryContentRoot(receipt) };
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const repository = flag(args, "repository", process.env.GITHUB_REPOSITORY);
+  const branch = flag(
+    args,
+    "branch",
+    process.env.BUILDCHAIN_DEV_DELIVERY_BRANCH || process.env.GITHUB_BASE_REF,
+  );
+  const command = flag(
+    args,
+    "command",
+    process.env.BUILDCHAIN_DEV_DELIVERY_NATIVE_COMMAND,
+  );
+  const cwd = path.resolve(
+    flag(args, "working-directory", process.env.GITHUB_WORKSPACE),
+  );
+  const fencingToken = exactRoot(
+    flag(
+      args,
+      "fencing-token",
+      process.env.BUILDCHAIN_DEV_DELIVERY_FENCING_TOKEN,
+    ),
+    "fencingToken",
+  );
+  const leaseGeneration = positiveInteger(
+    flag(
+      args,
+      "lease-generation",
+      process.env.BUILDCHAIN_DEV_DELIVERY_LEASE_GENERATION,
+    ),
+    "leaseGeneration",
+  );
+  const leaseSeconds = positiveInteger(
+    flag(
+      args,
+      "lease-seconds",
+      process.env.BUILDCHAIN_DEV_DELIVERY_LEASE_SECONDS,
+    ),
+    "leaseSeconds",
+    3600,
+  );
+  const heartbeatSeconds = positiveInteger(
+    flag(
+      args,
+      "heartbeat-seconds",
+      process.env.BUILDCHAIN_DEV_DELIVERY_HEARTBEAT_SECONDS,
+    ),
+    "heartbeatSeconds",
+    Math.max(15, Math.floor(leaseSeconds / 3)),
+  );
+  if (heartbeatSeconds >= leaseSeconds) {
+    throw new Error("heartbeatSeconds must be less than leaseSeconds");
+  }
+  const output = path.resolve(
+    flag(args, "output", ".buildchain/dev-delivery/native-heartbeat-run.json"),
+  );
+  const result = await runNativeWithHeartbeat({
+    command,
+    cwd,
+    intervalMs: heartbeatSeconds * 1000,
+    heartbeat: async () => {
+      await runDevDeliveryCommand({
+        command: "heartbeat",
+        repository,
+        branch,
+        fencingToken,
+        leaseGeneration,
+        leaseSeconds,
+        execute: true,
+      });
+    },
+  });
+  fs.mkdirSync(path.dirname(output), { recursive: true });
+  fs.writeFileSync(output, `${JSON.stringify(result, null, 2)}\n`);
+  process.stdout.write(`Native heartbeat run: ${result.receiptRoot}\n`);
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch((error) => {
+    console.error(`buildchain dev native: ${error.message}`);
+    process.exit(1);
+  });
+}