@abloatai/ablo 0.27.0 → 0.29.0

package/dist/wire/protocolVersion.d.ts

@@ -2,31 +2,30 @@
  * The sync protocol version — a single integer, increasing over time, that
  * covers everything the client and server must agree on to talk to each other:
  * the WebSocket frame shapes, the HTTP request and response envelopes, and the
- * delta encodings a client replays. It is separate from the app-schema hash
- * (WebSocket close code 4009), which detects drift in your data model; this
- * detects drift in the protocol itself.
+ * delta encodings a client replays. It is separate from the advisory
+ * app-schema hash, which diagnoses data-model drift; this version selects a
+ * concrete transport codec.
  *
  * Deploy ordering: the server is deployed first. It accepts every version in
- * the inclusive range from {@link MIN_SUPPORTED_PROTOCOL_VERSION} to
- * {@link PROTOCOL_VERSION}, and a client is never expected to connect to a
- * server older than itself. If that does happen — for example a partial server
- * rollback — {@link protocolVersionProblem} reports it as `too_new` so the
- * mismatch is visible rather than undefined.
+ * {@link SUPPORTED_PROTOCOL_VERSIONS}, and a client is never expected to connect
+ * to a server older than itself. If that does happen — for example a partial
+ * server rollback — {@link protocolVersionProblem} reports it as `too_new` so
+ * the mismatch is visible rather than undefined.
  *
  * To change the protocol:
  *   1. Make the change backward-tolerant where you can. The server ignores
  *      unknown payload keys, so an additive field usually needs no version bump.
- *   2. For a breaking change, bump {@link PROTOCOL_VERSION}, add a changelog
- *      entry below, and keep {@link MIN_SUPPORTED_PROTOCOL_VERSION} low enough
- *      to cover every client still in use; raise it only after a deprecation
- *      window.
- *   3. The protocol-version contract test fails on any bump — update it in the
- *      same change, deliberately.
+ *   2. For a breaking change, bump {@link PROTOCOL_VERSION}, add its codec to
+ *      {@link SUPPORTED_PROTOCOL_VERSIONS}, and add a changelog entry below.
+ *   3. Keep {@link MIN_SUPPORTED_PROTOCOL_VERSION} low enough to cover every
+ *      client still in use; raise it only after a deprecation window.
+ *   4. The protocol contract tests fail on a version without a codec and on any
+ *      unreviewed bump — update them in the same change, deliberately.
  *
  * Changelog
  *   v1 (2026-07-03) — the protocol as of this field's introduction: the
  *      sync-request frame (`cursor`, `lastSyncId`, `capabilities`, optional
- *      `protocolVersion`), the commit, mutation, claim, release, ack, and
+ *      `protocolVersion`), the commit, claim, release, ack, and
  *      presence-update frames, the bootstrap and delta batches, and the HTTP
  *      error and list envelopes. A client that predates this field sends no
  *      `protocolVersion` and is treated as v1, since introducing the field
@@ -39,10 +38,22 @@ export declare const PROTOCOL_VERSION = 1;
  * and with a changelog entry.
  */
 export declare const MIN_SUPPORTED_PROTOCOL_VERSION = 1;
+/** The version used by clients from before the version field existed. */
+export declare const DEFAULT_PROTOCOL_VERSION = 1;
+/**
+ * Every wire version this build can actually decode. This is intentionally an
+ * explicit manifest rather than a computed numeric range: a version is not
+ * supported merely because its number falls between two constants. Server
+ * codec registries use {@link SupportedProtocolVersion} as their key type, so
+ * adding a version here makes a missing decoder a compile error.
+ */
+export declare const SUPPORTED_PROTOCOL_VERSIONS: readonly [1];
+export type SupportedProtocolVersion = (typeof SUPPORTED_PROTOCOL_VERSIONS)[number];
+export type ProtocolVersionProblem = 'too_old' | 'too_new' | 'codec_missing';
 /**
  * The WebSocket close code the server sends to reject a protocol-version
  * mismatch. It sits alongside the other application close codes (4001 for a
- * credential problem, 4009 for app-schema drift), and its reason string is the
+ * credential problem), and its reason string is the
  * error code `protocol_version_unsupported`. A client should treat this close
  * as terminal: reconnecting cannot heal a version mismatch, but upgrading the
  * client or rolling the server forward can.
@@ -55,6 +66,8 @@ export declare const WS_CLOSE_PROTOCOL_VERSION = 4010;
  * — counts as v1. A non-integer value is treated as `'too_old'` so the check
  * fails closed and visibly.
  */
-export declare function protocolVersionProblem(announced: number | undefined): 'too_old' | 'too_new' | null;
+export declare function protocolVersionProblem(announced: number | undefined): ProtocolVersionProblem | null;
+/** Resolve an announced value to a version that has a concrete codec. */
+export declare function resolveProtocolVersion(announced: number | undefined): SupportedProtocolVersion | null;
 /** The HTTP request header a client uses to announce its protocol version. */
 export declare const PROTOCOL_VERSION_HEADER = "Ablo-Protocol-Version";

package/dist/wire/protocolVersion.js

@@ -2,31 +2,30 @@
  * The sync protocol version — a single integer, increasing over time, that
  * covers everything the client and server must agree on to talk to each other:
  * the WebSocket frame shapes, the HTTP request and response envelopes, and the
- * delta encodings a client replays. It is separate from the app-schema hash
- * (WebSocket close code 4009), which detects drift in your data model; this
- * detects drift in the protocol itself.
+ * delta encodings a client replays. It is separate from the advisory
+ * app-schema hash, which diagnoses data-model drift; this version selects a
+ * concrete transport codec.
  *
  * Deploy ordering: the server is deployed first. It accepts every version in
- * the inclusive range from {@link MIN_SUPPORTED_PROTOCOL_VERSION} to
- * {@link PROTOCOL_VERSION}, and a client is never expected to connect to a
- * server older than itself. If that does happen — for example a partial server
- * rollback — {@link protocolVersionProblem} reports it as `too_new` so the
- * mismatch is visible rather than undefined.
+ * {@link SUPPORTED_PROTOCOL_VERSIONS}, and a client is never expected to connect
+ * to a server older than itself. If that does happen — for example a partial
+ * server rollback — {@link protocolVersionProblem} reports it as `too_new` so
+ * the mismatch is visible rather than undefined.
  *
  * To change the protocol:
  *   1. Make the change backward-tolerant where you can. The server ignores
  *      unknown payload keys, so an additive field usually needs no version bump.
- *   2. For a breaking change, bump {@link PROTOCOL_VERSION}, add a changelog
- *      entry below, and keep {@link MIN_SUPPORTED_PROTOCOL_VERSION} low enough
- *      to cover every client still in use; raise it only after a deprecation
- *      window.
- *   3. The protocol-version contract test fails on any bump — update it in the
- *      same change, deliberately.
+ *   2. For a breaking change, bump {@link PROTOCOL_VERSION}, add its codec to
+ *      {@link SUPPORTED_PROTOCOL_VERSIONS}, and add a changelog entry below.
+ *   3. Keep {@link MIN_SUPPORTED_PROTOCOL_VERSION} low enough to cover every
+ *      client still in use; raise it only after a deprecation window.
+ *   4. The protocol contract tests fail on a version without a codec and on any
+ *      unreviewed bump — update them in the same change, deliberately.
  *
  * Changelog
  *   v1 (2026-07-03) — the protocol as of this field's introduction: the
  *      sync-request frame (`cursor`, `lastSyncId`, `capabilities`, optional
- *      `protocolVersion`), the commit, mutation, claim, release, ack, and
+ *      `protocolVersion`), the commit, claim, release, ack, and
  *      presence-update frames, the bootstrap and delta batches, and the HTTP
  *      error and list envelopes. A client that predates this field sends no
  *      `protocolVersion` and is treated as v1, since introducing the field
@@ -39,10 +38,20 @@ export const PROTOCOL_VERSION = 1;
  * and with a changelog entry.
  */
 export const MIN_SUPPORTED_PROTOCOL_VERSION = 1;
+/** The version used by clients from before the version field existed. */
+export const DEFAULT_PROTOCOL_VERSION = 1;
+/**
+ * Every wire version this build can actually decode. This is intentionally an
+ * explicit manifest rather than a computed numeric range: a version is not
+ * supported merely because its number falls between two constants. Server
+ * codec registries use {@link SupportedProtocolVersion} as their key type, so
+ * adding a version here makes a missing decoder a compile error.
+ */
+export const SUPPORTED_PROTOCOL_VERSIONS = [1];
 /**
  * The WebSocket close code the server sends to reject a protocol-version
  * mismatch. It sits alongside the other application close codes (4001 for a
- * credential problem, 4009 for app-schema drift), and its reason string is the
+ * credential problem), and its reason string is the
  * error code `protocol_version_unsupported`. A client should treat this close
  * as terminal: reconnecting cannot heal a version mismatch, but upgrading the
  * client or rolling the server forward can.
@@ -56,12 +65,19 @@ export const WS_CLOSE_PROTOCOL_VERSION = 4010;
  * fails closed and visibly.
  */
 export function protocolVersionProblem(announced) {
-    const v = announced ?? 1;
+    const v = announced ?? DEFAULT_PROTOCOL_VERSION;
     if (!Number.isInteger(v) || v < MIN_SUPPORTED_PROTOCOL_VERSION)
         return 'too_old';
     if (v > PROTOCOL_VERSION)
         return 'too_new';
-    return null;
+    return SUPPORTED_PROTOCOL_VERSIONS.some((candidate) => candidate === v)
+        ? null
+        : 'codec_missing';
+}
+/** Resolve an announced value to a version that has a concrete codec. */
+export function resolveProtocolVersion(announced) {
+    const version = announced ?? DEFAULT_PROTOCOL_VERSION;
+    return SUPPORTED_PROTOCOL_VERSIONS.find((candidate) => candidate === version) ?? null;
 }
 /** The HTTP request header a client uses to announce its protocol version. */
 export const PROTOCOL_VERSION_HEADER = 'Ablo-Protocol-Version';

package/docs/agents.md

@@ -27,10 +27,15 @@ import { schema } from "./schema";
 
 const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY, transport: "http" });
 
-// Reads + writes, fully typed off your schema — each is one HTTP round-trip:
+// Reads + writes, fully typed off your schema.
+// `retrieve` resolves to the row, or `undefined` when none matches.
 const open = await ablo.tasks.list({ where: { status: "todo" } });
-const { data } = await ablo.tasks.retrieve({ id: open[0].id });
-await ablo.tasks.update({ id: open[0].id, data: { status: "done" } });
+
+const task = await ablo.tasks.retrieve({ id: open[0].id });
+if (!task) throw new Error("task not found");
+
+console.log(task.title);
+await ablo.tasks.update({ id: task.id, data: { status: "done" } });
 ```
 
 It exposes `retrieve` / `list` / `create` / `update` / `delete`, plus `commits`

package/docs/api.md

@@ -206,27 +206,29 @@ The SDK is a convenience wrapper over a model-scoped HTTP surface — the same
 noun (`model`) and verbs as `ablo.<model>.…`. Non-JS callers (or curl) use it
 directly. The table below shows the shape with `{model}` as a placeholder; the
 [OpenAPI spec](./openapi.json) expands it into one **typed** path per model
-(`/v1/models/task`, `/v1/models/deck`, …, generated from your schema) so each
+(`/api/v1/models/task`, `/api/v1/models/deck`, …, generated from your schema) so each
 endpoint documents that model's real field contract instead of a generic blob.
 
 | SDK call | HTTP |
 |---|---|
-| `ablo.<model>.create({ data })` | `POST /v1/models/{model}` |
-| `ablo.<model>.list({ where })` | `GET /v1/models/{model}` |
-| `ablo.<model>.retrieve({ id })` | `GET /v1/models/{model}/{id}` |
-| `ablo.<model>.update({ id, data })` | `PATCH /v1/models/{model}/{id}` |
-| `ablo.<model>.delete({ id })` | `DELETE /v1/models/{model}/{id}` |
-| `ablo.<model>.claim({ id })` | `POST /v1/models/{model}/{id}/claim` |
-| (release a claim) | `DELETE /v1/models/{model}/{id}/claim` |
+| `ablo.<model>.create({ data })` | `POST /api/v1/models/{model}` |
+| `ablo.<model>.list({ where })` | `GET /api/v1/models/{model}` |
+| `ablo.<model>.retrieve({ id })` | `GET /api/v1/models/{model}/{id}` |
+| `ablo.<model>.update({ id, data })` | `PATCH /api/v1/models/{model}/{id}` |
+| `ablo.<model>.delete({ id })` | `DELETE /api/v1/models/{model}/{id}` |
+| `ablo.<model>.claim({ id })` | `POST /api/v1/models/{model}/{id}/claim` |
+| (release a claim) | `DELETE /api/v1/models/{model}/{id}/claim` |
 
 Auth is a bearer API key: `Authorization: Bearer sk_…`. Mutations take an
 `Idempotency-Key` header — derive it from the business event, not a random
-value, so a retry never double-writes. Writes return a `CommitReceipt`; a
-rejected write carries an error `code` (e.g. `stale_context`, `intent_conflict`)
-to act on. `GET /v1/models/{model}` is cursor-paginated (`limit`, `order`,
-`order_by`, `starting_after`) and returns `{ data, has_more, next_cursor }`.
-
-`POST /v1/commits` remains the path for **atomic multi-op** writes (several
+value, so a retry never double-writes. Direct HTTP writes return a protocol
+receipt; the typed SDK turns single-model writes into their application result
+(the created or updated row, or nothing for delete). A rejected write carries an
+error `code` (e.g. `stale_context`, `intent_conflict`) to act on.
+`GET /api/v1/models/{model}` is cursor-paginated (`limit`, `order`, `order_by`,
+`starting_after`) and returns `{ data, has_more, next_cursor }`.
+
+`POST /api/v1/commits` remains the path for **atomic multi-op** writes (several
 operations across rows/models that must commit together) — the per-model routes
 above are the one-record path. Both run the identical guarded-write engine.
 

package/docs/client-behavior.md

@@ -32,6 +32,7 @@ Common options:
 | `databaseUrl` | Optional, server-only. Registers your Postgres directly (the connection-string path). Pass it explicitly — it is **not** auto-read from the environment. Omit it for a signed Data Source endpoint or the hosted sandbox. The SDK throws if it sees this in a browser. |
 | `baseURL` | Override the hosted sync endpoint for staging or private deployments. |
 | `persistence` | `memory` by default. Use `indexeddb` for a durable browser cache that survives reloads. |
+| `durableWrites` | Optional crash recovery for unacknowledged agent/worker writes. Independent of the default memory cache; accepts `{ store, namespace? }`. |
 | `transport` | `'websocket'` (default) is the live, stateful client — a persistent socket, a local synced pool, and `onChange` subscriptions. `'http'` returns the **stateless** client for server-side actors (agents, workers, serverless): the same `ablo.<model>` read/write/claim surface, but each call is one HTTP round-trip with no socket. Under `'http'` the return type narrows to `AbloHttpClient`, so stateful-only methods (`get`/`getAll`, `onChange`, `watch`) are compile errors rather than runtime gaps. |
 | `fetch` | Custom fetch implementation for tests or non-standard runtimes. |
 | `defaultHeaders` | Extra headers attached to every HTTP request. |
@@ -109,7 +110,6 @@ await ablo.weatherReports.update({
   readAt: snap.stamp,
   onStale: 'reject',
   idempotencyKey: 'report_stockholm:mark-ready:v1',
-  timeout: 20_000,
 });
 ```
 
@@ -119,7 +119,6 @@ await ablo.weatherReports.update({
 | `readAt` | State cursor the write was based on. |
 | `onStale` | Policy when the target changed after `readAt`. Prefer `reject`. |
 | `idempotencyKey` | Stable key for retry-safe writes. The SDK generates one when omitted. |
-| `timeout` | Maximum time for the write call. |
 
 ## Claimed Behavior
 
@@ -136,7 +135,11 @@ if (active) {
 }
 
 const handle = await ablo.weatherReports.claim({ id: 'report_stockholm' });
-await ablo.weatherReports.update({ id: handle.data.id, data: { status: 'ready' } });
+await ablo.weatherReports.update({
+  id: handle.data.id,
+  data: { status: 'ready' },
+  claim: handle,
+});
 await handle.release();
 ```
 

package/docs/coordination.md

@@ -465,13 +465,13 @@ Each beat's answer carries two more things:
 
 Works identically on both transports: the realtime client sends a
 `claim_heartbeat` frame; the HTTP client posts
-`POST /v1/models/{model}/{id}/claim/heartbeat` (`{ ttl?, claimId?, details? }`).
+`POST /api/v1/models/{model}/{id}/claim/heartbeat` (`{ ttl?, claimId?, details? }`).
 Over HTTP, a **queued** claim can heartbeat too — it refreshes the waiter's
 slot in the line (a queued slot is TTL'd like a lease) and reports
 `{ status: 'queued', position }`.
 
 A stateless worker holding **many** rows beats them all in one round trip:
-`ablo.claims.heartbeatAll({ ttl: '5m' })` → `POST /v1/claims/heartbeat`, one
+`ablo.claims.heartbeatAll({ ttl: '5m' })` → `POST /api/v1/claims/heartbeat`, one
 entry per extended lease. This is the socketless twin of the realtime
 keepalive, which already renews every held lease on each ping.
 
@@ -631,9 +631,8 @@ guarantee can't drift): read the freshest row + its watermark → run your updat
 comes from the watermark, **not** from participant identity — so it's immune to
 the shared-credential clobber footgun and needs no `claim` and no per-agent `rk_`.
 
-Nothing about claims, identity, or conflict codes surfaces. The call either
-returns the reconciled row (a `CommitReceipt` on the HTTP client; the row on the
-WebSocket client) or, at the extreme, throws **one** error:
+Nothing about claims, identity, or conflict codes surfaces. On both transports,
+the call returns the reconciled row or, at the extreme, throws **one** error:
 
 ```ts
 import { AbloContentionError } from '@abloatai/ablo';

package/docs/data-sources.md

@@ -180,14 +180,11 @@ database, schema — the connection string itself is sealed and never echoed bac
 the replication slot position, and the commit log that drives sync. Never your
 rows.
 
-> **Logical-replication runtime status: Preview.** The setup path above
-> (`ablo connect` and `ablo connect --check`) is real and shipping. The
-> server-side component that consumes your WAL and turns it into sync deltas is in
-> **Preview** — it is implemented and tested but **not yet GA / boot-wired in the
-> hosted runtime**. Treat WAL consumption as not-yet-deployed until this note is
-> removed. Maintainers: see
-> [internal/byo-wal-consumer.md](./internal/byo-wal-consumer.md) for the
-> architecture and remaining slices.
+> **Postgres replication status: Preview.** Registration, readiness checks, and
+> the server replication fleet are implemented and boot-wired. Preview describes
+> product rollout and support, not an inactive code path. Maintainers: see
+> [internal/postgres-replication.md](./internal/postgres-replication.md) for the
+> architecture and operational invariants.
 
 ## Next steps
 

package/docs/guarantees.md

@@ -125,6 +125,27 @@ const ablo = Ablo({
 
 Node, SSR, tests, and agents use in-memory persistence ('memory') automatically.
 
+Cache persistence and outbound-write recovery are separate concerns. Most
+clients need only the default memory cache: once the server confirms a write,
+the server is durable and the idempotency key makes a retry safe. A long-running
+worker that must also recover an unacknowledged write after its own process dies
+can opt into a durable write journal:
+
+```ts
+const ablo = Ablo({
+  schema,
+  apiKey: process.env.ABLO_API_KEY,
+  durableWrites: {
+    store: workerWriteStore,
+    namespace: 'report-worker',
+  },
+});
+```
+
+The store can be backed by the worker's workflow state, SQLite, or another
+durable system. Actor identity is derived from authentication; `namespace` only
+separates workflow or deployment lanes sharing the same store.
+
 ## Storage Boundary
 
 Ablo does not need a customer database URL. When your own database is canonical,

package/docs/integration-guide.md

@@ -492,6 +492,7 @@ Keep agent writes on the same schema client surface as the app.
 | `/testing`                                | Test harnesses and deterministic mocks.                           |
 | `Data Source`                             | Keep your app database canonical.                                 |
 | `persistence: 'indexeddb'`                | Durable browser cache that survives reloads, for apps that need it. |
+| `durableWrites: { store, namespace? }`     | Recover unacknowledged worker writes after a process restart.      |
 | `claim` / `claim.state` / `claim.queue`          | Show active work and coordinate before a write.                   |
 | `snapshot` + `readAt`                     | Reject writes based on stale state.                               |
 | `mutable`, `readOnly`, `field`, `indexed` | Advanced schema and read tuning.                                  |

package/docs/mcp.md

@@ -16,7 +16,7 @@ edits rows → coordination; teaching your IDE assistant the SDK → helper.
 ## Coordination server (`@ablo/mcp`)
 
 The coordination server is the MCP projection of the model-scoped API
-(`/v1/models/...`) — the same surface as `ablo.<model>.create/update/claim` and
+(`/api/v1/models/...`) — the same surface as `ablo.<model>.create/update/claim` and
 the REST routes, rendered as tools. An agent connects with your API key and
 gets one safe loop: **claim → read → commit → release.**
 

package/docs/migration.md

@@ -11,7 +11,8 @@ change when you upgrade.
 
 | Version | What changed | What to do |
 |---|---|---|
-| **0.11.0** | `intent` → `claim` rename completed across the React hook, type namespace, and wire frames | `useIntent` → `useClaim`; `Register.Intents` → `Register.Claims`; `Ablo.Intent.*` → `Ablo.Claim.*`. Upgrade client **and** server together (wire frames moved `intent_*` → `claim_*`) |
+| **0.28.0** | Removed React placeholders that had no working runtime | `usePresence` → `usePeers` or `useWatch`; `useClaim` → `ablo.<model>.claim`; `SyncGroupProvider` / `useSyncGroup` → `useWatch({ scope })` |
+| **0.11.0** | Historical `intent` → `claim` rename | The hook renamed in that release was later removed in 0.28.0. Current code uses `ablo.<model>.claim` or `useWatch` |
 | **0.10.0** | Environment enum renamed `test`/`live` → `sandbox`/`production` | Update code that branches on the environment (e.g. source `mode`): `'test'`→`'sandbox'`, `'live'`→`'production'`. Key prefixes `sk_test_`/`sk_live_` are unchanged |
 | **0.9.2** | `turn` primitive + agent-work `tasks` resource removed | Coordinate with `claim`; mint a scoped session instead of `agent().run()` |
 | **0.9.2** | `intents` deprecated in favor of `claim` | Use `ablo.<model>.claim`; `ablo.intents` is now `@internal` |
@@ -25,8 +26,27 @@ change when you upgrade.
 
 ---
 
+## 0.28.0 — dead React multiplayer placeholders removed
+
+Four React exports looked usable but had no live implementation:
+
+- `usePresence` returned no provider-backed presence value. Use `usePeers` for
+  read-only presence or `useWatch` to join a scoped participant.
+- `useClaim` depended on a callback the provider never supplied and always
+  threw. Use `ablo.<model>.claim({ id, ... })` for row claims or
+  `useWatch({ scope, claim: true })` for a scoped participant claim.
+- `SyncGroupProvider` and `useSyncGroup` had no repository consumers. Pass the
+  scope directly to `useWatch({ scope })`.
+
+There is no compatibility alias: the replacement APIs were already the only
+working paths.
+
 ## 0.11.0 — `intent` → `claim` rename completed
 
+> **Historical note:** this section documents the 0.11.0 transition.
+> `useClaim` was subsequently removed in 0.28.0 because its provider callback
+> was never wired. Do not migrate new code to it; use the replacements above.
+
 The coordination primitive has been `claim` since 0.9.2, but a few `intent`-named
 surfaces lingered. 0.11.0 finishes the rename. There are three edits, all
 mechanical:

package/docs/quickstart.md

@@ -191,6 +191,17 @@ const updated = await ablo.weatherReports.update({
 console.log({ id: updated.id, status: updated.status }); // { id: '...', status: 'ready' }
 ```
 
+Read a single row back with `retrieve({ id })`. It resolves to the row, or to
+`undefined` when no row has that id — so narrow it once, then the fields are
+fully typed:
+
+```ts
+const report = await ablo.weatherReports.retrieve({ id: created.id });
+if (!report) throw new Error(`weatherReports ${created.id} not found`);
+
+console.log(report.status); // 'ready'
+```
+
 ## Add coordination for slow work
 
 When AI or background work will touch an existing row for more than a quick

package/docs/react.md

@@ -178,52 +178,6 @@ imperative work after an event or effect.
 
 See [API reference](/docs/api) for the full options surface.
 
-## useClaim — named-claim dispatcher
-
-`useClaim` (renamed from `useIntent` in 0.11.0) is typed sugar for invoking a
-*named* claim from your own coordination vocabulary — distinct from the
-row-level `ablo.<model>.claim({ id })` resource claim. Use it when you want to
-broadcast a semantic claim like "I'm editing this layer" or "the agent is
-generating here" and let your transport turn it into a network effect.
-
-Declare the vocabulary once via module augmentation on the `Register` interface
-(the `Claims` key — previously `Intents`):
-
-```ts
-declare module '@abloatai/ablo' {
-  interface Register {
-    Claims: {
-      editLayer: { slideId: string; layerId: string };
-      generateWithAI: { entityId: string; tool: string };
-    };
-  }
-}
-```
-
-Then `useClaim('editLayer')` returns a function whose sole argument is the
-`editLayer` shape — purely compile-time narrowing, no runtime checks:
-
-```tsx
-'use client';
-
-import { useClaim } from '@abloatai/ablo/react';
-
-export function LayerToolbar({ slideId, layerId }: { slideId: string; layerId: string }) {
-  const claimEditLayer = useClaim('editLayer');
-
-  return (
-    <button onClick={() => claimEditLayer({ slideId, layerId })}>
-      Edit layer
-    </button>
-  );
-}
-```
-
-The hook is pure sugar: the actual network effect lives in the `beginClaim`
-function wired into the provider (bound to your transport). If no `beginClaim`
-is wired, the returned invoker throws `AbloValidationError` with code
-`claim_not_wired`.
-
 ## useWatch — scoped presence + read interest
 
 `useWatch` is the React form of `ablo.<model>.watch`. It joins multiplayer for a

package/examples/README.md

@@ -21,13 +21,14 @@ const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
 Then:
 
 - create with `ablo.weatherReports.create`
-- read with `ablo.weatherReports.load`
-- mark long-running AI work with `ablo.weatherReports.edit`
+- read with `ablo.weatherReports.retrieve` or `ablo.weatherReports.list`
+- coordinate long-running work with `ablo.weatherReports.claim`
 - write with `ablo.weatherReports.update`
-- wait for confirmation when the write must be durable before continuing
+- dispose the client when the worker finishes
 
-Use schema-less resources and `commits.create` only for advanced runtimes that
-intentionally cannot import the app schema.
+Import the same schema in every runtime. Use `commits.create` only when several
+typed row operations must land atomically; ordinary writes stay on
+`ablo.<model>.create/update/delete`.
 
 ## Running
 

package/llms.txt

@@ -8,7 +8,7 @@ Use AI SDK for the agent loop. Use Ablo when agent reads and writes must persist
 
 ## Start here
 
-First action when integrating into an app: run `npx ablo init --yes --framework <nextjs|vite|remix|vanilla>`. Agents have no TTY — `--yes` is REQUIRED or it HANGS. The default `--storage direct` (connection string) scaffolds `ablo/schema.ts`, the client, and (for Next.js) the browser provider + session route; pass `--storage endpoint` instead when database credentials must stay inside the app — that variant scaffolds a signed Data Source endpoint. All on the current API. Edit the generated files rather than hand-writing from this doc.
+First action when integrating into an app: run `npx ablo init --yes --framework <nextjs|vite|remix|vanilla>`. Agents have no TTY — `--yes` is REQUIRED or it HANGS. It scaffolds `ablo/schema.ts`, the `Ablo({ schema, apiKey })` client, and (for Next.js) the browser provider + session route. All on the current API. Edit the generated files rather than hand-writing from this doc. Connecting a database is a SEPARATE step with one path — logical replication via `npx ablo connect` (see Storage Boundary); the signed Data Source endpoint is the fallback when database credentials must stay inside the app.
 
 Second: make sure a key exists — WITHOUT printing it. The key is a secret; it must never appear in your output, your reasoning, or a file you echo (it would live in the conversation history forever). Check PRESENCE only: `[ -n "$ABLO_API_KEY" ] && echo set` and `grep -cq '^ABLO_API_KEY=' .env.local && echo wired` — never `cat .env.local`, never `echo $ABLO_API_KEY`. If neither check passes, ask the HUMAN to run `npx ablo login` once — it opens a browser and saves a `sk_test_` key locally; an agent must NOT run it. You never copy the key by hand: the next step writes it into `.env.local` (and gitignores it) for you.
 
@@ -69,14 +69,14 @@ await. The query reads accept `where`, `filter`, `orderBy`, `limit`, `offset`,
 and `state`; state defaults to `'live'`, with `'archived'` and `'all'` to include
 retired rows.
 
-Workers that can't import the app schema can use a schema-less mode (covered in
-`integration-guide`).
+Workers import the same app schema and select `transport: 'http'`. The transport
+changes; the typed `ablo.<model>` contract does not. There is no public
+schema-less or string-keyed model client.
 
 React reads should use selector `useAblo`: `useAblo((ablo) => ablo.weatherReports.get(id))` (synchronous local read, reactive in render).
 Use zero-argument `useAblo()` only when a component needs the client for an
-event handler or effect. Treat `useQuery`, `useOne`, `useReader`, and
-`useMutate` as compatibility hooks for older string-keyed integrations, not the
-first integration path.
+event handler or effect. The older string-keyed hooks (`useQuery`, `useOne`,
+`useReader`, and `useMutate`) are removed; do not import or recommend them.
 
 ## Multiplayer
 
@@ -98,9 +98,10 @@ coordination until the app reports it through Data Source events.
 ## Claimed Behavior
 
 Reads never silently block. Schema reads stay open while a row is claimed.
-Server reads through `ablo.model(name)` can pass `ifClaimed: 'return'` (the
-default — returns the row plus active claim metadata) or `ifClaimed: 'fail'`
-to throw `AbloClaimedError`.
+Typed reads through `ablo.<model>.retrieve({ id })` return the row by default,
+even while it is claimed. Pass `ifClaimed: 'fail'` to throw
+`AbloClaimedError`, and inspect active coordination separately through
+`ablo.<model>.claim.state({ id })`.
 
 Reads never block on a claim. To wait for a row to free up, `claim({ id })` it —
 the claim queues fairly behind the current holder and is granted when the row
@@ -126,9 +127,7 @@ THE ONE PATH IS LOGICAL REPLICATION. In production every schema model is backed
 
 FALLBACK (only when the database can't grant a `REPLICATION` role, e.g. a locked-down managed DB): a signed Data Source endpoint that hands Ablo an ORM `adapter` (Drizzle default; Prisma and Kysely supported) — it owns the transaction, exactly-once idempotency, and outbox in ONE pass; your credentials never leave your infrastructure.
 
-DEPRECATED — being removed, do NOT recommend or scaffold: the `databaseUrl` constructor option (the dial-in, where Ablo held a read/write connection and committed directly to your DB). The end-state constructor is `Ablo({ schema, apiKey })`; the database is connected out of band via `ablo connect`, not through `databaseUrl`. (Note: `ablo init` still defaults to `--storage direct` scaffolding `databaseUrl` — that default is itself slated to lead with `ablo connect`; prefer logical replication regardless of what `init` scaffolds.)
-
-GOTCHA the user WILL hit: `DATABASE_URL` must use a NON-superuser, NON-BYPASSRLS role (Ablo enforces row-level security; owner roles are rejected with `database_role_cannot_enforce_rls`). Neon's and Supabase's default dashboard connection strings use the database OWNER (e.g. `neondb_owner`) and are rejected. EASIEST: `npx ablo migrate` detects the unsafe role and creates the scoped one automatically from the user's machine (owner credential never reaches Ablo; new DATABASE_URL written to the env file). Manual alternative — create a scoped role first: `CREATE ROLE ablo_app LOGIN PASSWORD '...' NOSUPERUSER NOBYPASSRLS; GRANT CREATE, CONNECT ON DATABASE <db> TO ablo_app; GRANT CREATE, USAGE ON SCHEMA public TO ablo_app;` — then swap user/password into the same host/db string.
+DEPRECATED — being removed, do NOT recommend or scaffold: the `databaseUrl` constructor option (the dial-in, where Ablo held a read/write connection and committed directly to your DB). The end-state constructor is `Ablo({ schema, apiKey })`; the database is connected out of band via `ablo connect`, not through `databaseUrl`. The role rule you may have seen belongs ONLY to this dial-in: a `databaseUrl` had to name a NON-superuser, NON-BYPASSRLS role, or Ablo rejected it with `database_role_cannot_enforce_rls` (it enforced row-level security through the connection it held, so an owner/BYPASSRLS role — e.g. Neon's `neondb_owner` — would have silently skipped RLS). The WAL path retires that rule entirely: Ablo never holds a connection to your rows, so there is no `DATABASE_URL` to scope — `ablo connect` needs a `REPLICATION` role instead. `ablo init` still scaffolds `--storage direct`/`databaseUrl` for existing dial-in projects and the CLI now warns on it; prefer `ablo connect` regardless of what `init` scaffolds.
 
 ```ts
 // app/api/ablo/source/route.ts
@@ -146,7 +145,7 @@ export const { POST } = dataSourceNext({
 });
 ```
 
-`npx ablo init` defaults to `--storage direct` (the connection-string path — it scaffolds the client carrying `databaseUrl` and the `DATABASE_URL` env entry; see CLI below). Pass `--storage endpoint` to scaffold the signed Data Source endpoint above instead, when app database credentials must stay private — Ablo only calls the endpoint.
+Connect a database with `npx ablo connect` (logical replication — the one path above). The signed Data Source endpoint (code above) is the fallback when app database credentials must stay private; scaffold it with `npx ablo init --storage endpoint` — Ablo only calls the endpoint. (`--storage direct` still exists for existing dial-in projects but is deprecated; the CLI warns on it.)
 
 ## Sandboxes
 
@@ -172,7 +171,7 @@ two-writer stale/claim smoke test.
 
 Import from these public paths only:
 
-- `@abloatai/ablo` — `Ablo`, errors, typed model clients, claims, `dataSource`, and advanced protocol models.
+- `@abloatai/ablo` — `Ablo`, errors, typed model clients, claims, and `dataSource`.
 - `@abloatai/ablo/schema` — schema DSL.
 - `@abloatai/ablo/react` — React provider and hooks.
 - `@abloatai/ablo/testing` — test harnesses and mocks.
@@ -188,7 +187,8 @@ Do not teach `/api`, `/agent`, `/ai-sdk`, `/core`, `/realtime`, or internal subp
 
 `ablo init` and other prompts need a TTY; an agent/CI run has none and will HANG. Always:
 
-- `npx ablo init --yes` (flags: `--framework`, `--auth`, `--storage direct|endpoint` (default `direct`), `--no-agent`, `--no-pull`, `--no-install`, `--no-login`). Generates `ablo/schema.ts` + the client; `--storage direct` (default) wires `databaseUrl`, `--storage endpoint` scaffolds the `ablo/data-source.ts` endpoint above instead.
+- `npx ablo init --yes` (flags: `--framework`, `--auth`, `--storage direct|endpoint`, `--no-agent`, `--no-pull`, `--no-install`, `--no-login`). Generates `ablo/schema.ts` + the `Ablo({ schema, apiKey })` client. `--storage endpoint` also scaffolds the `ablo/data-source.ts` fallback endpoint; `--storage direct` (deprecated, CLI warns) wires the legacy `databaseUrl`.
+- `npx ablo connect` connects your database via logical replication — the read path (prints the `wal_level=logical` + publication + `REPLICATION`-role SQL); `npx ablo connect --register` registers it, `npx ablo connect --check` validates.
 - Key: see "Start here" — env → `.env.local` → ask the human to `npx ablo login`; never run `login` yourself, never copy keys by hand (`ablo push` writes `.env.local`).
 - Adopt an existing DB: `npx ablo pull prisma [path]` / `npx ablo pull drizzle <module>`.
 - `npx ablo push` pushes the schema (sandbox) AND writes `ABLO_API_KEY` to `.env.local`; `npx ablo dev --no-watch` is the push-once form of the watcher; `npx ablo logs --no-follow` exits instead of tailing forever; `npx ablo mode sandbox|production` always needs the argument. `npx ablo push`/`status`/`pull`/`check`/`generate` are one-shot.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/ablo",
-  "version": "0.27.0",
+  "version": "0.29.0",
   "description": "The Collaboration Layer For AI Agents",
   "license": "Apache-2.0",
   "type": "module",
@@ -158,7 +158,7 @@
     "test:e2e": "E2E_TEST=true jest --config jest.e2e.config.ts",
     "test:e2e:up": "docker compose -f docker-compose.test.yml up -d --wait",
     "test:e2e:down": "docker compose -f docker-compose.test.yml down -v",
-    "test:e2e:run": "npm run test:e2e:up && npm run test:e2e; npm run test:e2e:down"
+    "test:e2e:run": "node scripts/run-e2e.mjs"
   },
   "publishConfig": {
     "access": "public",
@@ -207,7 +207,7 @@
     "mobx": "^6.13.7",
     "mobx-react-lite": "^4.0.0",
     "uuid": "^11.1.0",
-    "zod": "^4.0.17"
+    "zod": "^4.1.11"
   },
   "devDependencies": {
     "@ai-sdk/provider": "^3.0.0",