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

package/scripts/universal-workflow-self-dogfood.mjs

@@ -0,0 +1,205 @@
+#!/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 {
+  UNIVERSAL_WORKFLOW_REQUEST,
+  validateUniversalWorkflowRequest,
+  universalWorkflowAdmissionRoot,
+} from "../packages/core/universal-workflow-bootstrap.js";
+
+const SHA = /^[0-9a-f]{40}$/u;
+
+function fail(message) {
+  throw new Error(message);
+}
+
+function canonical(value) {
+  if (Array.isArray(value)) return value.map(canonical);
+  if (value && typeof value === "object")
+    return Object.fromEntries(
+      Object.keys(value)
+        .sort((left, right) => Buffer.from(left).compare(Buffer.from(right)))
+        .map((key) => [key, canonical(value[key])]),
+    );
+  return value;
+}
+
+function contentRoot(domain, value) {
+  const hash = crypto.createHash("sha256");
+  hash.update(domain, "utf8");
+  hash.update(Buffer.from([0]));
+  hash.update(`${JSON.stringify(canonical(value))}\n`, "utf8");
+  return `sha256:${hash.digest("hex")}`;
+}
+
+function defaultPolicy() {
+  return JSON.parse(
+    fs.readFileSync(
+      new URL(
+        "../architecture/universal-workflow-train-admission.json",
+        import.meta.url,
+      ),
+    ),
+  );
+}
+
+function exactSha(value, label) {
+  const normalized = String(value || "").toLowerCase();
+  if (!SHA.test(normalized)) fail(`${label} must be an exact Git SHA`);
+  return normalized;
+}
+
+export function createUniversalSelfDogfoodRequest({
+  candidateSha,
+  consumerSha,
+  pullRequest,
+  channel,
+  policy = defaultPolicy(),
+}) {
+  const expectedSha = exactSha(candidateSha, "candidateSha");
+  const sourceSha = exactSha(consumerSha, "consumerSha");
+  if (!Number.isSafeInteger(pullRequest) || pullRequest < 1)
+    fail("pullRequest must be a positive integer");
+  if (!["alpha", "stable", "conformance"].includes(channel))
+    fail("channel must be alpha, stable, or conformance");
+  const capability =
+    channel === "conformance"
+      ? {
+          id: "bootstrap-conformance",
+          payload: {
+            schema: "kungfu-buildchain-v4-universal-bootstrap-conformance/v1",
+            expectedGovernedWorkflowCount: 40,
+          },
+        }
+      : {
+          id: "release-candidate-promote",
+          payload: {
+            schema: "kungfu-buildchain-v4-universal-release-promotion/v1",
+            inputs: {
+              channel,
+              "dry-run": true,
+              "target-ref":
+                channel === "alpha" ? "alpha/v4/v4.0" : "release/v4/v4.0",
+              "target-sha": sourceSha,
+            },
+            dryRunObservation: {
+              observedSha: sourceSha,
+              comparisonStatus: "identical",
+            },
+          },
+        };
+  return validateUniversalWorkflowRequest({
+    schema: UNIVERSAL_WORKFLOW_REQUEST,
+    mode: "train",
+    candidate: {
+      repository: "kungfu-systems/buildchain",
+      discoveryRef: "train/v4/v4.0/universal-reusable-workflow-bootstrap",
+      expectedSha,
+      admissionRoot: universalWorkflowAdmissionRoot(policy),
+      reviewPullRequest: pullRequest,
+    },
+    consumer: {
+      repository: "kungfu-systems/buildchain",
+      workflow: ".github/workflows/self-ops-bootstrap-dogfood.yml",
+      sourceSha,
+    },
+    capability: {
+      id: capability.id,
+      contractRoots: policy.contractRoots,
+      permissions: { contents: "read" },
+    },
+    payload: capability.payload,
+  });
+}
+
+function exactResult(value, label, expectedSha, expectedChannel) {
+  if (
+    value?.schema !== "kungfu-buildchain-v4-universal-workflow-result/v1" ||
+    value.status !== "succeeded" ||
+    value.runtime?.repository !== "kungfu-systems/buildchain" ||
+    value.runtime?.sha !== expectedSha
+  )
+    fail(`${label} is not a successful exact-Train result`);
+  if (expectedChannel === "conformance") {
+    if (
+      value.output?.schema !==
+        "kungfu-buildchain-v4-universal-bootstrap-conformance-result/v1" ||
+      value.output?.status !== "candidate-engine-executed"
+    )
+      fail(`${label} did not execute the candidate conformance engine`);
+  } else if (
+    value.output?.dryRun !== true ||
+    value.output?.route?.decision !== "Fresh" ||
+    value.output?.route?.channel !== expectedChannel
+  ) {
+    fail(
+      `${label} did not execute the ${expectedChannel}-shaped release route`,
+    );
+  }
+  return value;
+}
+
+export function verifyUniversalSelfDogfoodPair({
+  primary,
+  recovery,
+  expectedSha,
+  channel,
+}) {
+  const sha = exactSha(expectedSha, "expectedSha");
+  const left = exactResult(primary, "primary result", sha, channel);
+  const right = exactResult(recovery, "recovery result", sha, channel);
+  for (const field of ["requestRoot", "capabilityRoot", "resultRoot"]) {
+    if (left[field] !== right[field])
+      fail(`primary and recovery ${field} differ`);
+  }
+  const body = {
+    schema: "kungfu-buildchain-v4-universal-self-dogfood-pair/v1",
+    channel,
+    runtimeSha: sha,
+    requestRoot: left.requestRoot,
+    capabilityRoot: left.capabilityRoot,
+    resultRoot: left.resultRoot,
+    equivalent: true,
+  };
+  return {
+    ...body,
+    pairRoot: contentRoot("universal-self-dogfood-pair", body),
+  };
+}
+
+function option(name) {
+  const index = process.argv.indexOf(`--${name}`);
+  return index >= 0 ? process.argv[index + 1] : "";
+}
+
+async function main() {
+  const command = process.argv[2];
+  if (command === "request") {
+    const request = createUniversalSelfDogfoodRequest({
+      candidateSha: option("candidate-sha"),
+      consumerSha: option("consumer-sha"),
+      pullRequest: Number(option("pull-request")),
+      channel: option("channel"),
+    });
+    process.stdout.write(`${JSON.stringify(request)}\n`);
+    return;
+  }
+  if (command === "verify-pair") {
+    const result = verifyUniversalSelfDogfoodPair({
+      primary: JSON.parse(process.env.BUILDCHAIN_PRIMARY_RESULT_JSON || ""),
+      recovery: JSON.parse(process.env.BUILDCHAIN_RECOVERY_RESULT_JSON || ""),
+      expectedSha: option("candidate-sha"),
+      channel: option("channel"),
+    });
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+    return;
+  }
+  fail("command must be request or verify-pair");
+}
+
+const isMain =
+  process.argv[1] &&
+  fileURLToPath(import.meta.url) === path.resolve(process.argv[1]);
+if (isMain) await main();

package/scripts/verify-version-state-delta.mjs

@@ -0,0 +1,175 @@
+import fs from "node:fs";
+import crypto from "node:crypto";
+import os from "node:os";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { pathToFileURL } from "node:url";
+import { invokeDomainWasm } from "../packages/core/domain-wasm.js";
+
+const execute = (command, args, options = {}) =>
+  execFileSync(command, args, {
+    maxBuffer: 64 * 1024 * 1024,
+    ...options,
+  });
+
+// Reconstruct with the protected base's generator. No candidate command runs.
+export function verifyVersionStateDelta({
+  baseSha,
+  headSha,
+  completedStableVersion,
+  cwd = process.cwd(),
+  nodeModules = path.resolve("node_modules"),
+}) {
+  if (![baseSha, headSha].every((value) => /^[a-f0-9]{40}$/u.test(value || "")))
+    throw new Error("version-state verification requires exact commits");
+  const git = (...args) => execute("git", args, { cwd }).toString().trim();
+  const bytes = (revision, file) =>
+    execute("git", ["show", `${revision}:${file}`], { cwd });
+  git("merge-base", "--is-ancestor", baseSha, headSha);
+  const changes = git("diff", "--raw", "--no-renames", baseSha, headSha)
+    .split("\n")
+    .filter(Boolean);
+  if (!changes.length) throw new Error("no version-state delta");
+  const temporary = fs.mkdtempSync(
+    path.join(os.tmpdir(), "buildchain-version-state-"),
+  );
+  const source = path.join(temporary, "source");
+  try {
+    fs.mkdirSync(source);
+    const archive = path.join(temporary, "base.tar");
+    git("-c", "core.autocrlf=false", "-c", "core.eol=lf", "archive", "--format=tar", `--output=${archive}`, baseSha);
+    execute("tar", ["-xf", "base.tar", "-C", "source"], { cwd: temporary });
+    fs.symlinkSync(nodeModules, path.join(source, "node_modules"), "junction");
+    const planSource = `
+      import fs from 'node:fs';
+      import { loadBuildchainConfig, discoverConfiguredVersionStateFiles,
+        updateConfiguredVersionStateContents } from './packages/core/buildchain-config.js';
+      const config = loadBuildchainConfig(process.cwd());
+      const files = discoverConfiguredVersionStateFiles(process.cwd(), config);
+      const allowed = [...new Set([...files.map(f => f.path), ...config.config.version.derivedFiles])];
+      if (JSON.stringify(config.config.lifecycle['version-state'].commands) !== JSON.stringify(['node scripts/generate-site-bundle.mjs']))
+        throw new Error('unsupported version-state generator');
+      if (process.env.BUILDCHAIN_DELTA_VERSION)
+        for (const f of updateConfiguredVersionStateContents(files, process.env.BUILDCHAIN_DELTA_VERSION))
+          fs.writeFileSync(f.path, f.content);
+      console.log(JSON.stringify(allowed));
+    `;
+    const plan = (version = "") =>
+      JSON.parse(
+        execute(process.execPath, ["--input-type=module", "-e", planSource], {
+          cwd: source,
+          env: { ...process.env, BUILDCHAIN_DELTA_VERSION: version },
+        }),
+      );
+    const allowed = plan();
+    for (const file of allowed)
+      if (path.isAbsolute(file) || file.split(/[\\/]/u).includes(".."))
+        throw new Error("unsafe declared version-state path");
+    for (const change of changes) {
+      const match = change.match(
+        /^:100644 100644 [a-f0-9]+ [a-f0-9]+ M\t(.+)$/u,
+      );
+      if (!match || !allowed.includes(match[1]))
+        throw new Error(
+          "delta includes undeclared source, lock, config or file mode changes",
+        );
+    }
+    const version = JSON.parse(bytes(headSha, "package.json")).version;
+    invokeDomainWasm("source-version-projection", {
+      baseVersion: JSON.parse(bytes(baseSha, "package.json")).version,
+      version,
+      ...(completedStableVersion ? { completedStableVersion } : {}),
+    });
+    const metadata = JSON.parse(bytes(headSha, "dist/site/site-manifest.json"));
+    if (
+      metadata.sourceRevision !== baseSha ||
+      metadata.package.version !== version ||
+      !Number.isFinite(Date.parse(metadata.generatedAt)) ||
+      metadata.generatedAt !== metadata.publishedAt
+    )
+      throw new Error(
+        "version-state projection source metadata is not bound to base",
+      );
+    plan(version);
+    execute(process.execPath, ["scripts/generate-site-bundle.mjs"], {
+      cwd: source,
+      env: {
+        ...process.env,
+        BUILDCHAIN_SOURCE_SHA: baseSha,
+        BUILDCHAIN_SITE_GENERATED_AT: metadata.generatedAt,
+        BUILDCHAIN_SITE_PUBLISHED_AT: metadata.publishedAt,
+        BUILDCHAIN_SITE_TIMESTAMP_POLICY: "ci-injected",
+        BUILDCHAIN_SURFACE_GENERATED_AT: metadata.generatedAt,
+        BUILDCHAIN_SURFACE_PUBLISHED_AT: metadata.publishedAt,
+        SOURCE_DATE_EPOCH: "0",
+      },
+    });
+    // Git blob hashes compare all tracked bytes without executing candidate code.
+    const expected = new Map(
+      git("ls-tree", "-r", headSha)
+        .split("\n")
+        .map((line) => {
+          const [meta, file] = line.split("\t");
+          return [file, meta.split(" ")[2]];
+        }),
+    );
+    for (const [file, digest] of expected) {
+      const generated = path.join(source, file);
+      const bytes = fs.lstatSync(generated).isSymbolicLink()
+        ? Buffer.from(fs.readlinkSync(generated))
+        : fs.readFileSync(generated);
+      const actual = crypto
+        .createHash("sha1")
+        .update(`blob ${bytes.length}\0`)
+        .update(bytes)
+        .digest("hex");
+      if (actual !== digest)
+        throw new Error(`version-state regeneration mismatch: ${file}`);
+    }
+    const walk = (directory) => {
+      for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+        const absolute = path.join(directory, entry.name);
+        if (absolute === path.join(source, "node_modules")) continue;
+        if (entry.isDirectory()) walk(absolute);
+        else if (
+          !expected.has(
+            path.relative(source, absolute).split(path.sep).join("/"),
+          )
+        )
+          throw new Error("version-state generator created undeclared output");
+      }
+    };
+    walk(source);
+    return {
+      validationKind: "version-state-projection",
+      baseSha,
+      headSha,
+      sourceTree: git("rev-parse", `${headSha}^{tree}`),
+      version,
+      changedPaths: changes.map((change) => change.split("\t")[1]),
+      generator: "scripts/generate-site-bundle.mjs",
+      generatedAt: metadata.generatedAt,
+    };
+  } finally {
+    fs.rmSync(temporary, { recursive: true, force: true });
+  }
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  try {
+    console.log(
+      JSON.stringify(
+        verifyVersionStateDelta({
+          baseSha: process.argv[2],
+          headSha: process.argv[3],
+        }),
+      ),
+    );
+  } catch (error) {
+    console.error(error.message);
+    process.exitCode = 1;
+  }
+}

package/scripts/{v4-warrant-shadow-plan.mjs → warrant-shadow-plan.mjs}

@@ -16,14 +16,14 @@ import {
   submitDevDeliveryCandidate,
 } from "../packages/core/dev-delivery-warrant.js";
 
-const PLAN_PATH = "architecture/v4-delivery-warrant-shadow-bootstrap-plan.json";
+const PLAN_PATH = "architecture/delivery-warrant-shadow-bootstrap-plan.json";
 const PLAN_SCHEMA_PATH =
-  "architecture/v4-delivery-warrant-shadow-bootstrap-plan.schema.json";
-const FIXTURES_PATH = "architecture/v4-delivery-warrant-shadow-fixtures.json";
+  "architecture/delivery-warrant-shadow-bootstrap-plan.schema.json";
+const FIXTURES_PATH = "architecture/delivery-warrant-shadow-fixtures.json";
 const FIXTURES_SCHEMA_PATH =
-  "architecture/v4-delivery-warrant-shadow-fixtures.schema.json";
-const MANIFEST_PATH = "architecture/v4-capability-state-machine-manifest.json";
-const BOOTSTRAP_PATH = "architecture/v4-bootstrap-authority.json";
+  "architecture/delivery-warrant-shadow-fixtures.schema.json";
+const MANIFEST_PATH = "architecture/capability-state-machine-manifest.json";
+const BOOTSTRAP_PATH = "architecture/bootstrap-authority.json";
 const ROOT_PATTERN = /^sha256:[0-9a-f]{64}$/u;
 const REQUIRED_PRIMITIVES = [
   "canonical-json",