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

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/record-action.js

@@ -0,0 +1,27 @@
+import { pipelineHost } from "./host.js";
+import { recordPipelineBuild } from "./build-control.js";
+import { publishRecorderStatus } from "./recorder-status.js";
+import {
+  RECOVERY_BUILD_CONTEXT,
+  recordRecoveryBuild,
+} from "./recovery-build-control.js";
+
+export async function recordPipelineBuildAction(core, env) {
+  const host = await pipelineHost(core, env, "Record product build");
+  host.publishBuildStatus = (context, readback) =>
+    publishRecorderStatus(context, readback, host);
+  const context = JSON.parse(core.getInput("context", { required: true }));
+  if (context.schema === "buildchain.pipeline-group-build-context/v1")
+    return host.groupRecord(context);
+  const result =
+    context.schema === RECOVERY_BUILD_CONTEXT
+      ? await recordRecoveryBuild(context, host)
+      : await recordPipelineBuild(context, host);
+  if (result.outcome !== "success")
+    throw new Error("Product build did not succeed");
+  core.info(
+    result.wakePending
+      ? "Build retained; next event will retry delivery wake"
+      : "Build retained and attempt woken",
+  );
+}

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

@@ -0,0 +1,69 @@
+import { createHash } from "node:crypto";
+import { parse } from "yaml";
+import { publishPipelineBuildStatus } from "./guard-build.js";
+import { recordDigest } from "../../release/discussion/envelope.js";
+
+// A repaired runtime may execute through an older immutable published entry.
+// Read the real recorder job's permission, rather than assuming the runtime's
+// current workflow is the one GitHub scheduled. API failures are never ignored.
+export async function publishRecorderStatus(context, readback, host) {
+  const { root, ...body } = readback;
+  if (
+    context.runId !== host.runId ||
+    context.runAttempt !== host.runAttempt ||
+    readback.runId !== host.runId ||
+    readback.runAttempt !== host.runAttempt ||
+    recordDigest(context.source) !== recordDigest(readback.source) ||
+    root !== recordDigest(body)
+  )
+    throw new Error("Recorder status changed its current source or execution");
+  const { run } = await host.runs.read(host.runId, host.runAttempt);
+  const path = ".github/workflows/.ops-pipeline-execute.yml";
+  const entries = (run.referenced_workflows || []).filter((entry) =>
+    entry.path?.startsWith(`kungfu-systems/buildchain/${path}@`),
+  );
+  if (entries.length !== 1 || !/^[0-9a-f]{40}$/u.test(entries[0].sha || ""))
+    throw new Error("Recorder has no exact published execution workflow");
+  const file = await host.request(
+    `/repos/kungfu-systems/buildchain/contents/${path}?ref=${entries[0].sha}`,
+  );
+  if (
+    file.type !== "file" ||
+    file.encoding !== "base64" ||
+    !Number.isSafeInteger(file.size) ||
+    file.size < 1 ||
+    file.size > 64000 ||
+    typeof file.content !== "string" ||
+    file.content.length > 128000
+  )
+    throw new Error(
+      "Recorder execution workflow is unavailable or exceeds its bound",
+    );
+  const bytes = Buffer.from(file.content, "base64");
+  const blob = createHash("sha1")
+    .update(`blob ${bytes.length}\0`)
+    .update(bytes)
+    .digest("hex");
+  if (bytes.length !== file.size || blob !== file.sha)
+    throw new Error("Recorder execution workflow bytes changed");
+  const job = parse(bytes.toString("utf8")).jobs?.["record-build"];
+  if (job?.name !== "Record product build")
+    throw new Error("Recorder execution workflow changed its job identity");
+  if (job.permissions?.statuses !== "write") return { published: false };
+  if (readback.outcome !== "success") return { published: false };
+  await publishPipelineBuildStatus(
+    {
+      "expected-head-sha": context.source.commit,
+      "source-workflow-run-id": String(readback.runId),
+    },
+    {
+      sourceHead: context.source.commit,
+      outcome: readback.outcome,
+      run: { id: readback.runId, run_attempt: readback.runAttempt },
+      readback,
+    },
+    host.request,
+    host.repository,
+  );
+  return { published: true };
+}

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

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

@@ -0,0 +1,122 @@
+import { recordDigest } from "../../release/discussion/envelope.js";
+import { readPipelineCaller } from "../../providers/github/pipeline-run-entry.js";
+import { RECOVERY_ENTRY } from "../../consumer/contract/entries.js";
+
+export async function recoveryExecution(host, definitionSha) {
+  const { run } = await host.runs.read(host.runId, host.runAttempt);
+  const definitions = (run.referenced_workflows || []).filter((item) =>
+    item.path?.startsWith(`kungfu-systems/buildchain/${RECOVERY_ENTRY}@`),
+  );
+  if (
+    run.event !== "workflow_dispatch" ||
+    run.status !== "in_progress" ||
+    run.repository?.full_name !== host.repository ||
+    run.head_repository?.full_name !== host.repository ||
+    run.path?.split("@")[0] !== ".github/workflows/buildchain-recover.yml" ||
+    definitions.length !== 1 ||
+    definitions[0].sha !== definitionSha ||
+    !/^[0-9a-f]{40}$/u.test(definitionSha || "")
+  )
+    throw new Error(
+      "Recovery must execute the exact canonical entry from the same consumer repository",
+    );
+  const channel = definitions[0].path
+    .split("@")
+    .at(-1)
+    .replace(/^refs\/tags\//u, "");
+  if (!["v4", "v4-alpha"].includes(channel))
+    throw new Error("Recovery entry must be a published floating channel");
+  return {
+    run,
+    channel,
+    entry: {
+      repository: "kungfu-systems/buildchain",
+      workflow: RECOVERY_ENTRY,
+      sha: definitionSha,
+    },
+  };
+}
+
+export async function admitRecoverySource(session, execution, host) {
+  const current = session.observed.history.at(-1);
+  const original = current.generation.source;
+  const source = await host.source.source(original.commit, original.configPath);
+  if (
+    recordDigest(source.identity) !== recordDigest(original) ||
+    host.selection.source?.sha !== original.commit ||
+    host.selection.source?.repository !== host.repository
+  )
+    throw new Error(
+      "Recovery source, config or selected runtime source changed",
+    );
+  const caller = await readPipelineCaller(
+    execution.run,
+    original.configPath,
+    host.request,
+    host.repository,
+  );
+  const admission = await host.source.observeIntent(
+    session.intent,
+    current.generation,
+    { "config-path": original.configPath },
+  );
+  if (
+    !admission.live.source ||
+    recordDigest(admission.live.source) !== recordDigest(original) ||
+    admission.live.targetBranch !== session.intent.source.targetBranch ||
+    (!admission.live.merged &&
+      (admission.live.state !== "open" ||
+        admission.live.routeEnabled === false ||
+        admission.live.baseCommit !== current.generation.baseCommit))
+  )
+    throw new Error(
+      "Selected source was closed, superseded or rebased; use its current admitted attempt",
+    );
+  return {
+    source,
+    admission,
+    caller,
+  };
+}
+
+export async function recoveryPredecessorRuns(session, host) {
+  const current = session.observed.history.at(-1);
+  const keys = [
+    ...new Map(
+      current.runs.map((writer) => [
+        `${writer.runId}:${writer.runAttempt}`,
+        writer,
+      ]),
+    ).values(),
+  ];
+  if (keys.length > 100)
+    throw new Error("Recovery predecessor run inventory exceeds its bound");
+  const observations = [];
+  for (const writer of keys) {
+    if (
+      Number(writer.runId) === host.runId &&
+      Number(writer.runAttempt) === host.runAttempt
+    )
+      throw new Error("Recovery cannot replace its own live execution");
+    const { run } = await host.runs.read(
+      Number(writer.runId),
+      Number(writer.runAttempt),
+    );
+    if (
+      run.repository?.full_name !== host.repository ||
+      run.head_repository?.full_name !== host.repository
+    )
+      throw new Error(
+        "Recovery predecessor execution crossed a repository or fork boundary",
+      );
+    observations.push(run);
+  }
+  return {
+    schema: "buildchain.pipeline-recovery-executions/v1",
+    predecessor: current.identity.id,
+    runs: observations,
+    terminal: observations.every(
+      (run) => run.status === "completed" && run.conclusion,
+    ),
+  };
+}

package/packages/core/workflow/pipeline/recovery-build-control.js

@@ -0,0 +1,95 @@
+import { object } from "../../consumer/contract/shape.js";
+import { recordDigest } from "../../release/discussion/envelope.js";
+import { resumePipelineSession } from "./session.js";
+import { recoveryBuildEvidence } from "./recovery-build-evidence.js";
+import { qualifyPipelineBuild } from "./build-qualification.js";
+import { retainPipelineBuildResult } from "./build-result.js";
+
+export const RECOVERY_BUILD_CONTEXT =
+  "buildchain.pipeline-recovery-build-context/v1";
+
+export async function beginRecoveryBuild(session, host) {
+  session.observed = await session.journal.read();
+  const { plan, build } = await recoveryBuildEvidence(session, host);
+  const observed = session.observed;
+  const previous = observed.phases.build;
+  if (
+    previous &&
+    (previous.payload.writer.runId !== String(host.runId) ||
+      previous.payload.writer.runAttempt !== String(host.runAttempt))
+  )
+    return null;
+  await session.progress.progress({
+    attempt: observed.attempt,
+    phase: "build",
+    state: "running",
+    eventKey: `build-start:${host.runId}:${host.runAttempt}`,
+    expectedHead: observed.head,
+    reason: build.reason,
+  });
+  return {
+    schema: RECOVERY_BUILD_CONTEXT,
+    attempt: observed.attempt,
+    generation: observed.generation,
+    source: build.source,
+    runId: host.runId,
+    runAttempt: host.runAttempt,
+    platforms: build.scheduled,
+    recoveryPlanRoot: plan.root,
+  };
+}
+
+export async function recordRecoveryBuild(context, host) {
+  object(context, [
+    "schema",
+    "attempt",
+    "generation",
+    "source",
+    "runId",
+    "runAttempt",
+    "platforms",
+    "recoveryPlanRoot",
+  ]);
+  if (
+    context.schema !== RECOVERY_BUILD_CONTEXT ||
+    context.runId !== host.runId ||
+    context.runAttempt !== host.runAttempt
+  )
+    throw new Error("Recovery build callback belongs to another execution");
+  const session = await resumePipelineSession(
+    { ...host, attempt: context.attempt },
+    host,
+  );
+  const { plan, build } = await recoveryBuildEvidence(session, host);
+  const writer = session.observed.phases.build?.payload.writer;
+  if (
+    context.generation !== session.observed.generation ||
+    context.recoveryPlanRoot !== plan.root ||
+    recordDigest(context.source) !== recordDigest(build.source) ||
+    recordDigest(context.platforms) !== recordDigest(build.scheduled) ||
+    writer?.runId !== String(host.runId) ||
+    writer?.runAttempt !== String(host.runAttempt)
+  )
+    throw new Error(
+      "Recovery build callback changed its reserved work or admission",
+    );
+  const segments = structuredClone(build.segments);
+  if (build.scheduled.length) {
+    const platforms = build.scheduled.map((item) => item.platform);
+    const readback = await host.runs.build(
+      host.runId,
+      host.runAttempt,
+      build.source,
+      platforms,
+    );
+    segments.push({ readback, platforms, runtime: host.runtime });
+  }
+  const result = qualifyPipelineBuild({
+    source: build.source,
+    platforms: build.platforms.map((item) => item.platform),
+    segments,
+    runId: host.runId,
+    runAttempt: host.runAttempt,
+  });
+  return retainPipelineBuildResult(context, result, session, host);
+}