@akagilnc/pi-workflow-roles 0.1.5241 → 0.1.5252

package/src/collector-github.ts

@@ -1,1032 +0,0 @@
-import { spawn } from "node:child_process";
-import { createHash } from "node:crypto";
-
-import { parseCollectorPrNumber } from "./collector-config.ts";
-
-export type GitHubPullRequest = {
-  number: number;
-  state: string;
-  headOid: string;
-  /** GitHub PR created_at — work-step start for new-PR auto-trigger rounds (#678 D4). */
-  createdAt?: string;
-  updatedAt?: string;
-  url: string;
-  raw: unknown;
-};
-
-export type GitHubUser = {
-  login: string;
-  raw: unknown;
-};
-
-export type GitHubMachineIdentity = {
-  userType: string;
-  userId: number;
-  appId?: number;
-};
-
-export type GitHubPullRequestReaction = {
-  id: number;
-  userLogin: string | null;
-  machineIdentity?: GitHubMachineIdentity | null;
-  content: string;
-  createdAt: string;
-  raw: unknown;
-};
-
-export type GitHubReview = {
-  id: number;
-  nodeId?: string;
-  /** Null when GitHub tombstones the author (`user: null`). */
-  userLogin: string | null;
-  machineIdentity?: GitHubMachineIdentity | null;
-  state: string;
-  body: string;
-  commitId: string | null;
-  submittedAt: string | null;
-  htmlUrl: string;
-  raw: unknown;
-};
-
-export type GitHubIssueComment = {
-  id: number;
-  /** Null when GitHub tombstones the author (`user: null`). */
-  userLogin: string | null;
-  machineIdentity?: GitHubMachineIdentity | null;
-  body: string;
-  createdAt: string;
-  updatedAt: string;
-  htmlUrl: string;
-  raw: unknown;
-};
-
-export type GitHubReviewComment = {
-  id: number;
-  pullRequestReviewId: number | null;
-  /** Null when GitHub tombstones the author (`user: null`). */
-  userLogin: string | null;
-  machineIdentity?: GitHubMachineIdentity | null;
-  body: string;
-  path: string;
-  line: number | null;
-  originalLine: number | null;
-  side: string | null;
-  position: number | null;
-  originalPosition: number | null;
-  commitId: string | null;
-  originalCommitId: string | null;
-  createdAt: string;
-  updatedAt: string;
-  htmlUrl: string;
-  raw: unknown;
-};
-
-export type GitHubPageDiagnostics = {
-  path: string;
-  page: number;
-  status: number;
-  itemCount: number;
-  linkHeader?: string;
-};
-
-export type GitHubCreateCommentResult =
-  | {
-      kind: "success";
-      comment: GitHubIssueComment;
-    }
-  | {
-      kind: "ambiguous_loss";
-      diagnostics: string;
-      cause?: { name: string; message: string; evidenceId: string };
-    }
-  | {
-      kind: "rejected";
-      status?: number;
-      diagnostics: string;
-    };
-
-export type CollectorGitHubTransport = {
-  getAuthenticatedUser(options?: {
-    signal?: AbortSignal;
-  }): Promise<GitHubUser>;
-  getPullRequest(input: {
-    owner: string;
-    repo: string;
-    prNumber: number;
-    signal?: AbortSignal;
-  }): Promise<GitHubPullRequest>;
-  listPullRequestReviews(input: {
-    owner: string;
-    repo: string;
-    prNumber: number;
-    signal?: AbortSignal;
-    /** Charge observation budget before aggregate append / next-page fetch. */
-    retainPage?: (items: GitHubReview[]) => void;
-  }): Promise<{ items: GitHubReview[]; pages: GitHubPageDiagnostics[] }>;
-  listPullRequestReactions?(input: {
-    owner: string;
-    repo: string;
-    prNumber: number;
-    signal?: AbortSignal;
-    retainPage?: (items: GitHubPullRequestReaction[]) => void;
-  }): Promise<{ items: GitHubPullRequestReaction[]; pages: GitHubPageDiagnostics[] }>;
-  listIssueComments(input: {
-    owner: string;
-    repo: string;
-    prNumber: number;
-    signal?: AbortSignal;
-    retainPage?: (items: GitHubIssueComment[]) => void;
-  }): Promise<{ items: GitHubIssueComment[]; pages: GitHubPageDiagnostics[] }>;
-  listReviewComments(input: {
-    owner: string;
-    repo: string;
-    prNumber: number;
-    signal?: AbortSignal;
-    retainPage?: (items: GitHubReviewComment[]) => void;
-  }): Promise<{ items: GitHubReviewComment[]; pages: GitHubPageDiagnostics[] }>;
-  createIssueComment(input: {
-    owner: string;
-    repo: string;
-    prNumber: number;
-    body: string;
-    signal?: AbortSignal;
-  }): Promise<GitHubCreateCommentResult>;
-};
-
-export type GhApiResponse = {
-  status: number;
-  headers: Record<string, string>;
-  bodyText: string;
-};
-
-export type GhApiRunner = (
-  args: string[],
-  options?: { stdin?: string; signal?: AbortSignal },
-) => Promise<GhApiResponse>;
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-function requireString(value: unknown, label: string): string {
-  if (typeof value !== "string") {
-    throw new Error(`GitHub payload missing string ${label}`);
-  }
-  return value;
-}
-
-function requireNumber(value: unknown, label: string): number {
-  if (typeof value !== "number" || !Number.isFinite(value)) {
-    throw new Error(`GitHub payload missing number ${label}`);
-  }
-  return value;
-}
-
-function optionalString(value: unknown): string | null {
-  return typeof value === "string" ? value : null;
-}
-
-function parseLinkNext(linkHeader: string | undefined): string | undefined {
-  if (linkHeader === undefined || linkHeader.length === 0) return undefined;
-  for (const part of linkHeader.split(",")) {
-    const match = part.trim().match(/^<([^>]+)>\s*;\s*rel="next"$/i);
-    if (match?.[1]) return match[1];
-  }
-  return undefined;
-}
-
-function parseJson(text: string, label: string): unknown {
-  try {
-    return JSON.parse(text);
-  } catch (error) {
-    throw new Error(`GitHub ${label} returned malformed JSON`, { cause: error });
-  }
-}
-
-/**
- * Shared PR-list payload parse for admission target lookup (#676 D1/D7).
- * Every entry must carry a positive safe-integer number — malformed items fail
- * the response (do not skip then claim uniqueness).
- */
-export function parsePullRequestNumberList(raw: unknown, label: string): number[] {
-  if (!Array.isArray(raw)) {
-    throw new Error(`GitHub ${label} payload is not a list`);
-  }
-  const numbers: number[] = [];
-  for (const item of raw) {
-    if (!isRecord(item)) {
-      throw new Error(`GitHub ${label} payload contains a non-object pull request entry`);
-    }
-    try {
-      numbers.push(parseCollectorPrNumber(item["number"]));
-    } catch (error) {
-      throw new Error(`GitHub ${label} payload contains an invalid pull request number`, {
-        cause: error,
-      });
-    }
-  }
-  return numbers;
-}
-
-/**
- * Online PR association by head owner:ref (state=all). Caller supplies the real
- * head owner from branch context — never assume base repository owner is the fork head.
- * Transport/HTTP/JSON failures throw with true cause (not target-ambiguity wash).
- */
-export async function listPullRequestNumbersByHead(
-  runner: GhApiRunner,
-  input: {
-    readonly owner: string;
-    readonly repo: string;
-    readonly headOwner: string;
-    readonly headRef: string;
-    readonly signal?: AbortSignal;
-  },
-): Promise<number[]> {
-  const head = `${input.headOwner}:${input.headRef}`;
-  const path =
-    `/repos/${input.owner}/${input.repo}/pulls?head=${encodeURIComponent(head)}&state=all&per_page=100`;
-  const response = await runner(
-    ["api", "--hostname", "github.com", "--include", "-X", "GET", path],
-    input.signal === undefined ? {} : { signal: input.signal },
-  );
-  if (response.status < 200 || response.status >= 300) {
-    throw new Error(`GitHub ${path} failed with HTTP ${response.status}`, {
-      cause: {
-        endpoint: path,
-        status: response.status,
-        headers: response.headers,
-        body: response.bodyText,
-      },
-    });
-  }
-  return parsePullRequestNumberList(parseJson(response.bodyText, path), path);
-}
-
-/**
- * Online PR association for a commit SHA (fork-safe; works when the commit is on the PR).
- * Transport/HTTP/JSON failures throw with true cause.
- */
-export async function listPullRequestNumbersByCommit(
-  runner: GhApiRunner,
-  input: {
-    readonly owner: string;
-    readonly repo: string;
-    readonly commitSha: string;
-    readonly signal?: AbortSignal;
-  },
-): Promise<number[]> {
-  const path = `/repos/${input.owner}/${input.repo}/commits/${encodeURIComponent(input.commitSha)}/pulls`;
-  const response = await runner(
-    ["api", "--hostname", "github.com", "--include", "-X", "GET", path],
-    input.signal === undefined ? {} : { signal: input.signal },
-  );
-  if (response.status < 200 || response.status >= 300) {
-    throw new Error(`GitHub ${path} failed with HTTP ${response.status}`, {
-      cause: {
-        endpoint: path,
-        status: response.status,
-        headers: response.headers,
-        body: response.bodyText,
-      },
-    });
-  }
-  return parsePullRequestNumberList(parseJson(response.bodyText, path), path);
-}
-
-/**
- * Online association for a structured ticket number (#676 D1):
- * - Number is itself a pull request → that PR.
- * - Number is an issue → PRs linked via timeline cross-reference / closed-by.
- * Transport/HTTP/JSON failures throw with true cause.
- * 404 / empty association → [].
- */
-export async function listPullRequestNumbersByTicket(
-  runner: GhApiRunner,
-  input: {
-    readonly owner: string;
-    readonly repo: string;
-    readonly ticketNumber: number;
-    readonly signal?: AbortSignal;
-  },
-): Promise<number[]> {
-  const issuePath = `/repos/${input.owner}/${input.repo}/issues/${input.ticketNumber}`;
-  const issueResponse = await runner(
-    ["api", "--hostname", "github.com", "--include", "-X", "GET", issuePath],
-    input.signal === undefined ? {} : { signal: input.signal },
-  );
-  if (issueResponse.status === 404) return [];
-  if (issueResponse.status < 200 || issueResponse.status >= 300) {
-    throw new Error(`GitHub ${issuePath} failed with HTTP ${issueResponse.status}`, {
-      cause: {
-        endpoint: issuePath,
-        status: issueResponse.status,
-        headers: issueResponse.headers,
-        body: issueResponse.bodyText,
-      },
-    });
-  }
-  const issueRaw = parseJson(issueResponse.bodyText, issuePath);
-  if (!isRecord(issueRaw)) {
-    throw new Error(`GitHub ${issuePath} payload is not an object`);
-  }
-  // Issues endpoint returns PRs too — own-key pull_request means the number is the PR.
-  if (Object.hasOwn(issueRaw, "pull_request")) {
-    return [parseCollectorPrNumber(issueRaw["number"] ?? input.ticketNumber)];
-  }
-
-  // Linked PRs: GraphQL closed-by + cross-referenced PR sources (existing gh runner seam).
-  const query = `query($owner: String!, $repo: String!, $number: Int!) {
-  repository(owner: $owner, name: $repo) {
-    issue(number: $number) {
-      closedByPullRequestsReferences(first: 50) { nodes { number } }
-      timelineItems(first: 100, itemTypes: [CROSS_REFERENCED_EVENT, CONNECTED_EVENT]) {
-        nodes {
-          __typename
-          ... on CrossReferencedEvent {
-            source { ... on PullRequest { number } }
-          }
-          ... on ConnectedEvent {
-            subject { ... on PullRequest { number } }
-          }
-        }
-      }
-    }
-  }
-}`;
-  const args = [
-    "api",
-    "graphql",
-    "--hostname",
-    "github.com",
-    "--include",
-    "-f",
-    `query=${query}`,
-    "-f",
-    `owner=${input.owner}`,
-    "-f",
-    `repo=${input.repo}`,
-    "-F",
-    `number=${input.ticketNumber}`,
-  ];
-  const gqlResponse = await runner(
-    args,
-    input.signal === undefined ? {} : { signal: input.signal },
-  );
-  if (gqlResponse.status < 200 || gqlResponse.status >= 300) {
-    throw new Error(`GitHub GraphQL issue→PR failed with HTTP ${gqlResponse.status}`, {
-      cause: {
-        endpoint: "graphql",
-        status: gqlResponse.status,
-        headers: gqlResponse.headers,
-        body: gqlResponse.bodyText,
-      },
-    });
-  }
-  let payload: unknown;
-  try {
-    payload = JSON.parse(gqlResponse.bodyText);
-  } catch (error) {
-    throw new Error("GitHub GraphQL issue→PR returned malformed JSON", { cause: error });
-  }
-  if (!isRecord(payload)) {
-    throw new Error("GitHub GraphQL issue→PR payload is not an object");
-  }
-  if (payload.errors !== undefined) {
-    throw new Error(`GitHub GraphQL issue→PR errors: ${JSON.stringify(payload.errors).slice(0, 600)}`, {
-      cause: { body: gqlResponse.bodyText, errors: payload.errors },
-    });
-  }
-  const data = payload.data;
-  if (!isRecord(data)) return [];
-  const repository = data["repository"];
-  if (!isRecord(repository)) return [];
-  const issue = repository["issue"];
-  if (!isRecord(issue)) return [];
-  const numbers: number[] = [];
-  const closedBy = issue["closedByPullRequestsReferences"];
-  if (isRecord(closedBy) && Array.isArray(closedBy["nodes"])) {
-    for (const node of closedBy["nodes"]) {
-      if (isRecord(node) && typeof node["number"] === "number") {
-        numbers.push(parseCollectorPrNumber(node["number"]));
-      }
-    }
-  }
-  const timeline = issue["timelineItems"];
-  if (isRecord(timeline) && Array.isArray(timeline["nodes"])) {
-    for (const node of timeline["nodes"]) {
-      if (!isRecord(node)) continue;
-      const source = node["source"];
-      if (isRecord(source) && typeof source["number"] === "number") {
-        numbers.push(parseCollectorPrNumber(source["number"]));
-      }
-      const subject = node["subject"];
-      if (isRecord(subject) && typeof subject["number"] === "number") {
-        numbers.push(parseCollectorPrNumber(subject["number"]));
-      }
-    }
-  }
-  return [...new Set(numbers)];
-}
-
-let commentFailureEvidence = 0;
-function commentFailureCause(error: unknown) {
-  return {
-    name: error instanceof Error ? error.name : typeof error,
-    message: error instanceof Error ? error.message : String(error),
-    evidenceId: `github-comment-failure-${++commentFailureEvidence}`,
-  };
-}
-
-/** Authenticated /user requires a login; throws when absent. */
-function requireUserLogin(raw: unknown): string {
-  if (!isRecord(raw) || typeof raw["login"] !== "string") {
-    throw new Error("GitHub payload missing user.login");
-  }
-  return raw["login"];
-}
-
-/**
- * Surface authors may be tombstoned only as literal JSON null (`user: null`).
- * Preserve that case with null login; every other shape fails closed.
- */
-function optionalUserLogin(raw: unknown): string | null {
-  if (raw === null) return null;
-  if (!isRecord(raw) || typeof raw["login"] !== "string") {
-    throw new Error("GitHub payload missing user.login");
-  }
-  return raw["login"];
-}
-
-function machineIdentity(raw: Record<string, unknown>): GitHubMachineIdentity | null {
-  const user = raw["user"];
-  if (!isRecord(user) || typeof user["type"] !== "string" || typeof user["id"] !== "number") {
-    return null;
-  }
-  const app = raw["performed_via_github_app"];
-  const appId = isRecord(app) && typeof app["id"] === "number" ? app["id"] : undefined;
-  return {
-    userType: user["type"],
-    userId: user["id"],
-    ...(appId === undefined ? {} : { appId }),
-  };
-}
-
-export function normalizePullRequest(raw: unknown): GitHubPullRequest {
-  if (!isRecord(raw)) throw new Error("GitHub pull request payload must be an object");
-  const head = raw["head"];
-  if (!isRecord(head) || typeof head["sha"] !== "string" || head["sha"].length === 0) {
-    throw new Error("GitHub pull request payload missing head.sha");
-  }
-  const number = requireNumber(raw["number"], "number");
-  // GitHub REST: merged PRs keep state="closed" and set merged/merged_at. Project the
-  // real merge fact so receipt/settlement can distinguish merged from merely closed (#676 D6).
-  const mergedFlag = raw["merged"] === true
-    || (typeof raw["merged_at"] === "string" && raw["merged_at"].length > 0);
-  const rawState = requireString(raw["state"], "state").toUpperCase();
-  // After toUpperCase the only OPEN spelling is "OPEN"; keep MERGED vs CLOSED distinction.
-  const state = mergedFlag ? "MERGED" : rawState;
-  const htmlUrl = typeof raw["html_url"] === "string"
-    ? raw["html_url"]
-    : `https://github.com/unknown/unknown/pull/${number}`;
-  return {
-    number,
-    state,
-    headOid: head["sha"],
-    ...(typeof raw["created_at"] === "string" ? { createdAt: raw["created_at"] } : {}),
-    ...(typeof raw["updated_at"] === "string" ? { updatedAt: raw["updated_at"] } : {}),
-    url: htmlUrl,
-    raw,
-  };
-}
-
-export function normalizePullRequestReaction(raw: unknown): GitHubPullRequestReaction {
-  if (!isRecord(raw)) throw new Error("GitHub reaction payload must be an object");
-  return {
-    id: requireNumber(raw["id"], "reaction.id"),
-    userLogin: optionalUserLogin(raw["user"]),
-    machineIdentity: machineIdentity(raw),
-    content: requireString(raw["content"], "reaction.content"),
-    createdAt: requireString(raw["created_at"], "reaction.created_at"),
-    raw,
-  };
-}
-
-export function normalizeReview(raw: unknown): GitHubReview {
-  if (!isRecord(raw)) throw new Error("GitHub review payload must be an object");
-  return {
-    id: requireNumber(raw["id"], "review.id"),
-    ...(typeof raw["node_id"] === "string" ? { nodeId: raw["node_id"] } : {}),
-    userLogin: optionalUserLogin(raw["user"]),
-    machineIdentity: machineIdentity(raw),
-    state: requireString(raw["state"], "review.state").toUpperCase(),
-    body: typeof raw["body"] === "string" ? raw["body"] : "",
-    commitId: optionalString(raw["commit_id"]),
-    submittedAt: optionalString(raw["submitted_at"]),
-    htmlUrl: typeof raw["html_url"] === "string" ? raw["html_url"] : "",
-    raw,
-  };
-}
-
-export function normalizeIssueComment(raw: unknown): GitHubIssueComment {
-  if (!isRecord(raw)) throw new Error("GitHub issue comment payload must be an object");
-  return {
-    id: requireNumber(raw["id"], "comment.id"),
-    userLogin: optionalUserLogin(raw["user"]),
-    machineIdentity: machineIdentity(raw),
-    body: typeof raw["body"] === "string" ? raw["body"] : "",
-    createdAt: requireString(raw["created_at"], "comment.created_at"),
-    updatedAt: requireString(raw["updated_at"], "comment.updated_at"),
-    htmlUrl: typeof raw["html_url"] === "string" ? raw["html_url"] : "",
-    raw,
-  };
-}
-
-export function normalizeReviewComment(raw: unknown): GitHubReviewComment {
-  if (!isRecord(raw)) throw new Error("GitHub review comment payload must be an object");
-  return {
-    id: requireNumber(raw["id"], "review_comment.id"),
-    pullRequestReviewId: typeof raw["pull_request_review_id"] === "number"
-      ? raw["pull_request_review_id"]
-      : null,
-    userLogin: optionalUserLogin(raw["user"]),
-    machineIdentity: machineIdentity(raw),
-    body: typeof raw["body"] === "string" ? raw["body"] : "",
-    path: requireString(raw["path"], "review_comment.path"),
-    line: typeof raw["line"] === "number" ? raw["line"] : null,
-    originalLine: typeof raw["original_line"] === "number" ? raw["original_line"] : null,
-    side: optionalString(raw["side"]),
-    position: typeof raw["position"] === "number" ? raw["position"] : null,
-    originalPosition: typeof raw["original_position"] === "number"
-      ? raw["original_position"]
-      : null,
-    commitId: optionalString(raw["commit_id"]),
-    originalCommitId: optionalString(raw["original_commit_id"]),
-    createdAt: requireString(raw["created_at"], "review_comment.created_at"),
-    updatedAt: requireString(raw["updated_at"], "review_comment.updated_at"),
-    htmlUrl: typeof raw["html_url"] === "string" ? raw["html_url"] : "",
-    raw,
-  };
-}
-
-export function createGhApiRunner(
-  options: {
-    spawnImpl?: typeof spawn;
-    env?: NodeJS.ProcessEnv;
-  } = {},
-): GhApiRunner {
-  const spawnImpl = options.spawnImpl ?? spawn;
-  return async (args, runOptions = {}) => {
-    return await new Promise<GhApiResponse>((resolve, reject) => {
-      const signal = runOptions.signal;
-      if (signal?.aborted) {
-        reject(signal.reason ?? new Error("aborted"));
-        return;
-      }
-      const child = spawnImpl("gh", args, {
-        env: options.env ?? process.env,
-        stdio: ["pipe", "pipe", "pipe"],
-      });
-      let stdout = "";
-      let stderr = "";
-      let settled = false;
-      const settle = (fn: () => void) => {
-        if (settled) return;
-        settled = true;
-        if (signal !== undefined) {
-          signal.removeEventListener("abort", onAbort);
-        }
-        fn();
-      };
-      const onAbort = () => {
-        try {
-          child.kill("SIGTERM");
-        } catch (error) {
-          settle(() => reject(error));
-          return;
-        }
-        settle(() => {
-          reject(signal?.reason ?? new Error("aborted"));
-        });
-      };
-      if (signal !== undefined) {
-        signal.addEventListener("abort", onAbort, { once: true });
-      }
-      child.stdout.setEncoding("utf8").on("data", (chunk) => {
-        stdout += chunk;
-      });
-      child.stderr.setEncoding("utf8").on("data", (chunk) => {
-        stderr += chunk;
-      });
-      child.on("error", (error) => {
-        settle(() => reject(error));
-      });
-      // Attach before write/end so early child exit cannot raise uncaught EPIPE.
-      child.stdin.on("error", (error) => {
-        settle(() => {
-          if (signal?.aborted) {
-            reject(signal.reason ?? new Error("aborted"));
-            return;
-          }
-          const err = error instanceof Error ? error : new Error(String(error));
-          reject(Object.assign(err, { ambiguousGhFailure: true }));
-        });
-      });
-      if (runOptions.stdin !== undefined) {
-        child.stdin.write(runOptions.stdin);
-      }
-      child.stdin.end();
-      child.on("close", (code, signal) => {
-        settle(() => {
-          // gh api --include prints: HTTP/ headers blank-line body
-          const match = stdout.match(/^HTTP\/[\d.]+\s+(\d+)[^\n]*\r?\n([\s\S]*?)\r?\n\r?\n([\s\S]*)$/);
-          if (match) {
-            const status = Number(match[1]);
-            const headerText = match[2] ?? "";
-            const bodyText = match[3] ?? "";
-            const headers: Record<string, string> = {};
-            for (const line of headerText.split(/\r?\n/)) {
-              const idx = line.indexOf(":");
-              if (idx === -1) continue;
-              const name = line.slice(0, idx).trim().toLowerCase();
-              const value = line.slice(idx + 1).trim();
-              headers[name] = value;
-            }
-            resolve({ status, headers, bodyText });
-            return;
-          }
-          if (code === 0) {
-            resolve({ status: 200, headers: {}, bodyText: stdout });
-            return;
-          }
-          // Ambiguous: process failed without parseable HTTP response
-          const failure = new Error(
-            `gh api failed without a parseable HTTP response (code=${String(code)}): ${stderr || stdout}`,
-            { cause: { code, signal, stderr, stdout } },
-          );
-          reject(Object.assign(failure, { ambiguousGhFailure: true, stderr, stdout, code, signal }));
-        });
-      });
-    });
-  };
-}
-
-export type GhIssueSoftFetchResult = Readonly<{ body: string }>;
-
-/** Input for the shared single-issue body projection. */
-export type GhIssueBodyFetchInput = {
-  readonly owner: string;
-  readonly repo: string;
-  readonly ticketNumber: number;
-  readonly signal?: AbortSignal;
-};
-
-/**
- * Shared projection of one GitHub issue body over the gh api runner.
- * Sole authority for transport argv, HTTP handling, JSON/object/PR/body parse.
- * Callers map disposition (soft undefined vs hard typed error) — they do not reimplement fetch.
- */
-export type GhIssueBodyProjection =
-  | { readonly status: "available"; readonly body: string }
-  | {
-      readonly status: "unavailable";
-      readonly reason: "transport" | "http-non-2xx" | "pull-request";
-      readonly cause?: unknown;
-      readonly httpStatus?: number;
-    }
-  | {
-      readonly status: "invalid";
-      readonly reason: "not-json" | "not-object" | "body-invalid";
-      readonly cause?: unknown;
-    };
-
-/**
- * Soft single-issue fetch over the shared gh api runner.
- * undefined = confirmed tracker unreachable / issue not found / gh tool unavailable:
- *   - HTTP non-2xx, or
- *   - runner-tagged ambiguousGhFailure (gh ran but no parseable HTTP — auth/network/transport), or
- *   - gh process could not start (ENOENT / spawn syscall failure).
- * After gh starts successfully: response JSON/shape/implementation errors propagate with true cause.
- */
-export type GhIssueSoftFetcher = (
-  input: GhIssueBodyFetchInput,
-) => Promise<GhIssueSoftFetchResult | undefined>;
-
-function isAmbiguousGhFailure(error: unknown): boolean {
-  return (
-    typeof error === "object" &&
-    error !== null &&
-    (error as { ambiguousGhFailure?: unknown }).ambiguousGhFailure === true
-  );
-}
-
-/** gh binary missing or otherwise unable to launch — ticket-authorized soft unavailable. */
-function isGhProcessStartFailure(error: unknown): boolean {
-  if (typeof error !== "object" || error === null) return false;
-  const code = (error as NodeJS.ErrnoException).code;
-  if (code === "ENOENT") return true;
-  const syscall = (error as NodeJS.ErrnoException).syscall;
-  return typeof syscall === "string" && (syscall === "spawn" || syscall.startsWith("spawn "));
-}
-
-/**
- * Sole shared issue-body fetch + projection over createGhApiRunner.
- * Soft and hard callers only map this result; they do not duplicate argv/parse.
- */
-export async function projectGhIssueBody(
-  runner: GhApiRunner,
-  input: GhIssueBodyFetchInput,
-): Promise<GhIssueBodyProjection> {
-  const path = `repos/${input.owner}/${input.repo}/issues/${input.ticketNumber}`;
-  let response: GhApiResponse;
-  try {
-    response = await runner(
-      ["api", "--hostname", "github.com", "--include", "-X", "GET", path],
-      input.signal === undefined ? {} : { signal: input.signal },
-    );
-  } catch (error) {
-    // Transport ambiguity / gh never started → unavailable. Other failures keep true cause as throw.
-    if (isAmbiguousGhFailure(error) || isGhProcessStartFailure(error)) {
-      return { status: "unavailable", reason: "transport", cause: error };
-    }
-    throw error;
-  }
-  if (response.status < 200 || response.status >= 300) {
-    return {
-      status: "unavailable",
-      reason: "http-non-2xx",
-      httpStatus: response.status,
-    };
-  }
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(response.bodyText);
-  } catch (error) {
-    return { status: "invalid", reason: "not-json", cause: error };
-  }
-  if (typeof parsed !== "object" || parsed === null) {
-    return { status: "invalid", reason: "not-object" };
-  }
-  // Issues endpoint also returns PRs. Own-key presence of pull_request → not an issue face.
-  if (Object.hasOwn(parsed, "pull_request")) {
-    return { status: "unavailable", reason: "pull-request" };
-  }
-  // Match former gh --jq `(.body // "")`: null/missing body projects to empty string.
-  const bodyRaw = (parsed as { body?: unknown }).body;
-  if (bodyRaw !== undefined && bodyRaw !== null && typeof bodyRaw !== "string") {
-    return { status: "invalid", reason: "body-invalid" };
-  }
-  const body = typeof bodyRaw === "string" ? bodyRaw : "";
-  return { status: "available", body };
-}
-
-/**
- * Production issue-fetch capability owned by the shared gh execution seam.
- * Reuses projectGhIssueBody. Softens only ticket-authorized unavailable results
- * (tracker unreachable / issue not found / gh cannot start / PR marker);
- * invalid payload shapes propagate with true cause.
- */
-export function createGhIssueSoftFetcher(
-  runner: GhApiRunner = createGhApiRunner(),
-): GhIssueSoftFetcher {
-  return async (input) => {
-    const projected = await projectGhIssueBody(runner, input);
-    if (projected.status === "available") {
-      return Object.freeze({ body: projected.body });
-    }
-    if (projected.status === "unavailable") {
-      return undefined;
-    }
-    // invalid — keep true cause (historical soft-fetcher contract).
-    if (projected.reason === "not-json") {
-      throw new Error("GitHub issue payload is not JSON", {
-        cause: projected.cause,
-      });
-    }
-    if (projected.reason === "not-object") {
-      throw new Error("GitHub issue payload must be a JSON object");
-    }
-    throw new Error("GitHub issue payload body must be string or null");
-  };
-}
-
-export function createGhCollectorGitHubTransport(
-  runner: GhApiRunner = createGhApiRunner(),
-): CollectorGitHubTransport {
-  const hostnameArgs = ["api", "--hostname", "github.com", "--include"] as const;
-
-  async function apiGet(
-    path: string,
-    signal?: AbortSignal,
-  ): Promise<GhApiResponse> {
-    return await runner(
-      [...hostnameArgs, "-X", "GET", path],
-      signal === undefined ? {} : { signal },
-    );
-  }
-
-  async function paginate<T>(
-    path: string,
-    mapItem: (raw: unknown) => T,
-    options: {
-      signal?: AbortSignal;
-      retainPage?: (items: T[]) => void;
-    } = {},
-  ): Promise<{ items: T[]; pages: GitHubPageDiagnostics[] }> {
-    const { signal, retainPage } = options;
-    const items: T[] = [];
-    const pages: GitHubPageDiagnostics[] = [];
-    let nextPath: string | undefined = path;
-    let page = 1;
-    const seen = new Set<string>();
-    while (nextPath !== undefined) {
-      if (signal?.aborted) {
-        throw signal.reason ?? new Error("aborted");
-      }
-      if (seen.has(nextPath)) {
-        throw new Error(`GitHub pagination repeated page: ${nextPath}`);
-      }
-      seen.add(nextPath);
-      const response = await apiGet(nextPath, signal);
-      const diagnostics: GitHubPageDiagnostics = {
-        path: nextPath,
-        page,
-        status: response.status,
-        itemCount: 0,
-        ...(response.headers["link"] === undefined
-          ? {}
-          : { linkHeader: response.headers["link"] }),
-      };
-      if (response.status === 429) {
-        throw Object.assign(
-          new Error(`GitHub API rate limited on ${nextPath} (HTTP 429)`),
-          { githubStatus: 429, page: diagnostics },
-        );
-      }
-      if (response.status < 200 || response.status >= 300) {
-        throw Object.assign(
-          new Error(`GitHub API ${nextPath} failed with HTTP ${response.status}`),
-          { githubStatus: response.status, page: diagnostics },
-        );
-      }
-      const parsed = parseJson(response.bodyText, nextPath);
-      if (!Array.isArray(parsed)) {
-        throw new Error(`GitHub API ${nextPath} did not return a JSON array`);
-      }
-      diagnostics.itemCount = parsed.length;
-      pages.push(diagnostics);
-      const pageItems = parsed.map((entry) => mapItem(entry));
-      // Observation budget hook: charge before aggregate append / next-page fetch.
-      retainPage?.(pageItems);
-      for (const item of pageItems) items.push(item);
-      const nextUrl = parseLinkNext(response.headers["link"]);
-      if (nextUrl === undefined) {
-        nextPath = undefined;
-      } else {
-        // Accept absolute or path-style next links; normalize to API path + query.
-        if (nextUrl.startsWith("/")) {
-          nextPath = nextUrl;
-        } else {
-          const url = new URL(nextUrl);
-          if (url.hostname !== "api.github.com" && url.hostname !== "github.com") {
-            throw new Error(`unexpected pagination host ${url.hostname}`);
-          }
-          nextPath = `${url.pathname}${url.search}`;
-          if (nextPath.startsWith("/api/v3/")) {
-            nextPath = nextPath.slice("/api/v3".length);
-          }
-        }
-      }
-      page += 1;
-    }
-    return { items, pages };
-  }
-
-  return {
-    async getAuthenticatedUser(options = {}) {
-      const response = await apiGet("/user", options.signal);
-      if (response.status < 200 || response.status >= 300) {
-        throw new Error(`GitHub /user failed with HTTP ${response.status}`, { cause: { endpoint: "/user", status: response.status, headers: response.headers, body: response.bodyText } });
-      }
-      const raw = parseJson(response.bodyText, "/user");
-      return { login: requireUserLogin(raw).toLowerCase(), raw };
-    },
-
-    async getPullRequest(input) {
-      const path =
-        `/repos/${input.owner}/${input.repo}/pulls/${input.prNumber}`;
-      const response = await apiGet(path, input.signal);
-      if (response.status < 200 || response.status >= 300) {
-        throw new Error(`GitHub ${path} failed with HTTP ${response.status}`, { cause: { endpoint: path, status: response.status, headers: response.headers, body: response.bodyText } });
-      }
-      return normalizePullRequest(parseJson(response.bodyText, path));
-    },
-
-    async listPullRequestReviews(input) {
-      const path =
-        `/repos/${input.owner}/${input.repo}/pulls/${input.prNumber}/reviews?per_page=100`;
-      return await paginate(path, normalizeReview, {
-        ...(input.signal === undefined ? {} : { signal: input.signal }),
-        ...(input.retainPage === undefined ? {} : { retainPage: input.retainPage }),
-      });
-    },
-
-    async listPullRequestReactions(input) {
-      const path =
-        `/repos/${input.owner}/${input.repo}/issues/${input.prNumber}/reactions?per_page=100`;
-      return await paginate(path, normalizePullRequestReaction, {
-        ...(input.signal === undefined ? {} : { signal: input.signal }),
-        ...(input.retainPage === undefined ? {} : { retainPage: input.retainPage }),
-      });
-    },
-
-    async listIssueComments(input) {
-      const path =
-        `/repos/${input.owner}/${input.repo}/issues/${input.prNumber}/comments?per_page=100`;
-      return await paginate(path, normalizeIssueComment, {
-        ...(input.signal === undefined ? {} : { signal: input.signal }),
-        ...(input.retainPage === undefined ? {} : { retainPage: input.retainPage }),
-      });
-    },
-
-    async listReviewComments(input) {
-      const path =
-        `/repos/${input.owner}/${input.repo}/pulls/${input.prNumber}/comments?per_page=100`;
-      return await paginate(path, normalizeReviewComment, {
-        ...(input.signal === undefined ? {} : { signal: input.signal }),
-        ...(input.retainPage === undefined ? {} : { retainPage: input.retainPage }),
-      });
-    },
-
-    async createIssueComment(input) {
-      const path =
-        `/repos/${input.owner}/${input.repo}/issues/${input.prNumber}/comments`;
-      try {
-        const response = await runner(
-          [...hostnameArgs, "-X", "POST", path, "--input", "-"],
-          input.signal === undefined
-            ? { stdin: JSON.stringify({ body: input.body }) }
-            : { stdin: JSON.stringify({ body: input.body }), signal: input.signal },
-        );
-        if (response.status >= 200 && response.status < 300) {
-          // Contract: README.md#Collector — a successful write with unreadable response is recoverable only as an observable ambiguous result.
-          // 2xx means the comment may already exist; parse/normalize failure is
-          // ambiguous_loss so ledger marker recovery can resolve without repost.
-          try {
-            return {
-              kind: "success",
-              comment: normalizeIssueComment(parseJson(response.bodyText, path)),
-            };
-            } catch (error) {
-            const cause = commentFailureCause(error);
-            return { kind: "ambiguous_loss", diagnostics: cause.message, cause };
-          }
-        }
-        return {
-          kind: "rejected",
-          status: response.status,
-          diagnostics: `HTTP ${response.status}: ${response.bodyText.slice(0, 500)}`,
-        };
-      } catch (error) {
-        // Signal state is authoritative cancel; rethrow exact caught value.
-        if (input.signal?.aborted) {
-          throw error;
-        }
-        // Non-aborted transport tag only (after signal).
-        if (isRecord(error) && error["ambiguousGhFailure"] === true) {
-          const cause = commentFailureCause(error);
-          return { kind: "ambiguous_loss", diagnostics: cause.message, cause };
-        }
-        // Non-signal AbortError belt only (after tag).
-        if (isRecord(error) && error["name"] === "AbortError") {
-          throw error;
-        }
-        throw error;
-      }
-    },
-  };
-}
-
-export function buildCollectorRequestMarker(input: {
-  manifestDigest: string;
-  requestId: string;
-  headOid: string;
-}): string {
-  const prefix = input.manifestDigest.slice(0, 12);
-  const requestMarkerId = createHash("sha256").update(input.requestId).digest("hex");
-  return `<!-- ak-collector:v1 manifest=${prefix} request=${requestMarkerId} head=${input.headOid} -->`;
-}
-
-export function buildCollectorRequestBody(input: {
-  configuredBody: string;
-  manifestDigest: string;
-  requestId: string;
-  headOid: string;
-}): { body: string; marker: string } {
-  const marker = buildCollectorRequestMarker(input);
-  // Preserve configured body byte-for-byte; append marker on its own line.
-  const body = input.configuredBody.endsWith("\n")
-    ? `${input.configuredBody}${marker}\n`
-    : `${input.configuredBody}\n${marker}\n`;
-  return { body, marker };
-}