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

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

@@ -0,0 +1,144 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { getOctokit } from "@actions/github";
+import { installationRoot } from "../../runtime/installation-root.js";
+import { preparedRuntimeSelection } from "../../runtime/entry/selection.js";
+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 { githubPipelineSource } from "../../providers/github/pipeline-source.js";
+import { githubPipelineRuns } from "../../providers/github/pipeline-runs.js";
+import { githubPipelineWorker } from "../../providers/github/pipeline-worker.js";
+import { githubPipelinePolicy } from "../../providers/github/pipeline-policy.js";
+import { discussionMaterials } from "../../providers/github/discussions/materials.js";
+import { pipelineMaterials } from "./materials.js";
+import { GitHubClient } from "../../dev-delivery/admission/github-client.js";
+import { githubPipelineIntegration } from "../../providers/github/pipeline-integration.js";
+import { recordPipelineGroup } from "./group-control.js";
+import { controlPipelineChannel } from "./channel-control.js";
+import { qualifyPipelineChannelSource } from "./channel-source.js";
+import { settlePipeline } from "./settlement.js";
+import { pipelineProjection } from "./projection.js";
+import { resumePipelineNotifications } from "./notifications.js";
+import { projectPipelineStatus } from "./web-status.js";
+import { inspectRecoveryPublication } from "../../publication/pipeline/recovery-inspection.js";
+
+export function pipelineQueue({ queueToken, ...options }) {
+  const reader = new GitHubClient(options);
+  return {
+    getMergeQueueState: (branch) => reader.getMergeQueueState(branch),
+    enqueuePullRequest: async (input) => {
+      // GITHUB_TOKEN enqueue suppresses the merge_group workflow it requires.
+      if (!queueToken || queueToken === options.token)
+        throw new Error(
+          "Channel enqueue requires a distinct App or automation credential",
+        );
+      return new GitHubClient({
+        ...options,
+        token: queueToken,
+      }).enqueuePullRequest(input);
+    },
+  };
+}
+
+export async function pipelineHost(core, env, jobName) {
+  const token = core.getInput("token", { required: true });
+  const repository = env.GITHUB_REPOSITORY;
+  const selection = preparedRuntimeSelection(
+    JSON.parse(env.BUILDCHAIN_RUNTIME_SELECTION),
+  );
+  const runtimeRoot = installationRoot(import.meta.url);
+  const reader = fs.readFileSync(
+    path.join(runtimeRoot, "dist/readers/business-attempt.cjs"),
+  );
+  const runtime = {
+    repository: selection.repository,
+    sha: selection.sha,
+    readerDigest: `sha256:${createHash("sha256").update(reader).digest("hex")}`,
+  };
+  const request = githubJsonClient({ token, userAgent: "buildchain-pipeline" });
+  const github = getOctokit(token);
+  const provider = githubAttemptJournal(request);
+  const index = githubAttemptIndex(request, provider, repository);
+  const runs = githubPipelineRuns(request, repository);
+  const runId = Number(env.GITHUB_RUN_ID),
+    runAttempt = Number(env.GITHUB_RUN_ATTEMPT);
+  const writer = await runs.writer(runId, runAttempt, jobName);
+  const source = githubPipelineSource(request, repository);
+  const [owner, repo] = repository.split("/");
+  const archives = new Map();
+  function archive(session) {
+    if (!archives.has(session.intent.id))
+      archives.set(
+        session.intent.id,
+        discussionMaterials({
+          octokit: github,
+          repository,
+          intentId: session.intent.id,
+          // Storage is partitioned by verified provider job, not attempt authority.
+          // Journal references still select exact immutable asset IDs and digests.
+          partition: `${writer.runId}-${writer.runAttempt}-${writer.jobId}`,
+          authorityDescription:
+            "The canonical Buildchain intent Git journal owns transaction state.",
+        }),
+      );
+    return archives.get(session.intent.id);
+  }
+  const host = {
+    repository,
+    token,
+    github,
+    selection,
+    runtime,
+    runtimeRoot,
+    request,
+    provider,
+    index,
+    runs,
+    runId,
+    runAttempt,
+    writer,
+    source,
+    workers: githubPipelineWorker(request),
+    policy: githubPipelinePolicy(request, repository),
+    queue: pipelineQueue({
+      repository: { owner, repo },
+      token,
+      queueToken: core.getInput("queue-token"),
+    }),
+    integration: githubPipelineIntegration(request, repository, source, runs),
+    groupRecord: (context) => recordPipelineGroup(context, host),
+    channel: (session, admission, inputs) =>
+      controlPipelineChannel(session, admission, inputs, host),
+    qualifyChannel: (source, branch) =>
+      qualifyPipelineChannelSource(source, branch, host),
+    settle: (session, fresh, delivery) =>
+      settlePipeline(session, fresh, delivery, host),
+    project: (session) =>
+      projectPipelineStatus(session, {
+        project: pipelineProjection(github.graphql),
+        core,
+      }),
+    notifyTerminal: (session) => resumePipelineNotifications(session, host),
+    recoverPublication: (session, admitted) =>
+      inspectRecoveryPublication(session, admitted, host),
+    materialStore: (session) =>
+      pipelineMaterials(archive(session), {
+        repository,
+        attempt: session.observed.history.at(-1).identity,
+      }),
+    productArchive: archive,
+    wake: async (attempt) => {
+      await index.resolve(attempt);
+      await request(`/repos/${repository}/dispatches`, {
+        method: "POST",
+        body: {
+          event_type: "buildchain-attempt-wake",
+          client_payload: { attempt },
+        },
+      });
+    },
+  };
+  return host;
+}

package/packages/core/workflow/pipeline/integration-status.js

@@ -0,0 +1,113 @@
+import { recordDigest } from "../../release/discussion/envelope.js";
+
+// The landing job already owns statuses:write. Keep its exact admission alive
+// through the actual queue result so later channel PRs need not borrow the
+// temporary queue branch's Actions check suite.
+async function observeProtectedQueue(current, ports) {
+  const { repository, request, queue } = ports;
+  const now = ports.now || Date.now;
+  const pause =
+    ports.pause || ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const deadline = now() + 120 * 60 * 1000;
+  const number = current.intent.source.pullRequest;
+  const branch = current.intent.source.targetBranch;
+  let queueExitAt;
+  while (true) {
+    const pr = await request(`/repos/${repository}/pulls/${number}`);
+    if (
+      pr.head?.sha !== current.generation.source.commit ||
+      pr.head?.repo?.full_name !== repository ||
+      pr.base?.repo?.full_name !== repository ||
+      pr.base?.ref !== branch
+    )
+      throw new Error("Integrated status lost its exact admitted PR source");
+    if (pr.merged) return { pr, deadline, now, pause };
+    if (now() >= deadline)
+      throw new Error(
+        "Protected queue did not complete the admitted integration",
+      );
+    const pending = await queue(branch);
+    if (
+      pr.state !== "open" ||
+      !pending.enabled ||
+      !pending.entries.some(
+        (entry) =>
+          entry.pullRequestNumber === number &&
+          entry.pullRequestHeadSha === current.generation.source.commit,
+      )
+    ) {
+      // Queue removal can precede the PR endpoint's merged readback. Bound
+      // convergence without treating absence or a closed PR as merge evidence.
+      queueExitAt ??= now();
+      if (now() - queueExitAt >= 30_000)
+        throw new Error("Admitted PR left its protected merge queue");
+    } else queueExitAt = undefined;
+    await pause(10000);
+  }
+}
+
+async function observeIntegrationWorkflow(merged, ports) {
+  const { pr, deadline, now, pause } = merged;
+  if (!/^[0-9a-f]{40}$/u.test(pr.merge_commit_sha || ""))
+    throw new Error("Merged PR has no exact integration commit");
+  while (true) {
+    const result = await ports.request(
+      `/repos/${ports.repository}/actions/runs?event=merge_group&head_sha=${pr.merge_commit_sha}&per_page=100`,
+    );
+    if (!Array.isArray(result.workflow_runs) || result.total_count > 100)
+      throw new Error("Integration workflow inventory exceeds its bound");
+    const runs = result.workflow_runs.filter(
+      (run) =>
+        run.path?.split("@")[0] === ".github/workflows/buildchain.yml" &&
+        run.event === "merge_group" &&
+        run.head_sha === pr.merge_commit_sha,
+    );
+    if (
+      runs.some(
+        (run) => run.status === "completed" && run.conclusion === "success",
+      )
+    )
+      return;
+    if (!runs.some((run) => run.status !== "completed") || now() >= deadline)
+      throw new Error("Merged integration has no successful queue workflow");
+    await pause(10000);
+  }
+}
+
+function validateIntegratedStatus(proof, current, repository) {
+  const { root, ...body } = proof;
+  if (
+    recordDigest(body) !== root ||
+    proof.repository !== repository ||
+    proof.pullRequest !== current.intent.source.pullRequest ||
+    proof.sourceHead !== current.generation.source.commit ||
+    proof.branch !== current.intent.source.targetBranch ||
+    proof.build.source.commit !== proof.mergeCommit ||
+    proof.build.source.repository !== repository ||
+    proof.build.outcome !== "success" ||
+    proof.run.conclusion !== "success" ||
+    proof.run.status !== "completed" ||
+    proof.run.event !== "merge_group" ||
+    proof.run.head_sha !== proof.mergeCommit
+  )
+    throw new Error("Integrated status differs from its verified queue result");
+}
+
+export async function publishIntegratedPipelineStatus(current, ports) {
+  const merged = await observeProtectedQueue(current, ports);
+  await observeIntegrationWorkflow(merged, ports);
+  const { repository, integration, status } = ports;
+  const proof = await integration.observe(current);
+  validateIntegratedStatus(proof, current, repository);
+  const { root } = proof;
+  await status(`/repos/${repository}/statuses/${proof.mergeCommit}`, {
+    method: "POST",
+    body: {
+      context: "check",
+      state: "success",
+      description: `Qualified protected integration: ${root}`.slice(0, 140),
+      target_url: `https://github.com/${repository}/actions/runs/${proof.run.id}/attempts/${proof.run.run_attempt}`,
+    },
+  });
+  return proof;
+}

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

@@ -0,0 +1,58 @@
+import {
+  canonicalJson,
+  recordDigest,
+} from "../../release/discussion/envelope.js";
+import {
+  materialReference,
+  verifyMaterialBytes,
+} from "../attempt/materials.js";
+
+// Receipts are retained before the atomic journal references them. An interrupted
+// upload can leave unreferenced material; it cannot advance attempt authority.
+export function pipelineMaterials(archive, { repository, attempt }) {
+  async function retain(id, receipt, kind = "receipt") {
+    const bytes = Buffer.from(`${canonicalJson(receipt)}\n`);
+    const handle = await archive.put(bytes, {
+      name: `${id.replaceAll("/", "-")}.json`,
+      mediaType: "application/json",
+    });
+    const reference = materialReference(
+      {
+        id,
+        kind,
+        digest: handle.digest,
+        bytes: handle.size,
+        url: `https://api.github.com/repos/${repository}/releases/assets/${handle.id}`,
+        producerAttempt: attempt.id,
+        generation: attempt.generation,
+      },
+      attempt,
+      repository,
+    );
+    verifyMaterialBytes(reference, await archive.read(handle));
+    return reference;
+  }
+  async function read(reference) {
+    materialReference(reference, attempt, repository);
+    const prefix = `https://api.github.com/repos/${repository}/releases/assets/`;
+    if (!reference.url.startsWith(prefix))
+      throw new Error(
+        "Pipeline receipt is not in its retained material archive",
+      );
+    const id = reference.url.slice(prefix.length);
+    if (!/^[1-9][0-9]*$/u.test(id) || !Number.isSafeInteger(Number(id)))
+      throw new Error("Pipeline receipt asset identity is invalid");
+    const bytes = await archive.read({
+      id: Number(id),
+      size: reference.bytes,
+      digest: reference.digest,
+    });
+    verifyMaterialBytes(reference, bytes);
+    const receipt = JSON.parse(bytes.toString("utf8"));
+    // Normalize the supported JSON value domain, rejecting undefined or NaN
+    // from alternate injected archive implementations before returning it.
+    recordDigest(receipt);
+    return receipt;
+  }
+  return { retain, read };
+}

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

@@ -0,0 +1,36 @@
+import { wakePipelineCandidate } from "./wake.js";
+import { pipelineCandidate } from "./reconcile.js";
+import { notifyPipelineParent } from "./parent-notification.js";
+
+export async function resumePipelineNotifications(session, host) {
+  await notifyPipelineParent(session, host);
+  const observed = await session.journal.read();
+  const current = { ...observed.history.at(-1), intent: session.intent };
+  const terminal = Object.values(current.phases).filter((phase) =>
+    ["success", "cancelled", "failure"].includes(phase.payload.state),
+  );
+  for (const phase of terminal) {
+    for (const reference of phase.payload.materials.filter((material) =>
+      /^(?:merge\/settlement-|cancellation\/receipt-|failure\/)/u.test(
+        material.id,
+      ),
+    )) {
+      const receipt = await host.materialStore(session).read(reference);
+      const successor =
+        receipt.receipt?.successorWake ||
+        (Array.isArray(receipt.candidates)
+          ? pipelineCandidate(receipt, current)?.terminal?.successorWake
+          : null);
+      if (successor)
+        await wakePipelineCandidate(
+          successor,
+          {
+            repository: host.repository,
+            token: host.token,
+            branch: session.intent.source.targetBranch,
+          },
+          host,
+        );
+    }
+  }
+}

package/packages/core/workflow/pipeline/parent-notification.js

@@ -0,0 +1,27 @@
+import { readBusinessAttempt } from "../attempt/reader.js";
+
+export async function notifyPipelineParent(session, host) {
+  const pr = await host.request(
+    `/repos/${host.repository}/pulls/${session.intent.source.pullRequest}`,
+  );
+  if (!/^feature\/buildchain-next\/[0-9a-f]{64}$/u.test(pr.head?.ref || ""))
+    return;
+  const matches = [
+    ...String(pr.body || "").matchAll(
+      /^Buildchain-Parent-Attempt: (attempt-[0-9a-f]{64})$/gmu,
+    ),
+  ];
+  if (matches.length !== 1) return;
+  const attempt = matches[0][1];
+  const parent = await host.index.resolve(attempt);
+  const state = readBusinessAttempt(parent.snapshot);
+  if (
+    state.attempt !== attempt ||
+    state.status === "complete" ||
+    !state.intent.expectedNodes.includes("next-development")
+  )
+    return;
+  // The body is only a bounded wake selector. Current journal source and exact
+  // generated PR readback are re-admitted before any parent mutation.
+  await host.wake(attempt);
+}

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

@@ -0,0 +1,21 @@
+// Standard labels verified against GitHub's runner reference on 2026-09-13:
+// https://docs.github.com/en/actions/reference/runners/github-hosted-runners
+const RUNNERS = Object.freeze({
+  "linux-x64": "ubuntu-24.04",
+  "linux-arm64": "ubuntu-24.04-arm",
+  "macos-arm64": "macos-15",
+  "macos-x64": "macos-15-intel",
+  "windows-x64": "windows-2025",
+});
+
+export function pipelinePlatforms(plan) {
+  const platforms = [
+    ...new Set(plan.products.flatMap((product) => product.platforms)),
+  ].sort();
+  if (
+    !platforms.length ||
+    platforms.some((platform) => !Object.hasOwn(RUNNERS, platform))
+  )
+    throw new Error("Pipeline product platform has no admitted hosted runner");
+  return platforms.map((platform) => ({ platform, runner: RUNNERS[platform] }));
+}

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

@@ -0,0 +1,108 @@
+import { businessAttempt, sourceGeneration } from "../attempt/identity.js";
+import { attemptRecord } from "../attempt/records.js";
+import { canonicalJson } from "../../release/discussion/envelope.js";
+import { STOP_REQUESTED } from "./fence.js";
+
+export function pipelineProgress(journal, { intent, writer, runtime }) {
+  async function open(source, baseCommit, { successor = false } = {}) {
+    const observed = await journal.read();
+    const generation = sourceGeneration(intent, source, baseCommit);
+    if (observed.attempt && observed.generation === generation.id && !successor)
+      return observed;
+    if (
+      observed.attempt &&
+      !["cancelled", "superseded", "failure", "complete"].includes(
+        observed.status,
+      )
+    )
+      throw new Error(
+        "Prior attempt must reach terminal state before its successor opens",
+      );
+    const attempt = businessAttempt({
+      intent,
+      generation,
+      predecessor: observed.attempt || "",
+      requestKey: `source:${generation.id}`,
+    });
+    const root = attemptRecord({
+      intent,
+      attempt,
+      generation,
+      writer,
+      runtime,
+      eventKey: `open:${attempt.id}`,
+      phase: "attempt",
+      state: "running",
+    });
+    return journal.append(root, observed.head || "");
+  }
+  async function progress({
+    attempt,
+    phase,
+    state,
+    eventKey,
+    reason = "",
+    materials = [],
+    expectedHead,
+  }) {
+    const observed = await journal.read();
+    if (observed.attempt !== attempt)
+      throw new Error("Late pipeline result belongs to a superseded attempt");
+    if (expectedHead !== undefined && observed.head !== expectedHead)
+      throw new Error(
+        "Pipeline scheduling head changed; reobserve the active execution",
+      );
+    const current = observed.history.at(-1);
+    if (
+      state === "success" &&
+      observed.phases[phase]?.payload.reason.startsWith(STOP_REQUESTED)
+    )
+      throw new Error("A stopped pipeline phase cannot report success");
+    const duplicate = current.events.find(
+      (event) => event.payload.eventKey === eventKey,
+    );
+    if (duplicate) {
+      if (
+        duplicate.node !== phase ||
+        duplicate.payload.state !== state ||
+        duplicate.payload.reason !== reason ||
+        canonicalJson(duplicate.payload.materials) !== canonicalJson(materials)
+      )
+        throw new Error("Duplicate pipeline event changed its meaning");
+      return observed;
+    }
+    const record = attemptRecord({
+      intent,
+      attempt: current.identity,
+      generation: current.generation,
+      writer,
+      runtime,
+      previous: current.events.at(-1),
+      eventKey,
+      phase,
+      state,
+      reason,
+      materials,
+    });
+    return journal.append(record, observed.head);
+  }
+  async function requestStop(reason) {
+    const observed = await journal.read();
+    if (
+      !observed.attempt ||
+      ["complete", "cancelled", "failure", "superseded"].includes(
+        observed.status,
+      )
+    )
+      return observed;
+    const phase = observed.missing[0];
+    return progress({
+      attempt: observed.attempt,
+      phase,
+      state: "waiting",
+      eventKey: `stop:${observed.attempt}:${reason}`,
+      reason: `${STOP_REQUESTED}${reason}`,
+    });
+  }
+  return { open, progress, requestStop };
+}

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

@@ -0,0 +1,20 @@
+import { releaseDiscussionStore } from "../../release/discussion/store.js";
+import { discussionTransport } from "../../providers/github/discussions/transport.js";
+
+// Copy committed journal records into their Discussion for human navigation.
+// A lagging, unavailable or duplicated projection never supplies write authority.
+export function pipelineProjection(
+  graphql,
+  transport = discussionTransport(graphql),
+) {
+  const store = releaseDiscussionStore(transport);
+  return async (session) => {
+    const observed = await session.journal.read();
+    const target = await store.initialize({ intent: session.intent });
+    const prior = await store.read(target);
+    const known = new Set(prior.records.map((record) => record.id));
+    for (const record of observed.snapshot.records)
+      if (!known.has(record.id)) await store.append(target, record);
+    return { url: target.discussion.url, journalHead: observed.head };
+  };
+}