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

package/dist/engine/composite-engine.js

@@ -0,0 +1,135 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CompositeEngine = exports.isAttributed = void 0;
+/**
+ * Routes each of the four operations to whichever delegate serves it, and re-routes on its own
+ * when one stops answering.
+ *
+ * The delegates are not equals. REST can serve everything; the Node SDK is an optimization - it
+ * has the cache, so ingest prefers it - and the governance surface exists only on REST. So the
+ * demotion rule is one-directional: an optimization that proves unreachable is dropped in favour
+ * of the complete implementation, never the other way around. Demoting REST for a transport blip
+ * would silently trade chains for no chains, which is a worse answer, not a slower one.
+ */
+const errors_1 = require("../errors");
+const errors_2 = require("../errors");
+/**
+ * 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.
+ */
+const isAttributed = (params) => Object.keys(params.dimensions).length > 0;
+exports.isAttributed = isAttributed;
+class CompositeEngine {
+    capabilities;
+    delegates;
+    resolution;
+    fallback;
+    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.
+     */
+    demoted = new Set();
+    /** What each delegate is, so a result names the client that actually answered it. */
+    sourceOf = new Map();
+    constructor(deps) {
+        this.delegates = deps.delegates;
+        this.resolution = deps.resolution;
+        this.fallback = deps.fallback;
+        this.logger = deps.logger;
+        const { ops } = deps.resolution;
+        const label = (engine, source) => {
+            if (engine)
+                this.sourceOf.set(engine, source);
+        };
+        label(deps.delegates.upsertEntity, ops.upsertEntity);
+        label(deps.delegates.check, ops.check);
+        label(deps.delegates.unattributedCheck, ops.unattributedCheck ?? ops.check);
+        label(deps.delegates.report, ops.report);
+        label(deps.delegates.archiveEntity, ops.archiveEntity);
+        // Last, so the complete implementation wins where it also serves as a delegate.
+        label(deps.fallback, 'rest');
+        this.capabilities = {
+            strictCheck: deps.delegates.check.capabilities.strictCheck,
+            chains: deps.delegates.check.capabilities.chains,
+            // What the delegate says it can do, not merely that it has the method: every engine
+            // implements `upsertEntity`, and one that cannot provision must not be routed to.
+            provisioning: deps.delegates.upsertEntity?.capabilities.provisioning ?? false,
+        };
+    }
+    // async, so a missing provisioner surfaces as a rejection like every other failure here -
+    // a promise-returning method that throws synchronously splits every caller's error handling.
+    async upsertEntity(customerId, entity, placement) {
+        await this.run('upsertEntity', this.provisioner(), (engine) => engine.upsertEntity(customerId, entity, placement));
+    }
+    async archiveEntity(customerId, entityId) {
+        await this.run('archiveEntity', this.provisioner(), (engine) => engine.archiveEntity(customerId, entityId));
+    }
+    async check(customerId, params) {
+        const delegate = (0, exports.isAttributed)(params)
+            ? this.delegates.check
+            : (this.delegates.unattributedCheck ?? this.delegates.check);
+        return this.run('check', delegate, (engine) => engine.check(customerId, params));
+    }
+    async report(customerId, params) {
+        return this.run('report', this.delegates.report, (engine) => engine.report(customerId, params));
+    }
+    /**
+     * 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.
+     */
+    async preload(customerId, dimensions) {
+        const delegate = (0, exports.isAttributed)({ dimensions })
+            ? this.delegates.check
+            : (this.delegates.unattributedCheck ?? this.delegates.check);
+        await delegate.preload?.(customerId, dimensions);
+    }
+    async close() {
+        const unique = new Set([...Object.values(this.delegates), this.fallback].filter(Boolean));
+        await Promise.all([...unique].map((engine) => engine.close?.()));
+    }
+    /**
+     * 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.
+     */
+    async run(operation, preferred, call) {
+        const key = `${operation}::${this.sourceOf.get(preferred) ?? 'unknown'}`;
+        const engine = this.demoted.has(key) && this.fallback ? this.fallback : preferred;
+        try {
+            return await this.stamp(engine, await call(engine));
+        }
+        catch (err) {
+            const canRetry = this.fallback && engine !== this.fallback && (0, errors_1.isTransportFailure)(err);
+            if (!canRetry)
+                throw err;
+            this.demoted.add(key);
+            this.logger?.warn(`[stigg] ${operation} could not reach its usual transport and was re-routed for the rest of this process: ` +
+                `${err instanceof Error ? err.message : String(err)}`);
+            return this.stamp(this.fallback, await call(this.fallback));
+        }
+    }
+    /** Results carry the client that actually answered, which is not always the one planned. */
+    stamp(engine, result) {
+        if (!result || typeof result !== 'object' || !('source' in result))
+            return result;
+        return { ...result, source: this.sourceOf.get(engine) ?? 'rest' };
+    }
+    provisioner() {
+        const delegate = this.delegates.upsertEntity;
+        if (!delegate?.capabilities.provisioning)
+            throw new errors_2.GovernanceNotEnabledError();
+        return delegate;
+    }
+}
+exports.CompositeEngine = CompositeEngine;

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

@@ -0,0 +1,16 @@
+import type { EngineConfig } from '../config';
+import type { CacheOptions, NodeSdkClient } from './node-sdk-engine';
+import type { EngineResolution, GovernanceEngine } from './engine';
+export type CreatedEngine = {
+    engine: GovernanceEngine;
+    resolution: EngineResolution;
+};
+export type EngineClientOptions = {
+    apiKey: string;
+    baseUrl?: string;
+    timeoutMs: number;
+    /** Both ignored by the REST client, which caches nothing and builds its own transport. */
+    cache?: CacheOptions;
+    client?: NodeSdkClient;
+};
+export declare function createGovernanceEngine(config: EngineConfig): Promise<CreatedEngine>;

package/dist/engine/create-engine.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createGovernanceEngine = createGovernanceEngine;
+/**
+ * Picks the engine and reports what it picked.
+ *
+ * The rule is SDK-first: the Node server SDK serves everything it can (it has the cache), and the
+ * REST client completes what only governance has. Governance itself is optional - not every
+ * account has it - so an account without it still gets a working customer-level engine rather
+ * than an error.
+ */
+const composite_engine_1 = require("./composite-engine");
+const node_sdk_engine_1 = require("./node-sdk-engine");
+const rest_governance_engine_1 = require("./rest-governance-engine");
+const CUSTOMER_LEVEL_OPS = {
+    upsertEntity: 'unavailable',
+    check: 'node-sdk',
+    report: 'node-sdk',
+    archiveEntity: 'unavailable',
+};
+const GOVERNANCE_OPS = {
+    upsertEntity: 'rest',
+    check: 'rest',
+    // A check with no dimensions resolves no entity, so it is the customer's pool either way -
+    // and the cached client can answer that without a round trip.
+    unattributedCheck: 'node-sdk',
+    report: 'node-sdk',
+    archiveEntity: 'rest',
+};
+async function createGovernanceEngine(config) {
+    const clientOptions = {
+        apiKey: config.apiKey,
+        baseUrl: config.baseUrl,
+        timeoutMs: config.timeoutMs,
+        cache: config.cache,
+        client: config.client,
+    };
+    const nodeSdk = new node_sdk_engine_1.NodeSdkEngine(clientOptions);
+    const rest = new rest_governance_engine_1.RestGovernanceEngine(clientOptions);
+    // Governance is assumed, and asked about once here rather than declared by the caller: the
+    // account already knows the answer, so making someone configure it only creates a second
+    // source of truth that can disagree with the first.
+    //
+    // Together with the probe, because they are two independent waits at startup and neither needs
+    // the other's answer. Warming is not optional work: until the Node SDK reports itself
+    // initialized every cache read counts as a miss and refetches, so skipping this would pay a
+    // round trip per check for as long as initialization takes.
+    const [probe] = await Promise.all([
+        rest.probe(),
+        nodeSdk.ready().catch((err) => {
+            // Non-fatal by design. An unreachable cache is a slow client, not a broken one - every read
+            // falls through to the API - and the first real check is where that surfaces as policy.
+            config.logger.warn(`[stigg] the entitlement cache did not finish starting up: ${String(err)}`);
+        }),
+    ]);
+    // REST stays in play either way: it is the complete implementation, so it is what the composite
+    // re-routes to if the Node SDK turns out to be unreachable.
+    if (probe === 'not-enabled') {
+        config.logger.warn('[stigg] governance is not enabled for this account: checks and usage still work at the ' +
+            'customer level, but agents cannot be registered. Contact Stigg to enable it.');
+        const resolution = customerLevel('governance not enabled for this account');
+        return {
+            engine: new composite_engine_1.CompositeEngine({
+                delegates: { check: nodeSdk, report: nodeSdk },
+                fallback: rest,
+                resolution,
+                logger: config.logger,
+            }),
+            resolution,
+        };
+    }
+    const resolution = {
+        mode: 'governance',
+        ops: { ...GOVERNANCE_OPS },
+        reason: 'governance enabled',
+    };
+    return {
+        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 },
+            fallback: rest,
+            resolution,
+            logger: config.logger,
+        }),
+        resolution,
+    };
+}
+const customerLevel = (reason) => ({
+    mode: 'customer-level',
+    ops: { ...CUSTOMER_LEVEL_OPS },
+    reason,
+});

package/dist/engine/decision.d.ts

@@ -0,0 +1,37 @@
+import type { GovernanceDecision, GovernanceRemedy } from '../types';
+import type { EngineCheckResult } from './engine';
+/**
+ * Denial reasons map to different products, so they must not be collapsed: an empty wallet is an
+ * upsell, an admin-set cap is an escalation, and a missing subscription is neither.
+ */
+export declare function remedyFor(reason: string | null | undefined): GovernanceRemedy | undefined;
+export type DecisionContext = {
+    customerId: string;
+};
+/**
+ * `remaining` is the tightest bound across the pool and every chain node, because the binding
+ * constraint is whichever runs out first. It stays undefined when nothing is bounded - the
+ * observe-only rollout, where usage is counted but never blocks.
+ */
+export declare function toDecision(result: EngineCheckResult, { customerId }: DecisionContext): GovernanceDecision;
+/**
+ * Attaches the human-readable halves, so every caller prints the same words. Exported because
+ * anything that adjusts a decision after the fact has to refresh them too - a stale summary is
+ * worse than none.
+ */
+export declare function withDecisionText(decision: Omit<GovernanceDecision, 'summary' | 'message'>): GovernanceDecision;
+/**
+ * The decision to return when the engine itself failed and policy resolved the outcome. No
+ * `deniedBy`: nobody's budget refused this, so naming an entity would be a lie - the failure
+ * detail goes to the `onError` hook instead.
+ */
+export declare function policyDecision(hasAccess: boolean): GovernanceDecision;
+/**
+ * The decision a run that named no entitlement hands back.
+ *
+ * Not `policyDecision(true)`: that one says the engine was asked and failed, which is why it carries
+ * `reason: 'EngineError'` and `remedy: 'retry'`. Nothing failed here and nothing was asked - there
+ * is no budget to ask about - so the only fields true of it are the allow and the source that says
+ * why it is one. No `remaining`, because nothing is bounded; no `deniedBy`, because nothing refused.
+ */
+export declare function unenforcedDecision(): GovernanceDecision;

package/dist/engine/decision.js

@@ -0,0 +1,128 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.remedyFor = remedyFor;
+exports.toDecision = toDecision;
+exports.withDecisionText = withDecisionText;
+exports.policyDecision = policyDecision;
+exports.unenforcedDecision = unenforcedDecision;
+/**
+ * Turns an engine result into the structured refusal callers branch on.
+ *
+ * The `chains` array IS the refusal: it names which entity in the hierarchy denied and by how
+ * much, so no new primitive is needed on top of it.
+ */
+const decision_text_1 = require("../decision-text");
+/**
+ * Denial reasons map to different products, so they must not be collapsed: an empty wallet is an
+ * upsell, an admin-set cap is an escalation, and a missing subscription is neither.
+ */
+function remedyFor(reason) {
+    switch (reason) {
+        case 'InsufficientCredits':
+            return 'top-up';
+        case 'BudgetExceeded':
+        case 'RequestedUsageExceedingLimit':
+            return 'raise-budget';
+        case 'NoActiveSubscription':
+        case 'NoFeatureEntitlementInSubscription':
+        case 'EntitlementNotFound':
+        case 'FeatureNotFound':
+            return 'subscribe';
+        case 'EngineError':
+            return 'retry';
+        default:
+            return undefined;
+    }
+}
+/**
+ * Credits are fractional, and a subtraction of two of them is not: `5 - 4.4258` lands on
+ * 0.5742000000000003, which then reads back to a user as the balance. Rounded to four places,
+ * which is finer than any credit currency prices and coarser than the noise.
+ */
+const remainingOf = (limit, used) => limit === null || limit === undefined ? undefined : Math.round(Math.max(0, limit - (used ?? 0)) * 1e4) / 1e4;
+const tightest = (values) => {
+    const bounded = values.filter((value) => value !== undefined);
+    return bounded.length ? Math.min(...bounded) : undefined;
+};
+/**
+ * `remaining` is the tightest bound across the pool and every chain node, because the binding
+ * constraint is whichever runs out first. It stays undefined when nothing is bounded - the
+ * observe-only rollout, where usage is counted but never blocks.
+ */
+function toDecision(result, { customerId }) {
+    const nodes = (result.chains ?? []).flat();
+    const denied = nodes.find((node) => !node.isGranted);
+    const reason = result.accessDeniedReason ?? undefined;
+    const decision = {
+        hasAccess: result.isGranted,
+        remaining: tightest([
+            remainingOf(result.usageLimit, result.currentUsage),
+            ...nodes.map((node) => remainingOf(node.usageLimit, node.currentUsage)),
+        ]),
+        usageLimit: result.usageLimit,
+        currentUsage: result.currentUsage,
+        source: result.source === 'unavailable' ? 'policy' : result.source,
+        checkedAt: Date.now(),
+    };
+    if (result.isFallback)
+        decision.isFallback = true;
+    if (result.locallyDerived)
+        decision.locallyDerived = true;
+    if (reason) {
+        decision.reason = reason;
+        decision.remedy = remedyFor(reason);
+    }
+    if (!result.isGranted) {
+        // With no chain (governance off, or a pool-level denial) the customer is what blocked.
+        decision.deniedBy = denied?.entityId ?? customerId;
+    }
+    if (result.isFallback && !result.isGranted) {
+        // A denied fallback is not a budget verdict - nobody's limit was consulted, the engine just
+        // could not see live state. Saying "raise the budget" here would send the reader somewhere
+        // there is nothing to fix.
+        decision.reason = 'EngineUnavailable';
+        decision.remedy = 'retry';
+        delete decision.deniedBy;
+        // Nor was it the SDK's arithmetic: whatever the comparison said has just been replaced by
+        // "could not see live state", and claiming authorship of a verdict that no longer stands
+        // would point a reader at the wrong thing to fix.
+        delete decision.locallyDerived;
+    }
+    return withDecisionText(decision);
+}
+/**
+ * Attaches the human-readable halves, so every caller prints the same words. Exported because
+ * anything that adjusts a decision after the fact has to refresh them too - a stale summary is
+ * worse than none.
+ */
+function withDecisionText(decision) {
+    const full = decision;
+    full.summary = (0, decision_text_1.describeDecision)(decision);
+    full.message = (0, decision_text_1.remedyMessage)(full);
+    return full;
+}
+/**
+ * The decision to return when the engine itself failed and policy resolved the outcome. No
+ * `deniedBy`: nobody's budget refused this, so naming an entity would be a lie - the failure
+ * detail goes to the `onError` hook instead.
+ */
+function policyDecision(hasAccess) {
+    return withDecisionText({
+        hasAccess,
+        reason: 'EngineError',
+        remedy: 'retry',
+        source: 'policy',
+        checkedAt: Date.now(),
+    });
+}
+/**
+ * The decision a run that named no entitlement hands back.
+ *
+ * Not `policyDecision(true)`: that one says the engine was asked and failed, which is why it carries
+ * `reason: 'EngineError'` and `remedy: 'retry'`. Nothing failed here and nothing was asked - there
+ * is no budget to ask about - so the only fields true of it are the allow and the source that says
+ * why it is one. No `remaining`, because nothing is bounded; no `deniedBy`, because nothing refused.
+ */
+function unenforcedDecision() {
+    return withDecisionText({ hasAccess: true, source: 'unenforced', checkedAt: Date.now() });
+}

package/dist/engine/engine.d.ts

@@ -0,0 +1,166 @@
+/**
+ * The engine seam. Deliberately narrow, so engine-specific caching behaviour cannot leak into the
+ * public API and v1 can ship on the simplest client and swap later.
+ *
+ * Caching lives entirely behind this seam. Nothing above it caches a decision, so an engine is
+ * free to hold as much state as it can keep correct - which is why `preload` is optional here and
+ * `strictCheck` is per engine rather than a property of the SDK.
+ */
+import type { Entitlement, IngestMode, Metrics } from '../types';
+/** Which client actually served an operation. Reported back so callers can see what ran. */
+export type EngineOpSource = 'rest' | 'node-sdk' | 'unavailable';
+export type EngineCapabilities = {
+    /**
+     * False when a check can be served from cached state. Two instances can then each approve a
+     * decrement against a balance a sibling already spent, so the SDK promises the weaker semantics
+     * rather than documenting hard limits as hard.
+     *
+     * True for the governance REST client, which holds no cache: every check it serves is a live
+     * question to Stigg, and Stigg is fail-closed.
+     */
+    strictCheck: boolean;
+    /** Whether checks carry per-entity governance chains. */
+    chains: boolean;
+    /** Whether entities and assignments can be written at all. */
+    provisioning: boolean;
+};
+export type EngineChainNode = {
+    entityId: string;
+    isGranted: boolean;
+    usageLimit: number | null;
+    currentUsage: number;
+    scopeEntityIds: string[];
+};
+export type EngineCheckResult = {
+    isGranted: boolean;
+    accessDeniedReason?: string | null;
+    usageLimit?: number | null;
+    currentUsage?: number;
+    /** One chain per resolved dimension, root to leaf. Absent when governance is not in play. */
+    chains?: EngineChainNode[][];
+    isFallback?: boolean;
+    /**
+     * True when the engine reached this verdict itself rather than reading one off a response.
+     * A separate axis from `isFallback`, which is about whether the state was live.
+     */
+    locallyDerived?: boolean;
+    source: EngineOpSource;
+};
+export type EngineCheckParams = {
+    /**
+     * Required, and deliberately so: a run that names no entitlement never reaches here at all -
+     * `RunHandle.check` answers it before the engine is consulted. Keeping it required is what makes
+     * a future caller that tries to check against nothing a compile error at the seam, rather than an
+     * allow invented inside a transport.
+     */
+    entitlement: Entitlement;
+    requestedUsage: number;
+    dimensions: Record<string, string>;
+};
+/**
+ * How to report a raw-events meter, for features Stigg aggregates from events rather than from
+ * values your app computes. The meter is matched by `name`, never by feature id.
+ */
+export type EventIngest = {
+    /**
+     * What the event is called. Every metric rides one event under its own dimension name, so a
+     * meter picks its number with `aggregation.field` and this is only what its filter matches on.
+     */
+    name: string;
+};
+export type EngineReportParams = {
+    /** One report per metric under `'sync'`; one event carrying all of them under `'async'`. */
+    metrics: Metrics;
+    /** Which of Stigg's ingest APIs to use. Chosen by the caller, never by a rejection. */
+    mode: IngestMode;
+    /** The vendor's own usage object, flattened to scalars. Rides an event; ignored by `'sync'`. */
+    raw?: Record<string, string | number | boolean>;
+    /**
+     * What the run checks against, when it checks anything. A metric named after this credit currency
+     * draws the wallet directly; every other metric is a feature, which Stigg converts on its own
+     * side. Absent for a metering-only run, where there is no wallet and therefore nothing that is
+     * not a feature.
+     */
+    entitlement?: Entitlement;
+    dimensions: Record<string, string>;
+    /**
+     * Under `'sync'` each metric is keyed `${idempotencyKey}:${featureId}`, so they dedupe
+     * independently. Under `'async'` the turn is one event and this key is the whole of it.
+     */
+    idempotencyKey: string;
+    event?: EventIngest;
+};
+export type EngineReportResult = {
+    /** What actually landed, by feature id. A metric missing here did not report. */
+    reported: Metrics;
+    /**
+     * Credits this report drew, when Stigg answered with a credit balance. Absent means the
+     * features reported are not credit-backed - so the budget the run checks will not drain.
+     */
+    creditsConsumed?: number;
+    currentUsage?: number;
+    /** Which API answered. `'async'` is eventually consistent and says nothing about the balance. */
+    mode: IngestMode;
+    /**
+     * Every key had already been ingested - Stigg reported nothing consumed. Undefined under
+     * `'async'`, whose empty response cannot tell a first delivery from a replay.
+     */
+    replayed?: boolean;
+    source: EngineOpSource;
+};
+/** Where an entity sits in the tree and what it may spend. Placement rides the assignment. */
+export type EntityPlacement = {
+    parentId?: string | null;
+    /**
+     * Required: an assignment is written over `(entity x entitlement)`, so a placement with nothing to
+     * write it against has nowhere to land. `register` refuses that case upstream, which is what keeps
+     * this required rather than optional-and-guarded in every transport.
+     */
+    entitlement: Entitlement;
+    /** Set the budget on every provision, overwriting whatever it was. */
+    usageLimit?: number | null;
+    /**
+     * Set the budget only when the assignment does not exist yet. An existing one keeps its limit
+     * and cadence, so a raise made in the dashboard survives the next run. Mutually exclusive with
+     * `usageLimit` - it costs one extra read, which is why it is not the default.
+     */
+    usageLimitOnCreate?: number;
+    cadence?: string;
+};
+export type EntityInput = {
+    id: string;
+    entityTypeId: string;
+    displayName?: string;
+    metadata?: Record<string, 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>;
+    /**
+     * Loads whatever state this engine caches for a customer, so the checks that follow are local.
+     *
+     * Optional, and absent is not a failure: an engine that caches nothing has nothing to warm, and
+     * the caller treats that as a no-op. `dimensions` is passed so a router can warm the engine that
+     * would actually serve this check rather than whichever one happens to hold a cache.
+     */
+    preload?(customerId: string, dimensions: Record<string, string>): Promise<void>;
+    /** Releases whatever the engine holds open (background caches, sockets). */
+    close?(): Promise<void>;
+}
+/** Which client serves each operation, and why. Returned by the factory as "the used solution". */
+export type EngineResolution = {
+    mode: 'governance' | 'customer-level';
+    ops: {
+        upsertEntity: EngineOpSource;
+        check: EngineOpSource;
+        /** Serves a check carrying no attribution, where there is no chain to lose. */
+        unattributedCheck?: EngineOpSource;
+        report: EngineOpSource;
+        archiveEntity: EngineOpSource;
+    };
+    reason: string;
+};
+export declare const describeResolution: (resolution: EngineResolution) => string;

package/dist/engine/engine.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.describeResolution = void 0;
+const describeResolution = (resolution) => {
+    const { ops } = resolution;
+    // Only worth saying when the two differ; in customer-level mode one client serves both.
+    const unattributed = ops.unattributedCheck && ops.unattributedCheck !== ops.check ? ` (${ops.unattributedCheck} when unattributed)` : '';
+    return (`mode=${resolution.mode} check=${ops.check}${unattributed} report=${ops.report} ` +
+        `provisioning=${ops.upsertEntity} (${resolution.reason})`);
+};
+exports.describeResolution = describeResolution;