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

package/packages/core/release/discussion/qualification.js

@@ -0,0 +1,122 @@
+import { discussionStatus } from "./reader.js";
+import fs from "node:fs";
+import path from "node:path";
+import { releaseCheckpoints } from "./checkpoints.js";
+import { openReleaseSession, selectedRecordRuntime } from "./session.js";
+import { decodeRecord } from "./envelope.js";
+import { discussionTransport } from "../../providers/github/discussions/transport.js";
+import { releaseDiscussionStore } from "./store.js";
+
+// The same public Bootstrap entry exposes transport qualification and diagnosis
+// to any consumer; this is not a Buildchain-only writer or runtime bootstrap.
+export async function executeReleaseDiscussion(request, _admission, context) {
+  const payload = request.payload;
+  if (
+    payload?.schema !== "buildchain.release-discussion-request/v1" ||
+    !["inspect", "qualify"].includes(payload.operation)
+  )
+    throw new Error("Unsupported release Discussion operation");
+  const allowed =
+    payload.operation === "inspect"
+      ? ["schema", "operation", "discussionId"]
+      : [
+          "schema",
+          "operation",
+          "key",
+          "outcome",
+          "discussionId",
+          "predecessor",
+          "verifyMaterials",
+        ];
+  if (Object.keys(payload).some((key) => !allowed.includes(key)))
+    throw new Error("Unknown release Discussion request field");
+  const repository = request.consumer.repository;
+  const transport = discussionTransport(context.octokit.graphql);
+  if (payload.operation === "inspect") {
+    const discussion = await transport.get(payload.discussionId);
+    const intent = decodeRecord(discussion.body);
+    if (intent?.repository !== repository)
+      throw new Error("Discussion is outside the consumer repository");
+    return discussionStatus(
+      await releaseDiscussionStore(transport).read({
+        discussion,
+        intent,
+        writerId: discussion.author.id,
+      }),
+    );
+  }
+  if (request.capability.permissions?.discussions !== "write")
+    throw new Error(
+      "Discussion qualification requires declared discussions: write",
+    );
+  if (
+    !/^[a-zA-Z0-9._-]{1,80}$/u.test(payload.key || "") ||
+    !["success", "failure"].includes(payload.outcome)
+  )
+    throw new Error("Invalid Discussion qualification request");
+  const journal = await openReleaseSession({
+    graphql: context.octokit.graphql,
+    repository,
+    key: `qualification:${payload.key}`,
+    source: { qualification: payload.key },
+    expectedNodes: ["transport", "recovery"],
+    runtime: selectedRecordRuntime({
+      BUILDCHAIN_RUNTIME_SELECTION: context.runtimeSelection,
+      BUILDCHAIN_RUNTIME_ROOT: context.runtimeRoot,
+    }),
+    attempt: `${context.runId}:${context.runAttempt || "1"}`,
+    discussionId: payload.discussionId || "",
+    predecessor: payload.predecessor || "",
+  });
+  await journal.observe("transport", async () => {
+    if (payload.verifyMaterials === true) {
+      if (request.capability.permissions?.contents !== "write")
+        throw new Error(
+          "Material qualification requires declared contents: write",
+        );
+      const retained = releaseCheckpoints({
+        session: journal.session,
+        store: journal.store,
+        octokit: context.octokit,
+      });
+      await retained.diagnostics("transport", "qualification-probe");
+      const probe = await retained.checkpoint("transport", {
+        schema: "buildchain.material-qualification/v1",
+        value: payload.key,
+      });
+      if ((await retained.readCheckpoint(probe)).value !== payload.key)
+        throw new Error("Small material qualification readback mismatch");
+      const reader = await retained.materials.put(
+        fs.readFileSync(
+          path.join(context.runtimeRoot, "dist/readers/release-discussion.cjs"),
+        ),
+      );
+      const checkpoint = await retained.checkpoint("transport", {
+        schema: "buildchain.material-qualification/v1",
+        reader,
+        value: payload.key,
+      });
+      const readback = await retained.readCheckpoint(checkpoint);
+      if (readback.value !== payload.key)
+        throw new Error("Material qualification readback mismatch");
+    }
+  });
+  await journal.record("recovery", payload.outcome);
+  const state = await journal.read();
+  if (payload.outcome === "failure")
+    throw Object.assign(
+      new Error(
+        "Injected Discussion qualification failure after durable recording",
+      ),
+      { code: "discussion-qualification-injected-failure" },
+    );
+  return {
+    schema: "buildchain.release-discussion-qualification/v1",
+    discussionId: journal.session.discussion.id,
+    discussionUrl: journal.session.discussion.url,
+    status: state.status,
+    handoff: state.handoff,
+    attempt: state.attempt,
+    runtime: journal.session.runtime,
+  };
+}

package/packages/core/release/discussion/reader-entry.js

@@ -0,0 +1,11 @@
+import fs from "node:fs";
+import { readReleaseDiscussion } from "./reader.js";
+export { readReleaseDiscussion } from "./reader.js";
+export { decodeRecord } from "./envelope.js";
+
+// The published self-contained reader accepts only captured JSON on stdin.
+// Run with Node's permission model: no network, child process or file writes.
+if (typeof require !== "undefined" && require.main === module) {
+  const input = JSON.parse(fs.readFileSync(0, "utf8"));
+  process.stdout.write(`${JSON.stringify(readReleaseDiscussion(input))}\n`);
+}

package/packages/core/release/discussion/reader.js

@@ -0,0 +1,177 @@
+import {
+  ENVELOPE_SCHEMA,
+  INTENT_SCHEMA,
+  PAYLOAD_SCHEMA,
+  decodeRecord,
+  recordDigest,
+  validateRuntime,
+} from "./envelope.js";
+
+// Pure historical reader: no provider access, writes or effect recovery.
+export function readReleaseDiscussion({ body, records }) {
+  const intent = decodeRecord(body);
+  if (intent?.schema !== INTENT_SCHEMA)
+    throw new Error("Missing release Discussion intent");
+  if (
+    intent.id !==
+    recordDigest({ repository: intent.repository, key: intent.key })
+  )
+    throw new Error("Release intent identity mismatch");
+  if (
+    !Array.isArray(intent.expectedNodes) ||
+    !intent.expectedNodes.length ||
+    new Set(intent.expectedNodes).size !== intent.expectedNodes.length
+  )
+    throw new Error("Missing or duplicate expected nodes");
+  if (intent.organization && intent.organization !== "attempt-threads/v1")
+    throw new Error(
+      "Discussion organization requires its historical runtime reader",
+    );
+  const attempts = groupAttempts(validateRecords(intent, records));
+  if (!attempts.size)
+    return {
+      intent,
+      status: "pending",
+      attempts: [],
+      missingNodes: intent.expectedNodes,
+    };
+  const { head, lineage } = resolveLineage(attempts);
+  const nodes = currentNodes(attempts.get(head).events);
+  const missingNodes = intent.expectedNodes.filter((node) => !nodes[node]);
+  const complete = intent.expectedNodes.every(
+    (node) => nodes[node]?.status === "success",
+  );
+  const failed = Object.values(nodes).some((event) =>
+    ["failure", "cancelled"].includes(event.status),
+  );
+  return {
+    intent,
+    attempt: head,
+    attempts: lineage.reverse(),
+    nodes,
+    missingNodes,
+    status: complete ? "complete" : failed ? "failed" : "running",
+    handoff: {
+      schema: "buildchain.release-handoff/v1",
+      intent: intent.id,
+      predecessor: head,
+      completedNodes: intent.expectedNodes.filter(
+        (node) => nodes[node]?.status === "success",
+      ),
+    },
+  };
+}
+
+function validateRecords(intent, records) {
+  const events = new Map();
+  for (const raw of records) {
+    const event = typeof raw === "string" ? decodeRecord(raw) : raw;
+    if (!event) continue;
+    validateRuntime(event.runtime);
+    if (
+      !["progress", "checkpoint"].includes(event.kind) ||
+      !event.writer ||
+      !event.attempt ||
+      typeof event.predecessor !== "string"
+    )
+      throw new Error("Invalid record ownership");
+    const { id, ...content } = event;
+    if (
+      event.schema !== ENVELOPE_SCHEMA ||
+      event.payloadSchema !== PAYLOAD_SCHEMA
+    )
+      throw new Error("Record requires its historical runtime reader");
+    if (event.intent !== intent.id || id !== recordDigest(content))
+      throw new Error("Release record identity mismatch");
+    if (event.node !== "attempt" && !intent.expectedNodes.includes(event.node))
+      throw new Error("Undeclared release node");
+    if (
+      !["running", "success", "failure", "cancelled"].includes(event.status) ||
+      !Number.isSafeInteger(event.sequence) ||
+      event.sequence < 0
+    )
+      throw new Error("Invalid release progress");
+    events.set(id, event);
+  }
+  return events;
+}
+
+function groupAttempts(events) {
+  const attempts = new Map();
+  for (const event of events.values()) {
+    const attempt = attempts.get(event.attempt) || {
+      predecessor: event.predecessor,
+      events: [],
+    };
+    if (attempt.predecessor !== event.predecessor)
+      throw new Error("Conflicting workflow attempt identity");
+    attempt.events.push(event);
+    attempts.set(event.attempt, attempt);
+  }
+  return attempts;
+}
+
+function resolveLineage(attempts) {
+  const predecessors = new Set(
+    [...attempts.values()]
+      .map((attempt) => attempt.predecessor)
+      .filter(Boolean),
+  );
+  for (const predecessor of predecessors)
+    if (!attempts.has(predecessor))
+      throw new Error("Recovery predecessor is missing");
+  const heads = [...attempts.keys()].filter((id) => !predecessors.has(id));
+  if (heads.length !== 1)
+    throw new Error("Release attempt succession is ambiguous or cyclic");
+  const lineage = [];
+  let current = heads[0];
+  while (current) {
+    if (lineage.includes(current)) throw new Error("Cyclic recovery chain");
+    lineage.push(current);
+    current = attempts.get(current).predecessor;
+  }
+  if (lineage.length !== attempts.size)
+    throw new Error("Disconnected recovery chain");
+  return { head: heads[0], lineage };
+}
+
+function currentNodes(events) {
+  const nodes = {},
+    sequences = new Map();
+  // Reuse is explicit and independently qualified by the recovering runtime.
+  for (const event of events) {
+    if (event.kind === "checkpoint") continue;
+    const key = `${event.node}:${event.sequence}`;
+    if (sequences.has(key) && sequences.get(key) !== event.id)
+      throw new Error("Conflicting node progress at the same sequence");
+    sequences.set(key, event.id);
+    const old = nodes[event.node];
+    if (!old || old.sequence < event.sequence) nodes[event.node] = event;
+  }
+  return nodes;
+}
+
+// Workflow outputs carry a bounded projection, never the complete comment log.
+export function discussionStatus(state) {
+  return {
+    discussionId: state.discussion.id,
+    discussionUrl: state.discussion.url,
+    intent: state.intent.id,
+    status: state.status,
+    attempt: state.attempt || "",
+    attempts: state.attempts,
+    threads: [...(state.roots || new Map())].map(([attempt, comment]) => ({
+      attempt,
+      commentId: comment.id,
+      url: comment.url,
+    })),
+    missingNodes: state.missingNodes,
+    handoff: state.handoff || null,
+    nodes: Object.fromEntries(
+      Object.entries(state.nodes || {}).map(([node, record]) => [
+        node,
+        { status: record.status, recordId: record.id, writer: record.writer },
+      ]),
+    ),
+  };
+}

package/packages/core/release/discussion/recovery.js

@@ -0,0 +1,132 @@
+import fs from "node:fs";
+import path from "node:path";
+import { getOctokit } from "@actions/github";
+import { decodeRecord } from "./envelope.js";
+import { releaseDiscussionStore } from "./store.js";
+import { discussionTransport } from "../../providers/github/discussions/transport.js";
+import { releaseCheckpoints, restoreRecoveryMaterials } from "./checkpoints.js";
+import { validateReleaseCandidatePassport } from "../release-candidate.js";
+import {
+  assertCandidateEvidenceBinding,
+  aggregateReleasePassport,
+  observeProtectedPublicationSource,
+} from "../promote-candidate/evidence-binding.js";
+
+export async function recoverDiscussionCandidate({
+  discussionId,
+  repository,
+  token,
+  outputDir,
+  targetSha,
+  targetRef,
+}) {
+  const octokit = getOctokit(token);
+  const transport = discussionTransport(octokit.graphql);
+  const discussion = await transport.get(discussionId);
+  const intent = decodeRecord(discussion.body);
+  if (
+    intent?.repository !== repository ||
+    discussion.author?.__typename !== "Bot" ||
+    discussion.author.login !== "github-actions"
+  )
+    throw new Error(
+      "Recovery requires the consumer workflow's original Discussion",
+    );
+  const session = { discussion, intent, writerId: discussion.author.id };
+  const store = releaseDiscussionStore(transport);
+  const observed = await store.read(session);
+  const snapshots = observed.records
+    .filter(
+      (record) =>
+        record.kind === "checkpoint" && record.node === "qualification",
+    )
+    .sort(
+      (a, b) =>
+        observed.attempts.indexOf(b.attempt) -
+          observed.attempts.indexOf(a.attempt) || b.sequence - a.sequence,
+    );
+  if (!snapshots.length)
+    throw new Error("Discussion has no retained qualified recovery material");
+  const retained = releaseCheckpoints({ session, store, octokit });
+  const manifest = await retained.readCheckpoint(snapshots[0]);
+  if (
+    manifest.source?.repository !== repository ||
+    manifest.source.version !== intent.key ||
+    manifest.source.targetRef !== targetRef
+  )
+    throw new Error("Recovery material belongs to a different release intent");
+  const workspace = path.resolve(outputDir, "../..");
+  const prefix =
+    path
+      .relative(workspace, path.resolve(outputDir))
+      .split(path.sep)
+      .join("/") + "/";
+  if (!manifest.files.every((file) => file.path.startsWith(prefix)))
+    throw new Error(
+      "Candidate recovery cannot restore files outside its evidence directory",
+    );
+  const inputs = await restoreRecoveryMaterials(
+    manifest,
+    workspace,
+    retained.materials,
+  );
+  const read = (file) => JSON.parse(fs.readFileSync(file, "utf8"));
+  const candidate = read(inputs["candidate-passport-path"]),
+    summary = read(inputs["candidate-build-summary-path"]);
+  const validation = validateReleaseCandidatePassport({
+    passport: candidate,
+    repository,
+    buildSummary: summary,
+  });
+  if (!validation.ok)
+    throw new Error(
+      `Recovered candidate is invalid: ${validation.errors.join("; ")}`,
+    );
+  const stageCapsules = read(inputs["stage-capsules-path"]),
+    qualification = read(inputs["publication-qualification-path"]);
+  assertCandidateEvidenceBinding({ candidate, stageCapsules, repository });
+  const sourceBinding = await observeProtectedPublicationSource({
+    octokit,
+    repository,
+    protectedSourceSha: targetSha,
+    candidate,
+  });
+  aggregateReleasePassport({
+    candidate,
+    stageCapsules,
+    qualification,
+    sourceBinding,
+    version: intent.key,
+    tag: `v${intent.key}`,
+    channel: manifest.source.channel,
+  });
+  // The shared candidate provider performs artifact-kind-specific sealed verification
+  // before effects; transport restoration verifies every retained file digest.
+  const paths = {
+    passport: inputs["candidate-passport-path"],
+    buildSummary: inputs["candidate-build-summary-path"],
+    stageCapsules: inputs["stage-capsules-path"],
+    publicationQualification: inputs["publication-qualification-path"],
+    sealedBundleRoot: inputs["sealed-bundle-root"],
+    sealedBundleManifest: inputs["sealed-bundle-manifest"],
+    publishRequiredArtifacts: inputs["required-artifacts-path"],
+    recoveryReceipt: inputs["recovery-receipt-path"] || "",
+    releaseAssets: (manifest.releaseAssets || []).map((file) =>
+      path.resolve(workspace, file),
+    ),
+  };
+  return {
+    enabled: true,
+    version: candidate.target.version,
+    publicationVersion: intent.key,
+    candidateVersion: candidate.target.version,
+    artifacts: {
+      sourceSha: candidate.source.headSha,
+      passport: `discussion-${discussion.number}`,
+    },
+    paths,
+    run: { id: snapshots[0].attempt.split(":")[0] },
+    discussionId,
+    handoff: observed.handoff,
+  };
+}

package/packages/core/release/discussion/session.js

@@ -0,0 +1,115 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { createIntent, createProgress } from "./envelope.js";
+import { releaseDiscussionStore } from "./store.js";
+import { discussionTransport } from "../../providers/github/discussions/transport.js";
+
+export const RELEASE_NODES = [
+  "qualification",
+  "publication",
+  "github-release",
+  "next-development",
+  "settlement",
+];
+
+export function selectedRecordRuntime(env) {
+  const selection = JSON.parse(env.BUILDCHAIN_RUNTIME_SELECTION || "{}");
+  const file = path.join(
+    env.BUILDCHAIN_RUNTIME_ROOT || "",
+    "dist/readers/release-discussion.cjs",
+  );
+  return {
+    repository: selection.repository,
+    sha: selection.sha,
+    readerPath: "dist/readers/release-discussion.cjs",
+    readerDigest: `sha256:${createHash("sha256").update(fs.readFileSync(file)).digest("hex")}`,
+  };
+}
+
+export async function openReleaseSession({
+  graphql,
+  repository,
+  key,
+  source,
+  runtime,
+  attempt,
+  discussionId = "",
+  predecessor = "",
+  dryRun = false,
+  recover = false,
+  expectedNodes = RELEASE_NODES,
+  onFailure = async () => {},
+}) {
+  const intent = createIntent({
+    repository,
+    key,
+    source,
+    runtime,
+    expectedNodes,
+  });
+  const store = releaseDiscussionStore(discussionTransport(graphql));
+  const session = await store.initialize({ intent, discussionId, dryRun });
+  if (dryRun)
+    return {
+      session,
+      observe: async (_node, effect) => effect(),
+      record: async () => {},
+      read: async () => ({ dryRun: true }),
+    };
+  const current = await store.read(session);
+  const retained = current.records.find((event) => event.attempt === attempt);
+  const prior =
+    retained?.predecessor ??
+    (predecessor || (recover ? current.attempt || "" : ""));
+  if (
+    current.attempt &&
+    current.attempt !== attempt &&
+    prior !== current.attempt
+  )
+    throw new Error(
+      `Recovery requires predecessor ${current.attempt} in the same Discussion`,
+    );
+  session.attempt = attempt;
+  session.predecessor = prior;
+  session.runtime = runtime;
+  const record = async (node, status, payload = {}, sequence = 0) =>
+    store.append(
+      session,
+      createProgress({
+        intent: session.intent,
+        runtime,
+        attempt,
+        predecessor: prior,
+        node,
+        status,
+        payload,
+        sequence,
+      }),
+    );
+  await record("attempt", "running");
+  const observe = async (node, effect, summarize = () => ({})) => {
+    await record(node, "running");
+    let result;
+    try {
+      result = await effect();
+    } catch (error) {
+      // Preserve the original failure even when the diagnostic provider is down.
+      try {
+        await record(
+          node,
+          "failure",
+          { code: String(error.code || "execution-failed") },
+          1,
+        );
+        await onFailure(node, error);
+      } catch (recordError) {
+        error.discussionRecordingError = recordError.message;
+      }
+      throw error;
+    }
+    await record(node, "success", summarize(result), 1);
+    return result;
+  };
+  return { session, store, observe, record, read: () => store.read(session) };
+}