@abloatai/ablo 0.26.0 → 0.28.0

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # Changelog
 
+## 0.28.0
+
+### Minor Changes
+
+- **Commits are now crash-durable — a sealed envelope replays the exact request after a restart, on both transports.** Before a batch reaches the wire, the WebSocket client seals it into one atomic outbox record: the stable idempotency key, the exact JSON-normalized ordered operations, and the source mutations it supersedes. Recovery replays the sealed request as it was sent — never re-projected from model state in the new process — and a multi-operation commit is only ever replayed whole, so an atomic A+B can't come back later as A and B separately.
+
+- **The stateless HTTP client replays its outbox on startup.** It persists the exact request (method, path, body, idempotency key) and re-sends unacknowledged envelopes before its first new request. A definitive rejection (a 4xx other than 429) settles the envelope instead of retrying it.
+
+- **New `commitOutbox` client option + `CommitOutboxStore` interface.** Browsers default to strict IndexedDB storage when persistence is on; Node agents and workers can inject workflow-, SQLite-, or filesystem-backed storage so commits survive process restarts. The client's transaction journal now writes with strict durability, so an acknowledged outbox record means disk-backed.
+
+- **Replay is fenced and fails closed.** Reusing an idempotency key with a different request is rejected on both transports; replay is scoped to the actor and server that sealed the envelope and bounded to the server's idempotency retention, so a stale envelope is held for review instead of re-sent; a write queued behind an ambiguous predecessor waits for it to settle rather than overtaking it; and a persistence adapter that cannot guarantee durability reports failure instead of phantom success. Generated create ids are sealed with the request, so a crash mid-create recovers the same row.
+
+- **`@abloatai/ablo/commit` publishes the transport-independent v2 commit contract.** Branded identifiers, ordered operations, explicit write preconditions (`unchanged_since`, `version_matches`, `claim_fence`), and a discriminated `CommitReceipt` — `committed`, `conflicted` (carrying the smallest current state needed to reconcile), or `rejected` (a typed error plus the capability a retry would need). This release publishes the contract so tooling and tests can validate against it today; the engine's live commit path still speaks the current protocol, and the cutover to v2 ships server-side.
+
+- **New wire exports.** `@abloatai/ablo/wire` gains the matching `CommitRequestMessage` / `CommitResultMessage` frames, re-exports the current transport's operation schemas under `legacyCommit*` names, and exports `BootstrapReason` — the machine-readable reasons a live delta stream must resume via catch-up (`too_far_behind`, `too_many_deltas`, `missing_entities`, `stream_gap`).
+
+- **Reactive reads are typed as what they actually return: snapshot rows, not model instances.** `useAblo` selectors now receive `AbloReads<Schema>` — model reads typed as the row's data fields plus schema computeds, without relation accessors or model methods. Reading `row.layers` inside a selector is a compile error instead of a silent `undefined` at runtime; compose relations through a dedicated hook or selector instead. The new `Row<'slides'>` / `InferRow` types are the snapshot-row companion to `Model<'slides'>`, mirroring what `toReactiveSnapshot()` produces. This is a type-level change only: selectors that compiled against relation accessors now fail to compile, and each of those reads was already returning `undefined` — the new errors point at real bugs. Runtime behavior is unchanged.
+
+### Patch Changes
+
+- **The resume cursor advances only through the contiguous durable prefix of a delta frame.** A frame spanning several local stores commits per store, and those transactions can fail independently — taking the maximum id from any successful store could permanently skip an earlier failed delta on every later catch-up.
+
+- **Conflicting undo-scope options warn instead of being silently ignored.** A scope keeps the options it was created with; the silent version of that rule could leave a surface believing it enabled stream recording when it hadn't.
+
+- **Docs and error copy name the real HTTP mount.** REST paths are documented as `/api/v1/...` — the OpenAPI server URLs carry the `/api` mount — and the `jwt_issuer_untrusted` message no longer points at an endpoint that doesn't exist.
+
+## 0.27.0
+
+### Minor Changes
+
+- **Claims can now be held for long-running work by heartbeating — on both transports.** A claim's TTL is crash cleanup, not a work estimate; work that outlives it (a 30-minute report, a long agent run) keeps its lease by beating. `claim({ heartbeat: true })` beats automatically until release; `held.heartbeat()` beats by hand. A lapsed lease answers the next beat with `AbloClaimedError` (`claim_lost`) — for a socketless worker, the failed beat _is_ the loss notification, and any write attempted under the old lease is independently rejected by its `readAt` guard.
+
+- **Beats carry progress and pressure.** `heartbeat({ details })` stores lightweight progress as the claim's peer-visible `meta.progress` (last beat wins, via `claim.state`); every beat's answer reports `queueDepth` — how many participants wait in line behind the lease — observable per auto-beat with the new `onHeartbeat` claim option.
+
+- **`ablo.claims.heartbeatAll({ ttl })`** extends every lease the credential holds in one request (`POST /api/v1/claims/heartbeat`) — the stateless twin of the WebSocket keepalive, for workers holding many rows.
+
+- **Keepalive renewals extend but never shorten a lease**, so an explicit work-duration `ttl` now survives pings and brief reconnects instead of collapsing to the liveness window.
+
+- **README.** The quick start leads with a runnable example, and a new _Background workers_ section shows the enqueue-on-your-own-queue / heartbeat-the-claim pattern end to end.
+
 ## 0.26.0
 
 ### Minor Changes
@@ -25,7 +65,7 @@
 ### Minor Changes
 
 - ca30064: Logical replication is now the documented default storage path, with self-service data-source registration from the CLI.
-  - **`ablo connect --register`** — registers your database as an Ablo data source over logical replication in one step: it runs the same pre-flight replication probe `ablo connect` uses (server reachable, `REPLICATION` privilege, `wal_level=logical`, publication/slot creatable), and on success `POST`s the connection to the engine's `/v1/datasources`. The `ek_`-authed call scopes the source to your org automatically; the password is stored decomposed as a secret, never echoed back. This is the "registration is the enable" path — there is no separate tier or flag to pick.
+  - **`ablo connect --register`** — registers your database as an Ablo data source over logical replication in one step: it runs the same pre-flight replication probe `ablo connect` uses (server reachable, `REPLICATION` privilege, `wal_level=logical`, publication/slot creatable), and on success `POST`s the connection to the engine's `/api/v1/datasources`. The `ek_`-authed call scopes the source to your org automatically; the password is stored decomposed as a secret, never echoed back. This is the "registration is the enable" path — there is no separate tier or flag to pick.
   - **`ablo init` leads with logical replication** — the default storage mode is now `replication` (was `endpoint`); the generated env + next-steps point at `ablo connect` / `ablo connect --register`. The signed-endpoint and direct modes remain as the explicit fallback / legacy options.
   - **`ablo status`** — a data-plane diagnostic that probes whether your registered source is reachable and replicating (failure-only reporting, so it never falsely reports healthy).
   - **`ablo push`** — minor guard/UX refinements (deploy-target clarity).
@@ -580,7 +620,7 @@
 
 ### Patch Changes
 
-- `Model<'name'>` type helper via the `Register` binding — name your model in one parameter (`Model<'tasks'>`) instead of restating `typeof schema`; `Model<S, 'name'>` is also supported and `InferModel` is deprecated. CLI: retire the stale `dev` wording from the login outro and `push` header. Docs: cover the `Register` binding end-to-end and document the `pk_` publishable key + the `/v1/commits` HTTP path.
+- `Model<'name'>` type helper via the `Register` binding — name your model in one parameter (`Model<'tasks'>`) instead of restating `typeof schema`; `Model<S, 'name'>` is also supported and `InferModel` is deprecated. CLI: retire the stale `dev` wording from the login outro and `push` header. Docs: cover the `Register` binding end-to-end and document the `pk_` publishable key + the `/api/v1/commits` HTTP path.
 - 3024593: Fix `sessions.create({ user })` 403 — user sessions now mint via the sk\_-gated ephemeral-key door
   - `sessions.create({ user })` mints an `ek_` user session via `/auth/ephemeral-keys` (was wrongly routed through `/auth/capability`, which rejects human participants — writes were being attributed to agents).
   - Control-plane calls always present your original `sk_`, never the client's exchanged sync credential.

package/README.md

@@ -39,10 +39,10 @@ Under the hood, you define your data once with a Zod schema and get the same
 typed model client for every actor — people, server actions, and agents:
 
 ```ts
-await ablo.task.create({ data })                  // create
-await ablo.task.retrieve({ id })                  // read
-await ablo.task.update({ id, data })              // update
-await using task = await ablo.task.claim({ id })  // claim for safe, slow agent work
+await ablo.weatherReports.create({ data })                  // create
+await ablo.weatherReports.retrieve({ id })                  // read
+await ablo.weatherReports.update({ id, data })              // update
+await using claim = await ablo.weatherReports.claim({ id }) // hold for slow agent work
 ```
 
 The schema is the public contract. It gives you typed model methods, realtime
@@ -63,8 +63,9 @@ yet? A **sandbox** `sk_test` key holds throwaway **test data** — like Stripe t
 mode — so you can explore before pointing it at your Postgres. Test-mode only; in
 production every row lives in your database.)
 
-**Built for** collaborative editors, AI agent workflows, and internal tools —
-anywhere people and agents change shared state and everyone has to see it live.
+**Built for** collaborative editors, AI agent workflows, background workers on
+your own infrastructure, and internal tools — anywhere people and agents change
+shared state and everyone has to see it live.
 
 ## Set up
 
@@ -111,62 +112,15 @@ instead of guessing:
 
 ## Quick Start
 
+One schema, one client, one write path for humans and agents — this runs as-is
+after `ablo push`:
+
 ```ts
 import Ablo from '@abloatai/ablo';
 import { defineSchema, model, z } from '@abloatai/ablo/schema';
-```
-
-The schema is registered once (init scaffolds `ablo/register.ts` for you), and
-every type is one parameter away — no `typeof schema` re-stating, anywhere:
-
-```ts
-// ablo/register.ts — scaffolded by `npx ablo init`, sits beside ablo/schema.ts
-import type { schema } from './schema';
-declare module '@abloatai/ablo' {
-  interface Register { Schema: typeof schema }
-}
-export {};
-```
-
-It's a regular `.ts` module, not a hand-authored `.d.ts`. The top-level
-`import type { schema }` makes the `declare module` block *merge* into (augment)
-the SDK's `Register` interface instead of colliding with it — the same shape
-[TanStack Router uses in `src/router.tsx`](https://tanstack.com/router/latest/docs/framework/react/guide/type-safety). Any `.ts` file in your
-`tsconfig` `include` works; it never needs to be imported.
-
-```ts
-import type { Model } from '@abloatai/ablo/schema';
-
-type WeatherReport = Model<'weatherReports'>; // fully typed from YOUR schema
-```
-
-(The same `Register` binding types every hook and client — it's the
-TanStack-Router pattern: declare the source of truth once, everything
-infers from it.)
 
-### Naming the client type
-
-When you need to pass the client around (a function parameter, a context value),
-**infer the type from the value** — `type Sync = typeof sync`:
-
-```ts
-export const sync = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
-export type Sync = typeof sync; // fully-typed, schema-aware
-
-function persist(client: Sync) { /* ... */ }
-```
-
-This is the same idiom as tRPC's `type AppRouter = typeof appRouter` and
-Drizzle's `typeof db` — the factory resolves the typed overload at the call
-site, so `typeof sync` carries your schema. Do **not** write
-`ReturnType<typeof Ablo>`: that collapses to the untyped last overload and
-loses your model types. There is no bespoke client-type generic to import —
-`typeof` your client value is the type.
-
-```ts
 const schema = defineSchema({
-  // Reserved fields (id, createdAt, updatedAt, organizationId, createdBy) are
-  // provided automatically — don't declare them.
+  // id, createdAt, updatedAt, organizationId, createdBy come free on every model
   weatherReports: model({
     location: z.string(),
     status: z.enum(['pending', 'ready']),
@@ -174,29 +128,21 @@ const schema = defineSchema({
   }),
 });
 
-const ablo = Ablo({
-  schema,
-  apiKey: process.env.ABLO_API_KEY, // written to .env.local by `npx ablo push`
-});
-// Your Postgres is connected once via `npx ablo connect` (logical replication) —
-// not passed here. Ablo tails its WAL; your rows never leave your database.
-
+const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
 await ablo.ready();
 
 const created = await ablo.weatherReports.create({
-  data: {
-    location: 'Stockholm',
-    status: 'pending',
-  },
+  data: { location: 'Stockholm', status: 'pending' },
 });
 
-// An agent claims the row, does its slow work, then writes back. While the
-// claim is held nobody else can overwrite it; anyone else who tries waits in
-// line and re-reads the result. This is the whole point of Ablo.
+// Claim the row before slow work — anyone else waits in line, then re-reads.
 await using claim = await ablo.weatherReports.claim({ id: created.id });
-const report = claim.data;
-const forecast = await fetchForecast(report.location); // slow: API or LLM call
-await ablo.weatherReports.update({ id: report.id, data: { status: 'ready', forecast } });
+const forecast = await fetchForecast(claim.data.location); // slow: API or LLM call
+await ablo.weatherReports.update({
+  id: created.id,
+  data: { status: 'ready', forecast },
+  claim, // the write completes the claimed work and releases the lease
+});
 
 const ready = ablo.weatherReports.get(created.id);
 console.log({ id: ready?.id, status: ready?.status });
@@ -210,6 +156,38 @@ Expected output:
 { id: '...', status: 'ready' }
 ```
 
+### TypeScript setup (once, scaffolded for you)
+
+`npx ablo init` writes `ablo/register.ts` next to your schema. It binds your
+schema to the SDK's types once — the same declaration-merging shape
+[TanStack Router uses](https://tanstack.com/router/latest/docs/framework/react/guide/type-safety) —
+so every hook and client infers from it:
+
+```ts
+// ablo/register.ts — scaffolded by `npx ablo init`
+import type { schema } from './schema';
+declare module '@abloatai/ablo' {
+  interface Register { Schema: typeof schema }
+}
+export {};
+```
+
+```ts
+import type { Model } from '@abloatai/ablo/schema';
+
+type WeatherReport = Model<'weatherReports'>; // fully typed from your schema
+```
+
+To pass the client around, take the type from the value — the tRPC /
+Drizzle idiom:
+
+```ts
+export const sync = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
+export type Sync = typeof sync;
+
+function persist(client: Sync) { /* ... */ }
+```
+
 ## Reading
 
 Two ways to read, depending on whether you can wait. `get(id)` / `getAll({ where })`
@@ -262,7 +240,11 @@ meanwhile, or worse, acts on stale state. `claim` holds the row across that gap:
 await using claim = await ablo.weatherReports.claim({ id: 'report_stockholm' });
 const report = claim.data;
 const forecast = await weatherAgent.getWeather(report.location);
-await ablo.weatherReports.update({ id: report.id, data: { forecast, status: 'ready' } });
+await ablo.weatherReports.update({
+  id: report.id,
+  data: { forecast, status: 'ready' },
+  claim, // attribute the write to the held claim
+});
 ```
 
 If someone else holds the row, `claim()` waits in a fair queue, then re-reads —
@@ -311,6 +293,46 @@ try {
 See [Coordination](./docs/coordination.md) for the full `claim` / `claim.state` /
 `claim.queue` / `claim.release` reference.
 
+## Background workers — jobs that run for minutes, not seconds
+
+Your API route enqueues a job on your own queue (SQS, EventBridge, anything);
+a worker on your own infrastructure does the slow part. **Keep that queue —
+Ablo is the worker's data layer.** It covers the two things every queue leaves
+to you: keeping the row safe, and showing progress live.
+
+Long work holds its claim by **heartbeating** — the same pattern as an SQS
+visibility heartbeat or a Temporal activity heartbeat:
+
+```ts
+// on your worker — stateless HTTP, no socket to hold
+await using claim = await ablo.weatherReports.claim({
+  id: msg.reportId,
+  ttl: '10m',
+  heartbeat: true,                 // beats automatically until release
+  onHeartbeatLost: () => abort(),  // the lease is gone → stop working
+});
+
+for (const step of steps) {
+  await runStep(step);
+  // write progress to the row — every subscribed UI updates live
+  await ablo.weatherReports.update({ id: msg.reportId, data: { progress: step.pct }, claim });
+}
+```
+
+- A worker that **crashes** stops beating; the row frees within one beat and
+  the next worker takes over.
+- A worker that **wakes up late** learns it on its next beat
+  (`AbloClaimedError`), and the write path rejects its stale writes anyway.
+- **Retries stay on your queue** — the redelivered job claims the now-free
+  row, reads its current state, and resumes.
+- A worker holding **many rows** extends them all in one call:
+  `ablo.claims.heartbeatAll({ ttl: '5m' })`.
+
+SQS's heartbeat protects the *message* from redelivery; Ablo's protects the
+*row* from concurrent and stale writes. SQS is at-least-once, so two workers
+will eventually get the same job — the claim is what keeps that from
+corrupting data.
+
 ## React
 
 In a React app it's the **same `ablo.<model>` API** — just mounted through a
@@ -420,7 +442,7 @@ HTTP endpoint when a server-to-server caller needs to write without opening a
 WebSocket:
 
 ```bash
-curl https://api.abloatai.com/v1/commits \
+curl https://api.abloatai.com/api/v1/commits \
   -H "Authorization: Bearer sk_test_..." \
   -H "Content-Type: application/json" \
   -d '{ "operations": [
@@ -445,14 +467,8 @@ connects:
 | **Logical replication** (primary) | `npx ablo connect` prints the setup SQL (`wal_level=logical`, a publication, a `REPLICATION` role); `npx ablo connect --register` tells Ablo to replicate it. Ablo tails the WAL — it never runs DDL on, writes to, owns, or migrates your database. | Your database can grant a `REPLICATION` role (most can). |
 | **Signed endpoint** (fallback) | Your app exposes one route built from an ORM adapter (`prismaDataSource` / `drizzleDataSource`); Ablo sends signed requests and your app touches its own database. Needs no database configuration. | Your database **can't** grant a replication role (a locked-down managed DB). |
 
-(No database yet? A **sandbox** `sk_test` key lets you try Ablo's full API and
-coordination with throwaway **test data** — like Stripe test mode — before you
-connect your own Postgres. Test-mode only: in production your rows always live in
-your database and Ablo holds just the transaction log, never your data.)
-
-Your database is the system of record. The old `databaseUrl` dial-in (Ablo
-holding a read/write connection) is **deprecated and being removed** — connect
-via logical replication instead. See
+Your database is the system of record — Ablo holds the transaction log and
+coordination, never your rows. See
 [Connect Your Database](./docs/data-sources.md).
 
 ## Configuration
@@ -466,7 +482,7 @@ Every other option has correct defaults:
 | --- | --- | --- | --- |
 | `schema` | `Schema` | — (required) | Typed model proxies (`ablo.<model>.*`) |
 | `apiKey` | `string \| ApiKeySetter \| null` | `process.env.ABLO_API_KEY` | Server key — a string, or an async function for rotation |
-| `databaseUrl` | `string \| null` | `—` | **Deprecated — being removed.** The old dial-in (Ablo holding a read/write connection to your DB). Connect via `npx ablo connect` (logical replication) instead; Ablo tails your WAL rather than dialing in. See [Connect Your Database](./docs/data-sources.md). |
+| `databaseUrl` | `string \| null` | `—` | Deprecated. Connect via `npx ablo connect` instead — see [Connect Your Database](./docs/data-sources.md). |
 
 Keep `apiKey` in trusted server runtimes. In the browser, `<AbloProvider>`
 authenticates with the signed-in user's session; the raw-key path is gated
@@ -519,7 +535,7 @@ contract; there are no retry or timeout knobs to tune.
 - [Guarantees](./docs/guarantees.md) — confirmed writes, stale-write protection, claim coordination, and agent lifecycle.
 - [Integration Guide](./docs/integration-guide.md) — integrate React, your database, multiplayer, and agents.
 - [React](./docs/react.md) — `<AbloProvider>`, `useAblo`, presence, status, and bootstrap gating.
-- [Coordination](./docs/coordination.md) — `claim` / `claim.state` / `claim.queue` / `claim.release` reference: hold a row across slow agent work, and observe the line waiting behind it.
+- [Coordination](./docs/coordination.md) — `claim` / `claim.state` / `claim.queue` / `claim.release` / `heartbeat` reference: hold a row across slow agent work — minutes or hours, via heartbeats — and observe the line waiting behind it.
 - [Client Behavior](./docs/client-behavior.md) — options, errors, retries, timeouts, and public imports.
 - [Connect Your Database](./docs/data-sources.md) — connect your Postgres by logical replication (`npx ablo connect`) or, as a fallback, a signed endpoint; your database is the system of record either way.
 - [Existing Python Backend](./docs/examples/existing-python-backend.md) — migrate existing Python endpoints to multiplayer and agent-safe writes gradually.