@intentius/chant 0.65.0 → 0.66.0

package/src/behaviour-http.ts

@@ -0,0 +1,252 @@
+/**
+ * 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,
+  type BehaviourEngineEndpoint,
+  type BehaviourEngineToken,
+  type BehaviourRefusalReport,
+  type BehaviourTransport,
+  type BehaviourTransportOutcome,
+} from "./behaviour";
+import { REDACTED } from "./identity";
+
+/** What {@link httpBehaviourTransport} can be handed instead of the process's own. */
+export interface HttpBehaviourTransportDeps {
+  /** The `fetch` to send with. Defaults to the global, and a test hands in a fake. */
+  fetch?: typeof fetch;
+  /** How long the engine has before it is treated as unreachable. */
+  timeoutMs?: number;
+}
+
+/** The default deadline: the same one augur's command transport gives a child. */
+export const HTTP_BEHAVIOUR_TIMEOUT_MS = 30_000;
+
+/** 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: string): boolean {
+  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: BehaviourEngineToken, text: string): string {
+  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: string,
+  endpoint: BehaviourEngineEndpoint,
+  token: BehaviourEngineToken,
+  status: number,
+  detail: string,
+  retryAfter?: string,
+): BehaviourRefusalReport | undefined {
+  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: string): string {
+  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: string,
+  endpoint: BehaviourEngineEndpoint,
+  env: Record<string, string | undefined>,
+  deps: HttpBehaviourTransportDeps = {},
+): BehaviourTransport {
+  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(): Promise<BehaviourTransportOutcome> { return { ok: false, refusal }; } };
+  }
+
+  return {
+    async send(body: string): Promise<BehaviourTransportOutcome> {
+      let response: 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: unknown, timeoutMs: number): string {
+  if (err instanceof Error) {
+    if (err.name === "TimeoutError" || err.name === "AbortError") {
+      return `no answer within ${timeoutMs} ms`;
+    }
+    const cause = (err as { cause?: { code?: unknown; message?: unknown } }).cause;
+    const code = typeof cause?.code === "string" ? cause.code : undefined;
+    if (code) return `${code}: ${err.message}`;
+    return err.message;
+  }
+  return String(err);
+}

package/src/behaviour-overlay.test.ts

@@ -0,0 +1,149 @@
+/**
+ * The overlay projection (#2360), held to behold's reader.
+ *
+ * behold reads `meta._behaviour` as `{ engine?, version?, at?, total?,
+ * refusal? }` and short-circuits on `refusal`. A bare `BehaviourRefusal` put
+ * there has `reason` and `remedy` at its top level and no `refusal` key, so
+ * the reader finds no refusal, then no engine, and drops the meta as
+ * "meta.engine missing". The shape assertions below are that reader's rules,
+ * restated, and they are what gates. Point `CHANT_BEHOLD_CHECKOUT` at a behold
+ * checkout and the last block runs that reader itself against the same values,
+ * which is how the restatement is checked for drift.
+ */
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import {
+  behaviourRefusal,
+  behaviourReport,
+  noBehaviourEngineRefusal,
+  predictedRate,
+  type PredictedBehaviour,
+} from "./behaviour";
+import { BEHAVIOUR_OVERLAY_ATTR, behaviourOverlay } from "./behaviour-overlay";
+
+/**
+ * Opt-in: behold's own reader, from a checkout the runner names.
+ *
+ * The assertions in the first block restate that reader's rules, which is what
+ * gates. This block runs the real thing, and is how somebody with both
+ * repositories checked out confirms the restatement has not drifted from
+ * `src/behaviour.ts` in INTENTIUS/behold. Same shape as the opt-in blocks
+ * that need a real dogwood or a real helm: an env var plus the artefact
+ * actually being there, and never gating, because CI has one repository.
+ */
+const BEHOLD_READER = process.env.CHANT_BEHOLD_CHECKOUT
+  ? join(process.env.CHANT_BEHOLD_CHECKOUT, "src", "behaviour.ts")
+  : undefined;
+const haveBeholdReader = BEHOLD_READER !== undefined && existsSync(BEHOLD_READER);
+
+const block: PredictedBehaviour = {
+  at: { traffic: "100 rps, p50" },
+  cost: predictedRate(0.0416, "USD"),
+  headroom: { cpu: 0.6, latency: 0.4 },
+  errorRate: 0.0005,
+  resilience: { failure: "one zone lost", verdict: "survives" },
+  provenance: { engine: "fixture", version: "0.0.1", tolerance: "±20%", basis: "modeled" },
+};
+
+const report = behaviourReport(
+  { entityNames: ["web", "role"], traffic: "100 rps, p50", edgeCoverage: { verdict: "complete" } },
+  { engine: "fixture", version: "0.0.1", total: predictedRate(0.0416, "USD") },
+  { web: block },
+  { role: { reason: "unsupported-kind", detail: "a role is a grant" } },
+);
+
+describe("behaviourOverlay", () => {
+  it("puts the whole refusal report on meta, so behold finds a `refusal` key", () => {
+    const overlay = behaviourOverlay(noBehaviourEngineRefusal("terraform"));
+    const meta = overlay.meta[BEHAVIOUR_OVERLAY_ATTR] as unknown as Record<string, unknown>;
+    // behold's reader: `refusal` present, with a non-empty `reason` and `remedy`.
+    expect(meta.refusal).toBeDefined();
+    const refusal = meta.refusal as { reason?: string; remedy?: string; cause?: string };
+    expect(refusal.reason).toMatch(/CHANT_BEHAVIOUR_ENGINE/);
+    expect(refusal.remedy?.length).toBeGreaterThan(0);
+    expect(refusal.cause).toBe("no-engine");
+    // The envelope stays, so the value says which contract it is in.
+    expect(meta.behaviour).toBe("v1");
+    // A refusal is present instead of every figure.
+    expect(meta.engine).toBeUndefined();
+    expect(Object.keys(overlay.attrs)).toEqual([]);
+  });
+
+  it("does not flatten a refusal to its reason and remedy, which behold would drop", () => {
+    const bare = behaviourRefusal({ cause: "no-engine", reason: "no engine", remedy: "set it" }).refusal;
+    // What the contract doc once said to put there: the bare refusal. Its
+    // top level has no `refusal` key, which is the shape behold rejects.
+    expect("refusal" in bare).toBe(false);
+    const meta = behaviourOverlay(noBehaviourEngineRefusal("terraform")).meta[BEHAVIOUR_OVERLAY_ATTR];
+    expect("refusal" in meta).toBe(true);
+  });
+
+  it("puts the report's meta on meta and each entity's block on its node", () => {
+    const overlay = behaviourOverlay(report);
+    const meta = overlay.meta[BEHAVIOUR_OVERLAY_ATTR] as unknown as Record<string, unknown>;
+    expect(meta.engine).toBe("fixture");
+    expect(meta.version).toBe("0.0.1");
+    expect(meta.at).toEqual({ traffic: "100 rps, p50" });
+    expect(meta.total).toEqual({ rate: "per-hour", perHour: 0.0416, currency: "USD" });
+    expect(meta.refusal).toBeUndefined();
+    // The coverage the verdicts were computed over rides along for a reader
+    // that wants it; behold's reader ignores it.
+    expect((meta.edgeCoverage as { verdict: string }).verdict).toBe("complete");
+    expect(Object.keys(overlay.attrs)).toEqual(["web"]);
+    expect(overlay.attrs.web[BEHAVIOUR_OVERLAY_ATTR]).toBe(block);
+  });
+
+  it("gives an unpredicted entity no block at all, rather than one full of zeroes", () => {
+    const overlay = behaviourOverlay(report);
+    expect(Object.prototype.hasOwnProperty.call(overlay.attrs, "role")).toBe(false);
+  });
+
+  it("is safe for an entity named after a prototype member", () => {
+    // `Object.create(null)` and assignment, not a literal: `{ __proto__: x }`
+    // sets the prototype rather than adding a key, so the entity a lexicon
+    // believed it had reported would not be there to project. This is the
+    // same hazard the projection guards on its own writing side.
+    const entities = Object.create(null) as Record<string, PredictedBehaviour>;
+    for (const name of ["__proto__", "constructor"]) entities[name] = block;
+    const named = behaviourReport(
+      { entityNames: ["__proto__", "constructor"], traffic: "100 rps, p50", edgeCoverage: { verdict: "complete" } },
+      { engine: "fixture", version: "0.0.1" },
+      entities,
+    );
+    const overlay = behaviourOverlay(named);
+    expect(Object.keys(overlay.attrs).sort()).toEqual(["__proto__", "constructor"]);
+    expect(overlay.attrs.__proto__[BEHAVIOUR_OVERLAY_ATTR]).toBe(block);
+  });
+});
+
+describe.skipIf(!haveBeholdReader)("behold's own reader accepts the projection (opt-in)", () => {
+  it("validates a refusal meta as a refusal, and a report meta as a report", async () => {
+    const behold = (await import(/* @vite-ignore */ BEHOLD_READER!)) as {
+      validateBehaviourMeta(v: unknown): { ok: true; value: unknown } | { ok: false; reason: string };
+      validateBehaviourBlock(v: unknown): { ok: true; value: unknown } | { ok: false; reason: string };
+    };
+    const refused = behold.validateBehaviourMeta(
+      behaviourOverlay(noBehaviourEngineRefusal("terraform")).meta[BEHAVIOUR_OVERLAY_ATTR],
+    );
+    expect(refused.ok, refused.ok ? "" : refused.reason).toBe(true);
+    if (refused.ok) expect(Object.keys(refused.value as object)).toEqual(["refusal"]);
+
+    const reported = behold.validateBehaviourMeta(behaviourOverlay(report).meta[BEHAVIOUR_OVERLAY_ATTR]);
+    expect(reported.ok, reported.ok ? "" : reported.reason).toBe(true);
+    if (reported.ok) expect((reported.value as { engine: string }).engine).toBe("fixture");
+
+    const painted = behold.validateBehaviourBlock(behaviourOverlay(report).attrs.web[BEHAVIOUR_OVERLAY_ATTR]);
+    expect(painted.ok, painted.ok ? "" : painted.reason).toBe(true);
+  });
+
+  it("drops a bare refusal, which is why the whole report goes on meta", async () => {
+    const behold = (await import(/* @vite-ignore */ BEHOLD_READER!)) as {
+      validateBehaviourMeta(v: unknown): { ok: true } | { ok: false; reason: string };
+    };
+    const bare = behold.validateBehaviourMeta(noBehaviourEngineRefusal("terraform").refusal);
+    expect(bare.ok).toBe(false);
+    if (!bare.ok) expect(bare.reason).toBe("meta.engine missing");
+  });
+});

package/src/behaviour-overlay.ts

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

package/src/behaviour.test.ts

@@ -31,9 +31,11 @@ import {
   BEHAVIOUR_UNPREDICTED_REASONS,
   assertNoCredentialInOptions,
   copyEdgeCoverage,
+  behaviourEngineChildEnvironment,
   behaviourEngineFrom,
   behaviourEngineVariables,
   behaviourReport,
+  behaviourWireRefusal,
   compareFigures,
   compareProvenance,
   figureMismatches,
@@ -438,6 +440,54 @@ describe("an engine that answers and still refuses (#2359)", () => {
   });
 });
 
+describe("the transport's one mapping from wire cause to refusal (#2373)", () => {
+  const endpoint = { value: "https://engine.example/predict", source: "CHANT_BEHAVIOUR_ENGINE_ACME" };
+
+  test("each wire cause reaches its own builder, and no other", () => {
+    const broke = behaviourWireRefusal("acme", endpoint, "engine-out-of-credit", "balance 0.00 USD");
+    const throttled = behaviourWireRefusal("acme", endpoint, "engine-over-quota", "5000/5000");
+    const down = behaviourWireRefusal("acme", endpoint, "engine-unreachable", "ECONNREFUSED");
+    expect(broke).toEqual(outOfCreditBehaviourEngineRefusal("acme", endpoint, "balance 0.00 USD"));
+    expect(throttled).toEqual(overQuotaBehaviourEngineRefusal("acme", endpoint, "5000/5000"));
+    expect(down).toEqual(unreachableBehaviourEngineRefusal("acme", endpoint, "ECONNREFUSED"));
+    expect([broke, throttled, down].map((r) => r.refusal.cause)).toEqual([
+      "engine-out-of-credit",
+      "engine-over-quota",
+      "engine-unreachable",
+    ]);
+    // Every one names the variable that pointed at the engine.
+    for (const r of [broke, throttled, down]) expect(r.refusal.source).toBe("CHANT_BEHAVIOUR_ENGINE_ACME");
+  });
+
+  test("the remedies stay distinct through the mapping", () => {
+    const remedies = (["engine-out-of-credit", "engine-over-quota", "engine-unreachable"] as const).map(
+      (cause) => behaviourWireRefusal("acme", endpoint, cause, "x").refusal.remedy,
+    );
+    expect(new Set(remedies).size).toBe(3);
+    expect(remedies[0]).toMatch(/credit/);
+    expect(remedies[0]).not.toMatch(/reachable/);
+    expect(remedies[1]).toMatch(/window|limit/);
+    expect(remedies[1]).not.toMatch(/credit/);
+    expect(remedies[2]).toMatch(/reachable|repoint/);
+  });
+});
+
+describe("the environment a transport hands a child (#2372, pinned by the contract)", () => {
+  test("is PATH and nothing else, whatever this process holds", () => {
+    const env = {
+      PATH: "/usr/bin:/bin",
+      AWS_SECRET_ACCESS_KEY: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
+      CHANT_BEHAVIOUR_TOKEN: "a-token-the-child-must-not-see",
+      HOME: "/home/somebody",
+    };
+    expect(behaviourEngineChildEnvironment(env)).toEqual({ PATH: "/usr/bin:/bin" });
+  });
+
+  test("gives an empty PATH rather than none when the process has none", () => {
+    expect(behaviourEngineChildEnvironment({})).toEqual({ PATH: "" });
+  });
+});
+
 /* -------------------------------------------------------------------------- */
 /* The request carries edges, not just nodes                                  */
 /* -------------------------------------------------------------------------- */