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

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

@@ -0,0 +1,166 @@
+import { readDiscussionThreads, eventParent } from "./threads.js";
+import { renderIntent, renderEvent } from "./presentation.js";
+import { collectDiscussionPages } from "../../providers/github/discussions/transport.js";
+import {
+  canonicalJson,
+  decodeRecord,
+  encodeRecord,
+  INTENT_SCHEMA,
+} from "./envelope.js";
+import { readReleaseDiscussion } from "./reader.js";
+
+function assertDiscussion(discussion, intent, writerId) {
+  if (
+    discussion.repository.nameWithOwner.toLowerCase() !==
+    intent.repository.toLowerCase()
+  )
+    throw new Error("Discussion belongs to a different consumer repository");
+  if (discussion.author?.id !== writerId || discussion.lastEditedAt)
+    throw new Error("Discussion intent has an untrusted author or was edited");
+  const existing = decodeRecord(discussion.body);
+  if (existing?.id !== intent.id || existing.schema !== INTENT_SCHEMA)
+    throw new Error("Discussion contains a different release intent");
+  if (
+    canonicalJson(existing.expectedNodes) !==
+      canonicalJson(intent.expectedNodes) ||
+    canonicalJson(existing.source) !== canonicalJson(intent.source)
+  )
+    throw new Error("Release intent changed during recovery");
+  return existing;
+}
+
+export function releaseDiscussionStore(
+  transport,
+  { sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)) } = {},
+) {
+  async function observeAfterUnknown(readback, cause) {
+    if (
+      [401, 403].includes(cause.status) ||
+      cause.errors?.some((error) =>
+        ["FORBIDDEN", "UNAUTHORIZED"].includes(error.type),
+      )
+    )
+      throw new Error(
+        "Consumer workflow cannot write this Discussion; grant discussions: write and permit Announcements creation",
+        { cause },
+      );
+    for (let attempt = 0; attempt < 4; attempt++) {
+      const record = await readback();
+      if (record) return record;
+      if (attempt < 3) await sleep(250 * (attempt + 1));
+    }
+    throw new Error(
+      "Discussion mutation outcome is unknown; retry by reading the same intent before any further write",
+      { cause },
+    );
+  }
+  async function initialize({
+    intent,
+    discussionId = "",
+    category = "Announcements",
+    dryRun = false,
+  }) {
+    if (dryRun) return { dryRun: true, intent };
+    const repository = await transport.repository(intent.repository);
+    const writerId = repository.viewer.id;
+    if (discussionId) {
+      const discussion = await transport.get(discussionId);
+      const original = assertDiscussion(discussion, intent, writerId);
+      return { discussion, intent: original, writerId };
+    }
+    const selected = repository.discussionCategories.nodes.filter(
+      (entry) => entry.name === category,
+    );
+    if (selected.length !== 1)
+      throw new Error(
+        `Release Discussion category ${category} must exist exactly once`,
+      );
+    const find = async () => {
+      const candidates = await collectDiscussionPages((after) =>
+        transport.list(intent.repository, selected[0].id, after),
+      );
+      const matching = candidates.filter(
+        (discussion) =>
+          discussion.author?.id === writerId &&
+          decodeRecord(discussion.body)?.id === intent.id,
+      );
+      if (matching.length > 1)
+        throw new Error(
+          "Multiple Discussions own this release intent; refusing ambiguous recovery",
+        );
+      if (matching.length) assertDiscussion(matching[0], intent, writerId);
+      return matching[0];
+    };
+    let discussion = await find();
+    if (!discussion) {
+      try {
+        discussion = await transport.create({
+          repositoryId: repository.id,
+          categoryId: selected[0].id,
+          title: intent.source?.qualification
+            ? `Buildchain qualification: ${intent.source.qualification}`
+            : `Buildchain release: ${intent.key}`,
+          body: encodeRecord(intent, renderIntent(intent)),
+        });
+      } catch (error) {
+        discussion = await observeAfterUnknown(find, error);
+      }
+    }
+    const original = assertDiscussion(discussion, intent, writerId);
+    return { discussion, intent: original, writerId };
+  }
+  async function read(session) {
+    const discussion = await transport.get(session.discussion.id);
+    const intent = assertDiscussion(
+      discussion,
+      session.intent,
+      session.writerId,
+    );
+    const threads = await readDiscussionThreads(transport, {
+      ...session,
+      intent,
+      discussion,
+    });
+    return {
+      discussion,
+      ...threads,
+      ...readReleaseDiscussion({
+        body: discussion.body,
+        records: threads.records,
+      }),
+    };
+  }
+  async function append(session, record) {
+    if (session.dryRun) return { dryRun: true };
+    let observed;
+    const find = async () => {
+      observed = await read(session);
+      const existing = observed.comments.find(
+        (comment) => decodeRecord(comment.body)?.id === record.id,
+      );
+      if (!existing)
+        readReleaseDiscussion({
+          body: observed.discussion.body,
+          records: [...observed.records, record],
+        });
+      return existing;
+    };
+    const existing = await find();
+    if (existing) return existing;
+    const parent = eventParent(observed, record);
+    const body = encodeRecord(
+      record,
+      renderEvent(record, session.intent, observed),
+    );
+    try {
+      await transport.append(session.discussion.id, body, parent);
+    } catch (error) {
+      return observeAfterUnknown(find, error);
+    }
+    return observeAfterUnknown(
+      find,
+      new Error("Discussion append requires provider readback"),
+    );
+  }
+  return { initialize, read, append };
+}

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

@@ -0,0 +1,83 @@
+import { decodeRecord } from "./envelope.js";
+import { collectDiscussionPages } from "../../providers/github/discussions/transport.js";
+
+export function isAttemptRoot(record) {
+  return (
+    record?.node === "attempt" &&
+    record.kind === "progress" &&
+    record.status === "running" &&
+    record.sequence === 0
+  );
+}
+
+// Provider placement is checked before the pure reader reduces event semantics.
+// Historical flat records retain their original representation; new writes always
+// use roots and replies. An explicit intent organization makes placement strict.
+export async function readDiscussionThreads(transport, session) {
+  const top = await collectDiscussionPages((after) =>
+    transport.comments(session.discussion.id, after),
+  );
+  const comments = [...top];
+  for (const root of top) {
+    if (root.replies?.totalCount === 0) continue;
+    const replies = await collectDiscussionPages((after) =>
+      transport.replies(root.id, after),
+    );
+    for (const reply of replies) {
+      if (reply.replyTo?.id !== root.id)
+        throw new Error(
+          "Discussion reply parent differs from its queried thread",
+        );
+    }
+    comments.push(...replies);
+    if (Buffer.byteLength(JSON.stringify(comments)) > 32 * 1024 * 1024)
+      throw new Error("Discussion threads exceed the complete-view byte bound");
+  }
+  const trusted = comments.filter(
+    (comment) => comment.author?.id === session.writerId,
+  );
+  const records = new Map();
+  for (const comment of trusted) {
+    const record = decodeRecord(comment.body);
+    if (!record) continue;
+    if (comment.lastEditedAt)
+      throw new Error(
+        "A transaction record was edited; historical facts are no longer intact",
+      );
+    records.set(comment.id, record);
+  }
+  const roots = new Map();
+  for (const comment of trusted) {
+    const record = records.get(comment.id);
+    if (!isAttemptRoot(record)) continue;
+    if (comment.replyTo || roots.has(record.attempt))
+      throw new Error("Ambiguous or nested Discussion attempt root");
+    roots.set(record.attempt, comment);
+  }
+  for (const comment of trusted) {
+    const record = records.get(comment.id);
+    if (!record || isAttemptRoot(record)) continue;
+    const root = roots.get(record.attempt);
+    if (comment.replyTo) {
+      if (!root || comment.replyTo.id !== root.id)
+        throw new Error(
+          "Transaction event is attached to a different attempt root",
+        );
+    } else if (session.intent.organization === "attempt-threads/v1") {
+      throw new Error("Transaction event requires its attempt root reply");
+    }
+  }
+  return { comments: trusted, records: [...records.values()], roots };
+}
+
+export function eventParent(state, record) {
+  const root = state.roots.get(record.attempt);
+  if (isAttemptRoot(record)) {
+    if (root)
+      throw new Error("Attempt root already exists with different content");
+    return null;
+  }
+  if (!root)
+    throw new Error("Open the attempt root before appending its events");
+  return root.id;
+}

package/packages/core/release/github-release.js

@@ -302,6 +302,7 @@ export async function publishGitHubReleaseEvidence({
   declarationPath,
   qualificationRoot = "",
   failureAfterCapability = "",
+  checkpoint: retainCheckpoint,
 } = {}) {
   const assetPaths = collectGitHubReleaseEvidenceAssets({
     publishEvidencePath,
@@ -349,8 +350,9 @@ export async function publishGitHubReleaseEvidence({
       }),
       ...createGitHubProviderAdapters(octokit, materialized.documents),
     }),
-    checkpoint: (checkpoint) => {
+    checkpoint: async (checkpoint) => {
       writeReleaseTailTransaction(resolvedStatePath, checkpoint);
+      if (retainCheckpoint) await retainCheckpoint(checkpoint);
       if (
         failureAfterCapability &&
         checkpoint.receipts.some(

package/packages/core/release/promote-candidate/action.js

@@ -1,9 +1,89 @@
 import * as github from "@actions/github";
-import { promoteReleaseCandidate } from "./transaction.js";
+import { publishWithDiscussion } from "../discussion/publication.js";
+import { selectedRecordRuntime } from "../discussion/session.js";
 export async function candidatePublicationAction(core, env) {
-  const required = new Set(["candidate-build-summary-path", "required-artifacts-path", "target-ref", "target-sha", "candidate-passport-path", "channel", "product-publication-intent-path", "publication-qualification-path", "publisher-workflow-sha", "repository", "runtime-commit", "runtime-tree", "source-sha", "stage-capsules-path", "tag", "token", "version"]);
-  const request = Object.fromEntries(["recovery-receipt-path", "candidate-build-summary-path", "candidate-passport-path", "channel", "failure-after-capability", "mutation-token", "product-publication-intent-path", "publication-qualification-path", "publish-artifact-kind", "publish-auth", "publish-command", "publish-dist-tag", "publish-mode", "publish-package-main", "publish-package-set-order", "publisher-workflow-sha", "repository", "required-artifacts-path", "required-status-check", "resume-transaction-id", "runtime-commit", "runtime-tree", "sealed-bundle-manifest", "sealed-bundle-root", "source-sha", "stage-capsules-path", "state-path", "tag", "target-ref", "target-sha", "token", "version"].map(name => [name, core.getInput(name, { required: required.has(name) }).trim()]));
-  for (const name of ["publish-rematerialize-on-resume", "publish-transaction-override"]) request[name] = core.getBooleanInput(name);
-  request["artifact-paths"] = core.getMultilineInput("artifact-paths").filter(Boolean);
-  return promoteReleaseCandidate(request, { octokit: github.getOctokit(request.token), mutationOctokit: github.getOctokit(request["mutation-token"] || request.token), actor: env.GITHUB_ACTOR, runId: env.GITHUB_RUN_ID || "", observe: outputs => { for (const [key, value] of Object.entries(outputs)) core.setOutput(key, value); } });
+  const required = new Set([
+    "candidate-build-summary-path",
+    "required-artifacts-path",
+    "target-ref",
+    "target-sha",
+    "candidate-passport-path",
+    "channel",
+    "product-publication-intent-path",
+    "publication-qualification-path",
+    "publisher-workflow-sha",
+    "repository",
+    "runtime-commit",
+    "runtime-tree",
+    "source-sha",
+    "stage-capsules-path",
+    "tag",
+    "token",
+    "version",
+  ]);
+  const request = Object.fromEntries(
+    [
+      "recovery-receipt-path",
+      "candidate-build-summary-path",
+      "candidate-passport-path",
+      "channel",
+      "failure-after-capability",
+      "mutation-token",
+      "product-publication-intent-path",
+      "publication-qualification-path",
+      "publish-artifact-kind",
+      "publish-auth",
+      "publish-command",
+      "publish-dist-tag",
+      "publish-mode",
+      "publish-package-main",
+      "publish-package-set-order",
+      "publisher-workflow-sha",
+      "repository",
+      "required-artifacts-path",
+      "required-status-check",
+      "resume-transaction-id",
+      "resume-discussion-id",
+      "runtime-commit",
+      "runtime-tree",
+      "sealed-bundle-manifest",
+      "sealed-bundle-root",
+      "source-sha",
+      "stage-capsules-path",
+      "state-path",
+      "tag",
+      "target-ref",
+      "target-sha",
+      "token",
+      "version",
+    ].map((name) => [
+      name,
+      core.getInput(name, { required: required.has(name) }).trim(),
+    ]),
+  );
+  for (const name of [
+    "publish-rematerialize-on-resume",
+    "publish-transaction-override",
+    "standalone-binary-distribution",
+  ])
+    request[name] = core.getBooleanInput(name);
+  request["artifact-paths"] = core
+    .getMultilineInput("artifact-paths")
+    .filter(Boolean);
+  return publishWithDiscussion(request, {
+    octokit: github.getOctokit(request.token),
+    mutationOctokit: github.getOctokit(
+      request["mutation-token"] || request.token,
+    ),
+    actor: env.GITHUB_ACTOR,
+    runId: env.GITHUB_RUN_ID,
+    attempt: `${env.GITHUB_RUN_ID}:${env.GITHUB_RUN_ATTEMPT}:${env.GITHUB_ACTION}`,
+    runtime: selectedRecordRuntime(env),
+    workspace: env.GITHUB_WORKSPACE,
+    runtimeRoot: env.BUILDCHAIN_RUNTIME_ROOT,
+    observe: (outputs) => {
+      for (const [key, value] of Object.entries(outputs))
+        core.setOutput(key, value);
+    },
+  });
 }

package/packages/core/release/promote-candidate/preparation.js

@@ -0,0 +1,106 @@
+import {
+  resolveCandidateBuildSummaryPath,
+  resolveCandidateProviderInputs,
+  resolvePublicationTarget,
+} from "./evidence-inputs.js";
+import {
+  assertCandidateEvidenceBinding,
+  canonicalChannel,
+  observeProtectedPublicationSource,
+} from "./evidence-binding.js";
+import { productProviderRequest } from "./provider-request.js";
+import { createReleaseDocuments } from "./release-documents.js";
+import { read } from "./files.js";
+import { planProductPublication } from "./product-provider.js";
+import path from "node:path";
+export async function prepareCandidatePublication(
+  request,
+  { octokit, mutationOctokit, actor, runId },
+) {
+  const repository = request["repository"];
+  const declaredSourceSha = request["source-sha"];
+  const fallbackVersion = request["version"];
+  const fallbackTag = request["tag"];
+  const channel = request["channel"];
+  const expectedTransactionId = request["resume-transaction-id"];
+  const candidatePassportPath = request["candidate-passport-path"];
+  const buildSummaryPath = resolveCandidateBuildSummaryPath({
+    declaredPath: request["candidate-build-summary-path"],
+  });
+  const candidate = read(candidatePassportPath);
+  const stageCapsules = read(request["stage-capsules-path"]);
+  const qualification = read(request["publication-qualification-path"]);
+  const token = request["token"];
+  const publicationTarget = resolvePublicationTarget({
+    recoveryReceiptPath: request["recovery-receipt-path"],
+    candidate,
+    repository,
+    channel,
+    sourceSha: declaredSourceSha,
+    targetRef: request["target-ref"],
+    targetSha: request["target-sha"],
+    expectedTransactionId,
+  });
+  const sourceSha = publicationTarget.sourceSha;
+  assertCandidateEvidenceBinding({ candidate, stageCapsules, repository });
+  const sourceBinding = await observeProtectedPublicationSource({
+    octokit,
+    repository,
+    protectedSourceSha: sourceSha,
+    candidate,
+  });
+  const providerInputs = resolveCandidateProviderInputs({
+    recoveryReceiptPath: request["recovery-receipt-path"],
+    artifactKind: request["publish-artifact-kind"] || "npm",
+    sealedBundleRoot: request["sealed-bundle-root"],
+    sealedBundleManifest: request["sealed-bundle-manifest"],
+    requiredArtifactsPath: request["required-artifacts-path"],
+    publishPackageMain: request["publish-package-main"],
+  });
+  const providerRequest = productProviderRequest({
+    request,
+    actor,
+    runId,
+    octokit,
+    mutationOctokit,
+    repository,
+    targetRef: publicationTarget.targetRef,
+    targetSha: publicationTarget.targetSha,
+    candidate,
+    candidatePassportPath,
+    buildSummaryPath,
+    qualification,
+    providerInputs,
+  });
+  const publicationPlan = await planProductPublication(providerRequest, {
+    fallbackVersion,
+    fallbackTag,
+  });
+  const documents = await createReleaseDocuments({
+    request,
+    actor,
+    runId,
+    repository,
+    sourceSha,
+    fallbackVersion,
+    channel,
+    candidate,
+    stageCapsules,
+    qualification,
+    sourceBinding,
+    publicationPlan,
+    publicationIntent: providerRequest.publicationIntent,
+    octokit,
+  });
+  return {
+    repository,
+    sourceSha,
+    token,
+    channel,
+    qualification,
+    providerRequest,
+    publicationPlan,
+    documents,
+    sourceBinding,
+  };
+}

package/packages/core/release/promote-candidate/product-provider.js

@@ -159,7 +159,10 @@ export async function applyProductPublication(request, plan) {
   });
   transaction = await executeReleaseTailTransaction(transaction, {
     adapters: runtime.adapters,
-    checkpoint: (next) => writeReleaseTailTransaction(statePath, next),
+    checkpoint: async (next) => {
+      writeReleaseTailTransaction(statePath, next);
+      if (request.discussionCheckpoint) await request.discussionCheckpoint("publication", next);
+    },
   });
   writeReleaseTailTransaction(statePath, transaction);
   const releaseSha = await runtime.resolveReleaseSha();

package/packages/core/release/promote-candidate/provider-settlement.js

@@ -18,12 +18,16 @@ export async function applyAndSettle({
   providerRequest,
   publicationPlan,
   documents,
+  observeNode = (_node, effect) => effect(),
 }) {
+  providerRequest.discussionCheckpoint = request.discussionCheckpoint;
   let productProviderResult;
   try {
-    productProviderResult = await applyProductPublication(
-      providerRequest,
-      documents.productPublicationPlan,
+    productProviderResult = await observeNode("publication", () =>
+      applyProductPublication(
+        providerRequest,
+        documents.productPublicationPlan,
+      ),
     );
   } catch (error) {
     if (error.providerProjection)
@@ -37,26 +41,35 @@ export async function applyAndSettle({
     ".buildchain/release-tail/product-provider-result.json",
     productProviderResult,
   );
-  const result = await publishGitHubReleaseEvidence({
-    octokit,
-    repository,
-    sourceSha: productProviderResult.promotedSha,
-    version: documents.version,
-    tag: documents.tag,
-    channel,
-    publishEvidencePath: documents.evidencePath,
-    releasePassportPath: documents.passportPath,
-    releasePassportOutputDir: path.dirname(documents.passportPath),
-    additionalAssetPaths: [
-      ...request["artifact-paths"],
-      ...(providerRequest.publicationIntent.artifactKind === "oci"
-        ? [".buildchain/release-tail/oci-publication-readback.json"]
-        : []),
-    ],
-    statePath: request["state-path"] || ".buildchain/release-tail/state.json",
-    qualificationRoot: qualification.receiptRoot,
-    failureAfterCapability: request["failure-after-capability"],
-  });
+  const result = await observeNode("github-release", () =>
+    publishGitHubReleaseEvidence({
+      octokit,
+      repository,
+      sourceSha: productProviderResult.promotedSha,
+      version: documents.version,
+      tag: documents.tag,
+      channel,
+      publishEvidencePath: documents.evidencePath,
+      releasePassportPath: documents.passportPath,
+      releasePassportOutputDir: path.dirname(documents.passportPath),
+      additionalAssetPaths: [
+        ...request["artifact-paths"],
+        ...(request.discussionReaderPath ? [request.discussionReaderPath] : []),
+        ...(request.discussionLocatorPath
+          ? [request.discussionLocatorPath]
+          : []),
+        ...(providerRequest.publicationIntent.artifactKind === "oci"
+          ? [".buildchain/release-tail/oci-publication-readback.json"]
+          : []),
+      ],
+      statePath: request["state-path"] || ".buildchain/release-tail/state.json",
+      qualificationRoot: qualification.receiptRoot,
+      failureAfterCapability: request["failure-after-capability"],
+      checkpoint: request.discussionCheckpoint
+        ? (state) => request.discussionCheckpoint("github-release", state)
+        : undefined,
+    }),
+  );
   const releaseReceipt = createReleaseReceipt({
     schema: RELEASE_RECEIPT_CONTRACT,
     transactionRoot: documents.releaseTransaction.transactionRoot,