@intentius/chant 0.8.1 → 0.9.0

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

@@ -2,7 +2,8 @@ import type { CommandContext } from "../registry.js";
 /**
  * `chant graph` — the Op dependency graph by default; `--stacks` renders the
  * cross-stack apply-ordering graph (edges, order, waves) chant computes from
- * cross-lexicon references.
+ * cross-lexicon references; `--format ir` emits the full entity-graph IR
+ * (lint-gated) for diagram painters and the agentic diagrammer (#493).
  */
 export declare function runGraph(ctx: CommandContext): Promise<number>;
 //# sourceMappingURL=graph.d.ts.map

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":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD;;;;GAIG;AACH,wBAAsB,QAAQ,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAGnE"}
+{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["../../../src/cli/handlers/graph.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD;;;;;GAKG;AACH,wBAAsB,QAAQ,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAInE"}

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,CAqIpD"}
+{"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,CAuIpD"}

package/dist/cli/registry.d.ts

@@ -56,6 +56,8 @@ export interface ParsedArgs {
     env?: string;
     /** `chant graph --stacks` — render the cross-stack apply-ordering graph */
     stacks?: boolean;
+    /** `chant graph --format ir --detail <0..3>` — graph IR detail tier */
+    detail?: number;
     /** `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-detail.d.ts

@@ -0,0 +1,21 @@
+import type { GraphIR } from "./graph-ir.js";
+/**
+ * Detail tiers — the diagram "detail dial". Each level is a pure IR → IR
+ * transform over the base graph IR (no re-discovery), so every emitter and the
+ * painter get them for free. See issue #494 / epic #492.
+ *
+ * - 0 STACKS      — one node per lexicon; edges are cross-lexicon dependencies
+ * - 1 COMPOSITES  — composite instances collapsed to a single node each
+ * - 2 DECLARABLES — every resource (the base produced by buildGraphIr)
+ * - 3 ATTRIBUTES  — declarables plus the producer attribute on each edge
+ */
+export type DetailLevel = 0 | 1 | 2 | 3;
+export declare const DETAIL: {
+    readonly STACKS: 0;
+    readonly COMPOSITES: 1;
+    readonly DECLARABLES: 2;
+    readonly ATTRIBUTES: 3;
+};
+/** Apply a detail tier to the base (declarable-level) IR. */
+export declare function applyDetail(ir: GraphIR, level: DetailLevel): GraphIR;
+//# sourceMappingURL=graph-detail.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"graph-detail.d.ts","sourceRoot":"","sources":["../src/graph-detail.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAkB,MAAM,YAAY,CAAC;AAE1D;;;;;;;;;GASG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAExC,eAAO,MAAM,MAAM;;;;;CAKT,CAAC;AAEX,6DAA6D;AAC7D,wBAAgB,WAAW,CAAC,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,WAAW,GAAG,OAAO,CAYpE"}

package/dist/graph-ir.d.ts

@@ -0,0 +1,78 @@
+import { type Declarable } from "./declarable.js";
+/**
+ * Graph IR — the engine-neutral, lint-gated representation of a project's
+ * resolved infrastructure graph. Painters (mermaid, graphviz, custom SVG) and
+ * the agentic diagrammer consume this; it is a pure function of lint-clean
+ * source. Every node traces to the file that declared it; every edge is a real
+ * cross-resource reference (AttrRef).
+ *
+ * Emitted by `chant graph --format ir`. See issue #493 / epic #492.
+ */
+/** Where in the source a node came from. Entity-level (file), not a line map. */
+export interface SourceLoc {
+    /** Path of the declaring file, relative to the project root when possible. */
+    file: string;
+    /**
+     * Line number, when available. Provenance is entity-level today, so this is
+     * usually absent — reserved for a future source map.
+     */
+    line?: number;
+}
+/** A reference in an attribute projection: `<producer>.<attribute>`. */
+export interface AttrRefEnvelope {
+    $ref: string;
+}
+/** One resource in the graph. */
+export interface IRNode {
+    /** Logical name (the export name, or composite-expanded name). */
+    id: string;
+    /** Resource type, e.g. "GkeCluster". */
+    kind: string;
+    /** Lexicon the resource belongs to, e.g. "gcp". */
+    lexicon: string;
+    /**
+     * Name of the composite *type* that expanded this node, when it came from one
+     * (e.g. "CockroachDbCluster").
+     */
+    compositeParent?: string;
+    /**
+     * The composite *instance* (export name) this node belongs to — shared by every
+     * node from the same composite call. Detail tiers collapse on this (#494).
+     */
+    compositeInstance?: string;
+    /** Literal/const/ref-resolved props. References appear as `{ $ref }`. */
+    attrs: Record<string, unknown>;
+    /** Where the node was declared. */
+    sourceLoc?: SourceLoc;
+}
+/** A directed dependency: `from` references an attribute of `to`. */
+export interface IREdge {
+    from: string;
+    to: string;
+    /** "ref" for an AttrRef-derived edge. */
+    kind: "ref";
+    /** The consumer-side property the reference flows through, when derivable. */
+    viaAttr?: string;
+    /** The producer-side attribute referenced (e.g. "id"). Added at detail T3. */
+    toAttr?: string;
+}
+/** Grouping metadata for cluster/subgraph rendering. Maps group name -> node ids. */
+export interface IRGroups {
+    byLexicon?: Record<string, string[]>;
+    byComposite?: Record<string, string[]>;
+    /** Reserved for stack grouping (#494). */
+    byStack?: Record<string, string[]>;
+}
+/** The full graph IR for a project at the default (declarable) detail level. */
+export interface GraphIR {
+    nodes: IRNode[];
+    edges: IREdge[];
+    groups: IRGroups;
+}
+/**
+ * Build the graph IR from resolved entities (the output of `discover`). Pure and
+ * deterministic: nodes and edges are sorted, so the same source yields identical
+ * IR. `projectPath` relativizes source-file paths for portable output.
+ */
+export declare function buildGraphIr(entities: Map<string, Declarable>, projectPath?: string): GraphIR;
+//# sourceMappingURL=graph-ir.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"graph-ir.d.ts","sourceRoot":"","sources":["../src/graph-ir.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,UAAU,EAAgB,MAAM,cAAc,CAAC;AAK7D;;;;;;;;GAQG;AAEH,iFAAiF;AACjF,MAAM,WAAW,SAAS;IACxB,8EAA8E;IAC9E,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,wEAAwE;AACxE,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;CACd;AAED,iCAAiC;AACjC,MAAM,WAAW,MAAM;IACrB,kEAAkE;IAClE,EAAE,EAAE,MAAM,CAAC;IACX,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,mDAAmD;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,yEAAyE;IACzE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,mCAAmC;IACnC,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB;AAED,qEAAqE;AACrE,MAAM,WAAW,MAAM;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,yCAAyC;IACzC,IAAI,EAAE,KAAK,CAAC;IACZ,8EAA8E;IAC9E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8EAA8E;IAC9E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,qFAAqF;AACrF,MAAM,WAAW,QAAQ;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACrC,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACvC,0CAA0C;IAC1C,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;CACpC;AAED,gFAAgF;AAChF,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,MAAM,EAAE,QAAQ,CAAC;CAClB;AAyID;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,EACjC,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAmDT"}

package/dist/index.d.ts

@@ -24,6 +24,8 @@ export * from "./discovery/graph.js";
 export * from "./discovery/index.js";
 export * from "./discovery/cache.js";
 export * from "./build.js";
+export * from "./graph-ir.js";
+export * from "./graph-detail.js";
 export * from "./detectLexicon.js";
 export * from "./lint/parser.js";
 export * from "./lint/rule.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,QAAQ,CAAC;AACvB,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,SAAS,CAAC;AACxB,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,WAAW,CAAC;AAC1B,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,WAAW,CAAC;AAC1B,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AACtC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,yBAAyB,CAAC;AACxC,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAElC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,EAAE,WAAW,EAAE,YAAY,EAClE,cAAc,EAAE,iBAAiB,EAAE,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC5F,YAAY,EAAE,QAAQ,EAAE,eAAe,EAAE,cAAc,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,QAAQ,CAAC;AACvB,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,SAAS,CAAC;AACxB,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,WAAW,CAAC;AAC1B,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,WAAW,CAAC;AAC1B,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AACtC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,yBAAyB,CAAC;AACxC,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAElC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,EAAE,WAAW,EAAE,YAAY,EAClE,cAAc,EAAE,iBAAiB,EAAE,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC5F,YAAY,EAAE,QAAQ,EAAE,eAAe,EAAE,cAAc,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC"}

package/dist/provenance.d.ts

@@ -12,8 +12,15 @@
 export interface EntityProvenance {
     /** Absolute path of the source file that declared (or exported) the entity. */
     sourceFile?: string;
-    /** The composite that expanded this entity, when it came from one. */
+    /** The composite (type) that expanded this entity, when it came from one. */
     composite?: string;
+    /**
+     * The composite *instance* this entity belongs to — the export name of the
+     * top-level composite, shared by every member it expanded to. Distinguishes
+     * two instances of the same composite type, which `composite` cannot. Used to
+     * collapse a composite to a single node at coarse diagram detail levels (#494).
+     */
+    compositeInstance?: string;
 }
 /**
  * Merge provenance onto an entity. Non-enumerable so it is invisible to

package/dist/provenance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provenance.d.ts","sourceRoot":"","sources":["../src/provenance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,MAAM,WAAW,gBAAgB;IAC/B,+EAA+E;IAC/E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,gBAAgB,GAAG,IAAI,CAc1E;AAED,6DAA6D;AAC7D,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,CAE1E"}
+{"version":3,"file":"provenance.d.ts","sourceRoot":"","sources":["../src/provenance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,MAAM,WAAW,gBAAgB;IAC/B,+EAA+E;IAC/E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,gBAAgB,GAAG,IAAI,CAe1E;AAED,6DAA6D;AAC7D,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,CAE1E"}

package/dist/reconcile.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Provider-agnostic reconcile primitive.
+ *
+ * The reusable machinery behind a declarative reconcile loop, with NO knowledge
+ * of any specific provider (GitHub, GitLab, a cloud, …): the change-set model,
+ * the generic collection diff (selective-by-omission + ownership-gated deletes),
+ * the plan renderer, and the guardrail framework (rename resolution + a removal
+ * 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
+ * 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.
+ */
+/** A single field-level change: what the old value was and what it will become. */
+export interface FieldChange {
+    field: string;
+    before: unknown;
+    after: unknown;
+}
+/** The kind of operation this change represents. */
+export type ChangeKind = "create" | "update" | "delete";
+/** A single entry in the change set. */
+export interface ChangeSetEntry {
+    kind: ChangeKind;
+    /** High-level resource category (e.g. "team", "member", "branch-protection"). */
+    resourceType: string;
+    /**
+     * Unique key identifying this resource within its type.
+     * - For top-level resources: a single name (team slug, member login, …).
+     * - For nested resources: "<parent>/<child>" (e.g. "backend/alice").
+     */
+    key: string;
+    /** The live value before the change (absent for creates). */
+    before?: unknown;
+    /** The desired value after the change (absent for deletes). */
+    after?: unknown;
+    /** Field-level diff, populated for `update` entries. */
+    fields?: FieldChange[];
+}
+/** The full set of changes to reconcile for one scope (e.g. one org). */
+export interface ChangeSet {
+    /** Scope identifier this change set applies to (e.g. a GitHub org login). */
+    org: string;
+    /** All proposed changes, in stable order. */
+    entries: ChangeSetEntry[];
+}
+/** Options controlling diff behaviour. */
+export interface DiffOptions {
+    /**
+     * Ownership predicate for collection entries. The diff only emits a `delete`
+     * for a live entry absent from desired when this returns `true`. Omitted →
+     * deletes are never emitted ("assume nothing is owned").
+     */
+    isOwned?: (resourceType: string, key: string) => boolean;
+    /**
+     * Reference "now" in epoch milliseconds, used by time-based diffs. Callers
+     * inject `Date.now()` when unset; tests pass an explicit value.
+     */
+    nowMs?: number;
+}
+/** Deep value equality via JSON for plain data (config/live snapshots). */
+export declare function deepEqual(a: unknown, b: unknown): boolean;
+/**
+ * Diff fields of `desired` against `live`, returning one `FieldChange` per
+ * differing field. When `keys` is given, only those keys are compared (and only
+ * when present in `desired`); otherwise every key in `desired` is compared.
+ * Selective-by-omission: keys absent from `desired` are never compared.
+ */
+export declare function diffFields(desired: Record<string, unknown>, live: Record<string, unknown>, keys?: string[]): FieldChange[];
+/** Parameters for {@link diffCollection}. */
+export interface DiffCollectionParams<D, L> {
+    /** Resource type stamped on emitted entries. */
+    resourceType: string;
+    /** Prefix prepended to each entry key (e.g. "<parent>/"). Default "". */
+    keyPrefix?: string;
+    /** Desired entries, keyed by logical key. */
+    desired: Map<string, D>;
+    /** Live entries, keyed by logical key. */
+    live: Map<string, L>;
+    /** Fields that differ → an update. Return `[]` for "no change". */
+    compareFields: (desired: D, live: L) => FieldChange[];
+    /** `after` value for a create entry. Defaults to the desired value. */
+    createAfter?: (key: string, desired: D) => unknown;
+    /** `after` value for an update entry. Defaults to the desired value. */
+    updateAfter?: (key: string, desired: D, live: L) => unknown;
+    opts: DiffOptions;
+    out: ChangeSetEntry[];
+}
+/**
+ * The generic managed-collection diff: creates for desired-not-live, updates
+ * when `compareFields` reports differences, and ownership-gated deletes for
+ * live-not-desired. This is the selective-by-omission + ownership-gated-delete
+ * pattern shared by every keyed-collection diff.
+ */
+export declare function diffCollection<D, L>(params: DiffCollectionParams<D, L>): void;
+/** Count entries per change kind. */
+export declare function summarizeChangeSet(cs: ChangeSet): Record<ChangeKind, number>;
+/** Human-readable plan summary for dry-run output. Pure. */
+export declare function renderChangeSet(cs: ChangeSet): string;
+/** A single tripped guardrail with a human-readable message. */
+export interface GuardrailDiagnostic {
+    /** Short identifier, e.g. "removalDeltaCap". */
+    guardrail: string;
+    /** Clear, actionable description of why the apply was refused. */
+    message: string;
+}
+/** Aggregated guardrail result. */
+export type GuardrailResult = {
+    ok: true;
+} | {
+    ok: false;
+    diagnostics: GuardrailDiagnostic[];
+};
+/** A guardrail check over a (rename-resolved) change set. Returns null when it passes. */
+export type GuardrailCheck = (resolved: ChangeSet) => GuardrailDiagnostic | null;
+/** Config for `removalDeltaCap`. */
+export interface RemovalDeltaCapOptions {
+    /** Max fraction of pre-existing entries that may be deleted. Must be in (0,1]. Default 0.25. */
+    maxFraction?: number;
+}
+/**
+ * Resolve rename aliases. A create entry carrying a `previously` key matching a
+ * delete entry's key is collapsed into an update, removing the delete. Returns a
+ * new ChangeSet with renames resolved. Provider-agnostic — works on any entry
+ * whose `after.previously` is a string.
+ */
+export declare function resolveRenames(changeSet: ChangeSet): ChangeSet;
+/**
+ * Refuse if deletes exceed `maxFraction` of the pre-existing managed entries
+ * (deletes + updates; creates excluded so a flood of new entries can't dilute
+ * the delete fraction). Guards against a typo wiping the config in one apply.
+ *
+ * CONTRACT: pass a RENAME-RESOLVED change set (see {@link resolveRenames}).
+ */
+export declare function removalDeltaCap(changeSet: ChangeSet, opts?: RemovalDeltaCapOptions): GuardrailDiagnostic | null;
+/**
+ * Run a set of guardrail checks against a change set. Resolves renames ONCE,
+ * then runs every check on the resolved set, aggregating any diagnostics. The
+ * caller composes provider-specific checks (e.g. an admin floor) as closures.
+ */
+export declare function runGuardrailChecks(changeSet: ChangeSet, checks: GuardrailCheck[]): GuardrailResult;
+//# sourceMappingURL=reconcile.d.ts.map

package/dist/reconcile.d.ts.map

@@ -0,0 +1 @@
+{"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.8.1",
+  "version": "0.9.0",
   "description": "Declarative infrastructure-as-code toolkit — TypeScript on Node.js",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",

package/src/cli/handlers/graph.ts

@@ -2,19 +2,61 @@ import { resolve } from "node:path";
 import { discoverOps } from "../../op/discover";
 import { discover } from "../../discovery/index";
 import { partitionByLexicon, computeStackGraph } from "../../build";
+import { buildGraphIr } from "../../graph-ir";
+import { applyDetail, type DetailLevel } from "../../graph-detail";
+import { lintCommand } from "../commands/lint";
 import { formatError, formatWarning, formatBold } from "../format";
 import type { CommandContext } from "../registry";
 
 /**
  * `chant graph` — the Op dependency graph by default; `--stacks` renders the
  * cross-stack apply-ordering graph (edges, order, waves) chant computes from
- * cross-lexicon references.
+ * cross-lexicon references; `--format ir` emits the full entity-graph IR
+ * (lint-gated) for diagram painters and the agentic diagrammer (#493).
  */
 export async function runGraph(ctx: CommandContext): Promise<number> {
+  if (ctx.args.format === "ir") return runGraphIr(ctx);
   if (ctx.args.stacks) return runStackGraph(ctx);
   return runOpGraph();
 }
 
+/**
+ * `chant graph --format ir` — emit the graph IR as JSON. Lint-gated: the IR is a
+ * representation of valid infra, so we refuse to emit it for source that does
+ * not pass lint (EVL + lexicon rules). Non-zero exit on discovery errors.
+ */
+async function runGraphIr(ctx: CommandContext): Promise<number> {
+  const projectPath = resolve(ctx.args.path === "." ? "." : ctx.args.path);
+
+  const level = ctx.args.detail ?? 2;
+  if (![0, 1, 2, 3].includes(level)) {
+    console.error(formatError({ message: `Invalid --detail ${level}. Expected 0, 1, 2, or 3.` }));
+    return 1;
+  }
+
+  // Gate: only emit an IR for lint-clean source.
+  const lint = await lintCommand({ path: ctx.args.path, format: "stylish" });
+  if (!lint.success) {
+    console.error(
+      formatError({
+        message:
+          "Refusing to emit graph IR: source has lint errors. Run `chant lint` and fix them first.",
+      }),
+    );
+    return 1;
+  }
+
+  const result = await discover(projectPath);
+  if (result.errors.length > 0) {
+    for (const e of result.errors) console.error(formatError({ message: e.message }));
+    return 1;
+  }
+
+  const ir = applyDetail(buildGraphIr(result.entities, projectPath), level as DetailLevel);
+  console.log(JSON.stringify(ir, null, 2));
+  return 0;
+}
+
 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

@@ -126,6 +126,8 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.theme = args[++i];
     } else if (arg === "--stacks") {
       result.stacks = true;
+    } else if (arg === "--detail") {
+      result.detail = Number(args[++i]);
     } else if (arg === "--base") {
       result.base = args[++i];
     } else if (arg === "--head") {
@@ -190,7 +192,9 @@ Ops:
   run cancel <name>     Cancel the active workflow run (requires --force)
   run log <name>        Show run history for an Op
 
-  graph                 Show Op dependency graph (--stacks for cross-stack order)
+  graph                 Show Op dependency graph (--stacks for cross-stack order,
+                        --format ir for the lint-gated entity-graph IR;
+                        --detail 0..3: stacks|composites|declarables|attributes)
 
 Lifecycle (alias: lc):
   lifecycle snapshot <env>  Query API, save metadata to orphan branch

package/src/cli/registry.ts

@@ -57,6 +57,8 @@ export interface ParsedArgs {
   env?: string;
   /** `chant graph --stacks` — render the cross-stack apply-ordering graph */
   stacks?: boolean;
+  /** `chant graph --format ir --detail <0..3>` — graph IR detail tier */
+  detail?: number;
   /** `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/discovery/collect.ts

@@ -58,7 +58,7 @@ export function collectEntities(
                   "resolution",
                 );
               }
-              setProvenance(entity, { sourceFile: file });
+              setProvenance(entity, { sourceFile: file, compositeInstance: indexedName });
               entities.set(expandedName, entity);
             }
           }
@@ -73,7 +73,7 @@ export function collectEntities(
               "resolution",
             );
           }
-          setProvenance(entity, { sourceFile: file });
+          setProvenance(entity, { sourceFile: file, compositeInstance: name });
           entities.set(expandedName, entity);
         }
       } else if (isLexiconOutput(value)) {

package/src/graph-detail.test.ts

@@ -0,0 +1,79 @@
+import { describe, test, expect } from "vitest";
+import { applyDetail, DETAIL } from "./graph-detail";
+import type { GraphIR } from "./graph-ir";
+
+// A small graph: a gcp vpc/subnet pair plus a k8s namespace and deployment that
+// came from one composite instance ("db"), with the deployment referencing the
+// subnet across lexicons.
+const base: GraphIR = {
+  nodes: [
+    { id: "vpc", kind: "Vpc", lexicon: "gcp", attrs: {} },
+    { id: "subnet", kind: "Subnet", lexicon: "gcp", attrs: { network: { $ref: "vpc.id" } } },
+    {
+      id: "dbNamespace",
+      kind: "Namespace",
+      lexicon: "k8s",
+      compositeParent: "DbStack",
+      compositeInstance: "db",
+      attrs: {},
+    },
+    {
+      id: "dbDeployment",
+      kind: "Deployment",
+      lexicon: "k8s",
+      compositeParent: "DbStack",
+      compositeInstance: "db",
+      attrs: { subnet: { $ref: "subnet.selfLink" } },
+    },
+  ],
+  edges: [
+    { from: "subnet", to: "vpc", kind: "ref", viaAttr: "network" },
+    { from: "dbDeployment", to: "subnet", kind: "ref", viaAttr: "subnet" },
+  ],
+  groups: { byLexicon: { gcp: ["subnet", "vpc"], k8s: ["dbDeployment", "dbNamespace"] } },
+};
+
+describe("applyDetail", () => {
+  test("T2 (declarables) is the identity", () => {
+    expect(applyDetail(base, DETAIL.DECLARABLES)).toBe(base);
+  });
+
+  test("T0 (stacks) collapses to one node per lexicon with cross-lexicon edges", () => {
+    const ir = applyDetail(base, DETAIL.STACKS);
+    expect(ir.nodes.map((n) => n.id)).toEqual(["gcp", "k8s"]);
+    expect(ir.nodes.every((n) => n.kind === "stack")).toBe(true);
+    // subnet→vpc is intra-gcp (dropped); dbDeployment→subnet is k8s→gcp (kept).
+    expect(ir.edges).toEqual([{ from: "k8s", to: "gcp", kind: "ref" }]);
+  });
+
+  test("T1 (composites) collapses a composite instance to a single node", () => {
+    const ir = applyDetail(base, DETAIL.COMPOSITES);
+    expect(ir.nodes.map((n) => n.id).sort()).toEqual(["db", "subnet", "vpc"]);
+    const db = ir.nodes.find((n) => n.id === "db")!;
+    expect(db).toMatchObject({ kind: "DbStack", lexicon: "k8s", attrs: { members: 2 } });
+    // The composite's external ref is preserved, remapped to the composite node.
+    expect(ir.edges).toContainEqual({ from: "db", to: "subnet", kind: "ref" });
+    // The intra-gcp edge survives with its label.
+    expect(ir.edges).toContainEqual({ from: "subnet", to: "vpc", kind: "ref", viaAttr: "network" });
+  });
+
+  test("T1 node count is between T0 and T2", () => {
+    const t0 = applyDetail(base, DETAIL.STACKS).nodes.length;
+    const t1 = applyDetail(base, DETAIL.COMPOSITES).nodes.length;
+    const t2 = applyDetail(base, DETAIL.DECLARABLES).nodes.length;
+    expect(t0).toBeLessThan(t1);
+    expect(t1).toBeLessThan(t2);
+  });
+
+  test("T3 (attributes) annotates edges with the producer attribute", () => {
+    const ir = applyDetail(base, DETAIL.ATTRIBUTES);
+    expect(ir.edges).toContainEqual({ from: "subnet", to: "vpc", kind: "ref", viaAttr: "network", toAttr: "id" });
+    expect(ir.edges).toContainEqual({
+      from: "dbDeployment",
+      to: "subnet",
+      kind: "ref",
+      viaAttr: "subnet",
+      toAttr: "selfLink",
+    });
+  });
+});