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

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

@@ -0,0 +1,241 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createProgress, recordDigest } from "./envelope.js";
+import { materialDigest } from "../../providers/github/discussions/materials.js";
+import { discussionMaterials } from "../../providers/github/discussions/materials.js";
+
+export function releaseCheckpoints({ session, store, octokit }) {
+  const materials = discussionMaterials({
+    octokit,
+    repository: session.intent.repository,
+    intentId: session.intent.id,
+  });
+  async function checkpoint(node, value) {
+    const observed = await store.read(session);
+    const records = observed.records.filter(
+      (record) =>
+        record.kind === "checkpoint" &&
+        record.attempt === session.attempt &&
+        record.node === node,
+    );
+    const root = recordDigest(value);
+    const duplicate = records.find((record) => record.payload.root === root);
+    if (duplicate) return duplicate;
+    const handle = await materials.put(Buffer.from(JSON.stringify(value)));
+    const record = createProgress({
+      intent: session.intent,
+      runtime: session.runtime,
+      attempt: session.attempt,
+      predecessor: session.predecessor,
+      kind: "checkpoint",
+      node,
+      status: "running",
+      sequence: Math.max(-1, ...records.map((record) => record.sequence)) + 1,
+      payload: {
+        schema: "buildchain.release-checkpoint/v1",
+        root,
+        material: handle,
+      },
+    });
+    await store.append(session, record);
+    return record;
+  }
+  async function readCheckpoint(record) {
+    if (
+      record.kind !== "checkpoint" ||
+      record.payload?.schema !== "buildchain.release-checkpoint/v1"
+    )
+      throw new Error("Unsupported recovery checkpoint");
+    const value = JSON.parse(await materials.read(record.payload.material));
+    if (recordDigest(value) !== record.payload.root)
+      throw new Error("Recovery checkpoint root differs from its record");
+    return value;
+  }
+  async function publicationReader(currentBytes) {
+    const observed = await store.read(session);
+    const first = observed.records
+      .filter(
+        (record) =>
+          record.kind === "checkpoint" && record.node === "qualification",
+      )
+      .sort(
+        (a, b) =>
+          observed.attempts.indexOf(a.attempt) -
+            observed.attempts.indexOf(b.attempt) || a.sequence - b.sequence,
+      )[0];
+    if (!first) return currentBytes;
+    const manifest = await readCheckpoint(first);
+    if (manifest.schema !== "buildchain.release-recovery-material/v1")
+      throw new Error("Unsupported retained publication reader manifest");
+    return materials.read(manifest.reader);
+  }
+  return { checkpoint, readCheckpoint, materials, publicationReader };
+}
+
+function assertNoSymlink(file, base) {
+  let current = file;
+  while (current.startsWith(base)) {
+    if (fs.existsSync(current) && fs.lstatSync(current).isSymbolicLink())
+      throw new Error("Recovery path contains a symbolic link");
+    if (current === base) break;
+    current = path.dirname(current);
+  }
+}
+
+const MATERIAL_INPUTS = [
+  "candidate-passport-path",
+  "candidate-build-summary-path",
+  "stage-capsules-path",
+  "product-publication-intent-path",
+  "publication-qualification-path",
+  "required-artifacts-path",
+  "sealed-bundle-manifest",
+  "recovery-receipt-path",
+];
+
+export async function retainRecoveryMaterials(
+  { request, workspace, readerFile },
+  materials,
+) {
+  const base = path.resolve(workspace);
+  const files = new Set(
+    MATERIAL_INPUTS.map((name) => request[name])
+      .filter(Boolean)
+      .map((file) => path.resolve(base, file)),
+  );
+  for (const file of request["artifact-paths"] || [])
+    files.add(path.resolve(base, file));
+  const walk = (directory) => {
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+      const file = path.join(directory, entry.name);
+      if (entry.isSymbolicLink())
+        throw new Error("Recovery materials must not contain symbolic links");
+      if (entry.isDirectory()) walk(file);
+      else if (entry.isFile()) files.add(file);
+      if (files.size > 512)
+        throw new Error("Recovery material file count exceeded");
+    }
+  };
+  if (request["sealed-bundle-root"]) {
+    const root = path.resolve(base, request["sealed-bundle-root"]);
+    if (!root.startsWith(path.join(base, ".buildchain") + path.sep))
+      throw new Error("Sealed recovery directory is outside consumer evidence");
+    assertNoSymlink(root, base);
+    walk(root);
+  }
+  const handles = [];
+  let totalSize = 0;
+  for (const file of files) {
+    const relative = path.relative(base, file).split(path.sep).join("/");
+    if (
+      !relative.startsWith(".buildchain/") ||
+      relative.startsWith(".buildchain/runtime/") ||
+      relative.includes("../")
+    )
+      throw new Error(
+        "Recovery materials must remain in the declared consumer evidence directory",
+      );
+    assertNoSymlink(file, base);
+    const info = fs.lstatSync(file);
+    if (!info.isFile())
+      throw new Error("Recovery material is not a regular file");
+    totalSize += info.size;
+    if (totalSize > 1024 * 1024 * 1024)
+      throw new Error("Recovery material byte budget exceeded");
+    handles.push({
+      path: relative,
+      ...(await materials.put(fs.readFileSync(file))),
+    });
+  }
+  return {
+    schema: "buildchain.release-recovery-material/v1",
+    source: {
+      repository: request.repository,
+      sourceSha: request["source-sha"],
+      version: request.version,
+      targetRef: request["target-ref"],
+      channel: request.channel,
+    },
+    releaseAssets: (request["artifact-paths"] || []).map((file) =>
+      path.relative(base, path.resolve(base, file)).split(path.sep).join("/"),
+    ),
+    files: handles,
+    inputs: Object.fromEntries(
+      [...MATERIAL_INPUTS, "sealed-bundle-root"].map((key) => [
+        key,
+        request[key]
+          ? path
+              .relative(base, path.resolve(base, request[key]))
+              .split(path.sep)
+              .join("/")
+          : "",
+      ]),
+    ),
+    reader: await materials.put(fs.readFileSync(readerFile)),
+  };
+}
+
+function recoveryInventory(manifest, directory) {
+  if (
+    manifest.schema !== "buildchain.release-recovery-material/v1" ||
+    !Array.isArray(manifest.files) ||
+    manifest.files.length > 512
+  )
+    throw new Error("Unsupported recovery material manifest");
+  const base = path.resolve(directory),
+    paths = new Set();
+  const files = manifest.files.map((handle) => {
+    if (
+      typeof handle.path !== "string" ||
+      !handle.path.startsWith(".buildchain/") ||
+      handle.path.startsWith(".buildchain/runtime/") ||
+      handle.path
+        .split(/[\\/]/u)
+        .some((part) => ["..", ".", ""].includes(part)) ||
+      paths.has(handle.path)
+    )
+      throw new Error("Unsafe recovery material path");
+    paths.add(handle.path);
+    const file = path.resolve(base, handle.path);
+    assertNoSymlink(file, base);
+    if (
+      fs.existsSync(file) &&
+      (!fs.lstatSync(file).isFile() ||
+        materialDigest(fs.readFileSync(file)) !== handle.digest)
+    )
+      throw new Error(
+        "Recovery material destination already exists with different bytes",
+      );
+    return { handle, file };
+  });
+  const inputs = Object.fromEntries(
+    Object.entries(manifest.inputs).map(([key, relative]) => {
+      if (!relative) return [key, ""];
+      const present =
+        key === "sealed-bundle-root"
+          ? [...paths].some((file) => file.startsWith(relative + "/"))
+          : paths.has(relative);
+      if (!present)
+        throw new Error("Recovery input is outside the retained inventory");
+      return [key, path.resolve(base, relative)];
+    }),
+  );
+  if ((manifest.releaseAssets || []).some((file) => !paths.has(file)))
+    throw new Error("Release asset is outside the retained inventory");
+  return { files, inputs };
+}
+
+export async function restoreRecoveryMaterials(manifest, directory, materials) {
+  const { files, inputs } = recoveryInventory(manifest, directory);
+  let total = 0;
+  for (const { handle, file } of files) {
+    total += handle.size || 0;
+    if (total > 1024 * 1024 * 1024)
+      throw new Error("Recovery material byte budget exceeded");
+    const bytes = await materials.read(handle);
+    if (fs.existsSync(file)) continue;
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, bytes, { flag: "wx" });
+  }
+  return inputs;
+}

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

@@ -0,0 +1,141 @@
+import { createHash } from "node:crypto";
+
+export const ENVELOPE_SCHEMA = "buildchain.discussion-record/v1";
+export const INTENT_SCHEMA = "buildchain.release-discussion/v1";
+export const PAYLOAD_SCHEMA = "buildchain.release-progress/v1";
+const MARKER = "<!-- buildchain-transaction\n";
+export const MAX_RECORD_BYTES = 48_000;
+
+export function canonicalJson(value) {
+  if (typeof value === "number" && !Number.isFinite(value))
+    throw new Error("Transaction numbers must be finite");
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  if (value && typeof value === "object")
+    return `{${Object.keys(value)
+      .sort()
+      .map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`)
+      .join(",")}}`;
+  const encoded = JSON.stringify(value);
+  if (encoded === undefined)
+    throw new Error("Transaction records must contain JSON values");
+  return encoded;
+}
+
+export function recordDigest(value) {
+  return `sha256:${createHash("sha256").update(canonicalJson(value)).digest("hex")}`;
+}
+
+export function requireString(value, label) {
+  if (typeof value !== "string" || !value.trim())
+    throw new Error(`${label} is required`);
+  return value;
+}
+
+export function validateRuntime(runtime) {
+  if (
+    !/^[\w.-]+\/[\w.-]+$/u.test(runtime?.repository || "") ||
+    !/^[a-f0-9]{40}$/u.test(runtime?.sha || "") ||
+    !/^sha256:[a-f0-9]{64}$/u.test(runtime?.readerDigest || "")
+  )
+    throw new Error(
+      "Record requires selected runtime repository, exact revision and reader digest",
+    );
+  return runtime;
+}
+
+export function encodeRecord(
+  record,
+  summary = "Buildchain release transaction record",
+) {
+  const body = `${summary}\n\n${MARKER}${canonicalJson(record)}\n-->`;
+  if (Buffer.byteLength(body) > MAX_RECORD_BYTES)
+    throw new Error(
+      "Transaction record exceeds the bounded body size; retain material as artifacts",
+    );
+  return body;
+}
+
+export function decodeRecord(body) {
+  if (typeof body !== "string" || !body.includes(MARKER)) return undefined;
+  if (Buffer.byteLength(body) > MAX_RECORD_BYTES)
+    throw new Error("Oversized transaction record");
+  const start = body.indexOf(MARKER) + MARKER.length;
+  const end = body.indexOf("\n-->", start);
+  if (end < 0 || body.indexOf(MARKER, start) >= 0)
+    throw new Error("Malformed transaction envelope");
+  const record = JSON.parse(body.slice(start, end));
+  if (![ENVELOPE_SCHEMA, INTENT_SCHEMA].includes(record.schema))
+    throw new Error("Unsupported transaction envelope schema");
+  return record;
+}
+
+export function createIntent({
+  repository,
+  key,
+  expectedNodes,
+  runtime,
+  source,
+}) {
+  requireString(repository, "Consumer repository");
+  requireString(key, "Release intent key");
+  if (key.length > 240 || /[\r\n<>]/u.test(key))
+    throw new Error("Invalid release intent key");
+  if (
+    !Array.isArray(expectedNodes) ||
+    !expectedNodes.length ||
+    new Set(expectedNodes).size !== expectedNodes.length ||
+    expectedNodes.some((node) => !/^[a-z][a-z0-9-]*$/u.test(node))
+  )
+    throw new Error("Release intent requires unique expected semantic nodes");
+  validateRuntime(runtime);
+  const identity = { repository, key };
+  return {
+    schema: INTENT_SCHEMA,
+    id: recordDigest(identity),
+    ...identity,
+    expectedNodes,
+    runtime,
+    source,
+  };
+}
+
+export function createProgress({
+  intent,
+  attempt,
+  predecessor = "",
+  runtime,
+  node,
+  status,
+  payload = {},
+  sequence = 0,
+  kind = "progress",
+  writer = attempt,
+}) {
+  validateRuntime(runtime);
+  requireString(writer, "Record writer");
+  requireString(attempt, "Workflow attempt");
+  if (node !== "attempt" && !intent.expectedNodes.includes(node))
+    throw new Error(`Undeclared release node: ${node}`);
+  if (!["running", "success", "failure", "cancelled"].includes(status))
+    throw new Error("Invalid release node status");
+  if (!Number.isSafeInteger(sequence) || sequence < 0)
+    throw new Error("Invalid record sequence");
+  if (predecessor === attempt) throw new Error("Attempt cannot recover itself");
+  if (!["progress", "checkpoint"].includes(kind))
+    throw new Error("Invalid transaction record kind");
+  const event = {
+    kind,
+    writer,
+    schema: ENVELOPE_SCHEMA,
+    intent: intent.id,
+    attempt,
+    predecessor,
+    runtime,
+    payloadSchema: PAYLOAD_SCHEMA,
+    node,
+    status,
+    sequence,
+    payload,
+  };
+  return { ...event, id: recordDigest(event) };
+}

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

@@ -0,0 +1,121 @@
+import { decodeRecord } from "./envelope.js";
+import { discussionTransport } from "../../providers/github/discussions/transport.js";
+import path from "node:path";
+import fs from "node:fs";
+import { openReleaseSession, RELEASE_NODES } from "./session.js";
+import { releaseCheckpoints, retainRecoveryMaterials } from "./checkpoints.js";
+import { promoteReleaseCandidate } from "../promote-candidate/transaction.js";
+
+export async function publicationNodes(request, graphql) {
+  if (!request["resume-discussion-id"])
+    return [
+      ...RELEASE_NODES,
+      ...(request["standalone-binary-distribution"]
+        ? ["binary-distribution"]
+        : []),
+    ];
+  const discussion = await discussionTransport(graphql).get(
+    request["resume-discussion-id"],
+  );
+  const intent = decodeRecord(discussion.body);
+  if (
+    intent?.repository !== request.repository ||
+    intent.key !== request.version
+  )
+    throw new Error("Discussion recovery cannot change the release intent");
+  return intent.expectedNodes;
+}
+
+export async function publishWithDiscussion(
+  request,
+  {
+    octokit,
+    mutationOctokit,
+    actor,
+    runId,
+    attempt,
+    runtime,
+    workspace,
+    runtimeRoot,
+    observe = () => {},
+  },
+) {
+  const journal = await openReleaseSession({
+    graphql: octokit.graphql,
+    repository: request.repository,
+    key: request.version,
+    source: { version: request.version },
+    expectedNodes: await publicationNodes(request, octokit.graphql),
+    runtime,
+    attempt,
+    discussionId: request["resume-discussion-id"],
+    recover: Boolean(
+      request["resume-discussion-id"] ||
+      request["publish-transaction-override"],
+    ),
+  });
+  const retained = releaseCheckpoints({
+    session: journal.session,
+    store: journal.store,
+    octokit,
+  });
+  const readerFile = path.join(
+    runtimeRoot,
+    "dist/readers/release-discussion.cjs",
+  );
+  const locator = {
+    "discussion-id": journal.session.discussion.id,
+    "discussion-url": journal.session.discussion.url,
+  };
+  observe(locator);
+  const locatorPath = path.join(
+    workspace,
+    ".buildchain/release-tail/buildchain.release-transaction.json",
+  );
+  fs.mkdirSync(path.dirname(locatorPath), { recursive: true });
+  fs.writeFileSync(
+    locatorPath,
+    JSON.stringify({
+      schema: "buildchain.release-locator/v1",
+      repository: request.repository,
+      version: request.version,
+      intent: journal.session.intent.id,
+      discussionId: journal.session.discussion.id,
+    }),
+  );
+  const publicReaderPath = path.join(
+    path.dirname(locatorPath),
+    "release-discussion.cjs",
+  );
+  fs.writeFileSync(
+    publicReaderPath,
+    await retained.publicationReader(fs.readFileSync(readerFile)),
+  );
+  const execution = {
+    ...request,
+    discussionCheckpoint: retained.checkpoint,
+    discussionReaderPath: publicReaderPath,
+    discussionLocatorPath: locatorPath,
+    retainRecoveryMaterials: async () =>
+      retained.checkpoint(
+        "qualification",
+        await retainRecoveryMaterials(
+          { request, workspace, readerFile },
+          retained.materials,
+        ),
+      ),
+  };
+  const result = await promoteReleaseCandidate(execution, {
+    octokit,
+    mutationOctokit,
+    actor,
+    runId,
+    observeNode: journal.observe,
+    observe: (outputs) => observe({ ...outputs, ...locator }),
+  });
+  return {
+    ...result,
+    discussion: journal.session.discussion,
+    outputs: { ...result.outputs, ...locator },
+  };
+}

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

@@ -0,0 +1,121 @@
+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,
+      });
+      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`);
+}