wontopos 2.2.23 → 2.2.25

package/dist/wontopos.d.ts

@@ -37,6 +37,8 @@
  * runtime's (never disabled by this SDK; Node 18+ floors TLS at 1.2). Prefer
  * `Client.fromEnv()` over keys in source code.
  */
+/** Test hook — the warn-once set is process-global by design. */
+export declare function _resetStoreIdWarnings(): void;
 /** Quota from a response's `X-RateLimit-*` headers, or `null` if absent. */
 export interface RateLimit {
     limit: number | null;
@@ -73,7 +75,18 @@ export declare class ConflictError extends WosError {
 /** 429 — too many requests. Back off and retry (the client already retries these). */
 export declare class RateLimitError extends WosError {
 }
-/** 5xx — the service failed. Safe to retry. */
+/**
+ * 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. This class used to say "safe to retry" for the whole 5xx range,
+ * which sent callers into a loop that could not end.
+ */
 export declare class ServerError extends WosError {
 }
 export interface Usage {
@@ -107,9 +120,24 @@ export interface Memory {
 /** `add` / `store` → `{ id, status }` (`status: "stored" | "stored (async)" | "duplicate"`). */
 export interface StoreResult {
     id?: string;
+    /** `"stored"`, or `"duplicate"` when nothing was saved. */
     status?: string;
+    /**
+     * Present when `status` is `"duplicate"`: the id of the memory this write collided with.
+     *
+     * The match is by MEANING, not by exact text — a genuinely new fact that only varies a
+     * detail of one already stored ("allergic to shellfish" next to "allergic to peanuts")
+     * lands here too. So a duplicate is not always a harmless no-op: read this id, and
+     * either merge the two into one sentence or `update()` the existing memory. Without it
+     * a dropped write gave the caller nothing to act on.
+     */
+    duplicate_of?: string;
     /** Present when the store was a duplicate and something (e.g. a speaker tag) was dropped. */
     note?: string;
+    /** `true` when this response was REPLAYED from a previous request with the same
+     *  `idempotencyKey` — nothing new was stored. Absent on a fresh write. Read it to
+     *  tell "my retry landed" from "my retry was a no-op". */
+    replayed?: boolean;
     [key: string]: unknown;
 }
 /** `addTurn` / `addBulk` / `delete` / `deleteAll` → `{ status }`. */
@@ -183,10 +211,28 @@ export interface ModelInfo {
     /** "shared" — reads the common memory pool; "isolated" — its own dedicated store. */
     memory: "shared" | "isolated";
 }
+/** One entry of the engram / delivery-form catalogue (`listEngrams`). */
+export interface EngramInfo {
+    name: string;
+    description: string;
+    [key: string]: unknown;
+}
+/** `listEngrams` → what the SELECTED model can run. `forms` is empty on models
+ *  without delivery forms; `note` explains an empty `engrams`. */
+export interface EngramCatalog {
+    engrams: EngramInfo[];
+    forms: EngramInfo[];
+    note?: string;
+}
 /** `createStore` / `deleteStore` → `{ user_id, status }`. */
 export interface StoreOpResult {
+    /** The store id the API actually used — NOT necessarily the one you sent.
+     *  Ids are normalized (see the `note`), so compare this against your input. */
     user_id?: string;
     status?: string;
+    /** Present when the API changed your id, explaining how. Read it: two of your
+     *  end users can land in one store if their ids differ only by punctuation. */
+    note?: string;
     [key: string]: unknown;
 }
 export interface StoreInfo {
@@ -215,6 +261,29 @@ export interface SpeakersList {
     limit?: number;
     [key: string]: unknown;
 }
+/**
+ * Narrow a search to part of a store — applied BEFORE ranking, so the results are
+ * the best matches *within* the filter, not a filtered top-N.
+ *
+ * Retrieval itself stays purely semantic (no keyword matching), so these behave
+ * identically in every language. Unlisted keys are dropped by the API rather than
+ * rejected, so a typo silently widens the search — spell them exactly.
+ */
+export interface SearchFilters {
+    /** Only these categories (the `category` you see on `listMemories` results). */
+    categories?: string[];
+    /** Ingestion-time window, as the API stores it. Plain strings, matched as given. */
+    time_from?: string;
+    time_to?: string;
+    /** WHEN THE CONTENT HAPPENED (`metadata.event_date`), not when it was written —
+     *  this is the one you usually want. RFC3339, or a plain `YYYY-MM-DD`. */
+    event_from?: string;
+    event_to?: string;
+    /** Drop matches the engine scored below this importance (0–1). */
+    min_importance?: number;
+}
+/** Test hook — the warn-once set is process-global by design. */
+export declare function _resetFilterWarnings(): void;
 /** Known `search` options; extra fields pass through to the API untouched. */
 export interface SearchOptions {
     /** Recall caching: repeated/extended queries within the TTL bill at 0.1×. */
@@ -223,8 +292,29 @@ export interface SearchOptions {
     };
     /** Recall only this person's words ("me" or a registered name). */
     speaker?: string;
+    /** Restrict the search to part of the store — see {@link SearchFilters}. */
+    filters?: SearchFilters;
     [key: string]: unknown;
 }
+/**
+ * Per-call options for a write.
+ *
+ * `idempotencyKey` makes repeating THIS EXACT write safe: the API replays the first
+ * response instead of storing again, for 10 minutes, and answers 422 if the same key
+ * arrives with a different body. Use it when a retry is your own (a job that died and
+ * was re-run, a queue that redelivers) — the SDK never retries writes by itself,
+ * because without a key it cannot know whether the first attempt landed.
+ *
+ * The key must be UNIQUE PER LOGICAL WRITE — derive it from the thing being stored
+ * (`` `import:${row.id}` ``), never a constant, or the second write replays the first
+ * and is silently lost. Format: 1-128 chars of `[A-Za-z0-9._:-]`, checked locally.
+ *
+ * The window is in-memory on the API, so a deploy or restart clears it early. It is a
+ * guard against a retry storm, not a durable ledger.
+ */
+export interface WriteOptions {
+    idempotencyKey?: string;
+}
 export interface ClientOptions {
     apiKey: string;
     /** API base URL (defaults to the hosted service). */
@@ -284,17 +374,25 @@ export declare class Client {
     withTimeout(timeoutMs: number): Client;
     /** A client with a different retry budget (everything else kept). 0 disables retries. */
     withRetries(maxRetries: number): Client;
-    /** Store one memory. `metadata` optional (e.g. { event_date: "2026-03-01T00:00:00Z" } — RFC3339).
-     * `metadata.speaker`: "me" = the assistant's own words, or a person's name (up to 50 per store). */
-    add(content: string, userId?: string, metadata?: Record<string, unknown>): Promise<StoreResult>;
+    /** Store one memory. `metadata` optional — e.g. `{ event_date: "2026-03-01" }` for when the
+     * content actually happened. A plain date works (read as UTC midnight); a full RFC3339
+     * timestamp also works. The API used to demand the full form and answered a bare date with
+     * an opaque 400, which is why older examples here show the long one.
+     * `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: string, userId?: string, metadata?: Record<string, unknown>, opts?: WriteOptions): Promise<StoreResult>;
     /** Alias of `add` — store one memory. Same surface as the Python SDK's `store`. */
-    store(content: string, userId?: string, metadata?: Record<string, unknown>): Promise<StoreResult>;
+    store(content: string, userId?: string, metadata?: Record<string, unknown>, opts?: WriteOptions): Promise<StoreResult>;
     /** Store a conversation turn (user + assistant). Payload first, userId last — same shape as add/search. */
-    addTurn(userMsg: string, assistantMsg: string, userId?: string): Promise<StatusResult>;
-    /** Bulk-ingest a large blob of text (chunked + embedded server-side). For backfilling. */
-    addBulk(content: string, userId?: string, category?: string, timestamp?: string): Promise<StatusResult>;
+    addTurn(userMsg: string, assistantMsg: string, userId?: string, opts?: WriteOptions): Promise<StatusResult>;
+    /** Bulk-ingest a large blob of text (chunked + embedded server-side). For backfilling.
+     *  The call most worth an `opts.idempotencyKey`: a backfill that dies halfway and is
+     *  re-run would otherwise re-chunk and re-bill the whole blob. */
+    addBulk(content: string, userId?: string, category?: string, timestamp?: string, opts?: WriteOptions): Promise<StatusResult>;
     /** Supersede an old memory with new content. Payload first, userId last — same shape as add/search. */
-    update(oldMemoryId: string, newContent: string, userId?: string): Promise<UpdateResult>;
+    update(oldMemoryId: string, newContent: string, userId?: string, opts?: WriteOptions): Promise<UpdateResult>;
     /** Semantic search over a store's memories. Returns memories, most relevant first. */
     search(query: string, userId?: string, limit?: number, opts?: SearchOptions): Promise<Memory[]>;
     /** Search a self-memory model (Scroll 1.2+): both lanes from ONE call. Returns
@@ -357,6 +455,19 @@ export declare class Client {
     ping(): Promise<boolean>;
     /** Available models: `[{ id, name, available, memory }, ...]`. Needs no API key. */
     listModels(): Promise<ModelInfo[]>;
+    /**
+     * The engrams (and delivery forms) the selected model can actually run.
+     *
+     * `engram()` could always RUN one, but there was no way to ASK what exists — so a
+     * caller had to hard-code names from the docs, and every engram we shipped after
+     * their code was written stayed invisible to them. The MCP server hit exactly this
+     * and stopped hard-coding for the same reason. The service is the authority: what
+     * 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();
+     */
+    listEngrams(): Promise<EngramCatalog>;
     /** 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.
@@ -380,6 +491,10 @@ export declare class Client {
      * this is destructive, so it never falls back to the default store. */
     deleteAll(userId: string): Promise<StatusResult>;
     private post;
+    /** 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. */
+    private idemHeader;
     /** Seconds→ms to sleep before retry `attempt` (0-based). Honors Retry-After. */
     private backoffMs;
     /** Read the body with a hard size cap, so a broken/hostile endpoint can't

package/dist/wontopos.js

@@ -37,7 +37,7 @@
  * runtime's (never disabled by this SDK; Node 18+ floors TLS at 1.2). Prefer
  * `Client.fromEnv()` over keys in source code.
  */
-const VERSION = "2.2.23";
+const VERSION = "2.2.25";
 /** 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). */
@@ -71,6 +71,46 @@ const MAX_RESPONSE_BYTES = 64 * 1024 * 1024;
 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, "_");
+}
+const warnedStoreIds = new Set();
+function warnIfStoreIdCollapses(id) {
+    if (!id || warnedStoreIds.has(id))
+        return;
+    const normalized = normalizeStoreId(id);
+    if (normalized === id)
+        return;
+    warnedStoreIds.add(id);
+    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. */
+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. */
 const MAX_PAGES = 1_000_000;
 /** Error codes that only occur while ESTABLISHING a connection — the request
@@ -202,7 +242,18 @@ 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. Safe to retry. */
+/**
+ * 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. This class used to say "safe to retry" for the whole 5xx range,
+ * which sent callers into a loop that could not end.
+ */
 export class ServerError extends WosError {
 }
 const STATUS_ERRORS = {
@@ -222,6 +273,34 @@ function errorFor(status, message, requestId) {
         : 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);
+        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. */
+export function _resetFilterWarnings() {
+    warnedFilterKeys.clear();
+}
 const DEFAULT_USER = "default";
 /** Wontopos memory client. Store and recall memories, isolated per `userId`. */
 export class Client {
@@ -304,7 +383,9 @@ export class Client {
     }
     /** Resolve a call's store: the explicit userId, else the client default. */
     uid(userId) {
-        return userId || this.defaultUser;
+        const id = userId || this.defaultUser;
+        warnIfStoreIdCollapses(id);
+        return id;
     }
     clone(overrides) {
         return new Client({
@@ -341,35 +422,44 @@ export class Client {
     // ----- 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-01T00:00:00Z" } — RFC3339).
-     * `metadata.speaker`: "me" = the assistant's own words, or a person's name (up to 50 per store). */
-    add(content, userId, metadata = {}) {
-        return this.post("/api/v1/memory/store", { user_id: this.uid(userId), content, metadata });
+    /** Store one memory. `metadata` optional — e.g. `{ event_date: "2026-03-01" }` for when the
+     * content actually happened. A plain date works (read as UTC midnight); a full RFC3339
+     * timestamp also works. The API used to demand the full form and answered a bare date with
+     * an opaque 400, which is why older examples here show the long one.
+     * `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 = {}) {
+        return this.post("/api/v1/memory/store", { user_id: this.uid(userId), content, metadata }, opts.idempotencyKey);
     }
     /** Alias of `add` — store one memory. Same surface as the Python SDK's `store`. */
-    store(content, userId, metadata = {}) {
-        return this.add(content, userId, metadata);
+    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) {
-        return this.post("/api/v1/memory/store-turn", { user_id: this.uid(userId), user_msg: userMsg, assistant_msg: assistantMsg });
+    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 (chunked + embedded server-side). For backfilling. */
-    addBulk(content, userId, category = "general", timestamp) {
+    /** Bulk-ingest a large blob of text (chunked + embedded server-side). For backfilling.
+     *  The call most worth an `opts.idempotencyKey`: a backfill that dies halfway and is
+     *  re-run would otherwise re-chunk 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);
+        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) {
-        return this.post("/api/v1/memory/supersede", { user_id: this.uid(userId), old_memory_id: oldMemoryId, new_content: newContent });
+    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 -----
     /** Semantic search over a store's memories. Returns memories, most relevant first. */
     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);
         const r = await this.post("/api/v1/memory/search", { ...opts, user_id: this.uid(userId), query, max_results: limit });
         return mergeLanes(r);
     }
@@ -379,6 +469,7 @@ export class Client {
      * speaker "me"), kept separate so the reader never confuses who said what. On a model
      * without a self lane, `self_memories` is `[]`. `userId` optional (default store). */
     async searchSelf(query, userId, limit = 10, opts = {}) {
+        warnOnUnknownFilters(opts.filters);
         const r = await this.post("/api/v1/memory/search", { ...opts, user_id: this.uid(userId), query, max_results: limit });
         return { memories: asRecords(r.memories), self_memories: asRecords(r.self_memories) };
     }
@@ -473,6 +564,29 @@ export class Client {
         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.
+     *
+     * `engram()` could always RUN one, but there was no way to ASK what exists — so a
+     * caller had to hard-code names from the docs, and every engram we shipped after
+     * their code was written stayed invisible to them. The MCP server hit exactly this
+     * and stopped hard-coding for the same reason. The service is the authority: what
+     * 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
@@ -526,8 +640,19 @@ export class Client {
         return this.post("/api/v1/memory/forget", { user_id: userId });
     }
     // ----- internal -----
-    post(path, body) {
-        return this.request("POST", path, body);
+    post(path, body, idempotencyKey) {
+        return this.request("POST", path, body, idempotencyKey);
+    }
+    /** 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) {
+        if (key === undefined)
+            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) {
@@ -573,7 +698,8 @@ export class Client {
         }
         return new TextDecoder().decode(buf);
     }
-    async request(method, path, body) {
+    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.
@@ -586,7 +712,7 @@ export class Client {
             try {
                 res = await fetch(`${this.base}${path}`, {
                     method,
-                    headers: this.headers,
+                    headers: extraHeaders ? { ...this.headers, ...extraHeaders } : this.headers,
                     body: body === undefined ? undefined : JSON.stringify(body),
                     signal: ctrl.signal,
                     // Never follow a redirect: fetch would forward the API key to
@@ -679,8 +805,15 @@ export class Client {
                     msg = msg.slice(0, MAX_ERR_MSG) + "…(truncated)";
                 throw errorFor(res.status, msg, requestId);
             }
-            if (!text)
-                return {};
+            // An empty body is only legal when the STATUS says there is no body. This
+            // used to accept any empty 2xx, so an `add()` answered by a truncating proxy
+            // returned `{}` and read as a successful write with no id — while the Python
+            // and Rust SDKs raised on the same response. Same rule in all three now.
+            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);
@@ -697,6 +830,13 @@ export class Client {
                 const got = data === null ? "null" : Array.isArray(data) ? "array" : typeof data;
                 throw new WosError(res.status, `expected a JSON object in the response, got ${got}`);
             }
+            // 멱등키를 쓴 쓰기가 **저장된 것인지 재생된 것인지**를 호출자가 알아야 한다.
+            // 서버는 `Idempotent-Replayed: true` 로 말해주는데 지금까지 SDK 가 삼켰다 —
+            // 멱등키를 쓰는 사람이 가장 알고 싶은 사실이 그것이다(재시도가 실제로
+            // 저장을 일으켰나, 아니면 첫 응답이 되풀이된 것인가).
+            if (res.headers.get("Idempotent-Replayed") === "true") {
+                data.replayed = true;
+            }
             return data;
         }
         throw new WosError(0, "retries exhausted"); // unreachable; keeps the compiler happy

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wontopos",
-  "version": "2.2.23",
+  "version": "2.2.25",
   "description": "Wontopos — long-term memory for AI agents. Pure semantic retrieval, identical recall in every language, ~100× lower LLM bill.",
   "keywords": [
     "memory",