@kungfu-tech/buildchain 4.1.3-alpha.0 → 4.1.3-alpha.10

package/packages/core/workflow/pipeline/delivery-request.js

@@ -0,0 +1,198 @@
+import { execFileSync } from "node:child_process";
+import { recordDigest } from "../../release/discussion/envelope.js";
+import { sourceQualificationPredicates } from "../../dev-delivery/source-proof/predicates.js";
+import { createNativeCommandContract } from "../../dev-delivery/dev-delivery-warrant.js";
+import { withPipelineSourceObjects } from "../../providers/github/pipeline-checkout.js";
+import { pipelinePlatforms } from "./platforms.js";
+import { pipelineCandidateRoot } from "./reconcile.js";
+import { consumerWorkflows } from "../../consumer/contract/entries.js";
+import { pipelineRunEntry } from "../../providers/github/pipeline-run-entry.js";
+import {
+  PIPELINE_BUILD_QUALIFICATION,
+  qualifyPipelineBuild,
+} from "./build-qualification.js";
+
+const quote = (value) => `'${value.replaceAll("'", "'\\''")}'`;
+
+export function qualifyPipelineSourceRun(run, current, build) {
+  const source = current.generation.source;
+  const pull = run.pull_requests?.find(
+    (pr) => pr.number === current.intent.source.pullRequest,
+  );
+  if (
+    !Number.isSafeInteger(run.id) ||
+    run.id < 1 ||
+    run.status !== "completed" ||
+    run.conclusion !== "success" ||
+    ![
+      "pull_request",
+      "repository_dispatch",
+      "pull_request_review",
+      "workflow_dispatch",
+    ].includes(run.event) ||
+    run.repository?.full_name !== current.intent.repository ||
+    (run.event === "pull_request" && run.head_sha !== source.commit) ||
+    (run.event === "pull_request" &&
+      pull?.base?.sha !== current.generation.baseCommit)
+  )
+    throw new Error(
+      "Pipeline source run does not qualify the exact PR generation",
+    );
+  if (build?.schema === PIPELINE_BUILD_QUALIFICATION) {
+    const verified = qualifyPipelineBuild({ ...build, source });
+    if (
+      recordDigest(verified) !== recordDigest(build) ||
+      build.runId !== run.id ||
+      build.runAttempt !== run.run_attempt ||
+      build.outcome !== "success"
+    )
+      throw new Error(
+        "Recovered source run does not bind complete independently qualified product segments",
+      );
+  } else if (run.event !== "pull_request") {
+    const { root, ...body } = build || {};
+    if (
+      root !== recordDigest(body) ||
+      body.schema !== "buildchain.pipeline-build-readback/v1" ||
+      body.runId !== run.id ||
+      body.runAttempt !== run.run_attempt ||
+      body.outcome !== "success" ||
+      recordDigest(body.source) !== recordDigest(source)
+    )
+      throw new Error(
+        "Attempt wake requires retained exact product build provider readback",
+      );
+  }
+  pipelineEntry(run);
+  return run;
+}
+
+function pipelineEntry(run) {
+  return pipelineRunEntry(run).channel;
+}
+
+function predicateInput(directory, current, run) {
+  const source = current.generation.source;
+  for (const [file, expected] of Object.entries(
+    consumerWorkflows(pipelineEntry(run), source.configPath),
+  )) {
+    const bytes = execFileSync(
+      "git",
+      ["-C", directory, "show", `${source.commit}:${file}`],
+      { encoding: "utf8", maxBuffer: 1024 * 1024 },
+    );
+    if (bytes !== expected)
+      throw new Error(
+        "Qualified source changed the minimal consumer workflow contract",
+      );
+  }
+  const paths = execFileSync(
+    "git",
+    ["-C", directory, "ls-tree", "-r", "--name-only", "-z", source.commit],
+    { maxBuffer: 32 * 1024 * 1024 },
+  )
+    .toString("utf8")
+    .split("\0")
+    .filter(Boolean)
+    .sort();
+  if (
+    !paths.length ||
+    paths.length > 50_000 ||
+    paths.some((file) => /[\r\n]/u.test(file))
+  )
+    throw new Error(
+      "Pipeline source inventory exceeds its qualification contract",
+    );
+  const policyPaths = paths.filter(
+    (file) =>
+      file === source.configPath || file.startsWith(".github/workflows/"),
+  );
+  const dependencies = paths.filter((file) =>
+    /(?:^|\/)(?:package(?:-lock)?\.json|pnpm-lock\.yaml|yarn\.lock|Cargo\.(?:toml|lock)|go\.(?:mod|sum))$/u.test(
+      file,
+    ),
+  );
+  return {
+    cwd: directory,
+    repository: current.intent.repository,
+    protectedBase: current.intent.source.targetBranch,
+    sourceHead: source.commit,
+    qualifiedBase: current.generation.baseCommit,
+    nodeVersion: "24",
+    workingDirectory: ".",
+    policyPaths: JSON.stringify(policyPaths),
+    closurePaths: JSON.stringify(paths),
+    dependencyPaths: JSON.stringify(
+      dependencies.length ? dependencies : policyPaths,
+    ),
+    requiredContexts: JSON.stringify(["check"]),
+  };
+}
+
+export async function preparePipelineDelivery(
+  { current, run, build, runtimeSha, token, plan },
+  withObjects = withPipelineSourceObjects,
+) {
+  qualifyPipelineSourceRun(run, current, build);
+  if (!/^[0-9a-f]{40}$/u.test(runtimeSha || ""))
+    throw new Error("Pipeline delivery requires the prepared exact runtime");
+  const source = current.generation.source;
+  const platforms = plan
+    ? pipelinePlatforms(plan).map((entry) => entry.platform)
+    : ["linux-x64"];
+  const nativePlatform = platforms.includes("linux-x64")
+    ? "linux-x64"
+    : platforms[0];
+  const predicates = await withObjects(
+    {
+      repository: current.intent.repository,
+      sourceHead: source.commit,
+      baseCommit: current.generation.baseCommit,
+      token,
+    },
+    (directory) =>
+      sourceQualificationPredicates(predicateInput(directory, current, run)),
+  );
+  // Native composition owns .buildchain/candidate beside the prepared runtime.
+  // Do not bind one job's absolute workspace path into another runner's command.
+  const nativeCommand = `node ../runtime/packages/core/workflow/commands/pipeline-build.mjs --platform ${nativePlatform} --config-path ${quote(source.configPath)}`;
+  const environmentRoot = recordDigest({
+    schema: "buildchain.pipeline-native-environment/v1",
+    runtimeSha,
+    node: "24",
+    platform: nativePlatform,
+    sourceContract: source.contract,
+  });
+  return {
+    "target-branch": current.intent.source.targetBranch,
+    "expected-pr-number": current.intent.source.pullRequest,
+    "expected-head-sha": source.commit,
+    "source-workflow-run-id": run.id,
+    "pipeline-attempt": current.identity.id,
+    "delivery-warrant-mode": "required",
+    "delivery-class": "native-proof-required",
+    "source-root": pipelineCandidateRoot(current),
+    "source-identity-root": predicates.sourceIdentityRoot,
+    "source-patch-root": predicates.sourcePatchRoot,
+    "plan-root": predicates.planRoot,
+    "closure-root": predicates.closureRoot,
+    "dependency-root": predicates.dependencyRoot,
+    "toolchain-root": predicates.toolchainRoot,
+    "environment-root": environmentRoot,
+    "native-command": nativeCommand,
+    "native-platform": nativePlatform,
+    "native-command-root":
+      createNativeCommandContract(nativeCommand).commandRoot,
+    "affected-paths-json": JSON.stringify(predicates.affectedPaths),
+    "shard-evidence-roots-json": "[]",
+    "required-status-checks": "check",
+    "ready-label": "ready",
+    "landing-mode": "queue",
+    "queue-admission-context": "Queue admission lease",
+    "active-lease-context": "Queue family lease/exact",
+    "require-approval": true,
+    "same-repository-only": true,
+    "max-merges": 1,
+    "dry-run": false,
+  };
+}

package/packages/core/workflow/pipeline/events.js

@@ -0,0 +1,84 @@
+import { admitEvent } from "../../consumer/contract/entries.js";
+
+const SHA = /^[0-9a-f]{40}$/u;
+function prNumber(value) {
+  if (!Number.isSafeInteger(value) || value < 1)
+    throw new Error("Pipeline event requires an exact PR number");
+  return value;
+}
+
+// Webhook payloads select readback work only. They never carry source, approval,
+// Warrant or mutation authority. Live provider state owns every decision.
+export function pipelineEvent(name, event, repository) {
+  admitEvent(name, event.action || "");
+  if (event.repository?.full_name !== repository)
+    throw new Error("Pipeline event repository mismatch");
+  if (
+    ["pull_request", "pull_request_target", "pull_request_review"].includes(
+      name,
+    )
+  )
+    return {
+      kind: "pull-request",
+      pullRequest: prNumber(event.pull_request?.number),
+      terminalOnly: name === "pull_request_target",
+    };
+  if (name === "repository_dispatch") {
+    const payload = event.client_payload;
+    if (
+      !payload ||
+      Object.keys(payload).length !== 1 ||
+      !/^attempt-[0-9a-f]{64}$/u.test(payload.attempt || "")
+    )
+      throw new Error("Attempt wake requires only its exact business selector");
+    return { kind: "attempt", attempt: payload.attempt, terminalOnly: false };
+  }
+  if (name === "merge_group") {
+    const group = event.merge_group;
+    if (
+      !SHA.test(group?.head_sha || "") ||
+      !SHA.test(group?.base_sha || "") ||
+      !group.base_ref?.startsWith("refs/heads/")
+    )
+      throw new Error("Merge group requires exact provider coordinates");
+    return {
+      kind: "merge-group",
+      commit: group.head_sha,
+      baseCommit: group.base_sha,
+      branch: group.base_ref.slice(11),
+      terminalOnly: false,
+    };
+  }
+  if (!event.ref?.startsWith("refs/heads/") || event.deleted === true)
+    return { kind: "ignore", reason: "not-a-live-branch" };
+  if (!SHA.test(event.after || ""))
+    throw new Error("Branch event requires an exact commit");
+  // Internal journal and lock writes must not recursively wake the pipeline.
+  const branch = event.ref.slice(11);
+  return /^(?:dev|alpha|release|publish-gate)\//u.test(branch)
+    ? { kind: "branch", branch, commit: event.after, terminalOnly: false }
+    : { kind: "ignore", reason: "not-a-channel-branch" };
+}
+
+function matches(pattern, branch) {
+  const escaped = pattern
+    .split("*")
+    .map((part) => part.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&"))
+    .join(".*");
+  return new RegExp(`^${escaped}$`, "u").test(branch);
+}
+
+export function channelRoute(plan, pullRequest, repository) {
+  if (
+    pullRequest.base?.repo?.full_name !== repository ||
+    pullRequest.head?.repo?.full_name !== repository
+  )
+    throw new Error("Pipeline delivery requires a repository-owned channel PR");
+  const routes = plan.channels.filter(
+    (channel) =>
+      channel.to === pullRequest.base.ref &&
+      matches(channel.from, pullRequest.head.ref),
+  );
+  if (routes.length > 1) throw new Error("Ambiguous protected channel route");
+  return routes[0] || null;
+}

package/packages/core/workflow/pipeline/fence.js

@@ -0,0 +1,42 @@
+import { recordDigest } from "../../release/discussion/envelope.js";
+
+export const STOP_REQUESTED = "pipeline-stop-requested:";
+
+// Credentialed controllers observe this source/attempt fence before Warrant
+// renewal and finalization. The isolated native job receives no read token.
+// Stopping renewal does not release its Warrant: provider-terminal native/seal
+// evidence is still required before a separate controller can transfer ownership.
+export function assertPipelineExecution(observed, expected) {
+  if (
+    observed.attempt !== expected.attempt ||
+    observed.generation !== expected.generation ||
+    observed.intent.id !== expected.intent
+  )
+    throw new Error("Pipeline execution lost its current attempt fence");
+  const current = observed.history.at(-1);
+  if (
+    !current ||
+    recordDigest(current.generation.source) !== expected.sourceRoot
+  )
+    throw new Error("Pipeline execution source fence changed");
+  if (
+    ["cancelled", "superseded", "failure", "complete"].includes(
+      observed.status,
+    ) ||
+    Object.values(observed.phases).some((record) =>
+      record.payload.reason.startsWith(STOP_REQUESTED),
+    )
+  )
+    throw new Error("Pipeline execution has a terminal or requested stop");
+  return true;
+}
+
+export function pipelineHeartbeat(journal, expected, warrantHeartbeat) {
+  return async () => {
+    assertPipelineExecution(await journal.read(), expected);
+    await warrantHeartbeat();
+    // Catch cancellation that raced the provider heartbeat without granting
+    // another controller interval from the stale pre-heartbeat read.
+    assertPipelineExecution(await journal.read(), expected);
+  };
+}

package/packages/core/workflow/pipeline/group-control.js

@@ -0,0 +1,59 @@
+import { recordDigest } from "../../release/discussion/envelope.js";
+import { object } from "../../consumer/contract/shape.js";
+
+export async function recordPipelineGroup(context, host) {
+  object(context, [
+    "schema",
+    "source",
+    "branch",
+    "baseCommit",
+    "runId",
+    "runAttempt",
+    "platforms",
+  ]);
+  if (
+    context.schema !== "buildchain.pipeline-group-build-context/v1" ||
+    context.runId !== host.runId ||
+    context.runAttempt !== host.runAttempt
+  )
+    throw new Error("Merge group callback execution drift");
+  const { run } = await host.runs.read(context.runId, context.runAttempt);
+  if (run.event !== "merge_group" || run.head_sha !== context.source.commit)
+    throw new Error("Merge group build is not the exact provider execution");
+  const queue = await host.queue.getMergeQueueState(context.branch);
+  if (
+    !queue.enabled ||
+    !queue.entries.some(
+      (entry) =>
+        entry.headSha === context.source.commit &&
+        entry.baseSha === context.baseCommit,
+    )
+  )
+    throw new Error("Merge group was removed or changed before verification");
+  const readback = await host.runs.build(
+    context.runId,
+    context.runAttempt,
+    context.source,
+    context.platforms.map((platform) => platform.platform),
+  );
+  if (readback.outcome === "success")
+    await host.qualifyChannel(context.source, context.branch);
+  await host.publishBuildStatus?.(context, readback);
+  await host.request(`/repos/${host.repository}/check-runs`, {
+    method: "POST",
+    body: {
+      name: "check",
+      head_sha: context.source.commit,
+      external_id: `buildchain:merge-group:${recordDigest(context)}`,
+      status: "completed",
+      conclusion: readback.outcome,
+      output: {
+        title: "Buildchain exact merge-group verification",
+        summary: `Provider product jobs: ${readback.root}`,
+      },
+    },
+  });
+  if (readback.outcome !== "success")
+    throw new Error("Merge-group products failed verification");
+  return readback;
+}

package/packages/core/workflow/pipeline/guard-build.js

@@ -0,0 +1,74 @@
+import { githubPipelineRuns } from "../../providers/github/pipeline-runs.js";
+import { readPipelineCaller } from "../../providers/github/pipeline-run-entry.js";
+import { pipelineBuildEvidence } from "./build-evidence.js";
+import { qualifyPipelineSourceRun } from "./delivery-request.js";
+
+export async function guardPipelineBuild(
+  input,
+  observed,
+  {
+    material,
+    source,
+    request,
+    repository,
+    runs = githubPipelineRuns(request, repository),
+  },
+) {
+  const session = { observed, journal: { read: async () => observed } };
+  const build = await pipelineBuildEvidence(session, {
+    runId: 0,
+    runs,
+    source,
+    materialStore: () => material,
+  });
+  if (!build || build.run.id !== Number(input["source-workflow-run-id"]))
+    throw new Error(
+      "Delivery requires its independently qualified exact product build",
+    );
+  const current = { ...observed.history.at(-1), intent: observed.intent };
+  qualifyPipelineSourceRun(build.run, current, build.readback);
+  await readPipelineCaller(
+    build.run,
+    current.generation.source.configPath,
+    request,
+    repository,
+  );
+  return build;
+}
+
+// A commit status is source-bound and survives later workflow suites. Publish
+// only the independently reread build at the protected landing boundary, whose
+// existing Actions credential owns statuses:write. Retained build receipts
+// preserve the original executions and their outcomes.
+export async function publishPipelineBuildStatus(
+  input,
+  build,
+  request,
+  repository,
+) {
+  if (
+    build.readback.source.repository !== repository ||
+    build.readback.source.commit !== input["expected-head-sha"] ||
+    build.sourceHead !== input["expected-head-sha"] ||
+    build.run.id !== Number(input["source-workflow-run-id"]) ||
+    build.readback.runId !== build.run.id ||
+    build.readback.runAttempt !== build.run.run_attempt ||
+    build.outcome !== "success" ||
+    build.readback.outcome !== "success"
+  )
+    throw new Error(
+      "Landing status differs from its qualified exact-source build",
+    );
+  return request(`/repos/${repository}/statuses/${build.sourceHead}`, {
+    method: "POST",
+    body: {
+      context: "check",
+      state: "success",
+      description: `Qualified product build: ${build.readback.root}`.slice(
+        0,
+        140,
+      ),
+      target_url: `https://github.com/${repository}/actions/runs/${build.run.id}/attempts/${build.run.run_attempt}`,
+    },
+  });
+}

package/packages/core/workflow/pipeline/guard.js

@@ -0,0 +1,158 @@
+import { githubJsonClient } from "../../providers/github/json-client.js";
+import { githubAttemptJournal } from "../../providers/github/attempt-journal.js";
+import { githubAttemptIndex } from "../../providers/github/attempt-index.js";
+import { readBusinessAttempt } from "../attempt/reader.js";
+import { assertPipelineExecution } from "./fence.js";
+import { recordDigest } from "../../release/discussion/envelope.js";
+import { githubPipelineSource } from "../../providers/github/pipeline-source.js";
+import { githubPipelinePolicy } from "../../providers/github/pipeline-policy.js";
+import { getOctokit } from "@actions/github";
+import { discussionMaterials } from "../../providers/github/discussions/materials.js";
+import { pipelineMaterials } from "./materials.js";
+import { guardPipelineBuild } from "./guard-build.js";
+
+async function assertRetainedRequest(input, connection, observed) {
+  const current = observed.history.at(-1);
+  const event = [...current.events]
+    .reverse()
+    .find((entry) =>
+      entry.payload.materials.some((material) =>
+        material.id.startsWith("delivery/execution-"),
+      ),
+    );
+  const reference = event?.payload.materials.find((material) =>
+    material.id.startsWith("delivery/execution-"),
+  );
+  if (!reference)
+    throw new Error("Pipeline delivery has no admitted execution request");
+  const archive = discussionMaterials({
+    octokit: getOctokit(connection.token),
+    repository: connection.repository,
+    intentId: observed.intent.id,
+  });
+  const material = pipelineMaterials(archive, {
+    repository: connection.repository,
+    attempt: current.identity,
+  });
+  const execution = await material.read(reference);
+  validatePipelineExecutionRequest(execution, input, observed, {
+    runId: Number(process.env.GITHUB_RUN_ID),
+    runAttempt: Number(process.env.GITHUB_RUN_ATTEMPT),
+  });
+  return material;
+}
+
+export function validatePipelineExecutionRequest(
+  execution,
+  input,
+  observed,
+  coordinates,
+) {
+  if (execution.schema !== "buildchain.pipeline-delivery-execution/v1")
+    throw new Error("Pipeline delivery request schema is unsupported");
+  if (
+    execution.attempt !== observed.attempt ||
+    execution.generation !== observed.generation ||
+    execution.runId !== coordinates.runId ||
+    execution.runAttempt !== coordinates.runAttempt
+  )
+    throw new Error(
+      "Pipeline delivery is not the exact admitted provider execution",
+    );
+  for (const [key, value] of Object.entries(execution.request))
+    if (
+      !Object.hasOwn(input, key) ||
+      recordDigest(input[key]) !== recordDigest(value)
+    )
+      throw new Error(
+        `Pipeline delivery changed its retained request field: ${key}`,
+      );
+}
+
+export async function guardPipelineAdmission(input, connection) {
+  const observed = await guardPipelineDelivery(input, connection);
+  if (!observed) return null;
+  const material = await assertRetainedRequest(input, connection, observed);
+  const request = githubJsonClient({
+    token: connection.token,
+    userAgent: "buildchain-pipeline-admission",
+  });
+  const current = { ...observed.history.at(-1), intent: observed.intent };
+  const source = githubPipelineSource(request, connection.repository);
+  const admission = await source.observeIntent(
+    observed.intent,
+    current.generation,
+    { "config-path": current.generation.source.configPath },
+  );
+  const { live } = admission;
+  if (
+    admission.cleanupOnly ||
+    !live.source ||
+    live.state !== "open" ||
+    live.draft ||
+    !live.ready ||
+    live.baseCommit !== current.generation.baseCommit ||
+    recordDigest(live.source) !== recordDigest(current.generation.source)
+  )
+    throw new Error(
+      "Pipeline source is no longer admitted for a delivery effect",
+    );
+  const policy = await githubPipelinePolicy(
+    request,
+    connection.repository,
+  ).observe(current, admission.protectedPlan.review);
+  if (!policy.review || !policy.checksPassing)
+    throw new Error(
+      "Pipeline protected review or required checks changed before delivery effect",
+    );
+  const build = await guardPipelineBuild(input, observed, {
+    material,
+    source,
+    request,
+    repository: connection.repository,
+  });
+  const fresh = await guardPipelineDelivery(input, connection);
+  await connection.publishBuildStatus?.(build);
+  return fresh;
+}
+
+export async function guardPipelineDelivery(input, connection, lookup) {
+  const attempt = input["pipeline-attempt"];
+  // Existing advanced delivery callers retain their domain authority. The new
+  // normal entry always supplies its internally selected business attempt.
+  if (!attempt) return null;
+  if (!connection.token)
+    throw new Error("Pipeline controller requires its scoped read credential");
+  const request = githubJsonClient({
+    token: connection.token,
+    userAgent: "buildchain-pipeline",
+  });
+  const index =
+    lookup ||
+    githubAttemptIndex(
+      request,
+      githubAttemptJournal(request),
+      connection.repository,
+    );
+  const loaded = await index.resolve(attempt);
+  const observed = readBusinessAttempt(loaded.snapshot);
+  const current = observed.history.at(-1);
+  if (
+    !current ||
+    observed.intent.repository !== connection.repository ||
+    observed.intent.source.targetBranch !== input["target-branch"] ||
+    observed.intent.source.pullRequest !==
+      Number(input["expected-pr-number"]) ||
+    current.generation.source.commit !== input["expected-head-sha"]
+  )
+    throw new Error(
+      "Pipeline delivery request changed its admitted source intent",
+    );
+  assertPipelineExecution(observed, {
+    attempt,
+    intent: observed.intent.id,
+    generation: current.generation.id,
+    sourceRoot: recordDigest(current.generation.source),
+  });
+  return observed;
+}