@dereekb/openrouter 14.8.0 → 14.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/openrouter",
-  "version": "14.8.0",
+  "version": "14.10.0",
   "sideEffects": false,
   "type": "module",
   "exports": {
@@ -19,19 +19,24 @@
       "types": "./index.d.ts",
       "import": "./index.esm.js",
       "default": "./index.esm.js"
+    },
+    "./decision": {
+      "types": "./decision.d.ts",
+      "import": "./decision.esm.js",
+      "default": "./decision.esm.js"
     }
   },
   "peerDependencies": {
-    "@dereekb/firebase": "14.8.0",
-    "@dereekb/firebase-server": "14.8.0",
-    "@dereekb/model": "14.8.0",
-    "@dereekb/util": "14.8.0",
+    "@dereekb/firebase": "14.10.0",
+    "@dereekb/firebase-server": "14.10.0",
+    "@dereekb/model": "14.10.0",
+    "@dereekb/util": "14.10.0",
     "@nestjs/common": "^12.0.1",
     "@openrouter/sdk": "^1.3.8",
     "arktype": "^2.2.0"
   },
   "devDependencies": {
-    "@dereekb/nestjs": "14.8.0"
+    "@dereekb/nestjs": "14.10.0"
   },
   "module": "./index.esm.js",
   "main": "./index.esm.js",

package/src/decision.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `@dereekb/openrouter/decision` — the System One (Jev) decision layer, loadable WITHOUT evaluating
+ * `@openrouter/sdk`.
+ *
+ * The root `@dereekb/openrouter` entry re-exports SDK values (`callModel`, `responsesSend`,
+ * `systemOneCreate`, …), so importing any value from it evaluates the SDK — a measurable cold-start cost
+ * that a test runner isolating each spec file pays once per file. This entry carries everything a decision
+ * is BUILT from and READ with, and nothing that sends one:
+ *
+ * - the declaration vocabulary — Choice / Score / Noul questions, answers, confidence bands, validation;
+ * - the request, the wire mapping (`openRouterDecisionRequestBody`), the reply reader
+ *   (`readOpenRouterDecisionAnswers`) and its faults, and the usage flattening;
+ * - the model config and the model ids, including the System One routing guard
+ *   (`isOpenRouterSystemOneModelId`).
+ *
+ * The transport, `openRouterDecision`, stays on the root entry because it is the one `systemOneCreate`
+ * caller. A consumer that owns its own transport pairs this entry with its own lazily-loaded client.
+ *
+ * Everything here is ALSO exported from the root entry, from the same modules — the two entries share one
+ * chunk, so a class such as `OpenRouterDecisionAnswerFaultError` has one identity whichever entry a value
+ * was imported through.
+ */
+export * from './lib/openrouter.config';
+export * from './lib/openrouter.decision';
+export * from './lib/openrouter.decision.question';
+export * from './lib/openrouter.type';

package/src/lib/index.d.ts

@@ -1,6 +1,7 @@
 export * from './openrouter.call';
 export * from './openrouter.config';
 export * from './openrouter.decision';
+export * from './openrouter.decision.call';
 export * from './openrouter.decision.question';
 export * from './openrouter.embedding';
 export * from './openrouter.generation';

package/src/lib/openrouter.decision.call.d.ts

@@ -0,0 +1,81 @@
+/**
+ * The TRANSPORT half of the decision layer: {@link openRouterDecision}, the one caller of the SDK's
+ * `systemOneCreate`.
+ *
+ * Kept apart from `openrouter.decision.ts` (declaring, validating, the wire mapping, reading a reply) so
+ * that everything a decision is built from can be loaded without evaluating `@openrouter/sdk` — see the
+ * `@dereekb/openrouter/decision` entry. A caller that owns its own transport (its own timeout, retry
+ * policy or error shape) builds the body with `openRouterDecisionRequestBody` and reads the reply with
+ * `readOpenRouterDecisionAnswers`, and never needs this file.
+ */
+import { type Maybe } from '@dereekb/util';
+import { type OpenRouterDecisionRequest } from './openrouter.decision';
+import { type OpenRouterDecisionAnswers, type OpenRouterDecisionQuestions } from './openrouter.decision.question';
+import { type DecisionsResponse, type OpenRouterCore, type RequestOptions } from './openrouter.sdk';
+import { type OpenRouterGenerationId, type OpenRouterModelId, type OpenRouterRunUsage } from './openrouter.type';
+/**
+ * A normalized result of one decision.
+ *
+ * Field names deliberately match `OpenRouterCallResult` wherever the two have the same meaning, so a
+ * caller reading `model` / `generationIds` / `usage` does not have to learn a second vocabulary for the
+ * second arm. There is no `outputText` or `error`: a decision has no prose output, and the route reports
+ * a failure as a thrown transport error rather than as a field on a 200.
+ */
+export interface OpenRouterDecisionResult<Q extends OpenRouterDecisionQuestions = OpenRouterDecisionQuestions> {
+    /**
+     * The answers, membership-checked against the declared questions.
+     */
+    readonly answers: OpenRouterDecisionAnswers<Q>;
+    /**
+     * The model that actually served the decision — a VERSIONED slug even when an alias was asked for,
+     * which is what makes an answer reproducible.
+     */
+    readonly model?: Maybe<OpenRouterModelId>;
+    /**
+     * The provider that served it.
+     */
+    readonly provider?: Maybe<string>;
+    /**
+     * Generation ids produced, for auditing. At most one on this route.
+     */
+    readonly generationIds: OpenRouterGenerationId[];
+    /**
+     * Token/cost usage.
+     */
+    readonly usage?: Maybe<OpenRouterRunUsage>;
+    /**
+     * The raw response, for anything the normalized shape drops.
+     */
+    readonly response: DecisionsResponse;
+}
+/**
+ * Params for {@link openRouterDecision}.
+ */
+export interface OpenRouterDecisionParams<Q extends OpenRouterDecisionQuestions = OpenRouterDecisionQuestions> {
+    /**
+     * The OpenRouter client.
+     */
+    readonly client: OpenRouterCore;
+    /**
+     * The built request.
+     */
+    readonly request: OpenRouterDecisionRequest<Q>;
+    /**
+     * Additional request options, merged under the config's `requestTimeoutMs`.
+     */
+    readonly options?: Maybe<RequestOptions>;
+}
+/**
+ * Asks a decision and returns its answers.
+ *
+ * The request is validated first, so a model that cannot serve a decision is refused HERE rather than by
+ * the route — the mirror of the refusal `callModelForOpenRouterRequest` makes for a System One model on
+ * the completion arm. Which surface a request belongs to is a property of the request, not a choice the
+ * caller makes at the call site.
+ *
+ * @param params - The client, request, and options.
+ * @returns The normalized decision result.
+ * @throws {OpenRouterDecisionDeclarationError} When the request cannot be asked as declared.
+ * @throws {OpenRouterDecisionAnswerFaultError} When the reply did not answer the declared questions.
+ */
+export declare function openRouterDecision<Q extends OpenRouterDecisionQuestions = OpenRouterDecisionQuestions>(params: OpenRouterDecisionParams<Q>): Promise<OpenRouterDecisionResult<Q>>;

package/src/lib/openrouter.decision.d.ts

@@ -3,8 +3,8 @@ import { type OpenRouterModelConfig, type OpenRouterModelConfigValidation } from
 import { type OpenRouterDecisionAnswer, type OpenRouterDecisionAnswers, type OpenRouterDecisionEntry, type OpenRouterDecisionQuestion, type OpenRouterDecisionQuestionId, type OpenRouterDecisionQuestions, type OpenRouterDecisionState } from './openrouter.decision.question';
 import { type OpenRouterResolvedPrompt } from './openrouter.prompt';
 import { type OpenRouterRequestTrace } from './openrouter.request';
-import { type DecisionsRequest, type DecisionsResponse, type OpenRouterCore, type RequestOptions } from './openrouter.sdk';
-import { type OpenRouterGenerationId, type OpenRouterModelId, type OpenRouterRunUsage } from './openrouter.type';
+import type { DecisionsRequest, DecisionsResponse } from './openrouter.sdk';
+import { type OpenRouterRunUsage } from './openrouter.type';
 /**
  * How far a distribution's probabilities may sum from 1 before the reply is read as malformed.
  *
@@ -284,69 +284,3 @@ export declare function readOpenRouterDecisionAnswers<Q extends OpenRouterDecisi
  * @__NO_SIDE_EFFECTS__
  */
 export declare function openRouterRunUsageFromDecisionsUsage(usage: Maybe<DecisionsResponse['usage']>): Maybe<OpenRouterRunUsage>;
-/**
- * A normalized result of one decision.
- *
- * Field names deliberately match `OpenRouterCallResult` wherever the two have the same meaning, so a
- * caller reading `model` / `generationIds` / `usage` does not have to learn a second vocabulary for the
- * second arm. There is no `outputText` or `error`: a decision has no prose output, and the route reports
- * a failure as a thrown transport error rather than as a field on a 200.
- */
-export interface OpenRouterDecisionResult<Q extends OpenRouterDecisionQuestions = OpenRouterDecisionQuestions> {
-    /**
-     * The answers, membership-checked against the declared questions.
-     */
-    readonly answers: OpenRouterDecisionAnswers<Q>;
-    /**
-     * The model that actually served the decision — a VERSIONED slug even when an alias was asked for,
-     * which is what makes an answer reproducible.
-     */
-    readonly model?: Maybe<OpenRouterModelId>;
-    /**
-     * The provider that served it.
-     */
-    readonly provider?: Maybe<string>;
-    /**
-     * Generation ids produced, for auditing. At most one on this route.
-     */
-    readonly generationIds: OpenRouterGenerationId[];
-    /**
-     * Token/cost usage.
-     */
-    readonly usage?: Maybe<OpenRouterRunUsage>;
-    /**
-     * The raw response, for anything the normalized shape drops.
-     */
-    readonly response: DecisionsResponse;
-}
-/**
- * Params for {@link openRouterDecision}.
- */
-export interface OpenRouterDecisionParams<Q extends OpenRouterDecisionQuestions = OpenRouterDecisionQuestions> {
-    /**
-     * The OpenRouter client.
-     */
-    readonly client: OpenRouterCore;
-    /**
-     * The built request.
-     */
-    readonly request: OpenRouterDecisionRequest<Q>;
-    /**
-     * Additional request options, merged under the config's `requestTimeoutMs`.
-     */
-    readonly options?: Maybe<RequestOptions>;
-}
-/**
- * Asks a decision and returns its answers.
- *
- * The request is validated first, so a model that cannot serve a decision is refused HERE rather than by
- * the route — the mirror of the refusal `callModelForOpenRouterRequest` makes for a System One model on
- * the completion arm. Which surface a request belongs to is a property of the request, not a choice the
- * caller makes at the call site.
- *
- * @param params - The client, request, and options.
- * @returns The normalized decision result.
- * @throws {OpenRouterDecisionDeclarationError} When the request cannot be asked as declared.
- * @throws {OpenRouterDecisionAnswerFaultError} When the reply did not answer the declared questions.
- */
-export declare function openRouterDecision<Q extends OpenRouterDecisionQuestions = OpenRouterDecisionQuestions>(params: OpenRouterDecisionParams<Q>): Promise<OpenRouterDecisionResult<Q>>;

package/src/lib/openrouter.decision.question.d.ts

@@ -26,24 +26,29 @@ export type OpenRouterDecisionEntry = string | Readonly<Record<string, unknown>>
  *
  * `inspect` and `compare` name parts of the state, in the same backticked dot-path convention prose
  * instructions use.
+ *
+ * A `type` alias, not an `interface`, and deliberately so for all three structured shapes: an interface
+ * has no implicit index signature, so a value typed as one is NOT assignable to the
+ * `Readonly<Record<string, unknown>>` arm of {@link OpenRouterDecisionEntry} — a structured entry
+ * declared through its own name would then be refused by the very builders it exists to feed.
  */
-export interface OpenRouterDecisionStructuredInstructions {
+export type OpenRouterDecisionStructuredInstructions = {
     readonly question: string;
     readonly focus?: Maybe<string>;
     readonly inspect?: Maybe<string | ReadonlyArray<string>>;
     readonly compare?: Maybe<ReadonlyArray<string>>;
-}
+};
 /**
  * A structured Choice option.
  *
  * CONTRASTIVE by design: use the SAME keys on every option of a question so the model compares like
  * with like. `not_for` is where an option's boundary against its neighbours goes.
  */
-export interface OpenRouterDecisionStructuredCriterion {
+export type OpenRouterDecisionStructuredCriterion = {
     readonly what: string;
     readonly not_for?: Maybe<string>;
     readonly examples?: Maybe<ReadonlyArray<string>>;
-}
+};
 /**
  * A structured Score level.
  *
@@ -51,11 +56,11 @@ export interface OpenRouterDecisionStructuredCriterion {
  * model something to match the state against, where "moderately severe" does not. Use the same keys on
  * every level of a question.
  */
-export interface OpenRouterDecisionStructuredLevel {
+export type OpenRouterDecisionStructuredLevel = {
     readonly what: string;
     readonly signals?: Maybe<ReadonlyArray<string>>;
     readonly examples?: Maybe<ReadonlyArray<string>>;
-}
+};
 /**
  * The declared options of a Choice, keyed by the option name the answer will quote.
  *
@@ -260,7 +265,9 @@ export declare function openRouterDecisionChoiceOptionNames<O extends string = s
  * Reads a confidence as a band.
  *
  * An ABSENT confidence reads `low` rather than throwing: the model is not required to report one, and a
- * caller that branches on the band should treat "did not say" the same as "not sure".
+ * caller that branches on the band should treat "did not say" the same as "not sure". A non-finite one
+ * (`NaN`, `Infinity`) reads `low` for the same reason — a garbled number is not a report of certainty,
+ * and without the guard `NaN` fails every comparison below and falls through to `medium`.
  *
  * @param confidence - The reported confidence, if any.
  * @returns The band.