@intentius/chant 0.74.1 → 0.75.0

package/bin/chant

@@ -11,4 +11,17 @@ done
 SCRIPT_DIR="$(cd "$(dirname "$SELF")" && pwd)"
 MAIN_TS="$SCRIPT_DIR/../src/cli/main.ts"
 
+# tsx is our own dependency, so register its hooks in this node process rather
+# than shelling `npx tsx`, which resolves a bin and then spawns a second node.
+# Worth ~30% of startup (#2481). Nested install first, then hoisted; npx stays
+# as the fallback for any layout neither guess covers.
+for CANDIDATE in \
+  "$SCRIPT_DIR/../node_modules/tsx/dist/loader.mjs" \
+  "$SCRIPT_DIR/../../../tsx/dist/loader.mjs"
+do
+  if [ -f "$CANDIDATE" ]; then
+    exec node --import "file://$CANDIDATE" "$MAIN_TS" "$@"
+  fi
+done
+
 exec npx tsx "$MAIN_TS" "$@"

package/dist/behaviour-graph.d.ts

@@ -0,0 +1,71 @@
+/**
+ * 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 { type BehaviourOverlay } from "./behaviour-overlay.js";
+import type { GraphIR } from "./graph-ir.js";
+import type { PredictBehaviourOptions } from "./behaviour.js";
+/**
+ * What the caller knows and the graph does not.
+ *
+ * `edgeCoverage` is here rather than derived because this module cannot
+ * honestly derive it. Whether the edges in hand are the whole graph depends on
+ * which anchoring produced them and which lexicons contributed a reference
+ * catalog, and both facts live with the caller.
+ */
+export interface BehaviourRequestContext extends Pick<PredictBehaviourOptions, "environment" | "traffic" | "buildOutput" | "edgeCoverage"> {
+    stack?: string;
+    region?: string;
+    owned?: boolean;
+}
+/**
+ * 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 declare function behaviourRequestFromIr(ir: GraphIR, ctx: BehaviourRequestContext): PredictBehaviourOptions;
+/**
+ * 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 declare function applyBehaviourOverlay(ir: GraphIR, overlay: BehaviourOverlay): GraphIR;
+//# sourceMappingURL=behaviour-graph.d.ts.map

package/dist/behaviour-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"behaviour-graph.d.ts","sourceRoot":"","sources":["../src/behaviour-graph.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,EAA0B,KAAK,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACpF,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAE3D;;;;;;;GAOG;AACH,MAAM,WAAW,uBACf,SAAQ,IAAI,CAAC,uBAAuB,EAAE,aAAa,GAAG,SAAS,GAAG,aAAa,GAAG,cAAc,CAAC;IACjG,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,uBAAuB,GAAG,uBAAuB,CAiBzG;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAUrF"}

package/dist/cli/handlers/graph.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["../../../src/cli/handlers/graph.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAiHlD;;;;;;;;;GASG;AACH,wBAAsB,QAAQ,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAwCnE"}
+{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["../../../src/cli/handlers/graph.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAiHlD;;;;;;;;;GASG;AACH,wBAAsB,QAAQ,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAkDnE"}

package/dist/cli/main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":";AAMA,OAAO,EAAkB,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AA0F9E;;GAEG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CA0WpD;AA+bD;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,EAAE,UAAU,EAmGvC,CAAC;AAqIF;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,CAAC,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAuB5E"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":";AAMA,OAAO,EAAkB,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AA0F9E;;GAEG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CA8WpD;AAocD;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,EAAE,UAAU,EAmGvC,CAAC;AAqIF;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,CAAC,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAuB5E"}

package/dist/cli/registry.d.ts

@@ -158,6 +158,17 @@ export interface ParsedArgs {
      * cross-substrate topology) and joins live status per node; `live` keeps the
      * provisioned graph's reconstructed edges (the pre-#821 behaviour). */
     overlayAnchor?: "source" | "live";
+    /** `chant graph --live --overlay --traffic "<level>"` (#2377) — predict the
+     * overlaid estate's behaviour at this traffic level and carry the result on
+     * the IR: each entity's block on `attrs._behaviour`, the report's meta (or a
+     * whole refusal report) on `meta._behaviour`.
+     *
+     * The flag is the trigger, and it has no default. The level is passed to the
+     * engine verbatim — chant does not parse it, default it or convert it
+     * (`../behaviour.ts`) — so without the flag there is no traffic level to
+     * predict *at*, nothing is asked, and neither key appears. A consumer reads
+     * that absence as "not looked", never as a refusal. */
+    traffic?: string;
     /** `chant list --components` / `chant graph --components` — surface discovered
      * `Component` declarations (#560) instead of/alongside lexicon resources. */
     components?: boolean;

package/dist/cli/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/cli/registry.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/cli/registry.ts"],"names":[],"mappings":"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"}

package/dist/graph-ir.d.ts

@@ -258,6 +258,21 @@ export interface GraphIR {
     nodes: IRNode[];
     edges: IREdge[];
     groups: IRGroups;
+    /**
+     * Graph-level facts that are about the whole read rather than any one node.
+     *
+     * Deliberately an open bag. A fact lands here when it has no node to sit on
+     * — `_behaviour` (#2377) carries the engine, its version, the traffic level
+     * the figures are *at*, and the estate's totals, or a whole refusal report
+     * when there was no engine to ask. None of that is a property of a single
+     * entity, and putting the refusal on nodes would mean writing it N times or
+     * dropping it, and dropping it is the one outcome the contract forbids
+     * (`./behaviour-overlay.ts`).
+     *
+     * Absent unless something filled it, and a consumer reads absence as "not
+     * looked" rather than as a negative finding.
+     */
+    meta?: Record<string, unknown>;
     /** Outputs this stack publishes for other stacks to import (#513). */
     exports?: IRExport[];
     /** Parameters this stack imports from other stacks. A viewer matches an import's

package/dist/graph-ir.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph-ir.d.ts","sourceRoot":"","sources":["../src/graph-ir.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"graph-ir.d.ts","sourceRoot":"","sources":["../src/graph-ir.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant",
-  "version": "0.74.1",
+  "version": "0.75.0",
   "description": "Declarative infrastructure-as-code toolkit — TypeScript on Node.js",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",

package/src/behaviour-graph.test.ts

@@ -0,0 +1,151 @@
+/**
+ * The graph seam (#2377): a request built from the graph in hand, and a
+ * projection put back onto it.
+ *
+ * The three states #2377 names are asserted on the values that reach the IR,
+ * because that IR is behold's whole input: a block per predicted node and the
+ * meta, nothing at all when no prediction was asked for, and the refusal on
+ * the meta with no node carrying a block.
+ */
+
+import { describe, expect, it } from "vitest";
+import {
+  behaviourReport,
+  noBehaviourEngineRefusal,
+  predictedRate,
+  type PredictedBehaviour,
+} from "./behaviour";
+import { BEHAVIOUR_OVERLAY_ATTR, behaviourOverlay } from "./behaviour-overlay";
+import { applyBehaviourOverlay, behaviourRequestFromIr } from "./behaviour-graph";
+import type { GraphIR, IRNode } from "./graph-ir";
+
+const node = (id: string, kind: string, attrs: Record<string, unknown> = {}): IRNode => ({
+  id,
+  kind,
+  lexicon: "aws",
+  attrs,
+});
+
+const ir = (nodes: IRNode[], edges: GraphIR["edges"] = []): GraphIR => ({
+  nodes,
+  edges,
+  groups: { stacks: [], composites: [] } as unknown as GraphIR["groups"],
+});
+
+const block: PredictedBehaviour = {
+  at: { traffic: "100 rps, p50" },
+  cost: predictedRate(0.0416, "USD"),
+  headroom: { cpu: 0.6 },
+  errorRate: 0.0005,
+  resilience: { failure: "one zone lost", verdict: "survives" },
+  provenance: { engine: "fixture", version: "0.0.1", tolerance: "±20%", basis: "modeled" },
+};
+
+const ctx = {
+  environment: "prod",
+  traffic: "100 rps, p50",
+  buildOutput: "",
+  edgeCoverage: { verdict: "unknown" } as const,
+};
+
+describe("behaviourRequestFromIr", () => {
+  it("names every node and carries its kind and props verbatim", () => {
+    const graph = ir([node("web", "AWS::EC2::Instance", { instanceType: "t3.small" }), node("role", "AWS::IAM::Role")]);
+    const req = behaviourRequestFromIr(graph, ctx);
+
+    expect(req.entityNames).toEqual(["web", "role"]);
+    expect(req.entities.get("web")).toEqual({
+      entityType: "AWS::EC2::Instance",
+      props: { instanceType: "t3.small" },
+    });
+    expect(req.traffic).toBe("100 rps, p50");
+    expect(req.environment).toBe("prod");
+  });
+
+  it("passes the graph's own edges through, because the prediction is about paths", () => {
+    const edges = [{ from: "web", to: "db", kind: "ref" }] as unknown as GraphIR["edges"];
+    const req = behaviourRequestFromIr(ir([node("web", "X"), node("db", "Y")], edges), ctx);
+    expect(req.edges).toBe(edges);
+  });
+
+  it("does not filter props down to what chant thinks matters", () => {
+    // chant prices nothing, so it cannot know which field moves a figure. A
+    // filtered request would hand the engine a silently incomplete entity.
+    const attrs = { instanceType: "t3.small", tags: { team: "core" }, somethingChantHasNeverHeardOf: 7 };
+    const req = behaviourRequestFromIr(ir([node("web", "AWS::EC2::Instance", attrs)]), ctx);
+    expect(req.entities.get("web")?.props).toEqual(attrs);
+  });
+
+  it("omits stack, region and owned rather than sending undefined for them", () => {
+    const req = behaviourRequestFromIr(ir([node("web", "X")]), ctx);
+    expect("stack" in req).toBe(false);
+    expect("region" in req).toBe(false);
+    expect("owned" in req).toBe(false);
+  });
+});
+
+describe("applyBehaviourOverlay", () => {
+  const report = behaviourReport(
+    { entityNames: ["web", "role"], traffic: "100 rps, p50", edgeCoverage: { verdict: "unknown" } },
+    { engine: "fixture", version: "0.0.1", total: predictedRate(0.0416, "USD") },
+    { web: block },
+    { role: { reason: "unsupported-kind", detail: "a role is a grant" } },
+  );
+
+  it("puts a predicted entity's block on its own node, and the meta on the graph", () => {
+    const out = applyBehaviourOverlay(ir([node("web", "X"), node("role", "Y")]), behaviourOverlay(report));
+
+    expect(out.nodes[0].attrs[BEHAVIOUR_OVERLAY_ATTR]).toBe(block);
+    const meta = out.meta?.[BEHAVIOUR_OVERLAY_ATTR] as Record<string, unknown>;
+    expect(meta.engine).toBe("fixture");
+    expect(meta.at).toEqual({ traffic: "100 rps, p50" });
+  });
+
+  it("leaves an unpredicted node with no _behaviour key at all", () => {
+    const out = applyBehaviourOverlay(ir([node("web", "X"), node("role", "Y")]), behaviourOverlay(report));
+    // Not a zeroed block: "costs nothing" and "was not priced" are different
+    // claims, and a renderer cannot tell them apart after the fact.
+    expect(BEHAVIOUR_OVERLAY_ATTR in out.nodes[1].attrs).toBe(false);
+  });
+
+  it("a refusal rides on the meta whole, and no node carries a block", () => {
+    const out = applyBehaviourOverlay(
+      ir([node("web", "X"), node("role", "Y")]),
+      behaviourOverlay(noBehaviourEngineRefusal("terraform")),
+    );
+
+    const meta = out.meta?.[BEHAVIOUR_OVERLAY_ATTR] as Record<string, unknown>;
+    // behold's reader branches on `refusal` before it looks for `engine`.
+    expect(meta.refusal).toBeDefined();
+    expect(meta.behaviour).toBe("v1");
+    for (const n of out.nodes) expect(BEHAVIOUR_OVERLAY_ATTR in n.attrs).toBe(false);
+  });
+
+  it("keeps the drift overlay's attrs on the node beside the new block", () => {
+    // `_behaviour` joins `_status` rather than replacing the attrs object;
+    // losing the drift paint to gain a prediction would be a regression a
+    // renderer shows as every node going uncoloured.
+    const graph = ir([node("web", "X", { _status: "good", instanceType: "t3.small" })]);
+    const out = applyBehaviourOverlay(graph, behaviourOverlay(report));
+
+    expect(out.nodes[0].attrs._status).toBe("good");
+    expect(out.nodes[0].attrs.instanceType).toBe("t3.small");
+    expect(out.nodes[0].attrs[BEHAVIOUR_OVERLAY_ATTR]).toBe(block);
+  });
+
+  it("does not mutate the graph it was given", () => {
+    // The caller's `ir` goes on to the lens pipeline; a prediction must not be
+    // the reason a later pass sees different nodes.
+    const graph = ir([node("web", "X", { _status: "good" })]);
+    const before = JSON.stringify(graph);
+    applyBehaviourOverlay(graph, behaviourOverlay(report));
+    expect(JSON.stringify(graph)).toBe(before);
+  });
+
+  it("keeps meta keys another pass already put on the graph", () => {
+    const graph = { ...ir([node("web", "X")]), meta: { _somethingElse: 1 } };
+    const out = applyBehaviourOverlay(graph, behaviourOverlay(report));
+    expect(out.meta?._somethingElse).toBe(1);
+    expect(out.meta?.[BEHAVIOUR_OVERLAY_ATTR]).toBeDefined();
+  });
+});

package/src/behaviour-graph.ts

@@ -0,0 +1,102 @@
+/**
+ * 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, type BehaviourOverlay } from "./behaviour-overlay";
+import type { GraphIR } from "./graph-ir";
+import type { PredictBehaviourOptions } from "./behaviour";
+
+/**
+ * What the caller knows and the graph does not.
+ *
+ * `edgeCoverage` is here rather than derived because this module cannot
+ * honestly derive it. Whether the edges in hand are the whole graph depends on
+ * which anchoring produced them and which lexicons contributed a reference
+ * catalog, and both facts live with the caller.
+ */
+export interface BehaviourRequestContext
+  extends Pick<PredictBehaviourOptions, "environment" | "traffic" | "buildOutput" | "edgeCoverage"> {
+  stack?: string;
+  region?: string;
+  owned?: boolean;
+}
+
+/**
+ * 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: GraphIR, ctx: BehaviourRequestContext): PredictBehaviourOptions {
+  const entities = new Map<string, { entityType: string; props: Record<string, unknown> }>();
+  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,
+    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: GraphIR, overlay: BehaviourOverlay): GraphIR {
+  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/src/cli/handlers/graph.test.ts

@@ -110,6 +110,7 @@ vi.mock("../../build", async () => {
 });
 
 const { runGraph } = await import("./graph");
+const { behaviourReport, noBehaviourEngineRefusal, predictedRate } = await import("../../behaviour");
 
 function makeArgs(overrides: Partial<ParsedArgs> = {}): ParsedArgs {
   return {
@@ -626,6 +627,200 @@ describe("runGraph", () => {
       expect(out).toContain("web-vpc");
     });
 
+    // #2377 — the overlay carries the prediction. behold's reader takes
+    // `attrs._behaviour` per node and `meta._behaviour` on the graph, and
+    // reads the absence of both as "not looked" rather than as a refusal, so
+    // all three states are asserted on what actually reaches the IR.
+    describe("behaviour overlay (--traffic)", () => {
+      const predictingPlugin = (predictBehaviour: unknown) => ({
+        name: "aws",
+        serializer: {},
+        emulator: awsEmulatorStub,
+        describeResources: () => Promise.resolve({}),
+        predictBehaviour,
+      });
+
+      const liveEstate = () => {
+        resolveLexMock.mockResolvedValue(["aws"]);
+        // `--overlay` builds the declared canvas to classify against. Empty is
+        // enough here: what is under test is the behaviour block, and an empty
+        // declared graph leaves the observed nodes in place as foreign.
+        discoverMock.mockResolvedValue({ entities: new Map(), errors: [], sourceFiles: [] });
+        observeMock.mockResolvedValue({
+          observations: [{ lexicon: "aws", resources: {
+            web: { type: "AWS::EC2::Instance", status: "OK" },
+            role: { type: "AWS::IAM::Role", status: "OK" },
+          } }],
+          errors: [],
+          warnings: [],
+        });
+      };
+
+      const report = () => behaviourReport(
+        { entityNames: ["web", "role"], traffic: "100 rps, p50", edgeCoverage: { verdict: "unknown" } },
+        { engine: "fixture", version: "0.0.1", total: predictedRate(0.0416, "USD") },
+        { web: {
+          at: { traffic: "100 rps, p50" },
+          cost: predictedRate(0.0416, "USD"),
+          headroom: { cpu: 0.6 },
+          errorRate: 0.0005,
+          resilience: { failure: "one zone lost", verdict: "survives" },
+          provenance: { engine: "fixture", version: "0.0.1", tolerance: "±20%", basis: "modeled" },
+        } },
+        { role: { reason: "unsupported-kind", detail: "a role is a grant" } },
+      );
+
+      test("with an engine: the block is on its node and the meta on the graph", async () => {
+        liveEstate();
+        loadPluginsMock.mockResolvedValue([predictingPlugin(() => Promise.resolve(report()))]);
+
+        const exit = await runGraph({
+          args: makeArgs({ format: "ir", live: true, overlay: true, env: "prod", traffic: "100 rps, p50" }),
+          plugins: [], serializers: [],
+        });
+
+        expect(exit).toBe(0);
+        const ir = JSON.parse(stdoutBuf.join("\n")) as {
+          nodes: Array<{ id: string; attrs: Record<string, unknown> }>;
+          meta?: Record<string, { engine?: string; at?: { traffic?: string } }>;
+        };
+        expect(ir.meta?._behaviour?.engine).toBe("fixture");
+        expect(ir.meta?._behaviour?.at?.traffic).toBe("100 rps, p50");
+        const web = ir.nodes.find((n) => n.id === "web");
+        expect((web?.attrs._behaviour as { cost?: { perHour?: number } })?.cost?.perHour).toBe(0.0416);
+        // An entity the engine could not price carries no block rather than a
+        // zeroed one — "costs nothing" is a different claim from "not priced".
+        expect("_behaviour" in (ir.nodes.find((n) => n.id === "role")?.attrs ?? {})).toBe(false);
+      });
+
+      test("the traffic level reaches the engine verbatim, with the graph's own entities", async () => {
+        liveEstate();
+        const seen: Array<{ traffic: string; entityNames: string[] }> = [];
+        loadPluginsMock.mockResolvedValue([predictingPlugin((o: { traffic: string; entityNames: string[] }) => {
+          seen.push({ traffic: o.traffic, entityNames: o.entityNames });
+          return Promise.resolve(report());
+        })]);
+
+        await runGraph({
+          args: makeArgs({ format: "ir", live: true, overlay: true, env: "prod", traffic: "1000 rps, p99" }),
+          plugins: [], serializers: [],
+        });
+
+        expect(seen[0]?.traffic).toBe("1000 rps, p99");
+        expect(seen[0]?.entityNames).toContain("web");
+      });
+
+      test("without --traffic: nothing is asked and neither key appears", async () => {
+        liveEstate();
+        let called = false;
+        loadPluginsMock.mockResolvedValue([predictingPlugin(() => { called = true; return Promise.resolve(report()); })]);
+
+        const exit = await runGraph({
+          args: makeArgs({ format: "ir", live: true, overlay: true, env: "prod" }),
+          plugins: [], serializers: [],
+        });
+
+        expect(exit).toBe(0);
+        // Not a refusal: an engine was configured and reachable. behold reads
+        // this absence as "not looked", which is why nothing may be written.
+        expect(called).toBe(false);
+        const ir = JSON.parse(stdoutBuf.join("\n")) as {
+          nodes: Array<{ attrs: Record<string, unknown> }>; meta?: Record<string, unknown>;
+        };
+        expect(ir.meta?._behaviour).toBeUndefined();
+        for (const n of ir.nodes) expect("_behaviour" in n.attrs).toBe(false);
+      });
+
+      test("a refusal rides on the meta whole, and no node carries a block", async () => {
+        liveEstate();
+        loadPluginsMock.mockResolvedValue([
+          predictingPlugin(() => Promise.resolve(noBehaviourEngineRefusal("aws"))),
+        ]);
+
+        const exit = await runGraph({
+          args: makeArgs({ format: "ir", live: true, overlay: true, env: "prod", traffic: "100 rps, p50" }),
+          plugins: [], serializers: [],
+        });
+
+        expect(exit).toBe(0);
+        const ir = JSON.parse(stdoutBuf.join("\n")) as {
+          nodes: Array<{ attrs: Record<string, unknown> }>;
+          meta?: { _behaviour?: { refusal?: { reason?: string }; behaviour?: string } };
+        };
+        // behold branches on `refusal` before it looks for `engine`; the
+        // envelope is what makes it findable at all.
+        expect(ir.meta?._behaviour?.refusal?.reason).toMatch(/CHANT_BEHAVIOUR_ENGINE/);
+        expect(ir.meta?._behaviour?.behaviour).toBe("v1");
+        for (const n of ir.nodes) expect("_behaviour" in n.attrs).toBe(false);
+      });
+
+      test("no predicting lexicon: the graph is served unchanged, and says so once", async () => {
+        liveEstate();
+        loadPluginsMock.mockResolvedValue([
+          { name: "aws", serializer: {}, emulator: awsEmulatorStub, describeResources: () => Promise.resolve({}) },
+        ]);
+
+        const exit = await runGraph({
+          args: makeArgs({ format: "ir", live: true, overlay: true, env: "prod", traffic: "100 rps, p50" }),
+          plugins: [], serializers: [],
+        });
+
+        expect(exit).toBe(0);
+        expect(stderrBuf.join("\n")).toContain("no installed lexicon implements predictBehaviour");
+        expect(JSON.parse(stdoutBuf.join("\n")).meta?._behaviour).toBeUndefined();
+      });
+
+      test("a thrown engine costs the prediction, never the graph", async () => {
+        liveEstate();
+        loadPluginsMock.mockResolvedValue([
+          predictingPlugin(() => Promise.reject(new Error("socket hang up"))),
+        ]);
+
+        const exit = await runGraph({
+          args: makeArgs({ format: "ir", live: true, overlay: true, env: "prod", traffic: "100 rps, p50" }),
+          plugins: [], serializers: [],
+        });
+
+        // The estate graph is what was asked for; a broken engine must not
+        // take it away.
+        expect(exit).toBe(0);
+        expect(stderrBuf.join("\n")).toContain("socket hang up");
+        const ir = JSON.parse(stdoutBuf.join("\n")) as { nodes: unknown[]; meta?: Record<string, unknown> };
+        expect(ir.nodes.length).toBeGreaterThan(0);
+        expect(ir.meta?._behaviour).toBeUndefined();
+      });
+
+      test("--traffic without --live is refused rather than silently ignored", async () => {
+        // Accepted-and-ignored would read as "predicted, and everything came
+        // back empty", which is the opposite of what happened.
+        const exit = await runGraph({
+          args: makeArgs({ format: "ir", traffic: "100 rps, p50" }),
+          plugins: [], serializers: [],
+        });
+
+        expect(exit).toBe(1);
+        expect(stderrBuf.join("\n")).toContain("--traffic needs --live");
+      });
+
+      test("two predicting lexicons is refused rather than attributed to one", async () => {
+        liveEstate();
+        loadPluginsMock.mockResolvedValue([
+          predictingPlugin(() => Promise.resolve(report())),
+          { ...predictingPlugin(() => Promise.resolve(report())), name: "gcp" },
+        ]);
+
+        const exit = await runGraph({
+          args: makeArgs({ format: "ir", live: true, overlay: true, env: "prod", traffic: "100 rps, p50" }),
+          plugins: [], serializers: [],
+        });
+
+        // One `meta._behaviour` key and two engines: taking the first would
+        // put one engine's figures under the other's provenance.
+        expect(exit).toBe(1);
+        expect(stderrBuf.join("\n")).toContain("cannot merge two engines");
+      });
+    });
+
     // #1279 — `graph` had no `--at`, so anyone wanting the raw IR of a recorded
     // estate had to reach for the live endpoint. A snapshot could answer most
     // questions and never all of them.

package/src/cli/handlers/graph.ts

@@ -3,6 +3,9 @@ import { discoverOps } from "../../op/discover";
 import { discover } from "../../discovery/index";
 import { partitionByLexicon, computeStackGraph, build, mergeBuildRootEntities } from "../../build";
 import { buildGraphIr, buildLiveGraphIr, collectUnobserved, overlayGraphs, sourceOverlayGraphs, type GraphIR, type IRPipeline, type LiveObservation } from "../../graph-ir";
+import { behaviourOverlay } from "../../behaviour-overlay";
+import type { SerializerResult } from "../../serializer";
+import { applyBehaviourOverlay, behaviourRequestFromIr } from "../../behaviour-graph";
 import { buildDeclaredPerStack } from "../../graph-declared";
 import { mergeProjectOps } from "../../graph-ops";
 import { reconstructEdges, mergeCatalogs, containmentGroups, type ReferenceCatalog, type ContainmentPair } from "../../graph-refs";
@@ -157,6 +160,16 @@ export async function runGraph(ctx: CommandContext): Promise<number> {
     }));
     return 1;
   }
+  // A prediction is about an estate, and only the live path has one. Without
+  // `--live` the flag would be accepted and do nothing at all, which reads as
+  // "predicted, and everything came back empty" rather than "never ran".
+  if (ctx.args.traffic && !ctx.args.live) {
+    console.error(formatError({
+      message: "--traffic needs --live: a prediction is made about the observed estate, and there is nothing to predict on the declared graph alone.",
+      hint: 'chant graph --format ir --live --env <name> --overlay --traffic "100 rps, p50"',
+    }));
+    return 1;
+  }
   // `--at` graphs a recorded observation instead of reading the estate (#1279).
   // Two different observations with no rule for which wins, so not both.
   if (ctx.args.at && ctx.args.live) {
@@ -434,6 +447,71 @@ async function runGraphLive(
     }
   }
 
+  // Behaviour overlay (#2377, epic #2355): carry a prediction on the graph.
+  //
+  // `--traffic` is the trigger, and it is the trigger because the contract
+  // forbids defaulting the level (../../behaviour.ts): every figure an engine
+  // returns is *at* a stated traffic, so inventing one here would silently
+  // decide what every number on the graph means. No flag: nothing is asked,
+  // neither key appears, and a consumer reads that absence as "not looked".
+  //
+  // Placed after the drift overlay so the prediction lands on the final node
+  // set — the canvas is settled by here under either anchoring — and before
+  // the lens below, so a lens filters predicted nodes like any other.
+  if (args.traffic) {
+    const predicting = plugins.filter((p) => p.predictBehaviour);
+    if (predicting.length === 0) {
+      console.error(formatWarning({
+        message:
+          "--traffic: no installed lexicon implements predictBehaviour, so nothing was predicted. The graph is unchanged.",
+      }));
+    } else if (predicting.length > 1) {
+      // Two engines would mean two `meta._behaviour` values and one key. Rather
+      // than pick, say so: a merged prediction across engines is not defined by
+      // the contract, and silently taking the first would attribute one
+      // engine's figures to the other's provenance.
+      console.error(formatError({
+        message: `--traffic: ${predicting.length} lexicons implement predictBehaviour (${predicting.map((p) => p.name).join(", ")}) — chant cannot merge two engines' figures onto one graph.`,
+        hint: "Predict one lexicon at a time, or drop --traffic to graph without a prediction",
+      }));
+      return 1;
+    } else {
+      // The first output the build produced, or empty. Nothing on this path
+      // reads it — the mirror is kept so the four observation methods take the
+      // same shape (../../op/activities/predict-behaviour.ts) — so a build
+      // result without outputs costs an empty string, never the graph.
+      const raw = buildResult.outputs ? [...buildResult.outputs.values()][0] : undefined;
+      const buildOutput = raw === undefined ? "" : typeof raw === "string" ? raw : (raw as SerializerResult).primary;
+      const request = behaviourRequestFromIr(ir, {
+        environment: environment ?? "",
+        traffic: args.traffic,
+        buildOutput,
+        // `unknown`, for the reason the declared path claims it
+        // (../../op/activities/predict-behaviour.ts): reference edges resolved,
+        // containment absent, and no vocabulary here for "this kind is a
+        // boundary whose containment is missing". Claiming `complete` would be
+        // true about references and false about the graph; `partial` has to
+        // name its gap as `dangling` or `unresolvedKinds`, and this gap is
+        // neither.
+        edgeCoverage: { verdict: "unknown" },
+        ...(args.owned === undefined ? {} : { owned: args.owned }),
+      });
+      try {
+        // A refusal is a value, not a throw: it comes back as a result and
+        // rides on `meta._behaviour` whole, which is the one shape behold's
+        // reader branches on (../../behaviour-overlay.ts).
+        const result = await predicting[0].predictBehaviour!(request);
+        ir = applyBehaviourOverlay(ir, behaviourOverlay(result));
+      } catch (err) {
+        // The estate graph is the thing asked for; a broken engine must not
+        // take it away. Say what failed and serve the graph without the block.
+        console.error(formatWarning({
+          message: `--traffic: ${predicting[0].name}'s predictBehaviour failed (${err instanceof Error ? err.message : String(err)}) — showing the graph without a prediction`,
+        }));
+      }
+    }
+  }
+
   if (args.lens) {
     try {
       ir = applyLens(ir, parseLens(args.lens, { up: args.up, down: args.down }));

package/src/cli/main.test.ts

@@ -4,6 +4,16 @@ import { parseArgs, waitForStreamDrain } from "./main";
 import { resolveCommand, type CommandDef, type ParsedArgs } from "./registry";
 
 describe("parseArgs", () => {
+  // #2377 — the level reaches the engine verbatim, so parsing must not
+  // normalise it, and an empty one must not read as "predict at nothing".
+  test("takes --traffic as an opaque level, and refuses an empty one", () => {
+    expect(parseArgs(["graph", "--live", "--overlay"]).traffic).toBeUndefined();
+    expect(parseArgs(["graph", "--live", "--overlay", "--traffic", "100 rps, p50"]).traffic).toBe("100 rps, p50");
+    // Spacing, casing and punctuation are the engine's to interpret.
+    expect(parseArgs(["graph", "--traffic", "1000rps p99"]).traffic).toBe("1000rps p99");
+    expect(() => parseArgs(["graph", "--traffic"])).toThrow(/--traffic needs a level/);
+  });
+
   test("--fold and --no-fold set the tri-state fold option (#1134)", () => {
     expect(parseArgs(["build", "src"]).fold).toBeUndefined();
     expect(parseArgs(["build", "src", "--fold"]).fold).toBe(true);

package/src/cli/main.ts

@@ -195,6 +195,10 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.betweenA = args[++i];
       result.betweenB = args[++i];
       if (!result.betweenA || !result.betweenB) throw new Error("--between needs two snapshot refs: --between <refA> <refB>");
+    } else if (arg === "--traffic") {
+      const v = args[++i];
+      if (!v) throw new Error('--traffic needs a level, passed to the engine verbatim: --traffic "100 rps, p50"');
+      result.traffic = v;
     } else if (arg === "--overlay-anchor") {
       const v = args[++i];
       if (v !== "source" && v !== "live") throw new Error(`--overlay-anchor must be 'source' or 'live', got '${v}'`);
@@ -595,6 +599,11 @@ Ops:
                         add the CI/pipeline projection (stages/jobs/needs) to
                         the component-graph IR, from the same generator
                         'build --components --generate' uses (#989)
+                        --live --overlay --traffic "<level>": ask the project's
+                        predicting lexicon what the overlaid estate does at that
+                        traffic level, and carry each entity's prediction on the
+                        IR. The level is passed to the engine verbatim; without
+                        the flag nothing is asked and nothing is carried (#2377)
 
 Lifecycle (alias: lc):
   lifecycle snapshot <env>  Query API, save metadata to orphan branch

package/src/cli/registry.ts

@@ -159,6 +159,17 @@ export interface ParsedArgs {
    * cross-substrate topology) and joins live status per node; `live` keeps the
    * provisioned graph's reconstructed edges (the pre-#821 behaviour). */
   overlayAnchor?: "source" | "live";
+  /** `chant graph --live --overlay --traffic "<level>"` (#2377) — predict the
+   * overlaid estate's behaviour at this traffic level and carry the result on
+   * the IR: each entity's block on `attrs._behaviour`, the report's meta (or a
+   * whole refusal report) on `meta._behaviour`.
+   *
+   * The flag is the trigger, and it has no default. The level is passed to the
+   * engine verbatim — chant does not parse it, default it or convert it
+   * (`../behaviour.ts`) — so without the flag there is no traffic level to
+   * predict *at*, nothing is asked, and neither key appears. A consumer reads
+   * that absence as "not looked", never as a refusal. */
+  traffic?: string;
   /** `chant list --components` / `chant graph --components` — surface discovered
    * `Component` declarations (#560) instead of/alongside lexicon resources. */
   components?: boolean;

package/src/graph-ir.ts

@@ -295,6 +295,21 @@ export interface GraphIR {
   nodes: IRNode[];
   edges: IREdge[];
   groups: IRGroups;
+  /**
+   * Graph-level facts that are about the whole read rather than any one node.
+   *
+   * Deliberately an open bag. A fact lands here when it has no node to sit on
+   * — `_behaviour` (#2377) carries the engine, its version, the traffic level
+   * the figures are *at*, and the estate's totals, or a whole refusal report
+   * when there was no engine to ask. None of that is a property of a single
+   * entity, and putting the refusal on nodes would mean writing it N times or
+   * dropping it, and dropping it is the one outcome the contract forbids
+   * (`./behaviour-overlay.ts`).
+   *
+   * Absent unless something filled it, and a consumer reads absence as "not
+   * looked" rather than as a negative finding.
+   */
+  meta?: Record<string, unknown>;
   /** Outputs this stack publishes for other stacks to import (#513). */
   exports?: IRExport[];
   /** Parameters this stack imports from other stacks. A viewer matches an import's