@jitsusama/agentic-harness.core 0.1.0

package/dist/review/providers/github/proposals.js

@@ -0,0 +1,298 @@
+/**
+ * Reading changes from GitHub.
+ *
+ * GitHub says a merged pull request is `closed` with a
+ * `merged_at` timestamp, and calls a draft a state in one API
+ * and a flag in another. The neutral model says merged is its
+ * own state and draft is a flag, so the translation happens
+ * here, once, rather than in every caller that has to decide
+ * what `closed` meant.
+ */
+import { run } from "../../../exec/index.js";
+import { GHOST, githubChange, ownerRepoFromKey } from "./claims.js";
+import { labelsAndAssignees } from "./fields.js";
+import { landabilityFrom, QUEUE_QUERY, queueStateFrom } from "./queue.js";
+/** Where a materialized change lands, so it is easy to spot. */
+const LOCAL_REF_PREFIX = "refs/pi-review/github";
+/** The `owner/repo` a ref belongs to, or a clear failure. */
+function slugOf(repo) {
+    const owned = ownerRepoFromKey(repo.key);
+    if (!owned) {
+        throw new Error(`${repo.key} is not a GitHub repo key`);
+    }
+    return `${owned.owner}/${owned.repo}`;
+}
+function asRecord(value, what) {
+    if (typeof value !== "object" || value === null) {
+        throw new Error(`GitHub returned no ${what}`);
+    }
+    return value;
+}
+function str(value) {
+    return typeof value === "string" ? value : undefined;
+}
+function nested(value, key) {
+    const record = asRecord(value, "object");
+    const inner = record[key];
+    return typeof inner === "object" && inner !== null
+        ? inner
+        : {};
+}
+function num(value) {
+    return typeof value === "number" ? value : undefined;
+}
+/** Who acted, or the ghost GitHub attributes orphaned work to. */
+function actorFrom(login) {
+    return { id: str(login) ?? GHOST };
+}
+/**
+ * How big the change is, from whichever of GitHub's spellings
+ * answered: REST says `changed_files`, GraphQL and the CLI say
+ * `changedFiles`.
+ *
+ * Each field is carried only when it is actually there. An
+ * unreported count and a count of zero are different facts, and a
+ * reader shown "0 files changed" would believe the wrong one.
+ */
+function sizeOf(raw) {
+    const additions = num(raw.additions);
+    const deletions = num(raw.deletions);
+    const changedFiles = num(raw.changedFiles) ?? num(raw.changed_files);
+    return {
+        ...(additions !== undefined ? { additions } : {}),
+        ...(deletions !== undefined ? { deletions } : {}),
+        ...(changedFiles !== undefined ? { changedFiles } : {}),
+    };
+}
+/**
+ * GitHub's state plus its merge timestamp, as one state. A
+ * closed pull request that merged is merged; one that did not
+ * is closed.
+ */
+function stateOf(raw) {
+    if (str(raw.merged_at))
+        return "merged";
+    const state = (str(raw.state) ?? "open").toLowerCase();
+    if (state === "merged")
+        return "merged";
+    return state === "closed" ? "closed" : "open";
+}
+/** One pull request from the REST representation. */
+function proposalFromRest(repo, raw) {
+    const id = String(raw.number ?? "");
+    return {
+        ref: githubChange(repo, id),
+        title: str(raw.title) ?? "",
+        body: str(raw.body) ?? "",
+        state: stateOf(raw),
+        draft: raw.draft === true,
+        author: actorFrom(nested(raw, "user").login),
+        base: str(nested(raw, "base").ref) ?? "",
+        head: str(nested(raw, "head").ref) ?? "",
+        ...(str(nested(raw, "head").sha)
+            ? { headCommit: str(nested(raw, "head").sha) }
+            : {}),
+        ...(str(raw.created_at) ? { createdAt: str(raw.created_at) } : {}),
+        ...(str(raw.updated_at) ? { updatedAt: str(raw.updated_at) } : {}),
+        ...(str(raw.html_url) ? { url: str(raw.html_url) } : {}),
+        ...sizeOf(raw),
+        ...labelsAndAssignees(raw),
+    };
+}
+/**
+ * One pull request from `gh pr list --json`, which is neither
+ * REST nor GraphQL but a third spelling of the same thing.
+ */
+function proposalFromListing(repo, raw) {
+    const id = String(raw.number ?? "");
+    const state = (str(raw.state) ?? "OPEN").toLowerCase();
+    return {
+        ref: githubChange(repo, id),
+        title: str(raw.title) ?? "",
+        body: str(raw.body) ?? "",
+        state: state === "merged" ? "merged" : state === "closed" ? "closed" : "open",
+        draft: raw.isDraft === true,
+        author: actorFrom(nested(raw, "author").login),
+        base: str(raw.baseRefName) ?? "",
+        head: str(raw.headRefName) ?? "",
+        ...(str(raw.url) ? { url: str(raw.url) } : {}),
+        ...sizeOf(raw),
+        ...labelsAndAssignees(raw),
+    };
+}
+/** One check's state, from either of GitHub's two shapes. */
+function checkStateOf(raw) {
+    // Check runs report status plus conclusion; legacy statuses
+    // report a single state.
+    const status = (str(raw.status) ?? "").toUpperCase();
+    const conclusion = (str(raw.conclusion) ?? "").toUpperCase();
+    const legacy = (str(raw.state) ?? "").toUpperCase();
+    if (status && status !== "COMPLETED")
+        return "pending";
+    const outcome = conclusion || legacy;
+    if (!outcome)
+        return "unreported";
+    if (["SUCCESS", "NEUTRAL"].includes(outcome))
+        return "passing";
+    if (["SKIPPED"].includes(outcome))
+        return "skipped";
+    if (["PENDING", "EXPECTED", "QUEUED"].includes(outcome))
+        return "pending";
+    return "failing";
+}
+/** Roll checks up, keeping unreported apart from failing. */
+function rollUp(checks) {
+    if (checks.length === 0)
+        return "unreported";
+    if (checks.some((check) => check.state === "failing"))
+        return "failing";
+    if (checks.some((check) => check.state === "pending"))
+        return "pending";
+    if (checks.some((check) => check.state === "unreported"))
+        return "pending";
+    return "passing";
+}
+/** Build the proposals facet. */
+export function githubProposals(exec) {
+    async function json(args, what) {
+        const stdout = await run(exec, "gh", args, what);
+        return JSON.parse(stdout);
+    }
+    /**
+     * Where the change stands with a merge queue, or nothing.
+     *
+     * A second call, and a GraphQL one, because REST does not carry the
+     * queue and neither does `gh pr view --json`. Both were checked
+     * against the live API rather than assumed.
+     *
+     * Failure is swallowed on purpose, and this is the one place in the
+     * provider where that is right: the queue is an extra fact about a
+     * change, and a token that cannot run GraphQL, or a GitHub instance
+     * too old to have merge queues, must still be able to read the change
+     * itself. An absent queue reads as unknown downstream, which permits
+     * the mutation, so guessing wrong here costs a gate that does not fire
+     * rather than one that fires wrongly.
+     */
+    /**
+     * The two things only GraphQL will say: where the change stands with the
+     * queue, and whether it could land. One query for both, since they come
+     * from the same node and a second round trip would buy nothing.
+     */
+    async function standingOf(repo, id) {
+        const owned = ownerRepoFromKey(repo.key);
+        if (!owned)
+            return {};
+        const number = Number(id);
+        if (!Number.isInteger(number))
+            return {};
+        try {
+            const raw = await json([
+                "api",
+                "graphql",
+                "-f",
+                `query=${QUEUE_QUERY}`,
+                "-F",
+                `owner=${owned.owner}`,
+                "-F",
+                `name=${owned.repo}`,
+                "-F",
+                `number=${number}`,
+            ], `reading where pull request ${id} stands`);
+            const landing = landabilityFrom(raw);
+            return {
+                queue: queueStateFrom(raw),
+                ...(landing === undefined ? {} : { landing }),
+            };
+        }
+        catch {
+            // Neither is worth failing a read of the change over: both are
+            // decoration on a proposal that was fetched successfully, and a
+            // caller can tell unreported from clear.
+            return {};
+        }
+    }
+    return {
+        async fetch(ref) {
+            const raw = await json(["api", `repos/${slugOf(ref.repo)}/pulls/${ref.id}`], `reading pull request ${ref.id}`);
+            const proposal = proposalFromRest(ref.repo, asRecord(raw, "pull request"));
+            return { ...proposal, ...(await standingOf(ref.repo, ref.id)) };
+        },
+        async diff(ref) {
+            return run(exec, "gh", ["pr", "diff", ref.id, "--repo", slugOf(ref.repo)], `reading the diff of pull request ${ref.id}`);
+        },
+        async checks(ref) {
+            const raw = await json([
+                "pr",
+                "view",
+                ref.id,
+                "--repo",
+                slugOf(ref.repo),
+                "--json",
+                "statusCheckRollup",
+            ], `reading checks on pull request ${ref.id}`);
+            const rollup = asRecord(raw, "checks").statusCheckRollup;
+            const entries = Array.isArray(rollup) ? rollup : [];
+            const checks = entries.map((entry) => {
+                const record = asRecord(entry, "check");
+                const name = str(record.name) ?? str(record.context) ?? "unnamed check";
+                const url = str(record.detailsUrl) ?? str(record.targetUrl);
+                return {
+                    name,
+                    state: checkStateOf(record),
+                    ...(url ? { url } : {}),
+                };
+            });
+            return { state: rollUp(checks), checks };
+        },
+        async list(repo, filter) {
+            const args = ["pr", "list", "--repo", slugOf(repo), "--json"];
+            args.push("number,title,body,state,isDraft,author,baseRefName,headRefName,url," +
+                // Free in the same call, and a listing is exactly where
+                // knowing which change is the big one earns its keep.
+                "additions,deletions,changedFiles");
+            if (filter.state)
+                args.push("--state", filter.state);
+            if (filter.author)
+                args.push("--author", filter.author);
+            if (filter.base)
+                args.push("--base", filter.base);
+            if (filter.head)
+                args.push("--head", filter.head);
+            if (filter.limit !== undefined)
+                args.push("--limit", String(filter.limit));
+            const raw = await json(args, "listing pull requests");
+            const entries = Array.isArray(raw) ? raw : [];
+            return entries.map((entry) => proposalFromListing(repo, asRecord(entry, "pull request")));
+        },
+        async fileAt(ref, path, at) {
+            const raw = await json([
+                "api",
+                `repos/${slugOf(ref.repo)}/contents/${path}?ref=${encodeURIComponent(at)}`,
+            ], `reading ${path} at ${at}`);
+            const answer = asRecord(raw, `contents of ${path}`);
+            const encoded = answer.content;
+            if (typeof encoded !== "string" || encoded.trim() === "") {
+                // A directory answers with an array, and a file too large
+                // for this route answers with an empty content field.
+                // Returning "" for either would look like an empty file.
+                throw new Error(`${path} at ${at} came back with no content, so it is not a file this route can serve.`);
+            }
+            // The encoding arrives wrapped at a fixed column, so the
+            // payload contains newlines that are not part of it.
+            return Buffer.from(encoded.replace(/\s+/g, ""), "base64").toString("utf8");
+        },
+        async fetchAsRef(ref, repoRoot) {
+            const local = `${LOCAL_REF_PREFIX}/${ref.id}`;
+            const remote = ref.repo.remoteUrl ?? "origin";
+            await run(exec, "git", [
+                "-C",
+                repoRoot,
+                "fetch",
+                "--force",
+                remote,
+                `pull/${ref.id}/head:${local}`,
+            ], `fetching pull request ${ref.id}`);
+            return local;
+        },
+    };
+}

package/dist/review/providers/github/queue.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Where GitHub says a pull request stands with a merge queue.
+ *
+ * The queue is not on the REST representation and not among the fields
+ * `gh pr view --json` offers, so this is the one place the GitHub
+ * provider has to ask GraphQL. Both facts were checked against a live
+ * API rather than assumed: `gh pr view --json` lists `autoMergeRequest`
+ * and `mergeStateStatus` and nothing else queue-shaped, and
+ * `MergeQueueEntry` exists only on the GraphQL `PullRequest`.
+ *
+ * GitHub's own vocabulary turned out to be sharper than the neutral
+ * model's first draft. `MergeQueueEntryState` distinguishes
+ * `AWAITING_CHECKS` from `QUEUED`, and `MergeQueueEntry.solo` says
+ * whether the change is being tested by itself or batched with others.
+ * That last one is the difference between ejecting one change's checks
+ * and ejecting a batch's, which is the whole reason a caller asks.
+ */
+import type { Landability } from "../../landing.js";
+import type { QueueState } from "../../queue.js";
+/** The GraphQL selection this module reads. */
+export declare const QUEUE_QUERY = "query($owner:String!,$name:String!,$number:Int!){\n  repository(owner:$owner,name:$name){\n    pullRequest(number:$number){\n      isInMergeQueue\n      autoMergeRequest{enabledAt}\n      mergeQueueEntry{state position solo}\n      reviewDecision\n      mergeStateStatus\n      mergeable\n    }\n  }\n}";
+/**
+ * Where GitHub says the change stands with landing.
+ *
+ * Read from the query the queue already runs, so it costs nothing extra. Three fields
+ * rather than one, because GitHub splits the question the same way this model does:
+ * `reviewDecision` is the people, `mergeStateStatus` is the checks and the base, and
+ * `mergeable` is whether the trees still agree.
+ *
+ * `BLOCKED` deliberately does not become `failingRequiredCheck`. It means a required
+ * status has not passed, which covers one that has not run as well as one that failed, and
+ * naming a check as failing when it merely has not started sends somebody to read a log
+ * that does not exist. The word itself is passed through instead.
+ */
+export declare function landabilityFrom(raw: unknown): Landability | undefined;
+/**
+ * Translate GitHub's answer into the neutral queue state.
+ *
+ * Three sources, in order of how much they cost to be wrong about.
+ * A merge queue entry is authoritative and detailed. Failing that, an
+ * auto-merge request means somebody has asked for this to land and the
+ * backend is waiting, which is the `waiting` posture rather than the
+ * `queued` one: nothing is batched, so nothing else gets ejected.
+ * Failing both, the change is not queued.
+ */
+export declare function queueStateFrom(raw: unknown): QueueState;

package/dist/review/providers/github/queue.js

@@ -0,0 +1,122 @@
+/**
+ * Where GitHub says a pull request stands with a merge queue.
+ *
+ * The queue is not on the REST representation and not among the fields
+ * `gh pr view --json` offers, so this is the one place the GitHub
+ * provider has to ask GraphQL. Both facts were checked against a live
+ * API rather than assumed: `gh pr view --json` lists `autoMergeRequest`
+ * and `mergeStateStatus` and nothing else queue-shaped, and
+ * `MergeQueueEntry` exists only on the GraphQL `PullRequest`.
+ *
+ * GitHub's own vocabulary turned out to be sharper than the neutral
+ * model's first draft. `MergeQueueEntryState` distinguishes
+ * `AWAITING_CHECKS` from `QUEUED`, and `MergeQueueEntry.solo` says
+ * whether the change is being tested by itself or batched with others.
+ * That last one is the difference between ejecting one change's checks
+ * and ejecting a batch's, which is the whole reason a caller asks.
+ */
+/** The GraphQL selection this module reads. */
+export const QUEUE_QUERY = `query($owner:String!,$name:String!,$number:Int!){
+  repository(owner:$owner,name:$name){
+    pullRequest(number:$number){
+      isInMergeQueue
+      autoMergeRequest{enabledAt}
+      mergeQueueEntry{state position solo}
+      reviewDecision
+      mergeStateStatus
+      mergeable
+    }
+  }
+}`;
+function record(value) {
+    return typeof value === "object" && value !== null
+        ? value
+        : {};
+}
+/**
+ * Where GitHub says the change stands with landing.
+ *
+ * Read from the query the queue already runs, so it costs nothing extra. Three fields
+ * rather than one, because GitHub splits the question the same way this model does:
+ * `reviewDecision` is the people, `mergeStateStatus` is the checks and the base, and
+ * `mergeable` is whether the trees still agree.
+ *
+ * `BLOCKED` deliberately does not become `failingRequiredCheck`. It means a required
+ * status has not passed, which covers one that has not run as well as one that failed, and
+ * naming a check as failing when it merely has not started sends somebody to read a log
+ * that does not exist. The word itself is passed through instead.
+ */
+export function landabilityFrom(raw) {
+    const pull = record(record(record(record(raw).data).repository).pullRequest);
+    const decision = typeof pull.reviewDecision === "string" ? pull.reviewDecision : undefined;
+    const status = typeof pull.mergeStateStatus === "string"
+        ? pull.mergeStateStatus
+        : undefined;
+    const mergeable = typeof pull.mergeable === "string" ? pull.mergeable : undefined;
+    if (decision === undefined &&
+        status === undefined &&
+        mergeable === undefined) {
+        return undefined;
+    }
+    return {
+        ...(status === undefined ? {} : { reason: status.toLowerCase() }),
+        ...(decision === undefined
+            ? {}
+            : {
+                approved: decision === "APPROVED",
+                changesRequested: decision === "CHANGES_REQUESTED",
+            }),
+        ...(mergeable === undefined
+            ? {}
+            : { conflicted: mergeable === "CONFLICTING" }),
+    };
+}
+/**
+ * Whether an entry's state means the queue is still waiting on checks.
+ *
+ * `AWAITING_CHECKS` is GitHub testing the batch and not yet ready to
+ * land it. The others (`QUEUED`, `MERGEABLE`, `LOCKED`, `UNMERGEABLE`)
+ * all mean the entry is holding a place, which is the expensive posture.
+ */
+function awaitingChecks(state) {
+    return state === "AWAITING_CHECKS";
+}
+/**
+ * Translate GitHub's answer into the neutral queue state.
+ *
+ * Three sources, in order of how much they cost to be wrong about.
+ * A merge queue entry is authoritative and detailed. Failing that, an
+ * auto-merge request means somebody has asked for this to land and the
+ * backend is waiting, which is the `waiting` posture rather than the
+ * `queued` one: nothing is batched, so nothing else gets ejected.
+ * Failing both, the change is not queued.
+ */
+export function queueStateFrom(raw) {
+    // The `data` envelope is part of the answer, not something a caller
+    // should have to strip: `gh api graphql` returns it unless it is given
+    // a `--jq`, and a reader that quietly accepted either shape would read
+    // an unwrapped answer as unqueued rather than saying so.
+    const pull = record(record(record(record(raw).data).repository).pullRequest);
+    const entry = pull.mergeQueueEntry;
+    if (entry !== null && entry !== undefined) {
+        const held = record(entry);
+        const state = typeof held.state === "string" ? held.state : undefined;
+        return {
+            posture: awaitingChecks(state) ? "waiting" : "queued",
+            ...(typeof held.solo === "boolean" ? { solo: held.solo } : {}),
+            ...(typeof held.position === "number" ? { position: held.position } : {}),
+            ...(state ? { detail: `merge queue entry is ${state}` } : {}),
+        };
+    }
+    // A queue entry is the only thing that batches, so auto-merge on its
+    // own is the cheaper hazard: the checks already ran and will not run
+    // again, but nobody else's work is riding on this one.
+    if (record(pull.autoMergeRequest).enabledAt !== undefined) {
+        return {
+            posture: "waiting",
+            solo: true,
+            detail: "auto-merge is enabled and the backend is waiting on checks",
+        };
+    }
+    return { posture: "unqueued" };
+}

package/dist/review/providers/github/stacking.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Deriving a stack from GitHub, which records none.
+ *
+ * GitHub knows only each pull request's base and head branch
+ * names, so a stack has to be inferred by matching one
+ * request's base against another's head. That inference is
+ * wrong at the edges by construction: a merged parent
+ * disappears from the open listing and the chain simply ends,
+ * a renamed branch breaks the link, and two forks can use the
+ * same branch name. This is why every stack reports its
+ * provenance, and why this one always reports `derived`.
+ *
+ * The walk follows fan-out downwards, because a branch with two
+ * children is a real shape people build and reporting only one
+ * of them would be a lie of omission.
+ */
+import type { Exec } from "../../../exec/index.js";
+import type { StackingFacet } from "../../provider.js";
+/** Build the stacking facet. */
+export declare function githubStacking(exec: Exec): StackingFacet;

package/dist/review/providers/github/stacking.js

@@ -0,0 +1,107 @@
+/**
+ * Deriving a stack from GitHub, which records none.
+ *
+ * GitHub knows only each pull request's base and head branch
+ * names, so a stack has to be inferred by matching one
+ * request's base against another's head. That inference is
+ * wrong at the edges by construction: a merged parent
+ * disappears from the open listing and the chain simply ends,
+ * a renamed branch breaks the link, and two forks can use the
+ * same branch name. This is why every stack reports its
+ * provenance, and why this one always reports `derived`.
+ *
+ * The walk follows fan-out downwards, because a branch with two
+ * children is a real shape people build and reporting only one
+ * of them would be a lie of omission.
+ */
+import { githubProposals } from "./proposals.js";
+/** How far to walk in each direction before giving up. */
+const MAX_DEPTH = 8;
+/** Build the stacking facet. */
+export function githubStacking(exec) {
+    const proposals = githubProposals(exec);
+    /** The single open change whose head is this branch. */
+    async function byHead(ref, branch) {
+        const found = await proposals.list?.(ref.repo, {
+            state: "open",
+            head: branch,
+        });
+        return found?.[0];
+    }
+    /** Every open change based on this branch. */
+    async function byBase(ref, branch) {
+        return ((await proposals.list?.(ref.repo, { state: "open", base: branch })) ?? []);
+    }
+    return {
+        async stack(subject) {
+            if (!("id" in subject)) {
+                throw new Error("the GitHub provider derives a stack from a pull request, not a bare branch");
+            }
+            const cursorProposal = await proposals.fetch(subject);
+            // Upwards: follow base to the change whose head it is.
+            const seen = new Set([cursorProposal.head]);
+            const ancestors = [];
+            let climbing = cursorProposal.base;
+            for (let depth = 0; depth < MAX_DEPTH; depth++) {
+                const parent = await byHead(subject, climbing);
+                if (!parent || seen.has(parent.head))
+                    break;
+                seen.add(parent.head);
+                ancestors.unshift(parent);
+                climbing = parent.base;
+            }
+            // Downwards: every change based on a branch we hold,
+            // breadth first, so a fan-out reports both sides.
+            const descendants = [];
+            let frontier = [cursorProposal.head];
+            for (let depth = 0; depth < MAX_DEPTH && frontier.length > 0; depth++) {
+                const next = [];
+                for (const branch of frontier) {
+                    for (const child of await byBase(subject, branch)) {
+                        if (seen.has(child.head))
+                            continue;
+                        seen.add(child.head);
+                        descendants.push({ proposal: child, parent: branch });
+                        next.push(child.head);
+                    }
+                }
+                frontier = next;
+            }
+            const ordered = [];
+            ancestors.forEach((proposal, index) => {
+                const parent = index === 0 ? undefined : ancestors[index - 1].head;
+                ordered.push({
+                    ref: proposal.head,
+                    ...(parent ? { parent } : {}),
+                    ...(proposal.headCommit ? { headCommit: proposal.headCommit } : {}),
+                    proposal,
+                });
+            });
+            const cursor = ordered.length;
+            const cursorParent = ancestors.at(-1)?.head;
+            ordered.push({
+                ref: cursorProposal.head,
+                ...(cursorParent ? { parent: cursorParent } : {}),
+                ...(cursorProposal.headCommit
+                    ? { headCommit: cursorProposal.headCommit }
+                    : {}),
+                proposal: cursorProposal,
+            });
+            for (const { proposal, parent } of descendants) {
+                ordered.push({
+                    ref: proposal.head,
+                    parent,
+                    ...(proposal.headCommit ? { headCommit: proposal.headCommit } : {}),
+                    proposal,
+                });
+            }
+            const trunk = ancestors[0]?.base ?? cursorProposal.base;
+            return {
+                provenance: "derived",
+                trunk,
+                nodes: ordered,
+                cursor,
+            };
+        },
+    };
+}

package/dist/review/queue.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Where a change stands with a merge queue, and what that costs.
+ *
+ * This exists because the substrate had the refusal and not the fact. An
+ * authoring intent could carry `enqueued: true` and be refused for it,
+ * but nothing ever read the queue from a provider, so the gate was
+ * unreachable and every mutation went through.
+ */
+/** How far along a queue a change is. */
+export type QueuePosture = "unqueued" | "waiting" | "queued";
+/** What the backend says about a change's place in a queue. */
+export interface QueueState {
+    posture: QueuePosture;
+    /** Whether the backend is testing it alone rather than with others. */
+    solo?: boolean;
+    /** Place in the queue, 1-based, when the backend counts. */
+    position?: number;
+    /** What the backend said, verbatim, for a refusal to quote. */
+    detail?: string;
+}
+/** A refusal, in the shape the authoring gate wants. */
+export interface QueueRefusal {
+    reason: string;
+    instead: string;
+}
+/**
+ * Why a mutation should not happen right now, or nothing.
+ *
+ * Two hazards, deliberately answered separately, because they have
+ * different fixes and a message covering both would name neither.
+ *
+ * A queued change ejects when it changes, and takes everything
+ * speculatively batched with it. That is the expensive one, and it is
+ * only expensive when the change is batched, so `solo` is respected: a
+ * refusal that claims hundreds of jobs for a change being tested alone
+ * teaches the reader to stop believing refusals.
+ *
+ * A waiting change has a subtler problem. The checks ran once, when it
+ * was marked ready, and a later commit does not retrigger them. So a
+ * mutation does not eject anything; it strands the change with results
+ * that describe code nobody has now.
+ */
+export declare function queueRefusal(queue: QueueState | undefined, providerId: string): QueueRefusal | undefined;