@kungfu-tech/buildchain 2.11.14-alpha.0 → 2.11.14-alpha.1

package/dist/site/site-manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-site-manifest",
-  "generatedAt": "2026-07-10T10:14:07.465Z",
-  "publishedAt": "2026-07-10T10:14:07.465Z",
+  "generatedAt": "2026-07-10T11:01:58.300Z",
+  "publishedAt": "2026-07-10T11:01:58.300Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "06c518d7c00527f0964e6c6eefd91532783565fe",
+  "sourceRevision": "5a95cdcb4e1114635046a0765aec1ea1ecc60dcd",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -37,7 +37,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "2.11.14-alpha.0",
+    "version": "2.11.14-alpha.1",
     "versionSource": "package.json#version"
   },
   "entrypoint": "buildchain-site.json",
@@ -221,7 +221,7 @@
       "path": "docs/release-governance.md",
       "plane": "why",
       "exists": true,
-      "digest": "sha256:9c8e3f096d314b2d0ea9a6badfdf263006e190aaa6e861489bdd05c93d3eaf04"
+      "digest": "sha256:f2eae65a8b678203da26e223bda9cffd7939852deea406f7328ce9e617da3c6f"
     },
     {
       "id": "release-flow",
@@ -229,7 +229,7 @@
       "path": "docs/release-flow.md",
       "plane": "verify",
       "exists": true,
-      "digest": "sha256:feb1e056975a4ffb714d8fc0583a0f6fd8ed774c30ca168c27d5e6baf02f1cde"
+      "digest": "sha256:5b855ab3863e197b2ab257536b1f3ff85c79bca1fe962c45089b3f4c5ab81189"
     },
     {
       "id": "runtime-train-validation",

package/docs/release-flow.md

@@ -12,6 +12,8 @@ flowchart TD
   Review["Protected branch review"]
   Merge["Merge PR into alpha or release"]
   Promotion["Buildchain Ref Promotion"]
+  StableDecision{"Release channel?"}
+  StableGate["Stable only: exact-alpha canaries + soak + cooldown"]
   Action["promote-buildchain-ref action"]
   VersionState["Version-state commit"]
   ExactTag["Exact tag"]
@@ -22,7 +24,10 @@ flowchart TD
   Verify --> Review
   Review --> Merge
   Merge --> Promotion
-  Promotion --> Action
+  Promotion --> StableDecision
+  StableDecision -->|yes| StableGate
+  StableDecision -->|no: alpha| Action
+  StableGate --> Action
   Action --> VersionState
   Action --> ExactTag
   Action --> FloatingRefs
@@ -33,6 +38,10 @@ flowchart TD
 Buildchain treats the PR merge as release intent and the promotion action as the
 only component allowed to turn that intent into release refs.
 
+`StableGate` applies only to Buildchain's release channel. Alpha and train
+iteration bypass it. See [Stable Release Throttle And Canary Gate](release-governance.md#stable-release-throttle-and-canary-gate)
+for the versioned policy and evidence contract.
+
 ## Ref State
 
 | Ref kind | Example | Mutability | Purpose |

package/docs/release-governance.md

@@ -206,6 +206,41 @@ The production channel and the test channel therefore intentionally diverge
 after release: production stays on the release commit, while alpha/dev continue
 at the next prerelease commit.
 
+### Stable Release Throttle And Canary Gate
+
+Buildchain's own stable channel has an additional pre-publication gate. It is
+evaluated after the PR-stage release candidate has been resolved and before the
+publish-gate ref, package registry, exact stable tag, or floating stable refs
+are mutated. Train refs and alpha promotion do not execute this gate.
+
+The policy is versioned in `.buildchain/stable-release-policy.json`. A stable
+candidate is allowed only when all of these facts are true:
+
+- the candidate resolves to an immutable exact alpha tag and its GitHub
+  prerelease timestamp;
+- at least 24 hours have passed since the preceding stable patch on the same
+  minor line;
+- the preceding stable-to-alpha comparison contains a product or public
+  contract path, not only version, test, evidence, or retrospective changes;
+- the version-bound impact record has a non-empty summary and at least one
+  surface impact;
+- the `Build Surface Fixture` release-candidate run succeeded;
+- `site-libkungfu-dev` completed its no-apply `Buildchain Stable Canary` and an allowed
+  maintainer attested that successful run on the exact alpha SHA through the
+  `buildchain-canary/site-libkungfu-dev` commit-status context;
+- at least one hour has elapsed after the last required canary completed.
+
+The machine report is written to
+`.buildchain/release-passport/stable-release-gate.json`. A passing report is
+uploaded with the stable release passport. A blocked run writes the same report
+before failing, so the missing or stale condition is inspectable without
+opening a publication transaction.
+
+The cooldown is a minimum interval, not an instruction to release every day.
+Compatible work should still be batched until a stable release has a concrete
+consumer need. Changing the interval, canary set, attestors, product path
+boundary, or soak time is a reviewed policy change.
+
 If release finalization is resumed after generated version-state bookkeeping was
 partially applied, Buildchain applies the same recovery rule: the current
 release head may be the generated commit, or a historical merge commit that
@@ -213,6 +248,13 @@ contains the recorded release material, existing exact tags and alpha/dev refs
 are accepted when they match the transaction, and missing floating `vX.Y` or
 `vX` tags are retried idempotently before completion.
 
+Once the durable release transaction is `complete` and the exact/floating
+stable refs have moved, next-alpha preparation is post-release bookkeeping. A
+failure there records `deferred-post-release-bookkeeping` and
+`next-anchor-required` instead of retroactively reporting the stable release as
+failed. Generated next-alpha merges use the current dev tree as their base and
+overlay only declared version-state paths, preserving concurrent dev changes.
+
 ## Major Gate Semantics
 
 A major gate merge is:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "2.11.14-alpha.0",
+  "version": "2.11.14-alpha.1",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",

package/packages/core/stable-release-gate.js

@@ -0,0 +1,284 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export const STABLE_RELEASE_POLICY_CONTRACT = "kungfu-buildchain-stable-release-policy";
+export const STABLE_RELEASE_GATE_CONTRACT = "kungfu-buildchain-stable-release-gate";
+
+function string(value = "") {
+  return String(value ?? "").trim();
+}
+
+function positiveInteger(value, label) {
+  const number = Number(value);
+  if (!Number.isInteger(number) || number < 0) {
+    throw new Error(`${label} must be a non-negative integer`);
+  }
+  return number;
+}
+
+function timestamp(value, label) {
+  const normalized = string(value);
+  const milliseconds = Date.parse(normalized);
+  if (!normalized || !Number.isFinite(milliseconds)) {
+    throw new Error(`${label} must be an ISO-8601 timestamp`);
+  }
+  return { iso: new Date(milliseconds).toISOString(), milliseconds };
+}
+
+function loadJsonInput({ cwd = process.cwd(), input = "", label }) {
+  const normalized = string(input);
+  if (!normalized) {
+    return undefined;
+  }
+  if (normalized.startsWith("{")) {
+    return JSON.parse(normalized);
+  }
+  const resolved = path.isAbsolute(normalized) ? normalized : path.resolve(cwd, normalized);
+  if (!fs.existsSync(resolved)) {
+    throw new Error(`${label} path does not exist: ${normalized}`);
+  }
+  return JSON.parse(fs.readFileSync(resolved, "utf8"));
+}
+
+export function loadStableReleasePolicy({ cwd = process.cwd(), input = "" } = {}) {
+  const policy = loadJsonInput({ cwd, input, label: "stable release policy" });
+  if (!policy) {
+    return undefined;
+  }
+  if (policy.contract !== STABLE_RELEASE_POLICY_CONTRACT) {
+    throw new Error(`stable release policy contract must be ${STABLE_RELEASE_POLICY_CONTRACT}`);
+  }
+  if (Number(policy.schemaVersion) !== 1) {
+    throw new Error("stable release policy schemaVersion must be 1");
+  }
+  const minimumStableIntervalSeconds = positiveInteger(
+    policy.minimumStableIntervalSeconds,
+    "minimumStableIntervalSeconds",
+  );
+  const minimumCanarySoakSeconds = positiveInteger(
+    policy.minimumCanarySoakSeconds,
+    "minimumCanarySoakSeconds",
+  );
+  const productPathPrefixes = [...new Set(
+    (Array.isArray(policy.productPathPrefixes) ? policy.productPathPrefixes : [])
+      .map(string)
+      .filter(Boolean),
+  )];
+  if (productPathPrefixes.length === 0) {
+    throw new Error("stable release policy requires productPathPrefixes[]");
+  }
+  const requiredCanaries = (Array.isArray(policy.requiredCanaries) ? policy.requiredCanaries : [])
+    .map((canary, index) => {
+      const id = string(canary?.id);
+      const source = string(canary?.source);
+      if (!id) {
+        throw new Error(`requiredCanaries[${index}].id is required`);
+      }
+      if (!new Set(["release-candidate", "commit-status"]).has(source)) {
+        throw new Error(`requiredCanaries[${index}].source must be release-candidate or commit-status`);
+      }
+      if (source === "commit-status" && !string(canary.context)) {
+        throw new Error(`requiredCanaries[${index}].context is required for commit-status canaries`);
+      }
+      return {
+        id,
+        source,
+        repository: string(canary.repository),
+        workflow: string(canary.workflow),
+        context: string(canary.context),
+        allowedAttestors: [...new Set(
+          (Array.isArray(canary.allowedAttestors) ? canary.allowedAttestors : [])
+            .map(string)
+            .filter(Boolean),
+        )],
+      };
+    });
+  if (requiredCanaries.length === 0) {
+    throw new Error("stable release policy requires requiredCanaries[]");
+  }
+  if (new Set(requiredCanaries.map((canary) => canary.id)).size !== requiredCanaries.length) {
+    throw new Error("stable release policy canary ids must be unique");
+  }
+  return {
+    schemaVersion: 1,
+    contract: STABLE_RELEASE_POLICY_CONTRACT,
+    enabled: policy.enabled !== false,
+    minimumStableIntervalSeconds,
+    minimumCanarySoakSeconds,
+    productPathPrefixes,
+    requiredCanaries,
+  };
+}
+
+function check(ok, id, message, details = {}) {
+  return { id, status: ok ? "pass" : "fail", message, details };
+}
+
+function matchesProductPath(file, prefixes) {
+  return prefixes.some((prefix) => file === prefix || file.startsWith(prefix));
+}
+
+export function evaluateStableReleaseGate({
+  policy,
+  channel = "",
+  candidate = {},
+  previousStable = undefined,
+  changedPaths = [],
+  impact = {},
+  canaries = [],
+  now = new Date().toISOString(),
+} = {}) {
+  const normalizedChannel = string(channel);
+  if (!policy || policy.enabled === false || normalizedChannel !== "release") {
+    return {
+      schemaVersion: 1,
+      contract: STABLE_RELEASE_GATE_CONTRACT,
+      applies: false,
+      ok: true,
+      channel: normalizedChannel,
+      checks: [],
+      summary: { reason: !policy ? "policy-not-configured" : policy.enabled === false ? "policy-disabled" : "non-stable-channel" },
+    };
+  }
+
+  const nowTime = timestamp(now, "now");
+  const candidatePublished = timestamp(candidate.publishedAt, "candidate.publishedAt");
+  const candidateSha = string(candidate.sha);
+  const candidateTag = string(candidate.tag);
+  const checks = [];
+  checks.push(check(/^[0-9a-f]{40}$/i.test(candidateSha), "candidate.sha", "candidate alpha SHA is exact", { sha: candidateSha }));
+  checks.push(check(/-alpha\.\d+$/.test(candidateTag), "candidate.tag", "candidate is an exact alpha tag", { tag: candidateTag }));
+
+  if (previousStable) {
+    const previousPublished = timestamp(previousStable.publishedAt, "previousStable.publishedAt");
+    const elapsedSeconds = Math.floor((nowTime.milliseconds - previousPublished.milliseconds) / 1000);
+    checks.push(check(
+      elapsedSeconds >= policy.minimumStableIntervalSeconds,
+      "stable.minimum_interval",
+      "minimum interval since the previous stable release is satisfied",
+      {
+        previousTag: string(previousStable.tag),
+        previousPublishedAt: previousPublished.iso,
+        elapsedSeconds,
+        requiredSeconds: policy.minimumStableIntervalSeconds,
+      },
+    ));
+  } else {
+    checks.push(check(true, "stable.minimum_interval", "no previous stable release exists", { firstStable: true }));
+  }
+
+  const normalizedChangedPaths = [...new Set(changedPaths.map(string).filter(Boolean))].sort();
+  const productChangedPaths = normalizedChangedPaths.filter((file) =>
+    matchesProductPath(file, policy.productPathPrefixes));
+  checks.push(check(
+    productChangedPaths.length > 0,
+    "stable.product_diff",
+    "candidate contains a product or contract difference from the current stable release",
+    { changedPaths: productChangedPaths, comparedPathCount: normalizedChangedPaths.length },
+  ));
+
+  const surfaceImpacts = Array.isArray(impact?.surfaceImpacts) ? impact.surfaceImpacts : [];
+  checks.push(check(
+    surfaceImpacts.length > 0 && string(impact?.summary) !== "",
+    "stable.impact",
+    "version-bound impact declares a summary and at least one surface",
+    { summary: string(impact?.summary), surfaceIds: surfaceImpacts.map((entry) => string(entry?.id)).filter(Boolean) },
+  ));
+
+  const canaryById = new Map(canaries.map((canary) => [string(canary?.id), canary]));
+  const canaryCompletionTimes = [];
+  for (const required of policy.requiredCanaries) {
+    const evidence = canaryById.get(required.id);
+    const completedAt = evidence?.completedAt
+      ? timestamp(evidence.completedAt, `canary ${required.id} completedAt`)
+      : undefined;
+    const attestorAllowed = required.allowedAttestors.length === 0 ||
+      required.allowedAttestors.includes(string(evidence?.attestor));
+    const valid = Boolean(
+      evidence &&
+      string(evidence.status) === "success" &&
+      string(evidence.candidateSha) === candidateSha &&
+      completedAt &&
+      completedAt.milliseconds >= candidatePublished.milliseconds &&
+      attestorAllowed,
+    );
+    if (completedAt) {
+      canaryCompletionTimes.push(completedAt.milliseconds);
+    }
+    checks.push(check(
+      valid,
+      `stable.canary.${required.id}`,
+      `required canary ${required.id} passed for the exact alpha candidate`,
+      {
+        source: required.source,
+        context: required.context,
+        repository: string(evidence?.repository || required.repository),
+        workflow: string(evidence?.workflow || required.workflow),
+        runtimeRef: string(evidence?.runtimeRef),
+        candidateSha: string(evidence?.candidateSha),
+        completedAt: completedAt?.iso || "",
+        evidenceUrl: string(evidence?.evidenceUrl),
+        attestor: string(evidence?.attestor),
+        attestorAllowed,
+      },
+    ));
+  }
+
+  const soakStartMilliseconds = Math.max(candidatePublished.milliseconds, ...canaryCompletionTimes);
+  const soakElapsedSeconds = Math.floor((nowTime.milliseconds - soakStartMilliseconds) / 1000);
+  checks.push(check(
+    canaryCompletionTimes.length === policy.requiredCanaries.length &&
+      soakElapsedSeconds >= policy.minimumCanarySoakSeconds,
+    "stable.canary_soak",
+    "minimum soak interval after the final required canary is satisfied",
+    {
+      soakStartedAt: new Date(soakStartMilliseconds).toISOString(),
+      elapsedSeconds: soakElapsedSeconds,
+      requiredSeconds: policy.minimumCanarySoakSeconds,
+    },
+  ));
+
+  const ok = checks.every((entry) => entry.status === "pass");
+  return {
+    schemaVersion: 1,
+    contract: STABLE_RELEASE_GATE_CONTRACT,
+    applies: true,
+    ok,
+    channel: normalizedChannel,
+    evaluatedAt: nowTime.iso,
+    candidate: {
+      tag: candidateTag,
+      sha: candidateSha,
+      publishedAt: candidatePublished.iso,
+    },
+    previousStable: previousStable
+      ? {
+          tag: string(previousStable.tag),
+          sha: string(previousStable.sha),
+          publishedAt: timestamp(previousStable.publishedAt, "previousStable.publishedAt").iso,
+        }
+      : undefined,
+    policy: {
+      minimumStableIntervalSeconds: policy.minimumStableIntervalSeconds,
+      minimumCanarySoakSeconds: policy.minimumCanarySoakSeconds,
+      requiredCanaries: policy.requiredCanaries.map((canary) => canary.id),
+    },
+    checks,
+    summary: {
+      decision: ok ? "allow" : "block",
+      failedChecks: checks.filter((entry) => entry.status === "fail").map((entry) => entry.id),
+      productChangedPaths,
+    },
+  };
+}
+
+export function assertStableReleaseGate(input = {}) {
+  const report = evaluateStableReleaseGate(input);
+  if (!report.ok) {
+    throw Object.assign(
+      new Error(`stable release gate blocked promotion: ${report.summary.failedChecks.join(", ")}`),
+      { report },
+    );
+  }
+  return report;
+}

package/scripts/check-inventory.mjs

@@ -725,6 +725,8 @@ for (const requiredSnippet of [
   "publish-source-ref: ${{ steps.publish-gate.outputs.ref }}",
   "publish-source-sha: ${{ steps.publish-gate.outputs.sha }}",
   "publish-source-locked: ${{ steps.publish-gate.outputs.locked }}",
+  "Enforce Buildchain stable release canary gate",
+  "BUILDCHAIN_STABLE_RELEASE_POLICY: .buildchain/stable-release-policy.json",
 ]) {
   if (!releaseCandidatePromoteWorkflow.includes(requiredSnippet)) {
     throw new Error(`release candidate promote workflow missing KFD gate pass-through: ${requiredSnippet}`);