wontopos 2.2.34 → 2.2.36

package/README.md

@@ -23,15 +23,23 @@ const ctx = await mem.recall("what does alice drink?", "alice");
 
 ## Why
 
-- **Pure semantic retrieval** — no keyword/BM25. Identical recall in every language (Korean · Japanese · Chinese · English).
-- **No LLM in the loop** — `store` / `search` / `recall` never call a language model. You pay embeddings, not generation.
-- **Bounded retrieval** — `recall()` returns a small, fixed-size slice (~1,200 tokens) regardless of how much you've stored.
+- **The same in every language** — identical recall whichever language a memory was written in (Korean · Japanese · Chinese · English).
+- **No LLM in the loop** — `store` / `search` / `recall` never call a language model. You pay retrieval, not generation.
+- **Bounded retrieval** — `recall()` returns a small, fixed-size slice regardless of how much you've stored (~1,000 tokens on `tablet-2`, the default engine).
 
 ## Methods
 
 `add` · `addTurn` · `addBulk` · `update` · `search` · `searchFull` · `recall` · `history` · `stats` · `get` · `listMemories` · `delete` · `deleteAll`
 
-Every method takes the store id as its second argument — `mem.add("...", "alice")`. Omit it to use the client's default store. A store is one isolated memory space per end-user, agent, or topic. WHO said each memory inside a store is the `speaker` tag below — storing the assistant's own words never needs a separate id.
+Where the store id goes depends on whether the method takes a payload. A method that
+writes or searches puts the payload first and the store second — `mem.add("...", "alice")`,
+`mem.search("...", "alice")`. A method that only addresses a store takes it first —
+`mem.listMemories("alice")`, `mem.stats("alice")`, `mem.delete("alice", memoryId)`.
+Most of them let you leave it out for the client's default store. Four take it
+positionally and cannot — `get`, `delete`, `lineage` and `forgetImage` want an explicit
+`undefined` there, because a second required argument follows it. Python omits it in
+all four; this is the one place the three clients differ in shape rather than meaning.
+Let your editor confirm the order: every signature is typed. A store is one isolated memory space per end-user, agent, or topic. WHO said each memory inside a store is the `speaker` tag below — storing the assistant's own words never needs a separate id.
 
 ## Who said it (speakers)
 
@@ -72,11 +80,23 @@ const hits = await mem.search("...the conversation so far...", "alice", 10,
 
 Built in, no configuration needed:
 
-- **Automatic retries** — 429 / 502 / 503 and connection errors retry twice with
+- **Automatic retries** — 429 always, and 502 / 503 or a connection error only when a
+  retry cannot double-process a write. The writes and the searches are POSTs, and a
+  502 on one of those may have been returned *after* the service already stored and
+  billed it, so those get 429 and connect-level failures only. The reads and the
+  deletes that address a whole store — `listStores`, `listSpeakers`, `deleteStore`,
+  `removeSpeaker`, `forgetImage` — are GET or DELETE and do retry a 502. Twice, with
   exponential backoff + jitter, honoring the server's `Retry-After`. Tune with
   `new Client({ maxRetries })`; `0` disables.
 - **Redirects refused** — the API key never follows a 3xx to another host.
-- **Timeouts** — 30s per attempt by default (`timeoutMs`).
+- **Timeouts** — 30s per attempt by default (`timeoutMs`), and a total budget for
+  the whole call across every retry with `deadlineMs` / `withDeadline(ms)`. At the
+  defaults one call can hold for 30s + backoff + 30s + backoff + 30s, which a
+  request handler with five seconds cannot use.
+- **Cancellable** — pass the caller's `AbortSignal` (`new Client({ signal })` or
+  `withSignal(signal)`). Aborting ends the request in flight and any backoff sleep
+  waiting to retry it.
+- **CommonJS and ESM** — `require("wontopos")` and `import` both resolve.
 - **Key never in logs** — `JSON.stringify(client)` and Node's `console.log(client)`
   print a masked key.
 - **Wipe guard** — `delete()` without a `memoryId` throws instead of silently
@@ -162,10 +182,13 @@ try {
 }
 ```
 
-## Self-host
+## A different API host
+
+Point the client somewhere other than the default endpoint - a dedicated region,
+a proxy of your own, or a local test server:
 
 ```ts
-const mem = new Client({ apiKey: "...", baseUrl: "https://wos.your-host.com" });
+const mem = new Client({ apiKey: "...", baseUrl: "https://api.example.com" });
 ```
 
 ## Links
@@ -189,7 +212,82 @@ data to fix it.
 
 The three clients release in lockstep — same version, same surface, same day.
 Patch releases are additive: nothing is removed or reordered within a minor line.
-
+Two have bent that, deliberately and named at the top of their entry — 2.2.34 moved the
+default engine, and 2.2.35 gives `search` the count range `recall` has always had. A
+rule you can bend without saying so is not a rule, so both are stated rather than left
+for a reader to hit.
+
+- **2.2.36** — an outside review, read by a different model with no knowledge of why
+  any of this was written. The one that mattered: `recall()` promised in its own
+  documentation that a count outside 5–20 was refused rather than clamped, and
+  nothing checked — so `{ limit: 500 }` travelled to the service and failed there, for a
+  mistake visible before opening a socket. `context_limit` (0–20) was unchecked the same way.
+  Both are refused here now, and `0` still passes for `context_limit` because "attach none" is
+  an answer, not a missing value.
+  An argument mistake now throws a plain `Error`, not a `WosError`. A `WosError` with
+  status 0 is `APIConnectionError` — "the request never got a response" — so
+  `if (e.status === 0) retry()` would have retried a typo forever. And `recall` is
+  now `async`: validating inside a non-async method threw synchronously, so
+  `mem.recall(...).catch(h)` walked past the handler while the same mistake in
+  `search` landed in it.
+  New `deadlineMs` / `withDeadline(ms)`: a TOTAL budget for one call across every
+  retry. `timeoutMs` bounds one ATTEMPT, so at the defaults a call could hold for 30s
+  + backoff + 30s + backoff + 30s and a request handler with five seconds had no way
+  to say so. New `signal` / `withSignal(signal)`: cancel work in flight — an abort
+  ends the request AND any backoff sleep waiting to retry it.
+  `require("wontopos")` now resolves: the package ships CommonJS and ESM from one
+  source. Previously `"type": "module"` with no `require` condition meant Node's CJS
+  resolver could not resolve this package at all.
+  `replayed` is set only when the service did not send that field itself.
+- **2.2.35** — fixes, and **two behaviour changes**, both listed first because a patch
+  release is not the place to find one by surprise.
+
+  ⚠️ **`search`'s count is now 5–20, and out of range is refused rather than
+  adjusted.** `recall` has carried that range from the start; search had no contract
+  anywhere, so the clients sent whatever they were given and the service capped at 50
+  with no floor. `search(q, limit=50)` and `search(q, limit=3)` both worked on 2.2.34
+  and now raise. The default is still 10, so a call that passes no count is unaffected.
+  Asking for 20 and silently getting 10 reads as "that is all there is", which is why
+  this refuses instead of clamping.
+
+  ⚠️ **A Rust `limit` of 0 is no longer rewritten to 10.** It was, and the caller whose
+  prompt budget computed zero was handed ten memories and the bill for them. It is now
+  refused under the range above rather than quietly changed to something nobody asked
+  for.
+
+  The fixes: a `null` idempotency key no longer becomes the literal key `"null"`, which
+  had made every write on that path share one key so the second onward stored nothing
+  (TypeScript). The async client no longer reads an explicit `retries=2` as "the caller
+  said nothing" (Python). The image read is actually streamed, so the 64MB cap bounds a
+  compressed body instead of measuring bytes already in memory (Python async), and that
+  route's ERROR body is capped too (Rust). `iter_images` stops on a repeated cursor the
+  way `iter_memories` always did (Python). `iterImages` no longer throws on the ordinary
+  end of a walk (TypeScript). `get_image` retries a 429 and a connect-level failure like
+  every other call — it had none at all — in the **sync Python client and TypeScript**;
+  the async Python client and the Rust crate still make a single attempt there, and say
+  so at the method. An empty or control-character API key is refused at the call site
+  rather than at the network in **Python and Rust**; TypeScript still refuses only empty
+  and whitespace. And a page walk that reaches its ceiling now raises instead of
+  returning a truncated list that looks complete.
+- **2.2.34** — the default engine is `tablet-2`: same token price as `tablet-1`, and
+  the one that serves images and re-ask. Pin the old one with
+  `model="tablet-1"` for the previous behaviour exactly. (The engine's own default
+  count differs between the two, but these SDKs always send one, so a call through
+  them is unaffected.) New `search_full` /
+  `searchFull` keeps every field the answer came with — `search` was merging away
+  the photos and `verify_used`, both of which you were billed for. Also: results arrive
+  best-first — take the order as given. `similarity` is a raw closeness score, and
+  sorting by it makes results worse.
+- **2.2.33** — `get_image` can return a different FORMAT than you uploaded: the
+  service re-encodes on downscale, so a large PNG comes back as WebP. Take the file
+  extension from the response Content-Type, not from what you sent.
+- **2.2.32** — `get_image` returns the picture the SERVICE holds, not your original.
+  An image whose long edge is over 1568px is downscaled on the way in, and that
+  smaller picture is what is stored and handed back. Keep your own copy if you need
+  the full file.
+- **2.2.31** — images, by-speaker, lineage and revisions are SDK methods in all three
+  clients; `search` and `recall` take `verify`, `max_images` and recall's `limit` /
+  `context_limit`.
 - **2.2.30** — documentation only: this changelog, which had not been updated
   in the shipped package since 2.2.10.
 - **2.2.29** — a store id that was PASSED but unusable no longer becomes the

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}