@abloatai/ablo 0.6.0 → 0.7.0

package/docs/cli.md

@@ -0,0 +1,212 @@
+# CLI
+
+The `ablo` CLI gets you from an empty project to live-syncing data: scaffold a
+schema, authenticate, push the schema, and watch it sync. Your
+`defineSchema(...)` is the single source of truth — the CLI and the hosted
+server lower it to **the same SQL** through one engine
+(`generateProvisionPlan` / `generateMigrationPlan` in `@abloatai/ablo/schema`).
+
+```bash
+npx ablo init      # scaffold ablo/schema.ts + client
+npx ablo login     # authorize in the browser
+npx ablo dev       # push schema to the test sandbox + watch
+```
+
+## Authenticate
+
+`ablo login` runs the OAuth 2.0 device flow: it opens your browser, you choose
+**log in** or **create an account** and approve, and the CLI provisions a
+**test + live key pair** (90-day, restricted) and stores them locally. This
+mirrors `stripe login`.
+
+| Command | What it does |
+| --- | --- |
+| `ablo login` | Authorize in the browser; provisions + stores a test and a live key. |
+| `ablo logout` | Remove the stored keys. |
+| `ablo status` | Show the active org, mode, both keys (prefix + expiry), and server health. |
+| `ablo mode [test\|live]` | Switch the active mode. With no argument, prompts. |
+
+Keys are stored in `~/.config/ablo/config.json` (mode `0600`). In **CI**, don't
+log in — set `ABLO_API_KEY`, which always overrides the stored key.
+
+## Test vs live
+
+Like Stripe, every account has a **test** mode and a **live** mode, and a key
+belongs to one of them. Test keys are bound to an isolated sandbox: their reads
+and writes never touch live data. Switch with `ablo mode`; `ablo dev` is always
+test mode by design.
+
+The schema, however, is **shared** across the org — pushing a schema (from
+either mode) defines the same models test and live see; only the rows differ.
+
+## Commands
+
+| Command | What it does | Flags |
+| --- | --- | --- |
+| `ablo init` | Scaffold `ablo/` (`schema.ts`, client, optional Data Source / agent / component), write `.env`, install the SDK. Offers to log in at the end. | — |
+| `ablo login` / `logout` / `status` | Authentication & status (above). | — |
+| `ablo mode [test\|live]` | Switch active mode. | — |
+| `ablo dev` | **Hosted** — push the schema to your test sandbox, then watch `ablo/schema.ts` and re-push on save. | `--no-watch`, `--schema <path>`, `--export <name>`, `--url <url>` |
+| `ablo logs` | Tail your scope's commit activity (`stripe logs tail`). Follows by default. | `-n, --tail <N>`, `--since <dur\|ts>`, `--model`, `--op`, `--json`, `--no-follow`, `--mode test\|live` |
+| `ablo schema push` | **Hosted** — upload the schema to Ablo; the server diffs, migrates, and activates it. | `--force`, `--rename old:new`, `--backfill model.field=value`, `--schema`, `--export`, `--url` |
+| `ablo pull` | **BYO** — generate `defineSchema(...)` from your existing tables (read-only, like `prisma db pull`). | `--out <path>`, `--app-schema <name>`, `--import <pkg>`, `--force` |
+| `ablo check` | **BYO** — verify your *existing* tables fit the schema (read-only, no DDL). | `--schema <path>`, `--export <name>`, `--app-schema <name>` |
+| `ablo generate` | Emit TypeScript types from the schema. | `--out <path>`, `--schema`, `--export` |
+
+## `ablo dev`
+
+The development loop. It pushes `ablo/schema.ts` to your **test sandbox**,
+prints the env line your app needs, then watches the file and re-pushes on every
+save (300 ms debounce). It refuses live keys so a tight save loop can never
+churn production data.
+
+```bash
+npx ablo dev             # push + watch
+npx ablo dev --no-watch  # push once and exit
+```
+
+## `ablo logs`
+
+Tail commit activity, like `stripe logs tail`. Scope comes from the key — a test
+key streams only its sandbox's writes, a live key the org's — so you never pass
+an org. Follows by default; `--no-follow` prints recent and exits.
+
+```bash
+npx ablo logs                      # last 50, then stream
+npx ablo logs -n 100 --model task  # backfill 100, one model
+npx ablo logs --since 15m --json   # last 15m as NDJSON, then stream
+```
+
+Each line is `time · op · model · id · actor`. `--json` emits one event per line
+(NDJSON) for piping to `jq` or an agent.
+
+## `ablo pull`
+
+Generate `defineSchema(...)` from the tables you already have — the inverse of
+provisioning, and read-only (like `prisma db pull`). It introspects
+`DATABASE_URL`, emits a model per adoptable table (one that has `id` +
+`organization_id`), maps Postgres types back to Zod, and writes `ablo/schema.ts`.
+
+```bash
+DATABASE_URL=postgres://… npx ablo pull
+```
+
+It never touches the database, and won't overwrite an existing schema without
+`--force`. Introspection is lossy — enum members, JSON shape, relations, and
+defaults can't be recovered from columns — so treat the output as a starting
+point: review it, then run `ablo check`.
+
+## `ablo check`
+
+The BYO front door. Instead of migrating (DDL on your database), Ablo *adopts*
+the tables you already have: `ablo check` introspects `DATABASE_URL`, compares it
+to your `defineSchema(...)`, and reports — per model — whether the table is
+adoptable. It never writes or alters anything.
+
+A table is adoptable when it has a primary key `id` and (for org-scoped models)
+an `organization_id` column — the tenancy marker the engine isolates on. Every
+other table in your database is ignored.
+
+**Why `organization_id`?** It's the one column that makes a table safe to
+multiplayer-sync. Row-level security scopes every read and write by it (org A
+can't see org B's rows), and the engine routes realtime deltas by `org:<id>`. A
+table without a tenancy key has no isolation boundary, so Ablo excludes it
+**by default** rather than risk exposing it across tenants. If your tenancy
+column has a different name, keep that table behind a
+[Data Source endpoint](/data-sources) for now.
+
+```bash
+DATABASE_URL=postgres://… npx ablo check
+```
+
+```text
+  ✓ tasks     → tasks (id, organization_id ok)
+  ✗ projects  → projects
+      • missing "organization_id" — add it, or move this model behind a Data Source
+  2 models · 1 ok · 1 error
+  12 other tables in your database — ignored by Ablo
+```
+
+If a table can't carry `organization_id` (or has business logic Ablo shouldn't
+bypass), keep it behind a [Data Source endpoint](/data-sources) rather than
+reshaping it. `ablo check` is read-only; it never proposes a migration.
+
+## `migrate` vs `schema push`
+
+Two front doors to the same engine. Use `migrate` when your app owns the
+database (it applies to `DATABASE_URL`); use `schema push` (and `dev`) on the
+hosted path (the server applies to Ablo-managed Postgres and version-gates
+connecting clients).
+
+```bash
+ablo migrate --dry-run            # preview the exact SQL
+ablo migrate                      # apply to DATABASE_URL
+ablo migrate --output schema.sql  # write SQL to a file
+```
+
+## Zod → Postgres type mapping
+
+The one type map, shared by both paths (there is no second mapping):
+
+| Zod | Postgres |
+| --- | --- |
+| `z.string()` | `TEXT` |
+| `z.number()` | `DOUBLE PRECISION` — never `INTEGER`; a Zod number may be fractional, and truncating is silent data loss |
+| `z.boolean()` | `BOOLEAN` |
+| `z.date()` | `TIMESTAMPTZ` |
+| `z.enum([...])` | `TEXT` + a `CHECK (col IN (...))` constraint |
+| `z.object` / `z.array` / `z.record` / `z.union` / `z.custom` | `JSONB` |
+| `.optional()` / `.nullable()` | nullable column |
+
+Each table also gets the platform columns (`id`, `organization_id`,
+`created_by`, `created_at`, `updated_at`), an `organization_id` index, and
+row-level security keyed on `current_setting('app.current_org_id')` for tenant
+isolation.
+
+`.default(...)` is **not** emitted as a SQL column default — Zod applies the
+default at write time (`create`), in one place, so a DB default and a schema
+default can't drift.
+
+## Structured errors
+
+A failed migration aborts the whole transaction (nothing partial lands) and
+reports the same `migration_failed` shape on both paths — naming the statement
+that broke and the Postgres SQLSTATE, not just "migration failed".
+
+`ablo migrate` (local) logs it:
+
+```txt
+[migrate] migration plan failed {
+  code: 'migration_failed',
+  failedStatement: 'ALTER TABLE "public"."tasks" RENAME COLUMN a TO b;',
+  failedStatementIndex: 4,
+  pgCode: '42P01',
+  durationMs: 133
+}
+```
+
+`ablo schema push` (hosted) returns the canonical error envelope (HTTP 500),
+which the SDK reconstructs as a typed `AbloServerError`:
+
+```json
+{
+  "type": "AbloServerError",
+  "code": "migration_failed",
+  "message": "schema migration failed: relation \"...\" does not exist",
+  "doc_url": "https://docs.abloatai.com/errors#migration_failed",
+  "failedStatement": "ALTER TABLE ... RENAME COLUMN a TO b;",
+  "pgCode": "42P01"
+}
+```
+
+The pushed artifact is recorded `failed` and is never activated, so a broken
+migration can't leave clients gated against tables that don't match.
+
+## Environment
+
+| Variable | Purpose | Default |
+| --- | --- | --- |
+| `ABLO_API_KEY` | Authenticate without `ablo login` (CI). Always overrides the stored key. | — |
+| `ABLO_API_URL` | Control-plane / API host (`schema push`, `dev`, `status`). | `https://api.abloatai.com` |
+| `ABLO_AUTH_URL` | Dashboard origin for `ablo login`'s device flow. | `https://abloatai.com` |
+| `ABLO_CONFIG_DIR` / `XDG_CONFIG_HOME` | Where the credential file lives. | `~/.config/ablo` |

package/docs/client-behavior.md

@@ -28,7 +28,7 @@ Common options:
 | `schema` | Required for typed model clients. |
 | `apiKey` | Bearer credential for trusted server runtimes. Defaults to `ABLO_API_KEY` when available. |
 | `baseURL` | Override the hosted sync endpoint for staging or private deployments. |
-| `persistence` | `volatile` by default. Use `indexeddb` for browser durable cache and offline queueing. |
+| `persistence` | `volatile` by default. Use `indexeddb` for a durable browser cache that survives reloads. |
 | `fetch` | Custom fetch implementation for tests or non-standard runtimes. |
 | `defaultHeaders` | Extra headers attached to every HTTP request. |
 | `defaultQuery` | Extra query parameters attached to every HTTP request. |

package/docs/coordination.md

@@ -11,10 +11,61 @@ does not poll. Reads are open by default; reading a claimed row is allowed unles
 the caller explicitly asks for claimed gating. A claim carries a TTL so a crashed
 holder is auto-released and the queue advances.
 
-This reference has three sections: the [claim state object](#the-claim-state-object),
-the SDK [methods](#methods) (`claim` · `claimState` · `queue` · `release` ·
-[writing under a claim](#writing-under-a-claim)), and the [errors](#errors) you
-can catch.
+This reference opens with [the model](#the-model--three-layers-one-decision) — the
+one answer to "how do two agents not clobber each other" — then covers the
+[claim state object](#the-claim-state-object), the SDK [methods](#methods)
+(`claim` · `claimState` · `queue` · `release` · [writing under a
+claim](#writing-under-a-claim)), and the [errors](#errors) you can catch.
+
+---
+
+## The model — three layers, one decision
+
+Ablo has exactly **three** coordination layers. They are **not** three competing
+answers to the same question — they stack, and only one of them is a decision you
+make:
+
+| layer | kind | what it does | enforces? |
+|---|---|---|---|
+| **Presence** (`claimState`, observers) | observation | Broadcasts who is working where, live. Renders cursors / "agent X is editing." | **No.** Advisory only — it never blocks or rejects a write. |
+| **Claim** (`claim`/`queue`/`release`) | pessimistic | Reserves a row for one participant. Foreign writers are rejected server-side; contenders join a fair FIFO queue. | **Yes**, between participants — mutual exclusion. |
+| **Stale-context** (`readAt` + `onStale`) | optimistic (LWW) | On commit, rejects a write whose snapshot is older than the row's latest delta. Last-writer-wins detection. | **Yes**, against time — lost-update detection. |
+
+**The one decision: do you hold the row across a slow gap (read → LLM call →
+write)?**
+
+- **No** (the common case — a single quick `update`): do nothing. `ablo.<model>.update`
+  is optimistically guarded by stale-context already; it rejects with
+  `AbloStaleContextError` if the row moved under you. This is the default and
+  needs no ceremony.
+- **Yes** (you'll reason for seconds while holding the row): `claim` it. The claim
+  excludes other participants for the duration, queues contenders fairly, and —
+  see below — your own writes under it stay stale-guarded too.
+
+**How they compose (what wins):**
+
+1. **Claim supersedes stale-context for *foreign* writers.** A non-holder writing
+   to a claimed row is rejected by the claim guard (`AbloClaimedError`,
+   `claim_conflict`/`entity_claimed`) *before* any watermark check — `readAt` is
+   irrelevant when you don't hold the lease. Pessimistic exclusion is the outer
+   gate.
+2. **Stale-context is the always-on backstop for *unclaimed* writes.** No claim
+   held → the watermark check is the only protection, and it's automatic. This is
+   why the no-claim path is safe by default.
+3. **Inside a claim, both apply.** A claim is not a license to clobber yourself:
+   writes under a held claim carry the claim's snapshot as `readAt` with
+   `onStale: 'reject'` (see [Writing under a claim](#writing-under-a-claim)), so a
+   `bypass` write or a row that moved between snapshot and write still rejects.
+   Claim = "no one else"; stale-context = "and not against a moved snapshot."
+4. **Presence never decides.** It is the visualization of (1)–(3), not a fourth
+   gate. Never branch enforcement logic on `claimState` — read it to render, act
+   on the errors above.
+
+Claims and stale-context are **orthogonal by construction**, not wired into each
+other on the server: the claim guard runs pre-transaction; the watermark check
+runs inside it. The SDK attaches `readAt`/`onStale` for you when writing under a
+claim — that coupling lives in the SDK, deliberately, so the server's two checks
+stay independent and individually testable.
 
 ---
 
@@ -36,7 +87,6 @@ a model row. It's what `claimState()` returns and what observers render.
 | `expiresAt` | `string` | Ms-epoch the server reclaims it if the holder goes **silent**. Renewed automatically while the holder's connection stays alive — a crash-cleanup floor, not a duration you size. |
 
 ```jsonc
-// A live claim state, as returned by claimState():
 {
   "id": "claim_8fJ2",
   "status": "active",
@@ -95,7 +145,6 @@ release hook for manual scopes.
 **Example**
 
 ```ts
-// Callback form — works on any toolchain:
 const forecast = await ablo.weatherReports.claim('report_stockholm', async (report) => {
   const weather = await weatherAgent.getWeather(report.location);
   await ablo.weatherReports.update(report.id, { forecast: weather });
@@ -114,8 +163,8 @@ held. Server/model reads can choose a claimed policy:
 
 ```ts
 await ablo.model('weatherReports').retrieve('report_stockholm', {
-  ifClaimed: 'wait',       // wait until the active claim clears
-  claimedTimeout: 30_000,  // maximum wait
+  ifClaimed: 'wait',
+  claimedTimeout: 30_000,
 });
 ```
 
@@ -145,11 +194,12 @@ is free.
 
 ```ts
 const who = ablo.weatherReports.claimState('report_stockholm');
-if (who) console.log(`${who.heldBy} is ${who.action}`); // 'agent:forecaster is editing'
+if (who) console.log(`${who.heldBy} is ${who.action}`);
 ```
 
+Returns the active claim state when the row is held, or `null` when it's free:
+
 ```jsonc
-// Resolved value when the row is held:
 {
   "id": "claim_8fJ2",
   "status": "active",
@@ -159,7 +209,6 @@ if (who) console.log(`${who.heldBy} is ${who.action}`); // 'agent:forecaster is
   "participantKind": "agent",
   "expiresAt": "1748160030000"
 }
-// → null when free.
 ```
 
 ### `queue`
@@ -190,7 +239,7 @@ the active holder; `[]` when no one is waiting.
 ```ts
 const { data: waiting } = ablo.weatherReports.queue('report_stockholm');
 console.log(`${waiting.length} ahead of you`);
-console.log(waiting.map((i) => i.heldBy)); // ['agent:b', 'agent:c']
+console.log(waiting.map((i) => i.heldBy));
 ```
 
 ### `release`

package/docs/data-sources.md

@@ -24,7 +24,7 @@ Use the SDK with an API key:
 
 ```ts
 import Ablo from '@abloatai/ablo';
-import { schema } from './ablo.schema';
+import { schema } from './ablo/schema';
 
 export const ablo = Ablo({
   schema,
@@ -100,7 +100,7 @@ The shape is the same as a production webhook integration:
 ```ts
 // app/api/ablo/source/route.ts
 import { dataSource } from '@abloatai/ablo';
-import { schema } from '@/ablo.schema';
+import { schema } from '@/ablo/schema';
 import { db } from '@/db';
 
 export const POST = dataSource({

package/docs/examples/existing-python-backend.md

@@ -26,7 +26,7 @@ Browser UI
 Create a schema for the records that need realtime coordination.
 
 ```ts
-// web/ablo.schema.ts
+// web/ablo/schema.ts
 import { defineSchema, model, z } from '@abloatai/ablo/schema';
 
 export const schema = defineSchema({
@@ -42,7 +42,7 @@ export const schema = defineSchema({
 ```ts
 // web/ablo.ts
 import Ablo from '@abloatai/ablo';
-import { schema } from './ablo.schema';
+import { schema } from './ablo/schema';
 
 export const ablo = Ablo({
   schema,
@@ -58,7 +58,7 @@ model clients without importing server credentials.
 'use client';
 
 import { AbloProvider } from '@abloatai/ablo/react';
-import { schema } from '@/ablo.schema';
+import { schema } from '@/ablo/schema';
 
 export function Providers({ children }: { children: React.ReactNode }) {
   return <AbloProvider schema={schema}>{children}</AbloProvider>;

package/docs/examples/scoped-agent.md

@@ -0,0 +1,78 @@
+# Agent Scoped to One Deck
+
+An agent that edits **one deck** and receives realtime updates for **only that
+deck** — not the whole org. Shows the sync-group model end to end: a scope root,
+a containment (`parent`) edge, identity roles, and the model-form `scope`.
+
+See [Identity & Sync Groups](../identity.md) for the full reference.
+
+## 1. Schema — declare the scope, once
+
+```ts
+import { defineSchema, identityRole, model, relation, z } from '@abloatai/ablo/schema';
+
+export const schema = defineSchema(
+  {
+    // A scope root: deck rows form the group `deck:<id>`.
+    decks: model(
+      { title: z.string() },
+      {},
+      { orgScoped: true, scope: 'deck' },
+    ),
+    // A child: no group of its own. It inherits its deck's group via the
+    // `parent` edge, so a slide write reaches everyone viewing the deck —
+    // even a slide edit that doesn't touch `deckId` (routing is keyed on the
+    // row's id, not the changed columns).
+    slides: model(
+      { deckId: z.string(), body: z.string() },
+      { deck: relation.belongsTo('decks', 'deckId', { parent: true }) },
+      { orgScoped: true },
+    ),
+  },
+  {
+    // Humans get their full org scope automatically from these.
+    identityRoles: [
+      identityRole({ kind: 'org', source: 'organizationId' }),
+      identityRole({ kind: 'user', source: 'userId' }),
+    ],
+  },
+);
+```
+
+## 2. Dispatch — narrow the agent to the deck it's working on
+
+The agent inherits the triggering user's identity (its ceiling) and is narrowed
+to one deck (the floor). You pass the **model and id** — never a `deck:<id>`
+string; the engine builds the group from the model's `scope`.
+
+```ts
+const ablo = Ablo({
+  schema,
+  url: process.env.ABLO_URL,
+  kind: 'agent',
+  agentId: 'agent:slide-writer',
+  userId: triggeringUser.id,     // ceiling: can't exceed this user's reach
+  organizationId: triggeringUser.organizationId,
+  scope: { decks: deckId },      // floor: just this deck → deck:<deckId>
+});
+await ablo.ready();
+```
+
+## 3. Write — it fans out to everyone on that deck
+
+```ts
+// Other participants subscribed to deck:<deckId> — the human in the editor,
+// a reviewer agent — receive this delta in realtime. Participants on other
+// decks never see it.
+await ablo.slides.update(slideId, { body: 'Q4 revenue up 12% YoY' });
+```
+
+The slide's delta is stamped `deck:<deckId>` (derived server-side from the
+slide → deck `parent` edge), so it reaches the deck's audience authoritatively —
+regardless of which groups the agent happened to subscribe to. And `scope` only
+ever *narrows*: the agent can't reach a deck its triggering user couldn't.
+
+## See also
+
+- [Identity & Sync Groups](../identity.md) — the full scope / parent / grants model.
+- [Agent + Human](./agent-human.md) — yielding when a human edits the same row.

package/docs/guarantees.md

@@ -62,6 +62,9 @@ Advanced policies exist for controlled product flows:
 
 ## Claim Coordination
 
+> The guarantee, not the how-to. Methods, the claim-state object, and the `queue`
+> live in [Coordination](./coordination.md).
+
 Claims are live coordination signals. They are not database locks.
 
 Claims are **advisory** and **cooperative**. `ablo.<model>.claim(id, ...)`
@@ -95,10 +98,10 @@ authorized it, which run did it, and what state was it based on?"
 
 ## Persistence
 
-Ablo defaults to volatile local persistence. That keeps the SDK focused on
+Ablo defaults to volatile in-memory persistence. That keeps the SDK focused on
 coordination and audit instead of silently becoming a browser storage product.
 
-Opt into durable browser cache and offline queueing when you need it:
+Opt into a durable browser cache that survives reloads when you need it:
 
 ```ts
 const ablo = Ablo({