wontopos 2.2.33 → 2.2.35

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.33";
+const VERSION = "2.2.35";
 /** 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). */
@@ -55,7 +58,15 @@ function logDebug(msg) {
     }
 }
 const DEFAULT_BASE_URL = "https://api.wontopos.com";
-const DEFAULT_MODEL = "tablet-1";
+/** The engine every call uses unless the caller names another.
+ *
+ *  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]);
 /** 502/503 are ambiguous for a write (gateway may return them AFTER the backend
@@ -96,8 +107,9 @@ function normalizeStoreId(id) {
  *  Bounded on purpose. The warning fires on ids that fold, and the shape it exists
  *  to catch is an email — which this SDK's own documented pattern ("one store per
  *  end user") turns into one entry PER USER, held for the life of the process and
- *  never released, even when the client is. A server passing 50,000 user ids grew
- *  this to 50,000 entries, a leak in exactly the case being warned about. A `Set`
+ *  never released, even when the client is. A server that forwards 50,000 distinct user
+ *  ids would grow this to 50,000 entries, leaking in exactly the case the warning
+ *  exists to catch. A `Set`
  *  keeps insertion order, so the oldest entry is the one evicted; dropping the
  *  oldest rather than refusing new ones means a collision that first shows up late
  *  still gets its one warning. */
@@ -131,15 +143,44 @@ 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;
+/** `search`'s count, refused out of range rather than quietly adjusted.
+ *
+ * `recall` has carried this contract from the start — 5 to 20, and the service
+ * refuses anything else, 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.
+ *
+ * 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 checkSearchLimit(limit) {
+    if (!Number.isInteger(limit) || limit < SEARCH_LIMIT_MIN || limit > SEARCH_LIMIT_MAX) {
+        throw new WosError(0, `limit 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.`);
+    }
+}
 /**
  * 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".
@@ -151,16 +192,15 @@ function normalizeImage(image) {
     if (typeof image.data !== "string" || image.data.trim() === "") {
         throw new Error("image.data is required — base64 of the image (a data: URL is fine).");
     }
-    // 🔴**다듬고 나서 접두어를 본다.** 예전엔 원본에 바로 `startsWith("data:")` 를
-    //   걸어서, 앞에 공백이 하나만 있어도(` data:image/png;base64,…`) 접두어를 못 떼고
-    //   **`data:image/png;base64,` 문자열까지 통째로 base64 로** 보냈다. 엔진은
-    //   "이미지를 읽을 수 없다"며 400 을 내고, 부르는 쪽은 왜인지 모른다.
+    // Trim before looking for the prefix. Checked against the raw string, one leading
+    // space (` data:image/png;base64,…`) hides the prefix, and the literal
+    // `data:image/png;base64,` travels as part of the base64. The engine answers 400
+    // "image could not be read" and the caller has no way to tell why.
     const raw = image.data.trim();
     const comma = raw.startsWith("data:") ? raw.indexOf(",") : -1;
-    // 🔴그리고 **가운데 공백까지** 없앤다. `base64` 명령과 `openssl base64` 는 76자마다
-    //   줄을 바꾼다 — 파일을 그렇게 만들어 붙여넣는 건 흔한 길인데, 양끝만 다듬으면
-    //   그 줄바꿈이 그대로 payload 에 남는다. base64 알파벳에 공백은 없으므로
-    //   전부 빼는 게 안전하다.
+    // Strip whitespace in the middle as well. `base64` and `openssl base64` wrap at 76
+    // columns, and trimming only the ends leaves those line breaks in the payload. The
+    // base64 alphabet contains no whitespace, so removing all of it is safe.
     const data = (comma === -1 ? raw : raw.slice(comma + 1)).replace(/\s+/g, "");
     if (data === "")
         throw new Error("image.data is empty after stripping its data: prefix.");
@@ -234,21 +274,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)
@@ -256,6 +293,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;
@@ -309,8 +349,8 @@ export class RateLimitError extends WosError {
  * `501` is NOT transient. It means the engine behind the model you selected does
  * not implement that endpoint at all (the error carries `model` and `endpoint`).
  * Retrying can never succeed — pick a model that supports it (`listModels`) or
- * drop the call. This class used to say "safe to retry" for the whole 5xx range,
- * which sent callers into a loop that could not end.
+ * drop the call. Treating the whole 5xx range as retryable sends a caller into a
+ * loop that cannot end.
  */
 export class ServerError extends WosError {
 }
@@ -396,6 +436,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
@@ -441,7 +487,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 self-hosted
+            // 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
@@ -545,8 +596,7 @@ export class Client {
     // store (set via `new Client({ apiKey, userId })` or `withUser`).
     /** Store one memory. `metadata` optional — e.g. `{ event_date: "2026-03-01" }` for when the
      * content actually happened. A plain date works (read as UTC midnight); a full RFC3339
-     * timestamp also works. The API used to demand the full form and answered a bare date with
-     * an opaque 400, which is why older examples here show the long one.
+     * timestamp also works; older examples here show the long form.
      * `metadata.speaker`: "me" = the assistant's own words, or a person's name (up to 50 per store).
      *
      * `opts.idempotencyKey`: see {@link WriteOptions} — pass one to make YOUR retry
@@ -565,9 +615,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)
@@ -579,31 +629,60 @@ 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);
+        checkSearchLimit(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);
+        checkSearchLimit(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 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 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
+     * rather than accepted and ignored.
+     */
+    async searchFull(query, userId, limit = 10, opts = {}) {
+        warnOnUnknownFilters(opts.filters);
+        checkSearchLimit(limit);
+        const r = await this.post("/api/v1/memory/search", { ...opts, user_id: this.uid(userId), query, max_results: limit });
+        // 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,
+            memories: asRecords(r.memories),
+            self_memories: asRecords(r.self_memories),
+            images: asRecords(r.images),
+        };
+    }
     /** 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. */
@@ -615,7 +694,9 @@ export class Client {
             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));
@@ -629,10 +710,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.
@@ -641,8 +723,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;
@@ -660,7 +742,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);
      */
@@ -675,12 +757,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 WosError(0, `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))
@@ -694,8 +778,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
@@ -759,15 +843,33 @@ export class Client {
     async *iterImages(userId, opts = {}) {
         let before;
         let skipIds;
+        // Same repeat-cursor guard as `iterMemories`. A server that hands back the
+        // cursor it was just given would otherwise re-yield one page MAX_PAGES times,
+        // and the caller reads those repeats as more images. The page cap alone bounds
+        // the walk; it does not stop the duplicates.
+        const seen = new Set();
         for (let page = 0; page < MAX_PAGES; page++) {
             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))
+                return;
+            seen.add(key);
             before = p.next_before;
             skipIds = Array.isArray(p.next_skip_ids) ? p.next_skip_ids : undefined;
         }
+        throw new WosError(0, `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 -----
     /**
@@ -780,10 +882,10 @@ export class Client {
      *
      * Counts memories a transform touched (supersede, update, retract, image removed).
      * Deletions are NOT counted: a deleted memory leaves nothing to count. Neither are
-     * atoms, the sentence fragments search uses internally — nobody stored one, so they
-     * do not belong in a ratio that answers "how much of MY memory changed".
+     * the internal records derived from what you stored — nobody stored those directly,
+     * so they do not belong in a ratio that answers "how much of MY memory changed".
      *
-     * ★By default this returns COUNTS ONLY, and the answer is the same size for a store
+     * By default this returns COUNTS ONLY, and the answer is the same size for a store
      * of a hundred memories and a store of a hundred million. That is deliberate: a model
      * asks this mid-conversation, and an answer that grew with the store would be
      * unusable for exactly the customers who most need to ask.
@@ -804,10 +906,10 @@ export class Client {
      * }
      * ```
      *
-     * ⚠️Pages are ordered by when each memory was STORED, not by when it was edited.
+     * Pages are ordered by when each memory was STORED, not by when it was edited.
      * The response says so in `ordered_by`.
      *
-     * ★Served from `/api/v1/won/*`, not `/api/v1/memory/*`. Won is the surface for calls
+     * Served from `/api/v1/won/*`, not `/api/v1/memory/*`. Won is the surface for calls
      * a model makes ABOUT its memory rather than calls an application makes WITH it, and
      * the address says so. The old path still answers, for clients published before
      * 2026-08-18, and both share one rate-limit budget.
@@ -847,9 +949,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() === "") {
@@ -881,10 +983,9 @@ export class Client {
     /**
      * The engrams (and delivery forms) the selected model can actually run.
      *
-     * `engram()` could always RUN one, but there was no way to ASK what exists — so a
-     * caller had to hard-code names from the docs, and every engram we shipped after
-     * their code was written stayed invisible to them. The MCP server hit exactly this
-     * and stopped hard-coding for the same reason. The service is the authority: what
+     * Ask rather than hard-code: a name copied from the docs freezes a caller to the
+     * catalogue as it was that day, and anything added later stays invisible. The
+     * service is the authority. What
      * comes back depends on the model (delivery forms need Scroll 1.2+), so pass
      * `withModel()` if you want another model's catalogue.
      *
@@ -915,9 +1016,9 @@ export class Client {
     }
     /** Delete a store and ALL its memories. Returns `{ user_id, status }`. */
     deleteStore(userId) {
-        // Validate BEFORE warning. The warning helper lowercases the id, so a non-string
-        // used to die there as "id.toLowerCase is not a function" — the caller got a
-        // TypeError from our internals instead of being told what was wrong with the id.
+        // Validate before warning. The warning helper lowercases the id, so a non-string
+        // reaches it and dies as "id.toLowerCase is not a function" — a TypeError from
+        // inside the SDK instead of a sentence about the id.
         if (typeof userId !== "string" || !userId.trim())
             throw new Error("userId is required (a non-blank string) — deleteStore never falls back to the default store.");
         warnIfStoreIdCollapses(userId); // destructive: the collision warning belongs here too
@@ -933,23 +1034,26 @@ 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.
         //
-        // `.trim()` matters as much as the emptiness check: "   " is truthy, so it used to
-        // pass this guard and travel as memory_id. A server that trims it back to nothing
-        // reads the request as the whole-store form — the single most destructive way for
-        // this SDK to be wrong. `deleteAll` below already trimmed; the more dangerous path
-        // was the one that did not.
+        // `.trim()` matters as much as the emptiness check: "   " is truthy, so without it
+        // a blank string passes the guard and travels as memory_id. A server that trims it
+        // back to nothing reads the request as the whole-store form, which is the most
+        // destructive way for this SDK to be wrong.
         if (typeof memoryId !== "string" || !memoryId.trim()) {
             throw new Error("memoryId is required (non-blank). To delete every memory in a store, call deleteAll(userId) explicitly.");
         }
@@ -984,65 +1088,107 @@ export class Client {
      * (`NotFoundError`) and 401 behaving the same as everywhere else.
      */
     async requestBytes(path, body) {
-        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",
-            });
-        }
-        catch (e) {
-            clearTimeout(timer);
-            if (e?.name === "AbortError" || ctrl.signal.aborted) {
-                throw new APIConnectionError(0, `request timed out after ${this.timeoutMs}ms`);
+        // 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;
+        for (let attempt = 0;; attempt++) {
+            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",
+                });
             }
-            throw new APIConnectionError(0, `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");
+            catch (e) {
+                clearTimeout(timer);
+                const timedOut = e?.name === "AbortError" || ctrl.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 new Promise((r) => setTimeout(r, this.backoffMs(attempt)));
+                    continue;
+                }
+                throw new APIConnectionError(0, timedOut ? `request timed out after ${this.timeoutMs}ms` : `network error: ${e?.message ?? e}`);
             }
-            if (!res.ok) {
-                let msg = await this.readCapped(res).catch(() => "");
+            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();
+                        clearTimeout(timer);
+                        await new Promise((r) => setTimeout(r, this.backoffMs(attempt, retryAfter)));
+                        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" || ctrl.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 {
+                clearTimeout(timer);
             }
-            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._:-]`);
@@ -1069,17 +1215,26 @@ export class Client {
     }
     /** The same cap, for a body that is not text.
      *
-     * `getImage` used to call `arrayBuffer()` here, which buffers whatever arrives. The
-     * cap exists for a hostile or broken `baseUrl`, and a photo endpoint is exactly where
-     * that shows up — the JSON paths were guarded while the one path that returns
-     * megabytes was not. One implementation, two callers, so they cannot drift. */
+     * `arrayBuffer()` would buffer whatever arrives. The cap exists for a hostile or
+     * broken `baseUrl`, and an endpoint that returns megabytes is where that costs the
+     * most. One implementation, two callers, so they cannot drift. */
     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`);
         }
-        if (!res.body)
-            return new Uint8Array(await res.arrayBuffer());
+        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(0, `response too large (${buf.byteLength} bytes) — refusing it`);
+            }
+            return buf;
+        }
         const reader = res.body.getReader();
         const parts = [];
         let size = 0;
@@ -1209,10 +1364,9 @@ export class Client {
                     msg = msg.slice(0, MAX_ERR_MSG) + "…(truncated)";
                 throw errorFor(res.status, msg, requestId);
             }
-            // An empty body is only legal when the STATUS says there is no body. This
-            // used to accept any empty 2xx, so an `add()` answered by a truncating proxy
-            // returned `{}` and read as a successful write with no id — while the Python
-            // and Rust SDKs raised on the same response. Same rule in all three now.
+            // An empty body is only legal when the STATUS says there is no body. Accepting
+            // any empty 2xx would make an `add()` answered by a truncating proxy return `{}`,
+            // which reads as a successful write with no id. All three SDKs apply this rule.
             if (!text) {
                 if (NO_BODY_STATUS.has(res.status))
                     return {};
@@ -1234,10 +1388,10 @@ export class Client {
                 const got = data === null ? "null" : Array.isArray(data) ? "array" : typeof data;
                 throw new WosError(res.status, `expected a JSON object in the response, got ${got}`);
             }
-            // 멱등키를 쓴 쓰기가 **저장된 것인지 재생된 것인지**를 호출자가 알아야 한다.
-            // 서버는 `Idempotent-Replayed: true` 로 말해주는데 지금까지 SDK 가 삼켰다 —
-            // 멱등키를 쓰는 사람이 가장 알고 싶은 사실이 그것이다(재시도가 실제로
-            // 저장을 일으켰나, 아니면 첫 응답이 되풀이된 것인가).
+            // Surface whether the write was stored or replayed. The server says so with
+            // `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") {
                 data.replayed = true;
             }