@abloatai/ablo 0.6.0 → 0.8.0

package/llms.txt

@@ -2,6 +2,8 @@
 
 Ablo is the state coordination layer for apps where humans and agents edit the same data.
 
+Here is the problem it solves. Two writers touch `report_stockholm` at once. The agent claims the row, does slow work (an LLM call, a fetch), and commits; the human's UI sees the claim live and never clobbers it. 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 two writers serialize instead of clobbering.
+
 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.
 
 ## Use this API
@@ -21,7 +23,7 @@ const schema = defineSchema({
 
 const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
 
-const [report] = await ablo.weatherReports.load({ where: { id: 'report_stockholm' } });
+const report = await ablo.weatherReports.retrieve('report_stockholm');
 if (!report) throw new Error('Row not found');
 
 const updated = await ablo.weatherReports.claim('report_stockholm', async (report) => {
@@ -33,20 +35,29 @@ const updated = await ablo.weatherReports.claim('report_stockholm', async (repor
 });
 ```
 
-That is the normal app path: declare models in a schema, then use `ablo.<model>.load(...)`, `ablo.<model>.retrieve(...)`, `ablo.<model>.create(...)`, `ablo.<model>.update(...)`, and `ablo.<model>.delete(...)`.
+That is the normal app path: declare models in a schema, then use `ablo.<model>.retrieve(...)`, `ablo.<model>.create(...)`, `ablo.<model>.update(...)`, and `ablo.<model>.delete(...)`.
+
+Treat the schema as the integration contract. It drives typed model clients,
+React selectors, server and agent writes, Data Source request/response shape,
+hosted schema push, and schema-version gating. Do not invent a parallel
+string-keyed write path for rows that belong to a schema model.
 
 For full integrations, use `integration-guide` as the canonical doc. It covers
 the same model API across Ablo-managed state, Data Source-backed app databases,
 React selectors, multiplayer, and future agent workers.
 
-`ablo.<model>.list(...)` and `count(...)` are synchronous local reads. They
-accept `where`, `filter`, `orderBy`, `limit`, `offset`, and `scope`; scope
-defaults to `'live'`, with `'archived'` and `'all'` for lifecycle-aware reads.
+Reads come in two flavors, and you pick by whether you can wait. `retrieve(id)`
+(one row) and `list({ where })` (many) are async — they hit the server and return
+a Promise, so await them. `get(id)`, `getAll({ where })`, and `getCount({ where })`
+are synchronous — they read the local graph and are reactive in render, so no
+await. The query reads accept `where`, `filter`, `orderBy`, `limit`, `offset`,
+and `state`; state defaults to `'live'`, with `'archived'` and `'all'` to include
+retired rows.
 
-Advanced schema-less agents exist for workers that cannot import the app schema,
-but do not teach that path first.
+Workers that can't import the app schema can use a schema-less mode (covered in
+`integration-guide`).
 
-React reads should use selector `useAblo`: `useAblo((ablo) => ablo.weatherReports.retrieve(id))`.
+React reads should use selector `useAblo`: `useAblo((ablo) => ablo.weatherReports.get(id))` (synchronous local read, reactive in render).
 Use zero-argument `useAblo()` only when a component needs the client for an
 event handler or effect. Treat `useQuery`, `useOne`, `useReader`, and
 `useMutate` as compatibility hooks for older string-keyed integrations, not the
@@ -57,7 +68,7 @@ first integration path.
 Multiplayer is not a separate mode. When human UI, server actions, and agents use
 the same schema client and write through `ablo.<model>`, Ablo coordinates the
 shared model stream: confirmed deltas fan out to subscribers, active claims are
-visible through `claimState(id)`, and stale writes can be rejected with `readAt`.
+visible through `claim.state(id)`, and stale writes can be rejected with `readAt`.
 
 If an app writes directly to its own database outside Ablo, that write bypasses
 coordination until the app reports it through Data Source events.
@@ -65,7 +76,7 @@ coordination until the app reports it through Data Source events.
 ## Nouns
 
 - `Model client` is the typed `ablo.<model>` object generated from schema.
-- `Claim` holds a model row while slow work runs; `claimState(id)` observes it.
+- `Claim` holds a model row while slow work runs; `claim.state(id)` observes it.
 - `Commit` is the durable protocol write behind `ablo.<model>.update(...)`.
 - `Receipt` confirms the commit.
 
@@ -76,23 +87,23 @@ Server reads through `ablo.model(name)` can pass `ifClaimed: 'return'` to
 receive active claims, `ifClaimed: 'fail'` to throw `AbloClaimedError`, or
 `ifClaimed: 'wait'` to wait until the active claim clears.
 
-Schema clients wait from the realtime claim stream. Schema-less HTTP callers must provide an explicit `claimedPollInterval` when using `ifClaimed: 'wait'`; Ablo does not hide a hard-coded polling loop.
+Schema clients learn when a claim clears by listening to the live claim stream, so they don't need to poll. Schema-less HTTP callers must provide an explicit `claimedPollInterval` when using `ifClaimed: 'wait'`; Ablo does not hide a hard-coded polling loop.
 
 Use `claimedTimeout` only as a maximum wait, not as the coordination mechanism.
 
 ## Guarantees
 
-`wait: 'confirmed'` means the server accepted the write. Schema model writes are optimistic by default; server rejection rolls back local state. Use `snapshot(...)` plus `readAt` and `onStale: 'reject'` to prevent lost updates.
+`wait: 'confirmed'` means the server accepted the write. Schema model writes are optimistic by default; server rejection rolls back local state. To prevent lost updates, read with `snapshot(...)` to capture a `readAt`, then write with `onStale: 'reject'` — the server rejects your update if someone else changed the row after that `readAt`.
 
 Claims coordinate writers; they do not block readers. Most users should stay on
-schema-backed reads/writes and `claim(...)`; do not teach manual protocol
-bookkeeping in the happy path.
+schema-backed reads/writes and `claim(...)`; manual protocol bookkeeping is not
+part of the happy path.
 
 All SDK errors extend `AbloError`. Important classes: `AbloClaimedError`, `AbloStaleContextError`, `AbloAuthenticationError`, `AbloPermissionError`, `AbloRateLimitError`, `AbloIdempotencyError`, `AbloConnectionError`, `AbloValidationError`, and `AbloServerError`.
 
 ## Schema Scope
 
-Teach schema as model fields and relations first. Advanced schema helpers such as `mutable`, `readOnly`, `field`, `indexed`, queries, and load strategies exist for offline/cache/indexing-heavy apps, but they should not be the first concept a new integration sees.
+A schema is model fields and relations. Advanced schema helpers such as `mutable`, `readOnly`, `field`, `indexed`, queries, and load strategies exist for offline/cache/indexing-heavy apps; reach for them only after the basic field/relation schema is working.
 
 ## Storage Boundary
 
@@ -135,4 +146,4 @@ Import from these public paths only:
 
 Do not teach `/api`, `/agent`, `/ai-sdk`, `/core`, `/realtime`, `/source`, or internal subpaths.
 
-Canonical docs to read before integrating: `quickstart`, `integration-guide`, `guarantees`, `client-behavior`, `data-sources`, `examples/existing-python-backend`, `api`, `examples/ai-sdk-tool`, and `examples/server-agent`.
+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`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/ablo",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "State control API for AI agents and collaborative apps.",
   "license": "Apache-2.0",
   "type": "module",
@@ -20,6 +20,11 @@
       "import": "./dist/schema/index.js",
       "default": "./dist/schema/index.js"
     },
+    "./coordination": {
+      "types": "./dist/coordination/index.d.ts",
+      "import": "./dist/coordination/index.js",
+      "default": "./dist/coordination/index.js"
+    },
     "./react": {
       "types": "./dist/react/index.d.ts",
       "import": "./dist/react/index.js",
@@ -49,6 +54,11 @@
       "types": "./dist/source/index.d.ts",
       "import": "./dist/source/index.js",
       "default": "./dist/source/index.js"
+    },
+    "./keys": {
+      "types": "./dist/keys/index.d.ts",
+      "import": "./dist/keys/index.js",
+      "default": "./dist/keys/index.js"
     }
   },
   "files": [
@@ -71,6 +81,8 @@
     "build": "npm run clean && tsc -p tsconfig.build.json",
     "pack:check": "npm_config_cache=${TMPDIR:-/tmp}/ablo-npm-cache npm pack --dry-run",
     "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:pkg": "publint",
     "prepublishOnly": "npm run build && npm run lint:pkg",
     "test": "jest",