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

package/scripts/generate-next-development-guidance.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { nextDevelopmentManual } from "../packages/core/next-development-projection.js";
+
+export const NEXT_DEVELOPMENT_MANUAL_PATH =
+  "docs/next-development-transition.md";
+
+export function generateNextDevelopmentGuidance({
+  cwd = process.cwd(),
+  check = false,
+} = {}) {
+  const target = path.resolve(cwd, NEXT_DEVELOPMENT_MANUAL_PATH);
+  const expected = nextDevelopmentManual();
+  const current = fs.existsSync(target) ? fs.readFileSync(target, "utf8") : "";
+  if (check) {
+    if (current !== expected) {
+      throw new Error(
+        `${NEXT_DEVELOPMENT_MANUAL_PATH} drifted from its contract source`,
+      );
+    }
+    return { ok: true, changed: false, path: NEXT_DEVELOPMENT_MANUAL_PATH };
+  }
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  if (current !== expected) fs.writeFileSync(target, expected);
+  return {
+    ok: true,
+    changed: current !== expected,
+    path: NEXT_DEVELOPMENT_MANUAL_PATH,
+  };
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  try {
+    const result = generateNextDevelopmentGuidance({
+      check: process.argv.includes("--check"),
+    });
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+  } catch (error) {
+    process.stderr.write(`next-development guidance: ${error.message}\n`);
+    process.exitCode = 1;
+  }
+}

package/scripts/generate-release-candidate-passport.mjs

@@ -1,19 +1,179 @@
 #!/usr/bin/env node
 import fs from "node:fs";
 import path from "node:path";
+import { execFileSync } from "node:child_process";
 import { pathToFileURL } from "node:url";
-import {
-  createReleaseCandidatePassport,
-  validateReleaseCandidatePassport,
-} from "../packages/core/release-candidate.js";
+import { createReleaseCandidatePassport, validateReleaseCandidatePassport } from "../packages/core/release-candidate.js";
+import { scanV4FloatingConsumerPolicy, v4ConsumerPolicyScannerRoot } from "../packages/core/v4-floating-consumer-policy.js";
+import { v4ContentRoot } from "../packages/core/v4-canonical-contracts.js";
+import { V4_STAGE_CAPSULE_CONTRACT, V4_STAGE_CAPSULE_IDENTITY_CONTRACT, v4StageCapsuleIdentityRoot, v4StageCapsuleRoot, validateV4StageCapsule } from "../packages/core/v4-stage-capsule.js";
+import { v4RuntimeResumeDocumentRoot } from "../packages/core/v4-runtime-ref-resume-authority.js";
 import { writeGitHubOutputs } from "./build-contract-core.mjs";
 
-function env(name, fallback = "") {
-  return process.env[name] || fallback;
+const env = (name, fallback = "") => process.env[name] || fallback;
+const readJsonFile = (filePath) => JSON.parse(fs.readFileSync(filePath, "utf8"));
+
+export function createReleaseCandidateStageCapsules({
+  passport,
+  buildSummary,
+  coordinates,
+}) {
+  if (!passport.consumerPolicy?.receiptRoot) return undefined;
+  if (
+    coordinates.repository !== passport.repository ||
+    String(coordinates.runId) !== String(passport.workflow.runId) ||
+    String(coordinates.runAttempt) !== String(passport.workflow.runAttempt) ||
+    coordinates.sourceSha !== passport.source.headSha
+  ) {
+    throw new Error(
+      "Stage Capsule coordinate set does not bind the candidate run",
+    );
+  }
+  const coordinateByPlatform = new Map(
+    coordinates.artifacts.map((entry) => [entry.platformId, entry]),
+  );
+  const qualificationRoot = passport.controllerReceipts?.[0]?.receiptDigest;
+  const entries = passport.platformMatrix
+    .map((platform) => {
+      const coordinate = coordinateByPlatform.get(platform.platformId);
+      if (!coordinate || coordinate.name !== platform.artifactName) {
+        throw new Error(
+          `Stage Capsule coordinate missing for ${platform.platformId}`,
+        );
+      }
+      const manifest = readJsonFile(platform.manifestPath);
+      const identity = {
+        schema: V4_STAGE_CAPSULE_IDENTITY_CONTRACT,
+        sourceRoot: v4ContentRoot("candidate-identity", passport.source),
+        platform: platform.platformId,
+        platformRoot: v4ContentRoot("candidate-identity", manifest.platform),
+        stage: "verify",
+        toolchainRoots: [],
+        runtimeRoot: v4ContentRoot("candidate-identity", {
+          sha: passport.buildchain.sha,
+        }),
+        policyRoot: passport.consumerPolicy.receiptRoot,
+        declaredInputs: [
+          {
+            name: "release-candidate",
+            root: `sha256:${passport.candidateHash}`,
+          },
+        ],
+        transformationRoot: v4ContentRoot("candidate-identity", {
+          lifecycle: manifest.lifecycle,
+          summary: platform.summary,
+        }),
+        outputManifestRoot: v4ContentRoot(
+          "stage-capsule-artifact-manifest",
+          { artifact: coordinate, manifest },
+        ),
+        qualificationRoot,
+        observationRoots: [
+          {
+            name: "provider-coordinate",
+            root: v4ContentRoot("provider-readback-sample", coordinate),
+          },
+        ],
+      };
+      const capsule = {
+        schema: V4_STAGE_CAPSULE_CONTRACT,
+        writerAuthority: "typescript-v3",
+        rustAuthority: "validation-only",
+        identity,
+        identityRoot: v4StageCapsuleIdentityRoot(identity),
+        retentionPromise: {
+          class: "github-artifact",
+          retainUntil: coordinate.expiresAt,
+        },
+        capsuleRoot: `sha256:${"0".repeat(64)}`,
+      };
+      capsule.capsuleRoot = v4StageCapsuleRoot(capsule);
+      validateV4StageCapsule(capsule);
+      return {
+        platform: platform.platformId,
+        artifactName: coordinate.name,
+        artifactDigest: coordinate.digest,
+        artifact: coordinate,
+        capsule,
+      };
+    })
+    .sort((left, right) => left.platform.localeCompare(right.platform));
+  const body = {
+    schemaVersion: 1,
+    contract: "kungfu-buildchain-v4-release-candidate-stage-capsules/v1",
+    status: "sealed",
+    repository: passport.repository,
+    buildAttempt: {
+      id: `github-run:${passport.workflow.runId}:attempt:${passport.workflow.runAttempt}`,
+      runtimeSha: passport.buildchain.sha,
+    },
+    source: {
+      sha: passport.source.headSha,
+      treeSha: passport.source.treeHash,
+    },
+    consumerPolicyReceiptRoot: passport.consumerPolicy.receiptRoot,
+    capsules: entries,
+  };
+  return { ...body, root: v4RuntimeResumeDocumentRoot(body) };
+}
+
+function writeReleaseCandidateStageCapsules({
+  passport,
+  buildSummary,
+  outputPath,
+}) {
+  const coordinatesPath = path.resolve(
+    env(
+      "BUILDCHAIN_ARTIFACT_COORDINATES_PATH",
+      ".buildchain/artifacts/artifact-coordinates.json",
+    ),
+  );
+  if (!fs.existsSync(coordinatesPath)) {
+    if (passport.consumerPolicy?.receiptRoot) {
+      throw new Error(
+        "v4 release candidate Stage Capsules require exact artifact coordinates",
+      );
+    }
+    return { path: "", root: "" };
+  }
+  const stageCapsules = createReleaseCandidateStageCapsules({
+    passport,
+    buildSummary,
+    coordinates: readJsonFile(coordinatesPath),
+  });
+  if (!stageCapsules) return { path: "", root: "" };
+  const stageCapsulesPath = path.join(
+    path.dirname(outputPath),
+    "release-candidate-stage-capsules.json",
+  );
+  fs.writeFileSync(
+    stageCapsulesPath,
+    `${JSON.stringify(stageCapsules, null, 2)}\n`,
+  );
+  return {
+    path: path
+      .relative(process.cwd(), stageCapsulesPath)
+      .split(path.sep)
+      .join("/"),
+    root: stageCapsules.root,
+  };
 }
 
-function readJsonFile(filePath) {
-  return JSON.parse(fs.readFileSync(filePath, "utf8"));
+export function resolveLegacyConsumerPolicyReceipt(options = {}) {
+  if (options.json) return { receipt: JSON.parse(options.json), receiptRoot: options.receiptRoot };
+  if (options.repository !== "kungfu-systems/buildchain" || options.targetChannel !== "alpha" || options.workflowShellRef !== "v4-alpha" || options.runtimeOverride !== true) return undefined;
+  if (!/^[0-9a-f]{40}$/u.test(options.runtimeRef || "") || options.runtimeRef !== options.runtimeSha || options.sourceTreeHash !== options.runtimeTreeHash()) return undefined;
+  const root = path.resolve(options.root || ".buildchain/runtime");
+  const alphaLock = readJsonFile(path.join(root, ".buildchain/alpha-contract-lock.json"));
+  const result = scanV4FloatingConsumerPolicy({
+    root, repository: options.repository, sourceSha: options.sourceSha,
+    invokedWorkflow: options.invokedWorkflow || ".github/workflows/build.yml", invocationSourcePath: options.invocationSourcePath,
+    expectedInvocationChannel: "alpha", resolvedWorkflowSha: alphaLock.buildchain?.resolvedSha,
+    resolvedRuntimeSha: options.runtimeSha, scannerRoot: v4ConsumerPolicyScannerRoot(),
+    policy: readJsonFile(path.resolve(import.meta.dirname, "../architecture/v4-floating-consumer-policy.json")),
+  });
+  if (!result.ok) throw new Error(`legacy floating-shell policy receipt invalid: ${result.failures.map(({ code }) => code).join(", ")}`);
+  return { receipt: result.receipt, receiptRoot: result.receiptRoot };
 }
 
 export function generateReleaseCandidatePassportCli() {
@@ -21,23 +181,28 @@ export function generateReleaseCandidatePassportCli() {
   const outputPath = path.resolve(env("BUILDCHAIN_RC_PASSPORT_PATH", ".buildchain/artifacts/release-candidate-passport.json"));
   const buildSummary = readJsonFile(buildSummaryPath);
   const sourceSha = env("BUILDCHAIN_RC_SOURCE_HEAD_SHA", buildSummary.publishSource?.sha || buildSummary.git?.sha || "");
-  const version = env(
-    "BUILDCHAIN_RC_VERSION",
-    buildSummary.publishSource?.consumerVersion || "",
-  );
+  const version = env("BUILDCHAIN_RC_VERSION", buildSummary.publishSource?.consumerVersion || "");
   const gateAggregateJson = env("BUILDCHAIN_GATE_PROFILE_AGGREGATE_JSON");
   const gateAggregate = gateAggregateJson ? JSON.parse(gateAggregateJson) : undefined;
   const controllerReceiptJson = env("BUILDCHAIN_CONTROLLER_RECEIPT_JSON");
   const controllerReceipts = controllerReceiptJson ? [JSON.parse(controllerReceiptJson)] : [];
   const familyEvidenceJson = env("BUILDCHAIN_RC_FAMILY_EVIDENCE_JSON");
   const familyEvidence = familyEvidenceJson ? JSON.parse(familyEvidenceJson) : undefined;
+  const consumerPolicyJson = env("BUILDCHAIN_V4_POLICY_RECEIPT_JSON");
+  const consumerPolicyReceipt = resolveLegacyConsumerPolicyReceipt({
+    json: consumerPolicyJson, receiptRoot: env("BUILDCHAIN_V4_POLICY_RECEIPT_ROOT"),
+    repository: env("GITHUB_REPOSITORY", buildSummary.git?.repository || ""), sourceSha,
+    targetChannel: env("BUILDCHAIN_RC_TARGET_CHANNEL", buildSummary.publishSource?.channel || buildSummary.publishGate?.channel || ""),
+    runtimeRef: env("BUILDCHAIN_RUNTIME_REF", buildSummary.runtime?.ref || ""), runtimeSha: env("BUILDCHAIN_RUNTIME_SHA", buildSummary.runtime?.sha || ""),
+    workflowShellRef: env("BUILDCHAIN_WORKFLOW_SHELL_REF", buildSummary.runtime?.workflowShellRef || ""), runtimeOverride: buildSummary.runtime?.override === true,
+    root: ".buildchain/runtime", invocationSourcePath: env("GITHUB_WORKFLOW_REF"), sourceTreeHash: env("BUILDCHAIN_RC_SOURCE_TREE_HASH"),
+    runtimeTreeHash: () => execFileSync("git", ["-C", ".buildchain/runtime", "rev-parse", "HEAD^{tree}"], { encoding: "utf8" }).trim(),
+  });
   const passport = createReleaseCandidatePassport({
     repository: env("GITHUB_REPOSITORY", buildSummary.git?.repository || ""),
     pullRequest: {
-      number: env("BUILDCHAIN_PULL_REQUEST_NUMBER"),
-      url: env("BUILDCHAIN_PULL_REQUEST_URL"),
-      headRef: env("BUILDCHAIN_PULL_REQUEST_HEAD_REF"),
-      baseRef: env("BUILDCHAIN_PULL_REQUEST_BASE_REF"),
+      number: env("BUILDCHAIN_PULL_REQUEST_NUMBER"), url: env("BUILDCHAIN_PULL_REQUEST_URL"),
+      headRef: env("BUILDCHAIN_PULL_REQUEST_HEAD_REF"), baseRef: env("BUILDCHAIN_PULL_REQUEST_BASE_REF"),
     },
     targetChannel: env("BUILDCHAIN_RC_TARGET_CHANNEL", buildSummary.publishSource?.channel || buildSummary.publishGate?.channel || ""),
     version,
@@ -47,32 +212,24 @@ export function generateReleaseCandidatePassportCli() {
     sourceTreeHash: env("BUILDCHAIN_RC_SOURCE_TREE_HASH"),
     buildSummary,
     buildchain: {
-      ref: env("BUILDCHAIN_RUNTIME_REF", buildSummary.runtime?.ref || ""),
-      sha: env("BUILDCHAIN_RUNTIME_SHA", buildSummary.runtime?.sha || ""),
-      version: env("BUILDCHAIN_RUNTIME_VERSION"),
-      workflowShellRef: env("BUILDCHAIN_WORKFLOW_SHELL_REF", buildSummary.runtime?.workflowShellRef || ""),
+      ref: env("BUILDCHAIN_RUNTIME_REF", buildSummary.runtime?.ref || ""), sha: env("BUILDCHAIN_RUNTIME_SHA", buildSummary.runtime?.sha || ""),
+      version: env("BUILDCHAIN_RUNTIME_VERSION"), workflowShellRef: env("BUILDCHAIN_WORKFLOW_SHELL_REF", buildSummary.runtime?.workflowShellRef || ""),
     },
     gateAggregate,
     familyEvidence,
+    consumerPolicyReceipt,
     controllerReceipts,
     workflow: {
-      name: env("GITHUB_WORKFLOW"),
-      runId: env("GITHUB_RUN_ID", buildSummary.git?.runId || ""),
-      runAttempt: env("GITHUB_RUN_ATTEMPT", buildSummary.git?.runAttempt || ""),
-      url: env("BUILDCHAIN_WORKFLOW_RUN_URL"),
+      name: env("GITHUB_WORKFLOW"), runId: env("GITHUB_RUN_ID", buildSummary.git?.runId || ""),
+      runAttempt: env("GITHUB_RUN_ATTEMPT", buildSummary.git?.runAttempt || ""), url: env("BUILDCHAIN_WORKFLOW_RUN_URL"),
     },
   });
   const validation = validateReleaseCandidatePassport({
-    passport,
-    repository: env("GITHUB_REPOSITORY", buildSummary.git?.repository || ""),
-    sourceHeadSha: sourceSha,
-    buildSummary,
-  });
-  if (!validation.ok) {
-    throw new Error(`release candidate passport invalid: ${validation.errors.join("; ")}`);
-  }
+    passport, repository: env("GITHUB_REPOSITORY", buildSummary.git?.repository || ""), sourceHeadSha: sourceSha, buildSummary });
+  if (!validation.ok) throw new Error(`release candidate passport invalid: ${validation.errors.join("; ")}`);
   fs.mkdirSync(path.dirname(outputPath), { recursive: true });
   fs.writeFileSync(outputPath, `${JSON.stringify(passport, null, 2)}\n`);
+  const stageCapsules = writeReleaseCandidateStageCapsules({ passport, buildSummary, outputPath });
   writeGitHubOutputs({
     "release-candidate-passport-path": path.relative(process.cwd(), outputPath).split(path.sep).join("/"),
     "release-candidate-passport-json": JSON.stringify({
@@ -84,8 +241,11 @@ export function generateReleaseCandidatePassportCli() {
       platformCount: passport.platformMatrix.length,
       gateProfileEvidence: passport.gateProfileEvidence,
       familyEvidence: passport.familyEvidence,
+      consumerPolicy: passport.consumerPolicy,
       controllerReceipts: passport.controllerReceipts || [],
     }),
+    "release-candidate-stage-capsules-path": stageCapsules.path,
+    "release-candidate-stage-capsules-root": stageCapsules.root,
   });
   return passport;
 }

package/scripts/generate-site-bundle.mjs

@@ -46,6 +46,31 @@ import {
 const SITE_BUNDLE_CONTRACT = "kungfu-buildchain-site-bundle";
 const PUBLICATION_RELEASE_REGISTRY_CONTRACT = "kungfu-buildchain-publication-release-registry";
 const README_PATH = "README.md";
+const DEV_DELIVERY_AUTHORITY_SCHEMA =
+  "schemas/dev-delivery-authority-v2.schema.json";
+const DEV_DELIVERY_AUTHORITY_SCHEMA_SOURCE =
+  "contracts/dev-delivery-authority-v2.schema.json";
+const V4_COMPATIBILITY_FACTS_SCHEMA =
+  "schemas/v4-compatibility-facts-v1.schema.json";
+const V4_COMPATIBILITY_FACTS_SCHEMA_SOURCE =
+  "contracts/v4-compatibility-facts-v1.schema.json";
+const V4_PUBLICATION_REHEARSAL_SCHEMA =
+  "schemas/v4-publication-rehearsal-capsule-v1.schema.json";
+const V4_PUBLICATION_REHEARSAL_SCHEMA_SOURCE =
+  "contracts/v4-publication-rehearsal-capsule-v1.schema.json";
+const V4_ADOPTER_DELIVERY_SCHEMA =
+  "schemas/v4-adopter-delivery-v1.schema.json";
+const V4_ADOPTER_DELIVERY_SCHEMA_SOURCE =
+  "contracts/v4-adopter-delivery-v1.schema.json";
+const RELEASE_TAIL_CAPABILITIES_SCHEMA =
+  "schemas/release-tail-capabilities-v1.schema.json";
+const RELEASE_TAIL_CAPABILITIES_SCHEMA_SOURCE =
+  "contracts/release-tail-capabilities-v1.schema.json";
+const PUBLICATION_REHEARSAL_SITE_SCHEMAS = [
+  V4_PUBLICATION_REHEARSAL_SCHEMA,
+  V4_ADOPTER_DELIVERY_SCHEMA,
+  RELEASE_TAIL_CAPABILITIES_SCHEMA,
+];
 const root = path.resolve(import.meta.dirname, "..");
 const outputDir = path.join(root, "dist", "site");
 const requireFromHere = createRequire(import.meta.url);
@@ -73,6 +98,21 @@ function stableJson(value) {
   return `${JSON.stringify(value, null, 2)}\n`;
 }
 
+function siteFileBytes(name, value) {
+  if (name === DEV_DELIVERY_AUTHORITY_SCHEMA) return readText(DEV_DELIVERY_AUTHORITY_SCHEMA_SOURCE);
+  if (name === V4_COMPATIBILITY_FACTS_SCHEMA) return readText(V4_COMPATIBILITY_FACTS_SCHEMA_SOURCE);
+  if (name === V4_PUBLICATION_REHEARSAL_SCHEMA) return readText(V4_PUBLICATION_REHEARSAL_SCHEMA_SOURCE);
+  if (name === V4_ADOPTER_DELIVERY_SCHEMA) return readText(V4_ADOPTER_DELIVERY_SCHEMA_SOURCE);
+  if (name === RELEASE_TAIL_CAPABILITIES_SCHEMA) return readText(RELEASE_TAIL_CAPABILITIES_SCHEMA_SOURCE);
+  return stableJson(value);
+}
+
+function writeSiteFile(name, value) {
+  const filePath = path.join(outputDir, name);
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, siteFileBytes(name, value));
+}
+
 function env(name) {
   return String(process.env[name] || "").trim();
 }
@@ -367,13 +407,16 @@ const manualMetaById = new Map(Object.entries({
   "release-activation-transaction": { capabilityGroup: "release-passport-trust", audience: ["release-operator", "agent"], maturity: "preview", order: 125 },
   "release-candidate": { capabilityGroup: "reusable-build", audience: ["release-operator", "consumer"], maturity: "stable", order: 130 },
   "release-train": { capabilityGroup: "governance-versioning", audience: ["release-operator", "consumer", "agent"], maturity: "preview", order: 132 },
+  "next-development-transition": { capabilityGroup: "governance-versioning", audience: ["release-operator", "consumer", "agent"], maturity: "preview", order: 133 },
   "stable-candidate-patrol": { capabilityGroup: "governance-versioning", audience: ["release-operator", "consumer"], maturity: "preview", order: 135 },
   "dev-qualification-patrol": { capabilityGroup: "governance-versioning", audience: ["release-operator", "consumer", "agent"], maturity: "preview", order: 136 },
   "dev-alpha-candidate-patrol": { capabilityGroup: "governance-versioning", audience: ["release-operator", "consumer", "agent"], maturity: "preview", order: 137 },
   "v4-canonical-contracts": { capabilityGroup: "governance-versioning", audience: ["developer", "maintainer", "agent"], maturity: "preview", order: 138 },
+  "v4-compatibility-facts": { capabilityGroup: "governance-versioning", audience: ["developer", "maintainer", "agent"], maturity: "preview", order: 139 },
   "observed-evidence-patrol": { capabilityGroup: "governance-versioning", audience: ["release-operator", "consumer", "agent"], maturity: "preview", order: 140 },
   "engineering-housekeeper": { capabilityGroup: "governance-versioning", audience: ["maintainer", "consumer", "agent"], maturity: "preview", order: 145 },
   "reusable-build-surface": { capabilityGroup: "reusable-build", audience: ["consumer", "release-operator"], maturity: "stable", order: 200 },
+  "v4-adopter-delivery": { capabilityGroup: "reusable-build", audience: ["consumer", "developer", "agent"], maturity: "preview", order: 205 },
   "lifecycle-protocol": { capabilityGroup: "reusable-build", audience: ["consumer", "developer"], maturity: "stable", order: 210 },
   "runtime-train-validation": { capabilityGroup: "governance-versioning", audience: ["maintainer", "consumer"], maturity: "stable", order: 220 },
   "kfd-support": { capabilityGroup: "kfd-trust", audience: ["agent", "maintainer"], maturity: "stable", order: 300 },
@@ -737,6 +780,7 @@ function buildSiteBundle() {
       "docs/reusable-build-surface.md",
       "docs/release-candidate.md",
       "docs/release-train.md",
+      "docs/next-development-transition.md",
       "docs/stable-candidate-patrol.md",
       "docs/dev-qualification-patrol.md",
       "docs/dev-alpha-candidate-patrol.md",
@@ -931,6 +975,9 @@ function buildSiteBundle() {
       "schemas/release-passport-v1.schema.json",
       "schemas/kfd-agent-hub-adoption.schema.json",
       "schemas/kfd-product-gate-input-v1.schema.json",
+      "schemas/dev-delivery-authority-v2.schema.json",
+      "schemas/v4-compatibility-facts-v1.schema.json",
+      ...PUBLICATION_REHEARSAL_SITE_SCHEMAS,
       "kfd-support.json",
       "artifact-evidence.json",
       "product-mechanism.json",
@@ -965,6 +1012,9 @@ function buildSiteBundle() {
       "schemas/release-passport-v1.schema.json",
       "schemas/kfd-agent-hub-adoption.schema.json",
       "schemas/kfd-product-gate-input-v1.schema.json",
+      "schemas/dev-delivery-authority-v2.schema.json",
+      "schemas/v4-compatibility-facts-v1.schema.json",
+      ...PUBLICATION_REHEARSAL_SITE_SCHEMAS,
       "buildchain-contract.json",
       "kfd-claims.json",
       "product-mechanism.json",
@@ -1095,6 +1145,9 @@ function buildSiteBundle() {
       "schemas/release-passport-v1.schema.json",
       "schemas/kfd-agent-hub-adoption.schema.json",
       "schemas/kfd-product-gate-input-v1.schema.json",
+      "schemas/dev-delivery-authority-v2.schema.json",
+      "schemas/v4-compatibility-facts-v1.schema.json",
+      ...PUBLICATION_REHEARSAL_SITE_SCHEMAS,
       "buildchain-contract.json",
       "kfd-upstream-aggregate.json",
       "kfd-claims.json",
@@ -1269,6 +1322,18 @@ function buildSiteBundle() {
     "schemas/release-passport-v1.schema.json": RELEASE_PASSPORT_SCHEMA,
     "schemas/kfd-agent-hub-adoption.schema.json": KFD_AGENT_HUB_ADOPTION_SCHEMA,
     "schemas/kfd-product-gate-input-v1.schema.json": KFD_PRODUCT_GATE_INPUT_SCHEMA,
+    [DEV_DELIVERY_AUTHORITY_SCHEMA]: readJson(
+      DEV_DELIVERY_AUTHORITY_SCHEMA_SOURCE,
+    ),
+    [V4_COMPATIBILITY_FACTS_SCHEMA]: readJson(
+      V4_COMPATIBILITY_FACTS_SCHEMA_SOURCE,
+    ),
+    ...Object.fromEntries(
+      PUBLICATION_REHEARSAL_SITE_SCHEMAS.map((name) => [
+        name,
+        JSON.parse(siteFileBytes(name)),
+      ]),
+    ),
     "badge-endpoint-registry.json": badgeEndpointRegistry,
     "publication-registry.json": publicationRegistry,
     "buildchain-contract.json": createBuildchainContractWorld({ root, controllerRegistry }),
@@ -1288,7 +1353,7 @@ export function writeSiteBundle({ check = false } = {}) {
   const mismatches = [];
   for (const [name, value] of Object.entries(files)) {
     const filePath = path.join(outputDir, name);
-    const next = stableJson(value);
+    const next = siteFileBytes(name, value);
     if (check) {
       if (existingJson(filePath) !== next) {
         mismatches.push(path.relative(root, filePath));
@@ -1301,11 +1366,11 @@ export function writeSiteBundle({ check = false } = {}) {
   if (!check) {
     for (let iteration = 0; iteration < 5; iteration += 1) {
       for (const [name, value] of Object.entries(files)) {
-        writeJson(path.join(outputDir, name), value);
+        writeSiteFile(name, value);
       }
       const nextFiles = buildSiteBundle();
       const stable = Object.entries(nextFiles).every(([name, value]) => (
-        existingJson(path.join(outputDir, name)) === stableJson(value)
+        existingJson(path.join(outputDir, name)) === siteFileBytes(name, value)
       ));
       files = nextFiles;
       if (stable) {
@@ -1316,7 +1381,7 @@ export function writeSiteBundle({ check = false } = {}) {
       }
     }
     for (const [name, value] of Object.entries(files)) {
-      writeJson(path.join(outputDir, name), value);
+      writeSiteFile(name, value);
     }
   }
   return {

package/scripts/init-repo.mjs

@@ -4,6 +4,11 @@ import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { BUILDCHAIN_CONFIG_PATH } from "../packages/core/buildchain-layout.js";
 import { detectPackageManager, assertPackageManager } from "../packages/core/package-manager.js";
+import {
+  appendNextDevelopmentToml,
+  mergeNextDevelopmentAgentInstructions,
+  nextDevelopmentWorkflowHeader,
+} from "../packages/core/next-development-projection.js";
 
 const BUILDCHAIN_WORKFLOW_REF = "kungfu-systems/buildchain/.github/workflows/.build.yml@v4";
 const DEFAULT_PUBLICATION_LATEX_IMAGE = "ghcr.io/kungfu-systems/build-images/latex-pdf-builder";
@@ -327,7 +332,9 @@ function workflowArtifactPaths(type) {
 }
 
 function publicationWorkflowYaml() {
-  return `name: Build
+  return `${nextDevelopmentWorkflowHeader()}# Commit both .buildchain/contract-lock.json and .buildchain/alpha-contract-lock.json.
+# Persist only @v4 or @v4-alpha; pass temporary train/SHA runtimes through workflow_dispatch.
+name: Build
 
 on:
   workflow_dispatch:
@@ -359,8 +366,10 @@ jobs:
 }
 
 function workflowYaml({ type, runnerPreset, artifactName }) {
-  return `# Buildchain v4 lifecycle checkpoints are governed by architecture/v4-platform-stage-checkpoints.json.
+  return `${nextDevelopmentWorkflowHeader()}# Buildchain v4 lifecycle checkpoints are governed by architecture/v4-platform-stage-checkpoints.json.
 # Do not add undeclared runner-only inputs, outputs, environment, or provider effects.
+# Commit both .buildchain/contract-lock.json and .buildchain/alpha-contract-lock.json.
+# Persist only @v4 or @v4-alpha; pass temporary train/SHA runtimes through workflow_dispatch.
 name: Build
 
 on:
@@ -403,6 +412,13 @@ function writeIfAllowed(filePath, content, { force }) {
   return filePath;
 }
 
+function writeManagedAgentEntry(filePath, current) {
+  const content = mergeNextDevelopmentAgentInstructions(current);
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, content);
+  return filePath;
+}
+
 export function initBuildchainRepo({
   cwd = process.cwd(),
   type = "package",
@@ -413,7 +429,7 @@ export function initBuildchainRepo({
 } = {}) {
   const resolvedCwd = path.resolve(cwd);
   const manager = detectOrDefaultPackageManager(resolvedCwd, packageManager);
-  const toml = (() => {
+  const toml = appendNextDevelopmentToml((() => {
     if (type === "package") {
       return packageToml(resolvedCwd, manager);
     }
@@ -433,7 +449,12 @@ export function initBuildchainRepo({
       return anchoredPackageToml(resolvedCwd, manager);
     }
     throw new Error("init --type must be one of package, native, web-surface, infra-contract, publication-artifact, or anchored-package");
-  })();
+  })());
+
+  const agentsPath = path.join(resolvedCwd, "AGENTS.md");
+  const currentAgents = fs.existsSync(agentsPath)
+    ? fs.readFileSync(agentsPath, "utf8")
+    : "";
 
   const written = [
     writeIfAllowed(path.join(resolvedCwd, BUILDCHAIN_CONFIG_PATH), toml, { force }),
@@ -448,6 +469,7 @@ export function initBuildchainRepo({
           }),
       { force },
     ),
+    writeManagedAgentEntry(agentsPath, currentAgents),
   ];
 
   if (type === "anchored-package" && !fs.existsSync(path.join(resolvedCwd, "release.json"))) {

package/scripts/inspect-artifact-signing-requests.mjs

@@ -82,6 +82,10 @@ export function inspectArtifactSigningRequests({
       if (seen.has(key))
         throw new Error(`duplicate artifact signing request: ${key}`);
       seen.add(key);
+      const {
+        entitlementsProfile = "none",
+        entitlementsPaths = [],
+      } = request.signature;
       const item = {
         id: request.artifact.id,
         slug: safeId(request.artifact.id),
@@ -104,6 +108,8 @@ export function inspectArtifactSigningRequests({
         sourceSha: request.source.sha,
         sourceTreeSha: request.source.treeSha,
         transportFormat: request.artifact.transport?.format || "",
+        entitlementsProfile,
+        entitlementsPaths: entitlementsPaths.join(","),
       };
       if (request.signature.profile === "detached-signature-v1")
         matrices.detached.push(item);