wontopos 2.2.34 → 2.2.36

package/dist/wontopos.js

@@ -15,12 +15,15 @@
  * so with no `userId` anywhere the zero-setup path just works.
  *
  * The API key picks *which memory* (your account); `model` picks *which engine*
- * reads it. All models share one memory, so you can store
- * with one and recall with another. Set a default in the constructor, or override
- * a single call with `mem.withModel("tablet-1").recall(...)`.
+ * reads it. Models on the shared pool read the same memory, so you can store with
+ * one and recall with another; `listModels()` reports each model's `memory` as
+ * `"shared"` or `"isolated"`, and an isolated one starts empty. Set a default in
+ * the constructor, or override a single call with
+ * `mem.withModel("tablet-1").recall(...)`.
  *
- * Pure semantic retrieval — no keyword/BM25 matching, so it works the SAME in every
- * language. Storing and searching call no LLM; you only pay for embeddings.
+ * Recall quality does not depend on which language a memory was written in: a
+ * memory stored in one language is found by a question asked in another. Storing
+ * and searching call no LLM.
  *
  * Reliability: every call retries transient failures with exponential backoff +
  * jitter, honoring `Retry-After` — 429 always; 502/503 and connection errors only
@@ -37,7 +40,7 @@
  * runtime's (never disabled by this SDK; Node 18+ floors TLS at 1.2). Prefer
  * `Client.fromEnv()` over keys in source code.
  */
-const VERSION = "2.2.34";
+const VERSION = "2.2.36";
 /** Runtime info helps support debug a report ("node 18 on Windows...") —
  * platform only, never anything identifying. Browsers have no `process` (and
  * silently drop the UA header anyway). */
@@ -57,11 +60,12 @@ function logDebug(msg) {
 const DEFAULT_BASE_URL = "https://api.wontopos.com";
 /** The engine every call uses unless the caller names another.
  *
- *  Tablet 2 costs the same per token as Tablet 1 and is the only released line that
- *  can serve images, re-ask passes (`verify`), and the self lane, so a caller who
- *  names nothing gets the engine that can answer the most. All models read the same
- *  memory, so switching is a header, not a migration. Pin an older one explicitly
- *  with `new Client({ apiKey, model: "tablet-1" })` or `withModel("tablet-1")`. */
+ *  Tablet 2 costs the same per token as Tablet 1 and is the one that
+ *  serves images, re-ask passes (`verify`), and `self_memories`, so a caller who
+ *  names nothing gets the engine that can answer the most. Models on the shared
+ *  pool read the same memory, so switching between them is a header, not a
+ *  migration. Pin an older one explicitly with
+ *  `new Client({ apiKey, model: "tablet-1" })` or `withModel("tablet-1")`. */
 const DEFAULT_MODEL = "tablet-2";
 /** 429 = rate-limited BEFORE processing → always safe to retry (no write, no bill). */
 const RETRY_ALWAYS = new Set([429]);
@@ -72,7 +76,7 @@ const RETRY_IF_IDEMPOTENT = new Set([502, 503]);
 const IDEMPOTENT_METHODS = new Set(["GET", "HEAD", "PUT", "DELETE", "OPTIONS"]);
 const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "::1", "0.0.0.0"]);
 /** Refuse to buffer absurd responses (real ones are a few KB) — protects the
- * process if a self-hosted baseUrl points somewhere broken or hostile. */
+ * process if a custom baseUrl points somewhere broken or hostile. */
 const MAX_RESPONSE_BYTES = 64 * 1024 * 1024;
 /** Model names travel in a header — only header-safe characters. */
 const MODEL_RE = /^[A-Za-z0-9._-]+$/;
@@ -139,15 +143,69 @@ export function _resetStoreIdWarnings() {
  *  answer with a JSON object — see the empty-body check in `request`. */
 const NO_BODY_STATUS = new Set([204, 205, 304]);
 /** Paging backstop: bound the walk so a fresh-cursor-forever server can't loop us. */
-const MAX_PAGES = 1_000_000;
+// A page walk has to stop somewhere, and 1,000,000 pages was not a stop: at 100 per
+// page that is 100 million memories, so a server minting a fresh cursor every time
+// would spend hours and a million billed requests before it fired. 20,000 pages is two
+// million memories — past any real store, reached in minutes.
+//
+// ★And it has to be LOUD. Falling out of the loop yielded a truncated list that looks
+// exactly like a complete one; the caller writes it to a file believing it is the
+// whole store. Hitting this now throws.
+const MAX_PAGES = 20_000;
+export const SEARCH_LIMIT_MIN = 5;
+export const SEARCH_LIMIT_MAX = 20;
+/** `recall`'s surrounding-context count. 0 to 20 inclusive; 0 attaches none. */
+export const CONTEXT_LIMIT_MIN = 0;
+export const CONTEXT_LIMIT_MAX = 20;
+/** The 5-to-20 count shared by `search` and `recall`, refused out of range rather
+ * than quietly adjusted.
+ *
+ * The service has refused anything else from the start, because asking for 20 and
+ * silently getting 10 reads as "that is all there is". Search had no contract at
+ * all: the three clients sent whatever they were given, the MCP server allowed 1 to
+ * 60, and the service quietly capped at 50 with no floor. Four surfaces, four
+ * answers, and the caller could not tell which one they got.
+ *
+ * ★ `recall` said it enforced this and did not. Its doc comment promised "out of
+ * range is refused, not clamped" while the value went straight to the wire in all
+ * three SDKs — so `limit: 500` travelled to the engine and died there. A comment
+ * that describes a guard is not a guard, and this is the shape of defect a reviewer
+ * reading one diff can never see: the promise and the missing code were written
+ * months apart.
+ *
+ * Thrown as a plain `Error`, like every other argument check in this file. It is
+ * NOT a `WosError` — nothing was sent, and `WosError` with status 0 means
+ * `APIConnectionError`, "the request never got a response". Reusing that status for
+ * a typo told a caller with `if (e.status === 0) retry()` to retry a bad argument
+ * forever.
+ *
+ * Refusing rather than clamping is the same decision as 2.2.35's, where a Rust
+ * `limit` of 0 had been rewritten to 10 and the caller was handed ten memories they
+ * had not asked for, and the bill for them. */
+function checkCount(limit, name) {
+    if (!Number.isInteger(limit) || limit < SEARCH_LIMIT_MIN || limit > SEARCH_LIMIT_MAX) {
+        throw new Error(`${name} must be an integer between ${SEARCH_LIMIT_MIN} and ${SEARCH_LIMIT_MAX}, got ${limit}. ` +
+            `Out of range is refused rather than adjusted, so a short answer always means ` +
+            `the store was short.`);
+    }
+}
+/** `recall`'s `context_limit`, 0 to 20. Same reason as the count above: the doc
+ *  comment on `recall` promises out-of-range is refused, and a promise the client
+ *  does not keep is worse than no promise — the caller reads the doc, sends 50, and
+ *  the failure arrives from the service with no hint that the SDK knew all along. */
+function checkContextLimit(n) {
+    if (!Number.isInteger(n) || n < CONTEXT_LIMIT_MIN || n > CONTEXT_LIMIT_MAX) {
+        throw new Error(`context_limit must be an integer between ${CONTEXT_LIMIT_MIN} and ${CONTEXT_LIMIT_MAX}, got ${n}.`);
+    }
+}
 /**
  * Put an image into the shape the API expects, and fail loudly on the parts we can
  * check from here.
  *
- * Deliberately NOT checked: the byte ceiling. It is a server setting (`/health`
- * reports it as `memory.images.max_bytes`), so a number baked in here would drift the
- * first time that config changes and would reject an image the service would have
- * taken. What we do check is what cannot change: an empty payload, and a `data:` URL
+ * Deliberately NOT checked: the byte ceiling. It is a service setting, so a number
+ * baked in here would drift the first time the service is reconfigured and would
+ * reject an image the service would have taken.
+ * What we do check is what cannot change: an empty payload, and a `data:` URL
  * prefix — browsers and file pickers hand you `data:image/jpeg;base64,…`, the API
  * wants the part after the comma, and the difference is invisible until the write
  * fails with "not a readable image".
@@ -241,21 +299,18 @@ const asObj = (x) => (x != null && typeof x === "object" && !Array.isArray(x) ?
 // user code. Drop elements that aren't objects and keep the valid records, so one
 // bad element never poisons the batch (and never destroys it).
 const asRecords = (x) => asList(x).filter((m) => m != null && typeof m === "object" && !Array.isArray(m));
-// Attach a delivery-form override (memoir/archive) + tz to a body, the way search
-// passes them; on Scroll 1.2+ this renders each returned memory's time in that form.
-/** Every memory a search returned — main lane and self lane together.
+/** Every memory a search returned, from both fields, as one array.
  *
- * On a self-lane model the service splits the result: the assistant's OWN words
- * come back in `self_memories` and are REMOVED from `memories`, so the two never
- * double-count. `search()` read only `memories`, so on Scroll 1.2 an assistant
- * turn stored with `addTurn` was silently missing from search while the same
- * query on tablet-1 returned it — upgrading the model made search return LESS,
- * and the dropped memories were already on the wire and already paid for.
+ * Some models answer with the assistant's own words in `self_memories`, not
+ * repeated in `memories`. `search()` used to return `memories` alone, so an
+ * assistant turn stored with `addTurn` was missing from its results on those
+ * models while the same query returned it on others — upgrading made search
+ * return LESS, and what went missing had already been retrieved and paid for.
  *
- * Both lanes, de-duplicated by id, each memory keeping its `speaker` so the
- * caller can still tell who said what. Callers who want the lanes kept apart use
- * `searchSelf()`, which exists for exactly that. */
-function mergeLanes(r) {
+ * Both fields are returned here, de-duplicated by id, each memory keeping its
+ * `speaker` so a caller can still tell who said what. Callers who want them kept
+ * apart use `searchSelf()`, which is what that method is for. */
+function mergeResults(r) {
     const main = asRecords(r?.memories);
     const mine = asRecords(r?.self_memories);
     if (mine.length === 0)
@@ -263,6 +318,9 @@ function mergeLanes(r) {
     const seen = new Set(main.map((m) => m.id).filter((id) => typeof id === "string"));
     return main.concat(mine.filter((m) => !(typeof m.id === "string" && seen.has(m.id))));
 }
+/** Attach a delivery-form override ("memoir"/"archive") + tz to a request body, the
+ * way search passes them; on Scroll 1.2+ this renders each returned memory's time in
+ * that form. The server validates the form (400 on an unknown one). */
 function withForm(body, form, tz) {
     if (form !== undefined)
         body.form = form;
@@ -383,6 +441,8 @@ export class Client {
     apiKey;
     model;
     maxRetries;
+    deadlineMs;
+    signal;
     /** Transport. Held as a field (not read off `globalThis` per call) so a caller
      * who passes one gets it for every request, including from cloned clients. */
     fetchImpl;
@@ -403,6 +463,12 @@ export class Client {
             throw new Error("apiKey is required");
         if (/\s/.test(key))
             throw new Error("apiKey contains whitespace - check for a stray newline or paste error");
+        // `\s` does not cover NUL, 0x01 or DEL, and those travel into the header and fail
+        // deep inside fetch as the mystery 401 this check exists to prevent. Python has
+        // `_HEADER_CTL_RE` and Rust tests `is_control`; this was the client that did not,
+        // while all three READMEs announced the guard without naming a language.
+        if (/[\x00-\x1f\x7f]/.test(key))
+            throw new Error("apiKey contains a control character - check for a stray byte or paste error");
         this.apiKey = key;
         this.base = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
         // Coerce a non-finite or non-positive timeout back to the default — NaN
@@ -420,6 +486,11 @@ export class Client {
         // "retries exhausted"; Infinity would retry forever.
         const mr = opts.maxRetries ?? opts.retries;
         this.maxRetries = typeof mr === "number" && Number.isFinite(mr) ? Math.max(0, Math.floor(mr)) : 2;
+        const dl = opts.deadlineMs;
+        // A zero or negative budget would fail every call before it starts — treat it as
+        // "no budget", the same way a non-positive timeout falls back to the default.
+        this.deadlineMs = typeof dl === "number" && Number.isFinite(dl) && dl > 0 ? dl : undefined;
+        this.signal = opts.signal;
         // Bind the global so `fetch` is not called as a method of `globalThis`, which
         // throws "Illegal invocation" on some runtimes. A caller-supplied fetch is
         // taken as given — it is already whatever they meant to hand us.
@@ -440,7 +511,7 @@ export class Client {
         if (this.model)
             this.headers["X-WOS-Model"] = this.model;
         // An API key on plain HTTP travels readable by anyone on the path. Loopback
-        // is fine (local dev / self-hosted on the same box); anything else gets a
+        // is fine (local dev, or a proxy on the same box); anything else gets a
         // warning, not an error, so private-network gateways keep working.
         // Parse, don't split. `http://127.0.0.1:9@evil.example` splits to "127.0.0.1" — the
         // USERINFO, not the host — so this check called it loopback and stayed quiet while
@@ -448,7 +519,12 @@ export class Client {
         // (Python already used urlsplit here; this was the copy that did not.)
         let host;
         try {
-            host = new URL(this.base).hostname.toLowerCase();
+            // `URL.hostname` keeps the brackets on an IPv6 literal — `http://[::1]:8080`
+            // gives back "[::1]", which was never in LOOPBACK_HOSTS, so a local
+            // client on the v6 loopback was told its key was travelling in cleartext when
+            // it was not. Python's urlsplit strips them and Rust strips them by hand; this
+            // was the copy that did not. Strip them here so all three agree.
+            host = new URL(this.base).hostname.toLowerCase().replace(/^\[|\]$/g, "");
         }
         catch {
             host = ""; // unparseable → not loopback → warn, which is the safe direction
@@ -523,6 +599,11 @@ export class Client {
             // friends would silently fall back to the global fetch and a proxy-bound
             // client would stop connecting the moment it was cloned.
             fetch: this.fetchImpl,
+            // Carried for the same reason as `fetch` above: a clone that quietly dropped
+            // the caller's signal would keep working right up until the moment someone
+            // needed to cancel it.
+            deadlineMs: this.deadlineMs,
+            signal: this.signal,
             ...overrides,
         });
     }
@@ -538,6 +619,22 @@ export class Client {
     withUser(userId) {
         return this.clone({ userId });
     }
+    /** A client bound to a caller's `AbortSignal` (everything else kept).
+     *
+     *     const ctrl = new AbortController();
+     *     req.on("close", () => ctrl.abort());
+     *     const r = await mem.withSignal(ctrl.signal).recall(q, user);
+     *
+     * Aborting ends the request in flight AND any backoff sleep waiting to retry it. */
+    withSignal(signal) {
+        return this.clone({ signal });
+    }
+    /** A client with a total budget per call, across every retry (everything else
+     * kept). `mem.withDeadline(5_000).search(q)` inside a handler that has five
+     * seconds. */
+    withDeadline(deadlineMs) {
+        return this.clone({ deadlineMs });
+    }
     /** A client with a different per-request timeout in ms (everything else kept).
      * `mem.withTimeout(120_000).addBulk(bigBlob)` — this slow call only. */
     withTimeout(timeoutMs) {
@@ -571,9 +668,9 @@ export class Client {
     addTurn(userMsg, assistantMsg, userId, opts = {}) {
         return this.post("/api/v1/memory/store-turn", { user_id: this.uid(userId), user_msg: userMsg, assistant_msg: assistantMsg }, opts.idempotencyKey);
     }
-    /** Bulk-ingest a large blob of text (chunked + embedded server-side). For backfilling.
+    /** Bulk-ingest a large blob of text in one call. For backfilling.
      *  The call most worth an `opts.idempotencyKey`: a backfill that dies halfway and is
-     *  re-run would otherwise re-chunk and re-bill the whole blob. */
+     *  re-run would otherwise re-ingest and re-bill the whole blob. */
     addBulk(content, userId, category = "general", timestamp, opts = {}) {
         const body = { user_id: this.uid(userId), content, category };
         if (timestamp)
@@ -585,40 +682,42 @@ export class Client {
         return this.post("/api/v1/memory/supersede", { user_id: this.uid(userId), old_memory_id: oldMemoryId, new_content: newContent }, opts.idempotencyKey);
     }
     // ----- read -----
-    /** Semantic search over a store's memories. Returns memories, most relevant first.
+    /** Search a store's memories. Returns them most relevant first.
      *
-     *  `limit` bounds the MAIN lane, not the returned array. On a self-lane model
-     *  (Scroll 1.2+) the service answers in two disjoint lanes — the assistant's own
-     *  words come back separately — and both are returned here, so the array can hold
-     *  more than `limit`. They were retrieved and billed either way; dropping them would
-     *  only hide what you already paid for. Size a prompt window on the array you get
-     *  back, not on `limit`. `searchSelf()` hands the lanes back apart. */
+     *  `limit` bounds `memories`, not the returned array. On a model that keeps the
+     *  assistant's own words separate (Scroll 1.2+) those come back as well, so the
+     *  array can hold more than `limit`. They were retrieved and billed either way;
+     *  dropping them would only hide what you already paid for. Size a prompt window
+     *  on the array you get back, not on `limit`. `searchSelf()` hands the two back
+     *  apart. */
     async search(query, userId, limit = 10, opts = {}) {
         // Reserved fields win over ...opts: an app that forwards untrusted input as
         // opts must not be able to override the store (user_id), query, or limit.
         warnOnUnknownFilters(opts.filters);
+        checkCount(limit, "limit");
         const r = await this.post("/api/v1/memory/search", { ...opts, user_id: this.uid(userId), query, max_results: limit });
-        return mergeLanes(r);
+        return mergeResults(r);
     }
-    /** Search a self-memory model (Scroll 1.2+): both lanes from ONE call. Returns
-     * `{ memories, self_memories }` — `memories` is the main lane (what others said /
-     * general memories), `self_memories` is the assistant's OWN words (stored with
-     * speaker "me"), kept separate so the reader never confuses who said what. On a model
-     * without a self lane, `self_memories` is `[]`. `userId` optional (default store). */
+    /** Search a self-memory model (Scroll 1.2+): both fields from ONE call. Returns
+     * `{ memories, self_memories }` — `memories` is what others said and general
+     * memories, `self_memories` is the assistant's OWN words (stored with speaker
+     * "me"), kept apart so whoever reads them never confuses who said what. On a model
+     * that does not keep them apart, `self_memories` is `[]`. `userId` may be omitted. */
     async searchSelf(query, userId, limit = 10, opts = {}) {
         warnOnUnknownFilters(opts.filters);
+        checkCount(limit, "limit");
         const r = await this.post("/api/v1/memory/search", { ...opts, user_id: this.uid(userId), query, max_results: limit });
         return { memories: asRecords(r.memories), self_memories: asRecords(r.self_memories) };
     }
     /**
-     * Search, and keep every lane the answer came in.
+     * Search, and keep every field the answer came with.
      *
      * Same request as {@link Client.search} — reach for this one when the options make
      * the merged array an incomplete answer:
      *
      *     const r = await mem.searchFull("the day we moved", "alice", 10,
      *                                    { max_images: 3, verify: 2 });
-     *     r.images.length;   // the photo lane, which `search` drops
+     *     r.images.length;   // the photos, which `search` drops
      *     r.verify_used;     // how many re-ask passes actually ran (you are billed per pass)
      *
      * Both options need Tablet 2 or newer and are refused (403) on an older engine
@@ -626,8 +725,9 @@ export class Client {
      */
     async searchFull(query, userId, limit = 10, opts = {}) {
         warnOnUnknownFilters(opts.filters);
+        checkCount(limit, "limit");
         const r = await this.post("/api/v1/memory/search", { ...opts, user_id: this.uid(userId), query, max_results: limit });
-        // Spread first so a lane added later still arrives; the known ones are then
+        // Spread first so a field added later still arrives; the known ones are then
         // normalized, because a broken proxy can null any of them.
         return {
             ...r,
@@ -639,15 +739,25 @@ export class Client {
     /** One-call LLM context: short-term turns + long-term matches + surrounding context.
      * `form` ("memoir"/"archive", Scroll 1.2+) renders each long-term memory's time in
      * that form; `tz` is your UTC-offset hours for that rendering. */
-    recall(query, userId, opts = {}) {
+    // `async` so an argument mistake arrives the way every other failure does — a
+    // rejected promise. Validating inside a non-async method threw synchronously, so
+    // `mem.recall(...).catch(h)` walked straight past the handler while the identical
+    // mistake in `search` (which is async) landed in it. Two shapes for one error.
+    async recall(query, userId, opts = {}) {
         const body = { user_id: this.uid(userId), query };
-        if (opts.limit !== undefined)
+        if (opts.limit !== undefined) {
+            checkCount(opts.limit, "limit");
             body.limit = opts.limit;
-        if (opts.context_limit !== undefined)
+        }
+        if (opts.context_limit !== undefined) {
+            checkContextLimit(opts.context_limit);
             body.context_limit = opts.context_limit;
+        }
         return this.post("/api/v1/memory/recall", withForm(body, opts.form, opts.tz));
     }
-    /** Run a built-in engram ("deep_recall" | "timeline" | "gather"). Returns the merged result.
+    /** Run a built-in engram ("deep_recall" | "timeline" | "gather" | "equilibrium" |
+     * "tone_stabilizer"; the service is the authority — an unknown name comes back with
+     * the list it accepts). Returns the merged result.
      * `form`/`tz` render memory times (memoir/archive) on Scroll 1.2+, same as search/recall. */
     engram(name, query, userId, opts = {}) {
         return this.post("/api/v1/engram/run", withForm({ name, user_id: this.uid(userId), query }, opts.form, opts.tz));
@@ -661,10 +771,11 @@ export class Client {
     stats(userId) {
         return this.post("/api/v1/memory/stats", { user_id: this.uid(userId) });
     }
-    /** Fetch ONE memory by id — the original text + metadata, never the vector.
+    /** Fetch ONE memory by id — the text you stored, and its metadata.
      * The id is what `add`/`store` or `listMemories` returned. Same visibility as
-     * `listMemories`: an id from another store, a decomposed atom sentence, or an
-     * invalidated memory rejects with `NotFoundError`. `userId` optional (default store). */
+     * `listMemories`: an id from another store, an internal record id, or an
+     * invalidated memory rejects with `NotFoundError`. Pass `undefined` as `userId` for
+     * the default store — it is positional here, not omittable as it is in Python. */
     get(userId, memoryId) {
         // Sync throw (same shape as `delete`), so a missing id fails loudly even
         // when the caller forgets to await.
@@ -673,8 +784,8 @@ export class Client {
         }
         return this.post("/api/v1/memory/get", { user_id: this.uid(userId), memory_id: memoryId }).then((r) => asObj(r.memory));
     }
-    /** List a store's stored memories — the original text plus metadata, never the
-     * vector. Paginated: pass the returned `next_cursor` back as `cursor` for the next
+    /** List a store's stored memories — the text you stored, plus its metadata.
+     * Paginated: pass the returned `next_cursor` back as `cursor` for the next
      * page; a `null` cursor means the last page. Use it to browse or export a store.
      *
      *     let cursor: string | null = null;
@@ -692,7 +803,7 @@ export class Client {
         return this.post("/api/v1/memory/list", body);
     }
     /** Async-iterate every stored memory in a store, paging under the hood — no cursor
-     * bookkeeping. Original text + metadata only, never vectors.
+     * bookkeeping. The text you stored and its metadata only.
      *
      *     for await (const m of mem.iterMemories()) console.log(m.id, m.content);
      */
@@ -707,12 +818,14 @@ export class Client {
                 yield m;
             const next = p.next_cursor ?? undefined;
             if (!next || seen.has(next))
-                break;
+                return;
             seen.add(next);
             cursor = next;
         }
+        throw new Error(`stopped after ${MAX_PAGES} pages — the store did not end. This is a truncated ` +
+            `answer, not the whole store.`);
     }
-    /** Collect ALL of a store's memories into an array (original text + metadata, no vectors). */
+    /** Collect ALL of a store's memories into an array (the text you stored, and its metadata). */
     async exportMemories(userId) {
         const out = [];
         for await (const m of this.iterMemories(userId))
@@ -726,8 +839,8 @@ export class Client {
      * Not necessarily your upload, in size OR in format: an image whose long edge was
      * over 1568px was downscaled to 1568 on the way in and re-encoded — lossless
      * formats as WebP, so a PNG comes back as `image/webp`; JPEG stays JPEG — and that
-     * smaller picture is what was embedded, stored and comes back here. Nothing in the
-     * retrieval path looks above 1568, so the extra pixels would be bytes nobody reads.
+     * smaller picture is what is stored and comes back here. Nothing on our side ever
+     * uses more than 1568, so the extra pixels would be bytes nobody reads.
      * Keep your own copy for the full-resolution file.
      *
      * The type is sniffed from the bytes themselves rather than from whatever the file
@@ -800,17 +913,24 @@ export class Client {
             const p = await this.listImages(userId, { limit: opts.pageSize, before, skipIds });
             for (const m of asRecords(p.images))
                 yield m;
+            // `return`, not `break`: the throw below is the MAX_PAGES backstop, and a
+            // `break` fell straight into it — so the ordinary end of a walk raised
+            // "the store did not end" on a store that had just ended. Python is safe
+            // here by using for/else and Rust by carrying an `ended` flag; TypeScript
+            // has neither, so the exit has to leave the function outright.
             if (!p.has_more || !p.next_before)
-                break;
+                return;
             // The cursor is the PAIR: several images can share a timestamp, so `before`
             // alone repeats across pages legitimately.
             const key = `${p.next_before}|${(Array.isArray(p.next_skip_ids) ? p.next_skip_ids : []).join(",")}`;
             if (seen.has(key))
-                break;
+                return;
             seen.add(key);
             before = p.next_before;
             skipIds = Array.isArray(p.next_skip_ids) ? p.next_skip_ids : undefined;
         }
+        throw new Error(`stopped after ${MAX_PAGES} pages — the store did not end. This is a truncated ` +
+            `answer, not the whole store.`);
     }
     // ----- how much has this memory been edited -----
     /**
@@ -890,9 +1010,9 @@ export class Client {
      * assistant's own words, otherwise a person's name. Same cursor paging as
      * `listImages`.
      *
-     * `chunks` / `points_to_delete` report the sentence-level fragments behind these
-     * memories, which is what a delete would actually remove — usually larger than
-     * `returned`, and worth showing before anyone confirms one.
+     * `chunks` / `points_to_delete` report how many internal records a delete would
+     * actually remove — usually more than `returned`, and worth showing to whoever is
+     * about to confirm one.
      */
     bySpeaker(speaker, userId, opts = {}) {
         if (!speaker || typeof speaker !== "string" || speaker.trim() === "") {
@@ -975,14 +1095,18 @@ export class Client {
     /** The store's registered people, each with its memory count. */
     async listSpeakers(userId) {
         const r = await this.request("GET", `/api/v1/memory/speakers?user_id=${encodeURIComponent(this.uid(userId))}`);
-        return { speakers: [], ...r };
+        // The spread came second, so a present-but-null `speakers` overwrote the default
+        // and the caller got null typed as an array. Every other list route goes through
+        // asRecords; this one did not.
+        return { ...r, speakers: asRecords(r?.speakers) };
     }
     /** Unregister a person. Their memories stay; the name tag goes. */
     removeSpeaker(speaker, userId) {
         return this.request("DELETE", "/api/v1/memory/speakers", { user_id: this.uid(userId), speaker });
     }
     // ----- delete -----
-    /** Delete a single memory by id. `userId` optional (uses the default store). */
+    /** Delete a single memory by id. Pass `undefined` as `userId` for the default
+     *  store — it is positional here, not omittable as it is in Python. */
     delete(userId, memoryId) {
         // Guard: without a memory_id the API's forget endpoint means "delete the
         // whole store". An undefined/"" slipping in here must never become a wipe.
@@ -1024,66 +1148,203 @@ export class Client {
      * a non-2xx we re-read the body as text and reuse `errorFor`, which keeps 404
      * (`NotFoundError`) and 401 behaving the same as everywhere else.
      */
-    async requestBytes(path, body) {
+    /** Where this call's budget runs out, or `undefined` when it has none. Computed
+     *  once per call, not per attempt — a budget recomputed each attempt is not a
+     *  budget. */
+    deadlineAt() {
+        return this.deadlineMs === undefined ? undefined : Date.now() + this.deadlineMs;
+    }
+    /** The abort wiring for ONE attempt: this SDK's per-attempt timeout, the caller's
+     *  signal, and whatever is left of the overall deadline — whichever fires first.
+     *
+     *  One function, two callers (`request` and `requestBytes`), because a guard living
+     *  in one of two request paths is exactly how `getImage` ended up with no retry loop
+     *  while the module doc promised every call had one. */
+    beginAttempt(deadlineAt) {
+        let why = "timeout";
+        let budget = this.timeoutMs;
+        if (deadlineAt !== undefined) {
+            const left = deadlineAt - Date.now();
+            // Refuse rather than open a socket there is no time to use. Python's
+            // `_attempt_budget` and Rust's `attempt_budget` have raised here from the start.
+            // This path instead clamped the budget to 0 and began the attempt anyway, which
+            // left `setTimeout(…, 0)` — it fires on the next timer phase — racing a fetch
+            // that a fast server answers first. The same call then sometimes reported its
+            // deadline and sometimes returned a result: one run in three, measured.
+            if (left <= 0)
+                throw new APIConnectionError(0, this.abortMessage("deadline"));
+            if (left < budget) {
+                budget = left;
+                why = "deadline";
+            }
+        }
         const ctrl = new AbortController();
-        const timer = setTimeout(() => ctrl.abort(), this.timeoutMs);
-        let res;
-        try {
-            res = await this.fetchImpl(`${this.base}${path}`, {
-                method: "POST",
-                headers: this.headers,
-                body: JSON.stringify(body),
-                signal: ctrl.signal,
-                redirect: "manual",
-            });
+        const timer = setTimeout(() => ctrl.abort(), budget);
+        const outer = this.signal;
+        const onCaller = () => {
+            why = "caller";
+            ctrl.abort();
+        };
+        if (outer) {
+            if (outer.aborted)
+                onCaller();
+            // Removed in clear(). `{ once: true }` would not be enough: one long-lived
+            // signal per user session would still collect one listener per request until
+            // the session ended.
+            else
+                outer.addEventListener("abort", onCaller);
         }
-        catch (e) {
-            clearTimeout(timer);
-            if (e?.name === "AbortError" || ctrl.signal.aborted) {
-                throw new APIConnectionError(0, `request timed out after ${this.timeoutMs}ms`);
-            }
-            throw new APIConnectionError(0, `network error: ${e?.message ?? e}`);
+        return {
+            signal: ctrl.signal,
+            clear: () => {
+                clearTimeout(timer);
+                outer?.removeEventListener("abort", onCaller);
+            },
+            why: () => why,
+        };
+    }
+    /** What to say when an attempt was cut short. The three reasons need different
+     *  words: a timeout may have landed server-side, a cancellation certainly did not
+     *  matter to the caller, and an exhausted budget is the caller's own setting. */
+    abortMessage(why) {
+        if (why === "caller")
+            return "cancelled — the caller's AbortSignal fired";
+        if (why === "deadline")
+            return `deadline of ${this.deadlineMs}ms exhausted`;
+        return `request timed out after ${this.timeoutMs}ms`;
+    }
+    /** Sleep between attempts — but wake the moment the caller aborts, and give up
+     *  rather than wait out a backoff the budget cannot cover. A backoff that runs to
+     *  completion after the caller gave up wastes exactly as long as the request it was
+     *  waiting to repeat.
+     *
+     *  Clamping the wait to what is left and retrying anyway is the same answer as
+     *  having no deadline at all: the call still spends the whole allowance, and the one
+     *  attempt it buys has nothing left to finish in. If the wait does not fit, the
+     *  budget is already decided. */
+    async backoffSleep(ms, deadlineAt) {
+        if (deadlineAt !== undefined && ms > deadlineAt - Date.now()) {
+            throw new APIConnectionError(0, this.abortMessage("deadline"));
         }
-        try {
-            this._rateLimit = parseRateLimit(res.headers) ?? this._rateLimit;
-            if ((res.status >= 300 && res.status < 400) || res.type === "opaqueredirect") {
-                void res.body?.cancel();
-                throw errorFor(res.status, "the API answered with a redirect; refusing to follow it");
+        const outer = this.signal;
+        if (!outer) {
+            await new Promise((r) => setTimeout(r, ms));
+            return;
+        }
+        if (outer.aborted)
+            return;
+        await new Promise((resolve) => {
+            const done = () => {
+                clearTimeout(timer);
+                outer.removeEventListener("abort", done);
+                resolve();
+            };
+            const timer = setTimeout(done, ms);
+            outer.addEventListener("abort", done);
+        });
+    }
+    async requestBytes(path, body) {
+        // This route had no retry loop at all, while the module doc promised "every call
+        // retries transient failures … 429 always". Measured with maxRetries: 4 against a
+        // server answering 429 — stats() made five requests, getImage() made one. The
+        // largest and most rate-limit-prone call in the SDK was the one that gave up
+        // immediately. The loop lives inside the function because honouring `Retry-After`
+        // means still holding the response.
+        const attempts = this.maxRetries + 1;
+        const deadlineAt = this.deadlineAt();
+        for (let attempt = 0;; attempt++) {
+            const att = this.beginAttempt(deadlineAt);
+            let res;
+            try {
+                res = await this.fetchImpl(`${this.base}${path}`, {
+                    method: "POST",
+                    headers: this.headers,
+                    body: JSON.stringify(body),
+                    signal: att.signal,
+                    redirect: "manual",
+                });
             }
-            if (!res.ok) {
-                let msg = await this.readCapped(res).catch(() => "");
+            catch (e) {
+                att.clear();
+                const timedOut = e?.name === "AbortError" || att.signal.aborted;
+                // Same rule as `request()`: a connect-level failure never reached the server,
+                // so re-sending cannot double-process anything. The 429 loop below was added
+                // in 2.2.35 and this branch was not, which left the module doc's promise —
+                // "every call retries transient failures" — still false for `getImage` on
+                // exactly the failure a retry is for. A timeout is ambiguous and stays final.
+                if (!timedOut && isConnectFailure(e) && attempt + 1 < attempts) {
+                    await this.backoffSleep(this.backoffMs(attempt), deadlineAt);
+                    continue;
+                }
+                throw new APIConnectionError(0, timedOut ? this.abortMessage(att.why()) : `network error: ${e?.message ?? e}`);
+            }
+            try {
+                this._rateLimit = parseRateLimit(res.headers) ?? this._rateLimit;
+                if ((res.status >= 300 && res.status < 400) || res.type === "opaqueredirect") {
+                    void res.body?.cancel();
+                    throw errorFor(res.status, "the API answered with a redirect; refusing to follow it");
+                }
+                if (!res.ok) {
+                    if (RETRY_ALWAYS.has(res.status) && attempt + 1 < attempts) {
+                        const retryAfter = res.headers.get("Retry-After");
+                        void res.body?.cancel();
+                        att.clear();
+                        await this.backoffSleep(this.backoffMs(attempt, retryAfter), deadlineAt);
+                        continue;
+                    }
+                    let msg = await this.readCapped(res).catch(() => "");
+                    try {
+                        const data = JSON.parse(msg);
+                        const err = data?.error;
+                        if (err && typeof err === "object")
+                            msg = err.message ?? err.type ?? msg;
+                        else if (typeof err === "string")
+                            msg = err;
+                    }
+                    catch {
+                        /* keep raw text */
+                    }
+                    if (msg.length > MAX_ERR_MSG)
+                        msg = msg.slice(0, MAX_ERR_MSG) + "…(truncated)";
+                    throw errorFor(res.status, msg || `HTTP ${res.status}`);
+                }
+                // Translated, not raw. A timeout that fires while the body is streaming used to
+                // escape as `AbortError` — not a WosError, not an APIConnectionError — so a
+                // caller's `catch (e) { if (e instanceof WosError) … }` handled every JSON route
+                // and let this one through unclassified. The JSON path already translated it.
+                let buf;
                 try {
-                    const data = JSON.parse(msg);
-                    const err = data?.error;
-                    if (err && typeof err === "object")
-                        msg = err.message ?? err.type ?? msg;
-                    else if (typeof err === "string")
-                        msg = err;
+                    buf = await this.readCappedBytes(res);
                 }
-                catch {
-                    /* keep raw text */
+                catch (e) {
+                    if (e?.name === "AbortError" || att.signal.aborted) {
+                        throw new APIConnectionError(0, `request timed out after ${this.timeoutMs}ms`);
+                    }
+                    throw e;
                 }
-                if (msg.length > MAX_ERR_MSG)
-                    msg = msg.slice(0, MAX_ERR_MSG) + "…(truncated)";
-                throw errorFor(res.status, msg || `HTTP ${res.status}`);
+                if (buf.byteLength === 0) {
+                    // An empty 200 would otherwise read as "here is your image" and write a
+                    // zero-byte file — indistinguishable from an image we lost.
+                    throw new WosError(res.status, "empty image body — the service returned no bytes");
+                }
+                return { bytes: buf, contentType: res.headers.get("content-type") ?? "application/octet-stream" };
             }
-            const buf = await this.readCappedBytes(res);
-            if (buf.byteLength === 0) {
-                // An empty 200 would otherwise read as "here is your image" and write a
-                // zero-byte file — indistinguishable from an image we lost.
-                throw new WosError(res.status, "empty image body — the service returned no bytes");
+            finally {
+                att.clear();
             }
-            return { bytes: buf, contentType: res.headers.get("content-type") ?? "application/octet-stream" };
-        }
-        finally {
-            clearTimeout(timer);
         }
     }
     /** Validate an idempotency key BEFORE the network. The API answers a malformed
      *  key with a 400, which on a retry path reads as "my write failed" when in fact
      *  it was never attempted — cheaper and clearer to reject it here. */
     idemHeader(key) {
-        if (key === undefined)
+        // `=== undefined` let `null` through: RegExp.test stringifies its argument, so
+        // `null` became the literal key "null" and passed the format check. A key read
+        // from JSON or a database row arrives as null, not undefined, and every write on
+        // that path then shared one key — the second onward returned the first response
+        // and stored nothing. Python guards with `is None`; Rust's Option makes it
+        // unrepresentable.
+        if (key === undefined || key === null)
             return undefined;
         if (!IDEMPOTENCY_KEY_RE.test(key)) {
             throw new Error(`invalid idempotencyKey: ${JSON.stringify(key)} — 1-128 chars of [A-Za-z0-9._:-]`);
@@ -1116,10 +1377,20 @@ export class Client {
     async readCappedBytes(res) {
         const cl = res.headers.get("content-length");
         if (cl && Number(cl) > MAX_RESPONSE_BYTES) {
-            throw new WosError(0, `response too large (${cl} bytes) — refusing to buffer it`);
+            throw new WosError(res.status, `response too large (${cl} bytes) — refusing to buffer it`);
+        }
+        if (!res.body) {
+            // `arrayBuffer()` has no ceiling, and only the content-length pre-check stands
+            // in front of it — which a server simply omits. Reachable through the documented
+            // `fetch` seam (test doubles, polyfills, wrappers that rebuild the Response),
+            // and the option's own doc promises "the size cap still applies". Measured: a
+            // body-less Response with no content-length buffered 73MB past the 64MB cap.
+            const buf = new Uint8Array(await res.arrayBuffer());
+            if (buf.byteLength > MAX_RESPONSE_BYTES) {
+                throw new WosError(res.status, `response too large (${buf.byteLength} bytes) — refusing it`);
+            }
+            return buf;
         }
-        if (!res.body)
-            return new Uint8Array(await res.arrayBuffer());
         const reader = res.body.getReader();
         const parts = [];
         let size = 0;
@@ -1130,7 +1401,7 @@ export class Client {
             size += value.byteLength;
             if (size > MAX_RESPONSE_BYTES) {
                 void reader.cancel();
-                throw new WosError(0, "response too large — refusing to buffer it");
+                throw new WosError(res.status, "response too large — refusing to buffer it");
             }
             parts.push(value);
         }
@@ -1148,26 +1419,26 @@ export class Client {
         // Debug logging shows the path WITHOUT its query string — a query can carry
         // a store id (listSpeakers), and logs must never carry data.
         const logPath = path.split("?")[0];
+        const deadlineAt = this.deadlineAt();
         for (let attempt = 0; attempt < attempts; attempt++) {
             const start = Date.now();
-            const ctrl = new AbortController();
-            const timer = setTimeout(() => ctrl.abort(), this.timeoutMs);
+            const att = this.beginAttempt(deadlineAt);
             let res;
             try {
                 res = await this.fetchImpl(`${this.base}${path}`, {
                     method,
                     headers: extraHeaders ? { ...this.headers, ...extraHeaders } : this.headers,
                     body: body === undefined ? undefined : JSON.stringify(body),
-                    signal: ctrl.signal,
+                    signal: att.signal,
                     // Never follow a redirect: fetch would forward the API key to
                     // wherever a 3xx points. The API never legitimately redirects.
                     redirect: "manual",
                 });
             }
             catch (e) {
-                clearTimeout(timer);
+                att.clear();
                 // Timeouts are ambiguous (the write may have landed) — don't retry those.
-                const timedOut = e?.name === "AbortError" || ctrl.signal.aborted;
+                const timedOut = e?.name === "AbortError" || att.signal.aborted;
                 // Other network errors retry only when a retry can't double-process a
                 // write: idempotent methods always; writes only for connect-level
                 // failures (the request never reached the server). A mid-stream drop on
@@ -1176,24 +1447,24 @@ export class Client {
                 if (!timedOut && safe && attempt + 1 < attempts) {
                     const delay = this.backoffMs(attempt);
                     logDebug(`${method} ${logPath}: ${e?.code ?? e?.name ?? "network error"} — retrying in ${delay}ms (attempt ${attempt + 1}/${attempts})`);
-                    await new Promise((r) => setTimeout(r, delay));
+                    await this.backoffSleep(delay, deadlineAt);
                     continue;
                 }
-                throw new APIConnectionError(0, timedOut ? `request timed out after ${this.timeoutMs}ms` : `network error: ${e?.message ?? e}`);
+                throw new APIConnectionError(0, timedOut ? this.abortMessage(att.why()) : `network error: ${e?.message ?? e}`);
             }
             const retryable = RETRY_ALWAYS.has(res.status) ||
                 (RETRY_IF_IDEMPOTENT.has(res.status) && IDEMPOTENT_METHODS.has(method.toUpperCase()));
             if (retryable && attempt + 1 < attempts) {
-                clearTimeout(timer);
+                att.clear();
                 const retryAfter = res.headers.get("Retry-After");
                 void res.body?.cancel();
                 const delay = this.backoffMs(attempt, retryAfter);
                 logDebug(`${method} ${logPath} -> ${res.status} — retrying in ${delay}ms (attempt ${attempt + 1}/${attempts})`);
-                await new Promise((r) => setTimeout(r, delay));
+                await this.backoffSleep(delay, deadlineAt);
                 continue;
             }
             if ((res.status >= 300 && res.status < 400) || res.type === "opaqueredirect") {
-                clearTimeout(timer);
+                att.clear();
                 void res.body?.cancel(); // release the stream — otherwise the connection leaks
                 throw new WosError(res.status, "unexpected redirect — refused (the API key never follows a redirect). Check baseUrl: exact host, https://.");
             }
@@ -1206,7 +1477,7 @@ export class Client {
                 text = await this.readCapped(res);
             }
             catch (e) {
-                if (e?.name === "AbortError" || ctrl.signal.aborted) {
+                if (e?.name === "AbortError" || att.signal.aborted) {
                     throw new APIConnectionError(0, `request timed out after ${this.timeoutMs}ms`);
                 }
                 if (e instanceof WosError)
@@ -1216,7 +1487,7 @@ export class Client {
                 throw new APIConnectionError(0, `network error: ${e?.message ?? e}`);
             }
             finally {
-                clearTimeout(timer);
+                att.clear();
             }
             logDebug(`${method} ${logPath} -> ${res.status} in ${Date.now() - start}ms (attempt ${attempt + 1}/${attempts})`);
             if (!res.ok) {
@@ -1277,12 +1548,17 @@ export class Client {
             // `Idempotent-Replayed: true`, and it answers the question someone using an
             // idempotency key is asking: did my retry write, or is this the first response
             // coming back again?
-            if (res.headers.get("Idempotent-Replayed") === "true") {
+            //
+            // Only when the body does not already carry the field. These responses are
+            // widening — the next engine adds `images`, `hop`, `tip_of_tongue`, `policy` —
+            // and a client that writes into a server's object is one release away from
+            // overwriting a real answer with its own guess. What the service said wins.
+            if (res.headers.get("Idempotent-Replayed") === "true" && !("replayed" in data)) {
                 data.replayed = true;
             }
             return data;
         }
-        throw new WosError(0, "retries exhausted"); // unreachable; keeps the compiler happy
+        throw new Error("retries exhausted"); // unreachable; keeps the compiler happy
     }
 }
 /** Back-compat alias: older code used `WME`. */