wontopos 2.2.34 → 2.2.35

package/README.md

@@ -23,15 +23,23 @@ const ctx = await mem.recall("what does alice drink?", "alice");
 
 ## Why
 
-- **Pure semantic retrieval** — no keyword/BM25. Identical recall in every language (Korean · Japanese · Chinese · English).
-- **No LLM in the loop** — `store` / `search` / `recall` never call a language model. You pay embeddings, not generation.
+- **The same in every language** — identical recall whichever language a memory was written in (Korean · Japanese · Chinese · English).
+- **No LLM in the loop** — `store` / `search` / `recall` never call a language model. You pay retrieval, not generation.
 - **Bounded retrieval** — `recall()` returns a small, fixed-size slice (~1,200 tokens) regardless of how much you've stored.
 
 ## Methods
 
 `add` · `addTurn` · `addBulk` · `update` · `search` · `searchFull` · `recall` · `history` · `stats` · `get` · `listMemories` · `delete` · `deleteAll`
 
-Every method takes the store id as its second argument — `mem.add("...", "alice")`. Omit it to use the client's default store. A store is one isolated memory space per end-user, agent, or topic. WHO said each memory inside a store is the `speaker` tag below — storing the assistant's own words never needs a separate id.
+Where the store id goes depends on whether the method takes a payload. A method that
+writes or searches puts the payload first and the store second — `mem.add("...", "alice")`,
+`mem.search("...", "alice")`. A method that only addresses a store takes it first —
+`mem.listMemories("alice")`, `mem.stats("alice")`, `mem.delete("alice", memoryId)`.
+Most of them let you leave it out for the client's default store. Four take it
+positionally and cannot — `get`, `delete`, `lineage` and `forgetImage` want an explicit
+`undefined` there, because a second required argument follows it. Python omits it in
+all four; this is the one place the three clients differ in shape rather than meaning.
+Let your editor confirm the order: every signature is typed. A store is one isolated memory space per end-user, agent, or topic. WHO said each memory inside a store is the `speaker` tag below — storing the assistant's own words never needs a separate id.
 
 ## Who said it (speakers)
 
@@ -72,7 +80,12 @@ const hits = await mem.search("...the conversation so far...", "alice", 10,
 
 Built in, no configuration needed:
 
-- **Automatic retries** — 429 / 502 / 503 and connection errors retry twice with
+- **Automatic retries** — 429 always, and 502 / 503 or a connection error only when a
+  retry cannot double-process a write. The writes and the searches are POSTs, and a
+  502 on one of those may have been returned *after* the service already stored and
+  billed it, so those get 429 and connect-level failures only. The reads and the
+  deletes that address a whole store — `listStores`, `listSpeakers`, `deleteStore`,
+  `removeSpeaker`, `forgetImage` — are GET or DELETE and do retry a 502. Twice, with
   exponential backoff + jitter, honoring the server's `Retry-After`. Tune with
   `new Client({ maxRetries })`; `0` disables.
 - **Redirects refused** — the API key never follows a 3xx to another host.
@@ -189,7 +202,60 @@ data to fix it.
 
 The three clients release in lockstep — same version, same surface, same day.
 Patch releases are additive: nothing is removed or reordered within a minor line.
-
+Two have bent that, deliberately and named at the top of their entry — 2.2.34 moved the
+default engine, and 2.2.35 gives `search` the count range `recall` has always had. A
+rule you can bend without saying so is not a rule, so both are stated rather than left
+for a reader to hit.
+
+- **2.2.35** — fixes, and **two behaviour changes**, both listed first because a patch
+  release is not the place to find one by surprise.
+
+  ⚠️ **`search`'s count is now 5–20, and out of range is refused rather than
+  adjusted.** `recall` has carried that range from the start; search had no contract
+  anywhere, so the clients sent whatever they were given and the service capped at 50
+  with no floor. `search(q, limit=50)` and `search(q, limit=3)` both worked on 2.2.34
+  and now raise. The default is still 10, so a call that passes no count is unaffected.
+  Asking for 20 and silently getting 10 reads as "that is all there is", which is why
+  this refuses instead of clamping.
+
+  ⚠️ **A Rust `limit` of 0 is no longer rewritten to 10.** It was, and the caller whose
+  prompt budget computed zero was handed ten memories and the bill for them. It is now
+  refused under the range above rather than quietly changed to something nobody asked
+  for.
+
+  The fixes: a `null` idempotency key no longer becomes the literal key `"null"`, which
+  had made every write on that path share one key so the second onward stored nothing
+  (TypeScript). The async client no longer reads an explicit `retries=2` as "the caller
+  said nothing" (Python). The image read is actually streamed, so the 64MB cap bounds a
+  compressed body instead of measuring bytes already in memory (Python async), and that
+  route's ERROR body is capped too (Rust). `iter_images` stops on a repeated cursor the
+  way `iter_memories` always did (Python). `iterImages` no longer throws on the ordinary
+  end of a walk (TypeScript). `get_image` retries a 429 and a connect-level failure like
+  every other call — it had none at all — in the **sync Python client and TypeScript**;
+  the async Python client and the Rust crate still make a single attempt there, and say
+  so at the method. An empty or control-character API key is refused at the call site
+  rather than at the network in **Python and Rust**; TypeScript still refuses only empty
+  and whitespace. And a page walk that reaches its ceiling now raises instead of
+  returning a truncated list that looks complete.
+- **2.2.34** — the default engine is `tablet-2`: same token price as `tablet-1`, and
+  the one that serves images and re-ask. Pin the old one with
+  `model="tablet-1"` for the previous behaviour exactly. (The engine's own default
+  count differs between the two, but these SDKs always send one, so a call through
+  them is unaffected.) New `search_full` /
+  `searchFull` keeps every field the answer came with — `search` was merging away
+  the photos and `verify_used`, both of which you were billed for. Also: results arrive
+  best-first — take the order as given. `similarity` is a raw closeness score, and
+  sorting by it makes results worse.
+- **2.2.33** — `get_image` can return a different FORMAT than you uploaded: the
+  service re-encodes on downscale, so a large PNG comes back as WebP. Take the file
+  extension from the response Content-Type, not from what you sent.
+- **2.2.32** — `get_image` returns the picture the SERVICE holds, not your original.
+  An image whose long edge is over 1568px is downscaled on the way in, and that
+  smaller picture is what is stored and handed back. Keep your own copy if you need
+  the full file.
+- **2.2.31** — images, by-speaker, lineage and revisions are SDK methods in all three
+  clients; `search` and `recall` take `verify`, `max_images` and recall's `limit` /
+  `context_limit`.
 - **2.2.30** — documentation only: this changelog, which had not been updated
   in the shipped package since 2.2.10.
 - **2.2.29** — a store id that was PASSED but unusable no longer becomes the

package/dist/wontopos.d.ts

@@ -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
@@ -39,6 +42,8 @@
  */
 /** Test hook — the warn-once set is process-global by design. */
 export declare function _resetStoreIdWarnings(): void;
+export declare const SEARCH_LIMIT_MIN = 5;
+export declare const SEARCH_LIMIT_MAX = 20;
 /** Quota from a response's `X-RateLimit-*` headers, or `null` if absent. */
 export interface RateLimit {
     limit: number | null;
@@ -104,7 +109,7 @@ export interface Memory {
      *  re-sorting by `similarity` overrides the ranking and makes results worse. Take the
      *  list in the order given. There is no `score` field. */
     similarity?: number;
-    /** Learned importance weight of the memory. */
+    /** Importance weight the service assigns to the memory. */
     importance?: number;
     /** Month bucket the memory belongs to (e.g. "2026-07"). Omitted when temporal fields are stripped. */
     time_bucket?: string;
@@ -128,11 +133,11 @@ export interface StoreResult {
     /**
      * Present when `status` is `"duplicate"`: the id of the memory this write collided with.
      *
-     * The match is by MEANING, not by exact text — a genuinely new fact that only varies a
-     * detail of one already stored ("allergic to shellfish" next to "allergic to peanuts")
-     * lands here too. So a duplicate is not always a harmless no-op: read this id, and
-     * either merge the two into one sentence or `update()` the existing memory. Without it
-     * a dropped write gave the caller nothing to act on.
+     * A genuinely new fact that only varies a detail of one already stored ("no meetings
+     * before 10am" next to "no meetings on Fridays") can land here too, so a duplicate is
+     * not always a harmless no-op: read this id, and either store one sentence that states
+     * both or `update()` the existing memory with the combined statement. Without it a
+     * dropped write gave the caller nothing to act on.
      */
     duplicate_of?: string;
     /** Present when the store was a duplicate and something (e.g. a speaker tag) was dropped. */
@@ -153,9 +158,9 @@ export interface StatusResult {
  *
  * What the service keeps is NOT your original. An image whose long edge is over
  * 1568px is downscaled to 1568 before anything else happens, and that smaller
- * picture is what gets embedded, stored, and handed back by `getImage`. Nothing in
- * the retrieval path ever looks above 1568 — the embedder and the reader both
- * shrink to it — so the extra pixels would be bytes nobody reads. This is a memory
+ * picture is what gets stored, and handed back by `getImage`. Nothing on our side
+ * ever uses more than 1568, so the extra pixels would be bytes nobody reads. This
+ * is a memory
  * service, not a photo host: the picture it holds has the resolution of a memory.
  *
  * It can also come back in a different FORMAT. Downscaling means re-encoding, and
@@ -302,14 +307,15 @@ export interface UpdateResult {
 /** `searchFull` → everything one search answered with, not just the merged memories.
  *
  *  `search` returns the memories and nothing else, which is the right answer for
- *  almost every call. Two options make it the wrong one: `max_images` asks for a lane
- *  that is delivered SEPARATELY (Tablet 2 splits photo results from text), and
- *  `verify` is reported on by `verify_used`. Merging away both means paying for a
+ *  almost every call. Two options make it the wrong one: `max_images` asks for
+ *  photos, which arrive in their own field, and `verify` is reported on by
+ *  `verify_used`. Merging away both means paying for a
  *  search you shaped and never seeing what came of it. */
 export interface SearchResult {
-    /** The main lane — what others said / general memories. */
+    /** What others said, and general memories. */
     memories: Memory[];
-    /** The assistant's own words (speaker "me"); `[]` on a model without a self lane. */
+    /** The assistant's own words (speaker "me"); `[]` on a model that does not keep
+     *  them apart. */
     self_memories: Memory[];
     /** Image memories, when `max_images` asked for any; `[]` otherwise. */
     images: Memory[];
@@ -355,7 +361,7 @@ export interface StatsResult {
     short_term_turns?: number;
     [key: string]: unknown;
 }
-/** `listMemories` → one page of a store's raw memories (original text + metadata, no vector). */
+/** `listMemories` → one page of a store's raw memories (the text you stored, and its metadata). */
 export interface MemoryPage {
     memories: Memory[];
     count: number;
@@ -363,9 +369,9 @@ export interface MemoryPage {
     next_cursor: string | null;
     [key: string]: unknown;
 }
-/** `searchSelf` result: the main lane plus the assistant's own words, split. */
+/** `searchSelf` result: general memories and the assistant's own, kept apart. */
 export interface SelfSearchResult {
-    /** Main lane — what others said / general memories. */
+    /** What others said, and general memories. */
     memories: Memory[];
     /** The assistant's own words (stored with speaker "me"); `[]` on non-self models. */
     self_memories: Memory[];
@@ -428,10 +434,11 @@ export interface SpeakersList {
     [key: string]: unknown;
 }
 /**
- * Narrow a search to part of a store — applied BEFORE ranking, so the results are
- * the best matches *within* the filter, not a filtered top-N.
+ * Narrow a search to part of a store. The filter chooses what is searched, not what
+ * is kept afterwards — so a narrow filter still returns your full `limit` when that
+ * many matches sit inside it.
  *
- * Retrieval itself stays purely semantic (no keyword matching), so these behave
+ * Retrieval behaves the same in every language, so these behave
  * identically in every language. Unlisted keys are dropped by the API rather than
  * rejected, so a typo silently widens the search — spell them exactly.
  */
@@ -465,7 +472,7 @@ export interface SearchOptions {
     /**
      * Re-ask passes, 0–3. After the first retrieval the service asks the engine again up
      * to this many times, each time telling it what was already returned so it skips
-     * those and reaches further back. Retrieval stays purely semantic — no LLM at any
+     * those and reaches further back. No LLM runs at any
      * value. Stops early when a pass finds nothing new; `verify_used` in the response
      * says how many actually ran.
      *
@@ -495,8 +502,11 @@ export interface SearchOptions {
  * `idempotencyKey` makes repeating THIS EXACT write safe: the API replays the first
  * response instead of storing again, for 10 minutes, and answers 422 if the same key
  * arrives with a different body. Use it when a retry is your own (a job that died and
- * was re-run, a queue that redelivers) — the SDK never retries writes by itself,
- * because without a key it cannot know whether the first attempt landed.
+ * was re-run, a queue that redelivers). The SDK retries a write on exactly one
+ * status: 429, which the service answers before it processes anything, so nothing
+ * was stored. It never retries a write on 502 / 503 or a dropped body, where the
+ * request may already have been stored and billed — without a key it cannot know
+ * whether that first attempt landed.
  *
  * The key must be UNIQUE PER LOGICAL WRITE — derive it from the thing being stored
  * (`` `import:${row.id}` ``), never a constant, or the second write replays the first
@@ -610,36 +620,36 @@ export declare class Client {
     store(content: string, userId?: string, metadata?: Record<string, unknown>, opts?: WriteOptions): Promise<StoreResult>;
     /** Store a conversation turn (user + assistant). Payload first, userId last — same shape as add/search. */
     addTurn(userMsg: string, assistantMsg: string, userId?: string, opts?: WriteOptions): Promise<StatusResult>;
-    /** 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: string, userId?: string, category?: string, timestamp?: string, opts?: WriteOptions): Promise<StatusResult>;
     /** Supersede an old memory with new content. Payload first, userId last — same shape as add/search. */
     update(oldMemoryId: string, newContent: string, userId?: string, opts?: WriteOptions): Promise<UpdateResult>;
-    /** Semantic search over a store's memories. Returns memories, 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. */
+    /** Search a store's memories. Returns them most relevant first.
+     *
+     *  `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. */
     search(query: string, userId?: string, limit?: number, opts?: SearchOptions): Promise<Memory[]>;
-    /** 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. */
     searchSelf(query: string, userId?: string, limit?: number, opts?: SearchOptions): Promise<SelfSearchResult>;
     /**
-     * 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
@@ -661,11 +671,13 @@ export declare class Client {
          * did not ask for.
          */
         limit?: number;
-        /** Chunks of surrounding context attached around the best match, 0–20. Default 10;
+        /** How much surrounding context is attached around the best match, 0–20. Default 10;
          *  0 attaches none. Same model floor as `limit`. */
         context_limit?: number;
     }): Promise<RecallResult>;
-    /** 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: string, query: string, userId?: string, opts?: {
         form?: string;
@@ -675,13 +687,14 @@ export declare class Client {
     history(userId?: string): Promise<HistoryTurn[]>;
     /** Memory counts for a store: { total_memories, short_term_turns }. */
     stats(userId?: string): Promise<StatsResult>;
-    /** 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: string | undefined, memoryId: string): Promise<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;
@@ -697,14 +710,14 @@ export declare class Client {
         cursor?: string;
     }): Promise<MemoryPage>;
     /** 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);
      */
     iterMemories(userId?: string, opts?: {
         pageSize?: number;
     }): AsyncGenerator<Memory>;
-    /** 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). */
     exportMemories(userId?: string): Promise<Memory[]>;
     /**
      * Fetch the bytes of an image memory — the picture the SERVICE holds.
@@ -712,8 +725,8 @@ export declare 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
@@ -831,9 +844,9 @@ export declare 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: string, userId?: string, opts?: {
         limit?: number;
@@ -875,7 +888,8 @@ export declare class Client {
     listSpeakers(userId?: string): Promise<SpeakersList>;
     /** Unregister a person. Their memories stay; the name tag goes. */
     removeSpeaker(speaker: string, userId?: string): Promise<SpeakerOpResult>;
-    /** 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: string | undefined, memoryId: string): Promise<StatusResult>;
     /** Delete ALL memories for a store (GDPR erase). `userId` is required on purpose -
      * this is destructive, so it never falls back to the default store. */

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.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). */
@@ -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]);
@@ -139,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".
@@ -241,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)
@@ -263,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;
@@ -403,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
@@ -448,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
@@ -571,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)
@@ -585,40 +629,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);
+        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 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 +672,9 @@ export class Client {
      */
     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 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,
@@ -647,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));
@@ -661,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.
@@ -673,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;
@@ -692,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);
      */
@@ -707,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))
@@ -726,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
@@ -800,17 +852,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 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 -----
     /**
@@ -890,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() === "") {
@@ -975,14 +1034,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.
@@ -1025,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._:-]`);
@@ -1118,8 +1223,18 @@ export class Client {
         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;

package/package.json

@@ -1,16 +1,13 @@
 {
   "name": "wontopos",
-  "version": "2.2.34",
-  "description": "Wontopos \u2014 long-term memory for AI agents. Pure semantic retrieval, identical recall in every language, ~100\u00d7 lower LLM bill.",
-  "repository": "github:wontopos/wontopos-typescript",
+  "version": "2.2.35",
+  "description": "Wontopos — long-term memory for AI agents. Identical recall in every language, ~100× lower LLM bill.",
   "keywords": [
     "memory",
     "ai",
     "agent",
     "llm",
-    "vector",
-    "embedding",
-    "semantic",
+    "multilingual",
     "rag",
     "context"
   ],
@@ -39,7 +36,7 @@
   "scripts": {
     "build": "tsc",
     "test": "npm run build && node --test tests/client.test.mjs",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build && node scripts/pre-publish.mjs"
   },
   "devDependencies": {
     "typescript": "^5.4.0"