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

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

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

@@ -0,0 +1,118 @@
+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 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 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");
+  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,
+    ),
+  };
+}

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

@@ -0,0 +1,198 @@
+import { execFileSync } from "node:child_process";
+import { recordDigest } from "../../release/discussion/envelope.js";
+import { sourceQualificationPredicates } from "../../dev-delivery/source-proof/predicates.js";
+import { createNativeCommandContract } from "../../dev-delivery/dev-delivery-warrant.js";
+import { withPipelineSourceObjects } from "../../providers/github/pipeline-checkout.js";
+import { pipelinePlatforms } from "./platforms.js";
+import { pipelineCandidateRoot } from "./reconcile.js";
+import { consumerWorkflows } from "../../consumer/contract/entries.js";
+import { pipelineRunEntry } from "../../providers/github/pipeline-run-entry.js";
+import {
+  PIPELINE_BUILD_QUALIFICATION,
+  qualifyPipelineBuild,
+} from "./build-qualification.js";
+
+const quote = (value) => `'${value.replaceAll("'", "'\\''")}'`;
+
+export function qualifyPipelineSourceRun(run, current, build) {
+  const source = current.generation.source;
+  const pull = run.pull_requests?.find(
+    (pr) => pr.number === current.intent.source.pullRequest,
+  );
+  if (
+    !Number.isSafeInteger(run.id) ||
+    run.id < 1 ||
+    run.status !== "completed" ||
+    run.conclusion !== "success" ||
+    ![
+      "pull_request",
+      "repository_dispatch",
+      "pull_request_review",
+      "workflow_dispatch",
+    ].includes(run.event) ||
+    run.repository?.full_name !== current.intent.repository ||
+    (run.event === "pull_request" && run.head_sha !== source.commit) ||
+    (run.event === "pull_request" &&
+      pull?.base?.sha !== current.generation.baseCommit)
+  )
+    throw new Error(
+      "Pipeline source run does not qualify the exact PR generation",
+    );
+  if (build?.schema === PIPELINE_BUILD_QUALIFICATION) {
+    const verified = qualifyPipelineBuild({ ...build, source });
+    if (
+      recordDigest(verified) !== recordDigest(build) ||
+      build.runId !== run.id ||
+      build.runAttempt !== run.run_attempt ||
+      build.outcome !== "success"
+    )
+      throw new Error(
+        "Recovered source run does not bind complete independently qualified product segments",
+      );
+  } else if (run.event !== "pull_request") {
+    const { root, ...body } = build || {};
+    if (
+      root !== recordDigest(body) ||
+      body.schema !== "buildchain.pipeline-build-readback/v1" ||
+      body.runId !== run.id ||
+      body.runAttempt !== run.run_attempt ||
+      body.outcome !== "success" ||
+      recordDigest(body.source) !== recordDigest(source)
+    )
+      throw new Error(
+        "Attempt wake requires retained exact product build provider readback",
+      );
+  }
+  pipelineEntry(run);
+  return run;
+}
+
+function pipelineEntry(run) {
+  return pipelineRunEntry(run).channel;
+}
+
+function predicateInput(directory, current, run) {
+  const source = current.generation.source;
+  for (const [file, expected] of Object.entries(
+    consumerWorkflows(pipelineEntry(run), source.configPath),
+  )) {
+    const bytes = execFileSync(
+      "git",
+      ["-C", directory, "show", `${source.commit}:${file}`],
+      { encoding: "utf8", maxBuffer: 1024 * 1024 },
+    );
+    if (bytes !== expected)
+      throw new Error(
+        "Qualified source changed the minimal consumer workflow contract",
+      );
+  }
+  const paths = execFileSync(
+    "git",
+    ["-C", directory, "ls-tree", "-r", "--name-only", "-z", source.commit],
+    { maxBuffer: 32 * 1024 * 1024 },
+  )
+    .toString("utf8")
+    .split("\0")
+    .filter(Boolean)
+    .sort();
+  if (
+    !paths.length ||
+    paths.length > 50_000 ||
+    paths.some((file) => /[\r\n]/u.test(file))
+  )
+    throw new Error(
+      "Pipeline source inventory exceeds its qualification contract",
+    );
+  const policyPaths = paths.filter(
+    (file) =>
+      file === source.configPath || file.startsWith(".github/workflows/"),
+  );
+  const dependencies = paths.filter((file) =>
+    /(?:^|\/)(?:package(?:-lock)?\.json|pnpm-lock\.yaml|yarn\.lock|Cargo\.(?:toml|lock)|go\.(?:mod|sum))$/u.test(
+      file,
+    ),
+  );
+  return {
+    cwd: directory,
+    repository: current.intent.repository,
+    protectedBase: current.intent.source.targetBranch,
+    sourceHead: source.commit,
+    qualifiedBase: current.generation.baseCommit,
+    nodeVersion: "24",
+    workingDirectory: ".",
+    policyPaths: JSON.stringify(policyPaths),
+    closurePaths: JSON.stringify(paths),
+    dependencyPaths: JSON.stringify(
+      dependencies.length ? dependencies : policyPaths,
+    ),
+    requiredContexts: JSON.stringify(["check"]),
+  };
+}
+
+export async function preparePipelineDelivery(
+  { current, run, build, runtimeSha, token, plan },
+  withObjects = withPipelineSourceObjects,
+) {
+  qualifyPipelineSourceRun(run, current, build);
+  if (!/^[0-9a-f]{40}$/u.test(runtimeSha || ""))
+    throw new Error("Pipeline delivery requires the prepared exact runtime");
+  const source = current.generation.source;
+  const platforms = plan
+    ? pipelinePlatforms(plan).map((entry) => entry.platform)
+    : ["linux-x64"];
+  const nativePlatform = platforms.includes("linux-x64")
+    ? "linux-x64"
+    : platforms[0];
+  const predicates = await withObjects(
+    {
+      repository: current.intent.repository,
+      sourceHead: source.commit,
+      baseCommit: current.generation.baseCommit,
+      token,
+    },
+    (directory) =>
+      sourceQualificationPredicates(predicateInput(directory, current, run)),
+  );
+  // Native composition owns .buildchain/candidate beside the prepared runtime.
+  // Do not bind one job's absolute workspace path into another runner's command.
+  const nativeCommand = `node ../runtime/packages/core/workflow/commands/pipeline-build.mjs --platform ${nativePlatform} --config-path ${quote(source.configPath)}`;
+  const environmentRoot = recordDigest({
+    schema: "buildchain.pipeline-native-environment/v1",
+    runtimeSha,
+    node: "24",
+    platform: nativePlatform,
+    sourceContract: source.contract,
+  });
+  return {
+    "target-branch": current.intent.source.targetBranch,
+    "expected-pr-number": current.intent.source.pullRequest,
+    "expected-head-sha": source.commit,
+    "source-workflow-run-id": run.id,
+    "pipeline-attempt": current.identity.id,
+    "delivery-warrant-mode": "required",
+    "delivery-class": "native-proof-required",
+    "source-root": pipelineCandidateRoot(current),
+    "source-identity-root": predicates.sourceIdentityRoot,
+    "source-patch-root": predicates.sourcePatchRoot,
+    "plan-root": predicates.planRoot,
+    "closure-root": predicates.closureRoot,
+    "dependency-root": predicates.dependencyRoot,
+    "toolchain-root": predicates.toolchainRoot,
+    "environment-root": environmentRoot,
+    "native-command": nativeCommand,
+    "native-platform": nativePlatform,
+    "native-command-root":
+      createNativeCommandContract(nativeCommand).commandRoot,
+    "affected-paths-json": JSON.stringify(predicates.affectedPaths),
+    "shard-evidence-roots-json": "[]",
+    "required-status-checks": "check",
+    "ready-label": "ready",
+    "landing-mode": "queue",
+    "queue-admission-context": "Queue admission lease",
+    "active-lease-context": "Queue family lease/exact",
+    "require-approval": true,
+    "same-repository-only": true,
+    "max-merges": 1,
+    "dry-run": false,
+  };
+}

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

@@ -0,0 +1,84 @@
+import { admitEvent } from "../../consumer/contract/entries.js";
+
+const SHA = /^[0-9a-f]{40}$/u;
+function prNumber(value) {
+  if (!Number.isSafeInteger(value) || value < 1)
+    throw new Error("Pipeline event requires an exact PR number");
+  return value;
+}
+
+// Webhook payloads select readback work only. They never carry source, approval,
+// Warrant or mutation authority. Live provider state owns every decision.
+export function pipelineEvent(name, event, repository) {
+  admitEvent(name, event.action || "");
+  if (event.repository?.full_name !== repository)
+    throw new Error("Pipeline event repository mismatch");
+  if (
+    ["pull_request", "pull_request_target", "pull_request_review"].includes(
+      name,
+    )
+  )
+    return {
+      kind: "pull-request",
+      pullRequest: prNumber(event.pull_request?.number),
+      terminalOnly: name === "pull_request_target",
+    };
+  if (name === "repository_dispatch") {
+    const payload = event.client_payload;
+    if (
+      !payload ||
+      Object.keys(payload).length !== 1 ||
+      !/^attempt-[0-9a-f]{64}$/u.test(payload.attempt || "")
+    )
+      throw new Error("Attempt wake requires only its exact business selector");
+    return { kind: "attempt", attempt: payload.attempt, terminalOnly: false };
+  }
+  if (name === "merge_group") {
+    const group = event.merge_group;
+    if (
+      !SHA.test(group?.head_sha || "") ||
+      !SHA.test(group?.base_sha || "") ||
+      !group.base_ref?.startsWith("refs/heads/")
+    )
+      throw new Error("Merge group requires exact provider coordinates");
+    return {
+      kind: "merge-group",
+      commit: group.head_sha,
+      baseCommit: group.base_sha,
+      branch: group.base_ref.slice(11),
+      terminalOnly: false,
+    };
+  }
+  if (!event.ref?.startsWith("refs/heads/") || event.deleted === true)
+    return { kind: "ignore", reason: "not-a-live-branch" };
+  if (!SHA.test(event.after || ""))
+    throw new Error("Branch event requires an exact commit");
+  // Internal journal and lock writes must not recursively wake the pipeline.
+  const branch = event.ref.slice(11);
+  return /^(?:dev|alpha|release|publish-gate)\//u.test(branch)
+    ? { kind: "branch", branch, commit: event.after, terminalOnly: false }
+    : { kind: "ignore", reason: "not-a-channel-branch" };
+}
+
+function matches(pattern, branch) {
+  const escaped = pattern
+    .split("*")
+    .map((part) => part.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&"))
+    .join(".*");
+  return new RegExp(`^${escaped}$`, "u").test(branch);
+}
+
+export function channelRoute(plan, pullRequest, repository) {
+  if (
+    pullRequest.base?.repo?.full_name !== repository ||
+    pullRequest.head?.repo?.full_name !== repository
+  )
+    throw new Error("Pipeline delivery requires a repository-owned channel PR");
+  const routes = plan.channels.filter(
+    (channel) =>
+      channel.to === pullRequest.base.ref &&
+      matches(channel.from, pullRequest.head.ref),
+  );
+  if (routes.length > 1) throw new Error("Ambiguous protected channel route");
+  return routes[0] || null;
+}

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

@@ -0,0 +1,42 @@
+import { recordDigest } from "../../release/discussion/envelope.js";
+
+export const STOP_REQUESTED = "pipeline-stop-requested:";
+
+// Credentialed controllers observe this source/attempt fence before Warrant
+// renewal and finalization. The isolated native job receives no read token.
+// Stopping renewal does not release its Warrant: provider-terminal native/seal
+// evidence is still required before a separate controller can transfer ownership.
+export function assertPipelineExecution(observed, expected) {
+  if (
+    observed.attempt !== expected.attempt ||
+    observed.generation !== expected.generation ||
+    observed.intent.id !== expected.intent
+  )
+    throw new Error("Pipeline execution lost its current attempt fence");
+  const current = observed.history.at(-1);
+  if (
+    !current ||
+    recordDigest(current.generation.source) !== expected.sourceRoot
+  )
+    throw new Error("Pipeline execution source fence changed");
+  if (
+    ["cancelled", "superseded", "failure", "complete"].includes(
+      observed.status,
+    ) ||
+    Object.values(observed.phases).some((record) =>
+      record.payload.reason.startsWith(STOP_REQUESTED),
+    )
+  )
+    throw new Error("Pipeline execution has a terminal or requested stop");
+  return true;
+}
+
+export function pipelineHeartbeat(journal, expected, warrantHeartbeat) {
+  return async () => {
+    assertPipelineExecution(await journal.read(), expected);
+    await warrantHeartbeat();
+    // Catch cancellation that raced the provider heartbeat without granting
+    // another controller interval from the stale pre-heartbeat read.
+    assertPipelineExecution(await journal.read(), expected);
+  };
+}