@tangleai/models 0.21.1 → 0.25.0

package/src/replay.d.ts

@@ -1,30 +1,59 @@
 /**
- * The replay cache seam a host implements.
- * @typedef {Object} ReplayCache
- * @property {(key: string) => any} get - the stored value, or `undefined`
- *   for a miss; may answer a promise
- * @property {(key: string, value: any) => any} set - remember a value
- *   under a key; may answer a promise. The value is JSON-only.
+ * The replay seam behind both wire clients: what a remembered reply is
+ * keyed by, and what a remembered entry must look like before it is
+ * served. This module owns the two decisions a host must not be left
+ * to make twice —
+ *
+ *  - **the key is the effective wire request, canonicalized.** It is
+ *    built by the client after endpoint resolution and default
+ *    application, from `{ wire, provider, base, request }` where
+ *    `request` is the body the client would POST (minus `stream`, which
+ *    does not change an answer). Never the headers (they carry the
+ *    credential), never the signal, never a callback. Because the key
+ *    is the body rather than an allow-list of request members, an
+ *    option added to the body later enters the key by construction — it
+ *    cannot alias an older key. The serialization is `semanticKey`:
+ *    injective over plain data, so two requests share a key exactly when
+ *    they are the same request, and a request that cannot be keyed
+ *    injectively (a function inside `tools`, a cycle) is refused up
+ *    front rather than folded onto someone else's entry;
+ *
+ *  - **a stored entry is verified, not trusted.** A chat entry must carry
+ *    a normalized result and the wall time of the purchase; an embedding
+ *    entry must carry a vector of finite numbers at the settled width.
+ *    Anything else is `AI0003`, never served — a cache that answers
+ *    garbage is worse than a cache that is down.
+ *
+ * The client hands the adapter the complete canonical string. It is
+ * long (a whole conversation is in it) and that is the point: it is
+ * collision-free. An adapter that needs a fixed-width storage id hashes
+ * it — with a cryptographic hash, because a 32-bit hash over prompts
+ * that differ by one token would sooner or later serve one prompt's
+ * answer for another's.
+ *
+ * The adapter contract is two members, each sync or async:
+ * `get(key) → value | undefined` and `set(key, value)`. The seam FAILS
+ * CLOSED: an adapter that throws fails the call. An adapter that wants
+ * to fail open — keep buying while its storage is broken — catches its
+ * own errors and answers `undefined`; the client will not guess which
+ * it wanted.
  */
+/** The replay cache seam a host implements. */
 /**
  * The `cache` option, checked once at client construction: absent means
  * no cache; present means both members are functions, or `AI0001`.
- * @param {unknown} cache
- * @returns {ReplayCache | null}
  */
-export function normalizeCache(cache: unknown): ReplayCache | null;
+export declare function normalizeCache(cache: unknown): ReplayCache | null;
 /**
  * The key one request has under one endpoint: the canonical
  * serialization of the wire, the credential-free endpoint identity and
  * the effective request. The same request keys the same string on
  * every host.
- * @param {'chat' | 'embeddings'} wire
- * @param {{ provider: string, base: string }} endpoint
- * @param {any} request - the body the client would POST, `stream` removed
- * @returns {string}
+ * @param request - the body the client would POST, `stream` removed
+ * @returns
  * @throws {AiError} `AI0001` when the request cannot be keyed injectively
  */
-export function replayKey(wire: "chat" | "embeddings", endpoint: {
+export declare function replayKey(wire: 'chat' | 'embeddings', endpoint: {
     provider: string;
     base: string;
 }, request: any): string;
@@ -32,10 +61,8 @@ export function replayKey(wire: "chat" | "embeddings", endpoint: {
  * A stored chat entry, verified: `{ value, ms }` with `value` a
  * normalized result carrying a `message` object and `ms` a finite
  * number — or `AI0003`.
- * @param {any} entry
- * @returns {{ value: any, ms: number }}
  */
-export function verifyChatEntry(entry: any): {
+export declare function verifyChatEntry(entry: any): {
     value: any;
     ms: number;
 };
@@ -44,33 +71,21 @@ export function verifyChatEntry(entry: any): {
  * ms }` with `vector` a non-empty array of finite numbers at the settled
  * width (any positive width when none is settled yet — the first replay
  * settles it exactly as a first wire reply would) — or `AI0003`.
- * @param {any} entry
- * @param {number | undefined} dims - the settled width, if any
- * @returns {Float32Array}
+ * @param dims - the settled width, if any
  */
-export function verifyEmbeddingEntry(entry: any, dims: number | undefined): Float32Array;
+export declare function verifyEmbeddingEntry(entry: any, dims: number | undefined): Float32Array;
 /**
  * A JSON-only copy: what is stored, and what a replay answers, so that a
  * caller mutating its result never mutates the adapter's entry.
  * @template T
- * @param {T} value
- * @returns {T}
  */
-export function cloneJson<T>(value: T): T;
+export declare function cloneJson<T>(value: T): T;
 /** Milliseconds now, for the wall time of a purchase. */
-export function now(): number;
-/**
- * The replay cache seam a host implements.
- */
+export declare function now(): number;
 export type ReplayCache = {
-    /**
-     * - the stored value, or `undefined`
-     * for a miss; may answer a promise
-     */
-    get: (key: string) => any;
-    /**
-     * - remember a value
-     * under a key; may answer a promise. The value is JSON-only.
-     */
+    get: (key: string) => any; /**
+   * - remember a value
+   * under a key; may answer a promise. The value is JSON-only.
+   */
     set: (key: string, value: any) => any;
 };

package/src/replay.js

@@ -1,4 +1,3 @@
-//@ts-check
 /**
  * The replay seam behind both wire clients: what a remembered reply is
  * keyed by, and what a remembered entry must look like before it is
@@ -39,103 +38,76 @@
  * own errors and answers `undefined`; the client will not guess which
  * it wanted.
  */
-
 import { semanticKey } from '@jarenjs/core/object';
-
-import { AiError } from './errors.js';
-import { verifyEmbeddingComponents } from './embedding-vector.js';
-
-/**
- * The replay cache seam a host implements.
- * @typedef {Object} ReplayCache
- * @property {(key: string) => any} get - the stored value, or `undefined`
- *   for a miss; may answer a promise
- * @property {(key: string, value: any) => any} set - remember a value
- *   under a key; may answer a promise. The value is JSON-only.
- */
-
+import { AiError } from "./errors.js";
+import { verifyEmbeddingComponents } from "./embedding-vector.js";
+/** The replay cache seam a host implements. */
 /**
  * The `cache` option, checked once at client construction: absent means
  * no cache; present means both members are functions, or `AI0001`.
- * @param {unknown} cache
- * @returns {ReplayCache | null}
  */
 export function normalizeCache(cache) {
-  if (cache === undefined || cache === null) return null;
-  const candidate = /** @type {any} */ (cache);
-  if (typeof candidate.get !== 'function' || typeof candidate.set !== 'function')
-    throw new AiError('AI0001', 'cache needs { get(key), set(key, value) } — both functions, sync or async');
-  return candidate;
+    if (cache === undefined || cache === null)
+        return null;
+    const candidate = cache;
+    if (typeof candidate.get !== 'function' || typeof candidate.set !== 'function')
+        throw new AiError('AI0001', 'cache needs { get(key), set(key, value) } — both functions, sync or async');
+    return candidate;
 }
-
 /**
  * The key one request has under one endpoint: the canonical
  * serialization of the wire, the credential-free endpoint identity and
  * the effective request. The same request keys the same string on
  * every host.
- * @param {'chat' | 'embeddings'} wire
- * @param {{ provider: string, base: string }} endpoint
- * @param {any} request - the body the client would POST, `stream` removed
- * @returns {string}
+ * @param request - the body the client would POST, `stream` removed
+ * @returns
  * @throws {AiError} `AI0001` when the request cannot be keyed injectively
  */
 export function replayKey(wire, endpoint, request) {
-  try {
-    return semanticKey({ wire, provider: endpoint.provider, base: endpoint.base, request });
-  }
-  catch (err) {
-    throw new AiError('AI0001',
-      `the ${wire} request is not cacheable: ${/** @type {Error} */ (err).message}`);
-  }
+    try {
+        return semanticKey({ wire, provider: endpoint.provider, base: endpoint.base, request });
+    }
+    catch (err) {
+        throw new AiError('AI0001', `the ${wire} request is not cacheable: ${err.message}`);
+    }
 }
-
-/** @param {any} value */
+/** @param value */
 const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
-
 /**
  * A stored chat entry, verified: `{ value, ms }` with `value` a
  * normalized result carrying a `message` object and `ms` a finite
  * number — or `AI0003`.
- * @param {any} entry
- * @returns {{ value: any, ms: number }}
  */
 export function verifyChatEntry(entry) {
-  if (!isRecord(entry) || !isRecord(entry.value) || !isRecord(entry.value.message)
-    || typeof entry.ms !== 'number' || !Number.isFinite(entry.ms))
-    throw new AiError('AI0003', 'malformed replay entry for the chat wire: expected { value: { message, … }, ms }');
-  return entry;
+    if (!isRecord(entry) || !isRecord(entry.value) || !isRecord(entry.value.message)
+        || typeof entry.ms !== 'number' || !Number.isFinite(entry.ms))
+        throw new AiError('AI0003', 'malformed replay entry for the chat wire: expected { value: { message, … }, ms }');
+    return entry;
 }
-
 /**
  * A stored embedding entry, verified into a fresh vector: `{ vector,
  * ms }` with `vector` a non-empty array of finite numbers at the settled
  * width (any positive width when none is settled yet — the first replay
  * settles it exactly as a first wire reply would) — or `AI0003`.
- * @param {any} entry
- * @param {number | undefined} dims - the settled width, if any
- * @returns {Float32Array}
+ * @param dims - the settled width, if any
  */
 export function verifyEmbeddingEntry(entry, dims) {
-  const vector = isRecord(entry) ? entry.vector : undefined;
-  if (!Array.isArray(vector) || vector.length === 0)
-    throw new AiError('AI0003', 'malformed replay entry for the embeddings wire: expected { vector: number[], ms }');
-  if (dims !== undefined && vector.length !== dims)
-    throw new AiError('AI0003', `replay entry carries ${vector.length} dimensions, expected ${dims}`);
-  return verifyEmbeddingComponents(vector, 'replay entry carries');
+    const vector = isRecord(entry) ? entry.vector : undefined;
+    if (!Array.isArray(vector) || vector.length === 0)
+        throw new AiError('AI0003', 'malformed replay entry for the embeddings wire: expected { vector: number[], ms }');
+    if (dims !== undefined && vector.length !== dims)
+        throw new AiError('AI0003', `replay entry carries ${vector.length} dimensions, expected ${dims}`);
+    return verifyEmbeddingComponents(vector, 'replay entry carries');
 }
-
 /**
  * A JSON-only copy: what is stored, and what a replay answers, so that a
  * caller mutating its result never mutates the adapter's entry.
  * @template T
- * @param {T} value
- * @returns {T}
  */
 export function cloneJson(value) {
-  return JSON.parse(JSON.stringify(value));
+    return JSON.parse(JSON.stringify(value));
 }
-
 /** Milliseconds now, for the wall time of a purchase. */
 export function now() {
-  return globalThis.performance.now();
+    return globalThis.performance.now();
 }

package/src/retry.d.ts

@@ -1,34 +1,24 @@
 /**
- * The `retry` option of every client.
- * @typedef {Object} RetryOptions
- * @property {number} [attempts] - the TOTAL number of tries (default 3;
- *   1 disables retrying)
- * @property {number} [baseMs] - the first backoff (default 500); each
- *   later one doubles, with full jitter
- * @property {number} [maxMs] - the ceiling on any single wait (default
- *   8 000) — a provider `Retry-After` included: a provider asking for a
- *   minute gets the cap, and the value it asked for rides the final
- *   error as `retryAfterMs` for the caller to honour
- * @property {() => number} [random] - the jitter source, for
- *   deterministic tests
- * @property {(ms: number, signal?: AbortSignal) => Promise<void>} [sleep]
- *   - the wait itself, for deterministic tests; the default is a timer
- *   that rejects with the abort reason the moment `signal` aborts
- */
-/**
- * The option with its defaults filled in.
- * @typedef {Object} RetryPolicy
- * @property {number} attempts
- * @property {number} baseMs
- * @property {number} maxMs
- * @property {() => number} random
- * @property {(ms: number, signal?: AbortSignal) => Promise<void>} sleep
+ * The transport policy every client in this package shares: which
+ * failures are transient, how long to wait before trying again, what a
+ * provider's `Retry-After` is worth, and how an abort cuts a wait
+ * short. The chat wire and the embeddings wire fail alike at the
+ * transport — a network error, a 408, a 429, a 5xx, a 200 whose body is
+ * not what the wire promised — and differ only in what a good reply
+ * must carry. So the loop lives here, once, and each client keeps its
+ * own reading of a reply: one implementation of retry, two wire shapes.
+ *
+ * Everything here is internal to the package; the public surface is
+ * the `retry` option each client documents.
  */
+import { AiError } from './errors.ts';
+import { abortError } from '@jarenjs/core/retry';
+export { abortError };
+/** The `retry` option of every client. */
+/** The option with its defaults filled in. */
 /**
- * @param {RetryOptions | undefined} retry
- * @returns {RetryPolicy}
  */
-export function normalizeRetry(retry: RetryOptions | undefined): RetryPolicy;
+export declare function normalizeRetry(retry: RetryOptions | undefined): RetryPolicy;
 /**
  * Whether a failure is the transient kind. A transport error with a
  * retryable status is (a network failure before any response counts
@@ -37,20 +27,17 @@ export function normalizeRetry(retry: RetryOptions | undefined): RetryPolicy;
  * tiers, and safe to retry precisely because nothing was delivered.
  * Anything else — a caller error, a 401, a 404 — is final on the first
  * try.
- * @param {unknown} err
- * @returns {boolean}
  */
-export function isTransientFailure(err: unknown): boolean;
+export declare function isTransientFailure(err: unknown): boolean;
 /**
  * The wait before the next try: exponential backoff with full jitter,
  * capped at `maxMs` — unless the provider named a `Retry-After`, which
  * wins up to the same cap.
- * @param {RetryPolicy} policy
- * @param {number} attempt - the try that just failed, counted from 1
- * @param {number | undefined} retryAfter - the provider's ask, in ms
- * @returns {number} milliseconds
+ * @param attempt - the try that just failed, counted from 1
+ * @param retryAfter - the provider's ask, in ms
+ * @returns milliseconds
  */
-export function retryDelay(policy: RetryPolicy, attempt: number, retryAfter: number | undefined): number;
+export declare function retryDelay(policy: RetryPolicy, attempt: number, retryAfter: number | undefined): number;
 /**
  * Run `once` until it settles. A failure `retryable` accepts backs off
  * and tries again while tries remain; anything else is thrown as it
@@ -59,77 +46,51 @@ export function retryDelay(policy: RetryPolicy, attempt: number, retryAfter: num
  * during backoff rejects with the abort reason, exactly like an abort
  * during the request — nothing is ever retried past an abort.
  * @template T
- * @param {RetryPolicy} policy
- * @param {() => Promise<T>} once - one request/response cycle
- * @param {{ signal?: AbortSignal, retryable: (failure: AiError) => boolean }} options
+ * @param once - one request/response cycle
  *   - `retryable` is the wire's own judgment over a coded failure (the
  *   chat client, for one, stops retrying once a streamed delta has
  *   reached the caller); it is never asked about an uncoded error
- * @returns {Promise<T>}
  */
-export function withRetry<T>(policy: RetryPolicy, once: () => Promise<T>, options: {
+export declare function withRetry<T>(policy: RetryPolicy, once: () => Promise<T>, options: {
     signal?: AbortSignal;
     retryable: (failure: AiError) => boolean;
 }): Promise<T>;
 /**
  * The `AI0002` for a response that is not ok: the status, a short
  * excerpt of the body, and the provider's `Retry-After` in ms.
- * @param {any} response
- * @param {string} url
- * @returns {Promise<AiError>}
  */
-export function httpFailure(response: any, url: string): Promise<AiError>;
+export declare function httpFailure(response: any, url: string): Promise<AiError>;
 /**
  * What to throw when `fetch` itself threw: an abort exactly as it came
  * (the caller's own signal, never retried, never rewrapped); anything
  * else the `AI0002` of a failure before any response, status 0.
- * @param {any} err
- * @param {string} url
- * @returns {any}
  */
-export function transportFailure(err: any, url: string): any;
+export declare function transportFailure(err: any, url: string): any;
 /**
  * Parse a `Retry-After` header (delta-seconds or HTTP-date) into ms.
- * @param {any} response
- * @returns {number | undefined}
- */
-export function retryAfterMs(response: any): number | undefined;
-export { abortError };
-/**
- * The `retry` option of every client.
  */
+export declare function retryAfterMs(response: any): number | undefined;
 export type RetryOptions = {
-    /**
-     * - the TOTAL number of tries (default 3;
-     * 1 disables retrying)
-     */
-    attempts?: number;
-    /**
-     * - the first backoff (default 500); each
-     * later one doubles, with full jitter
-     */
-    baseMs?: number;
-    /**
-     * - the ceiling on any single wait (default
-     * 8 000) — a provider `Retry-After` included: a provider asking for a
-     * minute gets the cap, and the value it asked for rides the final
-     * error as `retryAfterMs` for the caller to honour
-     */
-    maxMs?: number;
-    /**
-     * - the jitter source, for
-     * deterministic tests
-     */
-    random?: () => number;
-    /**
-     * - the wait itself, for deterministic tests; the default is a timer
-     * that rejects with the abort reason the moment `signal` aborts
-     */
+    attempts?: number; /**
+   * - the first backoff (default 500); each
+   * later one doubles, with full jitter
+   */
+    baseMs?: number; /**
+   * - the ceiling on any single wait (default
+   * 8 000) — a provider `Retry-After` included: a provider asking for a
+   * minute gets the cap, and the value it asked for rides the final
+   * error as `retryAfterMs` for the caller to honour
+   */
+    maxMs?: number; /**
+   * - the jitter source, for
+   * deterministic tests
+   */
+    random?: () => number; /**
+   * - the wait itself, for deterministic tests; the default is a timer
+   * that rejects with the abort reason the moment `signal` aborts
+   */
     sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
 };
-/**
- * The option with its defaults filled in.
- */
 export type RetryPolicy = {
     attempts: number;
     baseMs: number;
@@ -137,5 +98,3 @@ export type RetryPolicy = {
     random: () => number;
     sleep: (ms: number, signal?: AbortSignal) => Promise<void>;
 };
-import { AiError } from './errors.js';
-import { abortError } from '@jarenjs/core/retry';