@niadra/sdk 0.7.0 → 0.9.1

package/CHANGELOG.md

@@ -2,6 +2,64 @@
 
 All notable changes to this package are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the package follows [Semantic Versioning](https://semver.org/).
 
+## [Unreleased]
+
+## [0.9.1] - 2026-10-02
+
+### Changed
+
+- The canonical phone of the suppression list follows the revised rules of the suppression spec (3.1 and 3.4): Mexico's and Argentina's mobile prefixes, an 11-digit North American number, a carrier code, `(0)`, `tel:` and direction marks. The key the SDK computes for an opted-out contact matches the server's again.
+
+### Added
+
+- A route or field the API deprecates answers with the `Deprecation`, `Sunset` and `Link` headers; the
+  client logs one warning per deprecated route per process through its `logger`, with the two dates and the
+  migration note, never the path.
+
+## [0.9.0] - 2026-09-30
+
+### Added
+
+- `ContextResult.ageMs`: how long ago Niadra sent or confirmed the pack a read served. It is 0 for an answer
+  just received and grows while the cache serves the pack (`cache`, `stale`, or `fallback` with Niadra down).
+- The chaos test (`test/chaos.test.ts`): Niadra's process killed, its network gone silent, answering 503 and
+  answering past the deadline, in the middle of a conversation.
+- A state read's objects carry `derived`: the type's derived fields over its related objects (a look's
+  `all_pieces_available`), computed at the read, each with `v`, `logic`, `over` and `unknown`
+  (`DerivedState`). A shared object of a derived type carries `derived_status`, and its push's `inputs` name
+  shared objects.
+
+### Fixed
+
+- The local copy of the suppression list is read to its end against the server: a page shorter than the limit
+  ends a read, and its cursor is where the next read starts. The server names the cursor on the last page
+  too, so the copy read 50 pages of nothing and was never held: `mayContact()` and a check that Niadra did not
+  answer fell back on the purpose's direction. The stand-in cell answers as the server does.
+- A batch of events that still fails after its attempts with an error that may pass goes back to the front of
+  the queue and leaves again after a pause, doubling up to a minute, instead of being dropped: what an agent
+  said during an outage longer than a few seconds reached Niadra only in part.
+- A check about an outbound contact keeps the local copy of the suppression list, read in the background once
+  a minute. Before, only `mayContact()` read it, so an agent that only called `check()` had no copy when Niadra
+  went down, and a purpose that fails open (`service`, `transactional`) went out to a customer who had opted
+  out of it.
+
+## [0.8.0] - 2026-09-30
+
+### Added
+
+- The claim guard takes the offers a context read served as evidence: each object in the constraints block's
+  `already_presented` carries the numbers it was last shown with (`values`: price, total, discount,
+  installment), each with its role and whether it may be claimed now, and `blockValues()` turns them into
+  values the guard checks a number against, as it checks a tool's result. An offer shown too long ago to claim makes the
+  number `stale`, and a price only the pack's text states is still `unsupported`. The constraints block's
+  `Shown` model gains `values` (`ShownValue`).
+
+### Removed
+
+- `tool(..., { binding })`, `new Counterfactual(..., { bindings })` and `niadra counterfactual --bindings`: a
+  tool's binding comes only from the space's `tool-bindings` document, which the SDK profile serves. A
+  counterfactual for a tool the space does not bind stops before calling it.
+
 ## [0.7.0] - 2026-09-30
 
 The agent core. Every turn an agent takes is recorded in its own process; what it says is checked against

package/README.md

@@ -77,6 +77,45 @@ ESM and CommonJS builds with full type definitions; it only needs `fetch`.
 | `objectState()`, `objectTimeline()` | a business object (an order, an invoice, a ticket) as the systems of record reported it |
 | `feedback()` | a correction of what Niadra derived, audited like any other event |
 
+## Benchmark
+
+Niadra and ten other memory systems for agents (thirteen configurations) were measured on the same dataset, in the same AWS region
+(us-east-2), with the same agent and the same judge for every system. The script, the dataset and every
+result file are in this repository, under [`benchmarks/`](https://github.com/ainiadra/niadra-sdk-python/tree/main/benchmarks),
+so anyone can run it again. The full page, with every metric and where Niadra does not lead, is at
+[niadra.com/benchmark](https://niadra.com/benchmark).
+
+Combined run of 01/10/2026 ([`2026-09-30-abb516`](https://github.com/ainiadra/niadra-sdk-python/tree/main/benchmarks/results/2026-09-30-abb516)),
+cross-channel accuracy on the same 165 valid cases, judged by the same model:
+
+| System | Accuracy | Model spend per 1,000 conversations |
+|---|---|---|
+| **Niadra** (3 repetitions) | **98.7%** | **US$ 0.36** |
+| Hindsight | 86.7% | US$ 6.10 |
+| Amazon Bedrock AgentCore Memory (3 repetitions) | 80% | US$ 7.50 (AWS public price, its models included) |
+| Honcho (dialectic) | 79.4% | US$ 6.92 |
+| Mem0 open source (3 repetitions) | 77.6% | US$ 1.88 |
+| Memobase | 77% | US$ 4.13 |
+| Supermemory local | 71.6% | US$ 5.78 |
+| Cognee | 70.3% | US$ 6.95 |
+| LangMem | 66.7% | US$ 3.70 |
+| Graphiti | 52.8% | US$ 18.72 |
+| MemOS | 51.6% | US$ 3.70 |
+
+With a different user id on each channel (agents from different vendors), Mem0 open source drops to
+28.5%, AgentCore Memory to 27.9%, and Niadra stays at 98.7%. Sensitive values reaching an unverified
+conversation: Niadra 0 of 32; Mem0 and AgentCore Memory 32 of 32.
+
+Typed state ([`typed/2026-09-30-b59a5d`](https://github.com/ainiadra/niadra-sdk-python/tree/main/benchmarks/results/typed/2026-09-30-b59a5d)):
+with the state and constraints blocks, 84.9% correct [78, 90] against 36.6% without them; declared
+constraints respected went from 0% to 94.4%, and what changed since the customer last saw it from 0% to
+100%, with no extra tokens on a turn that asks for no block.
+
+Where Niadra does not lead in that run: ingest acknowledgement against systems that write in the
+background, opening a single history item, history search p95 against LangMem by a few ms, and tokens per
+turn against readers that return answer text. The benchmark is produced by Niadra; that is why every input
+and output is public.
+
 ## Questions people ask
 
 **How do I give my AI agent memory of past conversations on other channels?** Record the turns
@@ -691,10 +730,11 @@ await convo.turn({ build: Niadra.build({ prompts: { store: "v16" }, model: "gpt-
   without `include` keeps its suffix. With Niadra down, the last good blocks serve.
 - **Coordination** decides by each purpose's direction when Niadra does not answer within 200 ms: a
   customer's message and service go, marketing, retention, collection and an effect with a key wait, and
-  the local copy of the opt-out list always holds.
-- **Tool bindings** the space declares come in the SDK profile: a tool without `binding` in code measures the
-  constraints block through the one served for its name, and its `capabilities.mask_output` decides the
-  masking when the code leaves `maskOutput` unset.
+  the local copy of the opt-out list always holds. Every check about an outbound contact keeps that copy,
+  read again in the background once a minute.
+- **Tool bindings** live in the space's `tool-bindings` document and come in the SDK profile, never in code: a
+  tool measures the constraints block through the one served for its name, the counterfactual runs through it,
+  and its `capabilities.mask_output` decides the masking when the code leaves `maskOutput` unset.
 - **The `niadra` command** (Node) runs `replay`, `counterfactual`, `resolver-worker` (the space's refresh
   requests, read with your resolvers inside your boundary; a watch fires only on a value the worker
   confirmed, and a resolver returns `NOT_FOUND` when the source no longer has the object), `types derive` and
@@ -714,10 +754,16 @@ Memory should make an agent better, never make it fail. By default:
 | 401 or 403 | Not treated as an outage: the cached packs are dropped (all of them on 401, the one requested on 403) and `context()` returns empty. Revoking a key also stops what the process had cached. |
 | 421 (the space moved to another cell) | Retried at once, up to three attempts. |
 | 429 on a batch | Retried after `Retry-After`. |
-| Batch failure | Retried with exponential backoff and jitter, three attempts. 4xx answers other than 408, 421 and 429 are never retried. A batch that still fails is dropped and logged. |
+| Batch failure | Retried with exponential backoff and jitter, three attempts. 4xx answers other than 408, 421 and 429 are never retried. A batch that still fails goes back to the front of the queue and leaves again after a pause that doubles, up to a minute, while Niadra stays down; each event keeps its idempotency key, so it is stored once. |
 | Queue full (10,000 items) | New events are dropped and logged. |
 | Server rejects one item of a batch (207) | Only that item fails; the rest are stored. |
 
+With Niadra down, a read serves the conversation's last good pack (`source: "fallback"`) with `ageMs`
+saying how old it is; the opt-out holds by the local copy of the suppression list; turn records, events
+and declarations wait in their queues and leave once Niadra answers again, each stored once.
+`test/chaos.test.ts` kills Niadra's process, silences its network, answers 503 and answers late in the
+middle of a conversation, and checks all of it.
+
 Every call you wait for has its own time budget for the whole call, retries and waits included, independent of your platform's:
 
 | Call | Default |
@@ -729,7 +775,7 @@ Every call you wait for has its own time budget for the whole call, retries and
 | `identify()`, `verify()`, `handoff()`, `feedback()` and the reservation in `uploadMedia()` | 5 s |
 | The transfer in `uploadMedia()` | 60 s |
 
-An `identify()`, `verify()` or `handoff()` that runs out of time resolves with a `NiadraTimeoutError` and stays in the queue, which keeps sending it. `track()` never waits; each attempt of a background batch has 5 s. Override them with `timeouts`, or per call with `{ timeout }`. Pass `{ signal }` to cancel a call.
+An `identify()`, `verify()` or `handoff()` that runs out of time, or that Niadra cannot take for now (a network error, a 5xx), resolves with that error and stays in the queue, which keeps sending it. `track()` never waits; each attempt of a background batch has 5 s. Override them with `timeouts`, or per call with `{ timeout }`. Pass `{ signal }` to cancel a call.
 
 ### The context cache
 
@@ -740,6 +786,8 @@ Inside a conversation or task, packs are cached in memory:
 - when a request fails: the last good pack, if it is less than 30 minutes old;
 - at most 1,000 packs, the least recently used evicted first.
 
+`source` says which of these served the read, and `ageMs` how long ago Niadra sent or confirmed that pack.
+
 Refreshes send the cached ETag, so an unchanged pack costs a `not_modified` answer instead of the
 full text, and only one background refresh per pack runs at a time. A 401 or 403 is not an
 outage: the cached packs go (all of them on 401, the one requested on 403), so cutting a vendor's
@@ -789,7 +837,7 @@ Include `requestId` when you contact support.
 
 ```sh
 pnpm install
-pnpm check     # typecheck, lint, tests (the integrations with their frameworks' real types)
+pnpm check     # typecheck, lint, tests (the integrations with their frameworks' real types), audit of the runtime dependencies
 pnpm build     # ESM and CommonJS into dist/, one entry per integration
 pnpm runtimes  # the build on Deno, Bun, workerd and the Edge Runtime
 pnpm --filter "./packages/*" check   # the n8n and Flowise nodes

package/dist/ai-sdk.cjs

@@ -385,7 +385,7 @@ function thenable(value) {
 function tool(name, fn, options = {}) {
   const isAsync = isAsyncFunction(fn);
   function bindingOf(frame) {
-    return options.binding ?? (options.served ?? frame?.profile.bindings)?.(name) ?? null;
+    return (options.served ?? frame?.profile.bindings)?.(name) ?? null;
   }
   function masks(frame) {
     return options.maskOutput ?? bindingOf(frame)?.capabilities?.mask_output ?? false;
@@ -500,8 +500,7 @@ function tool(name, fn, options = {}) {
   const marker = {
     name,
     dryRun: options.dryRun ?? false,
-    provenance: options.provenance ?? null,
-    binding: options.binding ?? null
+    provenance: options.provenance ?? null
   };
   Object.defineProperty(wrapped, RECORDED, { value: marker });
   return wrapped;
@@ -527,7 +526,7 @@ function measure(frame, raw, args) {
 
 // src/context.ts
 function emptyResult(error) {
-  return { text: "", suffix: "", variables: {}, pack: null, source: "none", response: null, error, constraints: null, state: null, coordination: null };
+  return { text: "", suffix: "", variables: {}, pack: null, source: "none", ageMs: null, response: null, error, constraints: null, state: null, coordination: null };
 }
 
 // src/integrations/shared.ts