@hourslabs/domovoi 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for describing the origin of the Work and
+      reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Support. While redistributing the Work or
+      Derivative Works thereof, You may choose to offer, and charge a
+      fee for, acceptance of support, warranty, indemnity, or other
+      liability obligations and/or rights consistent with this License.
+      However, in accepting such obligations, You may act only on Your
+      own behalf and on Your sole responsibility, not on behalf of any
+      other Contributor, and only if You agree to indemnify, defend, and
+      hold each Contributor harmless for any liability incurred by, or
+      claims asserted against, such Contributor by reason of your accepting
+      any such warranty or support.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Alex Roh
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied. See the License for the specific language governing permissions
+   and limitations under the License.

package/NOTICE

@@ -0,0 +1,4 @@
+domovoi
+Copyright 2026 Alex Roh
+
+This product includes software developed by Alex Roh and contributors.

package/README.md

@@ -0,0 +1,312 @@
+<div align="center">
+  <img alt="domovoi — a small lit cabin in a forest of binary digits, where a craftsman gnome works at his bench" src=".github/assets/cover.png" width="100%" />
+</div>
+
+# domovoi
+
+[![npm version](https://img.shields.io/npm/v/@hourslabs/domovoi)](https://www.npmjs.com/package/@hourslabs/domovoi)
+[![node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
+[![typescript](https://img.shields.io/badge/typescript-%3E%3D5-blue)](https://www.typescriptlang.org)
+[![license](https://img.shields.io/badge/license-Apache%202.0-lightgrey)](LICENSE)
+
+**domovoi is an embedded intelligence in the runtime — a primitive that lives inside your software.** Ask at the forks where rules break down, get a typed Verdict, and direct it with bounded cost and full observability.
+
+---
+
+- [What is domovoi](#what-is-domovoi)
+- [Install](#install)
+- [Typed Verdicts](#typed-verdicts)
+- [When to Use It](#when-to-use-it)
+- [API](#api)
+- [Chaining](#chaining)
+- [Provider Chain and Escalation](#provider-chain-and-escalation)
+- [Local LLMs](#local-llms)
+- [Configuration](#configuration)
+- [Cancellation](#cancellation)
+- [Calibration](#calibration)
+- [Cache](#cache)
+- [Current Limitations](#current-limitations)
+- [Roadmap](#roadmap)
+- [Origin](#origin)
+
+---
+
+## What is domovoi
+
+Some decisions in software resist code. Is "SQ *COFFEE 0421" a restaurant or a grocery store? Is this message a refund request or a complaint? Is this form submission an abandoned checkout or a contact inquiry? A human decides in seconds. Code never will.
+
+Rules and trained classifiers have tackled this for decades. Rules break on edge cases, then multiply until they collapse under their own weight. Classifiers return a confidence score and leave the handling to you. They don't know what they don't know.
+
+domovoi is a single function call at the decision point. Unlike agent frameworks or workflow engines, it doesn't restructure how you build — it drops into existing code like any other dependency. Ask it, get a typed `Verdict`, continue.
+
+The `Verdict` is the core idea. Not a string, not a confidence score — one of three typed states: `Classified` when confident, `Uncertain` when the top answer falls below threshold, `Unknown` when no answer is possible. Uncertainty becomes a first-class value your type system understands, not a silent wrong answer. Everything around the `Verdict` stays deterministic.
+
+```tsx
+import { domovoi, match } from "@hourslabs/domovoi";
+
+async function processTransaction(txn: Transaction) {
+  const account = await accounts.get(txn.accountId);
+  if (await fraud.isSuspicious(txn)) return holds.queue(txn);
+
+  const verdict = await domovoi.classify(
+    txn.merchant,           // e.g. "NETFLIX.COM"
+    account.budget.categories  // e.g. ["shopping", "groceries", ...]
+  );
+
+  await match(verdict, {
+    classified: ({ value }) => budget.attribute(account, txn, value),
+    uncertain:  ({ top, runnerUp }) =>
+      budget.attributePending(account, txn, top, runnerUp),
+    unknown:    ({ reason }) =>
+      retryQueue.schedule(txn, { reason, delayMs: 5 * 60_000 }),
+  });
+
+  await receipts.archive(txn);
+  events.emit("txn.processed", txn.id);
+}
+```
+
+---
+
+## Install
+
+```bash
+npm install @hourslabs/domovoi
+
+# set your provider credentials
+OPENAI_API_KEY=sk-...
+```
+
+---
+
+## Typed Verdicts
+
+domovoi treats classification as a probabilistic decision over a finite space and returns one of three typed variants:
+
+- **`Classified<T>`** — confident answer with `value: T` and calibrated `probability`.
+- **`Uncertain<T>`** — top class below threshold; carries `top`, `runnerUp`, and the full `distribution`.
+- **`Unknown<T>`** — no answer; `reason` discriminates `out_of_distribution`, `chain_exhausted`, `provider_failure`, `predicate_rejected`, `budget_exhausted`, or `cancelled`.
+
+Failure-to-classify is a typed result, not an exception. Dispatch is exhaustive at the type level.
+
+```
+"NETFLIX.COM"                   →  subscriptions   (p=1.00)
+"WHOLE FOODS MARKET #10293"     →  groceries       (p=0.99)
+"UBER EATS"                     →  dining          (p=0.99)
+"SHELL OIL 12345"               →  transportation  (p=0.93)
+"AMZN MKTP US*A12B3C4D5"        →  uncertain       (shopping vs groceries, p=0.55)
+```
+
+The `AMZN MKTP` row shows why the third state exists: it could be shopping or groceries depending on the cart. A forced `argmax` would silently pick the wrong one. domovoi surfaces the ambiguity as a first-class result instead.
+
+---
+
+## When to Use It
+
+The pattern that fits: *a decision that's obvious to a person but impossible to write rules for, with a bounded downside when you get it wrong.*
+
+- **Intent routing** — refund, complaint, or question. Rules and regex can't cover the full input space.
+- **Content classification** — tag an article, ticket, or submission against your taxonomy. Replace brittle keyword rules with a classifier that handles edge cases.
+- **Tiered dispatch** — chain `[gpt-4o-mini, gpt-5]`. The cheap model handles the easy cases; the expensive one runs only on `Uncertain`. Cost savings are meaningful when ≥70–80% of calls resolve at the cheaper tier.
+- **Free-form validation + privacy filters** — does this description match the product? Does this profile bio violate guidelines? Does this user input contain PII or a prompt-injection attempt?
+
+---
+
+## API
+
+Three core verbs:
+
+```tsx
+domovoi.classify(input, space, opts?)    // multi-class one-shot
+domovoi.boolean(input, question, opts?)  // binary one-shot
+domovoi.classifier({ ... })             // reusable, configured → Classifier<T, I>
+```
+
+Three ways to consume a Verdict:
+
+```tsx
+// Type guard — single-variant cases
+if (isClassified(verdict)) save(verdict.value);
+
+// switch — when each Unknown reason needs its own handler
+switch (verdict.kind) { ... }
+
+// match — exhaustive expression form, type-checked
+match(verdict, {
+  classified: ({ value })         => save(value),
+  uncertain:  ({ top, runnerUp }) => saveTentative(top, runnerUp),
+  unknown:    ({ reason })        => handleUnknown(reason),
+});
+```
+
+`Verdict.filter(pred)` rejects domain-invalid `Classified` or `Uncertain` to `Unknown { predicate_rejected }`; `Unknown` passes through untouched.
+
+Three extension interfaces let you write your own without forking: **`Provider`** for any LLM API, **`Calibrator`** for custom calibration math, **`Cache`** for persistent or distributed backends. `mockProvider` from `@hourslabs/domovoi/testing` covers unit tests with controllable Distributions.
+
+---
+
+## Chaining
+
+Verdicts compose. A Verdict can gate the next call, so each classifier works over a small, coherent space rather than one flat list of labels:
+
+```tsx
+import { domovoi, isClassified } from "@hourslabs/domovoi";
+
+const kind = await domovoi.classify(issue.body, [
+  "bug", "feature", "question", "docs",
+]);
+
+// only bugs need surface-area triage — the first Verdict gates the second call
+const surface =
+  isClassified(kind) && kind.value === "bug"
+    ? await domovoi.classify(issue.body, [
+        "frontend", "backend", "infra", "data",
+      ])
+    : null;
+
+await issues.label(issue, {
+  kind:    isClassified(kind)    ? kind.value    : "triage",
+  surface: surface && isClassified(surface) ? surface.value : null,
+});
+```
+
+---
+
+## Provider Chain and Escalation
+
+Configure a named classifier with a provider chain, thresholds, and a calibrator using `domovoi.classifier`:
+
+```tsx
+const articleClassifier = domovoi.classifier({
+  name: "articles",
+  space: ["news", "sports", "music"],
+  question: "Which category fits this article?",
+  format: (article: Article) => `${article.title}\n\n${article.body}`,
+  thresholds: { high: 0.7, coverageMin: 0.5 },
+  providers: [openai("gpt-4o-mini"), openai("gpt-4o")],
+  calibrator: temperatureScaling(0.85),
+});
+```
+
+If the first provider returns `Uncertain` or errors, the engine tries the next. Errors land in `verdict.meta.providerErrors`. The default `onErrorPolicy: "fallback"` returns `Unknown { provider_failure }` on full-chain failure — it never throws. Set `onErrorPolicy: "throw"` for `AggregateError`.
+
+Every Verdict includes rich metadata — provider, attempted chain, latency, cache hits, distribution source, and swallowed fallback errors — without extra instrumentation.
+
+---
+
+## Local LLMs
+
+Local runtimes ship OpenAI-compatible APIs, so you can mix them freely with hosted models in a single chain:
+
+```tsx
+// local primary, hosted fallback
+providers: [ollama("llama-3.1-70b"), openai("gpt-4o")]
+```
+
+`ollama(model)` defaults to `localhost:11434`. `openaiCompat(model, { baseURL, apiKey })` covers LM Studio, vLLM, Together, Fireworks, and OpenRouter.
+
+---
+
+## Configuration
+
+```bash
+# Credentials — provider factories pick these up automatically
+OPENAI_API_KEY=sk-...
+
+# Default provider chain — comma-separated factory/model
+DOMOVOI_PROVIDERS=openai/gpt-4o-mini,openai/gpt-4o
+
+# Per-classifier override — when the classifier has `name: "articles"`
+DOMOVOI_PROVIDERS_ARTICLES=openai/gpt-4o-mini,ollama/llama-3.1-70b
+```
+
+Format: `factory/model[,factory/model...]`. Whitespace is trimmed; empty entries are skipped. In-code overrides win — pass `providers` to `domovoi.classifier({ ... })` and the env is ignored.
+
+---
+
+## Cancellation
+
+Pass `signal` to any call. Standard Web API throughout:
+
+```tsx
+// per-call timeout
+const verdict = await domovoi.classify(input, space, {
+  signal: AbortSignal.timeout(2000),
+});
+
+// composing signals
+const signal = AbortSignal.any([parentSignal, AbortSignal.timeout(5000)]);
+
+// abort with reason
+controller.abort("budget_exceeded");
+// → Unknown { kind: "cancelled", reason: "budget_exceeded" }
+```
+
+`.batch` always returns partial results. Finished items keep their Verdicts; in-flight and queued items become `Unknown { cancelled }`. The Promise resolves; it does not reject.
+
+---
+
+## Calibration
+
+Three closed-form scaling factories from `@hourslabs/domovoi/calibration`:
+
+| Factory | When to use |
+|---|---|
+| `identity` | Default. No calibration applied. |
+| `temperatureScaling(T)` | Works on any space size. |
+| `plattScaling({ a, b })` | Binary classifiers only. |
+
+Fit the parameters on your held-out eval set. `Calibrator.fit(eval)` is on the roadmap; until then, fitting is manual. Calibrators run per-caller after cache resolution, so different configs on the same cache key produce different Verdicts from the same raw Distribution.
+
+---
+
+## Cache
+
+Raw distributions are cached per `(input, provider)` keyed by SHA-256. The default is an in-memory LRU at 10k entries per classifier:
+
+```tsx
+// override the default
+domovoi.classifier({
+  cache: domovoi.memoryCache({ maxEntries: 50_000 }),
+  // ...
+});
+```
+
+The cache hashes the *output* of `format(input)`, not the function itself. Two classifiers with different `format` implementations but identical output share cache rows.
+
+Custom backends implement the public `Cache` interface. Redis, SQLite, and Cloudflare KV are planned as first-party packages; they're implementable today via the interface.
+
+---
+
+## Current Limitations
+
+1. **Single adapter family.** OpenAI Chat plus OpenAI-compatible runtimes (Ollama, vLLM, LM Studio, Together, Fireworks). Anthropic native and Gemini are on the roadmap.
+2. **In-memory cache only.** Process-local; serverless cold starts begin empty. Persistent backends are implementable today via the public `Cache` interface; first-party Redis, SQLite, and KV packages are planned.
+3. **Identity calibrator default.** Provide `temperatureScaling(T)` or `plattScaling({ a, b })` with parameters you fit on your eval set for real calibration. Automated fitting (`Calibrator.fit(eval)`) is planned.
+4. **No per-provider retries.** Chain fallback covers between-provider failures; per-provider retries are planned.
+5. **No streaming.** `.stream` on `Classifier` is planned; `.batch` ships today.
+6. **No few-shot prompting.** Input passes verbatim; wrap with your own example-injection if needed.
+
+---
+
+## Roadmap
+
+Milestones are ordered; dates are not. For exact versions, see the npm package page and GitHub Releases.
+
+**Today.** The Verdict primitive — `Classified<T>`, `Uncertain<T>`, and `Unknown<T>` with structured failure modes. The `classify`, `boolean`, and `classifier` verbs. Calibration infrastructure, pluggable provider chain, tokenizer-aware OpenAI adapter, and the `Provider` / `Calibrator` / `Cache` extension points.
+
+**Next.** Ambient context propagation via `domovoi.scope({ budget, signal, tracer }, fn)` — opt into budget enforcement, tracing, and cancellation across all `domovoi.classify(...)` calls deep in your call tree. New public extension point: `ContextStorage<T>`, backed by Node `AsyncLocalStorage`. Calls outside a scope continue to work exactly as today.
+
+**Stability.** The Verdict shape, the three core verbs, and the four error classes are stable across releases. The `Provider` / `Calibrator` / `Cache` extension interfaces are public — breaking changes require a major version bump. Pre-1.0 releases may break anything outside these interfaces; pin an exact version if stability is required today.
+
+---
+
+## Origin
+
+In Slavic folklore, a _domovoi_ (домово́й — "of the house") is a household spirit, not summoned from outside but bound to the home itself. It belongs to whoever lives there, watches over the household, and tends to what needs tending. domovoi is that spirit for your software: present at every decision, bound to you.
+
+---
+
+## License
+
+Apache License 2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).

package/dist/cache.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Cache primitives.
+ *
+ * The public `Cache` interface is async, opaque-string-valued, and requires
+ * `delete`. The engine owns serialization; backends (Redis, KV, SQLite,
+ * in-memory) just round-trip strings.
+ *
+ * `InFlight` is the engine-side dedup table — concurrent calls with the same
+ * key share one Promise. Distinct from the `Cache` interface so external
+ * backends never see in-flight state.
+ */
+import type { Distribution } from "./types.js";
+/**
+ * Bump manually only when a change would make existing cache entries
+ * semantically wrong (cache key composition, stored value shape, provider
+ * distribution computation). Library-version bumps alone do not bump this.
+ */
+export declare const CACHE_SCHEMA_VERSION = 1;
+type CacheKeyInputs = {
+    readonly providerId: string;
+    readonly modelId: string;
+    readonly tokenizerId: string;
+    readonly templateHash: string;
+    /**
+     * Decision space in user-given order. Re-ordering changes the prompt — and
+     * therefore the model output — so it must change the cache key.
+     */
+    readonly decisionSpace: readonly string[];
+    readonly temperature: number;
+    /**
+     * Stable hash of provider options that affect Distribution shape (e.g.
+     * `multiSampleN`). Empty string for providers without such options.
+     */
+    readonly providerConfigHash: string;
+    /** Output of `classifier({ format })`, not the raw input. */
+    readonly formattedInput: string;
+};
+/**
+ * SHA-256 hex digest over canonical-JSON of all inputs. Stable across
+ * processes — safe for persistent backends.
+ */
+export declare function computeCacheKey(inputs: CacheKeyInputs): string;
+export declare function serializeCachedValue<T extends string>(d: Distribution<T>): string;
+/**
+ * Returns `undefined` on a stored-schema-version mismatch; the engine treats
+ * that as a miss and re-samples from the provider.
+ */
+export declare function deserializeCachedValue<T extends string>(raw: string): Distribution<T> | undefined;
+/**
+ * @example
+ * const redisCache: Cache = {
+ *   async get(key) { return await redis.get(key); },
+ *   async set(key, value, ttlMs) {
+ *     if (ttlMs !== undefined) await redis.set(key, value, "PX", ttlMs);
+ *     else await redis.set(key, value);
+ *   },
+ *   async delete(key) { await redis.del(key); },
+ * };
+ */
+export interface Cache {
+    get(key: string): Promise<string | undefined>;
+    set(key: string, value: string, ttlMs?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+export type CacheStats = {
+    readonly size: number;
+    readonly hits: number;
+    readonly misses: number;
+    readonly evictions: number;
+};
+/**
+ * Optional extension over `Cache`. The built-in `memoryCache` implements it;
+ * external backends may opt in.
+ */
+export interface CacheWithStats extends Cache {
+    stats(): CacheStats;
+}
+/**
+ * Count-bounded in-memory LRU cache. Used as the per-classifier default when
+ * `cache` isn't supplied. Eviction runs after every successful `set`; the
+ * cache may briefly hold `maxEntries + concurrent-in-flight` entries during
+ * concurrent writes, then drops back to bound.
+ *
+ * @param options.maxEntries  Default 10_000.
+ * @param options.defaultTtlMs  Optional fallback TTL when `set` omits it.
+ */
+export declare function memoryCache(options?: {
+    maxEntries?: number;
+    defaultTtlMs?: number;
+}): CacheWithStats;
+/**
+ * Engine-side dedup table. Two callers hitting the same key concurrently
+ * share a single Promise; on settle the slot is cleared.
+ */
+export declare class InFlight<V> {
+    private readonly map;
+    run(key: string, factory: () => Promise<V>): Promise<V>;
+    /** Drop the in-flight slot for `key`, allowing the next caller to retry. */
+    forget(key: string): void;
+}
+export {};
+//# sourceMappingURL=cache.d.ts.map

package/dist/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,IAAI,CAAC;AAEtC,KAAK,cAAc,GAAG;IACpB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;OAGG;IACH,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,6DAA6D;IAC7D,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC,CAAC;AAEF;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAc9D;AAQD,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,MAAM,CAOjF;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,SAAS,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,YAAY,CAAC,CAAC,CAAC,GAAG,SAAS,CAQjG;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,KAAK;IACpB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAC9C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/D,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpC;AAED,MAAM,MAAM,UAAU,GAAG;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B,CAAC;AAEF;;;GAGG;AACH,MAAM,WAAW,cAAe,SAAQ,KAAK;IAC3C,KAAK,IAAI,UAAU,CAAC;CACrB;AAOD;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,OAAO,CAAC,EAAE;IACpC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,GAAG,cAAc,CA0DjB;AAED;;;GAGG;AACH,qBAAa,QAAQ,CAAC,CAAC;IACrB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAiC;IAE/C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAU7D,4EAA4E;IAC5E,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;CAG1B"}

package/dist/calibration/index.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Built-in calibrator factories.
+ *
+ *   - `identity` — pass-through; the default.
+ *   - `temperatureScaling(T)` — `p^(1/T) / Σ p_j^(1/T)`; equivalent to
+ *     scaling logits before softmax.
+ *   - `plattScaling({ a, b })` — sigmoid scaling; binary spaces only.
+ *
+ * `Calibrator.apply` must be pure and stateless. The engine runs it
+ * per-caller after the Distribution is loaded from the cache, so impurity
+ * would leak across callers sharing a cache row.
+ */
+import type { Distribution } from "../types.js";
+export interface Calibrator {
+    /** Identifier; `"identity"` is reserved and recognized by the engine. */
+    readonly kind: string;
+    apply<T extends string>(d: Distribution<T>): Distribution<T>;
+}
+export declare const identity: Calibrator;
+/**
+ *   - `T = 1` → identity.
+ *   - `T > 1` → softens (less peaked).
+ *   - `T < 1` → sharpens (more peaked).
+ *
+ * Operates on probabilities (not logits) and leaves `coverage` unchanged.
+ * Throws `ConfigError` on `T <= 0`.
+ *
+ * @example
+ *   calibrator: temperatureScaling(0.85)  // user-fit on held-out eval set
+ */
+export declare function temperatureScaling(T: number): Calibrator;
+/**
+ * Platt scaling: `sigmoid(a*z + b)` where `z = logit(p_pos)`.
+ *
+ * Binary-only — the second label in the distribution (in user-given order)
+ * is treated as the positive class. Construction-time space-size validation
+ * happens in the classifier; `apply()` re-checks at runtime as a defensive
+ * guard against direct misuse.
+ */
+export declare function plattScaling(params: {
+    a: number;
+    b: number;
+}): Calibrator;
+export declare function isIdentityCalibrator(c: Calibrator): boolean;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/calibration/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,MAAM,WAAW,UAAU;IACzB,yEAAyE;IACzE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC;CAC9D;AAED,eAAO,MAAM,QAAQ,EAAE,UAKtB,CAAC;AAEF;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,MAAM,GAAG,UAAU,CA4BxD;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,UAAU,CAuCzE;AAMD,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,UAAU,GAAG,OAAO,CAE3D"}