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

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

@@ -0,0 +1,95 @@
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { bindConsumerSource } from "../../consumer/contract/identity.js";
+import { recordDigest } from "../../release/discussion/envelope.js";
+import { consumerCommandSession } from "../../runtime/consumer-shell.js";
+import { createNativeChildEnvironment } from "../../dev-delivery/native/execution.js";
+
+function sourceCheckout(cwd, expected) {
+  const git = (...args) =>
+    execFileSync("git", ["-C", cwd, ...args], {
+      encoding: "utf8",
+      maxBuffer: 1024 * 1024,
+    }).trim();
+  if (
+    git("rev-parse", "HEAD") !== expected.commit ||
+    git("rev-parse", "HEAD^{tree}") !== expected.tree
+  )
+    throw new Error("Build checkout does not match admitted source");
+  const configFile = fs.realpathSync(path.join(cwd, expected.configPath));
+  if (!configFile.startsWith(`${fs.realpathSync(cwd)}${path.sep}`))
+    throw new Error("Consumer TOML escapes the source checkout");
+  const { identity, plan } = bindConsumerSource(
+    {
+      repository: expected.repository,
+      commit: expected.commit,
+      tree: expected.tree,
+      configPath: expected.configPath,
+      configBlob: git("rev-parse", `HEAD:${expected.configPath}`),
+    },
+    fs.readFileSync(configFile),
+  );
+  if (recordDigest(identity) !== recordDigest(expected))
+    throw new Error("Build TOML changed after source admission");
+  if (git("status", "--porcelain", "--untracked-files=no"))
+    throw new Error(
+      "Build source has tracked modifications at its verification boundary",
+    );
+  return plan;
+}
+
+function productDirectory(cwd, product) {
+  const directory = fs.realpathSync(
+    path.resolve(cwd, product.directory || "."),
+  );
+  const root = fs.realpathSync(cwd);
+  if (directory !== root && !directory.startsWith(`${root}${path.sep}`))
+    throw new Error("Product directory escapes its source checkout");
+  return directory;
+}
+
+// This node executes only product-owned build/test commands, on a read-only
+// credential job. Its output is an observation; independent seal/qualification
+// jobs must bind provider completion and exact artifacts before granting reuse.
+export async function buildPipelineSource(
+  { cwd, source, platform, environment = process.env },
+  { inspect = sourceCheckout, session = consumerCommandSession } = {},
+) {
+  const plan = inspect(cwd, source);
+  const result = await buildPipelineProducts(
+    { cwd, plan, platform, environment },
+    session,
+  );
+  inspect(cwd, source);
+  return {
+    schema: "buildchain.pipeline-build-observation/v1",
+    source,
+    ...result,
+  };
+}
+
+export async function buildPipelineProducts(
+  { cwd, plan, platform, environment = process.env },
+  session = consumerCommandSession,
+) {
+  const products = plan.products.filter((product) =>
+    product.platforms.includes(platform),
+  );
+  if (!products.length)
+    throw new Error("No products declared for the selected platform");
+  const results = [];
+  for (const product of products) {
+    const commands = session(createNativeChildEnvironment(environment));
+    const directory = productDirectory(cwd, product);
+    for (const phase of ["install", "build", "verify"]) {
+      for (const script of product[phase] || [])
+        await commands.run({ script, cwd: directory, strict: true });
+    }
+    results.push({ product: product.id, outcome: "success" });
+  }
+  return {
+    platform,
+    products: results,
+  };
+}

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