wontopos 2.2.35 → 2.2.36

package/dist/cjs/wontopos.js

@@ -0,0 +1,1582 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WME = exports.Client = exports.ServerError = exports.RateLimitError = exports.ConflictError = exports.NotFoundError = exports.PermissionDeniedError = exports.PaymentRequiredError = exports.AuthenticationError = exports.BadRequestError = exports.APIConnectionError = exports.WosError = exports.CONTEXT_LIMIT_MAX = exports.CONTEXT_LIMIT_MIN = exports.SEARCH_LIMIT_MAX = exports.SEARCH_LIMIT_MIN = void 0;
+exports._resetStoreIdWarnings = _resetStoreIdWarnings;
+exports._resetFilterWarnings = _resetFilterWarnings;
+const VERSION = "2.2.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 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") {
+        console.error(`wontopos: ${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. */
+const WARNED_FILTER_KEYS_MAX = 1024;
+const warnedStoreIds = new Set();
+function warnIfStoreIdCollapses(id) {
+    if (!id || warnedStoreIds.has(id))
+        return;
+    const normalized = normalizeStoreId(id);
+    if (normalized === id)
+        return;
+    warnedStoreIds.add(id);
+    while (warnedStoreIds.size > WARNED_STORE_IDS_MAX) {
+        const oldest = warnedStoreIds.values().next().value;
+        if (oldest === undefined)
+            break;
+        warnedStoreIds.delete(oldest);
+    }
+    console.warn(`wontopos: store id ${JSON.stringify(id)} is stored as ${JSON.stringify(normalized)} ` +
+        `(lowercased, and anything outside [a-z0-9_] becomes "_"). Ids that differ only by case or ` +
+        `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. */
+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;
+exports.SEARCH_LIMIT_MIN = 5;
+exports.SEARCH_LIMIT_MAX = 20;
+/** `recall`'s surrounding-context count. 0 to 20 inclusive; 0 attaches none. */
+exports.CONTEXT_LIMIT_MIN = 0;
+exports.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 < exports.SEARCH_LIMIT_MIN || limit > exports.SEARCH_LIMIT_MAX) {
+        throw new Error(`${name} must be an integer between ${exports.SEARCH_LIMIT_MIN} and ${exports.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 < exports.CONTEXT_LIMIT_MIN || n > exports.CONTEXT_LIMIT_MAX) {
+        throw new Error(`context_limit must be an integer between ${exports.CONTEXT_LIMIT_MIN} and ${exports.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>' }.");
+    }
+    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.");
+    const out = { data };
+    if (image.reference !== undefined)
+        out.reference = image.reference;
+    if (image.taken_at !== undefined)
+        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",
+    "EAI_AGAIN",
+    "EHOSTUNREACH",
+    "ENETUNREACH",
+    "ENETDOWN",
+    "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++) {
+        const cur = stack.pop();
+        if (!cur || typeof cur !== "object")
+            continue;
+        if (typeof cur.code === "string" && CONNECT_FAIL_CODES.has(cur.code))
+            return true;
+        if (cur.cause)
+            stack.push(cur.cause);
+        if (Array.isArray(cur.errors))
+            stack.push(...cur.errors.slice(0, 8));
+    }
+    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)}` : "***";
+}
+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
+        const n = Number(v);
+        return Number.isFinite(n) ? n : null;
+    };
+    const limit = num("X-RateLimit-Limit");
+    const remaining = num("X-RateLimit-Remaining");
+    const reset = num("X-RateLimit-Reset");
+    if (limit === null && remaining === null && reset === null)
+        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);
+    if (mine.length === 0)
+        return main;
+    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;
+    if (tz !== undefined)
+        body.tz = tz;
+    return body;
+}
+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.status = status;
+        this.requestId = requestId;
+    }
+}
+exports.WosError = WosError;
+// 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. */
+class APIConnectionError extends WosError {
+}
+exports.APIConnectionError = APIConnectionError;
+/** 400 — the request was malformed (bad arguments). */
+class BadRequestError extends WosError {
+}
+exports.BadRequestError = BadRequestError;
+/** 401 — the API key is missing, wrong, or revoked. */
+class AuthenticationError extends WosError {
+}
+exports.AuthenticationError = AuthenticationError;
+/** 402 — no card on file or the balance is depleted. Top up to continue. */
+class PaymentRequiredError extends WosError {
+}
+exports.PaymentRequiredError = PaymentRequiredError;
+/** 403 — the key/model isn't allowed to do this. */
+class PermissionDeniedError extends WosError {
+}
+exports.PermissionDeniedError = PermissionDeniedError;
+/** 404 — the store or resource doesn't exist (create the store first). */
+class NotFoundError extends WosError {
+}
+exports.NotFoundError = NotFoundError;
+/** 409 — a concurrent write to the same store. Retry. */
+class ConflictError extends WosError {
+}
+exports.ConflictError = ConflictError;
+/** 429 — too many requests. Back off and retry (the client already retries these). */
+class RateLimitError extends WosError {
+}
+exports.RateLimitError = RateLimitError;
+/**
+ * 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.
+ */
+class ServerError extends WosError {
+}
+exports.ServerError = ServerError;
+const STATUS_ERRORS = {
+    400: BadRequestError,
+    401: AuthenticationError,
+    402: PaymentRequiredError,
+    403: PermissionDeniedError,
+    404: NotFoundError,
+    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",
+    "event_to",
+    "time_from",
+    "time_to",
+    "min_importance",
+]);
+const warnedFilterKeys = new Set();
+function warnOnUnknownFilters(filters) {
+    if (!filters || typeof filters !== "object" || Array.isArray(filters))
+        return;
+    for (const k of Object.keys(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)
+                break;
+            warnedFilterKeys.delete(oldest);
+        }
+        console.warn(`wontopos: unknown search filter ${JSON.stringify(k)} — the API drops keys it does not know, ` +
+            `so this filter has NO effect and the search is wider than you think. ` +
+            `Known keys: ${[...KNOWN_FILTER_KEYS].join(", ")}.`);
+    }
+}
+/** Test hook — the warn-once set is process-global by design. */
+function _resetFilterWarnings() {
+    warnedFilterKeys.clear();
+}
+const DEFAULT_USER = "default";
+/** Wontopos memory client. Store and recall memories, isolated per `userId`. */
+class Client {
+    base;
+    headers;
+    timeoutMs;
+    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;
+    /** 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");
+        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.
+        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)");
+        }
+        this.fetchImpl = f ?? (globalThis.fetch ? globalThis.fetch.bind(globalThis) : undefined);
+        if (typeof this.fetchImpl !== "function") {
+            throw new Error("no fetch available in this runtime — pass one as `fetch` (Node 18+ has it built in; older Node needs undici)");
+        }
+        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
+        }
+        // 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;
+        warnIfStoreIdCollapses(id);
+        return id;
+    }
+    clone(overrides) {
+        return new Client({
+            apiKey: this.apiKey,
+            baseUrl: this.base,
+            timeoutMs: this.timeoutMs,
+            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) {
+        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.
+        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 });
+        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 = {}) {
+        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 });
+        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 = {}) {
+        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.
+        return {
+            ...r,
+            memories: asRecords(r.memories),
+            self_memories: asRecords(r.self_memories),
+            images: asRecords(r.images),
+        };
+    }
+    /** One-call LLM context: short-term turns + long-term matches + surrounding context.
+     * `form` ("memoir"/"archive", Scroll 1.2+) renders each long-term memory's time in
+     * that form; `tz` is your UTC-offset hours for that rendering. */
+    // `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) {
+            checkCount(opts.limit, "limit");
+            body.limit = opts.limit;
+        }
+        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" |
+     * "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. */
+    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") {
+            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);
+     */
+    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))
+                yield m;
+            const next = p.next_cursor ?? undefined;
+            if (!next || seen.has(next))
+                return;
+            seen.add(next);
+            cursor = next;
+        }
+        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") {
+            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 *\/ }
+     */
+    forgetImage(userId, memoryId, opts = {}) {
+        if (!memoryId || typeof memoryId !== "string") {
+            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 };
+        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)
+            body.limit = opts.limit;
+        if (opts.before !== undefined)
+            body.before = opts.before;
+        if (opts.skipIds !== undefined)
+            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;
+            seen.add(key);
+            before = p.next_before;
+            skipIds = Array.isArray(p.next_skip_ids) ? p.next_skip_ids : undefined;
+        }
+        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)
+            body.include = opts.include;
+        if (opts.limit !== undefined)
+            body.limit = opts.limit;
+        if (opts.before !== undefined)
+            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") {
+            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.
+     */
+    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.');
+        }
+        const body = { user_id: this.uid(userId), speaker: speaker.trim() };
+        if (opts.limit !== undefined)
+            body.limit = opts.limit;
+        if (opts.before !== undefined)
+            body.before = opts.before;
+        if (opts.skipIds !== undefined)
+            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
+        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) {
+                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
+        // 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++) {
+            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: att.signal,
+                    redirect: "manual",
+                });
+            }
+            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;
+                }
+                throw new APIConnectionError(0, timedOut ? this.abortMessage(att.why()) : `network error: ${e?.message ?? e}`);
+            }
+            try {
+                this._rateLimit = parseRateLimit(res.headers) ?? this._rateLimit;
+                if ((res.status >= 300 && res.status < 400) || res.type === "opaqueredirect") {
+                    void res.body?.cancel();
+                    throw errorFor(res.status, "the API answered with a redirect; refusing to follow it");
+                }
+                if (!res.ok) {
+                    if (RETRY_ALWAYS.has(res.status) && attempt + 1 < attempts) {
+                        const retryAfter = res.headers.get("Retry-After");
+                        void res.body?.cancel();
+                        att.clear();
+                        await this.backoffSleep(this.backoffMs(attempt, retryAfter), deadlineAt);
+                        continue;
+                    }
+                    let msg = await this.readCapped(res).catch(() => "");
+                    try {
+                        const data = JSON.parse(msg);
+                        const err = data?.error;
+                        if (err && typeof err === "object")
+                            msg = err.message ?? err.type ?? msg;
+                        else if (typeof err === "string")
+                            msg = err;
+                    }
+                    catch {
+                        /* keep raw text */
+                    }
+                    if (msg.length > MAX_ERR_MSG)
+                        msg = msg.slice(0, MAX_ERR_MSG) + "…(truncated)";
+                    throw errorFor(res.status, msg || `HTTP ${res.status}`);
+                }
+                // Translated, not raw. A timeout that fires while the body is streaming used to
+                // escape as `AbortError` — not a WosError, not an APIConnectionError — so a
+                // caller's `catch (e) { if (e instanceof WosError) … }` handled every JSON route
+                // and let this one through unclassified. The JSON path already translated it.
+                let buf;
+                try {
+                    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 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" };
+            }
+            finally {
+                att.clear();
+            }
+        }
+    }
+    /** 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)) {
+            throw new Error(`invalid idempotencyKey: ${JSON.stringify(key)} — 1-128 chars of [A-Za-z0-9._:-]`);
+        }
+        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`);
+            }
+            return buf;
+        }
+        const reader = res.body.getReader();
+        const parts = [];
+        let size = 0;
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            size += value.byteLength;
+            if (size > MAX_RESPONSE_BYTES) {
+                void reader.cancel();
+                throw new WosError(res.status, "response too large — refusing to buffer it");
+            }
+            parts.push(value);
+        }
+        const buf = new Uint8Array(size);
+        let off = 0;
+        for (const p of parts) {
+            buf.set(p, off);
+            off += p.byteLength;
+        }
+        return buf;
+    }
+    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();
+        for (let attempt = 0; attempt < attempts; attempt++) {
+            const start = Date.now();
+            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: 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);
+                    logDebug(`${method} ${logPath}: ${e?.code ?? e?.name ?? "network error"} — retrying in ${delay}ms (attempt ${attempt + 1}/${attempts})`);
+                    await this.backoffSleep(delay, deadlineAt);
+                    continue;
+                }
+                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) {
+                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 this.backoffSleep(delay, deadlineAt);
+                continue;
+            }
+            if ((res.status >= 300 && res.status < 400) || res.type === "opaqueredirect") {
+                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://.");
+            }
+            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`);
+                }
+                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 new APIConnectionError(0, `network error: ${e?.message ?? e}`);
+            }
+            finally {
+                att.clear();
+            }
+            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 {
+                    const data = JSON.parse(text);
+                    if (data && typeof data === "object") {
+                        const err = data.error;
+                        if (err && typeof err === "object") {
+                            msg = err.message ?? err.type ?? msg;
+                            if (typeof err.request_id === "string")
+                                requestId = err.request_id;
+                        }
+                        else if (typeof err === "string")
+                            msg = err;
+                        else if (typeof data.message === "string")
+                            msg = data.message;
+                    }
+                }
+                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 {};
+                throw new WosError(res.status, "empty response body — expected a JSON object");
+            }
+            let data;
+            try {
+                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
+    }
+}
+exports.Client = Client;
+/** Back-compat alias: older code used `WME`. */
+exports.WME = Client;
+exports.default = Client;