@intentius/chant 0.124.13 → 0.124.15

package/dist/graph-layout.js

@@ -0,0 +1,184 @@
+import { spawn } from "node:child_process";
+/** 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 const DEFAULT_NODE_SIZE = { w: 54, h: 36 };
+/** Spacing between adjacent nodes / ranks for the JS engine, in layout units. */
+const NODE_SEP = 28;
+const RANK_SEP = 44;
+/** 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 function toLayoutInput(ir, sizes = {}) {
+    return {
+        nodes: ir.nodes.map((n) => ({ id: n.id, ...(sizes[n.id] ?? DEFAULT_NODE_SIZE) })),
+        edges: ir.edges.map((e) => ({ from: e.from, to: e.to })),
+        groups: ir.groups?.byLexicon,
+    };
+}
+/** Drop duplicate / self edges — layout cares about structure, not multiplicity. */
+function layoutEdges(input) {
+    const seen = new Set();
+    const out = [];
+    for (const e of input.edges) {
+        if (e.from === e.to)
+            continue;
+        const key = `${e.from}\u0000${e.to}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(e);
+    }
+    out.sort((a, b) => a.from.localeCompare(b.from) || a.to.localeCompare(b.to));
+    return out;
+}
+/**
+ * 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 class DagreLayout {
+    constructor() {
+        this.name = "dagre";
+    }
+    async layout(input) {
+        const dagre = (await import("@dagrejs/dagre")).default;
+        const g = new dagre.graphlib.Graph();
+        g.setGraph({ rankdir: "TB", nodesep: NODE_SEP, ranksep: RANK_SEP });
+        g.setDefaultEdgeLabel(() => ({}));
+        const nodes = [...input.nodes].sort((a, b) => a.id.localeCompare(b.id));
+        for (const n of nodes)
+            g.setNode(n.id, { width: n.w, height: n.h });
+        for (const e of layoutEdges(input)) {
+            if (g.hasNode(e.from) && g.hasNode(e.to))
+                g.setEdge(e.from, e.to);
+        }
+        dagre.layout(g);
+        const gg = g.graph();
+        const width = gg.width ?? 0;
+        const height = gg.height ?? 0;
+        if (width === 0 || height === 0)
+            throw new Error("zero graph bounds");
+        const out = g.nodes().map((id) => {
+            const n = g.node(id);
+            return { id, x: n.x, y: height - n.y, w: n.width, h: n.height };
+        });
+        out.sort((a, b) => a.id.localeCompare(b.id));
+        return { width, height, nodes: out };
+    }
+}
+/** Layout via `dot -Tjson`. Opt-in; requires Graphviz (`brew install graphviz`).
+ * Lays out with real node sizes (`fixedsize`) and honours `groups` as clusters. */
+export class GraphvizLayout {
+    constructor() {
+        this.name = "graphviz";
+    }
+    async layout(input) {
+        return parseDotJson(await runDot(inputToDot(input)));
+    }
+}
+/** Resolve a layout engine by name. Defaults to dagre (no native dependency). */
+export function getLayoutEngine(name) {
+    if (name === "graphviz")
+        return new GraphvizLayout();
+    if (name && name !== "dagre") {
+        throw new Error(`unknown layout engine "${name}". Available: dagre (default), graphviz.`);
+    }
+    return new DagreLayout();
+}
+/** Build the DOT for a layout pass: real node footprints via `fixedsize`, so
+ * `dot` spaces for the painted size rather than its tiny default box. */
+function inputToDot(input) {
+    const lines = ["digraph chant {", "  rankdir=TB;", "  node [shape=box, fixedsize=true];"];
+    const byId = new Map(input.nodes.map((n) => [n.id, n]));
+    const grouped = new Set();
+    if (input.groups) {
+        for (const [group, members] of Object.entries(input.groups)) {
+            lines.push(`  subgraph ${q(`cluster_${group}`)} {`);
+            for (const id of members) {
+                const n = byId.get(id);
+                if (!n)
+                    continue;
+                grouped.add(id);
+                lines.push(`    ${dotNode(n)}`);
+            }
+            lines.push("  }");
+        }
+    }
+    for (const n of input.nodes) {
+        if (!grouped.has(n.id))
+            lines.push(`  ${dotNode(n)}`);
+    }
+    for (const e of layoutEdges(input))
+        lines.push(`  ${q(e.from)} -> ${q(e.to)};`);
+    lines.push("}");
+    return lines.join("\n") + "\n";
+}
+/** A DOT node line. `dot` sizes are inches; layout units are points (72/inch). */
+function dotNode(n) {
+    return `${q(n.id)} [width=${(n.w / 72).toFixed(4)}, height=${(n.h / 72).toFixed(4)}];`;
+}
+function q(s) {
+    return `"${s.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+function runDot(dot) {
+    return new Promise((resolve, reject) => {
+        let proc;
+        try {
+            proc = spawn("dot", ["-Tjson"], { stdio: ["pipe", "pipe", "pipe"] });
+        }
+        catch (err) {
+            reject(installHint(err));
+            return;
+        }
+        let out = "";
+        let errOut = "";
+        proc.stdout.on("data", (d) => (out += d));
+        proc.stderr.on("data", (d) => (errOut += d));
+        proc.on("error", (err) => reject(installHint(err)));
+        proc.on("close", (code) => {
+            if (code !== 0)
+                reject(new Error(`dot exited ${code}: ${errOut.trim()}`));
+            else
+                resolve(out);
+        });
+        proc.stdin.write(dot);
+        proc.stdin.end();
+    });
+}
+function installHint(err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return new Error(`could not run 'dot' (${msg}). Graphviz is required for --layout-engine graphviz — ` +
+        `install it with 'brew install graphviz', or drop the flag to use the default dagre engine ` +
+        `(no native dependency).`);
+}
+/** Parse `dot -Tjson` output into a {@link Layout}. Pure; exported for testing. */
+export function parseDotJson(json) {
+    const parsed = JSON.parse(json);
+    const bb = (parsed.bb ?? "").split(",");
+    if (bb.length !== 4)
+        throw new Error(`bad bounding box ${parsed.bb}`);
+    const width = num(bb[2]);
+    const height = num(bb[3]);
+    if (width === 0 || height === 0)
+        throw new Error("zero graph bounds");
+    const nodes = [];
+    for (const o of parsed.objects ?? []) {
+        if (!o.name || !o.pos)
+            continue;
+        const p = o.pos.split(",");
+        if (p.length !== 2)
+            continue;
+        const node = { id: o.name, x: num(p[0]), y: num(p[1]) };
+        // dot reports width/height in inches; echo as layout units (points).
+        if (o.width)
+            node.w = num(o.width) * 72;
+        if (o.height)
+            node.h = num(o.height) * 72;
+        nodes.push(node);
+    }
+    nodes.sort((a, b) => a.id.localeCompare(b.id));
+    return { width, height, nodes };
+}
+function num(s) {
+    const f = Number.parseFloat(s.trim());
+    return Number.isFinite(f) ? f : 0;
+}

package/dist/graph-lens.js

@@ -0,0 +1,105 @@
+const KINDS = new Set(["lexicon", "stack", "blast"]);
+/** Parse a `--lens` spec. Throws a descriptive Error on a malformed spec. */
+export function parseLens(spec, opts = {}) {
+    const colon = spec.indexOf(":");
+    if (colon <= 0 || colon === spec.length - 1) {
+        throw new Error(`Invalid --lens "${spec}". Expected <kind>:<target>, e.g. lexicon:gcp or blast:vpc.`);
+    }
+    const kind = spec.slice(0, colon);
+    const target = spec.slice(colon + 1);
+    if (!KINDS.has(kind)) {
+        throw new Error(`Unknown lens "${kind}". Expected one of: ${[...KINDS].join(", ")}.`);
+    }
+    // For blast, default to both directions when neither flag is given.
+    const both = !opts.up && !opts.down;
+    return {
+        kind: kind,
+        target,
+        up: opts.up ?? both,
+        down: opts.down ?? both,
+    };
+}
+/** Apply a lens to the IR. Throws a descriptive Error when the target matches nothing. */
+export function applyLens(ir, lens) {
+    const keep = lens.kind === "blast" ? blastSet(ir, lens) : partitionSet(ir, lens);
+    return subgraph(ir, keep);
+}
+/** Node ids for a lexicon/stack lens. */
+function partitionSet(ir, lens) {
+    if (lens.kind === "stack") {
+        const members = ir.groups.byStack?.[lens.target] ?? ir.groups.byLexicon?.[lens.target];
+        if (members && members.length)
+            return new Set(members);
+        // Fall through to a direct scan if groups are absent.
+    }
+    const keep = new Set();
+    for (const n of ir.nodes)
+        if (n.lexicon === lens.target)
+            keep.add(n.id);
+    if (keep.size === 0) {
+        throw new Error(`No nodes match lens ${lens.kind}:${lens.target}.`);
+    }
+    return keep;
+}
+/** Node ids in the transitive neighbourhood of a node. */
+function blastSet(ir, lens) {
+    if (!ir.nodes.some((n) => n.id === lens.target)) {
+        throw new Error(`No node "${lens.target}" for lens blast:${lens.target}.`);
+    }
+    const out = new Map(); // from -> [to]  (depends-on)
+    const inc = new Map(); // to -> [from]  (depended-on-by)
+    const push = (m, k, v) => {
+        const arr = m.get(k);
+        if (arr)
+            arr.push(v);
+        else
+            m.set(k, [v]);
+    };
+    for (const e of ir.edges) {
+        push(out, e.from, e.to);
+        push(inc, e.to, e.from);
+    }
+    const keep = new Set([lens.target]);
+    if (lens.up)
+        walk(lens.target, out, keep);
+    if (lens.down)
+        walk(lens.target, inc, keep);
+    return keep;
+}
+function walk(start, adj, keep) {
+    const stack = [start];
+    while (stack.length) {
+        const cur = stack.pop();
+        for (const next of adj.get(cur) ?? []) {
+            if (!keep.has(next)) {
+                keep.add(next);
+                stack.push(next);
+            }
+        }
+    }
+}
+/** Restrict the IR to a node set: keep internal edges, rebuild groups. */
+function subgraph(ir, keep) {
+    var _a, _b;
+    const nodes = ir.nodes.filter((n) => keep.has(n.id));
+    const edges = ir.edges.filter((e) => keep.has(e.from) && keep.has(e.to));
+    const byLexicon = {};
+    const byComposite = {};
+    for (const n of nodes) {
+        (byLexicon[_a = n.lexicon] ?? (byLexicon[_a] = [])).push(n.id);
+        if (n.compositeInstance)
+            (byComposite[_b = n.compositeInstance] ?? (byComposite[_b] = [])).push(n.id);
+    }
+    const groups = {};
+    if (Object.keys(byLexicon).length)
+        groups.byLexicon = sortGroups(byLexicon);
+    if (Object.keys(byComposite).length)
+        groups.byComposite = sortGroups(byComposite);
+    return { nodes, edges, groups };
+}
+function sortGroups(rec) {
+    const out = {};
+    for (const k of Object.keys(rec).sort())
+        out[k] = rec[k].sort();
+    return out;
+}

package/dist/graph-mermaid.js

@@ -0,0 +1,83 @@
+/**
+ * Render the graph IR as a Mermaid `flowchart`. Mermaid is the zero-install
+ * default — it renders in GitHub, docs, and browsers with no native dependency,
+ * so `chant graph --format mermaid` gives a diagram out of the box without the
+ * standalone painter. Lower fidelity than a custom painter, but portable.
+ *
+ * Consumes whatever IR it is given, so it honours `--detail` and `--lens` for
+ * free (those are IR → IR transforms). See issue #496 / epic #492.
+ *
+ * Known limits: Mermaid owns layout, so there is little control over node
+ * placement, and very large graphs get hard to read — that is the trade-off for
+ * zero-install portability. Reach for the graphviz/custom-painter path (#497,
+ * pinhole) when fidelity matters.
+ */
+export function toMermaid(ir) {
+    const ids = new Map(); // logical name -> mermaid-safe id
+    for (const n of ir.nodes)
+        safeId(n.id, ids);
+    const lines = ["flowchart TD"];
+    // Cluster by wave (component graph) when present, else by lexicon (entity
+    // graph); nodes outside any group fall through to the top level. Both are
+    // sorted, so output is deterministic.
+    const clusters = ir.groups.byWave ?? ir.groups.byLexicon;
+    const clusterPrefix = ir.groups.byWave ? "wave" : "lex";
+    const grouped = new Set();
+    if (clusters) {
+        for (const [name, members] of Object.entries(clusters)) {
+            lines.push(`  subgraph ${safeId(`${clusterPrefix}_${name}`, ids)}[${quote(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, ids)}`);
+            }
+            lines.push("  end");
+        }
+    }
+    for (const node of ir.nodes) {
+        if (grouped.has(node.id))
+            continue;
+        lines.push(`  ${nodeLine(node, ids)}`);
+    }
+    for (const e of ir.edges) {
+        lines.push(`  ${edgeLine(e, ids)}`);
+    }
+    return lines.join("\n") + "\n";
+}
+function nodeLine(node, ids) {
+    const id = safeId(node.id, ids);
+    const parts = [node.id];
+    if (node.kind && node.kind !== node.id)
+        parts.push(node.kind);
+    return `${id}[${quote(parts.join("\n"))}]`;
+}
+function edgeLine(e, ids) {
+    const from = safeId(e.from, ids);
+    const to = safeId(e.to, ids);
+    const label = [e.viaAttr, e.toAttr].filter(Boolean).join(" → ");
+    return label ? `${from} -->|${quote(label)}| ${to}` : `${from} --> ${to}`;
+}
+/** Map an arbitrary logical name to a stable, unique Mermaid-safe node id. */
+function safeId(raw, ids) {
+    const existing = ids.get(raw);
+    if (existing)
+        return existing;
+    let base = raw.replace(/[^A-Za-z0-9_]/g, "_");
+    if (base === "" || /^[0-9]/.test(base))
+        base = `n_${base}`;
+    const taken = new Set(ids.values());
+    let candidate = base;
+    let i = 1;
+    while (taken.has(candidate))
+        candidate = `${base}_${i++}`;
+    ids.set(raw, candidate);
+    return candidate;
+}
+/** Quote a Mermaid label, escaping markup and turning newlines into <br/>. */
+function quote(text) {
+    const esc = (s) => s.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+    const body = text.split("\n").map(esc).join("<br/>");
+    return `"${body}"`;
+}

package/dist/graph-ops.js

@@ -0,0 +1,39 @@
+import { basename, resolve } from "node:path";
+import { discoverOps } from "./op/discover.js";
+import { Op } from "./op/builders.js";
+import { setProvenance } from "./provenance.js";
+/**
+ * #1675 — the graph IR is built from `discover(sourceDir)`, but the Op
+ * convention keeps `*.op.ts` files OUTSIDE `sourceDir` (`ops/` or the project
+ * root beside `sourceDir: "src"`), and `chant op` / `chant graph` find them via
+ * {@link discoverOps}, which scans from the git root. Join the two scopes: every
+ * Op `discoverOps` finds that discovery did not already load becomes a
+ * `Chant::Op` entity in the map, keyed the way discovery keys a default
+ * export (the file's basename sans `.op.ts`), so the IR carries the declared
+ * DAG whatever the layout. Ops discovery already loaded (same file) are left
+ * alone. Returns the op-discovery errors for the caller to surface.
+ */
+export async function mergeProjectOps(entities, sourceFiles, projectPath) {
+    const added = [];
+    let found;
+    try {
+        found = await discoverOps({ cwd: projectPath });
+    }
+    catch (err) {
+        // Not a git checkout — nothing beyond sourceDir to join.
+        return { added, errors: [err instanceof Error ? err.message : String(err)] };
+    }
+    const loaded = new Set(sourceFiles.map((f) => resolve(f)));
+    for (const { config, filePath } of found.ops.values()) {
+        if (loaded.has(resolve(filePath)))
+            continue;
+        const key = basename(filePath).replace(/\.ts$/, "").replace(/\.op$/, "");
+        if (entities.has(key))
+            continue;
+        const entity = Op(config);
+        setProvenance(entity, { sourceFile: resolve(filePath) });
+        entities.set(key, entity);
+        added.push(key);
+    }
+    return { added, errors: found.errors };
+}

package/dist/graph-refs.js

@@ -0,0 +1,156 @@
+function toStr(v) {
+    if (typeof v === "string")
+        return v;
+    if (typeof v === "number" || typeof v === "boolean")
+        return String(v);
+    return undefined;
+}
+/**
+ * Read all scalar values at an attr path. Supports nested keys (`a.b`) and array
+ * fan-out (`arr[]`, `arr[].id`). Returns every scalar found — a path through an
+ * array yields one value per element.
+ */
+export function readPath(obj, path) {
+    let cur = [obj];
+    for (const part of path.split(".")) {
+        const isArr = part.endsWith("[]");
+        const key = isArr ? part.slice(0, -2) : part;
+        const next = [];
+        for (const c of cur) {
+            if (c == null || typeof c !== "object")
+                continue;
+            const val = c[key];
+            if (isArr) {
+                if (Array.isArray(val))
+                    next.push(...val);
+            }
+            else if (val !== undefined) {
+                next.push(val);
+            }
+        }
+        cur = next;
+    }
+    const out = [];
+    for (const c of cur) {
+        const s = toStr(c);
+        if (s !== undefined)
+            out.push(s);
+    }
+    return out;
+}
+/** Merge several lexicons' catalogs into one (concatenate identities + refs). */
+export function mergeCatalogs(catalogs) {
+    return {
+        identities: catalogs.flatMap((c) => c.identities),
+        refs: catalogs.flatMap((c) => c.refs),
+    };
+}
+/**
+ * Reconstruct edges + containment from live nodes and a catalog. Pure and
+ * deterministic. Matching is exact on identifier value; identifier collisions
+ * across kinds are disambiguated by `targetKind`. Self-references are dropped.
+ */
+export function reconstructEdges(nodes, catalog) {
+    // Identity index: identifier value → the node(s) that own it.
+    const index = new Map();
+    const add = (value, id, kind) => {
+        (index.get(value) ?? index.set(value, []).get(value)).push({ id, kind });
+    };
+    for (const node of nodes) {
+        // Every node is identified by its own logical id — so references resolved to
+        // a logical id (e.g. a CloudFormation `{Ref: LogicalId}` from exportResources,
+        // #784) match directly — plus its physical id and any catalog identity attrs.
+        add(node.id, node.id, node.kind);
+        if (node.physicalId)
+            add(node.physicalId, node.id, node.kind);
+        for (const rule of catalog.identities) {
+            if (rule.kind !== node.kind)
+                continue;
+            for (const p of rule.ids)
+                for (const v of readPath(node.attrs, p))
+                    add(v, node.id, node.kind);
+        }
+    }
+    const edges = [];
+    const containment = [];
+    const containmentEdges = [];
+    const seenContEdge = new Set();
+    const dangling = [];
+    const seenEdge = new Set();
+    const seenCont = new Set();
+    for (const node of nodes) {
+        for (const rule of catalog.refs) {
+            if (rule.from !== node.kind)
+                continue;
+            for (const value of readPath(node.attrs, rule.path)) {
+                const candidates = index.get(value) ?? [];
+                const match = rule.targetKind ? candidates.find((c) => c.kind === rule.targetKind) : candidates[0];
+                if (!match) {
+                    dangling.push({ from: node.id, path: rule.path, value, ...(rule.targetKind ? { targetKind: rule.targetKind } : {}) });
+                    continue;
+                }
+                if (match.id === node.id)
+                    continue; // self-reference (e.g. an SG rule to its own group)
+                const pushEdge = (via) => {
+                    const k = `${node.id}|${match.id}|${via}`;
+                    if (seenEdge.has(k))
+                        return;
+                    seenEdge.add(k);
+                    edges.push({ from: node.id, to: match.id, kind: "ref", viaAttr: via });
+                };
+                if (rule.relation === "containment") {
+                    const k = `${node.id}|${match.id}`;
+                    if (!seenCont.has(k)) {
+                        seenCont.add(k);
+                        containment.push({ child: node.id, parent: match.id, ...(rule.label ? { label: rule.label } : {}) });
+                    }
+                    // Traversable by construction. The attribute the containment was read
+                    // through is its traversal name, so `<-attr:` can still discriminate
+                    // between two ways of being inside something.
+                    const via = rule.viaAttr ?? rule.path;
+                    const ke = `${node.id}|${match.id}|${via}`;
+                    if (!seenContEdge.has(ke)) {
+                        seenContEdge.add(ke);
+                        containmentEdges.push({ from: node.id, to: match.id, kind: "ref", viaAttr: via });
+                    }
+                    // A containment relation is a boundary hint, not an edge — unless the
+                    // rule declares a traversal name (#1275). A fold's first hop is
+                    // sometimes exactly a containment ("an instance is in a subnet"), and
+                    // it must be traversable without duplicating the rule as a reference
+                    // and drawing the line twice.
+                    if (rule.viaAttr)
+                        pushEdge(rule.viaAttr);
+                }
+                else {
+                    // Traversal name wins over the rendering label: the labels are
+                    // human-facing ("sg", "via"), and a fold matches provider attribute
+                    // names (#1275).
+                    pushEdge(rule.viaAttr ?? rule.label ?? rule.path);
+                }
+            }
+        }
+    }
+    edges.sort((a, b) => `${a.from}|${a.to}|${a.viaAttr}`.localeCompare(`${b.from}|${b.to}|${b.viaAttr}`));
+    containmentEdges.sort((a, b) => `${a.from}|${a.to}|${a.viaAttr}`.localeCompare(`${b.from}|${b.to}|${b.viaAttr}`));
+    containment.sort((a, b) => `${a.child}|${a.parent}`.localeCompare(`${b.child}|${b.parent}`));
+    dangling.sort((a, b) => `${a.from}|${a.path}|${a.value}`.localeCompare(`${b.from}|${b.path}|${b.value}`));
+    return { edges, containment, containmentEdges, dangling };
+}
+/**
+ * Invert containment pairs into grouping metadata (#779): container node id → the
+ * node ids directly inside it. The result is the `IRGroups.byContainer` shape a
+ * renderer draws as boundary boxes. It represents the full nesting *flatly* — a
+ * subnet is both a member of its VPC's entry and a key with its own members —
+ * so a boundary-box renderer recurses it (VPC ⊃ subnet ⊃ resources). Sorted for
+ * determinism.
+ */
+export function containmentGroups(pairs) {
+    const byParent = new Map();
+    for (const { child, parent } of pairs) {
+        (byParent.get(parent) ?? byParent.set(parent, new Set()).get(parent)).add(child);
+    }
+    const out = {};
+    for (const parent of [...byParent.keys()].sort())
+        out[parent] = [...byParent.get(parent)].sort();
+    return out;
+}

package/dist/held-elsewhere.js

@@ -0,0 +1,87 @@
+/**
+ * `heldElsewhere` — a typed, per-property declaration that a field belongs to
+ * something else once the first apply happens (chant #2162).
+ *
+ * An autoscaler owns a Deployment's `replicas` after the first apply. A
+ * controller writes an annotation on every sync. An operator was granted one
+ * knob deliberately. None of these are drift, and reconciling them back to
+ * whatever chant last declared would fight the thing that is actually
+ * supposed to own the field.
+ *
+ * Terraform's answer is `lifecycle { ignore_changes = [...] }`: a list of
+ * strings, carrying no reason, invisible once written. This is the typed
+ * alternative — a marker written where the property's value would go, so a
+ * lexicon's generated types check it the same way they check any other value,
+ * and it cannot be attached to a property that does not exist.
+ *
+ * This is not a suppression comment. `chant-ignore` (#2111) hides a *lint*
+ * finding about source; a `heldElsewhere` marker is a fact about who operates
+ * a field at *runtime*, so it lives in the typed declaration, where
+ * `chant lifecycle plan` and `chant lifecycle diff --live` can render it,
+ * rather than in a comment only a linter reads.
+ */
+/**
+ * Runtime-only marker, symbol-keyed so it never collides with a real
+ * property actually named `by` or `reason` and never serializes by accident
+ * through `JSON.stringify` or `Object.entries` (which do not visit symbol
+ * keys) — the two places a stray plain-object marker would otherwise leak
+ * into a snapshot or a wire payload unnoticed.
+ */
+export const HELD_ELSEWHERE_MARKER = Symbol.for("chant.heldElsewhere");
+/**
+ * Declare a property held by something else after the first apply.
+ *
+ * Typed `T` — the property's own declared type — rather than
+ * `HeldElsewhereMarker`, so it type-checks in exactly the position the
+ * property's real value would go: `replicas: heldElsewhere({ by: "hpa",
+ * reason: "the autoscaler owns replicas after the first apply" })` against a
+ * generated `replicas?: number` typechecks the same way `replicas: 3` does,
+ * and writing it against a property that does not exist on the resource's
+ * props is an excess-property error like any other.
+ *
+ * The runtime value is the marker object, not a `T` — this function tells
+ * TypeScript otherwise on purpose. Every consumer that must tell the two
+ * apart checks {@link isHeldElsewhere} before trusting a declared value's
+ * real shape: the synth-time serializer (`serializer-walker.ts`, which omits
+ * the field from the applied payload so the property is never sent — the
+ * provider defaults it once at creation, and the holder owns it from there)
+ * and the deep-diff declared side (`deep-observation.ts`/`deep-diff.ts`,
+ * which reports a live difference as held rather than as drift).
+ */
+export function heldElsewhere(opts) {
+    const marker = {
+        [HELD_ELSEWHERE_MARKER]: true,
+        by: opts.by,
+        reason: opts.reason,
+    };
+    return marker;
+}
+/**
+ * True when `value` is a {@link HeldElsewhereMarker} — the runtime shape a
+ * `heldElsewhere()` call produces, wherever it ends up (a resource's own
+ * prop, nested inside a property-kind Declarable's props).
+ */
+export function isHeldElsewhere(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        value[HELD_ELSEWHERE_MARKER] === true);
+}
+/**
+ * JSON-safe tag a held marker normalizes to (see `deep-observation.ts`) so
+ * its identity survives normalization, `flattenDeepProperties`, and a
+ * `--json` round-trip. The symbol marker above does not serialize and
+ * `Object.entries` does not enumerate it, so without a JSON-safe stand-in the
+ * normalization pass would flatten `{ by, reason }` into two ordinary leaf
+ * paths instead of keeping the marker recognizable as one value.
+ */
+export const HELD_ELSEWHERE_TAG = "chant:heldElsewhere";
+/** Normalize a runtime marker to its JSON-safe tagged form. */
+export function normalizeHeldElsewhere(marker) {
+    return { heldElsewhere: HELD_ELSEWHERE_TAG, by: marker.by, reason: marker.reason };
+}
+/** True when `value` is the normalized, JSON-safe tagged form of a held marker. */
+export function isNormalizedHeldElsewhere(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        value.heldElsewhere === HELD_ELSEWHERE_TAG);
+}