@kungfu-tech/buildchain 3.0.9-alpha.8 → 4.0.0-alpha.0

package/scripts/v4-bridge-bootstrap.mjs

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const manifestPath = path.join(
+  root,
+  "crates",
+  "buildchain-v4-bridge",
+  "Cargo.toml",
+);
+
+function bridgeBinary(profile = "debug", platform = process.platform) {
+  return path.join(
+    root,
+    "crates",
+    "buildchain-v4-bridge",
+    "target",
+    profile,
+    `buildchain-v4-bridge${platform === "win32" ? ".exe" : ""}`,
+  );
+}
+
+function createV4HostRequest({
+  command,
+  args = [],
+  input = Buffer.alloc(0),
+  requiredCapabilities = ["canonical-input-v1", "exit-semantics-v1"],
+  timeoutMs = 5000,
+  requestId = crypto.randomUUID(),
+} = {}) {
+  return {
+    schemaVersion: 1,
+    contract: "kungfu-buildchain-v4-host-request",
+    protocolVersion: "1.0",
+    requestId,
+    command: { id: command, arguments: args },
+    input: { encoding: "base64", bytes: Buffer.from(input).toString("base64") },
+    requiredCapabilities,
+    timeoutMs,
+  };
+}
+
+function buildV4Bridge({ release = false } = {}) {
+  return spawnSync(
+    "cargo",
+    [
+      "build",
+      "--locked",
+      "--manifest-path",
+      manifestPath,
+      ...(release ? ["--release"] : []),
+    ],
+    { cwd: root, encoding: "utf8" },
+  );
+}
+
+function runV4Bridge(
+  request,
+  { mode = "exchange", profile = "debug", env = {}, encoding = null } = {},
+) {
+  const binary = bridgeBinary(profile);
+  if (!fs.existsSync(binary)) {
+    throw new Error(
+      `Buildchain v4 bridge is not built: ${path.relative(root, binary)}; run pnpm bridge:v4:build`,
+    );
+  }
+  return spawnSync(binary, [mode], {
+    cwd: root,
+    env: {
+      ...process.env,
+      BUILDCHAIN_V4_HOST_COMMAND: process.execPath,
+      BUILDCHAIN_V4_HOST_SCRIPT: path.join(
+        root,
+        "scripts",
+        "v4-host-adapter.mjs",
+      ),
+      ...env,
+    },
+    input: JSON.stringify(request),
+    encoding,
+    maxBuffer: 16 * 1024 * 1024,
+  });
+}
+
+function parseRunArgs(args) {
+  const separator = args.indexOf("--");
+  const bridgeArgs = separator === -1 ? args : args.slice(0, separator);
+  const commandArgs = separator === -1 ? [] : args.slice(separator + 1);
+  const command = bridgeArgs[0];
+  if (!command) {
+    throw new Error(
+      "usage: node scripts/v4-bridge-bootstrap.mjs <run|exchange> <command-id> -- [command-args...]",
+    );
+  }
+  return { command, commandArgs };
+}
+
+function main(args = process.argv.slice(2)) {
+  const [mode = "", ...rest] = args;
+  if (mode === "build") {
+    const result = buildV4Bridge({ release: rest.includes("--release") });
+    process.stdout.write(result.stdout || "");
+    process.stderr.write(result.stderr || "");
+    process.exitCode = result.status ?? 1;
+    return;
+  }
+  if (!["run", "exchange"].includes(mode)) {
+    throw new Error(
+      "usage: node scripts/v4-bridge-bootstrap.mjs <build|run|exchange> ...",
+    );
+  }
+  const { command, commandArgs } = parseRunArgs(rest);
+  const input = fs.readFileSync(0);
+  const request = createV4HostRequest({ command, args: commandArgs, input });
+  const result = runV4Bridge(request, {
+    mode: mode === "run" ? "compat" : "exchange",
+  });
+  if (result.error) throw result.error;
+  process.stdout.write(result.stdout || Buffer.alloc(0));
+  process.stderr.write(result.stderr || Buffer.alloc(0));
+  process.exitCode = result.status ?? 1;
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href
+) {
+  try {
+    main();
+  } catch (error) {
+    process.stderr.write(`buildchain v4 bridge bootstrap: ${error.message}\n`);
+    process.exitCode = 1;
+  }
+}
+
+export { bridgeBinary, buildV4Bridge, createV4HostRequest, main, runV4Bridge };

package/scripts/v4-bridge-evidence.mjs

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+
+import { execFileSync, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+import {
+  bridgeBinary,
+  buildV4Bridge,
+  createV4HostRequest,
+  runV4Bridge,
+} from "./v4-bridge-bootstrap.mjs";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const hostScript = path.join(root, "scripts", "v4-host-adapter.mjs");
+
+function flag(args, name, fallback = "") {
+  const index = args.indexOf(`--${name}`);
+  return index === -1 ? fallback : args[index + 1] || fallback;
+}
+
+function git(rootPath, args) {
+  return execFileSync("git", args, { cwd: rootPath, encoding: "utf8" }).trim();
+}
+
+function timed(run, iterations) {
+  const samples = [];
+  for (let index = 0; index < iterations; index += 1) {
+    const started = process.hrtime.bigint();
+    const result = run();
+    const elapsed = Number(process.hrtime.bigint() - started) / 1_000_000;
+    if (result.status !== 0) {
+      throw new Error(
+        result.stderr?.toString("utf8") || `probe exited ${result.status}`,
+      );
+    }
+    samples.push(elapsed);
+  }
+  samples.sort((left, right) => left - right);
+  return {
+    iterations,
+    medianMs: Number(samples[Math.floor(samples.length / 2)].toFixed(3)),
+    minMs: Number(samples[0].toFixed(3)),
+    maxMs: Number(samples.at(-1).toFixed(3)),
+  };
+}
+
+function collectEvidence(args = process.argv.slice(2)) {
+  const iterations = Number.parseInt(flag(args, "iterations", "7"), 10);
+  if (!Number.isInteger(iterations) || iterations < 3 || iterations > 50) {
+    throw new Error("--iterations must be between 3 and 50");
+  }
+  const build = buildV4Bridge({ release: true });
+  if (build.status !== 0) throw new Error(build.stderr || build.stdout);
+  const binary = bridgeBinary("release");
+  const request = createV4HostRequest({
+    command: "architecture.list",
+    args: ["--json"],
+  });
+  const serialized = JSON.stringify(request);
+  const direct = timed(
+    () =>
+      spawnSync(process.execPath, [hostScript], {
+        cwd: root,
+        input: serialized,
+        encoding: "utf8",
+        maxBuffer: 16 * 1024 * 1024,
+      }),
+    iterations,
+  );
+  const bridge = timed(
+    () =>
+      runV4Bridge(request, {
+        mode: "exchange",
+        profile: "release",
+        encoding: "utf8",
+      }),
+    iterations,
+  );
+
+  const libnodeRoot = flag(
+    args,
+    "libnode-root",
+    process.env.BUILDCHAIN_LIBNODE_ROOT || "",
+  );
+  let libnode = {
+    observed: false,
+    repository: "kungfu-systems/libnode",
+    revision: null,
+    artifactBytes: null,
+  };
+  if (libnodeRoot) {
+    const artifact = fs
+      .readdirSync(path.join(libnodeRoot, "dist", "node"))
+      .find((entry) => /^libnode\..+\.(?:dylib|so|dll)$/u.test(entry));
+    libnode = {
+      observed: Boolean(artifact),
+      repository: "kungfu-systems/libnode",
+      revision: git(libnodeRoot, ["rev-parse", "HEAD"]),
+      artifactBytes: artifact
+        ? fs.statSync(path.join(libnodeRoot, "dist", "node", artifact)).size
+        : null,
+    };
+  }
+
+  return {
+    schemaVersion: 1,
+    contract: "kungfu-buildchain-v4-bridge-evidence",
+    generatedAt: new Date().toISOString(),
+    source: {
+      buildchainRevision: git(root, ["rev-parse", "HEAD"]),
+      rustc: execFileSync("rustc", ["--version"], { encoding: "utf8" }).trim(),
+      node: process.version,
+      platform: process.platform,
+      architecture: process.arch,
+    },
+    selection: "rust-trunk-node-subprocess-host-v1",
+    contractPath: "contracts/v4-host-contract-v1.schema.json",
+    measurements: {
+      directNodeHostColdStart: direct,
+      rustSubprocessBridgeColdStart: bridge,
+      rustReleaseBinaryBytes: fs.statSync(binary).size,
+      libnode,
+    },
+  };
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href
+) {
+  try {
+    process.stdout.write(`${JSON.stringify(collectEvidence(), null, 2)}\n`);
+  } catch (error) {
+    process.stderr.write(`buildchain v4 bridge evidence: ${error.message}\n`);
+    process.exitCode = 1;
+  }
+}
+
+export { collectEvidence, timed };

package/scripts/v4-host-adapter.mjs

@@ -0,0 +1,182 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { architectureList, architectureShow } from "./v4-architecture.mjs";
+
+const MAX_REQUEST_BYTES = 8 * 1024 * 1024;
+const SUPPORTED_CAPABILITIES = Object.freeze([
+  "architecture-read-v1",
+  "cancellation-v1",
+  "canonical-input-v1",
+  "diagnostics-v1",
+  "exit-semantics-v1",
+  "structured-result-v1",
+]);
+
+function encodedBytes(value = Buffer.alloc(0)) {
+  return { encoding: "base64", bytes: Buffer.from(value).toString("base64") };
+}
+
+function response(request, overrides = {}) {
+  return {
+    schemaVersion: 1,
+    contract: "kungfu-buildchain-v4-host-response",
+    protocolVersion: "1.0",
+    requestId: request.requestId,
+    status: "ok",
+    host: {
+      kind: "node-subprocess",
+      implementation: "buildchain-v4-mjs-adapter",
+      capabilities: [...SUPPORTED_CAPABILITIES],
+    },
+    command: request.command,
+    output: {
+      stdout: encodedBytes(),
+      stderr: encodedBytes(),
+    },
+    structuredResult: null,
+    diagnostics: [],
+    exit: { code: 0, signal: null },
+    ...overrides,
+  };
+}
+
+function validateRequest(request) {
+  if (
+    request?.schemaVersion !== 1 ||
+    request?.contract !== "kungfu-buildchain-v4-host-request" ||
+    request?.protocolVersion !== "1.0"
+  ) {
+    throw new Error("unsupported Buildchain v4 host request contract");
+  }
+  if (!request.requestId || !request.command?.id) {
+    throw new Error("requestId and command.id must be non-empty");
+  }
+  if (
+    request.input?.encoding !== "base64" ||
+    typeof request.input?.bytes !== "string"
+  ) {
+    throw new Error("input must contain canonical base64 bytes");
+  }
+  Buffer.from(request.input.bytes, "base64");
+}
+
+function unsupportedResponse(request, unsupported) {
+  const message = `unsupported host capabilities: ${unsupported.join(", ")}`;
+  return response(request, {
+    status: "unsupported",
+    output: { stdout: encodedBytes(), stderr: encodedBytes(`${message}\n`) },
+    diagnostics: [
+      { code: "unsupported-capability", message, retryable: false },
+    ],
+    exit: { code: 64, signal: null },
+  });
+}
+
+async function dispatch(request, root = process.cwd()) {
+  validateRequest(request);
+  const unsupported = request.requiredCapabilities.filter(
+    (capability) => !SUPPORTED_CAPABILITIES.includes(capability),
+  );
+  if (unsupported.length > 0) return unsupportedResponse(request, unsupported);
+
+  const args = request.command.arguments;
+  if (request.command.id === "architecture.list") {
+    const result = architectureList(root);
+    return response(request, {
+      output: {
+        stdout: encodedBytes(
+          `${JSON.stringify(result, null, args.includes("--json") ? 2 : 0)}\n`,
+        ),
+        stderr: encodedBytes(),
+      },
+      structuredResult: result,
+    });
+  }
+  if (request.command.id === "architecture.show") {
+    const id = args.find((entry) => !entry.startsWith("--"));
+    try {
+      const result = architectureShow(id, root);
+      return response(request, {
+        output: {
+          stdout: encodedBytes(
+            `${JSON.stringify(result, null, args.includes("--json") ? 2 : 0)}\n`,
+          ),
+          stderr: encodedBytes(),
+        },
+        structuredResult: result,
+      });
+    } catch (error) {
+      const message = `buildchain architecture: ${error.message}`;
+      return response(request, {
+        status: "failed",
+        output: {
+          stdout: encodedBytes(),
+          stderr: encodedBytes(`${message}\n`),
+        },
+        diagnostics: [
+          { code: "legacy-command-failed", message, retryable: false },
+        ],
+        exit: { code: 1, signal: null },
+      });
+    }
+  }
+  if (request.command.id === "fixture.echo") {
+    const input = Buffer.from(request.input.bytes, "base64");
+    return response(request, {
+      output: { stdout: encodedBytes(input), stderr: encodedBytes() },
+      structuredResult: { bytes: input.length },
+    });
+  }
+  if (request.command.id === "fixture.fail") {
+    return response(request, {
+      status: "failed",
+      output: {
+        stdout: encodedBytes("partial-output\n"),
+        stderr: encodedBytes("controlled fixture failure\n"),
+      },
+      structuredResult: { failureClass: "controlled" },
+      diagnostics: [
+        {
+          code: "fixture-controlled-failure",
+          message: "controlled fixture failure",
+          retryable: false,
+        },
+      ],
+      exit: { code: 42, signal: null },
+    });
+  }
+  if (request.command.id === "fixture.wait") {
+    const delay = Number.parseInt(args[0] || "10000", 10);
+    await new Promise((resolve) => setTimeout(resolve, delay));
+    return response(request, {
+      structuredResult: { waitedMs: delay },
+    });
+  }
+  if (request.command.id === "fixture.crash") process.exit(86);
+  return unsupportedResponse(request, [`command:${request.command.id}`]);
+}
+
+async function main() {
+  const serialized = fs.readFileSync(0);
+  if (serialized.length > MAX_REQUEST_BYTES) {
+    throw new Error(`host request exceeds ${MAX_REQUEST_BYTES} bytes`);
+  }
+  const request = JSON.parse(serialized.toString("utf8"));
+  const result = await dispatch(request);
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href
+) {
+  main().catch((error) => {
+    process.stderr.write(`buildchain v4 host: ${error.message}\n`);
+    process.exitCode = 70;
+  });
+}
+
+export { SUPPORTED_CAPABILITIES, dispatch, response, validateRequest };

package/scripts/v4-platform-stage-checkpoint-rehearsal.mjs

@@ -0,0 +1,207 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+import { v4CanonicalBytes } from "../packages/core/v4-canonical-contracts.js";
+import { V4StageCapsuleLocalStore } from "../packages/core/v4-stage-capsule-local-store.js";
+import { v4StageCapsuleBlobRoot } from "../packages/core/v4-stage-capsule-store.js";
+import {
+  emitV4PlatformStageCheckpoint,
+  restoreV4PlatformStageCheckpoint,
+  validateV4PlatformStageCheckpointDeclaration,
+} from "../packages/core/v4-platform-stage-checkpoints.js";
+
+const repoRoot = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "..",
+);
+const scriptPath = fileURLToPath(import.meta.url);
+
+function option(name, fallback = "") {
+  const index = process.argv.indexOf(`--${name}`);
+  return index >= 0 ? process.argv[index + 1] : fallback;
+}
+
+function required(name) {
+  const value = option(name);
+  if (!value) throw new Error(`--${name} is required`);
+  return value;
+}
+
+function readDeclaration() {
+  return validateV4PlatformStageCheckpointDeclaration(
+    JSON.parse(
+      fs.readFileSync(
+        path.join(repoRoot, "architecture/v4-platform-stage-checkpoints.json"),
+        "utf8",
+      ),
+    ),
+  );
+}
+
+function stageFor(declaration, stageId) {
+  const stage = declaration.stages.find((entry) => entry.id === stageId);
+  if (!stage) throw new Error(`undeclared stage: ${stageId}`);
+  return stage;
+}
+
+function rooted(label) {
+  return v4StageCapsuleBlobRoot(Buffer.from(`${label}\n`, "utf8"));
+}
+
+function writeJson(file, value) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, v4CanonicalBytes(value), { flag: "wx" });
+}
+
+function emit({ workRoot, platformId, stageId, recordedAt }) {
+  const declaration = readDeclaration();
+  const stage = stageFor(declaration, stageId);
+  const inputs = Object.fromEntries(
+    stage.inputs.map((name) => [
+      name,
+      rooted(`${platformId}:${stageId}:input:${name}`),
+    ]),
+  );
+  const environment = Object.fromEntries(
+    stage.environment.map((name) => [name, `${platformId}-${name}-declared`]),
+  );
+  const toolchains = Object.fromEntries(
+    stage.toolchains.map((name) => [
+      name,
+      rooted(`${platformId}:toolchain:${name}`),
+    ]),
+  );
+  const outputs = Object.fromEntries(
+    stage.outputs.map(({ name }) => [
+      name,
+      Buffer.from(
+        `${platformId}:${stageId}:${name}:production-bytes\n`,
+        "utf8",
+      ),
+    ]),
+  );
+  const productionOutputRoots = Object.fromEntries(
+    Object.entries(outputs).map(([name, bytes]) => [
+      name,
+      v4StageCapsuleBlobRoot(bytes),
+    ]),
+  );
+  const store = new V4StageCapsuleLocalStore(path.join(workRoot, "store"));
+  const result = emitV4PlatformStageCheckpoint({
+    declaration,
+    platformId,
+    stageId,
+    stageOutcome: "success",
+    recordedAt,
+    overheadMs: 0,
+    inputs,
+    outputs,
+    productionOutputRoots,
+    productionLifecycleResult: { outcome: "success", stage: stageId },
+    shadowLifecycleResult: { outcome: "success", stage: stageId },
+    environment,
+    toolchains,
+    runtime: { engine: "node", mode: "clean-process-rehearsal" },
+    transformation: { command: "fixture-only", providerEffects: false },
+    qualification: { exactBytes: true, productionBytesChanged: false },
+    retentionPromise: {
+      class: "wave-evidence",
+      retainUntil: "2026-09-08T00:00:00.000Z",
+    },
+    store,
+  });
+  writeJson(path.join(workRoot, "emission.json"), {
+    schema: "buildchain-v4-platform-stage-rehearsal-emission/v1",
+    platform: platformId,
+    stage: stageId,
+    capsuleRoot: result.capsule.capsuleRoot,
+    report: result.report,
+    storeReceipt: result.receipt,
+  });
+}
+
+function restore({ workRoot, platformId, stageId, recordedAt }) {
+  const declaration = readDeclaration();
+  const emission = JSON.parse(
+    fs.readFileSync(path.join(workRoot, "emission.json"), "utf8"),
+  );
+  if (emission.platform !== platformId || emission.stage !== stageId)
+    throw new Error("emission identity does not match restore request");
+  const store = new V4StageCapsuleLocalStore(path.join(workRoot, "store"));
+  const result = restoreV4PlatformStageCheckpoint({
+    declaration,
+    expectedPlatform: platformId,
+    expectedStage: stageId,
+    capsuleRoot: emission.capsuleRoot,
+    recordedAt,
+    targetDirectory: path.join(workRoot, "restored"),
+    store,
+  });
+  writeJson(path.join(workRoot, "restore.json"), result.report);
+}
+
+function child(action, common) {
+  const result = spawnSync(
+    process.execPath,
+    [
+      scriptPath,
+      action,
+      "--work-root",
+      common.workRoot,
+      "--platform",
+      common.platformId,
+      "--stage",
+      common.stageId,
+      "--recorded-at",
+      common.recordedAt,
+    ],
+    { cwd: repoRoot, encoding: "utf8" },
+  );
+  if (result.status !== 0)
+    throw new Error(
+      `${action} child failed: ${(result.stderr || result.stdout).trim()}`,
+    );
+}
+
+const action = process.argv[2] || "";
+const common = {
+  workRoot: path.resolve(required("work-root")),
+  platformId: required("platform"),
+  stageId: option("stage", "build"),
+  recordedAt: required("recorded-at"),
+};
+
+if (action === "emit") emit(common);
+else if (action === "restore") restore(common);
+else if (action === "rehearse") {
+  fs.mkdirSync(common.workRoot, { recursive: true });
+  child("emit", common);
+  child("restore", common);
+  const emission = JSON.parse(
+    fs.readFileSync(path.join(common.workRoot, "emission.json"), "utf8"),
+  );
+  const restored = JSON.parse(
+    fs.readFileSync(path.join(common.workRoot, "restore.json"), "utf8"),
+  );
+  const evidence = {
+    schema: "buildchain-v4-platform-stage-clean-process-rehearsal/v1",
+    mode: "shadow-only",
+    platform: common.platformId,
+    stage: common.stageId,
+    capsuleRoot: emission.capsuleRoot,
+    emissionReportRoot: emission.report.reportRoot,
+    restoreReportRoot: restored.reportRoot,
+    exactRootVerified: restored.exactRootVerified,
+    productionBytesChanged: emission.report.productionBytesChanged,
+    lifecycleResultChanged: emission.report.lifecycleResultChanged,
+    providerCredentialsUsed: restored.providerCredentialsUsed,
+  };
+  writeJson(path.join(common.workRoot, "evidence.json"), evidence);
+  process.stdout.write(v4CanonicalBytes(evidence));
+} else {
+  throw new Error("action must be emit, restore, or rehearse");
+}