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

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

@@ -0,0 +1,142 @@
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+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 inspectTrackedBytes(cwd, tree) {
+  const root = fs.realpathSync(cwd);
+  const entries = execFileSync(
+    "git",
+    ["-C", root, "ls-tree", "-r", "-z", tree],
+    {
+      encoding: "utf8",
+      maxBuffer: 16 * 1024 * 1024,
+    },
+  )
+    .split("\0")
+    .filter(Boolean);
+  for (const entry of entries) {
+    const match =
+      /^(100644|100755|120000) blob ([0-9a-f]{40})\t([\s\S]+)$/u.exec(entry);
+    if (!match) throw new Error("Build source requires resolved tracked files");
+    const [, mode, blob, file] = match;
+    const absolute = path.join(root, file);
+    if (fs.realpathSync(path.dirname(absolute)) !== path.dirname(absolute))
+      throw new Error(`Build source parent became a symbolic link: ${file}`);
+    const stat = fs.lstatSync(absolute);
+    const link = mode === "120000";
+    if (link ? !stat.isSymbolicLink() : !stat.isFile())
+      throw new Error(`Build tracked source kind changed: ${file}`);
+    if (
+      !link &&
+      process.platform !== "win32" &&
+      Boolean(stat.mode & 0o111) !== (mode === "100755")
+    )
+      throw new Error(`Build tracked source executable mode changed: ${file}`);
+    const bytes = link
+      ? fs.readlinkSync(absolute, { encoding: "buffer" })
+      : fs.readFileSync(absolute);
+    const actual = createHash("sha1")
+      .update(`blob ${bytes.length}\0`)
+      .update(bytes)
+      .digest("hex");
+    if (actual !== blob)
+      throw new Error(
+        `Build tracked source bytes differ from the admitted tree: ${file}`,
+      );
+  }
+}
+
+export function inspectPipelineSource(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",
+    );
+  // Index flags and local Git filters cannot qualify different product bytes.
+  inspectTrackedBytes(cwd, expected.tree);
+  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 = inspectPipelineSource, 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,157 @@
+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();
+  if (observed.attempt !== session.observed.attempt)
+    throw new Error("Channel receipt belongs to a superseded attempt");
+  const root = recordDigest(receipt);
+  const eventKey = `${phase}:${state}:${root}`;
+  const store = host.materialStore(session);
+  const prior = observed.history
+    .at(-1)
+    .events.find((event) => event.payload.eventKey === eventKey);
+  if (prior) {
+    if (
+      prior.node !== phase ||
+      prior.payload.state !== state ||
+      prior.payload.reason !== reason ||
+      prior.payload.materials.length !== 1 ||
+      recordDigest(await store.read(prior.payload.materials[0])) !== root
+    )
+      throw new Error("Channel retry changed its immutable receipt");
+    return observed;
+  }
+  const reference = await store.retain(
+    `${phase}/${root.slice(7)}`,
+    receipt,
+    "provider-readback",
+  );
+  return session.progress.progress({
+    attempt: observed.attempt,
+    phase,
+    state,
+    eventKey,
+    reason,
+    materials: [reference],
+    expectedHead: observed.head,
+  });
+}
+
+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 qualification = await host.qualifyChannel(
+    live.source,
+    live.targetBranch,
+  );
+  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",
+      qualification,
+      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/channel-source.js

@@ -0,0 +1,53 @@
+import { recordDigest } from "../../release/discussion/envelope.js";
+import { selectProductPublicationIntent } from "../../release/product-publication.js";
+import { pipelineExpectedProducts } from "../../publication/pipeline/plan.js";
+import { githubPipelineVersion } from "../../providers/github/pipeline-version.js";
+
+// This read-only qualification must precede both required checks and queue
+// admission. Publication repeats the Rust-owned decision after protected merge.
+export async function qualifyPipelineChannelSource(source, branch, host) {
+  if (branch.startsWith("dev/")) return null;
+  const admitted = await host.source.source(source.commit, source.configPath);
+  if (recordDigest(admitted.identity) !== recordDigest(source))
+    throw new Error("Channel qualification source identity drift");
+  const { plan } = admitted;
+  const routes = plan.channels.filter(
+    (route) => route.to === branch && route.operation !== "develop",
+  );
+  if (routes.length !== 1)
+    throw new Error("Channel qualification requires one publication route");
+  const route = routes[0];
+  const from = `${route.operation === "alpha" ? "dev" : "alpha"}/${branch.split("/").slice(1).join("/")}`;
+  if (["alpha", "stable"].includes(route.operation) && route.from !== from)
+    throw new Error("Channel source and target version lines must match");
+  const version = await githubPipelineVersion(
+    host.request,
+    host.repository,
+  ).inspect(source, plan.version);
+  const selection = selectProductPublicationIntent({
+    channel: route.operation === "alpha" ? "alpha" : "stable",
+    targetRef: branch,
+    sourceSha: source.commit,
+    sourceTimestamp: version.sourceTimestamp,
+    repository: source.repository,
+    artifactKind: "custom",
+    requiredArtifactsRoot: recordDigest(pipelineExpectedProducts(plan)),
+    candidateVersion: version.version,
+    observedVersions: [],
+  });
+  if (
+    plan.version.strategy === "anchored" &&
+    selection.version !== version.version
+  )
+    throw new Error("Anchored channel source requires a materialized version");
+  const body = {
+    schema: "buildchain.pipeline-channel-source-qualification/v1",
+    source,
+    route,
+    contractRoot: recordDigest(plan),
+    version: version.version,
+    versionFilesRoot: recordDigest(version.files),
+    selection,
+  };
+  return { ...body, root: recordDigest(body) };
+}

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