@abloatai/ablo 0.57.0 → 0.59.0

package/AGENTS.md

@@ -1,11 +1,17 @@
 # AGENTS.md
 
-Ablo lets AI agents and humans safely edit the same typed data without clobbering each other. When two of them touch the same row, a "claim" makes one wait for the other instead of overwriting it. This file shows a coding assistant the one safe pattern: read a row, claim it, then write.
+Ablo lets AI agents and humans safely edit the same typed data without clobbering each other. When two of them touch the same row, a "claim" makes one wait for the other instead of overwriting it. For an existing application, first preserve its named operation and persistence boundary; use the schema-backed row pattern below only when that route owns the write.
 
 Claims don't lock. If another writer holds the row, `claim` waits for them and re-reads the fresh row before handing it to you — so two writers serialize instead of clobbering.
 
 ## 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
+[coordinate existing work guide](./docs/coordinate-existing-work.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 pass `claim` when writing through a held claim. If the declared read moved or the claim was lost, 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
@@ -74,6 +80,7 @@ const claimed = claim.data;
 await ablo.weatherReports.update({
   id: claimed.id,
   data: { status: 'ready', forecast: await getForecast(claimed.location) },
+  claim,
 });
 ```
 

package/CHANGELOG.md

@@ -1,23 +1,279 @@
 # Changelog
 
-## 0.57.0
+## 0.59.0
+
+### Schema changes now have one ordered deployment plan
+
+`ablo plan` compares the source schema, the active Ablo schema artifact, and the
+connected PostgreSQL shape without changing any of them. It produces one
+fingerprinted expand, dual-write, backfill, verify, switch, and contract
+sequence, with explicit owners, blockers, and a rollback target:
+
+```sh
+npx ablo plan
+npx ablo plan --json
+```
+
+`ablo check` is now the database-compatibility view of that same plan. `ablo
+push` and `ablo migrate` consume it instead of maintaining separate migration
+judgments, and `ablo rollback` plans or applies a reviewed reactivation of an
+earlier schema artifact. The shared deployment contracts are available through
+`@abloatai/ablo/schema` and `@abloatai/transaction/schema`.
+
+Planning must observe all three states. `ablo plan`, `ablo check`, and `ablo
+migrate` therefore require `ABLO_API_KEY` plus
+`DATABASE_ADMIN_URL`/`DATABASE_URL`; a migration dry run is no longer a
+source-only operation. `ablo push` now refuses a blocked plan and can accept an
+explicit lifecycle manifest with `--manifest <path>`.
+
+Runtime schema-drift warnings now name the affected fields and distinguish
+client-only fields, active-only fields, and changes to type or optionality.
+
+### Declared timestamps no longer recurse during local edits
+
+Schemas can declare `createdAt` and `updatedAt` for typed reads and ordering
+without turning Ablo's automatic timestamp bookkeeping into another model
+edit. Updating an observable field now advances `updatedAt` once, keeps the
+timestamp observable, and excludes system-managed timestamps from the
+user-authored change payload.
+
+### The public client configuration boundary is explicit
+
+The supported `Ablo({ ... })` options are now machine-checked against the
+published reference. The internal `onCommitReceipt` transport callback is no
+longer accepted by the public factory type.
+
+### Connection capacity is selectable from the public pricing model
+
+The pricing API can now select the first tier that accommodates a requested
+connection count. The published Pro allowance increases from 1,000 to 5,000
+concurrent connections.
+
+### CLI telemetry can reach authenticated ingestion
+
+When an Ablo runtime key is available, the CLI uses it only in memory to
+authenticate product-analytics delivery. The key is not written to the local
+telemetry state, and existing telemetry opt-outs continue to apply.
+
+### Version-matched integration guidance is easier to enter
+
+The documentation bundled with `@abloatai/ablo` now starts from installation,
+the operation being coordinated, and whether an existing write boundary must
+be preserved. New focused pages cover basic usage, implementation choices,
+existing-operation coordination, every client option, security,
+instrumentation, comparisons, common questions, and GraphQL.js. `npx ablo
+docs` continues to read this package-local documentation, so the guidance
+matches the installed version.
+
+A new stale-context agent-turn example shows the complete long-running policy:
+abort cancellable work when an exact read moves, rebuild context for a bounded
+retry, retain the authoritative write guard, and reconcile rather than blindly
+replay an irreversible external side effect.
+
+## 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.
 
-### Before you upgrade: drain the endpoint outbox
+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();
+}
+```
 
-This release adds a `sync_groups` column to the source outbox, and the migration
-refuses to run while legacy rows are still sitting in it. That refusal is
-deliberate. A legacy row has no routes recorded, and assigning it one would
-either invent an audience or give it none, so the migration stops and tells you
-rather than guessing.
+`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.
 
-If you run a `dataSource()` endpoint, do this on the previous release, in order:
+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.
 
-1. Let Ablo poll until every event already in `ablo_outbox` has been consumed.
-2. Confirm the polling cursor has advanced past the last of them.
-3. Delete those consumed rows.
+### 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
 
-Then upgrade and run the migration. If you connect your database over
-replication rather than an endpoint, there is no outbox and nothing to do.
+### 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
 

package/README.md

@@ -3,12 +3,12 @@
 </p>
 
 <p align="center">
-  <strong>Collaboration infrastructure for AI agents.</strong>
+  <strong>Coordination infrastructure for agents, applications, services, and people working on shared state.</strong>
 </p>
 
 <p align="center">
   <a href="https://docs.abloatai.com">Docs</a> &nbsp;|&nbsp;
-  <a href="https://docs.abloatai.com/quickstart">Quickstart</a> &nbsp;|&nbsp;
+  <a href="https://docs.abloatai.com/installation">Installation</a> &nbsp;|&nbsp;
   <a href="https://docs.abloatai.com/api">API</a> &nbsp;|&nbsp;
   <a href="https://github.com/Abloatai/ablo">GitHub</a>
 </p>
@@ -22,8 +22,8 @@
 
 ---
 
-Ablo is collaboration infrastructure for AI agents: one API for agents, apps,
-and services to claim, change, and confirm the same rows.
+Ablo is coordination infrastructure for agents, applications, services, and
+people working on shared state.
 
 Every write goes through it, so authority, idempotency, conflicts, ordering,
 and confirmation are enforced in one place. Your Postgres remains the source of
@@ -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

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/context/index.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAa,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAEzD,OAAO,EAAyB,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AAE5E,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,YAAY,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAI5E,MAAM,WAAW,cAAc,CAAC,KAAK,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7E,kFAAkF;IAClF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,wEAAwE;IACxE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;CACtB;AAED,MAAM,WAAW,aAAa,CAAC,KAAK,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5E,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC,KAAK,CAAC,CAAC;IAClC;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,CAAC;IACvC,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;CACpC;AAED,wBAAsB,OAAO,CAAC,KAAK,CAAC,KAAK,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACjF,OAAO,EAAE,cAAc,CAAC,KAAK,CAAC,GAC7B,OAAO,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CAgB/B"}

package/dist/context/index.js

@@ -0,0 +1,26 @@
+/**
+ * Assemble the values selected for one action and retain the exact Ablo reads
+ * they contain. Each read keeps its own `readAt`; context does not collapse
+ * those independent premises into another watermark.
+ */
+import { z } from 'zod';
+import { awaitDeep } from './await.js';
+import { bindContextEvidence } from './evidence.js';
+import { createContextOnChange } from './onChange.js';
+const contextDataSchema = z.record(z.string(), z.unknown());
+export async function context(options) {
+    const evidenceBinding = bindContextEvidence(options.ablo);
+    const data = await awaitDeep(options.data);
+    const parsed = contextDataSchema.safeParse(data);
+    if (!parsed.success) {
+        throw new TypeError('context() requires `data` to be an object.', { cause: parsed.error });
+    }
+    const evidence = evidenceBinding.collect(data);
+    const dependencies = evidence.map((item) => item.entry);
+    return {
+        data: data,
+        reads: evidence.map((item) => item.row),
+        onChange: createContextOnChange(dependencies, evidenceBinding.onChange),
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/context/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/context/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,SAAS,EAAoB,MAAM,YAAY,CAAC;AACzD,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EAAE,qBAAqB,EAAwB,MAAM,eAAe,CAAC;AAK5E,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;AAoB5D,MAAM,CAAC,KAAK,UAAU,OAAO,CAC3B,OAA8B;IAE9B,MAAM,eAAe,GAAG,mBAAmB,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1D,MAAM,IAAI,GAAG,MAAM,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3C,MAAM,MAAM,GAAG,iBAAiB,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IACjD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,IAAI,SAAS,CAAC,4CAA4C,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC;IAC7F,CAAC;IAED,MAAM,QAAQ,GAAG,eAAe,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,MAAM,YAAY,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAExD,OAAO;QACL,IAAI,EAAE,IAA0B;QAChC,KAAK,EAAE,QAAQ,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,GAAkB,CAAC;QACtD,QAAQ,EAAE,qBAAqB,CAAC,YAAY,EAAE,eAAe,CAAC,QAAQ,CAAC;KACxE,CAAC;AACJ,CAAC"}

package/dist/context/onChange.d.ts

@@ -0,0 +1,9 @@
+import type { ReadDependency } from '@abloatai/transaction/coordination';
+import type { AbloStaleContextError } from '@abloatai/transaction';
+export type ContextChangeListener = (error: AbloStaleContextError) => void;
+export type ContextOnChange = (listener: ContextChangeListener) => () => void;
+type StartOnChange = (reads: readonly ReadDependency[], listener: ContextChangeListener) => () => void;
+/** Share one transport subscription for every listener on one context. */
+export declare function createContextOnChange(reads: readonly ReadDependency[], start: StartOnChange | undefined): ContextOnChange;
+export {};
+//# sourceMappingURL=onChange.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"onChange.d.ts","sourceRoot":"","sources":["../../src/context/onChange.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AACzE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAEnE,MAAM,MAAM,qBAAqB,GAAG,CAAC,KAAK,EAAE,qBAAqB,KAAK,IAAI,CAAC;AAC3E,MAAM,MAAM,eAAe,GAAG,CAAC,QAAQ,EAAE,qBAAqB,KAAK,MAAM,IAAI,CAAC;AAE9E,KAAK,aAAa,GAAG,CACnB,KAAK,EAAE,SAAS,cAAc,EAAE,EAChC,QAAQ,EAAE,qBAAqB,KAC5B,MAAM,IAAI,CAAC;AAEhB,0EAA0E;AAC1E,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,SAAS,cAAc,EAAE,EAChC,KAAK,EAAE,aAAa,GAAG,SAAS,GAC/B,eAAe,CAoCjB"}

package/dist/context/onChange.js

@@ -0,0 +1,37 @@
+/** Share one transport subscription for every listener on one context. */
+export function createContextOnChange(reads, start) {
+    const listeners = new Set();
+    let stop;
+    let stale;
+    const changed = (error) => {
+        if (stale)
+            return;
+        stale = error;
+        stop?.();
+        stop = undefined;
+        for (const listener of [...listeners])
+            listener(error);
+    };
+    return (listener) => {
+        if (stale) {
+            listener(stale);
+            return () => undefined;
+        }
+        listeners.add(listener);
+        if (reads.length > 0 && !stop) {
+            if (!start) {
+                listeners.delete(listener);
+                throw new TypeError('This Ablo client does not support context().onChange.');
+            }
+            stop = start(reads, changed);
+        }
+        return () => {
+            listeners.delete(listener);
+            if (listeners.size === 0) {
+                stop?.();
+                stop = undefined;
+            }
+        };
+    };
+}
+//# sourceMappingURL=onChange.js.map

package/dist/context/onChange.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"onChange.js","sourceRoot":"","sources":["../../src/context/onChange.ts"],"names":[],"mappings":"AAWA,0EAA0E;AAC1E,MAAM,UAAU,qBAAqB,CACnC,KAAgC,EAChC,KAAgC;IAEhC,MAAM,SAAS,GAAG,IAAI,GAAG,EAAyB,CAAC;IACnD,IAAI,IAA8B,CAAC;IACnC,IAAI,KAAwC,CAAC;IAE7C,MAAM,OAAO,GAAG,CAAC,KAA4B,EAAQ,EAAE;QACrD,IAAI,KAAK;YAAE,OAAO;QAClB,KAAK,GAAG,KAAK,CAAC;QACd,IAAI,EAAE,EAAE,CAAC;QACT,IAAI,GAAG,SAAS,CAAC;QACjB,KAAK,MAAM,QAAQ,IAAI,CAAC,GAAG,SAAS,CAAC;YAAE,QAAQ,CAAC,KAAK,CAAC,CAAC;IACzD,CAAC,CAAC;IAEF,OAAO,CAAC,QAAQ,EAAE,EAAE;QAClB,IAAI,KAAK,EAAE,CAAC;YACV,QAAQ,CAAC,KAAK,CAAC,CAAC;YAChB,OAAO,GAAG,EAAE,CAAC,SAAS,CAAC;QACzB,CAAC;QAED,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACxB,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;YAC9B,IAAI,CAAC,KAAK,EAAE,CAAC;gBACX,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;gBAC3B,MAAM,IAAI,SAAS,CAAC,uDAAuD,CAAC,CAAC;YAC/E,CAAC;YACD,IAAI,GAAG,KAAK,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QAC/B,CAAC;QAED,OAAO,GAAG,EAAE;YACV,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;YAC3B,IAAI,SAAS,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;gBACzB,IAAI,EAAE,EAAE,CAAC;gBACT,IAAI,GAAG,SAAS,CAAC;YACnB,CAAC;QACH,CAAC,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC"}

package/dist/source-conformance.d.ts

@@ -1,2 +1,2 @@
-export * from '@abloatai/transaction/source/conformance';
+export * from '@abloatai/transaction/source/adapters';
 //# sourceMappingURL=source-conformance.d.ts.map

package/dist/source-conformance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"source-conformance.d.ts","sourceRoot":"","sources":["../src/source-conformance.ts"],"names":[],"mappings":"AAAA,cAAc,0CAA0C,CAAC"}
+{"version":3,"file":"source-conformance.d.ts","sourceRoot":"","sources":["../src/source-conformance.ts"],"names":[],"mappings":"AAAA,cAAc,uCAAuC,CAAC"}

package/dist/source-conformance.js

@@ -1,2 +1,2 @@
-export * from '@abloatai/transaction/source/conformance';
+export * from '@abloatai/transaction/source/adapters';
 //# sourceMappingURL=source-conformance.js.map

package/dist/source-conformance.js.map

@@ -1 +1 @@
-{"version":3,"file":"source-conformance.js","sourceRoot":"","sources":["../src/source-conformance.ts"],"names":[],"mappings":"AAAA,cAAc,0CAA0C,CAAC"}
+{"version":3,"file":"source-conformance.js","sourceRoot":"","sources":["../src/source-conformance.ts"],"names":[],"mappings":"AAAA,cAAc,uCAAuC,CAAC"}