wontopos 2.2.32 → 2.2.34

package/README.md

@@ -4,10 +4,13 @@
 npm install wontopos
 ```
 
+Get an API key in the [console](https://wontopos.com). Keys look like `wos-live-...`;
+the client also reads `WONTOPOS_API_KEY` from the environment.
+
 ```ts
 import { Client } from "wontopos";
 
-const mem = new Client({ apiKey: "wos-..." });
+const mem = new Client({ apiKey: "wos-live-..." });
 
 // Each end-user / agent / topic gets its own store — create it once.
 // (A `default` store already exists, so you can skip this and omit the id.)
@@ -20,15 +23,15 @@ const ctx = await mem.recall("what does alice drink?", "alice");
 
 ## Why
 
-- **Pure semantic retrieval** — no keyword/BM25. Identical recall in every language (한국어 · 日本語 · 中文 · English).
+- **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.
 - **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` · `recall` · `history` · `stats` · `get` · `listMemories` · `delete` · `deleteAll`
+`add` · `addTurn` · `addBulk` · `update` · `search` · `searchFull` · `recall` · `history` · `stats` · `get` · `listMemories` · `delete` · `deleteAll`
 
-All methods take `{ userId }` — it names the **store**: one isolated memory space per end-user, agent, or topic, then per account. WHO said each memory inside a store is the `speaker` tag below — storing the assistant's own words never needs a separate id.
+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.
 
 ## Who said it (speakers)
 
@@ -87,6 +90,9 @@ egress proxy this SDK could not connect at all — while the Python and Rust SDK
 through, because `requests` and `reqwest` both read those variables. Pass a
 proxy-aware `fetch` and the three behave the same:
 
+This one needs `npm i undici` — Node's global `fetch` is built on undici, but the
+package itself is not installed for you.
+
 ```ts
 import { ProxyAgent } from "undici";
 
@@ -126,10 +132,17 @@ update. `search` options are typed too (`SearchOptions`: `cache_control`,
 `speaker`, plus pass-through).
 
 ```ts
+import { type Memory } from "wontopos";
+
 const hits: Memory[] = await mem.search("what did Bob say?", "alice", 10, { speaker: "Bob" });
 console.log(hits[0].speaker, hits[0].time_bucket);   // typed: string | undefined
 ```
 
+`hits` arrives best-first — take it in the order given. `similarity` is a raw
+closeness score, not the ranking key: what produces the order is internal and is
+not returned, so sorting by `similarity` overrides the ranking and makes results
+worse. There is no `score` field.
+
 ## Errors
 
 Any non-2xx response throws `WosError` with `status`, `message`, and — when the
@@ -162,8 +175,7 @@ const mem = new Client({ apiKey: "...", baseUrl: "https://wos.your-host.com" });
 
 ## Reporting a bug
 
-Found something wrong, or something that looks unsafe? Tell us — one person reads
-every report.
+Found something wrong, or something that looks unsafe? Tell us — every report gets read.
 
 - Bugs: <https://wontopos.com/contact?topic=bug>
 - Security: <https://wontopos.com/contact?topic=security> (also published at

package/dist/wontopos.d.ts

@@ -84,8 +84,8 @@ export declare 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 declare class ServerError extends WosError {
 }
@@ -99,7 +99,10 @@ export interface Memory {
     content?: string;
     /** Cognitive category, e.g. "general". */
     category?: string;
-    /** Semantic relevance to the query — higher is closer. This IS the relevance score; there is no `score` field. */
+    /** Raw closeness to the query — higher is closer. NOT the ranking key: results already
+     *  arrive best-first, and what produces that order is internal and not returned, so
+     *  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?: number;
@@ -155,6 +158,13 @@ export interface StatusResult {
  * shrink to it — 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
+ * we write lossless formats as WebP — send a PNG or a GIF over 1568px and `getImage`
+ * hands back `image/webp`; JPEG stays JPEG. So do not name the file from the
+ * extension you uploaded: read `contentType`. Nothing is re-encoded when the image
+ * already fits within 1568px, and a re-encode that would make the file BIGGER is
+ * thrown away and your bytes kept as they were.
+ *
  * Keep your own copy if you need the full-resolution file. Either archive it
  * yourself, or put its URL in `reference` — we store that string and never open it.
  *
@@ -180,7 +190,8 @@ export interface ImageBytes {
      * The image as stored. Write it to a file, or wrap it in a Blob to show it.
      *
      * This is the service's copy, not necessarily your upload: anything over 1568px
-     * on its long edge was downscaled on the way in (see `ImageInput`).
+     * on its long edge was downscaled on the way in, and re-encoded to WebP unless it
+     * was a JPEG (see `ImageInput`). Take the file extension from `contentType`.
      */
     bytes: Uint8Array;
     /** Sniffed from the BYTES, not from whatever the upload was named — e.g. `image/jpeg`. */
@@ -223,7 +234,7 @@ export interface RevisionsResult {
     revised?: number;
     /** Memories nothing has touched since they were written. Always `total - revised`. */
     unrevised?: number;
-    /** Every memory in the store. Atoms — the fragments search uses internally — are not counted. */
+    /** Every memory in the store. Internal records nobody stored directly are not counted. */
     total?: number;
     /** What `revised` counts, spelled out by the service. */
     counts?: string;
@@ -272,7 +283,7 @@ export interface LineageResult {
 export interface SpeakerPage {
     speaker?: string;
     memories: Memory[];
-    /** Sentence-level fragments behind these memories — what a delete would actually remove. */
+    /** How many underlying records a delete would actually remove, beyond what was returned. */
     chunks?: number;
     points_to_delete?: number;
     returned?: number;
@@ -288,6 +299,25 @@ export interface UpdateResult {
     status?: string;
     [key: string]: unknown;
 }
+/** `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
+ *  search you shaped and never seeing what came of it. */
+export interface SearchResult {
+    /** The main lane — what others said / general memories. */
+    memories: Memory[];
+    /** The assistant's own words (speaker "me"); `[]` on a model without a self lane. */
+    self_memories: Memory[];
+    /** Image memories, when `max_images` asked for any; `[]` otherwise. */
+    images: Memory[];
+    /** Re-ask passes actually performed. Present only when `verify` was sent; lower
+     *  than you asked for means the store had nothing further to add. */
+    verify_used?: number;
+    [key: string]: unknown;
+}
 export interface RecallResult {
     short_term: {
         turns: unknown[];
@@ -444,7 +474,7 @@ export interface SearchOptions {
      * that need several distinct memories from far apart in the history; it does little
      * on a single-fact lookup.
      *
-     * ⚠️Requires a re-ask-capable model. Older ones REFUSE the call (403) rather than
+     * Requires a re-ask-capable model. Older ones REFUSE the call (403) rather than
      * quietly charging you for passes that never happened.
      */
     verify?: number;
@@ -453,7 +483,7 @@ export interface SearchOptions {
      * Out of range is refused, not clamped — silently cutting 5 to 1 would leave you
      * believing you got five.
      *
-     * ⚠️Requires an image-capable model, and is refused (403) on one without it rather
+     * Requires an image-capable model, and is refused (403) on one without it rather
      * than answering with no images.
      */
     max_images?: number;
@@ -570,8 +600,7 @@ export declare class Client {
     withRetries(maxRetries: number): Client;
     /** 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
@@ -602,6 +631,21 @@ export declare class Client {
      * 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). */
     searchSelf(query: string, userId?: string, limit?: number, opts?: SearchOptions): Promise<SelfSearchResult>;
+    /**
+     * Search, and keep every lane the answer came in.
+     *
+     * 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.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.
+     */
+    searchFull(query: string, userId?: string, limit?: number, opts?: SearchOptions): Promise<SearchResult>;
     /** 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. */
@@ -612,7 +656,7 @@ export declare class Client {
          * Long-term memories to recall, 5–20. Default 10. Out of range is refused, not
          * clamped — asking for 20 and silently getting 10 reads as "that is all there is".
          *
-         * ⚠️Needs a limit-aware model. An older one recalls a fixed ten no matter what you
+         * Needs a limit-aware model. An older one recalls a fixed ten no matter what you
          * send, so the API refuses the call (403) rather than answering with a number you
          * did not ask for.
          */
@@ -665,18 +709,24 @@ export declare class Client {
     /**
      * Fetch the bytes of an image memory — the picture the SERVICE holds.
      *
-     * Not necessarily your upload: an image whose long edge was over 1568px was
-     * downscaled to 1568 on the way in, and that 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. Keep your own copy for the full-resolution
-     * file. The type is sniffed from the bytes themselves rather
-     * than from whatever the file was called. Rejects with `NotFoundError` when this
-     * memory has no image, or when the service was not configured to keep originals —
-     * it says "no" instead of handing back something empty, so "a memory with no image"
-     * never looks the same as "an image we lost".
+     * 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.
+     * Keep your own copy for the full-resolution file.
+     *
+     * The type is sniffed from the bytes themselves rather than from whatever the file
+     * was called, so name the file from `contentType` rather than from what you sent.
+     * When the format changed, the response also carries `x-wos-image-converted-from`
+     * naming what you uploaded. Rejects with `NotFoundError` when this memory has no
+     * image, or when the service keeps no image bytes at all — it says "no" instead of
+     * handing back something empty, so "a memory with no image" never looks the same as
+     * "an image we lost".
      *
      *     const { bytes, contentType } = await mem.getImage(undefined, id);
-     *     await fs.writeFile("image.jpg", bytes);
+     *     const ext = contentType.split("/")[1];   // "webp" for a downscaled PNG
+     *     await fs.writeFile(`image.${ext}`, bytes);
      */
     getImage(userId: string | undefined, memoryId: string): Promise<ImageBytes>;
     /**
@@ -721,10 +771,10 @@ export declare 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.
@@ -745,10 +795,10 @@ export declare 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.
@@ -799,10 +849,9 @@ export declare 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.
      *
@@ -856,10 +905,9 @@ export declare class Client {
     private readCapped;
     /** 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. */
     private readCappedBytes;
     private request;
 }

package/dist/wontopos.js

@@ -37,7 +37,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.32";
+const VERSION = "2.2.34";
 /** 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 +55,14 @@ 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 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")`. */
+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 +103,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. */
@@ -151,16 +159,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.");
@@ -309,8 +316,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 {
 }
@@ -545,8 +552,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
@@ -604,6 +610,32 @@ export class Client {
         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.
+     *
+     * 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.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);
+        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
+        // 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. */
@@ -691,18 +723,24 @@ export class Client {
     /**
      * Fetch the bytes of an image memory — the picture the SERVICE holds.
      *
-     * Not necessarily your upload: an image whose long edge was over 1568px was
-     * downscaled to 1568 on the way in, and that 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. Keep your own copy for the full-resolution
-     * file. The type is sniffed from the bytes themselves rather
-     * than from whatever the file was called. Rejects with `NotFoundError` when this
-     * memory has no image, or when the service was not configured to keep originals —
-     * it says "no" instead of handing back something empty, so "a memory with no image"
-     * never looks the same as "an image we lost".
+     * 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.
+     * Keep your own copy for the full-resolution file.
+     *
+     * The type is sniffed from the bytes themselves rather than from whatever the file
+     * was called, so name the file from `contentType` rather than from what you sent.
+     * When the format changed, the response also carries `x-wos-image-converted-from`
+     * naming what you uploaded. Rejects with `NotFoundError` when this memory has no
+     * image, or when the service keeps no image bytes at all — it says "no" instead of
+     * handing back something empty, so "a memory with no image" never looks the same as
+     * "an image we lost".
      *
      *     const { bytes, contentType } = await mem.getImage(undefined, id);
-     *     await fs.writeFile("image.jpg", bytes);
+     *     const ext = contentType.split("/")[1];   // "webp" for a downscaled PNG
+     *     await fs.writeFile(`image.${ext}`, bytes);
      */
     getImage(userId, memoryId) {
         if (!memoryId || typeof memoryId !== "string") {
@@ -753,12 +791,23 @@ 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;
             if (!p.has_more || !p.next_before)
                 break;
+            // 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;
+            seen.add(key);
             before = p.next_before;
             skipIds = Array.isArray(p.next_skip_ids) ? p.next_skip_ids : undefined;
         }
@@ -774,10 +823,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.
@@ -798,10 +847,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.
@@ -875,10 +924,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.
      *
@@ -909,9 +957,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
@@ -939,11 +987,10 @@ export class Client {
         // 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.");
         }
@@ -1063,10 +1110,9 @@ 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) {
@@ -1203,10 +1249,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 {};
@@ -1228,10 +1273,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;
             }

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "wontopos",
-  "version": "2.2.32",
-  "description": "Wontopos — long-term memory for AI agents. Pure semantic retrieval, identical recall in every language, ~100× lower LLM bill.",
+  "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",
   "keywords": [
     "memory",
     "ai",
@@ -37,7 +38,7 @@
   },
   "scripts": {
     "build": "tsc",
-    "test": "npm run build && node --test test/client.test.mjs",
+    "test": "npm run build && node --test tests/client.test.mjs",
     "prepublishOnly": "npm run build"
   },
   "devDependencies": {