wontopos 2.2.45 → 2.2.46

package/README.md

@@ -24,8 +24,8 @@ const ctx = await mem.recall("what does alice drink?", "alice");
 ## Why
 
 - **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 regardless of how much you've stored (~1,000 tokens on `tablet-2`, the default engine).
+- **No LLM reads your memories** — no language model reads your stored memories, on any model. You pay retrieval, not generation.
+- **Bounded retrieval** — `recall()` returns the recent turns, at most `limit` long-term memories (default 10, up to 20) and at most `context_limit` rows of the surrounding conversation (default 10, up to 20), however much you've stored.
 
 ## Methods
 
@@ -38,7 +38,7 @@ writes or searches puts the payload first and the store second — `mem.add("...
 Most of them let you leave it out for the client's default store. Five take it
 positionally and cannot — `get`, `getImage`, `delete`, `lineage` and `forgetImage` want
 an explicit `undefined` there, because a second required argument follows it. Python
-omits it in all five; this is the one place the three clients differ in shape rather than meaning.
+omits it in all five, and Rust takes it positionally (`None` for the default store, where there is one).
 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)
@@ -56,19 +56,22 @@ await mem.search("what did Bob say about deadlines?", "alice", 10, { speaker: "B
 ```
 
 `listSpeakers()` shows the registered people with per-person memory counts;
-`removeSpeaker()` unregisters (memories stay, the tag goes). A store registers
+`removeSpeaker()` unregisters (memories stay; the tag goes, except on `tablet-2`, which keeps it on memories already stored). A store registers
 up to 50 people to start (a limit we plan to raise); `"me"` never needs
 registration and never counts against it.
 
 ## Recall caching
 
-Opt in per search and repeated or extended queries reuse the previous result
-at 10% of the normal rate (Tablet and Scroll models).
+Opt in per search and a repeated query reuses the previous result at 10% of the
+normal rate; an extended one reuses part of it (Tablet and Scroll models).
 
 It is not free to turn on: the FIRST call writes the cache and bills the query
-tokens at 2x for a `5m` TTL, 3x for `1h`. Only hits inside the TTL bill at 0.1x.
-So it pays for a query you repeat or extend, and costs more for one you issue
-once — do not switch it on globally. Any write to the store invalidates its cache
+tokens at 2x for a `5m` TTL, 3x for `1h`. The same query again inside the TTL bills
+its query and its results at 0.1x. A query that extends the cached one (its text plus
+more) bills the cached part at 0.1x, the new part at the write rate and its results
+at the normal rate. A store keeps one cached query per model and set of options, so a
+different query replaces it. So it pays for a query you repeat or extend, and costs
+more for one you issue once — do not switch it on globally. Any write to the store invalidates its cache
 at once, so a hit can never predate a new memory.
 
 ```ts
@@ -82,11 +85,11 @@ Built in, no configuration needed:
 
 - **Automatic retries** — 429 and a 409 for a write already in flight always, and 408 /
   502 / 503 / 504 or a connection error only when a retry cannot double-process a write.
-  The writes and the searches are POSTs, and any of those four may have been returned
-  *after* the write already landed, so those get 429, that 409 and connect-level
-  failures only. The GET and DELETE calls — `ping`, `listStores`, `listSpeakers`,
-  `listModels`, `listEngrams`, `usage`, `deleteStore`, `removeSpeaker`, `forgetImage` —
-  retry all four. Twice, with exponential backoff + jitter, honoring the server's
+  A write may already have landed when any of those four comes back, so a POST write gets
+  429, that 409 and connect-level failures only. The calls that are safe to send again
+  retry all four: the reads sent as POST (`search`, `recall`, `get`, `listMemories`,
+  `stats`, ...) and the GET and DELETE calls (`ping`, `listStores`, `listSpeakers`,
+  `listModels`, `listEngrams`, `usage`, `deleteStore`, `removeSpeaker`, `forgetImage`). Twice, with exponential backoff + jitter, honoring the server's
   `Retry-After` up to 30s. Tune with `new Client({ maxRetries })`; `0` disables.
 - **Redirects refused** — the API key never follows a 3xx to another host.
 - **Timeouts** — 30s per attempt by default (`timeoutMs`), and a total budget for
@@ -147,7 +150,8 @@ Built in, none of it configurable off:
 Every method returns a documented shape — `StoreResult`, `UpdateResult`,
 `RecallResult`, `EngramResult`, `StatsResult`, `SpeakersList`, `Memory[]`, ... —
 each with an index signature, so new server fields flow through without an SDK
-update. `search` options are typed too (`SearchOptions`: `cache_control`,
+update. `searchSelf`'s result and `getImage`'s bytes are built by the client and
+carry only their own fields. `search` options are typed too (`SearchOptions`: `cache_control`,
 `speaker`, plus `extra` for pass-through).
 
 ```ts
@@ -157,7 +161,8 @@ const hits: Memory[] = await mem.search("what did Bob say?", "alice", 10, { spea
 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
+`hits` holds memories best-first, then the assistant's own words and image memories in
+their own order. 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.

package/dist/cjs/wontopos.d.cts

@@ -14,7 +14,7 @@
  * (`createStore`) or calls return 404. Every account starts with a `default` store,
  * so with no `userId` anywhere the zero-setup path just works.
  *
- * The API key picks *which memory* (your account); `model` picks *which engine*
+ * The API key picks *which memory* (your workspace); `model` picks *which engine*
  * 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
@@ -22,14 +22,14 @@
  * `mem.withModel("tablet-1").recall(...)`.
  *
  * 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.
+ * memory stored in one language is found by a question asked in another. No language
+ * model reads your stored memories.
  *
  * Reliability: every call retries transient failures with exponential backoff +
  * jitter, honoring `Retry-After` up to 30s — 429 and a 409 that says another write
  * to the store was in flight, always; 408/502/503/504 and connection errors only when
- * a retry can never double-process a write (idempotent calls, or a failure at connect
- * time). Tune with `maxRetries` (0 disables) and `timeoutMs`, or per call site via
+ * a retry can never double-process a write (reads, the DELETE calls, or a failure at
+ * connect time). Tune with `maxRetries` (0 disables) and `timeoutMs`, or per call site via
  * the `withTimeout()` / `withRetries()` clones.
  *
  * Debugging: set `WONTOPOS_LOG=debug` to log method/path/status/timing/retries
@@ -89,7 +89,9 @@ export declare class BadRequestError extends WosError {
 /** 401 — the API key is missing, wrong, or revoked. */
 export declare class AuthenticationError extends WosError {
 }
-/** 402 — no card on file or the balance is depleted. Top up to continue. */
+/** 402 — no card on file, the balance is depleted, or the month's spend cap for the
+ *  account's tier is reached (`details.reason` is `tier_cap_reached`). Top up to
+ *  continue; a top-up also raises the tier. */
 export declare class PaymentRequiredError extends WosError {
 }
 /** 403 — the key/model isn't allowed to do this. */
@@ -194,8 +196,9 @@ export interface StatusResult {
 /**
  * An image attached to a memory, passed to `add`/`store` via `opts.image`.
  *
- * Both edges must be 700px or more; a smaller image is refused (400). A request
- * body is capped at 10MB.
+ * Both edges must be 700px or more and the long edge at most 2500px, and the image
+ * file at most 7MB; anything else is refused (400) with the reason. A request body is
+ * capped at 10MB.
  *
  * 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
@@ -241,8 +244,9 @@ 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, and re-encoded to WebP unless it
-     * was a JPEG (see `ImageInput`). Take the file extension from `contentType`.
+     * on its long edge (2500 at most) 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`. */
@@ -317,7 +321,8 @@ export interface LineageStep {
     is_current?: boolean;
     [key: string]: unknown;
 }
-/** `lineage` → the full chain of edits behind one memory, oldest first. */
+/** `lineage` → the edits that followed one memory, from the id passed forward to the
+ *  version in force, oldest first. */
 export interface LineageResult {
     memory_id?: string;
     chain: LineageStep[];
@@ -360,8 +365,8 @@ export interface SearchResult {
     /** Image memories the answer carried (one by default on an image-capable model,
      *  up to `max_images`); `[]` when there were none. */
     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. */
+    /** Re-ask passes that added memories. Present only when `verify` above 0 was sent;
+     *  lower than you asked for means a pass found nothing new, or could not run. */
     verify_used?: number;
     [key: string]: unknown;
 }
@@ -414,7 +419,7 @@ export interface UsageResult {
         output_tokens?: number;
         since?: string;
     };
-    /** The workspace this key belongs to, over the window. */
+    /** The workspace this key belongs to, over the window: every key in it, not only this one. */
     workspace?: {
         workspace_id?: string | null;
         requests?: number;
@@ -542,9 +547,8 @@ export interface SpeakersList {
     [key: string]: unknown;
 }
 /**
- * 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.
+ * Narrow a search to part of a store. A narrow filter can return fewer than `limit`
+ * even when the store holds more inside it.
  *
  * Retrieval behaves the same in every language, so these behave
  * identically in every language. Unlisted keys are dropped by the API rather than
@@ -565,7 +569,8 @@ export interface SearchFilters {
     time_from?: string;
     time_to?: string;
     /** WHEN THE CONTENT HAPPENED (`metadata.event_date`), not when it was written —
-     *  this is the one you usually want. */
+     *  this is the one you usually want. A memory stored without an `event_date` is
+     *  matched by when it was stored. */
     event_from?: string;
     event_to?: string;
     /** Drop matches the engine scored below this importance (0–1). */
@@ -578,9 +583,11 @@ export declare function _resetFilterWarnings(): void;
  *  could not be told from an option that worked. Put a genuinely new one under
  *  `extra`. */
 export interface SearchOptions {
-    /** Recall caching. A hit inside the TTL bills at 0.1× — but the FIRST call
-     *  writes the cache and bills the query tokens at 2× (`5m`) or 3× (`1h`), so
-     *  this only pays for a query you repeat or extend. Do not enable it globally. */
+    /** Recall caching. The same query again inside the TTL bills at 0.1×; one that
+     *  extends the cached query bills only its cached part at 0.1×, the new part at the
+     *  write rate and its results at the normal rate. The FIRST call writes the cache
+     *  and bills the query tokens at 2× (`5m`) or 3× (`1h`), so this only pays for a
+     *  query you repeat or extend. Do not enable it globally. */
     cache_control?: {
         ttl: "5m" | "1h";
     };
@@ -591,9 +598,9 @@ 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. No LLM runs at any
+     * those and reaches further back. Raising it adds no language model call at any
      * value. Stops early when a pass finds nothing new; `verify_used` in the response
-     * says how many actually ran.
+     * says how many passes added memories.
      *
      * Each pass is another engine call and can add up to `limit` more memories, so it
      * costs more — you are billed for what is delivered. Default 0. Worth it on questions
@@ -859,15 +866,16 @@ export declare class Client {
     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>;
-    /** Search a store's memories. Returns them most relevant first.
+    /** Search a store's memories. They come most relevant first; the assistant's own
+     *  words and image memories, when there are any, follow them in their own order.
      *
      *  `limit` is 5-20, and out of range is refused rather than clamped: asking for 50
      *  and silently receiving 20 reads as "that is all there is". The default is 10.
      *
-     *  `limit` bounds `memories`, not the returned array. The assistant's own words (on
-     *  a model that lists `self_memories` in its capabilities) and image memories (one
-     *  unless `max_images` says otherwise, on a model that lists `images`) come back in
-     *  it as well, so it can hold more than `limit`. They are billed either way. Size a
+     *  `limit` bounds `memories`, not the returned array, and each `verify` pass can add
+     *  up to `limit` more. The assistant's own words (on a model that lists
+     *  `self_memories` in its capabilities) and image memories (one unless `max_images`
+     *  says otherwise, on a model that lists `images`) come back after them in it as well, so it can hold more than `limit`. They are billed either way. Size a
      *  prompt window on the array you get back, not on `limit`. `searchFull()` hands the
      *  fields back apart.
      *
@@ -891,7 +899,7 @@ export declare class Client {
      *     const r = await mem.searchFull("the day we moved", "alice", 10,
      *                                    { max_images: 3, verify: 2 });
      *     r.images.length;   // the photos, apart from the text memories
-     *     r.verify_used;     // how many re-ask passes actually ran (you are billed per pass)
+     *     r.verify_used;     // re-ask passes that added memories (each billed for what it added)
      *
      * Each option needs a model that lists it in its `listModels()` capabilities
      * (`images`, `re_ask`) and is refused (403) on any other rather than accepted and
@@ -928,7 +936,8 @@ export declare class Client {
     }): Promise<EngramResult>;
     /** Recent conversation turns (short-term memory). */
     history(userId?: string): Promise<HistoryTurn[]>;
-    /** Memory counts for a store: { total_memories, short_term_turns }. */
+    /** Memory counts for a store: { total_memories, short_term_turns }. `total_memories`
+     *  can be larger than the number `listMemories` lists. */
     stats(userId?: string): Promise<StatsResult>;
     /**
      * What this key has spent, and what is left — the numbers behind "can I keep going?".
@@ -936,18 +945,17 @@ export declare class Client {
      * Free: it carries no charge and skips the balance gate, because an account at zero
      * still has to be able to find out why. Rate-limited instead.
      *
-     * Scoped to THIS key: its own lifetime spend, its workspace and stores over the
-     * window. It never returns another key's spend. `balance_cents` is account-wide,
-     * because that is what gates the next call whichever key makes it.
+     * `key` is THIS key's own lifetime spend. `workspace` and `stores` cover the window
+     * for the workspace this key belongs to, every key in it included. `balance_cents` is
+     * account-wide, because that is what gates the next call whichever key makes it.
      *
      *     const u = await mem.usage(7);
      *     if (u.balance_cents! < 100) stop();
      */
     usage(days?: number): Promise<UsageResult>;
     /** 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, an id `listMemories` does not return,
-     * or an invalidated memory rejects with `NotFoundError`. Pass `undefined` as
+     * The id is what `add`/`store` or `listMemories` returned. An unknown id or one
+     * from another store rejects with `NotFoundError`. Pass `undefined` as
      * `userId` for the default store — it is positional here. */
     get(userId: string | undefined, memoryId: string): Promise<Memory>;
     /** List a store's stored memories — the text you stored, plus its metadata.
@@ -993,9 +1001,10 @@ export declare class Client {
      * Fetch the bytes of an image memory — the picture the SERVICE holds.
      *
      * 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 is stored and comes back here. Nothing on our side ever
+     * over 1568px (2500 at most) 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;
+     * kept as sent when the re-encode came out bigger — and that 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.
      *
@@ -1100,11 +1109,13 @@ export declare class Client {
         skipIds?: string[];
     }): Promise<RevisionsResult>;
     /**
-     * The full chain of edits behind one memory, oldest first.
+     * The edits that followed one memory: from the id you pass forward to the version in
+     * force, oldest first.
      *
-     * `is_current` marks the version in force. Use it to answer "what did this used to
-     * say, and when did it change" — `revisions()` tells you HOW MUCH a store moved,
-     * this tells you what happened to one fact.
+     * `is_current` marks the version in force. The chain runs forward only, so to answer
+     * "what did this used to say, and when did it change" pass the first version's id;
+     * the current version's id (what `search` returns) comes back alone. `revisions()`
+     * tells you HOW MUCH a store moved, this tells you what happened to one fact.
      */
     lineage(userId: string | undefined, memoryId: string): Promise<LineageResult>;
     /**
@@ -1126,8 +1137,7 @@ export declare class Client {
      * `AuthenticationError` (bad key), `PaymentRequiredError` (valid key but no card /
      * depleted balance), or `APIConnectionError` (unreachable). Makes one metered request. */
     ping(): Promise<boolean>;
-    /** Available models: `[{ id, name, available, memory, capabilities, retires_at? }, ...]`.
-     *  Needs no API key. */
+    /** Available models: `[{ id, name, available, memory, capabilities, retires_at? }, ...]`. */
     listModels(): Promise<ModelInfo[]>;
     /**
      * The engrams (and delivery forms) the selected model can actually run.
@@ -1160,7 +1170,9 @@ export declare class Client {
     addSpeaker(speaker: string, userId?: string): Promise<SpeakerOpResult>;
     /** The store's registered people, each with its memory count. */
     listSpeakers(userId?: string): Promise<SpeakersList>;
-    /** Unregister a person. Their memories stay; the name tag goes. Retried like
+    /** Unregister a person. Their memories stay, and the name can no longer tag a new
+     *  memory or filter a search. The tag goes from stored memories too, except on
+     *  `tablet-2`, which keeps it on memories already stored with it. Retried like
      *  `deleteStore`, with the same note on a 404 after an ambiguous failure. */
     removeSpeaker(speaker: string, userId?: string): Promise<SpeakerOpResult>;
     /** Delete a single memory by id. Pass `undefined` as `userId` for the default
@@ -1210,12 +1222,12 @@ export declare class Client {
      *
      * Retried: 429, and a 409 whose error carries `retry_after_ms` (another write to the
      * store was in flight; nothing was stored), on every method; 408/502/503/504 and
-     * dropped connections on idempotent methods; connect failures on every method. A
-     * retry whose wait is over the cap, or does not fit the deadline, is not made: the
-     * call fails with the error of the response it has. So does a retry the deadline
-     * leaves no time to send, and the retry of an idempotent method or of a POST that
-     * only reads that the deadline cuts short. Any other retry cut short stays a status-0
-     * deadline error: a write may have been applied.
+     * dropped connections on a call that only reads (an idempotent method, or a POST
+     * that only reads); connect failures on every method. A retry whose wait is over the
+     * cap, or does not fit the deadline, is not made: the call fails with the error of
+     * the response it has. So does a retry the deadline leaves no time to send, and the
+     * retry of a call that only reads that the deadline cuts short. Any other retry cut
+     * short stays a status-0 deadline error: a write may have been applied.
      */
     private send;
     /**

package/dist/cjs/wontopos.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.WME = exports.Client = exports.ServerError = exports.RateLimitError = exports.GoneError = exports.ConflictError = exports.NotFoundError = exports.PermissionDeniedError = exports.PaymentRequiredError = exports.AuthenticationError = exports.BadRequestError = exports.APIConnectionError = exports.WosError = exports.CONTEXT_LIMIT_MAX = exports.CONTEXT_LIMIT_MIN = exports.SEARCH_LIMIT_MAX = exports.SEARCH_LIMIT_MIN = void 0;
 exports._resetStoreIdWarnings = _resetStoreIdWarnings;
 exports._resetFilterWarnings = _resetFilterWarnings;
-const VERSION = "2.2.45";
+const VERSION = "2.2.46";
 const RUNTIME = (() => {
     const p = globalThis?.process;
     return p?.version ? ` (node/${p.version}; ${p.platform}-${p.arch})` : "";
@@ -1113,8 +1113,8 @@ class Client {
         }
         const attempts = this.maxRetries + 1;
         const upper = method.toUpperCase();
-        const idempotent = IDEMPOTENT_METHODS.has(upper);
         const logPath = path.split("?")[0];
+        const idempotent = IDEMPOTENT_METHODS.has(upper) || reads || (upper === "POST" && READ_POSTS.has(logPath));
         const deadlineAt = this.deadlineAt();
         const headers = extraHeaders ? { ...this.headers, ...extraHeaders } : this.headers;
         let ambiguous = false;
@@ -1135,7 +1135,7 @@ class Client {
             };
             const cutShort = () => {
                 const why = att.why();
-                if (why === "deadline" && (idempotent || reads || (upper === "POST" && READ_POSTS.has(logPath))) && previous) {
+                if (why === "deadline" && idempotent && previous) {
                     return previous;
                 }
                 return new APIConnectionError(0, this.abortMessage(why));

package/dist/wontopos.d.ts

@@ -14,7 +14,7 @@
  * (`createStore`) or calls return 404. Every account starts with a `default` store,
  * so with no `userId` anywhere the zero-setup path just works.
  *
- * The API key picks *which memory* (your account); `model` picks *which engine*
+ * The API key picks *which memory* (your workspace); `model` picks *which engine*
  * 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
@@ -22,14 +22,14 @@
  * `mem.withModel("tablet-1").recall(...)`.
  *
  * 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.
+ * memory stored in one language is found by a question asked in another. No language
+ * model reads your stored memories.
  *
  * Reliability: every call retries transient failures with exponential backoff +
  * jitter, honoring `Retry-After` up to 30s — 429 and a 409 that says another write
  * to the store was in flight, always; 408/502/503/504 and connection errors only when
- * a retry can never double-process a write (idempotent calls, or a failure at connect
- * time). Tune with `maxRetries` (0 disables) and `timeoutMs`, or per call site via
+ * a retry can never double-process a write (reads, the DELETE calls, or a failure at
+ * connect time). Tune with `maxRetries` (0 disables) and `timeoutMs`, or per call site via
  * the `withTimeout()` / `withRetries()` clones.
  *
  * Debugging: set `WONTOPOS_LOG=debug` to log method/path/status/timing/retries
@@ -89,7 +89,9 @@ export declare class BadRequestError extends WosError {
 /** 401 — the API key is missing, wrong, or revoked. */
 export declare class AuthenticationError extends WosError {
 }
-/** 402 — no card on file or the balance is depleted. Top up to continue. */
+/** 402 — no card on file, the balance is depleted, or the month's spend cap for the
+ *  account's tier is reached (`details.reason` is `tier_cap_reached`). Top up to
+ *  continue; a top-up also raises the tier. */
 export declare class PaymentRequiredError extends WosError {
 }
 /** 403 — the key/model isn't allowed to do this. */
@@ -194,8 +196,9 @@ export interface StatusResult {
 /**
  * An image attached to a memory, passed to `add`/`store` via `opts.image`.
  *
- * Both edges must be 700px or more; a smaller image is refused (400). A request
- * body is capped at 10MB.
+ * Both edges must be 700px or more and the long edge at most 2500px, and the image
+ * file at most 7MB; anything else is refused (400) with the reason. A request body is
+ * capped at 10MB.
  *
  * 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
@@ -241,8 +244,9 @@ 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, and re-encoded to WebP unless it
-     * was a JPEG (see `ImageInput`). Take the file extension from `contentType`.
+     * on its long edge (2500 at most) 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`. */
@@ -317,7 +321,8 @@ export interface LineageStep {
     is_current?: boolean;
     [key: string]: unknown;
 }
-/** `lineage` → the full chain of edits behind one memory, oldest first. */
+/** `lineage` → the edits that followed one memory, from the id passed forward to the
+ *  version in force, oldest first. */
 export interface LineageResult {
     memory_id?: string;
     chain: LineageStep[];
@@ -360,8 +365,8 @@ export interface SearchResult {
     /** Image memories the answer carried (one by default on an image-capable model,
      *  up to `max_images`); `[]` when there were none. */
     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. */
+    /** Re-ask passes that added memories. Present only when `verify` above 0 was sent;
+     *  lower than you asked for means a pass found nothing new, or could not run. */
     verify_used?: number;
     [key: string]: unknown;
 }
@@ -414,7 +419,7 @@ export interface UsageResult {
         output_tokens?: number;
         since?: string;
     };
-    /** The workspace this key belongs to, over the window. */
+    /** The workspace this key belongs to, over the window: every key in it, not only this one. */
     workspace?: {
         workspace_id?: string | null;
         requests?: number;
@@ -542,9 +547,8 @@ export interface SpeakersList {
     [key: string]: unknown;
 }
 /**
- * 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.
+ * Narrow a search to part of a store. A narrow filter can return fewer than `limit`
+ * even when the store holds more inside it.
  *
  * Retrieval behaves the same in every language, so these behave
  * identically in every language. Unlisted keys are dropped by the API rather than
@@ -565,7 +569,8 @@ export interface SearchFilters {
     time_from?: string;
     time_to?: string;
     /** WHEN THE CONTENT HAPPENED (`metadata.event_date`), not when it was written —
-     *  this is the one you usually want. */
+     *  this is the one you usually want. A memory stored without an `event_date` is
+     *  matched by when it was stored. */
     event_from?: string;
     event_to?: string;
     /** Drop matches the engine scored below this importance (0–1). */
@@ -578,9 +583,11 @@ export declare function _resetFilterWarnings(): void;
  *  could not be told from an option that worked. Put a genuinely new one under
  *  `extra`. */
 export interface SearchOptions {
-    /** Recall caching. A hit inside the TTL bills at 0.1× — but the FIRST call
-     *  writes the cache and bills the query tokens at 2× (`5m`) or 3× (`1h`), so
-     *  this only pays for a query you repeat or extend. Do not enable it globally. */
+    /** Recall caching. The same query again inside the TTL bills at 0.1×; one that
+     *  extends the cached query bills only its cached part at 0.1×, the new part at the
+     *  write rate and its results at the normal rate. The FIRST call writes the cache
+     *  and bills the query tokens at 2× (`5m`) or 3× (`1h`), so this only pays for a
+     *  query you repeat or extend. Do not enable it globally. */
     cache_control?: {
         ttl: "5m" | "1h";
     };
@@ -591,9 +598,9 @@ 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. No LLM runs at any
+     * those and reaches further back. Raising it adds no language model call at any
      * value. Stops early when a pass finds nothing new; `verify_used` in the response
-     * says how many actually ran.
+     * says how many passes added memories.
      *
      * Each pass is another engine call and can add up to `limit` more memories, so it
      * costs more — you are billed for what is delivered. Default 0. Worth it on questions
@@ -859,15 +866,16 @@ export declare class Client {
     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>;
-    /** Search a store's memories. Returns them most relevant first.
+    /** Search a store's memories. They come most relevant first; the assistant's own
+     *  words and image memories, when there are any, follow them in their own order.
      *
      *  `limit` is 5-20, and out of range is refused rather than clamped: asking for 50
      *  and silently receiving 20 reads as "that is all there is". The default is 10.
      *
-     *  `limit` bounds `memories`, not the returned array. The assistant's own words (on
-     *  a model that lists `self_memories` in its capabilities) and image memories (one
-     *  unless `max_images` says otherwise, on a model that lists `images`) come back in
-     *  it as well, so it can hold more than `limit`. They are billed either way. Size a
+     *  `limit` bounds `memories`, not the returned array, and each `verify` pass can add
+     *  up to `limit` more. The assistant's own words (on a model that lists
+     *  `self_memories` in its capabilities) and image memories (one unless `max_images`
+     *  says otherwise, on a model that lists `images`) come back after them in it as well, so it can hold more than `limit`. They are billed either way. Size a
      *  prompt window on the array you get back, not on `limit`. `searchFull()` hands the
      *  fields back apart.
      *
@@ -891,7 +899,7 @@ export declare class Client {
      *     const r = await mem.searchFull("the day we moved", "alice", 10,
      *                                    { max_images: 3, verify: 2 });
      *     r.images.length;   // the photos, apart from the text memories
-     *     r.verify_used;     // how many re-ask passes actually ran (you are billed per pass)
+     *     r.verify_used;     // re-ask passes that added memories (each billed for what it added)
      *
      * Each option needs a model that lists it in its `listModels()` capabilities
      * (`images`, `re_ask`) and is refused (403) on any other rather than accepted and
@@ -928,7 +936,8 @@ export declare class Client {
     }): Promise<EngramResult>;
     /** Recent conversation turns (short-term memory). */
     history(userId?: string): Promise<HistoryTurn[]>;
-    /** Memory counts for a store: { total_memories, short_term_turns }. */
+    /** Memory counts for a store: { total_memories, short_term_turns }. `total_memories`
+     *  can be larger than the number `listMemories` lists. */
     stats(userId?: string): Promise<StatsResult>;
     /**
      * What this key has spent, and what is left — the numbers behind "can I keep going?".
@@ -936,18 +945,17 @@ export declare class Client {
      * Free: it carries no charge and skips the balance gate, because an account at zero
      * still has to be able to find out why. Rate-limited instead.
      *
-     * Scoped to THIS key: its own lifetime spend, its workspace and stores over the
-     * window. It never returns another key's spend. `balance_cents` is account-wide,
-     * because that is what gates the next call whichever key makes it.
+     * `key` is THIS key's own lifetime spend. `workspace` and `stores` cover the window
+     * for the workspace this key belongs to, every key in it included. `balance_cents` is
+     * account-wide, because that is what gates the next call whichever key makes it.
      *
      *     const u = await mem.usage(7);
      *     if (u.balance_cents! < 100) stop();
      */
     usage(days?: number): Promise<UsageResult>;
     /** 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, an id `listMemories` does not return,
-     * or an invalidated memory rejects with `NotFoundError`. Pass `undefined` as
+     * The id is what `add`/`store` or `listMemories` returned. An unknown id or one
+     * from another store rejects with `NotFoundError`. Pass `undefined` as
      * `userId` for the default store — it is positional here. */
     get(userId: string | undefined, memoryId: string): Promise<Memory>;
     /** List a store's stored memories — the text you stored, plus its metadata.
@@ -993,9 +1001,10 @@ export declare class Client {
      * Fetch the bytes of an image memory — the picture the SERVICE holds.
      *
      * 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 is stored and comes back here. Nothing on our side ever
+     * over 1568px (2500 at most) 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;
+     * kept as sent when the re-encode came out bigger — and that 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.
      *
@@ -1100,11 +1109,13 @@ export declare class Client {
         skipIds?: string[];
     }): Promise<RevisionsResult>;
     /**
-     * The full chain of edits behind one memory, oldest first.
+     * The edits that followed one memory: from the id you pass forward to the version in
+     * force, oldest first.
      *
-     * `is_current` marks the version in force. Use it to answer "what did this used to
-     * say, and when did it change" — `revisions()` tells you HOW MUCH a store moved,
-     * this tells you what happened to one fact.
+     * `is_current` marks the version in force. The chain runs forward only, so to answer
+     * "what did this used to say, and when did it change" pass the first version's id;
+     * the current version's id (what `search` returns) comes back alone. `revisions()`
+     * tells you HOW MUCH a store moved, this tells you what happened to one fact.
      */
     lineage(userId: string | undefined, memoryId: string): Promise<LineageResult>;
     /**
@@ -1126,8 +1137,7 @@ export declare class Client {
      * `AuthenticationError` (bad key), `PaymentRequiredError` (valid key but no card /
      * depleted balance), or `APIConnectionError` (unreachable). Makes one metered request. */
     ping(): Promise<boolean>;
-    /** Available models: `[{ id, name, available, memory, capabilities, retires_at? }, ...]`.
-     *  Needs no API key. */
+    /** Available models: `[{ id, name, available, memory, capabilities, retires_at? }, ...]`. */
     listModels(): Promise<ModelInfo[]>;
     /**
      * The engrams (and delivery forms) the selected model can actually run.
@@ -1160,7 +1170,9 @@ export declare class Client {
     addSpeaker(speaker: string, userId?: string): Promise<SpeakerOpResult>;
     /** The store's registered people, each with its memory count. */
     listSpeakers(userId?: string): Promise<SpeakersList>;
-    /** Unregister a person. Their memories stay; the name tag goes. Retried like
+    /** Unregister a person. Their memories stay, and the name can no longer tag a new
+     *  memory or filter a search. The tag goes from stored memories too, except on
+     *  `tablet-2`, which keeps it on memories already stored with it. Retried like
      *  `deleteStore`, with the same note on a 404 after an ambiguous failure. */
     removeSpeaker(speaker: string, userId?: string): Promise<SpeakerOpResult>;
     /** Delete a single memory by id. Pass `undefined` as `userId` for the default
@@ -1210,12 +1222,12 @@ export declare class Client {
      *
      * Retried: 429, and a 409 whose error carries `retry_after_ms` (another write to the
      * store was in flight; nothing was stored), on every method; 408/502/503/504 and
-     * dropped connections on idempotent methods; connect failures on every method. A
-     * retry whose wait is over the cap, or does not fit the deadline, is not made: the
-     * call fails with the error of the response it has. So does a retry the deadline
-     * leaves no time to send, and the retry of an idempotent method or of a POST that
-     * only reads that the deadline cuts short. Any other retry cut short stays a status-0
-     * deadline error: a write may have been applied.
+     * dropped connections on a call that only reads (an idempotent method, or a POST
+     * that only reads); connect failures on every method. A retry whose wait is over the
+     * cap, or does not fit the deadline, is not made: the call fails with the error of
+     * the response it has. So does a retry the deadline leaves no time to send, and the
+     * retry of a call that only reads that the deadline cuts short. Any other retry cut
+     * short stays a status-0 deadline error: a write may have been applied.
      */
     private send;
     /**

package/dist/wontopos.js

@@ -1,4 +1,4 @@
-const VERSION = "2.2.45";
+const VERSION = "2.2.46";
 const RUNTIME = (() => {
     const p = globalThis?.process;
     return p?.version ? ` (node/${p.version}; ${p.platform}-${p.arch})` : "";
@@ -1097,8 +1097,8 @@ export class Client {
         }
         const attempts = this.maxRetries + 1;
         const upper = method.toUpperCase();
-        const idempotent = IDEMPOTENT_METHODS.has(upper);
         const logPath = path.split("?")[0];
+        const idempotent = IDEMPOTENT_METHODS.has(upper) || reads || (upper === "POST" && READ_POSTS.has(logPath));
         const deadlineAt = this.deadlineAt();
         const headers = extraHeaders ? { ...this.headers, ...extraHeaders } : this.headers;
         let ambiguous = false;
@@ -1119,7 +1119,7 @@ export class Client {
             };
             const cutShort = () => {
                 const why = att.why();
-                if (why === "deadline" && (idempotent || reads || (upper === "POST" && READ_POSTS.has(logPath))) && previous) {
+                if (why === "deadline" && idempotent && previous) {
                     return previous;
                 }
                 return new APIConnectionError(0, this.abortMessage(why));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wontopos",
-  "version": "2.2.45",
+  "version": "2.2.46",
   "description": "Wontopos \u2014 long-term memory for AI agents. Identical recall in every language, ~100\u00d7 lower LLM bill.",
   "keywords": [
     "memory",