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

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

@@ -0,0 +1,169 @@
+import { recordDigest } from "../../release/discussion/envelope.js";
+
+function cancellationEvent(reason) {
+  if (reason === "source-generation-changed") return "synchronize";
+  if (reason === "pull-request-dequeued") return "dequeued";
+  if (reason === "pull-request-closed") return "closed";
+  return "cancelled";
+}
+
+function exactCandidate(fresh, id) {
+  const candidate = fresh.queue.candidates.find(
+    (entry) => entry.candidateId === id,
+  );
+  if (
+    !candidate ||
+    candidate.sourceHead !== fresh.current.generation.source.commit ||
+    candidate.pullRequestNumber !== fresh.current.intent.source.pullRequest
+  )
+    throw new Error("Cancellation candidate source identity drift");
+  return candidate;
+}
+
+async function applyCleanup(fresh, readback, service) {
+  const { decision } = readback;
+  const candidate = exactCandidate(fresh, readback.candidateId);
+  const request = {
+    expectedOldStateRoot: fresh.queue.stateRoot,
+    pullRequestNumber: candidate.pullRequestNumber,
+    expectedSourceHead: candidate.sourceHead,
+    eventAction: cancellationEvent(decision.reason),
+    evidenceRoot: recordDigest(readback),
+    outcome:
+      decision.reason === "pull-request-dequeued" ? "dequeued" : "cancelled",
+    reason: decision.reason,
+    execute: true,
+  };
+  if (decision.operation === "cancel-queued")
+    return service.cancelQueued({
+      ...request,
+      candidateId: candidate.candidateId,
+      observedSourceHead:
+        readback.live.observedHead || readback.live.source?.commit,
+    });
+  if (
+    !candidate.terminal &&
+    (fresh.queue.activeWarrant?.candidateId !== candidate.candidateId ||
+      fresh.worker?.status !== "completed")
+  )
+    throw new Error(
+      "Active cancellation requires exact terminal worker readback",
+    );
+  const warrant =
+    fresh.queue.activeWarrant?.candidateId === candidate.candidateId
+      ? fresh.queue.activeWarrant
+      : null;
+  return service.settle({
+    ...request,
+    ...(warrant
+      ? {
+          fencingToken: warrant.fencingToken,
+          leaseGeneration: warrant.generation,
+        }
+      : {}),
+  });
+}
+
+async function finishCleanup(fresh, result, readbackMaterial, ports) {
+  const receipt = await ports.materials.retain(
+    `cancellation/receipt-${result.receiptRoot.slice(7)}`,
+    result,
+  );
+  if (
+    result.observation.activeWarrant?.candidateId === fresh.decision.candidateId
+  )
+    return { status: "waiting", reason: "warrant-retained" };
+  const prior = fresh.current.phases[fresh.phase];
+  if (prior?.payload.state === "cancelled") {
+    if (
+      prior.payload.reason !== fresh.decision.reason ||
+      !prior.payload.materials.some(
+        (material) => recordDigest(material) === recordDigest(readbackMaterial),
+      )
+    )
+      throw new Error(
+        "Terminal cancellation projection has different evidence",
+      );
+  } else
+    await ports.progress.progress({
+      attempt: fresh.attempt,
+      phase: fresh.phase,
+      state: "cancelled",
+      eventKey: `cancelled:${result.receiptRoot}`,
+      reason: fresh.decision.reason,
+      materials: [readbackMaterial, receipt],
+    });
+  if (result.receipt.successorWake)
+    await ports.wake(result.receipt.successorWake);
+  return { status: "cancelled", receiptRoot: result.receiptRoot };
+}
+
+// The pending readback is committed to the attempt before the domain mutation.
+// Recovery can therefore prove a completed effect even if its response was lost.
+export async function cancelPipelineCandidate({ attempt, decision }, ports) {
+  const fresh = await ports.observe();
+  if (
+    fresh.attempt !== attempt ||
+    recordDigest(fresh.decision) !== recordDigest(decision)
+  )
+    throw new Error("Pipeline cancellation changed during admission");
+  if (decision.operation === "stop-worker") {
+    await ports.progress.requestStop(decision.reason);
+    return { status: "waiting", reason: "provider-worker-stop-required" };
+  }
+  if (!["cancel-queued", "settle-cancelled"].includes(decision.operation))
+    throw new Error("Pipeline cancellation requires an exact cleanup decision");
+  const candidate = exactCandidate(fresh, decision.candidateId);
+  const readback = {
+    schema: "buildchain.pipeline-cancellation-readback/v1",
+    attempt,
+    generation: fresh.current.generation.id,
+    decision,
+    live: fresh.live,
+    worker: fresh.worker || null,
+    candidateId: candidate.candidateId,
+    stateRoot: fresh.queue.stateRoot,
+  };
+  const evidenceRoot = recordDigest(readback);
+  const reference = await ports.materials.retain(
+    `cancellation/readback-${evidenceRoot.slice(7)}`,
+    readback,
+    "provider-readback",
+  );
+  await ports.progress.progress({
+    attempt,
+    phase: fresh.phase,
+    state: "waiting",
+    eventKey: `cancellation-request:${evidenceRoot}`,
+    reason: `pipeline-stop-requested:${decision.reason}`,
+    materials: [reference],
+  });
+  const result = await applyCleanup(fresh, readback, ports.service);
+  return finishCleanup(fresh, result, reference, ports);
+}
+
+export async function recoverPipelineCancellation(fresh, ports) {
+  const candidate = exactCandidate(fresh, fresh.decision.candidateId);
+  if (
+    !["cancelled", "dequeued"].includes(candidate.status) ||
+    !candidate.terminal?.evidenceRoot
+  )
+    throw new Error(
+      "Cancellation recovery requires terminal provider evidence",
+    );
+  const id = `cancellation/readback-${candidate.terminal.evidenceRoot.slice(7)}`;
+  const reference = fresh.current.materials[id];
+  if (!reference)
+    throw new Error("Cancellation intent was not retained before its effect");
+  const readback = await ports.materials.read(reference);
+  if (
+    recordDigest(readback) !== candidate.terminal.evidenceRoot ||
+    readback.attempt !== fresh.attempt ||
+    readback.generation !== fresh.current.generation.id ||
+    readback.candidateId !== candidate.candidateId
+  )
+    throw new Error("Cancellation recovery retained evidence drift");
+  const recovered = { ...fresh, decision: readback.decision };
+  const result = await applyCleanup(recovered, readback, ports.service);
+  return finishCleanup(recovered, result, reference, ports);
+}

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

@@ -0,0 +1,127 @@
+import { recordDigest } from "../../release/discussion/envelope.js";
+import { pipelineBuildEvidence } from "./build-evidence.js";
+
+async function record(session, phase, state, receipt, host, reason = "") {
+  const observed = await session.journal.read();
+  const root = recordDigest(receipt);
+  const reference = await host
+    .materialStore(session)
+    .retain(`${phase}/${root.slice(7)}`, receipt, "provider-readback");
+  return session.progress.progress({
+    attempt: observed.attempt,
+    phase,
+    state,
+    eventKey: `${phase}:${state}:${root}`,
+    reason,
+    materials: [reference],
+  });
+}
+
+async function channelMerge(session, admission, host) {
+  const observed = await session.journal.read();
+  const current = { ...observed.history.at(-1), intent: session.intent };
+  if (current.phases.merge?.payload.state !== "success") {
+    const integration = await host.integration.observe(current);
+    await record(session, "merge", "success", integration, host);
+  }
+  if (host.terminalOnly) {
+    await host.wake(observed.attempt);
+    return {
+      operation: "wait",
+      reason: "publication-requires-a-normal-dispatch",
+      attempt: observed.attempt,
+    };
+  }
+  // Product publication is a separate typed domain stage. This operation keeps
+  // the business attempt open until its published byte/readback receipts exist.
+  return {
+    operation: "publish",
+    attempt: observed.attempt,
+    source: admission.live.source,
+  };
+}
+
+export async function controlPipelineChannel(session, admission, inputs, host) {
+  const observed = await session.journal.read();
+  const current = { ...observed.history.at(-1), intent: session.intent };
+  const { live } = admission;
+  if (live.merged) return channelMerge(session, admission, host);
+  if (
+    live.state !== "open" ||
+    !live.source ||
+    live.routeEnabled === false ||
+    live.targetBranch !== session.intent.source.targetBranch ||
+    live.baseCommit !== current.generation.baseCommit
+  ) {
+    await record(
+      session,
+      observed.missing[0],
+      "superseded",
+      live,
+      host,
+      "channel-source-no-longer-admitted",
+    );
+    return {
+      operation: "successor",
+      reason: "channel-source-no-longer-admitted",
+    };
+  }
+  if (host.terminalOnly)
+    return { operation: "wait", reason: "terminal-event-cannot-execute" };
+  const build = await pipelineBuildEvidence(session, host);
+  if (!build) return { operation: "build", admission };
+  if (build.run.status !== "completed" || build.run.conclusion !== "success")
+    return { operation: "wait", reason: "source-workflow-not-qualified" };
+  const policy = await host.policy.observe(
+    current,
+    admission.protectedPlan.review,
+  );
+  if (!policy.review || !policy.checksPassing || !live.ready || live.draft)
+    return { operation: "wait", reason: "protected-channel-gates-pending" };
+  if (!current.phases.review)
+    await record(session, "review", "success", policy, host);
+  const queue = await host.queue.getMergeQueueState(
+    session.intent.source.targetBranch,
+  );
+  if (!queue.enabled)
+    throw new Error("Protected channel merge queue is disabled");
+  const entry = queue.entries.find(
+    (item) => item.pullRequestNumber === live.pullRequest,
+  );
+  if (entry) {
+    if (entry.pullRequestHeadSha !== live.source.commit)
+      throw new Error("Protected queue source drift");
+    return { operation: "wait", reason: "channel-in-protected-merge-queue" };
+  }
+  await record(
+    session,
+    "merge",
+    "waiting",
+    { schema: "buildchain.pipeline-channel-enqueue/v1", policy, queue },
+    host,
+  );
+  const again = await host.source.observeIntent(
+    session.intent,
+    current.generation,
+    inputs,
+  );
+  if (recordDigest(again.live) !== recordDigest(live))
+    throw new Error("Channel changed before queue admission");
+  await host.queue.enqueuePullRequest({
+    pullRequestId: policy.pr.id,
+    expectedHeadOid: live.source.commit,
+  });
+  const readback = await host.queue.getMergeQueueState(
+    session.intent.source.targetBranch,
+  );
+  if (
+    !readback.entries.some(
+      (item) =>
+        item.pullRequestNumber === live.pullRequest &&
+        item.pullRequestHeadSha === live.source.commit,
+    )
+  )
+    throw new Error("Channel queue admission requires exact provider readback");
+  await record(session, "merge", "waiting", readback, host);
+  return { operation: "wait", reason: "channel-enqueued" };
+}

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

@@ -0,0 +1,133 @@
+import { pipelineEvent } from "./events.js";
+import { selectPipelineSession } from "./selection.js";
+import { beginPipelineBuild } from "./build-control.js";
+import { controlPipelineDelivery } from "./delivery-control.js";
+import { githubPipelineEvents } from "../../providers/github/pipeline-events.js";
+import { pipelinePlatforms } from "./platforms.js";
+import { recordDigest } from "../../release/discussion/envelope.js";
+
+async function groupBuild(event, inputs, host) {
+  const queue = await host.queue.getMergeQueueState(event.branch);
+  if (
+    !queue.enabled ||
+    !queue.entries.some(
+      (entry) =>
+        entry.headSha === event.commit && entry.baseSha === event.baseCommit,
+    )
+  )
+    throw new Error(
+      "Merge-group execution is not in the exact protected provider queue",
+    );
+  const admitted = await host.source.source(
+    event.commit,
+    inputs["config-path"],
+  );
+  const context = {
+    schema: "buildchain.pipeline-group-build-context/v1",
+    source: admitted.identity,
+    branch: event.branch,
+    baseCommit: event.baseCommit,
+    runId: host.runId,
+    runAttempt: host.runAttempt,
+    platforms: pipelinePlatforms(admitted.plan),
+  };
+  return { operation: "build", context };
+}
+
+export async function controlPipeline(name, payload, inputs, host) {
+  const event = pipelineEvent(name, payload, host.repository);
+  host.terminalOnly = event.terminalOnly;
+  host.eventAction = payload.action || "";
+  if (event.kind === "ignore")
+    return { operation: "wait", reason: event.reason };
+  if (event.kind === "branch") {
+    const events = githubPipelineEvents(
+      host.request,
+      host.provider,
+      host.repository,
+    );
+    const attempts = await events.branch(event.branch, event.commit);
+    for (const attempt of attempts) await host.wake(attempt);
+    return {
+      operation: "wait",
+      reason: "existing-channel-intents-woken",
+      count: attempts.length,
+    };
+  }
+  if (event.kind === "merge-group") return groupBuild(event, inputs, host);
+  const selected = await selectPipelineSession(event, payload, inputs, host);
+  if (!selected)
+    return { operation: "wait", reason: "no-admitted-pipeline-intent" };
+  const { session, admission } = selected;
+  const current = session.observed.history.at(-1);
+  if (
+    current.identity.requestKey.startsWith("recover:") &&
+    recordDigest(current.events[0].runtime) !== recordDigest(host.runtime)
+  ) {
+    await host.wake(current.identity.id);
+    return {
+      operation: "wait",
+      reason: "admitted-recovery-runtime-continuation-required",
+      attempt: current.identity.id,
+    };
+  }
+  if (
+    ["failure", "cancelled", "superseded", "complete"].includes(
+      session.observed.status,
+    )
+  ) {
+    await host.notifyTerminal?.(session);
+    await host.project(session);
+    return {
+      operation: "wait",
+      reason: `attempt-${session.observed.status}`,
+      attempt: session.observed.attempt,
+    };
+  }
+  if (
+    admission.live.source &&
+    host.selection.source.sha !== admission.live.source.commit
+  ) {
+    await host.wake(session.observed.attempt);
+    return {
+      operation: "wait",
+      reason: "source-generation-runtime-selection-required",
+      attempt: session.observed.attempt,
+    };
+  }
+  const operation = session.intent.expectedNodes.includes("warrant")
+    ? await controlPipelineDelivery(session, inputs, host)
+    : await host.channel(session, admission, inputs);
+  if (operation.operation === "build") {
+    const context = await beginPipelineBuild(
+      session,
+      operation.admission || admission,
+      host,
+    );
+    await host.project(session);
+    if (!context)
+      return { operation: "wait", reason: "existing-build-execution-retained" };
+    return { operation: "build", context };
+  }
+  await host.project(session);
+  if (operation.operation === "successor") {
+    // Closed or retargeted PRs do not authorize a new attempt on the old route.
+    // A later normal event re-admits a lawful source after the old candidate ends.
+    await host.wake(session.observed.attempt);
+    return {
+      operation: "wait",
+      reason: operation.reason,
+      attempt: session.observed.attempt,
+    };
+  }
+  if (operation.operation === "settle") {
+    const settled = await host.settle(
+      session,
+      operation.fresh,
+      operation.delivery,
+    );
+    await host.project(session);
+    return settled;
+  }
+  return operation;
+}

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

@@ -0,0 +1,204 @@
+import { recordDigest } from "../../release/discussion/envelope.js";
+import { preparePipelineDelivery } from "./delivery-request.js";
+import { pipelineBuildEvidence } from "./build-evidence.js";
+import {
+  observePipelineWorker,
+  pipelineDeliveryStore,
+} from "./delivery-observation.js";
+import { reconcilePipeline, pipelineCandidate } from "./reconcile.js";
+import {
+  cancelPipelineCandidate,
+  recoverPipelineCancellation,
+} from "./cancellation.js";
+import { readBusinessAttempt } from "../attempt/reader.js";
+
+export async function observePipelineDelivery(session, inputs, host, delivery) {
+  const observed = await session.journal.read();
+  const current = { ...observed.history.at(-1), intent: session.intent };
+  const admission = await host.source.observeIntent(
+    session.intent,
+    current.generation,
+    inputs,
+  );
+  admission.live.terminalOnly = host.terminalOnly === true;
+  admission.live.dequeued = host.eventAction === "dequeued";
+  const queue = await delivery.read();
+  const worker = await observePipelineWorker(session, current, queue, host);
+  const input = { current, live: admission.live, queue, worker, evidence: {} };
+  return {
+    ...input,
+    admission,
+    observed,
+    attempt: observed.attempt,
+    phase: observed.missing[0],
+    decision: reconcilePipeline(input),
+  };
+}
+
+async function cleanup(fresh, session, inputs, host, delivery) {
+  const ports = {
+    observe: () => observePipelineDelivery(session, inputs, host, delivery),
+    progress: session.progress,
+    service: delivery.service,
+    materials: host.materialStore(session),
+    wake: async (successor) => {
+      const retained = await host.provider.lookup(
+        host.repository,
+        successor.pullRequestNumber,
+        session.intent.source.targetBranch,
+      );
+      if (retained)
+        await host.wake(readBusinessAttempt(retained.snapshot).attempt);
+    },
+  };
+  if (fresh.decision.operation === "record-cancellation")
+    return recoverPipelineCancellation(fresh, ports);
+  if (
+    ["stop-worker", "cancel-queued", "settle-cancelled"].includes(
+      fresh.decision.operation,
+    )
+  )
+    return cancelPipelineCandidate(fresh, ports);
+  return null;
+}
+
+async function retainDeliveryRequest(fresh, session, build, host) {
+  const scheduling = await session.journal.read();
+  const schedulingCurrent = {
+    ...scheduling.history.at(-1),
+    intent: session.intent,
+  };
+  const active = await observePipelineWorker(
+    session,
+    schedulingCurrent,
+    fresh.queue,
+    host,
+  );
+  if (active?.status === "in_progress")
+    return { operation: "wait", reason: "native-worker-running" };
+  const request = await (host.prepareDelivery || preparePipelineDelivery)({
+    current: fresh.current,
+    run: build.run,
+    build: build.readback,
+    runtimeSha: host.runtime.sha,
+    token: host.token,
+    plan: fresh.admission.plan,
+  });
+  const execution = {
+    schema: "buildchain.pipeline-delivery-execution/v1",
+    attempt: fresh.attempt,
+    generation: fresh.current.generation.id,
+    runId: host.runId,
+    runAttempt: host.runAttempt,
+    request,
+  };
+  const reference = await host
+    .materialStore(session)
+    .retain(`delivery/execution-${host.runId}-${host.runAttempt}`, execution);
+  await session.progress.progress({
+    attempt: fresh.attempt,
+    phase: "warrant",
+    state: "running",
+    eventKey: `delivery:${host.runId}:${host.runAttempt}`,
+    materials: [reference],
+    expectedHead: scheduling.head,
+  });
+  return { operation: "deliver", request, attempt: fresh.attempt };
+}
+
+export async function controlPipelineDelivery(session, inputs, host) {
+  const delivery = host.delivery
+    ? host.delivery(session)
+    : pipelineDeliveryStore(session, host);
+  const fresh = await observePipelineDelivery(session, inputs, host, delivery);
+  const candidate = pipelineCandidate(fresh.queue, fresh.current);
+  if (["cancelled", "dequeued"].includes(candidate?.status))
+    fresh.decision = {
+      operation: "record-cancellation",
+      candidateId: candidate.candidateId,
+    };
+  if (candidate?.status === "terminal-failure") {
+    const material = await host
+      .materialStore(session)
+      .retain(
+        `failure/${fresh.queue.stateRoot.slice(7)}`,
+        fresh.queue,
+        "provider-readback",
+      );
+    await session.progress.progress({
+      attempt: fresh.attempt,
+      phase: fresh.phase,
+      state: "failure",
+      eventKey: `failure:${fresh.queue.stateRoot}`,
+      reason: "native-execution-failed",
+      materials: [material],
+    });
+    return { operation: "wait", reason: "native-execution-failed" };
+  }
+  const result = await cleanup(fresh, session, inputs, host, delivery);
+  if (result) {
+    if (result.status === "cancelled") await host.wake(fresh.attempt);
+    return { operation: "wait", reason: result.reason || result.status };
+  }
+  if (fresh.decision.operation === "supersede") {
+    if (
+      !["cancelled", "failure", "superseded", "complete"].includes(
+        fresh.observed.status,
+      )
+    )
+      await session.progress.progress({
+        attempt: fresh.attempt,
+        phase: fresh.phase,
+        state: "superseded",
+        eventKey: `supersede:${recordDigest(fresh.live)}`,
+        reason: fresh.decision.reason,
+      });
+    return { operation: "successor", reason: fresh.decision.reason };
+  }
+  if (fresh.live.merged) return { operation: "settle", fresh, delivery };
+  if (fresh.live.state !== "open" || fresh.live.terminalOnly)
+    return { operation: "wait", reason: "no-execution-admission" };
+  const build = await pipelineBuildEvidence(session, host);
+  if (!build) return { operation: "build", admission: fresh.admission };
+  if (build.run.status !== "completed")
+    return { operation: "wait", reason: "source-workflow-still-running" };
+  const policy = await host.policy.observe(
+    fresh.current,
+    fresh.admission.protectedPlan.review,
+  );
+  if (
+    !policy.review ||
+    !policy.checksPassing ||
+    !fresh.live.ready ||
+    fresh.live.draft
+  )
+    return { operation: "wait", reason: "protected-source-gates-pending" };
+  if (!fresh.current.phases.review) {
+    const material = await host
+      .materialStore(session)
+      .retain(`review/${policy.root.slice(7)}`, policy, "provider-readback");
+    await session.progress.progress({
+      attempt: fresh.attempt,
+      phase: "review",
+      state: "success",
+      eventKey: `review:${policy.root}`,
+      materials: [material],
+    });
+  }
+  const decision = reconcilePipeline({
+    ...fresh,
+    evidence: {
+      build,
+      review: policy,
+      checks: policy,
+      qualification: fresh.queue.activeWarrant?.phase === "qualified",
+    },
+  });
+  if (fresh.worker?.status === "in_progress")
+    return { operation: "wait", reason: "native-worker-running" };
+  if (
+    ["reserve", "select", "qualify-native", "land"].includes(decision.operation)
+  )
+    return retainDeliveryRequest(fresh, session, build, host);
+  return decision;
+}