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

package/scripts/universal-workflow-engine.mjs

@@ -0,0 +1,620 @@
+#!/usr/bin/env node
+import crypto from "node:crypto";
+import fs from "node:fs";
+import { currentWorkflowPath } from "./workflow-taxonomy.mjs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import {
+  admitUniversalWorkflow,
+  completeUniversalWorkflow,
+  selectRecoveredProductPublicationVersion, productStateVersion,
+  validateUniversalWorkflowRequest,
+  universalWorkflowRequestRoot,
+} from "../packages/core/universal-workflow-bootstrap.js";
+import {
+  createReleaseInvocation,
+  createReleaseReceipt,
+  createDomainReleaseTransaction,
+  planReleaseRoute,
+} from "../packages/core/release-invocation.js";
+import { assertDeclarativePromotionInputs } from "../packages/core/publication-qualification.js";
+import {
+  githubJson,
+  resolveReleaseCandidateArtifacts,
+} from "./release-candidate-resolver.mjs";
+
+function fail(message) {
+  throw new Error(message);
+}
+function readJsonEnvironment(name) {
+  const source = process.env[name];
+  if (!source) fail(`${name} is required`);
+  try {
+    return JSON.parse(source);
+  } catch (error) {
+    throw new Error(`${name} is not valid JSON`, { cause: error });
+  }
+}
+function exactRuntime(admission) {
+  const runtime = admission?.runtime;
+  if (
+    admission?.status !== "admitted" ||
+    runtime?.repository !== "kungfu-systems/buildchain" ||
+    !/^[0-9a-f]{40}$/u.test(runtime?.sha || "")
+  )
+    fail("an exact admitted Buildchain runtime is required");
+  return runtime;
+}
+function contentRoot(domain, value) {
+  const hash = crypto.createHash("sha256");
+  hash.update(domain, "utf8");
+  hash.update(Buffer.from([0]));
+  hash.update(`${JSON.stringify(value)}\n`, "utf8");
+  return `sha256:${hash.digest("hex")}`;
+}
+function emit(value) {
+  process.stdout.write(`${JSON.stringify(value)}\n`);
+}
+function exactObject(value, keys, label) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    fail(`${label} must be an object`);
+  const actual = Object.keys(value).sort();
+  const expected = [...keys].sort();
+  if (
+    actual.length !== expected.length ||
+    actual.some((key, index) => key !== expected[index])
+  )
+    fail(`${label} has an invalid field set`);
+}
+
+function validateWorkflowInputs(workflowId, inputs) {
+  const registry = JSON.parse(
+    fs.readFileSync(
+      new URL("../dist/site/workflow-registry.json", import.meta.url),
+    ),
+  );
+  const workflow = registry.workflows.find((entry) => entry.id === workflowId);
+  if (!workflow) fail(`candidate workflow registry is missing ${workflowId}`);
+  const allowed = new Set(workflow.inputs);
+  const unknown = Object.keys(inputs).filter((name) => !allowed.has(name));
+  if (unknown.length > 0)
+    fail(
+      `candidate payload has unregistered workflow inputs: ${unknown.sort().join(", ")}`,
+    );
+}
+const TRUSTED_PUBLISHING_NPM_VERSION = "11.13.0";
+function prepareTrustedPublishingNpm() {
+  if (
+    !process.env.ACTIONS_ID_TOKEN_REQUEST_URL ||
+    !process.env.ACTIONS_ID_TOKEN_REQUEST_TOKEN
+  )
+    fail("trusted publishing requires GitHub Actions OIDC authority");
+  const binDirectory = path.resolve(".buildchain/runtime/bin");
+  const npmShim = path.join(binDirectory, "npm");
+  fs.mkdirSync(binDirectory, { recursive: true });
+  fs.writeFileSync(
+    npmShim,
+    `#!/bin/sh\nexec corepack pnpm@11.7.0 dlx npm@${TRUSTED_PUBLISHING_NPM_VERSION} "$@"\n`,
+    { mode: 0o755 },
+  );
+  fs.chmodSync(npmShim, 0o755);
+  process.env.PATH = `${binDirectory}${path.delimiter}${process.env.PATH || ""}`;
+}
+function prepareReleasePromotionConsumerDependencies(repository) {
+  if (repository !== "kungfu-systems/buildchain") return;
+  const manifest = JSON.parse(fs.readFileSync("package.json", "utf8"));
+  if (manifest.packageManager !== "pnpm@11.7.0" || !fs.existsSync("pnpm-lock.yaml")) fail("Buildchain release consumer dependency lock is unavailable");
+  const consumerModules = path.resolve("node_modules"), runtimeModules = path.resolve(".buildchain/runtime/node_modules");
+  if (!fs.existsSync(consumerModules) && fs.existsSync(runtimeModules)) fs.symlinkSync(path.relative(path.dirname(consumerModules), runtimeModules), consumerModules, "dir");
+  if (!fs.existsSync("node_modules/@kungfu-tech/kfd/package.json")) execFileSync("corepack", "pnpm@11.7.0 install --frozen-lockfile --ignore-scripts".split(" "), { stdio: ["ignore", 2, 2] });
+  if (fs.existsSync(runtimeModules)) {
+    if (fs.realpathSync(consumerModules) !== fs.realpathSync(runtimeModules)) fail("Buildchain release consumer runtime bridge conflicts");
+    return;
+  }
+  fs.mkdirSync(path.dirname(runtimeModules), { recursive: true }); fs.renameSync(consumerModules, runtimeModules);
+  fs.symlinkSync(path.relative(path.dirname(consumerModules), runtimeModules), consumerModules, "dir");
+}
+function actionEnvironment(inputs, outputPath) {
+  const environment = { ...process.env, GITHUB_OUTPUT: outputPath };
+  for (const [name, value] of Object.entries(inputs))
+    environment[`INPUT_${name.replace(/ /gu, "_").toUpperCase()}`] =
+      typeof value === "boolean" ? String(value) : String(value ?? "");
+  return environment;
+}
+
+function readGitHubOutputs(outputPath) {
+  const source = fs.readFileSync(outputPath, "utf8");
+  const outputs = {};
+  const lines = source.split("\n");
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index];
+    const heredoc = line.match(/^([^<]+)<<(.+)$/u);
+    if (heredoc) {
+      const values = [];
+      while (index + 1 < lines.length && lines[index + 1] !== heredoc[2])
+        values.push(lines[(index += 1)]);
+      if (index + 1 >= lines.length)
+        fail(`GitHub output ${heredoc[1]} has no closing delimiter`);
+      index += 1;
+      outputs[heredoc[1]] = values.join("\n");
+      continue;
+    }
+    const separator = line.indexOf("=");
+    if (separator > 0)
+      outputs[line.slice(0, separator)] = line.slice(separator + 1);
+  }
+  return outputs;
+}
+
+function rawFileRoot(relative) {
+  const hash = crypto.createHash("sha256");
+  hash.update(fs.readFileSync(new URL(`../${relative}`, import.meta.url)));
+  return `sha256:${hash.digest("hex")}`;
+}
+
+function executeBootstrapConformance(request, admission) {
+  exactObject(
+    request.payload,
+    ["schema", "expectedGovernedWorkflowCount"],
+    "bootstrap conformance payload",
+  );
+  if (
+    request.payload.schema !==
+    "kungfu-buildchain-v4-universal-bootstrap-conformance/v1"
+  )
+    fail("bootstrap conformance payload schema is unsupported");
+  if (
+    !Number.isSafeInteger(request.payload.expectedGovernedWorkflowCount) ||
+    request.payload.expectedGovernedWorkflowCount < 1
+  )
+    fail("bootstrap conformance workflow count is invalid");
+  const architecture = JSON.parse(
+    fs.readFileSync(
+      new URL(
+        "../architecture/universal-workflow-bootstrap.json",
+        import.meta.url,
+      ),
+    ),
+  );
+  const policy = JSON.parse(
+    fs.readFileSync(
+      new URL(
+        "../architecture/universal-workflow-train-admission.json",
+        import.meta.url,
+      ),
+    ),
+  );
+  if (
+    architecture.bootstrapGovernedWorkflows.length !==
+      request.payload.expectedGovernedWorkflowCount ||
+    architecture.migration.candidateEngine !== "bounded-capability-adapters" ||
+    policy.allowedCapabilities.includes("workflow-contract")
+  )
+    fail("candidate Bootstrap conformance does not close execution semantics");
+  for (const relative of architecture.bootstrapGovernedWorkflows) {
+    const source = fs.readFileSync(
+      path.join(path.resolve(import.meta.dirname, ".."), currentWorkflowPath(path.resolve(import.meta.dirname, ".."), relative)),
+      "utf8",
+    );
+    if (
+      relative !== architecture.bootstrap.publicWorkflow &&
+      !/(?:\.\/)?\.github\/workflows\/bootstrap\.yml/u.test(source)
+    )
+      fail(`candidate Bootstrap facade is not governed: ${relative}`);
+  }
+  return {
+    schema: "kungfu-buildchain-v4-universal-bootstrap-conformance-result/v1",
+    status: "candidate-engine-executed",
+    runtime: exactRuntime(admission),
+    governedWorkflowCount: architecture.bootstrapGovernedWorkflows.length,
+    architectureRoot: rawFileRoot(
+      "architecture/universal-workflow-bootstrap.json",
+    ),
+    engineRoot: rawFileRoot("scripts/universal-workflow-engine.mjs"),
+  };
+}
+
+async function observeReleaseRoute({
+  repository,
+  targetRef,
+  requestedSha,
+  inputs,
+}) {
+  const token = process.env.GH_TOKEN || process.env.GITHUB_TOKEN || "";
+  const apiUrl = process.env.GITHUB_API_URL || "https://api.github.com";
+  const observed = await githubJson({
+    apiUrl,
+    token,
+    path: `/repos/${repository}/git/ref/heads/${targetRef}`,
+  });
+  const currentSha = observed.object.sha;
+  let comparisonStatus = "identical";
+  if (currentSha !== requestedSha) {
+    const comparison = await githubJson({
+      apiUrl,
+      token,
+      path: `/repos/${repository}/compare/${requestedSha}...${currentSha}`,
+    });
+    comparisonStatus = comparison.status;
+  }
+  return planReleaseRoute({
+    requestedSha,
+    observedSha: currentSha,
+    comparisonStatus,
+    requestedChannel: inputs.channel,
+    targetRef,
+    dryRun: inputs["dry-run"] === true,
+    resume:
+      String(inputs["resume-candidate-run-id"] || "") !== "" ||
+      inputs["publish-transaction-override"] === true,
+  });
+}
+
+async function observedSourceTimestamp(repository, sourceSha) {
+  const token = process.env.GH_TOKEN || process.env.GITHUB_TOKEN || "";
+  const apiUrl = process.env.GITHUB_API_URL || "https://api.github.com";
+  const commit = await githubJson({
+    apiUrl,
+    token,
+    path: `/repos/${repository}/git/commits/${sourceSha}`,
+  });
+  const observed = String(
+    commit?.committer?.date || commit?.author?.date || "",
+  ).trim();
+  if (!observed || Number.isNaN(Date.parse(observed)))
+    fail("protected publication source timestamp is unavailable");
+  return new Date(observed).toISOString();
+}
+async function observeProductPublicationRecovery(repository, sourceSha, candidateVersion, channel) {
+  const apiUrl = process.env.GITHUB_API_URL || "https://api.github.com", token = process.env.GH_TOKEN || process.env.GITHUB_TOKEN || "", prefix = `heads/buildchain/v4-product-state/${sourceSha}-`;
+  const stateRefs = (await githubJson({ apiUrl, token, path: `/repos/${repository}/git/matching-refs/${prefix}`, allowNotFound: true })) || [];
+  const recoveryStates = await Promise.all(stateRefs.map(async (stateRef) => { const version = productStateVersion(stateRef, sourceSha); const [stateCommit, exactTagRef] = await Promise.all([githubJson({ apiUrl, token, path: `/repos/${repository}/git/commits/${stateRef.object.sha}` }), githubJson({ apiUrl, token, path: `/repos/${repository}/git/ref/tags/v${version}`, allowNotFound: true })]); return { stateRef, stateCommit, exactTagRef }; }));
+  const exactTagRef = recoveryStates.length ? undefined : await githubJson({ apiUrl, token, path: `/repos/${repository}/git/ref/tags/v${encodeURIComponent(channel === "stable" ? candidateVersion.replace(/-alpha\.\d+$/u, "") : candidateVersion)}`, allowNotFound: true }); return { recoveryStates, exactTagRef };
+}
+async function materializeProductPublicationIntent({
+  candidate,
+  inputs,
+  repository,
+  route,
+}) {
+  const intentPath = path.resolve(
+    ".buildchain/release-candidate/product-publication-intent.json",
+  );
+  const sourceTimestamp = await observedSourceTimestamp(repository, route.requestedSha);
+  const version = String(candidate.publicationVersion || candidate.version || "").trim(), explicitResume = String(inputs["resume-transaction-id"] || "") !== "";
+  const recovery = route.decision !== "Resume" || explicitResume ? {} : await observeProductPublicationRecovery(repository, route.requestedSha, version, route.channel);
+  const recoveredVersion = selectRecoveredProductPublicationVersion({ routeDecision: route.decision, candidateVersion: version, channel: route.channel, requestedSha: route.requestedSha, explicitResume, ...recovery });
+  execFileSync(
+    process.execPath,
+    [
+      path.resolve(
+        ".buildchain/candidate/scripts/product-publication-intent.mjs",
+      ),
+    ],
+    {
+      env: {
+        ...process.env,
+        GITHUB_OUTPUT: "",
+        BUILDCHAIN_REPOSITORY: repository,
+        BUILDCHAIN_CHANNEL: route.channel,
+        BUILDCHAIN_TARGET_REF: route.targetRef,
+        BUILDCHAIN_SOURCE_SHA: route.requestedSha,
+        BUILDCHAIN_SOURCE_TIMESTAMP: sourceTimestamp,
+        BUILDCHAIN_CANDIDATE_VERSION:
+          candidate.publicationVersion || candidate.version,
+        BUILDCHAIN_RECOVERED_PUBLICATION_VERSION: recoveredVersion,
+        BUILDCHAIN_SEALED_BUNDLE_MANIFEST: candidate.paths.sealedBundleManifest,
+        BUILDCHAIN_REQUIRED_ARTIFACTS_PATH:
+          candidate.paths.publishRequiredArtifacts,
+        BUILDCHAIN_PUBLISH_ARTIFACT_KIND: inputs["publish-artifact-kind"] || "npm",
+        BUILDCHAIN_PUBLISH_PACKAGE_MAIN: inputs["publish-package-main"] || "",
+        BUILDCHAIN_PUBLISH_DIST_TAG: inputs["publish-dist-tag"] || "",
+        BUILDCHAIN_PRODUCT_PUBLICATION_INTENT_PATH: intentPath,
+      },
+      stdio: ["ignore", "ignore", "inherit"],
+    },
+  );
+  return intentPath;
+}
+function verifiedReleaseDocuments() {
+  const base = path.resolve(".buildchain/release-tail");
+  const invocation = JSON.parse(
+    fs.readFileSync(path.join(base, "release-invocation.json")),
+  );
+  const transaction = JSON.parse(
+    fs.readFileSync(path.join(base, "release-transaction.json")),
+  );
+  const storedReceipt = JSON.parse(
+    fs.readFileSync(path.join(base, "release-receipt.json")),
+  );
+  const invocationProjection = createReleaseInvocation(invocation);
+  const transactionProjection = createDomainReleaseTransaction({
+    invocationRoot: transaction.invocationRoot,
+    publisherRoot: transaction.publisherRoot,
+    runtimeRoot: transaction.runtimeRoot,
+    providerRoot: transaction.providerRoot,
+    parentRoot: transaction.parentRoot,
+  });
+  const { receiptRoot, ...receipt } = storedReceipt;
+  const receiptProjection = createReleaseReceipt(receipt);
+  if (
+    transaction.invocationRoot !== invocationProjection.roots.invocationRoot ||
+    transaction.transactionRoot !== transactionProjection.transactionRoot ||
+    receipt.transactionRoot !== transactionProjection.transactionRoot ||
+    receiptProjection.receiptRoot !== receiptRoot ||
+    receipt.outcome !== "complete"
+  )
+    fail("terminal ReleaseReceipt lineage does not verify");
+  return { invocation, transaction, receipt: storedReceipt };
+}
+
+async function executeReleasePromotion(request, admission) {
+  const payload = request.payload;
+  exactObject(
+    payload,
+    ["schema", "inputs", "dryRunObservation"],
+    "release promotion payload",
+  );
+  if (payload.schema !== "kungfu-buildchain-v4-universal-release-promotion/v1")
+    fail("release promotion payload schema is unsupported");
+  exactObject(
+    payload.inputs,
+    Object.keys(payload.inputs),
+    "release promotion inputs",
+  );
+  validateWorkflowInputs("release-candidate-promote", payload.inputs);
+  assertDeclarativePromotionInputs(payload.inputs);
+  const repository = request.consumer.repository;
+  const targetRef = String(payload.inputs["target-ref"] || "").replace(
+    /^refs\/heads\//u,
+    "",
+  );
+  const requestedSha = String(
+    payload.inputs["target-sha"] || request.consumer.sourceSha,
+  );
+  let route;
+  if (payload.inputs["dry-run"] === true && payload.dryRunObservation) {
+    exactObject(
+      payload.dryRunObservation,
+      ["observedSha", "comparisonStatus"],
+      "dry-run observation",
+    );
+    route = planReleaseRoute({
+      requestedSha,
+      observedSha: payload.dryRunObservation.observedSha,
+      comparisonStatus: payload.dryRunObservation.comparisonStatus,
+      requestedChannel: payload.inputs.channel,
+      targetRef,
+      dryRun: true,
+      resume: false,
+    });
+  } else {
+    route = await observeReleaseRoute({
+      repository,
+      targetRef,
+      requestedSha,
+      inputs: payload.inputs,
+    });
+  }
+  if (route.decision === "Blocked")
+    fail(`release route blocked: ${route.reason}`);
+  if (route.decision === "NoOp" || payload.inputs["dry-run"] === true)
+    return { route, dryRun: payload.inputs["dry-run"] === true };
+  prepareReleasePromotionConsumerDependencies(repository);
+  if (payload.inputs["trusted-publishing"] === true)
+    prepareTrustedPublishingNpm();
+  const candidate = await resolveReleaseCandidateArtifacts({
+    repository,
+    targetRef: route.targetRef,
+    targetSha: route.requestedSha,
+    token: process.env.GH_TOKEN || process.env.GITHUB_TOKEN,
+    workflowFile: payload.inputs["release-candidate-workflow-file"],
+    workflowName: payload.inputs["release-candidate-workflow-name"],
+    artifactName: payload.inputs["artifact-name"],
+    artifactPatterns: payload.inputs["artifact-patterns"],
+    githubReleasePayloadPatterns:
+      payload.inputs["github-release-payload-patterns"],
+    requiredArtifactCount: payload.inputs["required-artifact-count"],
+    publishArtifactKind: payload.inputs["publish-artifact-kind"],
+    publishPackageMain: payload.inputs["publish-package-main"],
+    runtimeSha: admission.runtime.sha,
+    outputDir: ".buildchain/release-candidate",
+    waitSeconds: payload.inputs["release-candidate-wait-seconds"],
+  });
+  if (!candidate.enabled)
+    fail(candidate.reason || "release candidate is unavailable");
+  const productPublicationIntentPath = await materializeProductPublicationIntent({
+    candidate,
+    inputs: payload.inputs,
+    repository,
+    route,
+  });
+  const productPublicationIntent = JSON.parse(fs.readFileSync(productPublicationIntentPath));
+  const runtimeTree = execFileSync(
+    "git",
+    ["-C", ".buildchain/candidate", "rev-parse", "HEAD^{tree}"],
+    { encoding: "utf8" },
+  ).trim();
+  const actionInputs = {
+    token: process.env.GH_TOKEN || process.env.GITHUB_TOKEN,
+    "mutation-token":
+      process.env.BUILDCHAIN_PROMOTION_TOKEN || process.env.GH_TOKEN,
+    repository,
+    "source-sha": route.requestedSha,
+    version: productPublicationIntent.version,
+    tag: productPublicationIntent.exactTag,
+    channel: route.channel,
+    "target-ref": route.targetRef,
+    "target-sha": route.requestedSha,
+    "candidate-passport-path": candidate.paths.passport,
+    "candidate-build-summary-path": candidate.paths.buildSummary,
+    "stage-capsules-path": candidate.paths.stageCapsules,
+    "publication-qualification-path": candidate.paths.publicationQualification,
+    "publish-artifact-kind": payload.inputs["publish-artifact-kind"] || "npm",
+    "sealed-bundle-root": candidate.paths.sealedBundleRoot,
+    "sealed-bundle-manifest": candidate.paths.sealedBundleManifest,
+    "required-artifacts-path": candidate.paths.publishRequiredArtifacts,
+    "product-publication-intent-path": productPublicationIntentPath,
+    "publisher-workflow-sha": admission.runtime.sha,
+    "runtime-commit": admission.runtime.sha,
+    "runtime-tree": runtimeTree,
+    "required-status-check": payload.inputs["required-status-check"],
+    "publish-command": payload.inputs["publish-command"],
+    "publish-mode": payload.inputs["publish-mode"],
+    "publish-dist-tag": payload.inputs["publish-dist-tag"],
+    "publish-package-set-order": payload.inputs["publish-package-set-order"],
+    "publish-package-main": payload.inputs["publish-package-main"],
+    "publish-auth": payload.inputs["trusted-publishing"]
+      ? "trusted-publishing"
+      : "npm-token",
+    "publish-rematerialize-on-resume":
+      payload.inputs["publish-rematerialize-on-resume"],
+    "publish-transaction-override":
+      payload.inputs["publish-transaction-override"],
+    "resume-transaction-id": payload.inputs["resume-transaction-id"],
+    "artifact-paths": candidate.paths.releaseAssets.join("\n"),
+    "state-path": ".buildchain/release-tail/state.json",
+    "failure-after-capability":
+      payload.inputs["provider-failure-after-capability"],
+  };
+  const actionOutput = path.resolve(".buildchain/universal-release-action.out");
+  fs.mkdirSync(path.dirname(actionOutput), { recursive: true });
+  fs.writeFileSync(actionOutput, "");
+  execFileSync(
+    process.execPath,
+    [
+      path.resolve(
+        ".buildchain/candidate/actions/release-candidate-promote/dist/index.js",
+      ),
+    ],
+    { env: actionEnvironment(actionInputs, actionOutput), stdio: ["ignore", 2, 2] },
+  );
+  return {
+    route,
+    candidate: {
+      runId: candidate.run.id,
+      sourceSha: candidate.artifacts.sourceSha,
+      version: candidate.version,
+    },
+    provider: readGitHubOutputs(actionOutput),
+    release: verifiedReleaseDocuments(),
+  };
+}
+
+async function capabilityResult(request, admission) {
+  if (request.capability.id === "bootstrap-conformance")
+    return executeBootstrapConformance(request, admission);
+  if (request.capability.id === "release-invocation") {
+    const release = createReleaseInvocation(request.payload);
+    return {
+      releaseInvocation: release.invocation,
+      releaseRoots: release.roots,
+    };
+  }
+  if (request.capability.id === "release-candidate-promote")
+    return executeReleasePromotion(request, admission);
+  fail(`candidate capability is not implemented: ${request.capability.id}`);
+}
+async function executeCandidate(request, admission) {
+  const runtime = exactRuntime(admission);
+  if (universalWorkflowRequestRoot(request) !== admission.requestRoot)
+    fail("candidate request does not match the admitted request root");
+  const engineSha = String(process.env.BUILDCHAIN_UNIVERSAL_ENGINE_SHA || "")
+    .trim()
+    .toLowerCase();
+  if (engineSha !== runtime.sha)
+    fail("candidate engine checkout does not match the admitted runtime SHA");
+  try {
+    return {
+      status: "succeeded",
+      output: await capabilityResult(request, admission),
+    };
+  } catch (error) {
+    return {
+      status: "failed",
+      error: {
+        code: String(error?.code || "candidate-execution-failed"),
+        message: "candidate capability execution failed",
+      },
+    };
+  }
+}
+
+function assertResultLineage(admission, result) {
+  if (
+    result?.schema !== "kungfu-buildchain-v4-universal-workflow-result/v1" ||
+    result.requestRoot !== admission.requestRoot ||
+    result.capabilityRoot !== admission.capabilityRoot ||
+    result.runtime?.repository !== admission.runtime?.repository ||
+    result.runtime?.sha !== admission.runtime?.sha ||
+    !["succeeded", "failed"].includes(result.status)
+  )
+    fail("candidate result does not match the admitted lineage");
+}
+
+const command = process.argv[2];
+if (!command) fail("a command is required");
+
+if (command === "inspect") {
+  const request = validateUniversalWorkflowRequest(
+    readJsonEnvironment("BUILDCHAIN_UNIVERSAL_REQUEST_JSON"),
+  );
+  emit({
+    schema: "kungfu-buildchain-v4-universal-workflow-inspection/v1",
+    requestRoot: universalWorkflowRequestRoot(request),
+    mode: request.mode,
+    candidate: request.candidate,
+    consumer: request.consumer,
+    capability: request.capability,
+  });
+} else if (command === "admit") {
+  emit(
+    admitUniversalWorkflow({
+      request: readJsonEnvironment("BUILDCHAIN_UNIVERSAL_REQUEST_JSON"),
+      policy: readJsonEnvironment("BUILDCHAIN_UNIVERSAL_ADMISSION_POLICY_JSON"),
+      observedRefSha: process.env.BUILDCHAIN_UNIVERSAL_OBSERVED_SHA,
+      observedConsumerRepository:
+        process.env.BUILDCHAIN_UNIVERSAL_CONSUMER_REPOSITORY,
+      observedConsumerSha: process.env.BUILDCHAIN_UNIVERSAL_CONSUMER_SHA,
+      observedConsumerWorkflowRef:
+        process.env.BUILDCHAIN_UNIVERSAL_CONSUMER_WORKFLOW_REF,
+      reviewEvidence: readJsonEnvironment(
+        "BUILDCHAIN_UNIVERSAL_REVIEW_EVIDENCE_JSON",
+      ),
+      now: process.env.BUILDCHAIN_UNIVERSAL_OBSERVED_AT,
+    }),
+  );
+} else if (command === "execute") {
+  const request = validateUniversalWorkflowRequest(
+    readJsonEnvironment("BUILDCHAIN_UNIVERSAL_REQUEST_JSON"),
+  );
+  const admission = readJsonEnvironment("BUILDCHAIN_UNIVERSAL_ADMISSION_JSON");
+  const runtime = exactRuntime(admission);
+  const execution = await executeCandidate(request, admission);
+  const result = {
+    schema: "kungfu-buildchain-v4-universal-workflow-result/v1",
+    status: execution.status,
+    requestRoot: admission.requestRoot,
+    runtime,
+    capabilityRoot: admission.capabilityRoot,
+    enginePath: "scripts/universal-workflow-engine.mjs",
+    ...execution,
+  };
+  emit({
+    ...result,
+    resultRoot: contentRoot("universal-workflow-result", result),
+  });
+} else if (command === "terminal") {
+  const admission = readJsonEnvironment("BUILDCHAIN_UNIVERSAL_ADMISSION_JSON");
+  const result = readJsonEnvironment("BUILDCHAIN_UNIVERSAL_RESULT_JSON");
+  assertResultLineage(admission, result);
+  emit(
+    completeUniversalWorkflow({
+      admission,
+      status: result.status,
+      resultRoot: result.resultRoot,
+    }),
+  );
+} else {
+  fail(`unsupported command: ${command}`);
+}