@intentius/chant 0.124.13 → 0.124.14

package/dist/gate-resume-run.js

@@ -0,0 +1,154 @@
+/**
+ * Resume the job that waits at a gate (#3683), bundle-safe (#3854).
+ *
+ * A CI job that reaches a gate nobody approved records a pending fact on
+ * `chant/lifecycle` and exits 3. Nothing re-runs it when the approval lands,
+ * because a push to the ledger branch starts no pipeline. This module closes
+ * that loop through the forge's API.
+ *
+ * When the job runs in CI, the pending fact it records carries a
+ * {@link GateRunLocator}, read from the job's environment by
+ * {@link resolveGateRunLocator}: which forge, the API base, the repository,
+ * the run, and what the forge needs to start it again. After an approval,
+ * {@link resumeGateRun} starts it again:
+ *
+ * | Forge | Call | Token |
+ * |---|---|---|
+ * | GitHub | `POST /repos/{repo}/actions/runs/{run}/rerun-failed-jobs` | `actions: write` (the job's `GITHUB_TOKEN` with that permission, or a fine-grained token with Actions read and write) |
+ * | GitLab | `POST /projects/{id}/jobs/{job}/retry` | a project or personal access token with the `api` scope and the Developer role; `CI_JOB_TOKEN` cannot retry jobs |
+ * | Forgejo | `POST /repos/{repo}/actions/workflows/{file}/dispatches` on the run's branch | a token with the `write:repository` scope; Forgejo has no API to re-run a run, so it starts a new run of the workflow |
+ *
+ * GitHub re-runs the failed job and the jobs that need it, at the same
+ * commit. GitLab retries the job, and the jobs it skipped run after it. A
+ * Forgejo dispatch runs the whole workflow again at the branch's head, so the
+ * jobs before the gate run again too; they must be safe to repeat (a wave
+ * whose runs already applied plans nothing and applies nothing new).
+ *
+ * Resuming approves nothing. The resumed job decides the gate again from the
+ * ledger, so resuming a run whose approval does not count only makes it wait
+ * again. {@link resumeGateRun} skips a run that is still going, that ended
+ * well, or that was already resumed (a later GitHub attempt, a newer GitLab
+ * job of the same name, a newer Forgejo run of the workflow), so a scheduled
+ * resume job can call it every few minutes without starting a run twice.
+ *
+ * This module imports no workspace, ledger, schema or git code, so a product
+ * that ships one bundled file (terragucci) can import it as
+ * `@intentius/chant/gate-resume-run` and resume a job in process. Which
+ * approval answers a pending fact is `./op/gate-resume.ts`'s
+ * `resolutionAnswering`, which reads the gate's quorum rules and does pull the
+ * workspace in; that module re-exports everything here.
+ */
+import { ForgeApiError } from "./pr-forge.js";
+export { isGateRunLocator, resolveGateRunLocator } from "./op/gate-run-locator.js";
+const trimSlash = (s) => s.replace(/\/+$/, "");
+const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+function client(base, headers, fetchImpl) {
+    return async (method, path, body) => {
+        const url = `${trimSlash(base)}${path}`;
+        const res = await fetchImpl(url, {
+            method,
+            headers: { ...headers, ...(body !== undefined ? { "Content-Type": "application/json" } : {}) },
+            ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+        });
+        const text = await res.text();
+        if (!res.ok)
+            throw new ForgeApiError(method, url, res.status, text);
+        if (!text)
+            return null;
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return text;
+        }
+    };
+}
+/**
+ * Start the job a pending fact's locator names again, or say why not. Throws
+ * {@link ForgeApiError} when the forge refuses a call, such as a token
+ * without the access the table in the module doc lists.
+ */
+export async function resumeGateRun(loc, opts) {
+    const fetchImpl = opts.fetch ?? globalThis.fetch;
+    const url = loc.url ? { url: loc.url } : {};
+    const skip = (reason) => ({ status: "skipped", forge: loc.forge, reason, ...url });
+    const wouldResume = (how) => ({ status: "would-resume", forge: loc.forge, how: `would ${how}`, ...url });
+    if (loc.forge === "github") {
+        const call = client(loc.api, { Authorization: `Bearer ${opts.token}`, Accept: "application/vnd.github+json" }, fetchImpl);
+        const path = `/repos/${loc.repo}/actions/runs/${loc.run}`;
+        const run = await call("GET", path);
+        if (!isObject(run))
+            throw new Error(`GET ${path} returned no run`);
+        if (run.status !== "completed")
+            return skip(`run ${loc.run} is ${String(run.status)}, not finished`);
+        const attempt = typeof run.run_attempt === "number" ? run.run_attempt : undefined;
+        if (loc.attempt !== undefined && attempt !== undefined && attempt > loc.attempt) {
+            return skip(`run ${loc.run} was already re-run (attempt ${attempt}; attempt ${loc.attempt} waited)`);
+        }
+        if (run.conclusion === "success")
+            return skip(`run ${loc.run} succeeded`);
+        if (opts.dryRun)
+            return wouldResume(`re-run the failed jobs of run ${loc.run}`);
+        await call("POST", `${path}/rerun-failed-jobs`, {});
+        return { status: "resumed", forge: "github", how: `re-ran the failed jobs of run ${loc.run}`, ...url };
+    }
+    if (loc.forge === "gitlab") {
+        const call = client(loc.api, { "PRIVATE-TOKEN": opts.token }, fetchImpl);
+        const project = `/projects/${encodeURIComponent(decodeURIComponent(loc.repo))}`;
+        const job = await call("GET", `${project}/jobs/${loc.job}`);
+        if (!isObject(job))
+            throw new Error(`GET ${project}/jobs/${loc.job} returned no job`);
+        const status = String(job.status);
+        if (status === "success")
+            return skip(`job ${loc.job} succeeded`);
+        if (!["failed", "canceled", "skipped"].includes(status))
+            return skip(`job ${loc.job} is ${status}, not finished`);
+        const name = loc.jobName ?? (typeof job.name === "string" ? job.name : undefined);
+        if (name) {
+            // The pipeline's jobs list leaves retried jobs out, so the job of this name is its newest try.
+            const jobs = await call("GET", `${project}/pipelines/${loc.run}/jobs?per_page=100`);
+            const newest = Array.isArray(jobs) ? jobs.find((j) => isObject(j) && j.name === name) : undefined;
+            if (isObject(newest) && String(newest.id) !== String(loc.job)) {
+                return skip(`job ${loc.job} (${name}) was already retried as job ${String(newest.id)}`);
+            }
+        }
+        if (opts.dryRun)
+            return wouldResume(`retry job ${loc.job}`);
+        const retried = await call("POST", `${project}/jobs/${loc.job}/retry`);
+        const id = isObject(retried) && retried.id !== undefined ? ` as job ${String(retried.id)}` : "";
+        return { status: "resumed", forge: "gitlab", how: `retried job ${loc.job}${id}`, ...url };
+    }
+    const call = client(loc.api, { Authorization: `token ${opts.token}`, Accept: "application/json" }, fetchImpl);
+    const repo = `/repos/${loc.repo}`;
+    const run = await call("GET", `${repo}/actions/runs/${loc.run}`);
+    if (!isObject(run))
+        throw new Error(`GET ${repo}/actions/runs/${loc.run} returned no run`);
+    const status = String(run.status);
+    if (status === "success")
+        return skip(`run ${loc.run} succeeded`);
+    if (["waiting", "running", "blocked", "unknown"].includes(status))
+        return skip(`run ${loc.run} is ${status}, not finished`);
+    const listed = await call("GET", `${repo}/actions/runs?workflow_id=${encodeURIComponent(loc.workflow)}&limit=50`);
+    const runs = isObject(listed) && Array.isArray(listed.workflow_runs) ? listed.workflow_runs : Array.isArray(listed) ? listed : [];
+    // Forgejo reports `created` in whole seconds.
+    const since = opts.since ? Math.floor(new Date(opts.since).getTime() / 1000) * 1000 : undefined;
+    const later = runs.find((r) => isObject(r) && Number(r.id) > Number(loc.run) &&
+        (r.prettyref === undefined || r.prettyref === loc.ref) &&
+        (since === undefined || (typeof r.created === "string" && new Date(r.created).getTime() >= since)));
+    if (isObject(later))
+        return skip(`run ${String(later.id)} of ${loc.workflow} started after the approval`);
+    if (opts.dryRun)
+        return wouldResume(`dispatch ${loc.workflow} on ${loc.ref}`);
+    await call("POST", `${repo}/actions/workflows/${encodeURIComponent(loc.workflow)}/dispatches`, { ref: loc.ref });
+    return { status: "resumed", forge: "forgejo", how: `dispatched ${loc.workflow} on ${loc.ref}`, ...url };
+}
+/**
+ * The token a resume uses: `CHANT_FORGE_TOKEN`, else the forge's own
+ * (`GITHUB_TOKEN` or `GH_TOKEN` on GitHub and Forgejo, `GITLAB_TOKEN` on
+ * GitLab), the same order the pull-request loop reads (`../pr-forge.ts`).
+ */
+export function resumeTokenFromEnv(forge, env = process.env) {
+    if (env.CHANT_FORGE_TOKEN)
+        return env.CHANT_FORGE_TOKEN;
+    return forge === "gitlab" ? env.GITLAB_TOKEN : env.GITHUB_TOKEN ?? env.GH_TOKEN;
+}

package/dist/gated-waves.js

@@ -0,0 +1,165 @@
+/**
+ * Gated waves (#3049): one change rolled out across many roots, a wave at a
+ * time, each wave behind its own gate bound to that wave's set digest.
+ *
+ * `chant components fan-out --wave-gate` is the runner. This module holds the
+ * parts that need no runner: how a set of roots is cut into waves, what a
+ * wave's digest is, what its gate is called, and what the attempt record says
+ * about each wave. They are kept apart from the runner because terragucci
+ * calls them from its CI stages as one bundled file with no TypeScript
+ * toolchain (#3421). Everything here imports `./change-set` and nothing else,
+ * and `gated-waves-bundle.test.ts` holds that.
+ *
+ * ## The set digest
+ *
+ * A wave's digest is {@link changeSetDigest} over its members' `{ member,
+ * planDigest }` pairs, the function #3181's change-set document uses. A
+ * terraform-family member is named after its root, so this is the issue's
+ * `jcs1-sha256` over sorted `{ root, planDigest }`, and a wave's digest equals
+ * the change-set digest of the wave's members. Each member's plan digest is
+ * the one a gate on that root alone binds (`terraformPlanDigest`, #2300), so a
+ * one-root wave and a one-root `TerraformApplyOp` approve the same value.
+ *
+ * ## Why a wave is planned when it is reached
+ *
+ * A later wave planned up front reads outputs that do not exist yet. Planned
+ * after the wave before it applied, its digest describes the real upstream
+ * values, which is what an approver of that wave is shown.
+ */
+import { changeSetDigest } from "./change-set.js";
+/** Thrown when a canary names something that is not in the set being planned. */
+export class UnknownCanaryError extends Error {
+    constructor(canary, known) {
+        super(`canary names "${canary}", which is not in this set (known: ${known.join(", ") || "none"})`);
+        this.canary = canary;
+        this.name = "UnknownCanaryError";
+    }
+}
+/** Thrown when the nodes being layered depend on each other in a cycle. */
+export class WaveCycleError extends Error {
+    constructor(members) {
+        super(`dependency cycle among: ${members.join(", ")}`);
+        this.members = members;
+        this.name = "WaveCycleError";
+    }
+}
+/**
+ * Cut `nodes` into ordered waves: each node lands after every node it reads
+ * from, and each wave is sorted by name so the same graph always produces the
+ * same waves. With a canary list, those nodes are wave 1.
+ *
+ * A dependency on a name outside `nodes` does not hold a node back. That is
+ * the subset case: the dependency already applied, or is not changing.
+ */
+export function layerWaves(nodes, options = {}) {
+    const names = new Set(nodes.map((n) => n.name));
+    const known = new Set([...names, ...(options.known ?? [])]);
+    for (const canary of options.canary ?? []) {
+        if (!known.has(canary))
+            throw new UnknownCanaryError(canary, [...known].sort());
+    }
+    const canaries = [...new Set((options.canary ?? []).filter((c) => names.has(c)))].sort();
+    const waves = canaries.length > 0 ? [canaries] : [];
+    const remaining = new Set([...names].filter((n) => !canaries.includes(n)));
+    const deps = new Map(nodes.map((n) => [n.name, (n.dependsOn ?? []).filter((d) => remaining.has(d))]));
+    while (remaining.size > 0) {
+        const wave = [...remaining].filter((n) => deps.get(n).every((d) => !remaining.has(d))).sort();
+        if (wave.length === 0)
+            throw new WaveCycleError([...remaining].sort());
+        for (const n of wave)
+            remaining.delete(n);
+        waves.push(wave);
+    }
+    return waves;
+}
+/** Thrown when a wave's members include a provisional plan, which no gate may bind. */
+export class ProvisionalWaveMemberError extends Error {
+    constructor(members) {
+        super(`a wave cannot be gated on a provisional plan: ${members.join(", ")} planned before what it reads applied. ` +
+            `Plan it again in its own wave, after its upstream applied`);
+        this.members = members;
+        this.name = "ProvisionalWaveMemberError";
+    }
+}
+/**
+ * A wave's set digest: {@link changeSetDigest} over its members. Order does
+ * not matter, and it moves whenever one member's plan digest does. A wave
+ * naming one member twice has no digest and is refused, and so is a wave
+ * holding a provisional plan (#3416): a gate bound to it would approve
+ * values nobody has yet.
+ */
+export function waveSetDigest(members) {
+    const provisional = members.filter((m) => m.provisional === true).map((m) => m.member);
+    if (provisional.length > 0)
+        throw new ProvisionalWaveMemberError([...new Set(provisional)].sort());
+    return changeSetDigest(members);
+}
+/**
+ * The gate a wave waits on: `<gate>-wave-<n>`, under the fan-out's op.
+ *
+ * One gate name per wave keeps each wave's approvals apart. With one name
+ * shared by every wave, wave 2 would find wave 1's approval and report it as
+ * an approval of another plan, which is true and useless. Wave numbers come
+ * from the derivation, not from what is left to run, so wave 3 stays wave 3
+ * on a resumed attempt and its approval still applies.
+ */
+export function waveGateName(gate, wave) {
+    return `${gate}-wave-${wave}`;
+}
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const strings = (value) => Array.isArray(value) ? value.filter((v) => typeof v === "string") : [];
+/**
+ * Read the `waves` array of an attempt record, dropping anything malformed.
+ * A record written before #3049 has none, which reads as no waves.
+ */
+export function readWaveRecords(value) {
+    if (!Array.isArray(value))
+        return [];
+    const out = [];
+    for (const raw of value) {
+        if (!isObject(raw))
+            continue;
+        const { wave, op, gate, digest, status } = raw;
+        if (typeof wave !== "number" || typeof op !== "string" || typeof gate !== "string" || typeof digest !== "string")
+            continue;
+        if (status !== "gated" && status !== "applied" && status !== "failed")
+            continue;
+        const members = Array.isArray(raw.members)
+            ? raw.members.filter((m) => isObject(m) && typeof m.member === "string" && typeof m.planDigest === "string")
+            : [];
+        const failed = Array.isArray(raw.failed)
+            ? raw.failed
+                .filter((f) => isObject(f) && typeof f.component === "string")
+                .map((f) => ({ component: f.component, ...(typeof f.error === "string" ? { error: f.error } : {}) }))
+            : [];
+        out.push({
+            wave,
+            op,
+            gate,
+            components: strings(raw.components),
+            digest,
+            members: members.map((m) => ({ member: m.member, planDigest: m.planDigest })),
+            status,
+            ...(typeof raw.approvedBy === "string" ? { approvedBy: raw.approvedBy } : {}),
+            ...(typeof raw.approved === "string" ? { approved: raw.approved } : {}),
+            ...(failed.length > 0 ? { failed } : {}),
+        });
+    }
+    return out;
+}
+/** Put `record` in `records` in place of any earlier record for the same wave, sorted by wave. */
+export function withWaveRecord(records, record) {
+    return [...records.filter((r) => r.wave !== record.wave), record].sort((a, b) => a.wave - b.wave);
+}
+/**
+ * The refusal for a wave whose set changed after it was approved: the digest
+ * that was approved, the one planned now, and that nothing in the wave ran.
+ * On a sealed gate the approve hint ends in `--sign`.
+ */
+export function describeChangedWave(record, 
+/** True when the gate is sealed (`identity.gates`): an approval without `--sign` doesn't count, so the hint says to sign. */
+sealed = false) {
+    return (`wave ${record.wave} changed after it was approved, so nothing in it was applied. ` +
+        `approved: ${record.approved ?? "(none)"}; planned now: ${record.digest}. ` +
+        `Read the new plan, then approve it: chant approve ${record.op} ${record.gate} --plan ${record.digest}${sealed ? " --sign" : ""}`);
+}

package/dist/governance.js

@@ -0,0 +1,43 @@
+/**
+ * Governance verb vocabulary .
+ *
+ * `resourceType` on a change-set entry is a free provider-specific string
+ * ("team", "branch-protection", "protected-tag", …) chosen per cycle. That is
+ * right for display but useless for reading two providers' plans as one
+ * grammar. The verb is the cross-provider category a cycle reconciles;
+ * provider-specific cycle names stay for display.
+ *
+ * SCM and cloud cycles stamp the same verbs, so a GitHub plan and an AWS plan
+ * group the same way:
+ *
+ * - `org-unit` — the containers and their settings: GitHub org/repo settings,
+ *   GitLab group/project/instance settings, cloud OUs/folders/accounts.
+ * - `policy-guardrail` — rules constraining what may happen: branch
+ *   protections, rulesets, push rules, MR approvals, security features,
+ *   dependency hygiene, SCPs, Org Policies.
+ * - `membership` — who belongs, directly or via teams: org members, team
+ *   membership, group members.
+ * - `identity-assignment` — non-person and delegated access: tokens, deploy
+ *   keys, service credentials, SSO/IAM assignments. `membership` is people
+ *   in containers; this is everything else that can act.
+ * - `audit-sink` — where events and evidence flow: webhooks, integrations,
+ *   CloudTrail/audit-log sinks.
+ * - `secret-material` — secrets and CI variables the platform stores.
+ *
+ * A cycle has exactly one verb. When a cycle plausibly spans two (GitHub
+ * `environments` carries both reviewer gates and secrets), stamp the verb of
+ * the cycle's primary object — the thing whose create/delete the cycle owns —
+ * not of fields it also happens to write.
+ */
+/** Every verb, for exhaustiveness checks ("does each cycle stamp one?"). */
+export const GOVERNANCE_VERBS = [
+    "org-unit",
+    "policy-guardrail",
+    "membership",
+    "identity-assignment",
+    "audit-sink",
+    "secret-material",
+];
+export function isGovernanceVerb(v) {
+    return typeof v === "string" && GOVERNANCE_VERBS.includes(v);
+}

package/dist/graph-declared.js

@@ -0,0 +1,45 @@
+import { resolve } from "node:path";
+import { discover } from "./discovery/index.js";
+import { buildGraphIr } from "./graph-ir.js";
+/**
+ * Build the DECLARED graph for a multi-stack project, scoped per stack (#1162).
+ *
+ * A whole-project discovery disambiguates colliding logical names by module path
+ * (two `server`s become `UsEast1Srcserver` / `UsWest1Srcserver`) — names that
+ * never appear in any deployed template, because each stack deploys its OWN
+ * scoped source with BARE LogicalResourceIds. Observation therefore keys live
+ * nodes by `${stack}::${logicalId}` (bare id). To make the declared side join
+ * that live side, build each stack's `src` in isolation and qualify its node ids
+ * and edge endpoints the same way. Stacks are merged into one graph.
+ *
+ * A stack without `src` contributes nothing here — it has no declared source to
+ * scope to (its live nodes still show as foreign in the overlay).
+ */
+export async function buildDeclaredPerStack(stacks, projectPath) {
+    var _a;
+    const nodes = [];
+    const edges = [];
+    // Which nodes belong to which stack (#1433). This is not derived or guessed:
+    // the stack is declared in config and every node here is being renamed with
+    // its name on the line below. The membership was always known and thrown
+    // away, which left `byStack` — the axis consumers draw boundary boxes from —
+    // empty for the one project shape that genuinely has side-by-side stacks.
+    const byStack = {};
+    for (const st of stacks) {
+        if (!st.src)
+            continue;
+        const g = buildGraphIr((await discover(resolve(projectPath, st.src))).entities, projectPath);
+        const q = (id) => `${st.name}::${id}`;
+        for (const n of g.nodes) {
+            const id = q(n.id);
+            nodes.push({ ...n, id });
+            (byStack[_a = st.name] ?? (byStack[_a] = [])).push(id);
+        }
+        for (const e of g.edges)
+            edges.push({ ...e, from: q(e.from), to: q(e.to) });
+    }
+    for (const ids of Object.values(byStack))
+        ids.sort();
+    const groups = Object.keys(byStack).length ? { byStack } : {};
+    return { nodes, edges, groups };
+}

package/dist/graph-detail.js

@@ -0,0 +1,207 @@
+export const DETAIL = {
+    STACKS: 0,
+    COMPOSITES: 1,
+    DECLARABLES: 2,
+    ATTRIBUTES: 3,
+};
+/** Apply a detail tier to the base (declarable-level) IR. */
+export function applyDetail(ir, level) {
+    switch (level) {
+        case 0:
+            return toStacks(ir);
+        case 1:
+            return toComposites(ir);
+        case 3:
+            return toAttributes(ir);
+        case 2:
+        default:
+            return toDeclarables(ir);
+    }
+}
+/** Overlay paint (`_status`, `_unobserved`, …) is a verdict about the node,
+ * not a property of the resource — it survives every tier above STACKS so a
+ * zoomed-out drift view keeps its colours. */
+function paintAttrs(attrs) {
+    const out = {};
+    for (const [k, v] of Object.entries(attrs))
+        if (k.startsWith("_"))
+            out[k] = v;
+    return out;
+}
+/** A `{ $ref: "producer.attribute" }` envelope — a reference, not a property tree. */
+function isRefEnvelope(v) {
+    return (typeof v === "object" &&
+        v !== null &&
+        !Array.isArray(v) &&
+        typeof v.$ref === "string");
+}
+/** T2's resource view of a node's attrs: overlay paint, scalar fields
+ * (identity, status-relevant values), and top-level reference envelopes.
+ * Nested property trees — a k8s `spec`/`metadata`, a Tags list — wait for T3. */
+function resourceAttrs(attrs) {
+    const out = {};
+    for (const [k, v] of Object.entries(attrs)) {
+        if (k.startsWith("_") || v === null || typeof v !== "object" || isRefEnvelope(v)) {
+            out[k] = v;
+        }
+    }
+    return out;
+}
+function edgeSortKey(e) {
+    return `${e.from}\0${e.to}\0${e.viaAttr ?? ""}`;
+}
+function sortEdges(edges) {
+    return edges.sort((a, b) => edgeSortKey(a).localeCompare(edgeSortKey(b)));
+}
+function byLexiconOf(nodes) {
+    var _a;
+    const out = {};
+    for (const n of nodes)
+        (out[_a = n.lexicon] ?? (out[_a] = [])).push(n.id);
+    const sorted = {};
+    for (const k of Object.keys(out).sort())
+        sorted[k] = out[k].sort();
+    return sorted;
+}
+/** T0 — collapse every resource to its lexicon; edges become cross-lexicon deps. */
+function toStacks(ir) {
+    const lexOf = new Map(ir.nodes.map((n) => [n.id, n.lexicon]));
+    const lexicons = [...new Set(ir.nodes.map((n) => n.lexicon))].sort();
+    const nodes = lexicons.map((l) => ({ id: l, kind: "stack", lexicon: l, attrs: {} }));
+    const seen = new Map();
+    for (const e of ir.edges) {
+        const from = lexOf.get(e.from);
+        const to = lexOf.get(e.to);
+        if (!from || !to || from === to)
+            continue;
+        const key = `${from}\0${to}`;
+        if (!seen.has(key))
+            seen.set(key, { from, to, kind: "ref" });
+    }
+    return { nodes, edges: sortEdges([...seen.values()]), groups: {} };
+}
+/** T2 — every resource, each carrying the resource view of its attrs (the
+ * scalar/reference projection; the full property tree is T3's addition). */
+function toDeclarables(ir) {
+    return { ...ir, nodes: ir.nodes.map((n) => ({ ...n, attrs: resourceAttrs(n.attrs) })) };
+}
+/** T1 — collapse each composite instance to one node; internal edges disappear.
+ * Topology view: surviving plain nodes keep only overlay paint, not properties. */
+function toComposites(ir) {
+    const idMap = new Map();
+    for (const n of ir.nodes)
+        idMap.set(n.id, n.compositeInstance ?? n.id);
+    const instances = new Map();
+    const plain = [];
+    for (const n of ir.nodes) {
+        if (n.compositeInstance) {
+            const arr = instances.get(n.compositeInstance) ?? [];
+            arr.push(n);
+            instances.set(n.compositeInstance, arr);
+        }
+        else {
+            plain.push({ ...n, attrs: paintAttrs(n.attrs) });
+        }
+    }
+    const nodes = [...plain];
+    for (const [inst, members] of instances) {
+        const types = new Set(members.map((m) => m.compositeParent).filter(Boolean));
+        const lexicons = new Set(members.map((m) => m.lexicon));
+        nodes.push({
+            id: inst,
+            kind: types.size === 1 ? [...types][0] : "Composite",
+            lexicon: lexicons.size === 1 ? [...lexicons][0] : "multi",
+            attrs: { members: members.length },
+        });
+    }
+    const seen = new Map();
+    for (const e of ir.edges) {
+        const from = idMap.get(e.from) ?? e.from;
+        const to = idMap.get(e.to) ?? e.to;
+        if (from === to)
+            continue; // edge internal to a composite
+        // A property label only makes sense when neither endpoint was collapsed.
+        const collapsed = from !== e.from || to !== e.to;
+        const edge = collapsed
+            ? { from, to, kind: "ref" }
+            : { from, to, kind: "ref", viaAttr: e.viaAttr };
+        const key = `${from}\0${to}\0${edge.viaAttr ?? ""}`;
+        if (!seen.has(key))
+            seen.set(key, edge);
+    }
+    nodes.sort((a, b) => a.id.localeCompare(b.id));
+    // Carry the cross-stack import list forward: parameter/import nodes aren't
+    // composites, so they survive the collapse as plain nodes — a viewer that
+    // hides imports (or matches them across stacks) needs `imports` at every tier,
+    // not just the base + ATTRIBUTES. Filter to handles whose node survived.
+    const surviving = new Set(nodes.map((n) => n.id));
+    const imports = ir.imports?.filter((i) => surviving.has(i.node));
+    return {
+        nodes,
+        edges: sortEdges([...seen.values()]),
+        groups: { byLexicon: byLexiconOf(nodes) },
+        ...(imports && imports.length ? { imports } : {}),
+    };
+}
+/** T3 — annotate each edge with the producer attribute it references. */
+function toAttributes(ir) {
+    const nodeById = new Map(ir.nodes.map((n) => [n.id, n]));
+    const edges = ir.edges.map((e) => {
+        const node = nodeById.get(e.from);
+        const toAttr = node ? findRefAttr(node.attrs, e.to) : undefined;
+        return toAttr ? { ...e, toAttr } : { ...e };
+    });
+    return { ...ir, edges };
+}
+/** Find the attribute in a `{ $ref: "producer.attribute" }` envelope under attrs. */
+function findRefAttr(attrs, producer) {
+    let found;
+    const visit = (v) => {
+        if (found !== undefined || v === null || typeof v !== "object")
+            return;
+        if (Array.isArray(v)) {
+            for (const item of v)
+                visit(item);
+            return;
+        }
+        const ref = v.$ref;
+        if (typeof ref === "string") {
+            const dot = ref.indexOf(".");
+            if (dot > 0 && ref.slice(0, dot) === producer) {
+                found = ref.slice(dot + 1);
+                return;
+            }
+        }
+        for (const val of Object.values(v))
+            visit(val);
+    };
+    visit(attrs);
+    return found;
+}
+/**
+ * chant #1489 — the message to print when `--detail 3` changed nothing.
+ *
+ * T3 adds two things over T2: the full property tree on each node and the
+ * producer attribute on `$ref`-derived edges. A graph whose nodes carry no
+ * properties beyond the resource view AND whose edges reference nothing (they
+ * link by name or label convention) gains neither, so levels 2 and 3 come out
+ * byte-identical — which reads as a broken dial from any consumer stepping
+ * through the levels (behold#131 was filed over exactly this). Accepting a
+ * value that changes nothing without saying so is the bug; this names it.
+ *
+ * Returns the warning text, or undefined when detail 3 did add something.
+ * `base` is the pre-detail IR the caller already holds (the same one it fed
+ * `applyDetail`); the T2 view to compare against is derived here, so callers
+ * don't run the projection twice for a message. Pure — no I/O.
+ */
+export function detailInertNotice(base, detailed) {
+    if (JSON.stringify(detailed) !== JSON.stringify(toDeclarables(base)))
+        return undefined;
+    const edges = base.edges.length;
+    const why = edges === 0
+        ? "this graph has no edges at all"
+        : `none of this graph's ${edges} edge(s) reference a producer attribute — they link by name or label convention`;
+    return (`--detail 3 adds each node's full property tree and the producer attribute on reference edges, ` +
+        `but every node's properties already fit the resource view and ${why}, ` +
+        `so the output is identical to --detail 2.`);
+}

package/dist/graph-dot.js

@@ -0,0 +1,54 @@
+/**
+ * Render the graph IR as Graphviz DOT. Pure text — no `dot` needed to produce
+ * it. Two consumers: render directly with `dot -Tsvg` (mingrammer-style), or
+ * feed it to a layout engine for node positions that a custom painter draws
+ * (the rackattack pattern; see {@link toLayout}). See issue #497 / epic #492.
+ *
+ * Consumes whatever IR it is given, so `--detail` (and future `--lens`) flow
+ * through for free.
+ */
+export function toDot(ir) {
+    const lines = ["digraph chant {", "  rankdir=TB;", '  node [shape=box];'];
+    // Cluster by wave (component graph) when present, else by lexicon (entity graph).
+    const clusters = ir.groups.byWave ?? ir.groups.byLexicon;
+    const grouped = new Set();
+    if (clusters) {
+        for (const [name, members] of Object.entries(clusters)) {
+            lines.push(`  subgraph ${q(`cluster_${name}`)} {`);
+            lines.push(`    label=${q(name)};`);
+            for (const id of members) {
+                const node = ir.nodes.find((n) => n.id === id);
+                if (!node)
+                    continue;
+                grouped.add(id);
+                lines.push(`    ${nodeLine(node)}`);
+            }
+            lines.push("  }");
+        }
+    }
+    for (const node of ir.nodes) {
+        if (grouped.has(node.id))
+            continue;
+        lines.push(`  ${nodeLine(node)}`);
+    }
+    for (const e of ir.edges)
+        lines.push(`  ${edgeLine(e)}`);
+    lines.push("}");
+    return lines.join("\n") + "\n";
+}
+function nodeLine(node) {
+    const label = node.kind && node.kind !== node.id ? `${node.id}\n${node.kind}` : node.id;
+    return `${q(node.id)} [label=${q(label)}];`;
+}
+function edgeLine(e) {
+    const from = q(e.from);
+    const to = q(e.to);
+    const label = [e.viaAttr, e.toAttr].filter(Boolean).join(" → ");
+    return label ? `${from} -> ${to} [label=${q(label)}];` : `${from} -> ${to};`;
+}
+/** Quote a DOT identifier/label. Graphviz accepts any string in double quotes;
+ * a real newline becomes the DOT line-break escape. */
+function q(s) {
+    const esc = s.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n");
+    return `"${esc}"`;
+}