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

package/dist/bindings/shared/weighted-metrics.d.ts

@@ -0,0 +1,37 @@
+/**
+ * A price per metric, as the mapper a run reports through.
+ *
+ * Writing one by hand is a reduce over a record and three details that are easy to miss: Stigg
+ * rejects fractions, a turn that measured nothing must report nothing rather than a zero, and a
+ * counter the response omitted is absent rather than zero. This gets all three right once.
+ */
+import type { MetricsMapper } from '../../types';
+import type { ClientRecipe } from '../client/core/types';
+export type WeightedMetricsOptions = {
+    /**
+     * How many weighted units make one of `target`. Defaults to 1, so a weight reads as the price
+     * of one unit of that metric: `output_tokens: 0.5` is half a credit per output token.
+     *
+     * Set it when the weights are easier to write per thousand than per one - `per: 1000` with
+     * `output_tokens: 5` prices five credits per thousand output tokens.
+     */
+    per?: number;
+};
+/**
+ * Prices what a vendor reported into one metric of your own.
+ *
+ * The weights are keyed to the recipe's own metric names, so a typo does not compile. Naming one
+ * is optional: a metric with no weight is free, and a table that prices nothing meters nothing.
+ *
+ * ```ts
+ * // Half a credit per output token, a whole one per input token, cache reads free.
+ * metrics: weightedMetrics(anthropicRecipe, 'data_credit', {
+ *   input_tokens: 1,
+ *   output_tokens: 0.5,
+ * })
+ * ```
+ *
+ * Prices what the vendor actually said, under its own names. For one vocabulary across several
+ * vendors, `normalizedMetrics` reports the four neutral counters instead.
+ */
+export declare function weightedMetrics<M extends string>(recipe: ClientRecipe<M>, target: string, weights: Partial<Record<M, number>>, options?: WeightedMetricsOptions): MetricsMapper;

package/dist/bindings/shared/weighted-metrics.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.weightedMetrics = weightedMetrics;
+/**
+ * Prices what a vendor reported into one metric of your own.
+ *
+ * The weights are keyed to the recipe's own metric names, so a typo does not compile. Naming one
+ * is optional: a metric with no weight is free, and a table that prices nothing meters nothing.
+ *
+ * ```ts
+ * // Half a credit per output token, a whole one per input token, cache reads free.
+ * metrics: weightedMetrics(anthropicRecipe, 'data_credit', {
+ *   input_tokens: 1,
+ *   output_tokens: 0.5,
+ * })
+ * ```
+ *
+ * Prices what the vendor actually said, under its own names. For one vocabulary across several
+ * vendors, `normalizedMetrics` reports the four neutral counters instead.
+ */
+function weightedMetrics(recipe, target, weights, options = {}) {
+    const per = options.per && options.per > 0 ? options.per : 1;
+    // The one thing this cannot report its way out of: an empty target is a feature id of `''`,
+    // which nothing downstream rejects - the value is validated, the key is not - so the turn
+    // reports to a feature that does not exist and the budget never moves.
+    if (!target.trim()) {
+        throw new Error('weightedMetrics needs a target to price into - an empty one reports to no feature.');
+    }
+    // Deduplicated, because the reducer walks the declaration: a recipe listing a name twice would
+    // charge for it twice, which is the one direction a meter must not be wrong in.
+    const priced = [...new Set(recipe.metrics)];
+    return ({ metrics }) => {
+        if (!metrics)
+            return {};
+        // An unpriced metric is free rather than an error, so a table names only what it charges for.
+        const weighted = priced.reduce((sum, name) => sum + (metrics[name] ?? 0) * (weights[name] ?? 0), 0);
+        // Nothing measured is not the same as nothing owed: report no metric at all, which the run
+        // counts as the no-op ingest it is rather than as a report of zero.
+        if (weighted <= 0)
+            return {};
+        // Stigg takes whole units, and rounding down would bill nothing for a turn that did happen.
+        return { [target]: Math.ceil(weighted / per) };
+    };
+}

package/dist/config.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Client configuration - everything that is true of one Stigg *environment*, and nothing else.
+ *
+ * A Stigg API key is environment-bound, so the key identifies the environment: one instance per
+ * environment, like the Node server SDK. That draws the line for what belongs here. Anything that
+ * varies within an environment - which customer, which agent, what it bills against, who wants to
+ * watch it happen - is context for the call that needs it, not configuration for the process.
+ *
+ * The data half (ids, urls, numbers, enums) goes through zod so a typo fails at construction with
+ * a readable message instead of as a 404 three calls later. The collaborator half (logger,
+ * onError) is injected as-is - those are substitution seams, not data to validate.
+ */
+import { z } from 'zod';
+import { type Logger } from './logger';
+import type { CacheOptions, NodeSdkClient } from './engine/node-sdk-engine';
+import type { CheckErrorAction, IngestMode } from './types';
+import type { EngineError } from './errors';
+/**
+ * Where the SDK sends its traffic, and how it identifies itself there.
+ *
+ * Either a server key - which names an environment on the hosted API - or a base URL that needs
+ * no key, which is a local stand-in, a self-hosted deployment, or the built-in mock. They are one
+ * positional parameter rather than two options fields precisely so they cannot both be given:
+ * "an API key or a URL" is the real rule, and a union says it without a runtime check to fail.
+ *
+ * A self-hosted deployment that *does* want a key passes the key here and the URL in options.
+ */
+export type StiggTarget = string | {
+    baseUrl: string;
+};
+declare const dataSchema: z.ZodObject<{
+    apiKey: z.ZodString;
+    baseUrl: z.ZodOptional<z.ZodString>;
+    checkErrorAction: z.ZodDefault<z.ZodEnum<{
+        deny: "deny";
+        allow: "allow";
+    }>>;
+    ingest: z.ZodDefault<z.ZodEnum<{
+        sync: "sync";
+        async: "async";
+    }>>;
+    timeoutMs: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+export type { CacheOptions, NodeSdkClient };
+/** Reported to `onError` alongside the failure, so a swallowed ingest is still diagnosable. */
+export type ErrorContext = {
+    operation: string;
+    runId?: string;
+    idempotencyKey?: string;
+    customerId?: string;
+};
+/**
+ * The second constructor argument: policy and transport, all of it optional and all of it with a
+ * working default. Nothing required lives here - the one thing the SDK cannot infer is the
+ * target, and that is the first argument.
+ */
+export type StiggAgentSDKOptions = {
+    /**
+     * How checks are cached. See {@link CacheOptions} - it is the Node server SDK's own cache
+     * configuration, passed through, because that is where caching actually happens.
+     */
+    cache?: CacheOptions;
+    /**
+     * A Node server SDK client you already have, used instead of building one.
+     *
+     * Pass it when the application uses `@stigg/node-server-sdk` directly. It is the only way to
+     * settle ownership: `Stigg.initialize` keeps one global instance per process and hands it back
+     * when the API key matches, so without this the SDK may be handed your client, believe it built
+     * it, and close it out from under you on `stigg.close()` - taking its cache and socket along.
+     * A client passed here is borrowed and never closed.
+     *
+     * It replaces only the cached half. The governance REST client is still built from the API key,
+     * because the Node SDK has no governance surface. Mutually exclusive with
+     * {@link StiggAgentSDKOptions.cache}, which configures a client this SDK is no longer building.
+     */
+    client?: NodeSdkClient;
+    /**
+     * @deprecated Ignored. There is no local decision cache to put a TTL on any more - the Node
+     * server SDK's entitlement cache serves these checks and keeps itself fresh, so there is no
+     * window to size. Configure caching with {@link StiggAgentSDKOptions.cache}; for a hard limit
+     * with no cached state at all, there is nothing to turn off on the attributed governance path.
+     */
+    cacheTtlMs?: number;
+    /**
+     * What happens to a call when the check itself fails - Stigg unreachable, a timeout, a 5xx.
+     *
+     * Defaults to `'allow'`: a soft limit, so an outage does not take the application down with it.
+     * Pass `'deny'` to mirror governance's own fail-closed behaviour. Overridable per call through
+     * `stiggContext`, and by `wrap`'s own context for every call through one client.
+     */
+    checkErrorAction?: CheckErrorAction;
+    /**
+     * Which of Stigg's ingest APIs a run reports through. Defaults to `'async'`: the event API, which
+     * costs a fraction of the latency and takes a far higher rate. Overridable per run, and see
+     * {@link IngestMode} for what the two trade against each other.
+     */
+    ingest?: IngestMode;
+    timeoutMs?: number;
+    /**
+     * Where the SDK narrates what it did. Defaults to `'console'`, because the things it says are
+     * the ones you need before anything is configured - which transport resolved, that a run is
+     * gating nothing, that what was reported names no entitlement the budget converts.
+     *
+     * Pass `'none'` to silence it, or your own logger to route it.
+     */
+    logger?: Logger | 'console' | 'none';
+    /**
+     * Every instrumentation failure, as structure rather than as a sentence.
+     *
+     * The one observability hook that is environment-scoped, because it is the only one that fires
+     * with no run to belong to: engine resolution, a bare `register()`, `close()`. Watching a
+     * decision or an ingest is per-run and lives on `run.start(..., { hooks })`.
+     *
+     * It is also the only place metering failures surface at all - they are swallowed so they
+     * cannot break a run - so it defaults to a warning through `logger` rather than to silence.
+     * Replace it to route an `EngineError` and its {@link ErrorContext} into your own telemetry.
+     */
+    onError?: (error: EngineError, context: ErrorContext) => void;
+};
+export type ResolvedConfig = Omit<Required<z.infer<typeof dataSchema>>, 'baseUrl'> & {
+    baseUrl?: string;
+    cache?: CacheOptions;
+    client?: NodeSdkClient;
+    logger: Logger;
+    onError: (error: EngineError, context: ErrorContext) => void;
+};
+export declare function resolveConfig(target?: StiggTarget, baseUrl?: string, options?: StiggAgentSDKOptions): ResolvedConfig;
+/** The slice of config the engine factory needs. */
+export type EngineConfig = {
+    apiKey: string;
+    baseUrl?: string;
+    timeoutMs: number;
+    cache?: CacheOptions;
+    client?: NodeSdkClient;
+    logger: Logger;
+};

package/dist/config.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveConfig = resolveConfig;
+/**
+ * Client configuration - everything that is true of one Stigg *environment*, and nothing else.
+ *
+ * A Stigg API key is environment-bound, so the key identifies the environment: one instance per
+ * environment, like the Node server SDK. That draws the line for what belongs here. Anything that
+ * varies within an environment - which customer, which agent, what it bills against, who wants to
+ * watch it happen - is context for the call that needs it, not configuration for the process.
+ *
+ * The data half (ids, urls, numbers, enums) goes through zod so a typo fails at construction with
+ * a readable message instead of as a 404 three calls later. The collaborator half (logger,
+ * onError) is injected as-is - those are substitution seams, not data to validate.
+ */
+const zod_1 = require("zod");
+const context_1 = require("./core/context");
+const logger_1 = require("./logger");
+/** The key sent when the target is a URL that needs none. Never reaches a real environment. */
+const KEYLESS = 'offline-mock';
+const dataSchema = zod_1.z.object({
+    apiKey: zod_1.z.string().min(1),
+    baseUrl: zod_1.z.string().url().optional(),
+    // Both default through the context's own table rather than restating it: the two used to
+    // disagree, and the one written here was the one nothing read.
+    checkErrorAction: zod_1.z.enum(['deny', 'allow']).default(context_1.CONTEXT_DEFAULTS.checkErrorAction),
+    ingest: zod_1.z.enum(['sync', 'async']).default(context_1.CONTEXT_DEFAULTS.ingestMode),
+    timeoutMs: zod_1.z.number().int().positive().default(3_000),
+});
+const resolveLogger = (logger) => {
+    if (logger === 'console' || logger === undefined)
+        return logger_1.consoleLogger;
+    if (logger === 'none')
+        return logger_1.noopLogger;
+    return logger;
+};
+/**
+ * The target, split into the key and the URL the transport actually needs.
+ *
+ * An absent target falls back to the environment variable, the way every vendor SDK does, so the
+ * smallest working program is `new StiggAgentSDK()`. The failure for a missing key is raised here
+ * rather than left to zod, because "set STIGG_SERVER_API_KEY" is the actionable half and the
+ * schema only knows the field was too short.
+ */
+function resolveTarget(target) {
+    if (typeof target === 'object')
+        return { apiKey: KEYLESS, baseUrl: target.baseUrl };
+    const apiKey = (target ?? process.env.STIGG_SERVER_API_KEY)?.trim();
+    if (!apiKey) {
+        throw new Error('No Stigg API key - pass a server key as the first argument, or set STIGG_SERVER_API_KEY. ' +
+            'To run without one, pass a target with a `baseUrl` instead: a local stand-in, a ' +
+            'self-hosted deployment, or the built-in mock.');
+    }
+    return { apiKey };
+}
+function resolveConfig(target, baseUrl, options = {}) {
+    const resolved = resolveTarget(target);
+    // A keyless target *is* a base URL, so naming a second one is two answers to one question.
+    // Refused rather than silently preferred: whichever the SDK picked, the other would be a URL
+    // the caller believes it is talking to and is not.
+    if (resolved.baseUrl && baseUrl) {
+        throw new Error(`This SDK was given a target with its own baseUrl (${resolved.baseUrl}) and a second one ` +
+            `(${baseUrl}). Pass the URL once: as the target when it needs no key, or as the second ` +
+            'argument alongside a key.');
+    }
+    const parsed = dataSchema.parse({
+        apiKey: resolved.apiKey,
+        baseUrl: resolved.baseUrl ?? baseUrl,
+        checkErrorAction: options.checkErrorAction,
+        ingest: options.ingest,
+        timeoutMs: options.timeoutMs,
+    });
+    // Refused rather than silently preferred, like the two-URL case above: `cache` configures a
+    // client, and a client that was handed in is already configured. Whichever the SDK picked, the
+    // other would be settings the caller believes are in force and are not.
+    if (options.client && options.cache) {
+        throw new Error('This SDK was given both a `client` and `cache` options. The cache options configure a ' +
+            'client at construction, and the one you passed is already built - so they would be ' +
+            'ignored. Pass one: `client` for a client you own, or `cache` to have the SDK build one.');
+    }
+    const logger = resolveLogger(options.logger);
+    // Said rather than ignored in silence: someone who set this was sizing an overshoot window, and
+    // the answer to that question is now different rather than smaller.
+    if (options.cacheTtlMs !== undefined) {
+        logger.warn('[stigg] cacheTtlMs is ignored - this SDK no longer caches decisions. Checks are served by ' +
+            "the Node server SDK's entitlement cache, which invalidates on updates and writes reported " +
+            'usage back, so there is no TTL to size. Configure it with `cache` instead.');
+    }
+    return {
+        ...parsed,
+        cache: options.cache,
+        client: options.client,
+        logger,
+        // Never silent, never fatal. Replace it to route into your own telemetry.
+        onError: options.onError ?? ((error, context) => logger.warn(`[stigg] ${context.operation} failed: ${error.message}`)),
+    };
+}

package/dist/core/context.d.ts

@@ -0,0 +1,151 @@
+import type { CheckErrorAction, Entitlement, IngestMode, Metrics, MetricsMapper } from '../types';
+import type { EventIngest } from '../engine/engine';
+/** The entity type an agent is provisioned and attributed as. Both halves, because they must agree. */
+export type AgentType = {
+    /** The governance entity type, as it exists in the account. */
+    entityTypeId: string;
+    /** The attribution key that type declares, under which `agentId` is sent on every call. */
+    attributionKey: string;
+};
+/**
+ * What a call is governed by. Every field is optional here because each one may have been given
+ * at `wrap` instead - `customerId` is the only one that has to come from somewhere, and the
+ * wrapped client's types say which calls still owe it.
+ */
+export type StiggContext = {
+    /** The tenant. Every governance call is scoped to one customer. */
+    customerId?: string;
+    /**
+     * The agent this call spends as. Travels as a dimension under {@link AgentType.attributionKey},
+     * which is the entire mechanism by which an agent is attributed - so naming one without an
+     * `agentType` is refused rather than guessed at.
+     *
+     * Omitted, the call resolves no entity and is checked against the customer's own budget.
+     */
+    agentId?: string;
+    /** The entity type `agentId` is identified as. Required whenever `agentId` is given. */
+    agentType?: AgentType;
+    /**
+     * Extra attribution, sent verbatim on the check and the report. Every key must be an attribution
+     * key on one of the entity types involved, or it matches nothing and the usage rolls up to the
+     * customer instead.
+     *
+     * Overriding this **merges** per key over the wrap's own, so a per-call `{ tenantId }` does not
+     * silently drop a client-wide `{ region }`.
+     */
+    dimensions?: Record<string, string>;
+    /**
+     * What this call **gates on** - a credit currency or a metered feature, never both. **Omit it
+     * and the call gates nothing**: no check leaves the process, nothing can be refused, and
+     * metering is unchanged. The presence of this field is the enforcement switch, because a call
+     * with nothing to check against cannot be enforced, and a separate flag would only be a second
+     * place for the two to disagree.
+     */
+    entitlement?: Entitlement;
+    /**
+     * What a check resolves to when the engine could not answer it. Defaults to `'allow'` - a soft
+     * limit, so an outage does not take the application down with it.
+     *
+     * Worth knowing what that trades: reporting fails in the same outage and is swallowed, so the
+     * spend allowed through is neither capped nor recorded afterwards. `'deny'` mirrors governance,
+     * which is fail-closed server-side.
+     */
+    checkErrorAction?: CheckErrorAction;
+    /**
+     * What to report for each completed call. Defaults to the vendor's own metric names and values
+     * exactly as they came back, so what lands in Stigg reconciles against that vendor's invoice.
+     *
+     * The name on the left is a Stigg feature or credit id, and metering the one the call checks -
+     * {@link StiggContext.entitlement} - is what makes the budget move.
+     */
+    usageMapper?: MetricsMapper;
+    /** Which of Stigg's ingest APIs this call reports through. Defaults to `'async'`. */
+    ingestMode?: IngestMode;
+    /**
+     * The event name to report under in `'async'` mode. Defaults to the vendor call that produced
+     * the usage - `anthropic.messages.create` - which is what a Stigg meter filters on.
+     */
+    eventName?: EventIngest;
+    /**
+     * The key that deduplicates this report. Defaults to the vendor's own request id when it has
+     * one - stable across the vendor's retries, which a local counter cannot be - and to a
+     * generated key otherwise.
+     */
+    idempotencyKey?: string;
+    /**
+     * Correlates work that continues in another process, as `x-stigg-run-id`. Defaults to the id
+     * the wrap generated, so a gateway sees one value per client unless a call says otherwise.
+     */
+    correlationId?: string;
+};
+/**
+ * A context with everything decided and everything derivable already derived.
+ *
+ * Nothing here is optional that the call path would otherwise have to default, and nothing is
+ * computed that a call could be asked to compute twice.
+ */
+export type ResolvedContext = {
+    /**
+     * Empty only for a client wrapped without one, whose calls each name their own. Every path that
+     * reaches the engine resolves it first, so nothing downstream has to re-check it.
+     */
+    customerId: string;
+    entitlement?: Entitlement;
+    /** The agent folded in, so the check and the report send one object and neither re-derives it. */
+    dimensions: Record<string, string>;
+    checkErrorAction: CheckErrorAction;
+    ingestMode: IngestMode;
+    eventName?: EventIngest;
+    usageMapper: MetricsMapper;
+    idempotencyKey?: string;
+    correlationId: string;
+    /** The entitlement's own id, resolved once - undefined when this context gates on nothing. */
+    checkedId?: string;
+};
+/**
+ * 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.
+ */
+export declare const CONTEXT_DEFAULTS: {
+    readonly checkErrorAction: "allow";
+    readonly ingestMode: "async";
+};
+/**
+ * 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. */
+export declare const noCustomer: () => Error;
+/**
+ * The client-wide policy a context falls back to before the SDK's own defaults.
+ *
+ * The chain is per-call, then `wrap`, then the constructor, then {@link CONTEXT_DEFAULTS}. The
+ * constructor link is this parameter: without it a configured policy is inert, because every
+ * context would land on the defaults instead.
+ */
+export type ContextDefaults = {
+    checkErrorAction?: CheckErrorAction;
+    ingestMode?: IngestMode;
+};
+export declare function resolveContext(context: StiggContext, correlationId: string, { requireCustomer, defaults }?: {
+    requireCustomer?: boolean;
+    defaults?: ContextDefaults;
+}): ResolvedContext;
+/**
+ * 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.
+ */
+export declare function overrideContext(base: ResolvedContext, override: StiggContext): ResolvedContext;
+/** Whether a context gates at all. The enforcement switch, read on every call. */
+export declare const isEnforced: (context: ResolvedContext) => boolean;
+/** Reported metrics, accumulated across a client's calls. */
+export declare const addMetrics: (into: Metrics, add: Metrics) => void;

package/dist/core/context.js

@@ -0,0 +1,154 @@
+"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.agentType) {
+        throw new Error(`stiggContext.agentId is '${context.agentId}' but no agentType says which key to send it under. ` +
+            'Pass `agentType: { entityTypeId, attributionKey }` - the pair the entity type was created ' +
+            'with. 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.agentType.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 } = {}) {
+    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,
+    };
+}
+/**
+ * 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) {
+    // 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);
+        }
+        // Merged per key, not replaced: a per-call tenant must not drop the client's own attribution.
+        const agent = agentDimension({ ...override, agentType: override.agentType });
+        dimensions =
+            override.dimensions || agent ? { ...base.dimensions, ...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,
+    };
+}
+/** 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>;