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

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,9 +6,17 @@ 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,
+  partition = "",
+  authorityDescription = "The associated Discussion owns transaction state.",
+}) {
   const [owner, repo] = repository.split("/");
-  const tag = `buildchain-records/${intentId.replace("sha256:", "")}`;
+  if (partition && !/^[1-9][0-9]*-[1-9][0-9]*-[1-9][0-9]*$/u.test(partition))
+    throw new Error("Invalid material archive writer partition");
+  const tag = `buildchain-records/${intentId.replace("sha256:", "")}${partition ? `/${partition}` : ""}`;
   const repos = octokit.rest.repos;
   let retainedArchive;
   async function findArchive() {
@@ -27,8 +35,7 @@ export function discussionMaterials({ octokit, repository, intentId }) {
       throw new Error("Ambiguous transaction material archive");
     return matches[0];
   }
-  async function archive() {
-    if (retainedArchive) return retainedArchive;
+  async function createArchive() {
     let release = await findArchive();
     if (!release) {
       try {
@@ -40,7 +47,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,
           })
@@ -55,9 +62,15 @@ export function discussionMaterials({ octokit, repository, intentId }) {
     }
     if (!release.draft || release.tag_name !== tag)
       throw new Error("Transaction material archive identity mismatch");
-    retainedArchive = release;
     return release;
   }
+  function archive() {
+    // Concurrent puts in one writer share the same creation, including readback.
+    return (retainedArchive ||= createArchive().catch((error) => {
+      retainedArchive = undefined;
+      throw error;
+    }));
+  }
   async function read(handle) {
     const response = await repos.getReleaseAsset({
       owner,
@@ -72,11 +85,13 @@ export function discussionMaterials({ octokit, repository, intentId }) {
       );
     return bytes;
   }
-  async function put(bytes) {
+  async function put(bytes, descriptor = {}) {
+    const extension =
+      descriptor.name?.match(/\.([a-zA-Z0-9]{1,8})$/u)?.[1] || "";
     if (bytes.length > 256 * 1024 * 1024)
       throw new Error("Transaction material exceeds the supported file bound");
     const digest = materialDigest(bytes),
-      name = digest.replace(":", "-");
+      name = digest.replace(":", "-") + (extension ? `.${extension}` : "");
     const release = await archive();
     const find = async () => {
       const assets = await octokit.paginate(repos.listReleaseAssets, {
@@ -101,7 +116,8 @@ export function discussionMaterials({ octokit, repository, intentId }) {
             name,
             data: bytes,
             headers: {
-              "content-type": "application/octet-stream",
+              "content-type":
+                descriptor.mediaType || "application/octet-stream",
             },
           })
         ).data;
@@ -113,7 +129,15 @@ export function discussionMaterials({ octokit, repository, intentId }) {
           });
       }
     }
-    const handle = { id: asset.id, digest, size: bytes.length };
+    const handle = {
+      id: asset.id,
+      digest,
+      size: bytes.length,
+      ...(asset.browser_download_url
+        ? { downloadUrl: asset.browser_download_url }
+        : {}),
+      ...(release.html_url ? { archiveUrl: release.html_url } : {}),
+    };
     await read(handle);
     return handle;
   }
@@ -140,7 +164,7 @@ export function discussionMaterials({ octokit, repository, intentId }) {
     }
   }
   return {
-    put: (bytes) => diagnose("put", () => put(bytes)),
+    put: (bytes, descriptor) => diagnose("put", () => put(bytes, descriptor)),
     read: (handle) => diagnose("read", () => read(handle)),
   };
 }

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

@@ -1,7 +1,7 @@
 const fields =
   "id number url body author { __typename login ... on Node { id } } lastEditedAt repository { nameWithOwner }";
 const commentFields =
-  "id url body author { __typename login ... on Node { id } } lastEditedAt";
+  "id url body author { __typename login ... on Node { id } } lastEditedAt replyTo { id }";
 
 export function discussionTransport(graphql) {
   async function request(query, variables) {
@@ -66,13 +66,22 @@ export function discussionTransport(graphql) {
   }
   async function comments(id, after = null) {
     const result = await request(
-      `query($id:ID!,$after:String){node(id:$id){... on Discussion{comments(first:100,after:$after){nodes{${commentFields}} pageInfo{hasNextPage endCursor}}}}}`,
+      `query($id:ID!,$after:String){node(id:$id){... on Discussion{comments(first:100,after:$after){nodes{${commentFields} replies{totalCount}} pageInfo{hasNextPage endCursor}}}}}`,
       { id, after },
     );
     if (!result.node?.comments)
       throw new Error("Release Discussion comments are unavailable");
     return result.node.comments;
   }
+  async function replies(id, after = null) {
+    const result = await request(
+      `query($id:ID!,$after:String){node(id:$id){... on DiscussionComment{replies(first:100,after:$after){nodes{${commentFields}} pageInfo{hasNextPage endCursor}}}}}`,
+      { id, after },
+    );
+    if (!result.node?.replies)
+      throw new Error("Release Discussion replies are unavailable");
+    return result.node.replies;
+  }
   async function create({ repositoryId, categoryId, title, body }) {
     const result = await request(
       `mutation($input:CreateDiscussionInput!){createDiscussion(input:$input){discussion{${fields}}}}`,
@@ -80,14 +89,16 @@ export function discussionTransport(graphql) {
     );
     return result.createDiscussion.discussion;
   }
-  async function append(id, body) {
+  async function append(id, body, replyToId = null) {
     const result = await request(
       `mutation($input:AddDiscussionCommentInput!){addDiscussionComment(input:$input){comment{${commentFields}}}}`,
-      { input: { discussionId: id, body } },
+      {
+        input: { discussionId: id, body, ...(replyToId ? { replyToId } : {}) },
+      },
     );
     return result.addDiscussionComment.comment;
   }
-  return { repository, list, get, comments, create, append };
+  return { repository, list, get, comments, replies, create, append };
 }
 
 export async function collectDiscussionPages(readPage, limit = 100) {

package/packages/core/providers/github/pipeline-checkout.js

@@ -0,0 +1,49 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { githubAuthEnv } from "../source-checkout/auth.js";
+import { createNativeChildEnvironment } from "../../dev-delivery/native/execution.js";
+
+// Read-only Git object access for credentialed source qualification. This is a
+// bare repository: no consumer checkout, hooks or build scripts are executed.
+export async function withPipelineSourceObjects(
+  { repository, sourceHead, baseCommit, token },
+  operation,
+) {
+  if (
+    !/^[\w.-]+\/[\w.-]+$/u.test(repository || "") ||
+    ![sourceHead, baseCommit].every((sha) => /^[0-9a-f]{40}$/u.test(sha || ""))
+  )
+    throw new Error(
+      "Pipeline qualification requires exact repository source coordinates",
+    );
+  const directory = fs.mkdtempSync(
+    path.join(os.tmpdir(), "buildchain-pipeline-source-"),
+  );
+  const environment = {
+    ...createNativeChildEnvironment(process.env),
+    GIT_TERMINAL_PROMPT: "0",
+    ...githubAuthEnv(token),
+  };
+  const git = (args) =>
+    execFileSync("git", ["-C", directory, ...args], {
+      env: environment,
+      stdio: ["ignore", "pipe", "pipe"],
+      maxBuffer: 32 * 1024 * 1024,
+    });
+  try {
+    git(["init", "--bare", "--quiet"]);
+    git([
+      "fetch",
+      "--quiet",
+      "--no-tags",
+      `https://github.com/${repository}.git`,
+      sourceHead,
+      baseCommit,
+    ]);
+    return await operation(directory);
+  } finally {
+    fs.rmSync(directory, { recursive: true, force: true });
+  }
+}

package/packages/core/providers/github/pipeline-entry-runs.js

@@ -0,0 +1,210 @@
+import { createHash } from "node:crypto";
+import { runtimeSelector } from "../../runtime/entry/selection.js";
+import { pipelineRunEntry, readPipelineCaller } from "./pipeline-run-entry.js";
+import { recordDigest } from "../../release/discussion/envelope.js";
+
+export async function pipelineEntryRuns(host, publishedAt) {
+  const created = encodeURIComponent(
+    `>=${new Date(publishedAt).toISOString()}`,
+  );
+  const prefix = `/repos/${host.repository}/actions/workflows/buildchain.yml/runs`;
+  const runs = [],
+    ids = new Set();
+  for (let page = 1; page <= 10; page++) {
+    const result = await host.request(
+      `${prefix}?event=pull_request&status=completed&created=${created}&per_page=100&page=${page}`,
+      { allow404: true },
+    );
+    if (!result && page === 1) return [];
+    if (
+      !Array.isArray(result?.workflow_runs) ||
+      result.workflow_runs.length > 100
+    )
+      throw new Error("Published entry run inventory is incomplete");
+    for (const run of result.workflow_runs) {
+      if (
+        !Number.isSafeInteger(run.id) ||
+        run.id < 1 ||
+        ids.has(run.id) ||
+        !Number.isSafeInteger(run.run_attempt) ||
+        run.run_attempt < 1 ||
+        !Number.isFinite(Date.parse(run.created_at))
+      )
+        throw new Error(
+          "Published entry run inventory has ambiguous coordinates",
+        );
+      ids.add(run.id);
+      runs.push(run);
+    }
+    if (result.workflow_runs.length < 100)
+      return runs.sort(
+        (a, b) =>
+          Date.parse(b.created_at) - Date.parse(a.created_at) || b.id - a.id,
+      );
+  }
+  throw new Error(
+    "Published entry run inventory exceeds its complete-read bound",
+  );
+}
+
+async function sourceLock(host, source, channel) {
+  const pathname =
+    channel === "v4-alpha"
+      ? ".buildchain/alpha-contract-lock.json"
+      : ".buildchain/contract-lock.json";
+  const file = await host.request(
+    `/repos/${host.repository}/contents/${pathname}?ref=${source.commit}`,
+    { allow404: true },
+  );
+  if (!file) return { value: undefined, evidence: null };
+  if (
+    file.type !== "file" ||
+    file.encoding !== "base64" ||
+    !Number.isSafeInteger(file.size) ||
+    file.size < 1 ||
+    file.size > 1024 * 1024 ||
+    typeof file.content !== "string" ||
+    file.content.length > 2 * 1024 * 1024
+  )
+    throw new Error("Published entry runtime lock exceeds its source boundary");
+  const bytes = Buffer.from(file.content, "base64");
+  const blob = createHash("sha1")
+    .update(`blob ${bytes.length}\0`)
+    .update(bytes)
+    .digest("hex");
+  if (bytes.length !== file.size || blob !== file.sha)
+    throw new Error("Published entry runtime lock bytes changed");
+  const value = JSON.parse(
+    new TextDecoder("utf-8", { fatal: true }).decode(bytes),
+  );
+  if (
+    value.schema === "buildchain.consumer-contract-lock/v2" &&
+    value.configDigest !== source.configDigest
+  )
+    throw new Error(
+      "Published entry runtime lock belongs to another consumer configuration",
+    );
+  return {
+    value,
+    evidence: {
+      path: pathname,
+      blob,
+      digest: `sha256:${createHash("sha256").update(bytes).digest("hex")}`,
+    },
+  };
+}
+
+export async function pipelineEntryRun(run, plan, source, host) {
+  if (
+    run.event !== "pull_request" ||
+    run.status !== "completed" ||
+    run.repository?.full_name !== host.repository ||
+    run.head_repository?.full_name !== host.repository ||
+    run.path?.split("@")[0] !== ".github/workflows/buildchain.yml" ||
+    !Number.isFinite(Date.parse(run.created_at)) ||
+    Date.parse(run.created_at) < Date.parse(source.candidate.publishedAt)
+  )
+    return null;
+  const entry = pipelineRunEntry(run);
+  if (entry.recovery || entry.definition.sha !== source.candidate.sha)
+    return null;
+  const consumer = await host.source.source(
+    run.head_sha,
+    plan.source.configPath,
+  );
+  if (recordDigest(consumer.plan) !== plan.contractRoot) return null;
+  if (
+    consumer.identity.commit !== run.head_sha ||
+    consumer.identity.configPath !== plan.source.configPath ||
+    consumer.identity.repository !== host.repository
+  )
+    throw new Error("Published entry consumer source changed during readback");
+  await readPipelineCaller(
+    run,
+    consumer.identity.configPath,
+    host.request,
+    host.repository,
+  );
+  const lock = await sourceLock(host, consumer.identity, entry.channel);
+  const selection = runtimeSelector({
+    lock: lock.value,
+    workflowSha: entry.definition.sha,
+  });
+  if (selection.ref !== source.candidate.sha) return null;
+  return {
+    source: consumer.identity,
+    entry: entry.definition,
+    selection,
+    lock: lock.evidence,
+  };
+}
+
+export async function pipelineEntryCheck(run, host) {
+  const checks = [],
+    ids = new Set();
+  const prefix = `/repos/${host.repository}/commits/${run.head_sha}/check-runs`;
+  for (let page = 1; page <= 10; page++) {
+    const result = await host.request(
+      `${prefix}?check_name=check&filter=all&per_page=100&page=${page}`,
+    );
+    if (!Array.isArray(result?.check_runs) || result.check_runs.length > 100)
+      throw new Error("Published entry check inventory is incomplete");
+    for (const check of result.check_runs) {
+      if (!Number.isSafeInteger(check.id) || check.id < 1 || ids.has(check.id))
+        throw new Error(
+          "Published entry check inventory has ambiguous identities",
+        );
+      ids.add(check.id);
+      checks.push(check);
+    }
+    if (result.check_runs.length < 100)
+      return exactCheck(checks, run, host.repository);
+  }
+  throw new Error(
+    "Published entry check inventory exceeds its complete-read bound",
+  );
+}
+
+function exactCheck(checks, run, repository) {
+  const url = `https://github.com/${repository}/actions/runs/${run.id}/attempts/${run.run_attempt}`;
+  // Actions may replace details_url with the check's own provider URL. Its
+  // exact external execution identity still binds the original native receipt.
+  const matches = checks.filter(
+    (check) =>
+      check.name === "check" &&
+      (check.details_url === url ||
+        (check.details_url ===
+          `https://github.com/${repository}/runs/${check.id}` &&
+          check.external_id?.endsWith(`:${run.id}:${run.run_attempt}`))),
+  );
+  if (!matches.length) return null;
+  const values = matches.map((check) => {
+    const parsed =
+      /^buildchain:(attempt-[0-9a-f]{64}):([1-9][0-9]*):([1-9][0-9]*)$/u.exec(
+        check.external_id || "",
+      );
+    if (
+      !parsed ||
+      Number(parsed[2]) !== run.id ||
+      Number(parsed[3]) !== run.run_attempt ||
+      check.head_sha !== run.head_sha ||
+      check.status !== "completed" ||
+      !["success", "failure"].includes(check.conclusion) ||
+      check.app?.slug !== "github-actions"
+    )
+      throw new Error(
+        "Published entry check does not bind its exact native attempt",
+      );
+    return {
+      attempt: parsed[1],
+      outcome: check.conclusion,
+      summary: check.output?.summary || "",
+    };
+  });
+  if (values.some((value) => recordDigest(value) !== recordDigest(values[0])))
+    throw new Error("Published entry checks disagree about the same execution");
+  return {
+    ...values[0],
+    ids: matches.map(({ id }) => id).sort((a, b) => a - b),
+  };
+}