@kungfu-tech/buildchain 4.0.1-alpha.2 → 4.0.1-alpha.21

package/scripts/site-capability-metadata.mjs

@@ -13,6 +13,11 @@ export function cliCommandMeta(id) {
   const map = new Map(Object.entries({
     audit: { group: "release-passport-trust", purpose: "Inspect read-only publication authority audit commands." },
     architecture: { group: "governance-versioning", purpose: "Inspect and qualify the Buildchain v4 capability and state-machine architecture contract." },
+    "adopter-delivery": { group: "reusable-build", purpose: "Run public protocol-neutral adopter delivery, exact readback, N-1 bootstrap, and published archive checks." },
+    "adopter-delivery-run": { group: "reusable-build", purpose: "Run one exact public adopter driver and artifact-profile selection offline." },
+    "adopter-delivery-verify": { group: "reusable-build", purpose: "Recompute and verify exact adopter delivery readback without authority widening." },
+    "adopter-delivery-bootstrap": { group: "reusable-build", purpose: "Qualify exact v3 N-1 bootstrap lineage against the v4 adopter delivery substrate." },
+    "adopter-delivery-archive": { group: "reusable-build", purpose: "Load content-addressed public npm archive bytes and verify their exact identity and readback root." },
     "architecture-list": { group: "governance-versioning", purpose: "Generate the Agent-readable capability list from the validated v4 architecture manifest." },
     "architecture-qualify": { group: "governance-versioning", purpose: "Qualify an exact candidate against a distinct N-1 Git authority revision without candidate self-qualification." },
     "architecture-show": { group: "governance-versioning", purpose: "Generate one capability and its state-machine details from the validated v4 architecture manifest." },
@@ -39,6 +44,10 @@ export function cliCommandMeta(id) {
     "explain-artifact": { group: "release-passport-trust", purpose: "Explain artifact evidence for humans or agents." },
     "explain-release": { group: "release-passport-trust", purpose: "Explain a release passport for humans or agents." },
     facts: { group: "observability-diagnostics", purpose: "Inspect build facts command families." },
+    "facts-compatibility-project": { group: "governance-versioning", purpose: "Project legacy digest and proof views from the current Cut-bound compatibility Fact registry." },
+    "facts-compatibility-query": { group: "governance-versioning", purpose: "Verify one explicit directional compatibility path and emit a rooted receipt." },
+    "facts-compatibility-query-template": { group: "governance-versioning", purpose: "Create a direct query template for one current compatibility Fact." },
+    "facts-compatibility-verify": { group: "governance-versioning", purpose: "Verify the exact append-only compatibility Fact registry and current Cut." },
     help: { group: "getting-started", purpose: "Print Buildchain CLI help." },
     homebrew: { group: "distribution-indexes", purpose: "Inspect Homebrew distribution-index command families." },
     "homebrew-check": { group: "distribution-indexes", purpose: "Verify Homebrew tap metadata against upstream release passport evidence." },
@@ -92,6 +101,17 @@ export function cliCommandMeta(id) {
     "kfd-upstream-roles": { group: "kfd-trust", purpose: "List Buildchain-managed KFD upstream role values and inference policy." },
     lifecycle: { group: "reusable-build", purpose: "Run configured lifecycle commands and write deterministic artifact manifests." },
     dev: { group: "governance-versioning", purpose: "Inspect protected development-channel governance command families." },
+    "dev-authority-admit-merge-group": { group: "governance-versioning", purpose: "Verify that one exact candidate holds the exclusive Landing Warrant before merge_group admission." },
+    "dev-authority-complete-qualification": { group: "governance-versioning", purpose: "Bind qualification evidence and release one bounded Qualification Lease without granting landing authority." },
+    "dev-authority-heartbeat-landing": { group: "governance-versioning", purpose: "Extend the exact fenced Landing Warrant while final landing work remains live." },
+    "dev-authority-heartbeat-qualification": { group: "governance-versioning", purpose: "Extend one exact fenced Qualification Lease while qualification work remains live." },
+    "dev-authority-lease-landing": { group: "governance-versioning", purpose: "Issue or retain the single exclusive Landing Warrant for a qualified candidate." },
+    "dev-authority-lease-qualification": { group: "governance-versioning", purpose: "Issue one qualification-only lease within the configured bounded lane count." },
+    "dev-authority-migrate": { group: "governance-versioning", purpose: "Migrate one exact v1 Warrant state into v2 without rewriting candidate or fencing evidence." },
+    "dev-authority-observe": { group: "governance-versioning", purpose: "Read bounded Qualification Leases and the exclusive Landing Warrant without mutating authority." },
+    "dev-authority-recover": { group: "governance-versioning", purpose: "Recover expired qualification or Landing authority and emit one rooted wake instruction." },
+    "dev-authority-settle": { group: "governance-versioning", purpose: "Settle terminal candidate evidence idempotently and release held qualification or Landing authority immediately." },
+    "dev-authority-submit": { group: "governance-versioning", purpose: "Submit an exact candidate to the opt-in bounded-qualification authority state." },
     "dev-proof-classify": { group: "governance-versioning", purpose: "Classify source-qualified candidate changes against a current integration base." },
     "dev-proof-integration": { group: "governance-versioning", purpose: "Seal final exact integration delivery proof for a warranted candidate." },
     "dev-proof-replay": { group: "governance-versioning", purpose: "Replay source qualification against a Project Cut without rewriting candidate source." },
@@ -128,6 +148,7 @@ export function cliCommandMeta(id) {
     "paper-status": { group: "reusable-build", purpose: "Report explicit evidence for every paper lifecycle state without unsupported inference." },
     "paper-work-start": { group: "getting-started", purpose: "Create a safe Paper work branch from the exact canonical remote development SHA." },
     "paper-work-submit": { group: "governance-versioning", purpose: "Push a Paper work branch without force and open or reuse the correctly targeted development PR." },
+    "next-development": { group: "governance-versioning", purpose: "Plan or apply one rooted declared-path next-development version transition without release or ref authority." },
     "publish-source": { group: "release-passport-trust", purpose: "Create, inspect, or verify publish-gate source-lock refs." },
     "publication-artifact": { group: "reusable-build", purpose: "Generate publication artifact manifests, passports, and source bundles for paper/report repositories." },
     "publication-artifact-manifest": { group: "reusable-build", purpose: "Write a site-consumable publication artifact manifest, publication passport, and source bundle." },
@@ -140,6 +161,7 @@ export function cliCommandMeta(id) {
     "release-governance": { group: "governance-versioning", purpose: "Reconcile a managed branch's Buildchain aggregate check to an already-tested pull request SHA." },
     "release-propagation": { group: "site-and-propagation", purpose: "Route exact Paper, KFD, Buildchain, or Core Site updates through one resumable propagation Work." },
     "release-tail": { group: "release-passport-trust", purpose: "Plan, initialize, resume, and verify one declarative provider-owned release-tail transaction." },
+    "tail-reseal": { group: "release-passport-trust", purpose: "Plan, admit, byte-verify, and seal one exact retained v4 Alpha candidate signing-finalization tail." },
     "release-transaction": { group: "release-passport-trust", purpose: "Inspect, recover, finalize, or abort durable release transactions." },
     sample: { group: "observability-diagnostics", purpose: "Inspect sampler command families." },
     "sample-process-tree": { group: "observability-diagnostics", purpose: "Sample process-tree diagnostics for a wrapped command." },
@@ -173,7 +195,9 @@ export function nodeApiMeta(exportName) {
     "./homebrew": { group: "distribution-indexes", summary: "Homebrew tap fact collection, Formula rendering, update, and check APIs." },
     "./build-facts": { group: "observability-diagnostics", summary: "Git source, version, module output, product artifact, and legacy Kungfu build fact APIs." },
     "./candidate-timeline": { group: "observability-diagnostics", summary: "Source-bound candidate event normalization, per-attempt critical-path-safe aggregation, and compact reporting APIs." },
+    "./ci-lane-change-budget": { group: "governance-versioning", summary: "Exact-baseline CI lane admission requiring authority, trigger, concurrency, runner, cancellation, and merge-critical SLO budgets." },
     "./channel-candidate": { group: "governance-versioning", summary: "Exact-source channel candidate decisions, same-SHA workflow evidence validation, and deterministic source-lock reference APIs." },
+    "./dev-delivery-authority": { group: "governance-versioning", summary: "Opt-in bounded Qualification Lease, exclusive Landing Warrant, provider-attempt admission and heartbeat readback, terminal sealing, and expired-Landing verification APIs." },
     "./dev-delivery-warrant": { group: "governance-versioning", summary: "Durable fair Dev Delivery Warrant queue, fenced lease, and split source and integration proof APIs." },
     "./cache-evidence": { group: "observability-diagnostics", summary: "Content-addressed cache operation receipts and source/platform-bound evidence-set verification APIs." },
     "./diagnostics": { group: "observability-diagnostics", summary: "Native diagnostics collection, summarization, cache, compiler, and process-sampler APIs." },
@@ -203,8 +227,24 @@ export function nodeApiMeta(exportName) {
     "./release-candidate": { group: "reusable-build", summary: "PR-stage release-candidate artifact, passport, and promote-only resolver APIs." },
     "./v4-floating-consumer-policy": { group: "governance-versioning", summary: "Semantic floating-selector admission, dual-lock receipt, and independent v4 consumer certification APIs." },
     "./v4-runtime-ref-resume-authority": { group: "release-passport-trust", summary: "Transient exact-runtime authorization, persisted-selector rejection, fresh-attempt Stage Capsule reuse, and A+B Passport lineage APIs." },
+    "./v4-tail-reseal": { group: "release-passport-trust", summary: "Effect-pure retained Stage Capsule validation and explicit Warrant-, credential-, and release-tail-fenced macOS reseal planning APIs." },
+    "./v4-tail-reseal-receipt": { group: "release-passport-trust", summary: "Four-platform byte readback, standard candidate Passport binding, and terminal v4 tail-reseal receipt APIs." },
+    "./v4-publication-rehearsal": { group: "release-passport-trust", summary: "Content-addressed v4 publication rehearsal capsules, shared production release-tail execution, replay, provider observation, and fail-closed verification APIs." },
+    "./adopter-delivery-gate": { group: "reusable-build", summary: "Protocol-neutral adopter delivery gate, driver interface, artifact profiles, and canonical result APIs." },
+    "./kfd-adopter-category-driver": { group: "kfd-trust", summary: "Published KFD adopter-category driver and exact package-cut verification APIs." },
+    "./buildchain-delivery-infrastructure": { group: "reusable-build", summary: "Public delivery-infrastructure instance creation and KFD verification APIs." },
+    "./buildchain-delivery-bootstrap": { group: "reusable-build", summary: "Protected, published N-1 Buildchain delivery bootstrap qualification APIs." },
+    "./buildchain-delivery-self-dogfood": { group: "reusable-build", summary: "Public archive-backed Buildchain delivery-infrastructure self-dogfood APIs." },
+    "./published-delivery-authority": { group: "release-passport-trust", summary: "Content-addressed public Buildchain and KFD archive loading and identity verification APIs." },
+    "./legacy-kfd-adopter-driver": { group: "kfd-trust", summary: "One-way legacy KFD support-matrix adapter driver APIs." },
+    "./adopter-delivery-passport": { group: "release-passport-trust", summary: "Non-authoritative adopter delivery Release Passport binding and substitution checks." },
+    "./adopter-delivery-vectors": { group: "reusable-build", summary: "Rooted public adopter delivery conformance vector suite APIs." },
+    "./v4-adopter-delivery": { group: "reusable-build", summary: "Public v4 adopter delivery runtime, exact readback, N-1 lineage, and published archive verification APIs." },
     "./release-candidate-recovery": { group: "release-passport-trust", summary: "Fail-closed verification and immutable receipts for reusing a successful sealed candidate run without rebuilding product payloads." },
     "./release-train": { group: "governance-versioning", summary: "Frozen Release Cut identity, rooted Release Train transitions, Dev observations, supersession, replay, and legacy read compatibility APIs." },
+    "./next-development-transition": { group: "governance-versioning", summary: "Provider-neutral completed-Alpha preservation and rooted next-development state, version-model, idempotency, and local materialization APIs." },
+    "./next-development-controller": { group: "governance-versioning", summary: "Durable completed-Alpha child scheduling, fresh-runner checkpoint resume, latest protected-Dev reconciliation, and exact version-root readback APIs." },
+    "./next-development-projection": { group: "governance-versioning", summary: "Canonical generated config, Agent, workflow-header, and manual projections for the next-development transition contract." },
     "./stable-candidate-ledger": { group: "governance-versioning", summary: "Immutable alpha candidate ledger, qualification, revocation, selection, and exact stable source-lock APIs." },
     "./release-propagation": { group: "site-and-propagation", summary: "Release propagation graph, plan, and exact upstream lock APIs." },
     "./release-activation-transaction": { group: "release-passport-trust", summary: "Ordered cross-repository activation, exact receipt-set binding, retry, abort, rollback, and shadow-rehearsal APIs." },
@@ -213,6 +253,7 @@ export function nodeApiMeta(exportName) {
     "./release-tail-compatibility": { group: "release-passport-trust", summary: "Bounded v3 release-hook compatibility diagnostics that reject new executable release-tail inputs." },
     "./release-line-bootstrap": { group: "governance-versioning", summary: "Semver release-line bootstrap planning and version-state APIs." },
     "./buildchain-contract": { group: "governance-versioning", summary: "Runtime contract world and compatibility digest APIs for floating-ref drift checks." },
+    "./compatibility-fact-authority": { group: "governance-versioning", summary: "Directional Cut-bound compatibility Fact, lifecycle, explicit path receipt, legacy projection, and Release Passport evidence APIs." },
     "./controller-evidence": { group: "reusable-build", summary: "Project-independent controller descriptors, source/runtime-bound plans, receipts, aggregates, and validation APIs." },
     "./surface-manifest": { group: "site-and-propagation", summary: "Surface manifest timestamp and reproducibility policy APIs." },
     "./issue-reporting": { group: "observability-diagnostics", summary: "Buildchain-owned issue reporting API for workflow friction feedback." },

package/scripts/stable-candidate-qualification.mjs

@@ -146,9 +146,7 @@ export async function runStableCandidateQualification(optionsInput = {}, clientI
   const options = normalizeStableCandidateQualificationOptions(optionsInput);
   const client = clientInput || createGitHubQualificationClient({ token: process.env.GITHUB_TOKEN });
   const candidate = await client.resolveExactAlpha(options.repository, options.candidateSha);
-  if (!candidate) {
-    return { schemaVersion: 1, contract: "kungfu-buildchain-stable-candidate-qualification", status: "skipped", reason: "exact-alpha-release-not-found", candidateSha: options.candidateSha };
-  }
+  if (!candidate) return { schemaVersion: 1, contract: "kungfu-buildchain-stable-candidate-qualification", status: "skipped", reason: "exact-alpha-release-not-found", candidateSha: options.candidateSha };
 
   const build = await ensureWorkflowEvidence({
     client,
@@ -156,12 +154,12 @@ export async function runStableCandidateQualification(optionsInput = {}, clientI
     workflowFile: options.buildWorkflowFile,
     workflowName: options.buildWorkflowName,
     ref: candidate.tag,
-    headSha: options.candidateSha,
+    headSha: candidate.sha,
     runName: "",
     options,
   });
 
-  let status = await client.findCommitStatus(options.repository, options.candidateSha, options.canaryStatusContext);
+  let status = await client.findCommitStatus(options.repository, candidate.sha, options.canaryStatusContext);
   let canary = { state: status?.state === "success" ? "existing" : "pending", run: undefined };
   if (status?.state !== "success") {
     const canaryRef = options.canaryRef || await client.defaultBranch(options.canaryRepository);
@@ -177,15 +175,15 @@ export async function runStableCandidateQualification(optionsInput = {}, clientI
       workflowFile: options.canaryWorkflowFile,
       workflowName: options.canaryWorkflowName,
       ref: canaryRef,
-      headSha: options.candidateSha,
-      runName: `${options.canaryWorkflowName} / ${options.candidateSha}`,
+      headSha: candidate.sha,
+      runName: `${options.canaryWorkflowName} / ${candidate.sha}`,
       sourceSha: options.canarySha,
       options,
     });
     if (!options.dryRun) {
       status = await client.createCommitStatus({
         repository: options.repository,
-        sha: options.candidateSha,
+        sha: candidate.sha,
         context: options.canaryStatusContext,
         targetUrl: canary.run.html_url,
         description: `No-apply ${options.canaryRepository} canary passed`,
@@ -256,11 +254,12 @@ export function createGitHubQualificationClient({
   }
   return {
     async resolveExactAlpha(repositoryName, candidateSha) {
-      const releases = await api(`/repos/${repositoryName}/releases?per_page=100`);
+      const releases = (await api(`/repos/${repositoryName}/releases?per_page=100`)).sort((left, right) => right.tag_name.localeCompare(left.tag_name, "en", { numeric: true }));
       for (const release of releases) {
         if (!release.prerelease || !/^v\d+\.\d+\.\d+-alpha\.\d+$/.test(release.tag_name || "")) continue;
         const sha = await resolveTagSha(repositoryName, release.tag_name);
-        if (sha === candidateSha) return { version: release.tag_name.slice(1), tag: release.tag_name, sha, releaseUrl: release.html_url };
+        if (sha !== candidateSha && !["ahead", "identical"].includes((await api(`/repos/${repositoryName}/compare/${sha}...${candidateSha}`)).status)) continue;
+        return { version: release.tag_name.slice(1), tag: release.tag_name, sha, releaseUrl: release.html_url };
       }
       return undefined;
     },

package/scripts/v4-consumer-policy.mjs

@@ -41,6 +41,9 @@ export function scanCommand(options = {}) {
   const root = path.resolve(
     options.root || env("BUILDCHAIN_CONSUMER_ROOT", process.cwd()),
   );
+  const invocationRoot = path.resolve(
+    options.invocationRoot || env("BUILDCHAIN_INVOCATION_SOURCE_ROOT", root),
+  );
   const output = path.resolve(
     root,
     options.output ||
@@ -54,6 +57,7 @@ export function scanCommand(options = {}) {
   );
   const result = scanV4FloatingConsumerPolicy({
     root,
+    invocationRoot,
     repository: options.repository || env("GITHUB_REPOSITORY"),
     sourceSha: options.sourceSha || env("GITHUB_SHA"),
     invokedWorkflow:
@@ -139,10 +143,6 @@ export function certifyCommand(options = {}) {
     stableLockPath,
     alphaLockPath,
   });
-  const selectedLock =
-    receipt?.invocation?.visibleSelector === "v4-alpha"
-      ? readJson(path.join(callerRoot, alphaLockPath))
-      : readJson(path.join(callerRoot, stableLockPath));
   const authorityScan = scanV4FloatingConsumerPolicy({
     root: callerRoot,
     repository,
@@ -150,7 +150,7 @@ export function certifyCommand(options = {}) {
     invokedWorkflow,
     invocationSourcePath: receipt?.invocation?.sourcePath,
     expectedInvocationChannel: receipt?.invocation?.channel,
-    resolvedWorkflowSha: selectedLock.buildchain?.resolvedSha,
+    resolvedWorkflowSha: receipt?.invocation?.resolvedWorkflowSha,
     resolvedRuntimeSha,
     stableLockPath,
     alphaLockPath,

package/scripts/v4-publication-rehearsal-fixture.mjs

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  createV4PublicationRehearsalCapsule,
+  executeV4PublicationRehearsal,
+} from "../packages/core/v4-publication-rehearsal.js";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const fixtureRoot = path.join(
+  root,
+  "contracts/fixtures/v4-publication-rehearsal-v1",
+);
+const candidateRoot = path.join(fixtureRoot, "candidate");
+
+function digest(bytes) {
+  return `sha256:${crypto.createHash("sha256").update(bytes).digest("hex")}`;
+}
+
+function candidateFiles() {
+  const roles = {
+    "artifacts/product.bin": "installable-product",
+    "config/buildchain.toml": "buildchain-config",
+    "documents/release-activation.json": "release-activation-document",
+    "documents/signed-channel.json": "signed-channel-document",
+    "evidence/qualification.json": "qualification-evidence",
+    "manifests/candidate.json": "candidate-manifest",
+    "manifests/release-passport.json": "release-passport",
+  };
+  return Object.keys(roles)
+    .map((relative) => {
+      const bytes = fs.readFileSync(path.join(candidateRoot, relative));
+      return {
+        role: roles[relative],
+        path: relative,
+        size: bytes.length,
+        root: digest(bytes),
+      };
+    })
+    .sort((left, right) =>
+      Buffer.from(left.path).compare(Buffer.from(right.path)),
+    );
+}
+
+async function generated() {
+  const declaration = JSON.parse(
+    fs.readFileSync(
+      path.join(
+        root,
+        "contracts/fixtures/release-tail-capabilities-v1/kungfu-alpha.json",
+      ),
+      "utf8",
+    ),
+  );
+  const files = candidateFiles();
+  const binding = (relative) => ({
+    path: relative,
+    root: files.find((entry) => entry.path === relative).root,
+  });
+  const capsule = createV4PublicationRehearsalCapsule({
+    source: {
+      repository: "kungfu-systems/buildchain",
+      revision: "bc12cd0ff18a7e1d918777ea093c169349952d34",
+    },
+    declaration,
+    manifest: binding("manifests/candidate.json"),
+    config: binding("config/buildchain.toml"),
+    providerBindings: {
+      schema: "kungfu.buildchain.release-tail.provider-bindings/v1",
+      artifacts: {
+        "installable-product": {
+          path: "artifacts/product.bin",
+          name: "product.bin",
+        },
+        "release-passport": {
+          path: "manifests/release-passport.json",
+          name: "release-passport.json",
+        },
+      },
+      documents: {
+        "release.activate": {
+          path: "documents/release-activation.json",
+          method: "PUT",
+        },
+        "signed-channel.commit": {
+          path: "documents/signed-channel.json",
+          method: "PUT",
+        },
+      },
+      evidence: {
+        inputs: ["evidence/qualification.json"],
+        output: "generated/released-evidence.json",
+      },
+    },
+    files,
+  });
+  const vectors = [];
+  for (const platform of ["linux", "macos", "windows"]) {
+    const result = await executeV4PublicationRehearsal({
+      capsule,
+      candidateRoot,
+      mode: "simulate",
+    });
+    vectors.push({
+      platform,
+      capsuleRoot: result.evidence.capsuleRoot,
+      transactionRoot: result.evidence.transactionRoot,
+      stateRoot: result.evidence.stateRoot,
+      evidenceRoot: result.evidence.evidenceRoot,
+    });
+  }
+  return {
+    capsule,
+    vectors: {
+      schema: "buildchain-v4-publication-rehearsal-offline-vectors/v1",
+      vectors,
+      vectorRoot: digest(JSON.stringify(vectors)),
+    },
+  };
+}
+
+const { capsule, vectors } = await generated();
+const outputs = new Map([
+  [path.join(fixtureRoot, "capsule.json"), capsule],
+  [path.join(fixtureRoot, "offline-vectors.json"), vectors],
+]);
+const check = process.argv.includes("--check");
+for (const [file, value] of outputs) {
+  const bytes = `${JSON.stringify(value, null, 2)}\n`;
+  if (check) {
+    if (!fs.existsSync(file) || fs.readFileSync(file, "utf8") !== bytes)
+      throw new Error(`${path.relative(root, file)} is stale`);
+  } else {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, bytes);
+  }
+}
+process.stdout.write(
+  `${JSON.stringify({ capsuleRoot: capsule.capsuleRoot, vectorRoot: vectors.vectorRoot })}\n`,
+);

package/scripts/v4-tail-reseal-macos-rehearsal.mjs

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { v4ContentRoot } from "../packages/core/v4-canonical-contracts.js";
+import { verifyV4TailResealPlatform } from "./v4-tail-reseal.mjs";
+
+function flag(args, name, fallback = "") {
+  const index = args.indexOf(`--${name}`);
+  return index < 0 ? fallback : String(args[index + 1] || "");
+}
+
+function fileRoot(file) {
+  return `sha256:${crypto
+    .createHash("sha256")
+    .update(fs.readFileSync(file))
+    .digest("hex")}`;
+}
+
+function writeCandidate(root, request, content) {
+  const platform = request.platforms.find(({ id }) => id === "macos-arm64");
+  const payload = path.join(root, "product/release/macos-arm64/payload.bin");
+  fs.mkdirSync(path.dirname(payload), { recursive: true });
+  fs.writeFileSync(payload, content);
+  const relative = path.relative(root, payload);
+  const file = {
+    path: relative,
+    size: fs.statSync(payload).size,
+    digest: fileRoot(payload),
+  };
+  const manifest = {
+    contract: "kungfu-buildchain-artifact",
+    artifactName: platform.artifactName,
+    git: {
+      repository: request.repository,
+      sha: request.source.sha,
+      treeSha: request.source.treeSha,
+      runId: String(request.source.runId),
+      runAttempt: String(request.source.runAttempt),
+    },
+    platform: { id: platform.id, name: platform.name },
+    files: [
+      {
+        path: relative,
+        size: file.size,
+        sha256: file.digest.replace(/^sha256:/u, ""),
+      },
+    ],
+    summary: { fileCount: 1, totalBytes: file.size },
+  };
+  const manifestPath = path.join(root, "evidence/macos-arm64/manifest.json");
+  fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
+  fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+  return {
+    artifactRoot: v4ContentRoot("tail-reseal-artifact-files", [file]),
+    manifestRoot: fileRoot(manifestPath),
+  };
+}
+
+export function rehearseV4TailResealMacos({
+  fixturePath = "contracts/fixtures/v4-tail-reseal-v1/valid.json",
+  outputPath = "",
+} = {}) {
+  const request = JSON.parse(
+    fs.readFileSync(path.resolve(fixturePath), "utf8"),
+  );
+  const workRoot = fs.mkdtempSync(
+    path.join(os.tmpdir(), "buildchain-v4-tail-macos-"),
+  );
+  try {
+    const retainedRoots = writeCandidate(workRoot, request, "unsigned");
+    const platform = request.platforms.find(({ id }) => id === "macos-arm64");
+    Object.assign(platform, retainedRoots);
+    const retained = verifyV4TailResealPlatform({
+      request,
+      platformId: "macos-arm64",
+      artifactRoot: workRoot,
+      mode: "retained",
+    });
+    writeCandidate(workRoot, request, "signed-and-notarized");
+    const resealed = verifyV4TailResealPlatform({
+      request,
+      platformId: "macos-arm64",
+      artifactRoot: workRoot,
+      mode: "resealed",
+      providerReadbackRoot: request.signing.providerReadbackRoot,
+    });
+    const payload = {
+      schema: "kungfu-buildchain-v4-tail-reseal-macos-rehearsal/v1",
+      platformId: "macos-arm64",
+      retained,
+      resealed,
+      buildStagesExecuted: 0,
+      signingFinalizationExecutions: 1,
+      providerReadbackRoot: request.signing.providerReadbackRoot,
+    };
+    const evidence = {
+      ...payload,
+      evidenceRoot: v4ContentRoot("tail-reseal-admission", payload),
+    };
+    if (outputPath) {
+      const output = path.resolve(outputPath);
+      fs.mkdirSync(path.dirname(output), { recursive: true });
+      fs.writeFileSync(output, `${JSON.stringify(evidence, null, 2)}\n`);
+    }
+    return evidence;
+  } finally {
+    fs.rmSync(workRoot, { recursive: true, force: true });
+  }
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  try {
+    const evidence = rehearseV4TailResealMacos({
+      fixturePath: flag(
+        process.argv.slice(2),
+        "fixture",
+        "contracts/fixtures/v4-tail-reseal-v1/valid.json",
+      ),
+      outputPath: flag(process.argv.slice(2), "output"),
+    });
+    process.stdout.write(`${JSON.stringify(evidence, null, 2)}\n`);
+  } catch (error) {
+    console.error(`v4-tail-reseal-macos-rehearsal: ${error.message}`);
+    process.exitCode = 1;
+  }
+}