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

package/packages/core/paper-agent-entry.js

@@ -12,6 +12,7 @@ import {
   stableJson,
   workCheck,
 } from "./paper-repository.js";
+import { mergeNextDevelopmentAgentInstructions } from "./next-development-projection.js";
 
 export const PAPER_AGENT_ENTRY_CONTRACT = "kungfu-buildchain-paper-agent-entry";
 export const PAPER_AGENT_ENTRY_SCHEMA_VERSION = 1;
@@ -167,9 +168,11 @@ export function paperAgentEntryFiles({
     [PAPER_PATHS.agentEntry, jsonText(entry)],
     [
       PAPER_PATHS.agentInstructions,
-      mergePaperAgentEntryInstructions(currentAgents, {
-        developmentRef: resolvedDevelopmentRef,
-      }),
+      mergeNextDevelopmentAgentInstructions(
+        mergePaperAgentEntryInstructions(currentAgents, {
+          developmentRef: resolvedDevelopmentRef,
+        }),
+      ),
     ],
   ]);
 }
@@ -205,8 +208,11 @@ function ciContext({ env, developmentRef }) {
     sourceBranch.startsWith(versionStatePrefix) &&
     /^[0-9a-f]{12}$/i.test(sourceBranch.slice(versionStatePrefix.length));
   const branchOk = pullRequest
-    ? (PAPER_WORK_BRANCH_PATTERN.test(sourceBranch) && targetBranch === developmentRef) ||
-      (channelIndex > 0 && sourceBranch === channelBranches[channelIndex - 1]) || generatedVersionState
+    ? (PAPER_WORK_BRANCH_PATTERN.test(sourceBranch) &&
+        targetBranch === developmentRef) ||
+      (channelIndex > 0 &&
+        sourceBranch === channelBranches[channelIndex - 1]) ||
+      generatedVersionState
     : channelBranches.includes(refName);
   return {
     mode: "ci",

package/packages/core/paper.js

@@ -46,6 +46,11 @@ import {
   scaffoldReadme,
 } from "./paper-scaffold-content.js";
 import { executePaperNpmBootstrap as executePaperNpmBootstrapOperation } from "./paper-npm-bootstrap.js";
+import {
+  appendNextDevelopmentToml,
+  nextDevelopmentWorkflowHeader,
+  projectNextDevelopmentToml,
+} from "./next-development-projection.js";
 
 export { PAPER_PATHS, resolvePaperRepository } from "./paper-repository.js";
 export {
@@ -350,7 +355,7 @@ immutable_base_url = ${tomlString(joinUrl(siteBaseUrl, "archive").replace(/\/$/,
 registry_path = ".buildchain/publication/publication-registry.json"
 `
     : "";
-  return `schema = 1
+  return appendNextDevelopmentToml(`schema = 1
 
 [project]
 type = "publication-artifact"
@@ -384,14 +389,14 @@ command = "make pdf"
 
 [lifecycle.verify]
 command = "make check"
-`;
+`);
 }
 
 function scaffoldBuildWorkflow(
   buildchainSha,
   { artifactName = "paper-publication" } = {},
 ) {
-  return `name: Build
+  return `${nextDevelopmentWorkflowHeader()}name: Build
 
 on:
   workflow_dispatch:
@@ -419,7 +424,7 @@ jobs:
 }
 
 function scaffoldVerifyWorkflow(buildchainSha) {
-  return `name: Verify
+  return `${nextDevelopmentWorkflowHeader()}name: Verify
 
 on:
   pull_request:
@@ -450,7 +455,7 @@ function scaffoldReleaseWorkflow(
   const passportInput = releasePassportProductName
     ? `      release-passport-product-name: ${JSON.stringify(releasePassportProductName)}\n`
     : "";
-  return `name: Paper Release
+  return `${nextDevelopmentWorkflowHeader()}name: Paper Release
 
 on:
   workflow_dispatch:
@@ -997,6 +1002,12 @@ function migrationFiles({
     runtimeIdentity.version,
   );
   const files = new Map([
+    [
+      PAPER_PATHS.config,
+      projectNextDevelopmentToml(
+        fs.readFileSync(path.resolve(cwd, PAPER_PATHS.config), "utf8"),
+      ),
+    ],
     [PAPER_PATHS.contractLock, contractLockText],
     [PAPER_PATHS.versionPin, `${runtimeIdentity.version}\n`],
     [PAPER_PATHS.buildWorkflow, buildWorkflow],

package/packages/core/v4-canonical-contracts.js

@@ -56,6 +56,11 @@ const ROOT_DOMAINS = new Set([
   "stable-publication-fence",
   "partial-mutation-recovery-checkpoint",
   "partial-mutation-recovery-plan",
+  "tail-reseal-plan",
+  "tail-reseal-admission",
+  "tail-reseal-artifact-files",
+  "tail-reseal-receipt",
+  "release-candidate-passport",
 ]);
 const FAULT_CLASSES = new Set([
   "validation",

package/packages/core/v4-floating-consumer-policy.js

@@ -1,6 +1,10 @@
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
+import {
+  createBuildchainContractWorld,
+  evaluateBuildchainContractLock,
+} from "./buildchain-contract.js";
 import { parseYamlUses } from "./workflow-yaml-contract.js";
 import {
   V4_FLOATING_CONSUMER_POLICY,
@@ -29,6 +33,7 @@ const TRANSIENT_ACTION =
 const SCANNER_PATHS = Object.freeze([
   "architecture/v4-floating-consumer-policy.json",
   "contracts/v4-floating-consumer-policy-receipt-v1.schema.json",
+  "packages/core/buildchain-contract.js",
   "packages/core/v4-floating-consumer-policy.js",
   "packages/core/workflow-yaml-contract.js",
   "scripts/v4-consumer-policy.mjs",
@@ -381,15 +386,30 @@ export function scanV4FloatingConsumerPolicy({
     expectedInvocationChannel,
   );
   const selectedLock = selected?.channel === "alpha" ? alpha : stable;
-  if (
-    selected?.channel &&
-    selectedLock?.buildchain?.resolvedSha?.toLowerCase() !==
-      normalizedWorkflowSha
-  ) {
-    failures.push({
-      code: "selected-lock-runtime-mismatch",
-      message: `${selected.channel} contract lock does not bind resolved workflow shell ${normalizedWorkflowSha}`,
-    });
+  if (selected?.channel && selectedLock) {
+    try {
+      const compatibility = evaluateBuildchainContractLock({
+        lock: selectedLock,
+        current: createBuildchainContractWorld({ root: defaultRuntimeRoot() }),
+        runtimeRef: selected.selector,
+        runtimeSha: normalizedWorkflowSha,
+        runtimeClass: selected.channel,
+        workflowShellRef: selected.selector,
+        expectedChannel: selected.channel,
+        expectedMajor: "v4",
+      });
+      if (!compatibility.ok) {
+        failures.push({
+          code: "selected-lock-runtime-incompatible",
+          message: `${selected.channel} contract lock rejects resolved workflow shell ${normalizedWorkflowSha}: ${compatibility.reasons?.join("; ") || compatibility.status}`,
+        });
+      }
+    } catch (error) {
+      failures.push({
+        code: "selected-lock-contract-world-invalid",
+        message: `cannot evaluate ${selected.channel} contract lock against the resolved workflow shell: ${error.message}`,
+      });
+    }
   }
 
   const policyRoot = sha256(stableJson(policy));

package/packages/core/v4-tail-reseal-contract.js

@@ -0,0 +1,26 @@
+export const V4_TAIL_RESEAL_REQUEST_CONTRACT =
+  "kungfu-buildchain-v4-tail-reseal-request/v1";
+export const V4_TAIL_RESEAL_PLAN_CONTRACT =
+  "kungfu-buildchain-v4-tail-reseal-plan/v1";
+
+export const V4_TAIL_RESEAL_PLATFORMS = Object.freeze([
+  "linux-arm64",
+  "linux-x64",
+  "macos-arm64",
+  "windows-x64",
+]);
+
+export const V4_TAIL_RESEAL_PLATFORM_RUNNERS = Object.freeze({
+  "linux-arm64": '["ubuntu-24.04-arm"]',
+  "linux-x64": '["ubuntu-24.04"]',
+  "macos-arm64": '["macos-15"]',
+  "windows-x64": '["windows-2025"]',
+});
+
+export const V4_TAIL_RESEAL_REUSED_STAGE_KEYS = Object.freeze(
+  V4_TAIL_RESEAL_PLATFORMS.flatMap((platformId) =>
+    ["build", "install", "package", "verify"].map(
+      (stage) => `${platformId}:${stage}`,
+    ),
+  ).sort(),
+);

package/packages/core/v4-tail-reseal-github.js

@@ -0,0 +1,178 @@
+import { v4ContentRoot } from "./v4-canonical-contracts.js";
+import {
+  V4TailResealFault,
+  normalizeV4TailResealRequest,
+} from "./v4-tail-reseal.js";
+
+export const V4_TAIL_RESEAL_ADMISSION_CONTRACT =
+  "kungfu-buildchain-v4-tail-reseal-admission/v1";
+
+const REQUIRED_SUCCESS_JOBS = Object.freeze([
+  "build / Linux ARM64",
+  "build / Linux x64",
+  "build / macOS ARM64",
+  "build / Windows x64",
+  "build / Control detached signing Linux ARM64",
+  "build / Control detached signing Linux x64",
+  "build / Control detached signing macOS ARM64",
+  "build / Control detached signing Windows x64",
+  "build / Finalize signed artifact Linux ARM64",
+  "build / Finalize signed artifact Linux x64",
+  "build / Finalize signed artifact Windows x64",
+]);
+
+function fault(code, path, message) {
+  throw new V4TailResealFault(code, path, message);
+}
+
+function exactArtifact(artifacts, name, digest, path) {
+  const matches = artifacts.filter((artifact) => artifact.name === name);
+  if (matches.length !== 1)
+    fault(
+      "tail-reseal-artifact-ambiguous",
+      path,
+      "retained artifact must resolve exactly once",
+    );
+  const artifact = matches[0];
+  if (artifact.expired === true)
+    fault("tail-reseal-retention-expired", path, "retained artifact expired");
+  if (artifact.digest !== digest)
+    fault(
+      "tail-reseal-artifact-archive-mismatch",
+      path,
+      "GitHub artifact archive digest drifted",
+    );
+  return artifact;
+}
+
+function validateSourceIdentity(normalized, sourceCommit, sourceRun) {
+  if (
+    sourceCommit?.sha !== normalized.source.sha ||
+    sourceCommit?.tree?.sha !== normalized.source.treeSha
+  )
+    fault(
+      "tail-reseal-source-mismatch",
+      "$/sourceCommit",
+      "source commit or tree readback drifted",
+    );
+  const workflowFile = String(sourceRun?.path || "")
+    .split("@")[0]
+    .replace(/^\.github\/workflows\//u, "");
+  if (
+    Number(sourceRun?.id) !== normalized.source.runId ||
+    Number(sourceRun?.run_attempt) !== normalized.source.runAttempt ||
+    sourceRun?.event !== "workflow_dispatch" ||
+    sourceRun?.status !== "completed" ||
+    sourceRun?.conclusion !== "failure" ||
+    sourceRun?.head_sha !== normalized.source.sha ||
+    workflowFile !== normalized.source.workflowFile ||
+    sourceRun?.name !== normalized.source.workflowName
+  )
+    fault(
+      "tail-reseal-source-run-mismatch",
+      "$/sourceRun",
+      "source run is not the exact retained failed Build run",
+    );
+}
+
+function validateSourceJobs(normalized, sourceJobs) {
+  const jobs = Array.isArray(sourceJobs) ? sourceJobs : [];
+  const byName = new Map(jobs.map((job) => [job.name, job]));
+  for (const name of REQUIRED_SUCCESS_JOBS)
+    if (byName.get(name)?.conclusion !== "success")
+      fault(
+        "tail-reseal-prior-stage-mismatch",
+        "$/sourceJobs",
+        `required source job did not succeed: ${name}`,
+      );
+  const failedJob = jobs.find(
+    (job) => Number(job.id) === normalized.failure.jobId,
+  );
+  const failedSteps = (failedJob?.steps || [])
+    .filter((step) => step.conclusion === "failure")
+    .map((step) => step.name);
+  if (
+    failedJob?.name !== normalized.failure.jobName ||
+    failedJob?.conclusion !== "failure" ||
+    JSON.stringify(failedSteps) !==
+      JSON.stringify([normalized.failure.stepName])
+  )
+    fault(
+      "tail-reseal-failure-mismatch",
+      "$/sourceJobs",
+      "observed failure is not the single authorized macOS tail failure",
+    );
+}
+
+function validateRetainedArtifacts(normalized, sourceArtifacts) {
+  for (const [index, platform] of normalized.platforms.entries()) {
+    exactArtifact(
+      sourceArtifacts || [],
+      platform.artifactName,
+      platform.artifactArchiveRoot,
+      `$/sourceArtifacts/${index}/payload`,
+    );
+    exactArtifact(
+      sourceArtifacts || [],
+      platform.manifestArtifactName,
+      platform.manifestArchiveRoot,
+      `$/sourceArtifacts/${index}/manifest`,
+    );
+  }
+}
+
+function validateSigningAuthority(normalized, signingRun, signingArtifacts) {
+  if (
+    Number(signingRun?.id) !== normalized.signing.authorityRunId ||
+    signingRun?.status !== "completed" ||
+    signingRun?.conclusion !== "success" ||
+    signingRun?.head_sha !== normalized.signing.runtimeSha
+  )
+    fault(
+      "tail-reseal-signer-authority-mismatch",
+      "$/signingRun",
+      "signing authority run readback drifted",
+    );
+  exactArtifact(
+    signingArtifacts || [],
+    normalized.signing.resultArtifact,
+    normalized.signing.resultArtifactRoot,
+    "$/signingArtifacts/result",
+  );
+}
+
+export function validateV4TailResealGitHubEvidence({
+  request,
+  sourceCommit,
+  sourceRun,
+  sourceJobs,
+  sourceArtifacts,
+  signingRun,
+  signingArtifacts,
+} = {}) {
+  const normalized = normalizeV4TailResealRequest(request);
+  validateSourceIdentity(normalized, sourceCommit, sourceRun);
+  validateSourceJobs(normalized, sourceJobs);
+  validateRetainedArtifacts(normalized, sourceArtifacts);
+  validateSigningAuthority(normalized, signingRun, signingArtifacts);
+  const payload = {
+    schema: V4_TAIL_RESEAL_ADMISSION_CONTRACT,
+    repository: normalized.repository,
+    sourceRoot: normalized.source.sourceRoot,
+    sourceRunId: normalized.source.runId,
+    signingAuthorityRunId: normalized.signing.authorityRunId,
+    retainedArchiveRoots: normalized.platforms.flatMap((platform) => [
+      platform.artifactArchiveRoot,
+      platform.manifestArchiveRoot,
+    ]),
+    priorFailureRoot: normalized.failure.evidenceRoot,
+    retentionReadbackRoot: normalized.retention.readbackRoot,
+    warrantReadbackRoot: normalized.warrant.stateReadbackRoot,
+  };
+  return {
+    ...payload,
+    admissionRoot: v4ContentRoot("tail-reseal-admission", payload),
+  };
+}
+
+export { REQUIRED_SUCCESS_JOBS as V4_TAIL_RESEAL_REQUIRED_SUCCESS_JOBS };

package/packages/core/v4-tail-reseal-receipt.js

@@ -0,0 +1,225 @@
+import { v4ContentRoot, validateV4Root } from "./v4-canonical-contracts.js";
+import { validateReleaseCandidatePassport } from "./release-candidate.js";
+import {
+  V4_TAIL_RESEAL_PLAN_CONTRACT,
+  V4_TAIL_RESEAL_PLATFORMS,
+  V4TailResealFault,
+  normalizeV4TailResealRequest,
+  planV4TailReseal,
+} from "./v4-tail-reseal.js";
+
+export const V4_TAIL_RESEAL_RECEIPT_CONTRACT =
+  "kungfu-buildchain-v4-tail-reseal-receipt/v1";
+
+function fault(code, path, message) {
+  throw new V4TailResealFault(code, path, message);
+}
+
+function root(value, path) {
+  try {
+    validateV4Root(value, path);
+  } catch (error) {
+    fault("invalid-tail-reseal-root", path, error.message);
+  }
+  return value;
+}
+
+function exactKeys(value, expected, path) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    fault("invalid-tail-reseal-shape", path, "object required");
+  const actual = Object.keys(value).sort();
+  const canonical = [...expected].sort();
+  if (
+    actual.length !== canonical.length ||
+    actual.some((key, index) => key !== canonical[index])
+  )
+    fault(
+      "invalid-tail-reseal-shape",
+      path,
+      "keys do not match the closed tail-reseal contract",
+    );
+}
+
+function positiveInteger(value, path) {
+  if (!Number.isSafeInteger(value) || value < 1)
+    fault(
+      "invalid-tail-reseal-integer",
+      path,
+      "positive safe integer required",
+    );
+}
+
+function validateReadbacks(readbacks, request) {
+  if (
+    !Array.isArray(readbacks) ||
+    readbacks.length !== V4_TAIL_RESEAL_PLATFORMS.length
+  )
+    fault(
+      "tail-reseal-readback-mismatch",
+      "$/readbacks",
+      "one readback per platform required",
+    );
+  const normalized = [...readbacks].sort((left, right) =>
+    Buffer.from(left.platformId || "").compare(
+      Buffer.from(right.platformId || ""),
+    ),
+  );
+  for (const [index, readback] of normalized.entries()) {
+    const path = `$/readbacks/${index}`;
+    exactKeys(
+      readback,
+      [
+        "platformId",
+        "artifactRoot",
+        "manifestRoot",
+        "capsuleRoot",
+        "byteIdentical",
+        "providerReadbackRoot",
+      ],
+      path,
+    );
+    const expected = request.platforms[index];
+    if (readback.platformId !== expected.id)
+      fault(
+        "tail-reseal-platform-mismatch",
+        `${path}/platformId`,
+        "unexpected platform readback",
+      );
+    for (const field of ["artifactRoot", "manifestRoot", "capsuleRoot"])
+      root(readback[field], `${path}/${field}`);
+    if (readback.capsuleRoot !== expected.capsuleRoot)
+      fault(
+        "tail-reseal-capsule-mismatch",
+        `${path}/capsuleRoot`,
+        "Stage Capsule identity changed during tail execution",
+      );
+    if (readback.platformId === "macos-arm64") {
+      if (readback.byteIdentical !== false)
+        fault(
+          "tail-reseal-macos-effect-missing",
+          `${path}/byteIdentical`,
+          "macOS signed bytes must be independently resealed",
+        );
+      root(readback.providerReadbackRoot, `${path}/providerReadbackRoot`);
+    } else if (
+      readback.byteIdentical !== true ||
+      readback.artifactRoot !== expected.artifactRoot ||
+      readback.manifestRoot !== expected.manifestRoot ||
+      readback.providerReadbackRoot !== null
+    )
+      fault(
+        "tail-reseal-nontail-byte-drift",
+        path,
+        "non-macOS retained artifacts must remain byte-identical and effect-free",
+      );
+  }
+  return normalized;
+}
+
+export function createV4TailResealReceipt({
+  request,
+  plan,
+  readbacks,
+  passport,
+  protectedReadbackRoot,
+  currentRun,
+} = {}) {
+  const normalized = normalizeV4TailResealRequest(request);
+  const expectedPlan = planV4TailReseal(normalized);
+  const { planRoot: _planRoot, ...planBody } = plan || {};
+  if (
+    plan?.schema !== V4_TAIL_RESEAL_PLAN_CONTRACT ||
+    plan.planRoot !== expectedPlan.planRoot ||
+    v4ContentRoot("tail-reseal-plan", planBody) !== expectedPlan.planRoot
+  )
+    fault(
+      "tail-reseal-plan-drift",
+      "$/plan",
+      "plan does not match the exact request",
+    );
+  const platformReadbacks = validateReadbacks(readbacks, normalized);
+  const passportValidation = validateReleaseCandidatePassport({
+    passport,
+    repository: normalized.repository,
+    targetChannel: normalized.target.channel,
+    version: normalized.target.version,
+    sourceHeadSha: normalized.source.sha,
+    requirePlatforms: true,
+  });
+  if (!passportValidation.ok)
+    fault(
+      "tail-reseal-passport-invalid",
+      "$/passport",
+      passportValidation.errors.join("; "),
+    );
+  if (
+    passport.contract !== "kungfu-buildchain-release-candidate-passport" ||
+    passport.buildchain?.sha !== normalized.runtime.sha ||
+    passport.consumerPolicy?.receiptRoot !==
+      normalized.runtime.consumerPolicyReceiptRoot
+  )
+    fault(
+      "tail-reseal-passport-binding-mismatch",
+      "$/passport",
+      "standard v4 candidate Passport bindings drifted",
+    );
+  root(protectedReadbackRoot, "$/protectedReadbackRoot");
+  exactKeys(currentRun, ["id", "attempt"], "$/currentRun");
+  positiveInteger(currentRun.id, "$/currentRun/id");
+  positiveInteger(currentRun.attempt, "$/currentRun/attempt");
+  const payload = {
+    schema: V4_TAIL_RESEAL_RECEIPT_CONTRACT,
+    action: "reused-retained-tail",
+    repository: normalized.repository,
+    source: normalized.source,
+    target: normalized.target,
+    runtime: normalized.runtime,
+    planRoot: expectedPlan.planRoot,
+    warrant: normalized.warrant,
+    retention: normalized.retention,
+    originalFailure: normalized.failure,
+    signingAuthority: normalized.signing,
+    releaseTail: normalized.releaseTail,
+    platformReadbacks,
+    skippedStages: expectedPlan.skippedStages,
+    rerunStages: expectedPlan.rerunStages,
+    passport: {
+      contract: passport.contract,
+      candidateHash: passport.candidateHash,
+      passportRoot: v4ContentRoot("release-candidate-passport", passport),
+    },
+    protectedReadbackRoot,
+    currentRun,
+  };
+  return {
+    ...payload,
+    receiptRoot: v4ContentRoot("tail-reseal-receipt", payload),
+  };
+}
+
+export function verifyV4TailResealReceipt({ receipt, request, passport } = {}) {
+  try {
+    const expected = createV4TailResealReceipt({
+      request,
+      plan: planV4TailReseal(request),
+      readbacks: receipt.platformReadbacks,
+      passport,
+      protectedReadbackRoot: receipt.protectedReadbackRoot,
+      currentRun: receipt.currentRun,
+    });
+    return {
+      ok: expected.receiptRoot === receipt.receiptRoot,
+      receiptRoot: expected.receiptRoot,
+      failures:
+        expected.receiptRoot === receipt.receiptRoot
+          ? []
+          : [{ code: "tail-reseal-receipt-root-mismatch" }],
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      receiptRoot: "",
+      failures: [{ code: error.code || "tail-reseal-receipt-invalid" }],
+    };
+  }
+}