@intentius/chant 0.64.0 → 0.66.0

package/src/cli/handlers/scenario.test.ts

@@ -8,6 +8,8 @@ import { Scenario, snapshot } from "../../lifecycle/scenario";
 import { EffectReceipt, receiptExpectation, type EffectReceiptDeclaration } from "../../effect-receipt";
 import type { ResourceMetadata } from "../../lexicon";
 import type { LifecycleSnapshot } from "../../lifecycle/types";
+import { behaviourReport, noBehaviourEngineRefusal, predictedRate } from "../../behaviour";
+import type { PredictedBehaviour } from "../../behaviour";
 
 const buildMock = vi.fn();
 const fetchLifecycleMock = vi.fn();
@@ -359,6 +361,112 @@ describe("runScenarioCheck", () => {
     expect(out).toContain("seeded");
   });
 
+  // ── The cost clause end to end (#2358) ────────────────────────────────
+  //
+  // `../../lifecycle/scenario-cost.test.ts` drives the evaluator directly.
+  // These four go through the handler instead, because the half the evaluator
+  // never sees is the half that reads the block off a fixture on disk: a
+  // recorded prediction is a `behaviour` key on the `LifecycleSnapshot`, and
+  // the clause is only offline and credential-free if `chant scenario check`
+  // can bound a change from that file alone.
+
+  const TRAFFIC = "1000 rps, p99";
+
+  /** One entity's figure at {@link TRAFFIC}, at `perHour` USD. */
+  function figure(perHour: number): PredictedBehaviour {
+    return {
+      at: { traffic: TRAFFIC },
+      cost: predictedRate(perHour, "USD"),
+      headroom: { cpu: 0.4 },
+      errorRate: 0.002,
+      resilience: { failure: "one zone lost", verdict: "survives" },
+      provenance: { engine: "acme-sim", version: "1.4.2", tolerance: "±15%", basis: "modeled" },
+    };
+  }
+
+  /** A snapshot carrying a recorded prediction over one entity, as `chant lifecycle snapshot` would write it. */
+  function pricedSnap(name: string, perHour: number): LifecycleSnapshot {
+    return snap({
+      resources: { [name]: meta() },
+      behaviour: behaviourReport(
+        { entityNames: [name], traffic: TRAFFIC, edgeCoverage: { verdict: "unknown" } },
+        { engine: "acme-sim", version: "1.4.2" },
+        { [name]: figure(perHour) },
+      ),
+    });
+  }
+
+  test("a cost bound turns red when the fixture's prediction exceeds it, naming both rates and the level", async () => {
+    const fixturePath = await writeFixture(pricedSnap("bucket", 0.9));
+    const scenario = Scenario("stays under a dollar an hour", {
+      given: snapshot(fixturePath),
+      expect: { noop: true, cost: { maxPerHour: 0.5, currency: "USD" } },
+    });
+    buildMock.mockResolvedValue(makeBuildResult({ aws: ["bucket"] }, { budget: scenario }));
+
+    const exit = await runScenarioCheck({ args: makeArgs(), plugins: [], serializers: [] });
+
+    expect(exit).toBe(1);
+    const out = combined();
+    expect(out).toContain("FAIL");
+    expect(out).toContain("cost:");
+    expect(out).toContain("exceeded");
+    expect(out).toContain("0.9 USD/hour");
+    expect(out).toContain("0.5 USD/hour");
+    expect(out).toContain(TRAFFIC);
+    // The other clause is unaffected: the plan itself is still neutral.
+    expect(out).not.toContain("noop:");
+  });
+
+  test("the same bound passes under the rate, and the pass says which figure it read", async () => {
+    const fixturePath = await writeFixture(pricedSnap("bucket", 0.2));
+    const scenario = Scenario("stays under a dollar an hour", {
+      given: snapshot(fixturePath),
+      expect: { cost: { maxPerHour: 0.5, currency: "USD" } },
+    });
+    buildMock.mockResolvedValue(makeBuildResult({ aws: ["bucket"] }, { budget: scenario }));
+
+    const exit = await runScenarioCheck({ args: makeArgs(), plugins: [], serializers: [] });
+
+    expect(exit).toBe(0);
+    expect(combined()).toContain("PASS");
+  });
+
+  test("a fixture with no behaviour block fails the bound by name, never passes on nothing", async () => {
+    const fixturePath = await writeFixture(snap({ resources: { bucket: meta() } }));
+    const scenario = Scenario("stays under a dollar an hour", {
+      given: snapshot(fixturePath),
+      expect: { cost: { maxPerHour: 0.5, currency: "USD" } },
+    });
+    buildMock.mockResolvedValue(makeBuildResult({ aws: ["bucket"] }, { budget: scenario }));
+
+    const exit = await runScenarioCheck({ args: makeArgs(), plugins: [], serializers: [] });
+
+    expect(exit).toBe(1);
+    const out = combined();
+    expect(out).toContain("FAIL");
+    expect(out).toContain("carries no `behaviour` block");
+  });
+
+  test("a fixture whose recorded prediction is a refusal fails with the refusal's own cause", async () => {
+    const fixturePath = await writeFixture(
+      snap({ resources: { bucket: meta() }, behaviour: noBehaviourEngineRefusal("augur") }),
+    );
+    const scenario = Scenario("stays under a dollar an hour", {
+      given: snapshot(fixturePath),
+      expect: { cost: { maxPerHour: 0.5, currency: "USD" } },
+    });
+    buildMock.mockResolvedValue(makeBuildResult({ aws: ["bucket"] }, { budget: scenario }));
+
+    const exit = await runScenarioCheck({ args: makeArgs(), plugins: [], serializers: [] });
+
+    expect(exit).toBe(1);
+    const out = combined();
+    expect(out).toContain("FAIL");
+    expect(out).toContain("no-engine");
+    expect(out).toContain("CHANT_BEHAVIOUR_ENGINE");
+  });
+
   test("a receipt whose live value matches its expectation is a genuine noop pass", async () => {
     // The positive control for the two reproductions above: a receipt that
     // HAS fired, with the right value, is still a clean noop — the pipeline

package/src/cli/handlers/scenario.ts

@@ -12,7 +12,8 @@ import {
   type ReceiptReading,
 } from "../../lifecycle/receipt-plan";
 import { collectEffectReceipts, isEffectReceipt, type EffectReceiptDeclaration } from "../../effect-receipt";
-import { evaluateScenario, type ScenarioVerdict } from "../../lifecycle/scenario-eval";
+import { evaluateScenario, type ScenarioBehaviourFixture, type ScenarioVerdict } from "../../lifecycle/scenario-eval";
+import { validateBehaviourResult } from "../../behaviour-delta";
 import { collectScenarios, type ScenarioDeclaration, type ScenarioGiven } from "../../lifecycle/scenario";
 import { isResourceDeclarable } from "../../declarable";
 import { loadChantConfig } from "../../config";
@@ -153,6 +154,46 @@ interface GivenResolution {
   perLexicon: Map<string, LifecycleSnapshot>;
   /** Set when the fixture itself could not be resolved — the scenario fails on this alone. */
   error?: string;
+  /**
+   * The fixture's recorded prediction, for a `cost` clause (#2358): the one
+   * `behaviour` block the fixture carries, held to the contract on the way
+   * in, or the reason there is none. Always set once the fixture resolved,
+   * so a `cost` clause against a fixture with no block fails by name rather
+   * than on `undefined`.
+   */
+  behaviour: ScenarioBehaviourFixture;
+}
+
+/**
+ * Read the `behaviour` block off the fixture's snapshots. One block, not one
+ * per lexicon: a prediction is over the whole estate (augur reads every
+ * lexicon's entities and holds none of its own), so it belongs to no single
+ * lexicon's file, and two files carrying two different blocks is a fixture
+ * that answers twice. Validated on arrival — a hand-edited fixture with a
+ * negative rate or a bare `{ behaviour: "v1" }` is refused as not a
+ * prediction, never read as one.
+ */
+function behaviourFrom(snapshots: Iterable<LifecycleSnapshot>, where: string): ScenarioBehaviourFixture {
+  const found: unknown[] = [];
+  for (const snap of snapshots) {
+    if (snap.behaviour !== undefined) found.push(snap.behaviour);
+  }
+  if (found.length === 0) return { missing: `given ${where} carries no \`behaviour\` block` };
+  const distinct = new Set(found.map((b) => JSON.stringify(b)));
+  if (distinct.size > 1) {
+    return {
+      missing: `given ${where} carries ${found.length} different \`behaviour\` blocks across its lexicon snapshots; a prediction is one answer over the whole estate`,
+    };
+  }
+  const block = found[0] as { entities?: Record<string, unknown>; unpredicted?: Record<string, unknown> };
+  const names = [...Object.keys(block?.entities ?? {}), ...Object.keys(block?.unpredicted ?? {})];
+  try {
+    return { result: validateBehaviourResult(block, names) };
+  } catch (err) {
+    return {
+      missing: `given ${where} carries a \`behaviour\` block that is not a valid prediction: ${(err as Error).message}`,
+    };
+  }
 }
 
 /** Read `given`'s fixture data. Offline: a file read for `snapshot(path)`, a
@@ -162,41 +203,47 @@ async function resolveGiven(given: ScenarioGiven): Promise<GivenResolution> {
   if (given.kind === "file") {
     const abs = resolve(given.path);
     let raw: string;
+    const unresolved = (error: string, env = ""): GivenResolution => ({
+      env,
+      perLexicon: new Map(),
+      error,
+      behaviour: { missing: error },
+    });
     try {
       raw = await readFile(abs, "utf8");
     } catch {
-      return { env: "", perLexicon: new Map(), error: `fixture not found: ${given.path}` };
+      return unresolved(`fixture not found: ${given.path}`);
     }
     let snap: LifecycleSnapshot;
     try {
       snap = JSON.parse(raw) as LifecycleSnapshot;
     } catch {
-      return { env: "", perLexicon: new Map(), error: `fixture is not valid JSON: ${given.path}` };
+      return unresolved(`fixture is not valid JSON: ${given.path}`);
     }
     if (typeof snap.lexicon !== "string" || typeof snap.environment !== "string" || typeof snap.resources !== "object") {
-      return {
-        env: typeof snap.environment === "string" ? snap.environment : "",
-        perLexicon: new Map(),
-        error: `${given.path} is not a LifecycleSnapshot — missing lexicon/environment/resources`,
-      };
+      return unresolved(
+        `${given.path} is not a LifecycleSnapshot — missing lexicon/environment/resources`,
+        typeof snap.environment === "string" ? snap.environment : "",
+      );
     }
-    return { env: snap.environment, perLexicon: new Map([[snap.lexicon, snap]]) };
+    return {
+      env: snap.environment,
+      perLexicon: new Map([[snap.lexicon, snap]]),
+      behaviour: behaviourFrom([snap], given.path),
+    };
   }
 
   const stored = await readEnvironmentSnapshots(given.env);
   if (stored.size === 0) {
-    return {
-      env: given.env,
-      perLexicon: new Map(),
-      error: `no recorded snapshot for environment "${given.env}" on chant/lifecycle — record one with \`chant lifecycle snapshot ${given.env}\``,
-    };
+    const error = `no recorded snapshot for environment "${given.env}" on chant/lifecycle — record one with \`chant lifecycle snapshot ${given.env}\``;
+    return { env: given.env, perLexicon: new Map(), error, behaviour: { missing: error } };
   }
   const perLexicon = new Map<string, LifecycleSnapshot>();
   for (const [key, content] of stored) {
     const snap = JSON.parse(content) as LifecycleSnapshot;
     perLexicon.set(snap.lexicon ?? key, snap);
   }
-  return { env: given.env, perLexicon };
+  return { env: given.env, perLexicon, behaviour: behaviourFrom(perLexicon.values(), `env "${given.env}"`) };
 }
 
 /**
@@ -317,7 +364,7 @@ async function evaluateOneScenario(
     mergeReceiptEntries(merged, receipts, receiptEntries);
   }
 
-  return { env: resolved.env, verdict: evaluateScenario(merged, scenario.expect) };
+  return { env: resolved.env, verdict: evaluateScenario(merged, scenario.expect, resolved.behaviour) };
 }
 
 /** Fallback for `chant scenario <unknown subcommand>` — mirrors `runLifecycleUnknown`. */

package/src/fold/subset-doc-parity.test.ts

@@ -64,6 +64,16 @@ import { findSubsetViolation } from "./subset";
  * comment): moving it under a `###` heading with a fenced block, the shape
  * every other case here uses, was necessary but not sufficient — the
  * fixture still has to be run through the right function.
+ *
+ * Two more claims are checked against `fold()` the same way — chant #2348.
+ * "typescript-as-data.mdx" said a method call never folds; #1966 made that
+ * false for a method call whose receiver folds to a real value. Both the
+ * corrected supported claim ("Method calls on folded values") and the
+ * corrected unsupported one ("An array method whose callback is a function
+ * value" — right outcome, `list.map(...)` still falls back, but because the
+ * callback is a function used as a value, not because `.map` is a method
+ * call) were previously unfenced prose sentences too, invisible to this file
+ * for the same reason #2306's was.
  */
 
 const repoRoot = fileURLToPath(new URL("../../../../", import.meta.url));
@@ -193,6 +203,17 @@ describe("subset-doc-parity — supported patterns in typescript-as-data.mdx cla
     if (!wrapped) throw new Error("subset-doc-parity: nullish-coalescing fragment failed to parse");
     expect(findSubsetViolation(wrapped)).toBeUndefined();
   });
+
+  test("Method calls on folded values", () => {
+    // chant #1966/#2348 — findSubsetViolation accepts this shape
+    // unconditionally regardless of whether the receiver actually resolves
+    // (module doc, point above the CallExpression case in ./subset.ts):
+    // shape-valid here is necessary but not sufficient. The real
+    // accept/reject decision is fold()'s, checked below in the
+    // fold()-decided describe block.
+    const consts = parseConsts(extractFencedBlock("Method calls on folded values"));
+    expect(findSubsetViolation(resourceArg(consts, "store"))).toBeUndefined();
+  });
 });
 
 describe("subset-doc-parity — unsupported patterns in typescript-as-data.mdx classify as rejected", () => {
@@ -221,6 +242,14 @@ describe("subset-doc-parity — unsupported patterns in typescript-as-data.mdx c
     const consts = parseConsts(extractFencedBlock("Spread from dynamic sources"));
     expect(findSubsetViolation(resourceArg(consts, "store"))).toBeDefined();
   });
+
+  test("An array method whose callback is a function value", () => {
+    // chant #2348 — the callback argument, an ArrowFunction, is what
+    // findSubsetViolation rejects here (falls through to the catch-all
+    // unsupportedExpressionMessage), not the `.map(...)` method call itself.
+    const consts = parseConsts(extractFencedBlock("An array method whose callback is a function value"));
+    expect(findSubsetViolation(resourceArg(consts, "store"))).toBeDefined();
+  });
 });
 
 describe("subset-doc-parity — fold()-decided claim in typescript-as-data.mdx (#2306)", () => {
@@ -242,3 +271,34 @@ describe("subset-doc-parity — fold()-decided claim in typescript-as-data.mdx (
     expect((error as FoldError).message).toContain("unknownTag");
   });
 });
+
+describe("subset-doc-parity — fold()-decided claims in typescript-as-data.mdx (#2348)", () => {
+  test("Method calls on folded values", () => {
+    // findSubsetViolation only proves the shape is admissible (above); prove
+    // the doc's own example actually folds, and to the value the doc claims,
+    // by running it through fold() with no externals at all — the receiver
+    // (`[prefix, "data"]`) is a plain array literal, so nothing needs to
+    // resolve across a file boundary for this one.
+    const consts = parseConsts(extractFencedBlock("Method calls on folded values"));
+    const arg = resourceArg(consts, "store");
+    expect(fold(arg, consts, [])).toEqual({ name: "acct-data" });
+  });
+
+  test("An array method whose callback is a function value — real reason", () => {
+    // The doc's corrected claim: this falls back because the ARROW FUNCTION
+    // is a value fold refuses, not because `.map` is a method call. Assert
+    // the actual FoldError says so, rather than something naming ".map" or
+    // "method call".
+    const consts = parseConsts(extractFencedBlock("An array method whose callback is a function value"));
+    const arg = resourceArg(consts, "store");
+    let error: unknown;
+    try {
+      fold(arg, consts, []);
+    } catch (e) {
+      error = e;
+    }
+    expect(error).toBeInstanceOf(FoldError);
+    expect((error as FoldError).message).toContain("a function used as a value is not foldable");
+    expect((error as FoldError).message).not.toContain("method call");
+  });
+});

package/src/identity.ts

@@ -161,7 +161,7 @@ export const REDACTED = "[redacted]";
  * name, so a lexicon that echoes one of these into an identity string has the
  * value removed before it is printed or serialized.
  */
-const CREDENTIAL_ENV_NAME =
+export const CREDENTIAL_ENV_NAME =
   /(SECRET|TOKEN|PASSWORD|PASSWD|CREDENTIAL|PRIVATE_KEY|APIKEY|API_KEY|ACCESS_KEY|SESSION_KEY|AUTH)/i;
 
 /** Shortest env value worth redacting. Below this a "secret" is a false positive. */
@@ -171,7 +171,7 @@ const MIN_CREDENTIAL_LENGTH = 8;
  * Literal credential shapes. Each is something a principal string cannot be,
  * so matching one is proof rather than a guess.
  */
-const CREDENTIAL_SHAPES: RegExp[] = [
+export const CREDENTIAL_SHAPES: RegExp[] = [
   // A PEM block of any key type.
   /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g,
   // A JWT: three base64url segments, the first starting with the `{"` header.
@@ -180,6 +180,32 @@ const CREDENTIAL_SHAPES: RegExp[] = [
   /\b(?:Bearer|Basic)\s+[A-Za-z0-9\-._~+/]{16,}={0,2}/g,
 ];
 
+/**
+ * Provider-prefixed access tokens, by their issuer's own prefix (#2356).
+ *
+ * Separate from {@link CREDENTIAL_SHAPES} because these are a **denylist of
+ * known formats** rather than proof-by-shape. A prefix nobody has added here —
+ * a new provider, an internal issuer, a bare random string — passes every one
+ * of them, and any caller relying on this must say so rather than claim
+ * coverage. What it does buy is that the tokens people actually paste are
+ * caught wherever they appear, whatever the field is called.
+ *
+ * The suffix bound is deliberately short. The prefix is the signal; a truncated
+ * or example token is still somebody having written a credential down.
+ */
+export const CREDENTIAL_TOKEN_SHAPES: { name: string; re: RegExp }[] = [
+  { name: "a GitHub token", re: /\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{6,}\b/g },
+  { name: "a GitHub fine-grained token", re: /\bgithub_pat_[A-Za-z0-9_]{6,}\b/g },
+  { name: "a GitLab personal access token", re: /\bglpat-[A-Za-z0-9_-]{3,}\b/g },
+  { name: "an OpenAI-style secret key", re: /\bsk-(?:live-|proj-|test-)?[A-Za-z0-9]{6,}\b/g },
+  { name: "a Stripe key", re: /\b[rs]k_(?:live|test)_[A-Za-z0-9]{6,}\b/g },
+  { name: "a Slack token", re: /\bxox[abposr]-[A-Za-z0-9-]{6,}\b/g },
+  { name: "an AWS access key id", re: /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/g },
+  { name: "a Google API key", re: /\bAIza[0-9A-Za-z_-]{20,}\b/g },
+  { name: "a Google OAuth token", re: /\bya29\.[0-9A-Za-z_-]{10,}/g },
+  { name: "an npm token", re: /\bnpm_[A-Za-z0-9]{10,}\b/g },
+];
+
 /**
  * Strip credential material from one reported field.
  *
@@ -205,6 +231,9 @@ export function redactCredentialMaterial(
     out = out.split(secret).join(REDACTED);
   }
   for (const shape of CREDENTIAL_SHAPES) out = out.replace(shape, REDACTED);
+  // Provider-prefixed tokens too (#2356): these are the ones people paste, and
+  // the three shapes above match none of them.
+  for (const { re } of CREDENTIAL_TOKEN_SHAPES) out = out.replace(re, REDACTED);
   return out;
 }
 

package/src/index.ts

@@ -62,6 +62,9 @@ export * from "./observation";
 export * from "./identity";
 export * from "./apply";
 export * from "./deep-observation";
+export * from "./behaviour";
+export * from "./behaviour-http";
+export * from "./behaviour-delta";
 export * from "./claimed-fields";
 export * from "./fold-provenance";
 export * from "./owner-chain";

package/src/lexicon.ts

@@ -23,6 +23,7 @@ import type { IREdge } from "./graph-ir";
 import type { DescribeResourcesResult, UnobservedReason } from "./observation";
 import type { DescribeIdentityOptions, DescribeIdentityResult } from "./identity";
 import type { DeepNormalizationHooks, DeepObservationResult } from "./deep-observation";
+import type { BehaviourResult, PredictBehaviourOptions } from "./behaviour";
 import type { DisruptionQuery, DisruptionVerdict } from "./lifecycle/disruption";
 import type { OwnerChainVerdict } from "./owner-chain";
 import type { CommandGroup } from "./cli/command-group";
@@ -1413,6 +1414,51 @@ export interface LexiconPlugin {
    */
   deepNormalizationHooks?: DeepNormalizationHooks;
 
+  /**
+   * Predict what the declared estate would *do* at a stated traffic level
+   * (#2356) — cost per hour, headroom, an error-rate expectation, a resilience
+   * verdict under a named failure, and a right-size hint, per entity, every
+   * figure carrying its provenance. Opt-in, and the fourth member of the
+   * observation family beside {@link describeResources}, {@link
+   * observeResourcesDeep} and {@link listArtifacts}.
+   *
+   * It is the odd one out in that family, and the type says so. The other three
+   * report what a substrate was asked and answered. This one reports what an
+   * engine believes would happen at a level nobody has run yet, so it is
+   * `predict`, not `observe`, and its result can never be read as a
+   * measurement or a bill: money exists only as a `PredictedRate` for one
+   * imagined hour, every entity states the `at` its figures answer, and
+   * `provenance.basis` says `modeled` or `validated` on every one of them. See
+   * `../behaviour.ts` for the full argument.
+   *
+   * Options mirror {@link observeResourcesDeep}'s field for field, plus
+   * `traffic` — a caller already driving the deep read drives this with the
+   * same object. What the options deliberately cannot carry is a credential:
+   * every name for one is declared `?: never`, because the engine is handed the
+   * resource graph and nothing else, reaches no account, and writes nothing.
+   *
+   * Three verdicts per entity, on the tri-state discipline #1089 established
+   * and a stricter total: PREDICTED (a key in `entities`),
+   * NOT-PREDICTABLE-FOR-THIS-KIND (`unpredicted` with `unsupported-kind` — an
+   * engine with no model for a kind says so and never returns zero), and
+   * NOT-PREDICTED (`unpredicted` with another reason). Every name the caller
+   * asked about lands in one map or the other; unlike the thin read there is no
+   * third position, because a prediction has no equivalent of "the provider
+   * says it is not there".
+   *
+   * A missing or unreachable engine is a `BehaviourRefusalReport` — the other
+   * arm of the result union, with no `entities` map to be empty and no total to
+   * be zero — carrying a named cause and a message that names the variable it
+   * wanted, in the style of `noGitlabNoteTokenMessage`
+   * (`./op/activities/reconcile.ts`). Build one with
+   * `noBehaviourEngineRefusal` / `unreachableBehaviourEngineRefusal` rather
+   * than by hand.
+   *
+   * Throwing is the whole-lexicon failure, same as the other reads. Prefer the
+   * refusal: it says which variable, and a stack trace does not.
+   */
+  predictBehaviour?(options: PredictBehaviourOptions): Promise<BehaviourResult>;
+
   /**
    * Report the live status of one deploy unit by its deployed name. Opt-in.
    *

package/src/lifecycle/scenario-cost.test.ts

@@ -0,0 +1,183 @@
+/**
+ * The `cost` clause on a scenario (#2358): its shape at declaration, and its
+ * evaluation against the fixture's recorded prediction.
+ */
+
+import { describe, expect, test } from "vitest";
+import { EXPECT_KEYS, Scenario, snapshot } from "./scenario";
+import { evaluateScenario, type ScenarioBehaviourFixture } from "./scenario-eval";
+import type { ChangeSet } from "./change-set";
+import {
+  behaviourReport,
+  noBehaviourEngineRefusal,
+  outOfCreditBehaviourEngineRefusal,
+  predictedRate,
+  type PredictedBehaviour,
+  type UnpredictedEntity,
+} from "../behaviour";
+
+const EMPTY: ChangeSet = { env: "prod", entries: [] };
+const TRAFFIC = "100 rps, p50";
+
+function figure(perHour: number, currency = "USD"): PredictedBehaviour {
+  return {
+    at: { traffic: TRAFFIC },
+    cost: predictedRate(perHour, currency),
+    headroom: { cpu: 0.5 },
+    errorRate: 0.001,
+    resilience: { failure: "one zone lost", verdict: "survives" },
+    provenance: { engine: "acme-sim", version: "1.4.2", tolerance: "±15%", basis: "modeled" },
+  };
+}
+
+function fixture(
+  entities: Record<string, PredictedBehaviour>,
+  unpredicted: Record<string, UnpredictedEntity> = {},
+  total?: { perHour: number; currency: string },
+): ScenarioBehaviourFixture {
+  return {
+    result: behaviourReport(
+      { entityNames: [...Object.keys(entities), ...Object.keys(unpredicted)], traffic: TRAFFIC, edgeCoverage: { verdict: "unknown" } },
+      { engine: "acme-sim", version: "1.4.2", ...(total ? { total: predictedRate(total.perHour, total.currency) } : {}) },
+      entities,
+      unpredicted,
+    ),
+  };
+}
+
+function cost(verdict: ReturnType<typeof evaluateScenario>) {
+  return verdict.checks.find((c) => c.clause === "cost")!;
+}
+
+describe("Scenario — the cost clause's shape", () => {
+  test("cost is a recognized expect key", () => {
+    expect(EXPECT_KEYS).toContain("cost");
+  });
+
+  test("accepts a bound with a currency, and an optional entity", () => {
+    const s = Scenario("s", { given: snapshot("fixtures/prod.json"), expect: { cost: { maxPerHour: 12.5, currency: "USD" } } });
+    expect(s.expect.cost).toEqual({ maxPerHour: 12.5, currency: "USD" });
+    const e = Scenario("s", { given: snapshot("prod"), expect: { cost: { maxPerHour: 1, currency: " EUR ", entity: "db" } } });
+    expect(e.expect.cost).toEqual({ maxPerHour: 1, currency: "EUR", entity: "db" });
+    expect(Object.isFrozen(e.expect.cost)).toBe(true);
+  });
+
+  test("composes with the other clauses", () => {
+    const s = Scenario("s", { given: snapshot("prod"), expect: { noop: true, cost: { maxPerHour: 1, currency: "USD" } } });
+    expect(Object.keys(s.expect).sort()).toEqual(["cost", "noop"]);
+  });
+
+  test("rejects a bound with no currency — chant converts nothing", () => {
+    expect(() =>
+      // @ts-expect-error deliberately omitting currency
+      Scenario("s", { given: snapshot("prod"), expect: { cost: { maxPerHour: 1 } } }),
+    ).toThrow(/expect.cost.currency/);
+  });
+
+  test("rejects a negative, non-finite or non-numeric bound", () => {
+    expect(() => Scenario("s", { given: snapshot("prod"), expect: { cost: { maxPerHour: -1, currency: "USD" } } })).toThrow(/non-negative finite/);
+    expect(() => Scenario("s", { given: snapshot("prod"), expect: { cost: { maxPerHour: Number.NaN, currency: "USD" } } })).toThrow(/non-negative finite/);
+    expect(() =>
+      // @ts-expect-error deliberately passing a string
+      Scenario("s", { given: snapshot("prod"), expect: { cost: { maxPerHour: "12", currency: "USD" } } }),
+    ).toThrow(/non-negative finite/);
+  });
+
+  test("rejects an unknown field inside cost, and a non-object cost", () => {
+    expect(() =>
+      // @ts-expect-error deliberately passing an unrecognized field
+      Scenario("s", { given: snapshot("prod"), expect: { cost: { maxPerHour: 1, currency: "USD", maxPerMonth: 700 } } }),
+    ).toThrow(/unknown `expect.cost` field "maxPerMonth"/);
+    expect(() =>
+      // @ts-expect-error deliberately passing a number
+      Scenario("s", { given: snapshot("prod"), expect: { cost: 12 } }),
+    ).toThrow(/must be \{ maxPerHour, currency, entity\? \}/);
+  });
+});
+
+describe("evaluateScenario — cost against the fixture's recorded prediction", () => {
+  test("a fixture with no behaviour block fails the clause by name — a bound cannot be checked against no figure", () => {
+    const verdict = evaluateScenario(EMPTY, { cost: { maxPerHour: 1, currency: "USD" } }, { missing: "given fixtures/prod.json carries no `behaviour` block" });
+    expect(verdict.pass).toBe(false);
+    expect(cost(verdict).detail).toMatch(/carries no `behaviour` block.*Record one/);
+    // And with nothing handed over at all.
+    expect(evaluateScenario(EMPTY, { cost: { maxPerHour: 1, currency: "USD" } }).pass).toBe(false);
+  });
+
+  test("a fixture whose prediction is a refusal fails with the refusal's reason, never a pass on nothing", () => {
+    const verdict = evaluateScenario(EMPTY, { cost: { maxPerHour: 1e9, currency: "USD" } }, { result: noBehaviourEngineRefusal("augur") });
+    expect(verdict.pass).toBe(false);
+    expect(cost(verdict).detail).toContain("the fixture's prediction is a refusal (no-engine)");
+    expect(cost(verdict).detail).toContain("Set CHANT_BEHAVIOUR_ENGINE to the engine's address.");
+
+    const broke = outOfCreditBehaviourEngineRefusal("augur", { value: "engine", source: "CHANT_BEHAVIOUR_ENGINE" }, "balance 0");
+    expect(cost(evaluateScenario(EMPTY, { cost: { maxPerHour: 1e9, currency: "USD" } }, { result: broke })).detail).toContain("engine-out-of-credit");
+  });
+
+  test("turns red when the fixture's figure exceeds the bound, naming both rates and the level", () => {
+    const verdict = evaluateScenario(EMPTY, { cost: { maxPerHour: 0.25, currency: "USD" } }, fixture({ db: figure(0.272) }));
+    expect(verdict.pass).toBe(false);
+    expect(cost(verdict).detail).toBe(
+      'exceeded: 0.272 USD/hour at "100 rps, p50" against a bound of 0.25 USD/hour; read from chant\'s own sum over 1 predicted entity (the engine states no total)',
+    );
+  });
+
+  test("passes at or under the bound, and says on the pass which figure it read", () => {
+    const verdict = evaluateScenario(EMPTY, { cost: { maxPerHour: 0.272, currency: "USD" } }, fixture({ db: figure(0.272) }));
+    expect(verdict.pass).toBe(true);
+    expect(cost(verdict).detail).toContain("read from chant's own sum");
+  });
+
+  test("reads the engine's own total when it states one, rather than summing", () => {
+    const verdict = evaluateScenario(EMPTY, { cost: { maxPerHour: 1, currency: "USD" } }, fixture({ db: figure(0.272), web: figure(0.04) }, {}, { perHour: 1.5, currency: "USD" }));
+    expect(verdict.pass).toBe(false);
+    expect(cost(verdict).detail).toContain("1.5 USD/hour");
+    expect(cost(verdict).detail).toContain("read from the engine's own estate total (acme-sim 1.4.2)");
+  });
+
+  test("chant's sum names every declined entity, because those are in the estate and not in the sum", () => {
+    const verdict = evaluateScenario(
+      EMPTY,
+      { cost: { maxPerHour: 1, currency: "USD" } },
+      fixture({ db: figure(0.272) }, { role: { type: "AWS::IAM::Role", reason: "unsupported-kind", detail: "a role is a grant" } }),
+    );
+    expect(verdict.pass).toBe(true);
+    expect(cost(verdict).detail).toContain("1 declined and not in the figure: role (unsupported-kind: a role is a grant)");
+  });
+
+  test("bounds one entity's own rate when named, with its provenance", () => {
+    const fx = fixture({ db: figure(0.272), web: figure(5) });
+    expect(evaluateScenario(EMPTY, { cost: { maxPerHour: 0.3, currency: "USD", entity: "db" } }, fx).pass).toBe(true);
+    const red = evaluateScenario(EMPTY, { cost: { maxPerHour: 0.3, currency: "USD", entity: "web" } }, fx);
+    expect(red.pass).toBe(false);
+    expect(cost(red).detail).toContain("read from web's own rate (acme-sim 1.4.2, ±15%, modeled)");
+  });
+
+  test("a named entity the engine declined, or never asked about, fails with the reason", () => {
+    const fx = fixture({ db: figure(0.272) }, { role: { reason: "unsupported-kind", detail: "a role is a grant" } });
+    expect(cost(evaluateScenario(EMPTY, { cost: { maxPerHour: 1, currency: "USD", entity: "role" } }, fx)).detail).toContain(
+      '"role" was declined by the engine (unsupported-kind: a role is a grant)',
+    );
+    expect(cost(evaluateScenario(EMPTY, { cost: { maxPerHour: 1, currency: "USD", entity: "ghost" } }, fx)).detail).toContain(
+      '"ghost" is in neither the fixture\'s figures nor its declined entities',
+    );
+  });
+
+  test("a bound in another currency fails — chant converts nothing", () => {
+    const verdict = evaluateScenario(EMPTY, { cost: { maxPerHour: 1, currency: "EUR" } }, fixture({ db: figure(0.272) }));
+    expect(verdict.pass).toBe(false);
+    expect(cost(verdict).detail).toContain("the bound is in EUR and the figure is 0.272 USD/hour");
+  });
+
+  test("entities priced in two currencies with no engine total cannot be summed", () => {
+    const verdict = evaluateScenario(EMPTY, { cost: { maxPerHour: 1, currency: "USD" } }, fixture({ db: figure(0.272), eu: figure(0.1, "EUR") }));
+    expect(verdict.pass).toBe(false);
+    expect(cost(verdict).detail).toContain("priced in EUR, USD");
+  });
+
+  test("the cost clause sits beside the others in declaration order and does not touch them", () => {
+    const verdict = evaluateScenario(EMPTY, { noop: true, cost: { maxPerHour: 1, currency: "USD" } }, fixture({ db: figure(0.272) }));
+    expect(verdict.checks.map((c) => c.clause)).toEqual(["noop", "cost"]);
+    expect(verdict.pass).toBe(true);
+  });
+});