@intentius/chant 0.10.0 → 0.12.0

package/dist/cli/handlers/graph.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["../../../src/cli/handlers/graph.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD;;;;;GAKG;AACH,wBAAsB,QAAQ,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAOnE"}
+{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["../../../src/cli/handlers/graph.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD;;;;;GAKG;AACH,wBAAsB,QAAQ,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAOnE"}

package/dist/cli/main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":";AAKA,OAAO,EAAmC,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAe9E;;GAEG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CA6IpD"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":";AAKA,OAAO,EAAmC,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAe9E;;GAEG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CAiJpD"}

package/dist/cli/registry.d.ts

@@ -64,6 +64,11 @@ export interface ParsedArgs {
     up?: boolean;
     /** `chant graph --lens blast:<node> --down` — include downstream dependents */
     down?: boolean;
+    /** `chant graph --format layout --node-sizes <json|-|@file>` — painter-measured
+     * node footprints `{id:{w,h}}` so the layout spaces for real card sizes (#509). */
+    nodeSizes?: string;
+    /** `chant graph --format layout --layout-engine dagre|graphviz` (default dagre). */
+    layoutEngine?: string;
     /** `chant lifecycle affected --base <ref>` — base git ref to diff against */
     base?: string;
     /** `chant lifecycle affected --head <ref>` — head git ref (default: working tree) */

package/dist/cli/registry.d.ts.map

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

package/dist/graph-layout.d.ts

@@ -1,39 +1,87 @@
+import type { GraphIR } from "./graph-ir.js";
 /**
  * Layout-position export — node coordinates a custom painter consumes (the
- * rackattack pattern: Graphviz lays out, the painter draws). Graphviz is used
- * for LAYOUT ONLY; its rendering is discarded. See issue #497 / epic #492.
+ * rackattack pattern: an engine lays out, the painter draws). The engine is used
+ * for LAYOUT ONLY; any rendering it can do is discarded. See issue #497 / epic
+ * #492, and #509 for the size-aware redesign.
  *
- * The {@link LayoutEngine} interface exists so a pure-JS engine (elkjs/dagre)
- * can drop in later for a zero-native-dependency path — closing the install gap
- * so a painter can run without `dot`.
+ * The engine takes an **engine-neutral {@link LayoutInput}** — sized nodes plus
+ * edges — not a DOT string, so the painter's real node sizes drive spacing
+ * (without sizes a layout engine packs for tiny default boxes and big cards
+ * collide). Two engines implement it:
+ *
+ * - {@link DagreLayout} (default) — pure JS, size-aware, **no native dependency**.
+ * - {@link GraphvizLayout} — opt-in; shells `dot`. Honours `groups` as clusters.
+ *
+ * Coordinate convention (both engines): **y grows up, origin bottom-left**, as
+ * `dot -Tjson` reports. A painter flips y to read top-to-bottom.
  */
-/** A laid-out position in the engine's coordinate space. */
+/** A laid-out position in the engine's coordinate space (y-up). */
 export interface Point {
     x: number;
     y: number;
 }
-/** Node positions plus the overall canvas size a painter needs. */
+/** Node positions plus the overall canvas size a painter needs. Centres are
+ * y-up (origin bottom-left). `w`/`h` echo the footprint the engine laid out
+ * with, so a painter can route edges to card borders rather than centres. */
 export interface Layout {
     /** Canvas width in the engine's coordinate space. */
     width: number;
     /** Canvas height in the engine's coordinate space. */
     height: number;
-    /** Each node's centre position, ordered by id for deterministic output. */
+    /** Each node's centre position (+ footprint), ordered by id for determinism. */
     nodes: Array<{
         id: string;
+        w?: number;
+        h?: number;
     } & Point>;
 }
-/** Turns DOT into node positions. The painter consumes the result; it never
- * asks the engine to paint. */
+/** A node's painted footprint, in layout units (≈ px / points). */
+export interface NodeSize {
+    w: number;
+    h: number;
+}
+/** Engine-neutral layout input: sized nodes + edges (+ optional groups). */
+export interface LayoutInput {
+    nodes: Array<{
+        id: string;
+    } & NodeSize>;
+    edges: Array<{
+        from: string;
+        to: string;
+    }>;
+    /** Group name → member ids, for cluster-aware engines (graphviz subgraphs). */
+    groups?: Record<string, string[]>;
+}
+/** Turns sized nodes + edges into node positions. The painter consumes the
+ * result; it never asks the engine to paint. */
 export interface LayoutEngine {
     readonly name: string;
-    layout(dot: string): Promise<Layout>;
+    layout(input: LayoutInput): Promise<Layout>;
+}
+/** Graphviz's default node box, in layout units — the fallback for a node the
+ * painter didn't measure, so a size-less call still lays out as it always did. */
+export declare const DEFAULT_NODE_SIZE: NodeSize;
+/** Build engine input from an IR and a painter-measured size map (id → {w,h}).
+ * Nodes absent from the map fall back to {@link DEFAULT_NODE_SIZE}. Pure. */
+export declare function toLayoutInput(ir: GraphIR, sizes?: Record<string, NodeSize>): LayoutInput;
+/**
+ * Layout via dagre — pure JS, size-aware, no native dependency. The default.
+ * Fed nodes/edges in id order so the result is deterministic. dagre's space is
+ * y-down; we flip to y-up so the {@link Layout} contract matches Graphviz.
+ */
+export declare class DagreLayout implements LayoutEngine {
+    readonly name = "dagre";
+    layout(input: LayoutInput): Promise<Layout>;
 }
-/** Layout via `dot -Tjson`. Requires Graphviz (`brew install graphviz`). */
+/** Layout via `dot -Tjson`. Opt-in; requires Graphviz (`brew install graphviz`).
+ * Lays out with real node sizes (`fixedsize`) and honours `groups` as clusters. */
 export declare class GraphvizLayout implements LayoutEngine {
     readonly name = "graphviz";
-    layout(dot: string): Promise<Layout>;
+    layout(input: LayoutInput): Promise<Layout>;
 }
+/** Resolve a layout engine by name. Defaults to dagre (no native dependency). */
+export declare function getLayoutEngine(name?: string): LayoutEngine;
 /** Parse `dot -Tjson` output into a {@link Layout}. Pure; exported for testing. */
 export declare function parseDotJson(json: string): Layout;
 //# sourceMappingURL=graph-layout.d.ts.map

package/dist/graph-layout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph-layout.d.ts","sourceRoot":"","sources":["../src/graph-layout.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AAEH,4DAA4D;AAC5D,MAAM,WAAW,KAAK;IACpB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED,mEAAmE;AACnE,MAAM,WAAW,MAAM;IACrB,qDAAqD;IACrD,KAAK,EAAE,MAAM,CAAC;IACd,sDAAsD;IACtD,MAAM,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,KAAK,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,GAAG,KAAK,CAAC,CAAC;CACtC;AAED;+BAC+B;AAC/B,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACtC;AAED,4EAA4E;AAC5E,qBAAa,cAAe,YAAW,YAAY;IACjD,QAAQ,CAAC,IAAI,cAAc;IAErB,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAG3C;AAsCD,mFAAmF;AACnF,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAiBjD"}
+{"version":3,"file":"graph-layout.d.ts","sourceRoot":"","sources":["../src/graph-layout.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C;;;;;;;;;;;;;;;;GAgBG;AAEH,mEAAmE;AACnE,MAAM,WAAW,KAAK;IACpB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED;;6EAE6E;AAC7E,MAAM,WAAW,MAAM;IACrB,qDAAqD;IACrD,KAAK,EAAE,MAAM,CAAC;IACd,sDAAsD;IACtD,MAAM,EAAE,MAAM,CAAC;IACf,gFAAgF;IAChF,KAAK,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,CAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,KAAK,CAAC,CAAC;CAC9D;AAED,mEAAmE;AACnE,MAAM,WAAW,QAAQ;IACvB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED,4EAA4E;AAC5E,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,GAAG,QAAQ,CAAC,CAAC;IACxC,KAAK,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC3C,+EAA+E;IAC/E,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;CACnC;AAED;gDACgD;AAChD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC7C;AAED;kFACkF;AAClF,eAAO,MAAM,iBAAiB,EAAE,QAA2B,CAAC;AAM5D;6EAC6E;AAC7E,wBAAgB,aAAa,CAAC,EAAE,EAAE,OAAO,EAAE,KAAK,GAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAM,GAAG,WAAW,CAM5F;AAiBD;;;;GAIG;AACH,qBAAa,WAAY,YAAW,YAAY;IAC9C,QAAQ,CAAC,IAAI,WAAW;IAElB,MAAM,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC;CA0BlD;AAED;mFACmF;AACnF,qBAAa,cAAe,YAAW,YAAY;IACjD,QAAQ,CAAC,IAAI,cAAc;IAErB,MAAM,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC;CAGlD;AAED,iFAAiF;AACjF,wBAAgB,eAAe,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,YAAY,CAM3D;AA0ED,mFAAmF;AACnF,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAqBjD"}

package/dist/reconcile.d.ts

@@ -8,13 +8,15 @@
  * cap + a pluggable check runner).
  *
  * A "warden" (e.g. github-warden) builds its provider-specific resource diffing,
- * live-state types, and domain guardrails on top of this. It complements
+ * live-state types, and domain guardrails on top of this, and drives them with
+ * the generic `runReconcile` loop + `Cycle` interface (below). It complements
  * chant's `ownership.ts` marker contract: ownership markers make a `delete`
  * precise; this module decides *which* entries are creates / updates / deletes
  * in the first place.
  *
- * Consumed as `@intentius/chant/reconcile`. Pure and deterministic: no I/O,
- * no clock.
+ * Consumed as `@intentius/chant/reconcile`. The diff and guardrail primitives
+ * are pure and clock-free; `runReconcile` is the orchestration loop and is the
+ * only part that drives I/O (through the provider's `Cycle` implementations).
  */
 /** A single field-level change: what the old value was and what it will become. */
 export interface FieldChange {
@@ -144,4 +146,110 @@ export declare function removalDeltaCap(changeSet: ChangeSet, opts?: RemovalDelt
  * caller composes provider-specific checks (e.g. an admin floor) as closures.
  */
 export declare function runGuardrailChecks(changeSet: ChangeSet, checks: GuardrailCheck[]): GuardrailResult;
+/** Controls how a cycle tracks its API usage against a shared request budget. */
+export interface RateBudget {
+    /** Remaining request capacity for this run. */
+    readonly remaining: number;
+    /** True once `remaining` has reached zero. */
+    readonly exhausted: boolean;
+    /** Decrement by `n` (default 1). Throws `BudgetExhaustedError` if exhausted. */
+    use(n?: number): void;
+}
+/** Thrown when a cycle or apply step attempts to use an exhausted budget. */
+export declare class BudgetExhaustedError extends Error {
+    constructor(message?: string);
+}
+/**
+ * A reconcile cycle: fetch live state for one resource domain, build desired
+ * state from config, and apply a single `ChangeSetEntry` back to the provider.
+ * Generic over the provider client (`TClient`), the per-scope config slice
+ * (`TConfig`), the live snapshot (`TLive`), and caller-supplied scope (`TScope`).
+ *
+ * `scopeId` is the current scope being iterated (e.g. an org login or group
+ * path); cycles use it — not `TScope` — for provider API paths, so a multi-scope
+ * config targets the right scope. Every network call must charge `budget`.
+ */
+export interface Cycle<TClient, TConfig, TLive, TScope = unknown> {
+    /** Human-readable name, e.g. "branch-protection". */
+    name: string;
+    fetchLive(client: TClient, scopeId: string, scope: TScope, budget: RateBudget): Promise<TLive>;
+    buildDesired(config: TConfig, scopeId: string, scope: TScope): TConfig;
+    apply(client: TClient, entry: ChangeSetEntry, scopeId: string, scope: TScope, budget: RateBudget): Promise<void>;
+}
+/** Per-cycle outcome recorded in the run result. */
+export interface CycleResult {
+    name: string;
+    /** Scope id this result is for (e.g. an org login). */
+    org: string;
+    counts: {
+        create: number;
+        update: number;
+        delete: number;
+    };
+    guardrails: GuardrailResult;
+    applied: ChangeSetEntry[];
+    failed: Array<{
+        entry: ChangeSetEntry;
+        error: string;
+    }>;
+    plan: string;
+    guardrailBlocked: boolean;
+}
+/** A cycle that errored during `fetchLive`/`buildDesired` (non-budget error). */
+export interface CycleError {
+    name: string;
+    org: string;
+    stage: "fetchLive" | "buildDesired";
+    error: string;
+}
+/** Work that could not complete due to budget exhaustion. */
+export interface DeferredWork {
+    skippedCycles: string[];
+    skippedEntries: Array<{
+        cycleName: string;
+        entry: ChangeSetEntry;
+    }>;
+}
+/** Structured result from a single `runReconcile` call. */
+export interface ReconcileResult {
+    mode: "dry-run" | "apply";
+    completed: boolean;
+    cycles: CycleResult[];
+    errored: CycleError[];
+    deferred: DeferredWork;
+    budgetRemaining: number;
+}
+/** Options for `runReconcile`. */
+export interface RunReconcileOptions<TClient, TConfig, TLive, TScope = unknown> {
+    /** Per-scope configs to reconcile, keyed by scope id (e.g. org login). */
+    scopes: Record<string, TConfig>;
+    /** Authed provider client, passed to every cycle. */
+    client: TClient;
+    /** Cycles to run; each runs against every scope in `scopes`. */
+    cycles: Array<Cycle<TClient, TConfig, TLive, TScope>>;
+    /** Scope forwarded to each cycle (filter/cursor); does not vary by scopeId. */
+    scope?: TScope;
+    /** "dry-run" (default) computes + reports; "apply" mutates after guardrails. */
+    mode?: "dry-run" | "apply";
+    /** Provider diff: turn (desired, live) into a ChangeSet for one scope. */
+    diff: (scopeId: string, desired: TConfig, live: TLive, opts: DiffOptions) => ChangeSet;
+    /** Guardrail check over the change set + live. Defaults to always-ok. */
+    guardrails?: (changeSet: ChangeSet, live: TLive) => GuardrailResult;
+    /** Diff options forwarded to `diff`. */
+    diffOptions?: DiffOptions;
+    /** Apply even when guardrails trip. Default false. */
+    allowGuardrailOverride?: boolean;
+    /** Max requests for the run (across all cycles). Default 1000. */
+    requestBudget?: number;
+}
+/**
+ * Run the reconcile loop. For each scope in `scopes` and each cycle:
+ *   1. fetchLive  2. buildDesired  3. diff  4. guardrails
+ *   5a. dry-run: record the plan  5b. apply: apply each entry (if guardrails pass)
+ *
+ * Budget-aware (stops cleanly + records deferred work on exhaustion) and
+ * fault-tolerant (a cycle that errors is recorded and the run continues).
+ * Returns a structured `ReconcileResult`.
+ */
+export declare function runReconcile<TClient, TConfig, TLive, TScope = unknown>(opts: RunReconcileOptions<TClient, TConfig, TLive, TScope>): Promise<ReconcileResult>;
 //# sourceMappingURL=reconcile.d.ts.map

package/dist/reconcile.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reconcile.d.ts","sourceRoot":"","sources":["../src/reconcile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAMH,mFAAmF;AACnF,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,oDAAoD;AACpD,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAExD,wCAAwC;AACxC,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,UAAU,CAAC;IACjB,iFAAiF;IACjF,YAAY,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ,6DAA6D;IAC7D,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,+DAA+D;IAC/D,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,wDAAwD;IACxD,MAAM,CAAC,EAAE,WAAW,EAAE,CAAC;CACxB;AAED,yEAAyE;AACzE,MAAM,WAAW,SAAS;IACxB,6EAA6E;IAC7E,GAAG,EAAE,MAAM,CAAC;IACZ,6CAA6C;IAC7C,OAAO,EAAE,cAAc,EAAE,CAAC;CAC3B;AAED,0CAA0C;AAC1C,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IAEzD;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAMD,2EAA2E;AAC3E,wBAAgB,SAAS,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,OAAO,CAKzD;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CACxB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,IAAI,CAAC,EAAE,MAAM,EAAE,GACd,WAAW,EAAE,CAUf;AAMD,6CAA6C;AAC7C,MAAM,WAAW,oBAAoB,CAAC,CAAC,EAAE,CAAC;IACxC,gDAAgD;IAChD,YAAY,EAAE,MAAM,CAAC;IACrB,yEAAyE;IACzE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IACxB,0CAA0C;IAC1C,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IACrB,mEAAmE;IACnE,aAAa,EAAE,CAAC,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,KAAK,WAAW,EAAE,CAAC;IACtD,uEAAuE;IACvE,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,KAAK,OAAO,CAAC;IACnD,wEAAwE;IACxE,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC;IAC5D,IAAI,EAAE,WAAW,CAAC;IAClB,GAAG,EAAE,cAAc,EAAE,CAAC;CACvB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,oBAAoB,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI,CA6C7E;AAMD,qCAAqC;AACrC,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,SAAS,GAAG,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,CAI5E;AAED,4DAA4D;AAC5D,wBAAgB,eAAe,CAAC,EAAE,EAAE,SAAS,GAAG,MAAM,CAuBrD;AAaD,gEAAgE;AAChE,MAAM,WAAW,mBAAmB;IAClC,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,mCAAmC;AACnC,MAAM,MAAM,eAAe,GAAG;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,WAAW,EAAE,mBAAmB,EAAE,CAAA;CAAE,CAAC;AAE/F,0FAA0F;AAC1F,MAAM,MAAM,cAAc,GAAG,CAAC,QAAQ,EAAE,SAAS,KAAK,mBAAmB,GAAG,IAAI,CAAC;AAEjF,oCAAoC;AACpC,MAAM,WAAW,sBAAsB;IACrC,gGAAgG;IAChG,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,SAAS,GAAG,SAAS,CAyC9D;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,SAAS,EACpB,IAAI,GAAE,sBAA2B,GAChC,mBAAmB,GAAG,IAAI,CAgB5B;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,SAAS,EAAE,MAAM,EAAE,cAAc,EAAE,GAAG,eAAe,CAQlG"}
+{"version":3,"file":"reconcile.d.ts","sourceRoot":"","sources":["../src/reconcile.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Declarative infrastructure-as-code toolkit — TypeScript on Node.js",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -65,6 +65,7 @@
     "prepack": "npm run build"
   },
   "dependencies": {
+    "@dagrejs/dagre": "^3.0.0",
     "fflate": "^0.8.2",
     "picomatch": "^4.0.3",
     "tsx": "^4.0.0",

package/src/cli/handlers/graph.test.ts

@@ -18,14 +18,12 @@ vi.mock("../commands/lint", () => ({
   lintCommand: () => lintMock(),
 }));
 
-// Avoid shelling out to graphviz in tests; the format dispatch is what matters.
+// Avoid running a real layout engine in tests; the format dispatch + size/engine
+// plumbing is what matters here (engines have their own unit tests).
 const layoutMock = vi.fn();
 vi.mock("../../graph-layout", () => ({
-  GraphvizLayout: class {
-    layout() {
-      return layoutMock();
-    }
-  },
+  toLayoutInput: (ir: { nodes: { id: string }[] }, sizes: unknown) => ({ ir, sizes }),
+  getLayoutEngine: (name?: string) => ({ name: name ?? "dagre", layout: (input: unknown) => layoutMock(input) }),
 }));
 
 const { runGraph } = await import("./graph");

package/src/cli/handlers/graph.ts

@@ -7,8 +7,9 @@ import { applyDetail, type DetailLevel } from "../../graph-detail";
 import { applyLens, parseLens } from "../../graph-lens";
 import { toMermaid } from "../../graph-mermaid";
 import { toDot } from "../../graph-dot";
-import { GraphvizLayout } from "../../graph-layout";
+import { getLayoutEngine, toLayoutInput, type NodeSize } from "../../graph-layout";
 import { lintCommand } from "../commands/lint";
+import { readFileSync } from "node:fs";
 import { formatError, formatWarning, formatBold } from "../format";
 import type { CommandContext } from "../registry";
 
@@ -30,9 +31,11 @@ export async function runGraph(ctx: CommandContext): Promise<number> {
 /**
  * `chant graph --format ir|mermaid|dot|layout` — build the graph IR (honouring
  * `--detail`) and emit it as JSON, a Mermaid flowchart, Graphviz DOT, or node
- * positions from a layout engine. Lint-gated: the IR represents valid infra, so
- * we refuse to emit for source that does not pass lint. Non-zero on discovery
- * errors, or on a missing `dot` for `--format layout`.
+ * positions from a layout engine. `layout` takes optional painter-measured
+ * `--node-sizes` so spacing fits real node footprints, and defaults to the dagre
+ * engine (no native dependency); `--layout-engine graphviz` opts into `dot`.
+ * Lint-gated: the IR represents valid infra, so we refuse to emit for source that
+ * does not pass lint. Non-zero on discovery errors or a layout-engine failure.
  */
 async function runGraphView(
   ctx: CommandContext,
@@ -86,7 +89,9 @@ async function runGraphView(
       return 0;
     case "layout":
       try {
-        const layout = await new GraphvizLayout().layout(toDot(ir));
+        const sizes = readNodeSizes(ctx.args.nodeSizes);
+        const engine = getLayoutEngine(ctx.args.layoutEngine);
+        const layout = await engine.layout(toLayoutInput(ir, sizes));
         console.log(JSON.stringify(layout, null, 2));
         return 0;
       } catch (err) {
@@ -100,6 +105,40 @@ async function runGraphView(
   }
 }
 
+/**
+ * Resolve the `--node-sizes` value into a `{ id: {w, h} }` map. The spec is one
+ * of: inline JSON, `-` (read JSON from stdin, to dodge arg-length limits), or
+ * `@path` (read from a file). Empty/absent → no sizes (engine uses defaults).
+ * Throws on malformed JSON so a typo fails loudly rather than mis-laying out.
+ */
+function readNodeSizes(spec?: string): Record<string, NodeSize> {
+  if (!spec) return {};
+  let raw: string;
+  if (spec === "-") raw = readFileSync(0, "utf8");
+  else if (spec.startsWith("@")) raw = readFileSync(spec.slice(1), "utf8");
+  else raw = spec;
+  raw = raw.trim();
+  if (!raw) return {};
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`--node-sizes is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  if (typeof parsed !== "object" || parsed === null) {
+    throw new Error("--node-sizes must be a JSON object mapping node id → {w, h}");
+  }
+  const out: Record<string, NodeSize> = {};
+  for (const [id, val] of Object.entries(parsed as Record<string, unknown>)) {
+    const v = val as { w?: unknown; h?: unknown };
+    if (typeof v?.w === "number" && typeof v?.h === "number" && v.w > 0 && v.h > 0) {
+      out[id] = { w: v.w, h: v.h };
+    }
+  }
+  return out;
+}
+
 async function runOpGraph(): Promise<number> {
   const { ops, errors } = await discoverOps();
   for (const err of errors) console.error(formatError({ message: err }));

package/src/cli/main.ts

@@ -134,6 +134,10 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.up = true;
     } else if (arg === "--down") {
       result.down = true;
+    } else if (arg === "--node-sizes") {
+      result.nodeSizes = args[++i];
+    } else if (arg === "--layout-engine") {
+      result.layoutEngine = args[++i];
     } else if (arg === "--base") {
       result.base = args[++i];
     } else if (arg === "--head") {
@@ -200,8 +204,10 @@ Ops:
 
   graph                 Show Op dependency graph (--stacks for cross-stack order,
                         --format ir|mermaid|dot|layout for the lint-gated graph IR,
-                        a Mermaid flowchart, Graphviz DOT, or node positions
-                        (layout needs graphviz);
+                        a Mermaid flowchart, Graphviz DOT, or node positions;
+                        layout uses dagre by default (no native dep) — pass
+                        --node-sizes <json|-|@file> for size-aware spacing,
+                        --layout-engine graphviz to use dot instead;
                         --detail 0..3: stacks|composites|declarables|attributes;
                         --lens lexicon:<n>|stack:<n>|blast:<node> (--up/--down))
 

package/src/cli/registry.ts

@@ -65,6 +65,11 @@ export interface ParsedArgs {
   up?: boolean;
   /** `chant graph --lens blast:<node> --down` — include downstream dependents */
   down?: boolean;
+  /** `chant graph --format layout --node-sizes <json|-|@file>` — painter-measured
+   * node footprints `{id:{w,h}}` so the layout spaces for real card sizes (#509). */
+  nodeSizes?: string;
+  /** `chant graph --format layout --layout-engine dagre|graphviz` (default dagre). */
+  layoutEngine?: string;
   /** `chant lifecycle affected --base <ref>` — base git ref to diff against */
   base?: string;
   /** `chant lifecycle affected --head <ref>` — head git ref (default: working tree) */

package/src/graph-layout.test.ts

@@ -0,0 +1,131 @@
+import { describe, it, expect } from "vitest";
+import {
+  toLayoutInput,
+  DagreLayout,
+  GraphvizLayout,
+  getLayoutEngine,
+  parseDotJson,
+  DEFAULT_NODE_SIZE,
+  type LayoutInput,
+} from "./graph-layout";
+import type { GraphIR } from "./graph-ir";
+
+const ir: GraphIR = {
+  nodes: [
+    { id: "vpc", kind: "Vpc", lexicon: "aws", attrs: {} },
+    { id: "subnet", kind: "Subnet", lexicon: "aws", attrs: {} },
+  ],
+  edges: [{ from: "subnet", to: "vpc", kind: "ref", viaAttr: "VpcId" }],
+  groups: { byLexicon: { aws: ["vpc", "subnet"] } },
+};
+
+describe("toLayoutInput", () => {
+  it("maps IR nodes/edges and carries groups", () => {
+    const input = toLayoutInput(ir, { vpc: { w: 180, h: 60 }, subnet: { w: 180, h: 76 } });
+    expect(input.nodes).toEqual([
+      { id: "vpc", w: 180, h: 60 },
+      { id: "subnet", w: 180, h: 76 },
+    ]);
+    expect(input.edges).toEqual([{ from: "subnet", to: "vpc" }]);
+    expect(input.groups).toEqual({ aws: ["vpc", "subnet"] });
+  });
+
+  it("falls back to the default box for unmeasured nodes", () => {
+    const input = toLayoutInput(ir);
+    expect(input.nodes.every((n) => n.w === DEFAULT_NODE_SIZE.w && n.h === DEFAULT_NODE_SIZE.h)).toBe(true);
+  });
+});
+
+describe("getLayoutEngine", () => {
+  it("defaults to dagre (no native dependency)", () => {
+    expect(getLayoutEngine().name).toBe("dagre");
+    expect(getLayoutEngine("dagre").name).toBe("dagre");
+  });
+  it("returns graphviz on request", () => {
+    expect(getLayoutEngine("graphviz").name).toBe("graphviz");
+  });
+  it("throws on an unknown engine", () => {
+    expect(() => getLayoutEngine("elk")).toThrow(/unknown layout engine/i);
+  });
+});
+
+describe("DagreLayout", () => {
+  const input: LayoutInput = {
+    nodes: [
+      { id: "vpc", w: 180, h: 60 },
+      { id: "subnetA", w: 180, h: 76 },
+      { id: "subnetB", w: 180, h: 76 },
+    ],
+    edges: [
+      { from: "subnetA", to: "vpc" },
+      { from: "subnetB", to: "vpc" },
+    ],
+  };
+
+  it("lays out with no native dependency and echoes sizes", async () => {
+    const layout = await new DagreLayout().layout(input);
+    expect(layout.nodes.map((n) => n.id)).toEqual(["subnetA", "subnetB", "vpc"]);
+    expect(layout.width).toBeGreaterThan(0);
+    expect(layout.nodes.find((n) => n.id === "vpc")).toMatchObject({ w: 180, h: 60 });
+  });
+
+  it("spaces sized cards so none overlap", async () => {
+    const layout = await new DagreLayout().layout(input);
+    const r = layout.nodes.map((n) => ({
+      id: n.id,
+      x0: n.x - (n.w ?? 0) / 2,
+      x1: n.x + (n.w ?? 0) / 2,
+      y0: n.y - (n.h ?? 0) / 2,
+      y1: n.y + (n.h ?? 0) / 2,
+    }));
+    for (let i = 0; i < r.length; i++) {
+      for (let j = i + 1; j < r.length; j++) {
+        const xOverlap = Math.min(r[i].x1, r[j].x1) - Math.max(r[i].x0, r[j].x0);
+        const yOverlap = Math.min(r[i].y1, r[j].y1) - Math.max(r[i].y0, r[j].y0);
+        expect(xOverlap > 0 && yOverlap > 0).toBe(false);
+      }
+    }
+  });
+
+  it("emits y-up coordinates matching graphviz (edge from drawn above to)", async () => {
+    // Edges are subnet → vpc (consumer → producer). rankdir=TB draws the tail
+    // above the head, so subnets sit above vpc — same as `dot`. In y-up space
+    // that means subnets have the larger y. (Verified against GraphvizLayout.)
+    const layout = await new DagreLayout().layout(input);
+    const vpc = layout.nodes.find((n) => n.id === "vpc")!;
+    const subnetA = layout.nodes.find((n) => n.id === "subnetA")!;
+    expect(subnetA.y).toBeGreaterThan(vpc.y);
+  });
+
+  it("is deterministic", async () => {
+    const a = await new DagreLayout().layout(input);
+    const b = await new DagreLayout().layout(input);
+    expect(a).toEqual(b);
+  });
+});
+
+describe("parseDotJson", () => {
+  it("reads bounds, positions, and echoes node size in points", () => {
+    const json = JSON.stringify({
+      bb: "0,0,200,100",
+      objects: [
+        { name: "b", pos: "50,80", width: "2.5", height: "0.5" },
+        { name: "a", pos: "50,20" },
+      ],
+    });
+    const layout = parseDotJson(json);
+    expect(layout).toMatchObject({ width: 200, height: 100 });
+    expect(layout.nodes.map((n) => n.id)).toEqual(["a", "b"]); // sorted
+    expect(layout.nodes.find((n) => n.id === "b")).toMatchObject({ x: 50, y: 80, w: 180, h: 36 });
+  });
+
+  it("rejects zero bounds", () => {
+    expect(() => parseDotJson(JSON.stringify({ bb: "0,0,0,0", objects: [] }))).toThrow(/zero graph bounds/);
+  });
+});
+
+describe("GraphvizLayout", () => {
+  it("exposes the graphviz engine name", () => {
+    expect(new GraphvizLayout().name).toBe("graphviz");
+  });
+});

package/src/reconcile.test.ts

@@ -222,3 +222,151 @@ describe("runGuardrailChecks", () => {
     expect(runGuardrailChecks(cs, [() => null])).toEqual({ ok: true });
   });
 });
+
+// ---------------------------------------------------------------------------
+// Reconcile runner (fake provider — proves provider-agnosticism)
+// ---------------------------------------------------------------------------
+
+import { runReconcile, BudgetExhaustedError } from "./reconcile";
+import type { Cycle } from "./reconcile";
+
+interface FakeClient {
+  calls: string[];
+}
+interface FakeConfig {
+  create?: number;
+}
+type FakeLive = Record<string, never>;
+
+function fakeCycle(
+  name: string,
+  over: Partial<Cycle<FakeClient, FakeConfig, FakeLive>> = {},
+): Cycle<FakeClient, FakeConfig, FakeLive> {
+  return {
+    name,
+    async fetchLive(client, scopeId, _scope, budget) {
+      budget.use(1);
+      client.calls.push(`fetch:${name}@${scopeId}`);
+      return {};
+    },
+    buildDesired(config) {
+      return config;
+    },
+    async apply(client, entry, _scopeId, _scope, budget) {
+      budget.use(1);
+      client.calls.push(`apply:${entry.key}`);
+    },
+    ...over,
+  };
+}
+
+// Injected diff: emit N create entries from config.create.
+const fakeDiff = (scopeId: string, desired: FakeConfig): ChangeSet => ({
+  org: scopeId,
+  entries: Array.from({ length: desired.create ?? 0 }, (_, i) => ({
+    kind: "create" as const,
+    resourceType: "thing",
+    key: `k${i}`,
+  })),
+});
+
+describe("runReconcile (generic)", () => {
+  test("dry-run reports the plan and mutates nothing", async () => {
+    const client: FakeClient = { calls: [] };
+    const result = await runReconcile<FakeClient, FakeConfig, FakeLive>({
+      client,
+      scopes: { acme: { create: 3 } },
+      cycles: [fakeCycle("c1")],
+      diff: fakeDiff,
+      mode: "dry-run",
+    });
+    expect(result.mode).toBe("dry-run");
+    expect(result.completed).toBe(true);
+    expect(result.cycles[0]!.counts.create).toBe(3);
+    expect(result.cycles[0]!.applied).toHaveLength(0);
+    expect(client.calls.filter((c) => c.startsWith("apply:"))).toHaveLength(0);
+  });
+
+  test("apply applies each entry across multiple scopes", async () => {
+    const client: FakeClient = { calls: [] };
+    const result = await runReconcile<FakeClient, FakeConfig, FakeLive>({
+      client,
+      scopes: { acme: { create: 2 }, beta: { create: 1 } },
+      cycles: [fakeCycle("c1")],
+      diff: fakeDiff,
+      mode: "apply",
+    });
+    expect(result.completed).toBe(true);
+    expect(result.cycles.flatMap((c) => c.applied)).toHaveLength(3);
+    expect(client.calls.filter((c) => c.startsWith("apply:"))).toHaveLength(3);
+  });
+
+  test("guardrails block the apply unless overridden", async () => {
+    const client: FakeClient = { calls: [] };
+    const opts = {
+      client,
+      scopes: { acme: { create: 1 } },
+      cycles: [fakeCycle("c1")],
+      diff: fakeDiff,
+      mode: "apply" as const,
+      guardrails: () => ({ ok: false as const, diagnostics: [{ guardrail: "x", message: "no" }] }),
+    };
+    const blocked = await runReconcile<FakeClient, FakeConfig, FakeLive>(opts);
+    expect(blocked.cycles[0]!.guardrailBlocked).toBe(true);
+    expect(blocked.cycles[0]!.applied).toHaveLength(0);
+
+    const overridden = await runReconcile<FakeClient, FakeConfig, FakeLive>({ ...opts, allowGuardrailOverride: true });
+    expect(overridden.cycles[0]!.guardrailBlocked).toBe(false);
+    expect(overridden.cycles[0]!.applied).toHaveLength(1);
+  });
+
+  test("records deferred work when the budget is exhausted", async () => {
+    const client: FakeClient = { calls: [] };
+    const result = await runReconcile<FakeClient, FakeConfig, FakeLive>({
+      client,
+      scopes: { acme: { create: 0 }, beta: { create: 0 } },
+      cycles: [fakeCycle("c1"), fakeCycle("c2")],
+      diff: fakeDiff,
+      requestBudget: 1, // only the first fetchLive fits
+    });
+    expect(result.completed).toBe(false);
+    expect(result.deferred.skippedCycles.length).toBeGreaterThan(0);
+  });
+
+  test("an errored fetchLive is recorded and the run continues", async () => {
+    const client: FakeClient = { calls: [] };
+    const boom = fakeCycle("boom", {
+      async fetchLive() {
+        throw new Error("kaboom");
+      },
+    });
+    const result = await runReconcile<FakeClient, FakeConfig, FakeLive>({
+      client,
+      scopes: { acme: { create: 1 } },
+      cycles: [boom, fakeCycle("ok")],
+      diff: fakeDiff,
+    });
+    expect(result.errored).toHaveLength(1);
+    expect(result.errored[0]!.name).toBe("boom");
+    expect(result.cycles.some((c) => c.name === "ok")).toBe(true); // ran past the error
+  });
+
+  test("a budget-exhausted throw mid-fetch is deferred, not errored", async () => {
+    const client: FakeClient = { calls: [] };
+    const greedy = fakeCycle("greedy", {
+      async fetchLive(_c, _s, _scope, budget) {
+        budget.use(1);
+        throw new BudgetExhaustedError();
+      },
+    });
+    const result = await runReconcile<FakeClient, FakeConfig, FakeLive>({
+      client,
+      scopes: { acme: { create: 0 } },
+      cycles: [greedy],
+      diff: fakeDiff,
+      requestBudget: 5,
+    });
+    expect(result.errored).toHaveLength(0);
+    expect(result.deferred.skippedCycles).toContain("greedy@acme");
+  });
+});

package/src/reconcile.ts

@@ -8,13 +8,15 @@
  * cap + a pluggable check runner).
  *
  * A "warden" (e.g. github-warden) builds its provider-specific resource diffing,
- * live-state types, and domain guardrails on top of this. It complements
+ * live-state types, and domain guardrails on top of this, and drives them with
+ * the generic `runReconcile` loop + `Cycle` interface (below). It complements
  * chant's `ownership.ts` marker contract: ownership markers make a `delete`
  * precise; this module decides *which* entries are creates / updates / deletes
  * in the first place.
  *
- * Consumed as `@intentius/chant/reconcile`. Pure and deterministic: no I/O,
- * no clock.
+ * Consumed as `@intentius/chant/reconcile`. The diff and guardrail primitives
+ * are pure and clock-free; `runReconcile` is the orchestration loop and is the
+ * only part that drives I/O (through the provider's `Cycle` implementations).
  */
 
 // ---------------------------------------------------------------------------
@@ -344,3 +346,247 @@ export function runGuardrailChecks(changeSet: ChangeSet, checks: GuardrailCheck[
   }
   return diagnostics.length > 0 ? { ok: false, diagnostics } : { ok: true };
 }
+
+// ---------------------------------------------------------------------------
+// Reconcile runner (generic over provider client / config / live / scope)
+// ---------------------------------------------------------------------------
+
+/** Controls how a cycle tracks its API usage against a shared request budget. */
+export interface RateBudget {
+  /** Remaining request capacity for this run. */
+  readonly remaining: number;
+  /** True once `remaining` has reached zero. */
+  readonly exhausted: boolean;
+  /** Decrement by `n` (default 1). Throws `BudgetExhaustedError` if exhausted. */
+  use(n?: number): void;
+}
+
+/** Thrown when a cycle or apply step attempts to use an exhausted budget. */
+export class BudgetExhaustedError extends Error {
+  constructor(message = "rate budget exhausted") {
+    super(message);
+    this.name = "BudgetExhaustedError";
+  }
+}
+
+class MutableRateBudget implements RateBudget {
+  private _remaining: number;
+  constructor(initial: number) {
+    this._remaining = initial;
+  }
+  get remaining(): number {
+    return this._remaining;
+  }
+  get exhausted(): boolean {
+    return this._remaining <= 0;
+  }
+  use(n = 1): void {
+    if (this.exhausted) throw new BudgetExhaustedError();
+    this._remaining = Math.max(0, this._remaining - n);
+  }
+}
+
+/**
+ * A reconcile cycle: fetch live state for one resource domain, build desired
+ * state from config, and apply a single `ChangeSetEntry` back to the provider.
+ * Generic over the provider client (`TClient`), the per-scope config slice
+ * (`TConfig`), the live snapshot (`TLive`), and caller-supplied scope (`TScope`).
+ *
+ * `scopeId` is the current scope being iterated (e.g. an org login or group
+ * path); cycles use it — not `TScope` — for provider API paths, so a multi-scope
+ * config targets the right scope. Every network call must charge `budget`.
+ */
+export interface Cycle<TClient, TConfig, TLive, TScope = unknown> {
+  /** Human-readable name, e.g. "branch-protection". */
+  name: string;
+  fetchLive(client: TClient, scopeId: string, scope: TScope, budget: RateBudget): Promise<TLive>;
+  buildDesired(config: TConfig, scopeId: string, scope: TScope): TConfig;
+  apply(
+    client: TClient,
+    entry: ChangeSetEntry,
+    scopeId: string,
+    scope: TScope,
+    budget: RateBudget,
+  ): Promise<void>;
+}
+
+/** Per-cycle outcome recorded in the run result. */
+export interface CycleResult {
+  name: string;
+  /** Scope id this result is for (e.g. an org login). */
+  org: string;
+  counts: { create: number; update: number; delete: number };
+  guardrails: GuardrailResult;
+  applied: ChangeSetEntry[];
+  failed: Array<{ entry: ChangeSetEntry; error: string }>;
+  plan: string;
+  guardrailBlocked: boolean;
+}
+
+/** A cycle that errored during `fetchLive`/`buildDesired` (non-budget error). */
+export interface CycleError {
+  name: string;
+  org: string;
+  stage: "fetchLive" | "buildDesired";
+  error: string;
+}
+
+/** Work that could not complete due to budget exhaustion. */
+export interface DeferredWork {
+  skippedCycles: string[];
+  skippedEntries: Array<{ cycleName: string; entry: ChangeSetEntry }>;
+}
+
+/** Structured result from a single `runReconcile` call. */
+export interface ReconcileResult {
+  mode: "dry-run" | "apply";
+  completed: boolean;
+  cycles: CycleResult[];
+  errored: CycleError[];
+  deferred: DeferredWork;
+  budgetRemaining: number;
+}
+
+/** Options for `runReconcile`. */
+export interface RunReconcileOptions<TClient, TConfig, TLive, TScope = unknown> {
+  /** Per-scope configs to reconcile, keyed by scope id (e.g. org login). */
+  scopes: Record<string, TConfig>;
+  /** Authed provider client, passed to every cycle. */
+  client: TClient;
+  /** Cycles to run; each runs against every scope in `scopes`. */
+  cycles: Array<Cycle<TClient, TConfig, TLive, TScope>>;
+  /** Scope forwarded to each cycle (filter/cursor); does not vary by scopeId. */
+  scope?: TScope;
+  /** "dry-run" (default) computes + reports; "apply" mutates after guardrails. */
+  mode?: "dry-run" | "apply";
+  /** Provider diff: turn (desired, live) into a ChangeSet for one scope. */
+  diff: (scopeId: string, desired: TConfig, live: TLive, opts: DiffOptions) => ChangeSet;
+  /** Guardrail check over the change set + live. Defaults to always-ok. */
+  guardrails?: (changeSet: ChangeSet, live: TLive) => GuardrailResult;
+  /** Diff options forwarded to `diff`. */
+  diffOptions?: DiffOptions;
+  /** Apply even when guardrails trip. Default false. */
+  allowGuardrailOverride?: boolean;
+  /** Max requests for the run (across all cycles). Default 1000. */
+  requestBudget?: number;
+}
+
+function errMsg(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+/**
+ * Run the reconcile loop. For each scope in `scopes` and each cycle:
+ *   1. fetchLive  2. buildDesired  3. diff  4. guardrails
+ *   5a. dry-run: record the plan  5b. apply: apply each entry (if guardrails pass)
+ *
+ * Budget-aware (stops cleanly + records deferred work on exhaustion) and
+ * fault-tolerant (a cycle that errors is recorded and the run continues).
+ * Returns a structured `ReconcileResult`.
+ */
+export async function runReconcile<TClient, TConfig, TLive, TScope = unknown>(
+  opts: RunReconcileOptions<TClient, TConfig, TLive, TScope>,
+): Promise<ReconcileResult> {
+  const {
+    scopes,
+    client,
+    cycles,
+    scope,
+    mode = "dry-run",
+    diff: diffFn,
+    guardrails = (): GuardrailResult => ({ ok: true }),
+    diffOptions = {},
+    allowGuardrailOverride = false,
+    requestBudget = 1000,
+  } = opts;
+
+  const budget = new MutableRateBudget(requestBudget);
+  const cycleResults: CycleResult[] = [];
+  const erroredCycles: CycleError[] = [];
+  const deferred: DeferredWork = { skippedCycles: [], skippedEntries: [] };
+
+  const scopeEntries = Object.entries(scopes);
+
+  for (const cycle of cycles) {
+    for (const [scopeId, scopeConfig] of scopeEntries) {
+      if (budget.exhausted) {
+        deferred.skippedCycles.push(`${cycle.name}@${scopeId}`);
+        continue;
+      }
+
+      let live: TLive;
+      try {
+        live = await cycle.fetchLive(client, scopeId, scope as TScope, budget);
+      } catch (err) {
+        if (err instanceof BudgetExhaustedError) {
+          deferred.skippedCycles.push(`${cycle.name}@${scopeId}`);
+          continue;
+        }
+        erroredCycles.push({ name: cycle.name, org: scopeId, stage: "fetchLive", error: errMsg(err) });
+        continue;
+      }
+
+      let desired: TConfig;
+      try {
+        desired = cycle.buildDesired(scopeConfig, scopeId, scope as TScope);
+      } catch (err) {
+        erroredCycles.push({ name: cycle.name, org: scopeId, stage: "buildDesired", error: errMsg(err) });
+        continue;
+      }
+
+      const changeSet = diffFn(scopeId, desired, live, diffOptions);
+      const guardrailResult = guardrails(changeSet, live);
+
+      const counts = { create: 0, update: 0, delete: 0 };
+      for (const e of changeSet.entries) counts[e.kind]++;
+
+      const cycleResult: CycleResult = {
+        name: cycle.name,
+        org: scopeId,
+        counts,
+        guardrails: guardrailResult,
+        applied: [],
+        failed: [],
+        plan: renderChangeSet(changeSet),
+        guardrailBlocked: false,
+      };
+
+      if (mode === "dry-run") {
+        cycleResults.push(cycleResult);
+        continue;
+      }
+
+      if (!guardrailResult.ok && !allowGuardrailOverride) {
+        cycleResult.guardrailBlocked = true;
+        cycleResults.push(cycleResult);
+        continue;
+      }
+
+      for (const entry of changeSet.entries) {
+        if (budget.exhausted) {
+          deferred.skippedEntries.push({ cycleName: cycle.name, entry });
+          continue;
+        }
+        try {
+          await cycle.apply(client, entry, scopeId, scope as TScope, budget);
+          cycleResult.applied.push(entry);
+        } catch (err) {
+          if (err instanceof BudgetExhaustedError) {
+            deferred.skippedEntries.push({ cycleName: cycle.name, entry });
+            continue;
+          }
+          cycleResult.failed.push({ entry, error: errMsg(err) });
+        }
+      }
+
+      cycleResults.push(cycleResult);
+    }
+  }
+
+  const completed =
+    deferred.skippedCycles.length === 0 &&
+    deferred.skippedEntries.length === 0 &&
+    erroredCycles.length === 0;
+
+  return { mode, completed, cycles: cycleResults, errored: erroredCycles, deferred, budgetRemaining: budget.remaining };
+}