wontopos 2.2.36 → 2.2.38

package/dist/wontopos.js

@@ -1,56 +1,9 @@
-/**
- * Wontopos — long-term memory for AI, in three lines.
- *
- *   npm install wontopos
- *
- *   import { Client } from "wontopos";
- *   const mem = new Client({ apiKey: "wos-...", userId: "alice" }); // set the store once
- *   await mem.createStore();                              // create it (uses the client's userId)
- *   await mem.add("she prefers tea over coffee");         // no userId needed
- *   const hits = await mem.search("what does alice drink?");
- *
- * Set `userId` once on the client and every call uses it; override any single call
- * by passing `userId` to it. Stores are explicit: the store must exist first
- * (`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*
- * reads it. Models on the shared pool read the same memory, so you can store with
- * one and recall with another; `listModels()` reports each model's `memory` as
- * `"shared"` or `"isolated"`, and an isolated one starts empty. Set a default in
- * the constructor, or override a single call with
- * `mem.withModel("tablet-1").recall(...)`.
- *
- * Recall quality does not depend on which language a memory was written in: a
- * memory stored in one language is found by a question asked in another. Storing
- * and searching call no LLM.
- *
- * Reliability: every call retries transient failures with exponential backoff +
- * jitter, honoring `Retry-After` — 429 always; 502/503 and connection errors only
- * 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 the `withTimeout()` / `withRetries()` clones.
- *
- * Debugging: set `WONTOPOS_LOG=debug` to log method/path/status/timing/retries
- * to stderr — never memory content, request bodies, or the API key.
- *
- * Security posture (not configurable off): redirects are refused so the API key
- * can never follow one to another host; responses over 64MB are refused; the key
- * is masked in `toJSON`/inspect output. TLS certificate verification is the
- * 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.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). */
+const VERSION = "2.2.38";
 const RUNTIME = (() => {
     const p = globalThis?.process;
     return p?.version ? ` (node/${p.version}; ${p.platform}-${p.arch})` : "";
 })();
 const USER_AGENT = `wontopos-node/${VERSION}${RUNTIME}`;
-/** Wire-level debug logging: set WONTOPOS_LOG=debug. Logs method/path/status/
- * timing/retries to stderr — NEVER memory content, request bodies, or the key. */
 function logDebug(msg) {
     const env = globalThis?.process?.env;
     if (typeof env?.WONTOPOS_LOG === "string" && env.WONTOPOS_LOG.toLowerCase() === "debug") {
@@ -58,63 +11,25 @@ function logDebug(msg) {
     }
 }
 const DEFAULT_BASE_URL = "https://api.wontopos.com";
-/** The engine every call uses unless the caller names another.
- *
- *  Tablet 2 costs the same per token as Tablet 1 and is the one that
- *  serves images, re-ask passes (`verify`), and `self_memories`, so a caller who
- *  names nothing gets the engine that can answer the most. Models on the shared
- *  pool read the same memory, so switching between them is a header, not a
- *  migration. Pin an older one explicitly with
- *  `new Client({ apiKey, model: "tablet-1" })` or `withModel("tablet-1")`. */
 const DEFAULT_MODEL = "tablet-2";
-/** 429 = rate-limited BEFORE processing → always safe to retry (no write, no bill). */
 const RETRY_ALWAYS = new Set([429]);
-/** 502/503 are ambiguous for a write (gateway may return them AFTER the backend
- *  processed + billed the request), so retry them only for idempotent methods —
- *  a retried POST could double-store / double-bill. */
 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 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._-]+$/;
-/** Cap a server-controlled error message so a hostile body can't blow up a log. */
 const MAX_ERR_MSG = 4096;
-/** What the API accepts as an `Idempotency-Key`. Checked client-side so a bad key
- *  fails before the request instead of coming back as a 400 mid-retry. */
 const IDEMPOTENCY_KEY_RE = /^[A-Za-z0-9._:\-]{1,128}$/;
-/**
- * The API normalizes a store id: lowercased, and every character outside
- * `[a-z0-9_]` becomes `_`. So `Alice.Smith`, `alice-smith` and `alice_smith` are
- * ALL the same store.
- *
- * That is a data-exposure hazard for the most common way this SDK is used — one
- * store per end user. Two accounts whose ids differ only by punctuation or case
- * (`bob.lee@x.com` / `bob-lee@x.com`) silently share every memory, and nothing in
- * the response says so: the note only appears when `createStore` creates one, and
- * an app that reuses an existing store never sees it.
- *
- * We cannot refuse the id — the API accepts it, and callers may have written it
- * this way for a year. So we say it once, loudly, at the moment it happens.
- */
 function normalizeStoreId(id) {
     return id.toLowerCase().replace(/[^a-z0-9_]/g, "_");
 }
-/** Ids already warned about, so each is reported once.
- *
- *  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 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. */
 const WARNED_STORE_IDS_MAX = 1024;
-/** Same cap, same reason, for the unknown-filter warn set. */
+function assertUsableStoreId(userId) {
+    if (userId !== undefined && (typeof userId !== "string" || !userId.trim())) {
+        throw new Error(`userId must be a non-blank string; got ${JSON.stringify(userId)}. Omit it to use the client's ` +
+            "default store, or pass a real store id — anything else would silently write into the default store.");
+    }
+}
 const WARNED_FILTER_KEYS_MAX = 1024;
 const warnedStoreIds = new Set();
 function warnIfStoreIdCollapses(id) {
@@ -135,53 +50,15 @@ function warnIfStoreIdCollapses(id) {
         `punctuation share ONE store and therefore one set of memories — if these ids come from your ` +
         `end users, normalize them yourself first so two people can never collide.`);
 }
-/** Test hook — the warn-once set is process-global by design. */
 export function _resetStoreIdWarnings() {
     warnedStoreIds.clear();
 }
-/** Statuses that legitimately carry NO body (RFC 9110). Everything else must
- *  answer with a JSON object — see the empty-body check in `request`. */
 const NO_BODY_STATUS = new Set([204, 205, 304]);
-/** Paging backstop: bound the walk so a fresh-cursor-forever server can't loop us. */
-// A page walk has to stop somewhere, and 1,000,000 pages was not a stop: at 100 per
-// page that is 100 million memories, so a server minting a fresh cursor every time
-// would spend hours and a million billed requests before it fired. 20,000 pages is two
-// million memories — past any real store, reached in minutes.
-//
-// ★And it has to be LOUD. Falling out of the loop yielded a truncated list that looks
-// exactly like a complete one; the caller writes it to a file believing it is the
-// whole store. Hitting this now throws.
 const MAX_PAGES = 20_000;
 export const SEARCH_LIMIT_MIN = 5;
 export const SEARCH_LIMIT_MAX = 20;
-/** `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.
- *
- * 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 checkCount(limit, name) {
     if (!Number.isInteger(limit) || limit < SEARCH_LIMIT_MIN || limit > SEARCH_LIMIT_MAX) {
         throw new Error(`${name} must be an integer between ${SEARCH_LIMIT_MIN} and ${SEARCH_LIMIT_MAX}, got ${limit}. ` +
@@ -189,27 +66,11 @@ function checkCount(limit, name) {
             `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.
- *
- * Deliberately NOT checked: the byte ceiling. It is a service setting, so a number
- * baked in here would drift the first time the service is reconfigured and would
- * reject an image the service would have taken.
- * What we do check is what cannot change: an empty payload, and a `data:` URL
- * prefix — browsers and file pickers hand you `data:image/jpeg;base64,…`, the API
- * wants the part after the comma, and the difference is invisible until the write
- * fails with "not a readable image".
- */
 function normalizeImage(image) {
     if (!image || typeof image !== "object") {
         throw new Error("image must be an object — { data: '<base64>' }.");
@@ -217,15 +78,8 @@ 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).");
     }
-    // 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;
-    // 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.");
@@ -236,10 +90,6 @@ function normalizeImage(image) {
         out.taken_at = image.taken_at;
     return out;
 }
-/** Error codes that only occur while ESTABLISHING a connection — the request
- * never reached the server, so a retry can't double-process a write. Mid-stream
- * codes (ECONNRESET, EPIPE, UND_ERR_SOCKET, ETIMEDOUT) are ambiguous: the server
- * may already have processed (and billed) the request, so they're excluded. */
 const CONNECT_FAIL_CODES = new Set([
     "ECONNREFUSED",
     "ENOTFOUND",
@@ -250,8 +100,6 @@ const CONNECT_FAIL_CODES = new Set([
     "EADDRNOTAVAIL",
     "UND_ERR_CONNECT_TIMEOUT",
 ]);
-/** Walk an error's `cause` chain (and AggregateError members — happy-eyeballs
- * connects) looking for a connect-level failure code. */
 function isConnectFailure(e) {
     const stack = [e];
     for (let steps = 0; stack.length && steps < 24; steps++) {
@@ -267,7 +115,6 @@ function isConnectFailure(e) {
     }
     return false;
 }
-/** `wos-abc...wxyz` — enough to tell keys apart, never enough to use. */
 function maskKey(key) {
     return key.length > 12 ? `${key.slice(0, 4)}...${key.slice(-4)}` : "***";
 }
@@ -275,7 +122,7 @@ function parseRateLimit(h) {
     const num = (name) => {
         const v = h.get(name);
         if (v == null || v.trim() === "")
-            return null; // Number("") is 0 — treat blank as absent
+            return null;
         const n = Number(v);
         return Number.isFinite(n) ? n : null;
     };
@@ -286,30 +133,9 @@ function parseRateLimit(h) {
         return null;
     return { limit, remaining, reset };
 }
-// A list/object field the API promises. `x ?? []` only replaces null/undefined — a
-// broken or hostile server sending a truthy wrong type (`"memories": "oops"`) would
-// slip through as a string and blow up the caller's `for (…of…)`. Coerce anything
-// that isn't actually an array/object to the empty value.
 const asList = (x) => (Array.isArray(x) ? x : []);
 const asObj = (x) => (x != null && typeof x === "object" && !Array.isArray(x) ? x : {});
-// A list of API records (memories, turns, models...) — every element is an object
-// by contract. `asList` only fixes the CONTAINER: a hostile/broken server sending
-// `{"memories": [null, 1, "x", {...}]}` still handed the caller those non-objects,
-// typed as Memory[], and the first `m.content` threw a raw TypeError from inside
-// user code. Drop elements that aren't objects and keep the valid records, so one
-// bad element never poisons the batch (and never destroys it).
 const asRecords = (x) => asList(x).filter((m) => m != null && typeof m === "object" && !Array.isArray(m));
-/** Every memory a search returned, from both fields, as one array.
- *
- * Some models answer with the assistant's own words in `self_memories`, not
- * repeated in `memories`. `search()` used to return `memories` alone, so an
- * assistant turn stored with `addTurn` was missing from its results on those
- * models while the same query returned it on others — upgrading made search
- * return LESS, and what went missing had already been retrieved and paid for.
- *
- * Both fields are returned here, de-duplicated by id, each memory keeping its
- * `speaker` so a caller can still tell who said what. Callers who want them kept
- * apart use `searchSelf()`, which is what that method is for. */
 function mergeResults(r) {
     const main = asRecords(r?.memories);
     const mine = asRecords(r?.self_memories);
@@ -318,9 +144,6 @@ function mergeResults(r) {
     const seen = new Set(main.map((m) => m.id).filter((id) => typeof id === "string"));
     return main.concat(mine.filter((m) => !(typeof m.id === "string" && seen.has(m.id))));
 }
-/** Attach a delivery-form override ("memoir"/"archive") + tz to a request body, the
- * way search passes them; on Scroll 1.2+ this renders each returned memory's time in
- * that form. The server validates the form (400 on an unknown one). */
 function withForm(body, form, tz) {
     if (form !== undefined)
         body.form = form;
@@ -330,53 +153,30 @@ function withForm(body, form, tz) {
 }
 export class WosError extends Error {
     status;
-    /** The server's id for the request when it sent one — include it when contacting support. */
     requestId;
     constructor(status, message, requestId) {
         super(`[${status}] ${message}${requestId ? ` (request_id: ${requestId})` : ""}`);
-        this.name = new.target.name; // the concrete subclass name (RateLimitError, …)
+        this.name = new.target.name;
         this.status = status;
         this.requestId = requestId;
     }
 }
-// Typed subclasses so callers can branch on the failure — `catch (e) { if (e instanceof
-// RateLimitError) … }`. Each is a WosError, so a broad `instanceof WosError` still works.
-/** The request never got a response (DNS/TLS/timeout/connection). `status` is 0. */
 export class APIConnectionError extends WosError {
 }
-/** 400 — the request was malformed (bad arguments). */
 export class BadRequestError extends WosError {
 }
-/** 401 — the API key is missing, wrong, or revoked. */
 export class AuthenticationError extends WosError {
 }
-/** 402 — no card on file or the balance is depleted. Top up to continue. */
 export class PaymentRequiredError extends WosError {
 }
-/** 403 — the key/model isn't allowed to do this. */
 export class PermissionDeniedError extends WosError {
 }
-/** 404 — the store or resource doesn't exist (create the store first). */
 export class NotFoundError extends WosError {
 }
-/** 409 — a concurrent write to the same store. Retry. */
 export class ConflictError extends WosError {
 }
-/** 429 — too many requests. Back off and retry (the client already retries these). */
 export class RateLimitError extends WosError {
 }
-/**
- * 5xx — the service failed.
- *
- * `502` / `503` are transient: the client already retries them for calls where a
- * retry cannot double-process a write, and retrying yourself is reasonable.
- *
- * `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. Treating the whole 5xx range as retryable sends a caller into a
- * loop that cannot end.
- */
 export class ServerError extends WosError {
 }
 const STATUS_ERRORS = {
@@ -388,17 +188,12 @@ const STATUS_ERRORS = {
     409: ConflictError,
     429: RateLimitError,
 };
-/** Build the most specific WosError subclass for an HTTP status. */
-// Internal factory — the typed error CLASSES are the public surface.
 function errorFor(status, message, requestId) {
     const Cls = status === 0
         ? APIConnectionError
         : STATUS_ERRORS[status] ?? (status >= 500 && status < 600 ? ServerError : WosError);
     return new Cls(status, message, requestId);
 }
-/** The filter keys the API acts on. Anything else it DROPS silently, so a typo
- *  widens the search instead of failing — we warn rather than reject, because the
- *  API may grow a key before this package is updated. */
 const KNOWN_FILTER_KEYS = new Set([
     "categories",
     "event_from",
@@ -408,6 +203,47 @@ const KNOWN_FILTER_KEYS = new Set([
     "min_importance",
 ]);
 const warnedFilterKeys = new Set();
+const KNOWN_SEARCH_KEYS = new Set([
+    "cache_control", "speaker", "filters", "verify", "max_images", "extra",
+]);
+const RESERVED_SEARCH_KEYS = new Set(["user_id", "query", "max_results"]);
+const KNOWN_RECALL_KEYS = new Set(["form", "tz", "limit", "context_limit"]);
+function checkSearchOpts(opts) {
+    checkOpts(opts, KNOWN_SEARCH_KEYS, "search");
+}
+function checkOpts(opts, known, what) {
+    for (const k of Object.keys(opts)) {
+        if (RESERVED_SEARCH_KEYS.has(k))
+            throw new Error(`${JSON.stringify(k)} is set by the call, not by options — pass it as an argument. ` +
+                `An app forwarding untrusted input as options cannot steer the store, the query ` +
+                `or the count, and this says so rather than dropping it silently.`);
+        if (known.has(k))
+            continue;
+        const near = [...known].find((n) => n !== "extra" && editWithin(k, n, 2));
+        throw new Error(`unknown ${what} option ${JSON.stringify(k)}` +
+            (near ? ` — did you mean ${JSON.stringify(near)}?` : "") +
+            `. The service drops keys it does not know and answers anyway, so this would ` +
+            `have looked like it worked.` +
+            (known.has("extra")
+                ? ` Pass it under \`extra\` if the service accepts it and this client does not know it yet.`
+                : ""));
+    }
+}
+function editWithin(a, b, max) {
+    if (Math.abs(a.length - b.length) > max)
+        return false;
+    const prev = Array.from({ length: b.length + 1 }, (_, j) => j);
+    for (let i = 1; i <= a.length; i++) {
+        let diag = prev[0];
+        prev[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const tmp = prev[j];
+            prev[j] = Math.min(prev[j] + 1, prev[j - 1] + 1, diag + (a[i - 1] === b[j - 1] ? 0 : 1));
+            diag = tmp;
+        }
+    }
+    return prev[b.length] <= max;
+}
 function warnOnUnknownFilters(filters) {
     if (!filters || typeof filters !== "object" || Array.isArray(filters))
         return;
@@ -415,8 +251,6 @@ function warnOnUnknownFilters(filters) {
         if (KNOWN_FILTER_KEYS.has(k) || warnedFilterKeys.has(k))
             continue;
         warnedFilterKeys.add(k);
-        // 2.2.27 capped the store-id warn set and left this sibling unbounded. An app that
-        // forwards user-supplied filter keys grows it forever, one entry per distinct typo.
         while (warnedFilterKeys.size > WARNED_FILTER_KEYS_MAX) {
             const oldest = warnedFilterKeys.values().next().value;
             if (oldest === undefined)
@@ -428,12 +262,10 @@ function warnOnUnknownFilters(filters) {
             `Known keys: ${[...KNOWN_FILTER_KEYS].join(", ")}.`);
     }
 }
-/** Test hook — the warn-once set is process-global by design. */
 export function _resetFilterWarnings() {
     warnedFilterKeys.clear();
 }
 const DEFAULT_USER = "default";
-/** Wontopos memory client. Store and recall memories, isolated per `userId`. */
 export class Client {
     base;
     headers;
@@ -443,57 +275,40 @@ export class Client {
     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;
-    /** The store every call uses unless one passes `userId`. */
     defaultUser;
     _rateLimit = null;
-    /** Quota from the MOST RECENT call: `{ limit, remaining, reset }` (or `null` before
-     * the first call). Read it to self-throttle — the client already retries 429s, but
-     * this lets you slow down before hitting the wall. */
     get rateLimit() {
         return this._rateLimit;
     }
     constructor(opts) {
-        // Trim the key and reject inner whitespace — a stray newline from a file or
-        // env var otherwise turns into a mystery 401 (or a mangled header).
         const key = (opts?.apiKey ?? "").trim();
         if (!key)
             throw new Error("apiKey is required");
         if (/\s/.test(key))
             throw new Error("apiKey contains whitespace - check for a stray newline or paste error");
-        // `\s` does not cover NUL, 0x01 or DEL, and those travel into the header and fail
-        // deep inside fetch as the mystery 401 this check exists to prevent. Python has
-        // `_HEADER_CTL_RE` and Rust tests `is_control`; this was the client that did not,
-        // while all three READMEs announced the guard without naming a language.
         if (/[\x00-\x1f\x7f]/.test(key))
             throw new Error("apiKey contains a control character - check for a stray byte or paste error");
+        if (/[^\x00-\x7f]/.test(key)) {
+            const bad = key.match(/[^\x00-\x7f]/)?.[0];
+            throw new Error(`apiKey contains a non-ASCII character (${JSON.stringify(bad)}) - rich text turns '-' into an ` +
+                "en dash; copy the key from a plain-text field");
+        }
         this.apiKey = key;
         this.base = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
-        // Coerce a non-finite or non-positive timeout back to the default — NaN
-        // (e.g. Number() of an unset env var) would otherwise make the abort timer
-        // fire immediately and every request "time out after NaNms".
         const tm = opts.timeoutMs;
         this.timeoutMs = typeof tm === "number" && Number.isFinite(tm) && tm > 0 ? tm : 30_000;
         this.model = opts.model ?? DEFAULT_MODEL;
         if (this.model && !MODEL_RE.test(this.model)) {
             throw new Error(`invalid model name: ${JSON.stringify(this.model)} (letters, digits, '.', '_', '-' only)`);
         }
-        this.defaultUser = opts.userId || DEFAULT_USER;
-        // Coerce a non-finite maxRetries (NaN/Infinity) back to the default — otherwise
-        // NaN makes `attempts = NaN + 1` and the loop runs zero requests then throws
-        // "retries exhausted"; Infinity would retry forever.
+        assertUsableStoreId(opts.userId);
+        this.defaultUser = opts.userId ?? DEFAULT_USER;
         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.
         const f = opts.fetch;
         if (f !== undefined && typeof f !== "function") {
             throw new Error("fetch must be a function (a fetch-compatible transport)");
@@ -505,85 +320,39 @@ export class Client {
         this.headers = {
             "X-API-Key": this.apiKey,
             "Content-Type": "application/json",
-            // Browsers silently drop User-Agent (forbidden header) — harmless.
             "User-Agent": USER_AGENT,
         };
         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, 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
-        // the key travelled in cleartext to evil.example. `new URL()` knows the difference.
-        // (Python already used urlsplit here; this was the copy that did not.)
         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 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.
             host = new URL(this.base).hostname.toLowerCase().replace(/^\[|\]$/g, "");
         }
         catch {
-            host = ""; // unparseable → not loopback → warn, which is the safe direction
+            host = "";
         }
-        // Scheme compare is case-insensitive — `HTTP://` connects in plaintext too.
         if (/^http:\/\//i.test(this.base) && !LOOPBACK_HOSTS.has(host)) {
             console.warn("wontopos: baseUrl uses plain HTTP on a non-local host, so the API key travels unencrypted. Use https://.");
         }
-        // TypeScript `private` is erased at runtime: `apiKey` is an ordinary enumerable
-        // property, so `{...client}` copies it and `JSON.stringify({...client})` prints the
-        // key in full. The existing masking covers `JSON.stringify(client)` and
-        // `util.inspect(client)` — but spreading an object into a log record is the common
-        // shape in structured logging, and it went straight past both. Make the key and the
-        // prepared auth header non-enumerable so a spread cannot pick them up; they stay
-        // readable inside the class, which is all the code needs.
         Object.defineProperty(this, "apiKey", { enumerable: false });
         Object.defineProperty(this, "headers", { enumerable: false });
     }
-    /** A client whose key comes from `WONTOPOS_API_KEY` (or `WOS_API_KEY`) — keeps
-     * keys out of source code. Node/Bun/Deno-with-env only. */
     static fromEnv(opts = {}) {
         const env = globalThis?.process?.env;
-        // First env var with a NON-EMPTY value wins — an empty WONTOPOS_API_KEY must
-        // not shadow a valid WOS_API_KEY (`??` only skips null/undefined, not "").
         const key = [env?.WONTOPOS_API_KEY, env?.WOS_API_KEY].find((v) => v && v.trim());
         if (!key)
             throw new Error("set WONTOPOS_API_KEY (or WOS_API_KEY) in the environment");
-        // apiKey LAST so a stray apiKey in opts can't override the env key.
         return new Client({ ...opts, apiKey: key });
     }
-    /** Never expose the key: `JSON.stringify(client)` gets the redacted view. */
     toJSON() {
         return { baseUrl: this.base, model: this.model, userId: this.defaultUser, apiKey: maskKey(this.apiKey) };
     }
-    /** Never expose the key: Node's `console.log(client)` gets the redacted view. */
     [Symbol.for("nodejs.util.inspect.custom")]() {
         return `Client(${this.base}, model=${this.model}, userId=${this.defaultUser}, apiKey=${maskKey(this.apiKey)})`;
     }
-    /** Resolve a call's store: the explicit userId, else the client default. */
     uid(userId) {
-        // An OMITTED id means "use the client's default" — that is the documented shortcut.
-        // An id that was PASSED but is blank is a different thing: the caller computed a
-        // tenant id and got nothing. Falling back there writes one customer's memories into
-        // whatever store this client defaults to, silently. Omission is a choice; a blank
-        // string is a bug, and it should say so where it happened.
-        //
-        // The check is `typeof !== "string"`, not `!String(userId).trim()`. The old form
-        // only caught a blank STRING, and the value a failed lookup actually produces in
-        // JavaScript is `null` — `String(null)` is the truthy "null", so it sailed through
-        // the guard and then `null || default` sent the write to the client's default
-        // store. `0` (an integer primary key) did the same. Both are the exact outcome the
-        // guard was written to stop, and both were still silent.
-        //
-        // `undefined` alone means "omitted", because that is what an absent argument is.
-        if (userId !== undefined && (typeof userId !== "string" || !userId.trim())) {
-            throw new Error(`userId must be a non-blank string; got ${JSON.stringify(userId)}. Omit it to use the client's ` +
-                "default store, or pass a real store id — anything else would silently write into the default store.");
-        }
-        const id = userId || this.defaultUser;
+        assertUsableStoreId(userId);
+        const id = userId ?? this.defaultUser;
         warnIfStoreIdCollapses(id);
         return id;
     }
@@ -595,140 +364,77 @@ export class Client {
             model: this.model,
             userId: this.defaultUser,
             maxRetries: this.maxRetries,
-            // Carry the transport across clones. Without this, `withModel(...)` and
-            // 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,
         });
     }
-    /**
-     * A client that uses `model` (sent as `X-WOS-Model`). Use it to set the default
-     * (`new Client({ apiKey, model })`) or to override one call
-     * (`client.withModel("tablet-1").recall(...)`).
-     */
     withModel(model) {
         return this.clone({ model });
     }
-    /** A client bound to `userId` as its default store (everything else kept). */
     withUser(userId) {
+        if (userId === undefined) {
+            throw new Error("withUser() needs a store id. It was called with undefined — usually a lookup that " +
+                "found nothing. Use the client's own default instead of calling withUser at all.");
+        }
         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) {
         return this.clone({ timeoutMs });
     }
-    /** A client with a different retry budget (everything else kept). 0 disables retries. */
     withRetries(maxRetries) {
         return this.clone({ maxRetries });
     }
-    // ----- write -----
-    // `userId` is optional in every call below - omit it to use the client's default
-    // 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; 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
-     * of this exact write safe to repeat. */
     add(content, userId, metadata = {}, opts = {}) {
         const body = { user_id: this.uid(userId), content, metadata };
         if (opts.image !== undefined)
             body.image = normalizeImage(opts.image);
         return this.post("/api/v1/memory/store", body, opts.idempotencyKey);
     }
-    /** Alias of `add` — store one memory. Same surface as the Python SDK's `store`. */
     store(content, userId, metadata = {}, opts = {}) {
         return this.add(content, userId, metadata, opts);
     }
-    /** Store a conversation turn (user + assistant). Payload first, userId last — same shape as add/search. */
     addTurn(userMsg, assistantMsg, userId, opts = {}) {
         return this.post("/api/v1/memory/store-turn", { user_id: this.uid(userId), user_msg: userMsg, assistant_msg: assistantMsg }, opts.idempotencyKey);
     }
-    /** Bulk-ingest a large blob of text in one call. For backfilling.
-     *  The call most worth an `opts.idempotencyKey`: a backfill that dies halfway and is
-     *  re-run would otherwise re-ingest and re-bill the whole blob. */
     addBulk(content, userId, category = "general", timestamp, opts = {}) {
         const body = { user_id: this.uid(userId), content, category };
         if (timestamp)
             body.timestamp = timestamp;
         return this.post("/api/v1/memory/bulk-store", body, opts.idempotencyKey);
     }
-    /** Supersede an old memory with new content. Payload first, userId last — same shape as add/search. */
     update(oldMemoryId, newContent, userId, opts = {}) {
         return this.post("/api/v1/memory/supersede", { user_id: this.uid(userId), old_memory_id: oldMemoryId, new_content: newContent }, opts.idempotencyKey);
     }
-    // ----- read -----
-    /** Search a store's memories. Returns them most relevant first.
-     *
-     *  `limit` bounds `memories`, not the returned array. On a model that keeps the
-     *  assistant's own words separate (Scroll 1.2+) those come back as well, so the
-     *  array can hold more than `limit`. They were retrieved and billed either way;
-     *  dropping them would only hide what you already paid for. Size a prompt window
-     *  on the array you get back, not on `limit`. `searchSelf()` hands the two back
-     *  apart. */
     async search(query, userId, limit = 10, opts = {}) {
-        // Reserved fields win over ...opts: an app that forwards untrusted input as
-        // opts must not be able to override the store (user_id), query, or limit.
+        checkSearchOpts(opts);
         warnOnUnknownFilters(opts.filters);
         checkCount(limit, "limit");
-        const r = await this.post("/api/v1/memory/search", { ...opts, user_id: this.uid(userId), query, max_results: limit });
+        const { extra, ...known } = opts;
+        const r = await this.post("/api/v1/memory/search", { ...extra, ...known, user_id: this.uid(userId), query, max_results: limit });
         return mergeResults(r);
     }
-    /** Search a self-memory model (Scroll 1.2+): both fields from ONE call. Returns
-     * `{ memories, self_memories }` — `memories` is what others said and general
-     * memories, `self_memories` is the assistant's OWN words (stored with speaker
-     * "me"), kept apart so whoever reads them never confuses who said what. On a model
-     * that does not keep them apart, `self_memories` is `[]`. `userId` may be omitted. */
     async searchSelf(query, userId, limit = 10, opts = {}) {
+        checkSearchOpts(opts);
         warnOnUnknownFilters(opts.filters);
         checkCount(limit, "limit");
-        const r = await this.post("/api/v1/memory/search", { ...opts, user_id: this.uid(userId), query, max_results: limit });
+        const { extra, ...known } = opts;
+        const r = await this.post("/api/v1/memory/search", { ...extra, ...known, user_id: this.uid(userId), query, max_results: limit });
         return { memories: asRecords(r.memories), self_memories: asRecords(r.self_memories) };
     }
-    /**
-     * Search, and keep every field the answer came with.
-     *
-     * Same request as {@link Client.search} — reach for this one when the options make
-     * the merged array an incomplete answer:
-     *
-     *     const r = await mem.searchFull("the day we moved", "alice", 10,
-     *                                    { max_images: 3, verify: 2 });
-     *     r.images.length;   // the photos, which `search` drops
-     *     r.verify_used;     // how many re-ask passes actually ran (you are billed per pass)
-     *
-     * Both options need Tablet 2 or newer and are refused (403) on an older engine
-     * rather than accepted and ignored.
-     */
     async searchFull(query, userId, limit = 10, opts = {}) {
+        checkSearchOpts(opts);
         warnOnUnknownFilters(opts.filters);
         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.
+        const { extra, ...known } = opts;
+        const r = await this.post("/api/v1/memory/search", { ...extra, ...known, user_id: this.uid(userId), query, max_results: limit });
         return {
             ...r,
             memories: asRecords(r.memories),
@@ -736,14 +442,8 @@ export class Client {
             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. */
-    // `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 = {}) {
+        checkOpts(opts, KNOWN_RECALL_KEYS, "recall");
         const body = { user_id: this.uid(userId), query };
         if (opts.limit !== undefined) {
             checkCount(opts.limit, "limit");
@@ -755,63 +455,37 @@ export class Client {
         }
         return this.post("/api/v1/memory/recall", withForm(body, opts.form, opts.tz));
     }
-    /** Run a built-in engram ("deep_recall" | "timeline" | "gather" | "equilibrium" |
-     * "tone_stabilizer"; the service is the authority — an unknown name comes back with
-     * the list it accepts). Returns the merged result.
-     * `form`/`tz` render memory times (memoir/archive) on Scroll 1.2+, same as search/recall. */
     engram(name, query, userId, opts = {}) {
         return this.post("/api/v1/engram/run", withForm({ name, user_id: this.uid(userId), query }, opts.form, opts.tz));
     }
-    /** Recent conversation turns (short-term memory). */
     async history(userId) {
         const r = await this.post("/api/v1/memory/history", { user_id: this.uid(userId) });
         return asRecords(r.turns);
     }
-    /** Memory counts for a store: { total_memories, short_term_turns }. */
     stats(userId) {
         return this.post("/api/v1/memory/stats", { user_id: this.uid(userId) });
     }
-    /** 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 internal record id, or an
-     * invalidated memory rejects with `NotFoundError`. Pass `undefined` as `userId` for
-     * the default store — it is positional here, not omittable as it is in Python. */
+    async usage(days = 7) {
+        if (!Number.isInteger(days) || days < 1 || days > 365) {
+            throw new Error(`days must be an integer between 1 and 365, got ${days}.`);
+        }
+        return this.request("GET", `/api/v1/won/usage?days=${days}`);
+    }
     get(userId, memoryId) {
-        // Sync throw (same shape as `delete`), so a missing id fails loudly even
-        // when the caller forgets to await.
-        if (!memoryId || typeof memoryId !== "string") {
+        if (typeof memoryId !== "string" || !memoryId.trim()) {
             throw new Error("memoryId is required — the id that add/store or listMemories returned.");
         }
-        return this.post("/api/v1/memory/get", { user_id: this.uid(userId), memory_id: memoryId }).then((r) => asObj(r.memory));
-    }
-    /** List a store's stored memories — the text you stored, plus its metadata.
-     * Paginated: pass the returned `next_cursor` back as `cursor` for the next
-     * page; a `null` cursor means the last page. Use it to browse or export a store.
-     *
-     *     let cursor: string | null = null;
-     *     const all: Memory[] = [];
-     *     do {
-     *       const page = await mem.listMemories(undefined, { cursor: cursor ?? undefined });
-     *       all.push(...page.memories);
-     *       cursor = page.next_cursor;
-     *     } while (cursor);
-     */
+        return this.post("/api/v1/memory/get", { user_id: this.uid(userId), memory_id: memoryId.trim() }).then((r) => asObj(r.memory));
+    }
     listMemories(userId, opts = {}) {
         const body = { user_id: this.uid(userId), limit: opts.limit ?? 100 };
         if (opts.cursor)
             body.cursor = opts.cursor;
         return this.post("/api/v1/memory/list", body);
     }
-    /** Async-iterate every stored memory in a store, paging under the hood — no cursor
-     * bookkeeping. The text you stored and its metadata only.
-     *
-     *     for await (const m of mem.iterMemories()) console.log(m.id, m.content);
-     */
     async *iterMemories(userId, opts = {}) {
         let cursor;
         const seen = new Set();
-        // Backstop: the cursor-repeat guard catches a repeated cursor, but not a
-        // server that mints a FRESH cursor every page forever — bound the walk.
         for (let page = 0; page < MAX_PAGES; page++) {
             const p = await this.listMemories(userId, { limit: opts.pageSize ?? 100, cursor });
             for (const m of asRecords(p.memories))
@@ -825,71 +499,27 @@ export class Client {
         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). */
     async exportMemories(userId) {
         const out = [];
         for await (const m of this.iterMemories(userId))
             out.push(m);
         return out;
     }
-    // ----- images (Tablet 2 and newer) -----
-    /**
-     * 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
-     * uses more than 1568, so the extra pixels would be bytes nobody reads.
-     * Keep your own copy for the full-resolution file.
-     *
-     * The type is sniffed from the bytes themselves rather than from whatever the file
-     * 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);
-     *     const ext = contentType.split("/")[1];   // "webp" for a downscaled PNG
-     *     await fs.writeFile(`image.${ext}`, bytes);
-     */
     getImage(userId, memoryId) {
-        if (!memoryId || typeof memoryId !== "string") {
+        if (typeof memoryId !== "string" || !memoryId.trim()) {
             throw new Error("memoryId is required — the id that add/store or listImages returned.");
         }
-        return this.requestBytes("/api/v1/memory/image", { user_id: this.uid(userId), memory_id: memoryId });
-    }
-    /**
-     * Remove the PHOTO from a memory, keeping its text.
-     *
-     * Except when there is no text: an image stored without a caption *is* the memory, so
-     * deleting the image deletes it. That is the one case worth checking before you
-     * commit, which is what `preview` is for — it reports `memory_kept` and changes
-     * nothing.
-     *
-     *     const p = await mem.forgetImage(undefined, id, { preview: true });
-     *     if (p.memory_kept === false) { /* this would delete the whole memory *\/ }
-     */
+        return this.requestBytes("/api/v1/memory/image", { user_id: this.uid(userId), memory_id: memoryId.trim() });
+    }
     forgetImage(userId, memoryId, opts = {}) {
-        if (!memoryId || typeof memoryId !== "string") {
+        if (typeof memoryId !== "string" || !memoryId.trim()) {
             throw new Error("memoryId is required — the id of the memory whose image you want removed.");
         }
-        const body = { user_id: this.uid(userId), memory_id: memoryId };
+        const body = { user_id: this.uid(userId), memory_id: memoryId.trim() };
         if (opts.preview)
             body.preview = true;
         return this.request("DELETE", "/api/v1/memory/image", body);
     }
-    /**
-     * List a store's image memories, newest first, and count them.
-     *
-     * `count` is the TOTAL in the store, not the size of the page — so you can show
-     * "142 images" without walking every page. Paging is by cursor, not offset: hand
-     * `next_before` and `next_skip_ids` back as `before` / `skipIds`. The pair exists
-     * because several images can share a timestamp, and a timestamp alone would either
-     * repeat them or skip them.
-     */
     listImages(userId, opts = {}) {
         const body = { user_id: this.uid(userId) };
         if (opts.limit !== undefined)
@@ -900,28 +530,16 @@ export class Client {
             body.skip_ids = opts.skipIds;
         return this.post("/api/v1/memory/images", body);
     }
-    /** Async-iterate every image memory, paging under the hood. */
     async *iterImages(userId, opts = {}) {
         let before;
         let skipIds;
-        // Same repeat-cursor guard as `iterMemories`. A server that hands back the
-        // cursor it was just given would otherwise re-yield one page MAX_PAGES times,
-        // and the caller reads those repeats as more images. The page cap alone bounds
-        // the walk; it does not stop the duplicates.
         const seen = new Set();
         for (let page = 0; page < MAX_PAGES; page++) {
             const p = await this.listImages(userId, { limit: opts.pageSize, before, skipIds });
             for (const m of asRecords(p.images))
                 yield m;
-            // `return`, not `break`: the throw below is the MAX_PAGES backstop, and a
-            // `break` fell straight into it — so the ordinary end of a walk raised
-            // "the store did not end" on a store that had just ended. Python is safe
-            // here by using for/else and Rust by carrying an `ended` flag; TypeScript
-            // has neither, so the exit has to leave the function outright.
             if (!p.has_more || !p.next_before)
                 return;
-            // The cursor is the PAIR: several images can share a timestamp, so `before`
-            // alone repeats across pages legitimately.
             const key = `${p.next_before}|${(Array.isArray(p.next_skip_ids) ? p.next_skip_ids : []).join(",")}`;
             if (seen.has(key))
                 return;
@@ -932,49 +550,6 @@ export class Client {
         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 -----
-    /**
-     * How much of this store has been altered since it was written.
-     *
-     * This one is aimed at the MODEL, not at you. An assistant leaning on its own memory
-     * should be able to ask how far that memory has been edited underneath it — a store
-     * nobody has touched reads differently from one where a third of the facts were
-     * rewritten. Free, and it never reaches the retrieval path.
-     *
-     * Counts memories a transform touched (supersede, update, retract, image removed).
-     * Deletions are NOT counted: a deleted memory leaves nothing to count. Neither are
-     * 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
-     * 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.
-     *
-     * To see WHICH memories, ask for one side and page through it — at most 20 per call,
-     * and never both sides in one response:
-     *
-     * ```ts
-     * const { revised, unrevised, total } = await mem.revisions();   // numbers only
-     *
-     * let before: string | undefined, skipIds: string[] | undefined;
-     * for (;;) {
-     *   const p = await mem.revisions(undefined, { include: "revised", before, skipIds });
-     *   for (const m of p.memories ?? []) console.log(m.content);
-     *   if (!p.has_more || !p.next_before) break;
-     *   before = p.next_before;
-     *   skipIds = p.next_skip_ids;
-     * }
-     * ```
-     *
-     * 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
-     * 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.
-     */
     revisions(userId, opts = {}) {
         const body = {};
         if (opts.include !== undefined)
@@ -985,35 +560,15 @@ export class Client {
             body.before = opts.before;
         if (opts.skipIds !== undefined)
             body.skip_ids = opts.skipIds;
-        // `user_id` LAST, after the caller's fields — an `opts` spread that can land on top
-        // of it is how a client ends up reading another store. Same order as `search`.
         body.user_id = this.uid(userId);
         return this.post("/api/v1/won/revisions", body);
     }
-    /**
-     * The full chain of edits behind one memory, 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.
-     */
     lineage(userId, memoryId) {
-        if (!memoryId || typeof memoryId !== "string") {
+        if (typeof memoryId !== "string" || !memoryId.trim()) {
             throw new Error("memoryId is required — the memory whose history you want.");
         }
-        return this.post("/api/v1/memory/lineage", { user_id: this.uid(userId), memory_id: memoryId });
-    }
-    /**
-     * What one person said, newest first.
-     *
-     * `speaker` is the tag written at store time (`metadata.speaker`) — `"me"` for the
-     * assistant's own words, otherwise a person's name. Same cursor paging as
-     * `listImages`.
-     *
-     * `chunks` / `points_to_delete` report how many internal records a delete would
-     * actually remove — usually more than `returned`, and worth showing to whoever is
-     * about to confirm one.
-     */
+        return this.post("/api/v1/memory/lineage", { user_id: this.uid(userId), memory_id: memoryId.trim() });
+    }
     bySpeaker(speaker, userId, opts = {}) {
         if (!speaker || typeof speaker !== "string" || speaker.trim() === "") {
             throw new Error('speaker is required — "me" for the assistant, or a person\'s name.');
@@ -1027,150 +582,68 @@ export class Client {
             body.skip_ids = opts.skipIds;
         return this.post("/api/v1/memory/by-speaker", body);
     }
-    /** Check connectivity AND that the API key works. Resolves `true`, or rejects — an
-     * `AuthenticationError` (bad key), `PaymentRequiredError` (valid key but no card /
-     * depleted balance), or `APIConnectionError` (unreachable). Makes one metered request. */
     async ping() {
         await this.request("GET", "/api/v1/memory/collections");
         return true;
     }
-    // ----- models -----
-    /** Available models: `[{ id, name, available, memory }, ...]`. Needs no API key. */
     async listModels() {
         const data = await this.request("GET", "/api/v1/models");
         return asRecords(data.models);
     }
-    // ----- engrams -----
-    /**
-     * The engrams (and delivery forms) the selected model can actually run.
-     *
-     * 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.
-     *
-     *   const { engrams, forms } = await mem.listEngrams();
-     */
     async listEngrams() {
         const data = await this.request("GET", "/api/v1/engram");
         return {
             engrams: asRecords(data.engrams),
             forms: asRecords(data.forms),
-            // Present when the selected model has no engram support — the service explains
-            // rather than returning a bare empty list.
             note: typeof data.note === "string" ? data.note : undefined,
         };
     }
-    // ----- stores -----
-    /** Create a store — the `userId` you read and write under. Stores are explicit:
-     * a store must exist before you `add` to or `search` it, otherwise those calls
-     * return 404. Idempotent. Every account starts with a `default` store.
-     * Returns `{ user_id, status }` (`status` is `"created"` or `"exists"`). */
     createStore(userId) {
         return this.post("/api/v1/memory/collection", { user_id: this.uid(userId) });
     }
-    /** List your stores: `[{ user_id, created_at }, ...]` (`default` first). */
     async listStores() {
         const r = await this.request("GET", "/api/v1/memory/collections");
         return asRecords(r.collections);
     }
-    /** 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
-        // 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
+        warnIfStoreIdCollapses(userId);
         return this.request("DELETE", "/api/v1/memory/collection", { user_id: userId });
     }
-    // ----- speakers (who said it) -----
-    /** Register a person for this store. Speakers are explicit: register once, then
-     * store with `{ speaker }`. `"me"` (the assistant itself) never needs
-     * registration. A store registers up to 50 people to start. */
     addSpeaker(speaker, userId) {
         return this.post("/api/v1/memory/speakers", { user_id: this.uid(userId), speaker });
     }
-    /** The store's registered people, each with its memory count. */
     async listSpeakers(userId) {
         const r = await this.request("GET", `/api/v1/memory/speakers?user_id=${encodeURIComponent(this.uid(userId))}`);
-        // The spread came second, so a present-but-null `speakers` overwrote the default
-        // and the caller got null typed as an array. Every other list route goes through
-        // asRecords; this one did not.
         return { ...r, speakers: asRecords(r?.speakers) };
     }
-    /** Unregister a person. Their memories stay; the name tag goes. */
     removeSpeaker(speaker, userId) {
         return this.request("DELETE", "/api/v1/memory/speakers", { user_id: this.uid(userId), speaker });
     }
-    // ----- delete -----
-    /** Delete a single memory by id. Pass `undefined` as `userId` for the default
-     *  store — it is positional here, not omittable as it is in Python. */
     delete(userId, memoryId) {
-        // Guard: without a memory_id the API's forget endpoint means "delete the
-        // whole store". An undefined/"" slipping in here must never become a wipe.
-        //
-        // `.trim()` matters as much as the emptiness check: "   " is truthy, so 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.");
         }
         return this.post("/api/v1/memory/forget", { user_id: this.uid(userId), memory_id: memoryId.trim() });
     }
-    /** Delete ALL memories for a store (GDPR erase). `userId` is required on purpose -
-     * this is destructive, so it never falls back to the default store. */
     deleteAll(userId) {
         if (typeof userId !== "string" || !userId.trim())
             throw new Error("userId is required (a non-blank string) for deleteAll — anything else would wipe the default store.");
-        // These two take the store id directly instead of going through uid(), so the
-        // collision warning — the one that says `Alice.Smith` and `alice_smith` are ONE
-        // store — never fired on the two calls that DESTROY data. Erasing the wrong
-        // tenant's memories is exactly the outcome that warning exists to prevent.
         warnIfStoreIdCollapses(userId);
         return this.post("/api/v1/memory/forget", { user_id: userId });
     }
-    // ----- internal -----
     post(path, body, idempotencyKey) {
         return this.request("POST", path, body, idempotencyKey);
     }
-    /**
-     * One request that answers with BYTES rather than JSON.
-     *
-     * Only `/memory/image` does this, and it is why this cannot go through `request()`:
-     * that path reads the body as text and insists the result parses to a JSON object.
-     * Feeding it a JPEG would throw "invalid JSON in response" — a confusing error for a
-     * call that actually succeeded.
-     *
-     * Errors still arrive as JSON, so those are handed back to the normal machinery: on
-     * 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) {
@@ -1188,9 +661,6 @@ export class Client {
         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);
         }
@@ -1203,9 +673,6 @@ export class Client {
             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";
@@ -1213,15 +680,6 @@ export class Client {
             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"));
@@ -1244,12 +702,6 @@ export class Client {
         });
     }
     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
-        // server answering 429 — stats() made five requests, getImage() made one. The
-        // largest and most rate-limit-prone call in the SDK was the one that gave up
-        // immediately. The loop lives inside the function because honouring `Retry-After`
-        // means still holding the response.
         const attempts = this.maxRetries + 1;
         const deadlineAt = this.deadlineAt();
         for (let attempt = 0;; attempt++) {
@@ -1267,11 +719,6 @@ export class Client {
             catch (e) {
                 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 this.backoffSleep(this.backoffMs(attempt), deadlineAt);
                     continue;
@@ -1302,29 +749,22 @@ export class Client {
                             msg = err;
                     }
                     catch {
-                        /* keep raw text */
                     }
                     if (msg.length > MAX_ERR_MSG)
                         msg = msg.slice(0, MAX_ERR_MSG) + "…(truncated)";
                     throw errorFor(res.status, msg || `HTTP ${res.status}`);
                 }
-                // Translated, not raw. A timeout that fires while the body is streaming used to
-                // escape as `AbortError` — not a WosError, not an APIConnectionError — so a
-                // caller's `catch (e) { if (e instanceof WosError) … }` handled every JSON route
-                // and let this one through unclassified. The JSON path already translated it.
                 let buf;
                 try {
                     buf = await this.readCappedBytes(res);
                 }
                 catch (e) {
                     if (e?.name === "AbortError" || att.signal.aborted) {
-                        throw new APIConnectionError(0, `request timed out after ${this.timeoutMs}ms`);
+                        throw new APIConnectionError(0, this.abortMessage(att.why()));
                     }
                     throw e;
                 }
                 if (buf.byteLength === 0) {
-                    // An empty 200 would otherwise read as "here is your image" and write a
-                    // zero-byte file — indistinguishable from an image we lost.
                     throw new WosError(res.status, "empty image body — the service returned no bytes");
                 }
                 return { bytes: buf, contentType: res.headers.get("content-type") ?? "application/octet-stream" };
@@ -1334,16 +774,7 @@ export class Client {
             }
         }
     }
-    /** Validate an idempotency key BEFORE the network. The API answers a malformed
-     *  key with a 400, which on a retry path reads as "my write failed" when in fact
-     *  it was never attempted — cheaper and clearer to reject it here. */
     idemHeader(key) {
-        // `=== undefined` let `null` through: RegExp.test stringifies its argument, so
-        // `null` became the literal key "null" and passed the format check. A key read
-        // from JSON or a database row arrives as null, not undefined, and every write on
-        // that path then shared one key — the second onward returned the first response
-        // and stored nothing. Python guards with `is None`; Rust's Option makes it
-        // unrepresentable.
         if (key === undefined || key === null)
             return undefined;
         if (!IDEMPOTENCY_KEY_RE.test(key)) {
@@ -1351,40 +782,26 @@ export class Client {
         }
         return { "Idempotency-Key": key };
     }
-    /** Seconds→ms to sleep before retry `attempt` (0-based). Honors Retry-After. */
     backoffMs(attempt, retryAfter) {
         if (retryAfter) {
             const s = Number(retryAfter);
             if (Number.isFinite(s) && s >= 0)
                 return Math.min(30_000, s * 1000);
-            // HTTP-date form (RFC 9110), e.g. "Wed, 21 Oct 2015 07:28:00 GMT".
             const t = Date.parse(retryAfter);
             if (Number.isFinite(t))
                 return Math.min(30_000, Math.max(0, t - Date.now()));
         }
         return Math.min(8_000, 500 * 2 ** attempt) + Math.random() * 250;
     }
-    /** Read the body with a hard size cap, so a broken/hostile endpoint can't
-     * make the process buffer gigabytes. */
     async readCapped(res) {
         return new TextDecoder().decode(await this.readCappedBytes(res));
     }
-    /** The same cap, for a body that is not text.
-     *
-     * `arrayBuffer()` would buffer whatever arrives. The cap exists for a hostile or
-     * broken `baseUrl`, and an endpoint that returns megabytes is where that costs the
-     * most. One implementation, two callers, so they cannot drift. */
     async readCappedBytes(res) {
         const cl = res.headers.get("content-length");
         if (cl && Number(cl) > MAX_RESPONSE_BYTES) {
             throw new WosError(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
-            // in front of it — which a server simply omits. Reachable through the documented
-            // `fetch` seam (test doubles, polyfills, wrappers that rebuild the Response),
-            // and the option's own doc promises "the size cap still applies". Measured: a
-            // body-less Response with no content-length buffered 73MB past the 64MB cap.
             const buf = new Uint8Array(await res.arrayBuffer());
             if (buf.byteLength > MAX_RESPONSE_BYTES) {
                 throw new WosError(res.status, `response too large (${buf.byteLength} bytes) — refusing it`);
@@ -1416,10 +833,16 @@ export class Client {
     async request(method, path, body, idempotencyKey) {
         const extraHeaders = this.idemHeader(idempotencyKey);
         const attempts = this.maxRetries + 1;
-        // 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();
+        let payload;
+        try {
+            payload = body === undefined ? undefined : JSON.stringify(body);
+        }
+        catch (e) {
+            throw new Error(`request body could not be serialized: ${e instanceof Error ? e.message : String(e)}. ` +
+                "Pass plain JSON values — an ORM entity, a BigInt or a circular reference cannot be sent.");
+        }
         for (let attempt = 0; attempt < attempts; attempt++) {
             const start = Date.now();
             const att = this.beginAttempt(deadlineAt);
@@ -1428,21 +851,14 @@ export class Client {
                 res = await this.fetchImpl(`${this.base}${path}`, {
                     method,
                     headers: extraHeaders ? { ...this.headers, ...extraHeaders } : this.headers,
-                    body: body === undefined ? undefined : JSON.stringify(body),
+                    body: payload,
                     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) {
                 att.clear();
-                // Timeouts are ambiguous (the write may have landed) — don't retry those.
                 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
-                // a POST may already have stored + billed server-side.
                 const safe = IDEMPOTENT_METHODS.has(method.toUpperCase()) || isConnectFailure(e);
                 if (!timedOut && safe && attempt + 1 < attempts) {
                     const delay = this.backoffMs(attempt);
@@ -1465,25 +881,20 @@ export class Client {
             }
             if ((res.status >= 300 && res.status < 400) || res.type === "opaqueredirect") {
                 att.clear();
-                void res.body?.cancel(); // release the stream — otherwise the connection leaks
+                void res.body?.cancel();
                 throw new WosError(res.status, "unexpected redirect — refused (the API key never follows a redirect). Check baseUrl: exact host, https://.");
             }
             this._rateLimit = parseRateLimit(res.headers) ?? this._rateLimit;
-            // Keep the abort timer alive THROUGH the body read: fetch resolves on
-            // headers, so a server that sends headers then trickles/hangs the body
-            // would otherwise stall forever. An abort mid-body surfaces as a timeout.
             let text;
             try {
                 text = await this.readCapped(res);
             }
             catch (e) {
                 if (e?.name === "AbortError" || att.signal.aborted) {
-                    throw new APIConnectionError(0, `request timed out after ${this.timeoutMs}ms`);
+                    throw new APIConnectionError(0, this.abortMessage(att.why()));
                 }
                 if (e instanceof WosError)
-                    throw e; // the size cap — already the right error
-                // A drop while READING the body is a transport failure — surface it as
-                // APIConnectionError, not a raw fetch TypeError. Ambiguous, never retried.
+                    throw e;
                 throw new APIConnectionError(0, `network error: ${e?.message ?? e}`);
             }
             finally {
@@ -1491,9 +902,6 @@ export class Client {
             }
             logDebug(`${method} ${logPath} -> ${res.status} in ${Date.now() - start}ms (attempt ${attempt + 1}/${attempts})`);
             if (!res.ok) {
-                // Server returns either Anthropic-style envelope
-                //   {"type":"error","error":{"type":...,"message":...,"request_id":...}}
-                // or simple {"error":"reason"}. Fall back to raw text.
                 let msg = text;
                 let requestId;
                 try {
@@ -1512,17 +920,11 @@ export class Client {
                     }
                 }
                 catch {
-                    /* keep raw text */
                 }
-                // Cap the FINAL message (a string `error` field can be as huge as the body),
-                // so a hostile server can't turn our exception/log into a giant string.
                 if (typeof msg === "string" && msg.length > MAX_ERR_MSG)
                     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. 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 {};
@@ -1533,34 +935,19 @@ export class Client {
                 data = JSON.parse(text);
             }
             catch (e) {
-                // A 2xx with a corrupt body is a real failure — surface it, don't leak
-                // a raw SyntaxError (parity with the Rust SDK).
                 throw new WosError(res.status, `invalid JSON in response: ${e?.message ?? e}`);
             }
-            // Enforce a JSON OBJECT: every method reads the result with `.field`, so a
-            // body that parses to null / a number / a string / an array (a broken or
-            // hostile server) must be a clean WosError, not a `null.memories` TypeError.
             if (data === null || typeof data !== "object" || Array.isArray(data)) {
                 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}`);
             }
-            // 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?
-            //
-            // 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 Error("retries exhausted"); // unreachable; keeps the compiler happy
+        throw new Error("retries exhausted");
     }
 }
-/** Back-compat alias: older code used `WME`. */
 export const WME = Client;
 export default Client;