@abloatai/ablo 0.35.0 → 0.36.0

package/docs/migration.md

@@ -13,6 +13,7 @@ change when you upgrade.
 
 | Version | What changed | What to do |
 |---|---|---|
+| **0.36.0** | `ttlSeconds` deprecated on the join surfaces in favour of `ttl` | `useJoin({ scope, ttlSeconds: '5m' })` → `useJoin({ scope, ttl: '5m' })`; same for `ParticipantJoinOptions`. Both spellings work until 0.37.0 |
 | **0.35.0** | Synchronous reads moved under `local`, mirroring the async verbs | `get(id)` → `local.retrieve(id)`; `getAll(options)` → `local.list(options)`; `getCount(options)` → `local.count(options)` |
 | **0.35.0** | `causedByTaskId` write option + seven `turn_*` error codes removed | Delete the `causedByTaskId` argument from writes; a branch on `turn_validation_failed` was unreachable and can go with it |
 | **0.34.0** | Presence verb renamed `watch` → `join` | `ablo.<model>.watch(ids)` → `ablo.<model>.join(ids)`; `useWatch` → `useJoin`; the `WatchOptions` / `UseWatchOptions` / `UseWatchReturn` types → `JoinOptions` / `UseJoinOptions` / `UseJoinReturn`; error code `model_watch_not_configured` → `model_join_not_configured` |
@@ -31,7 +32,25 @@ change when you upgrade.
 
 ---
 
-## 0.35.0 — the synchronous reads move under `local`
+## 0.36.0: one lease is spelled `ttl`
+
+```diff
+- useJoin({ scope: { documents: [id] }, ttlSeconds: '5m' })
++ useJoin({ scope: { documents: [id] }, ttl: '5m' })
+```
+
+`ablo.<model>.join(ids, { ttl })` has always said `ttl`, and so does every other
+lease in the SDK: `claim`'s `ttl`, `ClaimLeaseOptions.ttl`. The lower-level join
+surfaces said `ttlSeconds` while accepting exactly the same values, including
+duration strings, so a `ttl: '5m'` handed down from the model verb arrived as
+`ttlSeconds: '5m'`, a field asserting a unit its value did not carry.
+
+Both spellings work until 0.37.0, and `ttl` wins if you pass both. The wire is
+unchanged: it has always carried seconds and still does.
+
+---
+
+## 0.35.0: the synchronous reads move under `local`
 
 ```diff
 - const task  = ablo.tasks.get(id);
@@ -53,7 +72,7 @@ in most codebases it is outnumbered many times over by `Map.get` and
 the compiler name the sites — each one is a type error at exactly the call that
 has to move.
 
-## 0.35.0 — `causedByTaskId` and the `turn_*` error codes removed
+## 0.35.0: `causedByTaskId` and the `turn_*` error codes removed
 
 0.9.2 retired the `turn` primitive but left one field standing: `causedByTaskId`
 on the write options bag. It was never usable. The server validated it against a
@@ -85,7 +104,7 @@ migration of its own.
 
 ---
 
-## 0.34.0 — presence verb renamed `watch` → `join`
+## 0.34.0: presence verb renamed `watch` → `join`
 
 The model-level presence verb read like a data subscription but delivered
 presence — who else is on a row and what they hold — so it now says what it
@@ -108,7 +127,7 @@ no compatibility alias — rename the call sites and the `WatchOptions` /
 
 ---
 
-## 0.28.0 — dead React multiplayer placeholders removed
+## 0.28.0: dead React multiplayer placeholders removed
 
 Four React exports looked usable but had no live implementation:
 
@@ -123,7 +142,7 @@ Four React exports looked usable but had no live implementation:
 There is no compatibility alias: the replacement APIs were already the only
 working paths.
 
-## 0.11.0 — `intent` → `claim` rename completed
+## 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
@@ -166,7 +185,7 @@ contending holders (`AbloClaimedError.claims` and a policy reason folded into th
 message), and `participantKind` is the canonical `'user' | 'agent' | 'system'`
 on presence and claim state.
 
-## 0.10.0 — environment enum `sandbox` / `production`; stateless HTTP transport
+## 0.10.0: environment enum `sandbox` / `production`; stateless HTTP transport
 
 ### Environment enum rename (the only breaking change)
 
@@ -222,7 +241,7 @@ await ablo.tasks.update({ id, data: { status: 'done' } });
 
 ---
 
-## 0.9.2 — `turn` / agent-`tasks` removed; `intents` deprecated
+## 0.9.2: `turn` / agent-`tasks` removed; `intents` deprecated
 
 The SDK's coordination surface is now exactly two things: `ablo.<model>` writes
 and `claim`. The parallel `turn` / agent-`tasks` mechanism was redundant —
@@ -271,7 +290,7 @@ everywhere you coordinate concurrent work.
 
 ---
 
-## 0.9.0 — one options object per verb; disposable `claim`
+## 0.9.0: one options object per verb; disposable `claim`
 
 Every model verb takes a single options object, so the id, the data, and every
 modifier are named siblings. Reactive local reads stay on the synchronous
@@ -305,7 +324,7 @@ options object.
 
 ---
 
-## 0.8.0 — callable `claim` namespace
+## 0.8.0: callable `claim` namespace
 
 The flat coordination methods are gone; everything lives under `claim`.
 
@@ -318,7 +337,7 @@ The flat coordination methods are gone; everything lives under `claim`.
 
 ---
 
-## 0.7.0 — legacy React hooks removed
+## 0.7.0: legacy React hooks removed
 
 The query/mutation hooks were replaced by the single `useAblo()` accessor over
 typed model methods.
@@ -340,7 +359,7 @@ shape with the canonical `{ type, code, message, doc_url, request_id }` envelope
 
 ---
 
-## 0.6.0 — `onChange` and the Resource → Model rename
+## 0.6.0: `onChange` and the Resource → Model rename
 
 ```diff
 - ablo.tasks.subscribe(cb)
@@ -356,7 +375,7 @@ Also renamed: `Ablo.Resource.*` → `Ablo.Model.*`, `ModelTarget.resource` →
 
 ---
 
-## 0.5.0 — intent-handle method renames
+## 0.5.0: intent-handle method renames
 
 On the model intent handle (`ablo.<model>.intent(id)`):
 
@@ -373,7 +392,7 @@ unchanged at this release. (They were later folded under `claim` in 0.9.2.)
 
 ---
 
-## 0.3.0 — umbrella `<AbloProvider>`
+## 0.3.0: umbrella `<AbloProvider>`
 
 One provider component now owns the full React lifecycle. `<SyncProvider>`,
 `createAbloContext()`, and `withSync` were removed.
@@ -407,10 +426,10 @@ old code or old docs, this is the through-line:
 
 | Release | State of coordination |
 |---|---|
-| 0.4.0 | `ablo.<model>.intent(id)` introduced — per-entity intent handle |
+| 0.4.0 | `ablo.<model>.intent(id)` introduced: per-entity intent handle |
 | 0.5.0 | Intent-handle methods renamed to claim vocabulary (`acquire`→`claim`, …) |
 | 0.8.0 | Callable `claim` namespace (`claim(id)`, `claim.state`, `claim.queue`, …) |
 | 0.9.0 | `claim` returns an `await using` disposable handle |
-| 0.9.2 | `intents` deprecated and made `@internal` — **`claim` is the one coordination API** |
+| 0.9.2 | `intents` deprecated and made `@internal`: **`claim` is the one coordination API** |
 
 For the full chronological history, see the [Changelog](../CHANGELOG.md).

package/docs/projects.md

@@ -95,5 +95,5 @@ another org's project ids 404 — never confirm existence across orgs.
 
 | Code | Status | Meaning |
 |------|--------|---------|
-| `project_scope_denied` | 403 | The model/resource belongs to another project in your org — use a key minted for that project. |
+| `project_scope_denied` | 403 | The model/resource belongs to another project in your org: use a key minted for that project. |
 | `project_slug_taken` | 409 | A project with this slug already exists in the organization. |

package/docs/react.md

@@ -27,6 +27,7 @@ the thing, then pass it.
 ```ts
 // lib/ablo.ts
 import Ablo from '@abloatai/ablo';
+import { createAbloReact } from '@abloatai/ablo/react';
 import { schema } from '@/ablo/schema';
 
 // The browser never holds your API key. It mints a short-lived session token
@@ -35,8 +36,18 @@ export const ablo = Ablo({
   schema,
   authEndpoint: '/api/ablo-session',
 });
+
+// The typed binding: capture the schema once, and every component imports
+// born-typed hooks from this file — `useAblo()` takes no type arguments,
+// and a selector's `ablo` parameter knows your models.
+export const { AbloProvider, useAblo } = createAbloReact(schema);
 ```
 
+Import `AbloProvider` and `useAblo` from `lib/ablo` rather than from the
+package, and the schema generic never appears at a call site again — the
+same one-binding-file convention as tRPC's `createTRPCReact` or
+react-redux's typed hooks.
+
 ## AbloProvider
 
 Mount it once near the root of your tree. It owns the connection, the local
@@ -67,10 +78,10 @@ export function Providers({
 
 | Prop        | Default          | Purpose                                                                                                   |
 | ----------- | ---------------- | --------------------------------------------------------------------------------------------------------- |
-| `client`    | —                | **Required.** The `Ablo({ schema, apiKey })` instance. It carries the schema and connection config. |
+| `client`    |: | **Required.** The `Ablo({ schema, apiKey })` instance. It carries the schema and connection config. |
 | `userId`    | resolved from auth | App participant id for app-owned fields and your `identityRoles`. Not the security boundary.            |
 | `fallback`  | neutral spinner  | Rendered during the *first* bootstrap only. Pass a branded skeleton, `null`, or `'passthrough'`.          |
-| `onError`   | —                | Engine / WebSocket / bootstrap errors. Wire to Sentry / Datadog.                                          |
+| `onError`   |: | Engine / WebSocket / bootstrap errors. Wire to Sentry / Datadog.                                          |
 
 Everything that used to be a provider prop — `schema`, `url`, `apiKey`,
 `teamIds`, `syncGroups`, `persistence`, `bootstrapMode` — now lives on
@@ -79,7 +90,7 @@ identity comes from, and why the API key never reaches the browser, is the whole
 of [Identity & Sync Groups](./identity.md) — read that if it isn't obvious how
 org / team / user map to what a participant can see.
 
-## useAblo — model client
+## useAblo: model client
 
 ```tsx
 'use client';
@@ -180,7 +191,7 @@ imperative work after an event or effect.
 
 See [API reference](/docs/api) for the full options surface.
 
-## useJoin — scoped presence + read interest
+## useJoin: scoped presence + read interest
 
 `useJoin` is the React form of `ablo.<model>.join`. It joins multiplayer for a
 scope on the engine's existing socket (one TCP connection, N logical
@@ -209,10 +220,10 @@ Options (`UseJoinOptions`):
 
 | Option | Default | Effect |
 | --- | --- | --- |
-| `scope` | — | Model-form scope (`{ slideDecks: id }`), resolved through the schema. Omit for engine-wide. |
-| `claim` | `false` | Acquire a write-claim on the scope (sent so peers observe it; pins the scope so it never warm-drops while held). A viewer is not a claimant — leave `false` for read-only. |
+| `scope` |: | Model-form scope (`{ slideDecks: id }`), resolved through the schema. Omit for engine-wide. |
+| `claim` | `false` | Acquire a write-claim on the scope (sent so peers observe it; pins the scope so it never warm-drops while held). A viewer is not a claimant: leave `false` for read-only. |
 | `hydrate` | `false` | Backfill the scope's current rows into the pool once on enter, then keep them fresh via the live tail. Set `true` for deep-linked / never-opened entities. Single-flight; soft-fails. |
-| `ttlSeconds` | — | Lease TTL for the scope claim. |
+| `ttlSeconds` |: | Lease TTL for the scope claim. |
 | `paused` | `false` | Tear down and don't re-join while true. |
 
 Returns (`UseJoinReturn`): `{ participant, peers, claims, status, error }`.
@@ -220,7 +231,7 @@ Returns (`UseJoinReturn`): `{ participant, peers, claims, status, error }`.
 write-claims; `status` is the join lifecycle. Auto-cleans up on unmount or when
 `paused` flips true.
 
-## usePeers — read-only presence
+## usePeers: read-only presence
 
 `usePeers` is a *pure reader* of the presence stream already flowing on the
 connection. Unlike `useJoin`, it does **not** enter/leave a scope (no

package/docs/sessions.md

@@ -175,7 +175,7 @@ Your schema lives in a **project** — you push it once (`npx ablo push`) and ev
 session you mint resolves against it. The flow for serving end-users:
 
 1. **Push your schema** to your project.
-2. **Mint an `ek_` per user** — `sessions.create({ user: { id } })`. Your users
+2. **Mint an `ek_` per user:** `sessions.create({ user: { id } })`. Your users
    commit to that one schema.
 
 **Your users do not have Ablo accounts.** You authenticate them however you

package/docs/webhooks.md

@@ -25,7 +25,7 @@ There are two ways data flows out of Ablo, and they're for different jobs:
 | | reaches | use it for |
 |---|---|---|
 | **Realtime** (`useAblo`, WSS) | your live UI | instant, optimistic rendering |
-| **Webhooks** (this page) | your database | a durable copy you own — analytics, backups, server logic |
+| **Webhooks** (this page) | your database | a durable copy you own: analytics, backups, server logic |
 
 Most apps use both: the realtime stream for the UI, the webhook stream to keep
 their database in sync. This page is the webhook stream.
@@ -34,8 +34,8 @@ If you know Stripe, you already know the shape:
 
 | Stripe | Ablo |
 |---|---|
-| `stripe.x.create(...)` — make the change | the Ablo client — make the change (+ live sync) |
-| `/stripe-webhook` — confirm and persist | `/api/ablo/[...all]` — persist into your database |
+| `stripe.x.create(...)`: make the change | the Ablo client: make the change (+ live sync) |
+| `/stripe-webhook`: confirm and persist | `/api/ablo/[...all]`: persist into your database |
 | Stripe owns the charges | Ablo owns the transaction log |
 | you mirror charges into your database | you mirror the log into your database |
 
@@ -50,11 +50,11 @@ Every delivery is a batch of events. Each event:
 | field | meaning |
 |---|---|
 | `type` | `"<model>.<verb>"` with the model name lowercased, e.g. `task.updated` |
-| `model` | the model name exactly as declared in your schema — the table to write |
+| `model` | the model name exactly as declared in your schema: the table to write |
 | `objectId` | the changed row's id |
 | `data` | the post-change row, or `null` on delete (like Stripe's `event.data.object`) |
-| `syncId` | monotonic log position — **dedupe and order by this** |
-| `id` | `String(syncId)` — the event id |
+| `syncId` | monotonic log position: **dedupe and order by this** |
+| `id` | `String(syncId)`: the event id |
 | `createdAt` | ISO commit timestamp |
 
 ```ts
@@ -200,8 +200,8 @@ sequenceDiagram
 
 | behavior | how it works |
 |---|---|
-| **Ordering** | Every event carries `syncId`, a monotonic log position. Apply in `syncId` order — Ablo guarantees the order because it owns the log. |
-| **Retries** | A non-`2xx` (or no response within the timeout) is retried with backoff: immediate, 5s, 5m, 30m, 2h, 5h, 10h, 10h — 8 attempts over ~32h. |
+| **Ordering** | Every event carries `syncId`, a monotonic log position. Apply in `syncId` order: Ablo guarantees the order because it owns the log. |
+| **Retries** | A non-`2xx` (or no response within the timeout) is retried with backoff: immediate, 5s, 5m, 30m, 2h, 5h, 10h, 10h: 8 attempts over ~32h. |
 | **Auto-disable** | After the retries exhaust, the endpoint is marked `disabled` and delivery stops until you `ablo webhooks enable <id>`. |
 | **Replay** | Nothing is lost on failure: the log *is* the durable buffer, and delivery resumes from the endpoint's cursor once it's healthy. |
 
@@ -213,7 +213,7 @@ sequenceDiagram
 - **Return `2xx` fast.** Acknowledge first, then do slow work asynchronously.
 - **Subscribe to only what you need.** Set `enabledEvents` to the models you
   mirror (`['*']` is the default = all).
-- **Roll secrets periodically.** `ablo webhooks roll <id>` mints a new secret;
+- **Roll secrets periodically:** `ablo webhooks roll <id>` mints a new secret;
   Standard Webhooks supports a rotation window so in-flight events still verify.
 - **Verify the raw body.** Frameworks that re-serialize JSON will break the
   signature — verify the bytes you received.

package/llms.txt

@@ -1,12 +1,12 @@
 # Ablo
 
-Ablo is the agentic coordination layer: one API for AI agents, apps, and services to claim, change, and confirm the same rows.
+Ablo is collaboration infrastructure for AI agents: one API for agents, apps, and services to claim, change, and confirm the same rows.
 
-Here is the problem it solves. Two agents reach for `report_stockholm` at once. One claims the row, does slow work (an LLM call, a fetch, a chain of tools), and commits. The second is neither rejected nor allowed to clobber: it waits in line, is handed the row as it now stands, and proceeds. Claims don't lock. If another writer holds the row, `claim` waits for them, re-reads the fresh row, then hands it to you — so writers serialize instead of colliding. A person editing that row is simply another holder; the agent waits behind them the same way.
+Here is the problem it solves. Two agents reach for `report_stockholm` at once. One claims the row, does slow work (an LLM call, a fetch, a chain of tools), and commits. The second is neither rejected nor allowed to clobber: it waits in line, is handed the row as it now stands, and proceeds. Claims don't lock. If another writer holds the row, `claim` waits for them, re-reads the fresh row, then hands it to you — so writers serialize instead of colliding. A person editing that row is simply another holder; the agent waits behind them the same way. And a claim is as narrow as its target: name a `path`, a `range`, or a `field` and two claims on non-overlapping parts of the same row are both granted — region locking within one row, with no queueing between regions.
 
 Use AI SDK for the agent loop. Use Ablo when agent reads and writes must persist, coordinate with concurrent work, and leave an audit trail.
 
-## Surfaces — pick by who is calling
+## Surfaces: pick by who is calling
 
 Every surface reaches the same coordinated state. They are not interchangeable.
 
@@ -217,7 +217,7 @@ Import from these public paths only:
 
 Do not teach `/api`, `/agent`, `/ai-sdk`, `/core`, `/realtime`, or internal subpaths. (`/source` IS public — it's the Data Source endpoint surface above.)
 
-## CLI — agents run it NON-INTERACTIVELY
+## CLI: agents run it NON-INTERACTIVELY
 
 `ablo init` and other prompts need a TTY; an agent/CI run has none and will HANG. Always:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/ablo",
-  "version": "0.35.0",
+  "version": "0.36.0",
   "description": "The Collaboration Layer For AI Agents",
   "license": "Apache-2.0",
   "type": "module",
@@ -10,7 +10,7 @@
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "bin": {
-    "ablo": "./dist/cli.cjs"
+    "ablo": "./bin/ablo.cjs"
   },
   "exports": {
     ".": {
@@ -33,11 +33,6 @@
       "import": "./dist/react/index.js",
       "default": "./dist/react/index.js"
     },
-    "./testing": {
-      "types": "./dist/testing/index.d.ts",
-      "import": "./dist/testing/index.js",
-      "default": "./dist/testing/index.js"
-    },
     "./core": {
       "types": "./dist/core/index.d.ts",
       "import": "./dist/core/index.js",
@@ -98,6 +93,11 @@
       "import": "./dist/wire/index.js",
       "default": "./dist/wire/index.js"
     },
+    "./syncLog": {
+      "types": "./dist/syncLog/index.d.ts",
+      "import": "./dist/syncLog/index.js",
+      "default": "./dist/syncLog/index.js"
+    },
     "./server": {
       "types": "./dist/server/index.d.ts",
       "import": "./dist/server/index.js",
@@ -115,6 +115,7 @@
     }
   },
   "files": [
+    "bin",
     "dist",
     "!dist/__type_probe.*",
     "docs/*.md",
@@ -129,21 +130,21 @@
   ],
   "scripts": {
     "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
-    "build": "npm run clean && tsc -p tsconfig.build.json && npm run build:cli",
-    "build:cli": "tsup --config tsup.cli.config.ts",
-    "typecheck": "npm run typecheck:src && npm run typecheck:cli && npm run typecheck:scripts",
+    "build": "npm run clean && tsc -p tsconfig.build.json",
+    "typecheck": "npm run typecheck:src && npm run typecheck:scripts",
     "typecheck:src": "tsc -p tsconfig.json",
-    "typecheck:cli": "tsc -p tsconfig.cli.json",
     "typecheck:scripts": "tsc -p tsconfig.scripts.json",
     "prepack": "node scripts/strip-source-condition.mjs",
     "postpack": "node scripts/restore-source-condition.mjs",
     "pack:check": "node scripts/pack-check.mjs",
-    "lint": "npm run lint:imports && npm run lint:errors && npm run lint:docs && npm run lint:docs-site",
+    "lint": "npm run lint:imports && npm run lint:errors && npm run lint:openapi && npm run lint:docs && npm run lint:docs-site",
     "build:docs": "node scripts/build-blume-docs.mjs",
     "lint:docs-site": "node scripts/build-blume-docs.mjs --check",
     "lint:imports": "node scripts/check-js-extensions.mjs",
     "generate:errors": "tsx scripts/generate-error-docs.mts",
+    "generate:openapi": "tsx --conditions=@ablo/source scripts/generate-openapi.mts",
     "lint:errors": "tsx scripts/check-error-docs.mts",
+    "lint:openapi": "tsx --conditions=@ablo/source scripts/generate-openapi.mts --check",
     "lint:docs": "node scripts/check-doc-drift.mjs",
     "lint:eslint": "eslint . --cache",
     "lint:pkg": "publint",
@@ -151,7 +152,6 @@
     "check:dist": "node scripts/check-dist-fresh.mjs",
     "pretest": "node scripts/check-dist-fresh.mjs",
     "test": "jest",
-    "test:quickstart": "node scripts/test-quickstart.mjs",
     "test:unit": "jest --testPathPatterns __tests__/unit",
     "test:integration": "jest --testPathPatterns __tests__/integration",
     "test:contract": "jest --testPathPatterns __tests__/contract",
@@ -205,7 +205,6 @@
     }
   },
   "dependencies": {
-    "jiti": "^2.7.0",
     "mobx": "^6.13.7",
     "mobx-react-lite": "^4.0.0",
     "uuid": "^11.1.0",
@@ -213,9 +212,7 @@
   },
   "devDependencies": {
     "@ai-sdk/provider": "^3.0.0",
-    "@clack/prompts": "^0.11.0",
     "@jest/globals": "^30.2.0",
-    "@prisma/client": "^7.3.0",
     "@types/jest": "^30.0.0",
     "@types/node": "^22.0.0",
     "@types/react": "^19.0.0",
@@ -230,13 +227,9 @@
     "jest": "^30.2.0",
     "jest-environment-jsdom": "^30.2.0",
     "jest-environment-node": "^30.2.0",
-    "picocolors": "^1.1.0",
-    "postgres": "^3.4.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "ts-jest": "^29.4.5",
-    "ts-morph": "^26.0.0",
-    "tsup": "^8.0.0",
     "tsx": "^4.19.0",
     "typescript": "^5.8.3",
     "publint": "^0.3.21",