@intentius/chant 0.65.0 → 0.66.0

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);
+  });
+});

package/src/lifecycle/scenario-eval.ts

@@ -17,7 +17,24 @@
 import { summarize, type ChangeSet } from "./change-set";
 import { evaluateUnobservedGate, type UnobservedGateFinding } from "./unobserved-gate";
 import { unobservedReasonText } from "../observation";
-import type { ScenarioDeleteExpectation, ScenarioExpect, ScenarioUnobservedPolicy } from "./scenario";
+import { isBehaviourRefusalReport, renderBehaviourRefusal, type BehaviourResult } from "../behaviour";
+import { formatPerHour } from "../behaviour-delta";
+import type {
+  ScenarioCostExpectation,
+  ScenarioDeleteExpectation,
+  ScenarioExpect,
+  ScenarioUnobservedPolicy,
+} from "./scenario";
+
+/**
+ * What stands in for the engine's answer when a scenario carries a `cost`
+ * clause (#2358): the fixture's `behaviour` block, or the reason there is
+ * none. The handler resolves it from the same fixture every other clause
+ * reads; this module only evaluates it.
+ */
+export type ScenarioBehaviourFixture =
+  | { readonly result: BehaviourResult }
+  | { readonly missing: string };
 
 /**
  * One clause's verdict — always present in {@link ScenarioVerdict.checks}, in
@@ -28,7 +45,11 @@ export interface ScenarioCheckResult {
   /** Which `expect` clause this is (`"noop"`, `"create"`, `"deletes"`, …). */
   clause: string;
   pass: boolean;
-  /** Present when `pass` is false — what was expected vs what the plan proposes, naming resources for delete/ownership failures. */
+  /** Present when `pass` is false — what was expected vs what the plan
+   * proposes, naming resources for delete/ownership failures. The `cost`
+   * clause carries it on a pass too, saying which figure was bounded and
+   * what the engine declined, so a passing bound is never read as a bound
+   * over the whole estate when it was not. */
   detail?: string;
 }
 
@@ -40,11 +61,17 @@ export interface ScenarioVerdict {
 }
 
 /**
- * Evaluate `expect` against `cs`. Pure: reads `cs` and `expect`, computes
- * nothing else. Every clause present on `expect` is checked independently and
- * every one contributes to `checks`; `pass` is true only when all of them are.
+ * Evaluate `expect` against `cs`. Pure: reads `cs`, `expect` and, for a
+ * `cost` clause, the fixture's `behaviour` block handed over as `behaviour`;
+ * computes nothing else. Every clause present on `expect` is checked
+ * independently and every one contributes to `checks`; `pass` is true only
+ * when all of them are.
  */
-export function evaluateScenario(cs: ChangeSet, expect: ScenarioExpect): ScenarioVerdict {
+export function evaluateScenario(
+  cs: ChangeSet,
+  expect: ScenarioExpect,
+  behaviour?: ScenarioBehaviourFixture,
+): ScenarioVerdict {
   const counts = summarize(cs);
   const checks: ScenarioCheckResult[] = [];
 
@@ -91,9 +118,109 @@ export function evaluateScenario(cs: ChangeSet, expect: ScenarioExpect): Scenari
     checks.push(evaluateUnobservedClause(cs, expect.unobserved));
   }
 
+  if (expect.cost !== undefined) {
+    checks.push(evaluateCostClause(expect.cost, behaviour));
+  }
+
   return { pass: checks.every((c) => c.pass), checks };
 }
 
+/**
+ * The `cost` clause (#2358). Three refusals before any number is read, each
+ * naming why, because the alternative to each is a bound that passes on
+ * nothing:
+ *
+ *  - no `behaviour` block in the fixture — nothing was predicted;
+ *  - the block is a refusal — the engine was absent, unreachable, out of
+ *    credit, over quota, or refused a credential, and the fixture carries
+ *    that refusal's own text;
+ *  - the named entity is not in the fixture's figures — declined with a
+ *    reason, or never asked about.
+ *
+ * The figure is then one of three, and the detail says which: the named
+ * entity's own rate, the engine's stated total, or chant's sum over every
+ * predicted entity when the engine states no total. The sum is chant's own
+ * arithmetic and is labelled so; it also names every entity the engine
+ * declined, because those are in the estate and not in the sum.
+ */
+function evaluateCostClause(
+  bound: ScenarioCostExpectation,
+  behaviour: ScenarioBehaviourFixture | undefined,
+): ScenarioCheckResult {
+  const fail = (detail: string): ScenarioCheckResult => ({ clause: "cost", pass: false, detail });
+
+  if (behaviour === undefined || "missing" in behaviour) {
+    return fail(
+      `${behaviour?.missing ?? "the fixture carries no `behaviour` block"} — a cost bound is checked against the ` +
+        "fixture's recorded prediction, and there is none. Record one on the snapshot, or drop the clause.",
+    );
+  }
+  const result = behaviour.result;
+  if (isBehaviourRefusalReport(result)) {
+    return fail(
+      `the fixture's prediction is a refusal (${result.refusal.cause}), and a bound cannot be checked against no ` +
+        `figure: ${renderBehaviourRefusal(result.refusal, { color: false }).replace(/\n\s*/g, " ")}`,
+    );
+  }
+
+  const declined = Object.entries(result.unpredicted ?? {}).map(
+    ([name, u]) => `${name} (${u.reason}${u.detail ? `: ${u.detail}` : ""})`,
+  );
+  const declinedNote = declined.length > 0 ? `; ${declined.length} declined and not in the figure: ${declined.join(", ")}` : "";
+
+  let perHour: number;
+  let currency: string;
+  let which: string;
+  if (bound.entity !== undefined) {
+    const figure = Object.prototype.hasOwnProperty.call(result.entities, bound.entity)
+      ? result.entities[bound.entity]
+      : undefined;
+    if (!figure) {
+      const hole = result.unpredicted?.[bound.entity];
+      return fail(
+        hole
+          ? `"${bound.entity}" was declined by the engine (${hole.reason}${hole.detail ? `: ${hole.detail}` : ""}), so it has no figure to bound`
+          : `"${bound.entity}" is in neither the fixture's figures nor its declined entities — the prediction never asked about it`,
+      );
+    }
+    perHour = figure.cost.perHour;
+    currency = figure.cost.currency;
+    which = `${bound.entity}'s own rate (${figure.provenance.engine} ${figure.provenance.version}, ${figure.provenance.tolerance}, ${figure.provenance.basis})`;
+  } else if (result.meta.total) {
+    perHour = result.meta.total.perHour;
+    currency = result.meta.total.currency;
+    which = `the engine's own estate total (${result.meta.engine} ${result.meta.version})${declinedNote}`;
+  } else {
+    const names = Object.keys(result.entities);
+    const currencies = new Set(names.map((n) => result.entities[n].cost.currency));
+    if (currencies.size > 1) {
+      return fail(
+        `the engine states no total and the entities are priced in ${[...currencies].sort().join(", ")} — chant converts ` +
+          "nothing, so there is no one sum to bound",
+      );
+    }
+    if (names.length === 0) {
+      return fail(`the engine states no total and predicted no entity${declinedNote} — nothing to bound`);
+    }
+    perHour = names.reduce((sum, n) => sum + result.entities[n].cost.perHour, 0);
+    currency = [...currencies][0];
+    which = `chant's own sum over ${names.length} predicted entit${names.length === 1 ? "y" : "ies"} (the engine states no total)${declinedNote}`;
+  }
+
+  const level = result.meta.at.traffic;
+  if (currency !== bound.currency) {
+    return fail(
+      `the bound is in ${bound.currency} and the figure is ${formatPerHour(perHour)} ${currency}/hour at "${level}" — ` +
+        `chant converts nothing; read from ${which}`,
+    );
+  }
+  const pass = perHour <= bound.maxPerHour;
+  const detail =
+    `${pass ? "" : "exceeded: "}${formatPerHour(perHour)} ${currency}/hour at "${level}" against a bound of ` +
+    `${formatPerHour(bound.maxPerHour)} ${bound.currency}/hour; read from ${which}`;
+  return { clause: "cost", pass, detail };
+}
+
 /** Names (with type) of every entry matching one of `actions`, for a legible failure message. */
 function nameList(cs: ChangeSet, actions: readonly string[]): string {
   const names = cs.entries

package/src/lifecycle/scenario.ts

@@ -107,12 +107,48 @@ export interface ScenarioDeleteExpectation {
  */
 export type ScenarioUnobservedPolicy = "refuse" | { readonly allow: readonly string[] };
 
+/**
+ * A bound on one predicted figure in the fixture (#2358).
+ *
+ * A scenario has one fixture, not a before-and-after pair, so this bounds a
+ * **single** predicted rate rather than a delta: the fixture's own
+ * `behaviour` block (a `BehaviourResult` recorded on the `LifecycleSnapshot`,
+ * ../lifecycle/types.ts) stands in for the engine's answer the way the rest
+ * of the snapshot stands in for a live read, and the clause asks whether one
+ * figure in it is at or under `maxPerHour`.
+ *
+ * Which figure: `entity`'s own `cost.perHour` when named; otherwise the
+ * estate's — the engine's own `meta.total` when it states one, and chant's
+ * sum over every predicted entity when it does not. The verdict's detail says
+ * which of the three it read, and names every entity the engine declined,
+ * because a sum over an estate with declined entities is a sum over less
+ * than the estate and the reader should know it.
+ *
+ * The bound is a rate for one hypothetical hour at the fixture's stated
+ * traffic level, never an amount; `currency` is required and compared
+ * exactly, because chant converts nothing and a bound in USD says nothing
+ * about a figure in EUR.
+ *
+ * A fixture whose `behaviour` block is a refusal, or that carries none, fails
+ * the clause with the refusal's reason. A bound cannot be checked against no
+ * figure, and passing would be the faked number the epic forbids.
+ */
+export interface ScenarioCostExpectation {
+  /** The figure must be at or under this many `currency` per hour. */
+  readonly maxPerHour: number;
+  /** ISO 4217 code the figure must be stated in. Compared exactly. */
+  readonly currency: string;
+  /** Bound one entity's figure instead of the estate's. */
+  readonly entity?: string;
+}
+
 /**
  * The assertion vocabulary (#1292 research, settled shape). Every clause is
  * independently optional and clauses compose within one `expect` object — a
- * scenario can assert `noop`, exact counts, specific named deletes, and an
- * unobserved policy together. At least one clause must be present; an empty
- * `expect` asserts nothing and is refused as a likely mistake.
+ * scenario can assert `noop`, exact counts, specific named deletes, an
+ * unobserved policy and a cost bound together. At least one clause must be
+ * present; an empty `expect` asserts nothing and is refused as a likely
+ * mistake.
  */
 export interface ScenarioExpect {
   /** The plan proposes no create, update, or delete, and no declared effect
@@ -135,11 +171,15 @@ export interface ScenarioExpect {
   /** How the scenario treats unobserved rows. Omitted = unconstrained (an
    * unobserved entity neither passes nor fails the scenario on its own). */
   readonly unobserved?: ScenarioUnobservedPolicy;
+  /** One predicted figure in the fixture's `behaviour` block is at or under
+   * a stated rate per hour (#2358). See {@link ScenarioCostExpectation} for
+   * which figure, and for why a refusal in the fixture fails it. */
+  readonly cost?: ScenarioCostExpectation;
 }
 
 /** Every recognized `expect` clause key — for the excess-key check below and
  * for exhaustiveness at call sites. */
-const EXPECT_KEYS = ["noop", "create", "update", "delete", "deletes", "unobserved"] as const;
+export const EXPECT_KEYS = ["noop", "create", "update", "delete", "deletes", "unobserved", "cost"] as const;
 
 const OWNERSHIP_VALUES: readonly Ownership[] = ["owned", "foreign", "unknown"];
 
@@ -293,6 +333,34 @@ function validateExpect(name: string, expect: unknown): ScenarioExpect {
       );
     }
   }
+  if ("cost" in e) {
+    const c = e.cost;
+    if (typeof c !== "object" || c === null || Array.isArray(c)) {
+      throw new Error(`Scenario("${name}"): \`expect.cost\` must be { maxPerHour, currency, entity? }`);
+    }
+    const { maxPerHour, currency, entity } = c as Record<string, unknown>;
+    if (typeof maxPerHour !== "number" || !Number.isFinite(maxPerHour) || maxPerHour < 0) {
+      throw new Error(`Scenario("${name}"): \`expect.cost.maxPerHour\` must be a non-negative finite number`);
+    }
+    if (typeof currency !== "string" || currency.trim() === "") {
+      throw new Error(
+        `Scenario("${name}"): \`expect.cost.currency\` must be a non-empty ISO 4217 code — chant converts nothing, so a bound needs its currency`,
+      );
+    }
+    if (entity !== undefined && (typeof entity !== "string" || entity.length === 0)) {
+      throw new Error(`Scenario("${name}"): \`expect.cost.entity\`, when present, must be a non-empty string`);
+    }
+    for (const key of Object.keys(c as object)) {
+      if (!["maxPerHour", "currency", "entity"].includes(key)) {
+        throw new Error(`Scenario("${name}"): unknown \`expect.cost\` field "${key}" — expected maxPerHour, currency, entity`);
+      }
+    }
+    out.cost = Object.freeze({
+      maxPerHour,
+      currency: currency.trim(),
+      ...(entity !== undefined ? { entity } : {}),
+    });
+  }
 
   return Object.freeze(out) as ScenarioExpect;
 }

package/src/lifecycle/types.ts

@@ -1,6 +1,7 @@
 import type { ResourceMetadata, ArtifactMetadata } from "../lexicon";
 import type { UnobservedEntity } from "../observation";
 import type { DeepResourceObservation } from "../deep-observation";
+import type { BehaviourResult } from "../behaviour";
 import type { IREdge } from "../graph-ir";
 
 export type { ResourceMetadata, ArtifactMetadata } from "../lexicon";
@@ -84,6 +85,22 @@ export interface LifecycleSnapshot {
   stackExports?: Record<string, Record<string, unknown>>;
   /** Build digest at snapshot time — what was declared when this snapshot was taken */
   digest?: BuildDigest;
+  /**
+   * What a behaviour engine said about this estate, when one was asked
+   * (#2358): the whole `BehaviourResult`, a report or a named refusal,
+   * exactly as `predictBehaviour()` returned it.
+   *
+   * Carried on the snapshot rather than in a fixture of its own because a
+   * `Scenario` has one `given`, and that one fixture stands in for everything
+   * a live read would have answered — presence, ownership, and now the
+   * engine's figures. A scenario's `expect.cost` clause reads this block;
+   * `chant scenario check` refuses the clause, naming the reason, when the
+   * block is absent or is a refusal, because a bound checked against no figure
+   * would pass on nothing. Absent on every snapshot written before this and
+   * on every snapshot recorded without an engine, which is read as "no
+   * prediction was made" rather than as a prediction of nothing.
+   */
+  behaviour?: BehaviourResult;
 }
 
 /**

package/src/lint/rules/op/ops012-activity-contract.test.ts

@@ -95,6 +95,37 @@ describe("OPS012: activity-contract", () => {
     expect(diags[0].entity).toBe("op");
   });
 
+  test("validates a step calling predictBehaviour or behaviourFinding against core's own table (#2358)", () => {
+    const ok = makeCtxFromEntities(new Map([
+      ["op", opEntity("pr-behaviour", [
+        { kind: "activity", fn: "predictBehaviour", args: { environment: "prod", traffic: "1000 rps, p99" } },
+        {
+          kind: "activity",
+          fn: "behaviourFinding",
+          args: { environment: "prod", traffic: "1000 rps, p99", op: "pr-behaviour", mode: "comment" },
+          outcomeAttribute: { name: "Comment", from: "commentUrl" },
+        },
+      ])],
+    ]));
+    expect(ops012.check(ok)).toHaveLength(0);
+
+    const typo = makeCtxFromEntities(new Map([
+      ["op", opEntity("pr-behaviour", [
+        { kind: "activity", fn: "behaviourFinding", args: { enviroment: "prod", traffic: "1000 rps, p99", op: "pr-behaviour" } },
+      ])],
+    ]));
+    const diags = ops012.check(typo);
+    expect(diags.length).toBeGreaterThan(0);
+    expect(diags.some((d) => d.message.includes("enviroment"))).toBe(true);
+
+    const badMode = makeCtxFromEntities(new Map([
+      ["op", opEntity("pr-behaviour", [
+        { kind: "activity", fn: "behaviourFinding", args: { environment: "prod", traffic: "1000 rps, p99", op: "pr-behaviour", mode: "issue" } },
+      ])],
+    ]));
+    expect(ops012.check(badMode).some((d) => d.message.includes("mode"))).toBe(true);
+  });
+
   test("errors on an outcomeAttribute.from path that doesn't exist on the declared return type", () => {
     const ctx = makeCtxFromEntities(new Map([
       ["op", opEntity("deploy", [

package/src/op/activities/activity-contracts.ts

@@ -64,3 +64,52 @@ export const chantTeardownContract = activityContract(
   "chantTeardown",
   z.strictObject({ path: z.string() }),
 );
+
+/**
+ * The prediction (#2358). `args` mirrors `PredictBehaviourArgs` field for
+ * field; the return is the contract's `BehaviourResult`, a report or a
+ * refusal, so `returns` is the envelope both arms share and a step's
+ * `outcomeAttribute.from` may name `behaviour` or `refusal`.
+ */
+export const predictBehaviourContract = activityContract(
+  "predictBehaviour",
+  z.strictObject({
+    environment: z.string(),
+    traffic: z.string(),
+    stack: z.string().optional(),
+    region: z.string().optional(),
+    owned: z.boolean().optional(),
+  }),
+  z.object({ behaviour: z.literal("v1"), refusal: z.unknown().optional() }),
+);
+
+/**
+ * The pull-request finding (#2358). Same inputs as the prediction plus the
+ * Op's name (the marker's key, #2319), the mode, and an optional explicit
+ * base branch. `returns` names what a step reads as an outcome — the posted
+ * URL, and whether either side refused.
+ */
+export const behaviourFindingContract = activityContract(
+  "behaviourFinding",
+  z.strictObject({
+    environment: z.string(),
+    traffic: z.string(),
+    op: z.string(),
+    mode: z.enum(["comment", "report"]).optional(),
+    base: z.string().optional(),
+    title: z.string().optional(),
+    stack: z.string().optional(),
+    region: z.string().optional(),
+    owned: z.boolean().optional(),
+  }),
+  z.object({
+    mode: z.enum(["comment", "report"]),
+    base: z.string(),
+    head: z.string(),
+    refused: z.boolean(),
+    summary: z.string(),
+    commentUrl: z.string().optional(),
+    pullRequest: z.string().optional(),
+    mergeRequest: z.string().optional(),
+  }),
+);

package/src/op/activities/index.ts

@@ -124,3 +124,27 @@ export type {
   GhRunner,
   ApplyBumpFn,
 } from "./lexicon-upgrade";
+
+// The behaviour prediction and the pull-request finding built on it (#2358).
+// Only the two activities and the pure helpers are re-exported: the registry
+// collects every exported function as an activity, so `createBehaviourFinding`
+// and `checkoutBase` stay on the module.
+export {
+  predictBehaviour,
+  behaviourFinding,
+  behaviourFindingMarker,
+  declaredEdgeCoverage,
+  baseRefFrom,
+  headRefFrom,
+  noBaseRefMessage,
+  noPredictingLexiconMessage,
+  ambiguousPredictorMessage,
+} from "./predict-behaviour";
+export type {
+  PredictBehaviourArgs,
+  BehaviourFindingArgs,
+  BehaviourFindingResult,
+  BehaviourFindingMode,
+  BehaviourFindingDeps,
+  BaseCheckout,
+} from "./predict-behaviour";