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

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

@@ -0,0 +1,71 @@
+import { recordDigest } from "../../release/discussion/envelope.js";
+import { retainedRecoveryEvidence } from "./recovery-session.js";
+import { pipelinePlatforms } from "./platforms.js";
+import { buildReadbackPlatforms } from "./build-qualification.js";
+import { qualifyRecoveryRuntime } from "./recovery-runtime.js";
+
+export async function recoveryBuildEvidence(session, host) {
+  const { plan, evidence } = await retainedRecoveryEvidence(session, host);
+  const build = evidence.build;
+  if (!build) throw new Error("Recovery admission has no qualified build plan");
+  const { root, ...body } = build;
+  const current = session.observed.history.at(-1);
+  const source = await host.source.source(
+    current.generation.source.commit,
+    current.generation.source.configPath,
+  );
+  if (
+    root !== recordDigest(body) ||
+    body.schema !== "buildchain.pipeline-recovery-build/v1" ||
+    body.predecessor !== plan.predecessor ||
+    recordDigest(body.source) !== recordDigest(current.generation.source) ||
+    recordDigest(source.identity) !== recordDigest(body.source) ||
+    recordDigest(pipelinePlatforms(source.plan)) !==
+      recordDigest(body.platforms) ||
+    recordDigest(host.runtime) !== recordDigest(plan.runtime)
+  )
+    throw new Error(
+      "Recovery build plan changed its source, platform inventory or executor",
+    );
+  const selected = new Set();
+  for (const segment of build.segments) {
+    const old = segment.readback;
+    const inventory = buildReadbackPlatforms(old);
+    const fresh = await host.runs.build(
+      old.runId,
+      old.runAttempt,
+      build.source,
+      inventory,
+    );
+    const runtime = await qualifyRecoveryRuntime(
+      segment.runtime,
+      host.runtime,
+      "build",
+      host.request,
+    );
+    if (recordDigest(fresh) !== recordDigest(old) || !runtime.compatible)
+      throw new Error(
+        "Recovered platform changed during execution requalification",
+      );
+    for (const platform of segment.platforms) {
+      const job = old.jobs[inventory.indexOf(platform)];
+      if (
+        selected.has(platform) ||
+        job?.status !== "completed" ||
+        job.conclusion !== "success"
+      )
+        throw new Error(
+          "Recovery cannot reuse duplicate or unsuccessful platform results",
+        );
+      selected.add(platform);
+    }
+  }
+  if (
+    recordDigest(build.scheduled) !==
+    recordDigest(build.platforms.filter((item) => !selected.has(item.platform)))
+  )
+    throw new Error(
+      "Recovery scheduling differs from the qualified remaining platform set",
+    );
+  return { plan, build };
+}

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

@@ -0,0 +1,121 @@
+import { recordDigest } from "../../release/discussion/envelope.js";
+import { pipelinePlatforms } from "./platforms.js";
+import { qualifyRecoveryRuntime } from "./recovery-runtime.js";
+import { unrecordedRecoveryBuild } from "./recovery-unrecorded-build.js";
+import {
+  PIPELINE_BUILD_QUALIFICATION,
+  buildReadbackPlatforms,
+  verifyPipelineBuildQualification,
+  qualifyPipelineBuild,
+} from "./build-qualification.js";
+
+async function retainedSegments(session, source, platforms, host) {
+  const phase = session.observed.history.at(-1).phases.build;
+  const references = (phase?.payload.materials || []).filter(
+    (item) =>
+      item.id.startsWith("build/provider-") ||
+      item.id.startsWith("build/qualified-"),
+  );
+  if (!references.length && phase?.payload.state !== "success")
+    return unrecordedRecoveryBuild(session, source, platforms, host);
+  if (references.length !== 1)
+    throw new Error(
+      "Recovery cannot qualify the unique retained build receipt",
+    );
+  const value = await host.materialStore(session).read(references[0]);
+  if (value.schema === PIPELINE_BUILD_QUALIFICATION) {
+    await verifyPipelineBuildQualification(value, source, platforms, host.runs);
+    return value.segments;
+  }
+  const inventory = buildReadbackPlatforms(value);
+  if (
+    recordDigest(value.source) !== recordDigest(source) ||
+    recordDigest([...inventory].sort()) !== recordDigest([...platforms].sort())
+  )
+    throw new Error(
+      "Recovery build receipt changed its original platform inventory",
+    );
+  const fresh = await host.runs.build(
+    value.runId,
+    value.runAttempt,
+    source,
+    inventory,
+  );
+  if (recordDigest(fresh) !== recordDigest(value))
+    throw new Error("Recovery build receipt changed during provider readback");
+  const segments = [{ readback: value, platforms, runtime: phase.runtime }];
+  qualifyPipelineBuild({
+    source,
+    platforms,
+    segments,
+    runId: value.runId,
+    runAttempt: value.runAttempt,
+  });
+  return segments;
+}
+
+// Every retained segment is independently observed, even when its old overall
+// workflow failed elsewhere. Only successful jobs with an unchanged execution
+// implementation qualify for reuse. Missing evidence is not invented.
+export async function qualifyRecoveryBuild(session, admission, host) {
+  const source = session.observed.history.at(-1).generation.source;
+  if (recordDigest(admission.identity) !== recordDigest(source))
+    throw new Error("Recovery build admission changed its exact source");
+  const platforms = pipelinePlatforms(admission.plan);
+  const prior = await retainedSegments(
+    session,
+    source,
+    platforms.map((item) => item.platform),
+    host,
+  );
+  const segments = [],
+    runtimes = [],
+    selected = new Set();
+  for (const segment of prior) {
+    const runtime = await qualifyRecoveryRuntime(
+      segment.runtime,
+      host.runtime,
+      "build",
+      host.request,
+    );
+    runtimes.push(runtime);
+    const inventory = buildReadbackPlatforms(segment.readback);
+    const reusable = segment.platforms.filter((platform) => {
+      const job = segment.readback.jobs[inventory.indexOf(platform)];
+      return (
+        runtime.compatible &&
+        job.status === "completed" &&
+        job.conclusion === "success"
+      );
+    });
+    if (reusable.length) {
+      for (const platform of reusable) {
+        if (
+          selected.has(platform) ||
+          !platforms.some((item) => item.platform === platform)
+        )
+          throw new Error(
+            "Recovery build has duplicate or undeclared retained platforms",
+          );
+        selected.add(platform);
+      }
+      segments.push({ ...segment, platforms: reusable });
+    }
+  }
+  const body = {
+    schema: "buildchain.pipeline-recovery-build/v1",
+    predecessor: session.observed.attempt,
+    predecessorHead: session.observed.head,
+    source,
+    platforms,
+    scheduled: platforms.filter((item) => !selected.has(item.platform)),
+    segments,
+    runtimes,
+    reason: !prior.length
+      ? "No retained product result; execute declared platforms"
+      : runtimes.some((item) => !item.compatible)
+        ? "Changed stage implementation requires affected platform execution"
+        : "Reuse independently verified successful platforms; execute only missing results",
+  };
+  return { ...body, root: recordDigest(body) };
+}

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

@@ -0,0 +1,91 @@
+import {
+  recoveryExecution,
+  admitRecoverySource,
+  recoveryPredecessorRuns,
+} from "./recovery-admission.js";
+import {
+  selectRecoveryAttempt,
+  openRecoveryAttempt,
+  retainedRecoveryPlan,
+} from "./recovery-session.js";
+import { qualifyRecoveryBuild } from "./recovery-build.js";
+import { observeRecoveryOwnership } from "./recovery-ownership.js";
+import {
+  terminateRecoveryPredecessor,
+  recoveryNodePlan,
+  replayRecoveryAdmission,
+} from "./recovery-transition.js";
+import { qualifyRecoveryIntegration } from "./recovery-integration.js";
+import { beginRecoveryBuild } from "./recovery-build-control.js";
+
+async function duplicateRecovery(session, host) {
+  await retainedRecoveryPlan(session, host);
+  // Root CAS can commit before the immutable lookup index acknowledgement.
+  await host.index.retain(session.intent, session.observed.attempt);
+  await host.project(session);
+  return {
+    operation: "wait",
+    attempt: session.observed.attempt,
+    reason: `Recovery already selected this successor (${session.observed.status}); any further recovery must select its exact attempt`,
+  };
+}
+
+export async function controlPipelineRecovery(attempt, definitionSha, host) {
+  const execution = await recoveryExecution(host, definitionSha);
+  let session = await selectRecoveryAttempt(attempt, host, execution.entry);
+  if (session.duplicate) return duplicateRecovery(session, host);
+  const admitted = await admitRecoverySource(session, execution, host);
+  const executions = await recoveryPredecessorRuns(session, host);
+  if (!executions.terminal) {
+    await host.project(session);
+    return {
+      operation: "wait",
+      attempt,
+      reason:
+        "Predecessor provider executions are still active; wait for completion or cancel their actual runs before recovery",
+    };
+  }
+  const build = await qualifyRecoveryBuild(session, admitted.source, host);
+  // Post-merge recovery must qualify the retained publication transaction before
+  // opening a successor. Its adapter preserves signed bytes and completed effects.
+  const integration = admitted.admission.live.merged
+    ? await qualifyRecoveryIntegration(session, admitted.admission, host)
+    : null;
+  const publication =
+    admitted.admission.live.merged &&
+    session.intent.expectedNodes.includes("publish")
+      ? await host.recoverPublication(session, admitted, execution)
+      : null;
+  const ownership = await observeRecoveryOwnership(session, executions, host);
+  session = await terminateRecoveryPredecessor(
+    session,
+    executions,
+    ownership,
+    host,
+  );
+  const evidence = {
+    admitted,
+    executions,
+    ownership,
+    build,
+    publication,
+    integration,
+  };
+  const plan = recoveryNodePlan(session, evidence, execution.entry, host);
+  session = await openRecoveryAttempt(session, plan, host, evidence);
+  await replayRecoveryAdmission(session, host);
+  const context = await beginRecoveryBuild(session, host);
+  await host.project(session);
+  if (!context)
+    return {
+      operation: "wait",
+      attempt: session.observed.attempt,
+      reason: "Recovery build already has an execution owner",
+    };
+  return {
+    operation: context.platforms.length ? "build" : "qualify-build",
+    context,
+    attempt: context.attempt,
+    reason: build.reason,
+  };
+}

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

@@ -0,0 +1,79 @@
+import { recordDigest } from "../../release/discussion/envelope.js";
+import { settleRecoveryOwnership } from "./recovery-ownership-settlement.js";
+import { retainedRecoveryEvidence } from "./recovery-session.js";
+
+export async function qualifyRecoveryIntegration(session, admission, host) {
+  const current = {
+    ...session.observed.history.at(-1),
+    intent: session.intent,
+  };
+  const policyAdmission = await host.source.observe(
+    session.intent.source.pullRequest,
+    { "config-path": current.generation.source.configPath },
+  );
+  if (
+    !policyAdmission.eligible ||
+    !policyAdmission.live.merged ||
+    policyAdmission.live.targetBranch !== session.intent.source.targetBranch ||
+    policyAdmission.live.mergeCommit !== admission.live.mergeCommit ||
+    recordDigest(policyAdmission.live.source) !==
+      recordDigest(current.generation.source)
+  )
+    throw new Error("Recovery observed changed protected integration");
+  const integration = await host.integration.observe(current);
+  const review = await host.policy.observeMerged(
+    current,
+    policyAdmission.protectedPlan.review,
+    integration,
+  );
+  if (!review.review || !review.checksPassing)
+    throw new Error(
+      "Recovery of protected integration requires current exact review and required checks",
+    );
+  return { integration, review };
+}
+
+async function replayPhase(session, phase, value, host) {
+  const observed = await session.journal.read();
+  const old = observed.phases[phase];
+  if (old?.payload.state === "success") return;
+  const root = recordDigest(value);
+  const reference = await host
+    .materialStore(session)
+    .retain(`recovery/${phase}-${root.slice(7)}`, value, "provider-readback");
+  await session.progress.progress({
+    attempt: observed.attempt,
+    phase,
+    state: "success",
+    eventKey: `recovery-${phase}:${root}`,
+    materials: [reference],
+    expectedHead: observed.head,
+  });
+}
+
+export async function replayRecoveryIntegration(session, host) {
+  session.observed = await session.journal.read();
+  const { evidence } = await retainedRecoveryEvidence(session, host);
+  if (!evidence.admitted.admission.live.merged) return;
+  const qualified = await qualifyRecoveryIntegration(
+    session,
+    evidence.admitted.admission,
+    host,
+  );
+  await replayPhase(session, "review", qualified.review, host);
+  if (session.intent.expectedNodes.includes("warrant")) {
+    const ownership = await settleRecoveryOwnership(session, qualified, host);
+    await replayPhase(
+      session,
+      "warrant",
+      {
+        schema: "buildchain.pipeline-recovery-merged-warrant/v1",
+        candidate: ownership.candidate,
+        proof: ownership.proof,
+        predecessor: evidence.ownership.ownerAttempt,
+      },
+      host,
+    );
+  }
+  await replayPhase(session, "merge", qualified.integration, host);
+}

package/packages/core/workflow/pipeline/recovery-merge-proof.js

@@ -0,0 +1,90 @@
+import {
+  createIntegrationDeliveryProof,
+  verifyIntegrationDeliveryProof,
+} from "../../dev-delivery/dev-delivery-warrant.js";
+import { recoveryOwnerSession } from "./recovery-ownership.js";
+
+export function verifyRecoveryMergeProof(
+  proof,
+  candidate,
+  integration,
+  session,
+) {
+  if (
+    !verifyIntegrationDeliveryProof(proof, {
+      repository: session.intent.repository,
+      protectedBase: session.intent.source.targetBranch,
+      sourceProofRoot: candidate.sourceProofRoot,
+      warrantCandidateId: candidate.candidateId,
+      currentBase: integration.mergeCommit,
+      replayTree: integration.mergeTree,
+      mergeGroupHead: integration.mergeCommit,
+      mergeGroupTree: integration.mergeTree,
+    }).ok
+  )
+    throw new Error(
+      "Recovery merged Warrant has no exact original integration proof",
+    );
+  return proof;
+}
+
+export async function retainedRecoveryMergeProof(
+  session,
+  candidate,
+  integration,
+  host,
+) {
+  let count = 0;
+  for (const owner of [...session.observed.history].reverse()) {
+    const store = host.materialStore(recoveryOwnerSession(session, owner));
+    for (const reference of owner.events
+      .flatMap((event) => event.payload.materials)
+      .filter(
+        (item) =>
+          item.id ===
+            `merge/proof-${candidate.terminal.evidenceRoot.slice(7)}` ||
+          item.id.startsWith("recovery/ownership-request/"),
+      )) {
+      if (++count > 100)
+        throw new Error(
+          "Recovery integration proof inventory exceeds its bound",
+        );
+      const value = await store.read(reference);
+      const proof = reference.id.startsWith("merge/proof-")
+        ? value
+        : value.proof;
+      if (proof?.proofRoot === candidate.terminal.evidenceRoot)
+        return verifyRecoveryMergeProof(proof, candidate, integration, session);
+    }
+  }
+  throw new Error(
+    "Merged predecessor lost its retained pre-effect integration proof",
+  );
+}
+
+export function createRecoveryMergeProof(
+  session,
+  queue,
+  candidate,
+  integration,
+) {
+  if (
+    queue.activeWarrant?.candidateId !== candidate.candidateId ||
+    queue.activeWarrant.phase !== "qualified"
+  )
+    throw new Error(
+      "Merged recovery requires the original qualified active Warrant",
+    );
+  return createIntegrationDeliveryProof({
+    repository: session.intent.repository,
+    protectedBase: session.intent.source.targetBranch,
+    sourceProofRoot: candidate.sourceProofRoot,
+    warrant: queue.activeWarrant,
+    currentBase: integration.mergeCommit,
+    replayTree: integration.mergeTree,
+    mergeGroupHead: integration.mergeCommit,
+    mergeGroupTree: integration.mergeTree,
+    requiredContextRoots: [integration.build.root, integration.root],
+    verifiedAt: new Date().toISOString(),
+  });
+}

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