@kungfu-tech/buildchain 4.0.1-alpha.3 → 4.0.1-alpha.5

package/scripts/release-train-self-dogfood.mjs

@@ -6,7 +6,11 @@ import fs from "node:fs";
 import {
   closeDevDeliveryWarrant,
   createDevDeliveryQueue,
+  createNativeCommandContract,
+  createNativeProofReuseDecision,
+  createNativeQualificationProof,
   createReleaseBlockerPriorityClaim,
+  qualifyDevDeliveryWarrant,
   selectDevDeliveryWarrant,
   submitDevDeliveryCandidate,
 } from "../packages/core/dev-delivery-warrant.js";
@@ -81,9 +85,12 @@ function branch(value, label) {
   return normalized;
 }
 
-function at(recordedAt, seconds) {
-  return new Date(Date.parse(recordedAt) + seconds * 1000).toISOString();
-}
+const at = (recordedAt, seconds) => new Date(Date.parse(recordedAt) + seconds * 1000).toISOString();
+
+const normalizeFields = (input, fields, normalizer, prefix = "") =>
+  Object.fromEntries(fields.map((field) => [field, normalizer(input?.[field], `${prefix}${field}`)]));
+
+const requireEvidence = (condition, message) => { if (!condition) throw new Error(message); };
 
 function normalizeDelivery(input, expected) {
   const delivery = {
@@ -92,59 +99,44 @@ function normalizeDelivery(input, expected) {
       "delivery.pullRequestNumber",
     ),
     baseBranch: branch(input?.baseBranch, "delivery.baseBranch"),
-    headSha: sha(input?.headSha, "delivery.headSha"),
-    headTreeSha: sha(input?.headTreeSha, "delivery.headTreeSha"),
-    state: text(input?.state, "delivery.state"),
-    reviewState: text(input?.reviewState, "delivery.reviewState"),
-    reviewHeadSha: sha(input?.reviewHeadSha, "delivery.reviewHeadSha"),
-    mergeSha: sha(input?.mergeSha, "delivery.mergeSha"),
-    mergeTreeSha: sha(input?.mergeTreeSha, "delivery.mergeTreeSha"),
-    ciHeadSha: sha(input?.ciHeadSha, "delivery.ciHeadSha"),
-    ciConclusion: text(input?.ciConclusion, "delivery.ciConclusion"),
-    reviewRoot: root(input?.reviewRoot, "delivery.reviewRoot"),
-    ciRoot: root(input?.ciRoot, "delivery.ciRoot"),
-    mergeRoot: root(input?.mergeRoot, "delivery.mergeRoot"),
-    artifactRoot: root(input?.artifactRoot, "delivery.artifactRoot"),
-    installedProductRoot: root(
-      input?.installedProductRoot,
-      "delivery.installedProductRoot",
+    ...normalizeFields(
+      input,
+      ["headSha", "headTreeSha", "reviewHeadSha", "mergeSha", "mergeTreeSha", "ciHeadSha"],
+      sha,
+      "delivery.",
+    ),
+    ...normalizeFields(input, ["state", "reviewState", "ciConclusion"], text, "delivery."),
+    ...normalizeFields(
+      input,
+      ["reviewRoot", "ciRoot", "mergeRoot", "artifactRoot", "installedProductRoot"],
+      root,
+      "delivery.",
     ),
   };
-  if (delivery.baseBranch !== expected.sourceBranch) {
-    throw new Error(
-      "protected delivery base does not match the Release Cut source branch",
-    );
-  }
-  if (
-    delivery.state !== "MERGED" ||
-    delivery.reviewState !== "APPROVED" ||
-    delivery.ciConclusion !== "success"
-  ) {
-    throw new Error(
-      "protected delivery is not merged, approved, and CI-successful",
-    );
-  }
-  if (
-    delivery.headSha !== expected.devLandingSha ||
-    delivery.reviewHeadSha !== delivery.headSha
-  ) {
-    throw new Error(
-      "protected delivery review does not bind the exact repaired head",
-    );
-  }
-  if (
-    delivery.headTreeSha !== expected.cutCandidateTreeSha ||
-    delivery.mergeTreeSha !== delivery.headTreeSha
-  ) {
-    throw new Error(
-      "protected delivery merge tree does not equal the repaired candidate tree",
-    );
-  }
-  if (delivery.ciHeadSha !== delivery.mergeSha) {
-    throw new Error(
-      "protected delivery CI does not bind the merge-group result",
-    );
-  }
+  requireEvidence(
+    delivery.baseBranch === expected.sourceBranch,
+    "protected delivery base does not match the Release Cut source branch",
+  );
+  requireEvidence(
+    delivery.state === "MERGED" &&
+      delivery.reviewState === "APPROVED" &&
+      delivery.ciConclusion === "success",
+    "protected delivery is not merged, approved, and CI-successful",
+  );
+  requireEvidence(
+    delivery.headSha === expected.devLandingSha &&
+      delivery.reviewHeadSha === delivery.headSha,
+    "protected delivery review does not bind the exact repaired head",
+  );
+  requireEvidence(
+    delivery.headTreeSha === expected.cutCandidateTreeSha &&
+      delivery.mergeTreeSha === delivery.headTreeSha,
+    "protected delivery merge tree does not equal the repaired candidate tree",
+  );
+  requireEvidence(
+    delivery.ciHeadSha === delivery.mergeSha,
+    "protected delivery CI does not bind the merge-group result",
+  );
   return delivery;
 }
 
@@ -153,50 +145,32 @@ function normalizeInput(input = {}) {
     repository: repository(input.repository),
     sourceBranch: branch(input.sourceBranch, "sourceBranch"),
     targetBranch: branch(input.targetBranch, "targetBranch"),
-    assignmentRoot: root(input.assignmentRoot, "assignmentRoot"),
-    initiativeRoot: root(input.initiativeRoot, "initiativeRoot"),
-    dependencyProofRoot: root(input.dependencyProofRoot, "dependencyProofRoot"),
-    originDevSha: sha(input.originDevSha, "originDevSha"),
-    candidateSha: sha(input.candidateSha, "candidateSha"),
-    candidateTreeSha: sha(input.candidateTreeSha, "candidateTreeSha"),
-    alphaBaseSha: sha(input.alphaBaseSha, "alphaBaseSha"),
-    buildchainRuntimeSha: sha(
-      input.buildchainRuntimeSha,
-      "buildchainRuntimeSha",
-    ),
-    observedDevSha: sha(input.observedDevSha, "observedDevSha"),
-    blockerRoot: root(input.blockerRoot, "blockerRoot"),
-    patchRoot: root(input.patchRoot, "patchRoot"),
-    cutCandidateSha: sha(input.cutCandidateSha, "cutCandidateSha"),
-    cutCandidateTreeSha: sha(input.cutCandidateTreeSha, "cutCandidateTreeSha"),
-    cutLandingEvidenceRoot: root(
-      input.cutLandingEvidenceRoot,
-      "cutLandingEvidenceRoot",
+    ...normalizeFields(
+      input,
+      ["assignmentRoot", "initiativeRoot", "dependencyProofRoot", "environmentRoot", "blockerRoot", "patchRoot", "cutLandingEvidenceRoot", "devConflictEvidenceRoot", "devLandingEvidenceRoot"],
+      root,
     ),
-    devBaseSha: sha(input.devBaseSha, "devBaseSha"),
-    devLandingSha: sha(input.devLandingSha, "devLandingSha"),
-    devConflictEvidenceRoot: root(
-      input.devConflictEvidenceRoot,
-      "devConflictEvidenceRoot",
-    ),
-    devLandingEvidenceRoot: root(
-      input.devLandingEvidenceRoot,
-      "devLandingEvidenceRoot",
+    ...normalizeFields(
+      input,
+      ["originDevSha", "candidateSha", "candidateTreeSha", "alphaBaseSha", "buildchainRuntimeSha", "observedDevSha", "cutCandidateSha", "cutCandidateTreeSha", "devBaseSha", "devLandingSha"],
+      sha,
     ),
+    nativeCommand: text(input.nativeCommand, "nativeCommand"),
+    nativeExecutionReceipt: structuredClone(input.nativeExecutionReceipt || {}),
     ordinaryPullRequestNumber: positiveInteger(
       input.ordinaryPullRequestNumber,
       "ordinaryPullRequestNumber",
     ),
     recordedAt: timestamp(input.recordedAt, "recordedAt"),
   };
-  if (normalized.observedDevSha === normalized.originDevSha) {
-    throw new Error(
-      "self-dogfood requires dev to advance beyond the frozen origin",
-    );
-  }
-  if (normalized.cutCandidateSha === normalized.candidateSha) {
-    throw new Error("self-dogfood requires a successor repair candidate");
-  }
+  requireEvidence(
+    normalized.observedDevSha !== normalized.originDevSha,
+    "self-dogfood requires dev to advance beyond the frozen origin",
+  );
+  requireEvidence(
+    normalized.cutCandidateSha !== normalized.candidateSha,
+    "self-dogfood requires a successor repair candidate",
+  );
   normalized.delivery = normalizeDelivery(input.delivery, normalized);
   return normalized;
 }
@@ -214,6 +188,10 @@ function deliveryCandidate(input, deliveryClass = "release") {
     closureRoot: input.closureRoot,
     dependencyRoot: input.dependencyRoot,
     toolchainRoot: input.toolchainRoot,
+    ...(input.environmentRoot ? { environmentRoot: input.environmentRoot } : {}),
+    ...(input.nativeCommand
+      ? { nativeCommandContract: createNativeCommandContract(input.nativeCommand) }
+      : {}),
     deliveryClass,
     priority: "ordinary",
     ...(input.releaseBlockerPriority
@@ -366,7 +344,7 @@ function runQueueCampaign(value, repaired, priorityClaim) {
       dependencyRoot: value.dependencyProofRoot,
       toolchainRoot: value.dependencyProofRoot,
     },
-    "native-proof-required",
+    "non-native-fast",
   );
   queue = submitDevDeliveryCandidate(queue, ordinary, {
     now: at(value.recordedAt, 6),
@@ -388,6 +366,8 @@ function runQueueCampaign(value, repaired, priorityClaim) {
     closureRoot: value.delivery.mergeRoot,
     dependencyRoot: value.dependencyProofRoot,
     toolchainRoot: value.delivery.installedProductRoot,
+    environmentRoot: value.environmentRoot,
+    nativeCommand: value.nativeCommand,
     releaseBlockerPriority: priorityClaim,
   });
   const submitted = submitDevDeliveryCandidate(queue, blocker, {
@@ -426,7 +406,29 @@ function runQueueCampaign(value, repaired, priorityClaim) {
       "eligible release blocker did not receive bounded priority",
     );
   }
-  const closed = closeDevDeliveryWarrant(selected.queue, selected.warrant, {
+  const nativeCommandRoot = createNativeCommandContract(value.nativeCommand).commandRoot;
+  const proof = createNativeQualificationProof({
+    ...selected.warrant,
+    repository: value.repository,
+    protectedBase: value.sourceBranch,
+    qualifiedBase: value.devBaseSha,
+    nativeCommandRoot,
+    nativeExecutionReceipt: value.nativeExecutionReceipt,
+    affectedPaths: [], shardEvidenceRoots: [],
+    qualifiedAt: at(value.recordedAt, 12),
+  });
+  const current = {
+    ...selected.warrant,
+    nativeCommandRoot,
+    currentBase: value.devBaseSha,
+    graphKnown: true, attributionComplete: true,
+    changedPaths: [], renames: [],
+  };
+  const reuseDecision = createNativeProofReuseDecision({ proof, current });
+  const qualified = qualifyDevDeliveryWarrant(selected.queue, selected.warrant, {
+    nativeProof: proof, reuseDecision, current, now: at(value.recordedAt, 12),
+  });
+  const closed = closeDevDeliveryWarrant(qualified.queue, qualified.warrant, {
     outcome: "merged",
     evidenceRoot: value.delivery.mergeRoot,
     now: at(value.recordedAt, 13),

package/scripts/site-capability-metadata.mjs

@@ -39,6 +39,10 @@ export function cliCommandMeta(id) {
     "explain-artifact": { group: "release-passport-trust", purpose: "Explain artifact evidence for humans or agents." },
     "explain-release": { group: "release-passport-trust", purpose: "Explain a release passport for humans or agents." },
     facts: { group: "observability-diagnostics", purpose: "Inspect build facts command families." },
+    "facts-compatibility-project": { group: "governance-versioning", purpose: "Project legacy digest and proof views from the current Cut-bound compatibility Fact registry." },
+    "facts-compatibility-query": { group: "governance-versioning", purpose: "Verify one explicit directional compatibility path and emit a rooted receipt." },
+    "facts-compatibility-query-template": { group: "governance-versioning", purpose: "Create a direct query template for one current compatibility Fact." },
+    "facts-compatibility-verify": { group: "governance-versioning", purpose: "Verify the exact append-only compatibility Fact registry and current Cut." },
     help: { group: "getting-started", purpose: "Print Buildchain CLI help." },
     homebrew: { group: "distribution-indexes", purpose: "Inspect Homebrew distribution-index command families." },
     "homebrew-check": { group: "distribution-indexes", purpose: "Verify Homebrew tap metadata against upstream release passport evidence." },
@@ -139,6 +143,7 @@ export function cliCommandMeta(id) {
     "paper-status": { group: "reusable-build", purpose: "Report explicit evidence for every paper lifecycle state without unsupported inference." },
     "paper-work-start": { group: "getting-started", purpose: "Create a safe Paper work branch from the exact canonical remote development SHA." },
     "paper-work-submit": { group: "governance-versioning", purpose: "Push a Paper work branch without force and open or reuse the correctly targeted development PR." },
+    "next-development": { group: "governance-versioning", purpose: "Plan or apply one rooted declared-path next-development version transition without release or ref authority." },
     "publish-source": { group: "release-passport-trust", purpose: "Create, inspect, or verify publish-gate source-lock refs." },
     "publication-artifact": { group: "reusable-build", purpose: "Generate publication artifact manifests, passports, and source bundles for paper/report repositories." },
     "publication-artifact-manifest": { group: "reusable-build", purpose: "Write a site-consumable publication artifact manifest, publication passport, and source bundle." },
@@ -151,6 +156,7 @@ export function cliCommandMeta(id) {
     "release-governance": { group: "governance-versioning", purpose: "Reconcile a managed branch's Buildchain aggregate check to an already-tested pull request SHA." },
     "release-propagation": { group: "site-and-propagation", purpose: "Route exact Paper, KFD, Buildchain, or Core Site updates through one resumable propagation Work." },
     "release-tail": { group: "release-passport-trust", purpose: "Plan, initialize, resume, and verify one declarative provider-owned release-tail transaction." },
+    "tail-reseal": { group: "release-passport-trust", purpose: "Plan, admit, byte-verify, and seal one exact retained v4 Alpha candidate signing-finalization tail." },
     "release-transaction": { group: "release-passport-trust", purpose: "Inspect, recover, finalize, or abort durable release transactions." },
     sample: { group: "observability-diagnostics", purpose: "Inspect sampler command families." },
     "sample-process-tree": { group: "observability-diagnostics", purpose: "Sample process-tree diagnostics for a wrapped command." },
@@ -215,8 +221,13 @@ export function nodeApiMeta(exportName) {
     "./release-candidate": { group: "reusable-build", summary: "PR-stage release-candidate artifact, passport, and promote-only resolver APIs." },
     "./v4-floating-consumer-policy": { group: "governance-versioning", summary: "Semantic floating-selector admission, dual-lock receipt, and independent v4 consumer certification APIs." },
     "./v4-runtime-ref-resume-authority": { group: "release-passport-trust", summary: "Transient exact-runtime authorization, persisted-selector rejection, fresh-attempt Stage Capsule reuse, and A+B Passport lineage APIs." },
+    "./v4-tail-reseal": { group: "release-passport-trust", summary: "Effect-pure retained Stage Capsule validation and explicit Warrant-, credential-, and release-tail-fenced macOS reseal planning APIs." },
+    "./v4-tail-reseal-receipt": { group: "release-passport-trust", summary: "Four-platform byte readback, standard candidate Passport binding, and terminal v4 tail-reseal receipt APIs." },
     "./release-candidate-recovery": { group: "release-passport-trust", summary: "Fail-closed verification and immutable receipts for reusing a successful sealed candidate run without rebuilding product payloads." },
     "./release-train": { group: "governance-versioning", summary: "Frozen Release Cut identity, rooted Release Train transitions, Dev observations, supersession, replay, and legacy read compatibility APIs." },
+    "./next-development-transition": { group: "governance-versioning", summary: "Provider-neutral completed-Alpha preservation and rooted next-development state, version-model, idempotency, and local materialization APIs." },
+    "./next-development-controller": { group: "governance-versioning", summary: "Durable completed-Alpha child scheduling, fresh-runner checkpoint resume, latest protected-Dev reconciliation, and exact version-root readback APIs." },
+    "./next-development-projection": { group: "governance-versioning", summary: "Canonical generated config, Agent, workflow-header, and manual projections for the next-development transition contract." },
     "./stable-candidate-ledger": { group: "governance-versioning", summary: "Immutable alpha candidate ledger, qualification, revocation, selection, and exact stable source-lock APIs." },
     "./release-propagation": { group: "site-and-propagation", summary: "Release propagation graph, plan, and exact upstream lock APIs." },
     "./release-activation-transaction": { group: "release-passport-trust", summary: "Ordered cross-repository activation, exact receipt-set binding, retry, abort, rollback, and shadow-rehearsal APIs." },
@@ -225,6 +236,7 @@ export function nodeApiMeta(exportName) {
     "./release-tail-compatibility": { group: "release-passport-trust", summary: "Bounded v3 release-hook compatibility diagnostics that reject new executable release-tail inputs." },
     "./release-line-bootstrap": { group: "governance-versioning", summary: "Semver release-line bootstrap planning and version-state APIs." },
     "./buildchain-contract": { group: "governance-versioning", summary: "Runtime contract world and compatibility digest APIs for floating-ref drift checks." },
+    "./compatibility-fact-authority": { group: "governance-versioning", summary: "Directional Cut-bound compatibility Fact, lifecycle, explicit path receipt, legacy projection, and Release Passport evidence APIs." },
     "./controller-evidence": { group: "reusable-build", summary: "Project-independent controller descriptors, source/runtime-bound plans, receipts, aggregates, and validation APIs." },
     "./surface-manifest": { group: "site-and-propagation", summary: "Surface manifest timestamp and reproducibility policy APIs." },
     "./issue-reporting": { group: "observability-diagnostics", summary: "Buildchain-owned issue reporting API for workflow friction feedback." },

package/scripts/v4-consumer-policy.mjs

@@ -139,10 +139,6 @@ export function certifyCommand(options = {}) {
     stableLockPath,
     alphaLockPath,
   });
-  const selectedLock =
-    receipt?.invocation?.visibleSelector === "v4-alpha"
-      ? readJson(path.join(callerRoot, alphaLockPath))
-      : readJson(path.join(callerRoot, stableLockPath));
   const authorityScan = scanV4FloatingConsumerPolicy({
     root: callerRoot,
     repository,
@@ -150,7 +146,7 @@ export function certifyCommand(options = {}) {
     invokedWorkflow,
     invocationSourcePath: receipt?.invocation?.sourcePath,
     expectedInvocationChannel: receipt?.invocation?.channel,
-    resolvedWorkflowSha: selectedLock.buildchain?.resolvedSha,
+    resolvedWorkflowSha: receipt?.invocation?.resolvedWorkflowSha,
     resolvedRuntimeSha,
     stableLockPath,
     alphaLockPath,

package/scripts/v4-tail-reseal-macos-rehearsal.mjs

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { v4ContentRoot } from "../packages/core/v4-canonical-contracts.js";
+import { verifyV4TailResealPlatform } from "./v4-tail-reseal.mjs";
+
+function flag(args, name, fallback = "") {
+  const index = args.indexOf(`--${name}`);
+  return index < 0 ? fallback : String(args[index + 1] || "");
+}
+
+function fileRoot(file) {
+  return `sha256:${crypto
+    .createHash("sha256")
+    .update(fs.readFileSync(file))
+    .digest("hex")}`;
+}
+
+function writeCandidate(root, request, content) {
+  const platform = request.platforms.find(({ id }) => id === "macos-arm64");
+  const payload = path.join(root, "product/release/macos-arm64/payload.bin");
+  fs.mkdirSync(path.dirname(payload), { recursive: true });
+  fs.writeFileSync(payload, content);
+  const relative = path.relative(root, payload);
+  const file = {
+    path: relative,
+    size: fs.statSync(payload).size,
+    digest: fileRoot(payload),
+  };
+  const manifest = {
+    contract: "kungfu-buildchain-artifact",
+    artifactName: platform.artifactName,
+    git: {
+      repository: request.repository,
+      sha: request.source.sha,
+      treeSha: request.source.treeSha,
+      runId: String(request.source.runId),
+      runAttempt: String(request.source.runAttempt),
+    },
+    platform: { id: platform.id, name: platform.name },
+    files: [
+      {
+        path: relative,
+        size: file.size,
+        sha256: file.digest.replace(/^sha256:/u, ""),
+      },
+    ],
+    summary: { fileCount: 1, totalBytes: file.size },
+  };
+  const manifestPath = path.join(root, "evidence/macos-arm64/manifest.json");
+  fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
+  fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+  return {
+    artifactRoot: v4ContentRoot("tail-reseal-artifact-files", [file]),
+    manifestRoot: fileRoot(manifestPath),
+  };
+}
+
+export function rehearseV4TailResealMacos({
+  fixturePath = "contracts/fixtures/v4-tail-reseal-v1/valid.json",
+  outputPath = "",
+} = {}) {
+  const request = JSON.parse(
+    fs.readFileSync(path.resolve(fixturePath), "utf8"),
+  );
+  const workRoot = fs.mkdtempSync(
+    path.join(os.tmpdir(), "buildchain-v4-tail-macos-"),
+  );
+  try {
+    const retainedRoots = writeCandidate(workRoot, request, "unsigned");
+    const platform = request.platforms.find(({ id }) => id === "macos-arm64");
+    Object.assign(platform, retainedRoots);
+    const retained = verifyV4TailResealPlatform({
+      request,
+      platformId: "macos-arm64",
+      artifactRoot: workRoot,
+      mode: "retained",
+    });
+    writeCandidate(workRoot, request, "signed-and-notarized");
+    const resealed = verifyV4TailResealPlatform({
+      request,
+      platformId: "macos-arm64",
+      artifactRoot: workRoot,
+      mode: "resealed",
+      providerReadbackRoot: request.signing.providerReadbackRoot,
+    });
+    const payload = {
+      schema: "kungfu-buildchain-v4-tail-reseal-macos-rehearsal/v1",
+      platformId: "macos-arm64",
+      retained,
+      resealed,
+      buildStagesExecuted: 0,
+      signingFinalizationExecutions: 1,
+      providerReadbackRoot: request.signing.providerReadbackRoot,
+    };
+    const evidence = {
+      ...payload,
+      evidenceRoot: v4ContentRoot("tail-reseal-admission", payload),
+    };
+    if (outputPath) {
+      const output = path.resolve(outputPath);
+      fs.mkdirSync(path.dirname(output), { recursive: true });
+      fs.writeFileSync(output, `${JSON.stringify(evidence, null, 2)}\n`);
+    }
+    return evidence;
+  } finally {
+    fs.rmSync(workRoot, { recursive: true, force: true });
+  }
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  try {
+    const evidence = rehearseV4TailResealMacos({
+      fixturePath: flag(
+        process.argv.slice(2),
+        "fixture",
+        "contracts/fixtures/v4-tail-reseal-v1/valid.json",
+      ),
+      outputPath: flag(process.argv.slice(2), "output"),
+    });
+    process.stdout.write(`${JSON.stringify(evidence, null, 2)}\n`);
+  } catch (error) {
+    console.error(`v4-tail-reseal-macos-rehearsal: ${error.message}`);
+    process.exitCode = 1;
+  }
+}