@intentius/chant 0.64.0 → 0.66.0

package/dist/behaviour-delta.d.ts

@@ -0,0 +1,181 @@
+/**
+ * The predicted delta between two behaviour results, and how it is shown
+ * (#2358, contract #2356).
+ *
+ * `behaviour.ts` ships the invariant and deliberately not the presentation:
+ * {@link compareFigures} says on which axes two figures fail to be a delta of
+ * like things, and binds every consumer to mark such a pair wherever it is
+ * shown. This module is the consumer. It takes the base side and the head
+ * side of a pull request as two {@link BehaviourResult}s and produces one
+ * finding, under four rules that are the contract's and #2358's rather than
+ * this file's:
+ *
+ *  1. A whole-run refusal on either side is a finding that says **no
+ *     prediction**, with the refusal's own text and remedy. Never a delta and
+ *     never a partial one: the five refusal causes are the engine being
+ *     absent, unreachable, out of credit, over quota, or a credential in the
+ *     request, and none of them is a statement about the estate.
+ *  2. A delta is computed only over entities predicted on **both** sides. An
+ *     entity declined on either side — `unpredicted`, whatever the reason —
+ *     is a row in the finding saying so, not an absent row and not a zero. An
+ *     estate that gained an unmapped kind between the two runs did not gain a
+ *     cost, and a finding that read it as one would be the faked number the
+ *     epic forbids.
+ *  3. Before any two figures are differenced, {@link compareFigures} runs. A
+ *     non-empty mismatch set means the pair is **marked** with every label in
+ *     it, in {@link FIGURE_MISMATCHES}' display order, and no number is
+ *     subtracted. `modeled` minus `validated` is not a change in the estate.
+ *  4. Every figure shown carries its provenance — engine, version, tolerance,
+ *     basis — and a rate is rendered as a rate: so much per hour, at the
+ *     stated traffic level, never an amount.
+ *
+ * Resilience has a fifth rule, from #2360's third comment: a verdict is
+ * computed over the graph the engine was handed, and the declared path hands
+ * over reference edges with no containment. When either side's
+ * `meta.edgeCoverage` is `partial` or `unknown`, the two verdicts were reached
+ * over graphs of different completeness, and the finding shows each side's
+ * verdict and says why they are not compared rather than drawing an arrow
+ * between them.
+ *
+ * Pure: no I/O, no clock, no environment. The Op activity that posts the
+ * result (`./op/activities/predict-behaviour.ts`) is where the sides come
+ * from.
+ */
+import { type BehaviourProvenance, type BehaviourRefusal, type BehaviourReportMeta, type BehaviourResult, type FigureMismatch, type PredictedBehaviour, type PredictedRate, type UnpredictedEntity } from "./behaviour.js";
+/**
+ * Hold a {@link BehaviourResult} to the contract, on arrival.
+ *
+ * `behaviourReport` checks a report as the ordinary route builds it, and its
+ * own doc says plainly that this is a check and not a proof: the report type
+ * is a plain interface, `isBehaviourResult` accepts a hand-built one, and a
+ * lexicon calling the builder with `entityNames: Object.keys(entities)`
+ * self-certifies. A consumer that needs the guarantee runs this instead, with
+ * the names it asked about, and the two consumers that need it are the delta
+ * (each side arrives from a plugin) and a scenario's fixture (the block
+ * arrives from JSON on disk).
+ *
+ * Throws, naming what is wrong. The refusals are the builder's, applied to a
+ * result rather than to its parts: an entity in neither map or in both, a
+ * figure for a name nobody asked about, a block priced at a level the run did
+ * not ask for, an unpredicted reason outside the closed set, an edge-coverage
+ * claim that names no gap, and any block failing `validateBehaviourBlock`. A
+ * refusal arm is held to having a legal cause and a non-empty reason and
+ * remedy, since those two strings are what a consumer prints.
+ */
+export declare function validateBehaviourResult(result: unknown, askedFor: readonly string[]): BehaviourResult;
+/** One side of the delta: the result, and what to call it in the finding. */
+export interface BehaviourDeltaSide {
+    /** `base` or `head`, or whatever the caller calls the two sides. */
+    label: string;
+    /** What the side was predicted from — a branch, a ref, a pull request. Free text. */
+    ref?: string;
+    result: BehaviourResult;
+}
+/** Why a row carries no plain difference. */
+export type BehaviourDeltaRowKind = 
+/** Predicted on both sides and comparable: `deltaPerHour` is a difference in the estate. */
+"comparable"
+/** Predicted on both sides and not a delta of like things: `mismatches` says on which axes. */
+ | "marked"
+/** Declined on one side or both: `baseDeclined`/`headDeclined` say why. */
+ | "declined"
+/** Present on the base side only — removed by the change. */
+ | "only-base"
+/** Present on the head side only — added by the change. */
+ | "only-head";
+/** One entity's row in the finding. */
+export interface BehaviourDeltaRow {
+    name: string;
+    /** Declared entity type, when either side knows it. */
+    type?: string;
+    kind: BehaviourDeltaRowKind;
+    base?: PredictedBehaviour;
+    head?: PredictedBehaviour;
+    baseDeclined?: UnpredictedEntity;
+    headDeclined?: UnpredictedEntity;
+    /** Every axis the pair disagrees on, in display order. Non-empty exactly when `kind` is `marked`. */
+    mismatches?: FigureMismatch[];
+    /** `head.cost.perHour - base.cost.perHour`, present exactly when `kind` is `comparable`. */
+    deltaPerHour?: number;
+    /** The currency both comparable figures share. */
+    currency?: string;
+}
+/** chant's own sum of the comparable rows' deltas, per currency, labelled as such wherever it is shown. */
+export interface ComparableDeltaSum {
+    currency: string;
+    perHour: number;
+    /** How many comparable pairs the sum is over. */
+    pairs: number;
+}
+/** A finding with figures on both sides. */
+export interface BehaviourDeltaReport {
+    kind: "delta";
+    base: {
+        label: string;
+        ref?: string;
+        meta: BehaviourReportMeta;
+    };
+    head: {
+        label: string;
+        ref?: string;
+        meta: BehaviourReportMeta;
+    };
+    /** Every entity either side named, one row each, sorted by name. */
+    rows: BehaviourDeltaRow[];
+    /** The comparable rows' deltas summed by chant, per currency. Empty when no row is comparable. */
+    sums: ComparableDeltaSum[];
+    /**
+     * Whether the two sides' resilience verdicts were reached over graphs of the
+     * same completeness — both `meta.edgeCoverage.verdict === "complete"`. When
+     * false the finding shows each verdict and does not compare them.
+     */
+    resilienceComparable: boolean;
+}
+/** A finding with no figures, because one side or both refused. */
+export interface BehaviourDeltaRefused {
+    kind: "no-prediction";
+    base: {
+        label: string;
+        ref?: string;
+        refusal?: BehaviourRefusal;
+    };
+    head: {
+        label: string;
+        ref?: string;
+        refusal?: BehaviourRefusal;
+    };
+}
+export type BehaviourDelta = BehaviourDeltaReport | BehaviourDeltaRefused;
+/**
+ * Compute the delta. Pure, and never subtracts two figures it has not first
+ * put through {@link compareFigures}.
+ */
+export declare function behaviourDelta(base: BehaviourDeltaSide, head: BehaviourDeltaSide): BehaviourDelta;
+/** What the rendered finding is about — the words in its heading. */
+export interface BehaviourFindingContext {
+    /** The environment the prediction is for. */
+    env: string;
+    /** The Op that produced it, named in the heading so two Ops' findings read apart. */
+    op: string;
+}
+/**
+ * Four significant fractional digits at most, trailing zeros dropped. A rate
+ * of `0.272` renders as `0.272`, of `3` as `3`, and of `0.00230000001` as
+ * `0.0023`. No locale: the finding is the same bytes on every runner.
+ */
+export declare function formatPerHour(n: number): string;
+/** A rate as a rate: `0.272 USD/hour`, never an amount. */
+export declare function renderRate(rate: PredictedRate): string;
+/** `acme-sim 1.4.2 · ±15% · modeled` — the four provenance fields, always together. */
+export declare function renderProvenance(p: BehaviourProvenance): string;
+/**
+ * The finding as Markdown, for a pull-request comment or a merge-request
+ * note. Deterministic for a given delta.
+ *
+ * The first paragraph says what the numbers are, before any of them appear:
+ * a modeled rate for one hypothetical hour, at the level the run was asked
+ * for, from a named engine at a stated tolerance. The paragraph is not
+ * decoration; it is rule 1 of the contract applied to prose.
+ */
+export declare function renderBehaviourFinding(delta: BehaviourDelta, ctx: BehaviourFindingContext): string;
+//# sourceMappingURL=behaviour-delta.d.ts.map

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

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

package/dist/behaviour-http.d.ts

@@ -0,0 +1,106 @@
+/**
+ * The first engine adapter (#2359): a {@link BehaviourTransport} that dials a
+ * URL with a bearer token, and maps what the wire says onto the contract's
+ * refusals.
+ *
+ * Unnamed on purpose. Nothing here is a vendor's API; it is the shape any
+ * metered HTTP engine has — an address, an account, a request body, and four
+ * ways the account or the wire can say no — so a second engine behind the
+ * same shape is a second address and a second token, not a second adapter.
+ * What this file knows about the engine is that it accepts a JSON body by
+ * `POST`, answers with a JSON body, and uses the HTTP status the way HTTP
+ * says to: `402` for an account with nothing left on it, `429` for a limit
+ * that is spent, `401`/`403` for a token it does not accept.
+ *
+ * ## The token is on the wire and nowhere else
+ *
+ * Rule 3 of the contract — the engine is never handed a credential — is about
+ * the request body, and `screenBehaviourRequest` has already walked the body
+ * by the time a transport exists. The bearer token here is a different thing:
+ * it is how the engine knows whose account to bill, it travels in the
+ * `authorization` header, and this module is the only code that holds its
+ * value. Four things follow, and each has a test:
+ *
+ *   - it is resolved from {@link behaviourTokenFrom}'s chain, never from the
+ *     address chain, so no message that prints the address can print it;
+ *   - it is never interpolated into a refusal, a `detail`, or an error — the
+ *     variable's *name* is what a refusal carries;
+ *   - whatever the engine writes back is passed through {@link concealing}
+ *     before it becomes a `detail`, because an engine that echoes its request
+ *     headers into an error page would otherwise put the token in a
+ *     merge-request comment (#2358 posts refusals publicly);
+ *   - the request is sent with `redirect: "error"`, so a `3xx` from the
+ *     address named is a refusal rather than a second request carrying the
+ *     header to whatever host the redirect names.
+ *
+ * ## No token, nothing sent
+ *
+ * This adapter is for an engine that bills an account: `engine-out-of-credit`
+ * and `engine-over-quota` are statements about an account, and an engine
+ * with no account has neither. So a token is required, and a missing one is
+ * refused before anything is sent — {@link noBehaviourTokenRefusal}, naming
+ * the chain — rather than sent bare and reported as whatever the engine's
+ * 401 page said. An engine that needs no token is not this adapter's, and
+ * the address chain still reaches it through a command on `PATH`.
+ *
+ * ## What the wire says, and what it becomes
+ *
+ * | Wire | Cause | Why |
+ * |---|---|---|
+ * | `2xx` | — | the body is the answer; the lexicon validates it |
+ * | `401`, `403` | `no-engine` | the token was rejected; the remedy is to set the variable |
+ * | `402` | `engine-out-of-credit` | the address answered; the account is empty |
+ * | `429` | `engine-over-quota` | the address answered; a limit is spent; `retry-after` is echoed |
+ * | any other status | `engine-unreachable` | the engine did not answer the question — a `5xx`, a `404`, a `3xx` |
+ * | `fetch` threw | `engine-unreachable` | connection refused, no such host, TLS, or the timeout |
+ *
+ * `4xx` outside the three named is deliberately `engine-unreachable` rather
+ * than a fifth cause. The contract's four causes are four remedies, and "the
+ * engine rejected this request as malformed" has no remedy an operator can
+ * apply — it is a bug on one side of the wire or the other, and the detail
+ * names the status so whoever reads it can tell which side.
+ */
+import { type BehaviourEngineEndpoint, type BehaviourEngineToken, type BehaviourRefusalReport, type BehaviourTransport } from "./behaviour.js";
+/** What {@link httpBehaviourTransport} can be handed instead of the process's own. */
+export interface HttpBehaviourTransportDeps {
+    /** The `fetch` to send with. Defaults to the global, and a test hands in a fake. */
+    fetch?: typeof fetch;
+    /** 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. */
+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;
+/**
+ * Every occurrence of the token's value replaced, in text that came from the
+ * engine or from an error. Exported so a test can assert on the one function
+ * every `detail` passes through.
+ *
+ * `split`/`join` rather than a `RegExp`, so a token containing `.` or `+` is
+ * matched as itself. Nothing shorter than four characters is concealed: a
+ * one-letter "token" would blank every occurrence of that letter, which is a
+ * detail nobody can read and a false sense that something was protected.
+ */
+export declare function concealing(token: BehaviourEngineToken, text: string): string;
+/**
+ * The refusal an HTTP status earns, or `undefined` for a status that carries
+ * an answer. Pure and exported so the whole table in the module doc is one
+ * function a test can walk.
+ *
+ * `detail` is the first non-empty line of the response body, already
+ * concealed; this adds the status in front of it so a `detail` never reads as
+ * the engine's prose alone.
+ */
+export declare function httpStatusRefusal(lexicon: string, endpoint: BehaviourEngineEndpoint, token: BehaviourEngineToken, status: number, detail: string, retryAfter?: string): BehaviourRefusalReport | undefined;
+/**
+ * Build the transport for one lexicon against one URL.
+ *
+ * The token is resolved here, once, from `env` — never from `process.env`
+ * unless that is what was passed — so a test can drive the whole wire with an
+ * environment of its own. A missing token makes a transport whose every
+ * `send` refuses by name and sends nothing; see the module doc for why that is
+ * the honest shape for an adapter whose engine bills an account.
+ */
+export declare function httpBehaviourTransport(lexicon: string, endpoint: BehaviourEngineEndpoint, env: Record<string, string | undefined>, deps?: HttpBehaviourTransportDeps): BehaviourTransport;
+//# sourceMappingURL=behaviour-http.d.ts.map

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

@@ -0,0 +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"}

package/dist/behaviour-overlay.d.ts

@@ -0,0 +1,61 @@
+/**
+ * A behaviour result, in the shape the overlay carries it (#2360, epic #2355).
+ *
+ * behold reads a prediction off `chant graph --live --overlay`'s IR and never
+ * calls an engine itself: one block per entity on `attrs._behaviour`, the
+ * channel every other live fact rides on (`_status`, `_release`, `_carve`),
+ * and the graph-level half on `meta._behaviour`. Its reader
+ * (`behold/src/behaviour.ts`, `validateBehaviourMeta`) takes `meta._behaviour`
+ * as `{ engine?, version?, at?, total?, refusal? }` and short-circuits on
+ * `refusal`: a refusal is present *instead of* the engine, and a meta with
+ * neither is dropped as "meta.engine missing".
+ *
+ * That last sentence is the whole reason this module exists. What goes on
+ * `meta._behaviour` for a refusal is the **entire** {@link BehaviourRefusalReport}
+ * — `{ behaviour: "v1", refusal: { cause, reason, remedy, source? } }` — and
+ * not the bare {@link BehaviourRefusal} inside it. A bare refusal has `reason`
+ * and `remedy` at its top level and no `refusal` key, so behold's reader finds
+ * no refusal, then finds no engine, and drops the meta with a diagnostic that
+ * names the wrong thing. The contract doc said the wrong type once
+ * (#2360's second review comment); this is written against the reader.
+ *
+ * For a report, `meta._behaviour` is the report's own `meta`: engine, version,
+ * `at`, an optional `total`, and `edgeCoverage`, which behold's reader ignores
+ * and a consumer that wants to know what a resilience verdict was computed
+ * over reads. Each entity's block goes on its node verbatim — the contract's
+ * {@link PredictedBehaviour} is field for field the block behold validates.
+ *
+ * Pure. Nothing here calls an engine; the result is whatever a lexicon's
+ * `predictBehaviour` returned.
+ */
+import { type BehaviourRefusalReport, type BehaviourReportMeta, type BehaviourResult, type PredictedBehaviour } from "./behaviour.js";
+/** The attribute a behaviour block rides on, on a node and on the graph's meta. */
+export declare const BEHAVIOUR_OVERLAY_ATTR = "_behaviour";
+/** What `meta._behaviour` holds: the report's meta, or the whole refusal report. */
+export type BehaviourOverlayMeta = BehaviourReportMeta | BehaviourRefusalReport;
+/** A behaviour result projected onto the overlay's two channels. */
+export interface BehaviourOverlay {
+    /** Goes on the IR's `meta`, keyed {@link BEHAVIOUR_OVERLAY_ATTR}. */
+    meta: {
+        [BEHAVIOUR_OVERLAY_ATTR]: BehaviourOverlayMeta;
+    };
+    /**
+     * One entry per priced entity, keyed by entity name: what goes on that
+     * node's `attrs`, keyed {@link BEHAVIOUR_OVERLAY_ATTR}. Empty for a refusal,
+     * because a refusal is present instead of every figure, and empty for an
+     * entity that was `unpredicted` — an unpriced node carries no block rather
+     * than a block full of zeroes.
+     */
+    attrs: Record<string, {
+        [BEHAVIOUR_OVERLAY_ATTR]: PredictedBehaviour;
+    }>;
+}
+/**
+ * Project a result onto the overlay's channels.
+ *
+ * A refusal keeps its envelope. behold reads `meta._behaviour.refusal`, and
+ * the envelope is also what makes the value self-describing to anything else
+ * reading the IR: `behaviour: "v1"` says which contract the refusal is in.
+ */
+export declare function behaviourOverlay(result: BehaviourResult): BehaviourOverlay;
+//# sourceMappingURL=behaviour-overlay.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"behaviour-overlay.d.ts","sourceRoot":"","sources":["../src/behaviour-overlay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,EAEL,KAAK,sBAAsB,EAC3B,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACxB,MAAM,aAAa,CAAC;AAErB,mFAAmF;AACnF,eAAO,MAAM,sBAAsB,eAAe,CAAC;AAEnD,oFAAoF;AACpF,MAAM,MAAM,oBAAoB,GAAG,mBAAmB,GAAG,sBAAsB,CAAC;AAEhF,oEAAoE;AACpE,MAAM,WAAW,gBAAgB;IAC/B,qEAAqE;IACrE,IAAI,EAAE;QAAE,CAAC,sBAAsB,CAAC,EAAE,oBAAoB,CAAA;KAAE,CAAC;IACzD;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,CAAC,sBAAsB,CAAC,EAAE,kBAAkB,CAAA;KAAE,CAAC,CAAC;CACzE;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,eAAe,GAAG,gBAAgB,CAS1E"}