@kungfu-tech/buildchain 4.0.2-alpha.9 → 4.0.3-alpha.0

package/scripts/check-universal-workflow-bootstrap.mjs

@@ -0,0 +1,266 @@
+import assert from "node:assert/strict";
+import { currentWorkflowPath, projectWorkflowIdentities } from "./workflow-taxonomy.mjs";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const contract = JSON.parse(
+  fs.readFileSync(path.join(root, "architecture/universal-workflow-bootstrap.json"), "utf8"),
+);
+const admissionPolicy = JSON.parse(
+  fs.readFileSync(path.join(root, "architecture/universal-workflow-train-admission.json"), "utf8"),
+);
+const admissionObservedAt = Date.now();
+assert.ok(
+  admissionObservedAt >= Date.parse(admissionPolicy.validFrom) &&
+    admissionObservedAt < Date.parse(admissionPolicy.expiresAt),
+  `release admission policy is outside its validity window (${admissionPolicy.validFrom} to ${admissionPolicy.expiresAt}); renew it through protected review before publishing`,
+);
+const fileRoot = (relative) =>
+  `sha256:${crypto
+    .createHash("sha256")
+    .update(fs.readFileSync(path.join(root, relative)))
+    .digest("hex")}`;
+
+const workflowRoot = path.join(root, ".github/workflows");
+const discovered = projectWorkflowIdentities(root, fs.readdirSync(workflowRoot)
+  .filter((name) => /\.ya?ml$/u.test(name))
+  .map((name) => ({ path: `.github/workflows/${name}`, text: fs.readFileSync(path.join(workflowRoot, name), "utf8") })))
+  .filter((entry) => /(?:^|\n)\s*workflow_call:\s*(?:\n|$)/u.test(entry.text))
+  .map((entry) => entry.path).sort();
+
+assert.equal(
+  contract.schema,
+  "kungfu-buildchain-v4-universal-workflow-bootstrap/v1",
+);
+assert.deepEqual(
+  contract.inventoryWorkflows,
+  [...new Set(contract.inventoryWorkflows)].sort(),
+  "inventoried public workflows must be sorted and duplicate-free",
+);
+assert.deepEqual(
+  contract.inventoryWorkflows,
+  discovered,
+  "every active public workflow_call surface must be inventoried",
+);
+for (const relative of contract.inventoryWorkflows)
+  assert.ok(
+    fs.statSync(path.join(root, currentWorkflowPath(root, relative))).isFile(),
+    `inventoried workflow is unavailable: ${relative}`,
+  );
+assert.deepEqual(
+  contract.bootstrapGovernedWorkflows,
+  [...new Set(contract.bootstrapGovernedWorkflows)].sort(),
+  "Bootstrap-governed workflows must be sorted and duplicate-free",
+);
+assert.deepEqual(
+  contract.retiredWorkflowSurfaces,
+  [...new Set(contract.retiredWorkflowSurfaces)].sort(),
+  "retired workflow surfaces must be sorted and duplicate-free",
+);
+for (const relative of contract.retiredWorkflowSurfaces) {
+  assert.ok(
+    contract.inventoryWorkflows.includes(relative),
+    `retired workflow is outside the inventory: ${relative}`,
+  );
+  assert.match(
+    fs.readFileSync(path.join(root, relative), "utf8"),
+    /retired/u,
+    `retired workflow does not fail closed explicitly: ${relative}`,
+  );
+}
+const activeWorkflows = contract.inventoryWorkflows.filter(
+  (relative) =>
+    !contract.retiredWorkflowSurfaces.includes(relative) &&
+    relative !== contract.bootstrap.consumerRecoveryWorkflow,
+);
+assert.deepEqual(
+  contract.bootstrapGovernedWorkflows,
+  activeWorkflows,
+  "every active public reusable workflow must be Bootstrap-governed",
+);
+for (const relative of contract.bootstrapGovernedWorkflows) {
+  assert.ok(
+    contract.inventoryWorkflows.includes(relative),
+    `Bootstrap-governed workflow is outside the inventory: ${relative}`,
+  );
+  const source = fs.readFileSync(path.join(root, currentWorkflowPath(root, relative)), "utf8");
+  assert.ok(
+    relative === contract.bootstrap.publicWorkflow ||
+      /uses:\s+(?:\.\/)?\.github\/workflows\/bootstrap\.yml/u.test(source) ||
+      /uses:\s+kungfu-systems\/buildchain\/\.github\/workflows\/bootstrap\.yml@/u.test(
+        source,
+      ),
+    `workflow is declared governed without a Bootstrap edge: ${relative}`,
+  );
+}
+
+assert.deepEqual(contract.complexityBudget, {
+  bootstrapAbis: 1,
+  requestEnvelopes: 1,
+  candidateResolvers: 1,
+  candidateEngines: 1,
+  terminalReceiptAuthorities: 1,
+  perWorkflowBootstrapImplementations: 0,
+  buildchainOnlySelfReleasePaths: 0,
+  perIncidentConsumerEdits: 0,
+});
+assert.equal(contract.bootstrap.discoveryRefExecutionAuthority, false);
+assert.equal(contract.bootstrap.exactShaExecutionAuthority, true);
+assert.equal(contract.bootstrap.consumerSourceMutationPerIncident, false);
+assert.equal(contract.bootstrap.buildchainReleasePromotionPerIncident, false);
+assert.equal(contract.bootstrap.selfDogfoodUsesPublicContract, true);
+assert.equal(contract.bootstrap.recoveryDependsOnPublishedBuildchain, false);
+assert.equal(
+  contract.bootstrap.reviewRuntimeBinding,
+  "reviewed-head-or-protected-alpha-merge-to-exact-runtime",
+);
+assert.deepEqual(
+  contract.capabilityAdapters.map(({ id }) => id).sort(),
+  [...admissionPolicy.allowedCapabilities].sort(),
+  "every admitted capability must have one real candidate adapter",
+);
+for (const adapter of contract.capabilityAdapters) {
+  assert.match(adapter.execution, /^exact-candidate-/u);
+  assert.ok(adapter.payloadSchema.endsWith("/v1"));
+}
+assert.ok(!admissionPolicy.allowedCapabilities.includes("workflow-contract"));
+assert.deepEqual(
+  admissionPolicy.contractRoots,
+  [
+    fileRoot("architecture/universal-workflow-bootstrap.json"),
+    fileRoot(contract.bootstrap.faultCampaign),
+    fileRoot("packages/core/universal-workflow-bootstrap.js"),
+    fileRoot("scripts/universal-workflow-backflow.mjs"),
+    fileRoot("scripts/universal-workflow-engine.mjs"),
+    fileRoot("scripts/universal-workflow-self-dogfood.mjs"),
+    fileRoot(contract.bootstrap.publicWorkflow),
+  ].sort(),
+);
+assert.doesNotMatch(
+  fs.readFileSync(
+    path.join(root, contract.bootstrap.candidateEnginePath),
+    "utf8",
+  ),
+  /request\.capability\.id\s*===\s*["']workflow-contract["']/u,
+  "contract-only validation must not be admitted as successful execution",
+);
+const bootstrapSource = fs.readFileSync(
+  path.join(root, contract.bootstrap.publicWorkflow),
+  "utf8",
+);
+assert.doesNotMatch(
+  bootstrapSource,
+  /admission-policy-json:/u,
+  "callers must not supply their own admission authority",
+);
+execFileSync(
+  process.execPath,
+  [path.join(root, contract.migration.compatibilityFacadeGenerator), "--check"],
+  { stdio: "inherit" },
+);
+assert.doesNotMatch(bootstrapSource, /^    permissions:/mu);
+assert.match(
+  bootstrapSource,
+  /execute:[\s\S]*BUILDCHAIN_PROMOTION_TOKEN: \$\{\{ secrets\.BUILDCHAIN_PROMOTION_TOKEN \}\}[\s\S]*GH_TOKEN: \$\{\{ github\.token \}\}/u,
+  "the privileged candidate executor must receive the protected-ref mutation token",
+);
+assert.match(bootstrapSource, /settle:[\s\S]*needs: \[admit, execute\]/u);
+assert.match(
+  bootstrapSource,
+  /ascii_downcase\) == "kungfu-origin"[\s\S]*\.name == "check"[\s\S]*map\(select\(\.status == "completed" and \(\.conclusion \/\/ ""\) != ""\)\)[\s\S]*candidate\/architecture\/universal-workflow-train-admission\.json/u,
+);
+assert.match(
+  bootstrapSource,
+  /CANDIDATE_MODE:[\s\S]*\.merged == true[\s\S]*\.merge_commit_sha == \$expected[\s\S]*\.base\.ref == "alpha\/v4\/v4\.0"[\s\S]*commitSha: \$expected[\s\S]*runtimeBinding:/u,
+);
+const consumerTemplate = fs.readFileSync(
+  path.join(root, contract.bootstrap.consumerTemplate),
+  "utf8",
+);
+const consumerRecoveryTemplate = fs.readFileSync(
+  path.join(root, contract.bootstrap.consumerRecoveryTemplate),
+  "utf8",
+);
+const consumerRecoveryWorkflow = fs.readFileSync(
+  path.join(root, contract.bootstrap.consumerRecoveryWorkflow),
+  "utf8",
+);
+const selfDogfood = fs.readFileSync(
+  path.join(root, contract.bootstrap.selfDogfoodWorkflow),
+  "utf8",
+);
+assert.match(
+  consumerTemplate,
+  /uses:\s+kungfu-systems\/buildchain\/\.github\/workflows\/bootstrap\.yml@v4/u,
+);
+assert.match(
+  consumerRecoveryTemplate,
+  /recovery-admit:[\s\S]*recovery-execute:/u,
+);
+assert.match(
+  consumerRecoveryTemplate,
+  /Parse exact recovery coordinates without Buildchain code[\s\S]*Prove exact independent review before candidate code runs[\s\S]*ascii_downcase\) == "kungfu-origin"[\s\S]*\.name == "check"[\s\S]*Admit candidate policy and exact-head checks[\s\S]*map\(select\(\.status == "completed" and \(\.conclusion \/\/ ""\) != ""\)\)/u,
+);
+assert.match(
+  consumerRecoveryTemplate,
+  /recovery-execute:[\s\S]*needs: recovery-admit[\s\S]*contents: write/u,
+);
+assert.doesNotMatch(
+  consumerRecoveryTemplate,
+  /uses:\s+kungfu-systems\/buildchain\/\.github\/workflows\//u,
+  "consumer recovery must not parse any published Buildchain workflow",
+);
+assert.equal(
+  consumerRecoveryWorkflow,
+  consumerRecoveryTemplate,
+  "the Buildchain self-consumer must exercise the exact distributable recovery shell",
+);
+assert.match(
+  selfDogfood,
+  /uses:\s+kungfu-systems\/buildchain\/\.github\/workflows\/bootstrap\.yml@train\/v4\/v4\.0\/universal-reusable-workflow-bootstrap/u,
+);
+assert.match(
+  selfDogfood,
+  /uses:\s+\.\/\.github\/workflows\/universal-bootstrap-recovery\.yml/u,
+);
+assert.doesNotMatch(
+  selfDogfood,
+  /\.github\/workflows\/bootstrap\.yml@(?:v4|v4-alpha)(?:\s|$)/u,
+  "Train self-dogfood must not depend on an alpha or stable Bootstrap tag",
+);
+for (const channel of ["conformance", "alpha", "stable"]) {
+  assert.match(selfDogfood, new RegExp(`primary-${channel}:`, "u"));
+  assert.match(selfDogfood, new RegExp(`recovery-${channel}:`, "u"));
+}
+assert.match(
+  selfDogfood,
+  /\.state == "APPROVED"[\s\S]*ascii_downcase\) == "kungfu-origin"[\s\S]*\.name == "check"[\s\S]*\.conclusion == "success"/u,
+);
+assert.match(
+  consumerRecoveryTemplate,
+  /result-json:[\s\S]*value:\s*\$\{\{ jobs\.recovery-execute\.outputs\.result-json \}\}/u,
+);
+
+console.log(
+  JSON.stringify({
+    ok: true,
+    schema: contract.schema,
+    publicWorkflowCount: discovered.length,
+    activePublicWorkflowCount: activeWorkflows.length,
+    retiredWorkflowCount: contract.retiredWorkflowSurfaces.length,
+    inventoriedWorkflowCount: contract.inventoryWorkflows.length,
+    inventoryCoveragePercent: 100,
+    governedWorkflowCount: contract.bootstrapGovernedWorkflows.length,
+    governedCoveragePercent: Number(
+      (
+        (contract.bootstrapGovernedWorkflows.length / activeWorkflows.length) *
+        100
+      ).toFixed(2),
+    ),
+    migration: contract.migration,
+  }),
+);

package/scripts/check-workflow-taxonomy.mjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { checkWorkflowTaxonomy } from "./workflow-taxonomy.mjs";
+
+const result = checkWorkflowTaxonomy(process.cwd());
+process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+if (!result.ok) process.exitCode = 1;

package/scripts/{v4-consumer-policy.mjs → consumer-policy.mjs}

@@ -3,11 +3,11 @@ import fs from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import {
-  certifyV4FloatingConsumerPolicyReceipt,
-  resolveV4FloatingConsumerPolicyAuthority,
-  scanV4FloatingConsumerPolicy,
-  v4ConsumerPolicyScannerRoot,
-} from "../packages/core/v4-floating-consumer-policy.js";
+  certifyFloatingConsumerPolicyReceipt,
+  resolveFloatingConsumerPolicyAuthority,
+  scanFloatingConsumerPolicy,
+  consumerPolicyScannerRoot,
+} from "../packages/core/floating-consumer-policy.js";
 import { writeGitHubOutputs } from "./build-contract-core.mjs";
 const RUNTIME_ROOT = path.resolve(import.meta.dirname, "..");
 function parseArgs(argv) {
@@ -36,7 +36,7 @@ function writeJson(file, value) {
   fs.mkdirSync(path.dirname(file), { recursive: true });
   fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`);
 }
-export { v4ConsumerPolicyScannerRoot };
+export { consumerPolicyScannerRoot };
 export function scanCommand(options = {}) {
   const root = path.resolve(
     options.root || env("BUILDCHAIN_CONSUMER_ROOT", process.cwd()),
@@ -49,13 +49,13 @@ export function scanCommand(options = {}) {
     options.output ||
       env(
         "BUILDCHAIN_V4_POLICY_RECEIPT_PATH",
-        ".buildchain/evidence/v4-consumer-policy-receipt.json",
+        ".buildchain/evidence/consumer-policy-receipt.json",
       ),
   );
   const policy = readJson(
-    path.join(RUNTIME_ROOT, "architecture/v4-floating-consumer-policy.json"),
+    path.join(RUNTIME_ROOT, "architecture/floating-consumer-policy.json"),
   );
-  const result = scanV4FloatingConsumerPolicy({
+  const result = scanFloatingConsumerPolicy({
     root,
     invocationRoot,
     repository: options.repository || env("GITHUB_REPOSITORY"),
@@ -86,7 +86,7 @@ export function scanCommand(options = {}) {
         ".buildchain/alpha-contract-lock.json",
       ),
     policy,
-    scannerRoot: v4ConsumerPolicyScannerRoot(),
+    scannerRoot: consumerPolicyScannerRoot(),
   });
   writeJson(output, result);
   writeGitHubOutputs({
@@ -137,13 +137,13 @@ export function certifyCommand(options = {}) {
     receipt?.invocation?.workflow;
   const resolvedRuntimeSha =
     options.resolvedRuntimeSha || env("BUILDCHAIN_EXPECTED_RUNTIME_SHA");
-  const authority = resolveV4FloatingConsumerPolicyAuthority({
+  const authority = resolveFloatingConsumerPolicyAuthority({
     runtimeRoot: RUNTIME_ROOT,
     callerRoot,
     stableLockPath,
     alphaLockPath,
   });
-  const authorityScan = scanV4FloatingConsumerPolicy({
+  const authorityScan = scanFloatingConsumerPolicy({
     root: callerRoot,
     repository,
     sourceSha,
@@ -163,7 +163,7 @@ export function certifyCommand(options = {}) {
     scannerRoot: authority.scannerRoot,
     contractLocks: authority.contractLocks,
   };
-  const result = certifyV4FloatingConsumerPolicyReceipt({
+  const result = certifyFloatingConsumerPolicyReceipt({
     receipt,
     receiptRoot,
     expectedReceiptRoot: authorityScan.receiptRoot,
@@ -183,7 +183,7 @@ export function certifyCommand(options = {}) {
     options.output ||
       env(
         "BUILDCHAIN_V4_POLICY_CERTIFICATION_PATH",
-        ".buildchain/evidence/v4-consumer-policy-certification.json",
+        ".buildchain/evidence/consumer-policy-certification.json",
       ),
   );
   const documentWithAuthority = {
@@ -211,7 +211,7 @@ function main(argv = process.argv.slice(2)) {
         ? certifyCommand(options)
         : (() => {
             throw new Error(
-              "usage: v4-consumer-policy.mjs <scan|certify> [--option value]",
+              "usage: consumer-policy.mjs <scan|certify> [--option value]",
             );
           })();
   process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);

package/scripts/copy-domain-wasm.mjs

@@ -0,0 +1,14 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const destination = path.resolve(process.argv[2] || "");
+if (!process.argv[2] || path.basename(destination) !== "dist") {
+  throw new Error("usage: copy-domain-wasm.mjs ACTION_DIST_DIRECTORY");
+}
+fs.mkdirSync(destination, { recursive: true });
+fs.copyFileSync(
+  path.join(root, "packages", "core", "buildchain-domain.wasm"),
+  path.join(destination, "buildchain-domain.wasm"),
+);

package/scripts/{v4-cross-platform-adopter-qualification.mjs → cross-platform-adopter-qualification.mjs}

@@ -5,10 +5,10 @@ import fs from "node:fs";
 import path from "node:path";
 
 import {
-  createV4CrossPlatformAdopterReport,
-  qualifyV4CrossPlatformAdopters,
-  summarizeV3V4CapabilityInventory,
-} from "../packages/core/v4-cross-platform-adopter-qualification.js";
+  createCrossPlatformAdopterReport,
+  qualifyCrossPlatformAdopters,
+  summarizeBaselineCapabilityInventory,
+} from "../packages/core/cross-platform-adopter-qualification.js";
 
 function flag(name, fallback = "") {
   const index = process.argv.indexOf(`--${name}`);
@@ -74,9 +74,9 @@ function runPlatform() {
     });
 
   const inventory = readJson(
-    path.join(runtimeRoot, "architecture/v3-v4-live-capability-inventory.json"),
+    path.join(runtimeRoot, "architecture/capability-parity-live-capability-inventory.json"),
   );
-  const inventoryEvidence = summarizeV3V4CapabilityInventory(inventory);
+  const inventoryEvidence = summarizeBaselineCapabilityInventory(inventory);
   fs.mkdirSync(workRoot, { recursive: true });
   const initialPath = path.join(workRoot, "initial-readback.json");
   const retryPath = path.join(workRoot, "retry-readback.json");
@@ -135,7 +135,7 @@ function runPlatform() {
   );
   expectPass(neutralDriver, "independent protocol-neutral driver");
 
-  const report = createV4CrossPlatformAdopterReport({
+  const report = createCrossPlatformAdopterReport({
     platform: required("platform"),
     consumer: required("consumer"),
     sourceBinding: {
@@ -210,7 +210,7 @@ function collectReports(root) {
 
 function aggregate() {
   const reportsRoot = path.resolve(required("reports-root"));
-  const qualification = qualifyV4CrossPlatformAdopters({
+  const qualification = qualifyCrossPlatformAdopters({
     reports: collectReports(reportsRoot),
     consumers: repeated("consumer"),
   });
@@ -224,5 +224,5 @@ if (mode === "run") runPlatform();
 else if (mode === "aggregate") aggregate();
 else
   throw new Error(
-    "usage: v4-cross-platform-adopter-qualification.mjs <run|aggregate> ...",
+    "usage: cross-platform-adopter-qualification.mjs <run|aggregate> ...",
   );

package/scripts/{v4-declarative-promotion-admission.mjs → declarative-promotion-admission.mjs}

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 import { pathToFileURL } from "node:url";
 
-import { assertV4DeclarativePromotionInputs } from "../packages/core/v4-publication-qualification.js";
+import { assertDeclarativePromotionInputs } from "../packages/core/publication-qualification.js";
 
-export function admitV4DeclarativePromotion({
+export function admitDeclarativePromotion({
   inputs,
   runtimeRef,
   declarative,
@@ -21,7 +21,7 @@ export function admitV4DeclarativePromotion({
     error.code = "v4-declarative-release-tail-required";
     throw error;
   }
-  assertV4DeclarativePromotionInputs(inputs);
+  assertDeclarativePromotionInputs(inputs);
   return Object.freeze({ mode: "v4-declarative", admitted: true });
 }
 
@@ -30,7 +30,7 @@ if (
   import.meta.url === pathToFileURL(process.argv[1]).href
 ) {
   try {
-    const result = admitV4DeclarativePromotion({
+    const result = admitDeclarativePromotion({
       inputs: JSON.parse(process.env.BUILDCHAIN_PROMOTION_INPUTS_JSON || "{}"),
       runtimeRef: process.env.BUILDCHAIN_RUNTIME_REF,
       declarative: process.env.BUILDCHAIN_DECLARATIVE_RELEASE_TAIL === "true",

package/scripts/dev-delivery-authority-command-adapters.mjs

@@ -1,4 +1,3 @@
-import fs from "node:fs";
 import path from "node:path";
 import {
   acquireDevDeliveryLandingWarrant,
@@ -66,6 +65,7 @@ function submitCandidate(state, options) {
     {
       pullRequestNumber: options.pullRequestNumber,
       sourceHead: options.sourceHead,
+      sourceRoot: options.sourceRoot,
       assignmentRoot: options.assignmentRoot,
       initiativeRoot: options.initiativeRoot,
       sourceIdentityRoot: options.sourceIdentityRoot,

package/scripts/dev-delivery-authority.mjs

@@ -276,16 +276,16 @@ export function devDeliveryAuthorityCliOptions(
       "source-head",
       environment.BUILDCHAIN_DEV_DELIVERY_SOURCE_HEAD,
     ),
-    assignmentRoot: flag(
+    sourceRoot: flag(
       rest,
-      "assignment-root",
-      environment.BUILDCHAIN_DEV_DELIVERY_ASSIGNMENT_ROOT,
-    ),
-    initiativeRoot: flag(
-      rest,
-      "initiative-root",
-      environment.BUILDCHAIN_DEV_DELIVERY_INITIATIVE_ROOT,
+      "source-root",
+      environment.BUILDCHAIN_WORK_SOURCE_ROOT ||
+        environment.BUILDCHAIN_DEV_DELIVERY_SOURCE_ROOT,
     ),
+    // Retired roots remain readable in persisted historical candidates.
+    // New authority submissions accept only the Work sourceRoot above.
+    // Retired CLI flags are intentionally ignored by this parser.
+    // This prevents producers from reconstructing obsolete identities.
     sourceIdentityRoot: flag(
       rest,
       "source-identity-root",

package/scripts/dev-delivery-source-proof-reuse.mjs

@@ -479,6 +479,7 @@ function cliInput(args) {
 export function sourceProofReuseCli(args = process.argv.slice(2)) {
   const [command = "", ...rest] = args;
   const input = cliInput(rest);
+  if (command === "predicates") return sourceQualificationPredicates(input);
   if (command === "seal") {
     const proof = sealSourceQualificationProof(input);
     writeJson(input.outputPath, proof);
@@ -527,7 +528,7 @@ export function sourceProofReuseCli(args = process.argv.slice(2)) {
     return decision;
   }
   throw new Error(
-    "usage: dev-delivery-source-proof-reuse.mjs <seal|verify> [options]",
+    "usage: dev-delivery-source-proof-reuse.mjs <predicates|seal|verify> [options]",
   );
 }
 

package/scripts/dev-delivery-warrant-options.mjs

@@ -1,8 +1,8 @@
+import fs from "node:fs";
 export function flag(args, name, fallback = "") {
   const index = args.indexOf(`--${name}`);
   return index === -1 ? fallback : args[index + 1] || "";
 }
-
 export function hasFlag(args, name) {
   return args.includes(`--${name}`);
 }
@@ -79,16 +79,16 @@ export function devDeliveryCliOptions(args = [], environment = process.env) {
       "source-head",
       environment.BUILDCHAIN_DEV_DELIVERY_SOURCE_HEAD,
     ),
-    expectedSourceHead: flag(
-      rest,
-      "expected-source-head",
-      environment.BUILDCHAIN_DEV_DELIVERY_EXPECTED_SOURCE_HEAD,
-    ),
-    observedSourceHead: flag(
+    sourceRoot: flag(
       rest,
-      "observed-source-head",
-      environment.BUILDCHAIN_DEV_DELIVERY_OBSERVED_SOURCE_HEAD,
+      "source-root",
+      environment.BUILDCHAIN_WORK_SOURCE_ROOT ||
+        environment.BUILDCHAIN_DEV_DELIVERY_SOURCE_ROOT ||
+        sourceRootFromGitHubEvent(environment),
     ),
+    // prettier-ignore
+    ...{ expectedSourceHead: flag(rest, "expected-source-head", environment.BUILDCHAIN_DEV_DELIVERY_EXPECTED_SOURCE_HEAD), observedSourceHead: flag(rest, "observed-source-head", environment.BUILDCHAIN_DEV_DELIVERY_OBSERVED_SOURCE_HEAD) },
+
     assignmentRoot: flag(
       rest,
       "assignment-root",
@@ -278,7 +278,7 @@ export function devDeliveryCliOptions(args = [], environment = process.env) {
       rest,
       "read-evidence-output",
       environment.BUILDCHAIN_V4_WARRANT_READ_EVIDENCE ||
-        ".buildchain/dev-delivery/v4-read-evidence.json",
+        ".buildchain/dev-delivery/read-evidence.json",
     ),
     now: flag(rest, "now", environment.BUILDCHAIN_DEV_DELIVERY_NOW),
     outputPath: flag(
@@ -291,3 +291,8 @@ export function devDeliveryCliOptions(args = [], environment = process.env) {
     json: hasFlag(rest, "json"),
   };
 }
+
+// prettier-ignore
+function sourceRootFromGitHubEvent(environment) {
+  try { const event = JSON.parse(fs.readFileSync(environment.GITHUB_EVENT_PATH, "utf8")); return event.client_payload?.candidate?.sourceRoot || JSON.parse(event.inputs?.["native-roots-json"] || "{}").sourceRoot || ""; } catch { return ""; }
+}