@stigg/agent-sdk-js 0.0.0-stage → 0.1.0

package/dist/core/context.js

@@ -0,0 +1,221 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addMetrics = exports.isEnforced = exports.noCustomer = exports.CONTEXT_DEFAULTS = void 0;
+exports.resolveContext = resolveContext;
+exports.overrideContext = overrideContext;
+/**
+ * The governance context: who a call is for, what gates it, and what it reports.
+ *
+ * One shape, given in two places. `wrap(client, { stiggContext })` sets the defaults for every
+ * call through that client; `client.messages.create({ ..., stiggContext })` overrides them for one
+ * call. That is the whole of the configuration surface - there is no run to open and nothing to
+ * keep in sync between a setup step and a call site.
+ *
+ * ## Why resolution is split in two
+ *
+ * A gated call sits directly in front of a network request the application is paying for, so the
+ * SDK's own work has to disappear next to it. The split below is what makes that true:
+ *
+ *   `resolveContext`  - runs once, at `wrap`. Validates, folds the agent into the dimensions,
+ *                       and precomputes everything a call would otherwise derive: the cache key,
+ *                       the entitlement id, the mapper.
+ *   `overrideContext` - runs only when a call actually carries a `stiggContext`, and only touches
+ *                       the keys that call named.
+ *
+ * So a call that overrides nothing does no merging, no validation and no allocation: it reads the
+ * object `wrap` already built. A client wrapped without a customer is the exception - its calls
+ * each name their own, so each one carries an override and pays for the merge.
+ */
+const types_1 = require("../types");
+/**
+ * What nobody told the SDK, and it will not guess.
+ *
+ * Exported because the constructor's own schema defaults to these: two copies of "what happens
+ * when nothing says" is how a configured `deny` came to be parsed, stored and then ignored in
+ * favour of an `allow` written somewhere else.
+ *
+ * `allow` is the soft limit - an unreachable Stigg does not take the application down with it.
+ */
+exports.CONTEXT_DEFAULTS = { checkErrorAction: 'allow', ingestMode: 'async' };
+/**
+ * The agent, as the dimension it travels as.
+ *
+ * Refused rather than defaulted when the type is missing: a guessed attribution key resolves no
+ * entity, so the spend lands on the customer and the output is indistinguishable from a call that
+ * was never governed. There is no error to read later, which is why there is one here.
+ */
+function agentDimension(context) {
+    if (context.agentId === undefined)
+        return undefined;
+    if (!context.agentId.trim()) {
+        throw new Error('stiggContext.agentId is empty - an agent nobody can name is also one nothing can bill.');
+    }
+    if (!context.attributionKey?.trim()) {
+        throw new Error(`stiggContext.agentId is '${context.agentId}' but no attributionKey says which key to send ` +
+            "it under. Pass the key the agent's entity type declares. Without it the agent resolves " +
+            'no entity and the spend lands on the customer, which looks exactly like a call that was ' +
+            'never governed.');
+    }
+    return { [context.attributionKey]: context.agentId };
+}
+/**
+ * Validates and derives, once. Everything expensive about a context happens here rather than on
+ * the call path - see the note at the top of this file for why that split exists.
+ */
+/** The one field a call cannot proceed without, said the same way wherever it is missing. */
+const noCustomer = () => new Error('No customerId - every governance call is scoped to a tenant. Give `wrap(client, ' +
+    '{ stiggContext: { customerId } })` a default for every call through this client, or name ' +
+    'one per call in `stiggContext`.');
+exports.noCustomer = noCustomer;
+function resolveContext(context, correlationId, 
+// `wrap` passes false: a client whose calls each name their own customer is legal, and its
+// types already say which calls still owe one. Every path that reaches the engine resolves it.
+{ requireCustomer = true, defaults } = {}) {
+    // Checked here as well as in `overrideContext`, and this is the half that matters more: `wrap`
+    // names an agent and its entitlement once for every call through the client, so a typo here
+    // governs *everything* by the fallback rather than one call.
+    assertKnownContext(context, requireCustomer ? 'stiggContext' : "wrap's stiggContext");
+    const customerId = context.customerId?.trim() ?? '';
+    if (!customerId && requireCustomer)
+        throw (0, exports.noCustomer)();
+    // Naming none is legal and means ungated. Naming an empty one is a typo that would meter into
+    // the dark, so it is refused here rather than three calls later.
+    const invalid = (0, types_1.entitlementError)(context.entitlement);
+    if (invalid)
+        throw invalid;
+    const agent = agentDimension(context);
+    const dimensions = agent ? { ...context.dimensions, ...agent } : (context.dimensions ?? {});
+    return {
+        customerId,
+        // Normalized, not passed through: `isEnforced` asks `!== undefined` while every other reader
+        // asks for truthiness, so a JS caller's `entitlement: null` would be enforced by one and
+        // absent to the rest - a call that runs the gate and then reports itself ungated.
+        entitlement: context.entitlement ?? undefined,
+        dimensions,
+        checkErrorAction: context.checkErrorAction ?? defaults?.checkErrorAction ?? exports.CONTEXT_DEFAULTS.checkErrorAction,
+        ingestMode: context.ingestMode ?? defaults?.ingestMode ?? exports.CONTEXT_DEFAULTS.ingestMode,
+        eventName: context.eventName,
+        usageMapper: context.usageMapper ?? types_1.vendorMetrics,
+        idempotencyKey: context.idempotencyKey,
+        correlationId: context.correlationId?.trim() || correlationId,
+        checkedId: context.entitlement ? (0, types_1.entitlementId)(context.entitlement) : undefined,
+        attributionKey: context.attributionKey,
+    };
+}
+/**
+ * Every field a `stiggContext` may carry.
+ *
+ * Typed as a total record of `keyof StiggContext` rather than written as a list, so a field added
+ * to the context without being added here is a compile error instead of a key this rejects.
+ */
+const CONTEXT_KEYS = {
+    customerId: true,
+    agentId: true,
+    attributionKey: true,
+    dimensions: true,
+    entitlement: true,
+    checkErrorAction: true,
+    usageMapper: true,
+    ingestMode: true,
+    eventName: true,
+    idempotencyKey: true,
+    correlationId: true,
+};
+/**
+ * Refuses a context carrying a field this SDK does not read.
+ *
+ * Almost always a typo, and a silent one without this: the context is read key by key, so an
+ * unknown key simply never arrives. A call meaning to spend as one agent spends as whatever
+ * `wrap` was given instead, and the only trace is a bill against the wrong entity.
+ *
+ * The types catch it everywhere but `messages.stream`, which Anthropic declares generic -
+ * `stream<Params extends MessageStreamParams>(body: Params, ...)` - and a generic parameter
+ * infers from its argument rather than checking it for excess properties. `WrappedClient`
+ * intersects the overlay with the vendor's own type to stay assignable to it, and an intersection
+ * of call signatures is an overload set resolved in order, so a context the overlay rejects falls
+ * through to that signature and is taken. Hence the runtime guarantee, which covers every surface
+ * as well as JS callers and hand-typed call sites.
+ *
+ * Thrown rather than warned, like the other guards in this file: the call it would have governed
+ * is in front of money, and a warning is read after the bill.
+ *
+ * `Object.hasOwn` rather than `in`, which walks the prototype chain and so answers true for
+ * `toString`, `constructor` and `hasOwnProperty` - the names likeliest to arrive from a JS caller
+ * building a context out of an object it did not create.
+ */
+function assertKnownContext(context, where) {
+    for (const key of Object.keys(context)) {
+        if (Object.hasOwn(CONTEXT_KEYS, key))
+            continue;
+        throw new Error(`${where} has no field \`${key}\` - this SDK would ignore it, and the call would be ` +
+            `governed by whatever remained instead. Valid fields: ${Object.keys(CONTEXT_KEYS).join(', ')}.`);
+    }
+}
+/**
+ * One call's override, applied over what `wrap` already resolved.
+ *
+ * Only reached when a call actually carried a `stiggContext`; a call that did not reuses the
+ * resolved object as-is. The ordering below is the one the caller asked for: the base identity
+ * first, because a changed customer or agent changes which budget is consulted, and the metering
+ * fields last, because nothing before the response depends on them.
+ */
+function overrideContext(base, override) {
+    assertKnownContext(override, 'stiggContext');
+    // The cheap test first: these are the only fields that can change which budget is consulted,
+    // so a call overriding only, say, `idempotencyKey` re-derives nothing.
+    const rebased = override.customerId !== undefined ||
+        override.agentId !== undefined ||
+        override.dimensions !== undefined ||
+        override.entitlement !== undefined;
+    let customerId = base.customerId;
+    let dimensions = base.dimensions;
+    let entitlement = base.entitlement;
+    let checkedId = base.checkedId;
+    if (rebased) {
+        customerId = override.customerId?.trim() || base.customerId;
+        if (override.entitlement !== undefined) {
+            const invalid = (0, types_1.entitlementError)(override.entitlement);
+            if (invalid)
+                throw invalid;
+            entitlement = override.entitlement;
+            checkedId = (0, types_1.entitlementId)(override.entitlement);
+        }
+        // The key falls back to the client's own, so a call naming a different agent of the same type
+        // need only name the agent - which is the multi-agent case, and the common one.
+        const attributionKey = override.attributionKey ?? base.attributionKey;
+        const agent = agentDimension({ ...override, attributionKey });
+        // Merged per key, not replaced: a per-call tenant must not drop the client's own attribution.
+        //
+        // With one exception. An override naming a *different* entity type writes its agent under a
+        // different key, and the client's own key would otherwise ride along beside it - two agent
+        // dimensions on one call, which governance resolves as two entities and bills accordingly.
+        // That one is dropped by name: it describes an agent this call is not acting as. Every other
+        // dimension the client set is kept, because none of them is claiming to be the agent.
+        const inherited = agent && base.attributionKey && attributionKey !== base.attributionKey
+            ? Object.fromEntries(Object.entries(base.dimensions).filter(([key]) => key !== base.attributionKey))
+            : base.dimensions;
+        dimensions = override.dimensions || agent ? { ...inherited, ...override.dimensions, ...agent } : base.dimensions;
+    }
+    return {
+        customerId,
+        entitlement,
+        dimensions,
+        checkedId,
+        checkErrorAction: override.checkErrorAction ?? base.checkErrorAction,
+        ingestMode: override.ingestMode ?? base.ingestMode,
+        eventName: override.eventName ?? base.eventName,
+        usageMapper: override.usageMapper ?? base.usageMapper,
+        idempotencyKey: override.idempotencyKey ?? base.idempotencyKey,
+        correlationId: override.correlationId?.trim() || base.correlationId,
+        attributionKey: override.attributionKey ?? base.attributionKey,
+    };
+}
+/** Whether a context gates at all. The enforcement switch, read on every call. */
+const isEnforced = (context) => context.entitlement !== undefined;
+exports.isEnforced = isEnforced;
+/** Reported metrics, accumulated across a client's calls. */
+const addMetrics = (into, add) => {
+    for (const [name, value] of Object.entries(add))
+        into[name] = (into[name] ?? 0) + value;
+};
+exports.addMetrics = addMetrics;

package/dist/core/dimensions.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The vendor's usage object, reduced to something an event can carry.
+ *
+ * Stigg dimensions are a flat map of scalars, so a nested object has to be flattened or dropped -
+ * there is no third option, and stringifying a subtree would put something no meter can aggregate
+ * into a field a meter is meant to read.
+ *
+ * Everything here is a limit rather than a translation, because the input is not ours: a vendor
+ * adds fields whenever it likes, and this runs on every metered call. Depth, count and type are
+ * all capped so a response that grows a large nested block cannot grow the event with it.
+ */
+/** Prefix for everything read off the vendor's object, so it can never shadow a metric. */
+export declare const RAW_PREFIX = "raw.";
+/**
+ * The vendor's own usage block as event dimensions, `raw.`-prefixed and flattened with dotted keys.
+ *
+ * Fractions are kept: an event states what the vendor said and a meter is free to sum decimals,
+ * which is the one place a gateway's `cost` can be reported honestly. `null`, `undefined`, arrays
+ * and anything past the depth cap are dropped rather than coerced - a zero that was never reported
+ * is worse than a counter that is absent.
+ */
+export declare function flattenRaw(raw: Record<string, unknown> | undefined): Record<string, string | number | boolean>;

package/dist/core/dimensions.js

@@ -0,0 +1,47 @@
+"use strict";
+/**
+ * The vendor's usage object, reduced to something an event can carry.
+ *
+ * Stigg dimensions are a flat map of scalars, so a nested object has to be flattened or dropped -
+ * there is no third option, and stringifying a subtree would put something no meter can aggregate
+ * into a field a meter is meant to read.
+ *
+ * Everything here is a limit rather than a translation, because the input is not ours: a vendor
+ * adds fields whenever it likes, and this runs on every metered call. Depth, count and type are
+ * all capped so a response that grows a large nested block cannot grow the event with it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RAW_PREFIX = void 0;
+exports.flattenRaw = flattenRaw;
+/** Prefix for everything read off the vendor's object, so it can never shadow a metric. */
+exports.RAW_PREFIX = 'raw.';
+const MAX_DEPTH = 2;
+const MAX_KEYS = 32;
+const isScalar = (value) => typeof value === 'string' || typeof value === 'boolean' || (typeof value === 'number' && Number.isFinite(value));
+/**
+ * The vendor's own usage block as event dimensions, `raw.`-prefixed and flattened with dotted keys.
+ *
+ * Fractions are kept: an event states what the vendor said and a meter is free to sum decimals,
+ * which is the one place a gateway's `cost` can be reported honestly. `null`, `undefined`, arrays
+ * and anything past the depth cap are dropped rather than coerced - a zero that was never reported
+ * is worse than a counter that is absent.
+ */
+function flattenRaw(raw) {
+    if (!raw)
+        return {};
+    const flat = {};
+    const walk = (node, path, depth) => {
+        for (const [key, value] of Object.entries(node)) {
+            if (Object.keys(flat).length >= MAX_KEYS)
+                return;
+            const name = path ? `${path}.${key}` : key;
+            if (isScalar(value))
+                flat[`${exports.RAW_PREFIX}${name}`] = value;
+            else if (depth < MAX_DEPTH && value && typeof value === 'object' && !Array.isArray(value)) {
+                walk(value, name, depth + 1);
+            }
+        }
+    };
+    walk(raw, '', 0);
+    return flat;
+}

package/dist/core/hooks.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Running an application's own callbacks, where their failure must not become the caller's.
+ *
+ * Hooks are instrumentation. One that throws has told us something went wrong with the watching,
+ * not with the work - so it cannot be allowed to fail a decision, flip a delivered ingest, or
+ * escape a promise the contract says never rejects. It cannot be ignored either, which is what a
+ * bare `try {} catch {}` amounts to.
+ *
+ * Shared, because every path that calls one has to get this right the same way, and the ones that
+ * reimplemented it are exactly the ones that got it wrong.
+ */
+/** Whether a callback typed `=> void` actually handed back something to wait on. */
+export declare function isThenable(value: unknown): value is PromiseLike<unknown>;
+/**
+ * Invokes a callback and routes its failure to `onFailure`, synchronous or not.
+ *
+ * The types say `void`, but nothing stops an application writing `async onIngest` - and a
+ * rejection there would otherwise surface as an unhandled one, which on Node's default takes the
+ * process down over instrumentation.
+ */
+export declare function safely(invoke: () => unknown, onFailure: (err: unknown) => void): void;

package/dist/core/hooks.js

@@ -0,0 +1,47 @@
+"use strict";
+/**
+ * Running an application's own callbacks, where their failure must not become the caller's.
+ *
+ * Hooks are instrumentation. One that throws has told us something went wrong with the watching,
+ * not with the work - so it cannot be allowed to fail a decision, flip a delivered ingest, or
+ * escape a promise the contract says never rejects. It cannot be ignored either, which is what a
+ * bare `try {} catch {}` amounts to.
+ *
+ * Shared, because every path that calls one has to get this right the same way, and the ones that
+ * reimplemented it are exactly the ones that got it wrong.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isThenable = isThenable;
+exports.safely = safely;
+/** Whether a callback typed `=> void` actually handed back something to wait on. */
+function isThenable(value) {
+    return typeof value?.then === 'function';
+}
+/**
+ * Invokes a callback and routes its failure to `onFailure`, synchronous or not.
+ *
+ * The types say `void`, but nothing stops an application writing `async onIngest` - and a
+ * rejection there would otherwise surface as an unhandled one, which on Node's default takes the
+ * process down over instrumentation.
+ */
+function safely(invoke, onFailure) {
+    // The reporter is the application's code too - an `onError` that throws, a logger that throws
+    // while saying so. Losing the report is the last acceptable failure here; letting it escape
+    // would fail the work the callback was only watching.
+    const report = (err) => {
+        try {
+            onFailure(err);
+        }
+        catch {
+            // Nowhere left to report to.
+        }
+    };
+    try {
+        const returned = invoke();
+        if (isThenable(returned))
+            void Promise.resolve(returned).catch(report);
+    }
+    catch (err) {
+        report(err);
+    }
+}

package/dist/core/session.d.ts

@@ -0,0 +1,190 @@
+import { EngineError } from '../errors';
+import { type GovernanceHeaders } from '../headers';
+import { type ResolvedContext } from './context';
+import type { GovernanceEngine } from '../engine/engine';
+import type { ErrorContext } from '../config';
+import type { Logger } from '../logger';
+import { type AccessDecision, type IngestResult, type Measurement, type Metrics, type TokenUsage } from '../types';
+/** Everything the session reports back while it works. Set once, at `wrap`. */
+/**
+ * Who the observation was for, which the observation itself cannot say.
+ *
+ * Neither an {@link AccessDecision} nor an {@link IngestResult} names the caller: `deniedBy`
+ * appears only on a refusal and names the entity that blocked, not the agent that asked. So one
+ * client serving several agents produced a stream of events nothing could attribute, and the only
+ * way to tell them apart was a separate wrapped client per agent - each with its own session
+ * state, which is a real cost rather than an inconvenience.
+ *
+ * `correlationId` is the one to reach for when reconciling: it ties a decision to the ingest that
+ * followed it, which is what anyone chasing a billing discrepancy actually needs.
+ */
+export type HookContext = {
+    /** The tenant this call was scoped to. */
+    customerId: string;
+    /** What it was attributed by - the agent under its entity type's own key, plus any extra. */
+    dimensions: Record<string, string>;
+    /** Shared by every observation of one call, and sent on the wire as `x-stigg-run-id`. */
+    correlationId: string;
+    /** What the call gated on, when it gated on anything. Undefined on a metering-only run. */
+    entitlementId?: string;
+};
+export type SessionHooks = {
+    /** Every check this client makes. The whole decision, already formatted as `.summary`. */
+    onDecision?: (decision: AccessDecision, context: HookContext) => void;
+    /** Every ingest this client makes - including the ones that failed. */
+    onIngest?: (result: IngestResult, context: HookContext) => void;
+};
+export type SessionDeps = {
+    /**
+     * Resolved at the point of use, not at construction.
+     *
+     * Building the engine is a network round trip - a probe that decides which transport serves
+     * which operation - and `wrap` is a setup call that reads as instant. So it starts that work
+     * and hands the session the promise: the first call that needs an engine awaits it, and every
+     * call after that gets one already resolved. The latency moves to the first request rather
+     * than disappearing.
+     */
+    engine: () => Promise<GovernanceEngine>;
+    logger: Logger;
+    onError: (error: EngineError, context: ErrorContext) => void;
+    hooks: SessionHooks;
+};
+/** What a client did, for whoever wants to print it. Spans every context it served. */
+export type SessionSummary = {
+    checks: number;
+    ingested: number;
+    /**
+     * Everything this client reported, summed per feature id - what it sent, not what it was billed.
+     *
+     * Under `'sync'` Stigg says whether a delivery was a replay, and a replay is left out: it
+     * consumed nothing. Under `'async'` it cannot say, so a retry Stigg deduplicated still counts
+     * here. Stigg remains the record of what was actually charged; this is the client's own tally.
+     */
+    reported: Metrics;
+    ingestFailures: number;
+    lastDecision?: AccessDecision;
+};
+export type IngestOptions = {
+    /** Overrides the context's own name for this one report - the vendor method that was gated. */
+    event?: {
+        name: string;
+    };
+    /** The vendor's usage object, for the event to carry. Ignored under `'sync'`. */
+    raw?: Record<string, unknown>;
+    /**
+     * What deduplicates this report. Overrides the context's own, and is what a caller reaches for
+     * when one logical turn is reported twice - a retry, or a resumed stream.
+     */
+    idempotencyKey?: string;
+};
+export declare class GovernanceSession {
+    private readonly deps;
+    private readonly pending;
+    private readonly reported;
+    private checks;
+    private ingested;
+    private ingestFailures;
+    private step;
+    private decision?;
+    /** The unmapped-feature warning is said once per client, not once per call. */
+    private warnedUnmapped;
+    /** Said once per client: the reason is the same every call, and so is the fix. */
+    private warnedRounded;
+    constructor(deps: SessionDeps);
+    get lastDecision(): AccessDecision | undefined;
+    /** The attribution to send downstream when part of the work happens in another process. */
+    headers(context: ResolvedContext): GovernanceHeaders;
+    /**
+     * Primes the cache that actually serves these checks, so the calls that follow read local state.
+     *
+     * It primes the *engine's* cache, not one here - there isn't one. The engine loads the
+     * customer's whole entitlement state, so every entitlement is warm rather than one decision,
+     * and each check is still evaluated against the amount it actually asks for. An engine with no
+     * cache (the governance REST client) implements nothing and this is a no-op, which is the
+     * honest answer: there would be nothing for the round trip to fill.
+     *
+     * Failures are logged rather than thrown: the client works either way, and the first real check
+     * applies the error policy.
+     */
+    warmUp(context: ResolvedContext): Promise<void>;
+    /**
+     * The enforcement path. Returns a decision, never throws - a refusal is a commercial event the
+     * application routes on, not an exception it recovers from.
+     */
+    check(context: ResolvedContext, requestedUsage?: number): Promise<AccessDecision>;
+    /** Applies the context's mapper to a token measurement. The path every binding uses. */
+    ingestTokens(context: ResolvedContext, usage: TokenUsage, options?: IngestOptions): Promise<IngestResult>;
+    /**
+     * Ingests whatever a binding measured, through the context's mapper.
+     *
+     * The mapper runs inside the boundary that never throws, because it is the application's own
+     * function over a vendor's object and either half is free to change shape - a throw there would
+     * put an exception where the contract promises a result.
+     */
+    ingestMeasurement(context: ResolvedContext, measurement: Measurement | TokenUsage, options?: IngestOptions): Promise<IngestResult>;
+    /**
+     * Reports one value against the entitlement this context checks.
+     *
+     * The narrow case, and the only one where the SDK knows what a report costs the budget it gates
+     * on - which is why it is also the only one that can name the feature for you.
+     */
+    ingest(context: ResolvedContext, value: number, options?: IngestOptions): Promise<IngestResult>;
+    /**
+     * Reports named metrics directly, skipping the mapper. The path a gateway and a hand-rolled
+     * binding use, where the numbers are already in Stigg's own vocabulary.
+     */
+    ingestMetrics(context: ResolvedContext, metrics: Metrics, options?: IngestOptions): Promise<IngestResult>;
+    /**
+     * The instrumentation path: one report per metric, all in one call where the transport has one.
+     *
+     * Never throws and never applies the error policy - the spend already happened, so failing here
+     * must not fail the caller's call. Errors go to `onError`.
+     */
+    private send;
+    /**
+     * A binding's own failure at measuring a call that already happened.
+     *
+     * A recipe reads usage off a vendor's response, and a vendor is free to change that response -
+     * so reading it can throw. The call succeeded and the money is spent either way, which makes
+     * this the same kind of event as a failed ingest: counted, reported, and never raised at the
+     * caller, who asked the vendor for something and got it.
+     */
+    failedToMeasure(context: ResolvedContext, err: unknown): void;
+    /** Waits for in-flight ingests, so a caller knows what was actually delivered. */
+    drain(): Promise<SessionSummary>;
+    summary(): SessionSummary;
+    /** `correlationId:n` - distinct per call, for a vendor that offered no id of its own. */
+    private nextKey;
+    /**
+     * The failure that looks like success, said once.
+     *
+     * A call gates on one capability and reports to another. Stigg only moves the one to the other
+     * when the feature is credit-backed in the catalog - and when it is not, every call still
+     * succeeds, every ingest returns `ok`, and the budget never moves. Nothing else in the system
+     * can notice: the check keeps passing because nothing was ever spent.
+     *
+     * The two modes fail the same way and can be told about it to different degrees. A usage report
+     * answers with a credit balance, so its silence is proof. An event answers with nothing at all,
+     * so the most that can be said is that nothing reported names what this call checks, and whether
+     * a meter closes that gap is configuration this process cannot see.
+     */
+    /**
+     * Says that an attributed run rounded, because an overcharge the caller did not ask for must
+     * not be silent - that silence is the thing this SDK was told off for in the first place.
+     */
+    private warnRounded;
+    private warnIfNothingDrains;
+    private record;
+    /**
+     * Hooks are instrumentation, so a throwing one must not reach the caller: it cannot turn an
+     * allow into a denial, flip a delivered ingest to `ok: false`, or reject a promise the contract
+     * says never rejects. The failure is reported like any other.
+     */
+    private hook;
+    /**
+     * The last stop for a failure. `onError` is the application's own code and can throw too, and
+     * there is nowhere left to report that to, so it falls back to the logger.
+     */
+    private reportError;
+    private failedIngest;
+}