@cat-factory/orchestration 0.283.2 → 0.284.0

package/dist/modules/useCases/InlineUseCaseService.js

@@ -0,0 +1,220 @@
+import { sanitizeDescriptorFields, validateDescriptorFields, withDescriptorFieldDefaults, } from '@cat-factory/contracts';
+import { composeUseCasePrompt, describeError, NotFoundError, RateLimitedError, resolveUseCaseModelOption, UnavailableError, useCaseGenerationLimits, ValidationError, } from '@cat-factory/kernel';
+/** The parameters a use case declares, as a list (absent ⇒ none). */
+function parametersOf(useCase) {
+    return useCase.parameters ?? [];
+}
+export class InlineUseCaseService {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** Every registered use case, projected for this scope (model availability included). */
+    async list(scope) {
+        const session = await this.discoverySession(scope);
+        return this.deps.registry.all().map((useCase) => this.project(useCase, session));
+    }
+    /** One registered use case by id, projected for this scope. */
+    async get(scope, useCaseId) {
+        const useCase = this.require(useCaseId);
+        return this.project(useCase, await this.discoverySession(scope));
+    }
+    /**
+     * Run one use case and answer with the generated text.
+     *
+     * The refusal ORDER is the point, and it is cheapest-first for the same reason the bug hunt's is:
+     * every step past the last one costs more than the step before it, so a request that was never
+     * going to run spends nothing. The registration lookup and the parameter check read nothing at
+     * all; binding the session reads the credential pool; the budget probe reads the spend ledger;
+     * only then does a vendor see a token.
+     */
+    async invoke(input) {
+        const useCase = this.require(input.useCaseId);
+        const generator = this.requireGenerator();
+        const parameters = this.validateParameters(useCase, input.parameters ?? {});
+        const option = this.requireModelOption(useCase, input.model);
+        const limits = useCaseGenerationLimits(useCase);
+        const temperature = requireWithinBounds(input.temperature, limits.temperature, 'temperature');
+        const maxOutputTokens = requireWithinBounds(input.maxOutputTokens, limits.maxOutputTokens, 'maxOutputTokens');
+        // NOT caught here, unlike the discovery path: a credential pool that could not be read is not
+        // an availability answer, and reporting it as "this model is unavailable" would send the caller
+        // to pick another one for a fault that has nothing to do with the model they named.
+        const session = await generator.forScope(input.scope);
+        const availability = session.availability(option);
+        if (!availability.available) {
+            throw new UnavailableError(`The model '${option.label}' cannot be served by this deployment`, 'use_case_model_unavailable', { model: option.id, cause: availability.reason });
+        }
+        if (await this.deps.isOverBudget?.(input.scope)) {
+            // Its OWN refusal rather than a generic failure: an exhausted budget is not a broken model,
+            // and the fix (raise the budget, or wait for the window to roll) is not the fix for a
+            // misconfigured provider. Fail-CLOSED, so no vendor call is made.
+            throw new RateLimitedError('This workspace has spent its configured model budget', 'budget_exhausted');
+        }
+        const prompt = composeUseCasePrompt(useCase, {
+            useCaseId: useCase.useCaseId,
+            workspaceId: input.scope.workspaceId,
+            parameters,
+            fields: parametersOf(useCase),
+        });
+        const generation = await session.generate({
+            useCaseId: useCase.useCaseId,
+            option,
+            system: prompt.system,
+            prompt: prompt.prompt,
+            temperature,
+            maxOutputTokens,
+        });
+        if (generation.text.trim() === '') {
+            // An empty visible reply means the model answered only into its private reasoning channel
+            // (seen on some reasoning models) or refused without saying so. Either way there is nothing
+            // to return, and a 200 carrying an empty string would read to a content editor as a model
+            // that had nothing to say about the scene.
+            this.deps.logger?.warn('An inline use case produced no text', {
+                workspaceId: input.scope.workspaceId,
+                useCaseId: useCase.useCaseId,
+                model: option.id,
+                finishReason: generation.finishReason,
+            });
+            throw new UnavailableError(`The model '${option.label}' returned no usable text`, 'use_case_empty_reply', { model: option.id, finishReason: generation.finishReason });
+        }
+        return {
+            useCaseId: useCase.useCaseId,
+            model: {
+                id: option.id,
+                label: option.label,
+                provider: generation.ref.provider,
+                model: generation.ref.model,
+            },
+            text: generation.text,
+            finishReason: generation.finishReason,
+            truncated: generation.finishReason === 'length',
+            usage: generation.usage,
+        };
+    }
+    /** The registered use case, or a 404 naming what was asked for. */
+    require(useCaseId) {
+        const useCase = this.deps.registry.get(useCaseId);
+        if (!useCase)
+            throw new NotFoundError('Use case', useCaseId, { reason: 'use_case_not_found' });
+        return useCase;
+    }
+    /**
+     * The generator, or a 503 naming the deployment-level gap.
+     *
+     * Distinct from a model being unavailable, which is what the per-option availability answers: an
+     * unconfigured deployment is fixed by wiring a model provider, and reporting every declared model
+     * as individually unavailable would send an operator looking for four missing keys instead.
+     */
+    requireGenerator() {
+        const generator = this.deps.generator;
+        if (!generator?.enabled) {
+            throw new UnavailableError('No model provider is configured, so use cases cannot be invoked', 'use_case_models_unconfigured');
+        }
+        return generator;
+    }
+    /**
+     * The session a DISCOVERY read projects against, or `undefined` when there is none to be had.
+     *
+     * Two causes land on the same undefined, and each is stated where it happens rather than
+     * inferred here: no provider is wired at all (ordinary, and the catalog says so per option), or
+     * the credential pool could not be read (a real fault, logged with its cause). Discovery answers
+     * either way, because a read that 500s tells a wrapper the surface does not exist when what
+     * failed was one query behind it.
+     */
+    async discoverySession(scope) {
+        const generator = this.deps.generator;
+        if (!generator?.enabled)
+            return undefined;
+        try {
+            return await generator.forScope(scope);
+        }
+        catch (error) {
+            this.deps.logger?.warn('Use-case model availability could not be resolved', {
+                workspaceId: scope.workspaceId,
+                ...describeError(error),
+            });
+            return undefined;
+        }
+    }
+    /**
+     * The caller's bag, checked against the declared parameters and frozen.
+     *
+     * The SHARED descriptor validator, so this surface refuses exactly what a reusable operation's
+     * create door refuses: unknown keys, wrong value types, missing required visible fields, values
+     * outside a `select`'s options. Every problem is reported at once, because a caller filling a
+     * form wants the whole list rather than one field per round trip.
+     */
+    validateParameters(useCase, supplied) {
+        const fields = parametersOf(useCase);
+        const withDefaults = withDescriptorFieldDefaults(fields, supplied);
+        const problems = validateDescriptorFields(fields, withDefaults);
+        if (problems.length > 0) {
+            throw new ValidationError(problems.join('; '), {
+                reason: 'use_case_parameters_invalid',
+                problems,
+            });
+        }
+        return sanitizeDescriptorFields(fields, withDefaults);
+    }
+    /** The option the invocation runs on, or a 422 naming what this use case does carry. */
+    requireModelOption(useCase, requested) {
+        const option = resolveUseCaseModelOption(useCase, requested);
+        if (!option) {
+            throw new ValidationError(`The use case '${useCase.useCaseId}' does not offer a model '${requested ?? ''}'`, {
+                reason: 'use_case_model_not_allowed',
+                // The allowed ids, so a caller holding a stale catalog can correct itself from the
+                // refusal rather than re-reading discovery to find out what changed.
+                allowed: useCase.models.map((declared) => declared.id),
+            });
+        }
+        return option;
+    }
+    /** One use case's wire projection, with each model's availability read off the bound session. */
+    project(useCase, session) {
+        return {
+            useCaseId: useCase.useCaseId,
+            label: useCase.label,
+            description: useCase.description,
+            ...(useCase.category ? { category: useCase.category } : {}),
+            models: useCase.models.map((option) => projectModel(useCase, option, session)),
+            parameters: [...parametersOf(useCase)],
+            generation: useCaseGenerationLimits(useCase),
+        };
+    }
+}
+/** One model option's wire projection. */
+function projectModel(useCase, option, session) {
+    // With no session there is no provider to ask, so every option is unavailable for the same
+    // deployment-level cause. Reported per option rather than omitted: a wrapper rendering the
+    // picker still shows what this use case OFFERS, greyed out, instead of an empty list that reads
+    // like a use case with no models declared.
+    const availability = session
+        ? session.availability(option)
+        : { available: false, reason: 'provider_unavailable' };
+    return {
+        id: option.id,
+        label: option.label,
+        ...(option.description ? { description: option.description } : {}),
+        default: resolveUseCaseModelOption(useCase, undefined)?.id === option.id,
+        available: availability.available,
+        ...(availability.available ? {} : { unavailableReason: availability.reason }),
+    };
+}
+/**
+ * A knob the caller named, checked against the declared bounds, else the declared default.
+ *
+ * REFUSED rather than clamped, which is why the name says `require` and not `clamp`. A caller
+ * asking for temperature 2.5 against a ceiling of 1.2 is asking for output the deployment has
+ * decided not to produce, and silently running at 1.2 answers that request with a different
+ * generation while reporting success: the caller stores the text believing it came from the
+ * settings it asked for.
+ */
+function requireWithinBounds(value, limit, name) {
+    if (value === undefined)
+        return limit.default;
+    if (!Number.isFinite(value) || value < limit.min || value > limit.max) {
+        throw new ValidationError(`'${name}' must be between ${limit.min} and ${limit.max} for this use case`, { reason: 'use_case_generation_out_of_range', field: name, min: limit.min, max: limit.max });
+    }
+    return value;
+}
+//# sourceMappingURL=InlineUseCaseService.js.map

package/dist/modules/useCases/InlineUseCaseService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"InlineUseCaseService.js","sourceRoot":"","sources":["../../../src/modules/useCases/InlineUseCaseService.ts"],"names":[],"mappings":"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"}

package/dist/modules/useCases/LlmInlineUseCaseGenerator.d.ts

@@ -0,0 +1,39 @@
+import type { InlineUseCaseGenerator, InlineUseCaseScope, InlineUseCaseSession, Logger, ModelFlavor, ModelProvider, ModelProviderResolver, ModelRef } from '@cat-factory/kernel';
+/**
+ * How long one invocation may wait on the vendor, by default.
+ *
+ * Generous, because the ceiling on `maxOutputTokens` is 32,000 and a long scene legitimately takes
+ * minutes, but FINITE: the alternative is a request held open for as long as the transport allows,
+ * on a surface whose whole shape is "ask and be answered". A deployment narrows it per facade.
+ */
+export declare const DEFAULT_USE_CASE_TIMEOUT_MS = 120000;
+/** What the generator needs to resolve its models and reach the provider. */
+export interface LlmInlineUseCaseGeneratorDeps {
+    /** Resolve a ModelProvider for a workspace's credential scope (preferred). */
+    modelProviderResolver?: ModelProviderResolver;
+    /** Static provider (e.g. a fake in tests) used when no resolver is set. */
+    modelProvider?: ModelProvider;
+    /** Resolve a model catalog id to a ref, under the deployment's route order. */
+    resolveBlockModel?: (modelId: string | undefined, providerPreference?: readonly ModelFlavor[]) => ModelRef | undefined;
+    /** Keep an ambient-eligible harness ref inline (local mode) instead of refusing it. */
+    runsInline?: (ref: ModelRef) => boolean;
+    /** The per-invocation deadline; absent ⇒ {@link DEFAULT_USE_CASE_TIMEOUT_MS}. */
+    timeoutMs?: number;
+    /** Facade logger; a failed generation with no trace is an unowned bug. */
+    logger?: Logger;
+}
+export declare class LlmInlineUseCaseGenerator implements InlineUseCaseGenerator {
+    private readonly deps;
+    constructor(deps: LlmInlineUseCaseGeneratorDeps);
+    /** Whether a generation can run at all (some provider is wired). */
+    get enabled(): boolean;
+    /**
+     * Resolve this request's credential pool ONCE and hand back the session that reads it.
+     *
+     * Not caught here: a pool that could not be read is a fact about the deployment, and each caller
+     * answers it differently (discovery says so per option and still publishes the catalog; an
+     * invocation lets it propagate). Swallowing it here would make both of them guess.
+     */
+    forScope(scope: InlineUseCaseScope): Promise<InlineUseCaseSession>;
+}
+//# sourceMappingURL=LlmInlineUseCaseGenerator.d.ts.map

package/dist/modules/useCases/LlmInlineUseCaseGenerator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LlmInlineUseCaseGenerator.d.ts","sourceRoot":"","sources":["../../../src/modules/useCases/LlmInlineUseCaseGenerator.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAGV,sBAAsB,EAGtB,kBAAkB,EAClB,oBAAoB,EACpB,MAAM,EACN,WAAW,EACX,aAAa,EACb,qBAAqB,EACrB,QAAQ,EAET,MAAM,qBAAqB,CAAA;AAqC5B;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B,SAAU,CAAA;AAWlD,6EAA6E;AAC7E,MAAM,WAAW,6BAA6B;IAC5C,8EAA8E;IAC9E,qBAAqB,CAAC,EAAE,qBAAqB,CAAA;IAC7C,2EAA2E;IAC3E,aAAa,CAAC,EAAE,aAAa,CAAA;IAC7B,+EAA+E;IAC/E,iBAAiB,CAAC,EAAE,CAClB,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,kBAAkB,CAAC,EAAE,SAAS,WAAW,EAAE,KACxC,QAAQ,GAAG,SAAS,CAAA;IACzB,uFAAuF;IACvF,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,QAAQ,KAAK,OAAO,CAAA;IACvC,iFAAiF;IACjF,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,0EAA0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AA+KD,qBAAa,yBAA0B,YAAW,sBAAsB;IAC1D,OAAO,CAAC,QAAQ,CAAC,IAAI;IAAjC,YAA6B,IAAI,EAAE,6BAA6B,EAAI;IAEpE,oEAAoE;IACpE,IAAI,OAAO,IAAI,OAAO,CAErB;IAED;;;;;;OAMG;IACG,QAAQ,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAGvE;CACF"}

package/dist/modules/useCases/LlmInlineUseCaseGenerator.js

@@ -0,0 +1,224 @@
+import { generateText } from 'ai';
+import { describeError, getErrorMessage, resolveScopedModelProvider, runsOnSubscriptionHarness, UnavailableError, } from '@cat-factory/kernel';
+import { catFactoryObservability } from '@cat-factory/agents';
+import { readUseCaseUsage } from './useCaseUsage.js';
+// ---------------------------------------------------------------------------
+// The default {@link InlineUseCaseGenerator}: the inline LLM call behind an invocation of a
+// registered use case.
+//
+// Structurally the `BugHuntAssessorService` twin, and for the same reason: an un-run-scoped inline
+// call built from the model dependencies every facade already wires, so the feature needs no
+// per-facade wiring of its own and the conformance harness swaps in a deterministic fake through
+// the `InlineUseCaseGenerator` seam.
+//
+// Three things differ from every other inline caller. Two follow from the use case being a DECLARED
+// narrowing rather than an engine step:
+//
+//  - There is no block, no task and no preset consult. A use case names its own models, so nothing
+//    a workspace pinned elsewhere may reach in and change which model runs; the workspace's per-kind
+//    preset default would be exactly such a substitution.
+//  - A subscription-harness ref is REFUSED rather than degraded. Every other inline site degrades
+//    one to the routing default (`inlineModelRef`), which is right where the model is an
+//    implementation detail of a step. Here the model IS the request.
+//
+// The third follows from the surface being SYNCHRONOUS: the call is bounded by a deadline and one
+// retry. Every other long-running model path in this repo is a dispatched job with a poll and a
+// watchdog; this one is a request the caller is holding open, so an unbounded vendor stall would be
+// paid for by whoever asked.
+// ---------------------------------------------------------------------------
+/**
+ * How long one invocation may wait on the vendor, by default.
+ *
+ * Generous, because the ceiling on `maxOutputTokens` is 32,000 and a long scene legitimately takes
+ * minutes, but FINITE: the alternative is a request held open for as long as the transport allows,
+ * on a surface whose whole shape is "ask and be answered". A deployment narrows it per facade.
+ */
+export const DEFAULT_USE_CASE_TIMEOUT_MS = 120_000;
+/**
+ * Retries the AI SDK may make inside one invocation.
+ *
+ * ONE, against the SDK's default of two: a transient 429 or 502 is worth a second attempt, and the
+ * third would be spent inside a deadline the caller is already waiting out. The deadline covers all
+ * attempts together (one signal, one absolute expiry), so retrying cannot extend it.
+ */
+const USE_CASE_MAX_RETRIES = 1;
+/**
+ * The AI SDK's finish reasons, mapped to the bounded wire class.
+ *
+ * `tool-calls` cannot occur (no tools are passed) and the SDK's `unknown`/`error` both mean the
+ * provider said nothing usable about why it stopped, so they land on `other` rather than on a
+ * fabricated `stop`. Reporting `stop` for an unknown finish would tell a caller the text is
+ * complete when nothing said so.
+ */
+function mapFinishReason(reason) {
+    switch (reason) {
+        case 'stop':
+            return 'stop';
+        case 'length':
+            return 'length';
+        case 'content-filter':
+            return 'content-filter';
+        default:
+            return 'other';
+    }
+}
+/**
+ * The credential scope, as the model-provider resolver takes it.
+ *
+ * An absent account or user is OMITTED rather than passed as null, because the two are different
+ * instructions to the pool: omitted means "resolve the workspace's owning account yourself", while
+ * an explicit null means "this pool has no account tier". Passing null for an unknown account would
+ * silently drop every account-scoped key.
+ */
+function modelScopeFor(scope) {
+    return {
+        workspaceId: scope.workspaceId,
+        ...(scope.accountId ? { accountId: scope.accountId } : {}),
+        ...(scope.userId ? { userId: scope.userId } : {}),
+    };
+}
+/**
+ * One request's generator: the credential pool, resolved once, plus the two answers that read it.
+ *
+ * Everything expensive happened in {@link LlmInlineUseCaseGenerator.forScope}, which is what makes
+ * `availability` synchronous. A discovery read over a catalog therefore probes every declared
+ * option for free, where a per-option resolution meant an `accountOf` read, a configured-providers
+ * read and a key LEASE (an atomic select-and-mark write plus a decrypt) each time.
+ */
+class ScopedInlineUseCaseSession {
+    deps;
+    scope;
+    provider;
+    constructor(deps, scope, provider) {
+        this.deps = deps;
+        this.scope = scope;
+        this.provider = provider;
+    }
+    availability(option) {
+        const ref = this.refFor(option);
+        if (!ref)
+            return { available: false, reason: 'provider_unavailable' };
+        if (runsOnSubscriptionHarness(ref) && !this.deps.runsInline?.(ref)) {
+            // A subscription harness runs inside a per-run container against a pooled OAuth token. A use
+            // case has no container and no run, so this is a permanent property of the pairing rather
+            // than a missing credential, and it is reported as its own cause. The test goes through
+            // kernel's `runsOnSubscriptionHarness` rather than a local spelling of it, because a ref
+            // carrying `harness: 'pi'` is the case a bare truthiness test gets wrong.
+            return { available: false, reason: 'container_only' };
+        }
+        if (!this.provider)
+            return { available: false, reason: 'provider_unavailable' };
+        try {
+            this.provider.resolve(ref);
+        }
+        catch (error) {
+            // `resolve` throws for a provider id with no registered resolver, which on this platform means
+            // the deployment configured no credentials for it. Logged rather than swallowed: an operator
+            // reading "unavailable" on a model they believe they configured needs the resolver's own
+            // message, which names what IS registered.
+            this.deps.logger?.debug('A use-case model did not resolve', {
+                workspaceId: this.scope.workspaceId,
+                model: option.id,
+                ...describeError(error),
+            });
+            return { available: false, reason: 'provider_unavailable' };
+        }
+        return { available: true, ref };
+    }
+    async generate(request) {
+        // Re-checked rather than trusted, and it costs nothing now that the pool is in hand: the port
+        // is called by the service AND directly by anything else holding a session, so `generate` owns
+        // the same refusal rather than assuming a caller made it.
+        const availability = this.availability(request.option);
+        if (!availability.available) {
+            throw new UnavailableError(`The model '${request.option.label}' cannot be served by this deployment`, 'use_case_model_unavailable', { model: request.option.id, cause: availability.reason });
+        }
+        const provider = this.provider;
+        if (!provider) {
+            throw new UnavailableError('No model provider is configured, so use cases cannot be invoked', 'use_case_models_unconfigured');
+        }
+        const timeoutMs = this.deps.timeoutMs ?? DEFAULT_USE_CASE_TIMEOUT_MS;
+        // ONE signal for the whole call, retries included, so the deadline is an absolute expiry rather
+        // than a per-attempt one. `aborted` is then what tells a timeout from a vendor error, without
+        // sniffing an error shape the SDK is free to change.
+        const deadline = AbortSignal.timeout(timeoutMs);
+        try {
+            const result = await generateText({
+                model: provider.resolve(availability.ref),
+                system: request.system,
+                prompt: request.prompt,
+                temperature: request.temperature,
+                maxOutputTokens: request.maxOutputTokens,
+                abortSignal: deadline,
+                maxRetries: USE_CASE_MAX_RETRIES,
+                // The call is tagged with the use case as its agent kind, so its tokens land in the same
+                // rollups every other inline call does and an operator can see what an editor is spending
+                // per use case rather than as one undifferentiated "inline" bucket.
+                providerOptions: catFactoryObservability({
+                    agentKind: request.useCaseId,
+                    workspaceId: this.scope.workspaceId,
+                }),
+            });
+            return {
+                text: result.text,
+                finishReason: mapFinishReason(result.finishReason),
+                usage: readUseCaseUsage(result.usage),
+                ref: availability.ref,
+            };
+        }
+        catch (error) {
+            throw this.failed(request, error, deadline.aborted ? timeoutMs : undefined);
+        }
+    }
+    /**
+     * The refusal for a call the vendor did not complete.
+     *
+     * A timeout is its OWN reason rather than one more generation failure, because the caller's move
+     * differs: a failed call is worth surfacing to whoever asked, a call that ran out of time is
+     * worth retrying with a smaller reply budget. Collapsing them would hide the only one of the two
+     * that the caller can do something about.
+     */
+    failed(request, error, timedOutAfterMs) {
+        const message = timedOutAfterMs === undefined
+            ? `The use-case model '${request.option.label}' failed: ${getErrorMessage(error)}`
+            : `The use-case model '${request.option.label}' did not answer within ${timedOutAfterMs}ms`;
+        this.deps.logger?.warn(message, {
+            workspaceId: this.scope.workspaceId,
+            useCaseId: request.useCaseId,
+            model: request.option.id,
+            ...describeError(error),
+        });
+        return new UnavailableError(message, timedOutAfterMs === undefined ? 'use_case_generation_failed' : 'use_case_generation_timeout', { model: request.option.id });
+    }
+    /** The ref one declared option resolves to, or undefined when this deployment cannot serve it. */
+    refFor(option) {
+        if (option.source.kind === 'provider')
+            return option.source.ref;
+        // A catalog id resolves under the DEPLOYMENT's default route order rather than a preset's: a
+        // use case is workspace-agnostic by construction (nothing about it is stored per workspace), so
+        // there is no preset in force to read an order off.
+        return this.deps.resolveBlockModel?.(option.source.modelId);
+    }
+}
+export class LlmInlineUseCaseGenerator {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** Whether a generation can run at all (some provider is wired). */
+    get enabled() {
+        return !!this.deps.modelProviderResolver || !!this.deps.modelProvider;
+    }
+    /**
+     * Resolve this request's credential pool ONCE and hand back the session that reads it.
+     *
+     * Not caught here: a pool that could not be read is a fact about the deployment, and each caller
+     * answers it differently (discovery says so per option and still publishes the catalog; an
+     * invocation lets it propagate). Swallowing it here would make both of them guess.
+     */
+    async forScope(scope) {
+        const provider = await resolveScopedModelProvider(modelScopeFor(scope), this.deps);
+        return new ScopedInlineUseCaseSession(this.deps, scope, provider);
+    }
+}
+//# sourceMappingURL=LlmInlineUseCaseGenerator.js.map

package/dist/modules/useCases/LlmInlineUseCaseGenerator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LlmInlineUseCaseGenerator.js","sourceRoot":"","sources":["../../../src/modules/useCases/LlmInlineUseCaseGenerator.ts"],"names":[],"mappings":"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"}

package/dist/modules/useCases/useCaseUsage.d.ts

@@ -0,0 +1,16 @@
+import type { UseCaseUsage } from '@cat-factory/contracts';
+/**
+ * The invocation's usage, as the public surface publishes it.
+ *
+ * The billed input is taken from the vendor's RAW payload through the shared reconciler, and the
+ * SDK's own flat total is the floor rather than the alternative: whichever is larger is the one
+ * that cannot be an understatement, and on every provider mapping in this build the two agree
+ * (each already folds both cache classes into its total). The floor is what keeps a provider that
+ * passes no `raw` through, or one whose payload this build does not recognise, from publishing a 0.
+ *
+ * `totalTokens` is the SUM rather than any total the provider reported, so the three numbers a
+ * caller receives always add up. A published total that disagreed with its own two parts would
+ * leave a consumer no way to tell which of them to trust.
+ */
+export declare function readUseCaseUsage(usage: unknown): UseCaseUsage;
+//# sourceMappingURL=useCaseUsage.d.ts.map

package/dist/modules/useCases/useCaseUsage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useCaseUsage.d.ts","sourceRoot":"","sources":["../../../src/modules/useCases/useCaseUsage.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAA;AAsB1D;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,YAAY,CAS7D"}

package/dist/modules/useCases/useCaseUsage.js

@@ -0,0 +1,40 @@
+import { readInputTokenClasses } from '@cat-factory/agents';
+// ---------------------------------------------------------------------------
+// What one inline use-case invocation cost, read off the AI SDK's usage object into the three
+// numbers the public surface publishes.
+//
+// Its own module with its own test because the reading is NOT the obvious field read. The SDK's
+// flat `inputTokens` is whatever the provider's own mapping put there, and vendors disagree about
+// whether a cached prefix is INSIDE the prompt count (OpenAI: `prompt_tokens` covers it) or BESIDE
+// it (Anthropic: `input_tokens` is fresh-only, with `cache_read_input_tokens` and
+// `cache_creation_input_tokens` alongside). This repo already owns that reconciliation once, in
+// `readInputTokenClasses`, and it is deliberately read here rather than re-spelled: a hand-rolled
+// `usage.inputTokens ?? usage.promptTokens` understates a cache-heavy call on half the vendors,
+// and the surface publishes that number as what was BILLED, which a wrapper metering its own users
+// would then under-bill from silently.
+// ---------------------------------------------------------------------------
+/** A usable token count, else 0. Never coerced, never negative. */
+function count(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : 0;
+}
+/**
+ * The invocation's usage, as the public surface publishes it.
+ *
+ * The billed input is taken from the vendor's RAW payload through the shared reconciler, and the
+ * SDK's own flat total is the floor rather than the alternative: whichever is larger is the one
+ * that cannot be an understatement, and on every provider mapping in this build the two agree
+ * (each already folds both cache classes into its total). The floor is what keeps a provider that
+ * passes no `raw` through, or one whose payload this build does not recognise, from publishing a 0.
+ *
+ * `totalTokens` is the SUM rather than any total the provider reported, so the three numbers a
+ * caller receives always add up. A published total that disagreed with its own two parts would
+ * leave a consumer no way to tell which of them to trust.
+ */
+export function readUseCaseUsage(usage) {
+    const reported = (usage ?? {});
+    const classes = readInputTokenClasses(reported.raw);
+    const inputTokens = Math.max(classes.fresh + classes.cacheRead + classes.cacheWrite, count(reported.inputTokens));
+    const outputTokens = count(reported.outputTokens);
+    return { inputTokens, outputTokens, totalTokens: inputTokens + outputTokens };
+}
+//# sourceMappingURL=useCaseUsage.js.map

package/dist/modules/useCases/useCaseUsage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useCaseUsage.js","sourceRoot":"","sources":["../../../src/modules/useCases/useCaseUsage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAA;AAG3D,8EAA8E;AAC9E,8FAA8F;AAC9F,wCAAwC;AACxC,EAAE;AACF,gGAAgG;AAChG,kGAAkG;AAClG,mGAAmG;AACnG,kFAAkF;AAClF,gGAAgG;AAChG,kGAAkG;AAClG,gGAAgG;AAChG,mGAAmG;AACnG,uCAAuC;AACvC,8EAA8E;AAE9E,mEAAmE;AACnE,SAAS,KAAK,CAAC,KAAc;IAC3B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;AACrF,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,MAAM,QAAQ,GAAG,CAAC,KAAK,IAAI,EAAE,CAA4B,CAAA;IACzD,MAAM,OAAO,GAAG,qBAAqB,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAA;IACnD,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAC1B,OAAO,CAAC,KAAK,GAAG,OAAO,CAAC,SAAS,GAAG,OAAO,CAAC,UAAU,EACtD,KAAK,CAAC,QAAQ,CAAC,WAAW,CAAC,CAC5B,CAAA;IACD,MAAM,YAAY,GAAG,KAAK,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAA;IACjD,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,WAAW,EAAE,WAAW,GAAG,YAAY,EAAE,CAAA;AAC/E,CAAC"}

package/dist/validation/validateInlineUseCases.d.ts

@@ -0,0 +1,30 @@
+import type { InlineUseCaseDefinition } from '@cat-factory/kernel';
+import type { RegistrationProblem } from './validateRegistrations.js';
+/**
+ * Deployment-registered INLINE USE CASES: every way a registration is broken that nothing at run
+ * time can recover from, minus its parameter form (which its host still runs the SHARED descriptor
+ * checker over, alongside every other registered form).
+ *
+ * Its own module rather than more of `validateRegistrations.ts` for the reason the binary-generator
+ * section has one: a cohesive concern with a growing rule set, and a host at its size ratchet.
+ *
+ * All errors, by the bar the rest of that validator uses: each is fully knowable from the
+ * registration itself. Boot is also the only door these ever reach. A use case is code, so no write
+ * boundary refuses it, and every fault below is either silent or MISATTRIBUTED at request time:
+ *
+ *  - a malformed id is unaddressable, because the id IS the path segment;
+ *  - an empty or ambiguously-defaulted model list means an invocation naming no model either cannot
+ *    resolve one or resolves whichever the author happened to list first, which is exactly the
+ *    substitution the narrowing exists to prevent;
+ *  - a bound whose default sits outside its own range refuses every invocation that omits the knob,
+ *    naming a value the caller never sent;
+ *  - a catalog model id nothing resolves publishes as `provider_unavailable`, whose documented
+ *    remedy is "configure the provider": the operator then hunts a key for a model that will never
+ *    resolve, and the two-member reason vocabulary the surface publishes cannot say otherwise;
+ *  - a caption outside the PUBLISHED bounds serves a shape the surface's own OpenAPI calls
+ *    impossible, and silently, because a response is not re-validated on the way out;
+ *  - a blank `systemPrompt` is the one the type comment already argues about: a use case with no
+ *    instruction is an unrestricted model call wearing a name.
+ */
+export declare function inlineUseCaseProblems(useCase: InlineUseCaseDefinition): RegistrationProblem[];
+//# sourceMappingURL=validateInlineUseCases.d.ts.map

package/dist/validation/validateInlineUseCases.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validateInlineUseCases.d.ts","sourceRoot":"","sources":["../../src/validation/validateInlineUseCases.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAA;AAKlE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAA;AAErE;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,uBAAuB,GAAG,mBAAmB,EAAE,CAgB7F"}