@stigg/agent-sdk-js 0.3.2 → 0.5.0

package/dist/core/context.js

@@ -58,15 +58,31 @@ function agentDimension(context) {
     }
     return { [context.attributionKey]: context.agentId };
 }
+/**
+ * A plan id as given, trimmed - or a refusal when it was given blank. Absent stays absent: no
+ * plan is a legal choice, while an empty one is a typo that would provision nobody onto nothing.
+ */
+function planId(value) {
+    if (value === undefined)
+        return undefined;
+    const named = typeof value === 'string' ? value.trim() : '';
+    if (!named) {
+        throw new Error('stiggContext.defaultPlanId is empty - leave the field out to provision no plan, or name the ' +
+            'plan new customers should start on.');
+    }
+    return named;
+}
+/**
+ * The one field a call cannot proceed without, refused the same way from every binding. Only where
+ * to put the customer differs, so the remedy is the caller's to word.
+ */
+const noCustomer = (remedy = 'Give `wrap(client, { stiggContext: { customerId } })` a default for every call through ' +
+    'this client, or name one per call in `stiggContext`.') => new Error(`No customerId - every governance call is scoped to a tenant. ${remedy}`);
+exports.noCustomer = noCustomer;
 /**
  * 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.
@@ -97,6 +113,7 @@ function resolveContext(context, correlationId,
     const dimensions = agent ? { ...context.dimensions, ...agent } : (context.dimensions ?? {});
     return {
         customerId,
+        defaultPlanId: planId(context.defaultPlanId),
         // 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.
@@ -120,6 +137,7 @@ function resolveContext(context, correlationId,
  */
 const CONTEXT_KEYS = {
     customerId: true,
+    defaultPlanId: true,
     agentId: true,
     attributionKey: true,
     dimensions: true,
@@ -223,6 +241,9 @@ function overrideContext(base, override) {
     }
     return {
         customerId,
+        // Independent of the customer: a call naming its own customer still provisions onto the
+        // client's plan unless it names a plan too.
+        defaultPlanId: override.defaultPlanId !== undefined ? planId(override.defaultPlanId) : base.defaultPlanId,
         entitlement,
         dimensions,
         checkedId,

package/dist/core/session.d.ts

@@ -27,6 +27,13 @@ export type HookContext = {
     correlationId: string;
     /** What the call gated on, when it gated on anything. Undefined on a metering-only run. */
     entitlementId?: string;
+    /**
+     * The agent that took the step, by the orchestrator's own name for it, when a middleware
+     * governs the run. Present at the customer level too, where nothing is attributed to an agent.
+     */
+    agent?: string;
+    /** The tool a step ran, when it was a paid tool a middleware checked. */
+    tool?: string;
 };
 export type SessionHooks = {
     /** Every check this client makes. The whole decision, already formatted as `.summary`. */
@@ -45,9 +52,20 @@ export type SessionDeps = {
      * than disappearing.
      */
     engine: () => Promise<GovernanceEngine>;
+    /**
+     * Creates the customer on their default plan if Stigg does not know them yet. Shared across
+     * every session of one SDK and remembered per customer, so only a customer's first call pays
+     * the round trip. Absent, nothing is ever provisioned.
+     */
+    provisionCustomer?: (customerId: string, planId: string) => Promise<void>;
     logger: Logger;
     onError: (error: EngineError, context: ErrorContext) => void;
     hooks: SessionHooks;
+    /**
+     * Whether each check and report is an OpenTelemetry span. On for an orchestrator's middleware,
+     * where an observability tool's trace is already open around the graph; off for `wrap`.
+     */
+    tracing?: boolean;
 };
 /** What a client did, for whoever wants to print it. Spans every context it served. */
 export type SessionSummary = {
@@ -175,12 +193,21 @@ export declare class GovernanceSession {
     private warnRounded;
     private warnIfNothingDrains;
     private record;
+    /** Every ingest result, however it ended: to its span, then to the application's hook. */
+    private emitIngest;
     /**
      * 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;
+    /**
+     * Makes sure a customer with a default plan exists. Never throws, and answers whether Stigg was
+     * reached - false only for an outage, which is reported here and retried by the next call. A
+     * refusal is an answer: the SDK reports it once, and the call goes on to meet whatever the check
+     * says about a customer that does not exist.
+     */
+    private provisionCustomer;
     /**
      * 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.

package/dist/core/session.js

@@ -29,6 +29,7 @@ const errors_1 = require("../errors");
 const headers_1 = require("../headers");
 const dimensions_1 = require("./dimensions");
 const hooks_1 = require("./hooks");
+const telemetry_1 = require("./telemetry");
 const context_1 = require("./context");
 const types_1 = require("../types");
 /** What a context looks like to a hook: the attribution, and nothing a hook could change. */
@@ -37,6 +38,8 @@ const hookContext = (context) => ({
     dimensions: context.dimensions,
     correlationId: context.correlationId,
     entitlementId: context.checkedId,
+    ...(context.agent !== undefined ? { agent: context.agent } : {}),
+    ...(context.tool !== undefined ? { tool: context.tool } : {}),
 });
 /** A metric nobody can bill: refused where the mapper that invented it can still be found. */
 const emptyMetricNameError = () => new errors_1.EngineError('measure', 'a metric needs a name - an empty one reports to no feature at all.');
@@ -49,6 +52,8 @@ const emptyMetricNameError = () => new errors_1.EngineError('measure', 'a metric
  * `'async'` report would reach the event API with no name at all.
  */
 const DEFAULT_EVENT_NAME = 'agent.usage';
+/** How both engines say a check found no such customer - the reason, verbatim, from the API. */
+const CUSTOMER_NOT_FOUND = 'CustomerNotFound';
 class GovernanceSession {
     deps;
     pending = new Set();
@@ -93,6 +98,8 @@ class GovernanceSession {
      * applies the error policy.
      */
     async warmUp(context) {
+        // First, so the cache below loads a customer that exists rather than remembering one that did not.
+        await this.provisionCustomer(context);
         if (!(0, context_1.isEnforced)(context))
             return;
         try {
@@ -107,28 +114,40 @@ class GovernanceSession {
      * application routes on, not an exception it recovers from.
      */
     async check(context, requestedUsage = 1) {
+        const startedAt = Date.now();
         this.checks += 1;
         const { entitlement } = context;
         // Asked and answered, with nobody to ask: this context named no entitlement, so there is no
         // budget to consult and no refusal that could come back. Still counted and recorded, because
         // the caller did ask and `lastDecision` is where they read what they got.
         if (!entitlement)
-            return this.record((0, decision_1.unenforcedDecision)(), context);
+            return this.record((0, decision_1.unenforcedDecision)(), context, startedAt);
         try {
             const engine = await this.deps.engine();
+            // Before the check, not after: a customer Stigg has never seen holds no entitlement, so their
+            // first call would be refused for not existing yet.
+            const reached = await this.provisionCustomer(context);
             const result = await engine.check(context.customerId, {
                 entitlement,
                 requestedUsage,
                 dimensions: context.dimensions,
             });
-            return this.record((0, decision_1.toDecision)(result, { customerId: context.customerId, entitlement: context.entitlement }), context);
+            // The policy answers only when both halves say so: Stigg could not be reached to create the
+            // customer, and the check then found no customer. Either alone is not that. An existing
+            // customer gets the real answer whatever happened to the create, and a customer Stigg
+            // refused - an unknown plan, an archived customer - is refused here too, rather than
+            // waved through by an `allow` that exists for outages, not for configuration mistakes.
+            if (!reached && result.accessDeniedReason === CUSTOMER_NOT_FOUND) {
+                return this.record((0, decision_1.policyDecision)(context.checkErrorAction === 'allow'), context, startedAt);
+            }
+            return this.record((0, decision_1.toDecision)(result, { customerId: context.customerId, entitlement: context.entitlement }), context, startedAt);
         }
         catch (err) {
             const error = asEngineError('check', err);
             this.reportError(error, 'check', context);
             // Governance is fail-closed server-side; `'deny'` mirrors that, and `'allow'` - the default -
             // is the soft limit that keeps the application up while Stigg is unreachable.
-            return this.record((0, decision_1.policyDecision)(context.checkErrorAction === 'allow'), context);
+            return this.record((0, decision_1.policyDecision)(context.checkErrorAction === 'allow'), context, startedAt);
         }
     }
     /** Applies the context's mapper to a token measurement. The path every binding uses. */
@@ -201,6 +220,7 @@ class GovernanceSession {
     send(context, metrics, sendOptions) {
         const { dimensions, idempotencyKey, raw, event } = sendOptions;
         const mode = context.ingestMode;
+        const startedAt = Date.now();
         // A broken value is one broken metric, not a broken call: the others measured fine and the
         // spend they describe already happened. Dropping only the bad one reports what is knowable.
         //
@@ -245,25 +265,29 @@ class GovernanceSession {
         // distinguishable from one that never tried, and reported to `onIngest` like every result.
         if (!Object.keys(sendable).length) {
             if (rejected)
-                return Promise.resolve(this.failedIngest(context, idempotencyKey, rejected));
+                return Promise.resolve(this.failedIngest(context, idempotencyKey, rejected, startedAt));
             this.ingested += 1;
             const noop = { ok: true, reported: {}, idempotencyKey, mode, replayed: false };
-            this.hook('onIngest', context, () => this.deps.hooks.onIngest?.(noop, hookContext(context)));
+            this.emitIngest(context, noop, startedAt);
             return Promise.resolve(noop);
         }
         const promise = this.deps
             .engine()
-            .then((engine) => engine.report(context.customerId, {
-            metrics: sendable,
-            entitlement: context.entitlement,
-            mode,
-            // Flattened here rather than in the engine, so both transports send the same event and a
-            // sync report pays nothing for a field it will not use.
-            raw: mode === 'async' ? (0, dimensions_1.flattenRaw)(raw) : undefined,
-            dimensions,
-            idempotencyKey,
-            event: event ?? { name: DEFAULT_EVENT_NAME },
-        }))
+            .then(async (engine) => {
+            // A metering-only client never checks, so this is the first place its customer is seen.
+            await this.provisionCustomer(context);
+            return engine.report(context.customerId, {
+                metrics: sendable,
+                entitlement: context.entitlement,
+                mode,
+                // Flattened here rather than in the engine, so both transports send the same event and a
+                // sync report pays nothing for a field it will not use.
+                raw: mode === 'async' ? (0, dimensions_1.flattenRaw)(raw) : undefined,
+                dimensions,
+                idempotencyKey,
+                event: event ?? { name: DEFAULT_EVENT_NAME },
+            });
+        })
             .then((result) => {
             this.ingested += 1;
             // A replay is a delivery that consumed nothing - the server had already counted these
@@ -292,10 +316,10 @@ class GovernanceSession {
                 this.ingestFailures += 1;
                 this.reportError(rejected, rejected.operation, context, idempotencyKey);
             }
-            this.hook('onIngest', context, () => this.deps.hooks.onIngest?.(landed, hookContext(context)));
+            this.emitIngest(context, landed, startedAt);
             return landed;
         })
-            .catch((err) => this.failedIngest(context, idempotencyKey, asEngineError('ingest', err)))
+            .catch((err) => this.failedIngest(context, idempotencyKey, asEngineError('ingest', err), startedAt))
             .finally(() => {
             this.pending.delete(promise);
         });
@@ -384,11 +408,22 @@ class GovernanceSession {
         this.deps.logger.warn(`[stigg] reported ${names} but the response carried no credit balance - ${names.includes(',') ? 'these features are' : 'this feature is'} not mapped to ${checked}, so the budget this call checks ` +
             'against will never drain. Map it in Stigg, or report to the currency directly.');
     }
-    record(decision, context) {
+    record(decision, context, startedAt) {
         this.decision = decision;
+        // Telemetry is instrumentation exactly as a hook is: it never reaches the caller.
+        if (this.deps.tracing) {
+            (0, hooks_1.safely)(() => (0, telemetry_1.traceCheck)(context, decision, startedAt), (err) => this.deps.logger.debug(`[stigg] check span failed: ${String(err)}`));
+        }
         this.hook('onDecision', context, () => this.deps.hooks.onDecision?.(decision, hookContext(context)));
         return decision;
     }
+    /** Every ingest result, however it ended: to its span, then to the application's hook. */
+    emitIngest(context, result, startedAt) {
+        if (this.deps.tracing) {
+            (0, hooks_1.safely)(() => (0, telemetry_1.traceIngest)(context, result, startedAt), (err) => this.deps.logger.debug(`[stigg] ingest span failed: ${String(err)}`));
+        }
+        this.hook('onIngest', context, () => this.deps.hooks.onIngest?.(result, hookContext(context)));
+    }
     /**
      * 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
@@ -397,6 +432,24 @@ class GovernanceSession {
     hook(name, context, invoke) {
         (0, hooks_1.safely)(invoke, (err) => this.reportError(asEngineError(name, err), name, context));
     }
+    /**
+     * Makes sure a customer with a default plan exists. Never throws, and answers whether Stigg was
+     * reached - false only for an outage, which is reported here and retried by the next call. A
+     * refusal is an answer: the SDK reports it once, and the call goes on to meet whatever the check
+     * says about a customer that does not exist.
+     */
+    async provisionCustomer(context) {
+        if (!context.defaultPlanId || !context.customerId || !this.deps.provisionCustomer)
+            return true;
+        try {
+            await this.deps.provisionCustomer(context.customerId, context.defaultPlanId);
+            return true;
+        }
+        catch (err) {
+            this.reportError(asEngineError('provisionCustomer', err), 'provisionCustomer', context);
+            return false;
+        }
+    }
     /**
      * 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.
@@ -409,7 +462,7 @@ class GovernanceSession {
             customerId: context?.customerId,
         }), (err) => this.deps.logger.warn(`[stigg] onError threw while reporting ${error.message}: ${String(err)}`));
     }
-    failedIngest(context, idempotencyKey, error) {
+    failedIngest(context, idempotencyKey, error, startedAt = Date.now()) {
         this.ingestFailures += 1;
         // The error knows what failed - reading a vendor's usage is not the same event as the report
         // that would have followed it, and a context that says otherwise makes the two
@@ -435,7 +488,7 @@ class GovernanceSession {
             replayed: error.replayed ?? false,
             error,
         };
-        this.hook('onIngest', context, () => this.deps.hooks.onIngest?.(failure, hookContext(context)));
+        this.emitIngest(context, failure, startedAt);
         return failure;
     }
 }

package/dist/core/telemetry.d.ts

@@ -0,0 +1,8 @@
+import type { AccessDecision, IngestResult } from '../types';
+import type { ResolvedContext } from './context';
+/** The instrumentation scope every Stigg span is reported under - what a span filter matches on. */
+export declare const TRACER_NAME = "@stigg/agent-sdk-js";
+/** One check, from when it was asked to when it was answered. */
+export declare function traceCheck(context: ResolvedContext, decision: AccessDecision, startedAt: number): void;
+/** One report, whether it landed, failed, or had nothing to send. */
+export declare function traceIngest(context: ResolvedContext, result: IngestResult, startedAt: number): void;

package/dist/core/telemetry.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TRACER_NAME = void 0;
+exports.traceCheck = traceCheck;
+exports.traceIngest = traceIngest;
+const sdk_identity_1 = require("../sdk-identity");
+/** The instrumentation scope every Stigg span is reported under - what a span filter matches on. */
+exports.TRACER_NAME = '@stigg/agent-sdk-js';
+let api;
+/** The application's copy of the API, loaded once - or `null` when it has none installed. */
+function openTelemetry() {
+    if (api === undefined) {
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            api = require('@opentelemetry/api');
+        }
+        catch {
+            api = null;
+        }
+    }
+    return api;
+}
+/** Asked for per span, so a provider registered after this package was loaded is still found. */
+const tracer = (otel) => otel.trace.getTracer(exports.TRACER_NAME, sdk_identity_1.AGENT_SDK_VERSION);
+/** Who the call was for: the attribution, as the check and the report both carry it. */
+function attribution(context) {
+    const attributes = {
+        'stigg.customer.id': context.customerId,
+        'stigg.correlation_id': context.correlationId,
+    };
+    if (context.agent !== undefined)
+        attributes['gen_ai.agent.name'] = context.agent;
+    if (context.tool !== undefined)
+        attributes['gen_ai.tool.name'] = context.tool;
+    if (context.attributionKey && context.dimensions[context.attributionKey] !== undefined) {
+        attributes['stigg.agent.id'] = context.dimensions[context.attributionKey];
+    }
+    for (const [key, value] of Object.entries(context.dimensions))
+        attributes[`stigg.dimension.${key}`] = value;
+    if (context.eventName)
+        attributes['stigg.event.name'] = context.eventName.name;
+    return attributes;
+}
+/** One check, from when it was asked to when it was answered. */
+function traceCheck(context, decision, startedAt) {
+    const otel = openTelemetry();
+    if (!otel)
+        return;
+    const attributes = {
+        ...attribution(context),
+        'stigg.decision.has_access': decision.hasAccess,
+        'stigg.decision.source': decision.source,
+    };
+    if (context.checkedId)
+        attributes['stigg.entitlement.id'] = context.checkedId;
+    if (decision.reason)
+        attributes['stigg.decision.reason'] = decision.reason;
+    if (decision.deniedBy)
+        attributes['stigg.decision.denied_by'] = decision.deniedBy;
+    if (decision.remaining !== undefined)
+        attributes['stigg.decision.remaining'] = decision.remaining;
+    if (decision.remedy)
+        attributes['stigg.decision.remedy'] = decision.remedy;
+    if (decision.isFallback)
+        attributes['stigg.decision.is_fallback'] = true;
+    const span = tracer(otel).startSpan('stigg.check', { startTime: startedAt, attributes });
+    if (!decision.hasAccess) {
+        span.recordException({ name: 'AccessDeniedError', message: decision.message });
+        span.setStatus({ code: otel.SpanStatusCode.ERROR, message: decision.summary });
+    }
+    span.end();
+}
+/** One report, whether it landed, failed, or had nothing to send. */
+function traceIngest(context, result, startedAt) {
+    const otel = openTelemetry();
+    if (!otel)
+        return;
+    const attributes = {
+        ...attribution(context),
+        'stigg.ingest.ok': result.ok,
+        'stigg.ingest.mode': result.mode,
+        'stigg.ingest.idempotency_key': result.idempotencyKey,
+    };
+    for (const [metric, value] of Object.entries(result.reported))
+        attributes[`stigg.metric.${metric}`] = value;
+    if (result.creditsConsumed !== undefined)
+        attributes['stigg.ingest.credits_consumed'] = result.creditsConsumed;
+    if (result.replayed !== undefined)
+        attributes['stigg.ingest.replayed'] = result.replayed;
+    const span = tracer(otel).startSpan('stigg.ingest', { startTime: startedAt, attributes });
+    if (!result.ok) {
+        const message = result.error instanceof Error ? result.error.message : String(result.error ?? 'ingest failed');
+        span.recordException({ name: 'EngineError', message });
+        span.setStatus({ code: otel.SpanStatusCode.ERROR, message });
+    }
+    span.end();
+}

package/dist/engine/composite-engine.d.ts

@@ -1,5 +1,5 @@
 import type { Logger } from '../logger';
-import type { EngineCapabilities, EngineCheckParams, EngineCheckResult, EngineReportParams, EngineReportResult, EngineResolution, EntityInput, EntityPlacement, GovernanceEngine } from './engine';
+import type { EngineCapabilities, EngineCheckParams, EngineCheckResult, EngineReportParams, EngineReportResult, EngineResolution, EntityInput, EntityPlacement, GovernanceEngine, ProvisionOutcome } from './engine';
 export type CompositeDelegates = {
     upsertEntity?: GovernanceEngine;
     check: GovernanceEngine;
@@ -11,6 +11,11 @@ export type CompositeDelegates = {
     unattributedCheck?: GovernanceEngine;
     report: GovernanceEngine;
     archiveEntity?: GovernanceEngine;
+    /**
+     * Creates customers on their default plan. The Node SDK, so the plan it answers with lands in
+     * the cache the next check reads. A customer API, so it needs no governance.
+     */
+    provisionCustomer?: GovernanceEngine;
 };
 /**
  * Whether this check is about an entity at all.
@@ -47,6 +52,7 @@ export declare class CompositeEngine implements GovernanceEngine {
     constructor(deps: CompositeDeps);
     upsertEntity(customerId: string, entity: EntityInput, placement?: EntityPlacement): Promise<void>;
     archiveEntity(customerId: string, entityId: string): Promise<void>;
+    provisionCustomer(customerId: string, planId: string): Promise<ProvisionOutcome>;
     check(customerId: string, params: EngineCheckParams): Promise<EngineCheckResult>;
     report(customerId: string, params: EngineReportParams): Promise<EngineReportResult>;
     /**

package/dist/engine/composite-engine.js

@@ -70,6 +70,15 @@ class CompositeEngine {
     async archiveEntity(customerId, entityId) {
         await this.run('archiveEntity', this.provisioner(), (engine) => engine.archiveEntity(customerId, entityId));
     }
+    async provisionCustomer(customerId, planId) {
+        const delegate = this.delegates.provisionCustomer;
+        if (!delegate?.provisionCustomer) {
+            throw new errors_2.EngineError('provisionCustomer', 'no client here can create customers.');
+        }
+        // Not through `run()`: its fallback is REST, which does not provision customers, so there is
+        // nothing to re-route to - an unreachable Node SDK fails here and the call's own check decides.
+        return delegate.provisionCustomer(customerId, planId);
+    }
     async check(customerId, params) {
         const delegate = (0, exports.isAttributed)(params)
             ? this.delegates.check

package/dist/engine/create-engine.js

@@ -61,7 +61,7 @@ async function createGovernanceEngine(config) {
         const resolution = customerLevel('governance not enabled for this account');
         return {
             engine: new composite_engine_1.CompositeEngine({
-                delegates: { check: nodeSdk, report: nodeSdk },
+                delegates: { check: nodeSdk, report: nodeSdk, provisionCustomer: nodeSdk },
                 fallback: rest,
                 resolution,
                 logger: config.logger,
@@ -78,7 +78,14 @@ async function createGovernanceEngine(config) {
         engine: new composite_engine_1.CompositeEngine({
             // An attributed check goes to REST because only it returns chains; an unattributed one has
             // no chain to lose, and ingest prefers the cached SDK either way.
-            delegates: { upsertEntity: rest, check: rest, unattributedCheck: nodeSdk, report: nodeSdk, archiveEntity: rest },
+            delegates: {
+                upsertEntity: rest,
+                check: rest,
+                unattributedCheck: nodeSdk,
+                report: nodeSdk,
+                archiveEntity: rest,
+                provisionCustomer: nodeSdk,
+            },
             fallback: rest,
             resolution,
             logger: config.logger,

package/dist/engine/engine.d.ts

@@ -133,12 +133,40 @@ export type EntityInput = {
     displayName?: string;
     metadata?: Record<string, string>;
 };
+/** What provisioning a customer came to. Every variant is an answer from Stigg. */
+export type ProvisionOutcome = {
+    status: 'created';
+    /** How the server chose the first subscription - `REQUESTED_PLAN` when it took ours. */
+    decision: string;
+    /** The plan the customer actually landed on, if they landed on one. */
+    planId?: string;
+} | {
+    status: 'existing';
+}
+/** Refused, for a reason a retry would not change: an unknown plan, a key that cannot write. */
+ | {
+    status: 'rejected';
+    reason: string;
+    code?: string;
+};
 export interface GovernanceEngine {
     readonly capabilities: EngineCapabilities;
     upsertEntity(customerId: string, entity: EntityInput, placement?: EntityPlacement): Promise<void>;
     check(customerId: string, params: EngineCheckParams): Promise<EngineCheckResult>;
     report(customerId: string, params: EngineReportParams): Promise<EngineReportResult>;
     archiveEntity(customerId: string, entityId: string): Promise<void>;
+    /**
+     * Creates the customer on `planId` when Stigg does not know them yet, and does nothing when it
+     * does. `existing` is the common answer, and it leaves the customer's subscriptions alone: a
+     * default plan is where a new customer starts, never something an existing one is moved onto.
+     *
+     * Resolves for every answer Stigg gave - including `rejected`, a request it refused - and
+     * throws only when Stigg could not be reached, which is the one failure worth trying again.
+     *
+     * Optional: an engine with no customer API cannot provision, and the caller treats its absence
+     * as having nothing to do.
+     */
+    provisionCustomer?(customerId: string, planId: string): Promise<ProvisionOutcome>;
     /**
      * Loads whatever state this engine caches for a customer, so the checks that follow are local.
      *

package/dist/engine/node-sdk-engine.d.ts

@@ -13,7 +13,7 @@
  * configuration passed straight through rather than re-described here.
  */
 import Stigg, { type ClientConfiguration } from '@stigg/node-server-sdk';
-import type { EngineCapabilities, EngineCheckParams, EngineCheckResult, EngineReportParams, EngineReportResult, GovernanceEngine } from './engine';
+import type { EngineCapabilities, EngineCheckParams, EngineCheckResult, EngineReportParams, EngineReportResult, GovernanceEngine, ProvisionOutcome } from './engine';
 /**
  * Caching - all of it, and none of it implemented here.
  *
@@ -84,6 +84,21 @@ export declare class NodeSdkEngine implements GovernanceEngine {
      * amount happened to warm it.
      */
     preload(customerId: string): Promise<void>;
+    /**
+     * One mutation, no lookup first. Stigg refuses to provision a customer it already has - the
+     * whole mutation, subscription included - so an existing customer comes back as a duplicate and
+     * is left exactly as they were. Reading first would only add a round trip to every customer's
+     * first call in each process, to learn what the create already says.
+     *
+     * Here rather than on REST because the Node SDK creates the customer and the subscription in one
+     * mutation, and writes the entitlements it answers with straight into the cache - so the check
+     * that follows reads the new plan locally instead of fetching it.
+     *
+     * Throws only when Stigg did not answer. Any answer - created, duplicate, or refused - resolves,
+     * because the caller treats them differently: a refusal will be the same next time, and an
+     * unreachable server may not.
+     */
+    provisionCustomer(customerId: string, planId: string): Promise<ProvisionOutcome>;
     upsertEntity(): Promise<void>;
     archiveEntity(): Promise<void>;
     /**

package/dist/engine/node-sdk-engine.js

@@ -52,6 +52,11 @@ const node_server_sdk_1 = __importStar(require("@stigg/node-server-sdk"));
 const errors_1 = require("../errors");
 const sdk_identity_1 = require("../sdk-identity");
 const report_1 = require("./report");
+/**
+ * The API's own code for an error it answered with. Absent when nothing answered - a refused
+ * connection, a dropped socket - which is what tells a refusal apart from an outage.
+ */
+const errorCode = (err) => err?.errorCode;
 const LOCAL_HOSTS = new Set(['localhost', '127.0.0.1', '::1', '[::1]']);
 /**
  * Drops keys that were never set, so a spread cannot un-set a default.
@@ -133,6 +138,39 @@ class NodeSdkEngine {
     async preload(customerId) {
         await this.client.reloadEntitlements(customerId);
     }
+    /**
+     * One mutation, no lookup first. Stigg refuses to provision a customer it already has - the
+     * whole mutation, subscription included - so an existing customer comes back as a duplicate and
+     * is left exactly as they were. Reading first would only add a round trip to every customer's
+     * first call in each process, to learn what the create already says.
+     *
+     * Here rather than on REST because the Node SDK creates the customer and the subscription in one
+     * mutation, and writes the entitlements it answers with straight into the cache - so the check
+     * that follows reads the new plan locally instead of fetching it.
+     *
+     * Throws only when Stigg did not answer. Any answer - created, duplicate, or refused - resolves,
+     * because the caller treats them differently: a refusal will be the same next time, and an
+     * unreachable server may not.
+     */
+    async provisionCustomer(customerId, planId) {
+        try {
+            const provisioned = await this.client.provisionCustomer({ customerId, subscriptionParams: { planId } });
+            return {
+                status: 'created',
+                decision: provisioned.subscriptionDecisionStrategy,
+                planId: provisioned.subscription?.planId,
+            };
+        }
+        catch (err) {
+            const code = errorCode(err);
+            if (code === 'DuplicatedEntityNotAllowed')
+                return { status: 'existing' };
+            if (code && code !== 'RequestTimeout') {
+                return { status: 'rejected', code, reason: err instanceof Error ? err.message : String(err) };
+            }
+            throw (0, errors_1.asEngineError)('provisionCustomer', err);
+        }
+    }
     async upsertEntity() {
         throw new errors_1.GovernanceNotEnabledError('The Node server SDK has no governance surface; entities need the REST client.');
     }

package/dist/errors.d.ts

@@ -50,7 +50,14 @@ export declare class EngineError extends Error {
 export declare class GovernanceNotEnabledError extends Error {
     constructor(detail?: string);
 }
-/** Returns the decision when `err` is a governance denial - the one-liner for a binding catch. */
+/**
+ * Returns the decision when `err` is a governance denial - the one-liner for a binding catch.
+ *
+ * Frameworks rarely let an error through untouched. Vendor SDKs wrap callback errors, LangChain
+ * wraps a model call's error once per middleware, and LangGraph reports two branches that failed
+ * in one step as an `AggregateError` - so the denial is looked for down the whole `cause` chain and
+ * inside every aggregated error, not only at the top.
+ */
 export declare function isAccessDenied(err: unknown): AccessDecision | undefined;
 export declare const isEngineError: (err: unknown) => err is EngineError;
 export declare const isGovernanceNotEnabled: (err: unknown) => err is GovernanceNotEnabledError;