agentopology 0.2.5 → 0.4.0

package/dist/resolve/__tests__/phase.test.js

@@ -0,0 +1,81 @@
+/**
+ * An unphased agent must sort the same way on every target.
+ *
+ * Regression: six consumers each picked their own sentinel — MAX_SAFE_INTEGER
+ * in claude-code and claude-workflow, 999 in gemini-cli, 0 in openclaw, kiro,
+ * mermaid and the markdown exporter. So the same topology put an unphased
+ * agent LAST on three targets and FIRST on three others. That is exactly the
+ * failure "write once, deploy to any platform" exists to prevent, and nothing
+ * compared them.
+ */
+import { describe, it, expect } from "vitest";
+import { readFileSync, readdirSync } from "node:fs";
+import { resolve, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parse } from "../../parser/index.js";
+import { phaseOf, byPhase, UNPHASED } from "../phase.js";
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "../../..");
+const MIXED = `topology t : [pipeline] {
+  meta {
+    version: "1.0.0"
+    description: "one phased agent, one not"
+  }
+  agent early {
+    model: sonnet
+    description: "e"
+    phase: 1
+  }
+  agent unphased {
+    model: sonnet
+    description: "u"
+  }
+  action i {
+    kind: inline
+    description: "in"
+  }
+  flow { i -> early -> unphased }
+}`;
+describe("phase resolution is defined in exactly one place", () => {
+    it("gives an unphased agent a key no real declaration can reach", () => {
+        // 999 collides with `phase: 999`; 0 collides with `phase: 0`. This cannot
+        // collide, because `phase` is parseFloat'd from a source literal.
+        expect(UNPHASED).toBe(Number.MAX_SAFE_INTEGER);
+    });
+    it("trails unphased agents rather than leading them", () => {
+        const agents = parse(MIXED).nodes.filter((n) => n.type === "agent");
+        const sorted = [...agents].sort(byPhase).map((a) => a.id);
+        expect(sorted).toEqual(["early", "unphased"]);
+    });
+    it("leaves declaration order intact when nobody declares a phase", () => {
+        const src = MIXED.replace("    phase: 1\n", "");
+        const agents = parse(src).nodes.filter((n) => n.type === "agent");
+        expect(agents.every((a) => phaseOf(a) === UNPHASED)).toBe(true);
+        expect([...agents].sort(byPhase).map((a) => a.id)).toEqual(["early", "unphased"]);
+    });
+    it("no consumer defines its own phase fallback", () => {
+        // The guard that actually prevents the regression: grep the source. A new
+        // `agent.phase ?? <n>` anywhere reintroduces the divergence silently.
+        const offenders = [];
+        const walk = (dir) => {
+            for (const entry of readdirSync(dir, { withFileTypes: true })) {
+                const p = join(dir, entry.name);
+                if (entry.isDirectory()) {
+                    if (entry.name === "__tests__" || entry.name === "node_modules")
+                        continue;
+                    walk(p);
+                    continue;
+                }
+                if (!entry.name.endsWith(".ts"))
+                    continue;
+                if (p.endsWith(join("resolve", "phase.ts")))
+                    continue;
+                const text = readFileSync(p, "utf8");
+                if (/\bphase\s*\?\?\s*/.test(text))
+                    offenders.push(p.slice(root.length + 1));
+            }
+        };
+        walk(join(root, "src"));
+        expect(offenders, `these define their own phase fallback instead of using resolve/phase.ts: ${offenders.join(", ")}`).toEqual([]);
+    });
+});
+//# sourceMappingURL=phase.test.js.map

package/dist/resolve/__tests__/phase.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"phase.test.js","sourceRoot":"","sources":["../../../src/resolve/__tests__/phase.test.ts"],"names":[],"mappings":"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"}

package/dist/resolve/defaults.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Defaults resolver — the first code in the package that reads the spec's
+ * defaults table (`spec/grammar.md` §7).
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * The parser writes a field only when it is present in the source, so every
+ * optional field on a node arrives `undefined`. Until now each binding filled
+ * the blanks itself, and they disagree: `agent.permissions` defaults to
+ * `"supervised"` in `bindings/codex.ts`, `"auto"` in `bindings/openclaw.ts`,
+ * while the spec says `autonomous`. Interpreted mode cannot tolerate that —
+ * an execution brief must state one resolved value and be able to name where
+ * it came from.
+ *
+ * WHAT THIS DOES NOT DO
+ * ---------------------
+ * It does not mutate the input and no binding consumes it. Wiring it into the
+ * bindings would silently change their output for three targets, which is a
+ * separate, deliberate change. This resolver serves `agentopology plan`.
+ *
+ * Only defaults that are a CONCRETE VALUE are applied. Table rows whose default
+ * is "-- (none)" stay `undefined`, because absence is their meaning.
+ *
+ * @module
+ */
+import type { TopologyAST } from "../parser/ast.js";
+/** One resolved field, and the fact that it was not authored. */
+export interface ResolvedDefault {
+    /** Node id, or `"<topology>"` for topology-level fields. */
+    node: string;
+    /** Field name as it appears in the grammar (kebab-case). */
+    field: string;
+    /** The value the spec says to use. */
+    value: unknown;
+}
+/** Result of resolving defaults: a new AST plus the list of what was filled. */
+export interface DefaultsResolution {
+    ast: TopologyAST;
+    applied: ResolvedDefault[];
+}
+/**
+ * Fill every omitted optional field that the spec gives a concrete default.
+ *
+ * Returns a NEW ast — the input is not mutated — plus the list of fields that
+ * were filled, so a caller can report which values the author never wrote.
+ *
+ * @param ast - A parsed topology.
+ * @returns The resolved AST and the record of what was applied.
+ */
+export declare function resolveDefaults(ast: TopologyAST): DefaultsResolution;
+//# sourceMappingURL=defaults.d.ts.map

package/dist/resolve/defaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../../src/resolve/defaults.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAA4C,MAAM,kBAAkB,CAAC;AAE9F,iEAAiE;AACjE,MAAM,WAAW,eAAe;IAC9B,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;IACb,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAC;IACd,sCAAsC;IACtC,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,gFAAgF;AAChF,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,WAAW,CAAC;IACjB,OAAO,EAAE,eAAe,EAAE,CAAC;CAC5B;AAyDD;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,WAAW,GAAG,kBAAkB,CA4BpE"}

package/dist/resolve/defaults.js

@@ -0,0 +1,109 @@
+/**
+ * Defaults resolver — the first code in the package that reads the spec's
+ * defaults table (`spec/grammar.md` §7).
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * The parser writes a field only when it is present in the source, so every
+ * optional field on a node arrives `undefined`. Until now each binding filled
+ * the blanks itself, and they disagree: `agent.permissions` defaults to
+ * `"supervised"` in `bindings/codex.ts`, `"auto"` in `bindings/openclaw.ts`,
+ * while the spec says `autonomous`. Interpreted mode cannot tolerate that —
+ * an execution brief must state one resolved value and be able to name where
+ * it came from.
+ *
+ * WHAT THIS DOES NOT DO
+ * ---------------------
+ * It does not mutate the input and no binding consumes it. Wiring it into the
+ * bindings would silently change their output for three targets, which is a
+ * separate, deliberate change. This resolver serves `agentopology plan`.
+ *
+ * Only defaults that are a CONCRETE VALUE are applied. Table rows whose default
+ * is "-- (none)" stay `undefined`, because absence is their meaning.
+ *
+ * @module
+ */
+/**
+ * Concrete agent defaults from `spec/grammar.md` §7. Keys are AST field names;
+ * `grammarName` is the kebab-case spelling used in `.at` source and in reports.
+ */
+const AGENT_DEFAULTS = [
+    { key: "permissions", grammarName: "permissions", value: "autonomous" },
+    { key: "disallowedTools", grammarName: "disallowed-tools", value: [] },
+    { key: "reads", grammarName: "reads", value: [] },
+    { key: "writes", grammarName: "writes", value: [] },
+    { key: "outputs", grammarName: "outputs", value: {} },
+    { key: "retry", grammarName: "retry", value: 0 },
+    { key: "invocation", grammarName: "invocation", value: "auto" },
+    { key: "behavior", grammarName: "behavior", value: "blocking" },
+    { key: "memory", grammarName: "memory", value: [] },
+    { key: "skills", grammarName: "skills", value: [] },
+    { key: "mcpServers", grammarName: "mcp-servers", value: [] },
+    { key: "background", grammarName: "background", value: false },
+    { key: "fallbackChain", grammarName: "fallback-chain", value: [] },
+];
+const GATE_DEFAULTS = [
+    { key: "checks", grammarName: "checks", value: [] },
+    { key: "retry", grammarName: "retry", value: 0 },
+    { key: "onFail", grammarName: "on-fail", value: "halt" },
+    { key: "behavior", grammarName: "behavior", value: "blocking" },
+];
+const ACTION_DEFAULTS = [
+    { key: "commands", grammarName: "commands", value: [] },
+];
+/** Deep-ish clone that is enough for an AST of plain data. */
+function cloneValue(v) {
+    if (Array.isArray(v))
+        return [...v];
+    if (v && typeof v === "object")
+        return { ...v };
+    return v;
+}
+function applyTo(node, id, table, applied) {
+    for (const { key, grammarName, value } of table) {
+        if (node[key] === undefined) {
+            node[key] = cloneValue(value);
+            // Clone for the REPORT too. Pushing `value` handed the caller a reference
+            // to the module-level table, so one mutation of a reported value poisoned
+            // the default for every later topology in the process.
+            applied.push({ node: id, field: grammarName, value: cloneValue(value) });
+        }
+    }
+}
+/**
+ * Fill every omitted optional field that the spec gives a concrete default.
+ *
+ * Returns a NEW ast — the input is not mutated — plus the list of fields that
+ * were filled, so a caller can report which values the author never wrote.
+ *
+ * @param ast - A parsed topology.
+ * @returns The resolved AST and the record of what was applied.
+ */
+export function resolveDefaults(ast) {
+    const applied = [];
+    const nodes = ast.nodes.map((n) => {
+        const copy = { ...n };
+        switch (n.type) {
+            case "agent":
+                applyTo(copy, n.id, AGENT_DEFAULTS, applied);
+                break;
+            case "gate":
+                applyTo(copy, n.id, GATE_DEFAULTS, applied);
+                break;
+            case "action":
+                applyTo(copy, n.id, ACTION_DEFAULTS, applied);
+                break;
+            case "orchestrator":
+                if (copy.outputs === undefined) {
+                    copy.outputs = {};
+                    applied.push({ node: n.id, field: "outputs", value: {} });
+                }
+                break;
+            default:
+                break;
+        }
+        return copy;
+    });
+    return { ast: { ...ast, nodes }, applied };
+}
+//# sourceMappingURL=defaults.js.map

package/dist/resolve/defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.js","sourceRoot":"","sources":["../../src/resolve/defaults.ts"],"names":[],"mappings":"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"}

package/dist/resolve/order.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Execution order resolver.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * `computeLayers` in `../analyzer` is a correct Kahn topological rank, but it
+ * cannot be used directly for execution order. Gates bind to the graph through
+ * `after:` / `before:` fields, never through edges, so they have in-degree 0
+ * and Kahn ranks them as SOURCES. Measured on `examples/code-review.at`, the
+ * gate `human-approval` lands in layer 0 next to the entry action.
+ *
+ * So: rank the flow-participating nodes only, then splice gates back in at the
+ * position their `after` / `before` actually names.
+ *
+ * The orchestrator is deliberately NOT a step. In interpreted mode the host
+ * coding agent IS the orchestrator — it does not spawn one.
+ *
+ * @module
+ */
+import type { TopologyAST, EdgeDef } from "../parser/ast.js";
+/** What the host does at one step. */
+export type StepKind = "spawn" | "gate" | "action" | "human" | "group";
+/** One step of the resolved execution order. */
+export interface OrderStep {
+    /** 1-based position. */
+    index: number;
+    kind: StepKind;
+    /** Node ids. More than one means they run in parallel, mutually blind. */
+    ids: string[];
+    /** Graph rank, or `null` for a gate (spliced by position, never ranked). */
+    depth: number | null;
+    /**
+     * True when the ids are mutually EXCLUSIVE branches, not a parallel fan-out:
+     * every one is reached only by a conditional edge from the same source.
+     * Exactly one runs.
+     *
+     * Without this the renderer called them "parallel" and the brief marked them
+     * mutually blind and told the host to dispatch all of them in one message —
+     * running every branch of a decision instead of taking one.
+     */
+    exclusive: boolean;
+    /** For an exclusive step, the condition that selects each id. */
+    branchOn?: Array<{
+        id: string;
+        condition: string;
+    }>;
+}
+/** A back-edge with its iteration budget. */
+export interface LoopInfo {
+    from: string;
+    to: string;
+    condition: string | null;
+    /** `[max N]` — the number of TRAVERSALS allowed, so the target runs N+1 times. */
+    budget: number | null;
+}
+export interface ResolvedOrder {
+    steps: OrderStep[];
+    loops: LoopInfo[];
+    /** Nodes Kahn could not reach — cycle members. `computeLayers` gives depth -1. */
+    unreachable: string[];
+    /** The orchestrator's id, if declared. It is the host, not a step. */
+    orchestrator: string | null;
+}
+/**
+ * Resolve the order in which a host agent should enact a topology.
+ *
+ * @param ast - A parsed topology. Order does not depend on defaults resolution.
+ * @returns Ordered steps, loop budgets, unreachable nodes, and the orchestrator id.
+ */
+export declare function resolveOrder(ast: TopologyAST): ResolvedOrder;
+/** All outbound edges from a node, in declaration order. */
+export declare function edgesFrom(ast: TopologyAST, id: string): EdgeDef[];
+//# sourceMappingURL=order.d.ts.map

package/dist/resolve/order.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"order.d.ts","sourceRoot":"","sources":["../../src/resolve/order.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,OAAO,EAAqB,MAAM,kBAAkB,CAAC;AAGhF,sCAAsC;AACtC,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAC;AAEvE,gDAAgD;AAChD,MAAM,WAAW,SAAS;IACxB,wBAAwB;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,QAAQ,CAAC;IACf,0EAA0E;IAC1E,GAAG,EAAE,MAAM,EAAE,CAAC;IACd,4EAA4E;IAC5E,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB;;;;;;;;OAQG;IACH,SAAS,EAAE,OAAO,CAAC;IACnB,iEAAiE;IACjE,QAAQ,CAAC,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACrD;AAED,6CAA6C;AAC7C,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,kFAAkF;IAClF,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,kFAAkF;IAClF,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,sEAAsE;IACtE,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAkDD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,WAAW,GAAG,aAAa,CAyI5D;AAED,4DAA4D;AAC5D,wBAAgB,SAAS,CAAC,GAAG,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,EAAE,CAEjE"}

package/dist/resolve/order.js

@@ -0,0 +1,208 @@
+/**
+ * Execution order resolver.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * `computeLayers` in `../analyzer` is a correct Kahn topological rank, but it
+ * cannot be used directly for execution order. Gates bind to the graph through
+ * `after:` / `before:` fields, never through edges, so they have in-degree 0
+ * and Kahn ranks them as SOURCES. Measured on `examples/code-review.at`, the
+ * gate `human-approval` lands in layer 0 next to the entry action.
+ *
+ * So: rank the flow-participating nodes only, then splice gates back in at the
+ * position their `after` / `before` actually names.
+ *
+ * The orchestrator is deliberately NOT a step. In interpreted mode the host
+ * coding agent IS the orchestrator — it does not spawn one.
+ *
+ * @module
+ */
+import { computeLayers } from "../analyzer/index.js";
+/**
+ * True back-edges, found by DFS over the FULL edge set.
+ *
+ * `findBackEdges` in the validator cannot be reused here: it strips every edge
+ * carrying `[max N]` first, because its job is to find loops the author has NOT
+ * acknowledged (that is V6). We need the opposite — the acknowledged ones too.
+ *
+ * And `computeLayers` strips them as well, so a plain FORWARD edge that happens
+ * to carry a bound both corrupts the ranking and gets reported as a loop.
+ * Classifying first, then ranking with only the real back-edges removed, fixes
+ * both.
+ */
+function trueBackEdges(edges, nodeIds) {
+    const out = new Map();
+    for (const e of edges) {
+        if (e.isError)
+            continue;
+        if (!nodeIds.has(e.from) || !nodeIds.has(e.to))
+            continue;
+        if (!out.has(e.from))
+            out.set(e.from, []);
+        out.get(e.from).push(e.to);
+    }
+    const WHITE = 0, GREY = 1, BLACK = 2;
+    const colour = new Map([...nodeIds].map((id) => [id, WHITE]));
+    const back = new Set();
+    const visit = (id) => {
+        colour.set(id, GREY);
+        for (const to of out.get(id) ?? []) {
+            const c = colour.get(to) ?? WHITE;
+            // An edge into a node still on the DFS stack closes a cycle.
+            if (c === GREY)
+                back.add(`${id} ${to}`);
+            else if (c === WHITE)
+                visit(to);
+        }
+        colour.set(id, BLACK);
+    };
+    for (const id of nodeIds)
+        if (colour.get(id) === WHITE)
+            visit(id);
+    return back;
+}
+const KIND_BY_TYPE = {
+    agent: "spawn",
+    action: "action",
+    human: "human",
+    group: "group",
+    gate: "gate",
+};
+/**
+ * Resolve the order in which a host agent should enact a topology.
+ *
+ * @param ast - A parsed topology. Order does not depend on defaults resolution.
+ * @returns Ordered steps, loop budgets, unreachable nodes, and the orchestrator id.
+ */
+export function resolveOrder(ast) {
+    const byId = new Map(ast.nodes.map((n) => [n.id, n]));
+    const orchestrator = ast.nodes.find((n) => n.type === "orchestrator")?.id ?? null;
+    const gates = ast.nodes.filter((n) => n.type === "gate");
+    const gateIds = new Set(gates.map((g) => g.id));
+    // Rank only what actually participates in the flow graph. Gates are excluded
+    // because they have no edges; the orchestrator because it is the host.
+    const flowIds = new Set(ast.nodes.filter((n) => !gateIds.has(n.id) && n.type !== "orchestrator").map((n) => n.id));
+    // Classify first: rank with only the REAL back-edges removed, so a forward
+    // edge carrying `[max N]` still advances the depth of its target.
+    const backKeys = trueBackEdges(ast.edges, flowIds);
+    const forwardEdges = ast.edges.filter((e) => !backKeys.has(`${e.from} ${e.to}`));
+    const layers = computeLayers(
+    // computeLayers strips `maxIterations` itself, so clear it on the edges we
+    // have already established are forward — otherwise they vanish again.
+    forwardEdges.map((e) => (e.maxIterations ? { ...e, maxIterations: null } : e)), flowIds);
+    // Build the ranked spine, splitting each layer by node kind so a step is
+    // never a mix of "spawn three agents" and "run a shell action".
+    const spine = [];
+    const unreachable = [];
+    for (const layer of layers) {
+        if (layer.depth === -1) {
+            unreachable.push(...layer.nodes);
+            continue;
+        }
+        const grouped = new Map();
+        for (const id of layer.nodes) {
+            const node = byId.get(id);
+            if (!node)
+                continue;
+            const kind = KIND_BY_TYPE[node.type] ?? "spawn";
+            if (!grouped.has(kind))
+                grouped.set(kind, []);
+            grouped.get(kind).push(id);
+        }
+        // Deterministic kind order within a layer: work first, then human gates.
+        for (const kind of ["action", "spawn", "group", "human"]) {
+            const ids = grouped.get(kind);
+            if (ids && ids.length)
+                spine.push({ kind, ids, depth: layer.depth });
+        }
+    }
+    // Splice gates. `after: X` inserts immediately after the step containing X.
+    // `before: Y` inserts immediately before the step containing Y. A gate with
+    // both prefers `after`, since that is when its check can actually run.
+    const withGates = [...spine];
+    // Splice in declaration order, tracking how many gates already landed on each
+    // anchor. Without the offset each new gate inserted at the same index and
+    // pushed its predecessor down, so two gates after the same agent ran in
+    // reverse declaration order.
+    const placedPerAnchor = new Map();
+    // A gate may anchor to ANOTHER gate. Splicing in declaration order meant a
+    // gate whose anchor was declared later found nothing, fell through to "runs
+    // last", and silently skipped past the step it was meant to guard. Order the
+    // gates so every anchor is already placed: repeat until no progress, then
+    // append whatever still cannot resolve.
+    const placedIds = new Set();
+    const pending = [...gates];
+    const ordered = [];
+    for (let pass = 0; pass < gates.length + 1 && pending.length; pass++) {
+        let moved = false;
+        for (let i = 0; i < pending.length;) {
+            const g = pending[i];
+            const anchors = [g.after, g.before].filter((a) => !!a);
+            const waitingOnGate = anchors.some((a) => gateIds.has(a) && !placedIds.has(a));
+            if (waitingOnGate) {
+                i++;
+                continue;
+            }
+            ordered.push(g);
+            placedIds.add(g.id);
+            pending.splice(i, 1);
+            moved = true;
+        }
+        if (!moved)
+            break; // a cycle among gate anchors — append them as-is
+    }
+    ordered.push(...pending);
+    for (const gate of ordered) {
+        let at = -1;
+        if (gate.after) {
+            const i = withGates.findIndex((s) => s.ids.includes(gate.after));
+            if (i >= 0) {
+                const already = placedPerAnchor.get(gate.after) ?? 0;
+                at = i + 1 + already;
+                placedPerAnchor.set(gate.after, already + 1);
+            }
+        }
+        if (at === -1 && gate.before) {
+            const i = withGates.findIndex((s) => s.ids.includes(gate.before));
+            if (i >= 0)
+                at = i;
+        }
+        // A gate anchored to nothing resolvable runs last — visible, not dropped.
+        if (at === -1)
+            at = withGates.length;
+        withGates.splice(at, 0, { kind: "gate", ids: [gate.id], depth: null });
+    }
+    // Classify each multi-node step: parallel fan-out, or exclusive branch?
+    const steps = withGates.map((s, i) => {
+        const base = { index: i + 1, ...s, exclusive: false };
+        if (s.ids.length < 2)
+            return base;
+        const inbound = s.ids.map((id) => ast.edges.filter((e) => e.to === id && !e.isError));
+        // Every id reached ONLY by conditional edges, and every one of those edges
+        // from the same single source → this is one decision, not a fan-out.
+        const allConditional = inbound.every((es) => es.length > 0 && es.every((e) => !!e.condition));
+        const sources = new Set(inbound.flat().map((e) => e.from));
+        if (!allConditional || sources.size !== 1)
+            return base;
+        base.exclusive = true;
+        base.branchOn = s.ids.map((id) => ({
+            id,
+            condition: ast.edges.find((e) => e.to === id && e.condition)?.condition ?? "",
+        }));
+        return base;
+    });
+    const loops = ast.edges
+        .filter((e) => backKeys.has(`${e.from} ${e.to}`))
+        .map((e) => ({
+        from: e.from,
+        to: e.to,
+        condition: e.condition,
+        budget: e.maxIterations ?? null,
+    }));
+    return { steps, loops, unreachable, orchestrator };
+}
+/** All outbound edges from a node, in declaration order. */
+export function edgesFrom(ast, id) {
+    return ast.edges.filter((e) => e.from === id);
+}
+//# sourceMappingURL=order.js.map

package/dist/resolve/order.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"order.js","sourceRoot":"","sources":["../../src/resolve/order.ts"],"names":[],"mappings":"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"}

package/dist/resolve/phase.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The single answer to "where does an agent with no declared `phase` go?"
+ *
+ * THE BUG THIS FIXES
+ * ------------------
+ * Six consumers each picked their own sentinel, so the same topology ordered
+ * an unphased agent differently on every target:
+ *
+ *   claude-code, claude-workflow  →  Number.MAX_SAFE_INTEGER  →  runs LAST
+ *   gemini-cli                    →  999                      →  runs near-last
+ *   openclaw, kiro, mermaid       →  0                        →  runs FIRST
+ *
+ * An agent that runs first on three targets and last on three others is
+ * precisely the failure "write once, deploy to any platform" exists to prevent.
+ * Found by an audit topology run through `agentopology plan`.
+ *
+ * WHY TRAILING, NOT LEADING
+ * -------------------------
+ * `spec/grammar.md` §7 gives `agent.phase` the default "-- (none, unordered)",
+ * so there is no declared answer — a sort simply needs one. Trailing is the
+ * safer reading: an author who phases *some* agents is expressing "these come
+ * first, in this order", and the ones they did not mention should not leap
+ * ahead of them. A stable sort then preserves declaration order among the
+ * unphased, which is the only ordering information they carry.
+ *
+ * When NO agent declares a phase, every agent takes the same sentinel and the
+ * stable sort leaves declaration order intact — the same result all six
+ * sentinels used to give, which is why this went unnoticed.
+ *
+ * @module
+ */
+import type { AgentNode } from "../parser/ast.js";
+/**
+ * Sort key for an agent with no declared `phase`.
+ *
+ * Deliberately `Number.MAX_SAFE_INTEGER` rather than a smaller magic number:
+ * `999` collides with a legitimately declared `phase: 999`, and `0` collides
+ * with `phase: 0`. This one cannot be reached by a real declaration, since
+ * `phase` is parsed with `parseFloat` from a source literal.
+ */
+export declare const UNPHASED: number;
+/**
+ * The ordering value for an agent — its declared `phase`, or {@link UNPHASED}.
+ *
+ * Every consumer that sorts by phase must use this. Sorting by
+ * `agent.phase ?? <anything else>` reintroduces the divergence.
+ *
+ * @param agent - Any agent node.
+ * @returns The numeric sort key.
+ */
+export declare function phaseOf(agent: Pick<AgentNode, "phase">): number;
+/**
+ * Comparator for `Array.prototype.sort`, stable on ties so declaration order
+ * survives among agents sharing a phase.
+ */
+export declare function byPhase(a: Pick<AgentNode, "phase">, b: Pick<AgentNode, "phase">): number;
+//# sourceMappingURL=phase.d.ts.map

package/dist/resolve/phase.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"phase.d.ts","sourceRoot":"","sources":["../../src/resolve/phase.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAElD;;;;;;;GAOG;AACH,eAAO,MAAM,QAAQ,QAA0B,CAAC;AAEhD;;;;;;;;GAQG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,SAAS,EAAE,OAAO,CAAC,GAAG,MAAM,CAE/D;AAED;;;GAGG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,IAAI,CAAC,SAAS,EAAE,OAAO,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,SAAS,EAAE,OAAO,CAAC,GAAG,MAAM,CAExF"}