@kungfu-tech/buildchain 3.0.3-alpha.0 → 3.0.3-alpha.2

package/packages/core/README.md

@@ -24,6 +24,13 @@ Current shared surfaces:
   through `@kungfu-tech/buildchain/badges`.
 - publication artifact manifests, source bundles, and publication artifact
   passports through `@kungfu-tech/buildchain/publication-artifact`.
+- two-clean-build byte reproducibility receipts through
+  `@kungfu-tech/buildchain/publication-reproducibility`.
+- build-once publication bundle manifests and exact-byte verification through
+  `@kungfu-tech/buildchain/publication-sealed-bundle`.
+- governed Paper work-branch start/submit, fleet audit/update, scaffold,
+  preflight, status, npm bootstrap, build, Alpha, and resume plans through
+  `@kungfu-tech/buildchain/paper`.
 
 ## Toolkit Imports
 
@@ -56,15 +63,20 @@ import {
 CommonJS scripts can use dynamic imports for the same package surfaces:
 
 ```js
-const { createBuildchainLogger } = await import("@kungfu-tech/buildchain/logging");
-const { collectRunnerDiagnostics } = await import("@kungfu-tech/buildchain/diagnostics");
+const { createBuildchainLogger } =
+  await import("@kungfu-tech/buildchain/logging");
+const { collectRunnerDiagnostics } =
+  await import("@kungfu-tech/buildchain/diagnostics");
 ```
 
 Build facts consumers can collect source-bound module/product facts before
 publishing and pass those facts into the release passport:
 
 ```js
-import { collectModuleBuildFacts, writeBuildFacts } from "@kungfu-tech/buildchain/build-facts";
+import {
+  collectModuleBuildFacts,
+  writeBuildFacts,
+} from "@kungfu-tech/buildchain/build-facts";
 
 const fact = collectModuleBuildFacts({ moduleId: "native-core" });
 writeBuildFacts({ fact, output: ".buildchain/facts/native-core.json" });
@@ -94,6 +106,48 @@ import { writePublicationArtifact } from "@kungfu-tech/buildchain/publication-ar
 writePublicationArtifact({ sourceSha: process.env.GITHUB_SHA });
 ```
 
+Before publication admission, prove the exact PDF, source bundle, manifests,
+and npm tarball twice from the same Git commit:
+
+```js
+import { verifyPublicationReproducibility } from "@kungfu-tech/buildchain/publication-reproducibility";
+
+const receipt = verifyPublicationReproducibility({
+  sourceSha: process.env.GITHUB_SHA,
+  promote: true,
+});
+if (!receipt.qualifying) throw new Error("publication is not reproducible");
+```
+
+Bind the promoted bytes into the durable build-once publication envelope:
+
+```js
+import {
+  createPublicationSealedBundle,
+  verifyPublicationSealedBundle,
+} from "@kungfu-tech/buildchain/publication-sealed-bundle";
+```
+
+The sealed manifest names the exact npm tarball and release assets. Promotion
+persists those binary files before registry publication and verifies them again
+when a fresh runner resumes.
+
+Paper automation can use the same typed contracts as the CLI:
+
+```js
+import {
+  collectPaperPreflight,
+  collectPaperStatus,
+  planPaperMigration,
+  planPaperScaffold,
+  writePaperMigration,
+} from "@kungfu-tech/buildchain/paper";
+```
+
+Planning and observation are side-effect free. `writePaperScaffold()` and
+`writePaperMigration()` perform the bounded local writes, while external
+mutations remain explicit CLI operations guarded by `--execute`.
+
 Web-surface validation stays in core because both local scripts and GitHub
 Actions need the same fail-closed interpretation of project, channel, deploy,
 retention, and staging security declarations.
@@ -102,7 +156,10 @@ README badge consumers should import the public badge subpath and treat
 Markdown as a projection of the returned facts:
 
 ```js
-import { collectBadgeBundleFacts, renderBadgeBundleBlock } from "@kungfu-tech/buildchain/badges";
+import {
+  collectBadgeBundleFacts,
+  renderBadgeBundleBlock,
+} from "@kungfu-tech/buildchain/badges";
 
 const facts = await collectBadgeBundleFacts({ cwd: process.cwd() });
 const markdown = renderBadgeBundleBlock(facts);

package/packages/core/buildchain-contract.js

@@ -69,7 +69,7 @@ function surface(root, value) {
 
 function majorLineFromPackageVersion(version = "") {
   const match = String(version || "").match(/^(\d+)\./);
-  return match ? `v${match[1]}` : "v2";
+  return match ? `v${match[1]}` : "v3";
 }
 
 export function createBuildchainContractWorld({
@@ -113,7 +113,7 @@ export function createBuildchainContractWorld({
         "release-candidate-artifact",
       ],
       breakingDefaults: {
-        buildchainRefDefault: "workflow-shell-ref-or-v2",
+        buildchainRefDefault: "workflow-shell-ref-or-v3",
         promoteOnlyHeavyBuildPolicy: "pr-stage-only",
       },
       optionalInputs: [
@@ -198,6 +198,8 @@ export function createBuildchainContractWorld({
         "release-passport-kfd-3-artifact-verify-command",
         "release-passport-invariant-passport-jsons",
         "release-passport-invariant-passport-command",
+        "release-passport-evidence-jsons",
+        "release-passport-attachment-command",
         "github-artifact-attestation-policy-json",
         "github-artifact-attestation-environment",
         "github-artifact-attestation-retention-days",
@@ -280,7 +282,7 @@ export function createBuildchainContractWorld({
         "web-surface-manifest-json",
       ],
       breakingDefaults: {
-        buildchainRefDefault: "workflow-shell-ref-or-v2",
+        buildchainRefDefault: "workflow-shell-ref-or-v3",
         contractCompatibilityPolicy: "major-compatible",
         breakingDriftPolicy: "fail-closed-before-build",
       },
@@ -382,6 +384,8 @@ export function createBuildchainContractWorld({
         "release-passport-kfd-3-artifact-verify-command",
         "release-passport-invariant-passport-jsons",
         "release-passport-invariant-passport-command",
+        "release-passport-evidence-jsons",
+        "release-passport-attachment-command",
         "release-passport-github-artifact-attestation-policy-jsons",
         "github-release",
         "github-release-title",
@@ -746,7 +750,7 @@ export function finalizeBuildchainContractWorld(contractWorld) {
 }
 
 export function createBuildchainContractLock({
-  buildchainRef = "v2",
+  buildchainRef = "v3",
   resolvedSha = "",
   contractWorld,
   compatibilityPolicy = DEFAULT_POLICY,

package/packages/core/cache-evidence.js

@@ -88,6 +88,7 @@ function normalizeBindings(bindings = {}) {
       "policyRoot",
       "platformRoot",
       "cacheProfileRoot",
+      "compilerCachePreparationRoot",
     ]),
     "bindings",
   );

package/packages/core/diagnostics.js

@@ -645,27 +645,84 @@ function observedMetric(unit, value, source, evidenceRoot) {
   };
 }
 
-function cacheStatsCount(stats, names) {
-  return names.reduce((sum, name) => sum + Number(stats?.[name] || 0), 0);
+function numericTotal(value) {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (value && typeof value === "object") {
+    return Object.values(value).reduce((sum, entry) => sum + numericTotal(entry), 0);
+  }
+  return 0;
 }
 
-function compilerCacheOutcome(compilerCaches) {
+function cacheStatsCount(stats, names) {
+  return names.reduce((sum, name) => sum + numericTotal(stats?.[name]), 0);
+}
+
+function compilerCacheObservation(compilerCaches, compilerCachePreparation) {
+  const preparationValid =
+    compilerCachePreparation?.contract ===
+      "kungfu-buildchain-compiler-cache-preparation" &&
+    compilerCachePreparation?.provider === "sccache" &&
+    compilerCachePreparation?.status === "prepared" &&
+    compilerCachePreparation?.action?.statsReset === true &&
+    /^sha256:[0-9a-f]{64}$/.test(compilerCachePreparation?.root || "");
+  const sccache = compilerCaches?.sccache;
+  if (preparationValid && sccache?.available && sccache.stats) {
+    const stats = sccache.stats.stats || sccache.stats;
+    return {
+      provider: "sccache",
+      producer: "sccache",
+      source: "sccache-current-run-stats",
+      stats,
+      hits: cacheStatsCount(stats, [
+        "cache_hits",
+        "cache_hit",
+        "cache_hits_count",
+        "cache_hit_count",
+      ]),
+      misses: cacheStatsCount(stats, [
+        "cache_misses",
+        "cache_miss",
+        "cache_misses_count",
+        "cache_miss_count",
+      ]),
+    };
+  }
   const logStats = compilerCaches?.ccache?.logStats;
-  if (!logStats?.available || !logStats.stats) return "unavailable";
-  const hits = cacheStatsCount(logStats.stats, [
-    "direct_cache_hit",
-    "preprocessed_cache_hit",
-  ]);
-  const misses = cacheStatsCount(logStats.stats, ["cache_miss"]);
-  if (hits > 0 && misses > 0) return "partial";
-  if (hits > 0) return "hit";
-  if (misses > 0) return "miss";
+  if (logStats?.available && logStats.stats) {
+    return {
+      provider: "ccache",
+      producer: "ccache",
+      source: "ccache-current-run-stats-log",
+      stats: logStats.stats,
+      hits: cacheStatsCount(logStats.stats, [
+        "direct_cache_hit",
+        "preprocessed_cache_hit",
+      ]),
+      misses: cacheStatsCount(logStats.stats, ["cache_miss"]),
+    };
+  }
+  return {
+    provider: sccache?.available ? "sccache" : "compiler-cache",
+    producer: "unavailable",
+    source: sccache?.available ? "sccache-cumulative-stats" : "compiler-cache-diagnostics",
+    stats: undefined,
+    hits: 0,
+    misses: 0,
+  };
+}
+
+function compilerCacheOutcome(observation) {
+  if (!observation?.stats) return "unavailable";
+  if (observation.hits > 0 && observation.misses > 0) return "partial";
+  if (observation.hits > 0) return "hit";
+  if (observation.misses > 0) return "miss";
   return "bypassed";
 }
 
-function createStructuredCacheEvidence({
+export function createStructuredCacheEvidence({
   sourceCheckout,
   compilerCaches,
+  compilerCachePreparation,
   platform,
   env = process.env,
 }) {
@@ -696,6 +753,9 @@ function createStructuredCacheEvidence({
       ? { policyRoot: env.BUILDCHAIN_CACHE_POLICY_ROOT }
       : {}),
     ...(policyRoot ? { cacheProfileRoot: policyRoot } : {}),
+    ...(compilerCachePreparation?.root
+      ? { compilerCachePreparationRoot: compilerCachePreparation.root }
+      : {}),
   };
   const operations = [];
   if (sourceCheckout) {
@@ -780,53 +840,65 @@ function createStructuredCacheEvidence({
       }),
     );
   }
-  const compilerEvidenceRoot = cacheEvidenceDigest(compilerCaches || {});
+  const compilerObservation = compilerCacheObservation(
+    compilerCaches,
+    compilerCachePreparation,
+  );
+  const compilerEvidenceRoot = cacheEvidenceDigest({
+    compilerCaches: compilerCaches || {},
+    compilerCachePreparation: compilerCachePreparation || null,
+  });
+  const compilerMetricReason = compilerObservation.stats
+    ? `${compilerObservation.provider} current-run stats do not expose this metric`
+    : compilerObservation.provider === "sccache"
+      ? "sccache stats were not admitted without a current-run reset preparation receipt"
+      : "compiler cache current-run stats were unavailable";
   operations.push(
     createCacheOperationReceipt({
       operationId: `compiler-cache:${platform}`,
       operation: "restore",
-      provider: compilerCaches?.ccache?.available ? "ccache" : "compiler-cache",
-      producer: compilerCaches?.ccache?.available ? "ccache" : "unavailable",
+      provider: compilerObservation.provider,
+      producer: compilerObservation.producer,
       platform,
-      cacheKey: policyRoot || null,
+      cacheKey: compilerCachePreparation?.root || policyRoot || null,
       cacheRoot: policyRoot || null,
-      outcome: compilerCacheOutcome(compilerCaches),
+      outcome: compilerCacheOutcome(compilerObservation),
       bindings,
       metrics: {
         lookupDuration: unavailableMetric(
           "ms",
-          "ccache stats log exposes outcomes but not lookup duration",
-          "ccache-stats-log",
+          compilerMetricReason,
+          compilerObservation.source,
           compilerEvidenceRoot,
         ),
         restoreDuration: unavailableMetric(
           "ms",
-          "ccache stats log exposes outcomes but not transfer duration",
-          "ccache-stats-log",
+          compilerMetricReason,
+          compilerObservation.source,
           compilerEvidenceRoot,
         ),
         saveDuration: unavailableMetric(
           "ms",
-          "ccache stats log exposes writes but not save duration",
-          "ccache-stats-log",
+          compilerMetricReason,
+          compilerObservation.source,
           compilerEvidenceRoot,
         ),
         restoredBytes: unavailableMetric(
           "bytes",
-          "ccache does not expose per-run restored bytes",
-          "ccache-stats-log",
+          compilerMetricReason,
+          compilerObservation.source,
           compilerEvidenceRoot,
         ),
         writtenBytes: unavailableMetric(
           "bytes",
-          "ccache does not expose per-run written bytes",
-          "ccache-stats-log",
+          compilerMetricReason,
+          compilerObservation.source,
           compilerEvidenceRoot,
         ),
         savedTime: unavailableMetric(
           "ms",
-          "ccache does not report evidence-backed compile time saved",
-          "ccache-stats-log",
+          compilerMetricReason,
+          compilerObservation.source,
           compilerEvidenceRoot,
         ),
       },
@@ -1343,6 +1415,7 @@ export function createDiagnosticsArtifact({
   processSummary = undefined,
   requestedParallelism = 0,
   sourceCheckout = undefined,
+  compilerCachePreparation = undefined,
   links = {},
 } = {}) {
   const resolvedCwd = path.resolve(cwd);
@@ -1370,6 +1443,7 @@ export function createDiagnosticsArtifact({
     cacheEvidence: createStructuredCacheEvidence({
       sourceCheckout,
       compilerCaches,
+      compilerCachePreparation,
       platform,
     }),
     nativeCacheDirs: native.cacheDirs || [],
@@ -1377,6 +1451,7 @@ export function createDiagnosticsArtifact({
     lifecycleObservability: lifecycleObservability || summarizeLifecycleObservability({ events, logPath }),
     process: processSummary || summarizeProcessSamples({ samples: processSamples, requestedParallelism }),
     ...(sourceCheckout ? { sourceCheckout } : {}),
+    ...(compilerCachePreparation ? { compilerCachePreparation } : {}),
     links,
   };
 }

package/packages/core/github-governance-authority.js

@@ -33,6 +33,11 @@ const target = (
   strictRequiredChecks,
   allowedBypassActors,
 });
+const paperTargets = (mainCheck) => [
+  target("main", [check(mainCheck)], false),
+  ...["dev", "alpha", "release"].map((family) =>
+    target(`${family}/v0/v0.1`, [check("check / check")], true)),
+];
 const PUBLIC_REPOSITORY_TARGETS = Object.freeze({
   ".github": [
     target("main", [check("governance")], false),
@@ -92,31 +97,11 @@ const PUBLIC_REPOSITORY_TARGETS = Object.freeze({
     target("dev/v1/v1.0", [check("Signed-off commits"), check("check")], true),
     target("alpha/v1/v1.0", [check("Signed-off commits"), check("check")], false),
   ],
-  "paper-episodes-to-primitives": [
-    target("main", [check("governance")], false),
-    target("dev/v0/v0.1", [check("check / check")], true),
-    target("alpha/v0/v0.1", [check("check / check")], true),
-  ],
-  "paper-kfd-foundation-real-world-agent-work": [
-    target("main", [check("check / check")], false),
-    target("dev/v0/v0.1", [check("check / check")], true),
-    target("alpha/v0/v0.1", [check("check / check")], true),
-  ],
-  "paper-kfd-machine-life-roadmap": [
-    target("main", [check("check / check")], false),
-    target("dev/v0/v0.1", [check("check / check")], true),
-    target("alpha/v0/v0.1", [check("check / check")], true),
-  ],
-  "paper-kungfu-product-white-paper": [
-    target("main", [check("check / check")], false),
-    target("dev/v0/v0.1", [check("check / check")], true),
-    target("alpha/v0/v0.1", [check("check / check")], true),
-  ],
-  "paper-observer-declared-timelines": [
-    target("main", [check("check / check")], false),
-    target("dev/v0/v0.1", [check("check / check")], true),
-    target("alpha/v0/v0.1", [check("check / check")], true),
-  ],
+  "paper-episodes-to-primitives": paperTargets("governance"),
+  "paper-kfd-foundation-real-world-agent-work": paperTargets("check / check"),
+  "paper-kfd-machine-life-roadmap": paperTargets("check / check"),
+  "paper-kungfu-product-white-paper": paperTargets("check / check"),
+  "paper-observer-declared-timelines": paperTargets("check / check"),
   "site-kungfu-tech": [
     target("main", [check("web-surface / Record web-surface controller receipt")], false),
   ],

package/packages/core/index.js

@@ -157,6 +157,7 @@ export {
 } from "./build-facts.js";
 
 export {
+  FAMILY_RELEASE_EVIDENCE_CONTRACT,
   RELEASE_CANDIDATE_PASSPORT_CONTRACT,
   createReleaseCandidatePassport,
   sha256Json,
@@ -386,6 +387,7 @@ export {
   KFD2_TRUST_PROOF_CONTRACT,
   PRODUCT_MECHANISM_CONTRACT,
   RELEASE_CHECK_REPORT_CONTRACT,
+  RELEASE_EVIDENCE_ATTACHMENT_CONTRACT,
   RELEASE_PASSPORT_CONTRACT,
   collectGitHubReleasePassport,
   createArtifactEvidence,
@@ -592,6 +594,8 @@ export {
   RELEASE_PROPAGATION_GRAPH_CONTRACT,
   RELEASE_PROPAGATION_LOCK_CONTRACT,
   RELEASE_PROPAGATION_PLAN_CONTRACT,
+  RELEASE_PROPAGATION_RECEIPT_CONTRACT,
+  createReleasePropagationReceipt,
   createReleasePropagationLock,
   normalizeReleasePropagationGraph,
   planReleasePropagation,
@@ -614,6 +618,42 @@ export {
   validateReleaseActivationTransaction,
 } from "./release-activation-transaction.js";
 
+export {
+  PUBLICATION_REPRODUCIBILITY_RECEIPT_CONTRACT,
+  verifyPublicationReproducibility,
+} from "./publication-reproducibility.js";
+
+export {
+  PUBLICATION_SEALED_BUNDLE_CONTRACT,
+  createPublicationSealedBundle,
+  verifyPublicationSealedBundle,
+} from "./publication-sealed-bundle.js";
+
+export {
+  PAPER_ALPHA_PLAN_CONTRACT,
+  PAPER_BUILD_PLAN_CONTRACT,
+  PAPER_MIGRATION_CONTRACT,
+  PAPER_NPM_BOOTSTRAP_CONTRACT,
+  PAPER_PATHS,
+  PAPER_PREFLIGHT_CONTRACT,
+  PAPER_RESUME_PLAN_CONTRACT,
+  PAPER_SCAFFOLD_CONTRACT,
+  PAPER_STATE_ORDER,
+  PAPER_STATUS_CONTRACT,
+  PAPER_VISIBILITY_CONTRACT,
+  collectPaperPreflight,
+  collectPaperStatus,
+  createPaperAlphaPlan,
+  createPaperBuildPlan,
+  createPaperResumePlan,
+  executePaperNpmBootstrap,
+  planPaperMigration,
+  planPaperScaffold,
+  resolvePaperRepository,
+  writePaperMigration,
+  writePaperScaffold,
+} from "./paper.js"; export * from "./paper-work.js"; export * from "./paper-fleet.js";
+
 export {
   SURFACE_TIMESTAMP_POLICY_CONTRACT,
   applySurfaceTimestampPolicy,