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

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

@@ -0,0 +1,141 @@
+import { pipelineEvent } from "./events.js";
+import { selectPipelineSession } from "./selection.js";
+import { beginPipelineBuild } from "./build-control.js";
+import { controlPipelineDelivery } from "./delivery-control.js";
+import {
+  githubPipelineEvents,
+  githubPipelineQueueExit,
+} 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,
+    };
+  }
+  if (session.intent.expectedNodes.includes("warrant"))
+    host.queueExit ||= githubPipelineQueueExit(
+      host.github.graphql,
+      host.repository,
+    );
+  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,249 @@
+import { recordDigest } from "../../release/discussion/envelope.js";
+import { preparePipelineDelivery } from "./delivery-request.js";
+import { pipelineBuildEvidence } from "./build-evidence.js";
+import {
+  observePipelineWorker,
+  pipelineDeliveryExecution,
+  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;
+  const queue = await delivery.read();
+  admission.live.queueExit =
+    admission.live.state === "open" &&
+    admission.live.source?.commit === current.generation.source.commit &&
+    admission.live.targetBranch === session.intent.source.targetBranch
+      ? await host.queueExit(current, pipelineCandidate(queue, current))
+      : null;
+  admission.live.dequeued = Boolean(admission.live.queueExit);
+  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,
+  };
+  // The provider execution owns the delivery slot before it acquires a
+  // Warrant. A later wake must not replace its retained coordinates while its
+  // queued or running job is still entitled to perform final admission.
+  const executionOwner = await pipelineDeliveryExecution(
+    session,
+    schedulingCurrent,
+    host,
+  );
+  if (executionOwner) {
+    const { run } = await host.runs.read(
+      executionOwner.runId,
+      executionOwner.runAttempt,
+    );
+    if (
+      run.id !== executionOwner.runId ||
+      run.run_attempt !== executionOwner.runAttempt
+    )
+      throw new Error("Retained delivery execution provider identity drift");
+    if (run.status !== "completed")
+      return {
+        operation: "wait",
+        reason: "admitted-delivery-execution-running",
+      };
+  }
+  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,
+      )
+    ) {
+      try {
+        await session.progress.progress({
+          attempt: fresh.attempt,
+          phase: fresh.phase,
+          state: "superseded",
+          eventKey: `supersede:${recordDigest(fresh.live)}`,
+          reason: fresh.decision.reason,
+        });
+      } catch (error) {
+        // Concurrent notifications can finish the same attempt after readback.
+        // Its immutable terminal result is sufficient; never rewrite that phase.
+        const latest = await session.journal.read();
+        if (
+          latest.attempt !== fresh.attempt ||
+          !["cancelled", "failure", "superseded", "complete"].includes(
+            latest.status,
+          )
+        )
+          throw error;
+      }
+    }
+    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;
+}

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

@@ -0,0 +1,124 @@
+import { GitHubDevDeliveryStore } from "../../providers/dev-delivery/store.js";
+import { defaultDevDeliveryStateRef } from "../../dev-delivery/warrant/values.js";
+import { createDeliveryWarrantService } from "../../dev-delivery/warrant/service.js";
+import { PIPELINE_WORKER } from "../../providers/github/pipeline-worker.js";
+import { pipelineCandidate } from "./reconcile.js";
+
+function workerJob(jobs, name) {
+  const selected = jobs.filter(
+    (job) => job.name === name || job.name.endsWith(` / ${name}`),
+  );
+  if (selected.length > 1)
+    throw new Error("Native worker job identity is ambiguous");
+  return selected[0];
+}
+
+export async function pipelineDeliveryExecution(session, current, host) {
+  const phase = [...current.events]
+    .reverse()
+    .find((event) =>
+      event.payload.materials.some((material) =>
+        material.id.startsWith("delivery/execution-"),
+      ),
+    );
+  const references =
+    phase?.payload.materials.filter((material) =>
+      material.id.startsWith("delivery/execution-"),
+    ) || [];
+  if (!references.length) return null;
+  if (references.length !== 1)
+    throw new Error("Native worker requires one admitted execution");
+  const execution = await host.materialStore(session).read(references[0]);
+  if (
+    execution.attempt !== current.identity.id ||
+    execution.generation !== current.generation.id
+  )
+    throw new Error("Native worker execution belongs to another attempt");
+  return execution;
+}
+
+export async function observePipelineWorker(session, current, queue, host) {
+  const warrant = queue.activeWarrant;
+  const candidate = pipelineCandidate(queue, current);
+  if (
+    !warrant ||
+    candidate?.candidateId !== warrant.candidateId ||
+    warrant.sourceHead !== current.generation.source.commit ||
+    warrant.pullRequestNumber !== current.intent.source.pullRequest
+  )
+    return null;
+  const execution = await pipelineDeliveryExecution(session, current, host);
+  if (!execution) return null;
+  const { run, jobs } = await host.runs.read(
+    execution.runId,
+    execution.runAttempt,
+  );
+  if (run.status !== "completed") {
+    const terminalJobs = [
+      "Credentialless native execution",
+      "Credentialless native evidence seal",
+    ].map((name) => workerJob(jobs, name));
+    if (terminalJobs.some((job) => !job || job.status !== "completed"))
+      return {
+        status: "in_progress",
+        reason: "admitted-execution-not-terminal",
+        run,
+      };
+  }
+  const entries = (run.referenced_workflows || []).filter((entry) =>
+    entry.path?.startsWith(
+      "kungfu-systems/buildchain/.github/workflows/public-ops-dev-auto-merge.yml@",
+    ),
+  );
+  if (entries.length !== 1) return null;
+  const native = workerJob(jobs, "Credentialless native execution"),
+    seal = workerJob(jobs, "Credentialless native evidence seal");
+  if (!native || !seal) return null;
+  if (
+    run.status !== "completed" &&
+    run.id !== host.runId &&
+    native.status === "completed" &&
+    seal.status === "completed"
+  )
+    await host.runs.completed(execution.runId, execution.runAttempt);
+  return host.workers.observe(
+    {
+      schema: PIPELINE_WORKER,
+      repository: host.repository,
+      attempt: current.identity.id,
+      generation: current.generation.id,
+      sourceHead: warrant.sourceHead,
+      candidateId: warrant.candidateId,
+      fencingToken: warrant.fencingToken,
+      leaseGeneration: warrant.generation,
+      runId: execution.runId,
+      runAttempt: execution.runAttempt,
+      nativeJobId: native.id,
+      sealJobId: seal.id,
+    },
+    current,
+    warrant,
+  );
+}
+
+export function pipelineDeliveryStore(session, host) {
+  const branch = session.intent.source.targetBranch;
+  const store = new GitHubDevDeliveryStore({
+    repository: host.repository,
+    token: host.token,
+  });
+  return {
+    read: async () =>
+      (
+        await store.read({
+          stateRef: defaultDevDeliveryStateRef(branch),
+          protectedBase: branch,
+          now: new Date().toISOString(),
+        })
+      ).queue,
+    service: createDeliveryWarrantService(
+      { repository: host.repository, token: host.token, branch },
+      store,
+    ),
+  };
+}