@intentius/chant 0.66.1 → 0.67.0

package/src/behaviour-predict.ts

@@ -0,0 +1,253 @@
+/**
+ * `predictBehaviour()` — the fourth
+ * observation method (#2357, contract #2356).
+ *
+ * The whole method is four moves, in this order, and the order is the contract:
+ *
+ *  1. **Screen the request.** `screenBehaviourRequest` and nothing else. It is
+ *     the only entry point, and calling `assertNoCredentialInOptions` instead
+ *     applies one rule of three — that was review finding F1 on #2365, where a
+ *     `ghp_…` past the walk's depth budget and an `awsSecretAccessKey` in
+ *     `props` both went out with the request.
+ *  2. **Resolve the engine.** `behaviourEngineFrom`, walking
+ *     `CHANT_BEHAVIOUR_ENGINE_BEHAVIOUR_SCOPE` → `CHANT_BEHAVIOUR_ENGINE` →
+ *     `BEHAVIOUR_ENGINE`. Nothing named means `noBehaviourEngineRefusal`, and
+ *     it happens **before** anything is priced: a lexicon that prices first and
+ *     checks the engine afterwards has already decided what zero means.
+ *  3. **Build the request.** `buildEngineRequest`, offline and pure
+ *     (`./request.ts`).
+ *  4. **Ask, and translate the answer.** One {@link EngineOutcome} onto the
+ *     contract's builders. A refusal comes back from the transport already
+ *     built — the contract's transport (#2373) names the condition and the
+ *     variable where the wire was seen — and is returned as it stands; this
+ *     file holds no switch over causes. No figure is ever computed here either:
+ *     this file has no arithmetic on money in it at all, and that is not an
+ *     accident. The epic's first rule is that a missing engine produces a
+ *     refusal and "never a locally faked number", and the surest way to keep
+ *     that true is for the code that would have faked it not to exist.
+ *
+ * ## Every entity lands somewhere
+ *
+ * `behaviourReport` refuses a report that leaves a name in neither map, so the
+ * loop below has no `continue` that drops one. Four ways an entity can end up
+ * unpredicted, and each names a different thing:
+ *
+ * | Outcome | Reason | Means |
+ * |---|---|---|
+ * | the coverage table declares it unmapped | `unsupported-kind` | chant looked, and this kind has no rate |
+ * | the coverage table has never seen it | `unsupported-kind` | chant has not looked; the detail says so and where to add the row |
+ * | the engine declined it | `read-failed` | chant asked and the engine could not answer |
+ * | the engine answered about neither | `read-failed` | the engine lost it, and this says so rather than hiding it |
+ *
+ * The last row is the one that would otherwise be silent. An engine that
+ * returns figures for eleven of twelve nodes and mentions the twelfth nowhere
+ * is a bug in the engine, and an estate that quietly renders eleven nodes is
+ * how it stays a bug.
+ */
+
+import {
+  behaviourReport,
+  behaviourEngineFrom,
+  noBehaviourEngineRefusal,
+  predictedRate,
+  screenBehaviourRequest,
+  unreachableBehaviourEngineRefusal,
+  type BehaviourResult,
+  type PredictBehaviourOptions,
+  type PredictedBehaviour,
+  type UnpredictedEntity,
+} from "./behaviour";
+import { buildEngineRequest } from "./behaviour-request";
+import type { BehaviourKinds } from "./behaviour-kinds";
+import { BEHAVIOUR_SCOPE, defaultConnect, type EngineConnect, type EngineFigure } from "./behaviour-engine";
+
+export { BEHAVIOUR_SCOPE };
+
+/** What {@link createBehaviourPredict} needs that the method's own options do not carry. */
+export interface BehaviourPredictDeps {
+  /**
+   * The coverage rows to resolve entity types against — every configured
+   * lexicon's `behaviourKinds`, in the order the plugins were loaded.
+   *
+   * An empty list is legal and means every declared entity is withheld as
+   * `unknown-type`: nothing has said what any of them are. That is a report
+   * about an estate nobody has rows for, not a refusal, because the engine was
+   * reachable and answered; the distinction is the whole point of the refusal
+   * arm.
+   */
+  kinds?: readonly BehaviourKinds[];
+  /** The environment the engine address is resolved from. Defaults to the process's. */
+  env?: Record<string, string | undefined>;
+  /**
+   * How an address becomes an engine. Defaults to `./behaviour-engine.ts`'s chooser,
+   * which dials a URL through core's HTTP transport and a bare address as a
+   * command on PATH.
+   */
+  connect?: EngineConnect;
+}
+
+/**
+ * Build core's `predictBehaviour`, with the environment and the
+ * transport injected.
+ *
+ * Injected rather than read from module scope so a test can drive the whole
+ * method — screen, resolve, serialize, translate — against a fixture engine
+ * without touching `process.env`, which is what the shared conformance suite's
+ * probes need in order to ask the same request twice and compare.
+ */
+export function createBehaviourPredict(
+  deps: BehaviourPredictDeps = {},
+): (options: PredictBehaviourOptions) => Promise<BehaviourResult> {
+  const env = deps.env ?? process.env;
+  const kinds = deps.kinds ?? [];
+  const connect = deps.connect ?? defaultConnect;
+
+  return async function predictBehaviour(options: PredictBehaviourOptions): Promise<BehaviourResult> {
+    const unsafe = screenBehaviourRequest(BEHAVIOUR_SCOPE, options);
+    if (unsafe) return unsafe;
+
+    const endpoint = behaviourEngineFrom(BEHAVIOUR_SCOPE, env);
+    if (!endpoint) return noBehaviourEngineRefusal(BEHAVIOUR_SCOPE);
+
+    const engine = connect(endpoint, env);
+    if (!engine) {
+      return unreachableBehaviourEngineRefusal(
+        BEHAVIOUR_SCOPE,
+        endpoint,
+        "no transport speaks that address — a http(s) URL is dialled with a bearer token, and a bare " +
+          "address is run as a command on PATH; any other scheme has no transport yet",
+      );
+    }
+
+    const request = buildEngineRequest(options, kinds);
+    const outcome = await engine.predict(request);
+
+    // Built where the wire was seen, and returned as it stands. The three
+    // engine-answered causes and the token cases are mapped once, in the
+    // contract's transport, rather than re-derived here from a cause.
+    if (!outcome.ok) return outcome.refusal;
+
+    const { answer } = outcome;
+    // `Object.create(null)`, not `{}`. An entity named `constructor` or
+    // `toString` writes onto `Object.prototype`'s members on a plain literal,
+    // and one named `__proto__` sets the prototype instead of adding a key, so
+    // the entry vanishes and `behaviourReport`'s totality check fires on an
+    // entity this function believed it had reported. `coverageFor` already
+    // guards its own lookups this way (`./mapping.ts`); these are the same
+    // hazard on the writing side.
+    const entities: Record<string, PredictedBehaviour> = Object.create(null) as Record<string, PredictedBehaviour>;
+    const unpredicted: Record<string, UnpredictedEntity> = Object.create(null) as Record<string, UnpredictedEntity>;
+
+    for (const held of request.withheld) {
+      unpredicted[held.name] = {
+        ...(held.entityType === "(undeclared)" ? {} : { type: held.entityType }),
+        reason: "unsupported-kind",
+        detail: held.detail,
+      };
+    }
+
+    for (const node of request.nodes) {
+      // `hasOwnProperty` for the same reason: `answer.declined` comes from
+      // `JSON.parse`, so `declined["constructor"]` is a function rather than
+      // `undefined` and the `!== undefined` guard below missed it.
+      const declined = has(answer.declined, node.name) ? answer.declined![node.name] : undefined;
+      if (declined !== undefined) {
+        unpredicted[node.name] = {
+          type: node.entityType,
+          reason: "read-failed",
+          detail: `${answer.engine} was sent ${node.name} as a ${node.kind} and declined it: ${declined}`,
+        };
+        continue;
+      }
+      const figure = has(answer.figures, node.name) ? answer.figures[node.name] : undefined;
+      if (figure === undefined) {
+        unpredicted[node.name] = {
+          type: node.entityType,
+          reason: "read-failed",
+          detail:
+            `${answer.engine} was sent ${node.name} and its answer names it in neither its figures nor ` +
+            "its declined list. An engine that loses a node is reported, not rendered as an estate one " +
+            "node smaller.",
+        };
+        continue;
+      }
+      entities[node.name] = block(options.traffic, figure, answer);
+    }
+
+    return behaviourReport(
+      options,
+      {
+        engine: answer.engine,
+        version: answer.version,
+        ...(answer.total
+          ? { total: predictedRate(answer.total.perHour, answer.total.currency) }
+          : {}),
+      },
+      entities,
+      unpredicted,
+    );
+  };
+}
+
+/** An own key, not a prototype member. See the accumulators above. */
+function has(map: Record<string, unknown> | undefined, key: string): boolean {
+  return map !== undefined && Object.prototype.hasOwnProperty.call(map, key);
+}
+
+/**
+ * One engine figure as a contract block.
+ *
+ * `at` comes from the request rather than from the engine's answer. The engine
+ * was asked at one level and `behaviourReport` refuses a block priced at a
+ * level the run did not ask for, so echoing the engine's own idea of the level
+ * would turn an engine that quietly substituted a level it liked better into a
+ * report that agrees with itself and answers the wrong question.
+ *
+ * `headroom` is copied axis by axis. An axis the engine did not model is
+ * **absent**, never `0` — zero headroom means saturated, which is the opposite
+ * claim, and `BehaviourHeadroom` is a union requiring at least one axis so a
+ * figure with neither is a type error rather than a block behold drops.
+ */
+function block(
+  traffic: string,
+  figure: EngineFigure,
+  answer: { engine: string; version: string; tolerance: string; basis: PredictedBehaviour["provenance"]["basis"] },
+): PredictedBehaviour {
+  const cpu = figure.headroom?.cpu;
+  const latency = figure.headroom?.latency;
+  // Built axis by axis, and the cast the first version used here was a lie:
+  // `EngineFigure.headroom` is optional, so a figure stating none produced
+  // `{ latency: undefined }` — an object satisfying `BehaviourHeadroom`
+  // structurally and carrying no axis at all, which behold drops. The doc
+  // claiming a type error caught this was false. `parseEngineAnswer` now
+  // refuses such a figure before it reaches here; this stays correct anyway,
+  // because a lexicon should not depend on its own validator having run.
+  const headroom =
+    cpu !== undefined
+      ? { cpu, ...(latency !== undefined ? { latency } : {}) }
+      : { latency: latency as number };
+  if (cpu === undefined && latency === undefined) {
+    throw new Error(
+      `predictBehaviour: the engine's figure for this entity carries neither a cpu nor a latency ` +
+        "headroom axis, and parseEngineAnswer should have refused it.",
+    );
+  }
+  return {
+    at: { traffic },
+    cost: predictedRate(figure.perHour, figure.currency),
+    headroom,
+    errorRate: figure.errorRate,
+    resilience: {
+      failure: figure.resilience.failure,
+      verdict: figure.resilience.verdict,
+      ...(figure.resilience.note ? { note: figure.resilience.note } : {}),
+    },
+    ...(figure.rightSize ? { rightSize: figure.rightSize } : {}),
+    provenance: {
+      engine: answer.engine,
+      version: answer.version,
+      tolerance: answer.tolerance,
+      basis: answer.basis,
+    },
+  };
+}

package/src/behaviour-request.ts

@@ -0,0 +1,294 @@
+/**
+ * The engine's request, built offline from chant's typed source (#2357).
+ *
+ * `chant build` reaches no network and is byte-identical on re-run
+ * (`packages/core/src/components/verbs/reproducibility.ts`, the
+ * `deterministic-synthesis` basis). The request an engine is handed is built
+ * the same way and holds itself to the same property, for a reason that is not
+ * tidiness: the epic wants the declared prediction and the live prediction
+ * shown as a delta, and a delta is only a statement about the estate if both
+ * sides were assembled the same way from the same source. A request carrying a
+ * timestamp, an unsorted map or a floating-point rendering that depends on the
+ * platform makes every re-run look like drift.
+ *
+ * So everything here is pure. No clock, no `Math.random`, no environment, no
+ * filesystem, no network. {@link renderEngineRequest} is the only place bytes
+ * are produced, and it produces them through a canonical writer that sorts
+ * every object key and every list.
+ *
+ * ## What is in the request, and why the withheld list is in it too
+ *
+ * Nodes, edges, the traffic level, the caller's edge-coverage claim — and
+ * `withheld`, the entities the caller asked about that this lexicon is not
+ * asking the engine about, each with the reason from the coverage table.
+ *
+ * That last one is the same argument `edgeCoverage` won on the contract
+ * (#2365, review finding 6). An engine handed twelve nodes cannot tell whether
+ * the estate has twelve or twenty, and a resilience verdict computed over a
+ * graph with eight nodes missing is a confident answer to a question nobody
+ * asked. Omitting them would make the request's own coverage invisible one
+ * level down from where the contract made it visible.
+ */
+
+import type { IREdge } from "./graph-ir";
+import type { BehaviourEdgeCoverage, PredictBehaviourOptions } from "./behaviour";
+import {
+  byCodeUnit,
+  coverageFor,
+  coverageLabel,
+  ownerOf,
+  unmappedDetail,
+  type BehaviourKinds,
+  type EngineKind,
+} from "./behaviour-kinds";
+
+/** The wire version. Bumped when the shape changes, the way `behaviour: "v1"` is. */
+export const BEHAVIOUR_REQUEST_VERSION = "behaviour/v1" as const;
+
+/** One entity, in the engine's four words: a kind, a provider, a region and a size. */
+export interface EngineNode {
+  /** The chant entity name, which is also the key `edges` uses. */
+  name: string;
+  /** The declared type it was translated from, so an engine can say what it choked on. */
+  entityType: string;
+  /**
+   * The provider's own type, where the declared type does not carry it: a
+   * terraform `resource` block is `Terraform::Resource` whatever it declares,
+   * and `aws_instance` is what an engine can say it choked on (#2360).
+   */
+  resourceType?: string;
+  kind: EngineKind;
+  provider: string;
+  /** Absent where neither the entity nor the caller states one. Never defaulted. */
+  region?: string;
+  /**
+   * The size in the provider's own words, verbatim. A string where the
+   * declaration holds one; absent where it holds none. Never parsed, never
+   * converted, never guessed — see the note in `./mapping.ts`.
+   */
+  size?: string;
+}
+
+/** One edge, flattened from `IREdge` to the two fields an engine reads. */
+export interface EngineEdge {
+  from: string;
+  to: string;
+  /** The referring attribute, where the edge came from a declared reference. */
+  via?: string;
+  /** The referenced attribute on the far end. */
+  toAttr?: string;
+}
+
+/** One entity the caller asked about that is not on the wire, and why. */
+export interface WithheldEntity {
+  name: string;
+  entityType: string;
+  /** The provider's own type, for a terraform block. See {@link EngineNode.resourceType}. */
+  resourceType?: string;
+  /**
+   * Which of the coverage table's three not-sent verdicts this is:
+   * `declared-unmapped` (looked at, and it carries no rate),
+   * `provider-not-modelled` (a substrate a lexicon states it does not cover), or
+   * `unknown-type` (a modelled provider's type with no row — the only one that
+   * is a defect). See `./mapping.ts` for why they are not one.
+   */
+  status: "declared-unmapped" | "provider-not-modelled" | "unknown-type";
+  detail: string;
+}
+
+/** What goes on the wire. */
+export interface EngineRequest {
+  request: typeof BEHAVIOUR_REQUEST_VERSION;
+  /** The level to predict at, verbatim from the caller. chant parses nothing. */
+  traffic: string;
+  /** Present only when the caller named one; the engine's own default is not chant's to pick. */
+  region?: string;
+  nodes: EngineNode[];
+  edges: EngineEdge[];
+  /** The caller's claim about how complete `edges` is, passed through unchanged. */
+  coverage: BehaviourEdgeCoverage;
+  withheld: WithheldEntity[];
+}
+
+/** Read a dotted path out of a declared property bag. Returns `undefined` for any miss. */
+function readPath(props: Record<string, unknown>, path: string): unknown {
+  let cursor: unknown = props;
+  for (const segment of path.split(".")) {
+    if (typeof cursor !== "object" || cursor === null) return undefined;
+    cursor = (cursor as Record<string, unknown>)[segment];
+  }
+  return cursor;
+}
+
+/**
+ * A declared size, as a string, or absent.
+ *
+ * `sizeType` says which type the row's property holds, and a value of the
+ * other type is **absent** rather than coerced. Without that, a
+ * `DBInstanceClass: 42` — a wrong-typed declaration, or a parameter that
+ * folded to a number — rendered as `"42"` and went to the engine to be matched
+ * against a price table of instance-class names it does not appear in. That is
+ * the outcome the paragraph below is written against, arriving through the
+ * door the paragraph left open.
+ *
+ * Anything else — an object, an array, an unresolved intrinsic, a `NaN` — is
+ * absent too, because a size an engine cannot read is worse than no size: it
+ * will either be ignored silently or matched against nothing.
+ *
+ * A terraform block's unresolved reference is a string, `"${var.size}"`, and
+ * is absent for the same reason a CloudFormation intrinsic object is: it is
+ * the name of a value, not the value (#2360).
+ */
+export function sizeOf(
+  props: Record<string, unknown>,
+  sizeProp: string | undefined,
+  sizeType?: "string" | "number",
+): string | undefined {
+  if (!sizeProp) return undefined;
+  const raw = readPath(props, sizeProp);
+  if (sizeType === "number") {
+    return typeof raw === "number" && Number.isFinite(raw) ? String(raw) : undefined;
+  }
+  // `string`, and the default for a row naming a property and no type.
+  return isLiteral(raw) ? raw : undefined;
+}
+
+/** A non-empty string that is a value rather than a terraform `${…}` reference to one. */
+function isLiteral(raw: unknown): raw is string {
+  return typeof raw === "string" && raw.length > 0 && !raw.includes("${");
+}
+
+/**
+ * Translate one request's worth of chant entities and edges into the engine's
+ * shape. Pure, and the same input gives the same output forever.
+ *
+ * Every name in `entityNames` comes out in exactly one of `nodes` or
+ * `withheld`. The caller in `./predict-behaviour.ts` depends on that to satisfy
+ * `behaviourReport`'s totality check, and a name the caller asked about that is
+ * missing from `options.entities` is `withheld` with an `unknown-type` detail
+ * rather than dropped — a `continue` in this loop is the exact silent hole the
+ * contract's totality refusal exists to catch.
+ */
+export function buildEngineRequest(
+  options: Pick<
+    PredictBehaviourOptions,
+    "entityNames" | "entities" | "edges" | "edgeCoverage" | "traffic" | "region"
+  >,
+  kinds: readonly BehaviourKinds[],
+): EngineRequest {
+  const nodes: EngineNode[] = [];
+  const withheld: WithheldEntity[] = [];
+
+  for (const name of [...options.entityNames].sort(byCodeUnit)) {
+    const declared = options.entities.get(name);
+    if (!declared) {
+      withheld.push({
+        name,
+        entityType: "(undeclared)",
+        status: "unknown-type",
+        detail:
+          `${name} was named in entityNames and is not in the entities map, so this lexicon has ` +
+          "nothing to translate. It is reported rather than dropped: an entity that vanished " +
+          "between the build and the request is a defect in the caller, and a silent omission " +
+          "hides it behind an estate that looks smaller.",
+      });
+      continue;
+    }
+    const verdict = coverageFor(kinds, declared.entityType, declared.props);
+    // Where a lexicon keys its rows on something other than the entity type,
+    // that key rides beside the entity type on the wire and in the withheld
+    // list: `Terraform::Resource` alone names nothing an engine or a reader
+    // can act on (#2360), and its provider type is what does. Asked of the
+    // owning contributor rather than special-cased here (#2382).
+    const owner = ownerOf(kinds, declared.entityType);
+    const resolved = owner?.resolveType?.(declared.entityType, declared.props);
+    const resourceType = resolved && resolved !== declared.entityType ? resolved : undefined;
+    if (verdict.status !== "mapped") {
+      withheld.push({
+        name,
+        entityType: declared.entityType,
+        ...(resourceType ? { resourceType } : {}),
+        status: verdict.status,
+        detail: unmappedDetail(
+          coverageLabel(kinds, declared.entityType, declared.props),
+          verdict,
+          owner,
+        ),
+      });
+      continue;
+    }
+    const { mapping } = verdict;
+    const declaredRegion = mapping.regionProp
+      ? readPath(declared.props, mapping.regionProp)
+      : undefined;
+    const region = isLiteral(declaredRegion) ? declaredRegion : options.region;
+    const size = sizeOf(declared.props, mapping.sizeProp, mapping.sizeType);
+    nodes.push({
+      name,
+      entityType: declared.entityType,
+      ...(resourceType ? { resourceType } : {}),
+      kind: mapping.kind,
+      provider: mapping.provider,
+      ...(region ? { region } : {}),
+      ...(size ? { size } : {}),
+    });
+  }
+
+  const edges: EngineEdge[] = options.edges
+    .map((edge: IREdge) => ({
+      from: edge.from,
+      to: edge.to,
+      ...(edge.viaAttr ? { via: edge.viaAttr } : {}),
+      ...(edge.toAttr ? { toAttr: edge.toAttr } : {}),
+    }))
+    // By code unit, like the node order above. `localeCompare` reads the
+    // ambient locale, so two machines with different `LANG` values produced
+    // two different byte streams from one estate — in a module whose whole
+    // claim is that its bytes are a function of its content and nothing else.
+    .sort(
+      (a, b) =>
+        byCodeUnit(a.from, b.from) ||
+        byCodeUnit(a.to, b.to) ||
+        byCodeUnit(a.via ?? "", b.via ?? "") ||
+        byCodeUnit(a.toAttr ?? "", b.toAttr ?? ""),
+    );
+
+  return {
+    request: BEHAVIOUR_REQUEST_VERSION,
+    traffic: options.traffic,
+    ...(options.region ? { region: options.region } : {}),
+    nodes,
+    edges,
+    coverage: options.edgeCoverage,
+    withheld,
+  };
+}
+
+/**
+ * Canonical JSON: object keys sorted, arrays in the order they were built,
+ * two-space indent, one trailing newline.
+ *
+ * Key order is where a "deterministic" serializer usually is not. `JSON.stringify`
+ * preserves insertion order, and insertion order here follows the order a
+ * property bag was assembled in, which follows discovery order, which follows
+ * the filesystem. Sorting the keys makes the bytes a function of the content
+ * and nothing else — which is what `chant build`'s own reproducibility claim
+ * means, and what makes a re-run comparable rather than merely re-run.
+ */
+export function renderEngineRequest(request: EngineRequest): string {
+  return `${JSON.stringify(canonical(request), null, 2)}\n`;
+}
+
+function canonical(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(canonical);
+  if (typeof value === "object" && value !== null) {
+    const out: Record<string, unknown> = {};
+    for (const key of Object.keys(value as Record<string, unknown>).sort()) {
+      const inner = (value as Record<string, unknown>)[key];
+      if (inner === undefined) continue;
+      out[key] = canonical(inner);
+    }
+    return out;
+  }
+  return value;
+}

package/src/behaviour.ts

@@ -146,8 +146,8 @@
  * ## The transport is part of the contract (#2373, decided in #2359)
  *
  * The first version of this module named the address chain, said the address
- * may be a URL, a socket path or a command on `PATH`, and stopped. augur
- * (#2357) then declared a private `BehaviourEngine` and its own mapping from
+ * may be a URL, a socket path or a command on `PATH`, and stopped. The first
+ * consumer (#2357) then declared a private `BehaviourEngine` and its own mapping from
  * what the wire said to which of the three engine-answered refusals to build.
  * With a second implementation to generalise from, the seam is here:
  * {@link BehaviourTransport} is one method, `send(body)`, taking the request
@@ -173,7 +173,7 @@
  *     is that switch, written once.
  *
  * What the wire says maps to the causes above as follows, and
- * `./behaviour-http.ts` (the first adapter) and augur's command transport both
+ * `./behaviour-http.ts` (the first adapter) and `./behaviour-engine.ts`'s command transport both
  * hold to it: an HTTP 402 is `engine-out-of-credit`; a 429 is
  * `engine-over-quota`; a connection refused, a timeout, a 5xx, a redirect, or
  * an answer that is not JSON is `engine-unreachable`; an unset address is
@@ -1256,7 +1256,7 @@ export function overQuotaBehaviourEngineRefusal(
  * refusal ready to be returned from `predictBehaviour` as it stands.
  *
  * The answer is text rather than a parsed object because what the text means
- * is the lexicon's wire version (`augur/v1`), and the lexicon is the one that
+ * is the wire version (`behaviour/v1`), and `./behaviour-engine.ts` is what
  * validates it — an answer that fails that validation is
  * {@link unreachableBehaviourEngineRefusal} with a detail naming the field,
  * built by the lexicon, since the transport has nothing to say about it.
@@ -1268,7 +1268,7 @@ export type BehaviourTransportOutcome =
 /**
  * The seam between a lexicon and whatever answers its request (#2373).
  *
- * One method. `body` is the request as the lexicon rendered it — augur's
+ * One method. `body` is the request as it was rendered —
  * canonical JSON, say — and the transport carries it to the address it was
  * built for and brings back what came out, or a refusal naming why nothing
  * did. A transport is built knowing the lexicon and the endpoint, which is
@@ -1276,7 +1276,7 @@ export type BehaviourTransportOutcome =
  * better than returning a cause.
  *
  * Two ship today: `./behaviour-http.ts` dials a URL with a bearer token, and
- * augur's `commandTransport` spawns a command on `PATH` with
+ * `./behaviour-engine.ts`'s `commandTransport` spawns a command on `PATH` with
  * {@link behaviourEngineChildEnvironment}. A lexicon picks one by the shape of
  * the address and does not otherwise know which it got.
  */
@@ -1323,7 +1323,7 @@ export function behaviourWireRefusal(
  * and the child holds `AWS_SECRET_ACCESS_KEY` anyway. So a transport that
  * spawns builds the environment from this and nothing more — `PATH` because
  * the address is resolved against it, and no allowlist beyond that, because
- * every name added is a name a credential could be sitting under. augur's
+ * every name added is a name a credential could be sitting under. The
  * command transport pins this by test (#2372); this is the rule it pins.
  */
 export function behaviourEngineChildEnvironment(

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

@@ -450,7 +450,7 @@ describe("runScenarioCheck", () => {
 
   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") }),
+      snap({ resources: { bucket: meta() }, behaviour: noBehaviourEngineRefusal("chant") }),
     );
     const scenario = Scenario("stays under a dollar an hour", {
       given: snapshot(fixturePath),

package/src/cli/handlers/scenario.ts

@@ -166,7 +166,7 @@ interface GivenResolution {
 
 /**
  * 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
+ * per lexicon: a prediction is over the whole estate (it 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

package/src/index.ts

@@ -64,6 +64,7 @@ export * from "./apply";
 export * from "./deep-observation";
 export * from "./behaviour";
 export * from "./behaviour-http";
+export * from "./behaviour-kinds";
 export * from "./behaviour-delta";
 export * from "./claimed-fields";
 export * from "./fold-provenance";

package/src/lexicon.ts

@@ -24,6 +24,7 @@ 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 { BehaviourKinds } from "./behaviour-kinds";
 import type { DisruptionQuery, DisruptionVerdict } from "./lifecycle/disruption";
 import type { OwnerChainVerdict } from "./owner-chain";
 import type { CommandGroup } from "./cli/command-group";
@@ -1459,6 +1460,25 @@ export interface LexiconPlugin {
    */
   predictBehaviour?(options: PredictBehaviourOptions): Promise<BehaviourResult>;
 
+  /**
+   * What this lexicon's own entity types are, to an engine that prices them
+   * (#2382). Rows, not a capability: core resolves and predicts, and a lexicon
+   * says only what its types mean.
+   *
+   * Optional in the way rows can safely be and a capability cannot. A lexicon
+   * that is not installed declared no entities of its types, so its absent
+   * rows describe an absent part of the estate; whereas a *capability* behind
+   * an optional install leaves a consumer with entities nobody will say
+   * anything about, and no refusal naming why — an outcome
+   * `packages/core/src/behaviour.ts` never defined.
+   *
+   * Three things can be said, and saying none is itself a statement that this
+   * lexicon has not been considered: `mapped` rows price a type, `unmapped`
+   * rows state that a real type carries no rate and why, and `nothingPriced`
+   * says it once for the whole substrate — a CI workflow is not an estate.
+   */
+  behaviourKinds?: BehaviourKinds;
+
   /**
    * Report the live status of one deploy unit by its deployed name. Opt-in.
    *