@abloatai/ablo 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # Changelog
 
+## 0.7.0
+
+### Minor Changes
+
+- Structured error contract, schema/migration engine, and a full `ablo` CLI.
+  - **Structured error contract across HTTP + WS planes.** A closed, canonical
+    error-code registry is now the `code` tier of a Stripe-style error model. A
+    single HTTP egress funnel converts every throw to a canonical
+    `{ type, code, message, doc_url, request_id, ...details }` envelope; the WS
+    plane narrows mutation/claim error codes to the same union.
+  - **Versioned contract + drift guard.** `ERROR_CONTRACT_VERSION` (date-based)
+    ships in `errors.json` and on the `Ablo-Version` response header, so consumers
+    detect contract changes without diffing docs. Generated `errors.mdx` /
+    `errors.json` plus a CI drift guard keep the docs, OpenAPI spec, and SDK from
+    silently diverging from the registry.
+  - **Always-on request correlation.** Every response carries a `req_…` request id
+    (honoring an inbound `x-request-id`), stamped into the envelope's `request_id`.
+  - **OpenAPI parity.** The stale `{ error, reason }` schema is replaced by the
+    canonical envelope plus a generated `ErrorCode` enum.
+
+  CLI + schema:
+  - **Schema diff + migration planning engine** (`generateProvisionPlan` /
+    `generateMigrationPlan` in `@abloatai/ablo/schema`) — pure diff, classify,
+    apply, and constant-value backfill for required-field migrations.
+  - **`ablo generate`** — emit TypeScript types from the pushed schema.
+  - **Full `ablo` CLI suite**, Stripe-CLI-shaped: `init`, `login` / `logout` /
+    `status`, `mode [test|live]`, `dev` (push schema to the test sandbox + watch),
+    `logs` (tail your scope's commit activity), and the data-source commands below.
+    Authentication is the OAuth 2.0 device flow; `login` provisions and stores a
+    test and a live key, and `mode` switches the active one.
+  - **Database-URL structure (bring-your-own-database).** The CLI is split by where
+    it writes:
+    - `ablo pull` / `ablo check` / `ablo migrate` operate on **your own
+      `DATABASE_URL`** — `pull` introspects it to emit `defineSchema(...)` from
+      existing tables (read-only, like `prisma db pull`), `check` verifies tables
+      fit the schema with no DDL, and `migrate` applies DDL to `DATABASE_URL`.
+    - `ablo schema push` / `ablo dev` target the **hosted** test/live sandbox; the
+      server diffs, migrates, and activates the uploaded schema. `dev` never
+      touches live data.
+
+  **BREAKING** — removed the legacy React hooks `useQuery` / `useOne` / `useMutate`
+  / `useReader`. Use `useAblo()` + `ablo.<model>.*` instead. The `MutateActions`,
+  `ReaderActions`, and `ReaderFindOptions` types are still re-exported for callers
+  that referenced them.
+
 ## 0.6.0
 
 ### Minor Changes

package/README.md

@@ -1,5 +1,10 @@
 # Ablo
 
+[![npm](https://img.shields.io/npm/v/@abloatai/ablo.svg)](https://www.npmjs.com/package/@abloatai/ablo)
+[![license](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](./LICENSE)
+[![types](https://img.shields.io/badge/types-included-blue.svg)](#)
+[![runtime](https://img.shields.io/badge/node-%E2%89%A522-brightgreen.svg)](#keys--runtime)
+
 Ablo is a typed sync engine for shared app state — the kind that humans,
 server code, and AI agents all edit at once.
 
@@ -11,29 +16,46 @@ of who changed what.
 schema -> ablo.<model>.create/retrieve/update/claim(...)
 ```
 
+## Why Ablo
+
+- **Real-time by default.** Every `create` / `update` / `delete` fans out
+  confirmed deltas to all subscribers — humans and agents — with no separate
+  "multiplayer mode" to switch on.
+- **No silent clobbers.** Writes are guarded against stale reads, and `claim`
+  holds a row across a slow read → LLM → write gap so concurrent edits queue
+  instead of overwriting.
+- **Built for agents.** See who's mid-edit (`claimState` / `queue`), coordinate a
+  fair line, and ship an `llms.txt` so coding agents integrate from the real API.
+- **Typed end to end.** Your Zod schema produces typed model proxies
+  (`ablo.<model>.update(...)`), optimistic local reads, and reactive React hooks.
+- **Bring your own auth and database.** Ablo scopes realtime data to *sync
+  groups* from your existing identity, and can leave your database as the source
+  of truth via a Data Source.
+
+**Built for:** collaborative editors, AI agent workflows, internal tools, and any
+app where multiple actors mutate shared state and everyone must see it live.
+
 ## Set up
 
 ```bash
 npm install @abloatai/ablo
 ```
 
-The package ships an `llms.txt` — a precise map of the API — so a coding agent
-integrates from the real surface instead of guessing it. Point Claude Code or
-Cursor at it:
-
-> Read `node_modules/@abloatai/ablo/llms.txt`, then add an Ablo schema and
-> `<AbloProvider>`, wire my first create / retrieve / update, and use `claim`
-> for anything an agent edits across a slow step (read → LLM → write).
+**Keys & runtime.** Ablo needs Node 22+ and TypeScript 5+. Grab an `sk_test_*`
+key for a sandbox
+(`export ABLO_API_KEY=sk_test_...`); keep keys in trusted server runtimes only.
+In the browser, `<AbloProvider>` authenticates with the signed-in user's
+session — never the raw key.
 
-Or wire it by hand — the [Quick Start](#quick-start) below is the shape it
-produces. For production (React, an existing backend, Data Source, agents), the
+Then wire it by hand — the [Quick Start](#quick-start) below is the shape to
+copy. For production (React, an existing backend, Data Source, agents), the
 [Integration Guide](./docs/integration-guide.md) is the deeper map.
 
-**Keys & runtime.** Ablo is ESM-only (`import`, not `require`) and needs Node
-22+ and TypeScript 5+. Grab an `sk_test_*` key
-for a sandbox (`export ABLO_API_KEY=sk_test_...`); keep keys in trusted server
-runtimes only. In the browser, `<AbloProvider>` authenticates with the signed-in
-user's session — never the raw key.
+**Prefer to let an agent wire it?** The package ships an `llms.txt` — a precise
+map of the API — so Claude Code or Cursor integrates from the real surface
+instead of guessing:
+
+> Read `node_modules/@abloatai/ablo/llms.txt`, then add an Ablo schema, a `<AbloProvider>`, and my first create / retrieve / update.
 
 ## Quick Start
 
@@ -87,23 +109,23 @@ reactive under `useAblo`/`subscribe`. `load(...)` fetches from the server when a
 row may not be local yet.
 
 ```ts
-ablo.weatherReports.retrieve('report_stockholm'); // → row | undefined
+ablo.weatherReports.retrieve('report_stockholm');
 
-// Synchronous, from the local cache → row[]
 const pending = ablo.weatherReports.list({
-  where: { status: 'pending' },   // equality filter (an array value means IN)
+  where: { status: 'pending' },
   orderBy: { location: 'asc' },
   limit: 20,
 });
 
-// Server fetch → Promise<row[]>. 'complete' waits for the server; 'unknown'
-// returns what's local now and refreshes in the background.
 const ready = await ablo.weatherReports.load({
   where: { status: 'ready' },
   type: 'complete',
 });
 ```
 
+An array value in `where` means `IN`. On `load`, `type: 'complete'` waits for
+the server; `'unknown'` returns what's local now and refreshes in the background.
+
 ## Writing
 
 `create` / `update` apply optimistically and resolve to the row. Two options
@@ -128,30 +150,35 @@ meanwhile, or worse, acts on stale state. `claim` holds the row across that gap:
 
 ```ts
 await ablo.weatherReports.claim('report_stockholm', async (report) => {
-  // If someone else holds it, claim() WAITS in a fair queue, then re-reads —
-  // so `report` is the current row, never a stale snapshot. Reads stay open by
-  // default; only acting-on-the-row serializes.
-
-  const forecast = await weatherAgent.getWeather(report.location); // slow LLM gap
+  const forecast = await weatherAgent.getWeather(report.location);
   await ablo.weatherReports.update(report.id, { forecast, status: 'ready' });
-}); // claim released here, whether the callback returns or throws
+});
 ```
 
+If someone else holds the row, `claim()` waits in a fair queue, then re-reads —
+so `report` is the current row, never a stale snapshot. Reads stay open by
+default; only acting on the row serializes. The claim releases when the callback
+returns or throws.
+
 See who's mid-edit before you act — decide to wait, or skip:
 
 ```ts
-ablo.weatherReports.claimState('report_stockholm'); // → the holder, or null
-ablo.weatherReports.queue('report_stockholm');    // → { data: [{ heldBy, action, position }, …] }
+ablo.weatherReports.claimState('report_stockholm');
+ablo.weatherReports.queue('report_stockholm');
 
 await ablo.weatherReports.claim(id, async (report) => {
   /* do the held work */
-}, { wait: false });      // held? skip (dedup) — throws instead of waiting
+}, { wait: false });
 
 await ablo.weatherReports.claim(id, async (report) => {
   /* do the held work */
-}, { maxQueueDepth: 2 }); // 2+ already ahead? bail
+}, { maxQueueDepth: 2 });
 ```
 
+`claimState` returns the holder (or `null`); `queue` returns the line waiting
+behind it. `wait: false` skips rather than waiting when the row is held;
+`maxQueueDepth: 2` bails when two or more are already ahead.
+
 Default reads keep working while a row is claimed. Server reads that need claimed
 semantics can opt in with `ifClaimed: 'return' | 'wait' | 'fail'`.
 
@@ -179,7 +206,7 @@ everything inside is live.
 
 ```tsx
 import { AbloProvider, useAblo } from '@abloatai/ablo/react';
-import { schema } from './ablo.schema';
+import { schema } from './ablo/schema';
 
 function App() {
   return (
@@ -190,14 +217,11 @@ function App() {
 }
 
 function Report({ id }: { id: string }) {
-  // Reactive read: this re-renders whenever the row changes — whether you,
-  // a teammate, or an agent changed it.
   const report = useAblo((ablo) => ablo.weatherReports.retrieve(id));
   const ablo = useAblo();
 
   if (!report) return null;
 
-  // Write: same method as the server example above. Optimistic; fans out.
   return (
     <button onClick={() => ablo?.weatherReports.update(id, { status: 'ready' })}>
       {report.status}
@@ -206,6 +230,10 @@ function Report({ id }: { id: string }) {
 }
 ```
 
+The `useAblo(selector)` read re-renders whenever the row changes — whether you,
+a teammate, or an agent changed it. The write is the same optimistic, fan-out
+method as the server example above.
+
 `<AbloProvider>` owns the connection — no API key in the browser. That's the
 whole loop: read with `useAblo(selector)`, write with `ablo.<model>`, and every
 other client (human or agent) on that row sees it in real time. See
@@ -226,8 +254,9 @@ the browser connects as an already-scoped participant — it never holds the key
 and can't widen its own scope. Your schema's `identityRoles` map that identity
 to sync-group strings.
 
+`userId` / `teamIds` come from your auth, resolved server-side:
+
 ```tsx
-// userId / teamIds come from YOUR auth, resolved server-side
 <AbloProvider schema={schema} userId={user.id} teamIds={user.teamIds}>
   <App />
 </AbloProvider>
@@ -262,7 +291,7 @@ HTTP endpoint when a server-to-server caller needs to write without opening a
 WebSocket:
 
 ```bash
-curl https://api.ablo.dev/v1/commits \
+curl https://api.abloatai.com/v1/commits \
   -H "Authorization: Bearer sk_test_..." \
   -H "Content-Type: application/json" \
   -d '{ "operations": [

package/dist/BaseSyncedStore.d.ts

@@ -662,7 +662,7 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
      */
     queryByClass(modelClass: ModelConstructor<Model>, options?: {
         predicate?: (model: Model) => boolean;
-        scope?: ModelScope;
+        state?: ModelScope;
         orderBy?: keyof Model;
         order?: 'asc' | 'desc';
         limit?: number;

package/dist/BaseSyncedStore.js

@@ -1688,7 +1688,7 @@ export class BaseSyncedStore {
         const modelName = this.objectPool.registry.getModelNameFromConstructor(modelClass);
         if (!modelName)
             return { data: [], total: 0, hasMore: false };
-        let allModels = this.objectPool.getByType(modelClass, options?.scope ?? ModelScope.live);
+        let allModels = this.objectPool.getByType(modelClass, options?.state ?? ModelScope.live);
         // Filter out pending deletes
         allModels = allModels.filter((m) => !this.pendingDeletes.has(m.id));
         // Apply predicate

package/dist/client/Ablo.d.ts

@@ -784,6 +784,7 @@ export declare namespace Ablo {
     type ActiveIntent = _Streams.ActiveIntent;
     type Claim = _Streams.Claim;
     type IntentRejection = _Streams.IntentRejection;
+    type IntentLost = _Streams.IntentLost;
     type Snapshot<TSchema extends _SchemaTypes.Schema = _SchemaTypes.Schema, K extends keyof TSchema['models'] = keyof TSchema['models']> = _Streams.Snapshot<TSchema, K>;
     type Turn = import('./Ablo.js').Turn;
     namespace Auth {

package/dist/client/Ablo.js

@@ -1211,6 +1211,7 @@ export function Ablo(options) {
                 entities: { [modelKey]: id },
             }),
             queue: (target) => publicIntents.queueFor({ type: target.model, id: target.id }),
+            reorder: (target, order) => publicIntents.reorder({ type: target.model, id: target.id }, order),
             observe: (target) => {
                 // The live intent stream only tracks *open* (active) claims;
                 // terminal states (committed / expired / canceled) drop out of

package/dist/client/createModelProxy.d.ts

@@ -35,10 +35,12 @@ export interface ModelListOptions<T> {
     };
     limit?: number;
     offset?: number;
-    /** Lifecycle scope. Defaults to live rows. */
-    scope?: ModelListScope;
+    /** Lifecycle filter — `live` (default), `archived`, or `all`. Named `state`
+     *  (GitHub's open/closed/all precedent) so it doesn't collide with the
+     *  sync-group `scope`. */
+    state?: ModelListScope;
 }
-export type ModelCountOptions<T> = Pick<ModelListOptions<T>, 'where' | 'filter' | 'scope'>;
+export type ModelCountOptions<T> = Pick<ModelListOptions<T>, 'where' | 'filter' | 'state'>;
 export interface ModelLoadOptions<T> {
     /**
      * Filter for the lookup. Accepts:
@@ -109,6 +111,14 @@ export interface ModelCollaboration<T> {
         model: string;
         id: string;
     }): readonly Intent[];
+    /**
+     * Re-rank the wait queue on a target (privileged — server-gated). `order` is
+     * the desired front-of-line ordering, taken from `queue(target)`.
+     */
+    reorder(target: {
+        model: string;
+        id: string;
+    }, order: readonly Intent[]): void;
     /**
      * Resolve once no participant holds an active intent on the target.
      * The contender's "wait until it's free" — delegates to the intent
@@ -226,6 +236,19 @@ export interface ModelOperations<T, CreateInput> {
         readonly object: 'list';
         readonly data: readonly Intent[];
     };
+    /**
+     * Re-rank the wait queue on a record — move waiters to the front in the
+     * given order. Pass the `Intent[]` from `queue(id).data`, reordered. A
+     * privileged operation: the server gates it (the caller needs the
+     * `intent.reorder` capability), so it's fire-and-forget — the new order
+     * arrives reactively through `queue(id)`.
+     *
+     * ```ts
+     * const { data } = ablo.decks.queue('deck_1');
+     * ablo.decks.reorder('deck_1', [data[2], data[0], data[1]]); // promote #2
+     * ```
+     */
+    reorder(id: string, order: readonly Intent[]): void;
     /** Release a claim you hold early. Usually implicit (scope exit). */
     release(id: string): Promise<void>;
     /** Listen for changes (callback called on every change). */

package/dist/client/createModelProxy.js

@@ -134,7 +134,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
             return objectPool.get(id);
         },
         list(options) {
-            const all = objectPool.getByType(ModelClass, (options?.scope ?? ModelScope.live));
+            const all = objectPool.getByType(ModelClass, (options?.state ?? ModelScope.live));
             let result = all;
             if (options?.where) {
                 const where = options.where;
@@ -220,6 +220,9 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
                 data: collaboration?.queue({ model: schemaKey, id }) ?? [],
             };
         },
+        reorder(id, order) {
+            collaboration?.reorder({ model: schemaKey, id }, order);
+        },
         release(id) {
             return releaseClaim(id);
         },

package/dist/client/validateAbloOptions.js

@@ -15,7 +15,7 @@ export function validateAbloOptions(input) {
     const kind = options.kind ?? 'user';
     if (!url) {
         return new Error('Ablo: `url` is required. Pass the sync server URL, e.g. ' +
-            `Ablo({ baseURL: 'wss://sync.ablo.dev', schema, user })`);
+            `Ablo({ baseURL: 'wss://sync.abloatai.com', schema, user })`);
     }
     // Schema is optional for the model-first API:
     //   Ablo({ apiKey }).model('clauses').retrieve(...)
@@ -37,7 +37,7 @@ export function validateAbloOptions(input) {
     if (!configuredApiKey && !configuredAuthToken && kind === 'agent' && !options.capabilityToken) {
         return new Error('Ablo: provide either `apiKey` (hosted cloud — SDK exchanges internally) ' +
             'or `capabilityToken` (self-hosted — your auth layer mints + hands in). ' +
-            'See https://ablo.dev/docs/api-keys for the full pattern.');
+            'See https://abloatai.com/docs/api-keys for the full pattern.');
     }
     return null;
 }

package/dist/coordination/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * `@abloatai/ablo/coordination` — the canonical wire schema for the three
+ * coordination layers (presence, pessimistic claims, optimistic stale-context).
+ * See `./schema.ts` for the model and the per-layer schemas.
+ */
+export * from './schema.js';

package/dist/coordination/index.js

@@ -0,0 +1,6 @@
+/**
+ * `@abloatai/ablo/coordination` — the canonical wire schema for the three
+ * coordination layers (presence, pessimistic claims, optimistic stale-context).
+ * See `./schema.ts` for the model and the per-layer schemas.
+ */
+export * from './schema.js';