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

package/packages/core/workflow/pipeline/recovery-unrecorded-build.js

@@ -0,0 +1,74 @@
+import { recordDigest } from "../../release/discussion/envelope.js";
+import { retainedRecoveryEvidence } from "./recovery-session.js";
+import { buildReadbackPlatforms } from "./build-qualification.js";
+
+// Cancellation can prevent the recorder from running after product jobs finish.
+// Recover those exact provider jobs, plus previously admitted segments, without
+// claiming that an unstarted or failed platform succeeded.
+export async function unrecordedRecoveryBuild(
+  session,
+  source,
+  platforms,
+  host,
+) {
+  const current = session.observed.history.at(-1);
+  const phase = current.phases.build;
+  if (!phase) return [];
+  const segments = [];
+  if (current.identity.requestKey.startsWith("recover:")) {
+    const { evidence } = await retainedRecoveryEvidence(session, host);
+    for (const segment of evidence.build.segments) {
+      const old = segment.readback;
+      const fresh = await host.runs.build(
+        old.runId,
+        old.runAttempt,
+        source,
+        buildReadbackPlatforms(old),
+      );
+      if (
+        recordDigest(old.source) !== recordDigest(source) ||
+        recordDigest(old) !== recordDigest(fresh)
+      )
+        throw new Error(
+          "Interrupted recovery lost its previously qualified build segment",
+        );
+      segments.push(segment);
+    }
+  }
+  const writer = phase.payload.writer;
+  const { run, jobs } = await host.runs.read(
+    Number(writer.runId),
+    Number(writer.runAttempt),
+  );
+  if (
+    run.status !== "completed" ||
+    run.repository?.full_name !== host.repository ||
+    run.head_repository?.full_name !== host.repository
+  )
+    throw new Error(
+      "Unrecorded build requires terminal same-repository provider execution",
+    );
+  const completed = platforms.filter((platform) => {
+    const name = `Build product (${platform})`;
+    const matches = jobs.filter(
+      (job) => job.name === name || job.name.endsWith(` / ${name}`),
+    );
+    if (matches.length > 1)
+      throw new Error("Interrupted build platform identity is ambiguous");
+    return (
+      matches[0]?.status === "completed" && matches[0].conclusion === "success"
+    );
+  });
+  if (completed.length)
+    segments.push({
+      readback: await host.runs.build(
+        Number(writer.runId),
+        Number(writer.runAttempt),
+        source,
+        completed,
+      ),
+      platforms: completed,
+      runtime: phase.runtime,
+    });
+  return segments;
+}

package/packages/core/workflow/pipeline/runtime-source.js

@@ -0,0 +1,111 @@
+import { githubAttemptJournal } from "../../providers/github/attempt-journal.js";
+import { githubAttemptIndex } from "../../providers/github/attempt-index.js";
+import { githubJsonClient } from "../../providers/github/json-client.js";
+import { readBusinessAttempt } from "../attempt/reader.js";
+
+async function retainedAttempt(attempt, repository, token, lookup) {
+  const request = githubJsonClient({
+    token,
+    userAgent: "buildchain-pipeline-runtime-source",
+  });
+  const index =
+    lookup ||
+    githubAttemptIndex(request, githubAttemptJournal(request), repository);
+  const loaded = await index.resolve(attempt);
+  const observed = readBusinessAttempt(loaded.snapshot);
+  if (observed.intent.repository !== repository)
+    throw new Error(
+      "Foreign pipeline selector cannot select the runtime source",
+    );
+  return observed;
+}
+
+function sourceOf(observed) {
+  const current = observed.history.at(-1);
+  return {
+    repository: observed.intent.repository,
+    sha: current.generation.source.commit,
+    ref: `refs/pull/${observed.intent.source.pullRequest}/head`,
+  };
+}
+
+export async function pipelineRuntimeSource(
+  attempt,
+  repository,
+  token,
+  lookup,
+) {
+  return (await pipelineRuntimeContinuation(attempt, repository, token, lookup))
+    .source;
+}
+
+export async function pipelineRuntimeContinuation(
+  attempt,
+  repository,
+  token,
+  lookup,
+) {
+  const observed = await retainedAttempt(attempt, repository, token, lookup);
+  if (observed.attempt !== attempt)
+    throw new Error(
+      "Historical or foreign pipeline selector cannot select the runtime source",
+    );
+  const current = observed.history.at(-1);
+  return {
+    source: sourceOf(observed),
+    recovery: current.identity.requestKey.startsWith("recover:")
+      ? {
+          attempt,
+          recordRoot: current.events[0].id,
+          runtime: current.events[0].runtime,
+        }
+      : null,
+  };
+}
+
+// Read-only bootstrap can locate a directly recovered successor after a lost
+// response. The credentialed recovery controller independently admits its exact
+// entry/runtime request before any replay or provider effect.
+export async function pipelineRecoveryRuntimeSource(
+  attempt,
+  repository,
+  token,
+  lookup,
+) {
+  return (
+    await pipelineRecoveryContinuation(attempt, repository, token, lookup)
+  ).source;
+}
+
+export async function pipelineRecoveryContinuation(
+  attempt,
+  repository,
+  token,
+  lookup,
+) {
+  const observed = await retainedAttempt(attempt, repository, token, lookup);
+  const current = observed.history.at(-1);
+  const selected = observed.history.find(
+    (item) => item.identity.id === attempt,
+  );
+  if (
+    !selected ||
+    (observed.attempt !== attempt &&
+      (current.identity.predecessor !== attempt ||
+        !current.identity.requestKey.startsWith("recover:") ||
+        current.generation.id !== selected.generation.id))
+  )
+    throw new Error(
+      "Historical recovery selector is not the direct current recovery predecessor",
+    );
+  return {
+    source: sourceOf(observed),
+    recovery: current.identity.requestKey.startsWith("recover:")
+      ? {
+          attempt: current.identity.id,
+          recordRoot: current.events[0].id,
+          runtime: current.events[0].runtime,
+        }
+      : null,
+  };
+}

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

@@ -0,0 +1,106 @@
+import { readBusinessAttempt } from "../attempt/reader.js";
+import { openPipelineSession, resumePipelineSession } from "./session.js";
+import { sourceGeneration } from "../attempt/identity.js";
+
+async function successorSelection(
+  session,
+  admission,
+  event,
+  payload,
+  inputs,
+  host,
+) {
+  if (
+    !["superseded", "cancelled"].includes(session.observed.status) ||
+    event.terminalOnly ||
+    admission.live.state !== "open" ||
+    admission.live.targetBranch !== session.intent.source.targetBranch
+  )
+    return { session, admission };
+  const next = await host.source.observe(
+    session.intent.source.pullRequest,
+    inputs,
+  );
+  if (!next.eligible) return { session, admission };
+  const changed =
+    sourceGeneration(session.intent, next.live.source, next.live.baseCommit)
+      .id !== session.observed.generation;
+  if (
+    !changed &&
+    !["reopened", "enqueued", "ready_for_review", "labeled"].includes(
+      payload.action,
+    )
+  )
+    return { session, admission };
+  await host.notifyTerminal?.(session);
+  return {
+    session: await openPipelineSession(
+      { admission: next, ...host, successor: true },
+      host,
+    ),
+    admission: next,
+  };
+}
+
+// Event branch names are lookup hints only. The immutable intent and live PR
+// readback decide whether an old route still needs cleanup before a new route.
+export async function selectPipelineSession(event, payload, inputs, host) {
+  if (event.kind === "attempt") {
+    const session = await resumePipelineSession(
+      { ...host, attempt: event.attempt },
+      host,
+    );
+    const admission = await host.source.observeIntent(
+      session.intent,
+      session.observed.history.at(-1).generation,
+      inputs,
+    );
+    return successorSelection(session, admission, event, payload, inputs, host);
+  }
+  if (event.kind !== "pull-request")
+    throw new Error("Not a PR pipeline selection");
+  const pr = await host.request(
+    `/repos/${host.repository}/pulls/${event.pullRequest}`,
+  );
+  const branches = [
+    ...new Set(
+      [payload.changes?.base?.ref?.from, pr.base?.ref].filter(Boolean),
+    ),
+  ];
+  for (const branch of branches) {
+    if (!/^(?:dev|alpha|release|publish-gate)\/[A-Za-z0-9/._-]+$/u.test(branch))
+      continue;
+    const retained = await host.provider.lookup(
+      host.repository,
+      event.pullRequest,
+      branch,
+    );
+    if (!retained) continue;
+    const observed = readBusinessAttempt(retained.snapshot);
+    if (!observed.attempt) continue;
+    if (
+      branch !== pr.base.ref &&
+      ["cancelled", "failure", "superseded", "complete"].includes(
+        observed.status,
+      )
+    )
+      continue;
+    const session = await resumePipelineSession(
+      { ...host, attempt: observed.attempt },
+      host,
+    );
+    const admission = await host.source.observeIntent(
+      session.intent,
+      observed.history.at(-1).generation,
+      inputs,
+    );
+    return successorSelection(session, admission, event, payload, inputs, host);
+  }
+  if (event.terminalOnly || pr.state !== "open") return null;
+  const admission = await host.source.observe(event.pullRequest, inputs);
+  if (!admission.eligible) return null;
+  return {
+    session: await openPipelineSession({ admission, ...host }, host),
+    admission,
+  };
+}

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

@@ -0,0 +1,72 @@
+import { pipelineIntent } from "../attempt/identity.js";
+import { atomicAttemptJournal } from "../attempt/journal.js";
+import { pipelineProgress } from "./progress.js";
+
+export function pipelinePhases(operation) {
+  if (operation === "develop")
+    return ["admission", "build", "review", "warrant", "merge"];
+  if (["alpha", "stable", "major"].includes(operation))
+    return [
+      "admission",
+      "build",
+      "review",
+      "merge",
+      "publish",
+      "distribution",
+      "next-development",
+    ];
+  throw new Error("Unsupported pipeline channel operation");
+}
+
+export async function openPipelineSession(
+  { admission, runtime, writer, successor = false },
+  { provider, index },
+) {
+  if (!admission.eligible || !admission.route || !admission.live.source)
+    throw new Error(
+      "A new pipeline attempt requires an admitted source and channel",
+    );
+  const { live } = admission;
+  const retained = await provider.lookup(
+    live.source.repository,
+    live.pullRequest,
+    admission.route.to,
+  );
+  const intent =
+    retained?.snapshot.intent ||
+    pipelineIntent({
+      repository: live.source.repository,
+      repositoryId: admission.repositoryId,
+      pullRequest: live.pullRequest,
+      targetBranch: admission.route.to,
+      phases: pipelinePhases(admission.route.operation),
+      runtime,
+    });
+  const journal = atomicAttemptJournal(provider, intent);
+  const progress = pipelineProgress(journal, { intent, writer, runtime });
+  const observed = await progress.open(live.source, live.baseCommit, {
+    successor,
+  });
+  await index.retain(intent, observed.attempt);
+  return { intent, journal, progress, observed };
+}
+
+export async function resumePipelineSession(
+  { attempt, runtime, writer },
+  { provider, index },
+) {
+  const retained = await index.resolve(attempt);
+  const intent = retained.snapshot.intent;
+  const journal = atomicAttemptJournal(provider, intent);
+  const observed = await journal.read();
+  if (observed.attempt !== attempt)
+    throw new Error(
+      "Selected attempt is historical; it cannot regain current write authority",
+    );
+  return {
+    intent,
+    journal,
+    observed,
+    progress: pipelineProgress(journal, { intent, writer, runtime }),
+  };
+}

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

@@ -0,0 +1,137 @@
+import {
+  createIntegrationDeliveryProof,
+  verifyIntegrationDeliveryProof,
+} from "../../dev-delivery/dev-delivery-warrant.js";
+import { readBusinessAttempt } from "../attempt/reader.js";
+import { pipelineCandidate } from "./reconcile.js";
+
+async function qualifyWarrant(session, current, queue, materials) {
+  if (current.phases.warrant?.payload.state === "success") return;
+  if (queue.activeWarrant?.phase !== "qualified")
+    throw new Error("Merged pipeline has no qualified active Warrant");
+  const reference = await materials.retain(
+    `warrant/qualified-${queue.stateRoot.slice(7)}`,
+    queue,
+    "provider-readback",
+  );
+  await session.progress.progress({
+    attempt: current.identity.id,
+    phase: "warrant",
+    state: "success",
+    eventKey: `qualified:${queue.stateRoot}`,
+    materials: [reference],
+  });
+}
+
+async function integrationProof(session, fresh, host, materials) {
+  const { queue, current } = fresh;
+  const candidate = pipelineCandidate(queue, current);
+  if (!candidate)
+    throw new Error("Merged pipeline candidate authority is missing");
+  if (candidate.status === "merged") {
+    const reference =
+      current.materials[
+        `merge/proof-${candidate.terminal.evidenceRoot.slice(7)}`
+      ];
+    if (!reference)
+      throw new Error(
+        "Merged Warrant has no retained pre-effect integration proof",
+      );
+    const proof = await materials.read(reference);
+    if (
+      !verifyIntegrationDeliveryProof(proof, {
+        sourceProofRoot: candidate.sourceProofRoot,
+        warrantCandidateId: candidate.candidateId,
+      }).ok
+    )
+      throw new Error("Retained integration proof is invalid");
+    return { candidate, proof, reference };
+  }
+  if (candidate.candidateId !== queue.activeWarrant?.candidateId)
+    throw new Error("Merged candidate is not the active Warrant");
+  await qualifyWarrant(session, current, queue, materials);
+  const readback = await host.integration.observe(current);
+  const proof = createIntegrationDeliveryProof({
+    repository: host.repository,
+    protectedBase: session.intent.source.targetBranch,
+    sourceProofRoot: candidate.sourceProofRoot,
+    warrant: queue.activeWarrant,
+    currentBase: readback.mergeCommit,
+    replayTree: readback.mergeTree,
+    mergeGroupHead: readback.mergeCommit,
+    mergeGroupTree: readback.mergeTree,
+    requiredContextRoots: [readback.build.root, readback.root],
+    verifiedAt: new Date().toISOString(),
+  });
+  const reference = await materials.retain(
+    `merge/proof-${proof.proofRoot.slice(7)}`,
+    proof,
+  );
+  const provider = await materials.retain(
+    `merge/provider-${readback.root.slice(7)}`,
+    readback,
+    "provider-readback",
+  );
+  await session.progress.progress({
+    attempt: current.identity.id,
+    phase: "merge",
+    state: "waiting",
+    eventKey: `merge-request:${proof.proofRoot}`,
+    materials: [reference, provider],
+  });
+  return { candidate, proof, reference };
+}
+
+export async function settlePipeline(session, fresh, delivery, host) {
+  const materials = host.materialStore(session);
+  const { candidate, proof, reference } = await integrationProof(
+    session,
+    fresh,
+    host,
+    materials,
+  );
+  const warrant = fresh.queue.activeWarrant;
+  const result = await delivery.service.settle({
+    expectedOldStateRoot: fresh.queue.stateRoot,
+    pullRequestNumber: candidate.pullRequestNumber,
+    expectedSourceHead: candidate.sourceHead,
+    outcome: "merged",
+    reason: "exact-protected-pipeline-integration",
+    evidenceRoot: proof.proofRoot,
+    execute: true,
+    ...(warrant?.candidateId === candidate.candidateId
+      ? {
+          fencingToken: warrant.fencingToken,
+          leaseGeneration: warrant.generation,
+        }
+      : {}),
+  });
+  if (result.observation.activeWarrant?.candidateId === candidate.candidateId)
+    throw new Error("Merged settlement retained its active Warrant");
+  const receipt = await materials.retain(
+    `merge/settlement-${result.receiptRoot.slice(7)}`,
+    result,
+  );
+  await session.progress.progress({
+    attempt: fresh.attempt,
+    phase: "merge",
+    state: "success",
+    eventKey: `merged:${result.receiptRoot}`,
+    materials: [reference, receipt],
+  });
+  await host.notifyTerminal?.(session);
+  const successor = result.receipt.successorWake;
+  if (successor) {
+    const next = await host.provider.lookup(
+      host.repository,
+      successor.pullRequestNumber,
+      session.intent.source.targetBranch,
+    );
+    if (next) await host.wake(readBusinessAttempt(next.snapshot).attempt);
+  }
+  return {
+    operation: "wait",
+    reason: "protected-delivery-settled",
+    attempt: fresh.attempt,
+  };
+}

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

@@ -0,0 +1,38 @@
+import { githubJsonClient } from "../../providers/github/json-client.js";
+import { githubAttemptJournal } from "../../providers/github/attempt-journal.js";
+import { readBusinessAttempt } from "../attempt/reader.js";
+import { pipelineCandidateRoot } from "./reconcile.js";
+
+export async function wakePipelineCandidate(candidate, connection, ports = {}) {
+  const repository = connection.repository;
+  const request =
+    ports.request ||
+    githubJsonClient({
+      token: connection.token,
+      userAgent: "buildchain-pipeline-wake",
+    });
+  const provider = ports.provider || githubAttemptJournal(request);
+  const branch = candidate.protectedBase || connection.branch;
+  const loaded = await provider.lookup(
+    repository,
+    candidate.pullRequestNumber,
+    branch,
+  );
+  if (!loaded)
+    throw new Error("Warrant handoff has no admitted business intent");
+  const observed = readBusinessAttempt(loaded.snapshot);
+  const current = { ...observed.history.at(-1), intent: observed.intent };
+  if (
+    candidate.sourceHead !== current.generation.source.commit ||
+    candidate.sourceRoot !== pipelineCandidateRoot(current)
+  )
+    throw new Error("Warrant handoff changed its admitted business attempt");
+  await request(`/repos/${repository}/dispatches`, {
+    method: "POST",
+    body: {
+      event_type: "buildchain-attempt-wake",
+      client_payload: { attempt: observed.attempt },
+    },
+  });
+  return observed.attempt;
+}

package/packages/core/workflow/pipeline/web-status.js

@@ -0,0 +1,108 @@
+const labels = {
+  admission: "Source admission",
+  build: "Product verification",
+  review: "Protected review",
+  warrant: "Delivery qualification",
+  merge: "Protected integration",
+  publish: "Product publication",
+  distribution: "Distribution",
+  "next-development": "Next development version",
+};
+const safe = (value) =>
+  String(value || "")
+    .replace(/[\r\n|]/gu, " ")
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replace(/[\\`*_[\]()]/gu, (character) => `\\${character}`)
+    .slice(0, 1000);
+
+export function pipelineWebStatus(observed, discussionUrl = "") {
+  const { intent, attempt } = observed;
+  const repositoryUrl = `https://github.com/${intent.repository}`;
+  const current = observed.history.at(-1);
+  if (!current) throw new Error("Pipeline status requires an admitted attempt");
+  const table = [
+    "| Step | State |",
+    "| --- | --- |",
+    ...intent.expectedNodes.map(
+      (phase) =>
+        `| ${labels[phase]} | ${safe(observed.phases[phase]?.payload.state || "pending")} |`,
+    ),
+  ].join("\n");
+  const lines = [
+    `## Buildchain · PR #${intent.source.pullRequest}`,
+    `Status: **${safe(observed.status)}**. ${safe(observed.reason)}`,
+    `Attempt: \`${attempt}\``,
+    `[Pull request](${repositoryUrl}/pull/${intent.source.pullRequest}) · ` +
+      `[Source ${current.generation.source.commit.slice(0, 7)}](${repositoryUrl}/commit/${current.generation.source.commit})`,
+    table,
+  ];
+  const publisher = [...observed.history]
+    .reverse()
+    .find(
+      (item) =>
+        item.generation.id === current.generation.id &&
+        item.phases.publish?.payload.state === "success",
+    );
+  const published = Boolean(publisher);
+  if (published && observed.missing.length)
+    lines.push(
+      `Publication succeeded and its immutable results remain preserved. The whole attempt is incomplete: ${observed.missing.map((phase) => labels[phase]).join(", ")}.`,
+    );
+  if (publisher && publisher.identity.id !== current.identity.id)
+    lines.push(
+      `Publication succeeded in predecessor \`${publisher.identity.id}\`. Current qualification and remaining steps are shown separately above.`,
+    );
+  if (current.identity.predecessor)
+    lines.push(
+      `Recovered from \`${current.identity.predecessor}\`; its original evidence remains in history.`,
+    );
+  if (observed.status !== "complete")
+    lines.push(
+      `[Recover this attempt](${repositoryUrl}/actions/workflows/buildchain-recover.yml): choose Run workflow and enter the exact attempt above. Select a repaired runtime only when needed.`,
+    );
+  lines.push(
+    "Execution links provide the provider's ordinary cancellation control. Cancellation stops remaining work; it does not undo completed publication.",
+  );
+  const runs = [
+    ...new Map(
+      current.runs.map((run) => [`${run.runId}:${run.runAttempt}`, run]),
+    ).values(),
+  ];
+  for (const run of runs.slice(-10))
+    lines.push(
+      `[Execution ${run.runId}, attempt ${run.runAttempt}](${repositoryUrl}/actions/runs/${run.runId}/attempts/${run.runAttempt})`,
+    );
+  if (discussionUrl) {
+    const url = new URL(discussionUrl);
+    if (
+      url.origin !== "https://github.com" ||
+      !url.pathname.startsWith(`/${intent.repository}/discussions/`) ||
+      !/\/discussions\/[1-9][0-9]*$/u.test(url.pathname) ||
+      url.search ||
+      url.hash ||
+      url.username ||
+      url.password
+    )
+      throw new Error(
+        "Pipeline evidence link belongs to another provider or repository",
+      );
+    lines.push(`[Retained evidence](${discussionUrl})`);
+  }
+  return `${lines.join("\n\n")}\n`;
+}
+
+export async function projectPipelineStatus(session, { project, core }) {
+  let result;
+  try {
+    result = await project(session);
+  } catch {
+    core.warning(
+      "Discussion projection unavailable; canonical attempt evidence remains retained.",
+    );
+  }
+  const observed = await session.journal.read();
+  await core.summary.addRaw(pipelineWebStatus(observed, result?.url)).write();
+  return result || { url: "", journalHead: observed.head };
+}

package/scripts/build-release-discussion-reader.mjs

@@ -10,25 +10,29 @@ try {
   await build({
     entry: {
       "release-discussion": "packages/core/release/discussion/reader-entry.js",
+      "business-attempt": "packages/core/workflow/attempt/reader-entry.js",
     },
     outDir: output,
     format: ["cjs"],
     target: "node24",
     platform: "node",
     splitting: false,
+    noExternal: ["smol-toml"],
     sourcemap: false,
     minify: false,
     clean: false,
     outExtension: () => ({ js: ".cjs" }),
     silent: true,
   });
-  if (
-    check &&
-    !fs
-      .readFileSync(path.join(output, "release-discussion.cjs"))
-      .equals(fs.readFileSync("dist/readers/release-discussion.cjs"))
-  )
-    throw new Error("Historical release reader bundle is stale");
+  if (check)
+    for (const name of ["release-discussion", "business-attempt"]) {
+      if (
+        !fs
+          .readFileSync(path.join(output, `${name}.cjs`))
+          .equals(fs.readFileSync(`dist/readers/${name}.cjs`))
+      )
+        throw new Error(`Historical ${name} reader bundle is stale`);
+    }
 } finally {
   if (check) fs.rmSync(output, { recursive: true, force: true });
 }