@corbits/system-one 0.1.0 → 0.2.0

package/README.md

@@ -1,279 +1,184 @@
 # @corbits/system-one
 
-[![License: LGPL-2.1](https://img.shields.io/badge/license-LGPL--2.1-green.svg)](./LICENSE)
-[![Runtime: Bun](https://img.shields.io/badge/runtime-Bun%201.2%2B-black.svg)](#development)
-
-**Typed decisions from System One (Jev-class) models — as an Interchange
-inference provider, or as a direct `evaluate()` call.**
-
-Ask choice, score, and boolean questions over a state payload. You get
-back per-kind decisions, or a typed fallback when the backend is
-unreachable. Official, gateway, and custom endpoints are config, not
-forked code.
-
-## Contents
-
-- [Why](#why)
-- [Quickstart](#quickstart)
-- [How it works](#how-it-works)
-- [Development](#development)
-- [License](#license)
-
-## Why
-
-Interchange agents and workflows already speak providers. This package
-is the System One adapter for that surface:
-
-- **One provider id.** `SYSTEM_ONE_PROVIDER` is `"corbits-system-one"`
-  — same naming as the other Corbits libraries, not a generic
-  `"system-one"`. Use it in `defineAgent` / workflow inference sources
-  the way you would `"anthropic"`.
-- **Questions on the call.** Pass Jev questions (and optional state)
-  through `providerOptions.systemOne`. The transcript is the default
-  state when you omit it.
-- **Two output shapes.** Direct `evaluate()` returns an
-  `EvaluateResult` or `FallbackResult`. The adapter unwraps the same
-  decisions into Interchange `inference.text.delta` / `inference.usage`
-  events so an agent step can consume them.
-- **Host-owned credentials.** The adapter sends Interchange's bearer
-  sentinel; the harness injects the real key. Peers are
-  `@intx/inference` and `@intx/types` — one copy, the host's.
+Typed choice, score and yes/no decisions about a JSON state from TypeSafe's Jev model, returned as a validated result or a typed fallback. An inference provider for Corbits and Interchange agents: registers as an `@intx/inference` adapter, and also works standalone through `evaluate()`.
 
-## Quickstart
+## Why @corbits/system-one?
 
-Requires [Bun](https://bun.sh/) 1.2+. Peers resolve to the host's
-Interchange copies.
+1. **Typed decisions, not free text.** You send questions with ids; you get back one validated decision per id, with probabilities and confidence. No prompt parsing.
+2. **Failures are data.** A missing key, timeout, HTTP error or bad body returns a `FallbackResult` with a `reason`, so a gate can fail closed without a `try`. Only invalid caller input throws.
+3. **One call, many questions.** Every question in a list goes out in one POST, bounded by a 1.5 s default timeout.
 
-```
-bun add @corbits/system-one
-```
+It evaluates structured state against questions. For open-ended chat completions, use a general inference provider such as [`@corbits/openai-responses`](https://github.com/corbitsdev/corbits-openai-responses).
 
-Shared questions used below:
+## Install
 
-```ts
-const questions = [
-  {
-    id: "route",
-    type: "choice",
-    instructions: "What permission decision does this request warrant?",
-    criteria: { allow: "Low-risk request", deny: "Refuse the request" },
-  },
-  {
-    id: "escalate",
-    type: "boolean",
-    instructions: "Must this request be escalated for human approval?",
-  },
-];
+```bash
+bun add @corbits/system-one @intx/inference@^0.4.0 @intx/types@^0.4.0
 ```
 
-### Direct `evaluate()` — typed result object
+Runs on Bun >= 1.2 or Node >= 24.
 
-No Interchange runtime. You get a discriminated result: success
-(`fallback: false`) or a typed fallback (`fallback: true`). Boolean
-questions answer as native `noul` (0..1).
+## Quickstart
+
+Needs `TYPESAFE_API_KEY` set.
 
 ```ts
 import { evaluate } from "@corbits/system-one";
 
 const result = await evaluate({
   state: { action: "deploy", env: "production" },
-  questions,
-  config: { apiKey: process.env.TYPESAFE_API_KEY },
-});
-```
-
-Success looks like:
-
-```ts
-{
-  fallback: false,
-  backend: "corbits-system-one", // official endpoint; "gateway" | "custom" otherwise
-  modelId: "jev-1.13.0",
-  latencyMs: 412,
-  usage: { inputTokens: 296, outputTokens: 20 },
-  decisions: [
-    {
-      id: "route",
-      type: "choice",
-      choice: "deny",
-      confidence: 0.86,
-      probabilities: { allow: 0.14, deny: 0.86 },
-    },
+  questions: [
     {
       id: "escalate",
-      type: "noul",
-      noul: 0.91,
+      type: "boolean",
+      instructions: "Must this request be escalated for human approval?",
     },
   ],
-}
+});
+
+console.log(result.fallback ? result.reason : result.decisions);
 ```
 
-No key / timeout / HTTP / parse failure looks like:
+On success it prints one decision per question, or the fallback reason on failure:
 
 ```ts
-{
-  fallback: true,
-  reason: "no-key", // or "timeout" | "network" | "http-error" | "parse-error" | "backend-unreachable"
-  latencyMs: 2,
-  backendAttempted: "https://api.typesafe.ai/...",
-  detail: "no API key in config.apiKey, TYPESAFE_API_KEY, or SYSTEM_ONE_API_KEY",
-}
+[{ id: "escalate", type: "noul", noul: 0.91 }];
 ```
 
-Invalid caller input (bad questions, custom endpoint without `url`)
-still **throws** a `SystemOneError` — that is not a fallback.
+Boolean questions answer as `noul`, a probability from 0 to 1 that the answer is yes.
 
-Auth: `config.apiKey`, else `TYPESAFE_API_KEY` (official),
-`AI_GATEWAY_API_KEY` / `VERCEL_OIDC_TOKEN` (gateway), else
-`SYSTEM_ONE_API_KEY`. Endpoint: omit for official (`jev-latest`);
-`{ kind: "gateway" }`; `{ kind: "custom", url }`.
+## Where it fits
 
-### Adapter — Interchange events, same decisions
+[Interchange](https://github.com/faremeter/interchange) runs AI agents as principals (accounts that hold their own identity, permissions and credentials). Corbits packages add what an agent product needs around it.
 
-`createSystemOneAdapter()` is a `ProviderAdapter`. Register
-`"corbits-system-one"`, put questions on the call. The harness
-streams events instead of returning `EvaluateResult`.
+- **Runs in:** the agent sidecar (the runtime next to each agent), or any process. `evaluate()` needs no Interchange runtime.
+- **Plugs into:** the [`@intx/inference`](https://github.com/faremeter/interchange/tree/main/packages/inference) adapter registry, as the adapter for the `corbits-system-one` provider id.
+- **Pairs with:** [`@corbits/openai-responses`](https://github.com/corbitsdev/corbits-openai-responses) and [`@corbits/ollama-adapter`](https://github.com/corbitsdev/corbits-ollama-adapter), the other Corbits inference providers.
 
-```ts
-import { createAgent, defineAgent } from "@intx/agent";
-import {
-  createSystemOneAdapter,
-  SYSTEM_ONE_PROVIDER, // "corbits-system-one"
-} from "@corbits/system-one";
+## Reference
 
-const def = defineAgent({
-  id: "permission-gate",
-  systemPrompt: "Decide whether this request needs human approval.",
-  tools: [],
-  capabilities: [],
-  inference: {
-    sources: [{ provider: SYSTEM_ONE_PROVIDER, model: "jev-latest" }],
-  },
-});
+| Export                            | Description                                                                      |
+| --------------------------------- | -------------------------------------------------------------------------------- |
+| `evaluate(input, options?)`       | Runs one evaluation. Returns `EvaluateResult`: decisions or a `FallbackResult`.  |
+| `createSystemOneAdapter(config?)` | Returns a `ProviderAdapter` for `runInference`. `config` is an `EvaluateConfig`. |
+| `SYSTEM_ONE_PROVIDER`             | The `"corbits-system-one"` provider id.                                          |
+| `DEFAULT_TIMEOUT_MS`              | `1500`, the default `timeoutMs`.                                                 |
+| `SystemOneError`                  | Thrown for invalid input or a `custom` endpoint without a `url`.                 |
+| `SystemOneTelemetryEvent`         | Schema and type for events passed to `onTelemetry`.                              |
+| `EvaluateOptions`, `EvaluateDeps` | Types for `options`: `onTelemetry`, and `deps: { fetch, scheduler }`.            |
 
-const agent = await createAgent(def, {
-  source: {
-    id: SYSTEM_ONE_PROVIDER,
-    provider: SYSTEM_ONE_PROVIDER,
-    model: "jev-latest",
-    apiKey: process.env.TYPESAFE_API_KEY,
-    adapter: createSystemOneAdapter(),
-  },
-});
+`Question`, `QuestionList`, `Decision`, `EvaluateInput`, `EvaluateConfig`, `EndpointConfig`, `EvaluateResult` and `FallbackResult` are exported as arktype schemas and types.
 
-const { reply } = await agent.send("Deploy to production?", {
-  providerOptions: { systemOne: { questions } },
-});
-```
+### Questions
 
-What the adapter emits (what `reply` is assembled from):
+| `type`    | Fields                                                                          | Decision fields                                  |
+| --------- | ------------------------------------------------------------------------------- | ------------------------------------------------ |
+| `choice`  | `instructions`, `criteria` (option name → description or `null`, 1–255 options) | `choice`, `probabilities`, `confidence`          |
+| `score`   | `instructions`, `criteria` (2–10 descriptions)                                  | `score`, `legend`, `probabilities`, `confidence` |
+| `boolean` | `instructions`, optional `criteria: { true?, false? }`                          | `noul`                                           |
+| `noul`    | Same as `boolean`                                                               | `noul`                                           |
 
-```ts
-[
-  {
-    type: "inference.text.delta",
-    data: {
-      index: 0,
-      token:
-        '{"id":"route","type":"choice","choice":"deny","confidence":0.86,"probabilities":{"allow":0.14,"deny":0.86}}',
-    },
-  },
-  {
-    type: "inference.text.delta",
-    data: {
-      index: 1,
-      token: '{"id":"escalate","type":"noul","noul":0.91}',
-    },
-  },
-  {
-    type: "inference.usage",
-    data: {
-      usage: {
-        input: 296,
-        output: 20,
-        cacheRead: 0,
-        cacheWrite: 0,
-        thinking: 0,
-      },
-    },
-  },
-];
-```
+Every question has an `id`, unique within the list.
 
-`JSON.parse` each `token` and you have the same decision objects as
-`result.decisions`. There is no `fallback` flag on this path: a bad
-wire body is a `ProtocolMismatchError`; auth/retry stay with the
-harness (`retry-after` is surfaced for 429/529).
+### Config
 
-### Workflow step
+`input.config` for `evaluate`, or the argument to `createSystemOneAdapter`:
 
-Same provider and options bag:
+| Field       | Type             | Default                | Description                                                                      |
+| ----------- | ---------------- | ---------------------- | -------------------------------------------------------------------------------- |
+| `endpoint`  | `EndpointConfig` | `{ kind: "official" }` | `official`, `gateway`, or `custom` with a `url`. Each takes an optional `model`. |
+| `timeoutMs` | `number`         | `1500`                 | Bound for the whole round trip.                                                  |
+| `apiKey`    | `string`         | from the environment   | Overrides the environment key.                                                   |
+
+### Endpoints and keys
+
+| `kind`     | URL                                                  | Default model     | Key from the environment                       |
+| ---------- | ---------------------------------------------------- | ----------------- | ---------------------------------------------- |
+| `official` | `https://api.typesafe.ai/v1/systemone`               | `jev-latest`      | `TYPESAFE_API_KEY`                             |
+| `gateway`  | `https://ai-gateway.vercel.sh/typesafe/v1/systemone` | `typesafe-ai/jev` | `AI_GATEWAY_API_KEY`, then `VERCEL_OIDC_TOKEN` |
+| `custom`   | `url`                                                | `typesafe-ai/jev` | `SYSTEM_ONE_API_KEY`                           |
+
+`SYSTEM_ONE_API_KEY` is also a supported alias on every endpoint, read after the endpoint's own key.
+
+### Fallback reasons
+
+| `reason`      | When                                                          |
+| ------------- | ------------------------------------------------------------- |
+| `no-key`      | No key in `apiKey` or the environment. No request is sent.    |
+| `timeout`     | The round trip, including the body read, exceeds `timeoutMs`. |
+| `network`     | The request fails before a response.                          |
+| `http-error`  | Non-2xx response. `httpStatus` holds the status.              |
+| `parse-error` | The body is not JSON or fails validation.                     |
+
+`detail` carries the underlying message.
+
+## Using with Interchange
+
+Register the adapter under `SYSTEM_ONE_PROVIDER` and pass questions per call in `providerOptions.systemOne` (`{ state?, questions? }`). Without `state`, the adapter sends the transcript text as state. Without `questions`, it asks one boolean question with id `response`.
 
 ```ts
-import { defineWorkflow } from "@intx/workflow";
+import { createDependencies, runInference } from "@intx/inference";
 import {
   createSystemOneAdapter,
   SYSTEM_ONE_PROVIDER,
+  type QuestionList,
 } from "@corbits/system-one";
 
-export const refundGate = defineWorkflow({
-  id: "refund-gate",
-  steps: [
+const deps = createDependencies({
+  has: (provider) => provider === SYSTEM_ONE_PROVIDER,
+  resolve: () => createSystemOneAdapter(),
+});
+
+const questions = [
+  {
+    id: "escalate",
+    type: "boolean",
+    instructions: "Must this request be escalated for human approval?",
+  },
+] satisfies QuestionList;
+
+let seq = 0;
+for await (const event of runInference({
+  deps,
+  source: {
+    id: "system-one",
+    provider: SYSTEM_ONE_PROVIDER,
+    baseURL: "https://api.typesafe.ai/v1/systemone",
+    credentialId: "TYPESAFE_API_KEY",
+    model: "jev-latest",
+  },
+  turns: [
     {
-      id: "decide",
-      inference: {
-        source: {
-          provider: SYSTEM_ONE_PROVIDER,
-          model: "jev-latest",
-          adapter: createSystemOneAdapter(),
-        },
-        providerOptions: {
-          systemOne: {
-            state: { amount: 48, priorRefunds: 1 },
-            questions: [
-              {
-                id: "approve",
-                type: "boolean",
-                instructions: "Approve this refund without review?",
-              },
-            ],
-          },
-        },
-      },
+      role: "user",
+      timestamp: Date.now(),
+      content: [{ type: "text", text: "Deploy to production?" }],
     },
   ],
-});
+  inferenceOptions: { providerOptions: { systemOne: { questions } } },
+  nextSeq: () => seq++,
+  readMaterial: (id) => {
+    const secret = process.env[id];
+    if (secret === undefined) throw new Error(`${id} is not set`);
+    return { secret };
+  },
+})) {
+  if (event.type === "inference.text.delta")
+    console.log(JSON.parse(event.data.token));
+}
 ```
 
-The step's inference output is the same event list: one text delta
-whose token is `{"id":"approve","type":"noul","noul":0.2}`, then
-usage.
-
-## How it works
+The adapter emits one `inference.text.delta` per decision, whose `token` is the decision as JSON, then an `inference.usage` event. The harness supplies the credential through `readMaterial` and owns retries. A malformed response body is a `ProtocolMismatchError`, not a fallback.
 
-- **Wire.** Live Jev contract ([docs.typesafe.ai](https://docs.typesafe.ai)):
-  `state` is string | object | array; questions go out as an id-keyed
-  map; answers come back the same way.
-- **Adapter.** Transcript → evaluation state; each decision →
-  `inference.text.delta`; token counts → `inference.usage`.
-- **Schemas.** Every trust boundary is arktype (`src/schemas.ts`).
-  Confidence is narrowed, not clamped. Public surface is
-  `src/index.ts` only.
-- **Telemetry.** Direct `evaluate()` records `evaluate.start` /
-  `.success` / `.fallback` in-memory (`drainTelemetryEvents`). No keys
-  in events.
-
-## Development
-
-```
-bun install
-bun run check   # typecheck + lint + format:check + test
-```
+## Upgrading from 0.1
 
-Compiled `dist/` is built with `tsc -p tsconfig.build.json` (no
-bundler) and ships on npm; `prepack` rebuilds so every pack/publish
-carries fresh output.
+- `HttpError`, `NetworkError` and `TimeoutError` are removed. Transport failures return a `FallbackResult`.
+- A 2xx body that is not JSON is `parse-error` (was `network`). A timeout during the body read is `timeout`.
+- `recordTelemetryEvent` and `drainTelemetryEvents` are removed. Pass `evaluate(input, { onTelemetry })`.
+- Wire helpers, quirks presets, `JsonRecord`, `Confidence` and the env-var name constants are no longer exported.
+- A `custom` endpoint without a `model` sends `typesafe-ai/jev`.
+- Peers are `@intx/inference` and `@intx/types` `^0.4.0`.
+- Environment variables are unchanged, including `SYSTEM_ONE_API_KEY`.
 
 ## License
 
-LGPL-2.1-only.
+[LGPL-2.1-only](https://github.com/corbitsdev/corbits-system-one/blob/main/LICENSE)

package/dist/adapter.js

@@ -100,7 +100,7 @@ function parseDecisions(body, provider) {
             throw new ProtocolMismatchError(`${provider} parseJSONResponse: ${cause instanceof Error ? cause.message : String(cause)}`, parsed);
         }
     });
-    return { decisions, usage: envelope.usage };
+    return { decisions, model: envelope.model, usage: envelope.usage };
 }
 /**
  * Builds the Interchange `ProviderAdapter` for System One against the
@@ -111,11 +111,6 @@ function parseDecisions(body, provider) {
  */
 export function createSystemOneAdapter(config) {
     const endpoint = resolveEndpoint(config?.endpoint);
-    const source = {
-        sourceId: SYSTEM_ONE_PROVIDER,
-        provider: SYSTEM_ONE_PROVIDER,
-        model: endpoint.model ?? "unknown",
-    };
     const buildRequest = (messages, model, options) => {
         let state = { transcript: transcriptText(messages) };
         let questions = DEFAULT_QUESTIONS;
@@ -130,8 +125,7 @@ export function createSystemOneAdapter(config) {
             if (overrides.questions !== undefined)
                 questions = overrides.questions;
         }
-        const requestModel = model || endpoint.model || "unknown";
-        source.model = requestModel;
+        const requestModel = model || endpoint.model;
         const headers = {
             "content-type": "application/json",
             accept: "application/json",
@@ -148,7 +142,7 @@ export function createSystemOneAdapter(config) {
         };
     };
     const parseJSONResponse = (responseBody) => {
-        const { decisions, usage } = parseDecisions(responseBody, SYSTEM_ONE_PROVIDER);
+        const { decisions, model, usage } = parseDecisions(responseBody, SYSTEM_ONE_PROVIDER);
         const events = [];
         let index = 0;
         for (const decision of decisions) {
@@ -163,7 +157,14 @@ export function createSystemOneAdapter(config) {
         events.push({
             type: "inference.usage",
             seq: 0,
-            data: { usage: toTokenUsage(usage), source: { ...source } },
+            data: {
+                usage: toTokenUsage(usage),
+                source: {
+                    sourceId: SYSTEM_ONE_PROVIDER,
+                    provider: SYSTEM_ONE_PROVIDER,
+                    model: model ?? endpoint.model,
+                },
+            },
         });
         return events;
     };

package/dist/client.d.ts

@@ -1,8 +1,11 @@
+import { type Dependencies } from "@intx/inference";
 /** Options for one evaluation POST: timeout and auth, resolved by `evaluate`. */
 export type PostEvaluateOptions = {
     timeoutMs?: number;
     apiKey?: string;
 };
+/** Transport dependencies: the `fetch` to POST with and the timeout scheduler. */
+export type EvaluateDeps = Pick<Dependencies, "fetch" | "scheduler">;
 /** The decoded JSON body of a 2xx evaluation response, with its latency. */
 export type PostEvaluateResponse = {
     data: unknown;
@@ -12,10 +15,12 @@ export type PostEvaluateResponse = {
 /**
  * POSTs an evaluation payload and returns the decoded JSON body. Sends
  * `Authorization: Bearer <apiKey>` only when a key is present; aborts the
- * exchange when `timeoutMs` elapses. A `timeoutMs` that is not a finite
- * number >= 0 falls back to `DEFAULT_TIMEOUT_MS`. Throws `TimeoutError` on
- * timeout, `HttpError` (status only, never the body) on non-2xx, and
- * `NetworkError` when no HTTP exchange completes or the 2xx body is not
- * valid JSON.
+ * exchange when `timeoutMs` elapses on `deps.scheduler`. A `timeoutMs`
+ * that is not a finite number >= 0 falls back to `DEFAULT_TIMEOUT_MS`.
+ * Throws a `TransportError` carrying a `timeout` classification on
+ * timeout, a `classifyHTTPError` classification (status only, never the
+ * body) on non-2xx, a `classifyNetworkError` classification when no HTTP
+ * exchange completes, and a `classifyProtocolMismatch` classification when
+ * the 2xx body is not valid JSON.
  */
-export declare function postEvaluate(url: string, body: unknown, options: PostEvaluateOptions): Promise<PostEvaluateResponse>;
+export declare function postEvaluate(url: string, body: unknown, options: PostEvaluateOptions, deps: EvaluateDeps): Promise<PostEvaluateResponse>;

package/dist/client.js

@@ -1,15 +1,18 @@
+import { classifyHTTPError, classifyNetworkError, classifyProtocolMismatch, } from "@intx/inference";
 import { DEFAULT_TIMEOUT_MS } from "./config.js";
-import { HttpError, NetworkError, SystemOneError, TimeoutError, } from "./errors.js";
+import { SystemOneError, TransportError } from "./errors.js";
 /**
  * POSTs an evaluation payload and returns the decoded JSON body. Sends
  * `Authorization: Bearer <apiKey>` only when a key is present; aborts the
- * exchange when `timeoutMs` elapses. A `timeoutMs` that is not a finite
- * number >= 0 falls back to `DEFAULT_TIMEOUT_MS`. Throws `TimeoutError` on
- * timeout, `HttpError` (status only, never the body) on non-2xx, and
- * `NetworkError` when no HTTP exchange completes or the 2xx body is not
- * valid JSON.
+ * exchange when `timeoutMs` elapses on `deps.scheduler`. A `timeoutMs`
+ * that is not a finite number >= 0 falls back to `DEFAULT_TIMEOUT_MS`.
+ * Throws a `TransportError` carrying a `timeout` classification on
+ * timeout, a `classifyHTTPError` classification (status only, never the
+ * body) on non-2xx, a `classifyNetworkError` classification when no HTTP
+ * exchange completes, and a `classifyProtocolMismatch` classification when
+ * the 2xx body is not valid JSON.
  */
-export async function postEvaluate(url, body, options) {
+export async function postEvaluate(url, body, options, deps) {
     let serialized;
     try {
         serialized = JSON.stringify(body);
@@ -24,10 +27,16 @@ export async function postEvaluate(url, body, options) {
         ? rawTimeoutMs
         : DEFAULT_TIMEOUT_MS;
     const controller = new AbortController();
-    const timer = setTimeout(() => {
+    const cancelTimeout = deps.scheduler.setTimeout(() => {
         controller.abort();
     }, timeoutMs);
-    const start = Date.now();
+    const start = deps.scheduler.now();
+    // The timeout can fire while awaiting headers or while reading the body.
+    // Built by hand: @intx/inference does not export classifyTimeoutError.
+    const timedOut = {
+        category: "timeout",
+        message: `system-one request timed out after ${timeoutMs}ms`,
+    };
     try {
         const headers = {
             "content-type": "application/json",
@@ -38,7 +47,7 @@ export async function postEvaluate(url, body, options) {
         }
         let res;
         try {
-            res = await fetch(url, {
+            res = await deps.fetch(url, {
                 method: "POST",
                 headers,
                 body: serialized,
@@ -46,22 +55,27 @@ export async function postEvaluate(url, body, options) {
             });
         }
         catch (cause) {
-            if (controller.signal.aborted)
-                throw new TimeoutError(timeoutMs);
-            throw new NetworkError(`system-one request failed: ${cause instanceof Error ? cause.message : String(cause)}`);
+            throw new TransportError(controller.signal.aborted ? timedOut : classifyNetworkError(cause));
+        }
+        if (!res.ok) {
+            throw new TransportError(classifyHTTPError(res.status, `system-one request failed with HTTP ${res.status}`));
         }
-        if (!res.ok)
-            throw new HttpError(res.status);
         let data;
         try {
             data = await res.json();
         }
         catch {
-            throw new NetworkError("system-one response body is not valid JSON");
+            throw new TransportError(controller.signal.aborted
+                ? timedOut
+                : classifyProtocolMismatch("system-one response body could not be read as JSON"));
         }
-        return { data, latencyMs: Date.now() - start, httpStatus: res.status };
+        return {
+            data,
+            latencyMs: deps.scheduler.now() - start,
+            httpStatus: res.status,
+        };
     }
     finally {
-        clearTimeout(timer);
+        cancelTimeout();
     }
 }

package/dist/config.d.ts

@@ -4,8 +4,14 @@ export declare const SystemOneQuirks: import("arktype/internal/variants/object.t
     model?: string;
 }, {}>;
 export type SystemOneQuirks = typeof SystemOneQuirks.infer;
-export declare const SYSTEM_ONE_DEFAULT_QUIRKS: SystemOneQuirks;
-export declare const GATEWAY_QUIRKS: SystemOneQuirks;
+export declare const SYSTEM_ONE_DEFAULT_QUIRKS: {
+    baseUrl: string;
+    model: string;
+};
+export declare const GATEWAY_QUIRKS: {
+    baseUrl: string;
+    model: string;
+};
 export declare const TYPESAFE_API_KEY_ENV = "TYPESAFE_API_KEY";
 export declare const GATEWAY_API_KEY_ENV = "AI_GATEWAY_API_KEY";
 export declare const GATEWAY_OIDC_ENV = "VERCEL_OIDC_TOKEN";
@@ -23,7 +29,7 @@ export declare const DEFAULT_TIMEOUT_MS = 1500;
 export type ResolvedEndpoint = {
     url: string;
     backend: "corbits-system-one" | "gateway" | "custom";
-    model?: string;
+    model: string;
 };
 /**
  * Resolves an evaluation endpoint to a concrete POST target. A per-call
@@ -31,6 +37,7 @@ export type ResolvedEndpoint = {
  * carry its own `url` and throws a typed `SystemOneError` when it does
  * not. A `custom` target keeps the `'custom'` backend label so telemetry
  * distinguishes caller-routed traffic from the official endpoint —
- * `'gateway'` is reserved for the proxy quirks path.
+ * `'gateway'` is reserved for the proxy quirks path. The model always
+ * resolves here: a `custom` target without one sends `typesafe-ai/jev`.
  */
 export declare function resolveEndpoint(endpoint?: EndpointConfig): ResolvedEndpoint;

package/dist/config.js

@@ -32,8 +32,8 @@ export const GATEWAY_QUIRKS = {
 };
 // Credential sources, one per endpoint: a TypeSafe key never authenticates
 // to the gateway and a gateway key never authenticates to TypeSafe direct,
-// so each endpoint reads its own names. `SYSTEM_ONE_API_KEY` stays as the
-// legacy universal fallback (and the key for `custom` endpoints).
+// so each endpoint reads its own names. `SYSTEM_ONE_API_KEY` is a supported
+// alias for every endpoint (and the key for `custom` endpoints).
 export const TYPESAFE_API_KEY_ENV = "TYPESAFE_API_KEY";
 export const GATEWAY_API_KEY_ENV = "AI_GATEWAY_API_KEY";
 export const GATEWAY_OIDC_ENV = "VERCEL_OIDC_TOKEN";
@@ -59,17 +59,19 @@ export const DEFAULT_TIMEOUT_MS = 1500;
  * carry its own `url` and throws a typed `SystemOneError` when it does
  * not. A `custom` target keeps the `'custom'` backend label so telemetry
  * distinguishes caller-routed traffic from the official endpoint —
- * `'gateway'` is reserved for the proxy quirks path.
+ * `'gateway'` is reserved for the proxy quirks path. The model always
+ * resolves here: a `custom` target without one sends `typesafe-ai/jev`.
  */
 export function resolveEndpoint(endpoint) {
     if (endpoint?.kind === "custom") {
         if (endpoint.url === "") {
             throw new SystemOneError("config-error", 'evaluate: endpoint kind "custom" requires an explicit url');
         }
-        const resolved = { url: endpoint.url, backend: "custom" };
-        if (endpoint.model !== undefined)
-            resolved.model = endpoint.model;
-        return resolved;
+        return {
+            url: endpoint.url,
+            backend: "custom",
+            model: endpoint.model ?? GATEWAY_QUIRKS.model,
+        };
     }
     const kind = endpoint?.kind ?? "official";
     const quirks = kind === "gateway" ? GATEWAY_QUIRKS : SYSTEM_ONE_DEFAULT_QUIRKS;
@@ -77,12 +79,9 @@ export function resolveEndpoint(endpoint) {
     if (url === undefined || url === "") {
         throw new SystemOneError("backend-unreachable", `evaluate: no baseUrl configured for endpoint kind "${kind}"`);
     }
-    const resolved = {
+    return {
         url,
         backend: kind === "gateway" ? "gateway" : "corbits-system-one",
+        model: endpoint?.model ?? quirks.model,
     };
-    const model = endpoint?.model ?? quirks.model;
-    if (model !== undefined)
-        resolved.model = model;
-    return resolved;
 }

package/dist/errors.d.ts

@@ -1,35 +1,22 @@
+import type { InferenceError } from "@intx/types/runtime";
 import type { FallbackReason } from "./schemas.js";
 /** Every error code `evaluate` can throw. Thrown-only codes (`"not-implemented"`, `"config-error"`) never appear as fallback reasons. */
 export type SystemOneErrorCode = FallbackReason | "not-implemented" | "config-error";
 /** Typed error thrown when `evaluate` cannot return a result at all. */
 export declare class SystemOneError extends Error {
     readonly code: SystemOneErrorCode;
-    constructor(code: SystemOneErrorCode, message: string);
+    readonly reason?: InferenceError;
+    constructor(code: SystemOneErrorCode, message: string, reason?: InferenceError);
 }
-/**
- * The evaluation POST exceeded its timeout budget. Thrown by `postEvaluate`;
- * `evaluate` reports it as a `FallbackResult` with reason `'timeout'`.
- */
-export declare class TimeoutError extends SystemOneError {
-    readonly timeoutMs: number;
-    constructor(timeoutMs: number);
-}
-/**
- * The evaluation POST never completed an HTTP exchange (DNS/TLS failure,
- * refused connection, reset stream) or the 200 body was not valid JSON.
- * Thrown by `postEvaluate`; `evaluate` reports it as a `FallbackResult`
- * with reason `'network'`.
- */
-export declare class NetworkError extends SystemOneError {
-    constructor(message: string);
+/** A transport failure: always carries its `InferenceError` classification. */
+export declare class TransportError extends SystemOneError {
+    readonly reason: InferenceError;
+    constructor(reason: InferenceError);
 }
 /**
- * The evaluation POST completed with a non-2xx status. Carries the status
- * only — never the response body, which is untrusted vendor output.
- * Thrown by `postEvaluate`; `evaluate` reports it as a `FallbackResult`
- * with reason `'http-error'`.
+ * Maps a transport classification to its fallback reason: a timeout stays
+ * `'timeout'`, an unreadable body is `'parse-error'`, anything with an HTTP
+ * status is `'http-error'`, and the rest never completed an exchange
+ * (`'network'`).
  */
-export declare class HttpError extends SystemOneError {
-    readonly httpStatus: number;
-    constructor(httpStatus: number);
-}
+export declare function transportFallbackReason(reason: InferenceError): FallbackReason;

package/dist/errors.js

@@ -1,47 +1,33 @@
 /** Typed error thrown when `evaluate` cannot return a result at all. */
 export class SystemOneError extends Error {
     code;
-    constructor(code, message) {
+    reason;
+    constructor(code, message, reason) {
         super(message);
         this.name = "SystemOneError";
         this.code = code;
+        if (reason !== undefined)
+            this.reason = reason;
     }
 }
-/**
- * The evaluation POST exceeded its timeout budget. Thrown by `postEvaluate`;
- * `evaluate` reports it as a `FallbackResult` with reason `'timeout'`.
- */
-export class TimeoutError extends SystemOneError {
-    timeoutMs;
-    constructor(timeoutMs) {
-        super("timeout", `system-one request timed out after ${timeoutMs}ms`);
-        this.name = "TimeoutError";
-        this.timeoutMs = timeoutMs;
+/** A transport failure: always carries its `InferenceError` classification. */
+export class TransportError extends SystemOneError {
+    constructor(reason) {
+        super(transportFallbackReason(reason), reason.message, reason);
     }
 }
 /**
- * The evaluation POST never completed an HTTP exchange (DNS/TLS failure,
- * refused connection, reset stream) or the 200 body was not valid JSON.
- * Thrown by `postEvaluate`; `evaluate` reports it as a `FallbackResult`
- * with reason `'network'`.
+ * Maps a transport classification to its fallback reason: a timeout stays
+ * `'timeout'`, an unreadable body is `'parse-error'`, anything with an HTTP
+ * status is `'http-error'`, and the rest never completed an exchange
+ * (`'network'`).
  */
-export class NetworkError extends SystemOneError {
-    constructor(message) {
-        super("network", message);
-        this.name = "NetworkError";
-    }
-}
-/**
- * The evaluation POST completed with a non-2xx status. Carries the status
- * only — never the response body, which is untrusted vendor output.
- * Thrown by `postEvaluate`; `evaluate` reports it as a `FallbackResult`
- * with reason `'http-error'`.
- */
-export class HttpError extends SystemOneError {
-    httpStatus;
-    constructor(httpStatus) {
-        super("http-error", `system-one request failed with HTTP ${httpStatus}`);
-        this.name = "HttpError";
-        this.httpStatus = httpStatus;
-    }
+export function transportFallbackReason(reason) {
+    if (reason.category === "timeout")
+        return "timeout";
+    if (reason.category === "protocol_mismatch")
+        return "parse-error";
+    if (reason.statusCode !== undefined)
+        return "http-error";
+    return "network";
 }

package/dist/evaluate.d.ts

@@ -1,4 +1,16 @@
-import { EvaluateInput, type EvaluateResult, type FallbackResult } from "./schemas.js";
+import { type EvaluateDeps } from "./client.js";
+import { EvaluateInput, type EvaluateResult, type FallbackResult, type Question, type WireAnswer } from "./schemas.js";
+import type { SystemOneTelemetryEvent } from "./telemetry.js";
+export declare function checkAnswers(questions: Question[], answers: Record<string, WireAnswer>): string | undefined;
+/**
+ * Per-call hooks for `evaluate`: `onTelemetry` receives each lifecycle
+ * event and must not throw, since a throw propagates out of `evaluate`;
+ * `deps` replaces the global `fetch` and `createDefaultScheduler()`.
+ */
+export type EvaluateOptions = {
+    onTelemetry?: (event: SystemOneTelemetryEvent) => void;
+    deps?: EvaluateDeps;
+};
 /**
  * Runs one typed-decision evaluation against System One (or its gateway)
  * and returns either the backend's decisions or a typed fallback. One POST
@@ -6,13 +18,16 @@ import { EvaluateInput, type EvaluateResult, type FallbackResult } from "./schem
  * a non-empty per-call `apiKey` (an empty string falls through to the
  * environment, never shadowing it), then the endpoint's environment key —
  * `TYPESAFE_API_KEY` for official, `AI_GATEWAY_API_KEY` then
- * `VERCEL_OIDC_TOKEN` for gateway — then the legacy `SYSTEM_ONE_API_KEY`
- * fallback, then a fail-closed `'no-key'` fallback with zero fetch calls.
+ * `VERCEL_OIDC_TOKEN` for gateway — then the `SYSTEM_ONE_API_KEY` alias,
+ * then a fail-closed `'no-key'` fallback with zero fetch calls.
  * A `timeoutMs` that is not a finite number >= 0 falls back to
  * `DEFAULT_TIMEOUT_MS`. Transport failures map to matching fallback reasons
- * (`'timeout'`, `'network'`, `'http-error'`); backend output that fails
- * strict validation maps to `'parse-error'` with the violation in `detail`.
+ * (`'timeout'`, `'network'`, `'http-error'`, or `'parse-error'` for a 2xx
+ * body that is not JSON) with the transport message in `detail`; backend
+ * output that fails strict validation maps to `'parse-error'` with the
+ * violation in `detail`.
  * Only caller-side misuse (invalid input, a `custom` endpoint without a
- * `url`) throws, as a typed `SystemOneError`.
+ * `url`) throws, as a typed `SystemOneError`. Lifecycle events go to
+ * `options.onTelemetry` when supplied.
  */
-export declare function evaluate(input: EvaluateInput): Promise<EvaluateResult | FallbackResult>;
+export declare function evaluate(input: EvaluateInput, options?: EvaluateOptions): Promise<EvaluateResult | FallbackResult>;

package/dist/evaluate.js

@@ -1,9 +1,9 @@
 import { type } from "arktype";
+import { createDefaultScheduler } from "@intx/inference";
 import { postEvaluate } from "./client.js";
 import { DEFAULT_TIMEOUT_MS, GATEWAY_API_KEY_ENV, GATEWAY_OIDC_ENV, resolveEndpoint, SYSTEM_ONE_API_KEY_ENV, TYPESAFE_API_KEY_ENV, } from "./config.js";
-import { HttpError, NetworkError, SystemOneError, TimeoutError, } from "./errors.js";
+import { SystemOneError, TransportError, transportFallbackReason, } from "./errors.js";
 import { APPROXIMATE_SUM_TOLERANCE as SUM_TOLERANCE, EvaluateInput, toDecision, toWireQuestions, WireRequest, WireResponseBody, } from "./schemas.js";
-import { recordTelemetryEvent, } from "./telemetry.js";
 // ---------------------------------------------------------------------------
 // evaluate
 // ---------------------------------------------------------------------------
@@ -100,7 +100,7 @@ function checkAnswer(question, id, answer) {
     if (question.type === "choice" && answer.type === "choice") {
         if (answer.choice === undefined)
             return `answer "${id}" is missing choice`;
-        if (!(answer.choice in question.criteria)) {
+        if (!Object.hasOwn(question.criteria, answer.choice)) {
             return `answer "${id}" illegal option ${JSON.stringify(answer.choice)}`;
         }
         return checkProbabilities(id, Object.keys(question.criteria), answer.probabilities);
@@ -149,7 +149,7 @@ function checkProbabilities(id, requiredKeys, probabilities) {
 // questions: the answer key set must equal the submitted id set exactly (no
 // unknowns, no drops — map keys are unique by construction), and each answer
 // must satisfy its question. Returns the first violation, if any.
-function checkAnswers(questions, answers) {
+export function checkAnswers(questions, answers) {
     const byId = new Map();
     for (const question of questions)
         byId.set(question.id, question);
@@ -181,17 +181,27 @@ function envKey(name) {
  * a non-empty per-call `apiKey` (an empty string falls through to the
  * environment, never shadowing it), then the endpoint's environment key —
  * `TYPESAFE_API_KEY` for official, `AI_GATEWAY_API_KEY` then
- * `VERCEL_OIDC_TOKEN` for gateway — then the legacy `SYSTEM_ONE_API_KEY`
- * fallback, then a fail-closed `'no-key'` fallback with zero fetch calls.
+ * `VERCEL_OIDC_TOKEN` for gateway — then the `SYSTEM_ONE_API_KEY` alias,
+ * then a fail-closed `'no-key'` fallback with zero fetch calls.
  * A `timeoutMs` that is not a finite number >= 0 falls back to
  * `DEFAULT_TIMEOUT_MS`. Transport failures map to matching fallback reasons
- * (`'timeout'`, `'network'`, `'http-error'`); backend output that fails
- * strict validation maps to `'parse-error'` with the violation in `detail`.
+ * (`'timeout'`, `'network'`, `'http-error'`, or `'parse-error'` for a 2xx
+ * body that is not JSON) with the transport message in `detail`; backend
+ * output that fails strict validation maps to `'parse-error'` with the
+ * violation in `detail`.
  * Only caller-side misuse (invalid input, a `custom` endpoint without a
- * `url`) throws, as a typed `SystemOneError`.
+ * `url`) throws, as a typed `SystemOneError`. Lifecycle events go to
+ * `options.onTelemetry` when supplied.
  */
-export async function evaluate(input) {
-    const start = Date.now();
+export async function evaluate(input, options) {
+    const deps = options?.deps ?? {
+        fetch: globalThis.fetch,
+        scheduler: createDefaultScheduler(),
+    };
+    const start = deps.scheduler.now();
+    const emit = (event) => {
+        options?.onTelemetry?.(event);
+    };
     const parsed = EvaluateInput(input);
     if (parsed instanceof type.errors) {
         let summary = parsed.summary;
@@ -230,12 +240,12 @@ export async function evaluate(input) {
         apiKey = envKey(SYSTEM_ONE_API_KEY_ENV);
         keySources = SYSTEM_ONE_API_KEY_ENV;
     }
-    const model = endpoint.model ?? "typesafe-ai/jev";
+    const model = endpoint.model;
     const fallback = (reason, extra) => {
         const result = {
             fallback: true,
             reason,
-            latencyMs: Date.now() - start,
+            latencyMs: deps.scheduler.now() - start,
             backendAttempted,
         };
         if (extra?.httpStatus !== undefined)
@@ -251,7 +261,7 @@ export async function evaluate(input) {
         };
         if (extra?.detail !== undefined)
             event.detail = extra.detail;
-        recordTelemetryEvent(event);
+        emit(event);
         return result;
     };
     const startEvent = {
@@ -260,7 +270,7 @@ export async function evaluate(input) {
         latencyMs: 0,
         modelId: model,
     };
-    recordTelemetryEvent(startEvent);
+    emit(startEvent);
     if (apiKey === undefined || apiKey === "") {
         return fallback("no-key", {
             detail: `no API key supplied; set config.apiKey or ${keySources}`,
@@ -277,22 +287,21 @@ export async function evaluate(input) {
     let data;
     let transportLatencyMs;
     try {
-        const response = await postEvaluate(endpoint.url, wire, {
-            timeoutMs,
-            apiKey,
-        });
+        const response = await postEvaluate(endpoint.url, wire, { timeoutMs, apiKey }, deps);
         data = response.data;
         transportLatencyMs = response.latencyMs;
     }
     catch (cause) {
-        if (cause instanceof HttpError) {
-            return fallback("http-error", { httpStatus: cause.httpStatus });
+        if (!(cause instanceof TransportError))
+            throw cause;
+        const reason = transportFallbackReason(cause.reason);
+        if (cause.reason.statusCode === undefined) {
+            return fallback(reason, { detail: cause.message });
         }
-        if (cause instanceof TimeoutError)
-            return fallback("timeout");
-        if (cause instanceof NetworkError)
-            return fallback("network");
-        throw cause;
+        return fallback(reason, {
+            httpStatus: cause.reason.statusCode,
+            detail: cause.message,
+        });
     }
     const envelope = WireResponseBody(data);
     if (envelope instanceof type.errors) {
@@ -341,6 +350,6 @@ export async function evaluate(input) {
         latencyMs: result.latencyMs,
         modelId,
     };
-    recordTelemetryEvent(successEvent);
+    emit(successEvent);
     return result;
 }

package/dist/index.d.ts

@@ -1,9 +1,9 @@
-export { DEFAULT_TIMEOUT_MS, GATEWAY_API_KEY_ENV, GATEWAY_OIDC_ENV, GATEWAY_QUIRKS, SYSTEM_ONE_API_KEY_ENV, SYSTEM_ONE_DEFAULT_QUIRKS, SystemOneQuirks, TYPESAFE_API_KEY_ENV, } from "./config.js";
-export { postEvaluate } from "./client.js";
-export type { PostEvaluateOptions, PostEvaluateResponse } from "./client.js";
+export { DEFAULT_TIMEOUT_MS } from "./config.js";
+export type { EvaluateDeps } from "./client.js";
 export { evaluate } from "./evaluate.js";
+export type { EvaluateOptions } from "./evaluate.js";
 export { createSystemOneAdapter, SYSTEM_ONE_PROVIDER } from "./adapter.js";
-export { HttpError, NetworkError, SystemOneError, TimeoutError, } from "./errors.js";
+export { SystemOneError } from "./errors.js";
 export type { SystemOneErrorCode } from "./errors.js";
-export { drainTelemetryEvents, MAX_BUFFERED_TELEMETRY_EVENTS, recordTelemetryEvent, SystemOneTelemetryEvent, } from "./telemetry.js";
-export { APPROXIMATE_SUM_TOLERANCE, BooleanQuestion, ChoiceQuestion, Confidence, Decision, Description, EndpointConfig, EvaluateConfig, EvaluateInput, EvaluateResult, EvaluateResponseBody, FallbackReason, FallbackResult, JsonRecord, NoulQuestion, ProbabilityMap, Question, QuestionList, ScoreQuestion, State, toDecision, toWireQuestions, Usage, WireAnswer, WireQuestion, WireRequest, WireResponseBody, WireUsage, } from "./schemas.js";
+export { SystemOneTelemetryEvent } from "./telemetry.js";
+export { BooleanQuestion, ChoiceQuestion, Decision, Description, EndpointConfig, EvaluateConfig, EvaluateInput, EvaluateResult, FallbackReason, FallbackResult, NoulQuestion, ProbabilityMap, Question, QuestionList, ScoreQuestion, State, Usage, } from "./schemas.js";

package/dist/index.js

@@ -1,7 +1,6 @@
-export { DEFAULT_TIMEOUT_MS, GATEWAY_API_KEY_ENV, GATEWAY_OIDC_ENV, GATEWAY_QUIRKS, SYSTEM_ONE_API_KEY_ENV, SYSTEM_ONE_DEFAULT_QUIRKS, SystemOneQuirks, TYPESAFE_API_KEY_ENV, } from "./config.js";
-export { postEvaluate } from "./client.js";
+export { DEFAULT_TIMEOUT_MS } from "./config.js";
 export { evaluate } from "./evaluate.js";
 export { createSystemOneAdapter, SYSTEM_ONE_PROVIDER } from "./adapter.js";
-export { HttpError, NetworkError, SystemOneError, TimeoutError, } from "./errors.js";
-export { drainTelemetryEvents, MAX_BUFFERED_TELEMETRY_EVENTS, recordTelemetryEvent, SystemOneTelemetryEvent, } from "./telemetry.js";
-export { APPROXIMATE_SUM_TOLERANCE, BooleanQuestion, ChoiceQuestion, Confidence, Decision, Description, EndpointConfig, EvaluateConfig, EvaluateInput, EvaluateResult, EvaluateResponseBody, FallbackReason, FallbackResult, JsonRecord, NoulQuestion, ProbabilityMap, Question, QuestionList, ScoreQuestion, State, toDecision, toWireQuestions, Usage, WireAnswer, WireQuestion, WireRequest, WireResponseBody, WireUsage, } from "./schemas.js";
+export { SystemOneError } from "./errors.js";
+export { SystemOneTelemetryEvent } from "./telemetry.js";
+export { BooleanQuestion, ChoiceQuestion, Decision, Description, EndpointConfig, EvaluateConfig, EvaluateInput, EvaluateResult, FallbackReason, FallbackResult, NoulQuestion, ProbabilityMap, Question, QuestionList, ScoreQuestion, State, Usage, } from "./schemas.js";

package/dist/schemas.d.ts

@@ -373,29 +373,6 @@ export declare const Usage: import("arktype/internal/variants/object.ts").Object
     outputTokens: number;
 }, {}>;
 export type Usage = typeof Usage.infer;
-export declare const EvaluateResponseBody: import("arktype/internal/variants/object.ts").ObjectType<{
-    answers: {
-        [x: string]: {
-            type: "choice" | "score" | "noul";
-            choice?: string;
-            score?: number;
-            noul?: number;
-            probabilities?: {
-                [x: string]: number;
-            };
-            confidence?: number;
-            legend?: {
-                [x: string]: string;
-            };
-        };
-    };
-    model?: string;
-    usage?: {
-        input_tokens: number;
-        output_tokens: number;
-    };
-}, {}>;
-export type EvaluateResponseBody = typeof EvaluateResponseBody.infer;
 export declare const EvaluateResult: import("arktype/internal/variants/object.ts").ObjectType<{
     decisions: ({
         id: string;

package/dist/schemas.js

@@ -285,9 +285,6 @@ export const Usage = type({
     outputTokens: "number",
     "+": "reject",
 });
-// Backwards-compatible alias: the envelope shared by `evaluate()` and the
-// provider adapter.
-export const EvaluateResponseBody = WireResponseBody;
 export const EvaluateResult = type({
     decisions: Decision.array(),
     modelId: "string",

package/dist/telemetry.d.ts

@@ -8,17 +8,3 @@ export declare const SystemOneTelemetryEvent: import("arktype/internal/variants/
     detail?: string;
 }, {}>;
 export type SystemOneTelemetryEvent = typeof SystemOneTelemetryEvent.infer;
-/** Maximum buffered events; beyond this the oldest drop first. */
-export declare const MAX_BUFFERED_TELEMETRY_EVENTS = 256;
-/**
- * Records one telemetry event to the in-memory ring. Validates the shape
- * (a malformed event is caller misuse and throws a typed `SystemOneError`)
- * and never touches the network, disk, or console.
- */
-export declare function recordTelemetryEvent(event: SystemOneTelemetryEvent): void;
-/**
- * Drains the buffered telemetry events in arrival order and clears the
- * buffer. The host calls this after each evaluation (or on its own cadence)
- * to forward events to its own sink.
- */
-export declare function drainTelemetryEvents(): SystemOneTelemetryEvent[];

package/dist/telemetry.js

@@ -1,18 +1,13 @@
 import { type } from "arktype";
-import { SystemOneError } from "./errors.js";
 import { FallbackReason } from "./schemas.js";
 // ---------------------------------------------------------------------------
 // Telemetry
 // ---------------------------------------------------------------------------
 //
-// Event shapes for evaluation observability. Data only, no sink: events are
-// validated and buffered in a bounded in-memory ring the host drains with
-// `drainTelemetryEvents` and forwards wherever it wants (stdout, OTLP, a
-// host hook). A ring — not a pluggable sink — because a sink interface is a
-// second public surface to version for no load-bearing reason: the host
-// already owns every destination, it only needs lossless-per-call access to
-// the events. The cap keeps a chatty loop from growing memory without bound
-// (oldest events drop first). No event field ever carries key material.
+// Event shape for evaluation observability. `evaluate` hands each event to
+// the caller's `onTelemetry` sink, which forwards it wherever the host wants
+// (stdout, OTLP, a host hook); no state is kept between calls. No event
+// field ever carries key material.
 /** One evaluation lifecycle event. */
 export const SystemOneTelemetryEvent = type({
     event: "'evaluate.start' | 'evaluate.success' | 'evaluate.fallback'",
@@ -23,29 +18,3 @@ export const SystemOneTelemetryEvent = type({
     "detail?": "string",
     "+": "reject",
 });
-/** Maximum buffered events; beyond this the oldest drop first. */
-export const MAX_BUFFERED_TELEMETRY_EVENTS = 256;
-const bufferedEvents = [];
-/**
- * Records one telemetry event to the in-memory ring. Validates the shape
- * (a malformed event is caller misuse and throws a typed `SystemOneError`)
- * and never touches the network, disk, or console.
- */
-export function recordTelemetryEvent(event) {
-    const parsed = SystemOneTelemetryEvent(event);
-    if (parsed instanceof type.errors) {
-        throw new SystemOneError("parse-error", `recordTelemetryEvent: invalid event: ${parsed.summary}`);
-    }
-    bufferedEvents.push(parsed);
-    if (bufferedEvents.length > MAX_BUFFERED_TELEMETRY_EVENTS) {
-        bufferedEvents.splice(0, bufferedEvents.length - MAX_BUFFERED_TELEMETRY_EVENTS);
-    }
-}
-/**
- * Drains the buffered telemetry events in arrival order and clears the
- * buffer. The host calls this after each evaluation (or on its own cadence)
- * to forward events to its own sink.
- */
-export function drainTelemetryEvents() {
-    return bufferedEvents.splice(0, bufferedEvents.length);
-}

package/package.json

@@ -1,64 +1,70 @@
 {
   "name": "@corbits/system-one",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Typed-decision evaluation client for System One (Jev-class) models: arktype question/decision schemas, endpoint configuration with gateway override, and timeout/fallback semantics.",
+  "keywords": [
+    "corbits",
+    "evaluation",
+    "inference",
+    "interchange",
+    "system-one",
+    "typesafe"
+  ],
+  "homepage": "https://github.com/corbitsdev/corbits-system-one#readme",
+  "bugs": {
+    "url": "https://github.com/corbitsdev/corbits-system-one/issues"
+  },
   "license": "LGPL-2.1-only",
   "author": "Sawyer Cutler <sawyer@dirtroad.dev>",
-  "type": "module",
-  "sideEffects": false,
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/corbitsdev/corbits-system-one.git"
+  },
   "files": [
     "dist",
     "README.md",
     "LICENSE"
   ],
-  "publishConfig": {
-    "access": "public"
-  },
+  "type": "module",
+  "sideEffects": false,
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     }
   },
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
-    "typecheck": "tsc --noEmit",
-    "lint": "eslint .",
-    "format": "prettier --write .",
-    "format:check": "prettier --check .",
-    "test": "bun test",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
     "prepack": "bun run build",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint",
+    "format": "oxfmt",
+    "format:check": "oxfmt --check",
+    "test": "bun test src --pass-with-no-tests",
+    "test:e2e": "bun test e2e",
     "check": "bun run typecheck && bun run lint && bun run format:check && bun run test"
   },
   "dependencies": {
     "arktype": "2.2.3"
   },
-  "peerDependencies": {
-    "@intx/inference": ">=0.4.0",
-    "@intx/types": ">=0.4.0"
-  },
   "devDependencies": {
-    "@eslint/js": "9.34.0",
     "@intx/inference": "0.4.0",
+    "@intx/inference-testing": "0.4.0",
     "@intx/types": "0.4.0",
-    "@types/bun": "1.3.9",
-    "eslint": "9.34.0",
-    "jiti": "2.5.1",
-    "prettier": "3.6.2",
-    "typescript": "5.9.3",
-    "typescript-eslint": "8.42.0"
-  },
-  "engines": {
-    "bun": ">=1.2.0"
+    "@types/bun": "1.3.14",
+    "oxfmt": "0.70.0",
+    "oxlint": "1.85.0",
+    "typescript": "6.0.3"
   },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/corbitsdev/corbits-system-one.git"
+  "peerDependencies": {
+    "@intx/inference": "^0.4.0",
+    "@intx/types": "^0.4.0"
   },
-  "homepage": "https://github.com/corbitsdev/corbits-system-one",
-  "bugs": {
-    "url": "https://github.com/corbitsdev/corbits-system-one/issues"
+  "engines": {
+    "bun": ">=1.2.0",
+    "node": ">=24"
   }
 }