@kungfu-tech/buildchain 4.0.0 → 4.0.1-alpha.10

package/architecture/v4-tail-reseal-parity.json

@@ -0,0 +1,150 @@
+{
+  "schemaVersion": 1,
+  "contract": "kungfu-buildchain-v4-tail-reseal-parity",
+  "sourceAuthority": {
+    "branch": "dev/v3/v3.0",
+    "capturedCommit": "6b96bdad8d9f8ccf9275f27d9370a226a9c78465",
+    "implementation": "scripts/release-candidate-tail-reseal.mjs",
+    "workflow": ".github/workflows/.build.yml",
+    "tests": "tests/release-candidate-tail-reseal.test.mjs"
+  },
+  "target": {
+    "branch": "dev/v4/v4.0",
+    "publicReusableWorkflow": "kungfu-systems/buildchain/.github/workflows/v4-tail-reseal.yml@v4-alpha",
+    "requestSchema": "contracts/v4-tail-reseal-v1.schema.json",
+    "planner": "packages/core/v4-tail-reseal.js",
+    "admission": "packages/core/v4-tail-reseal-github.js",
+    "receipt": "packages/core/v4-tail-reseal-receipt.js",
+    "cli": "buildchain tail-reseal"
+  },
+  "authority": {
+    "productionAuthority": "v4",
+    "stageCapsuleEffectAuthority": "none",
+    "signingAuthority": "explicit-live-release-tail",
+    "credentialAuthority": "lease-bound-secret-island",
+    "runtimePersistence": "floating-only",
+    "v3BehaviorChange": false
+  },
+  "allowedDispositions": [
+    "implemented",
+    "superseded-equivalent",
+    "missing-before-closeout"
+  ],
+  "invariants": [
+    {
+      "id": "TR-01",
+      "claim": "The exact captured v3 retained-candidate script, workflow and tests are rooted as parity authority.",
+      "disposition": "implemented",
+      "implementationEvidence": ["architecture/v4-tail-reseal-parity.json"],
+      "verificationEvidence": ["tests/v4-tail-reseal-parity.test.mjs"]
+    },
+    {
+      "id": "TR-02",
+      "claim": "One exact failed run binds four byte-addressed platform payloads, manifests, archives and Stage Capsules.",
+      "disposition": "implemented",
+      "implementationEvidence": [
+        "contracts/v4-tail-reseal-v1.schema.json",
+        "packages/core/v4-tail-reseal-github.js"
+      ],
+      "verificationEvidence": [
+        "contracts/fixtures/v4-tail-reseal-v1/valid.json",
+        "tests/v4-tail-reseal.test.mjs"
+      ]
+    },
+    {
+      "id": "TR-03",
+      "claim": "A fresh runner downloads retained archives and verifies every manifest and payload byte before any tail effect.",
+      "disposition": "implemented",
+      "implementationEvidence": [
+        "scripts/v4-tail-reseal.mjs",
+        ".github/workflows/v4-tail-reseal.yml"
+      ],
+      "verificationEvidence": ["tests/v4-tail-reseal.test.mjs"]
+    },
+    {
+      "id": "TR-04",
+      "claim": "Install, build, verify, package and platform-matrix remain explicitly skipped under effect-free Stage Capsule reuse.",
+      "disposition": "implemented",
+      "implementationEvidence": ["packages/core/v4-tail-reseal.js"],
+      "verificationEvidence": ["tests/v4-tail-reseal.test.mjs"]
+    },
+    {
+      "id": "TR-05",
+      "claim": "Only macOS signing-finalization may change bytes; every other platform stays byte-identical and provider-effect-free.",
+      "disposition": "implemented",
+      "implementationEvidence": [
+        "packages/core/v4-tail-reseal-receipt.js",
+        "scripts/v4-tail-reseal.mjs"
+      ],
+      "verificationEvidence": ["tests/v4-tail-reseal.test.mjs"]
+    },
+    {
+      "id": "TR-06",
+      "claim": "The macOS effect is fenced by exact Warrant lineage, credential authority, release-tail transaction and idempotency key.",
+      "disposition": "implemented",
+      "implementationEvidence": [
+        "packages/core/v4-tail-reseal.js",
+        ".github/workflows/v4-tail-reseal.yml"
+      ],
+      "verificationEvidence": ["tests/v4-tail-reseal.test.mjs"]
+    },
+    {
+      "id": "TR-07",
+      "claim": "Source, platform, archive, manifest, signer, Warrant, credential, retention and prior-failure drift fails closed.",
+      "disposition": "implemented",
+      "implementationEvidence": [
+        "packages/core/v4-tail-reseal.js",
+        "packages/core/v4-tail-reseal-github.js"
+      ],
+      "verificationEvidence": ["tests/v4-tail-reseal.test.mjs"]
+    },
+    {
+      "id": "TR-08",
+      "claim": "Expired retention or credential leases invalidate reuse and require a normal candidate rebuild.",
+      "disposition": "implemented",
+      "implementationEvidence": ["packages/core/v4-tail-reseal.js"],
+      "verificationEvidence": ["tests/v4-tail-reseal.test.mjs"]
+    },
+    {
+      "id": "TR-09",
+      "claim": "Successful reseal emits the ordinary v4 Release Candidate Passport with its original floating-consumer policy receipt.",
+      "disposition": "implemented",
+      "implementationEvidence": [
+        "packages/core/v4-tail-reseal-receipt.js",
+        ".github/workflows/v4-tail-reseal.yml"
+      ],
+      "verificationEvidence": ["tests/v4-tail-reseal.test.mjs"]
+    },
+    {
+      "id": "TR-10",
+      "claim": "The reusable workflow resolves job.workflow_sha as runtime evidence and exposes no persisted SHA, variable indirection or private self-dogfood path.",
+      "disposition": "implemented",
+      "implementationEvidence": [".github/workflows/v4-tail-reseal.yml"],
+      "verificationEvidence": ["tests/v4-tail-reseal-parity.test.mjs"]
+    },
+    {
+      "id": "TR-11",
+      "claim": "Node API, CLI, schema, deterministic fixture, generated references and macOS bounded qualification project one contract.",
+      "disposition": "implemented",
+      "implementationEvidence": [
+        "package.json",
+        "bin/buildchain.mjs",
+        "scripts/v4-tail-reseal.mjs",
+        "docs/v4-tail-reseal.md"
+      ],
+      "verificationEvidence": [
+        "tests/command-registry.test.mjs",
+        "tests/v4-tail-reseal.test.mjs",
+        "tests/v4-tail-reseal-parity.test.mjs"
+      ]
+    },
+    {
+      "id": "TR-12",
+      "claim": "Independent review, protected merge and exact post-merge public readback remain external closeout evidence.",
+      "disposition": "missing-before-closeout",
+      "implementationEvidence": [],
+      "verificationEvidence": []
+    }
+  ],
+  "matrixRoot": "sha256:126ec51c12a9dedeb9b9e187202781e3895856af1927b399ba3902f3940750ad"
+}

package/bin/buildchain.mjs

@@ -11,6 +11,7 @@ import { runLifecycle } from "../scripts/run-lifecycle-core.mjs";
 import { runReleasePropagationCli } from "../scripts/release-propagation.mjs";
 import { runReleaseGovernanceCli } from "../scripts/reconcile-release-governance.mjs";
 import { runReleaseTailCli } from "../scripts/release-tail.mjs";
+import { runV4TailResealCli } from "../scripts/v4-tail-reseal.mjs";
 import { runPublicationArtifactCli } from "../scripts/publication-artifact.mjs";
 import { runPublicationPackageCli } from "../scripts/publication-package.mjs";
 import { runPublicationReproducibilityCli } from "../scripts/publication-reproducibility.mjs";
@@ -109,6 +110,8 @@ import {
   dispatchTrustReleaseCommand,
 } from "./internal/trust-release-cli.mjs";
 import { dispatchRegisteredCommand } from "./internal/command-registry.mjs";
+import { runCompatibilityFactsCli } from "./internal/compatibility-facts-cli.mjs";
+import { runAdopterDeliveryCli } from "./internal/adopter-delivery-cli.mjs";
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const embeddedPackageVersion = process.env.BUILDCHAIN_EMBEDDED_PACKAGE_VERSION || "";
@@ -987,6 +990,9 @@ async function runKfdCli(args = []) {
 async function runBuildFactsCli(args = []) {
   const [subcommand = "", ...factArgs] = args;
   const cwd = path.resolve(readFlag(factArgs, "cwd", process.cwd()));
+  if (subcommand === "compatibility") {
+    return runCompatibilityFactsCli({ args: factArgs, cwd, packageRoot: root });
+  }
   if (subcommand === "module") {
     const fact = collectModuleBuildFacts({
       cwd,
@@ -1060,7 +1066,7 @@ async function runBuildFactsCli(args = []) {
     }
     return;
   }
-  throw new Error("usage: buildchain facts <module|aggregate|verify> ...");
+  throw new Error("usage: buildchain facts <module|aggregate|verify|compatibility> ...");
 }
 
 function appendJsonLine(filePath, value) {
@@ -1385,12 +1391,20 @@ async function handleDevCommand(args) {
       runScript("dev-delivery-warrant.mjs", devArgs);
       return;
     }
+    if (subcommand === "authority") {
+      runScript("dev-delivery-authority.mjs", devArgs);
+      return;
+    }
     if (subcommand === "proof") {
       runScript("dev-delivery-proof.mjs", devArgs);
       return;
     }
+    if (subcommand === "two-phase") {
+      runScript("dev-delivery-two-phase.mjs", devArgs);
+      return;
+    }
     if (subcommand !== "merge-queue") {
-      throw new Error("usage: buildchain dev <pr-admit|merge-queue|warrant|proof> [options]");
+      throw new Error("usage: buildchain dev <pr-admit|merge-queue|warrant|authority|proof|two-phase> [options]");
     }
     runScript("dev-merge-queue.mjs", devArgs);
     return;
@@ -1662,7 +1676,15 @@ async function handleReleaseGovernanceCommand(args) {
 }
 
 async function handleReleaseTailCommand(args) {
-  runReleaseTailCli(args);
+  await runReleaseTailCli(args);
+}
+
+async function handleTailResealCommand(args) {
+  await runV4TailResealCli(args);
+}
+
+async function handleNextDevelopmentCommand(args) {
+  runScript("next-development-transition.mjs", args);
 }
 
 async function handleGitHubGovernanceCommand(args) {
@@ -1729,6 +1751,10 @@ async function handleArchitectureCommand(args) {
   runScript("v4-architecture.mjs", args);
 }
 
+async function handleAdopterDeliveryCommand(args) {
+  await runAdopterDeliveryCli(args);
+}
+
 const BUILDCHAIN_COMMAND_HANDLERS = Object.freeze({
   "help": handleHelpCommand,
   "version": handleVersionCommand,
@@ -1761,12 +1787,15 @@ const BUILDCHAIN_COMMAND_HANDLERS = Object.freeze({
   "release-propagation": handleReleasePropagationCommand,
   "release-governance": handleReleaseGovernanceCommand,
   "release-tail": handleReleaseTailCommand,
+  "tail-reseal": handleTailResealCommand,
+  "next-development": handleNextDevelopmentCommand,
   "github-governance": handleGitHubGovernanceCommand,
   "badges": handleBadgesCommand,
   "homebrew": handleHomebrewCommand,
   "build-contract": handleBuildContractCommand,
   "publish-source": handlePublishSourceCommand,
   "architecture": handleArchitectureCommand,
+  "adopter-delivery": handleAdopterDeliveryCommand,
 });
 
 async function main(argv = process.argv.slice(2)) {

package/bin/internal/adopter-delivery-cli.mjs

@@ -0,0 +1,70 @@
+import {
+  loadV4PublishedAdopterDeliveryAuthority,
+  qualifyV4AdopterDeliveryBootstrap,
+  runV4AdopterDeliveryGate,
+  verifyV4AdopterDeliveryReadback,
+} from "../../packages/core/v4-adopter-delivery.js";
+import {
+  printJson,
+  readFlag,
+  readJsonInput,
+  writeJsonFile,
+} from "./cli-options.mjs";
+
+function emit(args, value) {
+  writeJsonFile(readFlag(args, "output", ""), value);
+  printJson(value);
+}
+
+export async function runAdopterDeliveryCli(args = []) {
+  const [subcommand = "", ...commandArgs] = args;
+  if (subcommand === "run") {
+    const input = readJsonInput(readFlag(commandArgs, "input", ""), {
+      label: "adopter delivery input",
+    });
+    emit(commandArgs, runV4AdopterDeliveryGate(input));
+    return;
+  }
+  if (subcommand === "verify") {
+    const input = readJsonInput(readFlag(commandArgs, "input", ""), {
+      label: "adopter delivery input",
+    });
+    const readback = readJsonInput(readFlag(commandArgs, "readback", ""), {
+      label: "adopter delivery readback",
+    });
+    emit(commandArgs, verifyV4AdopterDeliveryReadback({ input, readback }));
+    return;
+  }
+  if (subcommand === "bootstrap") {
+    const request = readJsonInput(readFlag(commandArgs, "input", ""), {
+      label: "adopter delivery bootstrap input",
+    });
+    emit(commandArgs, qualifyV4AdopterDeliveryBootstrap(request));
+    return;
+  }
+  if (subcommand === "archive") {
+    const request = readJsonInput(readFlag(commandArgs, "input", ""), {
+      label: "published archive input",
+    });
+    const authority = await loadV4PublishedAdopterDeliveryAuthority(request);
+    try {
+      emit(commandArgs, {
+        schemaVersion: authority.schemaVersion,
+        contract: authority.contract,
+        packages: authority.packages,
+        moduleCoordinates: authority.moduleCoordinates,
+        authorityRoot: authority.authorityRoot,
+        qualifying: authority.qualifying,
+        selfCertified: authority.selfCertified,
+        releaseAuthorized: authority.releaseAuthorized,
+        finalAuthority: authority.finalAuthority,
+      });
+    } finally {
+      await authority.dispose();
+    }
+    return;
+  }
+  throw new Error(
+    "usage: buildchain adopter-delivery <run|verify|bootstrap|archive> --input <json-or-path> [--readback <json-or-path>] [--output <path>]",
+  );
+}

package/bin/internal/command-registry.mjs

@@ -33,12 +33,15 @@ const BUILDCHAIN_COMMAND_REGISTRY = Object.freeze([
   { id: "release-propagation", aliases: [] },
   { id: "release-governance", aliases: [] },
   { id: "release-tail", aliases: [] },
+  { id: "tail-reseal", aliases: [] },
+  { id: "next-development", aliases: [] },
   { id: "github-governance", aliases: [] },
   { id: "badges", aliases: [] },
   { id: "homebrew", aliases: [] },
   { id: "build-contract", aliases: [] },
   { id: "publish-source", aliases: [] },
   { id: "architecture", aliases: [] },
+  { id: "adopter-delivery", aliases: [] },
 ]);
 
 function buildCommandLookup(registry = BUILDCHAIN_COMMAND_REGISTRY) {

package/bin/internal/compatibility-facts-cli.mjs

@@ -0,0 +1,101 @@
+import path from "node:path";
+
+import {
+  createBuildchainCompatibilityFactRegistry,
+  verifyBuildchainCompatibilityFactRegistry,
+} from "../../packages/core/buildchain-compatibility-fact.js";
+import {
+  createBuildchainCompatibilityPathQuery,
+  createBuildchainCompatibilityProofRegistry,
+  verifyBuildchainCompatibilityPath,
+} from "../../packages/core/buildchain-compatibility-authority.js";
+import { createBuildchainContractWorld } from "../../packages/core/buildchain-contract.js";
+import {
+  printJson,
+  readBooleanFlag,
+  readFlag,
+  readJsonInput,
+  writeJsonFile,
+} from "./cli-options.mjs";
+
+export function runCompatibilityFactsCli({ args, cwd, packageRoot }) {
+  const [action = "project", ...factArgs] = args;
+  const registryInput = readFlag(factArgs, "registry", "");
+  const registry = registryInput
+    ? readJsonInput(registryInput, {
+        cwd,
+        label: "compatibility Fact registry",
+      })
+    : createBuildchainCompatibilityFactRegistry();
+  if (action === "project") {
+    const world = createBuildchainContractWorld({ root: packageRoot });
+    const projection = createBuildchainCompatibilityProofRegistry({
+      proofs: registry.legacyProofs,
+      surfaces: world.surfaces,
+      majorLine: world.majorLine,
+    });
+    const result = {
+      schema: "kungfu.buildchain.compatibility-fact-projection/v1",
+      authority: "Fact-registry-only",
+      grantsReleaseAuthority: false,
+      registry,
+      projections: projection.projections,
+    };
+    const output = readFlag(factArgs, "output", "");
+    if (output) writeJsonFile(path.resolve(cwd, output), result);
+    if (readBooleanFlag(factArgs, "json") || !output) printJson(result);
+    else
+      process.stdout.write(
+        `buildchain facts compatibility project: wrote ${output}\n`,
+      );
+    return;
+  }
+  if (action === "verify") {
+    const result = verifyBuildchainCompatibilityFactRegistry(registry);
+    printJson(result);
+    if (!result.ok) process.exitCode = 1;
+    return;
+  }
+  if (action === "query") {
+    const queryInput = readFlag(factArgs, "query", "");
+    if (!queryInput) {
+      throw new Error(
+        "usage: buildchain facts compatibility query --query <json-or-path> [--registry <json-or-path>]",
+      );
+    }
+    const query = readJsonInput(queryInput, {
+      cwd,
+      label: "compatibility Fact query",
+    });
+    const receipt = verifyBuildchainCompatibilityPath({ registry, query });
+    printJson(receipt);
+    if (receipt.record.status !== "accepted") process.exitCode = 1;
+    return;
+  }
+  if (action === "query-template") {
+    const factRoot = readFlag(factArgs, "fact-root", "");
+    const fact = registry.facts.find((entry) => entry.factRoot === factRoot);
+    if (!fact) {
+      throw new Error(
+        "buildchain facts compatibility query-template requires a current --fact-root",
+      );
+    }
+    printJson(
+      createBuildchainCompatibilityPathQuery({
+        registry,
+        queryId: readFlag(
+          factArgs,
+          "query-id",
+          `buildchain:compatibility:${fact.factId}`,
+        ),
+        sourceRoot: fact.sourceRoot,
+        targetRoot: fact.targetRoot,
+        relationPathRoots: [fact.factRoot],
+      }),
+    );
+    return;
+  }
+  throw new Error(
+    "usage: buildchain facts compatibility <project|verify|query|query-template> ...",
+  );
+}

package/bin/internal/trust-release-release-handlers.mjs

@@ -262,6 +262,11 @@ async function handleCollectCommand({ args, runScript, packageVersion }) {
       collectArgs,
       "release-evidence-json",
     ),
+    v4RuntimeResumeEvidenceJson: readFlag(
+      collectArgs,
+      "v4-runtime-resume-evidence-json",
+      "",
+    ),
     githubArtifactAttestationPolicyJsons: readRepeatedFlag(
       collectArgs,
       "github-artifact-attestation-policy-json",