@abloatai/ablo 0.56.0 → 0.58.0

package/AGENTS.md

@@ -6,6 +6,12 @@ Claims don't lock. If another writer holds the row, `claim` waits for them and r
 
 ## Start here — scaffold with `ablo init`
 
+Before choosing among identifier claims, row claims, captured reads, atomic
+commits, existing database writes, and Ablo-routed writes, use the
+[Agent Integration Decision Guide](./docs/agent-integration-decision-guide.md).
+It routes existing applications to the smallest relevant example and names the
+test layer that proves each guarantee.
+
 Don't hand-write the integration. Run the CLI; it generates the current-API schema, client, the database connection (logical replication by default, or a signed Data Source endpoint as the fallback), and (for Next.js) the browser provider + session route:
 
 - **Read the docs for THIS version:** `npx ablo docs` lists every page, `npx ablo docs <page>` prints one. They ship inside the installed package, so they describe the code in `node_modules` and work with no network. Read them instead of a docs URL — a website describes the newest release, so against a pinned version it will hand you a call your package doesn't have (`retrieve`/`list` replaced `get`/`getAll`/`getCount` in 0.35.0).
@@ -21,7 +27,7 @@ Don't hand-write the integration. Run the CLI; it generates the current-API sche
 
 When you use the signed-endpoint fallback, the generated `ablo/data-source.ts` is the whole endpoint and needs no hand-editing: `dataSourceNext({ schema, apiKey, adapter: prismaDataSource(prisma, schema) })` (or `drizzleDataSource(db, schema)`). The adapter owns commit / idempotency / outbox.
 
-**Working on a real database?** Plain model writes are last-write-wins when no active claim applies. Use a functional update, a held claim, or `readAt` when a result depends on an earlier value. Reads are safe to inspect; raw application DDL (`ALTER TABLE …`) and a `--yes` connection cutover belong to a human. When you're unsure whether a write fits, `npx ablo check` reports the live column-by-column fit read-only, before anything runs. Full sorting rule: [Operating on Your Database](./docs/operating-on-your-database.md).
+**Working on a real database?** Plain model writes are last-write-wins when no active claim applies. Use a functional update, a held claim, or `read` plus `reads` when a result depends on an earlier value. Reads are safe to inspect; raw application DDL (`ALTER TABLE …`) and a `--yes` connection cutover belong to a human. When you're unsure whether a write fits, `npx ablo check` reports the live column-by-column fit read-only, before anything runs. Full sorting rule: [Operating on Your Database](./docs/operating-on-your-database.md).
 
 ## Rule
 
@@ -35,10 +41,10 @@ The schema is the integration contract — it drives typed model clients, React
 
 Every model verb takes ONE options object. The common loop:
 
-1. **Read** the row — `await ablo.<model>.get({ id })` (async; from the server) or `await ablo.<model>.list({ where })` for many. In React render, read synchronously with `useAblo((a) => a.<model>.local.get(id))`.
+1. **Get or read** the row — `get({ id })` observes; `read({ id })` declares that a later mutation depends on this exact version. `list({ where })` is observational. In React render, use `local.get(id)`.
 2. **See who's active** (optional) — `ablo.<model>.claim.state({ id })` (synchronous; never blocks).
 3. **Claim** the row before changing it — `await using claim = await ablo.<model>.claim({ id, description?, ttl? })`. If someone else holds it, this waits for them, then gives you the fresh row on `claim.data`. The claim auto-releases when it goes out of scope (`await using`).
-4. **Write** — `await ablo.<model>.update({ id: claim.data.id, data })`. Because you hold the claim, the write is rejected if the row changed underneath you.
+4. **Write** — pass `reads: [row]` when the decision used a row returned by `read`, or write through the held claim. If the declared read moved, the mutation does not land.
 
 Keep coding assistants on this schema-backed path.
 
@@ -58,7 +64,7 @@ const schema = defineSchema({
 
 const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
 
-const report = await ablo.weatherReports.get({ id: 'report_stockholm' });
+const report = await ablo.weatherReports.read({ id: 'report_stockholm' });
 if (!report) throw new Error('Report not found');
 
 // If someone else holds the row, claim waits for them and re-reads the fresh

package/CHANGELOG.md

@@ -1,19 +1,437 @@
 # Changelog
 
+## 0.58.0
+
+### Reads now distinguish observation from decision input
+
+`get({ id })` returns the current row for display or inspection. `read({ id })`
+returns the same row while privately retaining its model, id, and watermark so a
+later write can prove exactly which state it depended on:
+
+```ts
+const report = await ablo.reports.read({ id: reportId });
+
+await ablo.reports.update({
+  id: report.id,
+  data: { summary },
+  reads: [report],
+});
+```
+
+If `report` changed in between, the update does not land and rejects with
+`AbloStaleContextError`. `get()` and `list()` remain observational, while
+`onChange()` remains the live notification surface.
+
+This replaces the older `retrieve()` and durable `track()` model surfaces. It is
+a public-surface break with no compatibility aliases:
+
+- replace `retrieve({ id })` with `get({ id })` for observation, or `read({ id })`
+  when a later mutation depends on the row;
+- replace `track(...)`, `CommitContext.track`, and mutation `track` / `onStale`
+  options with captured rows passed through the mutation's `reads` option; and
+- replace AI SDK `ToolModel.get` with `ToolModel.read`.
+
+Schema conflict-policy configuration and the `agents*`, `humans*`, and
+`system*` policy constants are also removed, together with the supporting
+conflict, stale-notification, persisted-read-set, and internal read-set exports.
+Use an active claim when work must exclude another participant. Use `read()` and
+`reads` when work may run concurrently but must not commit from a stale premise.
+
+The removals announced by earlier releases now take effect too:
+`SourceRequestContext.requiredSyncGroups` is gone in favor of `syncGroups`, and
+`DeltaPosition`, `deltaPositionSchema`, `ReadSetWatermark`, and
+`readSetWatermarkSchema` are gone in favor of `LogPosition` and
+`logPositionSchema`.
+
+### Context follows exact reads and can stop stale work early
+
+`context()` now assembles ordinary application values and exact Ablo reads into
+one result with `data`, `reads`, and `onChange`. It no longer publishes a
+context-level cursor or source classification. `ContextResult.cursor`,
+`ContextResult.sources`, `ContextChange`, `ContextSource`, and
+`contextSourceSchema` leave with that older model.
+
+The reactive client's cache-based `snapshot()` operation and `Snapshot` type are
+removed. Call `read()` for every row an action depends on, assemble those values
+with `context()`, and pass `ctx.reads` to the final write:
+
+```ts
+const ctx = await context({
+  ablo,
+  data: {
+    report: ablo.reports.read({ id: reportId }),
+    documents: searchDocuments(reportId),
+  },
+});
+
+const stop = ctx.onChange((error) => controller.abort(error));
+
+try {
+  const summary = await generateSummary(ctx.data, controller.signal);
+  await ablo.reports.update({
+    id: reportId,
+    data: { summary },
+    reads: ctx.reads,
+  });
+} finally {
+  stop();
+}
+```
+
+`onChange` calls its listeners once when any captured row moves, which lets an
+expensive model call stop early. The final write must still receive
+`reads: ctx.reads`; that server-side check stays authoritative if notification
+races the write or the connection drops.
+
+Atomic `commits.create()` batches accept the same captured rows on both the
+stateless HTTP and reactive WebSocket clients. Typed model claim handles can be
+passed directly as a batch's `claim`, without losing their row type. Disposing a
+reactive client now also disposes its mutation queue and commit-lane timers.
+
+### Claims are available from the shell
+
+The CLI can now acquire, queue for, inspect, heartbeat, and release a row lease:
+
+```bash
+npx ablo claims acquire reports report_123 --queue -- npm run reconcile
+npx ablo claims list reports report_123
+npx ablo claims release reports report_123
+```
+
+The `-- <command>` form keeps the lease alive only while the child process runs
+and releases it on success, failure, or interruption. This lets an operator or
+coding agent participate in the same coordination boundary as SDK clients
+without first adding application code.
+
+### An agent run can carry the person who started it
+
+An agent session can now name the person it acts for. Pass `onBehalfOf` when you
+mint, and every write that agent makes records both principals: the agent as the
+actor, that user as the delegator.
+
+```ts
+const { token } = await server.sessions.create({
+  agent: { id: agentId },
+  onBehalfOf: { user: { id: requestingUserId } },
+  can: { records: ['read', 'update'] },
+  syncGroups: [syncGroup('workspace', workspaceId)],
+});
+```
+
+Until now the delegation chain root came from whoever called the mint. A browser
+session minting for its own user recorded that person; a backend minting with a
+secret key recorded nobody. Background work is the second case, so a queued
+job's writes arrived attributed to the agent alone, or to `system` where the
+worker wrote around Ablo entirely. Ablo never sees your user directory, so it
+cannot recover that identity afterwards.
+
+The rule is about who may attest, not who may ask. A secret key already carries
+organization authority, so it may name any user id, which is what lets a worker
+resume a job somebody else started. A human session may name only its own user,
+and naming another is refused. `onBehalfOf` on a capability that is not an agent
+is refused as well.
+
+Two habits make this hold in practice. Persist the user id on the job before you
+enqueue it, because request context and in-memory arguments do not survive a
+retry or a process boundary, and a durable job without its delegator can only
+produce agent-only attribution. And do not quietly fall back to writing straight
+to the database when minting is unavailable. Those writes are still observed,
+but they carry no trusted correlation and are recorded as `system`.
+
+Omit the field and sessions mint exactly as they did before.
+
+### The CLI has one credential input and a clearer project boundary
+
+`ABLO_API_KEY` is now the CLI's single explicit credential input. Management,
+branch-runtime, and restricted-agent authority follow from the credential kind
+and its server-side grant; `ABLO_MANAGEMENT_KEY` is no longer a separate input.
+Keep management credentials at the control-plane boundary and pass only a
+delegated, per-run `rk_` credential into a sandbox or agent runtime.
+
+After browser approval, `ablo login` now lets an organization with multiple
+projects choose the project in the terminal. `ablo login --project <slug>` skips
+the picker. Credentials remain fixed to the project that minted them, and the
+CLI refuses to silently use another project's stored key.
+
+Database connection setup now handles more provider-specific PostgreSQL role
+constraints, repairs required role inheritance, registers local connectors
+through the control-plane boundary, and reports a missing Data Source API key as
+an authentication problem with a concrete fix. A branch still needs a database
+connected before its schema can be pushed.
+
+### Hosted test branches are explicit and temporary
+
+Live integration fixtures can create an expiring `test` branch backed by Ablo's
+hosted log storage. Hosted storage must be requested explicitly and the branch
+must expire within 24 hours. Ordinary customer branches remain unbound until
+their own database is connected, so a test convenience cannot silently choose
+where customer data lives.
+
+The documentation now includes a coordination-conformance fixture, an
+existing-document evidence pipeline, an existing Python backend path, a
+GraphQL.js approach, and a sandbox-runtime integration guide. These examples
+separate the guarantees Ablo enforces from application, provider, database, and
+deployment responsibilities.
+
+### Pricing and plan limits moved
+
+The rate card, the included allowances, and the plan ceilings all changed in
+this release. The canonical page is published at
+https://docs.abloatai.com/pricing and needs no sign-in.
+
+## 0.57.0
+
+### The endpoint outbox upgrades without a drain
+
+Endpoint events now have an explicit envelope version. Existing rows and writes
+from an older endpoint are version 1 and pass through the preserved pre-subject
+routing decoder. New adapters write version 2, capturing `sync_groups` in the
+same transaction as the row change. The database constraint requires every
+version-2 event to carry those immutable routes.
+
+Old and new endpoint versions may run together during rollout without stalling
+the feed. A page served by an old reader necessarily uses version-1 semantics,
+even when a new writer created the row, because that reader does not select the
+new routing columns. Version-2 routing is therefore universal once every
+endpoint reader has upgraded. There is still no pre-upgrade drain, write pause,
+cursor inspection, or manual deletion.
+
+Ablo sends `cursor` as the read position and `acknowledgedThrough` separately
+after the event and consumer position are durable. Built-in adapters use that
+explicit acknowledgement for bounded cleanup; custom event handlers may do the
+same.
+
+Version 1 remains a deliberately named compatibility decoder, not a
+NULL value silently interpreted as an empty audience. Replication connections
+have no endpoint outbox and require no action.
+
+### A row is authorized by the subject its schema declares
+
+A model may now declare which field decides who a row belongs to, and that rule
+is enforced on every path: reads, writes, claims, presence, and every storage
+adapter, including the endpoint ones. A row is authorized exactly when the
+request carries the sync group `${group}:${row[field]}`.
+
+This is what 0.56.0's boundary change was heading towards. Sync groups routed
+delivery and did not decide authorization, so a model that used them as though
+they did was relying on something the guide told you not to rely on. A declared
+subject is that rule made real, checked in one place and failing closed.
+
+Two consequences worth knowing. A subject-scoped model stamps exactly one group
+on a change, because delivery matching is OR-based and a second group would
+widen the audience rather than narrow it. And a tombstone now reaches only the
+row's authorized subject group, where before a delete could be announced more
+widely than the row ever was.
+
+A schema that routes by sync group without a matching row-access policy is
+flagged. If the routing really is only routing, acknowledge it explicitly and
+the flag goes quiet.
+
+### Creating many rows is one commit
+
+`create` takes a list as well as a single row, under the same verb:
+
+```ts
+const rows = await ablo.weatherReports.create({
+  data: [
+    { location: 'Stockholm', summary: 'Clear' },
+    { location: 'Oslo', summary: 'Rain' },
+  ],
+});
+```
+
+They are written as one atomic commit rather than one request each, so either
+every row lands or none does. The result comes back in the order you gave it,
+not the order the batch settled, and carries whatever defaults the server
+stamped. An empty list writes nothing rather than opening an empty commit.
+
+### Reading a whole collection, in as many words
+
+`listAll({ where, maxPages, signal })` reads a complete collection by walking the
+same cursor `list` returns, so the common case stops being a hand-rolled loop:
+
+```ts
+const open = await ablo.weatherReports.listAll({
+  where: { status: ['draft', 'review'] },
+  maxPages: 20,
+});
+```
+
+It is bounded on purpose. `maxPages` is how you say how much you are willing to
+read, and `signal` cancels a walk that is taking longer than the work is worth.
+A complete read that cannot say when it will stop is how a page turns into an
+outage.
+
+### A claimed write carries its stale guard again
+
+Holding a claim and then writing gave mutual exclusion but not lost-update
+detection, on the stateless transport agents run. The claim handle carries the
+position the row was read at, and the write defaults to rejecting on a change
+since then. Unwrapping the handle cleared the claim before that default was
+read, so the guard was unreachable and every model write through the public
+surface lost it.
+
+It read as though both protections were present: claim, read, decide, write. The
+watermark now travels with the handle, and your own `readAt` or `onStale` still
+win where you set them.
+
+### A create on an id that already exists is refused
+
+It reported success and returned a row. A caller-selected id is a claim about
+which row this is, so a create that finds one already there is a conflict rather
+than an update, and it now says so.
+
+### CLI: a session route that revalidates before it mints
+
+`ablo init` scaffolds a Next.js session route that re-checks membership at mint
+time rather than trusting the caller, and puts secret clients behind the
+framework's `server-only` boundary so a key cannot be imported into a component
+that ships to a browser.
+
+### Filtering a server read by a reference field
+
+`list({ where: { issueId } })` matched nothing on a replicated plane. It raised
+no error and returned a well-formed empty array, so the read looked like a
+question with no answers rather than a filter that never ran. Filtering on
+`id`, `title` or `body` worked, which made the failure look like a property of
+the data instead of a property of the field name.
+
+The cause was a key space. A row served from the log is a snapshot in the wire
+shape, so its fields are spelled the way your schema spells them, while the
+filter looked them up by their database column. Those two agree exactly when a
+column is a single word, and part ways on every `issueId`, `teamId` or
+`assigneeId`. Ordering, relation expansion and any field declared with
+`.from()` were reading the same wrong spelling: a `related` list came back
+empty, and a `.from()` field was simply absent from the row.
+
+If you page a collection and filter it in your own code to work around this,
+that code can go.
+
+A filter naming a field the model does not declare is now refused, with the
+same error the direct-database plane already gave it. It used to return
+nothing, which reads as an answer.
+
+### A list read walks its own pages
+
+`list` returns a page, and a page of 20 looks exactly like a complete answer of 20. Every caller either checked `hasMore` or, more often, reasoned about a
+truncated collection without knowing there was more.
+
+Iterate the result for the page. Walk it for the collection:
+
+```ts
+for await (const issue of await ablo.issues.list({ where: { teamId } })) {
+  …
+}
+```
+
+`hasMore` and `nextCursor` are unchanged, and taking the cursor yourself is
+still the right thing when the pages go somewhere other than a loop.
+
+### Clearing a field
+
+`null` clears a field, and the types now say so. They used to accept only the
+field's own type or `undefined`, and `undefined` means "leave this alone": it
+is dropped from the payload, so an unassign written that way kept the old
+assignee and reported success. The only spelling that both compiled and worked
+was one that cast the payload, which turned off type checking for the whole
+write.
+
+Only a field your schema declares optional accepts `null`. A required field has
+no empty value to move to, and the type says that too.
+
+### A write that does not name its row is refused
+
+`delete({ where: { id } })` reads like it should work, and `where` is what the
+commit protocol takes one layer down. It used to spell the missing id into the
+request as the literal text `undefined`, match no row, and return an ordinary
+receipt. It now fails at the call, naming the model, the action, and `{ id }`.
+
+The same guard covers `update`.
+
+### A create honours the id you gave it
+
+An id passed inside `data`, which the create input has always allowed, was
+never read: the row was written under a generated id and you were handed back
+one you had not named. Both spellings now work, and the standalone `id` wins if
+they disagree.
+
+### Every response says what your allowance is
+
+The limiter knew the allowance and the refill and told you neither, so the only
+strategy available was to retry and find the wall again.
+
+```
+RateLimit-Policy: "secret";q=600;w=12
+RateLimit: "secret";r=573;t=8
+Retry-After: 3
+```
+
+`RateLimit-Policy` is the standing allowance and is always present.
+`RateLimit` reports what is left and when it refills, once a request is
+attributed to a key. A 429 adds `Retry-After` in whole seconds. Pace against
+these rather than retrying blind.
+
+### A route says when it is going away
+
+Every response carries `Ablo-Version`, a date stamp for the contract being
+served, so a caller can notice the contract moved under it.
+
+A route being withdrawn now says so on itself for at least 180 days first.
+`Deprecation` (RFC 9745) carries when the deprecation took effect, and the route
+keeps answering; `Sunset` (RFC 8594) carries when it stops. The same operations
+are marked `deprecated: true` in the OpenAPI document, so a generated client
+sees it too.
+
+Breaking changes still arrive as a new path segment beside `/v1`, never as a
+change to it. Additive ones land in `/v1`, so ignore what you do not recognise.
+
+### The documentation answers a reader that is not a browser
+
+The surfaces `llms.txt` names are routes now rather than a promise:
+`/llms-full.txt` for the whole corpus in one fetch, `/openapi.json` for the REST
+contract, `/developers` naming every developer surface on one page,
+`/.well-known/mcp.json` for the MCP manifest.
+
+Every page also answers from its own URL in Markdown. Send
+`Accept: text/markdown`, or append `.md` where a client cannot set headers.
+Responses carry `Vary: Accept`, a client that will take neither type gets a 406
+listing what is available, and a path that does not exist answers a real 404
+rather than a 200 carrying a sign-in page.
+
+### Renamed and removed
+
+`SourceRequestContext.requiredSyncGroups` is now `syncGroups`. Ablo populates
+both spellings this release, so a source adapter still reading the old name gets
+the groups rather than `undefined`, which on a routing field would read as "no
+groups" rather than as a field that moved. The old spelling is removed in
+0.58.0.
+
+`DeltaPosition`, `deltaPositionSchema`, `ReadSetWatermark`, and
+`readSetWatermarkSchema` are removed, as 0.56.0 announced. Use `LogPosition` and
+`logPositionSchema`, which they have resolved to since then.
+
 ## 0.56.0
 
-### One customer no longer sees another's live work
+### Coordination reads are scoped to the customer, not the organization
+
+Coordination has always been scoped to the organization, and through 0.51.0 that
+was the whole boundary: a platform gave each customer its own organization, and
+the sessions guide was explicit that sync groups decide which changes travel
+rather than what a session may read.
+
+This release moves that line. A platform's customers are rows in its own schema,
+reached by the sync groups on the session, so many customers share one
+organization and the organization is no longer the finest boundary. The delivery
+path already applied the finer cut. The claim listing and the presence read did
+not, so under that newer arrangement one customer could see which rows another
+had claimed, who held them, what the work was called, and who was online. Row
+contents were never exposed; everything around them was.
 
-A platform's customers are rows in its own schema, so they share one
-organization and one plane. The claim listing and the presence read were scoped
-to exactly that pair and nothing finer. One customer could therefore see which
-rows another had claimed, who held them, what the work was called, and who was
-online. Row contents were never exposed; everything around them was.
+Both reads now take the same cut, from the groups each side already carries.
 
-Both reads now apply the same cut the delivery path already applies, taken from
-the groups each side already carries. A customer sees the coordination for the
-rows it can see, and nothing else. If you serve many customers from one
-organization, this closes the gap without any change on your side.
+If you give each customer its own organization, nothing changes for you and
+nothing was reachable across customers. If you serve many customers from one
+organization, this closes the gap with no change on your side.
 
 ### A client converges on the head it was measured against
 

package/LICENSE

@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2025-2026 Lukas Andersson
+   Copyright 2025-2026 Ablo Inc.
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

package/NOTICE

@@ -1,10 +1,10 @@
 @ablo/ablo
-Copyright 2025-2026 Lukas Andersson
+Copyright 2025-2026 Ablo Inc.
 
-This product includes software developed by Lukas Andersson
+This product includes software developed by Ablo Inc.
 (https://abloatai.com).
 
-"Ablo" is a trademark of Lukas Andersson. This license does not grant
+"Ablo" is a trademark of Ablo Inc. This license does not grant
 permission to use the Ablo name, logo, or trademarks. Third parties
 may describe their use of or compatibility with Ablo factually (e.g.,
 "built with @ablo/ablo") but may not use the Ablo name in a way

package/README.md

@@ -56,12 +56,13 @@ for changes.
 Read and write through one typed API:
 
 ```ts
-const order = await ablo.orders.get({ id: orderId });
+const order = await ablo.orders.read({ id: orderId });
 
 if (!order) throw new Error('Order not found');
 await ablo.orders.update({
   id: order.id,
   data: { status: 'approved' },
+  reads: [order],
 });
 ```
 

package/dist/ai-sdk.d.ts

@@ -1,5 +1,5 @@
 export * from '@abloatai/transaction/ai-sdk';
-import type { ContextResult } from './context.js';
+import type { ContextResult } from './context/index.js';
 export interface ContextMessageOptions<TData extends Readonly<Record<string, unknown>>> {
     /** Top-level context keys to render. The default is every selected key. */
     readonly include?: readonly (keyof TData & string)[];

package/dist/ai-sdk.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ai-sdk.d.ts","sourceRoot":"","sources":["../src/ai-sdk.ts"],"names":[],"mappings":"AAAA,cAAc,8BAA8B,CAAC;AAG7C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAMlD,MAAM,WAAW,qBAAqB,CAAC,KAAK,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpF,2EAA2E;IAC3E,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,CAAC,MAAM,KAAK,GAAG,MAAM,CAAC,EAAE,CAAC;CACtD;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,kFAAkF;AAClF,wBAAgB,cAAc,CAAC,KAAK,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAC5E,KAAK,EAAE,aAAa,CAAC,KAAK,CAAC,EAC3B,OAAO,GAAE,qBAAqB,CAAC,KAAK,CAAM,GACzC,cAAc,CAehB"}
+{"version":3,"file":"ai-sdk.d.ts","sourceRoot":"","sources":["../src/ai-sdk.ts"],"names":[],"mappings":"AAAA,cAAc,8BAA8B,CAAC;AAG7C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAMxD,MAAM,WAAW,qBAAqB,CAAC,KAAK,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpF,2EAA2E;IAC3E,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,CAAC,MAAM,KAAK,GAAG,MAAM,CAAC,EAAE,CAAC;CACtD;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,kFAAkF;AAClF,wBAAgB,cAAc,CAAC,KAAK,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAC5E,KAAK,EAAE,aAAa,CAAC,KAAK,CAAC,EAC3B,OAAO,GAAE,qBAAqB,CAAC,KAAK,CAAM,GACzC,cAAc,CAehB"}

package/dist/context/evidence.d.ts

@@ -1,11 +1,9 @@
 import { type CapturedReadEvidence } from '@abloatai/transaction/internal/read-set';
-export interface ContextEvidenceSlice {
-    readonly reads: readonly CapturedReadEvidence[];
-    readonly includesInformational: boolean;
+import type { ReadDependency } from '@abloatai/transaction/coordination';
+import type { AbloStaleContextError } from '@abloatai/transaction';
+export interface BoundContextEvidence {
+    readonly collect: (data: unknown) => readonly CapturedReadEvidence[];
+    readonly onChange?: (reads: readonly ReadDependency[], listener: (error: AbloStaleContextError) => void) => () => void;
 }
-export interface ContextEvidence {
-    readonly all: readonly CapturedReadEvidence[];
-    readonly inspect: (value: unknown) => ContextEvidenceSlice;
-}
-export declare function bindContextEvidence(client: object): (data: unknown) => ContextEvidence;
+export declare function bindContextEvidence(client: object): BoundContextEvidence;
 //# sourceMappingURL=evidence.d.ts.map

package/dist/context/evidence.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"evidence.d.ts","sourceRoot":"","sources":["../../src/context/evidence.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,oBAAoB,EAE1B,MAAM,yCAAyC,CAAC;AAQjD,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,KAAK,EAAE,SAAS,oBAAoB,EAAE,CAAC;IAChD,QAAQ,CAAC,qBAAqB,EAAE,OAAO,CAAC;CACzC;AAsCD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,GAAG,EAAE,SAAS,oBAAoB,EAAE,CAAC;IAC9C,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,oBAAoB,CAAC;CAC5D;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,CAAC,IAAI,EAAE,OAAO,KAAK,eAAe,CAWtF"}
+{"version":3,"file":"evidence.d.ts","sourceRoot":"","sources":["../../src/context/evidence.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,oBAAoB,EAE1B,MAAM,yCAAyC,CAAC;AACjD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AACzE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAiCnE,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,SAAS,oBAAoB,EAAE,CAAC;IACrE,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAClB,KAAK,EAAE,SAAS,cAAc,EAAE,EAChC,QAAQ,EAAE,CAAC,KAAK,EAAE,qBAAqB,KAAK,IAAI,KAC7C,MAAM,IAAI,CAAC;CACjB;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,oBAAoB,CAQxE"}

package/dist/context/evidence.js

@@ -8,12 +8,9 @@ function isTraversable(value) {
 function inspectValue(binding, value) {
     const found = [];
     const seen = new WeakSet();
-    let includesInformational = false;
     const visit = (current) => {
-        if (typeof current !== 'object' || current === null) {
-            includesInformational = true;
+        if (typeof current !== 'object' || current === null)
             return;
-        }
         if (seen.has(current))
             return;
         seen.add(current);
@@ -23,31 +20,20 @@ function inspectValue(binding, value) {
             return;
         }
         if (isTraversable(current)) {
-            const children = Object.values(current);
-            if (children.length === 0)
-                includesInformational = true;
-            for (const child of children)
+            for (const child of Object.values(current))
                 visit(child);
-            return;
         }
-        includesInformational = true;
     };
     visit(value);
-    return {
-        reads: [...new Map(found.map((item) => [item.row, item])).values()],
-        includesInformational,
-    };
+    return [...new Map(found.map((item) => [item.row, item])).values()];
 }
 export function bindContextEvidence(client) {
     const binding = readEvidenceBinding(client);
     if (!binding)
         throw new TypeError('context() requires an Ablo client in `ablo`.');
-    return (data) => {
-        const inspect = (value) => inspectValue(binding, value);
-        return {
-            all: inspect(data).reads,
-            inspect,
-        };
+    return {
+        collect: (data) => inspectValue(binding, data),
+        ...(binding.onChange ? { onChange: binding.onChange } : {}),
     };
 }
 //# sourceMappingURL=evidence.js.map

package/dist/context/evidence.js.map

@@ -1 +1 @@
-{"version":3,"file":"evidence.js","sourceRoot":"","sources":["../../src/context/evidence.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,mBAAmB,GAGpB,MAAM,yCAAyC,CAAC;AAEjD,SAAS,aAAa,CAAC,KAAa;IAClC,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACtC,MAAM,SAAS,GAAG,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;IAC/C,OAAO,SAAS,KAAK,MAAM,CAAC,SAAS,IAAI,SAAS,KAAK,IAAI,CAAC;AAC9D,CAAC;AAOD,SAAS,YAAY,CACnB,OAA4B,EAC5B,KAAc;IAEd,MAAM,KAAK,GAA2B,EAAE,CAAC;IACzC,MAAM,IAAI,GAAG,IAAI,OAAO,EAAU,CAAC;IACnC,IAAI,qBAAqB,GAAG,KAAK,CAAC;IAElC,MAAM,KAAK,GAAG,CAAC,OAAgB,EAAQ,EAAE;QACvC,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;YACpD,qBAAqB,GAAG,IAAI,CAAC;YAC7B,OAAO;QACT,CAAC;QACD,IAAI,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC;YAAE,OAAO;QAC9B,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAClB,MAAM,QAAQ,GAAG,cAAc,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QAClD,IAAI,QAAQ,EAAE,CAAC;YACb,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YACrB,OAAO;QACT,CAAC;QACD,IAAI,aAAa,CAAC,OAAO,CAAC,EAAE,CAAC;YAC3B,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;YACxC,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;gBAAE,qBAAqB,GAAG,IAAI,CAAC;YACxD,KAAK,MAAM,KAAK,IAAI,QAAQ;gBAAE,KAAK,CAAC,KAAK,CAAC,CAAC;YAC3C,OAAO;QACT,CAAC;QACD,qBAAqB,GAAG,IAAI,CAAC;IAC/B,CAAC,CAAC;IAEF,KAAK,CAAC,KAAK,CAAC,CAAC;IACb,OAAO;QACL,KAAK,EAAE,CAAC,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;QACnE,qBAAqB;KACtB,CAAC;AACJ,CAAC;AAOD,MAAM,UAAU,mBAAmB,CAAC,MAAc;IAChD,MAAM,OAAO,GAAG,mBAAmB,CAAC,MAAM,CAAC,CAAC;IAC5C,IAAI,CAAC,OAAO;QAAE,MAAM,IAAI,SAAS,CAAC,8CAA8C,CAAC,CAAC;IAElF,OAAO,CAAC,IAAI,EAAE,EAAE;QACd,MAAM,OAAO,GAAG,CAAC,KAAc,EAAE,EAAE,CAAC,YAAY,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QACjE,OAAO;YACL,GAAG,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK;YACxB,OAAO;SACR,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"evidence.js","sourceRoot":"","sources":["../../src/context/evidence.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,mBAAmB,GAGpB,MAAM,yCAAyC,CAAC;AAIjD,SAAS,aAAa,CAAC,KAAa;IAClC,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACtC,MAAM,SAAS,GAAG,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;IAC/C,OAAO,SAAS,KAAK,MAAM,CAAC,SAAS,IAAI,SAAS,KAAK,IAAI,CAAC;AAC9D,CAAC;AAED,SAAS,YAAY,CACnB,OAA4B,EAC5B,KAAc;IAEd,MAAM,KAAK,GAA2B,EAAE,CAAC;IACzC,MAAM,IAAI,GAAG,IAAI,OAAO,EAAU,CAAC;IAEnC,MAAM,KAAK,GAAG,CAAC,OAAgB,EAAQ,EAAE;QACvC,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI;YAAE,OAAO;QAC5D,IAAI,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC;YAAE,OAAO;QAC9B,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAClB,MAAM,QAAQ,GAAG,cAAc,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QAClD,IAAI,QAAQ,EAAE,CAAC;YACb,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YACrB,OAAO;QACT,CAAC;QACD,IAAI,aAAa,CAAC,OAAO,CAAC,EAAE,CAAC;YAC3B,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC;gBAAE,KAAK,CAAC,KAAK,CAAC,CAAC;QAC3D,CAAC;IACH,CAAC,CAAC;IAEF,KAAK,CAAC,KAAK,CAAC,CAAC;IACb,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;AACtE,CAAC;AAUD,MAAM,UAAU,mBAAmB,CAAC,MAAc;IAChD,MAAM,OAAO,GAAG,mBAAmB,CAAC,MAAM,CAAC,CAAC;IAC5C,IAAI,CAAC,OAAO;QAAE,MAAM,IAAI,SAAS,CAAC,8CAA8C,CAAC,CAAC;IAElF,OAAO;QACL,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,YAAY,CAAC,OAAO,EAAE,IAAI,CAAC;QAC9C,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC5D,CAAC;AACJ,CAAC"}

package/dist/context/index.d.ts

@@ -0,0 +1,23 @@
+import type { CapturedRow } from '@abloatai/transaction';
+import { type AwaitedDeep } from './await.js';
+import { type ContextOnChange } from './onChange.js';
+export type { AwaitedDeep } from './await.js';
+export type { ContextChangeListener, ContextOnChange } from './onChange.js';
+export interface ContextOptions<TData extends Readonly<Record<string, unknown>>> {
+    /** The client whose read evidence may guard a later create, update, or delete. */
+    readonly ablo: object;
+    /** Values selected by the application. Nested promises are accepted. */
+    readonly data: TData;
+}
+export interface ContextResult<TData extends Readonly<Record<string, unknown>>> {
+    readonly data: AwaitedDeep<TData>;
+    /**
+     * Exact returned Ablo rows, ready to pass to create, update, or delete
+     * through `reads`.
+     */
+    readonly reads: readonly CapturedRow[];
+    /** Called once when any exact read in this context becomes stale. */
+    readonly onChange: ContextOnChange;
+}
+export declare function context<const TData extends Readonly<Record<string, unknown>>>(options: ContextOptions<TData>): Promise<ContextResult<TData>>;
+//# sourceMappingURL=index.d.ts.map