@intentius/chant 0.124.13 → 0.124.15

package/dist/behaviour.js

@@ -0,0 +1,1325 @@
+/**
+ * The behaviour prediction contract (#2356) — what a lexicon's
+ * `predictBehaviour()` is allowed to mean.
+ *
+ * `describeResources()` (./observation.ts) answers whether a declared entity
+ * exists. `observeResourcesDeep()` (./deep-observation.ts) answers what its
+ * properties currently are. Both report facts a substrate was asked for. This
+ * third axis reports something no substrate holds: what the declared estate
+ * would *do* at a stated traffic level — cost per hour, how far each entity is
+ * from saturation, the error rate to expect, whether it survives a named
+ * failure, and a smaller size that would still carry the load.
+ *
+ * None of that is a measurement, and the type is built so it cannot be read as
+ * one.
+ *
+ * ## A prediction is not a bill
+ *
+ * The one failure mode that matters here is somebody quoting a modeled figure
+ * as money owed. Four things in this module work against that, and it is worth
+ * being exact about how much they buy, because an overstated guarantee is how
+ * a consumer ends up trusting one:
+ *
+ *   1. Money appears in exactly one shape, {@link PredictedRate}, and that
+ *      shape carries a literal `rate: "per-hour"` discriminant. There is no
+ *      field anywhere for an amount, a period, an account, an invoice or a
+ *      due date, so an elapsed charge is not expressible *in this module's
+ *      types*.
+ *   2. A figure cannot exist without {@link PredictedBehaviour.at}, the traffic
+ *      level it was predicted for. A bill is for an hour that happened; this is
+ *      for an hour the engine was asked to imagine.
+ *   3. {@link BehaviourProvenance} is required on every entity, and its
+ *      {@link BehaviourProvenance.basis} is a closed two-value enum: `modeled`
+ *      off list prices, or `validated` against a real bill. A figure that will
+ *      not say which of the two it is cannot be constructed.
+ *   4. A refusal is a separate member of the {@link BehaviourResult} union with
+ *      no figures on it at all, so "the engine is gone" and "the engine says
+ *      zero" are different objects rather than the same object with zeroes in
+ *      it. This one is airtight: there is no `entities` key on the refusal arm
+ *      to be empty and no total to be zero.
+ *
+ * **What this does not do is make a bill a type error.** A consumer holding a
+ * {@link PredictedBehaviour} can write
+ * `const { rate, ...rest } = cost; return { amount: rest.perHour * hours }`
+ * and TypeScript will not object; the discriminant is a field on an object, and
+ * a field can be dropped. behold's own validator rebuilds `cost` as
+ * `{ perHour, currency }` and its estate sum carries no discriminant at all, so
+ * the marker is stripped by the first consumer *by design*. What the shape
+ * genuinely buys is that a bill cannot be constructed **accidentally** — every
+ * route from a prediction to something that reads as money owed has a
+ * deliberate destructure or cast in it, and shows up in review as one. Treat
+ * rules 1 to 3 as a speed bump with a name, and rule 4 as the enforced one.
+ *
+ * ## The engine sees no credential and writes nothing
+ *
+ * {@link PredictBehaviourOptions} mirrors `observeResourcesDeep`'s options
+ * field for field, plus `traffic`, `edges` and `edgeCoverage`, and then works
+ * against credentials on two levels. The type declares every obvious name
+ * `?: never`, which catches the deliberate attempt; and
+ * {@link screenBehaviourRequest} walks the whole request at runtime, matching
+ * credential-shaped **values** as well as credential-shaped keys, which is what
+ * catches the accident.
+ *
+ * `screenBehaviourRequest` is the one entry point — its own doc comment carries
+ * the call sequence, and nothing else here restates it. The runtime walk is the
+ * load-bearing half, because the type cannot see the two channels that actually
+ * carry a secret in practice: `entities[*].props` is `Record<string, unknown>`
+ * straight out of the build, and a lexicon surfacing a connection string puts
+ * one there without deciding to. See {@link assertNoCredentialInOptions} for
+ * exactly what the walk detects and, more importantly, what it does not.
+ *
+ * `edges` is the one place the options mirror breaks, and the field's own doc
+ * says why: the epic's input is a resource graph, a deep read has no use for
+ * neighbours, and a prediction is nothing but statements about paths through
+ * the estate. It carries `IREdge` (./graph-ir.ts) rather than an edge type of
+ * this contract's own, because that is already the shape both the declared
+ * path and the live path produce.
+ *
+ * Nothing in the options is a handle. There is no client, no transport, no
+ * apply callback, no writer — only strings, a name list and the entity map the
+ * build already produced. An engine handed this cannot reach the account even
+ * if it wanted to, which is the structural half of "it never writes".
+ *
+ * ## The tri-state, and why it is not `UnobservedReason`
+ *
+ * Behaviour keeps the same three-verdict discipline `./observation.ts`
+ * established — PREDICTED, NOT-PREDICTABLE-FOR-THIS-KIND, and NOT-PREDICTED
+ * with a named reason — but on a stricter total: every entity the caller asked
+ * about lands in `entities` or in `unpredicted`, never in neither. The thin
+ * read needs a third position because "the provider says it is not there" is a
+ * real answer with no row to sit on. A prediction has no such answer. An entity
+ * either got a figure or it did not, and when it did not there is a reason,
+ * so an entity in neither map means the lexicon lost track of it.
+ *
+ * {@link BehaviourUnpredictedReason} derives from `UnobservedReason` rather
+ * than restating it, so the four shared verdicts provably keep their spelling
+ * and their meaning. It differs in two ways, both deliberate:
+ *
+ *   - `no-credentials` is **excluded**. A behaviour read has no credential to
+ *     be missing — see the section above — so an enum that could say it would
+ *     be inviting a lexicon to send an operator hunting for a variable this
+ *     contract forbids.
+ *   - Four reasons about the predictor itself are **added** — `no-engine`,
+ *     `engine-unreachable`, `engine-out-of-credit` and `engine-over-quota` —
+ *     because the epic wants a missing engine named and `no-binding` is about
+ *     the environment resolving to no target, a different axis. They are four
+ *     rather than one because each has a different remedy, and a refusal that
+ *     names the wrong remedy is worse than a slow one: set a variable, check an
+ *     address, pay for the account, or wait for a window. The last two arrive
+ *     from an engine that answered perfectly well (#2359), so folding them into
+ *     `engine-unreachable` would send somebody to debug a network that is fine.
+ *
+ * ## Deltas: the invariant is here, the presentation is not
+ *
+ * The epic wants a declared prediction and a live prediction shown as a delta,
+ * and #2358 posts one on a merge request. This module deliberately ships no
+ * delta type and no differencing function. What it ships is the one thing a
+ * hand-rolled diff silently loses, which is that a figure's context does not
+ * survive subtraction: {@link compareFigures} classifies a pair `comparable`,
+ * `mixed-basis`, `mixed-level` or `mixed-engine`, and the rule this contract
+ * binds its consumers to is that anything but `comparable` must be marked
+ * wherever it is shown. A `modeled` figure minus a `validated` one is not a
+ * change in the estate; part of that difference is the gap between a price list
+ * and an invoice. Nor is a 100 rps figure minus a 1000 rps one, which is why
+ * {@link compareProvenance} — which cannot see `at` and never could — is not
+ * the function to reach for. How the mark looks is #2358's to define. Whether
+ * there is one is not.
+ *
+ * ## Shape compatibility with the overlay
+ *
+ * {@link PredictedBehaviour} is the object `chant graph --live --overlay` puts
+ * on a node as `attrs._behaviour`.
+ *
+ * On the graph, `meta._behaviour` takes {@link BehaviourReportMeta} **or the
+ * whole {@link BehaviourRefusalReport}** — not a bare {@link BehaviourRefusal}.
+ * behold reads that key as `{ engine?, version?, at?, total?, refusal? }` and
+ * branches on the presence of `refusal`, so a bare `BehaviourRefusal` has no
+ * `refusal` key, falls through to the engine check, and is dropped as
+ * "meta.engine missing" — a refusal that renders as nothing at all, which is
+ * the one outcome this contract exists to prevent. #2360 implements this
+ * sentence, so it says what behold does.
+ *
+ * behold reads those keys and does arithmetic on the engine's figures; it never
+ * produces one of its own. Fields beyond what it reads (`cause` and `source` on
+ * a refusal, `edgeCoverage` on the meta) are additive and ignorable.
+ *
+ * ## The transport is part of the contract (#2373, decided in #2359)
+ *
+ * The first version of this module named the address chain, said the address
+ * may be a URL, a socket path or a command on `PATH`, and stopped. The first
+ * consumer (#2357) then declared a private `BehaviourEngine` and its own mapping from
+ * what the wire said to which of the three engine-answered refusals to build.
+ * With a second implementation to generalise from, the seam is here:
+ * {@link BehaviourTransport} is one method, `send(body)`, taking the request
+ * as the lexicon rendered it and returning either the engine's answer as text
+ * or a {@link BehaviourRefusalReport} ready to return.
+ *
+ * Two things about that shape are decisions rather than defaults.
+ *
+ *   - **The transport returns text, not a report.** #2373 proposed
+ *     `send(request) → Promise<BehaviourResult>`. A report cannot be built
+ *     without the request's `entityNames`, `traffic` and `edgeCoverage`, and
+ *     what an answer's fields *mean* is the lexicon's wire version, not the
+ *     contract's. A transport that built reports would have to know both, and
+ *     every lexicon would need its own. One that carries bytes is one HTTP
+ *     client and one subprocess spawner for every lexicon there will ever be.
+ *   - **The failure arm is a finished refusal, not a `{cause, detail}` pair.**
+ *     The transport is the one party that saw the wire condition and holds the
+ *     lexicon name and the endpoint, so it is the one party that can name the
+ *     condition, the address and the variable together. Handing back a cause
+ *     for the lexicon to translate would put the same three-way switch in
+ *     every lexicon, and one of them would fold `engine-over-quota` into
+ *     `engine-unreachable` on a bad afternoon. {@link behaviourWireRefusal}
+ *     is that switch, written once.
+ *
+ * What the wire says maps to the causes above as follows, and
+ * `./behaviour-http.ts` (the first adapter) and `./behaviour-engine.ts`'s command transport both
+ * hold to it: an HTTP 402 is `engine-out-of-credit`; a 429 is
+ * `engine-over-quota`; a connection refused, a timeout, a 5xx, a redirect, or
+ * an answer that is not JSON is `engine-unreachable`; an unset address is
+ * `no-engine` before any transport is built; and an unset or rejected bearer
+ * token is `no-engine` too, because its remedy is the same kind — set a
+ * variable — and the reason says which. A transport that spawns a child hands
+ * it {@link behaviourEngineChildEnvironment} and nothing more, for the reason
+ * given on that function.
+ *
+ * A bearer token on the wire is the transport's, and is not the credential
+ * rule 3 is about. "The engine is never handed a credential" is a statement
+ * about the *request body* — the graph — which {@link screenBehaviourRequest}
+ * still walks first. {@link behaviourTokenFrom} resolves the token an engine
+ * authenticates chant with, on a chain parallel to the address chain, and the
+ * token goes in a header the engine reads and nowhere else: never in the body,
+ * never in a refusal, never in a `detail`.
+ */
+import { CREDENTIAL_ENV_NAME, CREDENTIAL_SHAPES, CREDENTIAL_TOKEN_SHAPES, REDACTED, redactCredentialMaterial, } from "./identity.js";
+/**
+ * Every legal {@link BehaviourBasis}, for validation and conformance checks.
+ *
+ * Derived from a total witness rather than typed as `readonly BehaviourBasis[]`
+ * and written out by hand. A hand-written array is only checked for having
+ * legal members, never for having ALL of them, so a value added to the union
+ * leaves the array silently short and every runtime guard built on it starts
+ * rejecting a value the type accepts. Keying a `Record` off the union makes the
+ * omission a compile error at the point of the omission. Same construction for
+ * {@link RESILIENCE_VERDICTS} and {@link BEHAVIOUR_UNPREDICTED_REASONS}, and
+ * the last of those is the one that needed it: it derives from
+ * `UnobservedReason`, so a reason added *upstream* would otherwise widen this
+ * type with nothing here failing.
+ */
+const BEHAVIOUR_BASIS_WITNESS = {
+    modeled: true,
+    validated: true,
+};
+export const BEHAVIOUR_BASES = Object.keys(BEHAVIOUR_BASIS_WITNESS);
+/** True when `value` is a legal {@link BehaviourBasis}. */
+export function isBehaviourBasis(value) {
+    return typeof value === "string" && BEHAVIOUR_BASES.includes(value);
+}
+/** Build a {@link PredictedRate}. Lexicons use this rather than writing the discriminant by hand. */
+export function predictedRate(perHour, currency) {
+    return { rate: "per-hour", perHour, currency };
+}
+const RESILIENCE_VERDICT_WITNESS = {
+    survives: true,
+    degrades: true,
+    fails: true,
+};
+/** Every legal {@link ResilienceVerdict}, for validation and conformance checks. */
+export const RESILIENCE_VERDICTS = Object.keys(RESILIENCE_VERDICT_WITNESS);
+/** True when `value` is a legal {@link ResilienceVerdict}. */
+export function isResilienceVerdict(value) {
+    return typeof value === "string" && RESILIENCE_VERDICTS.includes(value);
+}
+/**
+ * The total witness. This is the one that earns the construction: the type
+ * above derives from `UnobservedReason`, so adding a reason to THAT union —
+ * in ./observation.ts, for reasons that have nothing to do with prediction —
+ * silently widens this one. With a hand-written array, the widening compiled
+ * clean, every existing test stayed green, and the new reason was assignable to
+ * `BehaviourUnpredictedReason` while {@link isBehaviourUnpredictedReason}
+ * returned `false` for it and the conformance suite rejected it. Keyed off the
+ * union, the same change fails to compile here and somebody has to decide
+ * whether the new reason belongs to behaviour at all.
+ */
+const BEHAVIOUR_UNPREDICTED_REASON_WITNESS = {
+    "read-failed": true,
+    "no-binding": true,
+    "unsupported-kind": true,
+    filtered: true,
+    "no-engine": true,
+    "engine-unreachable": true,
+    "engine-out-of-credit": true,
+    "engine-over-quota": true,
+    "credential-in-request": true,
+};
+/** Every legal {@link BehaviourUnpredictedReason}, for validation and conformance checks. */
+export const BEHAVIOUR_UNPREDICTED_REASONS = Object.keys(BEHAVIOUR_UNPREDICTED_REASON_WITNESS);
+/** True when `value` is a legal {@link BehaviourUnpredictedReason}. */
+export function isBehaviourUnpredictedReason(value) {
+    return (typeof value === "string" &&
+        BEHAVIOUR_UNPREDICTED_REASONS.includes(value));
+}
+/** True when the lexicon refused rather than predicting. */
+export function isBehaviourRefusalReport(value) {
+    return typeof value === "object" && value !== null && "refusal" in value;
+}
+/**
+ * True when `value` is either arm of the versioned {@link BehaviourResult}
+ * envelope.
+ *
+ * Both the discriminant AND an arm, because the discriminant alone is not the
+ * type. `{ behaviour: "v1" }` carries the version and is neither arm: it fails
+ * {@link isBehaviourRefusalReport}, so a consumer's `if (refusal) … else …`
+ * narrows it to {@link BehaviourReport}, and `result.entities` is `undefined`
+ * at a site TypeScript has been told cannot be.
+ */
+export function isBehaviourResult(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const v = value;
+    if (v.behaviour !== "v1")
+        return false;
+    if (typeof v.refusal === "object" && v.refusal !== null)
+        return true;
+    return (typeof v.entities === "object" && v.entities !== null && typeof v.meta === "object" && v.meta !== null);
+}
+/**
+ * Words that state nothing. Rejected wherever this contract asks an engine to
+ * *state* something — its tolerance, and the failure a verdict is about.
+ *
+ * `"none"` as a `resilience.failure` was the hole: the module's own doc says a
+ * verdict with no named failure says nothing, and `"none"` names no failure
+ * while sailing through a non-empty-string check.
+ */
+const STATES_NOTHING = ["n/a", "na", "none", "unknown", "-", "?", "tbd", "null"];
+/** True when a stated value is one of the words that state nothing. */
+function statesNothing(value) {
+    return STATES_NOTHING.includes(value.trim().toLowerCase().replace(/\.$/, ""));
+}
+const isFraction = (v) => typeof v === "number" && Number.isFinite(v) && v >= 0 && v <= 1;
+const isFilled = (v) => typeof v === "string" && v.trim() !== "";
+/**
+ * Every rule behold's `validateBehaviourBlock` applies, applied here instead —
+ * before the block is built rather than after it has travelled.
+ *
+ * The rule set is deliberately, literally the same set. behold
+ * (`behold/src/behaviour.ts:209`) validates each block on arrival and **drops
+ * the whole block** with a diagnostic when one fails, so a block chant's types
+ * accept and behold's validator rejects renders nothing at all, having looked
+ * perfectly legal every step of the way here. Types cannot carry most of these:
+ * `tolerance: string` accepts `""`, `errorRate: number` accepts `1.2`, and
+ * `cost.perHour: number` accepts `-4`.
+ *
+ * The mapping, by behold's own numbering, so a future change there has a named
+ * place to land here:
+ *
+ *  2 `at.traffic` non-empty · 3 `cost.perHour` finite · 4 not negative ·
+ *  5 `cost.currency` non-empty · 6 `headroom` present · 7/8 each axis a
+ *  fraction · 9 at least one axis · 10 `errorRate` a fraction ·
+ *  11 `resilience.failure` non-empty · 12 verdict in the closed set ·
+ *  13 `rightSize` implies a `suggestion` · 14 `provenance.engine` non-empty ·
+ *  15 `version` non-empty · 16 `tolerance` non-empty · 17 `basis` in the closed
+ *  set.
+ *
+ * Rules 9 and 16 are the two chant is stricter on. Rule 9 is also a type here
+ * ({@link BehaviourHeadroom} is a union requiring one axis), so this is the
+ * backstop for a JavaScript caller. And on 16, behold accepts any non-empty
+ * string while this rejects `n/a`, `none`, `unknown` and friends: the epic asks
+ * for the engine's *stated* tolerance, and a word meaning "I have none to
+ * state" passes behold's check while defeating its purpose.
+ */
+export function validateBehaviourBlock(name, block) {
+    const bad = (why) => {
+        throw new Error(`predictBehaviour produced an invalid block for "${name}": ${why}. behold's own validator ` +
+            "(behold/src/behaviour.ts) drops a block failing this, so it would render nothing rather than " +
+            "render wrong — which is worse to debug, because everything here looked legal.");
+    };
+    if (!isFilled(block.at?.traffic))
+        bad("at.traffic is missing — name the traffic level you priced");
+    const perHour = block.cost?.perHour;
+    if (typeof perHour !== "number" || !Number.isFinite(perHour))
+        bad("cost.perHour is not a finite number");
+    if (perHour < 0)
+        bad("cost.perHour is negative");
+    if (!isFilled(block.cost?.currency))
+        bad("cost.currency is missing");
+    const headroom = block.headroom;
+    if (!headroom || typeof headroom !== "object")
+        bad("headroom is missing");
+    const h = headroom;
+    if (h.cpu !== undefined && !isFraction(h.cpu))
+        bad("headroom.cpu is not a fraction 0..1");
+    if (h.latency !== undefined && !isFraction(h.latency))
+        bad("headroom.latency is not a fraction 0..1");
+    if (h.cpu === undefined && h.latency === undefined) {
+        bad("headroom carries neither cpu nor latency — an axis you did not model is absent, and a block with no axis at all says nothing");
+    }
+    if (!isFraction(block.errorRate))
+        bad("errorRate is not a fraction 0..1");
+    if (!isFilled(block.resilience?.failure)) {
+        bad("resilience.failure is missing — a verdict with no named failure says nothing");
+    }
+    if (statesNothing(block.resilience.failure)) {
+        bad(`resilience.failure ${JSON.stringify(block.resilience.failure)} names no failure. behold takes ` +
+            "any non-empty string here, so this passes its validator and renders a confident verdict about " +
+            'nothing. Name the event: "one zone lost", "primary database failover"');
+    }
+    if (!isResilienceVerdict(block.resilience?.verdict)) {
+        bad(`resilience.verdict ${JSON.stringify(block.resilience?.verdict)} is not survives/degrades/fails`);
+    }
+    if (block.rightSize !== undefined && !isFilled(block.rightSize.suggestion)) {
+        bad("rightSize is present without a suggestion");
+    }
+    const p = block.provenance;
+    if (!p || typeof p !== "object")
+        bad("provenance is missing");
+    if (!isFilled(p?.engine))
+        bad("provenance.engine is missing");
+    if (!isFilled(p?.version))
+        bad("provenance.version is missing");
+    if (!isFilled(p?.tolerance)) {
+        bad("provenance.tolerance is missing — a figure without a stated tolerance is not a prediction");
+    }
+    if (statesNothing(p.tolerance)) {
+        bad(`provenance.tolerance ${JSON.stringify(p.tolerance)} states no tolerance. An engine with nothing ` +
+            "to say about its own error bars has no business publishing a figure; say the number, however wide");
+    }
+    if (!isBehaviourBasis(p?.basis)) {
+        bad(`provenance.basis ${JSON.stringify(p?.basis)} is not modeled/validated`);
+    }
+}
+/**
+ * Build a {@link BehaviourReport}, and refuse to build an invalid one.
+ *
+ * Takes the request rather than a hand-assembled meta, and derives `at`,
+ * `edgeCoverage` and the asked-for names from it. A lexicon states only what is
+ * genuinely its own — which engine answered, at what version, and a total if
+ * the engine has one — so the three fields that must agree with the request
+ * cannot be restated differently.
+ *
+ * That is a check and not a proof, and the distinction matters enough to say
+ * plainly: {@link BehaviourReport} is a plain interface, {@link isBehaviourResult}
+ * accepts a hand-built one, and a lexicon calling this with
+ * `entityNames: Object.keys(entities)` self-certifies. What passing the request
+ * buys is that the ordinary route is checked and the check names what is wrong;
+ * a consumer that needs the guarantee runs its own
+ * `validateBehaviourResult(result, askedFor)` on arrival, which is #2358's and
+ * #2360's to write.
+ *
+ * Refusals, all naming what went wrong:
+ *
+ *  - an entity in neither map — the tri-state's whole point, and the one a
+ *    `continue` in a lexicon's loop produces silently;
+ *  - an entity in both maps — priced and unpriced at once;
+ *  - a figure for something nobody asked about;
+ *  - a block priced at a level the run did not ask for;
+ *  - an edge-coverage claim that names no gap ({@link validateEdgeCoverage});
+ *  - any block failing {@link validateBehaviourBlock}.
+ */
+export function behaviourReport(request, stamp, entities, unpredicted) {
+    if (!isFilled(stamp?.engine))
+        throw new Error("predictBehaviour: meta.engine is missing");
+    if (!isFilled(stamp?.version))
+        throw new Error("predictBehaviour: meta.version is missing");
+    if (!isFilled(request?.traffic))
+        throw new Error("predictBehaviour: meta.at.traffic is missing");
+    if (stamp.total && (!Number.isFinite(stamp.total.perHour) || stamp.total.perHour < 0)) {
+        throw new Error("predictBehaviour: meta.total.perHour is not a non-negative finite number");
+    }
+    validateEdgeCoverage(request.edgeCoverage);
+    const meta = {
+        engine: stamp.engine,
+        version: stamp.version,
+        at: { traffic: request.traffic },
+        ...(stamp.total ? { total: stamp.total } : {}),
+        // Copied, not aliased. `readonly` is erased at runtime, so assigning the
+        // request's object by reference let a caller mutate
+        // `request.edgeCoverage.unresolvedKinds` after construction and change what
+        // the report claims it was computed over — the one field whose whole job is
+        // to be the report's honest account of its own inputs.
+        edgeCoverage: copyEdgeCoverage(request.edgeCoverage),
+    };
+    const entityNames = request.entityNames;
+    const asked = new Set(entityNames);
+    const holes = new Set(Object.keys(unpredicted ?? {}));
+    for (const name of Object.keys(entities)) {
+        if (holes.has(name)) {
+            throw new Error(`predictBehaviour reported "${name}" as both priced and unpriced. An entity has one verdict.`);
+        }
+        if (!asked.has(name)) {
+            throw new Error(`predictBehaviour returned a figure for "${name}", which was not in entityNames. An engine ` +
+                "answering about entities nobody asked about is answering about the wrong estate.");
+        }
+        validateBehaviourBlock(name, entities[name]);
+        if (entities[name].at.traffic !== meta.at.traffic) {
+            throw new Error(`predictBehaviour priced "${name}" at ${JSON.stringify(entities[name].at.traffic)} in a run ` +
+                `whose meta.at.traffic is ${JSON.stringify(meta.at.traffic)}. One run, one level.`);
+        }
+    }
+    for (const name of holes) {
+        if (!asked.has(name)) {
+            throw new Error(`predictBehaviour reported "${name}" unpredicted, and it was not in entityNames.`);
+        }
+        if (!isBehaviourUnpredictedReason(unpredicted[name]?.reason)) {
+            throw new Error(`predictBehaviour gave "${name}" the reason ` +
+                `${JSON.stringify(unpredicted[name]?.reason)}, which is not one of ` +
+                `${BEHAVIOUR_UNPREDICTED_REASONS.join(", ")}.`);
+        }
+    }
+    const missing = entityNames.filter((name) => !Object.prototype.hasOwnProperty.call(entities, name) && !holes.has(name));
+    if (missing.length > 0) {
+        throw new Error(`predictBehaviour gave no verdict at all for ${missing.map((n) => `"${n}"`).join(", ")}. Every ` +
+            "entity asked about lands in `entities` or in `unpredicted` — there is no third position, " +
+            "because a prediction has no equivalent of \"the provider says it is not there\". An entity " +
+            "you could not price is `unsupported-kind`, not an omission.");
+    }
+    return {
+        behaviour: "v1",
+        meta,
+        entities,
+        ...(unpredicted && Object.keys(unpredicted).length > 0 ? { unpredicted } : {}),
+    };
+}
+/** Build a {@link BehaviourRefusalReport}. */
+export function behaviourRefusal(refusal) {
+    return { behaviour: "v1", refusal };
+}
+/**
+ * Classify a pair of *provenances*. Almost always the wrong function to call —
+ * see {@link compareFigures}, which is the one consumers want.
+ *
+ * The limit is structural rather than an oversight: `at` lives on
+ * {@link PredictedBehaviour} and not on {@link BehaviourProvenance}, so this
+ * function cannot see the traffic level and will happily answer `comparable`
+ * for a figure at 100 rps and a figure at 1000 rps. Two predictions of the same
+ * estate by the same engine at different levels are not a delta of like things;
+ * they are answers to different questions. Use this only where the two figures
+ * are already known to share a level.
+ */
+export function compareProvenance(a, b) {
+    if (a.engine !== b.engine || a.version !== b.version || a.tolerance !== b.tolerance) {
+        return "mixed-engine";
+    }
+    return a.basis === b.basis ? "comparable" : "mixed-basis";
+}
+/**
+ * The total witness, keyed by the union — the same construction the other four
+ * closed sets use, and this one needs it as much as any.
+ *
+ * {@link figureMismatches} filters {@link compareFigures}'s output through the
+ * array below. An axis added to the union and to `compareFigures` but not to
+ * the array would be reported by one and silently dropped by the other, which
+ * is exactly the "a mismatch went unsaid" failure the set return was added to
+ * prevent, reappearing in the display path.
+ *
+ * The value is the display rank rather than `true`, so the order is derived
+ * from the witness too and there is one place to state it.
+ */
+const FIGURE_MISMATCH_WITNESS = {
+    "mixed-engine": 0,
+    "mixed-level": 1,
+    "mixed-currency": 2,
+    "mixed-basis": 3,
+    "mixed-failure": 4,
+};
+/**
+ * Every mismatch, in the order a consumer should show them — most fundamental
+ * first. Order is presentation; membership is the contract.
+ */
+export const FIGURE_MISMATCHES = Object.keys(FIGURE_MISMATCH_WITNESS).sort((a, b) => FIGURE_MISMATCH_WITNESS[a] - FIGURE_MISMATCH_WITNESS[b]);
+/**
+ * Classify a pair of figures for delta purposes. **This is the one to call.**
+ *
+ * Returns **every** axis on which the two disagree, not the first. An earlier
+ * version returned one label and stopped at the first mismatch, which meant a
+ * pair differing in level AND basis reported `mixed-level` and dropped the
+ * basis crossing on the floor — a consumer told "different traffic level" would
+ * caption it as such and show a modeled-minus-validated difference underneath
+ * with nothing said. Precedence is a fine way to decide what to show first and
+ * a bad way to decide what to know.
+ *
+ * The axes:
+ *
+ *  - `mixed-engine` — engine, version or tolerance differs. Two models are not
+ *    one scale.
+ *  - `mixed-level` — different `at`. The same question asked of two different
+ *    worlds.
+ *  - `mixed-currency` — different `cost.currency`. chant converts nothing, so
+ *    USD minus EUR is not a number. behold already refuses to *sum* these
+ *    (`behold/src/behaviour.ts`); permitting them to be *differenced* left this
+ *    contract laxer than its own consumer.
+ *  - `mixed-basis` — one figure off a price list, the other off an invoice.
+ *  - `mixed-failure` — different `resilience.failure`. "Survives one zone lost"
+ *    against "survives a region lost" are two verdicts about two events, and
+ *    differencing the costs beside them implies they answer the same question.
+ *
+ * The rule this contract binds its consumers to, in one sentence: **a delta
+ * between two figures whose mismatch set is not empty must be marked as such
+ * wherever it is shown, and must never be presented as a plain difference.**
+ * How it is marked is #2358's to choose. Whether it must be marked is not.
+ */
+export function compareFigures(a, b) {
+    const out = new Set();
+    if (compareProvenance(a.provenance, b.provenance) === "mixed-engine")
+        out.add("mixed-engine");
+    if (a.at.traffic !== b.at.traffic)
+        out.add("mixed-level");
+    if (a.cost.currency !== b.cost.currency)
+        out.add("mixed-currency");
+    if (a.provenance.basis !== b.provenance.basis)
+        out.add("mixed-basis");
+    if (a.resilience.failure !== b.resilience.failure)
+        out.add("mixed-failure");
+    return out;
+}
+/** The mismatches, ordered for display. A convenience over {@link compareFigures}. */
+export function figureMismatches(a, b) {
+    const found = compareFigures(a, b);
+    return FIGURE_MISMATCHES.filter((m) => found.has(m));
+}
+/** True when two whole figures may be shown as a plain difference, with no mark. */
+export function isComparableFigure(a, b) {
+    return compareFigures(a, b).size === 0;
+}
+/** True when two provenances may be shown as a plain difference. Level-blind — see {@link compareProvenance}. */
+export function isComparableProvenance(a, b) {
+    return compareProvenance(a, b) === "comparable";
+}
+/**
+ * The variables that can name a behaviour engine, most specific first. Exported
+ * so a refusal message and a test can agree on the chain without restating it.
+ *
+ * `lexicon` scopes the first entry, which is what lets an estate priced by two
+ * engines point each lexicon at its own without a per-call flag.
+ */
+export function behaviourEngineVariables(lexicon) {
+    const scope = lexicon.toUpperCase().replace(/[^A-Z0-9]+/g, "_");
+    return [`CHANT_BEHAVIOUR_ENGINE_${scope}`, "CHANT_BEHAVIOUR_ENGINE", "BEHAVIOUR_ENGINE"];
+}
+/**
+ * Resolve the engine one lexicon predicts against, most specific first. Pure —
+ * exported for testing.
+ *
+ * The chain is lexicon-scoped, then chant-scoped, then bare, for the same
+ * reason `gitlabNoteTokenFrom` reads `CHANT_GITLAB_TOKEN` before `GITLAB_TOKEN`
+ * (`./op/activities/reconcile.ts`): the narrower name exists so a project that
+ * has to differ can differ, and the wider one exists so a project that does not
+ * need to sets one variable.
+ *
+ * Returns `undefined` when nothing in the chain answered. That is `no-engine`,
+ * and the caller turns it into {@link noBehaviourEngineMessage} — never into an
+ * empty report.
+ */
+export function behaviourEngineFrom(lexicon, env) {
+    for (const source of behaviourEngineVariables(lexicon)) {
+        const value = env[source]?.trim();
+        if (value)
+            return { value, source };
+    }
+    return undefined;
+}
+/** What a lexicon says when no variable in the chain names an engine. */
+export function noBehaviourEngineMessage(lexicon) {
+    const [scoped, chantWide, bare] = behaviourEngineVariables(lexicon);
+    return (`predictBehaviour has the ${lexicon} estate to predict and no engine to predict it with. Set a ` +
+        `${chantWide} environment variable to the engine's address — a URL, a socket path, or a command on ` +
+        `PATH — or ${bare} where nothing else in the environment is chant's. ${scoped} is read first, for an ` +
+        "estate whose lexicons are priced by different engines. The address is not a credential: the engine " +
+        "is never handed one and never writes.");
+}
+/**
+ * The variables that can hold a behaviour engine's token, most specific first.
+ * Parallel to {@link behaviourEngineVariables} and deliberately not the same
+ * chain: `CHANT_BEHAVIOUR_ENGINE` is an address, and an address is printed in
+ * refusals, while a token is never printed anywhere. Reusing one chain for
+ * both would put the token in every message that names the address.
+ */
+export function behaviourTokenVariables(lexicon) {
+    const scope = lexicon.toUpperCase().replace(/[^A-Z0-9]+/g, "_");
+    return [`CHANT_BEHAVIOUR_TOKEN_${scope}`, "CHANT_BEHAVIOUR_TOKEN", "BEHAVIOUR_TOKEN"];
+}
+/**
+ * Resolve the token one lexicon's transport authenticates with, most specific
+ * first. Pure — exported for testing. The same shape as `gitlabNoteTokenFrom`
+ * (`./op/activities/reconcile.ts`): a chain, the first non-empty value wins,
+ * and the result names the variable so a refusal can say which one it read.
+ *
+ * Returns `undefined` when nothing in the chain answered. A transport whose
+ * engine bills an account turns that into {@link noBehaviourTokenRefusal}
+ * before sending anything: a request sent without the token is a request the
+ * engine will reject, and the refusal should name the variable rather than
+ * quote the engine's 401.
+ */
+export function behaviourTokenFrom(lexicon, env) {
+    for (const source of behaviourTokenVariables(lexicon)) {
+        const value = env[source]?.trim();
+        if (value)
+            return { value, source };
+    }
+    return undefined;
+}
+/** What a transport says when the engine bills an account and no variable named a token. */
+export function noBehaviourTokenMessage(lexicon, endpoint) {
+    const [scoped, chantWide, bare] = behaviourTokenVariables(lexicon);
+    return (`predictBehaviour has the ${lexicon} behaviour engine at ${redactEngineAddress(endpoint.value)}, ` +
+        `named by ${endpoint.source}, and no token to authenticate to it with, so nothing was sent. Set a ` +
+        `${chantWide} environment variable to the bearer token the engine issued — or ${bare} where nothing ` +
+        `else in the environment is chant's. ${scoped} is read first, for an estate whose lexicons are ` +
+        "priced by different engines on different accounts. The token goes in a header the engine reads " +
+        "and nowhere else; it is never in the request body and never in a message.");
+}
+/**
+ * The refusal for a metered engine with no token configured. `no-engine`,
+ * because that is the cause whose remedy is "set a variable" — the engine is
+ * named, reachable for all anyone knows, and unusable until one more variable
+ * is set. No `source`: the token chain is the chain this refusal is about, and
+ * nothing in it answered.
+ */
+export function noBehaviourTokenRefusal(lexicon, endpoint) {
+    const [, chantWide] = behaviourTokenVariables(lexicon);
+    return behaviourRefusal({
+        cause: "no-engine",
+        reason: noBehaviourTokenMessage(lexicon, endpoint),
+        remedy: `Set ${chantWide} to the bearer token the engine at ${redactEngineAddress(endpoint.value)} issued.`,
+    });
+}
+/**
+ * The refusal for an engine that answered and rejected the token it was sent.
+ * Also `no-engine`: the address is fine, the account is not the problem, and
+ * the one action is to set the named variable to a token the engine accepts.
+ * `source` is the token variable, not the address variable, because that is
+ * the one a consumer would tell somebody to change.
+ *
+ * `detail` is whatever the engine said, and it goes through
+ * {@link scrubEngineDetail}. The token's own value is never in a message: a
+ * transport passes the variable's name here and keeps the value to itself.
+ */
+export function rejectedBehaviourTokenRefusal(lexicon, endpoint, token, detail) {
+    return behaviourRefusal({
+        cause: "no-engine",
+        reason: `The ${lexicon} behaviour engine at ${redactEngineAddress(endpoint.value)}, named by ` +
+            `${endpoint.source}, answered and rejected the token ${token.source} holds ` +
+            `(${scrubEngineDetail(detail)}). The address is reachable and the account is not the problem; ` +
+            "the token is not one this engine accepts. No overlay is drawn and no figure is guessed locally.",
+        remedy: `Set ${token.source} to a bearer token the engine at ${redactEngineAddress(endpoint.value)} accepts.`,
+        source: token.source,
+    });
+}
+/** What a lexicon says when a variable named an engine and the engine did not answer. */
+export function unreachableBehaviourEngineMessage(lexicon, endpoint, detail) {
+    return (`predictBehaviour reached for the ${lexicon} behaviour engine at ${redactEngineAddress(endpoint.value)}, ` +
+        `named by ${endpoint.source}, and it did not answer: ${scrubEngineDetail(detail)}. No overlay is drawn and no figure is ` +
+        `guessed locally. Check the engine is up and that ${endpoint.source} names the address this ` +
+        "environment can reach.");
+}
+/**
+ * The refusal for an estate with no engine configured. The whole of the
+ * `no-engine` path, so no lexicon has to assemble one by hand.
+ */
+export function noBehaviourEngineRefusal(lexicon) {
+    const [, chantWide] = behaviourEngineVariables(lexicon);
+    return behaviourRefusal({
+        cause: "no-engine",
+        reason: noBehaviourEngineMessage(lexicon),
+        remedy: `Set ${chantWide} to the engine's address.`,
+    });
+}
+/** The refusal for a configured engine that did not answer. */
+export function unreachableBehaviourEngineRefusal(lexicon, endpoint, detail) {
+    return behaviourRefusal({
+        cause: "engine-unreachable",
+        reason: unreachableBehaviourEngineMessage(lexicon, endpoint, detail),
+        remedy: `Check the engine at ${redactEngineAddress(endpoint.value)} is reachable, or repoint ${endpoint.source}.`,
+        source: endpoint.source,
+    });
+}
+/**
+ * What a lexicon says when the engine answered and refused for want of money
+ * (#2359). Distinct from unreachable on purpose: the address is fine, the
+ * request arrived, and telling somebody to check their networking wastes the
+ * one thing a refusal is for.
+ */
+export function outOfCreditBehaviourEngineMessage(lexicon, endpoint, detail) {
+    return (`The ${lexicon} behaviour engine at ${redactEngineAddress(endpoint.value)}, named by ${endpoint.source}, ` +
+        `answered and refused: the account behind it is out of credit (${scrubEngineDetail(detail)}). The address is reachable and nothing ` +
+        "here is a networking problem. Add credit to the account this engine bills, or point " +
+        `${endpoint.source} at an engine on an account that has some. No overlay is drawn and no figure is ` +
+        "guessed locally.");
+}
+/** What a lexicon says when the engine answered and refused for a spent limit (#2359). */
+export function overQuotaBehaviourEngineMessage(lexicon, endpoint, detail) {
+    return (`The ${lexicon} behaviour engine at ${redactEngineAddress(endpoint.value)}, named by ${endpoint.source}, ` +
+        `answered and refused: a rate or volume limit is spent (${scrubEngineDetail(detail)}). The account has credit and the address is ` +
+        "reachable, so this usually clears when the engine's window rolls over. Wait for it, raise the limit " +
+        `on the account, or point ${endpoint.source} at an engine with its own budget. No overlay is drawn ` +
+        "and no figure is guessed locally.");
+}
+/** The refusal for an engine that answered and said the account has no balance (#2359). */
+export function outOfCreditBehaviourEngineRefusal(lexicon, endpoint, detail) {
+    return behaviourRefusal({
+        cause: "engine-out-of-credit",
+        reason: outOfCreditBehaviourEngineMessage(lexicon, endpoint, detail),
+        remedy: `Add credit to the account behind ${endpoint.source}, or repoint it at a funded engine.`,
+        source: endpoint.source,
+    });
+}
+/** The refusal for an engine that answered and said a limit is spent (#2359). */
+export function overQuotaBehaviourEngineRefusal(lexicon, endpoint, detail) {
+    return behaviourRefusal({
+        cause: "engine-over-quota",
+        reason: overQuotaBehaviourEngineMessage(lexicon, endpoint, detail),
+        remedy: `Wait for the engine's window to roll over, or raise the limit on the account behind ${endpoint.source}.`,
+        source: endpoint.source,
+    });
+}
+/**
+ * One wire cause onto the refusal builder that names it. The whole of the
+ * mapping every transport applies, so it is written once: a transport that
+ * classified the wire correctly and then reached for the wrong builder would
+ * send an operator to check a network that is answering.
+ */
+export function behaviourWireRefusal(lexicon, endpoint, cause, detail) {
+    switch (cause) {
+        case "engine-out-of-credit":
+            return outOfCreditBehaviourEngineRefusal(lexicon, endpoint, detail);
+        case "engine-over-quota":
+            return overQuotaBehaviourEngineRefusal(lexicon, endpoint, detail);
+        case "engine-unreachable":
+            return unreachableBehaviourEngineRefusal(lexicon, endpoint, detail);
+    }
+}
+/**
+ * The environment a transport hands a child process: `PATH`, and nothing else.
+ *
+ * Rule 3 says the engine never sees a credential, and
+ * {@link screenBehaviourRequest} enforces it on the request. A child that
+ * inherits `process.env` walks straight around that: the request is spotless
+ * and the child holds `AWS_SECRET_ACCESS_KEY` anyway. So a transport that
+ * spawns builds the environment from this and nothing more — `PATH` because
+ * the address is resolved against it, and no allowlist beyond that, because
+ * every name added is a name a credential could be sitting under. The
+ * command transport pins this by test (#2372); this is the rule it pins.
+ */
+export function behaviourEngineChildEnvironment(env = process.env) {
+    return { PATH: env.PATH ?? "" };
+}
+/* -------------------------------------------------------------------------- */
+/* Rendering                                                                  */
+/* -------------------------------------------------------------------------- */
+const RED = "\x1b[31m";
+const RESET = "\x1b[0m";
+/**
+ * Render a refusal for a terminal, in red.
+ *
+ * Red rather than the amber a degradation gets, because a missing engine is not
+ * a partial answer: every behaviour-derived figure and colour is gone, and the
+ * one thing the reader must not do is assume the numbers are merely late.
+ *
+ * `color` defaults to the same rule the rest of the CLI uses (`NO_COLOR`, and a
+ * TTY on stdout); pass it explicitly where the output is asserted on.
+ */
+export function renderBehaviourRefusal(refusal, options = {}) {
+    const color = options.color ?? (!process.env.NO_COLOR && process.stdout.isTTY !== false);
+    const body = `behaviour: refused (${refusal.cause}) — ${refusal.reason}\n  ${refusal.remedy}`;
+    return color ? `${RED}${body}${RESET}` : body;
+}
+/* -------------------------------------------------------------------------- */
+/* The request                                                                */
+/* -------------------------------------------------------------------------- */
+/**
+ * Names this contract refuses to carry, each declared `?: never` on
+ * {@link PredictBehaviourOptions} so the deliberate attempt is a compile error.
+ *
+ * This list is the *narrow* half of the guard and never the whole of it. A
+ * denylist of names cannot enforce "the engine never sees a credential" — the
+ * same argument that made `?: never` better than omission applies to every name
+ * the list omits, and `xApiKey`, `pat` and `Authorization` with a capital A all
+ * sailed past an earlier version of this file. What actually enforces the rule
+ * is {@link assertNoCredentialInOptions}, which walks values.
+ */
+export const CREDENTIAL_OPTION_KEYS = [
+    "token",
+    "credential",
+    "credentials",
+    "secret",
+    "secrets",
+    "password",
+    "apiKey",
+    "accessKey",
+    "secretKey",
+    "sessionToken",
+    "auth",
+    "authorization",
+    "bearer",
+    "privateKey",
+];
+/**
+ * Key names that are credential-shaped on their own but not as a substring —
+ * the two `CREDENTIAL_ENV_NAME` (./identity.ts) does not cover.
+ */
+const EXTRA_CREDENTIAL_KEYS = ["pat", "cookie"];
+/**
+ * Shortest string worth suspecting. Borrowed from `identity.ts`'s
+ * `MIN_CREDENTIAL_LENGTH`, and for the same reason: below it, a "secret" is a
+ * false positive.
+ */
+const MIN_CREDENTIAL_LENGTH = 8;
+/**
+ * Key suffixes that name a **reference to** a credential rather than a
+ * credential, and the handful of whole names that do the same.
+ *
+ * This is the correction that made the guard usable. Run over every distinct
+ * property key in this repo's own generated schemas, a bare substring match on
+ * `SECRET|TOKEN|PASSWORD|AUTH` refused 406 aws keys, 173 azure, 89 gcp and 7
+ * k8s — `imagePullSecrets`, `secretName`, `secretKeyRef` (all three are
+ * references to a Secret *by name*), `ClientToken` (an idempotency nonce on
+ * dozens of AWS resources), `CertificateAuthorityArn`, `authorizedNetworks`,
+ * `passwordPolicy`, `authMode`, `oauthScopes`. A `tags: { author: "…" }` was
+ * refused because `author` contains `auth`.
+ *
+ * None of those hold secret material, and every one of them is ordinary in real
+ * infrastructure, which #2357, #2359 and #2360 all assemble their requests from.
+ */
+const REFERENCE_KEY_SUFFIXES = [
+    "ref",
+    "refs",
+    "name",
+    "names",
+    "id",
+    "ids",
+    "arn",
+    "arns",
+    "count",
+    "validity",
+    "mode",
+    "modes",
+    "policy",
+    "policies",
+    "scope",
+    "scopes",
+    "network",
+    "networks",
+    "type",
+    "types",
+    "enabled",
+    "required",
+    "version",
+    "uri",
+    "url",
+    "urls",
+    "config",
+    "configs",
+    "settings",
+    "options",
+];
+/** Whole key names that are never credential material, whatever they contain. */
+const REFERENCE_KEY_NAMES = [
+    "imagepullsecrets",
+    "clienttoken",
+    // A Kubernetes boolean: "mount the service account's token into this pod".
+    // It holds no token and never did.
+    "automountserviceaccounttoken",
+    "author",
+    "authors",
+    "authority",
+    "secretsmanager",
+];
+/**
+ * `CREDENTIAL_ENV_NAME` with its underscores removed, derived from the same
+ * source so the two cannot drift.
+ *
+ * That pattern was written for environment variables, where the convention is
+ * `AWS_SECRET_ACCESS_KEY`, so several of its alternatives carry an underscore:
+ * `PRIVATE_KEY`, `ACCESS_KEY`, `SESSION_KEY`. Object keys are written
+ * `privateKey` and `accessKey`, which match none of them. Squashing both sides
+ * makes one rule cover `PRIVATE_KEY`, `privateKey`, `private-key` and
+ * `privatekey`.
+ */
+const CREDENTIAL_ENV_NAME_SQUASHED = new RegExp(CREDENTIAL_ENV_NAME.source.replace(/_/g, ""), "i");
+/**
+ * True when a string carries a password in userinfo — with or without a scheme.
+ *
+ * The scheme-less half matters: a DSN is routinely written
+ * `app:hunter2@db.internal:5432/prod`, with the driver supplying the scheme, and
+ * `new URL()` will not parse that at all.
+ */
+function hasUrlPassword(value) {
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(value)) {
+        try {
+            if (new URL(value).password !== "")
+                return true;
+        }
+        catch {
+            /* fall through to the scheme-less test */
+        }
+    }
+    // `user:pass@host` with no scheme. Both halves non-empty, no whitespace, and
+    // a host that looks like a host, so `mailto`-ish text and prose do not match.
+    return /^[^\s:@/]+:[^\s:@/]+@[A-Za-z0-9._-]+(?::\d+)?(?:[/?#]|$)/.test(value.trim());
+}
+/**
+ * True when a key name is credential-shaped, whatever its casing or separators.
+ *
+ * Reuses `CREDENTIAL_ENV_NAME`, which is a case-insensitive substring match over
+ * `SECRET|TOKEN|PASSWORD|PASSWD|CREDENTIAL|PRIVATE_KEY|APIKEY|API_KEY|ACCESS_KEY|SESSION_KEY|AUTH`.
+ * That one expression covers `Authorization`, `xApiKey`, `clientSecret`,
+ * `refreshToken`, `awsSecretAccessKey` and `x-api-key` — every name an earlier
+ * fixed 14-entry list here missed — because it is chant's existing answer to
+ * the same question and had already been widened by everyone who hit a gap.
+ */
+function isCredentialKey(key) {
+    const squashed = key.toLowerCase().replace(/[^a-z0-9]/g, "");
+    if (REFERENCE_KEY_NAMES.includes(squashed))
+        return false;
+    if (REFERENCE_KEY_SUFFIXES.some((s) => squashed.endsWith(s)))
+        return false;
+    if (EXTRA_CREDENTIAL_KEYS.includes(squashed))
+        return true;
+    return CREDENTIAL_ENV_NAME.test(key) || CREDENTIAL_ENV_NAME_SQUASHED.test(squashed);
+}
+/**
+ * True when a string is evidently a *pointer to* a secret rather than one.
+ *
+ * `AdminPassword` on `AWS::DirectoryService::MicrosoftAD` is a genuine
+ * credential field, and chant source almost always fills it with a
+ * `{{resolve:secretsmanager:…}}` string or an interpolation rather than a
+ * literal. Refusing those would refuse the correct way to write it.
+ */
+function looksLikeSecretReference(value) {
+    return (/^\{\{[^}]+\}\}$/.test(value.trim()) ||
+        /^\$\{[^}]+\}$/.test(value.trim()) ||
+        /^!(?:Ref|GetAtt|Sub|ImportValue)\b/.test(value.trim()) ||
+        /^arn:[a-z0-9-]*:secretsmanager:/i.test(value.trim()) ||
+        /^projects\/[^/]+\/secrets\/[^/]+/.test(value.trim()));
+}
+/**
+ * What a credential-shaped value is, or `undefined`. Named so a refusal can say
+ * which rule fired rather than "something looked wrong".
+ */
+function credentialValueShape(value) {
+    for (const re of CREDENTIAL_SHAPES) {
+        re.lastIndex = 0;
+        if (re.test(value))
+            return "a literal credential shape (PEM key, JWT or Authorization value)";
+    }
+    for (const { name, re } of CREDENTIAL_TOKEN_SHAPES) {
+        re.lastIndex = 0;
+        if (re.test(value))
+            return name;
+    }
+    if (hasUrlPassword(value))
+        return "a password in a URL's userinfo";
+    return undefined;
+}
+/** A URL-ish string with its userinfo blanked and its query dropped. */
+function stripUrlSecrets(value) {
+    if (!/^[a-z][a-z0-9+.-]*:\/\//i.test(value))
+        return value;
+    try {
+        const url = new URL(value);
+        const hadUserinfo = url.username !== "" || url.password !== "";
+        const hadQuery = url.search !== "";
+        // The fragment too. OAuth's implicit flow puts the access token there
+        // (`#access_token=…`), it never reaches a server, and it was untouched.
+        const hadFragment = url.hash !== "";
+        url.username = "";
+        url.password = "";
+        url.search = "";
+        url.hash = "";
+        // Markers are appended AFTER `toString()` and in wire order — query then
+        // fragment. Appending the query marker to a string that still carried a
+        // fragment used to land it inside the fragment.
+        let out = url.toString();
+        if (hadUserinfo)
+            out = out.replace("://", `://${REDACTED}@`);
+        if (hadQuery)
+            out += `?${REDACTED}`;
+        if (hadFragment)
+            out += `#${REDACTED}`;
+        return out;
+    }
+    catch {
+        return value;
+    }
+}
+/**
+ * Blank the value of an inline command-line flag: `--token=x`, `-p x`,
+ * `--api-key x`. A behaviour engine may be a command on `PATH`, and a command
+ * carries its credential as an argument rather than in a URL, so the URL parse
+ * has nothing to bite on and `redactCredentialMaterial` — which knows env
+ * values and ten token prefixes — sees an inline flag value as neither.
+ */
+function stripFlagSecrets(value) {
+    return value
+        .replace(/(--?[A-Za-z0-9-]*(?:secret|token|password|passwd|key|credential|auth|pat)[A-Za-z0-9-]*)([=\s])(\S+)/gi, (_m, flag, sep) => `${flag}${sep}${REDACTED}`)
+        .replace(/(^|\s)(-[pPkK])(\s+)(\S+)/g, (_m, lead, flag, sp) => `${lead}${flag}${sp}${REDACTED}`);
+}
+/**
+ * An engine address, safe to interpolate into a refusal that a merge-request
+ * comment will carry (#2358).
+ *
+ * `CHANT_BEHAVIOUR_ENGINE=https://svc:s3cr3t@engine.internal/predict?key=abc` is
+ * an ordinary way to point at an authenticated endpoint, and it is the shape
+ * this contract's own "resolve auth on your own transport" guidance produces.
+ * Printing it verbatim in a refusal publishes it.
+ *
+ * Three passes, in order:
+ *
+ *  1. The URL parse blanks `username`/`password`, and drops the query string and
+ *     the fragment **whole** rather than by known parameter name — `?key=`,
+ *     `?token=`, `?sig=` and `#access_token=` are all common and the set is not
+ *     enumerable. The fragment matters on its own account: OAuth's implicit
+ *     flow puts the access token there.
+ *  2. Inline command-line flag values (`--token=…`, `-p …`), for an engine that
+ *     is a command on `PATH` rather than a URL.
+ *  3. {@link redactCredentialMaterial}, for env-held values and the token
+ *     shapes chant knows.
+ *
+ * **What survives:** a credential written as a bare path segment
+ * (`https://host/predict/<token>/go`) unless it matches a known token shape.
+ * Nothing here can tell that segment from a resource id, and an earlier version
+ * of this doc claimed pass 3 caught it, which was wrong. If an engine
+ * authenticates by path, do not put its address in a variable whose refusal
+ * text is published.
+ */
+export function redactEngineAddress(value, env = process.env) {
+    return redactCredentialMaterial(stripFlagSecrets(stripUrlSecrets(value)), env);
+}
+/**
+ * Engine-supplied detail, bounded and scrubbed before it reaches a refusal.
+ *
+ * `detail` on a credit or quota refusal is whatever the engine said, echoed.
+ * An engine is a third party: it can be verbose, and it can quote the request
+ * back at you, which is how a URL or an id ends up in a public comment. So the
+ * text is truncated, anything URL-shaped is reduced to its host, and the result
+ * goes through {@link redactCredentialMaterial}.
+ */
+export function scrubEngineDetail(detail, env = process.env) {
+    const withoutUrls = detail.replace(/\b[a-z][a-z0-9+.-]*:\/\/\S+/gi, (match) => {
+        try {
+            return new URL(match).host || REDACTED;
+        }
+        catch {
+            return REDACTED;
+        }
+    });
+    const scrubbed = redactCredentialMaterial(withoutUrls, env).replace(/\s+/g, " ").trim();
+    return scrubbed.length > MAX_ENGINE_DETAIL ? `${scrubbed.slice(0, MAX_ENGINE_DETAIL)}…` : scrubbed;
+}
+/** How much engine-supplied text a refusal will repeat. */
+const MAX_ENGINE_DETAIL = 200;
+const EDGE_COVERAGE_WITNESS = {
+    complete: true,
+    partial: true,
+    unknown: true,
+};
+/** Every legal {@link EdgeCoverageVerdict}. */
+export const EDGE_COVERAGE_VERDICTS = Object.keys(EDGE_COVERAGE_WITNESS);
+/** True when `value` is a legal {@link EdgeCoverageVerdict}. */
+export function isEdgeCoverageVerdict(value) {
+    return typeof value === "string" && EDGE_COVERAGE_VERDICTS.includes(value);
+}
+/**
+ * Refuse an edge-coverage claim that does not say anything.
+ *
+ * `partial` means "some references are known to be missing", and a `partial`
+ * with neither `dangling` nor `unresolvedKinds` names none of them — which is
+ * `unknown` wearing a more confident word. Use `unknown` for "I cannot say";
+ * `partial` is for "I can say, and here it is".
+ */
+/**
+ * A detached copy, frozen. The report's account of its own inputs must not
+ * change after the report exists, and `readonly` buys nothing at runtime.
+ */
+export function copyEdgeCoverage(coverage) {
+    const copy = {
+        verdict: coverage.verdict,
+        ...(coverage.dangling ? { dangling: Object.freeze(coverage.dangling.map((d) => Object.freeze({ ...d }))) } : {}),
+        ...(coverage.unresolvedKinds ? { unresolvedKinds: Object.freeze([...coverage.unresolvedKinds]) } : {}),
+        ...(coverage.containmentEdges
+            ? { containmentEdges: Object.freeze(coverage.containmentEdges.map((e) => Object.freeze({ ...e }))) }
+            : {}),
+    };
+    return Object.freeze(copy);
+}
+export function validateEdgeCoverage(coverage) {
+    if (!isEdgeCoverageVerdict(coverage?.verdict)) {
+        throw new Error(`predictBehaviour: edgeCoverage.verdict ${JSON.stringify(coverage?.verdict)} is not ` +
+            `${EDGE_COVERAGE_VERDICTS.join("/")}.`);
+    }
+    if (coverage.verdict === "partial" &&
+        (coverage.dangling?.length ?? 0) === 0 &&
+        (coverage.unresolvedKinds?.length ?? 0) === 0) {
+        throw new Error('predictBehaviour: edgeCoverage is "partial" and names nothing missing. Populate `dangling` ' +
+            'or `unresolvedKinds`, or say "unknown" — a partial that lists no gap is an unknown with a ' +
+            "more confident word on it.");
+    }
+}
+/** How deep the credential walk goes before it stops descending. */
+/**
+ * How deep the credential walk goes before it stops descending and says so.
+ *
+ * Budget the levels honestly: `options → entities → .get(name) → props` spends
+ * three before a single declared property is reached, so the number here is not
+ * the depth a lexicon author is thinking about. A Kubernetes workload tree
+ * (`spec.template.spec.containers[].env[].valueFrom.secretKeyRef.key`) or a
+ * nested CloudFormation `Properties` block runs to a dozen on its own, and
+ * exceeding this is now a *refusal* rather than silence — so a budget set too
+ * low refuses real estates instead of protecting them.
+ */
+const CREDENTIAL_WALK_DEPTH = 32;
+/**
+ * Every objection the walk has to a request. Pure, and exported so a caller can
+ * decide what to do rather than take this module's word for it.
+ */
+export function findCredentialsInOptions(options) {
+    const findings = [];
+    const seen = new WeakSet();
+    const walk = (value, path, depth) => {
+        if (depth > CREDENTIAL_WALK_DEPTH) {
+            // Not silence. A request deeper than the walk goes is a request this
+            // guard has not actually checked, and saying nothing about it is the
+            // shape of failure this whole contract exists to refuse.
+            findings.push({
+                path,
+                rule: "walk-depth",
+                what: `a structure deeper than ${CREDENTIAL_WALK_DEPTH} levels, which the credential walk did not read`,
+            });
+            return;
+        }
+        if (typeof value === "string") {
+            const shape = credentialValueShape(value);
+            if (shape)
+                findings.push({ path, rule: "value-shape", what: shape });
+            return;
+        }
+        if (value === null || typeof value !== "object")
+            return;
+        if (seen.has(value))
+            return;
+        seen.add(value);
+        if (Array.isArray(value)) {
+            value.forEach((item, i) => walk(item, `${path}[${i}]`, depth + 1));
+            return;
+        }
+        if (value instanceof Map) {
+            for (const [key, item] of value) {
+                const label = typeof key === "string" ? key : String(key);
+                const child = `${path}.get(${label})`;
+                // Both halves. A Map's KEY is as likely to be `DB_PASSWORD` as an
+                // object's is — an env block is the obvious case — and walking only
+                // values missed it entirely.
+                if (typeof key === "string")
+                    checkKey(key, child, item);
+                walk(item, child, depth + 1);
+            }
+            return;
+        }
+        if (value instanceof Set) {
+            let i = 0;
+            for (const item of value)
+                walk(item, `${path}.item[${i++}]`, depth + 1);
+            return;
+        }
+        for (const [key, item] of Object.entries(value)) {
+            const child = `${path}.${key}`;
+            checkKey(key, child, item);
+            walk(item, child, depth + 1);
+        }
+    };
+    /**
+     * The name arm. Gated on the value being a string long enough to be a secret,
+     * and not an evident reference to one — see {@link REFERENCE_KEY_SUFFIXES}
+     * for why the ungated version was unusable.
+     */
+    function checkKey(key, path, item) {
+        if (typeof item !== "string")
+            return;
+        if (item.length < MIN_CREDENTIAL_LENGTH)
+            return;
+        if (looksLikeSecretReference(item))
+            return;
+        if (!isCredentialKey(key))
+            return;
+        findings.push({ path, rule: "key-name", what: `a credential-shaped field name ("${key}")` });
+    }
+    walk(options, "options", 0);
+    return findings;
+}
+/**
+ * Throw when the request carries something that **is** a credential.
+ *
+ * **Not the entry point.** This applies one of the three rules and discards the
+ * other two, so a `key-name` hit and a `walk-depth` hit both pass it silently.
+ * Call {@link screenBehaviourRequest}, which runs this and then acts on what is
+ * left. This stays exported because "did the request contain an actual token"
+ * is a question worth asking on its own, and because the split is what keeps
+ * the blast radii different.
+ *
+ * Only the value-shape rule throws, and throwing is deliberate: a live token in
+ * a request bound for a third party is not a degradation to report, it is a
+ * stop. Throwing is the whole-lexicon failure per `lexicon.ts`, which is the
+ * right blast radius for this and the wrong one for a suspicious field name.
+ */
+export function assertNoCredentialInOptions(options) {
+    const found = findCredentialsInOptions(options).filter((f) => f.rule === "value-shape");
+    if (found.length === 0)
+        return;
+    const [first] = found;
+    throw new Error(`predictBehaviour was passed ${first.what} at ${first.path}. The behaviour engine is never handed ` +
+        "a credential: it is given the resource graph and a traffic level, and nothing it receives can " +
+        "reach the account. Remove it — a lexicon that needs authenticated access to its own engine " +
+        "resolves that on its own transport, not through this contract.");
+}
+/**
+ * Screen a whole request. **This is the entry point, and the only one.**
+ *
+ * This doc comment is the source of truth for the sequence; the module header
+ * and the authoring page both point here rather than restating it. A lexicon's
+ * `predictBehaviour` opens with exactly this and nothing else:
+ *
+ * ```ts
+ * const refusal = screenBehaviourRequest("acme", options);
+ * if (refusal) return refusal;
+ * ```
+ *
+ * Calling {@link assertNoCredentialInOptions} instead applies one rule of three
+ * and drops the rest, which is how a `ghp_…` token nested past the walk's depth
+ * budget, and an `awsSecretAccessKey` in `props`, both sailed through into a
+ * request that was then sent.
+ *
+ * Two outcomes, because two things are being caught and they deserve different
+ * blast radii:
+ *
+ *  - a value that IS a credential throws, via
+ *    {@link assertNoCredentialInOptions};
+ *  - a merely suspicious field name, or a structure too deep to have been read,
+ *    returns a {@link BehaviourRefusalReport} with cause
+ *    `credential-in-request`. No overlay is drawn and the reason names the
+ *    path, which is the contract's own answer to "no faked numbers" applied to
+ *    its own guard.
+ *
+ * The split exists because the name arm is a heuristic and the old version
+ * threw on it. One `tags: { author: "…" }` anywhere in an estate killed the
+ * entire overlay with a stack trace, which is the exact failure mode constraint
+ * 2 was written against.
+ *
+ * Returns `undefined` when the request is clean, so a lexicon reads
+ * `const refusal = screenBehaviourRequest(name, options); if (refusal) return refusal;`
+ */
+export function screenBehaviourRequest(lexicon, options) {
+    assertNoCredentialInOptions(options);
+    const findings = findCredentialsInOptions(options);
+    if (findings.length === 0)
+        return undefined;
+    const [first] = findings;
+    const more = findings.length > 1 ? ` (and ${findings.length - 1} more)` : "";
+    return behaviourRefusal({
+        cause: "credential-in-request",
+        reason: `The ${lexicon} behaviour request carries ${first.what} at ${first.path}${more}, so it was not ` +
+            "sent. The engine is a third party and this contract hands it the resource graph and a traffic " +
+            "level only. No overlay is drawn and no figure is guessed locally.",
+        remedy: "Remove the value from the declaration, or hold it in a secret reference the build does not " +
+            "expand. If the field is a false positive, it still leaves the process in this request.",
+    });
+}