@hourslabs/domovoi 0.1.0

package/dist/calibration/index.js

@@ -0,0 +1,95 @@
+// src/errors.ts
+var DomovoiError = class extends Error {
+  code;
+  constructor(message, options) {
+    super(message, options?.cause !== void 0 ? { cause: options.cause } : void 0);
+    this.name = "DomovoiError";
+    this.code = options?.code ?? "unspecified";
+  }
+};
+var ConfigError = class extends DomovoiError {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "ConfigError";
+  }
+};
+
+// src/calibration/index.ts
+var identity = {
+  kind: "identity",
+  apply(d) {
+    return d;
+  }
+};
+function temperatureScaling(T) {
+  if (Number.isNaN(T) || T <= 0) {
+    throw new ConfigError(`temperatureScaling(T): T must be > 0; got ${T}.`, {
+      code: "incompatible_calibrator"
+    });
+  }
+  const inverseT = 1 / T;
+  return {
+    kind: "temperature",
+    apply(d) {
+      const scaledEntries = Object.entries(d.probs).map(
+        ([label, prob]) => [label, prob === 0 ? 0 : prob ** inverseT]
+      );
+      const partitionFn = scaledEntries.reduce(
+        (running, [, scaledProb]) => running + scaledProb,
+        0
+      );
+      if (partitionFn === 0) return d;
+      const normalizedProbs = Object.fromEntries(
+        scaledEntries.map(([label, scaledProb]) => [label, scaledProb / partitionFn])
+      );
+      return {
+        probs: normalizedProbs,
+        coverage: d.coverage
+      };
+    }
+  };
+}
+function plattScaling(params) {
+  if (Number.isNaN(params.a) || Number.isNaN(params.b) || !Number.isFinite(params.a) || !Number.isFinite(params.b)) {
+    throw new ConfigError(
+      `plattScaling({ a, b }): a and b must be finite numbers; got a=${params.a}, b=${params.b}.`,
+      { code: "incompatible_calibrator" }
+    );
+  }
+  return {
+    kind: "platt",
+    apply(d) {
+      const labels = Object.keys(d.probs);
+      if (labels.length !== 2) {
+        throw new ConfigError(
+          `plattScaling is binary-only; got distribution with ${labels.length} labels.`,
+          { code: "incompatible_calibrator" }
+        );
+      }
+      const [neg, pos] = labels;
+      const probs = d.probs;
+      const pPos = probs[pos] ?? 0;
+      const eps = 1e-9;
+      const clamped = Math.min(1 - eps, Math.max(eps, pPos));
+      const logit = Math.log(clamped / (1 - clamped));
+      const calibratedPos = sigmoid(params.a * logit + params.b);
+      return {
+        probs: {
+          [neg]: 1 - calibratedPos,
+          [pos]: calibratedPos
+        },
+        coverage: d.coverage
+      };
+    }
+  };
+}
+function sigmoid(x) {
+  return 1 / (1 + Math.exp(-x));
+}
+function isIdentityCalibrator(c) {
+  return c.kind === "identity";
+}
+
+export { identity, isIdentityCalibrator, plattScaling, temperatureScaling };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/calibration/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/errors.ts","../../src/calibration/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Error taxonomy for domovoi.\n *\n * Four classes (`DomovoiError` base + `ProviderError`, `ConfigError`,\n * `BudgetExhaustedError`) with a stable `code` field for fine-grained\n * discrimination. All accept `{ cause }` for ES2022 chaining.\n *\n * The engine canonicalizes anything thrown from `Provider.sample` that isn't\n * already a `DomovoiError` into `ProviderError({ cause })`, so callers always\n * see a known error type. Under the default `onErrorPolicy: \"fallback\"`,\n * runtime errors become `Unknown` Verdict variants rather than throw;\n * `ConfigError` always throws.\n */\n\n/**\n * Stable error codes carried in `error.code`. Discriminate on these rather\n * than on `instanceof` of removed-historical subclasses.\n */\nexport type ErrorCode =\n  // ConfigError — construction-time\n  | \"decision_space_collision\"\n  | \"decision_space_too_large\"\n  | \"missing_provider_config\"\n  | \"malformed_provider_config\"\n  | \"unknown_provider_factory\"\n  | \"missing_credential\"\n  | \"incompatible_calibrator\"\n  | \"invalid_classifier_name\"\n  | \"invalid_thresholds\"\n  | \"invalid_space\"\n  | \"empty_providers\"\n  // ProviderError — runtime\n  | \"provider_network\"\n  | \"provider_rate_limit\"\n  | \"provider_timeout\"\n  | \"provider_unauthorized\"\n  | \"provider_server_error\"\n  | \"provider_malformed_response\"\n  | \"invalid_distribution\"\n  // BudgetExhaustedError — runtime\n  | \"per_call_timeout\"\n  | \"chain_timeout\"\n  | \"max_calls\";\n\nexport class DomovoiError extends Error {\n  readonly code: string;\n\n  constructor(message: string, options?: { code?: string; cause?: unknown }) {\n    super(message, options?.cause !== undefined ? { cause: options.cause } : undefined);\n    this.name = \"DomovoiError\";\n    this.code = options?.code ?? \"unspecified\";\n  }\n}\n\nexport class ProviderError extends DomovoiError {\n  constructor(message: string, options?: { code?: string; cause?: unknown }) {\n    super(message, options);\n    this.name = \"ProviderError\";\n  }\n}\n\nexport class ConfigError extends DomovoiError {\n  constructor(message: string, options?: { code?: string; cause?: unknown }) {\n    super(message, options);\n    this.name = \"ConfigError\";\n  }\n}\n\nexport class BudgetExhaustedError extends DomovoiError {\n  readonly attemptedProviders: readonly string[];\n  readonly elapsedMs: number;\n  readonly scope: \"per_call_timeout\" | \"chain_timeout\" | \"max_calls\";\n\n  constructor(\n    message: string,\n    options: {\n      scope: \"per_call_timeout\" | \"chain_timeout\" | \"max_calls\";\n      attemptedProviders: readonly string[];\n      elapsedMs: number;\n      cause?: unknown;\n    },\n  ) {\n    super(message, { code: options.scope, cause: options.cause });\n    this.name = \"BudgetExhaustedError\";\n    this.scope = options.scope;\n    this.attemptedProviders = options.attemptedProviders;\n    this.elapsedMs = options.elapsedMs;\n  }\n}\n\n/**\n * Wraps any non-DomovoiError thrown value in `ProviderError({ cause })`.\n * `DomovoiError` subtypes — including `ProviderError` subclasses defined by\n * external Provider implementations — pass through unchanged.\n */\nexport function canonicalizeProviderThrow(thrown: unknown): DomovoiError {\n  if (thrown instanceof DomovoiError) return thrown;\n  if (thrown instanceof Error) {\n    return new ProviderError(thrown.message || \"Provider call failed\", {\n      code: \"provider_network\",\n      cause: thrown,\n    });\n  }\n  return new ProviderError(String(thrown), {\n    code: \"provider_network\",\n    cause: thrown,\n  });\n}\n\n/**\n * Convert an Error to the JSON-safe shape stored in\n * `Verdict.meta.providerErrors`. Cause chains are preserved recursively.\n */\nexport function serializeError(err: unknown): {\n  readonly name: string;\n  readonly message: string;\n  readonly code?: string;\n  readonly cause?: ReturnType<typeof serializeError>;\n  readonly stack?: string;\n} {\n  if (!(err instanceof Error)) {\n    return { name: \"Error\", message: String(err) };\n  }\n  const code = err instanceof DomovoiError ? err.code : undefined;\n  const cause = err.cause !== undefined ? serializeError(err.cause) : undefined;\n  return {\n    name: err.name,\n    message: err.message,\n    ...(code !== undefined ? { code } : {}),\n    ...(cause !== undefined ? { cause } : {}),\n    ...(err.stack !== undefined ? { stack: err.stack } : {}),\n  };\n}\n","/**\n * Built-in calibrator factories.\n *\n *   - `identity` — pass-through; the default.\n *   - `temperatureScaling(T)` — `p^(1/T) / Σ p_j^(1/T)`; equivalent to\n *     scaling logits before softmax.\n *   - `plattScaling({ a, b })` — sigmoid scaling; binary spaces only.\n *\n * `Calibrator.apply` must be pure and stateless. The engine runs it\n * per-caller after the Distribution is loaded from the cache, so impurity\n * would leak across callers sharing a cache row.\n */\n\nimport { ConfigError } from \"../errors.js\";\nimport type { Distribution } from \"../types.js\";\n\nexport interface Calibrator {\n  /** Identifier; `\"identity\"` is reserved and recognized by the engine. */\n  readonly kind: string;\n  apply<T extends string>(d: Distribution<T>): Distribution<T>;\n}\n\nexport const identity: Calibrator = {\n  kind: \"identity\",\n  apply<T extends string>(d: Distribution<T>): Distribution<T> {\n    return d;\n  },\n};\n\n/**\n *   - `T = 1` → identity.\n *   - `T > 1` → softens (less peaked).\n *   - `T < 1` → sharpens (more peaked).\n *\n * Operates on probabilities (not logits) and leaves `coverage` unchanged.\n * Throws `ConfigError` on `T <= 0`.\n *\n * @example\n *   calibrator: temperatureScaling(0.85)  // user-fit on held-out eval set\n */\nexport function temperatureScaling(T: number): Calibrator {\n  if (Number.isNaN(T) || T <= 0) {\n    throw new ConfigError(`temperatureScaling(T): T must be > 0; got ${T}.`, {\n      code: \"incompatible_calibrator\",\n    });\n  }\n  const inverseT = 1 / T;\n  return {\n    kind: \"temperature\",\n    apply<U extends string>(d: Distribution<U>): Distribution<U> {\n      const scaledEntries = (Object.entries(d.probs) as [string, number][]).map(\n        ([label, prob]) => [label, prob === 0 ? 0 : prob ** inverseT] as const,\n      );\n      const partitionFn = scaledEntries.reduce(\n        (running, [, scaledProb]) => running + scaledProb,\n        0,\n      );\n      // Degenerate input (every prob is 0) — return as-is rather than divide by 0.\n      if (partitionFn === 0) return d;\n      const normalizedProbs = Object.fromEntries(\n        scaledEntries.map(([label, scaledProb]) => [label, scaledProb / partitionFn] as const),\n      );\n      return {\n        probs: normalizedProbs as Distribution<U>[\"probs\"],\n        coverage: d.coverage,\n      };\n    },\n  };\n}\n\n/**\n * Platt scaling: `sigmoid(a*z + b)` where `z = logit(p_pos)`.\n *\n * Binary-only — the second label in the distribution (in user-given order)\n * is treated as the positive class. Construction-time space-size validation\n * happens in the classifier; `apply()` re-checks at runtime as a defensive\n * guard against direct misuse.\n */\nexport function plattScaling(params: { a: number; b: number }): Calibrator {\n  if (\n    Number.isNaN(params.a) ||\n    Number.isNaN(params.b) ||\n    !Number.isFinite(params.a) ||\n    !Number.isFinite(params.b)\n  ) {\n    throw new ConfigError(\n      `plattScaling({ a, b }): a and b must be finite numbers; got a=${params.a}, b=${params.b}.`,\n      { code: \"incompatible_calibrator\" },\n    );\n  }\n  return {\n    kind: \"platt\",\n    apply<U extends string>(d: Distribution<U>): Distribution<U> {\n      const labels = Object.keys(d.probs);\n      if (labels.length !== 2) {\n        throw new ConfigError(\n          `plattScaling is binary-only; got distribution with ${labels.length} labels.`,\n          { code: \"incompatible_calibrator\" },\n        );\n      }\n      const [neg, pos] = labels as [string, string];\n      const probs = d.probs as Record<string, number>;\n      const pPos = probs[pos] ?? 0;\n      // Clamp away from {0, 1} so `Math.log(p / (1 - p))` is finite.\n      const eps = 1e-9;\n      const clamped = Math.min(1 - eps, Math.max(eps, pPos));\n      const logit = Math.log(clamped / (1 - clamped));\n      const calibratedPos = sigmoid(params.a * logit + params.b);\n      return {\n        probs: {\n          [neg]: 1 - calibratedPos,\n          [pos]: calibratedPos,\n        } as Distribution<U>[\"probs\"],\n        coverage: d.coverage,\n      };\n    },\n  };\n}\n\nfunction sigmoid(x: number): number {\n  return 1 / (1 + Math.exp(-x));\n}\n\nexport function isIdentityCalibrator(c: Calibrator): boolean {\n  return c.kind === \"identity\";\n}\n"]}

package/dist/engine/abort.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Abort and budget utilities.
+ *
+ * Engine signal merging: user signal + per-call timeout merge into a single
+ * `AbortSignal.any` that's passed to the provider. When the merged signal
+ * aborts, we discriminate on the abort reason to decide whether the
+ * resulting Verdict is `Unknown { cancelled }` (user-initiated) or
+ * `Unknown { budget_exhausted, scope: "per_call_timeout" }` (timeout-initiated).
+ *
+ * AggregateError construction: under `onErrorPolicy: "throw"` and full-chain
+ * provider failure, we throw `AggregateError` containing rehydrated `Error`
+ * instances. `deserializeForAggregate` walks the SerializableError shape back
+ * into Error instances with `cause` chaining preserved.
+ */
+import type { Provider } from "../providers/provider.js";
+import type { SerializableError, Unknown } from "../types.js";
+import type { MetaBuilder } from "./meta.js";
+/**
+ * Returns a human-readable string describing why a signal aborted, or
+ * `undefined` if the signal isn't aborted (or wasn't supplied).
+ */
+export declare function abortReason(signal: AbortSignal | undefined): string | undefined;
+/**
+ * Detects whether a merged signal's abort came from `AbortSignal.timeout(...)`.
+ * The timeout path produces a DOMException with `name === "TimeoutError"`.
+ */
+export declare function isTimeoutAbort(signal: AbortSignal): boolean;
+export declare function buildCancelledVerdict<T extends string>(meta: MetaBuilder, reason: string, provider: Provider): Unknown<T>;
+type BudgetScope = "per_call_timeout" | "chain_timeout" | "max_calls";
+/**
+ * Build `Unknown { budget_exhausted, scope }` for `onErrorPolicy: "fallback"`.
+ * Returns `undefined` under `"throw"` policy — the engine throws
+ * `BudgetExhaustedError` instead.
+ */
+export declare function buildBudgetExhaustedVerdict<T extends string>(meta: MetaBuilder, scope: BudgetScope, policy: "fallback" | "throw", provider?: Provider): Unknown<T> | undefined;
+/**
+ * Rehydrate a `SerializableError` (the JSON-safe shape stored in
+ * `meta.providerErrors`) back into an `Error` instance suitable for
+ * `AggregateError`. Cause chains are reconstructed recursively.
+ */
+export declare function deserializeForAggregate(serialized: SerializableError): Error;
+export {};
+//# sourceMappingURL=abort.d.ts.map

package/dist/engine/abort.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"abort.d.ts","sourceRoot":"","sources":["../../src/engine/abort.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACzD,OAAO,KAAK,EAAE,iBAAiB,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAG7C;;;GAGG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAO/E;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAG3D;AAED,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,MAAM,EACpD,IAAI,EAAE,WAAW,EACjB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,QAAQ,GACjB,OAAO,CAAC,CAAC,CAAC,CAMZ;AAED,KAAK,WAAW,GAAG,kBAAkB,GAAG,eAAe,GAAG,WAAW,CAAC;AAEtE;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,CAAC,SAAS,MAAM,EAC1D,IAAI,EAAE,WAAW,EACjB,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,UAAU,GAAG,OAAO,EAC5B,QAAQ,CAAC,EAAE,QAAQ,GAClB,OAAO,CAAC,CAAC,CAAC,GAAG,SAAS,CAOxB;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,UAAU,EAAE,iBAAiB,GAAG,KAAK,CAY5E"}

package/dist/engine/config.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Engine configuration: `DecideConfig`, defaults, validation, and the
+ * `withDefaults` builder used by verbs and one-shots.
+ *
+ * `DecideConfig` is the engine's internal contract — verbs (boolean,
+ * classify, classifier) translate user-facing options into this shape.
+ */
+import { type Cache } from "../cache.js";
+import type { Calibrator } from "../calibration/index.js";
+import type { ProviderError } from "../errors.js";
+import type { Provider } from "../providers/provider.js";
+import type { Budget, PromptTemplate, Thresholds } from "../types.js";
+export declare const DEFAULT_PER_CALL_TIMEOUT_MS = 10000;
+export declare const DEFAULT_CHAIN_TIMEOUT_MS = 30000;
+type OnProviderErrorHook = (err: ProviderError, ctx: {
+    providerId: string;
+    attempt: number;
+}) => void | Promise<void>;
+type EngineHooks = {
+    onCall?: (...args: unknown[]) => void | Promise<void>;
+    onResult?: (...args: unknown[]) => void | Promise<void>;
+};
+export type DecideConfig<T extends string> = {
+    readonly space: readonly T[];
+    readonly thresholds: Thresholds<readonly T[]>;
+    readonly providers: readonly Provider[];
+    readonly calibrator: Calibrator;
+    readonly cache: Cache;
+    readonly template: PromptTemplate;
+    readonly question?: string;
+    readonly budget?: Budget;
+    readonly onErrorPolicy: "fallback" | "throw";
+    readonly onProviderError?: OnProviderErrorHook;
+    readonly hooks?: EngineHooks;
+    /**
+     * Stable hash of provider-specific options that affect Distribution shape
+     * (e.g. `multiSampleN`). Mixed into the cache key so changing those opts is
+     * a cache miss. Empty string when the provider has no such options.
+     */
+    readonly providerConfigHash: string;
+    readonly temperature: number;
+};
+type DecideConfigInput<T extends string> = {
+    readonly space: readonly T[];
+    readonly thresholds: Thresholds<readonly T[]>;
+    readonly providers: readonly Provider[];
+    readonly calibrator?: Calibrator;
+    readonly cache?: Cache;
+    readonly template?: PromptTemplate;
+    readonly question?: string;
+    readonly budget?: Budget;
+    readonly onErrorPolicy?: "fallback" | "throw";
+    readonly onProviderError?: OnProviderErrorHook;
+    readonly hooks?: EngineHooks;
+    readonly providerConfigHash?: string;
+};
+/**
+ * Materialize a fully-defaulted `DecideConfig` from a partial input. Used by
+ * verbs to translate caller-facing options into the engine's internal shape.
+ */
+export declare function withDefaults<T extends string>(input: DecideConfigInput<T>): DecideConfig<T>;
+type ValidateClassifierConfigInput<T extends string> = {
+    readonly name?: string;
+    readonly space: readonly T[];
+    readonly thresholds: Thresholds<readonly T[]>;
+    readonly providers: readonly Provider[];
+    readonly calibrator: Calibrator;
+};
+/**
+ * Validate a classifier configuration at construction. Throws `ConfigError`
+ * with the relevant `code` on first failure; never partially configures.
+ *
+ * Each registered provider's optional `validate(space)` hook fires last —
+ * giving tokenizer-aware adapters (e.g. OpenAI) a chance to surface
+ * first-token collisions eagerly, before any network I/O.
+ */
+export declare function validateClassifierConfig<T extends string>(input: ValidateClassifierConfigInput<T>): void;
+export {};
+//# sourceMappingURL=config.d.ts.map

package/dist/engine/config.d.ts.map

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

package/dist/engine/decide.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `decide()` — the engine orchestrator. Walks the provider chain, dispatching
+ * each attempt's outcome (`Verdict` / `lastUncertain` / `continue`) into the
+ * right terminal path.
+ *
+ * Single-responsibility helpers handle the heavy lifting:
+ *   - cache + provider call → `engine/distribution.ts`
+ *   - error → outcome translation → `engine/error-recording.ts`
+ *   - terminal Verdict construction → `engine/finalize.ts`
+ *
+ * Errors during the chain become `Unknown` Verdicts under the default
+ * `onErrorPolicy: "fallback"`; under `"throw"` they propagate as
+ * `BudgetExhaustedError` / `AbortError` / `AggregateError`.
+ */
+import type { Verdict } from "../types.js";
+import { type DecideConfig } from "./config.js";
+export declare function decide<T extends string>(formattedInput: string, config: DecideConfig<T>, signal?: AbortSignal): Promise<Verdict<T>>;
+//# sourceMappingURL=decide.d.ts.map

package/dist/engine/decide.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decide.d.ts","sourceRoot":"","sources":["../../src/engine/decide.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAgD,OAAO,EAAE,MAAM,aAAa,CAAC;AAGzF,OAAO,EAGL,KAAK,YAAY,EAClB,MAAM,aAAa,CAAC;AAYrB,wBAAsB,MAAM,CAAC,CAAC,SAAS,MAAM,EAC3C,cAAc,EAAE,MAAM,EACtB,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,EACvB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CA8DrB"}

package/dist/engine/distribution.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Cache lookup, in-flight dedup, and per-attempt cache-key composition.
+ * The provider call itself happens inside `loadDistribution`; the engine
+ * orchestrator never invokes `Provider.sample` directly.
+ */
+import type { Provider } from "../providers/provider.js";
+import type { Distribution } from "../types.js";
+import { type DecideConfig } from "./config.js";
+import type { MetaBuilder } from "./meta.js";
+export declare function computeProviderCacheKey<T extends string>(provider: Provider, formattedInput: string, config: DecideConfig<T>): string;
+export declare function mergeSignals(userSignal: AbortSignal | undefined, timeoutSignal: AbortSignal): AbortSignal;
+export declare function loadDistribution<T extends string>(provider: Provider, formattedInput: string, config: DecideConfig<T>, meta: MetaBuilder, signal: AbortSignal, cacheKey: string): Promise<Distribution<T>>;
+/**
+ * Drop the in-flight slot for a key after a failed sample so a concurrent
+ * caller in another classifier doesn't keep getting served the failed Promise.
+ */
+export declare function forgetInFlight(cacheKey: string): void;
+//# sourceMappingURL=distribution.d.ts.map

package/dist/engine/distribution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"distribution.d.ts","sourceRoot":"","sources":["../../src/engine/distribution.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAQH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACzD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAA+B,KAAK,YAAY,EAAE,MAAM,aAAa,CAAC;AAC7E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAS7C,wBAAgB,uBAAuB,CAAC,CAAC,SAAS,MAAM,EACtD,QAAQ,EAAE,QAAQ,EAClB,cAAc,EAAE,MAAM,EACtB,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,GACtB,MAAM,CAWR;AAED,wBAAgB,YAAY,CAC1B,UAAU,EAAE,WAAW,GAAG,SAAS,EACnC,aAAa,EAAE,WAAW,GACzB,WAAW,CAIb;AAED,wBAAsB,gBAAgB,CAAC,CAAC,SAAS,MAAM,EACrD,QAAQ,EAAE,QAAQ,EAClB,cAAc,EAAE,MAAM,EACtB,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,EACvB,IAAI,EAAE,WAAW,EACjB,MAAM,EAAE,WAAW,EACnB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAa1B;AAmBD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAErD"}

package/dist/engine/error-recording.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Error-handling helpers for `decide()`'s attempt loop. Translates raw
+ * exceptions thrown from the provider/cache/validation path into either
+ * a terminal `Verdict` (for cancellation, budget exhaustion) or a
+ * "continue chain" signal (for swallowable `ProviderError`).
+ *
+ * Distinguishes between three error sources: per-call timeout, user
+ * cancellation, and provider-side failure. Each produces a different
+ * `AttemptOutcome` shape that the orchestrator dispatches on.
+ */
+import type { Provider } from "../providers/provider.js";
+import type { Distribution, Uncertain, Verdict } from "../types.js";
+import type { DecideConfig } from "./config.js";
+import type { MetaBuilder } from "./meta.js";
+/**
+ * Outcome of a single provider attempt within `decide()`. The orchestrator
+ * dispatches on this:
+ *   - `verdict`: terminal — return immediately.
+ *   - `lastUncertain`: terminal-if-last-provider — return Uncertain Verdict.
+ *   - `continue`: try the next provider (after recording any error in meta).
+ */
+export type AttemptOutcome<T extends string> = {
+    kind: "verdict";
+    verdict: Verdict<T>;
+} | {
+    kind: "lastUncertain";
+    verdict: Uncertain<T>;
+    calibrated: Distribution<T>;
+} | {
+    kind: "continue";
+    calibrated?: Distribution<T>;
+};
+export declare function handleDistributionError<T extends string>(err: unknown, provider: Provider, meta: MetaBuilder, config: DecideConfig<T>, userSignal: AbortSignal | undefined, timeoutSignal: AbortSignal, index: number, chainStartMs: number, cacheKey: string): AttemptOutcome<T>;
+export declare function recordValidationError<T extends string>(err: unknown, provider: Provider, meta: MetaBuilder, config: DecideConfig<T>, index: number, cacheKey: string): AttemptOutcome<T>;
+//# sourceMappingURL=error-recording.d.ts.map

package/dist/engine/error-recording.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-recording.d.ts","sourceRoot":"","sources":["../../src/engine/error-recording.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAQH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACzD,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAOpE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAGhD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAE7C;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,MAAM,IACvC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,CAAA;CAAE,GACxC;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC;IAAC,UAAU,EAAE,YAAY,CAAC,CAAC,CAAC,CAAA;CAAE,GAC7E;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,UAAU,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC,CAAA;CAAE,CAAC;AAEvD,wBAAgB,uBAAuB,CAAC,CAAC,SAAS,MAAM,EACtD,GAAG,EAAE,OAAO,EACZ,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,WAAW,EACjB,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,EACvB,UAAU,EAAE,WAAW,GAAG,SAAS,EACnC,aAAa,EAAE,WAAW,EAC1B,KAAK,EAAE,MAAM,EACb,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,GACf,cAAc,CAAC,CAAC,CAAC,CAwBnB;AAwBD,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,MAAM,EACpD,GAAG,EAAE,OAAO,EACZ,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,WAAW,EACjB,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,EACvB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,GACf,cAAc,CAAC,CAAC,CAAC,CAUnB"}

package/dist/engine/finalize.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Terminal-Verdict construction for `decide()`'s exit paths:
+ * chain-budget exhaustion, pre/mid-loop cancellation, and chain-exhausted
+ * (every-provider-errored vs last-provider-uncertain).
+ */
+import type { Distribution, Unknown, Verdict } from "../types.js";
+import type { DecideConfig } from "./config.js";
+import { type MetaBuilder } from "./meta.js";
+export declare function checkChainBudget<T extends string>(meta: MetaBuilder, chainStartMs: number, chainTimeoutMs: number, config: DecideConfig<T>): Unknown<T> | undefined;
+export declare function makeCancelledFromMeta<T extends string>(meta: MetaBuilder, reason: string): Unknown<T>;
+export declare function finalizeChainExhausted<T extends string>(meta: MetaBuilder, lastCalibrated: Distribution<T> | undefined, attempts: number, config: DecideConfig<T>): Verdict<T>;
+//# sourceMappingURL=finalize.d.ts.map

package/dist/engine/finalize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"finalize.d.ts","sourceRoot":"","sources":["../../src/engine/finalize.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAElE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,OAAO,EAAuB,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AAElE,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,MAAM,EAC/C,IAAI,EAAE,WAAW,EACjB,YAAY,EAAE,MAAM,EACpB,cAAc,EAAE,MAAM,EACtB,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,GACtB,OAAO,CAAC,CAAC,CAAC,GAAG,SAAS,CAUxB;AAED,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,MAAM,EACpD,IAAI,EAAE,WAAW,EACjB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,CAAC,CAAC,CAMZ;AAED,wBAAgB,sBAAsB,CAAC,CAAC,SAAS,MAAM,EACrD,IAAI,EAAE,WAAW,EACjB,cAAc,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,SAAS,EAC3C,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,GACtB,OAAO,CAAC,CAAC,CAAC,CAqCZ"}

package/dist/engine/hooks.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Hook invocation helper.
+ *
+ * All observability hooks (`onCall`, `onResult`, `onProviderError`) are
+ * fire-and-forget: the engine never awaits them, and sync or async errors
+ * inside the hook are swallowed. A slow logger doesn't slow fallback; an
+ * unhandled rejection inside a hook can't crash the engine.
+ */
+type FireAndForgetFn = ((...args: never[]) => void | Promise<void>) | undefined;
+export declare function fireAndForget(fn: FireAndForgetFn, ...args: unknown[]): void;
+export {};
+//# sourceMappingURL=hooks.d.ts.map

package/dist/engine/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../src/engine/hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,KAAK,eAAe,GAAG,CAAC,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,SAAS,CAAC;AAEhF,wBAAgB,aAAa,CAAC,EAAE,EAAE,eAAe,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAU3E"}

package/dist/engine/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Engine barrel. Verbs (`boolean` / `classify` / `classifier`) import from
+ * here; threshold / meta / abort / hooks stay module-private.
+ */
+export { validateClassifierConfig, withDefaults } from "./config.js";
+export { decide } from "./decide.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/engine/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/engine/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,wBAAwB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACrE,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC"}

package/dist/engine/meta.d.ts

@@ -0,0 +1,37 @@
+/**
+ * `VerdictMeta` builder — accumulates state across the engine's chain
+ * (providers attempted, errors swallowed, latency, cache hits) and produces
+ * the final `meta` object on every Verdict variant.
+ */
+import type { Provider } from "../providers/provider.js";
+import type { SerializableError, VerdictMeta } from "../types.js";
+type ProviderErrorRecord = {
+    readonly providerId: string;
+    readonly error: SerializableError;
+};
+/**
+ * Mutable accumulator used by `decide()`. Only the helpers in this file should
+ * mutate it; callers append to `providersAttempted` / `providerErrors` and
+ * flip `cacheHit` directly.
+ */
+export type MetaBuilder = {
+    readonly providersAttempted: string[];
+    readonly providerErrors: ProviderErrorRecord[];
+    readonly startedAtMs: number;
+    cacheHit: boolean;
+};
+export declare function makeMetaBuilder(): MetaBuilder;
+/**
+ * Build the final `VerdictMeta` for a Classified or Uncertain Verdict produced
+ * by a specific (successful) provider.
+ */
+export declare function buildMeta(builder: MetaBuilder, provider: Provider): VerdictMeta;
+/**
+ * Build `VerdictMeta` for failure-mode Verdicts (provider_failure,
+ * chain_exhausted, cancelled, budget_exhausted) where there's no clear
+ * "successful provider" to attribute. Falls back to the last-attempted
+ * provider for `providerUsed`, or the empty string when none was attempted.
+ */
+export declare function buildMetaForFailure(builder: MetaBuilder, fallbackProvider?: Provider): VerdictMeta;
+export {};
+//# sourceMappingURL=meta.d.ts.map

package/dist/engine/meta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"meta.d.ts","sourceRoot":"","sources":["../../src/engine/meta.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACzD,OAAO,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAElE,KAAK,mBAAmB,GAAG;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;CACnC,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,QAAQ,CAAC,kBAAkB,EAAE,MAAM,EAAE,CAAC;IACtC,QAAQ,CAAC,cAAc,EAAE,mBAAmB,EAAE,CAAC;IAC/C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,EAAE,OAAO,CAAC;CACnB,CAAC;AAEF,wBAAgB,eAAe,IAAI,WAAW,CAO7C;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,QAAQ,GAAG,WAAW,CAU/E;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,WAAW,EACpB,gBAAgB,CAAC,EAAE,QAAQ,GAC1B,WAAW,CAWb"}

package/dist/engine/threshold.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Threshold application — turn a calibrated Distribution into a per-variant
+ * decision. All comparisons are inclusive (`>=`, `<=`).
+ *
+ * - **Coverage gate first.** If `coverage < coverageMin`, return
+ *   `out_of_distribution` (engine wraps this into Unknown).
+ * - **Binary (N=2):** classic deadband. `top.prob >= high` → top wins;
+ *   `top.prob <= low` → other wins; else Uncertain.
+ * - **Multi-class (N>2):** top-confidence rule. `top.prob >= high` → top wins;
+ *   else Uncertain. Optional margin rule: requires *both*
+ *   `top.prob >= high` AND `top.prob - second.prob >= margin`.
+ */
+import type { Distribution, Thresholds } from "../types.js";
+type ThresholdResult<T extends string> = {
+    kind: "classified";
+    value: T;
+    probability: number;
+} | {
+    kind: "uncertain";
+    top: T;
+    probability: number;
+    runnerUp: T;
+} | {
+    kind: "out_of_distribution";
+    coverage: number;
+    topIfRenormalized: T;
+    probabilityIfRenormalized: number;
+};
+export declare function applyThresholds<T extends string>(d: Distribution<T>, thresholds: Thresholds<readonly T[]>, space: readonly T[]): ThresholdResult<T>;
+export {};
+//# sourceMappingURL=threshold.d.ts.map

package/dist/engine/threshold.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"threshold.d.ts","sourceRoot":"","sources":["../../src/engine/threshold.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE5D,KAAK,eAAe,CAAC,CAAC,SAAS,MAAM,IACjC;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,KAAK,EAAE,CAAC,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GACrD;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,GAAG,EAAE,CAAC,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,CAAC,CAAA;CAAE,GAC/D;IACE,IAAI,EAAE,qBAAqB,CAAC;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,iBAAiB,EAAE,CAAC,CAAC;IACrB,yBAAyB,EAAE,MAAM,CAAC;CACnC,CAAC;AAWN,wBAAgB,eAAe,CAAC,CAAC,SAAS,MAAM,EAC9C,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC,EAClB,UAAU,EAAE,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC,EACpC,KAAK,EAAE,SAAS,CAAC,EAAE,GAClB,eAAe,CAAC,CAAC,CAAC,CAqBpB"}

package/dist/env.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Environment-driven provider chain resolution.
+ *
+ *   DOMOVOI_PROVIDERS=openai/gpt-4o-mini,openai/gpt-4o,ollama/llama-3.1-70b
+ *   DOMOVOI_PROVIDERS_ARTICLES=...   (override for `classifier({ name: "articles" })`)
+ *
+ * Format: `factory/model[,factory/model…]`. The first `/` separates factory
+ * from model; later slashes belong to the model name (e.g.
+ * `openrouter/meta-llama/llama-3.1-70b`). Whitespace is trimmed; empty
+ * entries are skipped; an empty / whitespace-only value counts as unset.
+ *
+ * Per-provider parametric options (`multiSampleN`, custom timeouts) cannot
+ * be expressed in env — drop to an explicit `providers: [...]` array for
+ * those.
+ */
+import type { Provider } from "./providers/provider.js";
+type ParsedEntry = {
+    readonly factory: string;
+    readonly model: string;
+};
+/**
+ * Parses a DOMOVOI_PROVIDERS-style string into typed entries. Throws
+ * `ConfigError` with `code: "malformed_provider_config"` on a bad entry.
+ * Returns `[]` for empty / whitespace-only input — callers treat that as unset.
+ */
+export declare function parseProvidersEnv(raw: string | undefined): readonly ParsedEntry[];
+/**
+ * Resolves a DOMOVOI_PROVIDERS-style env value into Provider instances.
+ *
+ * Throws `ConfigError` with `code` ∈ { `missing_provider_config`,
+ * `malformed_provider_config`, `unknown_provider_factory` }. Credential
+ * presence is not checked here — the underlying SDK surfaces that on first
+ * call.
+ */
+export declare function resolveProvidersFromEnv(raw: string | undefined): readonly Provider[];
+/**
+ * Resolves the chain for a classifier with optional `name`. Tries
+ * `DOMOVOI_PROVIDERS_<NAME>` first (uppercased), then `DOMOVOI_PROVIDERS`.
+ * Throws `ConfigError({ code: "missing_provider_config" })` if both are unset.
+ *
+ * Tests must stub env *before* the first domovoi call — env is read lazily,
+ * but only once per classifier resolution.
+ */
+export declare function resolveDefaultProviders(name?: string): readonly Provider[];
+export {};
+//# sourceMappingURL=env.d.ts.map

package/dist/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAcxD,KAAK,WAAW,GAAG;IACjB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,WAAW,EAAE,CAUjF;AAqBD;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,QAAQ,EAAE,CAmBpF;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,QAAQ,EAAE,CAS1E"}

package/dist/errors.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Error taxonomy for domovoi.
+ *
+ * Four classes (`DomovoiError` base + `ProviderError`, `ConfigError`,
+ * `BudgetExhaustedError`) with a stable `code` field for fine-grained
+ * discrimination. All accept `{ cause }` for ES2022 chaining.
+ *
+ * The engine canonicalizes anything thrown from `Provider.sample` that isn't
+ * already a `DomovoiError` into `ProviderError({ cause })`, so callers always
+ * see a known error type. Under the default `onErrorPolicy: "fallback"`,
+ * runtime errors become `Unknown` Verdict variants rather than throw;
+ * `ConfigError` always throws.
+ */
+/**
+ * Stable error codes carried in `error.code`. Discriminate on these rather
+ * than on `instanceof` of removed-historical subclasses.
+ */
+export type ErrorCode = "decision_space_collision" | "decision_space_too_large" | "missing_provider_config" | "malformed_provider_config" | "unknown_provider_factory" | "missing_credential" | "incompatible_calibrator" | "invalid_classifier_name" | "invalid_thresholds" | "invalid_space" | "empty_providers" | "provider_network" | "provider_rate_limit" | "provider_timeout" | "provider_unauthorized" | "provider_server_error" | "provider_malformed_response" | "invalid_distribution" | "per_call_timeout" | "chain_timeout" | "max_calls";
+export declare class DomovoiError extends Error {
+    readonly code: string;
+    constructor(message: string, options?: {
+        code?: string;
+        cause?: unknown;
+    });
+}
+export declare class ProviderError extends DomovoiError {
+    constructor(message: string, options?: {
+        code?: string;
+        cause?: unknown;
+    });
+}
+export declare class ConfigError extends DomovoiError {
+    constructor(message: string, options?: {
+        code?: string;
+        cause?: unknown;
+    });
+}
+export declare class BudgetExhaustedError extends DomovoiError {
+    readonly attemptedProviders: readonly string[];
+    readonly elapsedMs: number;
+    readonly scope: "per_call_timeout" | "chain_timeout" | "max_calls";
+    constructor(message: string, options: {
+        scope: "per_call_timeout" | "chain_timeout" | "max_calls";
+        attemptedProviders: readonly string[];
+        elapsedMs: number;
+        cause?: unknown;
+    });
+}
+/**
+ * Wraps any non-DomovoiError thrown value in `ProviderError({ cause })`.
+ * `DomovoiError` subtypes — including `ProviderError` subclasses defined by
+ * external Provider implementations — pass through unchanged.
+ */
+export declare function canonicalizeProviderThrow(thrown: unknown): DomovoiError;
+/**
+ * Convert an Error to the JSON-safe shape stored in
+ * `Verdict.meta.providerErrors`. Cause chains are preserved recursively.
+ */
+export declare function serializeError(err: unknown): {
+    readonly name: string;
+    readonly message: string;
+    readonly code?: string;
+    readonly cause?: ReturnType<typeof serializeError>;
+    readonly stack?: string;
+};
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;GAGG;AACH,MAAM,MAAM,SAAS,GAEjB,0BAA0B,GAC1B,0BAA0B,GAC1B,yBAAyB,GACzB,2BAA2B,GAC3B,0BAA0B,GAC1B,oBAAoB,GACpB,yBAAyB,GACzB,yBAAyB,GACzB,oBAAoB,GACpB,eAAe,GACf,iBAAiB,GAEjB,kBAAkB,GAClB,qBAAqB,GACrB,kBAAkB,GAClB,uBAAuB,GACvB,uBAAuB,GACvB,6BAA6B,GAC7B,sBAAsB,GAEtB,kBAAkB,GAClB,eAAe,GACf,WAAW,CAAC;AAEhB,qBAAa,YAAa,SAAQ,KAAK;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAK1E;AAED,qBAAa,aAAc,SAAQ,YAAY;gBACjC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAI1E;AAED,qBAAa,WAAY,SAAQ,YAAY;gBAC/B,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAI1E;AAED,qBAAa,oBAAqB,SAAQ,YAAY;IACpD,QAAQ,CAAC,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,kBAAkB,GAAG,eAAe,GAAG,WAAW,CAAC;gBAGjE,OAAO,EAAE,MAAM,EACf,OAAO,EAAE;QACP,KAAK,EAAE,kBAAkB,GAAG,eAAe,GAAG,WAAW,CAAC;QAC1D,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAC;QACtC,SAAS,EAAE,MAAM,CAAC;QAClB,KAAK,CAAC,EAAE,OAAO,CAAC;KACjB;CAQJ;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,OAAO,GAAG,YAAY,CAYvE;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG;IAC5C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC;IACnD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB,CAaA"}

package/dist/hash.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Stable canonical hashing for cache keys.
+ *
+ * - SHA-256 from `node:crypto` (stdlib only; cross-process stable so future
+ *   persistent backends can share keys).
+ * - Canonical JSON serialization with lexicographically sorted object keys.
+ * - NFC normalization + trim for input string hashing.
+ */
+/** SHA-256 hex digest of the given string. */
+export declare function sha256(s: string): string;
+/**
+ * Canonicalize a JSON-serializable value into a deterministic string:
+ * - Object keys sorted lexicographically.
+ * - Arrays preserve order — decision-space ordering in cache keys honors
+ *   the user-given order (re-ordering changes the prompt and the model's
+ *   first-token distribution, so it must change the cache key).
+ * - undefined values are omitted (matches JSON.stringify semantics for object values).
+ *
+ * Throws on non-JSON-serializable inputs (functions, symbols, circular refs).
+ */
+export declare function canonicalJSON(value: unknown): string;
+/**
+ * Normalize an input string for hashing: NFC normalization + trim.
+ * Used to compute `input_hash` in the cache key composition.
+ */
+export declare function normalizeInput(input: string): string;
+//# sourceMappingURL=hash.d.ts.map

package/dist/hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../src/hash.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,8CAA8C;AAC9C,wBAAgB,MAAM,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAExC;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEpD;AAeD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEpD"}