@jitsusama/agentic-harness.core 0.1.0

package/dist/work/stack.d.ts

@@ -0,0 +1,126 @@
+/**
+ * A stack of branches, each sitting on the one below it.
+ *
+ * Git does not track this. A branch knows its commits and nothing about which
+ * other branch it was built on top of, so a stack is either recorded somewhere
+ * or guessed at, and guessing is what makes stacked tooling feel haunted: infer
+ * parentage from merge-base and the answer changes under you the moment two
+ * branches share history for an unrelated reason.
+ *
+ * So parentage is recorded, and everything here is a function of that record.
+ * This file is the part that thinks. It never runs git: it takes what the
+ * record says and works out the order to replay in, what a reorder implies, and
+ * which moves would produce something that is not a stack at all. The git side
+ * is a thin adapter over these answers, which is what makes the hard part
+ * testable without a repository.
+ *
+ * The one rule worth stating up front: a replay step carries the base the
+ * branch was last aligned at, not just the branch and its new parent. Replaying
+ * without it hands the branch every commit its parent already has, which is the
+ * duplicated-commit mess that makes people abandon stacks and go back to one
+ * enormous branch.
+ */
+/** A branch and what it sits on. */
+export interface StackedBranch {
+    name: string;
+    /** What it sits on. Absent means it sits on trunk and is a root. */
+    parent?: string;
+    /**
+     * The parent's commit when this branch was last aligned with it.
+     *
+     * This is the boundary of what belongs to this branch. Without it a
+     * replay cannot tell which commits are its own, and hands the branch
+     * copies of everything its parent already carries.
+     */
+    base?: string;
+}
+/** One replay a restack needs, in the order it has to happen. */
+export interface ReplayStep {
+    branch: string;
+    /** What it is being replayed onto: a parent branch, or trunk. */
+    onto: string;
+    /** The base to replay from, when one is recorded. */
+    from?: string;
+}
+/** One parentage change a reorder implies. */
+export interface ReparentStep {
+    branch: string;
+    /** Its new parent, or trunk when it becomes a root. */
+    parent?: string;
+}
+/** Why a set of branches is not a stack. */
+export interface StackFault {
+    kind: "cycle" | "unknown-parent" | "duplicate";
+    /** The branches involved, so the message can name them. */
+    branches: readonly string[];
+    reason: string;
+}
+/** The reason a set of branches is not a stack. */
+export interface Faulted {
+    kind: "faulted";
+    fault: StackFault;
+}
+/** Either an ordering or the reason there is not one. */
+export type StackOrder = {
+    kind: "ordered";
+    branches: readonly StackedBranch[];
+} | Faulted;
+/** Either a plan of replays or the reason there is not one. */
+export type RestackPlan = {
+    kind: "planned";
+    steps: readonly ReplayStep[];
+} | Faulted;
+/** Either a plan of parentage changes or the reason there is not one. */
+export type ReorderPlan = {
+    kind: "planned";
+    steps: readonly ReparentStep[];
+} | Faulted;
+/**
+ * Put a stack in the order work has to happen: roots first, each branch after
+ * whatever it sits on.
+ *
+ * A restack that runs out of order is worse than one that does not run: replay
+ * a child onto its parent before the parent has moved and the child is now
+ * aligned to a base that is about to stop existing.
+ *
+ * Siblings keep the order they were given. Nothing here can rank two branches
+ * that sit on the same parent, and inventing a rank would make a restack's
+ * output depend on a detail nobody chose.
+ */
+export declare function orderStack(branches: readonly StackedBranch[]): StackOrder;
+/** Every branch sitting on this one, however far down. */
+export declare function descendantsOf(branches: readonly StackedBranch[], name: string): readonly string[];
+/**
+ * The replays a restack needs, in order.
+ *
+ * `trunk` is what a root sits on. Every step carries the base its branch was
+ * last aligned at, because that boundary is the only thing separating the
+ * branch's own commits from its parent's.
+ *
+ * A branch whose base is unrecorded still gets a step. The adapter falls back
+ * to asking git for a merge-base, which is a guess, but a guess made at the
+ * moment of replaying and reported as one beats refusing to replay a branch
+ * somebody tracked by hand.
+ */
+export declare function planRestack(branches: readonly StackedBranch[], trunk: string): RestackPlan;
+/**
+ * What a reorder implies, as parentage changes.
+ *
+ * The caller says the order it wants, root first, and gets back the reparenting
+ * that produces it. Expressing a reorder as reparenting rather than as its own
+ * operation is deliberate: there is only one way for a branch to move in a
+ * stack, and a second vocabulary for it would be a second set of rules about
+ * what is legal.
+ *
+ * The desired order has to name the same branches as the chain it is
+ * reordering. Naming a subset would quietly orphan whatever was left out.
+ */
+export declare function planReorder(branches: readonly StackedBranch[], desired: readonly string[]): ReorderPlan;
+/**
+ * Whether pointing a branch at a new parent still leaves a stack.
+ *
+ * Checked before anything runs, because the failure is silent: a branch made
+ * its own ancestor still rebases, and produces a repository where a restack
+ * never terminates.
+ */
+export declare function reparentFault(branches: readonly StackedBranch[], name: string, parent: string | undefined): StackFault | undefined;

package/dist/work/stack.js

@@ -0,0 +1,243 @@
+/**
+ * A stack of branches, each sitting on the one below it.
+ *
+ * Git does not track this. A branch knows its commits and nothing about which
+ * other branch it was built on top of, so a stack is either recorded somewhere
+ * or guessed at, and guessing is what makes stacked tooling feel haunted: infer
+ * parentage from merge-base and the answer changes under you the moment two
+ * branches share history for an unrelated reason.
+ *
+ * So parentage is recorded, and everything here is a function of that record.
+ * This file is the part that thinks. It never runs git: it takes what the
+ * record says and works out the order to replay in, what a reorder implies, and
+ * which moves would produce something that is not a stack at all. The git side
+ * is a thin adapter over these answers, which is what makes the hard part
+ * testable without a repository.
+ *
+ * The one rule worth stating up front: a replay step carries the base the
+ * branch was last aligned at, not just the branch and its new parent. Replaying
+ * without it hands the branch every commit its parent already has, which is the
+ * duplicated-commit mess that makes people abandon stacks and go back to one
+ * enormous branch.
+ */
+/**
+ * Put a stack in the order work has to happen: roots first, each branch after
+ * whatever it sits on.
+ *
+ * A restack that runs out of order is worse than one that does not run: replay
+ * a child onto its parent before the parent has moved and the child is now
+ * aligned to a base that is about to stop existing.
+ *
+ * Siblings keep the order they were given. Nothing here can rank two branches
+ * that sit on the same parent, and inventing a rank would make a restack's
+ * output depend on a detail nobody chose.
+ */
+export function orderStack(branches) {
+    const byName = new Map();
+    for (const branch of branches) {
+        if (byName.has(branch.name)) {
+            return {
+                kind: "faulted",
+                fault: {
+                    kind: "duplicate",
+                    branches: [branch.name],
+                    reason: `${branch.name} appears twice, so there is no single answer to what it sits on.`,
+                },
+            };
+        }
+        byName.set(branch.name, branch);
+    }
+    for (const branch of branches) {
+        if (branch.parent !== undefined && !byName.has(branch.parent)) {
+            return {
+                kind: "faulted",
+                fault: {
+                    kind: "unknown-parent",
+                    branches: [branch.name, branch.parent],
+                    reason: `${branch.name} sits on ${branch.parent}, which is not in this stack. Track it, or point ${branch.name} at something that is here.`,
+                },
+            };
+        }
+    }
+    const ordered = [];
+    const placed = new Set();
+    // Walking to the root from each branch and placing ancestors first is
+    // what makes a cycle visible: a chain that revisits a name it is
+    // already walking has no root to reach.
+    for (const branch of branches) {
+        const chain = [];
+        const walking = new Set();
+        let at = branch;
+        while (at !== undefined && !placed.has(at.name)) {
+            if (walking.has(at.name)) {
+                return {
+                    kind: "faulted",
+                    fault: {
+                        kind: "cycle",
+                        branches: [...walking],
+                        reason: `${[...walking].join(" sits on ")} sits on ${at.name}, which closes a loop. A stack has to end somewhere.`,
+                    },
+                };
+            }
+            walking.add(at.name);
+            chain.unshift(at);
+            at = at.parent === undefined ? undefined : byName.get(at.parent);
+        }
+        for (const one of chain) {
+            if (placed.has(one.name))
+                continue;
+            placed.add(one.name);
+            ordered.push(one);
+        }
+    }
+    return { kind: "ordered", branches: ordered };
+}
+/** Every branch sitting on this one, however far down. */
+export function descendantsOf(branches, name) {
+    const found = [];
+    const frontier = [name];
+    while (frontier.length > 0) {
+        const at = frontier.shift();
+        for (const branch of branches) {
+            if (branch.parent !== at || found.includes(branch.name))
+                continue;
+            found.push(branch.name);
+            frontier.push(branch.name);
+        }
+    }
+    return found;
+}
+/**
+ * The replays a restack needs, in order.
+ *
+ * `trunk` is what a root sits on. Every step carries the base its branch was
+ * last aligned at, because that boundary is the only thing separating the
+ * branch's own commits from its parent's.
+ *
+ * A branch whose base is unrecorded still gets a step. The adapter falls back
+ * to asking git for a merge-base, which is a guess, but a guess made at the
+ * moment of replaying and reported as one beats refusing to replay a branch
+ * somebody tracked by hand.
+ */
+export function planRestack(branches, trunk) {
+    const order = orderStack(branches);
+    if (order.kind === "faulted")
+        return order;
+    const steps = order.branches.map((branch) => ({
+        branch: branch.name,
+        onto: branch.parent ?? trunk,
+        ...(branch.base === undefined ? {} : { from: branch.base }),
+    }));
+    return { kind: "planned", steps };
+}
+/**
+ * What a reorder implies, as parentage changes.
+ *
+ * The caller says the order it wants, root first, and gets back the reparenting
+ * that produces it. Expressing a reorder as reparenting rather than as its own
+ * operation is deliberate: there is only one way for a branch to move in a
+ * stack, and a second vocabulary for it would be a second set of rules about
+ * what is legal.
+ *
+ * The desired order has to name the same branches as the chain it is
+ * reordering. Naming a subset would quietly orphan whatever was left out.
+ */
+export function planReorder(branches, desired) {
+    const order = orderStack(branches);
+    if (order.kind === "faulted")
+        return order;
+    const known = new Set(branches.map((branch) => branch.name));
+    const missing = desired.filter((name) => !known.has(name));
+    if (missing.length > 0) {
+        return {
+            kind: "faulted",
+            fault: {
+                kind: "unknown-parent",
+                branches: missing,
+                reason: `${missing.join(", ")} ${missing.length === 1 ? "is" : "are"} not in this stack, so ${missing.length === 1 ? "it" : "they"} cannot be placed in it.`,
+            },
+        };
+    }
+    const duplicated = desired.filter((name, at) => desired.indexOf(name) !== at);
+    if (duplicated.length > 0) {
+        return {
+            kind: "faulted",
+            fault: {
+                kind: "duplicate",
+                branches: duplicated,
+                reason: `${duplicated.join(", ")} appears more than once in the order asked for, and a branch can only sit in one place.`,
+            },
+        };
+    }
+    // Reordering a chain means reordering exactly that chain. A subset would
+    // leave a branch sitting on something that has moved out from under it,
+    // which is a broken stack presented as a completed reorder.
+    const chain = new Set(desired);
+    const orphaned = branches.filter((branch) => !chain.has(branch.name) &&
+        branch.parent !== undefined &&
+        chain.has(branch.parent));
+    if (orphaned.length > 0) {
+        return {
+            kind: "faulted",
+            fault: {
+                kind: "unknown-parent",
+                branches: orphaned.map((branch) => branch.name),
+                reason: `${orphaned.map((branch) => branch.name).join(", ")} sits on a branch being reordered but was not named in the new order, so the reorder would leave it behind. Name every branch above the lowest one you are moving.`,
+            },
+        };
+    }
+    const steps = [];
+    // The new lowest branch inherits whatever the old lowest sat on, since a
+    // reorder rearranges a chain rather than relocating it. Topological order
+    // is what identifies the old lowest: it is the first of the chain to
+    // appear once ancestors come before descendants.
+    const anchor = order.branches.find((branch) => chain.has(branch.name))?.parent;
+    desired.forEach((name, at) => {
+        const parent = at === 0 ? anchor : desired[at - 1];
+        const current = branches.find((branch) => branch.name === name)?.parent;
+        if (current === parent)
+            return;
+        steps.push({ branch: name, ...(parent === undefined ? {} : { parent }) });
+    });
+    return { kind: "planned", steps };
+}
+/**
+ * Whether pointing a branch at a new parent still leaves a stack.
+ *
+ * Checked before anything runs, because the failure is silent: a branch made
+ * its own ancestor still rebases, and produces a repository where a restack
+ * never terminates.
+ */
+export function reparentFault(branches, name, parent) {
+    if (parent === undefined)
+        return undefined;
+    if (parent === name) {
+        return {
+            kind: "cycle",
+            branches: [name],
+            reason: `${name} cannot sit on itself.`,
+        };
+    }
+    if (!branches.some((branch) => branch.name === name)) {
+        return {
+            kind: "unknown-parent",
+            branches: [name],
+            reason: `${name} is not tracked in this stack.`,
+        };
+    }
+    if (!branches.some((branch) => branch.name === parent)) {
+        return {
+            kind: "unknown-parent",
+            branches: [parent],
+            reason: `${parent} is not tracked in this stack, so nothing can be stacked on it yet. Track it first.`,
+        };
+    }
+    if (descendantsOf(branches, name).includes(parent)) {
+        return {
+            kind: "cycle",
+            branches: [name, parent],
+            reason: `${parent} already sits above ${name}, so putting ${name} on it would close a loop.`,
+        };
+    }
+    return undefined;
+}

package/dist/work/stacks.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Keeping a stack, and replaying it when what it sits on moves.
+ *
+ * The thinking lives in `stack.ts` and never touches a repository. This is the
+ * adapter: it stores parentage, asks git to replay, and stops the moment a
+ * replay halts.
+ *
+ * Parentage is stored in git's own config, under the branch it describes. That
+ * puts it in the repository rather than in this package's state, which is the
+ * property that matters: the record survives a session, is visible to anybody
+ * who runs `git config`, and is deleted by git itself when the branch is. A
+ * stack recorded in a tool's private state is a stack that quietly outlives the
+ * branches it names.
+ *
+ * A stacked backend that tracks parentage itself is the reason this is a facet
+ * rather than the implementation. On a repository driven by such a tool, its
+ * record is the truth and this one would be a second opinion; a provider there
+ * should offer its own `WorkStacks` instead of teaching this one a second
+ * vocabulary.
+ *
+ * Restacking stops at the first halt and says what it did not reach. Carrying
+ * on would replay later branches onto a parent that is mid-rebase, which
+ * produces a stack that looks restacked and is built on a commit that is about
+ * to be rewritten.
+ */
+import type { Exec } from "../exec/index.js";
+import type { WorkRebaser } from "./rebase.js";
+import { type StackedBranch, type StackFault } from "./stack.js";
+/** What happened to one branch during a restack. */
+export interface ReplayResult {
+    branch: string;
+    onto: string;
+    outcome: "replayed" | "already-there" | "halted" | "skipped";
+    /** Paths that disagree, when it halted. */
+    conflicted?: readonly string[];
+}
+/** How a restack went. */
+export type RestackOutcome = {
+    kind: "restacked";
+    results: readonly ReplayResult[];
+    /** Where the tree was left, which is where it started. */
+    on?: string;
+} | {
+    kind: "halted";
+    /** What was done, what stopped, and what was never reached. */
+    results: readonly ReplayResult[];
+    at: string;
+    conflicted: readonly string[];
+} | {
+    kind: "faulted";
+    fault: StackFault;
+} | {
+    kind: "refused";
+    reason: string;
+};
+/** How a change to the stack's shape went. */
+export type ShapeOutcome = {
+    kind: "shaped";
+    changed: readonly string[];
+} | {
+    kind: "unchanged";
+} | {
+    kind: "faulted";
+    fault: StackFault;
+} | {
+    kind: "refused";
+    reason: string;
+};
+/** Keeping and replaying a stack of branches. */
+export interface WorkStacks {
+    /** What this repository records about its stack. */
+    read(treePath: string): Promise<readonly StackedBranch[]>;
+    /** Record that a branch sits on another, or on trunk. */
+    track(treePath: string, branch: string, parent?: string): Promise<ShapeOutcome>;
+    /** Forget a branch, moving whatever sat on it down onto its parent. */
+    untrack(treePath: string, branch: string): Promise<ShapeOutcome>;
+    /** Point a branch at a different parent. */
+    reparent(treePath: string, branch: string, parent?: string): Promise<ShapeOutcome>;
+    /** Rearrange a chain into the order given, lowest first. */
+    reorder(treePath: string, desired: readonly string[]): Promise<ShapeOutcome>;
+    /**
+     * Which tracked branches no longer sit on the branch beneath them.
+     *
+     * The one fact about a stack that git will not tell you and that a listing of
+     * names cannot show. A branch drifts whenever what it sits on moves without it:
+     * its parent gets amended, or rebased, or reparented, and now the branch is
+     * built on a commit that is no longer anybody's tip. Until it is replayed the
+     * shape on paper and the shape in the commits disagree, and the whole point of
+     * recording a stack is to be told when that has happened.
+     *
+     * A root branch is judged against trunk, so trunk has to be named to judge one.
+     * Without it the roots are reported as undecidable rather than as aligned,
+     * because a listing that quietly calls an unknown "fine" is worse than one that
+     * says it does not know.
+     */
+    drifted(treePath: string, trunk?: string): Promise<DriftReport>;
+    /**
+     * Record where a branch sits, after a replay this object did not run.
+     *
+     * The boundary between a branch's commits and its parent's is written by a
+     * restack as it goes, which is fine until a restack halts. The way out of a halt
+     * is to settle the conflict and resume, and resume belongs to the rebaser, which
+     * knows nothing about stacks and so recorded nothing. That is the documented
+     * recovery from the commonest failure here, and it left the record describing a
+     * branch as it was several commits ago.
+     *
+     * The consequence was not a wrong label. The next restack measured the replay
+     * from that stale boundary, which sat below six of trunk's own commits, and so
+     * handed the branch copies of trunk's history and a conflict on each one.
+     *
+     * Naming no branch means the one checked out, which is where a resume leaves you.
+     * Untracked branches are ignored rather than refused: this is called on the way
+     * out of an operation that has already succeeded, and it has no standing to fail
+     * it.
+     */
+    settled(treePath: string, branch?: string): Promise<void>;
+    /** Replay the whole stack onto trunk, in order. */
+    restack(treePath: string, trunk: string): Promise<RestackOutcome>;
+    /**
+     * Fetch trunk, then replay the stack onto where it now is.
+     *
+     * The daily operation, and one verb rather than two because doing half of it
+     * is the mistake: restacking without fetching replays the stack onto a trunk
+     * as stale as the one it was already on, reports success, and leaves
+     * everything exactly as behind as it was.
+     */
+    sync(treePath: string, trunk: string): Promise<SyncOutcome>;
+}
+/** Which branches are out of step with what they sit on. */
+export interface DriftReport {
+    /** Tracked branches no longer sitting on their parent's tip. */
+    drifted: readonly string[];
+    /**
+     * Branches whose alignment could not be judged, and why not.
+     *
+     * Reported rather than folded into either answer. Absent means unreported, not
+     * aligned, and a diagram that draws "could not tell" as "fine" is the reason
+     * somebody trusts a stale stack.
+     */
+    undecided: readonly string[];
+}
+/** How a sync went. */
+export type SyncOutcome = {
+    kind: "synced";
+    /** True when fetching actually moved trunk. */
+    moved: boolean;
+    replay: RestackOutcome;
+} | {
+    kind: "refused";
+    reason: string;
+};
+/** Keep and replay a stack with plain git. */
+export declare function createGitStacks(deps: {
+    exec: Exec;
+    rebaser: WorkRebaser;
+}): WorkStacks;