@kungfu-tech/buildchain 3.0.7-alpha.0 → 3.0.7

package/docs/release-governance.md

@@ -610,6 +610,12 @@ The reusable caller supports `off`, read-only `shadow`, and fail-closed
 `required` rollout modes. GitHub Merge Queue remains the final protected-ref
 authority in every mode.
 
+Bounded-concurrency experiments use the separate effect-disabled Warrant
+shadow planner. It may evaluate at most two fully bound lanes from one exact
+observation, but it cannot mint a second production Warrant or mutate GitHub.
+Its aggregate threshold decision is qualification evidence for a later rollout
+change, not authority to change the live single-flight policy.
+
 The canonical consumer required check context is `check / check`, matching the
 reusable workflow call plus its `check` job. Buildchain's own `Verify` workflow
 emits the repository-local context `check`, so Buildchain self-promotion,
@@ -785,6 +791,12 @@ active semver dev line, so consumers do not pin patrol to a stale minor branch.
 The separate workflow names keep consumer schedules readable and stable while
 Buildchain adds new checks behind the cadence wrappers.
 
+Branch and pull-request residue uses the separate
+[`Engineering Housekeeper`](engineering-housekeeper.md) contract. Its scheduled
+callers are report-only and read-only by default; apply requires a manual,
+explicit two-part gate, exact provider-state revalidation, scoped job
+permissions, and rooted plan/report/receipt evidence.
+
 ## Package-Manager Adapters
 
 Old ABV assumed JavaScript repositories with root version state and often
@@ -816,8 +828,11 @@ declare version-state files and lifecycle commands without pretending every
 project is a Node workspace. Supported version files include JSON, TOML, and
 regex-based files such as `CMakeLists.txt` or `conanfile.py`.
 
-The promotion action consumes `version.files`, optional anchored/manual
-`version.derived_files`, and `lifecycle.verify`.
+The promotion action consumes `version.files`, optional
+`version.derived_files`, and `lifecycle.verify`. Semver and anchored/manual
+repositories may both declare lifecycle-regenerated tracked outputs as derived
+files; anchored/manual repositories additionally bind them into their committed
+version witnesses.
 The verify stage runs after generated version-state changes are applied locally
 and before any release refs move. If `verification-command` is passed directly
 to the action, that explicit command overrides `lifecycle.verify`.

package/docs/release-tail-provider-plane.md

@@ -95,7 +95,7 @@ Buildchain self-release calls the same public reusable workflow coordinate as a
 consumer:
 
 ```text
-kungfu-systems/buildchain/.github/workflows/release-candidate-promote.yml@9a0cdf8d84aacf8c7daaac82efa43d1b34696a03
+kungfu-systems/buildchain/.github/workflows/release-candidate-promote.yml@769b221bad7a6b9104afad4c2628d9dca396ab0f
 ```
 
 The caller pins the public router and runtime to the same exact implementation

package/docs/reusable-build-surface.md

@@ -683,6 +683,17 @@ For a declared macOS `archive`, the authority safely extracts the sealed
 container, signs and verifies every Mach-O payload, signs Mach-O payloads inside
 embedded Python wheels, rebuilds each affected wheel's PEP 427 `RECORD`, and
 recreates the original zip or tar.gz before returning the exact final bytes.
+Archives whose executable hosts a JIT runtime can additionally request the
+Buildchain-owned `entitlements_profile = "jit-executable-v1"` and exact paths,
+for example `entitlements_paths = ["product/runtime/python/bin/python3"]`.
+Paths are relative to the extracted archive root. The authority
+then attaches only `com.apple.security.cs.allow-jit` to the exact executable
+Mach-O files sealed in `entitlements_paths`, leaves every other executable and
+library without exception entitlements, and records the profile, paths, and
+entitled executable count in provider evidence. Consumer-provided entitlement
+files and wildcard target paths are unsupported. The profile is valid only for
+Apple `archive` requests and fails closed on an unsafe, missing,
+non-executable, duplicate, or unsealed target path.
 Windows `pe` and `binary` artifacts
 resolve to timestamped native `windows-authenticode`; Windows PE never falls
 back to a detached signature. Linux and other non-native binary files,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "3.0.7-alpha.0",
+  "version": "3.0.7",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",
@@ -49,6 +49,8 @@
     "./publication-control-plane-audit": "./packages/core/publication-control-plane-audit.js",
     "./buildchain-publication-authority": "./packages/core/buildchain-publication-authority.js",
     "./github-governance-authority": "./packages/core/github-governance-authority.js",
+    "./engineering-housekeeper": "./packages/core/engineering-housekeeper.js",
+    "./engineering-housekeeper-github": "./packages/core/engineering-housekeeper-github.js",
     "./kfd-gate": "./packages/core/kfd-gate.js",
     "./release-candidate": "./packages/core/release-candidate.js",
     "./release-candidate-recovery": "./packages/core/release-candidate-recovery.js",
@@ -137,6 +139,7 @@
   },
   "dependencies": {
     "@kungfu-tech/kfd": "1.0.0-alpha.53",
+    "ajv": "8.20.0",
     "smol-toml": "1.7.0"
   }
 }

package/packages/core/artifact-signing.js

@@ -9,6 +9,7 @@ export const ARTIFACT_SIGNING_AUTHORITY_CONTRACT =
 
 const SHA256_PATTERN = /^sha256:[0-9a-f]{64}$/u;
 const SOURCE_SHA_PATTERN = /^[0-9a-f]{40}$/u;
+const ENTITLEMENTS_PROFILES = new Set(["none", "jit-executable-v1"]);
 const FORBIDDEN_CREDENTIAL_KEYS =
   /(?:certificate|password|private.?key|secret|token|notary|issuer|team.?id|environment)/iu;
 
@@ -88,6 +89,64 @@ function exactSourceSha(value, label) {
   return normalized;
 }
 
+function entitlementsPaths(value) {
+  if (value === undefined) return [];
+  if (!Array.isArray(value)) {
+    throw new Error("signing entitlements paths must be an array");
+  }
+  const paths = value.map((entry, index) => {
+    const normalized = nonEmptyString(
+      entry,
+      `signing entitlements paths[${index}]`,
+    );
+    const parts = normalized.split("/");
+    if (
+      normalized.startsWith("/") ||
+      normalized.includes("\\") ||
+      normalized.includes(",") ||
+      parts.some((part) => part === "" || part === "." || part === "..")
+    ) {
+      throw new Error(
+        `signing entitlements paths[${index}] must be a safe archive-relative path`,
+      );
+    }
+    return normalized;
+  });
+  if (new Set(paths).size !== paths.length) {
+    throw new Error("signing entitlements paths must not contain duplicates");
+  }
+  return paths;
+}
+
+function signingEntitlements(profileId, kind, signature) {
+  const profile = String(signature.entitlementsProfile || "none").trim();
+  const paths = entitlementsPaths(signature.entitlementsPaths);
+  if (!ENTITLEMENTS_PROFILES.has(profile)) {
+    throw new Error(
+      `unsupported signing entitlements profile: ${profile || "<empty>"}`,
+    );
+  }
+  if (
+    profile !== "none" &&
+    (profileId !== "apple-developer-id" || kind !== "archive")
+  ) {
+    throw new Error(
+      `signing entitlements profile ${profile} requires an Apple archive`,
+    );
+  }
+  if (
+    (profile === "none" && paths.length !== 0) ||
+    (profile !== "none" && paths.length === 0)
+  ) {
+    throw new Error(
+      "signing entitlements paths must be non-empty exactly when an entitlements profile is enabled",
+    );
+  }
+  return profile === "none"
+    ? {}
+    : { entitlementsProfile: profile, entitlementsPaths: paths };
+}
+
 function assertNoCredentialMaterial(value, path = "request") {
   if (!value || typeof value !== "object") return;
   for (const [key, child] of Object.entries(value)) {
@@ -191,6 +250,7 @@ export function createArtifactSigningRequest({
     platform,
     artifactKind: kind,
   });
+  const entitlementIntent = signingEntitlements(profile.id, kind, signature);
   const request = {
     schemaVersion: 1,
     contract: ARTIFACT_SIGNING_REQUEST_CONTRACT,
@@ -253,6 +313,7 @@ export function createArtifactSigningRequest({
       profile: profile.id,
       provider: profile.provider,
       semantics: profile.semantics,
+      ...entitlementIntent,
     },
     delivery: {
       mode: nonEmptyString(

package/packages/core/buildchain-config.js

@@ -61,6 +61,10 @@ const SUPPORTED_SIGNING_PROFILES = new Set([
   "windows-authenticode",
   "detached-signature-v1",
 ]);
+const SUPPORTED_SIGNING_ENTITLEMENTS_PROFILES = new Set([
+  "none",
+  "jit-executable-v1",
+]);
 const SUPPORTED_SIGNING_ARTIFACT_KINDS = new Set([
   "auto", "binary", "archive", "blob", "directory", "mach-o", "app-bundle",
   "framework-bundle", "plugin-bundle", "xpc-bundle", "dylib", "pkg", "dmg",
@@ -99,6 +103,27 @@ function normalizeStringArray(value, label) {
   return value.map((entry, index) => assertString(entry, `${label}[${index}]`));
 }
 
+function normalizeSigningEntitlementsPaths(value, label) {
+  const paths = normalizeStringArray(value, label);
+  for (const [index, entry] of paths.entries()) {
+    const parts = entry.split("/");
+    if (
+      entry.startsWith("/") ||
+      entry.includes("\\") ||
+      entry.includes(",") ||
+      parts.some((part) => part === "" || part === "." || part === "..")
+    ) {
+      throw new Error(
+        `${label}[${index}] must be a safe archive-relative path`,
+      );
+    }
+  }
+  if (new Set(paths).size !== paths.length) {
+    throw new Error(`${label} must not contain duplicate paths`);
+  }
+  return paths;
+}
+
 function getByDottedKey(target, key) {
   return String(key)
     .split(".")
@@ -362,7 +387,16 @@ function normalizeSigningSection(signing) {
   const artifacts = signing.artifacts.map((artifact, index) => {
     const label = `signing.artifacts[${index}]`;
     assertPlainObject(artifact, label);
-    const allowedKeys = new Set(["id", "path", "profile", "kind", "platforms", "required"]);
+    const allowedKeys = new Set([
+      "id",
+      "path",
+      "profile",
+      "entitlements_profile",
+      "entitlements_paths",
+      "kind",
+      "platforms",
+      "required",
+    ]);
     for (const key of Object.keys(artifact)) {
       if (!allowedKeys.has(key)) {
         throw new Error(`${label}.${key} is not supported; declare desired signature state only`);
@@ -377,10 +411,41 @@ function normalizeSigningSection(signing) {
     if (!SUPPORTED_SIGNING_ARTIFACT_KINDS.has(kind)) {
       throw new Error(`${label}.kind is not a supported signing artifact kind`);
     }
+    const entitlementsProfile =
+      artifact.entitlements_profile === undefined
+        ? "none"
+        : assertString(
+            artifact.entitlements_profile,
+            `${label}.entitlements_profile`,
+          );
+    if (!SUPPORTED_SIGNING_ENTITLEMENTS_PROFILES.has(entitlementsProfile)) {
+      throw new Error(
+        `${label}.entitlements_profile must be one of none or jit-executable-v1`,
+      );
+    }
+    if (entitlementsProfile !== "none" && kind !== "archive") {
+      throw new Error(
+        `${label}.entitlements_profile ${entitlementsProfile} requires kind = "archive"`,
+      );
+    }
+    const entitlementsPaths = normalizeSigningEntitlementsPaths(
+      artifact.entitlements_paths,
+      `${label}.entitlements_paths`,
+    );
+    if (
+      (entitlementsProfile === "none" && entitlementsPaths.length !== 0) ||
+      (entitlementsProfile !== "none" && entitlementsPaths.length === 0)
+    ) {
+      throw new Error(
+        `${label}.entitlements_paths must be non-empty exactly when entitlements_profile is enabled`,
+      );
+    }
     return {
       id: artifact.id === undefined ? artifactPath : assertString(artifact.id, `${label}.id`),
       path: artifactPath,
       profile,
+      entitlementsProfile,
+      entitlementsPaths,
       kind,
       platforms: normalizeStringArray(artifact.platforms, `${label}.platforms`),
       required: optionalBoolean(artifact.required, true),
@@ -1193,11 +1258,6 @@ function validateAnchoredDerivedVersionMaterialConfig(config) {
   if (derivedFiles.length === 0) {
     return;
   }
-  if (config.version.strategy !== "anchored" || config.version.next !== "manual") {
-    throw new Error(
-      "version.derived_files requires version.strategy = \"anchored\" and version.next = \"manual\"",
-    );
-  }
   const versionState =
     config.lifecycle?.["version-state"] ||
     config.lifecycle?.version_state;

package/packages/core/buildchain-publication-authority.js

@@ -37,6 +37,10 @@ const DESCRIPTORS = Object.freeze([
   [".github/workflows/dev-delivery-warrant-cancel.yml", "governance-write"],
   [".github/workflows/dev-merge-queue-governance.yml", "governance-write"],
   [".github/workflows/dev-pr-auto-merge.yml", "governance-write"],
+  [".github/workflows/engineering-housekeeper-daily.yml", "governance-write"],
+  [".github/workflows/engineering-housekeeper-monthly.yml", "governance-write"],
+  [".github/workflows/engineering-housekeeper-weekly.yml", "governance-write"],
+  [".github/workflows/engineering-housekeeper.yml", "governance-write"],
   [".github/workflows/github-governance-audit.yml", "governance-write"],
   [".github/workflows/github-artifact-attestation.yml", "evidence-publication", true, ["github-artifact-attestation"], "oidc", "consumer-defined", "caller-bound", "caller-bound"],
   [".github/workflows/npm-publish.yml", "dry-run-only"],

package/packages/core/controller-evidence.js

@@ -34,13 +34,14 @@ const CONTROLLER_SPECS = [
       "resolve-runtime",
       "resolve-source",
       "anchored-release-preflight",
+      "pre-build-contracts",
       "build",
       "signing-finalization",
       "credential-island",
       "verify",
       "aggregate",
     ],
-    optionalStages: ["anchored-release-preflight", "credential-island"],
+    optionalStages: ["anchored-release-preflight", "pre-build-contracts", "credential-island"],
     evidence: [
       "platform-manifests",
       "build-summary",

package/packages/core/dev-delivery-warrant-cancellation.js

@@ -6,6 +6,7 @@ const TERMINAL_STATES = new Set(["merged", "terminal-failure", "dequeued", "canc
 const QUEUED_CANCELLATION_EVENTS = new Map([
   ["closed", "cancelled"],
   ["cancelled", "cancelled"],
+  ["synchronize", "cancelled"],
   ["dequeued", "dequeued"],
 ]);