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

package/packages/core/workflow/pipeline/recovery-ownership-settlement.js

@@ -0,0 +1,150 @@
+import { recordDigest } from "../../release/discussion/envelope.js";
+import {
+  readRecoveryOwnership,
+  recoveryDelivery,
+} from "./recovery-ownership.js";
+import { terminalPipelineCandidate } from "./reconcile.js";
+import {
+  createRecoveryMergeProof,
+  retainedRecoveryMergeProof,
+} from "./recovery-merge-proof.js";
+
+function cleanupRequest(session, ownership, qualified) {
+  const { queue, candidate, worker } = ownership;
+  const active = queue.activeWarrant?.candidateId === candidate.candidateId;
+  if (!active && candidate.status !== "queued")
+    throw new Error("Recovery cannot clean up an unfenced candidate");
+  if (active && worker?.status !== "completed")
+    throw new Error(
+      "Recovery cleanup requires exact terminal native execution",
+    );
+  const proof = qualified
+    ? createRecoveryMergeProof(session, queue, candidate, qualified.integration)
+    : null;
+  const evidence = {
+    schema: "buildchain.pipeline-recovery-ownership/v1",
+    attempt: session.observed.attempt,
+    ownership,
+    proof,
+  };
+  const request = {
+    expectedOldStateRoot: queue.stateRoot,
+    pullRequestNumber: candidate.pullRequestNumber,
+    expectedSourceHead: candidate.sourceHead,
+    eventAction: "cancelled",
+    outcome: proof ? "merged" : "cancelled",
+    evidenceRoot: proof?.proofRoot || recordDigest(evidence),
+    reason: proof
+      ? "exact-protected-recovery-integration"
+      : "explicit-pipeline-recovery",
+    execute: true,
+    ...(active
+      ? {
+          fencingToken: queue.activeWarrant.fencingToken,
+          leaseGeneration: queue.activeWarrant.generation,
+        }
+      : {
+          candidateId: candidate.candidateId,
+          observedSourceHead: candidate.sourceHead,
+        }),
+  };
+  return { ...evidence, method: active ? "settle" : "cancelQueued", request };
+}
+
+async function retainRequest(session, pending, host) {
+  const root = recordDigest(pending);
+  const material = await host
+    .materialStore(session)
+    .retain(
+      `recovery/ownership-request/${root.slice(7)}`,
+      pending,
+      "provider-readback",
+    );
+  session.observed = await session.journal.read();
+  await session.progress.progress({
+    attempt: session.observed.attempt,
+    phase: "admission",
+    state: "waiting",
+    eventKey: `recovery-ownership:${root}`,
+    materials: [material],
+    expectedHead: session.observed.head,
+  });
+  session.observed = await session.journal.read();
+}
+
+function verifyTerminal(before, after, request) {
+  if (
+    !after ||
+    after.candidateId !== before.candidateId ||
+    after.sourceRoot !== before.sourceRoot ||
+    after.status !== request.outcome ||
+    after.terminal?.evidenceRoot !== request.evidenceRoot
+  )
+    throw new Error("Recovery cleanup lacks exact terminal native readback");
+}
+
+async function applyRequest(session, pending, host) {
+  const current = await session.journal.read();
+  if (
+    current.attempt !== pending.attempt ||
+    current.head !== session.observed.head
+  )
+    throw new Error(
+      "Recovery ownership admission advanced before native cleanup",
+    );
+  const delivery = recoveryDelivery(session, host);
+  let response = null,
+    error = null;
+  try {
+    response = await delivery.service[pending.method](pending.request);
+  } catch (cause) {
+    error = cause;
+  }
+  const queue = await delivery.read();
+  const candidate = queue.candidates.find(
+    (item) => item.candidateId === pending.ownership.candidate.candidateId,
+  );
+  try {
+    verifyTerminal(pending.ownership.candidate, candidate, pending.request);
+    if (queue.activeWarrant?.candidateId === candidate.candidateId)
+      throw new Error("Recovery cleanup retained its active Warrant");
+  } catch (readbackError) {
+    throw error || readbackError;
+  }
+  return {
+    queue,
+    candidate,
+    proof: pending.proof,
+    response,
+    lostResponse: Boolean(error),
+  };
+}
+
+export async function settleRecoveryOwnership(session, qualified, host) {
+  const ownership = await readRecoveryOwnership(session, host);
+  if (!ownership?.candidate) {
+    if (qualified && session.intent.expectedNodes.includes("warrant"))
+      throw new Error(
+        "Merged recovery lost its original native candidate authority",
+      );
+    return ownership;
+  }
+  if (terminalPipelineCandidate(ownership.candidate)) {
+    if (Boolean(qualified) !== (ownership.candidate.status === "merged"))
+      throw new Error(
+        "Protected integration conflicts with terminal native ownership",
+      );
+    const proof = qualified
+      ? await retainedRecoveryMergeProof(
+          session,
+          ownership.candidate,
+          qualified.integration,
+          host,
+        )
+      : null;
+    return { ...ownership, proof, response: null, lostResponse: false };
+  }
+  const pending = cleanupRequest(session, ownership, qualified);
+  await retainRequest(session, pending, host);
+  return applyRequest(session, pending, host);
+}

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

@@ -0,0 +1,91 @@
+import { pipelineCandidate, terminalPipelineCandidate } from "./reconcile.js";
+import {
+  pipelineDeliveryStore,
+  observePipelineWorker,
+} from "./delivery-observation.js";
+
+export function recoveryDelivery(session, host) {
+  return host.delivery
+    ? host.delivery(session)
+    : pipelineDeliveryStore(session, host);
+}
+
+export function recoveryOwnerSession(session, owner) {
+  return {
+    ...session,
+    observed: {
+      ...session.observed,
+      attempt: owner.identity.id,
+      generation: owner.generation.id,
+      history: [owner],
+    },
+  };
+}
+
+export function recoveryOwnedCandidate(session, queue) {
+  if (
+    queue.repository !== session.intent.repository ||
+    queue.protectedBase !== session.intent.source.targetBranch
+  )
+    throw new Error(
+      "Recovery ownership crossed its protected repository or branch",
+    );
+  const matches = [...session.observed.history]
+    .reverse()
+    .filter((owner) => owner.generation.id === session.observed.generation)
+    .map((owner) => ({
+      owner,
+      candidate: pipelineCandidate(queue, { ...owner, intent: session.intent }),
+    }))
+    .filter((item) => item.candidate);
+  if (
+    matches.filter((item) => !terminalPipelineCandidate(item.candidate))
+      .length > 1
+  )
+    throw new Error(
+      "Recovery found conflicting live native owners in predecessor history",
+    );
+  return (
+    matches.find(
+      (item) => item.candidate.candidateId === queue.activeWarrant?.candidateId,
+    ) ||
+    matches[0] ||
+    null
+  );
+}
+
+export async function observeRecoveryOwnership(session, executions, host) {
+  if (
+    !executions.terminal ||
+    executions.predecessor !== session.observed.attempt
+  )
+    throw new Error(
+      "Recovery ownership requires exact terminal predecessor runs",
+    );
+  return readRecoveryOwnership(session, host);
+}
+
+export async function readRecoveryOwnership(session, host) {
+  if (!session.intent.expectedNodes.includes("warrant")) return null;
+  const queue = await recoveryDelivery(session, host).read();
+  const selected = recoveryOwnedCandidate(session, queue);
+  if (!selected)
+    return { queue, ownerAttempt: null, candidate: null, worker: null };
+  const { owner, candidate } = selected;
+  const active = queue.activeWarrant?.candidateId === candidate.candidateId;
+  const worker = active
+    ? await observePipelineWorker(
+        recoveryOwnerSession(session, owner),
+        { ...owner, intent: session.intent },
+        queue,
+        host,
+      )
+    : null;
+  if (active && worker?.status !== "completed")
+    throw new Error(
+      "Recovery cannot transfer an active Warrant without exact terminal native worker evidence",
+    );
+  // Read-only admission: the successor retains cleanup intent before settling
+  // original ownership and before starting any new execution.
+  return { queue, ownerAttempt: owner.identity.id, candidate, worker };
+}

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

@@ -0,0 +1,126 @@
+import {
+  recordDigest,
+  validateRuntime,
+} from "../../release/discussion/envelope.js";
+import { object, text, choice } from "../../consumer/contract/shape.js";
+import { RECOVERY_ENTRY } from "../../consumer/contract/entries.js";
+
+export const PIPELINE_RECOVERY_PLAN = "buildchain.pipeline-recovery-plan/v1";
+const ROOT = /^sha256:[0-9a-f]{64}$/u;
+
+export function recoveryRequestKey(predecessor, runtime, entry) {
+  text(predecessor, "predecessor", /^attempt-[0-9a-f]{64}$/u);
+  object(runtime, ["repository", "sha", "readerDigest"]);
+  validateRuntime(runtime);
+  object(entry, ["repository", "workflow", "sha"]);
+  if (
+    runtime.repository !== "kungfu-systems/buildchain" ||
+    entry.repository !== "kungfu-systems/buildchain" ||
+    entry.workflow !== RECOVERY_ENTRY ||
+    !/^[0-9a-f]{40}$/u.test(entry.sha)
+  )
+    throw new Error(
+      "Recovery requires an exact canonical runtime and recovery entry",
+    );
+  return `recover:${recordDigest({ predecessor, runtime, entry })}`;
+}
+
+// Provider adapters must qualify each node before this pure plan is admitted.
+// A reused node names its actual evidence; omission never means rebuild-all.
+export function planPipelineRecovery({
+  observed,
+  runtime,
+  entry,
+  nodes,
+  evidenceRoot,
+}) {
+  const current = observed.history.at(-1);
+  if (!current || observed.status === "complete" || !observed.missing.length)
+    throw new Error(
+      "Completed or absent attempts have no remaining recovery work",
+    );
+  if (!["failure", "cancelled", "superseded"].includes(observed.status))
+    throw new Error(
+      "Recovery requires terminal predecessor execution and ownership",
+    );
+  text(evidenceRoot, "recovery.evidenceRoot", ROOT);
+  if (
+    !Array.isArray(nodes) ||
+    nodes.length !== observed.intent.expectedNodes.length
+  )
+    throw new Error("Recovery must explicitly classify every required node");
+  let pending = false;
+  for (const [index, node] of nodes.entries()) {
+    object(node, ["phase", "operation", "reason", "evidenceRoots"]);
+    if (node.phase !== observed.intent.expectedNodes[index])
+      throw new Error("Recovery node order differs from the original intent");
+    choice(
+      node.operation,
+      ["reuse", "reconcile", "execute"],
+      "recovery.operation",
+    );
+    text(node.reason, "recovery.reason");
+    if (
+      node.reason.length > 1000 ||
+      !Array.isArray(node.evidenceRoots) ||
+      node.evidenceRoots.length > 100 ||
+      new Set(node.evidenceRoots).size !== node.evidenceRoots.length
+    )
+      throw new Error("Recovery node evidence exceeds its exact bound");
+    node.evidenceRoots.forEach((root) =>
+      text(root, "recovery.nodeEvidence", ROOT),
+    );
+    if (node.operation === "reuse" && (!node.evidenceRoots.length || pending))
+      throw new Error(
+        "Only an independently qualified contiguous prefix can be replayed",
+      );
+    if (node.operation !== "reuse") pending = true;
+  }
+  const body = {
+    schema: PIPELINE_RECOVERY_PLAN,
+    intent: observed.intent.id,
+    predecessor: observed.attempt,
+    predecessorHead: observed.head,
+    generation: current.generation.id,
+    sourceRoot: recordDigest(current.generation.source),
+    runtime,
+    entry,
+    requestKey: recoveryRequestKey(observed.attempt, runtime, entry),
+    nodes: structuredClone(nodes),
+    evidenceRoot,
+  };
+  return { ...body, root: recordDigest(body) };
+}
+
+export function verifyRecoveryPlan(plan, observed) {
+  object(plan, [
+    "schema",
+    "intent",
+    "predecessor",
+    "predecessorHead",
+    "generation",
+    "sourceRoot",
+    "runtime",
+    "entry",
+    "requestKey",
+    "nodes",
+    "evidenceRoot",
+    "root",
+  ]);
+  if (
+    recordDigest(plan) !==
+    recordDigest(
+      planPipelineRecovery({
+        observed,
+        runtime: plan.runtime,
+        entry: plan.entry,
+        nodes: plan.nodes,
+        evidenceRoot: plan.evidenceRoot,
+      }),
+    )
+  )
+    throw new Error(
+      "Recovery plan changed its exact predecessor or qualified evidence",
+    );
+  return plan;
+}

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

@@ -0,0 +1,68 @@
+import {
+  recordDigest,
+  validateRuntime,
+} from "../../release/discussion/envelope.js";
+
+const stages = {
+  build: "actions/workflow/pipeline/build/dist",
+  "publication-build": "actions/publication/pipeline/build/dist",
+};
+
+export async function qualifyRecoveryRuntime(
+  previous,
+  current,
+  stage,
+  request,
+) {
+  validateRuntime(previous);
+  validateRuntime(current);
+  if (
+    ![previous.repository, current.repository].every(
+      (repo) => repo === "kungfu-systems/buildchain",
+    ) ||
+    !stages[stage]
+  )
+    throw new Error(
+      "Recovery runtime comparison requires a declared canonical execution stage",
+    );
+  if (
+    previous.sha === current.sha &&
+    previous.readerDigest !== current.readerDigest
+  )
+    throw new Error("An exact runtime changed its immutable reader bytes");
+  async function closure(runtime) {
+    const files = [];
+    for (const name of ["index.js", "buildchain-domain.wasm"]) {
+      const file = `${stages[stage]}/${name}`;
+      const metadata = await request(
+        `/repos/${runtime.repository}/contents/${file}?ref=${runtime.sha}`,
+        { allow404: name.endsWith(".wasm") },
+      );
+      if (!metadata && name.endsWith(".wasm")) {
+        files.push({ path: file, blob: null });
+        continue;
+      }
+      if (
+        metadata?.type !== "file" ||
+        !/^[0-9a-f]{40}$/u.test(metadata.sha || "")
+      )
+        throw new Error(
+          "Recovery runtime has no exact distributed stage implementation",
+        );
+      files.push({ path: file, blob: metadata.sha });
+    }
+    return files;
+  }
+  const before = await closure(previous);
+  const after = previous.sha === current.sha ? before : await closure(current);
+  const body = {
+    schema: "buildchain.pipeline-recovery-runtime/v1",
+    stage,
+    previous,
+    current,
+    before,
+    after,
+    compatible: recordDigest(before) === recordDigest(after),
+  };
+  return { ...body, root: recordDigest(body) };
+}

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