@intentius/chant 0.124.12 → 0.124.14

package/dist/behaviour-engine.js

@@ -0,0 +1,357 @@
+/**
+ * The seam between core and whatever answers its request (#2357),
+ * on the contract's transport (#2373, decided in #2359).
+ *
+ * `packages/core/src/behaviour.ts` says what a prediction may mean, how an
+ * absent engine must refuse, and — since #2359 — how a request reaches an
+ * engine: a `BehaviourTransport` carries the rendered request and brings back
+ * the engine's text or a finished refusal. This file adds what is core's on
+ * top of that and nothing more: the parse of a `behaviour/v1` answer, a command
+ * transport for an address that is a program on `PATH`, and the chooser that
+ * turns an address into one transport or the other.
+ *
+ * {@link BehaviourEngine} is what `./predict-behaviour.ts` talks to. It is
+ * one level above the transport — request in, parsed answer or refusal out —
+ * so the fixture engine in `__fixtures__` can be one without pretending to be
+ * a wire, and so `predict-behaviour.ts` never sees a byte. {@link
+ * transportEngine} is the only bridge between the two levels.
+ *
+ * ## The two transports
+ *
+ * A **URL** is dialled by core's `httpBehaviourTransport`
+ * (`packages/core/src/behaviour-http.ts`): `POST`, a bearer token from
+ * `CHANT_BEHAVIOUR_TOKEN` → `BEHAVIOUR_TOKEN`,
+ * and the status mapping the contract fixes. Nothing about that is core's,
+ * which is why it does not live here.
+ *
+ * A **command on PATH** is {@link commandTransport}, below: request on stdin,
+ * answer on stdout, no shell — a shell would make the address a
+ * code-execution surface for whatever set the variable. The child gets
+ * `behaviourEngineChildEnvironment()` and nothing else, for the reason given
+ * on that function: the request-side screen cannot see an inherited
+ * `process.env`. An engine that answered and still refused says so on stderr,
+ * and the words it uses pick the cause.
+ *
+ * ## A malformed answer is unreachable, not a report with holes
+ *
+ * Taking the fields that parsed and reporting the rest unpredicted would turn
+ * an engine emitting garbage into an estate that looks partly free — the
+ * failure the refusal arm exists to prevent, one level down. So the parse
+ * refuses whole, with a detail naming the entity and the field.
+ *
+ * With one exception, and it is the same rule the command transport applies
+ * to stderr: an engine that took the request, answered `200`, and wrote
+ * `{"error": "out of credit"}` has refused for a reason a status never
+ * carried. {@link transportEngine} reads that body's words after the parse
+ * has failed and never before, so an answer that priced the estate and
+ * declined one node "rate limit reached for this region" stays the report it
+ * is. Both transports reach the same three causes; only the evidence differs.
+ */
+import { execFile } from "node:child_process";
+import { behaviourEngineChildEnvironment, behaviourWireRefusal, isBehaviourBasis, isResilienceVerdict, unreachableBehaviourEngineRefusal, } from "./behaviour.js";
+import { httpBehaviourTransport, isHttpBehaviourAddress } from "./behaviour-http.js";
+import { renderEngineRequest } from "./behaviour-request.js";
+/**
+ * The name a refusal is built under.
+ *
+ * It was the predicting lexicon's name while a lexicon predicted. Core
+ * predicts for the whole project since #2382, so there is no lexicon to scope
+ * the variable chain by: the chain is the chant-wide one, and this is the word
+ * a message uses for the thing that refused.
+ */
+export const BEHAVIOUR_SCOPE = "chant";
+/**
+ * A {@link BehaviourEngine} over a contract transport: render the request
+ * canonically, send it, parse what came back. The one bridge between the
+ * transport level and the engine level, so the parse runs on every wire and
+ * no transport gets its own.
+ */
+export function transportEngine(transport, endpoint) {
+    return {
+        async predict(request) {
+            const sent = await transport.send(renderEngineRequest(request));
+            if (!sent.ok)
+                return { ok: false, refusal: sent.refusal };
+            const parsed = parseEngineAnswer(sent.body);
+            if (!parsed.ok) {
+                // An engine that answers 200 with an error envelope is a real shape,
+                // and its own words are the only thing that says which refusal it is.
+                // Read after the parse and never before: an answer that priced the
+                // estate and declined one node "rate limit reached for this region"
+                // parses, and a vocabulary check running first would turn a report
+                // about the other nodes into an over-quota refusal about none.
+                const said = causeFromEngineWords(sent.body);
+                if (said) {
+                    return {
+                        ok: false,
+                        refusal: behaviourWireRefusal(BEHAVIOUR_SCOPE, endpoint, said, `the engine answered ${firstLine(sent.body)}`),
+                    };
+                }
+                return { ok: false, refusal: unreachableBehaviourEngineRefusal(BEHAVIOUR_SCOPE, endpoint, parsed.detail) };
+            }
+            return { ok: true, answer: parsed.answer };
+        },
+    };
+}
+/** How long a command engine is given before it is treated as unreachable. */
+const COMMAND_TIMEOUT_MS = 30000;
+/** How much stdout is read before the answer is treated as malformed. */
+const COMMAND_MAX_BUFFER = 8 * 1024 * 1024;
+/**
+ * A `command on PATH` address, run as a subprocess: the contract's
+ * `BehaviourTransport` for the third kind of address it names.
+ *
+ * The address is split on whitespace into a program and its arguments, which
+ * is the shape `CHANT_BEHAVIOUR_ENGINE="my-engine --model tiny"` produces.
+ * No shell: a shell would make the address a code-execution surface for
+ * whatever set the variable, and every argument the address needs can be
+ * written without one.
+ */
+export function commandTransport(endpoint) {
+    const [program, ...args] = endpoint.value.trim().split(/\s+/);
+    return {
+        async send(body) {
+            const raw = await new Promise((resolve) => {
+                const child = execFile(program, args, {
+                    timeout: COMMAND_TIMEOUT_MS,
+                    maxBuffer: COMMAND_MAX_BUFFER,
+                    // Not `process.env`. The contract's rule, and its reason, are on
+                    // `behaviourEngineChildEnvironment`; the test below pins it.
+                    env: behaviourEngineChildEnvironment(),
+                }, (error, stdout, stderr) => {
+                    resolve({ stdout: String(stdout), stderr: String(stderr), ...(error ? { error } : {}) });
+                });
+                child.stdin?.end(body);
+            });
+            if (raw.error) {
+                return {
+                    ok: false,
+                    refusal: behaviourWireRefusal(BEHAVIOUR_SCOPE, endpoint, causeFromEngineWords(raw.stderr) ?? "engine-unreachable", firstLine(raw.stderr) || raw.error.message),
+                };
+            }
+            return { ok: true, body: raw.stdout };
+        },
+    };
+}
+/** {@link commandTransport}, bridged to the engine level. */
+export function commandEngine(endpoint) {
+    return transportEngine(commandTransport(endpoint), endpoint);
+}
+/**
+ * An engine that answered and still refused says so in words, and the three
+ * causes want three different actions (`behaviour.ts`'s remedy table). Matched
+ * on the words an engine would use rather than on an exit code or an HTTP
+ * status, because the contract fixes no exit codes, inventing some would bind
+ * every future engine to this file, and a status is only available on one of
+ * the two transports anyway.
+ *
+ * Both transports read it, on the text each has: a command's stderr, and an
+ * HTTP body that failed to parse as an answer. `./behaviour-http.ts` has
+ * already classified every status that carries one, so this runs on the case
+ * a status does not cover — the engine that took the request, answered 200,
+ * and put its refusal in the envelope.
+ */
+function causeFromEngineWords(said) {
+    const text = said.toLowerCase();
+    if (/\b(out of credit|insufficient (funds|balance)|no balance|payment required)\b/.test(text)) {
+        return "engine-out-of-credit";
+    }
+    if (/\b(over quota|quota exceeded|rate limit|too many requests|throttl)/.test(text)) {
+        return "engine-over-quota";
+    }
+    return undefined;
+}
+function firstLine(text) {
+    return text.split("\n").find((line) => line.trim().length > 0)?.trim() ?? "";
+}
+/**
+ * Everything wrong with one figure, as readable field paths. Empty means the
+ * figure is usable.
+ *
+ * Pure and exported so the shapes an engine can get wrong are testable without
+ * a subprocess. Every check here mirrors one `validateBehaviourBlock` applies
+ * downstream (`packages/core/src/behaviour.ts`) — the difference is *when*:
+ * that one throws, and a throw is the whole-lexicon failure `lexicon.ts`
+ * reserves for a live credential. A third party emitting one bad number is not
+ * that, and reporting it as that is how an operator goes looking for a leak.
+ */
+export function figureProblems(name, figure) {
+    const at = (field) => `figures.${name}.${field}`;
+    if (typeof figure !== "object" || figure === null || Array.isArray(figure)) {
+        return [`${at("")} is ${Array.isArray(figure) ? "an array" : typeof figure}, not an object`];
+    }
+    const f = figure;
+    const out = [];
+    const fraction = (field, value) => {
+        if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > 1) {
+            out.push(`${at(field)} is not a number in 0..1`);
+        }
+    };
+    if (typeof f.perHour !== "number" || !Number.isFinite(f.perHour) || f.perHour < 0) {
+        out.push(`${at("perHour")} is not a non-negative finite number`);
+    }
+    if (typeof f.currency !== "string" || f.currency.trim().length === 0) {
+        out.push(`${at("currency")} is empty`);
+    }
+    fraction("errorRate", f.errorRate);
+    const headroom = f.headroom;
+    if (typeof headroom !== "object" || headroom === null || Array.isArray(headroom)) {
+        out.push(`${at("headroom")} is missing`);
+    }
+    else {
+        const h = headroom;
+        // At least one axis, and an axis the engine did not model must be absent
+        // rather than zero — zero headroom means saturated, the opposite claim.
+        if (h.cpu === undefined && h.latency === undefined) {
+            out.push(`${at("headroom")} carries neither cpu nor latency`);
+        }
+        for (const axis of ["cpu", "latency"]) {
+            if (h[axis] !== undefined)
+                fraction(`headroom.${axis}`, h[axis]);
+        }
+    }
+    const resilience = f.resilience;
+    if (typeof resilience !== "object" || resilience === null || Array.isArray(resilience)) {
+        out.push(`${at("resilience")} is missing`);
+    }
+    else {
+        const r = resilience;
+        if (typeof r.failure !== "string" || r.failure.trim().length === 0) {
+            out.push(`${at("resilience.failure")} names no failure`);
+        }
+        if (!isResilienceVerdict(r.verdict)) {
+            out.push(`${at("resilience.verdict")} is not survives/degrades/fails`);
+        }
+        if (r.note !== undefined && typeof r.note !== "string") {
+            out.push(`${at("resilience.note")} is not a string`);
+        }
+    }
+    const rightSize = f.rightSize;
+    if (rightSize !== undefined) {
+        if (typeof rightSize !== "object" || rightSize === null || Array.isArray(rightSize)) {
+            out.push(`${at("rightSize")} is not an object`);
+        }
+        else if (typeof rightSize.suggestion !== "string") {
+            out.push(`${at("rightSize.suggestion")} is missing`);
+        }
+    }
+    return out;
+}
+/** One malformed verdict, with the detail the refusal will scrub and print. */
+function malformed(detail) {
+    return { ok: false, detail };
+}
+/**
+ * Parse an engine's text into an {@link EngineAnswer}.
+ *
+ * A malformed answer is `engine-unreachable` and not a report full of holes.
+ * The alternative — taking the fields that parsed and reporting the rest as
+ * unpredicted — would turn an engine emitting garbage into an estate that
+ * looks partially free, which is the failure the refusal arm exists to
+ * prevent, one level down.
+ *
+ * **Every figure is validated here, not only the envelope.** The first version
+ * of this function checked `engine`/`version`/`tolerance`/`basis` and that
+ * `figures` was an object, and then handed each figure's contents straight to
+ * `block()` in `./predict-behaviour.ts`, which dereferenced
+ * `figure.resilience.failure`. Seven malformed shapes were executed against
+ * it and all seven threw: three as bare `TypeError`s with no chant message,
+ * four through `validateBehaviourBlock` after the fact. A throw is the
+ * whole-lexicon failure `lexicon.ts` reserves for a live credential in the
+ * request, so a third-party engine emitting one bad number was indistinguishable
+ * from a leak — and the doc above claimed the opposite was happening.
+ *
+ * The detail names the entity and the field, because "the engine sent
+ * something wrong" is not a thing anybody can act on and "figures.web.headroom
+ * carries neither cpu nor latency" is. It flows into
+ * `unreachableBehaviourEngineRefusal`, which runs it through
+ * `scrubEngineDetail` and bounds it.
+ */
+export function parseEngineAnswer(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return malformed(`the engine wrote ${text.length} byte(s) that are not JSON`);
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        return malformed("the engine's answer is not an object");
+    }
+    const answer = parsed;
+    const missing = ["engine", "version", "tolerance"].filter((key) => typeof answer[key] !== "string" || answer[key].trim().length === 0);
+    if (missing.length > 0) {
+        return malformed(`the engine's answer states no ${missing.join(", ")}. Every figure carries provenance, so an ` +
+            "answer that cannot say who produced it is not a usable answer");
+    }
+    // A closed enum downstream, so a free-form basis is caught here rather than
+    // by a throw from `validateBehaviourBlock` after the report is half built.
+    if (!isBehaviourBasis(answer.basis)) {
+        return malformed(`the engine's answer states a basis of ${JSON.stringify(answer.basis)}, which is not ` +
+            "modeled or validated");
+    }
+    if (typeof answer.figures !== "object" || answer.figures === null || Array.isArray(answer.figures)) {
+        // `Array.isArray` explicitly: `typeof [] === "object"`, so `figures: []`
+        // parsed clean and produced a report in which every node had been lost.
+        return malformed("the engine's answer carries no figures map");
+    }
+    if (answer.total !== undefined) {
+        const total = answer.total;
+        if (typeof total !== "object" ||
+            total === null ||
+            typeof total.perHour !== "number" ||
+            !Number.isFinite(total.perHour) ||
+            total.perHour < 0 ||
+            typeof total.currency !== "string" ||
+            total.currency.trim().length === 0) {
+            return malformed("the engine's answer states a total that is not a non-negative rate in a named currency");
+        }
+    }
+    if (answer.declined !== undefined) {
+        const declined = answer.declined;
+        if (typeof declined !== "object" || declined === null || Array.isArray(declined)) {
+            return malformed("the engine's answer carries a declined list that is not a map");
+        }
+        for (const [name, reason] of Object.entries(declined)) {
+            if (typeof reason !== "string") {
+                return malformed(`the engine declined ${name} with a reason that is not a string`);
+            }
+        }
+    }
+    const problems = [];
+    for (const [name, figure] of Object.entries(answer.figures)) {
+        problems.push(...figureProblems(name, figure));
+        if (problems.length >= 5)
+            break;
+    }
+    if (problems.length > 0) {
+        return malformed(`the engine's answer is malformed: ${problems.slice(0, 5).join("; ")}` +
+            (problems.length >= 5 ? " (and possibly more)" : ""));
+    }
+    return { ok: true, answer: answer };
+}
+/**
+ * The transport chooser, with what the HTTP transport needs injectable.
+ *
+ * A `http://` or `https://` address gets core's `httpBehaviourTransport`,
+ * with its token read from `env` — the same `env` the address was read from,
+ * so a test drives both chains from one object. A bare address gets
+ * {@link commandTransport}. Any other scheme (`grpc://`, `unix://`) gets
+ * `undefined`, and the caller refuses naming the address: no transport here
+ * speaks it, and saying so beats a guess.
+ */
+export function connectWith(deps = {}) {
+    return (endpoint, env) => {
+        const address = endpoint.value.trim();
+        if (address.length === 0)
+            return undefined;
+        if (isHttpBehaviourAddress(address)) {
+            return transportEngine(httpBehaviourTransport(BEHAVIOUR_SCOPE, endpoint, env, deps), endpoint);
+        }
+        if (/^[a-z][a-z0-9+.-]*:\/\//i.test(address))
+            return undefined;
+        return commandEngine(endpoint);
+    };
+}
+/** The chooser the shipped plugin uses: the process's own `fetch`, the default deadline. */
+export const defaultConnect = connectWith();

package/dist/behaviour-graph.js

@@ -0,0 +1,83 @@
+/**
+ * The seam between a graph read and a prediction (#2377, epic #2355).
+ *
+ * `./behaviour-overlay.ts` projects a {@link BehaviourResult} onto the two
+ * channels the IR carries it on. This module is the other half: it builds the
+ * request from the graph the read already holds, and puts the projection back
+ * onto that graph. Both halves are pure, and neither calls an engine — the
+ * plugin call itself lives in `./cli/handlers/graph.ts`, which is the only
+ * place that has plugins to call.
+ *
+ * ## The request is the graph, not a second read
+ *
+ * The epic's rule is that the engine never sees credentials, and the way this
+ * path keeps that true is by never reading anything: `chant graph --live`
+ * already observed the estate, and {@link behaviourRequestFromIr} reshapes
+ * exactly those nodes and edges into the contract's options. There is no
+ * provider call here and nothing to leak, because there is no second read to
+ * leak from. `screenBehaviourRequest` (`./behaviour-predict.ts`) still screens
+ * what this produces; a node whose observed `attrs` picked up a secret is
+ * caught there, on the one path every prediction goes through.
+ *
+ * ## Why `attrs` are the props verbatim
+ *
+ * An IR node's `attrs` are what the read resolved — literals, and `{ $ref }`
+ * for a reference. The contract's `props` is the same thing, so this passes
+ * them across unchanged rather than filtering to a "useful" subset. Filtering
+ * would be chant deciding which properties can affect a price, and chant does
+ * not price anything; an engine that needs a field chant thought irrelevant
+ * would get a silently wrong figure with nothing to say so.
+ */
+import { BEHAVIOUR_OVERLAY_ATTR } from "./behaviour-overlay.js";
+/**
+ * Reshape an already-read graph into `predictBehaviour`'s options.
+ *
+ * Entity identity is the node's `id` and nothing derived from it. That is the
+ * same key the drift overlay writes `_status` under and the same key
+ * {@link applyBehaviourOverlay} reads back, so in a multi-stack project where
+ * ids are `${stack}::${logicalId}`, the block lands on the node it was
+ * predicted for without this module knowing that qualification exists.
+ */
+export function behaviourRequestFromIr(ir, ctx) {
+    const entities = new Map();
+    for (const node of ir.nodes) {
+        entities.set(node.id, { entityType: node.kind, props: node.attrs });
+    }
+    return {
+        environment: ctx.environment,
+        buildOutput: ctx.buildOutput,
+        entityNames: [...entities.keys()],
+        entities,
+        edges: ir.edges,
+        edgeCoverage: ctx.edgeCoverage,
+        from: ctx.from,
+        traffic: ctx.traffic,
+        ...(ctx.stack === undefined ? {} : { stack: ctx.stack }),
+        ...(ctx.region === undefined ? {} : { region: ctx.region }),
+        ...(ctx.owned === undefined ? {} : { owned: ctx.owned }),
+    };
+}
+/**
+ * Put a projection back onto the graph: each entity's block on its node's
+ * `attrs`, the graph-level half on `ir.meta`.
+ *
+ * A node with no entry keeps the `attrs` object it already had, untouched —
+ * an unpriced entity carries no `_behaviour` key rather than an empty or
+ * zeroed one, because zero cost and "not priced" are different claims and a
+ * renderer cannot tell them apart after the fact.
+ *
+ * Returns a new graph and mutates nothing: the caller's `ir` is shared with
+ * the lens pipeline downstream, and a prediction is not allowed to be the
+ * reason a later pass sees different nodes.
+ */
+export function applyBehaviourOverlay(ir, overlay) {
+    const nodes = ir.nodes.map((node) => {
+        const block = overlay.attrs[node.id];
+        return block === undefined ? node : { ...node, attrs: { ...node.attrs, ...block } };
+    });
+    return {
+        ...ir,
+        nodes,
+        meta: { ...(ir.meta ?? {}), [BEHAVIOUR_OVERLAY_ATTR]: overlay.meta[BEHAVIOUR_OVERLAY_ATTR] },
+    };
+}

package/dist/behaviour-http.js

@@ -0,0 +1,188 @@
+/**
+ * The first engine adapter (#2359): a {@link BehaviourTransport} that dials a
+ * URL with a bearer token, and maps what the wire says onto the contract's
+ * refusals.
+ *
+ * Unnamed on purpose. Nothing here is a vendor's API; it is the shape any
+ * metered HTTP engine has — an address, an account, a request body, and four
+ * ways the account or the wire can say no — so a second engine behind the
+ * same shape is a second address and a second token, not a second adapter.
+ * What this file knows about the engine is that it accepts a JSON body by
+ * `POST`, answers with a JSON body, and uses the HTTP status the way HTTP
+ * says to: `402` for an account with nothing left on it, `429` for a limit
+ * that is spent, `401`/`403` for a token it does not accept.
+ *
+ * ## The token is on the wire and nowhere else
+ *
+ * Rule 3 of the contract — the engine is never handed a credential — is about
+ * the request body, and `screenBehaviourRequest` has already walked the body
+ * by the time a transport exists. The bearer token here is a different thing:
+ * it is how the engine knows whose account to bill, it travels in the
+ * `authorization` header, and this module is the only code that holds its
+ * value. Four things follow, and each has a test:
+ *
+ *   - it is resolved from {@link behaviourTokenFrom}'s chain, never from the
+ *     address chain, so no message that prints the address can print it;
+ *   - it is never interpolated into a refusal, a `detail`, or an error — the
+ *     variable's *name* is what a refusal carries;
+ *   - whatever the engine writes back is passed through {@link concealing}
+ *     before it becomes a `detail`, because an engine that echoes its request
+ *     headers into an error page would otherwise put the token in a
+ *     merge-request comment (#2358 posts refusals publicly);
+ *   - the request is sent with `redirect: "error"`, so a `3xx` from the
+ *     address named is a refusal rather than a second request carrying the
+ *     header to whatever host the redirect names.
+ *
+ * ## No token, nothing sent
+ *
+ * This adapter is for an engine that bills an account: `engine-out-of-credit`
+ * and `engine-over-quota` are statements about an account, and an engine
+ * with no account has neither. So a token is required, and a missing one is
+ * refused before anything is sent — {@link noBehaviourTokenRefusal}, naming
+ * the chain — rather than sent bare and reported as whatever the engine's
+ * 401 page said. An engine that needs no token is not this adapter's, and
+ * the address chain still reaches it through a command on `PATH`.
+ *
+ * ## What the wire says, and what it becomes
+ *
+ * | Wire | Cause | Why |
+ * |---|---|---|
+ * | `2xx` | — | the body is the answer; the lexicon validates it |
+ * | `401`, `403` | `no-engine` | the token was rejected; the remedy is to set the variable |
+ * | `402` | `engine-out-of-credit` | the address answered; the account is empty |
+ * | `429` | `engine-over-quota` | the address answered; a limit is spent; `retry-after` is echoed |
+ * | any other status | `engine-unreachable` | the engine did not answer the question — a `5xx`, a `404`, a `3xx` |
+ * | `fetch` threw | `engine-unreachable` | connection refused, no such host, TLS, or the timeout |
+ *
+ * `4xx` outside the three named is deliberately `engine-unreachable` rather
+ * than a fifth cause. The contract's four causes are four remedies, and "the
+ * engine rejected this request as malformed" has no remedy an operator can
+ * apply — it is a bug on one side of the wire or the other, and the detail
+ * names the status so whoever reads it can tell which side.
+ */
+import { behaviourTokenFrom, behaviourWireRefusal, noBehaviourTokenRefusal, rejectedBehaviourTokenRefusal, } from "./behaviour.js";
+import { REDACTED } from "./identity.js";
+/** The default deadline: the same one the command transport gives a child. */
+export const HTTP_BEHAVIOUR_TIMEOUT_MS = 30000;
+/** How much of an error body a `detail` repeats. `scrubEngineDetail` bounds it again downstream. */
+const MAX_BODY_IN_DETAIL = 300;
+/** True when an address is one this adapter dials. `grpc://` and friends are not. */
+export function isHttpBehaviourAddress(value) {
+    return /^https?:\/\//i.test(value.trim());
+}
+/**
+ * Every occurrence of the token's value replaced, in text that came from the
+ * engine or from an error. Exported so a test can assert on the one function
+ * every `detail` passes through.
+ *
+ * `split`/`join` rather than a `RegExp`, so a token containing `.` or `+` is
+ * matched as itself. Nothing shorter than four characters is concealed: a
+ * one-letter "token" would blank every occurrence of that letter, which is a
+ * detail nobody can read and a false sense that something was protected.
+ */
+export function concealing(token, text) {
+    if (token.value.length < 4 || !text.includes(token.value))
+        return text;
+    return text.split(token.value).join(REDACTED);
+}
+/**
+ * The refusal an HTTP status earns, or `undefined` for a status that carries
+ * an answer. Pure and exported so the whole table in the module doc is one
+ * function a test can walk.
+ *
+ * `detail` is the first non-empty line of the response body, already
+ * concealed; this adds the status in front of it so a `detail` never reads as
+ * the engine's prose alone.
+ */
+export function httpStatusRefusal(lexicon, endpoint, token, status, detail, retryAfter) {
+    if (status >= 200 && status < 300)
+        return undefined;
+    const said = detail.trim().length > 0 ? `: ${detail.trim()}` : "";
+    if (status === 401 || status === 403) {
+        return rejectedBehaviourTokenRefusal(lexicon, endpoint, token, `HTTP ${status}${said}`);
+    }
+    if (status === 402) {
+        // The account is the token's, so the variable that named the token is
+        // the one an operator funds — put it first, ahead of whatever the
+        // engine said, so `scrubEngineDetail`'s bound never drops it.
+        return behaviourWireRefusal(lexicon, endpoint, "engine-out-of-credit", `the account ${token.source} authenticates answered HTTP 402${said}`);
+    }
+    if (status === 429) {
+        const window = retryAfter && retryAfter.trim().length > 0 ? `, retry after ${retryAfter.trim()}` : "";
+        return behaviourWireRefusal(lexicon, endpoint, "engine-over-quota", `the account ${token.source} authenticates answered HTTP 429${window}${said}`);
+    }
+    return behaviourWireRefusal(lexicon, endpoint, "engine-unreachable", `HTTP ${status}${said || " with no body"}`);
+}
+/** The first non-empty line of a body, bounded, for a `detail`. */
+function firstLine(text) {
+    const line = text.split("\n").find((l) => l.trim().length > 0)?.trim() ?? "";
+    return line.length > MAX_BODY_IN_DETAIL ? `${line.slice(0, MAX_BODY_IN_DETAIL)}…` : line;
+}
+/**
+ * Build the transport for one lexicon against one URL.
+ *
+ * The token is resolved here, once, from `env` — never from `process.env`
+ * unless that is what was passed — so a test can drive the whole wire with an
+ * environment of its own. A missing token makes a transport whose every
+ * `send` refuses by name and sends nothing; see the module doc for why that is
+ * the honest shape for an adapter whose engine bills an account.
+ */
+export function httpBehaviourTransport(lexicon, endpoint, env, deps = {}) {
+    const token = behaviourTokenFrom(lexicon, env);
+    const send = deps.fetch ?? globalThis.fetch;
+    const timeoutMs = deps.timeoutMs ?? HTTP_BEHAVIOUR_TIMEOUT_MS;
+    if (!token) {
+        const refusal = noBehaviourTokenRefusal(lexicon, endpoint);
+        return { async send() { return { ok: false, refusal }; } };
+    }
+    return {
+        async send(body) {
+            let response;
+            try {
+                response = await send(endpoint.value.trim(), {
+                    method: "POST",
+                    headers: {
+                        "content-type": "application/json",
+                        accept: "application/json",
+                        authorization: `Bearer ${token.value}`,
+                    },
+                    body,
+                    // A redirect would carry the header above to whatever host the
+                    // engine named. Refused here, reported as unreachable below.
+                    redirect: "error",
+                    signal: AbortSignal.timeout(timeoutMs),
+                });
+            }
+            catch (err) {
+                return {
+                    ok: false,
+                    refusal: behaviourWireRefusal(lexicon, endpoint, "engine-unreachable", concealing(token, describeFetchError(err, timeoutMs))),
+                };
+            }
+            const text = await response.text().catch(() => "");
+            const refusal = httpStatusRefusal(lexicon, endpoint, token, response.status, concealing(token, firstLine(text)), response.headers.get("retry-after") ?? undefined);
+            if (refusal)
+                return { ok: false, refusal };
+            return { ok: true, body: concealing(token, text) };
+        },
+    };
+}
+/**
+ * A thrown `fetch` in words an operator can act on. Node's `fetch` wraps the
+ * socket error one level down (`err.cause.code`), and the timeout arrives as
+ * a `TimeoutError` DOMException; both are named here rather than left as
+ * `fetch failed`, which says nothing about which of the two it was.
+ */
+function describeFetchError(err, timeoutMs) {
+    if (err instanceof Error) {
+        if (err.name === "TimeoutError" || err.name === "AbortError") {
+            return `no answer within ${timeoutMs} ms`;
+        }
+        const cause = err.cause;
+        const code = typeof cause?.code === "string" ? cause.code : undefined;
+        if (code)
+            return `${code}: ${err.message}`;
+        return err.message;
+    }
+    return String(err);
+}