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

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

@@ -0,0 +1,129 @@
+import { readBusinessAttempt } from "../attempt/reader.js";
+import { atomicAttemptJournal } from "../attempt/journal.js";
+import { businessAttempt } from "../attempt/identity.js";
+import { attemptRecord } from "../attempt/records.js";
+import { pipelineProgress } from "./progress.js";
+import { recoveryRequestKey, verifyRecoveryPlan } from "./recovery-plan.js";
+import { recordDigest } from "../../release/discussion/envelope.js";
+
+export async function selectRecoveryAttempt(attempt, host, entry) {
+  const loaded = await host.index.resolve(attempt);
+  const journal = atomicAttemptJournal(host.provider, loaded.snapshot.intent);
+  const observed = await journal.read();
+  if (observed.intent.repository !== host.repository)
+    throw new Error("Recovery cannot cross consumer repositories");
+  const selected = observed.history.find(
+    (item) => item.identity.id === attempt,
+  );
+  if (!selected)
+    throw new Error("Recovery attempt is absent from canonical history");
+  const key = recoveryRequestKey(attempt, host.runtime, entry);
+  const current = observed.history.at(-1);
+  const duplicate = current.identity.id !== attempt;
+  if (
+    duplicate &&
+    (current.identity.predecessor !== attempt ||
+      current.identity.requestKey !== key)
+  )
+    throw new Error(
+      `Historical recovery cannot fork current ownership; select ${current.identity.id}`,
+    );
+  return {
+    intent: observed.intent,
+    journal,
+    observed,
+    selected,
+    duplicate,
+    progress: pipelineProgress(journal, { intent: observed.intent, ...host }),
+  };
+}
+
+export async function openRecoveryAttempt(session, plan, host, evidence) {
+  const observed = await session.journal.read();
+  verifyRecoveryPlan(plan, observed);
+  if (recordDigest(plan.runtime) !== recordDigest(host.runtime))
+    throw new Error("Recovery executor differs from the admitted runtime");
+  if (evidence === undefined || recordDigest(evidence) !== plan.evidenceRoot)
+    throw new Error(
+      "Recovery requires the actual qualified evidence bound by its plan",
+    );
+  const generation = observed.history.at(-1).generation;
+  const identity = businessAttempt({
+    intent: session.intent,
+    generation,
+    predecessor: observed.attempt,
+    requestKey: plan.requestKey,
+  });
+  const pending = {
+    ...session,
+    observed: { ...observed, history: [{ identity, generation }] },
+  };
+  const reference = await host
+    .materialStore(pending)
+    .retain("recovery/admission", plan);
+  const evidenceReference = await host
+    .materialStore(pending)
+    .retain("recovery/evidence", evidence);
+  const root = attemptRecord({
+    intent: session.intent,
+    attempt: identity,
+    generation,
+    writer: host.writer,
+    runtime: host.runtime,
+    eventKey: `open:${identity.id}`,
+    phase: "attempt",
+    state: "running",
+    reason:
+      "Explicit recovery; completed effects remain immutable in predecessor history",
+    materials: [reference, evidenceReference],
+  });
+  const opened = await session.journal.append(root, observed.head);
+  await host.index.retain(session.intent, identity.id);
+  return {
+    ...session,
+    observed: opened,
+    duplicate: false,
+    progress: pipelineProgress(session.journal, {
+      intent: session.intent,
+      ...host,
+    }),
+  };
+}
+
+export async function retainedRecoveryPlan(session, host) {
+  const current = session.observed.history.at(-1);
+  const references = current.events[0].payload.materials.filter(
+    (item) => item.id === "recovery/admission",
+  );
+  if (references.length !== 1)
+    throw new Error("Recovery successor has no unique retained admission plan");
+  const plan = await host.materialStore(session).read(references[0]);
+  const records = session.observed.snapshot.records.filter((record) =>
+    session.observed.history
+      .slice(0, -1)
+      .some((item) => item.identity.id === record.attempt),
+  );
+  const predecessor = readBusinessAttempt({ intent: session.intent, records });
+  verifyRecoveryPlan(plan, predecessor);
+  if (
+    current.identity.predecessor !== plan.predecessor ||
+    current.identity.requestKey !== plan.requestKey
+  )
+    throw new Error("Recovery successor does not bind its immutable admission");
+  return plan;
+}
+
+export async function retainedRecoveryEvidence(session, host) {
+  const plan = await retainedRecoveryPlan(session, host);
+  const references = session.observed.history
+    .at(-1)
+    .events[0].payload.materials.filter(
+      (item) => item.id === "recovery/evidence",
+    );
+  if (references.length !== 1)
+    throw new Error("Recovery successor lacks its unique qualified evidence");
+  const evidence = await host.materialStore(session).read(references[0]);
+  if (recordDigest(evidence) !== plan.evidenceRoot)
+    throw new Error("Recovery evidence differs from its immutable admission");
+  return { plan, evidence };
+}

package/packages/core/workflow/pipeline/recovery-transition.js

@@ -0,0 +1,135 @@
+import { recordDigest } from "../../release/discussion/envelope.js";
+import { planPipelineRecovery } from "./recovery-plan.js";
+import { settleRecoveryOwnership } from "./recovery-ownership-settlement.js";
+import { qualifyRecoveryIntegration } from "./recovery-integration.js";
+import { retainedRecoveryEvidence } from "./recovery-session.js";
+
+export async function terminateRecoveryPredecessor(
+  session,
+  executions,
+  ownership,
+  host,
+) {
+  const observed = await session.journal.read();
+  if (observed.head !== session.observed.head || !executions.terminal)
+    throw new Error(
+      "Recovery predecessor advanced after terminal execution readback",
+    );
+  if (["failure", "cancelled", "superseded"].includes(observed.status))
+    return session;
+  if (observed.status === "complete")
+    throw new Error("Completed attempt has no recovery work");
+  const evidence = { executions, ownership };
+  const material = await host
+    .materialStore(session)
+    .retain("recovery/predecessor-terminal", evidence, "provider-readback");
+  const after = await session.progress.progress({
+    attempt: observed.attempt,
+    phase: observed.missing[0],
+    state: "cancelled",
+    eventKey: `recovery-terminal:${recordDigest(evidence)}`,
+    reason:
+      "Explicit recovery after provider executions became terminal; native ownership remains fenced until successor admission",
+    materials: [material],
+    expectedHead: observed.head,
+  });
+  return { ...session, observed: after };
+}
+
+export function recoveryNodePlan(session, evidence, entry, host) {
+  const cleanup = Boolean(evidence.ownership?.candidate);
+  const nodes = session.intent.expectedNodes.map((phase) => {
+    if (phase === "admission")
+      return {
+        phase,
+        operation: cleanup ? "reconcile" : "reuse",
+        reason:
+          "Exact original source and protected route independently reobserved",
+        evidenceRoots: [recordDigest(evidence.admitted)],
+      };
+    if (phase === "build")
+      return {
+        phase,
+        operation: evidence.build.scheduled.length
+          ? "execute"
+          : cleanup
+            ? "reconcile"
+            : "reuse",
+        reason: evidence.build.reason,
+        evidenceRoots: [evidence.build.root],
+      };
+    return {
+      phase,
+      operation: "reconcile",
+      reason:
+        "Reobserve protected provider authority and execute remaining work",
+      evidenceRoots: [],
+    };
+  });
+  return planPipelineRecovery({
+    observed: session.observed,
+    runtime: host.runtime,
+    entry,
+    nodes,
+    evidenceRoot: recordDigest(evidence),
+  });
+}
+
+export async function replayRecoveryAdmission(session, host) {
+  session.observed = await session.journal.read();
+  const { plan, evidence } = await retainedRecoveryEvidence(session, host);
+  const value = {
+    schema: "buildchain.pipeline-recovery-source/v1",
+    recoveryPlanRoot: plan.root,
+    predecessor: plan.predecessor,
+    source: evidence.admitted.source.identity,
+    admission: evidence.admitted.admission,
+    caller: evidence.admitted.caller,
+  };
+  const prior = session.observed.phases.admission;
+  if (prior?.payload.state === "success") {
+    if (
+      prior.payload.state !== "success" ||
+      prior.payload.materials.length !== 1 ||
+      recordDigest(
+        sourceFields(
+          await host.materialStore(session).read(prior.payload.materials[0]),
+        ),
+      ) !== recordDigest(value)
+    )
+      throw new Error(
+        "Recovery admission replay differs from its immutable source qualification",
+      );
+    return session;
+  }
+  const qualified = evidence.admitted.admission.live.merged
+    ? await qualifyRecoveryIntegration(
+        session,
+        evidence.admitted.admission,
+        host,
+      )
+    : null;
+  const ownership = await settleRecoveryOwnership(session, qualified, host);
+  const reference = await host
+    .materialStore(session)
+    .retain(
+      "source/recovery-admission",
+      { ...value, ownership },
+      "provider-readback",
+    );
+  await session.progress.progress({
+    attempt: session.observed.attempt,
+    phase: "admission",
+    state: "success",
+    eventKey: `recovery-source:${plan.root}`,
+    materials: [reference],
+    expectedHead: session.observed.head,
+  });
+  session.observed = await session.journal.read();
+  return session;
+}
+
+function sourceFields(value) {
+  const { ownership, ...source } = value;
+  return source;
+}

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