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

package/packages/core/consumer/contract/shape.js

@@ -0,0 +1,46 @@
+// Closed data validation shared by TOML, event identities and managed locks.
+export function object(value, required, optional = [], location = "config") {
+  if (!value || Object.getPrototypeOf(value) !== Object.prototype)
+    throw new Error(`${location}: expected a table`);
+  for (const key of Object.keys(value))
+    if (![...required, ...optional].includes(key))
+      throw new Error(`${location}.${key}: unknown field`);
+  for (const key of required)
+    if (!Object.hasOwn(value, key))
+      throw new Error(`${location}.${key}: required field`);
+  return value;
+}
+
+export function text(value, location, pattern = /\S/u) {
+  if (typeof value !== "string" || !pattern.test(value) || value.includes("\0"))
+    throw new Error(`${location}: invalid string`);
+  return value;
+}
+
+export function choice(value, choices, location) {
+  if (!choices.includes(value))
+    throw new Error(`${location}: expected ${choices.join(" or ")}`);
+  return value;
+}
+
+export function list(value, location, validate) {
+  if (!Array.isArray(value) || !value.length)
+    throw new Error(`${location}: expected a nonempty list`);
+  return value.map((item, index) => validate(item, `${location}[${index}]`));
+}
+
+export function unique(values, location) {
+  if (new Set(values).size !== values.length)
+    throw new Error(`${location}: duplicate identity`);
+}
+
+export function relativePath(value, location) {
+  text(value, location, /^[A-Za-z0-9_.][A-Za-z0-9_./*-]*$/u);
+  if (value.split("/").some((part) => !part || part === ".." || part === "."))
+    throw new Error(`${location}: expected a repository-relative path`);
+  return value;
+}
+
+export function slug(value, location) {
+  return text(value, location, /^[a-z][a-z0-9-]*$/u);
+}

package/packages/core/dev-delivery/candidate/admission.js

@@ -1,10 +1,7 @@
 import path from "node:path";
 import fs from "node:fs";
 import crypto from "node:crypto";
-import {
-  sourceCoordinates,
-  validateNativeContract,
-} from "./coordinates.js";
+import { sourceCoordinates, validateNativeContract } from "./coordinates.js";
 import {
   verifyProjectCutReplayProof,
   createSourceQualificationProof,
@@ -16,6 +13,7 @@ import { assertBranchUnlocked } from "../../providers/dev-delivery/protection.js
 import { deriveSourcePaths } from "./source-paths.js";
 import { admissionPolicyRequest } from "../admission/request.js";
 import { runAdmissionTransaction } from "../admission/transaction.js";
+import { guardPipelineAdmission } from "../../workflow/pipeline/guard.js";
 export function admitDeliveryRequest(input, defaultBranch) {
   const target = sourceCoordinates({
     branch: input["target-branch"],
@@ -46,6 +44,7 @@ export async function qualifyDeliverySource(
   },
   dependencies = {},
 ) {
+  const pipeline = await guardPipelineAdmission(request, { repository, token });
   const outputs = {
     "runtime-sha": runtimeSha,
     "qualify-outcome": "skipped",
@@ -146,7 +145,12 @@ export async function qualifyDeliverySource(
   if (!affectedPaths.length)
     affectedPaths = await (dependencies.derivePaths || deriveSourcePaths)(
       source,
-      { token, apiUrl, environment },
+      {
+        token,
+        apiUrl,
+        environment,
+        qualifiedBase: pipeline?.history.at(-1).generation.baseCommit,
+      },
     );
   const receiptRoot = qualification.result.receiptRoot;
   if (!/^sha256:[0-9a-f]{64}$/u.test(receiptRoot || ""))

package/packages/core/dev-delivery/candidate/reservation.js

@@ -10,6 +10,8 @@ import { dispatchDeliveryHandoff } from "../warrant/handoff.js";
 import { resolveCandidateAffectedPaths } from "./evidence.js";
 import { deliverySubmissionRequest } from "./submission.js";
 import { jsonList } from "../warrant/values.js";
+import { guardPipelineAdmission } from "../../workflow/pipeline/guard.js";
+import { wakePipelineCandidate } from "../../workflow/pipeline/wake.js";
 export async function reserveDeliveryCandidate(
   {
     workspace,
@@ -31,6 +33,7 @@ export async function reserveDeliveryCandidate(
     );
   if (!predecessorsOk || proofOutcome !== "success")
     throw new Error("Delivery candidate submission failed");
+  await guardPipelineAdmission(input, connection);
   const service =
     dependencies.service ||
     createDeliveryWarrantService({ ...connection, branch });
@@ -77,6 +80,14 @@ export async function reserveDeliveryCandidate(
     warrant.pullRequestNumber !== Number(input["expected-pr-number"]) ||
     warrant.sourceHead !== input["expected-head-sha"]
   ) {
+    if (input["pipeline-attempt"]) {
+      await wakePipelineCandidate(warrant, { ...connection, branch });
+      return {
+        "warrant-outcome": "success",
+        "warrant-handoff-required": "true",
+        "warrant-handoff-dispatched": "true",
+      };
+    }
     outputs = await dispatchDeliveryHandoff(
       {
         warrant,

package/packages/core/dev-delivery/candidate/source-paths.js

@@ -52,7 +52,7 @@ export function pathsAtQualifiedSource(directory, qualifiedBase, source) {
 
 export async function deriveSourcePaths(
   source,
-  { token, apiUrl, environment = process.env },
+  { token, apiUrl, environment = process.env, qualifiedBase },
   provider = new GitHubTwoPhaseClient({
     repository: source.repository,
     token,
@@ -65,10 +65,18 @@ export async function deriveSourcePaths(
       /^[1-9]\d*$/u.test(String(source.sourceWorkflowRunId || "")),
     "Exact source run coordinates are required",
   );
-  const run = await provider.request(
-    `/repos/${source.repository}/actions/runs/${source.sourceWorkflowRunId}`,
+  if (qualifiedBase === undefined) {
+    const run = await provider.request(
+      `/repos/${source.repository}/actions/runs/${source.sourceWorkflowRunId}`,
+    );
+    qualifiedBase = qualifiedRunBase(run, source);
+  }
+  // The internal pipeline guard already requalifies the source run and immutable
+  // generation. Zero-delta recovery still verifies the full source identity below.
+  requireValue(
+    /^[0-9a-f]{40}$/u.test(qualifiedBase || ""),
+    "Exact qualified source base is required",
   );
-  const qualifiedBase = qualifiedRunBase(run, source);
   const directory = fs.mkdtempSync(
     path.join(os.tmpdir(), "buildchain-source-paths-"),
   );

package/packages/core/dev-delivery/commands/project-cut-merge-queue-admission.mjs

@@ -61,19 +61,32 @@ function git(
   {
     env = {},
     input = undefined,
+    inputFile = undefined,
+    outputFile = undefined,
     encoding = "utf8",
     reason = "git-failed",
   } = {},
 ) {
-  const result = spawnSync("git", args, {
-    cwd,
-    env: { ...process.env, ...env },
-    input,
-    encoding,
-    maxBuffer: 64 * 1024 * 1024,
-  });
+  let result, inputDescriptor, outputDescriptor;
+  try {
+    if (inputFile) inputDescriptor = fs.openSync(inputFile, "r");
+    if (outputFile) outputDescriptor = fs.openSync(outputFile, "w");
+    result = spawnSync("git", args, {
+      cwd,
+      env: { ...process.env, ...env },
+      input,
+      encoding,
+      stdio: [inputDescriptor ?? "pipe", outputDescriptor ?? "pipe", "pipe"],
+      maxBuffer: 64 * 1024 * 1024,
+    });
+  } finally {
+    for (const descriptor of [inputDescriptor, outputDescriptor])
+      if (descriptor !== undefined) fs.closeSync(descriptor);
+  }
   if (result.status !== 0) {
-    const detail = String(result.stderr || result.stdout || "").trim();
+    const detail = String(
+      result.stderr || result.error?.message || result.stdout || "",
+    ).trim();
     throw new ProjectCutAdmissionError(
       reason,
       `git ${args.join(" ")} failed${detail ? `: ${detail}` : ""}`,
@@ -135,7 +148,7 @@ function linearSourceCommits(cwd, fork, head) {
 
 function patchId(cwd, patch) {
   const output = git(cwd, ["patch-id", "--stable"], {
-    input: patch,
+    inputFile: patch,
     encoding: "utf8",
     reason: "patch-id-failed",
   });
@@ -184,30 +197,41 @@ function replayProjectCut(cwd, base, head) {
       env: indexEnvironment,
       reason: "base-tree-unreadable",
     });
-    const sourcePatch = git(
+    // Generated bundles can exceed the metadata-output bound. Git streams the
+    // exact patches through private files; patch identity and replay stay intact.
+    const sourcePatch = path.join(temporary, "source.patch");
+    git(
       cwd,
       ["diff", "--binary", "--full-index", "--no-ext-diff", fork, head],
       {
-        encoding: null,
+        outputFile: sourcePatch,
         reason: "source-patch-unreadable",
       },
     );
-    const emptySourcePatch = sourcePatch.length === 0;
+    const emptySourcePatch = fs.statSync(sourcePatch).size === 0;
     if (emptySourcePatch && commits.length !== 1)
-      throw new ProjectCutAdmissionError("empty-source-composition", "an empty source composition must be exactly one linear commit");
-    if (!emptySourcePatch) git(cwd, ["apply", "--cached", "--3way", "--whitespace=nowarn", "-"], {
-        env: indexEnvironment, input: sourcePatch, encoding: "utf8", reason: "project-cut-conflict",
+      throw new ProjectCutAdmissionError(
+        "empty-source-composition",
+        "an empty source composition must be exactly one linear commit",
+      );
+    if (!emptySourcePatch)
+      git(cwd, ["apply", "--cached", "--3way", "--whitespace=nowarn", "-"], {
+        env: indexEnvironment,
+        inputFile: sourcePatch,
+        encoding: "utf8",
+        reason: "project-cut-conflict",
       });
     const candidateTreeOid = git(cwd, ["write-tree"], {
       env: indexEnvironment,
       reason: "candidate-tree-unreadable",
     });
-    const replayPatch = git(
+    const replayPatch = path.join(temporary, "replay.patch");
+    git(
       cwd,
       ["diff", "--cached", "--binary", "--full-index", "--no-ext-diff", base],
       {
         env: indexEnvironment,
-        encoding: null,
+        outputFile: replayPatch,
         reason: "replay-patch-unreadable",
       },
     );
@@ -226,9 +250,12 @@ function replayProjectCut(cwd, base, head) {
         reason: "replay-paths-unreadable",
       },
     );
-    const compositionDrifted = emptySourcePatch ? replayPatch.length !== 0 ||
-      sourceNames !== "" || replayNames !== "" : patchId(cwd, sourcePatch) !==
-      patchId(cwd, replayPatch) || sourceNames !== replayNames;
+    const compositionDrifted = emptySourcePatch
+      ? fs.statSync(replayPatch).size !== 0 ||
+        sourceNames !== "" ||
+        replayNames !== ""
+      : patchId(cwd, sourcePatch) !== patchId(cwd, replayPatch) ||
+        sourceNames !== replayNames;
     if (compositionDrifted) {
       throw new ProjectCutAdmissionError(
         "composition-drift",

package/packages/core/dev-delivery/native/actions.js

@@ -5,6 +5,7 @@ import {
   qualifyTransferredNative,
 } from "./transactions.js";
 import { admitProviderFinalizer } from "./finalizer-admission.js";
+import { guardPipelineAdmission } from "../../workflow/pipeline/guard.js";
 function request(core, env) {
   const candidate = JSON.parse(
     core.getInput("request-json", { required: true }),
@@ -41,11 +42,16 @@ export async function executeDeliveryNativeAction(core, env) {
 }
 export async function qualifyTransferredNativeAction(core, env) {
   const context = deliveryActionContext(core, env);
+  const input = request(core, env);
+  await guardPipelineAdmission(input.request, {
+    repository: env.GITHUB_REPOSITORY,
+    token: core.getInput("token", { required: true }),
+  });
   outputs(
     core,
     await qualifyTransferredNative({
       ...context,
-      candidate: request(core, env).candidate,
+      candidate: input.candidate,
       sourceProofRoot: core.getInput("source-proof-root", { required: true }),
       token: core.getInput("token", { required: true }),
       apiUrl: env.GITHUB_API_URL || "https://api.github.com",

package/packages/core/dev-delivery/native/heartbeat-action.js

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { deliveryActionContext } from "./action-context.js";
 import { heartbeatDeliveryAttempt } from "./heartbeat.js";
+import { guardPipelineDelivery } from "../../workflow/pipeline/guard.js";
 export async function heartbeatDeliveryAttemptAction(core, env) {
   const { workspace, run } = deliveryActionContext(core, env);
   const admission = JSON.parse(
@@ -20,6 +21,21 @@ export async function heartbeatDeliveryAttemptAction(core, env) {
     apiUrl: env.GITHUB_API_URL || "https://api.github.com",
     leaseSeconds: Number(core.getInput("lease-seconds")),
     heartbeatSeconds: Number(core.getInput("heartbeat-seconds")),
+    beforeHeartbeat: () => {
+      const warrant = admission.observation?.activeWarrant || admission.warrant;
+      return guardPipelineDelivery(
+        {
+          "pipeline-attempt": core.getInput("pipeline-attempt"),
+          "target-branch": core.getInput("branch", { required: true }),
+          "expected-pr-number": warrant?.pullRequestNumber,
+          "expected-head-sha": warrant?.sourceHead,
+        },
+        {
+          repository: env.GITHUB_REPOSITORY,
+          token: core.getInput("token", { required: true }),
+        },
+      );
+    },
   });
   fs.writeFileSync(
     path.join(workspace, ".buildchain/provider-heartbeat-receipt.json"),

package/packages/core/dev-delivery/native/heartbeat.js

@@ -68,13 +68,14 @@ export async function heartbeatDeliveryAttempt(options) {
       heartbeatSeconds: options.heartbeatSeconds,
     },
     {
-      heartbeat: ({
+      heartbeat: async ({
         expectedOldStateRoot,
         fencingToken,
         leaseGeneration,
         leaseSeconds,
-      }) =>
-        runDevDeliveryCommand({
+      }) => {
+        await options.beforeHeartbeat?.();
+        return runDevDeliveryCommand({
           command: "heartbeat",
           repository: options.repository,
           branch: options.branch,
@@ -85,7 +86,8 @@ export async function heartbeatDeliveryAttempt(options) {
           execute: true,
           token: options.token,
           apiUrl: options.apiUrl,
-        }),
+        });
+      },
       readJobs: () =>
         githubJson(
           options.apiUrl,

package/packages/core/dev-delivery/queue/landing-action.js

@@ -3,9 +3,14 @@ import { deliveryActionContext } from "../native/action-context.js";
 import { admissionPolicyRequest } from "../admission/request.js";
 import { runAdmissionTransaction } from "../admission/transaction.js";
 import { enforceLanding } from "./completion.js";
+import { guardPipelineAdmission } from "../../workflow/pipeline/guard.js";
 export async function admitLandingAction(core, env) {
   const context = deliveryActionContext(core, env);
   const request = JSON.parse(core.getInput("request-json", { required: true }));
+  await guardPipelineAdmission(request, {
+    repository: env.GITHUB_REPOSITORY,
+    token: core.getInput("token", { required: true }),
+  });
   const result = await runAdmissionTransaction(
     {
       ...admissionPolicyRequest(request, {

package/packages/core/governance/buildchain-publication-authority.js

@@ -39,6 +39,12 @@ const DESCRIPTORS = Object.freeze([
   [".github/workflows/public-ops-warrant-cancel.yml", "governance-write"],
   [".github/workflows/self-ops-merge-queue.yml", "governance-write"],
   [".github/workflows/public-ops-dev-auto-merge.yml", "governance-write"],
+  [".github/workflows/public-ops-pipeline.yml", "product-publication", true, ["npm-publish", "github-release", "channel-ref"], "trusted-publishing", "none", "fixed", "fixed", ".github/workflows/.release-pipeline-products.yml"],
+  [".github/workflows/public-ops-recover.yml", "product-publication", true, ["npm-publish", "github-release", "channel-ref"], "trusted-publishing", "none", "fixed", "fixed", ".github/workflows/.release-pipeline-products.yml"],
+  [".github/workflows/.ops-pipeline-execute.yml", "product-publication", true, ["npm-publish", "github-release", "channel-ref"], "trusted-publishing", "none", "fixed", "fixed", ".github/workflows/.release-pipeline-products.yml"],
+  [".github/workflows/.release-pipeline-products.yml", "product-publication", true, ["npm-publish", "github-release", "channel-ref"], "trusted-publishing", "none", "fixed", "fixed"],
+  [".github/workflows/.release-pipeline-version.yml", "governance-write"],
+  [".github/workflows/.ops-pipeline-delivery.yml", "governance-write"],
   [".github/workflows/self-ops-housekeeping-daily.yml", "governance-write"],
   [".github/workflows/self-ops-housekeeping-monthly.yml", "governance-write"],
   [".github/workflows/self-ops-housekeeping-weekly.yml", "governance-write"],

package/packages/core/paper/operations/bootstrap.js

@@ -1,3 +1,4 @@
+import { readNpmPackResult } from "../../publication/npm/pack-result.js";
 import path from "node:path";
 import fs from "node:fs";
 import { jsonText, extractUrls, safeParseJson, toPosix } from "./files.js";
@@ -66,6 +67,7 @@ export function executePaperNpmBootstrap(options = {}) {
     path,
     resolvePaperRepository,
     safeParseJson,
+    readNpmPackResult,
     toPosix,
     validatePaperProvisioningAuthority,
     writePaperReceipt,

package/packages/core/paper/paper-npm-bootstrap.js

@@ -20,6 +20,7 @@ function executePaperNpmBootstrap(options = {}, runtime) {
     path,
     resolvePaperRepository,
     safeParseJson,
+    readNpmPackResult,
     toPosix,
     validatePaperProvisioningAuthority,
     writePaperReceipt,
@@ -208,8 +209,7 @@ function executePaperNpmBootstrap(options = {}, runtime) {
           pack: {
             status: pack.ok ? "pass" : "fail",
             entryCount: (() => {
-              const parsed = safeParseJson(pack.stdout);
-              const value = Array.isArray(parsed) ? parsed[0] : parsed;
+              const value = pack.ok ? readNpmPackResult(pack.stdout) : null;
               return Array.isArray(value?.files) ? value.files.length : 0;
             })(),
           },

package/packages/core/providers/github/attempt-index.js

@@ -0,0 +1,60 @@
+// Immutable lookup pointers are derived from admitted journal commits. The
+// canonical intent journal must contain the selected root before a pointer can
+// resolve; an orphan commit or pointer cannot create attempt authority.
+export function githubAttemptIndex(request, journal, repository) {
+  if (!/^[\w.-]+\/[\w.-]+$/u.test(repository || ""))
+    throw new Error("Invalid attempt lookup repository");
+  const base = `/repos/${repository}`;
+  function ref(attempt) {
+    if (!/^attempt-[0-9a-f]{64}$/u.test(attempt || ""))
+      throw new Error("Invalid business attempt selector");
+    return `buildchain/attempt-index/${attempt}`;
+  }
+  function root(snapshot, attempt) {
+    const roots = snapshot.records.filter(
+      (record) => record.attempt === attempt && record.node === "attempt",
+    );
+    if (roots.length !== 1)
+      throw new Error("Lookup does not identify one admitted attempt root");
+    return roots[0];
+  }
+  async function resolve(attempt) {
+    const pointer = await request(`${base}/git/ref/heads/${ref(attempt)}`, {
+      allow404: true,
+    });
+    if (!pointer) throw new Error("Business attempt lookup is not retained");
+    const indexed = await journal.readCommit(repository, pointer.object?.sha);
+    const selected = root(indexed.snapshot, attempt);
+    const current = await journal.read(indexed.snapshot.intent);
+    if (!current || root(current.snapshot, attempt).id !== selected.id)
+      throw new Error(
+        "Lookup attempt is absent from the authoritative journal",
+      );
+    return { ...current, selectedAttempt: attempt };
+  }
+  async function retain(intent, attempt) {
+    if (intent.repository !== repository)
+      throw new Error("Attempt lookup repository drift");
+    const current = await journal.read(intent);
+    if (!current) throw new Error("Cannot index an unadmitted attempt");
+    const expected = root(current.snapshot, attempt);
+    let failure;
+    try {
+      await request(`${base}/git/refs`, {
+        method: "POST",
+        body: { ref: `refs/heads/${ref(attempt)}`, sha: current.commit },
+      });
+    } catch (error) {
+      failure = error;
+    }
+    try {
+      const result = await resolve(attempt);
+      if (root(result.snapshot, attempt).id !== expected.id)
+        throw new Error("Conflicting business attempt lookup");
+      return result;
+    } catch (error) {
+      throw failure || error;
+    }
+  }
+  return { retain, resolve };
+}

package/packages/core/providers/github/attempt-journal.js

@@ -0,0 +1,154 @@
+import { createHash } from "node:crypto";
+import {
+  canonicalJson,
+  recordDigest,
+} from "../../release/discussion/envelope.js";
+import { validateJournal } from "../../workflow/attempt/journal.js";
+
+const PATH = "attempt.json";
+const LIMIT = 34 * 1024 * 1024;
+
+function exactSha(value) {
+  if (!/^[0-9a-f]{40}$/u.test(value || ""))
+    throw new Error("Attempt journal requires an exact Git SHA");
+  return value;
+}
+
+export function githubAttemptJournal(request) {
+  function coordinates(intent) {
+    if (
+      !/^[\w.-]+\/[\w.-]+$/u.test(intent.repository) ||
+      !/^sha256:[0-9a-f]{64}$/u.test(intent.id)
+    )
+      throw new Error("Invalid attempt journal coordinates");
+    return {
+      base: `/repos/${intent.repository}`,
+      ref: `buildchain/attempts/${intent.id.slice(7)}`,
+    };
+  }
+  async function verifyRepository(intent, base) {
+    const repository = await request(base);
+    if (repository.node_id !== intent.source.repositoryId)
+      throw new Error("Attempt repository identity changed");
+  }
+  async function read(intent) {
+    const { base, ref } = coordinates(intent);
+    await verifyRepository(intent, base);
+    const pointer = await request(`${base}/git/ref/heads/${ref}`, {
+      allow404: true,
+    });
+    if (!pointer) return null;
+    if (pointer.object?.type !== "commit")
+      throw new Error("Attempt journal ref is not a commit");
+    const result = await readCommit(intent.repository, pointer.object.sha);
+    validateJournal(result.snapshot, intent);
+    return result;
+  }
+  async function readCommit(repository, commitSha) {
+    if (!/^[\w.-]+\/[\w.-]+$/u.test(repository || ""))
+      throw new Error("Invalid attempt journal repository");
+    const base = `/repos/${repository}`;
+    const sha = exactSha(commitSha);
+    const commit = await request(`${base}/git/commits/${sha}`);
+    const tree = await request(
+      `${base}/git/trees/${exactSha(commit.tree?.sha)}`,
+    );
+    if (
+      tree.truncated ||
+      tree.tree?.length !== 1 ||
+      tree.tree[0].path !== PATH ||
+      tree.tree[0].type !== "blob" ||
+      tree.tree[0].mode !== "100644"
+    )
+      throw new Error("Invalid attempt journal tree");
+    const blobSha = exactSha(tree.tree[0].sha);
+    const blob = await request(`${base}/git/blobs/${blobSha}`);
+    if (
+      blob.encoding !== "base64" ||
+      !Number.isSafeInteger(blob.size) ||
+      blob.size < 0 ||
+      blob.size > LIMIT ||
+      typeof blob.content !== "string" ||
+      blob.content.length > LIMIT * 2
+    )
+      throw new Error("Invalid or oversized attempt journal blob");
+    const bytes = Buffer.from(blob.content, "base64");
+    const digest = createHash("sha1")
+      .update(`blob ${bytes.length}\0`)
+      .update(bytes)
+      .digest("hex");
+    if (bytes.length !== blob.size || digest !== blobSha)
+      throw new Error("Attempt journal blob integrity mismatch");
+    const snapshot = JSON.parse(bytes.toString("utf8"));
+    if (snapshot.intent?.repository !== repository)
+      throw new Error("Attempt journal snapshot belongs to another repository");
+    validateJournal(snapshot, snapshot.intent);
+    await verifyRepository(snapshot.intent, base);
+    return { commit: sha, snapshot };
+  }
+  async function append({ intent, snapshot, expectedCommit }) {
+    validateJournal(snapshot, intent);
+    const { base, ref } = coordinates(intent);
+    await verifyRepository(intent, base);
+    const bytes = `${canonicalJson(snapshot)}\n`;
+    if (Buffer.byteLength(bytes) > LIMIT)
+      throw new Error("Attempt journal byte bound exceeded");
+    const blob = await request(`${base}/git/blobs`, {
+      method: "POST",
+      body: { content: bytes, encoding: "utf-8" },
+    });
+    const tree = await request(`${base}/git/trees`, {
+      method: "POST",
+      body: {
+        tree: [
+          { path: PATH, mode: "100644", type: "blob", sha: exactSha(blob.sha) },
+        ],
+      },
+    });
+    const commit = await request(`${base}/git/commits`, {
+      method: "POST",
+      body: {
+        message: `chore(attempt): append ${snapshot.root}`,
+        tree: exactSha(tree.sha),
+        parents: expectedCommit ? [exactSha(expectedCommit)] : [],
+      },
+    });
+    const sha = exactSha(commit.sha);
+    if (expectedCommit)
+      await request(`${base}/git/refs/heads/${ref}`, {
+        method: "PATCH",
+        body: { sha, force: false },
+      });
+    else
+      await request(`${base}/git/refs`, {
+        method: "POST",
+        body: { ref: `refs/heads/${ref}`, sha },
+      });
+    return { commit: sha };
+  }
+  async function lookup(repository, pullRequest, targetBranch) {
+    if (
+      !Number.isSafeInteger(pullRequest) ||
+      pullRequest < 1 ||
+      !/^(?:dev|alpha|release|publish-gate)\/[A-Za-z0-9/._-]+$/u.test(
+        targetBranch || "",
+      ) ||
+      targetBranch.includes("..")
+    )
+      throw new Error("Invalid pipeline intent lookup");
+    const id = recordDigest({
+      repository,
+      key: `pr-${pullRequest}:${targetBranch}`,
+    });
+    const { base, ref } = coordinates({ repository, id });
+    const pointer = await request(`${base}/git/ref/heads/${ref}`, {
+      allow404: true,
+    });
+    if (!pointer) return null;
+    const result = await readCommit(repository, pointer.object?.sha);
+    if (result.snapshot.intent.id !== id)
+      throw new Error("Pipeline intent lookup drift");
+    return result;
+  }
+  return { read, append, readCommit, lookup };
+}

package/packages/core/providers/github/discussions/materials.js

@@ -6,7 +6,12 @@ export function materialDigest(bytes) {
 
 // Draft release assets retain immutable recovery bytes outside the source Git
 // object database. Only the Discussion record selects a committed manifest.
-export function discussionMaterials({ octokit, repository, intentId }) {
+export function discussionMaterials({
+  octokit,
+  repository,
+  intentId,
+  authorityDescription = "The associated Discussion owns transaction state.",
+}) {
   const [owner, repo] = repository.split("/");
   const tag = `buildchain-records/${intentId.replace("sha256:", "")}`;
   const repos = octokit.rest.repos;
@@ -40,7 +45,7 @@ export function discussionMaterials({ octokit, repository, intentId }) {
             // Storage archives use the repository default; candidate identity is
             // retained in the material manifest, never in a storage Git ref.
             name: `Buildchain transaction materials ${intentId}`,
-            body: "Immutable recovery material. The associated Discussion owns transaction state.",
+            body: `Immutable recovery material. ${authorityDescription}`,
             draft: true,
             prerelease: true,
           })