@intentius/chant 0.124.13 → 0.124.15

package/dist/behaviour-kinds.js

@@ -0,0 +1,172 @@
+/**
+ * What an engine is asked to price, and who gets to say so (#2382).
+ *
+ * `./behaviour.ts` says what a prediction may mean and `./behaviour-http.ts`
+ * carries one to an engine. Between them sits a question neither answers: for
+ * a given entity in a project's graph, what *kind* of thing is it, and is it
+ * something an engine prices at all? #2357 answered it with one table in one
+ * lexicon, keyed by every other lexicon's entity types. That table described
+ * 117 types it did not own, and the capability rode on whether an optional
+ * package happened to be installed — which gave a consumer a fourth
+ * outcome this contract never named: no overlay, no refusal, and no reason.
+ *
+ * So the resolution lives here, where every other part of the feature already
+ * does, and the *rows* are contributed by the lexicon that owns the substrate.
+ * Core learns that an entity has an engine kind. It never learns which.
+ *
+ * ## Why rows are safe to make optional when the capability is not
+ *
+ * A lexicon that is not installed declared no entities of its types, so it has
+ * no rows to contribute and nothing goes missing: the estate simply contains
+ * nothing of that substrate. That is the opposite of the capability itself
+ * being optional, where an uninstalled package means an estate full of
+ * entities nobody will say anything about.
+ *
+ * ## The three things a lexicon can say about its own types
+ *
+ *   - **mapped** — this type is a `compute`/`database`/`queue`, and its size
+ *     is read from this declared property, in the provider's own vocabulary.
+ *   - **declared unmapped** — this type is real and carries no rate an engine
+ *     can quote, with the sentence saying why. A grant is not a resource; a
+ *     boundary is not a node; a meter chant cannot read is not a figure.
+ *   - **nothing priced** — nothing this lexicon declares is an estate an
+ *     engine prices, once, for the whole substrate. A CI workflow is not an
+ *     estate, and a policy language has nothing to saturate.
+ *
+ * A type a contributor claims and has no row for is `unknown-type`: the one
+ * verdict that is a defect rather than a decision, and the reason the three
+ * above are distinct states instead of one absent row.
+ */
+const ENGINE_KIND_WITNESS = {
+    compute: true,
+    serverless: true,
+    "control-plane": true,
+    database: true,
+    cache: true,
+    queue: true,
+    "object-store": true,
+    "block-store": true,
+    "load-balancer": true,
+    cdn: true,
+};
+/**
+ * Every legal {@link EngineKind}, derived from a total witness rather than
+ * written out by hand — the construction `behaviour.ts` uses for
+ * `BEHAVIOUR_BASES`, for the same reason: a hand-written array is checked for
+ * having legal members and never for having all of them.
+ */
+export const ENGINE_KINDS = Object.keys(ENGINE_KIND_WITNESS);
+/** True when `value` is a legal {@link EngineKind}. */
+export function isEngineKind(value) {
+    return typeof value === "string" && ENGINE_KINDS.includes(value);
+}
+/** chant's own build-time entities, which no lexicon owns and nothing bills. */
+const CHANT_PSEUDO_PREFIX = "chant:";
+/**
+ * Resolve one entity type against the contributed rows.
+ *
+ * Total by construction: every type reaches one of the four states and there
+ * is no fifth arm for "dropped". That is the property the request builder
+ * relies on to guarantee every entity it was asked about lands in `entities`
+ * or in `unpredicted`.
+ *
+ * `hasOwnProperty` rather than a truthiness check, because these are plain
+ * object literals and an entity named after a prototype member would otherwise
+ * resolve to a mapping that does not exist.
+ */
+export function coverageFor(contributors, entityType, props) {
+    if (entityType.startsWith(CHANT_PSEUDO_PREFIX)) {
+        return {
+            status: "declared-unmapped",
+            reason: "one of chant's own build-time entities rather than something an account holds — a declared " +
+                "output, or a default that rides onto the resources beside it. It is never created and never " +
+                "billed",
+        };
+    }
+    const owner = contributors.find((c) => c.prefixes.some((p) => entityType.startsWith(p)));
+    if (!owner)
+        return { status: "unknown-type" };
+    if (owner.nothingPriced)
+        return { status: "provider-not-modelled", substrate: owner.nothingPriced };
+    const type = owner.resolveType ? owner.resolveType(entityType, props) : entityType;
+    if (type === undefined)
+        return { status: "unknown-type" };
+    if (owner.mapped && Object.prototype.hasOwnProperty.call(owner.mapped, type)) {
+        const row = owner.mapped[type];
+        return { status: "mapped", mapping: { ...row, provider: row.provider ?? owner.provider } };
+    }
+    if (owner.unmapped && Object.prototype.hasOwnProperty.call(owner.unmapped, type)) {
+        return { status: "declared-unmapped", reason: owner.unmapped[type] };
+    }
+    // Before `unmappedWhen`, and after both tables: a row is this lexicon's
+    // decision about a type it models, and a substrate boundary is a statement
+    // about types it never will. A type inside the modelled substrate with no
+    // row falls past both and stays the defect it is.
+    const elsewhere = owner.notModelledWhen?.(type);
+    if (elsewhere !== undefined)
+        return { status: "provider-not-modelled", substrate: elsewhere };
+    const late = owner.unmappedWhen?.(type);
+    if (late !== undefined)
+        return { status: "declared-unmapped", reason: late };
+    return { status: "unknown-type" };
+}
+/**
+ * The contributor that owns an entity type, or `undefined` when nobody claims
+ * it. Exported because a caller that has already resolved a verdict often
+ * needs the owner too — to name it in a detail, or to label the entity the way
+ * its own lexicon would.
+ */
+export function ownerOf(contributors, entityType) {
+    return contributors.find((c) => c.prefixes.some((p) => entityType.startsWith(p)));
+}
+/**
+ * How a detail names an entity's kind. The chant entity type, except where the
+ * owning lexicon keys its rows on something else: `Terraform::Resource` names
+ * nothing a reader can act on, and the provider type is the kind, so the label
+ * is `aws_vpc (Terraform::Resource)`.
+ */
+export function coverageLabel(contributors, entityType, props) {
+    const owner = ownerOf(contributors, entityType);
+    if (!owner?.resolveType)
+        return entityType;
+    const type = owner.resolveType(entityType, props);
+    return type === undefined || type === entityType ? entityType : `${type} (${entityType})`;
+}
+/**
+ * The `detail` an `unpredicted` entry carries, naming the kind in every case.
+ *
+ * The kind is named here, in the per-entity decline, because that is the only
+ * place in this contract with a per-entity axis: a `BehaviourRefusalReport` is
+ * a statement about the whole run and has no `entities` key by design, so a
+ * report-level refusal for one unmapped bucket would take the other nineteen
+ * entities' figures down with it.
+ *
+ * The `unknown-type` arm names the lexicon that owns the type rather than a
+ * file path, because since #2382 the row belongs to whichever lexicon defines
+ * the type, and that is the thing a reader needs to be told.
+ */
+export function unmappedDetail(label, verdict, owner) {
+    if (verdict.status === "declared-unmapped") {
+        return `${label} is declared unmapped by the ${owner?.provider ?? "declaring"} coverage rows: ${verdict.reason}.`;
+    }
+    if (verdict.status === "provider-not-modelled") {
+        return (`${label} belongs to ${verdict.substrate}, which nothing here models. A substrate is added by ` +
+            "the lexicon that owns its types contributing rows for them, not by adding a row elsewhere. " +
+            "This is a stated boundary rather than a gap — nothing needs filing.");
+    }
+    const where = owner
+        ? `the lexicon that owns ${owner.prefixes.join(", ")}`
+        : "the lexicon that owns this entity type";
+    return (`${label} has no row in any contributed coverage table. It is a type from a substrate that is ` +
+        "modelled, and is neither mapped to an engine kind nor declared unmapped, so nothing has an " +
+        `opinion about it rather than a stated one. Add a row in ${where}.`);
+}
+/**
+ * Compare two strings by UTF-16 code unit.
+ *
+ * Not `localeCompare`, which reads the ambient locale: under `sv-SE` and
+ * `et-EE` it orders these type names differently from `en-US`, which would
+ * make the request's bytes — and therefore any golden fixture, and therefore
+ * any declared-versus-live delta — a function of the machine that built them.
+ */
+export const byCodeUnit = (a, b) => (a < b ? -1 : a > b ? 1 : 0);

package/dist/behaviour-overlay.js

@@ -0,0 +1,50 @@
+/**
+ * A behaviour result, in the shape the overlay carries it (#2360, epic #2355).
+ *
+ * behold reads a prediction off `chant graph --live --overlay`'s IR and never
+ * calls an engine itself: one block per entity on `attrs._behaviour`, the
+ * channel every other live fact rides on (`_status`, `_release`, `_carve`),
+ * and the graph-level half on `meta._behaviour`. Its reader
+ * (`behold/src/behaviour.ts`, `validateBehaviourMeta`) takes `meta._behaviour`
+ * as `{ engine?, version?, at?, total?, refusal? }` and short-circuits on
+ * `refusal`: a refusal is present *instead of* the engine, and a meta with
+ * neither is dropped as "meta.engine missing".
+ *
+ * That last sentence is the whole reason this module exists. What goes on
+ * `meta._behaviour` for a refusal is the **entire** {@link BehaviourRefusalReport}
+ * — `{ behaviour: "v1", refusal: { cause, reason, remedy, source? } }` — and
+ * not the bare {@link BehaviourRefusal} inside it. A bare refusal has `reason`
+ * and `remedy` at its top level and no `refusal` key, so behold's reader finds
+ * no refusal, then finds no engine, and drops the meta with a diagnostic that
+ * names the wrong thing. The contract doc said the wrong type once
+ * (#2360's second review comment); this is written against the reader.
+ *
+ * For a report, `meta._behaviour` is the report's own `meta`: engine, version,
+ * `at`, an optional `total`, and `edgeCoverage`, which behold's reader ignores
+ * and a consumer that wants to know what a resilience verdict was computed
+ * over reads. Each entity's block goes on its node verbatim — the contract's
+ * {@link PredictedBehaviour} is field for field the block behold validates.
+ *
+ * Pure. Nothing here calls an engine; the result is whatever a lexicon's
+ * `predictBehaviour` returned.
+ */
+import { isBehaviourRefusalReport, } from "./behaviour.js";
+/** The attribute a behaviour block rides on, on a node and on the graph's meta. */
+export const BEHAVIOUR_OVERLAY_ATTR = "_behaviour";
+/**
+ * Project a result onto the overlay's channels.
+ *
+ * A refusal keeps its envelope. behold reads `meta._behaviour.refusal`, and
+ * the envelope is also what makes the value self-describing to anything else
+ * reading the IR: `behaviour: "v1"` says which contract the refusal is in.
+ */
+export function behaviourOverlay(result) {
+    if (isBehaviourRefusalReport(result)) {
+        return { meta: { [BEHAVIOUR_OVERLAY_ATTR]: result }, attrs: {} };
+    }
+    const attrs = Object.create(null);
+    for (const [name, block] of Object.entries(result.entities)) {
+        attrs[name] = { [BEHAVIOUR_OVERLAY_ATTR]: block };
+    }
+    return { meta: { [BEHAVIOUR_OVERLAY_ATTR]: result.meta }, attrs };
+}

package/dist/behaviour-predict.js

@@ -0,0 +1,188 @@
+/**
+ * `predictBehaviour()` — the fourth
+ * observation method (#2357, contract #2356).
+ *
+ * The whole method is four moves, in this order, and the order is the contract:
+ *
+ *  1. **Screen the request.** `screenBehaviourRequest` and nothing else. It is
+ *     the only entry point, and calling `assertNoCredentialInOptions` instead
+ *     applies one rule of three — that was review finding F1 on #2365, where a
+ *     `ghp_…` past the walk's depth budget and an `awsSecretAccessKey` in
+ *     `props` both went out with the request.
+ *  2. **Resolve the engine.** `behaviourEngineFrom`, walking
+ *     `CHANT_BEHAVIOUR_ENGINE_BEHAVIOUR_SCOPE` → `CHANT_BEHAVIOUR_ENGINE` →
+ *     `BEHAVIOUR_ENGINE`. Nothing named means `noBehaviourEngineRefusal`, and
+ *     it happens **before** anything is priced: a lexicon that prices first and
+ *     checks the engine afterwards has already decided what zero means.
+ *  3. **Build the request.** `buildEngineRequest`, offline and pure
+ *     (`./request.ts`).
+ *  4. **Ask, and translate the answer.** One {@link EngineOutcome} onto the
+ *     contract's builders. A refusal comes back from the transport already
+ *     built — the contract's transport (#2373) names the condition and the
+ *     variable where the wire was seen — and is returned as it stands; this
+ *     file holds no switch over causes. No figure is ever computed here either:
+ *     this file has no arithmetic on money in it at all, and that is not an
+ *     accident. The epic's first rule is that a missing engine produces a
+ *     refusal and "never a locally faked number", and the surest way to keep
+ *     that true is for the code that would have faked it not to exist.
+ *
+ * ## Every entity lands somewhere
+ *
+ * `behaviourReport` refuses a report that leaves a name in neither map, so the
+ * loop below has no `continue` that drops one. Four ways an entity can end up
+ * unpredicted, and each names a different thing:
+ *
+ * | Outcome | Reason | Means |
+ * |---|---|---|
+ * | the coverage table declares it unmapped | `unsupported-kind` | chant looked, and this kind has no rate |
+ * | the coverage table has never seen it | `unsupported-kind` | chant has not looked; the detail says so and where to add the row |
+ * | the engine declined it | `read-failed` | chant asked and the engine could not answer |
+ * | the engine answered about neither | `read-failed` | the engine lost it, and this says so rather than hiding it |
+ *
+ * The last row is the one that would otherwise be silent. An engine that
+ * returns figures for eleven of twelve nodes and mentions the twelfth nowhere
+ * is a bug in the engine, and an estate that quietly renders eleven nodes is
+ * how it stays a bug.
+ */
+import { behaviourReport, behaviourEngineFrom, noBehaviourEngineRefusal, predictedRate, screenBehaviourRequest, unreachableBehaviourEngineRefusal, } from "./behaviour.js";
+import { buildEngineRequest } from "./behaviour-request.js";
+import { BEHAVIOUR_SCOPE, defaultConnect } from "./behaviour-engine.js";
+export { BEHAVIOUR_SCOPE };
+/**
+ * Build core's `predictBehaviour`, with the environment and the
+ * transport injected.
+ *
+ * Injected rather than read from module scope so a test can drive the whole
+ * method — screen, resolve, serialize, translate — against a fixture engine
+ * without touching `process.env`, which is what the shared conformance suite's
+ * probes need in order to ask the same request twice and compare.
+ */
+export function createBehaviourPredict(deps = {}) {
+    const env = deps.env ?? process.env;
+    const kinds = deps.kinds ?? [];
+    const connect = deps.connect ?? defaultConnect;
+    return async function predictBehaviour(options) {
+        const unsafe = screenBehaviourRequest(BEHAVIOUR_SCOPE, options);
+        if (unsafe)
+            return unsafe;
+        const endpoint = behaviourEngineFrom(BEHAVIOUR_SCOPE, env);
+        if (!endpoint)
+            return noBehaviourEngineRefusal(BEHAVIOUR_SCOPE);
+        const engine = connect(endpoint, env);
+        if (!engine) {
+            return unreachableBehaviourEngineRefusal(BEHAVIOUR_SCOPE, endpoint, "no transport speaks that address — a http(s) URL is dialled with a bearer token, and a bare " +
+                "address is run as a command on PATH; any other scheme has no transport yet");
+        }
+        const request = buildEngineRequest(options, kinds);
+        const outcome = await engine.predict(request);
+        // Built where the wire was seen, and returned as it stands. The three
+        // engine-answered causes and the token cases are mapped once, in the
+        // contract's transport, rather than re-derived here from a cause.
+        if (!outcome.ok)
+            return outcome.refusal;
+        const { answer } = outcome;
+        // `Object.create(null)`, not `{}`. An entity named `constructor` or
+        // `toString` writes onto `Object.prototype`'s members on a plain literal,
+        // and one named `__proto__` sets the prototype instead of adding a key, so
+        // the entry vanishes and `behaviourReport`'s totality check fires on an
+        // entity this function believed it had reported. `coverageFor` already
+        // guards its own lookups this way (`./mapping.ts`); these are the same
+        // hazard on the writing side.
+        const entities = Object.create(null);
+        const unpredicted = Object.create(null);
+        for (const held of request.withheld) {
+            unpredicted[held.name] = {
+                ...(held.entityType === "(undeclared)" ? {} : { type: held.entityType }),
+                reason: "unsupported-kind",
+                detail: held.detail,
+            };
+        }
+        for (const node of request.nodes) {
+            // `hasOwnProperty` for the same reason: `answer.declined` comes from
+            // `JSON.parse`, so `declined["constructor"]` is a function rather than
+            // `undefined` and the `!== undefined` guard below missed it.
+            const declined = has(answer.declined, node.name) ? answer.declined[node.name] : undefined;
+            if (declined !== undefined) {
+                unpredicted[node.name] = {
+                    type: node.entityType,
+                    reason: "read-failed",
+                    detail: `${answer.engine} was sent ${node.name} as a ${node.kind} and declined it: ${declined}`,
+                };
+                continue;
+            }
+            const figure = has(answer.figures, node.name) ? answer.figures[node.name] : undefined;
+            if (figure === undefined) {
+                unpredicted[node.name] = {
+                    type: node.entityType,
+                    reason: "read-failed",
+                    detail: `${answer.engine} was sent ${node.name} and its answer names it in neither its figures nor ` +
+                        "its declined list. An engine that loses a node is reported, not rendered as an estate one " +
+                        "node smaller.",
+                };
+                continue;
+            }
+            entities[node.name] = block(options.traffic, figure, answer);
+        }
+        return behaviourReport(options, {
+            engine: answer.engine,
+            version: answer.version,
+            ...(answer.total
+                ? { total: predictedRate(answer.total.perHour, answer.total.currency) }
+                : {}),
+        }, entities, unpredicted);
+    };
+}
+/** An own key, not a prototype member. See the accumulators above. */
+function has(map, key) {
+    return map !== undefined && Object.prototype.hasOwnProperty.call(map, key);
+}
+/**
+ * One engine figure as a contract block.
+ *
+ * `at` comes from the request rather than from the engine's answer. The engine
+ * was asked at one level and `behaviourReport` refuses a block priced at a
+ * level the run did not ask for, so echoing the engine's own idea of the level
+ * would turn an engine that quietly substituted a level it liked better into a
+ * report that agrees with itself and answers the wrong question.
+ *
+ * `headroom` is copied axis by axis. An axis the engine did not model is
+ * **absent**, never `0` — zero headroom means saturated, which is the opposite
+ * claim, and `BehaviourHeadroom` is a union requiring at least one axis so a
+ * figure with neither is a type error rather than a block behold drops.
+ */
+function block(traffic, figure, answer) {
+    const cpu = figure.headroom?.cpu;
+    const latency = figure.headroom?.latency;
+    // Built axis by axis, and the cast the first version used here was a lie:
+    // `EngineFigure.headroom` is optional, so a figure stating none produced
+    // `{ latency: undefined }` — an object satisfying `BehaviourHeadroom`
+    // structurally and carrying no axis at all, which behold drops. The doc
+    // claiming a type error caught this was false. `parseEngineAnswer` now
+    // refuses such a figure before it reaches here; this stays correct anyway,
+    // because a lexicon should not depend on its own validator having run.
+    const headroom = cpu !== undefined
+        ? { cpu, ...(latency !== undefined ? { latency } : {}) }
+        : { latency: latency };
+    if (cpu === undefined && latency === undefined) {
+        throw new Error(`predictBehaviour: the engine's figure for this entity carries neither a cpu nor a latency ` +
+            "headroom axis, and parseEngineAnswer should have refused it.");
+    }
+    return {
+        at: { traffic },
+        cost: predictedRate(figure.perHour, figure.currency),
+        headroom,
+        errorRate: figure.errorRate,
+        resilience: {
+            failure: figure.resilience.failure,
+            verdict: figure.resilience.verdict,
+            ...(figure.resilience.note ? { note: figure.resilience.note } : {}),
+        },
+        ...(figure.rightSize ? { rightSize: figure.rightSize } : {}),
+        provenance: {
+            engine: answer.engine,
+            version: answer.version,
+            tolerance: answer.tolerance,
+            basis: answer.basis,
+        },
+    };
+}

package/dist/behaviour-request.js

@@ -0,0 +1,194 @@
+/**
+ * The engine's request, built offline from chant's typed source (#2357).
+ *
+ * `chant build` reaches no network and is byte-identical on re-run
+ * (`packages/core/src/components/verbs/reproducibility.ts`, the
+ * `deterministic-synthesis` basis). The request an engine is handed is built
+ * the same way and holds itself to the same property, for a reason that is not
+ * tidiness: the epic wants the declared prediction and the live prediction
+ * shown as a delta, and a delta is only a statement about the estate if both
+ * sides were assembled the same way from the same source. A request carrying a
+ * timestamp, an unsorted map or a floating-point rendering that depends on the
+ * platform makes every re-run look like drift.
+ *
+ * So everything here is pure. No clock, no `Math.random`, no environment, no
+ * filesystem, no network. {@link renderEngineRequest} is the only place bytes
+ * are produced, and it produces them through a canonical writer that sorts
+ * every object key and every list.
+ *
+ * ## What is in the request, and why the withheld list is in it too
+ *
+ * Nodes, edges, the traffic level, the caller's edge-coverage claim — and
+ * `withheld`, the entities the caller asked about that this lexicon is not
+ * asking the engine about, each with the reason from the coverage table.
+ *
+ * That last one is the same argument `edgeCoverage` won on the contract
+ * (#2365, review finding 6). An engine handed twelve nodes cannot tell whether
+ * the estate has twelve or twenty, and a resilience verdict computed over a
+ * graph with eight nodes missing is a confident answer to a question nobody
+ * asked. Omitting them would make the request's own coverage invisible one
+ * level down from where the contract made it visible.
+ */
+import { byCodeUnit, coverageFor, coverageLabel, ownerOf, unmappedDetail, } from "./behaviour-kinds.js";
+/** The wire version. Bumped when the shape changes, the way `behaviour: "v1"` is. */
+export const BEHAVIOUR_REQUEST_VERSION = "behaviour/v1";
+/** Read a dotted path out of a declared property bag. Returns `undefined` for any miss. */
+function readPath(props, path) {
+    let cursor = props;
+    for (const segment of path.split(".")) {
+        if (typeof cursor !== "object" || cursor === null)
+            return undefined;
+        cursor = cursor[segment];
+    }
+    return cursor;
+}
+/**
+ * A declared size, as a string, or absent.
+ *
+ * `sizeType` says which type the row's property holds, and a value of the
+ * other type is **absent** rather than coerced. Without that, a
+ * `DBInstanceClass: 42` — a wrong-typed declaration, or a parameter that
+ * folded to a number — rendered as `"42"` and went to the engine to be matched
+ * against a price table of instance-class names it does not appear in. That is
+ * the outcome the paragraph below is written against, arriving through the
+ * door the paragraph left open.
+ *
+ * Anything else — an object, an array, an unresolved intrinsic, a `NaN` — is
+ * absent too, because a size an engine cannot read is worse than no size: it
+ * will either be ignored silently or matched against nothing.
+ *
+ * A terraform block's unresolved reference is a string, `"${var.size}"`, and
+ * is absent for the same reason a CloudFormation intrinsic object is: it is
+ * the name of a value, not the value (#2360).
+ */
+export function sizeOf(props, sizeProp, sizeType) {
+    if (!sizeProp)
+        return undefined;
+    const raw = readPath(props, sizeProp);
+    if (sizeType === "number") {
+        return typeof raw === "number" && Number.isFinite(raw) ? String(raw) : undefined;
+    }
+    // `string`, and the default for a row naming a property and no type.
+    return isLiteral(raw) ? raw : undefined;
+}
+/** A non-empty string that is a value rather than a terraform `${…}` reference to one. */
+function isLiteral(raw) {
+    return typeof raw === "string" && raw.length > 0 && !raw.includes("${");
+}
+/**
+ * Translate one request's worth of chant entities and edges into the engine's
+ * shape. Pure, and the same input gives the same output forever.
+ *
+ * Every name in `entityNames` comes out in exactly one of `nodes` or
+ * `withheld`. The caller in `./predict-behaviour.ts` depends on that to satisfy
+ * `behaviourReport`'s totality check, and a name the caller asked about that is
+ * missing from `options.entities` is `withheld` with an `unknown-type` detail
+ * rather than dropped — a `continue` in this loop is the exact silent hole the
+ * contract's totality refusal exists to catch.
+ */
+export function buildEngineRequest(options, kinds) {
+    const nodes = [];
+    const withheld = [];
+    for (const name of [...options.entityNames].sort(byCodeUnit)) {
+        const declared = options.entities.get(name);
+        if (!declared) {
+            withheld.push({
+                name,
+                entityType: "(undeclared)",
+                status: "unknown-type",
+                detail: `${name} was named in entityNames and is not in the entities map, so this lexicon has ` +
+                    "nothing to translate. It is reported rather than dropped: an entity that vanished " +
+                    "between the build and the request is a defect in the caller, and a silent omission " +
+                    "hides it behind an estate that looks smaller.",
+            });
+            continue;
+        }
+        const verdict = coverageFor(kinds, declared.entityType, declared.props);
+        // Where a lexicon keys its rows on something other than the entity type,
+        // that key rides beside the entity type on the wire and in the withheld
+        // list: `Terraform::Resource` alone names nothing an engine or a reader
+        // can act on (#2360), and its provider type is what does. Asked of the
+        // owning contributor rather than special-cased here (#2382).
+        const owner = ownerOf(kinds, declared.entityType);
+        const resolved = owner?.resolveType?.(declared.entityType, declared.props);
+        const resourceType = resolved && resolved !== declared.entityType ? resolved : undefined;
+        if (verdict.status !== "mapped") {
+            withheld.push({
+                name,
+                entityType: declared.entityType,
+                ...(resourceType ? { resourceType } : {}),
+                status: verdict.status,
+                detail: unmappedDetail(coverageLabel(kinds, declared.entityType, declared.props), verdict, owner),
+            });
+            continue;
+        }
+        const { mapping } = verdict;
+        const declaredRegion = mapping.regionProp
+            ? readPath(declared.props, mapping.regionProp)
+            : undefined;
+        const region = isLiteral(declaredRegion) ? declaredRegion : options.region;
+        const size = sizeOf(declared.props, mapping.sizeProp, mapping.sizeType);
+        nodes.push({
+            name,
+            entityType: declared.entityType,
+            ...(resourceType ? { resourceType } : {}),
+            kind: mapping.kind,
+            provider: mapping.provider,
+            ...(region ? { region } : {}),
+            ...(size ? { size } : {}),
+        });
+    }
+    const edges = options.edges
+        .map((edge) => ({
+        from: edge.from,
+        to: edge.to,
+        ...(edge.viaAttr ? { via: edge.viaAttr } : {}),
+        ...(edge.toAttr ? { toAttr: edge.toAttr } : {}),
+    }))
+        // By code unit, like the node order above. `localeCompare` reads the
+        // ambient locale, so two machines with different `LANG` values produced
+        // two different byte streams from one estate — in a module whose whole
+        // claim is that its bytes are a function of its content and nothing else.
+        .sort((a, b) => byCodeUnit(a.from, b.from) ||
+        byCodeUnit(a.to, b.to) ||
+        byCodeUnit(a.via ?? "", b.via ?? "") ||
+        byCodeUnit(a.toAttr ?? "", b.toAttr ?? ""));
+    return {
+        request: BEHAVIOUR_REQUEST_VERSION,
+        traffic: options.traffic,
+        ...(options.region ? { region: options.region } : {}),
+        nodes,
+        edges,
+        coverage: options.edgeCoverage,
+        withheld,
+    };
+}
+/**
+ * Canonical JSON: object keys sorted, arrays in the order they were built,
+ * two-space indent, one trailing newline.
+ *
+ * Key order is where a "deterministic" serializer usually is not. `JSON.stringify`
+ * preserves insertion order, and insertion order here follows the order a
+ * property bag was assembled in, which follows discovery order, which follows
+ * the filesystem. Sorting the keys makes the bytes a function of the content
+ * and nothing else — which is what `chant build`'s own reproducibility claim
+ * means, and what makes a re-run comparable rather than merely re-run.
+ */
+export function renderEngineRequest(request) {
+    return `${JSON.stringify(canonical(request), null, 2)}\n`;
+}
+function canonical(value) {
+    if (Array.isArray(value))
+        return value.map(canonical);
+    if (typeof value === "object" && value !== null) {
+        const out = {};
+        for (const key of Object.keys(value).sort()) {
+            const inner = value[key];
+            if (inner === undefined)
+                continue;
+            out[key] = canonical(inner);
+        }
+        return out;
+    }
+    return value;
+}