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

package/contracts/v4-runtime-ref-resume-authority-v1.schema.json

@@ -1,235 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://buildchain.libkungfu.dev/schema/v4-runtime-ref-resume-authority-v1.schema.json",
-  "title": "Buildchain v4 transient runtime authorization and resume lineage evidence",
-  "type": "object",
-  "additionalProperties": false,
-  "required": ["authorizationRoot", "authorization", "lineageRoot", "lineage"],
-  "properties": {
-    "authorizationRoot": { "$ref": "#/$defs/root" },
-    "authorization": { "$ref": "#/$defs/authorization" },
-    "lineageRoot": { "$ref": "#/$defs/root" },
-    "lineage": { "$ref": "#/$defs/lineage" }
-  },
-  "$defs": {
-    "root": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
-    "sha": { "type": "string", "pattern": "^[0-9a-f]{40}$" },
-    "token": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:/-]*$" },
-    "authorization": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": [
-        "schemaVersion",
-        "contract",
-        "status",
-        "mode",
-        "eventName",
-        "repository",
-        "actor",
-        "reason",
-        "authorizedAt",
-        "source",
-        "request",
-        "runtime",
-        "contractLocks",
-        "consumerPolicyReceiptRoot",
-        "persistenceScanRoot"
-      ],
-      "properties": {
-        "schemaVersion": { "const": 1 },
-        "contract": {
-          "const": "kungfu-buildchain-v4-runtime-authorization/v1"
-        },
-        "status": { "const": "authorized" },
-        "mode": { "enum": ["dispatch", "resume", "rescue"] },
-        "eventName": { "const": "workflow_dispatch" },
-        "repository": { "type": "string", "minLength": 3 },
-        "actor": { "$ref": "#/$defs/actor" },
-        "reason": { "type": "string", "minLength": 1 },
-        "authorizedAt": {
-          "type": "string",
-          "pattern": "^(?!0000)\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{3})?Z$"
-        },
-        "source": { "$ref": "#/$defs/source" },
-        "request": { "$ref": "#/$defs/request" },
-        "runtime": { "$ref": "#/$defs/runtime" },
-        "contractLocks": { "$ref": "#/$defs/contractLocks" },
-        "consumerPolicyReceiptRoot": { "$ref": "#/$defs/root" },
-        "persistenceScanRoot": { "$ref": "#/$defs/root" }
-      }
-    },
-    "lineage": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": [
-        "schemaVersion",
-        "contract",
-        "status",
-        "authorizationRoot",
-        "source",
-        "consumerPolicyReceiptRoot",
-        "attempts",
-        "floatingRefMovement",
-        "continuation",
-        "stageCapsules",
-        "finalPublicReadbackRoot"
-      ],
-      "properties": {
-        "schemaVersion": { "const": 1 },
-        "contract": {
-          "const": "kungfu-buildchain-v4-runtime-resume-lineage/v1"
-        },
-        "status": { "const": "qualified" },
-        "authorizationRoot": { "$ref": "#/$defs/root" },
-        "source": { "$ref": "#/$defs/source" },
-        "consumerPolicyReceiptRoot": { "$ref": "#/$defs/root" },
-        "attempts": { "$ref": "#/$defs/attempts" },
-        "floatingRefMovement": { "$ref": "#/$defs/floatingRefMovement" },
-        "continuation": { "$ref": "#/$defs/continuation" },
-        "stageCapsules": { "$ref": "#/$defs/stageCapsules" },
-        "finalPublicReadbackRoot": { "$ref": "#/$defs/root" }
-      }
-    },
-    "actor": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["login", "permission"],
-      "properties": {
-        "login": { "type": "string", "minLength": 1 },
-        "permission": { "enum": ["write", "maintain", "admin"] }
-      }
-    },
-    "source": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["sha", "treeSha"],
-      "properties": {
-        "sha": { "$ref": "#/$defs/sha" },
-        "treeSha": { "$ref": "#/$defs/sha" }
-      }
-    },
-    "request": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["ref", "class"],
-      "properties": {
-        "ref": { "type": "string", "minLength": 1 },
-        "class": { "enum": ["exact-sha", "floating", "train", "authority"] }
-      }
-    },
-    "readback": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["ref", "sha", "containsRuntimeSha", "readbackRoot"],
-      "properties": {
-        "ref": { "type": "string", "minLength": 1 },
-        "sha": { "$ref": "#/$defs/sha" },
-        "containsRuntimeSha": { "type": "boolean" },
-        "readbackRoot": { "$ref": "#/$defs/root" }
-      }
-    },
-    "runtime": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["sha", "reachableFrom"],
-      "properties": {
-        "sha": { "$ref": "#/$defs/sha" },
-        "reachableFrom": {
-          "type": "array",
-          "minItems": 1,
-          "uniqueItems": true,
-          "items": { "$ref": "#/$defs/readback" }
-        }
-      }
-    },
-    "contractLocks": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["stableRoot", "alphaRoot"],
-      "properties": {
-        "stableRoot": { "$ref": "#/$defs/root" },
-        "alphaRoot": { "$ref": "#/$defs/root" }
-      }
-    },
-    "attempt": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["id", "runtimeSha"],
-      "properties": {
-        "id": { "$ref": "#/$defs/token" },
-        "runtimeSha": { "$ref": "#/$defs/sha" }
-      }
-    },
-    "attempts": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["build", "resume"],
-      "properties": {
-        "build": { "$ref": "#/$defs/attempt" },
-        "resume": { "$ref": "#/$defs/attempt" }
-      }
-    },
-    "refReadback": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["ref", "sha"],
-      "properties": {
-        "ref": { "enum": ["v4", "v4-alpha"] },
-        "sha": { "$ref": "#/$defs/sha" }
-      }
-    },
-    "floatingRefMovement": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["before", "after"],
-      "properties": {
-        "before": { "$ref": "#/$defs/refReadback" },
-        "after": { "$ref": "#/$defs/refReadback" }
-      }
-    },
-    "continuation": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["mechanism", "rerunFailedJobs", "resumePlanRoot"],
-      "properties": {
-        "mechanism": { "const": "new-governed-attempt" },
-        "rerunFailedJobs": { "const": false },
-        "resumePlanRoot": { "$ref": "#/$defs/root" }
-      }
-    },
-    "capsule": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["platform", "capsuleRoot", "identityRoot", "artifactDigest"],
-      "properties": {
-        "platform": { "$ref": "#/$defs/token" },
-        "capsuleRoot": { "$ref": "#/$defs/root" },
-        "identityRoot": { "$ref": "#/$defs/root" },
-        "artifactDigest": { "$ref": "#/$defs/root" }
-      }
-    },
-    "stageCapsules": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["requiredPlatforms", "reused", "rebuildPlatforms"],
-      "properties": {
-        "requiredPlatforms": {
-          "type": "array",
-          "minItems": 1,
-          "uniqueItems": true,
-          "items": { "$ref": "#/$defs/token" }
-        },
-        "reused": {
-          "type": "array",
-          "uniqueItems": true,
-          "items": { "$ref": "#/$defs/capsule" }
-        },
-        "rebuildPlatforms": {
-          "type": "array",
-          "uniqueItems": true,
-          "items": { "$ref": "#/$defs/token" }
-        }
-      }
-    }
-  }
-}

package/docs/v4-runtime-ref-resume-authority.md

@@ -1,69 +0,0 @@
----
-status: draft
-period: ongoing
-theme: buildchain-v4-runtime-ref-resume-authority
-doc_type: contract-guide
-source_level: local-files
-confidence: high
-sensitivity: public
-evidence_grade: A
-review_state: unreviewed
-last_reviewed: 2026-08-15
-ai_provenance:
-  model_family: GPT-5
-  product: Codex
-  generated_at: 2026-08-14
-  invisible_context: not asserted
----
-
-# Buildchain v4 transient runtime and resume authority
-
-Buildchain v4 consumers keep `v4` or `v4-alpha` in tracked workflow source.
-A train, authority ref, or exact SHA is transient run data, never a new
-committed default. The public promotion router accepts that escape only from a
-trusted `workflow_dispatch` actor with write, maintain, or admin permission.
-Before heavy promotion work, it binds an exact source tree, operator reason,
-dual consumer contract-lock roots, the floating-consumer policy receipt, a
-clean persistence scan, and GitHub provider readbacks proving that the selected
-runtime is reachable from an approved v4 ref.
-
-The persistence scan covers tracked workflow, composite-action, JSON, TOML, and
-YAML surfaces. Exact SHA, train/authority defaults, and runtime selectors hidden
-through repository variables, secrets, or environment indirection reject the
-run. OIDC, IAM, and other external authority references are inventoried as
-metadata only; credential values are never read or written to evidence.
-
-## Resume after a floating ref moves
-
-A late platform failure is resumed as a new governed attempt. It is not a
-GitHub failed-job rerun. The lineage keeps runtime A (the runtime that built and
-sealed each reusable Stage Capsule) separate from runtime B (the authorized
-runtime executing the new attempt). A Capsule is reusable only when its source
-SHA, source tree, platform, policy root, build runtime, identity root, Capsule
-root, and artifact digest still match. Valid unaffected platforms are restored;
-only missing platforms rebuild. Stale, ambiguous, unsealed, cross-source, or
-cross-policy evidence fails closed.
-
-This deliberately does not weaken the existing Stage Capsule resume planner's
-`runtime-changed` invalidation. That planner decides whether a stage may be
-reused under one expected build identity. This contract instead proves that an
-already sealed output built under runtime A remains the exact product input
-while a distinct orchestration attempt runs under runtime B. Runtime B never
-rewrites the Capsule's build identity.
-
-Final Release Passport evidence embeds the complete authorization receipt and
-the A+B resume lineage under `v4RuntimeResume`. The section binds the new
-attempt, floating-ref movement, reused and rebuilt platform partition,
-consumer-policy receipt, resume plan, and final public readback roots. Tampering
-with either document or crossing authorization/lineage roots rejects Passport
-construction and verification.
-
-Normative files:
-
-- `architecture/runtime-ref-resume-authority.json`
-- `contracts/v4-runtime-ref-resume-authority-v1.schema.json`
-- `packages/core/consumer/runtime-ref-resume-authority.js`
-- `packages/core/release/runtime-override-authorization.js`
-
-This contract changes no v3 behavior, grants no provider mutation authority,
-and stores no credential material.

package/packages/core/consumer/channel-selection.js

@@ -1,211 +0,0 @@
-const CHANNELS = new Set(["auto", "alpha", "stable"]);
-const STABLE_PUBLISH_CHANNELS = new Set(["release", "major"]);
-const OFFICIAL_REF = /^v(\d+)(?:\.\d+)?(?:-alpha)?$/;
-const EXACT_SHA = /^[0-9a-f]{40}$/i;
-const TRAIN_REF =
-  /^(?:refs\/heads\/)?train\/v(\d+)\/v\d+\.\d+\/[A-Za-z0-9._/-]+$/;
-const AUTHORITY_REF =
-  /^(?:refs\/heads\/)?authority\/v(\d+)\/v\d+\.\d+\/[A-Za-z0-9._/-]+$/;
-const SEMVER_TAG = /^refs\/tags\/v?\d+\.\d+\.\d+(?:-([0-9A-Za-z.-]+))?$/;
-
-function normalized(value) {
-  return String(value ?? "").trim();
-}
-
-function parseBoolean(value, name) {
-  const text = normalized(value).toLowerCase();
-  if (text === "true") return true;
-  if (text === "false") return false;
-  throw new Error(`${name} must be true or false`);
-}
-
-function majorFrom(value) {
-  const text = normalized(value).replace(/^refs\/(?:heads|tags)\//, "");
-  const official = text.match(OFFICIAL_REF);
-  if (official) return Number(official[1]);
-  const train = text.match(TRAIN_REF);
-  if (train) return Number(train[1]);
-  const authority = text.match(AUTHORITY_REF);
-  if (authority) return Number(authority[1]);
-  const embedded = text.match(/(?:^|\/)v(\d+)(?:$|[./-])/);
-  if (embedded) return Number(embedded[1]);
-  const version = text.match(/^(\d+)\.\d+\.\d+/);
-  return version ? Number(version[1]) : undefined;
-}
-
-function resolveMajor({ requestedRef, routerRef, packageVersion }) {
-  for (const candidate of [requestedRef, routerRef, packageVersion]) {
-    const major = majorFrom(candidate);
-    if (Number.isInteger(major)) return major;
-  }
-  throw new Error(
-    "unable to derive the Buildchain major; call the router from a vN ref or provide a vN buildchain-ref",
-  );
-}
-
-function classifyRequestedRef(value) {
-  const ref = normalized(value).replace(/^refs\/(?:heads|tags)\//, "");
-  if (!ref) return { kind: "none", ref };
-  if (EXACT_SHA.test(ref)) return { kind: "override", ref };
-  if (TRAIN_REF.test(value) || TRAIN_REF.test(ref)) {
-    return {
-      kind: "override",
-      ref: normalized(value).replace(/^refs\/heads\//, ""),
-    };
-  }
-  if (AUTHORITY_REF.test(value) || AUTHORITY_REF.test(ref)) {
-    return {
-      kind: "override",
-      ref: normalized(value).replace(/^refs\/heads\//, ""),
-    };
-  }
-  const official = ref.match(OFFICIAL_REF);
-  if (official) {
-    return {
-      kind: ref.endsWith("-alpha") ? "alpha" : "stable",
-      ref,
-      major: Number(official[1]),
-    };
-  }
-  throw new Error(
-    "buildchain-ref must be an official vN/vN.M channel, a train ref, an authority ref, or an exact 40-character SHA",
-  );
-}
-
-function selected(channel, major, source, reason) {
-  return {
-    channel,
-    major,
-    buildchainRef: channel === "alpha" ? `v${major}-alpha` : `v${major}`,
-    runtimeOverride: false,
-    selectionSource: source,
-    reason,
-  };
-}
-
-export function resolveBuildchainChannel({
-  requestedChannel = "auto",
-  requestedRef = "",
-  publishChannel = "none",
-  eventName = "",
-  gitRef = "",
-  releasePrerelease = "",
-  routerRef = "",
-  packageVersion = "",
-} = {}) {
-  const channel = normalized(requestedChannel || "auto").toLowerCase();
-  if (!CHANNELS.has(channel)) {
-    throw new Error("buildchain-channel must be auto, alpha, or stable");
-  }
-
-  const explicitRef = classifyRequestedRef(requestedRef);
-  const major = resolveMajor({
-    requestedRef: explicitRef.ref,
-    routerRef,
-    packageVersion,
-  });
-  if (explicitRef.kind !== "none") {
-    if (
-      channel !== "auto" &&
-      explicitRef.kind !== "override" &&
-      channel !== explicitRef.kind
-    ) {
-      throw new Error(
-        `buildchain-channel=${channel} conflicts with buildchain-ref=${explicitRef.ref}`,
-      );
-    }
-    if (explicitRef.kind === "override") {
-      const lane = resolveBuildchainChannel({
-        requestedChannel: channel,
-        requestedRef: "",
-        publishChannel,
-        eventName,
-        gitRef,
-        releasePrerelease,
-        routerRef: `v${major}`,
-        packageVersion,
-      });
-      return {
-        ...lane,
-        major,
-        buildchainRef: explicitRef.ref,
-        runtimeOverride: true,
-        selectionSource: "explicit-buildchain-ref+channel-evidence",
-        reason: `trusted runtime override ${explicitRef.ref} bound to ${lane.channel}`,
-      };
-    }
-    return {
-      channel: explicitRef.kind,
-      major,
-      buildchainRef: explicitRef.ref,
-      runtimeOverride: false,
-      selectionSource: "explicit-buildchain-ref",
-      reason: `explicit Buildchain runtime ref ${explicitRef.ref}`,
-    };
-  }
-
-  if (channel !== "auto") {
-    return selected(
-      channel,
-      major,
-      "explicit-channel",
-      `explicit buildchain-channel=${channel}`,
-    );
-  }
-
-  const publishing = normalized(publishChannel || "none").toLowerCase();
-  if (publishing === "alpha") {
-    return selected("alpha", major, "publish-channel", "publish-channel=alpha");
-  }
-  if (STABLE_PUBLISH_CHANNELS.has(publishing)) {
-    return selected(
-      "stable",
-      major,
-      "publish-channel",
-      `publish-channel=${publishing}`,
-    );
-  }
-  if (publishing !== "none") {
-    throw new Error(
-      `custom publish-channel=${publishing} requires an explicit buildchain-channel`,
-    );
-  }
-
-  if (eventName === "release") {
-    if (normalized(releasePrerelease) === "") {
-      throw new Error(
-        "release events require github.event.release.prerelease to select a Buildchain channel",
-      );
-    }
-    const prerelease = parseBoolean(releasePrerelease, "releasePrerelease");
-    return selected(
-      prerelease ? "alpha" : "stable",
-      major,
-      "release-event",
-      prerelease ? "GitHub prerelease event" : "GitHub stable release event",
-    );
-  }
-
-  const ref = normalized(gitRef);
-  if (ref.startsWith("refs/tags/")) {
-    const tag = ref.match(SEMVER_TAG);
-    if (!tag) {
-      throw new Error(
-        `tag ${ref} is not a canonical semver release tag; set buildchain-channel explicitly`,
-      );
-    }
-    return selected(
-      tag[1] ? "alpha" : "stable",
-      major,
-      "semver-tag",
-      tag[1] ? `prerelease tag ${ref}` : `stable tag ${ref}`,
-    );
-  }
-
-  return selected(
-    "alpha",
-    major,
-    "development-default",
-    `non-release ${eventName || "unknown"} event`,
-  );
-}

package/packages/core/consumer/commands/buildchain-channel-router.mjs

@@ -1,81 +0,0 @@
-#!/usr/bin/env node
-
-import fs from "node:fs";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-
-import { resolveBuildchainChannel } from "../channel-selection.js";
-function readPackageVersion(cwd) {
-  try {
-    return JSON.parse(fs.readFileSync(path.join(cwd, "package.json"), "utf8")).version || "";
-  } catch {
-    return "";
-  }
-}
-
-function parseArgs(argv) {
-  const values = {};
-  for (let index = 0; index < argv.length; index += 1) {
-    const token = argv[index];
-    if (!token.startsWith("--")) throw new Error(`unexpected argument: ${token}`);
-    const key = token.slice(2);
-    const value = argv[index + 1];
-    if (value === undefined || value.startsWith("--")) throw new Error(`missing value for --${key}`);
-    values[key] = value;
-    index += 1;
-  }
-  return values;
-}
-
-function appendOutputs(file, result) {
-  const entries = {
-    channel: result.channel,
-    major: String(result.major),
-    "buildchain-ref": result.buildchainRef,
-    "runtime-override": String(result.runtimeOverride),
-    "selection-source": result.selectionSource,
-    reason: result.reason,
-  };
-  fs.appendFileSync(file, Object.entries(entries).map(([key, value]) => `${key}=${value}\n`).join(""));
-}
-
-function appendSummary(file, result) {
-  fs.appendFileSync(
-    file,
-    [
-      "## Buildchain channel router",
-      "",
-      `- selected channel: \`${result.channel}\``,
-      `- selected runtime ref: \`${result.buildchainRef}\``,
-      `- selection source: \`${result.selectionSource}\``,
-      `- reason: ${result.reason}`,
-      "",
-    ].join("\n"),
-  );
-}
-
-async function main() {
-  const args = parseArgs(process.argv.slice(2));
-  const cwd = path.resolve(args.cwd || process.cwd());
-  const result = resolveBuildchainChannel({
-    requestedChannel: args.channel,
-    requestedRef: args["buildchain-ref"],
-    publishChannel: args["publish-channel"],
-    eventName: args["event-name"],
-    gitRef: args.ref,
-    releasePrerelease: args["release-prerelease"],
-    routerRef: args["router-ref"],
-    packageVersion: readPackageVersion(cwd),
-  });
-  if (process.env.GITHUB_OUTPUT) appendOutputs(process.env.GITHUB_OUTPUT, result);
-  if (process.env.GITHUB_STEP_SUMMARY) appendSummary(process.env.GITHUB_STEP_SUMMARY, result);
-  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
-}
-
-const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
-if (isMain) {
-  main().catch((error) => {
-    console.error(`buildchain-channel-router: ${error.message}`);
-    process.exitCode = 1;
-  });
-}

package/packages/core/consumer/invocation-selector.js

@@ -1,4 +0,0 @@
-export const SOURCE_OWNED_PROMOTION = Object.freeze({
-  repository: "kungfu-systems/buildchain",
-  workflow: ".github/workflows/public-release-promote.yml",
-});