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

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

@@ -0,0 +1,56 @@
+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),
+  );
+  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,37 @@
+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;
+}

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

@@ -0,0 +1,156 @@
+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",
+    );
+  await guardPipelineBuild(input, observed, {
+    material,
+    source,
+    request,
+    repository: connection.repository,
+  });
+  return guardPipelineDelivery(input, connection);
+}
+
+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;
+}

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 };
+  };
+}