wontopos 2.2.35 → 2.2.36

package/dist/wontopos.d.ts

@@ -44,6 +44,9 @@
 export declare function _resetStoreIdWarnings(): void;
 export declare const SEARCH_LIMIT_MIN = 5;
 export declare const SEARCH_LIMIT_MAX = 20;
+/** `recall`'s surrounding-context count. 0 to 20 inclusive; 0 attaches none. */
+export declare const CONTEXT_LIMIT_MIN = 0;
+export declare const CONTEXT_LIMIT_MAX = 20;
 /** Quota from a response's `X-RateLimit-*` headers, or `null` if absent. */
 export interface RateLimit {
     limit: number | null;
@@ -547,6 +550,22 @@ export interface ClientOptions {
      *  key on an options object is not an error in TS at runtime). Both names work;
      *  `maxRetries` wins if somehow both are given. */
     retries?: number;
+    /** A total budget for one call, in ms, across every attempt.
+     *
+     *  `timeoutMs` bounds ONE attempt. At the defaults — 30s, two retries — a single
+     *  call can hold a connection for 30s + backoff + 30s + backoff + 30s, over a
+     *  minute, and a server handler awaiting it has no way to say "I only have five
+     *  seconds". This is that way. Unset means no overall budget. */
+    deadlineMs?: number;
+    /** The caller's `AbortSignal` — cancel work already in flight.
+     *
+     *  The SDK aborts on its own timeout; this is the seam for the caller's reason.
+     *  When someone closes the chat window, the recall that window asked for should
+     *  end, and the backoff sleep waiting to retry it should end too, instead of
+     *  running to completion and billing for an answer nobody will read.
+     *
+     *  Per call, clone: `mem.withSignal(ctrl.signal).recall(...)`. */
+    signal?: AbortSignal;
     /** The `fetch` used for every request (default: the global `fetch`).
      *
      *  This is the seam for anything the runtime cannot express through options.
@@ -576,6 +595,8 @@ export declare class Client {
     private readonly apiKey;
     private readonly model;
     private readonly maxRetries;
+    private readonly deadlineMs?;
+    private readonly signal?;
     /** Transport. Held as a field (not read off `globalThis` per call) so a caller
      * who passes one gets it for every request, including from cloned clients. */
     private readonly fetchImpl;
@@ -603,6 +624,18 @@ export declare class Client {
     withModel(model: string): Client;
     /** A client bound to `userId` as its default store (everything else kept). */
     withUser(userId: string): Client;
+    /** A client bound to a caller's `AbortSignal` (everything else kept).
+     *
+     *     const ctrl = new AbortController();
+     *     req.on("close", () => ctrl.abort());
+     *     const r = await mem.withSignal(ctrl.signal).recall(q, user);
+     *
+     * Aborting ends the request in flight AND any backoff sleep waiting to retry it. */
+    withSignal(signal: AbortSignal): Client;
+    /** A client with a total budget per call, across every retry (everything else
+     * kept). `mem.withDeadline(5_000).search(q)` inside a handler that has five
+     * seconds. */
+    withDeadline(deadlineMs: number): Client;
     /** A client with a different per-request timeout in ms (everything else kept).
      * `mem.withTimeout(120_000).addBulk(bigBlob)` — this slow call only. */
     withTimeout(timeoutMs: number): Client;
@@ -907,6 +940,31 @@ export declare class Client {
      * a non-2xx we re-read the body as text and reuse `errorFor`, which keeps 404
      * (`NotFoundError`) and 401 behaving the same as everywhere else.
      */
+    /** Where this call's budget runs out, or `undefined` when it has none. Computed
+     *  once per call, not per attempt — a budget recomputed each attempt is not a
+     *  budget. */
+    private deadlineAt;
+    /** The abort wiring for ONE attempt: this SDK's per-attempt timeout, the caller's
+     *  signal, and whatever is left of the overall deadline — whichever fires first.
+     *
+     *  One function, two callers (`request` and `requestBytes`), because a guard living
+     *  in one of two request paths is exactly how `getImage` ended up with no retry loop
+     *  while the module doc promised every call had one. */
+    private beginAttempt;
+    /** What to say when an attempt was cut short. The three reasons need different
+     *  words: a timeout may have landed server-side, a cancellation certainly did not
+     *  matter to the caller, and an exhausted budget is the caller's own setting. */
+    private abortMessage;
+    /** Sleep between attempts — but wake the moment the caller aborts, and give up
+     *  rather than wait out a backoff the budget cannot cover. A backoff that runs to
+     *  completion after the caller gave up wastes exactly as long as the request it was
+     *  waiting to repeat.
+     *
+     *  Clamping the wait to what is left and retrying anyway is the same answer as
+     *  having no deadline at all: the call still spends the whole allowance, and the one
+     *  attempt it buys has nothing left to finish in. If the wait does not fit, the
+     *  budget is already decided. */
+    private backoffSleep;
     private requestBytes;
     /** 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

package/dist/wontopos.js

@@ -40,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.35";
+const VERSION = "2.2.36";
 /** Runtime info helps support debug a report ("node 18 on Windows...") —
  * platform only, never anything identifying. Browsers have no `process` (and
  * silently drop the UA header anyway). */
@@ -76,7 +76,7 @@ const RETRY_IF_IDEMPOTENT = new Set([502, 503]);
 const IDEMPOTENT_METHODS = new Set(["GET", "HEAD", "PUT", "DELETE", "OPTIONS"]);
 const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "::1", "0.0.0.0"]);
 /** Refuse to buffer absurd responses (real ones are a few KB) — protects the
- * process if a self-hosted baseUrl points somewhere broken or hostile. */
+ * process if a custom baseUrl points somewhere broken or hostile. */
 const MAX_RESPONSE_BYTES = 64 * 1024 * 1024;
 /** Model names travel in a header — only header-safe characters. */
 const MODEL_RE = /^[A-Za-z0-9._-]+$/;
@@ -154,25 +154,50 @@ const NO_BODY_STATUS = new Set([204, 205, 304]);
 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`'s surrounding-context count. 0 to 20 inclusive; 0 attaches none. */
+export const CONTEXT_LIMIT_MIN = 0;
+export const CONTEXT_LIMIT_MAX = 20;
+/** The 5-to-20 count shared by `search` and `recall`, refused out of range rather
+ * than quietly adjusted.
  *
- * `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.
+ * The service has refused anything else from the start, because asking for 20 and
+ * silently getting 10 reads as "that is all there is". Search had no contract at
+ * all: the three clients sent whatever they were given, the MCP server allowed 1 to
+ * 60, and the service quietly capped at 50 with no floor. Four surfaces, four
+ * answers, and the caller could not tell which one they got.
+ *
+ * ★ `recall` said it enforced this and did not. Its doc comment promised "out of
+ * range is refused, not clamped" while the value went straight to the wire in all
+ * three SDKs — so `limit: 500` travelled to the engine and died there. A comment
+ * that describes a guard is not a guard, and this is the shape of defect a reviewer
+ * reading one diff can never see: the promise and the missing code were written
+ * months apart.
+ *
+ * Thrown as a plain `Error`, like every other argument check in this file. It is
+ * NOT a `WosError` — nothing was sent, and `WosError` with status 0 means
+ * `APIConnectionError`, "the request never got a response". Reusing that status for
+ * a typo told a caller with `if (e.status === 0) retry()` to retry a bad argument
+ * forever.
  *
  * Refusing rather than clamping is the same decision as 2.2.35's, where a Rust
  * `limit` of 0 had been rewritten to 10 and the caller was handed ten memories they
  * had not asked for, and the bill for them. */
-function checkSearchLimit(limit) {
+function checkCount(limit, name) {
     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}. ` +
+        throw new Error(`${name} must be an integer between ${SEARCH_LIMIT_MIN} and ${SEARCH_LIMIT_MAX}, got ${limit}. ` +
             `Out of range is refused rather than adjusted, so a short answer always means ` +
             `the store was short.`);
     }
 }
+/** `recall`'s `context_limit`, 0 to 20. Same reason as the count above: the doc
+ *  comment on `recall` promises out-of-range is refused, and a promise the client
+ *  does not keep is worse than no promise — the caller reads the doc, sends 50, and
+ *  the failure arrives from the service with no hint that the SDK knew all along. */
+function checkContextLimit(n) {
+    if (!Number.isInteger(n) || n < CONTEXT_LIMIT_MIN || n > CONTEXT_LIMIT_MAX) {
+        throw new Error(`context_limit must be an integer between ${CONTEXT_LIMIT_MIN} and ${CONTEXT_LIMIT_MAX}, got ${n}.`);
+    }
+}
 /**
  * Put an image into the shape the API expects, and fail loudly on the parts we can
  * check from here.
@@ -416,6 +441,8 @@ export class Client {
     apiKey;
     model;
     maxRetries;
+    deadlineMs;
+    signal;
     /** Transport. Held as a field (not read off `globalThis` per call) so a caller
      * who passes one gets it for every request, including from cloned clients. */
     fetchImpl;
@@ -459,6 +486,11 @@ export class Client {
         // "retries exhausted"; Infinity would retry forever.
         const mr = opts.maxRetries ?? opts.retries;
         this.maxRetries = typeof mr === "number" && Number.isFinite(mr) ? Math.max(0, Math.floor(mr)) : 2;
+        const dl = opts.deadlineMs;
+        // A zero or negative budget would fail every call before it starts — treat it as
+        // "no budget", the same way a non-positive timeout falls back to the default.
+        this.deadlineMs = typeof dl === "number" && Number.isFinite(dl) && dl > 0 ? dl : undefined;
+        this.signal = opts.signal;
         // Bind the global so `fetch` is not called as a method of `globalThis`, which
         // throws "Illegal invocation" on some runtimes. A caller-supplied fetch is
         // taken as given — it is already whatever they meant to hand us.
@@ -479,7 +511,7 @@ export class Client {
         if (this.model)
             this.headers["X-WOS-Model"] = this.model;
         // An API key on plain HTTP travels readable by anyone on the path. Loopback
-        // is fine (local dev / self-hosted on the same box); anything else gets a
+        // is fine (local dev, or a proxy on the same box); anything else gets a
         // warning, not an error, so private-network gateways keep working.
         // Parse, don't split. `http://127.0.0.1:9@evil.example` splits to "127.0.0.1" — the
         // USERINFO, not the host — so this check called it loopback and stayed quiet while
@@ -488,7 +520,7 @@ export class Client {
         let host;
         try {
             // `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
+            // gives back "[::1]", which was never in LOOPBACK_HOSTS, so a local
             // client on the v6 loopback was told its key was travelling in cleartext when
             // it was not. Python's urlsplit strips them and Rust strips them by hand; this
             // was the copy that did not. Strip them here so all three agree.
@@ -567,6 +599,11 @@ export class Client {
             // friends would silently fall back to the global fetch and a proxy-bound
             // client would stop connecting the moment it was cloned.
             fetch: this.fetchImpl,
+            // Carried for the same reason as `fetch` above: a clone that quietly dropped
+            // the caller's signal would keep working right up until the moment someone
+            // needed to cancel it.
+            deadlineMs: this.deadlineMs,
+            signal: this.signal,
             ...overrides,
         });
     }
@@ -582,6 +619,22 @@ export class Client {
     withUser(userId) {
         return this.clone({ userId });
     }
+    /** A client bound to a caller's `AbortSignal` (everything else kept).
+     *
+     *     const ctrl = new AbortController();
+     *     req.on("close", () => ctrl.abort());
+     *     const r = await mem.withSignal(ctrl.signal).recall(q, user);
+     *
+     * Aborting ends the request in flight AND any backoff sleep waiting to retry it. */
+    withSignal(signal) {
+        return this.clone({ signal });
+    }
+    /** A client with a total budget per call, across every retry (everything else
+     * kept). `mem.withDeadline(5_000).search(q)` inside a handler that has five
+     * seconds. */
+    withDeadline(deadlineMs) {
+        return this.clone({ deadlineMs });
+    }
     /** A client with a different per-request timeout in ms (everything else kept).
      * `mem.withTimeout(120_000).addBulk(bigBlob)` — this slow call only. */
     withTimeout(timeoutMs) {
@@ -641,7 +694,7 @@ export class Client {
         // 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);
+        checkCount(limit, "limit");
         const r = await this.post("/api/v1/memory/search", { ...opts, user_id: this.uid(userId), query, max_results: limit });
         return mergeResults(r);
     }
@@ -652,7 +705,7 @@ export class Client {
      * 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);
+        checkCount(limit, "limit");
         const r = await this.post("/api/v1/memory/search", { ...opts, user_id: this.uid(userId), query, max_results: limit });
         return { memories: asRecords(r.memories), self_memories: asRecords(r.self_memories) };
     }
@@ -672,7 +725,7 @@ export class Client {
      */
     async searchFull(query, userId, limit = 10, opts = {}) {
         warnOnUnknownFilters(opts.filters);
-        checkSearchLimit(limit);
+        checkCount(limit, "limit");
         const r = await this.post("/api/v1/memory/search", { ...opts, user_id: this.uid(userId), query, max_results: limit });
         // Spread first so a field added later still arrives; the known ones are then
         // normalized, because a broken proxy can null any of them.
@@ -686,12 +739,20 @@ export class Client {
     /** One-call LLM context: short-term turns + long-term matches + surrounding context.
      * `form` ("memoir"/"archive", Scroll 1.2+) renders each long-term memory's time in
      * that form; `tz` is your UTC-offset hours for that rendering. */
-    recall(query, userId, opts = {}) {
+    // `async` so an argument mistake arrives the way every other failure does — a
+    // rejected promise. Validating inside a non-async method threw synchronously, so
+    // `mem.recall(...).catch(h)` walked straight past the handler while the identical
+    // mistake in `search` (which is async) landed in it. Two shapes for one error.
+    async recall(query, userId, opts = {}) {
         const body = { user_id: this.uid(userId), query };
-        if (opts.limit !== undefined)
+        if (opts.limit !== undefined) {
+            checkCount(opts.limit, "limit");
             body.limit = opts.limit;
-        if (opts.context_limit !== undefined)
+        }
+        if (opts.context_limit !== undefined) {
+            checkContextLimit(opts.context_limit);
             body.context_limit = opts.context_limit;
+        }
         return this.post("/api/v1/memory/recall", withForm(body, opts.form, opts.tz));
     }
     /** Run a built-in engram ("deep_recall" | "timeline" | "gather" | "equilibrium" |
@@ -761,7 +822,7 @@ export class Client {
             seen.add(next);
             cursor = next;
         }
-        throw new WosError(0, `stopped after ${MAX_PAGES} pages — the store did not end. This is a truncated ` +
+        throw new Error(`stopped after ${MAX_PAGES} pages — the store did not end. This is a truncated ` +
             `answer, not the whole store.`);
     }
     /** Collect ALL of a store's memories into an array (the text you stored, and its metadata). */
@@ -868,7 +929,7 @@ export class Client {
             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 ` +
+        throw new Error(`stopped after ${MAX_PAGES} pages — the store did not end. This is a truncated ` +
             `answer, not the whole store.`);
     }
     // ----- how much has this memory been edited -----
@@ -1087,6 +1148,101 @@ export class Client {
      * a non-2xx we re-read the body as text and reuse `errorFor`, which keeps 404
      * (`NotFoundError`) and 401 behaving the same as everywhere else.
      */
+    /** Where this call's budget runs out, or `undefined` when it has none. Computed
+     *  once per call, not per attempt — a budget recomputed each attempt is not a
+     *  budget. */
+    deadlineAt() {
+        return this.deadlineMs === undefined ? undefined : Date.now() + this.deadlineMs;
+    }
+    /** The abort wiring for ONE attempt: this SDK's per-attempt timeout, the caller's
+     *  signal, and whatever is left of the overall deadline — whichever fires first.
+     *
+     *  One function, two callers (`request` and `requestBytes`), because a guard living
+     *  in one of two request paths is exactly how `getImage` ended up with no retry loop
+     *  while the module doc promised every call had one. */
+    beginAttempt(deadlineAt) {
+        let why = "timeout";
+        let budget = this.timeoutMs;
+        if (deadlineAt !== undefined) {
+            const left = deadlineAt - Date.now();
+            // Refuse rather than open a socket there is no time to use. Python's
+            // `_attempt_budget` and Rust's `attempt_budget` have raised here from the start.
+            // This path instead clamped the budget to 0 and began the attempt anyway, which
+            // left `setTimeout(…, 0)` — it fires on the next timer phase — racing a fetch
+            // that a fast server answers first. The same call then sometimes reported its
+            // deadline and sometimes returned a result: one run in three, measured.
+            if (left <= 0)
+                throw new APIConnectionError(0, this.abortMessage("deadline"));
+            if (left < budget) {
+                budget = left;
+                why = "deadline";
+            }
+        }
+        const ctrl = new AbortController();
+        const timer = setTimeout(() => ctrl.abort(), budget);
+        const outer = this.signal;
+        const onCaller = () => {
+            why = "caller";
+            ctrl.abort();
+        };
+        if (outer) {
+            if (outer.aborted)
+                onCaller();
+            // Removed in clear(). `{ once: true }` would not be enough: one long-lived
+            // signal per user session would still collect one listener per request until
+            // the session ended.
+            else
+                outer.addEventListener("abort", onCaller);
+        }
+        return {
+            signal: ctrl.signal,
+            clear: () => {
+                clearTimeout(timer);
+                outer?.removeEventListener("abort", onCaller);
+            },
+            why: () => why,
+        };
+    }
+    /** What to say when an attempt was cut short. The three reasons need different
+     *  words: a timeout may have landed server-side, a cancellation certainly did not
+     *  matter to the caller, and an exhausted budget is the caller's own setting. */
+    abortMessage(why) {
+        if (why === "caller")
+            return "cancelled — the caller's AbortSignal fired";
+        if (why === "deadline")
+            return `deadline of ${this.deadlineMs}ms exhausted`;
+        return `request timed out after ${this.timeoutMs}ms`;
+    }
+    /** Sleep between attempts — but wake the moment the caller aborts, and give up
+     *  rather than wait out a backoff the budget cannot cover. A backoff that runs to
+     *  completion after the caller gave up wastes exactly as long as the request it was
+     *  waiting to repeat.
+     *
+     *  Clamping the wait to what is left and retrying anyway is the same answer as
+     *  having no deadline at all: the call still spends the whole allowance, and the one
+     *  attempt it buys has nothing left to finish in. If the wait does not fit, the
+     *  budget is already decided. */
+    async backoffSleep(ms, deadlineAt) {
+        if (deadlineAt !== undefined && ms > deadlineAt - Date.now()) {
+            throw new APIConnectionError(0, this.abortMessage("deadline"));
+        }
+        const outer = this.signal;
+        if (!outer) {
+            await new Promise((r) => setTimeout(r, ms));
+            return;
+        }
+        if (outer.aborted)
+            return;
+        await new Promise((resolve) => {
+            const done = () => {
+                clearTimeout(timer);
+                outer.removeEventListener("abort", done);
+                resolve();
+            };
+            const timer = setTimeout(done, ms);
+            outer.addEventListener("abort", done);
+        });
+    }
     async requestBytes(path, body) {
         // This route had no retry loop at all, while the module doc promised "every call
         // retries transient failures … 429 always". Measured with maxRetries: 4 against a
@@ -1095,32 +1251,32 @@ export class Client {
         // immediately. The loop lives inside the function because honouring `Retry-After`
         // means still holding the response.
         const attempts = this.maxRetries + 1;
+        const deadlineAt = this.deadlineAt();
         for (let attempt = 0;; attempt++) {
-            const ctrl = new AbortController();
-            const timer = setTimeout(() => ctrl.abort(), this.timeoutMs);
+            const att = this.beginAttempt(deadlineAt);
             let res;
             try {
                 res = await this.fetchImpl(`${this.base}${path}`, {
                     method: "POST",
                     headers: this.headers,
                     body: JSON.stringify(body),
-                    signal: ctrl.signal,
+                    signal: att.signal,
                     redirect: "manual",
                 });
             }
             catch (e) {
-                clearTimeout(timer);
-                const timedOut = e?.name === "AbortError" || ctrl.signal.aborted;
+                att.clear();
+                const timedOut = e?.name === "AbortError" || att.signal.aborted;
                 // Same rule as `request()`: a connect-level failure never reached the server,
                 // so re-sending cannot double-process anything. The 429 loop below was added
                 // in 2.2.35 and this branch was not, which left the module doc's promise —
                 // "every call retries transient failures" — still false for `getImage` on
                 // exactly the failure a retry is for. A timeout is ambiguous and stays final.
                 if (!timedOut && isConnectFailure(e) && attempt + 1 < attempts) {
-                    await new Promise((r) => setTimeout(r, this.backoffMs(attempt)));
+                    await this.backoffSleep(this.backoffMs(attempt), deadlineAt);
                     continue;
                 }
-                throw new APIConnectionError(0, timedOut ? `request timed out after ${this.timeoutMs}ms` : `network error: ${e?.message ?? e}`);
+                throw new APIConnectionError(0, timedOut ? this.abortMessage(att.why()) : `network error: ${e?.message ?? e}`);
             }
             try {
                 this._rateLimit = parseRateLimit(res.headers) ?? this._rateLimit;
@@ -1132,8 +1288,8 @@ export class Client {
                     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)));
+                        att.clear();
+                        await this.backoffSleep(this.backoffMs(attempt, retryAfter), deadlineAt);
                         continue;
                     }
                     let msg = await this.readCapped(res).catch(() => "");
@@ -1161,7 +1317,7 @@ export class Client {
                     buf = await this.readCappedBytes(res);
                 }
                 catch (e) {
-                    if (e?.name === "AbortError" || ctrl.signal.aborted) {
+                    if (e?.name === "AbortError" || att.signal.aborted) {
                         throw new APIConnectionError(0, `request timed out after ${this.timeoutMs}ms`);
                     }
                     throw e;
@@ -1174,7 +1330,7 @@ export class Client {
                 return { bytes: buf, contentType: res.headers.get("content-type") ?? "application/octet-stream" };
             }
             finally {
-                clearTimeout(timer);
+                att.clear();
             }
         }
     }
@@ -1221,7 +1377,7 @@ export class Client {
     async readCappedBytes(res) {
         const cl = res.headers.get("content-length");
         if (cl && Number(cl) > MAX_RESPONSE_BYTES) {
-            throw new WosError(0, `response too large (${cl} bytes) — refusing to buffer it`);
+            throw new WosError(res.status, `response too large (${cl} bytes) — refusing to buffer it`);
         }
         if (!res.body) {
             // `arrayBuffer()` has no ceiling, and only the content-length pre-check stands
@@ -1231,7 +1387,7 @@ export class Client {
             // 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`);
+                throw new WosError(res.status, `response too large (${buf.byteLength} bytes) — refusing it`);
             }
             return buf;
         }
@@ -1245,7 +1401,7 @@ export class Client {
             size += value.byteLength;
             if (size > MAX_RESPONSE_BYTES) {
                 void reader.cancel();
-                throw new WosError(0, "response too large — refusing to buffer it");
+                throw new WosError(res.status, "response too large — refusing to buffer it");
             }
             parts.push(value);
         }
@@ -1263,26 +1419,26 @@ export class Client {
         // Debug logging shows the path WITHOUT its query string — a query can carry
         // a store id (listSpeakers), and logs must never carry data.
         const logPath = path.split("?")[0];
+        const deadlineAt = this.deadlineAt();
         for (let attempt = 0; attempt < attempts; attempt++) {
             const start = Date.now();
-            const ctrl = new AbortController();
-            const timer = setTimeout(() => ctrl.abort(), this.timeoutMs);
+            const att = this.beginAttempt(deadlineAt);
             let res;
             try {
                 res = await this.fetchImpl(`${this.base}${path}`, {
                     method,
                     headers: extraHeaders ? { ...this.headers, ...extraHeaders } : this.headers,
                     body: body === undefined ? undefined : JSON.stringify(body),
-                    signal: ctrl.signal,
+                    signal: att.signal,
                     // Never follow a redirect: fetch would forward the API key to
                     // wherever a 3xx points. The API never legitimately redirects.
                     redirect: "manual",
                 });
             }
             catch (e) {
-                clearTimeout(timer);
+                att.clear();
                 // Timeouts are ambiguous (the write may have landed) — don't retry those.
-                const timedOut = e?.name === "AbortError" || ctrl.signal.aborted;
+                const timedOut = e?.name === "AbortError" || att.signal.aborted;
                 // Other network errors retry only when a retry can't double-process a
                 // write: idempotent methods always; writes only for connect-level
                 // failures (the request never reached the server). A mid-stream drop on
@@ -1291,24 +1447,24 @@ export class Client {
                 if (!timedOut && safe && attempt + 1 < attempts) {
                     const delay = this.backoffMs(attempt);
                     logDebug(`${method} ${logPath}: ${e?.code ?? e?.name ?? "network error"} — retrying in ${delay}ms (attempt ${attempt + 1}/${attempts})`);
-                    await new Promise((r) => setTimeout(r, delay));
+                    await this.backoffSleep(delay, deadlineAt);
                     continue;
                 }
-                throw new APIConnectionError(0, timedOut ? `request timed out after ${this.timeoutMs}ms` : `network error: ${e?.message ?? e}`);
+                throw new APIConnectionError(0, timedOut ? this.abortMessage(att.why()) : `network error: ${e?.message ?? e}`);
             }
             const retryable = RETRY_ALWAYS.has(res.status) ||
                 (RETRY_IF_IDEMPOTENT.has(res.status) && IDEMPOTENT_METHODS.has(method.toUpperCase()));
             if (retryable && attempt + 1 < attempts) {
-                clearTimeout(timer);
+                att.clear();
                 const retryAfter = res.headers.get("Retry-After");
                 void res.body?.cancel();
                 const delay = this.backoffMs(attempt, retryAfter);
                 logDebug(`${method} ${logPath} -> ${res.status} — retrying in ${delay}ms (attempt ${attempt + 1}/${attempts})`);
-                await new Promise((r) => setTimeout(r, delay));
+                await this.backoffSleep(delay, deadlineAt);
                 continue;
             }
             if ((res.status >= 300 && res.status < 400) || res.type === "opaqueredirect") {
-                clearTimeout(timer);
+                att.clear();
                 void res.body?.cancel(); // release the stream — otherwise the connection leaks
                 throw new WosError(res.status, "unexpected redirect — refused (the API key never follows a redirect). Check baseUrl: exact host, https://.");
             }
@@ -1321,7 +1477,7 @@ export class Client {
                 text = await this.readCapped(res);
             }
             catch (e) {
-                if (e?.name === "AbortError" || ctrl.signal.aborted) {
+                if (e?.name === "AbortError" || att.signal.aborted) {
                     throw new APIConnectionError(0, `request timed out after ${this.timeoutMs}ms`);
                 }
                 if (e instanceof WosError)
@@ -1331,7 +1487,7 @@ export class Client {
                 throw new APIConnectionError(0, `network error: ${e?.message ?? e}`);
             }
             finally {
-                clearTimeout(timer);
+                att.clear();
             }
             logDebug(`${method} ${logPath} -> ${res.status} in ${Date.now() - start}ms (attempt ${attempt + 1}/${attempts})`);
             if (!res.ok) {
@@ -1392,12 +1548,17 @@ export class Client {
             // `Idempotent-Replayed: true`, and it answers the question someone using an
             // idempotency key is asking: did my retry write, or is this the first response
             // coming back again?
-            if (res.headers.get("Idempotent-Replayed") === "true") {
+            //
+            // Only when the body does not already carry the field. These responses are
+            // widening — the next engine adds `images`, `hop`, `tip_of_tongue`, `policy` —
+            // and a client that writes into a server's object is one release away from
+            // overwriting a real answer with its own guess. What the service said wins.
+            if (res.headers.get("Idempotent-Replayed") === "true" && !("replayed" in data)) {
                 data.replayed = true;
             }
             return data;
         }
-        throw new WosError(0, "retries exhausted"); // unreachable; keeps the compiler happy
+        throw new Error("retries exhausted"); // unreachable; keeps the compiler happy
     }
 }
 /** Back-compat alias: older code used `WME`. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wontopos",
-  "version": "2.2.35",
+  "version": "2.2.36",
   "description": "Wontopos — long-term memory for AI agents. Identical recall in every language, ~100× lower LLM bill.",
   "keywords": [
     "memory",
@@ -15,13 +15,14 @@
   "license": "MIT",
   "author": "Wontopos",
   "type": "module",
-  "main": "./dist/wontopos.js",
+  "main": "./dist/cjs/wontopos.js",
   "module": "./dist/wontopos.js",
   "types": "./dist/wontopos.d.ts",
   "exports": {
     ".": {
       "types": "./dist/wontopos.d.ts",
       "import": "./dist/wontopos.js",
+      "require": "./dist/cjs/wontopos.js",
       "default": "./dist/wontopos.js"
     }
   },
@@ -34,8 +35,8 @@
     "node": ">=18"
   },
   "scripts": {
-    "build": "tsc",
-    "test": "npm run build && node --test tests/client.test.mjs",
+    "build": "tsc && tsc -p tsconfig.cjs.json && node -e \"require('fs').writeFileSync('dist/cjs/package.json','{\\\"type\\\":\\\"commonjs\\\"}\\n')\"",
+    "test": "npm run build && node --test tests/client.test.mjs tests/cjs.test.cjs",
     "prepublishOnly": "npm run build && node scripts/pre-publish.mjs"
   },
   "devDependencies": {