@kungfu-tech/buildchain 4.1.3-alpha.1 → 4.1.3-alpha.3

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

@@ -0,0 +1,114 @@
+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 { 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 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 host = {
+    repository,
+    token,
+    github,
+    selection,
+    runtime,
+    runtimeRoot,
+    request,
+    provider,
+    index,
+    runs,
+    runId,
+    runAttempt,
+    writer,
+    source,
+    workers: githubPipelineWorker(request),
+    policy: githubPipelinePolicy(request, repository),
+    queue: new GitHubClient({ repository: { owner, repo }, token }),
+    integration: githubPipelineIntegration(request, repository, source, runs),
+    groupRecord: (context) => recordPipelineGroup(context, host),
+    channel: (session, admission, inputs) =>
+      controlPipelineChannel(session, admission, inputs, 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(
+        discussionMaterials({
+          octokit: github,
+          repository,
+          intentId: session.intent.id,
+          authorityDescription:
+            "The canonical Buildchain intent Git journal owns transaction state.",
+        }),
+        { repository, attempt: session.observed.history.at(-1).identity },
+      ),
+    productArchive: (session) =>
+      discussionMaterials({
+        octokit: github,
+        repository,
+        intentId: session.intent.id,
+        authorityDescription:
+          "The canonical Buildchain intent Git journal owns transaction state.",
+      }),
+    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/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 };
+  };
+}

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

@@ -0,0 +1,194 @@
+import { recordDigest } from "../../release/discussion/envelope.js";
+
+const TERMINAL = new Set([
+  "merged",
+  "terminal-failure",
+  "dequeued",
+  "cancelled",
+]);
+const wait = (reason) => ({ operation: "wait", reason });
+
+export function terminalPipelineCandidate(candidate) {
+  return Boolean(candidate && TERMINAL.has(candidate.status));
+}
+
+export function pipelineCandidateRoot(current) {
+  if (
+    !current.identity?.id ||
+    current.identity.generation !== current.generation.id
+  )
+    throw new Error(
+      "Pipeline candidate requires its exact business attempt identity",
+    );
+  return recordDigest({
+    schema: "buildchain.pipeline-candidate-source/v1",
+    intent: current.intent,
+    attempt: current.identity,
+    generation: current.generation,
+  });
+}
+
+export function pipelineCandidate(queue, current) {
+  const source = current.generation.source;
+  const number = current.intent.source.pullRequest;
+  const matches = queue.candidates.filter(
+    (candidate) =>
+      candidate.pullRequestNumber === number &&
+      candidate.sourceHead === source.commit &&
+      candidate.sourceRoot === pipelineCandidateRoot(current),
+  );
+  const active = matches.find(
+    (candidate) => candidate.candidateId === queue.activeWarrant?.candidateId,
+  );
+  return active || matches.at(-1) || null;
+}
+
+function cancellation({
+  candidate,
+  queue,
+  worker,
+  reason,
+  observedSourceHead,
+}) {
+  if (candidate && ["cancelled", "dequeued"].includes(candidate.status))
+    return {
+      operation: "record-cancellation",
+      reason,
+      candidateId: candidate.candidateId,
+    };
+  if (!candidate || TERMINAL.has(candidate.status))
+    return { operation: "supersede", reason };
+  if (candidate.candidateId !== queue.activeWarrant?.candidateId) {
+    if (candidate.status !== "queued") return wait("unfenced-candidate-state");
+    return {
+      operation: "cancel-queued",
+      reason,
+      candidateId: candidate.candidateId,
+      expectedSourceHead: candidate.sourceHead,
+      observedSourceHead,
+    };
+  }
+  // Expiration is not evidence that the old native worker stopped. Never
+  // release or transfer an active Warrant until the provider proves terminality.
+  if (!worker || worker.status !== "completed")
+    return {
+      operation: "stop-worker",
+      reason: "active-worker-not-terminal",
+      candidateId: candidate.candidateId,
+    };
+  return {
+    operation: "settle-cancelled",
+    reason,
+    candidateId: candidate.candidateId,
+  };
+}
+
+function sameSource(current, live) {
+  if (!live.source) return false;
+  return recordDigest(current.generation.source) === recordDigest(live.source);
+}
+
+function mergedDelivery(candidate, live, evidence) {
+  if (!candidate) return wait("merged-candidate-authority-required");
+  if (
+    !evidence.integration ||
+    evidence.integration.sourceHead !== live.source.commit
+  )
+    return wait("exact-protected-integration-proof-required");
+  if (candidate.status !== "merged")
+    return { operation: "settle-merged", reason: "protected-merge-observed" };
+  if (
+    !evidence.settlement ||
+    evidence.settlement.candidateId !== candidate.candidateId
+  )
+    return wait("terminal-settlement-readback-required");
+  return { operation: "wake-publication", reason: "delivery-terminal" };
+}
+
+// This pure planner selects the next domain transaction. Its booleans are
+// authenticated provider readbacks at the adapter boundary, never workflow inputs.
+// A selected operation is not a receipt or permission to skip that domain's gates.
+export function reconcilePipeline({ current, live, queue, worker, evidence }) {
+  if (
+    queue.repository !== current.intent.repository ||
+    queue.protectedBase !== current.intent.source.targetBranch ||
+    live.pullRequest !== current.intent.source.pullRequest
+  )
+    throw new Error("Pipeline observation belongs to another intent");
+  const candidate = pipelineCandidate(queue, current);
+  const cancellationInput = {
+    candidate,
+    queue,
+    worker,
+    observedSourceHead: live.observedHead || live.source?.commit,
+  };
+  if (live.state === "closed" && !live.merged)
+    return cancellation({
+      ...cancellationInput,
+      reason: "pull-request-closed",
+    });
+  if (
+    live.targetBranch &&
+    live.targetBranch !== current.intent.source.targetBranch
+  )
+    return cancellation({
+      ...cancellationInput,
+      reason: "target-branch-changed",
+    });
+  if (live.routeEnabled === false)
+    return cancellation({
+      ...cancellationInput,
+      reason: "channel-policy-changed",
+    });
+  if (!sameSource(current, live))
+    return cancellation({
+      ...cancellationInput,
+      reason: "source-generation-changed",
+    });
+  if (live.merged) return mergedDelivery(candidate, live, evidence);
+  if (current.generation.baseCommit !== live.baseCommit)
+    return cancellation({
+      ...cancellationInput,
+      reason: "protected-base-advanced",
+    });
+  if (live.dequeued === true)
+    return cancellation({
+      ...cancellationInput,
+      reason: "pull-request-dequeued",
+    });
+  return openDelivery({ candidate, live, queue, worker, evidence });
+}
+
+function openDelivery({ candidate, live, queue, worker, evidence }) {
+  if (live.state !== "open") return wait("unknown-provider-state");
+  if (live.terminalOnly) return wait("terminal-event-cannot-start-execution");
+  if (candidate && TERMINAL.has(candidate.status))
+    return wait("successor-attempt-required");
+  if (!evidence.build)
+    return { operation: "build", reason: "source-needs-qualification" };
+  if (evidence.build.sourceHead !== live.source.commit)
+    throw new Error("Build evidence belongs to another source");
+  if (evidence.build.outcome !== "success") {
+    if (candidate && candidate.candidateId === queue.activeWarrant?.candidateId)
+      return worker?.status === "completed"
+        ? { operation: "settle-failure", reason: "native-execution-failed" }
+        : { operation: "stop-worker", reason: "failed-worker-not-terminal" };
+    return wait("build-failed");
+  }
+  if (!live.ready || live.draft) return wait("ready-review-required");
+  if (!evidence.review) return wait("independent-protected-review-required");
+  if (!evidence.checks) return wait("exact-required-checks-pending");
+  if (!candidate) return { operation: "reserve", reason: "source-admitted" };
+  if (candidate.candidateId !== queue.activeWarrant?.candidateId)
+    return queue.activeWarrant
+      ? wait("another-candidate-active")
+      : { operation: "select", reason: "candidate-queued" };
+  if (queue.activeWarrant.phase === "provisional")
+    return {
+      operation: "qualify-native",
+      reason: "independent-native-proof-required",
+    };
+  if (!evidence.qualification)
+    return wait("qualified-warrant-readback-required");
+  return { operation: "land", reason: "protected-queue-admission" };
+}

package/packages/core/workflow/pipeline/recovery-action.js

@@ -0,0 +1,30 @@
+import { recoveryInputs } from "../../consumer/contract/entries.js";
+import { pipelineHost } from "./host.js";
+import { controlPipelineRecovery } from "./recovery-controller.js";
+import { pipelineActionOutputs } from "./action-output.js";
+import { resumePipelineSession } from "./session.js";
+
+export async function recoverPipelineAction(core, env) {
+  const { attempt } = recoveryInputs({
+    attempt: core.getInput("attempt", { required: true }),
+  });
+  const host = await pipelineHost(core, env, "Buildchain recovery controller");
+  try {
+    const result = await controlPipelineRecovery(
+      attempt,
+      core.getInput("definition-sha", { required: true }),
+      host,
+    );
+    pipelineActionOutputs(core, result);
+  } catch (error) {
+    try {
+      const session = await resumePipelineSession({ ...host, attempt }, host);
+      await host.project(session);
+    } catch {
+      core.warning(
+        "Recovery status projection is unavailable; the canonical attempt remains authoritative.",
+      );
+    }
+    throw error;
+  }
+}