@jitsusama/agentic-harness.core 0.1.0

package/dist/review/queue.js

@@ -0,0 +1,56 @@
+/**
+ * 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.
+ */
+/** `1st`, `2nd`, `3rd`, `4th`. */
+function ordinal(n) {
+    const teen = n % 100;
+    if (teen >= 11 && teen <= 13)
+        return `${n}th`;
+    const suffix = { 1: "st", 2: "nd", 3: "rd" }[n % 10] ?? "th";
+    return `${n}${suffix}`;
+}
+/**
+ * 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 function queueRefusal(queue, providerId) {
+    // Absent is unknown rather than queued. A provider with no queue must
+    // not have every mutation refused on suspicion.
+    if (queue === undefined || queue.posture === "unqueued")
+        return undefined;
+    const said = queue.detail ? ` The backend says: ${queue.detail}.` : "";
+    if (queue.posture === "waiting") {
+        return {
+            reason: `This change is waiting on checks to merge on ${providerId}, and those checks ran once when it was marked ready. Changing it now does not run them again, so the results would describe code that no longer exists.${said}`,
+            instead: "Cancel the merge, make the change, then re-run the checks and queue it again.",
+        };
+    }
+    const place = queue.position === undefined
+        ? ""
+        : ` It is ${ordinal(queue.position)} in line.`;
+    const batch = queue.solo === true
+        ? ""
+        : " Everything speculatively batched with it is ejected too, and re-running the checks for the rest is measured in hundreds of jobs.";
+    return {
+        reason: `This change is queued to merge on ${providerId}, and changing it now ejects it from the queue.${batch}${place}${said}`,
+        instead: "Cancel the merge, make the change, and queue it again, or wait for it to land.",
+    };
+}

package/dist/review/reactable.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Addressing one comment out of a conversation.
+ *
+ * A thread has an address a person can read and repeat: the listing numbers
+ * threads `[T1]`, `[T2]`, and every tool that acts on one takes that number.
+ * The rule that goes with it is stated in the tool's own guidelines: refer to
+ * a thread by the index the listing shows, never invent one.
+ *
+ * A comment had no such address. Reacting to one needed a provider's internal
+ * id, `rc:2098169118733` on GitHub, which no listing printed anywhere, so the
+ * only way to name a comment was to guess at a number the surface had never
+ * shown. The rule against inventing ids was stated and, for reactions, not
+ * backed by anything.
+ *
+ * So comments are numbered too, and the numbering lives here rather than in a
+ * renderer because it has to survive being computed twice: once to render a
+ * listing and again to resolve what somebody read off it. Those are separate
+ * reads of the conversation, and a number meaning one comment in the listing
+ * and another at resolution would be worse than no number at all.
+ *
+ * What keeps them agreeing is that the address says which kind of comment it
+ * is. A remark inside a thread is `[C1]` upward; a top-level message is `[M1]`
+ * upward. Because the two families are numbered apart, a caller holding only
+ * the threads computes exactly the labels a caller holding the whole
+ * conversation computes for those same threads, and the listing that shows
+ * only messages does not have to fetch every thread to number them. Sharing
+ * one space would have made every listing read the whole conversation to
+ * print an address for a part of it.
+ */
+import type { Message, Thread } from "./conversation.js";
+/** Which family a comment's address belongs to. */
+export type ReactableKind = "comment" | "message";
+/** One comment, with the address a listing prints for it. */
+export interface Reactable {
+    /** Whether it sits in a thread or stands on its own. */
+    kind: ReactableKind;
+    /** The 1-based number within its own family. */
+    index: number;
+    /** The address itself, as `[C3]`, so a renderer does not rebuild it. */
+    label: string;
+    /** The comment, whole, for handing to a provider. */
+    message: Message;
+    /** The thread it sits in, when it sits in one. */
+    thread?: Thread;
+}
+/** The address a listing prints for the nth comment of a kind. */
+export declare function reactableLabel(kind: ReactableKind, index: number): string;
+/**
+ * Number every comment in a conversation, or in the part of one to hand.
+ *
+ * Both arguments are optional because the two listings that print these
+ * addresses each hold half the conversation, and neither should have to fetch
+ * the other half to number what it already has.
+ *
+ * Order within a family is by the provider's own order, since that is what the
+ * listing shows and a number that disagreed with the line it sits on would be
+ * unusable. Threads are walked in the order given for the same reason.
+ */
+export declare function reactables(conversation: {
+    threads?: Thread[];
+    messages?: Message[];
+}): Reactable[];
+/**
+ * What a listing needs to print an address beside each comment.
+ *
+ * By comment id, because a renderer walks the conversation in its own shape
+ * and should not have to search a list to find the label for the line it is
+ * on.
+ */
+export declare function reactableAddresses(among: Reactable[]): Map<string, string>;
+/** What went wrong when a comment could not be found. */
+export interface ReactableRefusal {
+    reason: string;
+}
+/**
+ * Resolve what somebody typed into the comment they meant.
+ *
+ * Takes the `[C3]` or `[M1]` a listing printed, or a provider's own id for the
+ * times one is to hand from elsewhere. The address is the discoverable form
+ * and the reason this exists; the raw id stays accepted because a caller who
+ * already holds one should not have to go and find its number.
+ *
+ * A bare number is refused rather than guessed at. It is ambiguous between the
+ * two families, and picking one would react to the wrong comment about half
+ * the time while looking like it worked.
+ *
+ * Every refusal says where the right answer comes from, since being told a
+ * number is wrong without being told where numbers come from leaves a caller
+ * guessing exactly as it was before.
+ */
+export declare function findReactable(asked: string, among: Reactable[]): Reactable | ReactableRefusal;
+/** Whether resolving a comment failed. */
+export declare function isReactableRefusal(outcome: Reactable | ReactableRefusal): outcome is ReactableRefusal;

package/dist/review/reactable.js

@@ -0,0 +1,140 @@
+/**
+ * Addressing one comment out of a conversation.
+ *
+ * A thread has an address a person can read and repeat: the listing numbers
+ * threads `[T1]`, `[T2]`, and every tool that acts on one takes that number.
+ * The rule that goes with it is stated in the tool's own guidelines: refer to
+ * a thread by the index the listing shows, never invent one.
+ *
+ * A comment had no such address. Reacting to one needed a provider's internal
+ * id, `rc:2098169118733` on GitHub, which no listing printed anywhere, so the
+ * only way to name a comment was to guess at a number the surface had never
+ * shown. The rule against inventing ids was stated and, for reactions, not
+ * backed by anything.
+ *
+ * So comments are numbered too, and the numbering lives here rather than in a
+ * renderer because it has to survive being computed twice: once to render a
+ * listing and again to resolve what somebody read off it. Those are separate
+ * reads of the conversation, and a number meaning one comment in the listing
+ * and another at resolution would be worse than no number at all.
+ *
+ * What keeps them agreeing is that the address says which kind of comment it
+ * is. A remark inside a thread is `[C1]` upward; a top-level message is `[M1]`
+ * upward. Because the two families are numbered apart, a caller holding only
+ * the threads computes exactly the labels a caller holding the whole
+ * conversation computes for those same threads, and the listing that shows
+ * only messages does not have to fetch every thread to number them. Sharing
+ * one space would have made every listing read the whole conversation to
+ * print an address for a part of it.
+ */
+/** The letter each family is addressed by. */
+const LETTER = {
+    comment: "C",
+    message: "M",
+};
+/** The address a listing prints for the nth comment of a kind. */
+export function reactableLabel(kind, index) {
+    return `[${LETTER[kind]}${index}]`;
+}
+/**
+ * Number every comment in a conversation, or in the part of one to hand.
+ *
+ * Both arguments are optional because the two listings that print these
+ * addresses each hold half the conversation, and neither should have to fetch
+ * the other half to number what it already has.
+ *
+ * Order within a family is by the provider's own order, since that is what the
+ * listing shows and a number that disagreed with the line it sits on would be
+ * unusable. Threads are walked in the order given for the same reason.
+ */
+export function reactables(conversation) {
+    const found = [];
+    let comments = 0;
+    for (const thread of conversation.threads ?? []) {
+        for (const message of thread.comments) {
+            comments += 1;
+            found.push({
+                kind: "comment",
+                index: comments,
+                label: reactableLabel("comment", comments),
+                message,
+                thread,
+            });
+        }
+    }
+    let messages = 0;
+    for (const message of conversation.messages ?? []) {
+        messages += 1;
+        found.push({
+            kind: "message",
+            index: messages,
+            label: reactableLabel("message", messages),
+            message,
+        });
+    }
+    return found;
+}
+/**
+ * What a listing needs to print an address beside each comment.
+ *
+ * By comment id, because a renderer walks the conversation in its own shape
+ * and should not have to search a list to find the label for the line it is
+ * on.
+ */
+export function reactableAddresses(among) {
+    return new Map(among.map((one) => [one.message.id, one.label]));
+}
+/**
+ * Resolve what somebody typed into the comment they meant.
+ *
+ * Takes the `[C3]` or `[M1]` a listing printed, or a provider's own id for the
+ * times one is to hand from elsewhere. The address is the discoverable form
+ * and the reason this exists; the raw id stays accepted because a caller who
+ * already holds one should not have to go and find its number.
+ *
+ * A bare number is refused rather than guessed at. It is ambiguous between the
+ * two families, and picking one would react to the wrong comment about half
+ * the time while looking like it worked.
+ *
+ * Every refusal says where the right answer comes from, since being told a
+ * number is wrong without being told where numbers come from leaves a caller
+ * guessing exactly as it was before.
+ */
+export function findReactable(asked, among) {
+    const wanted = asked.trim();
+    if (wanted === "") {
+        return { reason: "Naming a comment needs something to go on." };
+    }
+    const addressed = /^\[?([CcMm])(\d+)\]?$/.exec(wanted);
+    if (addressed) {
+        const kind = addressed[1].toLowerCase() === "c" ? "comment" : "message";
+        const at = Number(addressed[2]);
+        const family = among.filter((one) => one.kind === kind);
+        const found = family.find((one) => one.index === at);
+        if (found)
+            return found;
+        const where = kind === "comment"
+            ? "Read the threads; the listing addresses every remark in them."
+            : "Read the messages; the listing addresses each one.";
+        return {
+            reason: family.length === 0
+                ? `There are no ${kind === "comment" ? "thread remarks" : "top-level messages"} on this change to react to.`
+                : `There is no ${reactableLabel(kind, at)} on this change; that family runs ${reactableLabel(kind, 1)} to ${reactableLabel(kind, family.length)}. ${where}`,
+        };
+    }
+    if (/^\d+$/.test(wanted)) {
+        return {
+            reason: `A bare ${wanted} does not say which comment: ${reactableLabel("comment", Number(wanted))} is a remark in a thread and ${reactableLabel("message", Number(wanted))} is a top-level message. Use the address the listing prints.`,
+        };
+    }
+    const byId = among.find((one) => one.message.id === wanted);
+    if (byId)
+        return byId;
+    return {
+        reason: `Nothing on this change has the id ${wanted}. Read the threads or the messages and use the address the listing prints, which is what this is for.`,
+    };
+}
+/** Whether resolving a comment failed. */
+export function isReactableRefusal(outcome) {
+    return "reason" in outcome;
+}

package/dist/review/register.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Provider registration. Mirrors the tree library: explicit
+ * registration for built-ins, free functions for ad-hoc
+ * providers, an opt-out clear for tests.
+ *
+ * Listing sorts by claim priority rather than registration
+ * order, because the order providers are asked in is part of
+ * the contract and no caller should have to re-sort to get
+ * it right.
+ */
+import { type Unbacked } from "./backed.js";
+import type { RepoLocator } from "./change.js";
+import type { ReviewProvider } from "./provider.js";
+/**
+ * What a provider was found saying about itself that is not true.
+ *
+ * Reported rather than thrown. A provider with one bad declaration still does
+ * everything else it says, and refusing to register it would take a working
+ * backend off the surface over a capability nobody in this session is going to
+ * reach for. The host says this out loud instead, which is the same bargain the
+ * rest of the substrate makes about degradation.
+ */
+export interface ProviderComplaint {
+    provider: string;
+    repo: string;
+    unbacked: Unbacked[];
+}
+/**
+ * Register a provider. Replaces any provider already
+ * registered under the same id.
+ *
+ * Pass a repo to have the provider's declarations checked against its methods
+ * as it arrives, and act on whatever comes back. This is the only place that
+ * check can be made of every provider: the ones that matter arrive over the
+ * event bus from other packages, and a build-time gate cannot import one. For
+ * weeks the answer to that was a hand-copied table in each package, which is
+ * one rule and one guess about it.
+ *
+ * The repo is asked for rather than invented because a provider is entitled to
+ * answer differently for different repos, and one handed a key from a space it
+ * does not recognize returns a default and reports greens having compared
+ * nothing.
+ */
+export declare function registerReviewProvider(provider: ReviewProvider, against?: RepoLocator): ProviderComplaint | undefined;
+/** Remove a provider from the registry. Idempotent. */
+export declare function unregisterReviewProvider(id: string): void;
+/** Look up a provider by id. */
+export declare function getReviewProvider(id: string): ReviewProvider | undefined;
+/** Every registered provider, in the order they are asked. */
+export declare function listReviewProviders(): ReviewProvider[];
+/** Empty the registry. Intended for tests. */
+export declare function clearReviewProviders(): void;

package/dist/review/register.js

@@ -0,0 +1,53 @@
+/**
+ * Provider registration. Mirrors the tree library: explicit
+ * registration for built-ins, free functions for ad-hoc
+ * providers, an opt-out clear for tests.
+ *
+ * Listing sorts by claim priority rather than registration
+ * order, because the order providers are asked in is part of
+ * the contract and no caller should have to re-sort to get
+ * it right.
+ */
+import { clear, get, list, register, unregister, } from "../internal/review/registry.js";
+import { unbackedDeclarations } from "./backed.js";
+/**
+ * Register a provider. Replaces any provider already
+ * registered under the same id.
+ *
+ * Pass a repo to have the provider's declarations checked against its methods
+ * as it arrives, and act on whatever comes back. This is the only place that
+ * check can be made of every provider: the ones that matter arrive over the
+ * event bus from other packages, and a build-time gate cannot import one. For
+ * weeks the answer to that was a hand-copied table in each package, which is
+ * one rule and one guess about it.
+ *
+ * The repo is asked for rather than invented because a provider is entitled to
+ * answer differently for different repos, and one handed a key from a space it
+ * does not recognize returns a default and reports greens having compared
+ * nothing.
+ */
+export function registerReviewProvider(provider, against) {
+    register(provider);
+    if (!against)
+        return undefined;
+    const unbacked = unbackedDeclarations(provider, against);
+    return unbacked.length > 0
+        ? { provider: provider.id, repo: against.key, unbacked }
+        : undefined;
+}
+/** Remove a provider from the registry. Idempotent. */
+export function unregisterReviewProvider(id) {
+    unregister(id);
+}
+/** Look up a provider by id. */
+export function getReviewProvider(id) {
+    return get(id);
+}
+/** Every registered provider, in the order they are asked. */
+export function listReviewProviders() {
+    return [...list()].sort((a, b) => a.priority - b.priority);
+}
+/** Empty the registry. Intended for tests. */
+export function clearReviewProviders() {
+    clear();
+}

package/dist/review/resolve.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Which provider handles this reference.
+ *
+ * The order is declared rather than emergent, because the
+ * failure mode this replaces is a tool quietly reaching for
+ * the wrong backend. Config comes first, since only the user
+ * knows which of two backends mirroring the same repo is the
+ * real one this week. Then the providers themselves, in claim
+ * priority order, so adding a backend never means editing
+ * this file. Then the user's own reference shapes, which
+ * catch what no provider recognizes. Then a refusal that
+ * names the knob to turn: never a default.
+ */
+import type { ChangeRef } from "./change.js";
+import type { ReviewConfig } from "./config.js";
+import type { RepoProbe, ReviewProvider } from "./provider.js";
+/** How a reference came to be resolved. */
+export type ResolvedVia = "config-repo" | "claim" | "config-reference";
+/** Why a reference could not be resolved. */
+export type ResolutionRefusal = "no-providers" | "unclaimed";
+/** What the caller knows when asking. */
+export interface ResolveContext {
+    config?: ReviewConfig;
+    /** The checkout the question was asked from, when there is one. */
+    probe?: RepoProbe;
+}
+/** The answer, resolved or refused with guidance. */
+export type Resolution = {
+    resolved: true;
+    change: ChangeRef;
+    provider: ReviewProvider;
+    via: ResolvedVia;
+} | {
+    resolved: false;
+    reason: ResolutionRefusal;
+    /** Provider ids that were asked, in order. */
+    tried: string[];
+    /** What the user can do about it. */
+    message: string;
+};
+/**
+ * Where the config says a repo is checked out, if it says.
+ *
+ * Matched against the repo's key rather than against a probe, because
+ * the caller asking this has a repo and no directory: that is the
+ * whole situation it is for. The same substring rule as everywhere
+ * else, so one mapping serves both questions.
+ */
+export declare function checkoutFor(repoKey: string, config: ReviewConfig | undefined): string | undefined;
+/**
+ * Resolve a reference to a change and the provider owning it.
+ *
+ * A mapped repo gets first refusal, then every provider in
+ * claim order, then the user's own reference shapes. Nothing
+ * defaults: an unrecognized reference comes back as a refusal
+ * naming the knob that would fix it.
+ */
+export declare function resolveReference(input: string, context?: ResolveContext): Resolution;

package/dist/review/resolve.js

@@ -0,0 +1,150 @@
+/**
+ * Which provider handles this reference.
+ *
+ * The order is declared rather than emergent, because the
+ * failure mode this replaces is a tool quietly reaching for
+ * the wrong backend. Config comes first, since only the user
+ * knows which of two backends mirroring the same repo is the
+ * real one this week. Then the providers themselves, in claim
+ * priority order, so adding a backend never means editing
+ * this file. Then the user's own reference shapes, which
+ * catch what no provider recognizes. Then a refusal that
+ * names the knob to turn: never a default.
+ */
+import { getReviewProvider, listReviewProviders } from "./register.js";
+/** Whether a mapping's match names this checkout. */
+function mappingMatches(mapping, probe) {
+    const haystacks = [probe.repoRoot ?? "", ...(probe.remoteUrls ?? [])];
+    return haystacks.some((value) => value.includes(mapping.match));
+}
+/**
+ * Where the config says a repo is checked out, if it says.
+ *
+ * Matched against the repo's key rather than against a probe, because
+ * the caller asking this has a repo and no directory: that is the
+ * whole situation it is for. The same substring rule as everywhere
+ * else, so one mapping serves both questions.
+ */
+export function checkoutFor(repoKey, config) {
+    for (const mapping of config?.repos ?? []) {
+        if (mapping.path === undefined)
+            continue;
+        if (repoKey.includes(mapping.match))
+            return mapping.path;
+    }
+    return undefined;
+}
+/** Providers a repo mapping names, in the order it names them. */
+function mappedProviders(context) {
+    const probe = context?.probe;
+    const mappings = context?.config?.repos;
+    if (!probe || !mappings)
+        return { ids: [], present: [] };
+    const mapping = mappings.find((entry) => mappingMatches(entry, probe));
+    if (!mapping)
+        return { ids: [], present: [] };
+    const present = [];
+    for (const id of mapping.providers) {
+        const provider = getReviewProvider(id);
+        if (provider)
+            present.push(provider);
+    }
+    return { ids: mapping.providers, present };
+}
+/** Build a change from a reference mapping that matched. */
+function changeFromMapping(mapping, input) {
+    const match = new RegExp(mapping.pattern).exec(input);
+    if (!match)
+        return undefined;
+    const repoKey = match.groups?.repo ?? mapping.repo;
+    const id = match.groups?.id ?? match[1];
+    if (!repoKey || !id)
+        return undefined;
+    // A user-supplied mapping has no provider to ask for a
+    // label, and what the person typed is what they will
+    // recognize back.
+    return {
+        provider: mapping.provider,
+        repo: { key: repoKey },
+        id,
+        label: input,
+    };
+}
+/**
+ * Ask a list of providers, in order, to claim the reference.
+ *
+ * Each provider is first asked what it makes of the checkout,
+ * and that answer is handed to it along with the reference. A
+ * bare number means "in this repo", and only the provider can
+ * say whether this repo is one of its own, so a number typed in
+ * a gitstream checkout does not become a GitHub pull request.
+ */
+function firstClaim(providers, input, via, tried, probe) {
+    for (const provider of providers) {
+        tried.push(provider.id);
+        const repo = probe ? (provider.claimRepo(probe) ?? undefined) : undefined;
+        const change = provider.claimReference(input, repo);
+        if (change)
+            return { resolved: true, change, provider, via };
+    }
+    return undefined;
+}
+/** The guidance a refusal carries. */
+function refusalMessage(absentMapped) {
+    const parts = [
+        "No review provider recognized that reference.",
+        "Map its shape under review.references, or pin the repo",
+        "under review.repos.",
+    ];
+    if (absentMapped.length > 0) {
+        parts.push(`Config names ${absentMapped.join(", ")} for this repo, but`, "no provider registered under that id.");
+    }
+    return parts.join(" ");
+}
+/**
+ * Resolve a reference to a change and the provider owning it.
+ *
+ * A mapped repo gets first refusal, then every provider in
+ * claim order, then the user's own reference shapes. Nothing
+ * defaults: an unrecognized reference comes back as a refusal
+ * naming the knob that would fix it.
+ */
+export function resolveReference(input, context) {
+    const providers = listReviewProviders();
+    if (providers.length === 0) {
+        return {
+            resolved: false,
+            reason: "no-providers",
+            tried: [],
+            message: "No review provider is registered, so nothing can be " +
+                "resolved. Load the review integration, or register a " +
+                "provider over the bus.",
+        };
+    }
+    const tried = [];
+    const probe = context?.probe;
+    const mapped = mappedProviders(context);
+    const byConfig = firstClaim(mapped.present, input, "config-repo", tried, probe);
+    if (byConfig)
+        return byConfig;
+    const remaining = providers.filter((p) => !tried.includes(p.id));
+    const byClaim = firstClaim(remaining, input, "claim", tried, probe);
+    if (byClaim)
+        return byClaim;
+    for (const mapping of context?.config?.references ?? []) {
+        const provider = getReviewProvider(mapping.provider);
+        if (!provider)
+            continue;
+        const change = changeFromMapping(mapping, input);
+        if (change) {
+            return { resolved: true, change, provider, via: "config-reference" };
+        }
+    }
+    const absentMapped = mapped.ids.filter((id) => !getReviewProvider(id));
+    return {
+        resolved: false,
+        reason: "unclaimed",
+        tried,
+        message: refusalMessage(absentMapped),
+    };
+}

package/dist/review/retarget.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Pointing a stack's changes back at what they now sit on.
+ *
+ * A local restack moves branches. It does not touch the changes those
+ * branches are proposed as, so afterwards each one still claims to
+ * merge into whatever it targeted when it went up. On a stack whose
+ * bottom has landed, that is a change targeting a branch nobody is
+ * merging any more, and the diff it shows is against the wrong thing.
+ *
+ * Whose job it is to fix that differs by backend, which is what
+ * deferred this the first time. On one, retargeting is per change and
+ * the caller walks the stack doing it. On another it is a single stack
+ * operation, because the backend holds the stack itself and moving one
+ * change without the others would leave its own model inconsistent.
+ *
+ * So the substrate does what it does for a diff: implement the general
+ * case over the parts every provider has, and stand aside where a
+ * provider says it owns the whole operation. The generic walk is not a
+ * lesser version of the native one; for a backend that has no notion
+ * of a stack it is the only version there is, and it is right there.
+ */
+import type { AuthoringFacet } from "./provider.js";
+import type { Stack } from "./stack.js";
+/** One change that should point somewhere else, and where. */
+export interface Retarget {
+    /** The change to move, by the ref its node names. */
+    ref: string;
+    /** What it targets now. */
+    from: string;
+    /** What it should target. */
+    to: string;
+}
+/** What a retarget pass would do, or why it would do nothing. */
+export interface RetargetPlan {
+    /** The moves, in the order they should happen. */
+    moves: Retarget[];
+    /** Nodes deliberately left alone, and the reason for each. */
+    skipped: {
+        ref: string;
+        why: string;
+    }[];
+}
+/**
+ * Which changes in a stack point at the wrong base, and where they go.
+ *
+ * Roots are excluded rather than pointed at the trunk. A root already
+ * targets the trunk in the ordinary case, and where it does not, the
+ * stack cannot say whether that is wrong: somebody may be proposing a
+ * root against a release branch on purpose, and moving it to the trunk
+ * would retarget a change nobody asked about onto a branch that asks a
+ * different team to review it.
+ */
+export declare function retargetPlan(stack: Stack): RetargetPlan;
+/** Whether a provider owns this operation, or the substrate walks it. */
+export interface RetargetRoute {
+    kind: "native" | "per-change";
+    /** Said out loud, because which one ran changes what can go wrong. */
+    why: string;
+}
+/**
+ * Who should carry out a retarget, and why that is the right answer.
+ *
+ * Named rather than decided silently because the two fail differently
+ * and a caller has to be able to report which happened. A native pass
+ * either moves the stack or does not. A per-change walk can stop half
+ * way, leaving some changes moved and some not, and somebody reading
+ * "retarget failed" needs to know which of those they are looking at.
+ */
+export declare function retargetRoute(stacking: {
+    restack?: unknown;
+} | undefined, authoring: AuthoringFacet | undefined): RetargetRoute | {
+    refusal: string;
+};