@intentius/chant 0.66.1 → 0.67.0

package/dist/behaviour-engine.d.ts

@@ -0,0 +1,212 @@
+/**
+ * The seam between core and whatever answers its request (#2357),
+ * on the contract's transport (#2373, decided in #2359).
+ *
+ * `packages/core/src/behaviour.ts` says what a prediction may mean, how an
+ * absent engine must refuse, and — since #2359 — how a request reaches an
+ * engine: a `BehaviourTransport` carries the rendered request and brings back
+ * the engine's text or a finished refusal. This file adds what is core's on
+ * top of that and nothing more: the parse of a `behaviour/v1` answer, a command
+ * transport for an address that is a program on `PATH`, and the chooser that
+ * turns an address into one transport or the other.
+ *
+ * {@link BehaviourEngine} is what `./predict-behaviour.ts` talks to. It is
+ * one level above the transport — request in, parsed answer or refusal out —
+ * so the fixture engine in `__fixtures__` can be one without pretending to be
+ * a wire, and so `predict-behaviour.ts` never sees a byte. {@link
+ * transportEngine} is the only bridge between the two levels.
+ *
+ * ## The two transports
+ *
+ * A **URL** is dialled by core's `httpBehaviourTransport`
+ * (`packages/core/src/behaviour-http.ts`): `POST`, a bearer token from
+ * `CHANT_BEHAVIOUR_TOKEN` → `BEHAVIOUR_TOKEN`,
+ * and the status mapping the contract fixes. Nothing about that is core's,
+ * which is why it does not live here.
+ *
+ * A **command on PATH** is {@link commandTransport}, below: request on stdin,
+ * answer on stdout, no shell — a shell would make the address a
+ * code-execution surface for whatever set the variable. The child gets
+ * `behaviourEngineChildEnvironment()` and nothing else, for the reason given
+ * on that function: the request-side screen cannot see an inherited
+ * `process.env`. An engine that answered and still refused says so on stderr,
+ * and the words it uses pick the cause.
+ *
+ * ## A malformed answer is unreachable, not a report with holes
+ *
+ * Taking the fields that parsed and reporting the rest unpredicted would turn
+ * an engine emitting garbage into an estate that looks partly free — the
+ * failure the refusal arm exists to prevent, one level down. So the parse
+ * refuses whole, with a detail naming the entity and the field.
+ *
+ * With one exception, and it is the same rule the command transport applies
+ * to stderr: an engine that took the request, answered `200`, and wrote
+ * `{"error": "out of credit"}` has refused for a reason a status never
+ * carried. {@link transportEngine} reads that body's words after the parse
+ * has failed and never before, so an answer that priced the estate and
+ * declined one node "rate limit reached for this region" stays the report it
+ * is. Both transports reach the same three causes; only the evidence differs.
+ */
+import type { BehaviourBasis, BehaviourEngineEndpoint, BehaviourRefusalReport, BehaviourTransport, ResilienceVerdict } from "./behaviour.js";
+import type { HttpBehaviourTransportDeps } from "./behaviour-http.js";
+import type { EngineRequest } from "./behaviour-request.js";
+/**
+ * The name a refusal is built under.
+ *
+ * It was the predicting lexicon's name while a lexicon predicted. Core
+ * predicts for the whole project since #2382, so there is no lexicon to scope
+ * the variable chain by: the chain is the chant-wide one, and this is the word
+ * a message uses for the thing that refused.
+ */
+export declare const BEHAVIOUR_SCOPE = "chant";
+/** One entity's figures, as the engine states them. */
+export interface EngineFigure {
+    perHour: number;
+    currency: string;
+    headroom: {
+        cpu?: number;
+        latency?: number;
+    };
+    errorRate: number;
+    resilience: {
+        failure: string;
+        verdict: ResilienceVerdict;
+        note?: string;
+    };
+    rightSize?: {
+        suggestion: string;
+        reason?: string;
+    };
+}
+/** A run the engine answered. */
+export interface EngineAnswer {
+    /** How the engine names itself, its version, and the tolerance it states. */
+    engine: string;
+    version: string;
+    tolerance: string;
+    basis: BehaviourBasis;
+    /** An estate total, when the engine states one of its own. Never chant's sum. */
+    total?: {
+        perHour: number;
+        currency: string;
+    };
+    /** Figures, keyed by the node name the request used. */
+    figures: Record<string, EngineFigure>;
+    /**
+     * Nodes the engine was sent and declined, keyed by name, with its reason.
+     * Separate from an absent key: a node in neither map is a defect, and
+     * `./predict-behaviour.ts` reports it rather than dropping it.
+     */
+    declined?: Record<string, string>;
+}
+/**
+ * What an engine call comes back with: a parsed answer, or a refusal built
+ * by whoever saw the failure — the transport for a wire condition, this file
+ * for an answer that does not parse. `./predict-behaviour.ts` returns the
+ * refusal as it stands and never rebuilds one, which is how the contract's
+ * four causes stay four remedies rather than one lexicon's guess.
+ */
+export type EngineOutcome = {
+    ok: true;
+    answer: EngineAnswer;
+} | {
+    ok: false;
+    refusal: BehaviourRefusalReport;
+};
+/** Whatever answers a request, one level above the wire. The fixture engine is one of these. */
+export interface BehaviourEngine {
+    predict(request: EngineRequest): Promise<EngineOutcome>;
+}
+/**
+ * Resolve an address to an engine, or to `undefined` when nothing here
+ * speaks it. `env` is where a transport that authenticates reads its token
+ * from, and a chooser that has no use for it may ignore it. A caller that
+ * gets `undefined` refuses as `engine-unreachable` naming the address, which
+ * is the honest verdict for an address chant cannot dial.
+ */
+export type EngineConnect = (endpoint: BehaviourEngineEndpoint, env: Record<string, string | undefined>) => BehaviourEngine | undefined;
+/**
+ * A {@link BehaviourEngine} over a contract transport: render the request
+ * canonically, send it, parse what came back. The one bridge between the
+ * transport level and the engine level, so the parse runs on every wire and
+ * no transport gets its own.
+ */
+export declare function transportEngine(transport: BehaviourTransport, endpoint: BehaviourEngineEndpoint): BehaviourEngine;
+/**
+ * A `command on PATH` address, run as a subprocess: the contract's
+ * `BehaviourTransport` for the third kind of address it names.
+ *
+ * The address is split on whitespace into a program and its arguments, which
+ * is the shape `CHANT_BEHAVIOUR_ENGINE="my-engine --model tiny"` produces.
+ * No shell: a shell would make the address a code-execution surface for
+ * whatever set the variable, and every argument the address needs can be
+ * written without one.
+ */
+export declare function commandTransport(endpoint: BehaviourEngineEndpoint): BehaviourTransport;
+/** {@link commandTransport}, bridged to the engine level. */
+export declare function commandEngine(endpoint: BehaviourEngineEndpoint): BehaviourEngine;
+/**
+ * Everything wrong with one figure, as readable field paths. Empty means the
+ * figure is usable.
+ *
+ * Pure and exported so the shapes an engine can get wrong are testable without
+ * a subprocess. Every check here mirrors one `validateBehaviourBlock` applies
+ * downstream (`packages/core/src/behaviour.ts`) — the difference is *when*:
+ * that one throws, and a throw is the whole-lexicon failure `lexicon.ts`
+ * reserves for a live credential. A third party emitting one bad number is not
+ * that, and reporting it as that is how an operator goes looking for a leak.
+ */
+export declare function figureProblems(name: string, figure: unknown): string[];
+/**
+ * What the parse of an engine's text comes to: the answer, or a detail
+ * naming what was wrong with it. Not a refusal yet — {@link transportEngine}
+ * builds that, with the endpoint the parse does not need to know.
+ */
+export type ParsedEngineAnswer = {
+    ok: true;
+    answer: EngineAnswer;
+} | {
+    ok: false;
+    detail: string;
+};
+/**
+ * Parse an engine's text into an {@link EngineAnswer}.
+ *
+ * A malformed answer is `engine-unreachable` and not a report full of holes.
+ * The alternative — taking the fields that parsed and reporting the rest as
+ * unpredicted — would turn an engine emitting garbage into an estate that
+ * looks partially free, which is the failure the refusal arm exists to
+ * prevent, one level down.
+ *
+ * **Every figure is validated here, not only the envelope.** The first version
+ * of this function checked `engine`/`version`/`tolerance`/`basis` and that
+ * `figures` was an object, and then handed each figure's contents straight to
+ * `block()` in `./predict-behaviour.ts`, which dereferenced
+ * `figure.resilience.failure`. Seven malformed shapes were executed against
+ * it and all seven threw: three as bare `TypeError`s with no chant message,
+ * four through `validateBehaviourBlock` after the fact. A throw is the
+ * whole-lexicon failure `lexicon.ts` reserves for a live credential in the
+ * request, so a third-party engine emitting one bad number was indistinguishable
+ * from a leak — and the doc above claimed the opposite was happening.
+ *
+ * The detail names the entity and the field, because "the engine sent
+ * something wrong" is not a thing anybody can act on and "figures.web.headroom
+ * carries neither cpu nor latency" is. It flows into
+ * `unreachableBehaviourEngineRefusal`, which runs it through
+ * `scrubEngineDetail` and bounds it.
+ */
+export declare function parseEngineAnswer(text: string): ParsedEngineAnswer;
+/**
+ * The transport chooser, with what the HTTP transport needs injectable.
+ *
+ * A `http://` or `https://` address gets core's `httpBehaviourTransport`,
+ * with its token read from `env` — the same `env` the address was read from,
+ * so a test drives both chains from one object. A bare address gets
+ * {@link commandTransport}. Any other scheme (`grpc://`, `unix://`) gets
+ * `undefined`, and the caller refuses naming the address: no transport here
+ * speaks it, and saying so beats a guess.
+ */
+export declare function connectWith(deps?: HttpBehaviourTransportDeps): EngineConnect;
+/** The chooser the shipped plugin uses: the process's own `fetch`, the default deadline. */
+export declare const defaultConnect: EngineConnect;
+//# sourceMappingURL=behaviour-engine.d.ts.map

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

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

package/dist/behaviour-http.d.ts

@@ -68,7 +68,7 @@ export interface HttpBehaviourTransportDeps {
     /** How long the engine has before it is treated as unreachable. */
     timeoutMs?: number;
 }
-/** The default deadline: the same one augur's command transport gives a child. */
+/** The default deadline: the same one the command transport gives a child. */
 export declare const HTTP_BEHAVIOUR_TIMEOUT_MS = 30000;
 /** True when an address is one this adapter dials. `grpc://` and friends are not. */
 export declare function isHttpBehaviourAddress(value: string): boolean;

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

@@ -1 +1 @@
-{"version":3,"file":"behaviour-http.d.ts","sourceRoot":"","sources":["../src/behaviour-http.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AAEH,OAAO,EAKL,KAAK,uBAAuB,EAC5B,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,EAC3B,KAAK,kBAAkB,EAExB,MAAM,aAAa,CAAC;AAGrB,sFAAsF;AACtF,MAAM,WAAW,0BAA0B;IACzC,oFAAoF;IACpF,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB,mEAAmE;IACnE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,kFAAkF;AAClF,eAAO,MAAM,yBAAyB,QAAS,CAAC;AAKhD,qFAAqF;AACrF,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE7D;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,oBAAoB,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAG5E;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,uBAAuB,EACjC,KAAK,EAAE,oBAAoB,EAC3B,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,UAAU,CAAC,EAAE,MAAM,GAClB,sBAAsB,GAAG,SAAS,CAgCpC;AAQD;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,uBAAuB,EACjC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,EACvC,IAAI,GAAE,0BAA+B,GACpC,kBAAkB,CAoDpB"}
+{"version":3,"file":"behaviour-http.d.ts","sourceRoot":"","sources":["../src/behaviour-http.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AAEH,OAAO,EAKL,KAAK,uBAAuB,EAC5B,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,EAC3B,KAAK,kBAAkB,EAExB,MAAM,aAAa,CAAC;AAGrB,sFAAsF;AACtF,MAAM,WAAW,0BAA0B;IACzC,oFAAoF;IACpF,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB,mEAAmE;IACnE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,8EAA8E;AAC9E,eAAO,MAAM,yBAAyB,QAAS,CAAC;AAKhD,qFAAqF;AACrF,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE7D;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,oBAAoB,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAG5E;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,uBAAuB,EACjC,KAAK,EAAE,oBAAoB,EAC3B,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,UAAU,CAAC,EAAE,MAAM,GAClB,sBAAsB,GAAG,SAAS,CAgCpC;AAQD;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,uBAAuB,EACjC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,EACvC,IAAI,GAAE,0BAA+B,GACpC,kBAAkB,CAoDpB"}

package/dist/behaviour-kinds.d.ts

@@ -0,0 +1,220 @@
+/**
+ * What an engine is asked to price, and who gets to say so (#2382).
+ *
+ * `./behaviour.ts` says what a prediction may mean and `./behaviour-http.ts`
+ * carries one to an engine. Between them sits a question neither answers: for
+ * a given entity in a project's graph, what *kind* of thing is it, and is it
+ * something an engine prices at all? #2357 answered it with one table in one
+ * lexicon, keyed by every other lexicon's entity types. That table described
+ * 117 types it did not own, and the capability rode on whether an optional
+ * package happened to be installed — which gave a consumer a fourth
+ * outcome this contract never named: no overlay, no refusal, and no reason.
+ *
+ * So the resolution lives here, where every other part of the feature already
+ * does, and the *rows* are contributed by the lexicon that owns the substrate.
+ * Core learns that an entity has an engine kind. It never learns which.
+ *
+ * ## Why rows are safe to make optional when the capability is not
+ *
+ * A lexicon that is not installed declared no entities of its types, so it has
+ * no rows to contribute and nothing goes missing: the estate simply contains
+ * nothing of that substrate. That is the opposite of the capability itself
+ * being optional, where an uninstalled package means an estate full of
+ * entities nobody will say anything about.
+ *
+ * ## The three things a lexicon can say about its own types
+ *
+ *   - **mapped** — this type is a `compute`/`database`/`queue`, and its size
+ *     is read from this declared property, in the provider's own vocabulary.
+ *   - **declared unmapped** — this type is real and carries no rate an engine
+ *     can quote, with the sentence saying why. A grant is not a resource; a
+ *     boundary is not a node; a meter chant cannot read is not a figure.
+ *   - **nothing priced** — nothing this lexicon declares is an estate an
+ *     engine prices, once, for the whole substrate. A CI workflow is not an
+ *     estate, and a policy language has nothing to saturate.
+ *
+ * A type a contributor claims and has no row for is `unknown-type`: the one
+ * verdict that is a defect rather than a decision, and the reason the three
+ * above are distinct states instead of one absent row.
+ */
+/**
+ * The categories a cost-and-saturation model actually distinguishes, not a
+ * taxonomy of every product a cloud sells.
+ *
+ * A kind is here when an engine would price it differently or when its
+ * saturation axis differs. `cache` is separate from `database` because a cache
+ * saturates on memory and a database on IO; `serverless` is separate from
+ * `compute` because one is priced per invocation and the other per hour of
+ * existence, and this contract's output shape is per hour. `control-plane` is
+ * separate from everything because a managed control plane is a flat hourly
+ * fee that does not move with the estate's traffic at all — pricing one as
+ * `compute` would make it look like something a right-size suggestion could
+ * shrink.
+ */
+export type EngineKind = "compute" | "serverless" | "control-plane" | "database" | "cache" | "queue" | "object-store" | "block-store" | "load-balancer" | "cdn";
+/**
+ * Every legal {@link EngineKind}, derived from a total witness rather than
+ * written out by hand — the construction `behaviour.ts` uses for
+ * `BEHAVIOUR_BASES`, for the same reason: a hand-written array is checked for
+ * having legal members and never for having all of them.
+ */
+export declare const ENGINE_KINDS: readonly EngineKind[];
+/** True when `value` is a legal {@link EngineKind}. */
+export declare function isEngineKind(value: unknown): value is EngineKind;
+/** One row of a lexicon's coverage: what one of its entity types becomes on the wire. */
+export interface EngineKindMapping {
+    /** The engine-side kind. */
+    kind: EngineKind;
+    /**
+     * The substrate, as the engine names it — `aws`, `kubernetes`. A plain
+     * string rather than a closed union: the contributing lexicon names its own
+     * substrate, and core adding a member here for every lexicon that ships
+     * would be core holding the list it exists to stop holding.
+     */
+    provider: string;
+    /**
+     * The declared property whose value is the entity's size, in the provider's
+     * own vocabulary — `InstanceType`, not a parsed vCPU count. Absent where the
+     * type has no size a single `size` string can carry.
+     */
+    sizeProp?: string;
+    /**
+     * Which type {@link sizeProp} holds. A value of the other type is absent
+     * rather than coerced: a number rendered into a size field an engine matches
+     * against a price table of strings is worse than no size at all.
+     */
+    sizeType?: "string" | "number";
+    /**
+     * The declared property naming the region or zone this entity sits in, where
+     * the type states one of its own. Most do not, and inherit the caller's.
+     */
+    regionProp?: string;
+}
+/**
+ * One lexicon's answer for its own entity types, contributed through the
+ * plugin's `behaviourKinds` field.
+ *
+ * Every field except {@link prefixes} is optional, and a lexicon that supplies
+ * only {@link nothingPriced} has said something complete: that none of what it
+ * declares is an estate an engine prices.
+ */
+export interface BehaviourKinds {
+    /** The substrate, as the engine names it. Every mapped row inherits it. */
+    provider: string;
+    /**
+     * The entity-type prefixes this lexicon owns — `["AWS::"]`, `["K8s::"]`.
+     * Ownership is what makes a missing row a defect rather than silence: a type
+     * nobody claims is nobody's mistake, and a type its own lexicon claims and
+     * cannot classify is a row somebody forgot to write.
+     */
+    prefixes: readonly string[];
+    /** Types this lexicon prices, keyed by entity type — or by resolved type where {@link resolveType} is given. */
+    mapped?: Readonly<Record<string, Omit<EngineKindMapping, "provider"> & {
+        provider?: string;
+    }>>;
+    /** Types that are real and carry no rate, keyed the same way, with the sentence saying why. */
+    unmapped?: Readonly<Record<string, string>>;
+    /**
+     * Nothing this lexicon declares is priced, and this says why — checked
+     * before the tables, so a lexicon that states it needs no rows at all.
+     */
+    nothingPriced?: string;
+    /**
+     * For a lexicon whose entities do not key rows by their entity type, the
+     * key to look rows up on instead. terraform's every `resource` block arrives
+     * as `Terraform::Resource`, and what an engine would price is the type its
+     * address carries.
+     *
+     * It is handed the entity type as well as the props, because a lexicon
+     * usually redirects only *some* of its types: terraform's root blocks
+     * (`Terraform::Variable`, `Terraform::Output`) key by entity type like
+     * everyone else, and only `Terraform::Resource` reads its key out of the
+     * props. Returning the entity type unchanged is how a contributor says "this
+     * one is ordinary". Returning `undefined` is "nothing to look up", the same
+     * no-opinion an unseen type gets.
+     */
+    resolveType?: (entityType: string, props: Record<string, unknown> | undefined) => string | undefined;
+    /**
+     * A family of this lexicon's types that belongs to a substrate nothing here
+     * models, named as the substrate — or `undefined` to let the type carry on
+     * to {@link unmappedWhen}. terraform is the case this exists for: one
+     * lexicon's `resource` blocks span every provider there is, so `google_`
+     * and `azurerm_` and `null_` are each a boundary of their own, while an
+     * `aws_` type with no row stays the defect it is. A contributor whose whole
+     * substrate is unpriced uses {@link nothingPriced} instead; this is for the
+     * lexicon that models part of what it declares.
+     */
+    notModelledWhen?: (type: string) => string | undefined;
+    /**
+     * A last word on a type this lexicon claims and has no row for: the reason
+     * it is unmapped, or `undefined` to leave it a defect. CloudFormation's
+     * property types are the case this exists for — hundreds of nested blocks
+     * that became entities of their own, never separately priced, and
+     * enumerating them one row at a time would bury the table's real decisions.
+     */
+    unmappedWhen?: (type: string) => string | undefined;
+}
+/** What one entity type resolves to. Total: every type reaches exactly one of these. */
+export type CoverageVerdict = {
+    status: "mapped";
+    mapping: EngineKindMapping;
+} | {
+    status: "declared-unmapped";
+    reason: string;
+} | {
+    status: "provider-not-modelled";
+    substrate: string;
+} | {
+    status: "unknown-type";
+};
+/**
+ * Resolve one entity type against the contributed rows.
+ *
+ * Total by construction: every type reaches one of the four states and there
+ * is no fifth arm for "dropped". That is the property the request builder
+ * relies on to guarantee every entity it was asked about lands in `entities`
+ * or in `unpredicted`.
+ *
+ * `hasOwnProperty` rather than a truthiness check, because these are plain
+ * object literals and an entity named after a prototype member would otherwise
+ * resolve to a mapping that does not exist.
+ */
+export declare function coverageFor(contributors: readonly BehaviourKinds[], entityType: string, props?: Record<string, unknown>): CoverageVerdict;
+/**
+ * The contributor that owns an entity type, or `undefined` when nobody claims
+ * it. Exported because a caller that has already resolved a verdict often
+ * needs the owner too — to name it in a detail, or to label the entity the way
+ * its own lexicon would.
+ */
+export declare function ownerOf(contributors: readonly BehaviourKinds[], entityType: string): BehaviourKinds | undefined;
+/**
+ * How a detail names an entity's kind. The chant entity type, except where the
+ * owning lexicon keys its rows on something else: `Terraform::Resource` names
+ * nothing a reader can act on, and the provider type is the kind, so the label
+ * is `aws_vpc (Terraform::Resource)`.
+ */
+export declare function coverageLabel(contributors: readonly BehaviourKinds[], entityType: string, props?: Record<string, unknown>): string;
+/**
+ * The `detail` an `unpredicted` entry carries, naming the kind in every case.
+ *
+ * The kind is named here, in the per-entity decline, because that is the only
+ * place in this contract with a per-entity axis: a `BehaviourRefusalReport` is
+ * a statement about the whole run and has no `entities` key by design, so a
+ * report-level refusal for one unmapped bucket would take the other nineteen
+ * entities' figures down with it.
+ *
+ * The `unknown-type` arm names the lexicon that owns the type rather than a
+ * file path, because since #2382 the row belongs to whichever lexicon defines
+ * the type, and that is the thing a reader needs to be told.
+ */
+export declare function unmappedDetail(label: string, verdict: CoverageVerdict, owner?: BehaviourKinds): string;
+/**
+ * Compare two strings by UTF-16 code unit.
+ *
+ * Not `localeCompare`, which reads the ambient locale: under `sv-SE` and
+ * `et-EE` it orders these type names differently from `en-US`, which would
+ * make the request's bytes — and therefore any golden fixture, and therefore
+ * any declared-versus-live delta — a function of the machine that built them.
+ */
+export declare const byCodeUnit: (a: string, b: string) => number;
+//# sourceMappingURL=behaviour-kinds.d.ts.map

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

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

package/dist/behaviour-predict.d.ts

@@ -0,0 +1,83 @@
+/**
+ * `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 { type BehaviourResult, type PredictBehaviourOptions } from "./behaviour.js";
+import type { BehaviourKinds } from "./behaviour-kinds.js";
+import { BEHAVIOUR_SCOPE, type EngineConnect } from "./behaviour-engine.js";
+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 declare function createBehaviourPredict(deps?: BehaviourPredictDeps): (options: PredictBehaviourOptions) => Promise<BehaviourResult>;
+//# sourceMappingURL=behaviour-predict.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"behaviour-predict.d.ts","sourceRoot":"","sources":["../src/behaviour-predict.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,OAAO,EAOL,KAAK,eAAe,EACpB,KAAK,uBAAuB,EAG7B,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,eAAe,EAAkB,KAAK,aAAa,EAAqB,MAAM,oBAAoB,CAAC;AAE5G,OAAO,EAAE,eAAe,EAAE,CAAC;AAE3B,4FAA4F;AAC5F,MAAM,WAAW,oBAAoB;IACnC;;;;;;;;;OASG;IACH,KAAK,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;IAClC,sFAAsF;IACtF,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzC;;;;OAIG;IACH,OAAO,CAAC,EAAE,aAAa,CAAC;CACzB;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,GAAE,oBAAyB,GAC9B,CAAC,OAAO,EAAE,uBAAuB,KAAK,OAAO,CAAC,eAAe,CAAC,CA0FhE"}