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

package/dist/core/session.js

@@ -0,0 +1,448 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GovernanceSession = void 0;
+/**
+ * The governance session: one per wrapped client, and the two operations every binding needs.
+ *
+ *   check(context, requestedUsage)      - before the call. Returns a decision, never throws.
+ *   ingest(context, measurement)        - after it. Never throws, never fails the caller's call.
+ *
+ * Everything that used to belong to a run belongs here instead, with one difference that matters:
+ * nothing is scoped to a single customer or budget. A context arrives with every operation, so one
+ * session serves every tenant a client is called for.
+ *
+ * ## What is deliberately not here
+ *
+ * No cache. This package holds no decision cache of its own, and that is the whole design: the
+ * Node server SDK underneath already caches entitlement state, and does it far better than a TTL
+ * over decisions ever could - write-through from the server's own measurement responses, realtime
+ * invalidation, usage-period resets applied at read time, fallbacks, and an optional Redis store
+ * that two processes can share.
+ *
+ * An earlier design cached decisions here for `cacheTtlMs`. It duplicated that machinery and
+ * degraded it: a cached allow outlived the report that spent the budget, and it could not hear an
+ * invalidation. What is left is a straight call to the engine, which is the thing that knows.
+ * {@link GovernanceSession.warmUp} primes the engine's cache rather than one of its own.
+ */
+const decision_1 = require("../engine/decision");
+const errors_1 = require("../errors");
+const headers_1 = require("../headers");
+const dimensions_1 = require("./dimensions");
+const hooks_1 = require("./hooks");
+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. */
+const hookContext = (context) => ({
+    customerId: context.customerId,
+    dimensions: context.dimensions,
+    correlationId: context.correlationId,
+    entitlementId: context.checkedId,
+});
+/** 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.');
+/**
+ * What a report is called when nothing names it.
+ *
+ * A gated call is named after the vendor method it wrapped - `anthropic.messages.create` - which
+ * is what a Stigg meter filters on. This is the floor underneath that, for the paths with no
+ * wrapped method behind them: `stigg.report(...)`, and a gateway's own ingest. Without it an
+ * `'async'` report would reach the event API with no name at all.
+ */
+const DEFAULT_EVENT_NAME = 'agent.usage';
+class GovernanceSession {
+    deps;
+    pending = new Set();
+    reported = {};
+    checks = 0;
+    ingested = 0;
+    ingestFailures = 0;
+    step = 0;
+    decision;
+    /** The unmapped-feature warning is said once per client, not once per call. */
+    warnedUnmapped = false;
+    /** Said once per client: the reason is the same every call, and so is the fix. */
+    warnedRounded = false;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    get lastDecision() {
+        return this.decision;
+    }
+    /** The attribution to send downstream when part of the work happens in another process. */
+    headers(context) {
+        return {
+            [headers_1.GOVERNANCE_HEADERS.customer]: context.customerId,
+            [headers_1.GOVERNANCE_HEADERS.dimensions]: JSON.stringify(context.dimensions),
+            [headers_1.GOVERNANCE_HEADERS.run]: context.correlationId,
+            // Which of those dimensions is the agent. Only this side knows: the receiver sees a flat
+            // map and cannot tell attribution from metadata. Empty when the run names no agent, which
+            // is a receiver that should round nothing.
+            [headers_1.GOVERNANCE_HEADERS.attributionKey]: context.attributionKey ?? '',
+        };
+    }
+    /**
+     * 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.
+     */
+    async warmUp(context) {
+        if (!(0, context_1.isEnforced)(context))
+            return;
+        try {
+            await (await this.deps.engine()).preload?.(context.customerId, context.dimensions);
+        }
+        catch (err) {
+            this.deps.logger.warn(`[stigg] warm-up failed for ${context.customerId}: ${String(err)}`);
+        }
+    }
+    /**
+     * The enforcement path. Returns a decision, never throws - a refusal is a commercial event the
+     * application routes on, not an exception it recovers from.
+     */
+    async check(context, requestedUsage = 1) {
+        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);
+        try {
+            const engine = await this.deps.engine();
+            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);
+        }
+        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);
+        }
+    }
+    /** Applies the context's mapper to a token measurement. The path every binding uses. */
+    ingestTokens(context, usage, options = {}) {
+        return this.ingestMeasurement(context, { usage }, options);
+    }
+    /**
+     * 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, measurement, options = {}) {
+        const measured = (0, types_1.toMeasurement)(measurement);
+        // Merged, not replaced: a measurement names what only it can know - the model that served -
+        // and the caller's own attribution is not an alternative to that. The measurement wins a key
+        // they both set, because it saw the call.
+        const dimensions = measured.dimensions ? { ...context.dimensions, ...measured.dimensions } : context.dimensions;
+        const idempotencyKey = measured.idempotencyKey ?? options.idempotencyKey ?? context.idempotencyKey ?? this.nextKey(context);
+        try {
+            return this.send(context, context.usageMapper(measured), {
+                dimensions,
+                idempotencyKey,
+                raw: measured.raw ?? options.raw,
+                event: options.event ?? context.eventName,
+            });
+        }
+        catch (err) {
+            return Promise.resolve(this.failedIngest(context, idempotencyKey, asEngineError('measure', err)));
+        }
+    }
+    /**
+     * 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, value, options = {}) {
+        if (!context.checkedId) {
+            // There is no feature id to put this under: the whole point of this overload is that the
+            // value names what the context checks, and this one checks nothing. Failing the way a broken
+            // metric fails - counted, reported, handed back as a result - is what keeps the one promise
+            // ingest makes, that metering never breaks the caller's call.
+            const key = options.idempotencyKey ?? context.idempotencyKey ?? this.nextKey(context);
+            return Promise.resolve(this.failedIngest(context, key, new errors_1.EngineError('ingest', 'ingest(value) reports against the entitlement the call checks, and this context named ' +
+                'none - so there is no feature id to report it under. Report by name with ' +
+                'ingestMetrics({ [featureId]: value }), or name an entitlement.')));
+        }
+        return this.ingestMetrics(context, { [context.checkedId]: value }, options);
+    }
+    /**
+     * 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, metrics, options = {}) {
+        return this.send(context, metrics, {
+            dimensions: context.dimensions,
+            idempotencyKey: options.idempotencyKey ?? context.idempotencyKey ?? this.nextKey(context),
+            raw: options.raw,
+            event: options.event ?? context.eventName,
+        });
+    }
+    /**
+     * 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`.
+     */
+    send(context, metrics, sendOptions) {
+        const { dimensions, idempotencyKey, raw, event } = sendOptions;
+        const mode = context.ingestMode;
+        // 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.
+        //
+        // What counts as broken follows the mode, because the two DTOs take different numbers. A zero
+        // survives into an event and is dropped from a usage report: a meter may filter on a field
+        // being present, and an event that omits it on a cache miss changes shape call to call, while
+        // a usage report of zero is a request that moves nothing.
+        // Which metric draws the wallet, which is what decides whether a fraction is legal: the one
+        // named after the currency this context checks goes to `consumeCredits`, and everything else
+        // to the usage report or an event. The same split `reportMetrics` makes further down.
+        const creditCurrencyId = context.entitlement && (0, types_1.entitlementKind)(context.entitlement) === 'credit' ? context.checkedId : undefined;
+        // Whether this run is attributed to a governance entity, which is what decides whether a
+        // fraction can be counted. See `wholeUnitsForGovernance`.
+        const attributed = !!context.attributionKey && !!context.dimensions[context.attributionKey];
+        const sendable = {};
+        let rejected;
+        for (const [featureId, rawValue] of Object.entries(metrics)) {
+            const drawsWallet = featureId === creditCurrencyId;
+            // The mapper's own number is what gets validated, before any rounding of ours. Rounding
+            // first laundered a negative into a success: `Math.ceil(-0.5)` is `-0`, which is not `< 0`,
+            // so it passed the guard that exists to catch it, was then dropped for not being `> 0`, and
+            // reported as the no-op ingest that an empty turn is. A mapper returning a negative would
+            // have been told it succeeded.
+            //
+            // The key is the feature id this spend lands on, and the mapper that produced it is the
+            // application's own function. An empty one is validated by nothing downstream - the value is
+            // checked, the key is not - so it would report to a feature that cannot exist, answer `ok`,
+            // and move no budget: the failure that looks like success, from a typo.
+            const invalid = featureId.trim() ? (0, types_1.usageValueError)(rawValue, mode, drawsWallet) : emptyMetricNameError();
+            if (invalid) {
+                rejected ??= invalid;
+                continue;
+            }
+            const value = attributed && drawsWallet ? (0, types_1.wholeUnitsForGovernance)(rawValue) : rawValue;
+            if (value !== rawValue)
+                this.warnRounded(featureId, rawValue, value);
+            if (value > 0 || mode === 'async')
+                sendable[featureId] = value;
+        }
+        // Zero-token calls are normal (a cached refusal, an empty stream); they are not an error. They
+        // are still an ingest that happened, though - counted, so a client that meters nothing is
+        // 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));
+            this.ingested += 1;
+            const noop = { ok: true, reported: {}, idempotencyKey, mode, replayed: false };
+            this.hook('onIngest', context, () => this.deps.hooks.onIngest?.(noop, hookContext(context)));
+            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((result) => {
+            this.ingested += 1;
+            // A replay is a delivery that consumed nothing - the server had already counted these
+            // keys - so it is one more ingest but not one more unit of spend.
+            if (!result.replayed)
+                (0, context_1.addMetrics)(this.reported, result.reported);
+            this.warnIfNothingDrains(context, result, sendable);
+            const landed = {
+                // A metric the caller's own mapper got wrong does not stop the rest from being
+                // delivered - the spend is real and dropping it would understate a bill. But the turn
+                // did not report everything it measured, and saying `ok` would hide that: the metrics
+                // that were refused are missing from `reported`, and nothing else would ever mention
+                // them. So what landed is reported as landed, and the refusal travels with it.
+                ok: !rejected,
+                reported: result.reported,
+                idempotencyKey,
+                mode: result.mode,
+                replayed: result.replayed,
+                creditsConsumed: result.creditsConsumed,
+                ...(rejected ? { error: rejected } : {}),
+            };
+            // Counted and routed to the error sink exactly as a wholly failed ingest is - a mapper
+            // that produced an unusable value is the application's own bug either way. `failedIngest`
+            // does this for the turn that delivered nothing; this is the turn that delivered some.
+            if (rejected) {
+                this.ingestFailures += 1;
+                this.reportError(rejected, rejected.operation, context, idempotencyKey);
+            }
+            this.hook('onIngest', context, () => this.deps.hooks.onIngest?.(landed, hookContext(context)));
+            return landed;
+        })
+            .catch((err) => this.failedIngest(context, idempotencyKey, asEngineError('ingest', err)))
+            .finally(() => {
+            this.pending.delete(promise);
+        });
+        this.pending.add(promise);
+        return promise;
+    }
+    /**
+     * 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, err) {
+        this.ingestFailures += 1;
+        this.reportError(asEngineError('measure', err), 'measure', context);
+    }
+    /** Waits for in-flight ingests, so a caller knows what was actually delivered. */
+    async drain() {
+        while (this.pending.size)
+            await Promise.allSettled([...this.pending]);
+        return this.summary();
+    }
+    summary() {
+        return {
+            checks: this.checks,
+            ingested: this.ingested,
+            reported: { ...this.reported },
+            ingestFailures: this.ingestFailures,
+            lastDecision: this.decision,
+        };
+    }
+    /** `correlationId:n` - distinct per call, for a vendor that offered no id of its own. */
+    nextKey(context) {
+        return `${context.correlationId}:${++this.step}`;
+    }
+    /**
+     * 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.
+     */
+    warnRounded(featureId, from, to) {
+        if (this.warnedRounded)
+            return;
+        this.warnedRounded = true;
+        this.deps.logger.warn(`[stigg] rounded ${featureId} up from ${from} to ${to}: this run is attributed to a governance ` +
+            'entity, and per-entity usage is counted in whole units. An unattributed run reports the ' +
+            'fraction as measured. Denominate the currency finely enough that one unit is small, or ' +
+            'drop the agent attribution to meter exactly.');
+    }
+    warnIfNothingDrains(context, result, sent) {
+        if (this.warnedUnmapped)
+            return;
+        // The warning exists to say that the budget this call checks will never drain. A call that
+        // named no entitlement checks no budget, so there is nothing here that can fail to drain -
+        // saying it anyway would invent a gate the caller deliberately did not ask for.
+        const checked = context.checkedId;
+        if (!checked)
+            return;
+        const names = Object.keys(sent).join(', ');
+        if (result.mode === 'async') {
+            if (Object.keys(sent).includes(checked))
+                return;
+            this.warnedUnmapped = true;
+            this.deps.logger.warn(`[stigg] reported ${names} as events under ${context.eventName?.name ?? 'the call event'} - none of ` +
+                `them names ${checked}, which is what this call checks. Whether the budget moves is now up to the ` +
+                'meters configured for that event, and the event API answers with nothing that can confirm it.');
+            return;
+        }
+        if (result.creditsConsumed !== undefined)
+            return;
+        this.warnedUnmapped = true;
+        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) {
+        this.decision = decision;
+        this.hook('onDecision', context, () => this.deps.hooks.onDecision?.(decision, hookContext(context)));
+        return decision;
+    }
+    /**
+     * 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.
+     */
+    hook(name, context, invoke) {
+        (0, hooks_1.safely)(invoke, (err) => this.reportError(asEngineError(name, err), name, context));
+    }
+    /**
+     * 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.
+     */
+    reportError(error, operation, context, idempotencyKey) {
+        (0, hooks_1.safely)(() => this.deps.onError(error, {
+            operation,
+            runId: context?.correlationId,
+            idempotencyKey,
+            customerId: context?.customerId,
+        }), (err) => this.deps.logger.warn(`[stigg] onError threw while reporting ${error.message}: ${String(err)}`));
+    }
+    failedIngest(context, idempotencyKey, error) {
+        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
+        // indistinguishable.
+        this.reportError(error, error.operation, context, idempotencyKey);
+        // `reported` is what landed, which is not always nothing: an ingest is up to two calls, and a
+        // rejection on the second leaves the first one's spend at Stigg. It is what was attempted
+        // minus whatever the failure took with it, so it comes off the error rather than off the
+        // metrics this call set out to send.
+        const landed = error.reported ?? {};
+        // Guarded exactly as a successful ingest is: what landed before the failure can itself have
+        // been a replay, and the server consumed nothing for it. Counting it here would make a
+        // half-failed retry the one way to inflate the summary past what was actually spent.
+        if (!error.replayed)
+            (0, context_1.addMetrics)(this.reported, landed);
+        const failure = {
+            ok: false,
+            reported: landed,
+            idempotencyKey,
+            mode: context.ingestMode,
+            // What the error carried, not an assumption: `undefined` stays undefined, because the event
+            // API cannot tell a first delivery from a replay and saying `false` would claim it can.
+            replayed: error.replayed ?? false,
+            error,
+        };
+        this.hook('onIngest', context, () => this.deps.hooks.onIngest?.(failure, hookContext(context)));
+        return failure;
+    }
+}
+exports.GovernanceSession = GovernanceSession;
+/** Whatever went wrong, as the seam's own error. */
+function asEngineError(operation, err) {
+    if (err instanceof errors_1.EngineError)
+        return err;
+    return new errors_1.EngineError(operation, err instanceof Error ? err.message : String(err), { cause: err });
+}

package/dist/decision-text.d.ts

@@ -0,0 +1,15 @@
+/**
+ * How a decision reads to a human. Kept next to the decision itself rather than in a binding,
+ * because every binding needs the same words and none of them should invent their own.
+ */
+import type { AccessDecision } from './types';
+/**
+ * Denial -> what to tell the user.
+ *
+ * An entitlement refusal is a commercial event, not an incident: an empty wallet is an upsell, an
+ * admin-set cap is an escalation to that admin, and the two must not be collapsed into one
+ * "you have been blocked" string.
+ */
+export declare function remedyMessage(decision: AccessDecision | undefined): string;
+/** One-line decision summary for logs. */
+export declare function describeDecision(decision: Omit<AccessDecision, 'summary' | 'message'>): string;

package/dist/decision-text.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.remedyMessage = remedyMessage;
+exports.describeDecision = describeDecision;
+/**
+ * Denial -> what to tell the user.
+ *
+ * An entitlement refusal is a commercial event, not an incident: an empty wallet is an upsell, an
+ * admin-set cap is an escalation to that admin, and the two must not be collapsed into one
+ * "you have been blocked" string.
+ */
+function remedyMessage(decision) {
+    if (!decision || decision.hasAccess)
+        return 'Allowed.';
+    const who = decision.deniedBy ? ` for ${decision.deniedBy}` : '';
+    switch (decision.remedy) {
+        case 'top-up':
+            return `Out of credits${who}. Top up the balance to continue.`;
+        case 'raise-budget':
+            return `Budget exhausted${who}. Ask whoever set this budget to raise it, or wait for the next reset.`;
+        case 'subscribe':
+            return `No entitlement${who}. An active subscription including this capability is required.`;
+        case 'retry':
+            return 'Governance is temporarily unavailable and the run was held back. Retry shortly.';
+        default:
+            return `Denied${who}${decision.reason ? ` (${decision.reason})` : ''}.`;
+    }
+}
+/** One-line decision summary for logs. */
+function describeDecision(decision) {
+    // Every field the line below is built from - remaining, who denied, which client answered - is
+    // absent on an unenforced decision, and a line assembled from what is left reads as an allow with
+    // a budget behind it. There is no budget behind it, so the line says that instead.
+    if (decision.source === 'unenforced') {
+        return 'hasAccess=true source=unenforced - this run named no entitlement, so nothing was checked';
+    }
+    const parts = [`hasAccess=${decision.hasAccess}`];
+    if (decision.remaining !== undefined)
+        parts.push(`remaining=${decision.remaining}`);
+    if (decision.deniedBy)
+        parts.push(`deniedBy=${decision.deniedBy}`);
+    if (decision.reason)
+        parts.push(`reason=${decision.reason}`);
+    if (decision.remedy)
+        parts.push(`remedy=${decision.remedy}`);
+    parts.push(`source=${decision.source}`);
+    if (decision.isFallback)
+        parts.push('fallback=true');
+    // Printed for the same reason `fallback` is: both say how much the line can be trusted, and an
+    // operator reading it back has no object to inspect - only this.
+    if (decision.locallyDerived)
+        parts.push('local=true');
+    return parts.join(' ');
+}

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

@@ -0,0 +1,72 @@
+import type { Logger } from '../logger';
+import type { EngineCapabilities, EngineCheckParams, EngineCheckResult, EngineReportParams, EngineReportResult, EngineResolution, EntityInput, EntityPlacement, GovernanceEngine } from './engine';
+export type CompositeDelegates = {
+    upsertEntity?: GovernanceEngine;
+    check: GovernanceEngine;
+    /**
+     * Serves a check that carries no attribution. With no dimensions there is no entity to resolve
+     * and no chain to lose, so the question is the customer's pool - which the cached client can
+     * answer without a round trip. Unset, every check goes to `check`.
+     */
+    unattributedCheck?: GovernanceEngine;
+    report: GovernanceEngine;
+    archiveEntity?: GovernanceEngine;
+};
+/**
+ * Whether this check is about an entity at all.
+ *
+ * `dimensions` is the only attribution a check carries - the REST call sends nothing else that
+ * could resolve one - so an empty map means the governance tree is never consulted and the answer
+ * is the customer's pool either way. Registration is deliberately NOT the signal: an agent
+ * provisioned last week is governed by a run that registers nothing today.
+ */
+export declare const isAttributed: (params: {
+    dimensions: Record<string, string>;
+}) => boolean;
+export type CompositeDeps = {
+    delegates: CompositeDelegates;
+    resolution: EngineResolution;
+    /** The complete implementation. Takes over from any delegate that proves unreachable. */
+    fallback?: GovernanceEngine;
+    logger?: Logger;
+};
+export declare class CompositeEngine implements GovernanceEngine {
+    readonly capabilities: EngineCapabilities;
+    private readonly delegates;
+    private readonly resolution;
+    private readonly fallback?;
+    private readonly logger?;
+    /**
+     * Which `operation::client` pairs have failed in a way another transport could survive. Keyed
+     * by the pair rather than by the engine: one client can serve two operations over two different
+     * services, and a GraphQL outage must not disable an entitlement read that never went there.
+     */
+    private readonly demoted;
+    /** What each delegate is, so a result names the client that actually answered it. */
+    private readonly sourceOf;
+    constructor(deps: CompositeDeps);
+    upsertEntity(customerId: string, entity: EntityInput, placement?: EntityPlacement): Promise<void>;
+    archiveEntity(customerId: string, entityId: string): Promise<void>;
+    check(customerId: string, params: EngineCheckParams): Promise<EngineCheckResult>;
+    report(customerId: string, params: EngineReportParams): Promise<EngineReportResult>;
+    /**
+     * Warms the delegate that would serve this check - not every delegate that holds a cache.
+     *
+     * Routed by the same rule `check` uses, because warming anything else is a round trip spent on
+     * a cache this context will never read: an attributed check under governance goes to REST,
+     * which caches nothing, so the honest answer there is to do nothing. Deliberately not run
+     * through `run()`: a warm-up that cannot reach its transport is not worth demoting an operation
+     * over, and the first real check will discover the same outage and apply the error policy.
+     */
+    preload(customerId: string, dimensions: Record<string, string>): Promise<void>;
+    close(): Promise<void>;
+    /**
+     * Runs an operation on its delegate, and once - and only once per delegate - retries on the
+     * complete implementation if the failure says the transport is unreachable rather than the
+     * request wrong.
+     */
+    private run;
+    /** Results carry the client that actually answered, which is not always the one planned. */
+    private stamp;
+    private provisioner;
+}