@jitsusama/agentic-harness.core 0.1.0

package/dist/review/budget.d.ts

@@ -0,0 +1,133 @@
+/**
+ * What bounds one reviewer's run, and which bound does which job.
+ *
+ * Two clocks answering two different questions, which is the whole
+ * point of the file. Is this reviewer wedged, which is liveness, and
+ * has it run long enough, which is a budget. One clock cannot answer
+ * both, and using the wall clock to answer the first is what killed
+ * working reviewers in six consecutive rounds.
+ *
+ * Separate from reading a reviewer's outcome because this is the half
+ * that consults config, and because a new knob here has nothing to do
+ * with a new terminal state there.
+ */
+import type { AskLimit, AskStop, Participant } from "./index.js";
+/**
+ * How long a reviewer may run before something stops it regardless.
+ *
+ * A backstop, not a budget. It exists for a reviewer that nothing else
+ * will stop, and it is deliberately no tighter than the runner's own
+ * default, because the review path knows nothing the runner does not
+ * about how long honest work takes. The previous value was fifteen
+ * minutes, chosen against a two-and-a-half-minute observation and
+ * living in the panel module, and it killed working reviewers in six
+ * consecutive rounds.
+ *
+ * Held equal to the pi adapter's subagent runner default
+ * (`DEFAULT_RUN_PI_TIMEOUT_MS`), which is host-coupled and stays in
+ * the adapter; this module has no subagent runner of its own to defer
+ * to, so the number is inlined rather than imported.
+ */
+export declare const REVIEWER_BACKSTOP_MS: number;
+/**
+ * How long a reviewer may say nothing at all before it is wedged.
+ *
+ * This is the guard that actually earns its keep, and the reason a
+ * generous backstop is safe. It fires on silence rather than on
+ * effort, so it cannot punish a reviewer for having a lot to read.
+ *
+ * Held at the supervisor's own default rather than tightened: a
+ * reviewer thinking hard against a large diff goes quiet for minutes,
+ * and shortening this would recreate the bug in a different clock.
+ */
+export declare const REVIEWER_IDLE_MS: number;
+/**
+ * How much of the backstop is kept back for the answer.
+ *
+ * The third clock, and the only one that is not a limit. The other
+ * two decide when a reviewer has to stop; this one decides when it is
+ * asked to finish, which is a different question and a kinder one.
+ *
+ * Five minutes out of forty-five, because a wrap-up is a reviewer
+ * writing down what it already knows rather than doing any more work.
+ * Larger would buy nothing and would take real investigation time to
+ * pay for it.
+ *
+ * Held equal to the pi adapter's subagent wrap-up default
+ * (`WRAP_UP_TIMEOUT_MS`), inlined for the same reason as the backstop
+ * above.
+ */
+export declare const REVIEWER_ANSWER_MS: number;
+/** What bounds one reviewer's run. */
+export interface ReviewerBudget {
+    timeoutMs: number;
+    idleTimeoutMs: number;
+    /** Kept back out of `timeoutMs` so the answer can be asked for. */
+    wrapUpReserveMs: number;
+}
+/**
+ * The clocks a limit can be measured against.
+ *
+ * Narrower than the whole budget on purpose. Judging a retry needs
+ * the two numbers a limit can run out of and nothing else, and asking
+ * for the full budget would make every caller invent a reserve it has
+ * no opinion about just to ask the question.
+ */
+export type ReviewerClocks = Pick<ReviewerBudget, "timeoutMs" | "idleTimeoutMs"> & Partial<Pick<ReviewerBudget, "wrapUpReserveMs">>;
+/**
+ * The clock a limit ran out of, where it is a clock at all.
+ *
+ * Shared with whatever records a stop, so the two cannot disagree
+ * about which number belongs to which limit. They were written twice
+ * and nothing joined them up.
+ */
+export declare function budgetForLimit(limit: AskLimit, budget: ReviewerClocks): number | undefined;
+/**
+ * Why asking this participant again would end the same way.
+ *
+ * A reviewer stopped by a clock will be stopped by that clock again if
+ * nothing about it has moved, and the evidence is not ambiguous: every
+ * failed retry in the round that prompted this work ran for 15.03
+ * minutes and died identically. Three of them, at full price, to learn
+ * what the first one had already said.
+ *
+ * So the refusal carries the number and the key that holds it. A
+ * refusal that only says no leaves somebody hunting for the knob, and
+ * the likeliest outcome of that is running the same retry again.
+ *
+ * Silent where it cannot know: an old round recorded no budget, and
+ * refusing on a number nobody has would block every retry of every
+ * round recorded before this existed.
+ */
+export declare function retryWouldRepeat(stopped: AskStop | undefined, budget: ReviewerClocks, keptBy?: string): string | undefined;
+/**
+ * What bounds this one participant, given what bounds the round.
+ *
+ * One number for a whole fan-out has to be sized for its slowest
+ * member, so a roster mixing a small fast model with a large one at
+ * high thinking either holds slots the fast reviewers do not need or
+ * cuts the slow one off mid-thought. That is the shape of the incident
+ * this whole workstream came out of: the rounds that ran past fifteen
+ * minutes lost two, three, six and seven reviewers, and the eight
+ * minute rounds beside them lost none.
+ *
+ * Each clock on its own, because the three answer three different
+ * questions and a participant with a lot to read needs the wall moved
+ * and not the liveness guard.
+ */
+export declare function boundsFor(participant: Participant, round: ReviewerBudget): ReviewerBudget;
+/**
+ * What bounds a round, taking any override from config.
+ *
+ * The fix for a bad constant is not a better constant. Both numbers
+ * are guesses about somebody else's hardware, model and diff, so they
+ * are overridable without patching source; a value that could not be
+ * used is ignored rather than honoured, because a typo that produced a
+ * zero budget would stop every reviewer the instant it started.
+ *
+ * This one is ignored rather than refused because it is read on the
+ * way into a round that is about to run, where the alternative to a
+ * default is no council at all. A participant's own clocks are read at
+ * config time with nothing yet spent, so those are refused instead.
+ */
+export declare function reviewerBudget(section: unknown): ReviewerBudget;

package/dist/review/budget.js

@@ -0,0 +1,278 @@
+/**
+ * What bounds one reviewer's run, and which bound does which job.
+ *
+ * Two clocks answering two different questions, which is the whole
+ * point of the file. Is this reviewer wedged, which is liveness, and
+ * has it run long enough, which is a budget. One clock cannot answer
+ * both, and using the wall clock to answer the first is what killed
+ * working reviewers in six consecutive rounds.
+ *
+ * Separate from reading a reviewer's outcome because this is the half
+ * that consults config, and because a new knob here has nothing to do
+ * with a new terminal state there.
+ */
+import { CLOCK_FLOOR_MS } from "../clock/index.js";
+/**
+ * How long a reviewer may run before something stops it regardless.
+ *
+ * A backstop, not a budget. It exists for a reviewer that nothing else
+ * will stop, and it is deliberately no tighter than the runner's own
+ * default, because the review path knows nothing the runner does not
+ * about how long honest work takes. The previous value was fifteen
+ * minutes, chosen against a two-and-a-half-minute observation and
+ * living in the panel module, and it killed working reviewers in six
+ * consecutive rounds.
+ *
+ * Held equal to the pi adapter's subagent runner default
+ * (`DEFAULT_RUN_PI_TIMEOUT_MS`), which is host-coupled and stays in
+ * the adapter; this module has no subagent runner of its own to defer
+ * to, so the number is inlined rather than imported.
+ */
+export const REVIEWER_BACKSTOP_MS = 45 * 60 * 1000;
+/**
+ * How long a reviewer may say nothing at all before it is wedged.
+ *
+ * This is the guard that actually earns its keep, and the reason a
+ * generous backstop is safe. It fires on silence rather than on
+ * effort, so it cannot punish a reviewer for having a lot to read.
+ *
+ * Held at the supervisor's own default rather than tightened: a
+ * reviewer thinking hard against a large diff goes quiet for minutes,
+ * and shortening this would recreate the bug in a different clock.
+ */
+export const REVIEWER_IDLE_MS = 15 * 60 * 1000;
+/**
+ * How much of the backstop is kept back for the answer.
+ *
+ * The third clock, and the only one that is not a limit. The other
+ * two decide when a reviewer has to stop; this one decides when it is
+ * asked to finish, which is a different question and a kinder one.
+ *
+ * Five minutes out of forty-five, because a wrap-up is a reviewer
+ * writing down what it already knows rather than doing any more work.
+ * Larger would buy nothing and would take real investigation time to
+ * pay for it.
+ *
+ * Held equal to the pi adapter's subagent wrap-up default
+ * (`WRAP_UP_TIMEOUT_MS`), inlined for the same reason as the backstop
+ * above.
+ */
+export const REVIEWER_ANSWER_MS = 5 * 60 * 1000;
+/**
+ * Which budget a limit is measured against, when it is one at all.
+ *
+ * Cancelled and parent-exit end a reviewer without any clock running
+ * out, so there is no number to compare and asking again is the right
+ * thing to do.
+ */
+const MEASURED_BY = {
+    "wall-clock": { of: "timeoutMs", named: "backstopMs" },
+    idle: { of: "idleTimeoutMs", named: "idleMs" },
+};
+/**
+ * Where the soft deadline actually landed.
+ *
+ * Not in the table above, because it is the one limit that is not a
+ * clock somebody set: it is the difference between two of them. Read
+ * off `timeoutMs` alone it reported the backstop, so a reviewer
+ * stopped at forty minutes was recorded as having hit forty-five, and
+ * the refusal that quotes the number told the reader to raise a
+ * budget the reviewer never reached.
+ *
+ * Two knobs move it, so the refusal names both.
+ */
+const SOFT = { named: "answerMs or backstopMs" };
+/** The moment a soft deadline falls, given the clocks around it. */
+function softDeadlineAt(budget) {
+    const reserve = budget.wrapUpReserveMs;
+    if (reserve === undefined || reserve <= 0)
+        return undefined;
+    const at = budget.timeoutMs - reserve;
+    return at > 0 ? at : undefined;
+}
+/**
+ * The clock a limit ran out of, where it is a clock at all.
+ *
+ * Shared with whatever records a stop, so the two cannot disagree
+ * about which number belongs to which limit. They were written twice
+ * and nothing joined them up.
+ */
+export function budgetForLimit(limit, budget) {
+    if (limit === "soft-deadline")
+        return softDeadlineAt(budget);
+    const measure = MEASURED_BY[limit];
+    return measure === undefined ? undefined : budget[measure.of];
+}
+/**
+ * Limits that will land in the same place if nothing changes.
+ *
+ * A wall clock is arithmetic: a reviewer that ran to the wall runs to
+ * it again, and the incident's failed retries all took 15.03 minutes
+ * to prove it. An idle clock is not. It fires when a reviewer went
+ * quiet, which is a hang, a slow tool, a provider stalling: things
+ * that may simply not happen twice. Refusing that retry blocks the
+ * one most likely to work, so it is allowed even though the number
+ * has not moved.
+ */
+const REPEATS = new Set([
+    "wall-clock",
+    // Arithmetic for the same reason a wall clock is, and derived
+    // from it: a reviewer asked to wrap up at forty minutes will be
+    // asked again at forty minutes. Left out, a round of seven soft
+    // deadlines would offer seven retries that all end identically,
+    // which is the bill this work exists to stop paying.
+    "soft-deadline",
+]);
+/**
+ * Why asking this participant again would end the same way.
+ *
+ * A reviewer stopped by a clock will be stopped by that clock again if
+ * nothing about it has moved, and the evidence is not ambiguous: every
+ * failed retry in the round that prompted this work ran for 15.03
+ * minutes and died identically. Three of them, at full price, to learn
+ * what the first one had already said.
+ *
+ * So the refusal carries the number and the key that holds it. A
+ * refusal that only says no leaves somebody hunting for the knob, and
+ * the likeliest outcome of that is running the same retry again.
+ *
+ * Silent where it cannot know: an old round recorded no budget, and
+ * refusing on a number nobody has would block every retry of every
+ * round recorded before this existed.
+ */
+export function retryWouldRepeat(stopped, budget, 
+// Whose clock this is, when it is not the round's. The refusal
+// exists to name the knob that would let the retry through, and a
+// participant keeping its own is precisely the reviewer whose limit
+// the round's knob does not move: told to raise `review.ask.
+// backstopMs`, somebody would raise it, retry, and be refused by the
+// same number for the same reason.
+keptBy) {
+    if (stopped?.budgetMs === undefined)
+        return undefined;
+    if (!REPEATS.has(stopped.limit))
+        return undefined;
+    const measure = stopped.limit === "soft-deadline" ? SOFT : MEASURED_BY[stopped.limit];
+    if (measure === undefined)
+        return undefined;
+    const now = budgetForLimit(stopped.limit, budget);
+    // A soft deadline that has since been switched off has no moment
+    // to compare against, and that is a change: the reviewer will now
+    // run to the wall instead, so the retry is a different question.
+    if (now === undefined || now > stopped.budgetMs)
+        return undefined;
+    return (`This reviewer was not failing, it was stopped: it hit the ${stopped.limit} ` +
+        `limit of ${stopped.budgetMs}ms and the limit is still ${now}ms, so asking ` +
+        `again buys the same wall at the same price. Raise ${knob(measure.named, keptBy)} ` +
+        "past what it needed and ask again, or take what it did send: a stopped " +
+        "reviewer's answer is kept, and the findings it finished are already read.");
+}
+/**
+ * Where the number that stopped this reviewer is written.
+ *
+ * A participant keeping its own is the reviewer whose limit the
+ * round's knob does not move, so naming the round's would send
+ * somebody to raise a number, retry, and meet the same wall.
+ */
+function knob(named, keptBy) {
+    if (keptBy === undefined)
+        return `review.ask.${named}`;
+    return `${named} on "${keptBy}" in review.ask.reviewers, which is where this one's clocks are kept, or pass it in who for one round`;
+}
+/**
+ * What bounds this one participant, given what bounds the round.
+ *
+ * One number for a whole fan-out has to be sized for its slowest
+ * member, so a roster mixing a small fast model with a large one at
+ * high thinking either holds slots the fast reviewers do not need or
+ * cuts the slow one off mid-thought. That is the shape of the incident
+ * this whole workstream came out of: the rounds that ran past fifteen
+ * minutes lost two, three, six and seven reviewers, and the eight
+ * minute rounds beside them lost none.
+ *
+ * Each clock on its own, because the three answer three different
+ * questions and a participant with a lot to read needs the wall moved
+ * and not the liveness guard.
+ */
+export function boundsFor(participant, round) {
+    const timeoutMs = participant.backstopMs ?? round.timeoutMs;
+    return {
+        timeoutMs,
+        // Never past the wall it now sits inside. Each clock is taken on
+        // its own, and that is the right reading of what somebody wrote,
+        // but the three are not independent: an idle guard that outlives
+        // its wall is a pair the runner refuses outright, so a reviewer
+        // given a shorter wall than the round's would not have started at
+        // all. Held down rather than refused, because the wall firing
+        // first is exactly what asking for a shorter wall means.
+        idleTimeoutMs: Math.min(participant.idleMs ?? round.idleTimeoutMs, timeoutMs),
+        // Zero is honoured here for the same reason it is honoured in the
+        // round's own config: it is the documented way to say do not
+        // interrupt me early. Read as a typo, a participant asking not to
+        // be interrupted would fall back to the round's reserve and be
+        // interrupted anyway, which is the one outcome nobody wrote it
+        // for.
+        wrapUpReserveMs: reserveInside(participant.answerMs ?? round.wrapUpReserveMs, timeoutMs),
+    };
+}
+/**
+ * A wrap-up reserve that leaves a reviewer something to wrap up.
+ *
+ * The reserve is carved out of the wall rather than added to it, so a
+ * reserve as large as the wall asks a reviewer for its findings before
+ * it has read anything. That could not happen while both numbers came
+ * from one config section; it can now, because a participant may
+ * shorten its wall and inherit the round's reserve, and five minutes
+ * out of forty-five is four minutes out of six.
+ *
+ * Held to half rather than refused, since the participant asked about
+ * the wall and has no opinion about the reserve it inherited. Below
+ * the floor it goes to zero, which is a reviewer that runs to the wall
+ * and is asked afterwards: the behaviour from before the reserve
+ * existed, and the honest answer for a wall too short to divide.
+ */
+function reserveInside(reserve, timeoutMs) {
+    if (reserve === 0)
+        return 0;
+    const held = Math.min(reserve, Math.floor(timeoutMs / 2));
+    return held < CLOCK_FLOOR_MS ? 0 : held;
+}
+/**
+ * What bounds a round, taking any override from config.
+ *
+ * The fix for a bad constant is not a better constant. Both numbers
+ * are guesses about somebody else's hardware, model and diff, so they
+ * are overridable without patching source; a value that could not be
+ * used is ignored rather than honoured, because a typo that produced a
+ * zero budget would stop every reviewer the instant it started.
+ *
+ * This one is ignored rather than refused because it is read on the
+ * way into a round that is about to run, where the alternative to a
+ * default is no council at all. A participant's own clocks are read at
+ * config time with nothing yet spent, so those are refused instead.
+ */
+export function reviewerBudget(section) {
+    const held = isRecord(section) ? section : {};
+    return {
+        timeoutMs: positiveNumber(held.backstopMs) ?? REVIEWER_BACKSTOP_MS,
+        idleTimeoutMs: positiveNumber(held.idleMs) ?? REVIEWER_IDLE_MS,
+        // Zero is honoured rather than rejected, because it is the
+        // documented way to turn the soft deadline off. Every other
+        // clock here treats zero as a typo, and for them it is: a zero
+        // backstop stops every reviewer the instant it starts. A zero
+        // reserve just means do not ask early.
+        wrapUpReserveMs: held.answerMs === 0
+            ? 0
+            : (positiveNumber(held.answerMs) ?? REVIEWER_ANSWER_MS),
+    };
+}
+/** A duration that could actually be used, or nothing. */
+function positiveNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0
+        ? value
+        : undefined;
+}
+/** Whether config handed us something with fields to read. */
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/review/capabilities.d.ts

@@ -0,0 +1,217 @@
+/**
+ * What a provider can actually do.
+ *
+ * Facets say which broad abilities a provider has; these say
+ * how far each one goes. The distinction earns its keep at
+ * the point of publishing: two providers both post reviews,
+ * but one caps a batch at a hundred comments, one cannot
+ * thread a reply onto a top-level message, and one has no
+ * way to unresolve. A consumer that cannot ask about those
+ * differences has to discover them from a rejected request,
+ * which is the worst moment to find out.
+ *
+ * Declaring capabilities is how degradation stays loud. The
+ * publish plan reads them, decides what will land and what
+ * will not, and says so before anything is sent.
+ *
+ * Which means a capability nothing reads is not a capability,
+ * it is a promise. Three were removed once an audit went
+ * looking for readers and found none:
+ *
+ * - `suggestions`, a suggested edit a reader can apply. No
+ *   finding or draft item in this substrate can carry one, so
+ *   the field described a feature nothing could express.
+ * - `pendingReviews`, holding a review as a draft on the
+ *   backend. The draft here is local and outlives the call,
+ *   which is what lets it work identically on a backend with
+ *   no such notion. The capability was obsolete by design.
+ * - `deleteBranchOnMerge`. The one thing the system now
+ *   deliberately refuses, because GitHub permanently closes
+ *   the dependent PRs and they cannot be reopened.
+ *
+ * A field is added here when a reader is added with it. That
+ * is the whole discipline, and these three are why.
+ *
+ * `autoMerge` went the same way and is the interesting one,
+ * because unlike those three it named something real. GitHub
+ * does merge once checks pass, and the capability report
+ * listed `auto-merge` among the verbs a caller was told they
+ * could use. There was no verb: no method on the authoring
+ * facet, no flag on a merge request, no action on the tool.
+ * Advertising a door that is painted on is worse than having
+ * no door, so it comes back the day it opens, which now means
+ * a `whenReady` flag on {@link MergeRequest} answered with an
+ * `enqueued` outcome, since that is exactly what it is.
+ */
+import type { Reaction, Verdict } from "./conversation.js";
+import type { StackProvenance } from "./stack.js";
+/** How a provider treats an anchor that no longer fits. */
+export type StalenessModel = 
+/** Anchors stay valid; the provider pins a witness commit. */
+"pinned"
+/** The provider flags a stranded anchor. */
+ | "flagged"
+/** The provider says nothing either way. */
+ | "none";
+/**
+ * Where a remark about a whole file is allowed to be posted.
+ *
+ * `standalone` means it has to be posted on its own, outside a batch
+ * review, which is what both backends surveyed require. `batch` means it can
+ * ride along with a verdict and the line-anchored remarks, which is what a
+ * boolean used to claim for backends that do not allow it.
+ */
+export type FileLevelComments = "never" | "standalone" | "batch";
+/** What a provider's conversation facet can do. */
+export interface ConversationCapabilities {
+    /** Post a verdict and anchored comments in one submission. */
+    anchoredBatchReview: boolean;
+    /** Cap on comments per batch, when there is one. */
+    maxBatchComments?: number;
+    /**
+     * Where a remark about a whole file can be posted, if anywhere.
+     *
+     * A boolean here could not be honest, and both backends proved it. Each
+     * declared `anchoredBatchReview: true` and `fileLevelComments: true` and
+     * each statement was true on its own, while their conjunction was false:
+     * neither will take a file-level comment inside a batch review. GitHub
+     * refuses the batch with `0.position (Expected value to not be null)` and
+     * gitstream with `comments[0].line missing_field`, and in both cases the
+     * whole review is rejected rather than the one remark. Posted on its own,
+     * with a subject type of file, both accept it.
+     *
+     * So the question is not whether a file-level remark is possible but
+     * where it can go, and a capability that cannot express a conjunction
+     * will lie about one.
+     */
+    fileLevelComments: FileLevelComments;
+    /** Anchor a remark to a run of lines. */
+    multiLineRanges: boolean;
+    /** Reopen a resolved thread. */
+    unresolve: boolean;
+    /** Reactions the provider accepts. Empty means none. */
+    reactions: readonly Reaction[];
+    /** Reply onto a top-level message, not just a thread. */
+    topLevelThreading: boolean;
+    /** How the provider treats an anchor that no longer fits. */
+    staleness: StalenessModel;
+    /**
+     * Verdicts that require a summary body. One backend
+     * rejects a request for changes with an empty body.
+     */
+    bodyRequiredFor?: readonly Verdict[];
+    /** Verdicts allowed on a change the actor authored. */
+    selfVerdicts?: readonly Verdict[];
+    /** Verdicts still allowed once a change has merged. */
+    verdictsAfterMerge?: readonly Verdict[];
+}
+/** What a provider's stacking facet can do. */
+export interface StackingCapabilities {
+    /** Whether the shape is recorded or inferred. */
+    provenance: StackProvenance;
+    /** Report a stack that branches, not just a chain. */
+    fanOut: boolean;
+}
+/** What a provider's proposals facet can do. */
+export interface ProposalCapabilities {
+    /** Fetch the change's commits into a local repo. */
+    fetchAsRef: boolean;
+    /** Report CI state for a change. */
+    checks: boolean;
+    /** List changes matching a filter. */
+    list: boolean;
+}
+/**
+ * When a backend will accept reviewers on a change.
+ *
+ * Three states rather than a boolean, because one backend takes them
+ * only as the change is created. A caller told "not supported" would
+ * never learn about the one moment it is.
+ */
+export type ReviewersAt = "creation" | "any-time" | "never";
+/**
+ * What retargeting a change's base means here.
+ *
+ * Not a boolean either. On one backend a base change goes through
+ * resubmitting the whole stack, so retargeting one change is not a
+ * smaller version of the same operation and a caller that treats it as
+ * one will move changes it did not mean to touch.
+ */
+export type RetargetScope = "change" | "stack" | "never";
+/**
+ * How a backend names a person.
+ *
+ * The same string is a valid assignee on one backend and meaningless on
+ * another: GitHub wants a login, gitstream wants a Shopify email address.
+ * Declared rather than inferred, because the failure otherwise arrives
+ * from the create route after the change exists.
+ *
+ * `unknown` is for a backend that has not been measured. It is checked
+ * against nothing, since silence is not a licence to guess: picking a
+ * rule for a backend nobody asked would refuse values it accepts.
+ */
+export type PersonForm = "login" | "email" | "unknown";
+/**
+ * What a provider's authoring facet can do.
+ *
+ * Every field here is a difference the CLI survey actually found. The
+ * ones that are booleans elsewhere and enums here are the ones where a
+ * boolean would have been a lie.
+ */
+export interface AuthoringCapabilities {
+    propose: boolean;
+    /** Propose a whole stack in dependency order, in one go. */
+    proposeStack: boolean;
+    reviewersAt: ReviewersAt;
+    retarget: RetargetScope;
+    /** Flip an existing change between draft and ready. */
+    setDraft: boolean;
+    close: boolean;
+    reopen: boolean;
+    merge: boolean;
+    labels: boolean;
+    assignees: boolean;
+    /**
+     * The form this backend names people in, for assignees and reviewers.
+     *
+     * Required rather than optional so a new backend has to answer it. An
+     * absent field would read as "no opinion" for a backend that simply
+     * had not been asked, which is the ambiguity that lets a login reach a
+     * server that only knows email addresses.
+     */
+    identifies: PersonForm;
+    /**
+     * Ask CI to run again.
+     *
+     * Here rather than beside `checks` on the proposals facet, which
+     * is where it reads more naturally, because this is a write and
+     * that facet is how a change is read. Every write goes through
+     * one gate and one `offerable` check, and a second write path
+     * hanging off the read facet would have to duplicate both or
+     * skip them.
+     *
+     * Reading CI and retriggering it are still different
+     * permissions, so a provider can report checks and decline to
+     * rerun them. What counts as a rerun is the backend's business:
+     * an API call against the change's own runs on one, and on
+     * another a build tool that is simply how that monorepo
+     * triggers CI.
+     */
+    rerunChecks: boolean;
+    /**
+     * Whether mutating a change ejects it from a merge queue.
+     *
+     * The expensive one. On a queue-backed backend a push, a rebase or a
+     * base change ejects the change and everything speculatively batched
+     * with it, and re-running CI for the rest is measured in hundreds of
+     * jobs. A caller has to be able to ask before it acts.
+     */
+    refusesWhileEnqueued: boolean;
+}
+/** Everything a provider declares about itself, per repo. */
+export interface Capabilities {
+    proposals?: ProposalCapabilities;
+    stacking?: StackingCapabilities;
+    conversation?: ConversationCapabilities;
+    authoring?: AuthoringCapabilities;
+}

package/dist/review/capabilities.js

@@ -0,0 +1,46 @@
+/**
+ * What a provider can actually do.
+ *
+ * Facets say which broad abilities a provider has; these say
+ * how far each one goes. The distinction earns its keep at
+ * the point of publishing: two providers both post reviews,
+ * but one caps a batch at a hundred comments, one cannot
+ * thread a reply onto a top-level message, and one has no
+ * way to unresolve. A consumer that cannot ask about those
+ * differences has to discover them from a rejected request,
+ * which is the worst moment to find out.
+ *
+ * Declaring capabilities is how degradation stays loud. The
+ * publish plan reads them, decides what will land and what
+ * will not, and says so before anything is sent.
+ *
+ * Which means a capability nothing reads is not a capability,
+ * it is a promise. Three were removed once an audit went
+ * looking for readers and found none:
+ *
+ * - `suggestions`, a suggested edit a reader can apply. No
+ *   finding or draft item in this substrate can carry one, so
+ *   the field described a feature nothing could express.
+ * - `pendingReviews`, holding a review as a draft on the
+ *   backend. The draft here is local and outlives the call,
+ *   which is what lets it work identically on a backend with
+ *   no such notion. The capability was obsolete by design.
+ * - `deleteBranchOnMerge`. The one thing the system now
+ *   deliberately refuses, because GitHub permanently closes
+ *   the dependent PRs and they cannot be reopened.
+ *
+ * A field is added here when a reader is added with it. That
+ * is the whole discipline, and these three are why.
+ *
+ * `autoMerge` went the same way and is the interesting one,
+ * because unlike those three it named something real. GitHub
+ * does merge once checks pass, and the capability report
+ * listed `auto-merge` among the verbs a caller was told they
+ * could use. There was no verb: no method on the authoring
+ * facet, no flag on a merge request, no action on the tool.
+ * Advertising a door that is painted on is worse than having
+ * no door, so it comes back the day it opens, which now means
+ * a `whenReady` flag on {@link MergeRequest} answered with an
+ * `enqueued` outcome, since that is exactly what it is.
+ */
+export {};