@abloatai/ablo 0.12.0 → 0.14.0

package/docs/integration-guide.md

@@ -142,20 +142,23 @@ model(
   },
   /* relations */ {},
   {
-    // Rows carry organization_id and bootstrap filters on it.
-    orgScoped: true,
+    // Axis 1 — `policy`: who may READ a row (tenant isolation / RLS). A
+    // row-local `organization_id` column is the default, so you omit this for
+    // normal tables; set it only for the exceptions (parent-inherited / global).
 
+    // Axis 2 — `groups`: which sync-group CHANNELS a row fans into.
     // Scope root: rows form the group `matter:<id>`. Children point at it with
     // `relation.belongsTo('matters', 'matterId', { parent: true })` to inherit.
-    scope: 'matter',
+    groups: { root: 'matter' },
   }
 );
 ```
 
-For rows that don't carry `organization_id` themselves but inherit
-tenancy via a foreign key, use `scopedVia` instead of `orgScoped:
-false` — the latter exposes the entire table cross-tenant. See
-`packages/sync-engine/src/schema/model.ts` for the full option set.
+For rows that don't carry `organization_id` themselves but inherit tenancy via a
+foreign key, set `policy: { by: 'parent', fk: '<fk>', parent: '<parentTable>' }`.
+For genuinely global/reference data, `policy: { by: 'none' }`. ⚠ `by: 'none'`
+exposes the whole table cross-tenant, so it's an explicit, named branch — never a
+falsy flag. See `packages/sync-engine/src/schema/model.ts` for the full option set.
 
 ## 2. Create The Client
 
@@ -444,7 +447,7 @@ scope.
 ```ts
 await using claim = await ablo.weatherReports.claim({
   id: reportId,
-  action: 'forecasting',
+  reason: 'forecasting',
 });
 const claimed = claim.data;
 if (!claimed) return;
@@ -510,7 +513,7 @@ them.
 | `update({ id, data, ...opts })`        | Update through the model client.                                                 |
 | `delete({ id, ...opts })`              | Delete through the model client.                                                 |
 | `claim.state({ id })`                  | See who is currently working on a row (synchronous).                             |
-| `claim({ id, action?, ttl? })`         | Acquire a disposable handle: wait for your turn, re-read, and hold the row.       |
+| `claim({ id, reason?, ttl? })`         | Acquire a disposable handle: wait for your turn, re-read, and hold the row.       |
 
 Keep first integrations on the model methods above. Every mutation and
 server-read verb takes one options object; only the synchronous `get(id)` stays

package/docs/interaction-model.md

@@ -70,7 +70,7 @@ automatically when the scope exits:
 ```ts
 await using claim = await ablo.weatherReports.claim({
   id: 'report_stockholm',
-  action: 'editing',
+  reason: 'editing',
 });
 await ablo.weatherReports.update({ id: claim.data.id, data: { status: 'ready' } }); // rejected if the row changed under the claim
 ```

package/docs/mcp.md

@@ -67,11 +67,23 @@ Point your assistant at the hosted endpoint — no auth, no token:
 claude mcp add --transport http ablo https://<your-app>/api/mcp
 ```
 
-Per-client walkthroughs:
+The endpoint is identical for every client — only the config surface differs:
 
-- [Claude Code](/docs/mcp/claude-code)
-- [Cursor](/docs/mcp/cursor)
-- [Windsurf](/docs/mcp/windsurf)
+- **Claude Code** — run the `claude mcp add` command above; verify with `/mcp list`, remove with `claude mcp remove ablo`.
+- **Cursor** — add the server to `~/.cursor/mcp.json` (macOS / Linux), then restart.
+- **Windsurf** — add the same JSON via Settings → Cascade → MCP, then restart.
+
+Cursor and Windsurf use the same config shape:
+
+```json
+{
+  "mcpServers": {
+    "ablo": { "transport": "http", "url": "https://<your-app>/api/mcp" }
+  }
+}
+```
+
+Each client then lists the Ablo tools (`search_ablo_docs`, `get_recipe`, `get_api_surface`, `validate_schema`, `scaffold_app`) in its MCP panel.
 
 ### What it exposes
 
@@ -96,7 +108,7 @@ loading everything into context.
 Reusable, parameterised templates that drive an end-to-end flow:
 
 - `integrate-sync-engine` — wire the SDK into an existing project.
-- `add-agent` — add an agent worker that coordinates via intents and
+- `add-agent` — add an agent worker that coordinates via claims and
   conflict-safe writes.
 - `define-schema` — design a Zod-first schema from a description, then run
   `validate_schema` before committing.

package/docs/quickstart.md

@@ -222,7 +222,7 @@ Call `handle.release()` when your work is done.
 // Claim the row so other participants serialize behind us while we work.
 const handle = await ablo.weatherReports.claim({
   id: 'weather_stockholm',
-  action: 'checking_weather',
+  reason: 'checking_weather',
   ttl: '2m',
 });
 
@@ -260,7 +260,7 @@ write through the model.
 ```ts
 const active = ablo.weatherReports.claim.state({ id: 'weather_stockholm' });
 if (active) {
-  console.log(`${active.heldBy} is ${active.action}`);
+  console.log(`${active.heldBy} is ${active.reason}`);
 }
 
 const handle = await ablo.weatherReports.claim({ id: 'weather_stockholm' });
@@ -268,7 +268,7 @@ await ablo.weatherReports.update({ id: handle.data.id, data: { status: 'ready' }
 await handle.release();
 ```
 
-Use `{ wait: false }` on `claim` when work should be skipped instead of queued
+Use `{ queue: false }` on `claim` when work should be skipped instead of queued
 behind an active holder.
 
 ## Next steps

package/docs/react.md

@@ -224,6 +224,75 @@ 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
+scope on the engine's existing socket (one TCP connection, N logical
+sub-syncgroup participants) and returns the reactive participant facade. Use it
+when a mount should both *see* who else is on an entity and, optionally, declare
+write interest in it.
+
+```tsx
+'use client';
+
+import { useWatch } from '@abloatai/ablo/react';
+
+export function DeckPresence({ deckId }: { deckId: string }) {
+  const { peers, claims, status } = useWatch({
+    scope: { slideDecks: deckId },
+    claim: true,   // I intend to write — pin the scope + let peers observe the claim
+    hydrate: true, // backfill the deck's current rows if not already loaded
+  });
+
+  if (status !== 'joined') return <span>connecting…</span>;
+  return <span>{peers.length} other{peers.length === 1 ? '' : 's'} here</span>;
+}
+```
+
+Options (`UseWatchOptions`):
+
+| 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. |
+| `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. |
+| `paused` | `false` | Tear down and don't re-join while true. |
+
+Returns (`UseWatchReturn`): `{ participant, peers, claims, status, error }`.
+`peers` is everyone else on the scope's sync groups; `claims` is their active
+write-claims; `status` is the join lifecycle. Auto-cleans up on unmount or when
+`paused` flips true.
+
+## usePeers — read-only presence
+
+`usePeers` is a *pure reader* of the presence stream already flowing on the
+connection. Unlike `useWatch`, it does **not** enter/leave a scope (no
+`update_subscription`, no warm-TTL churn) — so reading it never changes what the
+connection is subscribed to.
+
+```tsx
+'use client';
+
+import { usePeers } from '@abloatai/ablo/react';
+
+export function CursorBroadcaster({ deckId }: { deckId: string }) {
+  const peers = usePeers({ slideDecks: deckId });
+  const alone = !peers.some((p) => p.participantKind === 'user');
+  // suppress live-cursor broadcasts while alone
+}
+```
+
+Pass `scope` to narrow to a sync group's peers, or omit it for everyone on the
+engine's groups. Returns `ReadonlyArray<Peer>`, where each `Peer` carries
+`participantKind` (`'user' | 'agent' | 'system'`), `participantId`, optional
+`label`, `syncGroups`, `activity`, `lastActive`, and optional `activeClaims`.
+
+Reach for `usePeers` (not a second `useWatch`) when some **other** mount already
+owns the scope's read interest — scope `leave` is not reference-counted, so a
+second `useWatch` on the same scope would warm-drop the owner's subscription on
+unmount.
+
 ## Next.js
 
 The Next.js [App Router landing](/nextjs) walks through Server Components

package/llms.txt

@@ -12,7 +12,7 @@ First action when integrating into an app: run `npx ablo init --yes --framework
 
 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.
 
-Then PUSH — this is the step everything depends on. The server keeps its OWN copy of the schema. Run `npx ablo push --no-watch`: it pushes `ablo/schema.ts` (sandbox) AND writes `ABLO_API_KEY` into `.env.local` from the stored login. Until the schema is pushed, EVERY write to a new or changed model fails with `server_execute_unknown_model`. Re-run it after schema changes (`npx ablo push` also works once the key is wired; bare `npx ablo push` watches forever — don't, you have no TTY).
+Then PUSH — this is the step everything depends on. The server keeps its OWN copy of the schema. Run `npx ablo push`: it pushes `ablo/schema.ts` (sandbox) AND writes `ABLO_API_KEY` into `.env.local` from the stored login. Until the schema is pushed, EVERY write to a new or changed model fails with `server_execute_unknown_model`. Re-run it after schema changes. `push` is one-shot; `dev` is the watcher, so use `npx ablo dev --no-watch` only when you intentionally want the dev command to push once and exit.
 
 ## Projects (one org, many apps)
 
@@ -29,7 +29,6 @@ TYPES: the project registers its schema ONCE via declaration merging — `npx ab
 
 const schema = defineSchema({
   weatherReports: model({
-    id: z.string(),
     location: z.string(),
     status: z.enum(['pending', 'ready']),
     forecast: z.string().optional(),
@@ -190,6 +189,6 @@ Do not teach `/api`, `/agent`, `/ai-sdk`, `/core`, `/realtime`, or internal subp
 - `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.
 - 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 --no-watch` pushes the schema (sandbox) AND writes `ABLO_API_KEY` to `.env.local` (default watches forever); `npx ablo logs --no-follow` (default tails forever); `npx ablo mode sandbox|production` (always pass the arg). `npx ablo push`/`status`/`pull`/`check`/`generate` are one-shot.
+- `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.
 
 Canonical docs to read before integrating: `quickstart`, `schema-contract`, `integration-guide`, `guarantees`, `client-behavior`, `data-sources`, `examples/existing-python-backend`, `api`, `examples/ai-sdk-tool`, and `examples/server-agent`. When upgrading an existing integration, read `migration` — every breaking change, what to change, and which version introduced it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/ablo",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "The Collaboration Layer For AI Agents",
   "license": "Apache-2.0",
   "type": "module",
@@ -43,6 +43,11 @@
       "import": "./dist/core/index.js",
       "default": "./dist/core/index.js"
     },
+    "./batching": {
+      "types": "./dist/batching/index.d.ts",
+      "import": "./dist/batching/index.js",
+      "default": "./dist/batching/index.js"
+    },
     "./agent": {
       "types": "./dist/agent/index.d.ts",
       "import": "./dist/agent/index.js",
@@ -119,7 +124,6 @@
     "examples",
     "AGENTS.md",
     "llms.txt",
-    "llms-full.txt",
     "LICENSE",
     "NOTICE",
     "README.md",
@@ -131,9 +135,11 @@
     "build:cli": "tsup --config tsup.cli.config.ts",
     "typecheck:cli": "tsc -p tsconfig.cli.json",
     "pack:check": "npm_config_cache=${TMPDIR:-/tmp}/ablo-npm-cache npm pack --dry-run",
+    "lint": "npm run lint:imports && npm run lint:errors && npm run lint:docs",
     "lint:imports": "node scripts/check-js-extensions.mjs",
     "generate:errors": "tsx scripts/generate-error-docs.mts",
     "lint:errors": "tsx scripts/check-error-docs.mts",
+    "lint:docs": "node scripts/check-doc-drift.mjs",
     "lint:pkg": "publint",
     "prepublishOnly": "npm run build && npm run lint:pkg",
     "check:dist": "node scripts/check-dist-fresh.mjs",

package/docs/mcp/claude-code.md

@@ -1,35 +0,0 @@
-# Claude Code
-
-## Install
-
-```bash
-claude mcp add --transport http ablo https://<your-app>/api/mcp
-```
-
-That's it — no token or header needed. The endpoint is public and serves
-only docs, schema lint, and scaffolds. The next `/help` in Claude Code will
-list the Ablo Sync tools.
-
-## Verify
-
-In Claude Code, run:
-
-```
-/mcp list
-```
-
-You should see `ablo` with the integration tools enumerated:
-`search_ablo_docs`, `get_recipe`, `get_api_surface`, `validate_schema`,
-`scaffold_app`.
-
-## Removing
-
-```bash
-claude mcp remove ablo
-```
-
-## More
-
-- [MCP overview](/docs/mcp) — what the server exposes and how the transport works.
-- [Cursor setup](/docs/mcp/cursor) — same URL, different UI.
-- [Windsurf setup](/docs/mcp/windsurf) — same URL, different UI.

package/docs/mcp/cursor.md

@@ -1,35 +0,0 @@
-# Cursor
-
-## Install
-
-Add the Ablo Sync MCP server to Cursor's `mcp.json`:
-
-```json
-{
-  "mcpServers": {
-    "ablo": {
-      "transport": "http",
-      "url": "https://<your-app>/api/mcp"
-    }
-  }
-}
-```
-
-The file lives at `~/.cursor/mcp.json` on macOS / Linux. No auth header is
-needed — the endpoint is public and serves only docs, schema lint, and
-scaffolds.
-
-Restart Cursor. The Ablo Sync tools appear under the MCP icon in the agent
-panel.
-
-## Verify
-
-In Cursor's agent panel, open the MCP tools list. You should see the
-Ablo Sync integration tools and their JSON schemas: `search_ablo_docs`,
-`get_recipe`, `get_api_surface`, `validate_schema`, `scaffold_app`.
-
-## More
-
-- [MCP overview](/docs/mcp) — what the server exposes and how the transport works.
-- [Claude Code setup](/docs/mcp/claude-code) — CLI install.
-- [Windsurf setup](/docs/mcp/windsurf) — same JSON shape.

package/docs/mcp/windsurf.md

@@ -1,33 +0,0 @@
-# Windsurf
-
-## Install
-
-Add the Ablo Sync MCP server to Windsurf's MCP config:
-
-```json
-{
-  "mcpServers": {
-    "ablo": {
-      "transport": "http",
-      "url": "https://<your-app>/api/mcp"
-    }
-  }
-}
-```
-
-The config path differs by platform — Windsurf surfaces it in Settings →
-Cascade → MCP. Restart Windsurf after saving. No auth header is needed —
-the endpoint is public and serves only docs, schema lint, and scaffolds.
-
-## Verify
-
-Cascade's MCP panel lists every configured server with its tools. You
-should see `ablo` with the integration tools enumerated:
-`search_ablo_docs`, `get_recipe`, `get_api_surface`, `validate_schema`,
-`scaffold_app`.
-
-## More
-
-- [MCP overview](/docs/mcp) — what the server exposes and how the transport works.
-- [Claude Code setup](/docs/mcp/claude-code) — CLI install.
-- [Cursor setup](/docs/mcp/cursor) — same JSON shape.

package/docs/roadmap.md

@@ -1,55 +0,0 @@
-# Roadmap
-
-What is shipped, what is next, and what we will not build.
-
-## Shipped
-
-- **Models, claims, commits** — the core API.
-- **Audit log** — a tamper-evident, hash-chained record of who did what,
-  per principal.
-- **MCP transport** — HTTP server at `/api/mcp`.
-- **TypeScript SDK** — `@abloatai/ablo`, with React bindings.
-- **Dashboard** — keys, audit, metrics, allowed origins.
-- **Schema migrations** — change a model's shape after it already has data.
-  Ablo plans the migration, tells you which changes are safe to auto-apply,
-  and backfills the rest; the server applies and activates a migration only
-  if it succeeds. `ablo generate` emits typed clients from a pushed schema.
-- **Structured errors** — every error has a stable code and a request id,
-  and the same codes work whether you reach Ablo over HTTP, WebSocket, or MCP.
-- **Sync groups** — clients automatically receive only the records they have
-  access to, based on relationships you declare in the schema.
-- **Agent coordination** — when several agents work on the same model, they
-  take turns instead of overwriting each other, via `intent(id)` handles
-  that claim, wait, and commit.
-
-## In flight
-
-- **Real-time presence** — see who else is viewing/editing a model
-  (coordination primitives landed; presence surface in progress).
-- **Cross-instance fan-out via Redis** — pub/sub deltas at scale.
-
-## On deck
-
-- **Field-level subscriptions** — subscribe to one path, not the whole row.
-- **Bulk import/export** — CSV/JSON round-trip with chain verification.
-
-## Maybe, if demand
-
-- **Python SDK** — when a customer is shipping a Python-only product.
-- **Go SDK** — same.
-- **Multi-region replication** — when latency requirements force it.
-
-## We will not build
-
-- **A general-purpose Postgres wrapper** — Ablo is for state with
-  concurrency semantics, not for storing every table.
-- **Server-side compute** — no triggers, no stored procedures. Compute
-  belongs in your application code.
-- **A document database UI** — your data lives in Ablo; the UI is your
-  product, not ours.
-
-## How priorities shift
-
-We move items between sections based on what customers ask for in
-production. Filing a [feature request](/docs/contact) with a concrete use
-case is more effective than a thread on Twitter.

package/docs/the-loop.md

@@ -1,21 +0,0 @@
-# The loop: how your data flows
-
-This explainer moved to the canonical, maintained docs:
-
-**→ https://abloatai.com/docs/webhooks**
-
-The short version: Ablo has the same two-sided shape as Stripe — **you call Ablo to make changes (the client), and Ablo calls you to persist them (a signed webhook)** — plus realtime sync to every connected client.
-
-```
-your app ──write──▶  Ablo (hosted)  ──realtime sync──▶  other clients
- (the client)        the transaction log               (live, optimistic)
-                            │
-                            └──signed event──▶  /api/ablo/[...all]  ──▶  YOUR database
-                                                (the webhook route)
-```
-
-Ablo owns the ordered transaction log (the source of truth); your database is a
-materialized copy you keep via the webhook. See the link above for the full
-guide: scaffolding the handler (`ablo init`), local testing (`ablo dev`),
-registering an endpoint (`ablo webhooks create`), signature verification, the
-delivery/retry model, and best practices.