@abloatai/ablo 0.3.1 → 0.5.0

package/docs/data-sources.md

@@ -2,6 +2,11 @@
 
 Every schema model has a backing store.
 
+Customer apps must define an Ablo schema. The schema is the contract between
+the SDK, agents, realtime subscriptions, and the Data Source endpoint. Use
+`defineSchema`, `model`, and Zod the same way a Prisma project starts with a
+`schema.prisma`.
+
 By default, Ablo stores the rows for the models you declare. That makes Ablo the
 managed state store for those resources, the same way Stripe stores `Customer`
 and `PaymentIntent` objects that you create through Stripe's API.
@@ -10,6 +15,11 @@ If you already have application tables and want those tables to remain
 canonical, attach a Data Source. Then Ablo coordinates the write and calls your
 app to commit it.
 
+Your app can keep using its own `DATABASE_URL`. Store that value in your app or
+backend environment, not in Ablo. The integration boundary is the HTTPS
+endpoint your app exposes. The happy path uses the same server-side
+`ABLO_API_KEY` to verify Ablo calls.
+
 Use the SDK with an API key:
 
 ```ts
@@ -24,6 +34,16 @@ export const ablo = Ablo({
 
 Do not pass a database URL to `Ablo(...)`.
 
+For the first production integration, prefer this shape:
+
+```bash
+# Stored only in your app/backend
+DATABASE_URL=postgres://...
+
+# The only Ablo credential in the customer app
+ABLO_API_KEY=sk_live_...
+```
+
 ## Backing Modes
 
 | Mode | Where rows live | What `create/update/delete` does | Use when |
@@ -62,21 +82,18 @@ When you add a Data Source in Ablo, you get:
 
 | Field | Purpose |
 |---|---|
-| Data Source URL | The public HTTPS route in your app that Ablo will call. |
-| Signing secret | Stored in your app as `ABLO_DATA_SOURCE_SIGNING_SECRET`; used to verify Ablo calls. |
-| Push events URL | Ablo endpoint your app can call when rows change outside Ablo. |
+| Data Source endpoint | The public HTTPS endpoint in your app that Ablo calls. |
+| API key | Stored in your app as `ABLO_API_KEY`; used by the SDK and the Data Source endpoint. |
+| External-write feed | Optional `events` handler on the same Data Source endpoint. |
 | Status | Last successful request, last error, and delivery attempts. |
 
 The shape is the same as a production webhook integration:
 
-1. Add a Data Source URL in Ablo.
-2. Store the signing secret in your app.
-3. Expose one signed HTTP route from your app.
+1. Expose one Data Source endpoint in your app.
+2. Store `ABLO_API_KEY` in your app.
+3. Verify signed HTTP calls before opening a database transaction.
 4. Keep your database credentials in your app.
-
-```bash
-ABLO_DATA_SOURCE_SIGNING_SECRET=whsec_...
-```
+5. Write an outbox row when data changes outside Ablo.
 
 ## Route
 
@@ -88,7 +105,7 @@ import { db } from '@/db';
 
 export const POST = dataSource({
   schema,
-  signingSecret: process.env.ABLO_DATA_SOURCE_SIGNING_SECRET,
+  apiKey: process.env.ABLO_API_KEY,
 
   authorize() {
     return { db };
@@ -176,7 +193,7 @@ handler so connected humans and agents stay current:
 ```ts
 export const POST = dataSource({
   schema,
-  signingSecret: process.env.ABLO_DATA_SOURCE_SIGNING_SECRET,
+  apiKey: process.env.ABLO_API_KEY,
 
   async events({ cursor, limit, context }) {
     const page = await context.auth.db.outbox.after(cursor, { limit });
@@ -201,14 +218,31 @@ export const POST = dataSource({
 `clientTxId` lets Ablo drop SDK echoes that already produced a realtime update.
 Events without `clientTxId` are treated as external writes.
 
+## Production Checklist
+
+Before using a customer-owned database in production:
+
+- Keep `DATABASE_URL` in the customer app or backend environment.
+- Use only the Data Source endpoint and `ABLO_API_KEY` as the customer-facing integration boundary.
+- Verify signatures before opening a database transaction.
+- Store `clientTxId` in an idempotency table before applying writes.
+- Return canonical rows after each commit.
+- Write outbox events in the same transaction as non-Ablo writes.
+- Dedupe outbox events by event `id`.
+- Monitor last success, last error, retry count, event lag, and cursor.
+
+Do not send the customer's database URL to Ablo for this path. Direct database
+URL custody would be a separate connector product with encrypted secret storage,
+rotation, least-privilege roles, connection limits, table allowlists, and clear
+data-processing terms.
+
 ## Security
 
-- Verify requests with `ABLO_DATA_SOURCE_SIGNING_SECRET`.
+- Verify requests with `ABLO_API_KEY`.
 - Keep database credentials in your app.
 - Dedupe commits by `clientTxId`.
 - Dedupe external events by event `id`.
 - Use HTTPS in production.
 
-The signing secret is not a database credential and does not give Ablo access to
-your database. It only lets your route verify that the request came from Ablo
-and was not modified in transit.
+The API key is not a database credential. It only lets your route verify that
+the request came from Ablo and was not modified in transit.

package/docs/examples/ai-sdk-tool.md

@@ -34,38 +34,21 @@ const updateTask = tool({
     const [task] = await ablo.tasks.load({ where: { id: taskId } });
     if (!task) return { ok: false, reason: 'not_found' };
 
-    const busy = ablo.intents.list({ resource: 'tasks', id: taskId });
-    if (busy.length > 0) {
-      await ablo.intents.waitFor(
-        { resource: 'tasks', id: taskId },
-        { timeout: 30_000 },
-      );
-    }
-
-    const snap = ablo.snapshot({ tasks: taskId });
-    const intent = await ablo.intents.create({
-      target: { resource: 'tasks', id: taskId, field: 'status' },
-      action: 'update',
-    });
+    const claim = ablo.tasks.intent(taskId);
+    if (claim.current) await claim.whenFree({ timeout: 30_000 });
 
+    await claim.claim({ action: 'editing', field: 'status', ttl: '2m' });
     try {
-      const updated = await ablo.tasks.update(
-        taskId,
-        {
-          status: status ?? task.status,
-          summary: summary ?? task.summary,
-        },
-        {
-          intent,
-          readAt: snap.stamp,
-          onStale: 'reject',
-          wait: 'confirmed',
-        },
-      );
+      // update commits with the held claim and auto-releases on success
+      const updated = await claim.update({
+        status: status ?? task.status,
+        summary: summary ?? task.summary,
+      });
 
       return { ok: true, task: updated };
-    } finally {
-      await intent.release();
+    } catch (err) {
+      await claim.finish();
+      throw err;
     }
   },
 });
@@ -85,8 +68,8 @@ The important part is not the model provider. The important part is that the
 tool:
 
 - loads the latest task,
-- checks active intent,
-- writes with `readAt`,
-- rejects stale state,
+- waits if another participant already holds the row,
+- acquires a claim before writing,
+- writes and auto-releases through the same handle,
 - waits for server confirmation.
 

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

@@ -95,16 +95,16 @@ No string model key is needed in the first example. The selector reads from
 
 ## 3. Add One Python Data Source Endpoint
 
-In Ablo, configure the Data Source URL:
+Expose one customer-owned Data Source endpoint:
 
 ```txt
 https://api.example.com/api/ablo/source
 ```
 
-Store the signing secret in the Python server:
+Store the Ablo API key in the Python server:
 
 ```bash
-ABLO_DATA_SOURCE_SIGNING_SECRET=whsec_...
+ABLO_API_KEY=sk_live_...
 ```
 
 Then expose one route that verifies the signed request and calls the existing
@@ -126,7 +126,7 @@ router = APIRouter()
 
 
 def verify_ablo_signature(request: Request, raw_body: bytes) -> None:
-    secret = os.environ["ABLO_DATA_SOURCE_SIGNING_SECRET"].encode()
+    api_key = os.environ["ABLO_API_KEY"].encode()
     message_id = request.headers.get("webhook-id")
     timestamp = request.headers.get("webhook-timestamp")
     signature_header = request.headers.get("webhook-signature", "")
@@ -135,12 +135,12 @@ def verify_ablo_signature(request: Request, raw_body: bytes) -> None:
         raise HTTPException(status_code=401, detail="missing signature")
 
     signed_at = int(timestamp)
-    if abs(int(time.time() * 1000) - signed_at) > 5 * 60 * 1000:
+    if abs(int(time.time()) - signed_at) > 5 * 60:
         raise HTTPException(status_code=401, detail="expired signature")
 
     payload = message_id.encode() + b"." + timestamp.encode() + b"." + raw_body
     expected = base64.b64encode(
-        hmac.new(secret, payload, hashlib.sha256).digest()
+        hmac.new(api_key, payload, hashlib.sha256).digest()
     ).decode()
 
     presented = [

package/docs/integration-guide.md

@@ -66,8 +66,8 @@ Every schema model has a backing store. The SDK call shape stays the same.
 | Schema-less resource API | Custom runtime | A server worker, MCP route, or migration script intentionally cannot import the app schema. |
 
 Do not pass a database URL to `Ablo(...)`. Application and agent code use
-`ABLO_API_KEY`. If your database stays canonical, add a Data Source URL in Ablo
-and keep the database credentials inside your app.
+`ABLO_API_KEY`. If your database stays canonical, expose a signed Data Source
+endpoint from your app and keep the database credentials inside your app.
 
 ## Test With Sandboxes
 
@@ -375,7 +375,7 @@ import { db } from '@/db';
 
 export const POST = dataSource({
   schema,
-  signingSecret: process.env.ABLO_DATA_SOURCE_SIGNING_SECRET,
+  apiKey: process.env.ABLO_API_KEY,
 
   authorize() {
     return { db };
@@ -404,14 +404,15 @@ export const POST = dataSource({
 });
 ```
 
-Ablo gives you a Data Source URL, a signing secret, push/events URL, and status.
-Your app stores:
+Ablo needs your Data Source endpoint and API key. External writes can be
+reported through an optional `events` handler on the same route. Your app
+stores one Ablo credential:
 
 ```bash
-ABLO_DATA_SOURCE_SIGNING_SECRET=whsec_...
+ABLO_API_KEY=sk_live_...
 ```
 
-The signing secret verifies Ablo's request. It is not a database credential.
+The API key verifies Ablo's request. It is not a database credential.
 
 ## 8. Agents
 

package/docs/interaction-model.md

@@ -20,7 +20,7 @@ Capability -> Task -> Usage
 |---|---|---|
 | `Schema` | State | Declares typed models the app and agents can read and write. |
 | `Model` | State | The generated `ablo.<model>` resource. Use `load`, `retrieve`, `create`, `update`, and `delete`. |
-| `Intent` | State | Pre-write coordination. It says what this actor is preparing to change. |
+| `Intent` | Coordination | Who is working on a target, as one Stripe-shaped object with a single `status`. Opened and read through `ablo.<model>.intent(id)`. Ephemeral — never persisted. |
 | `Commit` | Protocol | The durable write underneath model updates. Most users do not call it directly. |
 | `Receipt` | Protocol | The lower-level durable result for custom runtimes. Schema writes use `wait: 'confirmed'`. |
 | `Capability` | Control | Signed credentials. It says who can do what, where, for how long, and on whose behalf. |
@@ -110,9 +110,21 @@ Removing any one of the three leaves a class of attack uncovered. The pattern ma
 
 ## Coordination
 
-Intents broadcast across the org. When `agent:task-writer` declares an intent to
-update a task, schema clients can see it through `ablo.intents.list(...)` or the
-live intent stream. Callers decide whether to yield, wait, or fail fast.
+Intents broadcast across the org. Open and read one on any row through the
+model accessor:
+
+```ts
+const task = ablo.tasks.intent('task_123');
+if (task.current) await task.whenFree();     // someone's working — wait
+await task.claim({ action: 'editing' });     // claim so others yield
+await task.update({ status: 'done' });        // commits + releases
+```
+
+`task.current` is the live `Intent` (or `null`); `task.whenFree()` resolves when
+the holder finishes. The same signal is visible to every schema client through
+`ablo.intents.list(...)` and the live intent stream, so callers decide whether
+to yield, wait, or fail fast. See [API → Intent](./api.md#intent) for the object
+reference and lifecycle.
 
 ## Conflict resolution
 

package/docs/mcp.md

@@ -21,7 +21,7 @@ Each resource you declare becomes one or more MCP tools:
 | `retrieve` | `<resource>.retrieve` | Returns the row + a stamp. |
 | `list` | `<resource>.list` | Cursor-paginated discovery. |
 | `update` | `<resource>.update` | Write, requires the prior stamp. |
-| `intents.create` | `intent.create` | Declare a claim before writing. |
+| `<model>.intent` | `intent.create` | Claim a row before writing, then auto-release on update. |
 
 The assistant gets typed JSON schemas, real argument types, and typed
 rejections when it writes stale state. No invention, no hallucinated IDs.

package/docs/quickstart.md

@@ -43,8 +43,9 @@ export const ablo = Ablo({
 });
 ```
 
-Pass `schema` for typed model resources. Omit it only for advanced server-side
-resource clients such as custom agents and MCP routes.
+Customer apps should always pass `schema`. Treat it like Prisma's schema file:
+it is the source of truth for typed model resources, realtime subscriptions,
+agent writes, and Data Source requests.
 
 ## 4. Create and Update
 
@@ -79,33 +80,34 @@ ABLO_API_KEY=sk_test_... npx tsx quickstart.ts
 
 ## 6. AI Activity on Existing State
 
-Use `edit` when AI or background work will touch an existing row for more than a
-quick write. Other participants can see the activity while your code runs. The
-activity is cleared when `update` finishes; call `release` if the work ends
-without a write.
+When AI or background work will touch an existing row for more than a quick
+write, coordinate through `ablo.<model>.intent(id)`. It returns a handle
+synchronously — read `.current` to see who's working on the row, `claim()` to
+claim it, `update()` to write under the claim (which auto-releases).
 
 ```ts
-const edit = await ablo.weatherReports.edit('weather_stockholm', {
-  activity: 'checking_weather',
-  field: 'forecast',
-  ttl: '2m',
-});
+const report = ablo.weatherReports.intent('weather_stockholm');
+
+// If another participant holds it, wait for them to finish.
+if (report.current) await report.whenFree();
+
+// Claim it so other participants yield while we work.
+await report.claim({ action: 'checking_weather', field: 'forecast', ttl: '2m' });
 
 // Your existing weather tool or agent call. While this runs, other clients see
 // that weather_stockholm is being checked.
-const weather = await weatherAgent.getWeather(edit.current.location, {
-  signal: edit.signal,
-});
+const row = ablo.weatherReports.retrieve('weather_stockholm');
+const weather = await weatherAgent.getWeather(row.location);
 
-await edit.update({
+await report.update({
   status: 'ready',
   forecast: weather.summary,
 });
 ```
 
-Ablo does not fetch the weather. It keeps the activity visible, gives the agent
-call an abort signal if the row changes, and clears the activity when
-`edit.update(...)` finishes.
+Ablo does not fetch the weather. It keeps the activity visible while the work
+runs, rejects `report.update(...)` with `AbloStaleContextError` if the row
+changed under you, and releases the intent automatically once the write lands.
 
 ## 7. Multiplayer and Busy Work
 

package/examples/data-source/README.md

@@ -22,7 +22,7 @@ npx tsx data-source/run.ts
 
 No network port, no env vars, no cloud credentials. The orchestrator
 calls the handler in-process. Signer and verifier still exchange
-signed bytes — flip the secret and you'll see a 401.
+signed bytes — flip the API key and you'll see a 401.
 
 ## What it proves
 

package/examples/data-source/ablo-driver.ts

@@ -7,7 +7,7 @@
  * locally without standing up the cloud.
  *
  * In production:
- *   - Ablo Cloud holds the signing secret in its config
+ *   - Ablo Cloud holds the API key in its config
  *   - It signs each outbound POST with `signAbloSourceRequest`
  *   - The customer's `dataSource(...)` handler verifies the signature
  *   - The response feeds back into Ablo Cloud's hosted realtime layer
@@ -19,7 +19,7 @@
 import {
   signAbloSourceRequest,
   type Ablo,
-} from '@ablo/sync-engine';
+} from '@abloatai/ablo';
 
 export interface AbloDriverOptions {
   /**
@@ -27,8 +27,8 @@ export interface AbloDriverOptions {
    * the handler directly so there's no http port to manage.
    */
   readonly handler: (request: Request) => Promise<Response>;
-  /** Same secret the customer's `dataSource(...)` is configured with. */
-  readonly signingSecret: string;
+  /** Same API key the customer's `dataSource(...)` is configured with. */
+  readonly apiKey: string;
 }
 
 export class AbloDriver {
@@ -68,7 +68,7 @@ export class AbloDriver {
     const body = JSON.stringify(payload);
     const messageId = `msg_${Date.now()}_${this.messageCounter}`;
     const signed = await signAbloSourceRequest({
-      secret: this.options.signingSecret,
+      apiKey: this.options.apiKey,
       body,
       messageId,
     });

package/examples/data-source/customer-server.ts

@@ -15,7 +15,7 @@
  * inside a transaction. The shape of the handlers stays identical.
  */
 
-import Ablo, { dataSource } from '@ablo/sync-engine';
+import Ablo, { dataSource } from '@abloatai/ablo';
 import { schema } from './schema';
 
 type TaskRow = {
@@ -68,20 +68,20 @@ taskStore.set('task_seed', {
 export const handleAbloSource = dataSource({
   schema,
 
-  // The signing secret pairs with what Ablo Cloud is configured with.
-  // Wrong secret -> 401 with `source_signature_invalid`. Passing a
-  // function (instead of the env value directly) re-reads the secret
-  // on every request — convenient for rotation, and required by the
+  // The API key pairs with what Ablo Cloud is configured with.
+  // Wrong key -> 401 with `source_signature_invalid`. Passing a
+  // function (instead of the env value directly) re-reads the key
+  // on every request and is required by the
   // example because `run.ts` configures the env after this module is
   // imported.
-  signingSecret: () => {
-    const secret = process.env.ABLO_DATA_SOURCE_SIGNING_SECRET;
-    if (!secret) {
+  apiKey: () => {
+    const apiKey = process.env.ABLO_API_KEY;
+    if (!apiKey) {
       throw new Error(
-        'ABLO_DATA_SOURCE_SIGNING_SECRET is not set — refusing to accept unsigned requests',
+        'ABLO_API_KEY is not set — refusing to accept unsigned requests',
       );
     }
-    return secret;
+    return apiKey;
   },
 
   // `authorize` runs before any handler. Use it to map the signed

package/examples/data-source/run.ts

@@ -9,7 +9,7 @@
  * What this proves:
  *
  *   1. Ablo Cloud's signer + the customer's verifier interop. A wrong
- *      secret produces `source_signature_invalid`.
+ *      API key produces `source_signature_invalid`.
  *   2. `load`, `list`, `commit`, and `events` all flow through the
  *      same Fetch-API handler.
  *   3. The customer's "database" (here a Map) holds canonical rows.
@@ -21,19 +21,17 @@
 import { handleAbloSource, _inspectStore } from './customer-server';
 import { AbloDriver } from './ablo-driver';
 
-const SIGNING_SECRET =
-  process.env.ABLO_DATA_SOURCE_SIGNING_SECRET ?? 'whsec_example_secret_do_not_use_in_prod';
+const API_KEY =
+  process.env.ABLO_API_KEY ?? 'sk_test_example_key_do_not_use_in_prod';
 
-// `dataSource()` reads `options.signingSecret` at construction; we
-// re-export the same value to the driver so signer and verifier agree.
-// In production this is one secret shared between Ablo Cloud config
-// and the customer's environment.
-process.env.ABLO_DATA_SOURCE_SIGNING_SECRET = SIGNING_SECRET;
+// `dataSource()` reads `options.apiKey` at request time; we re-export
+// the same value to the driver so signer and verifier agree.
+process.env.ABLO_API_KEY = API_KEY;
 
 async function main() {
   const driver = new AbloDriver({
     handler: handleAbloSource,
-    signingSecret: SIGNING_SECRET,
+    apiKey: API_KEY,
   });
 
   log('--- 1. load (existing seeded row) ---');
@@ -68,10 +66,10 @@ async function main() {
   const events = await driver.events();
   log('events:', events);
 
-  log('\n--- 5. signature failure (wrong secret) ---');
+  log('\n--- 5. signature failure (wrong API key) ---');
   const badDriver = new AbloDriver({
     handler: handleAbloSource,
-    signingSecret: 'whsec_wrong_secret',
+    apiKey: 'sk_test_wrong_key',
   });
   try {
     await badDriver.load('tasks', 'task_seed');

package/examples/data-source/schema.ts

@@ -12,7 +12,7 @@
  * side without the other is a compile error.
  */
 
-import { defineSchema, model, z } from '@ablo/sync-engine/schema';
+import { defineSchema, model, z } from '@abloatai/ablo/schema';
 
 export const schema = defineSchema({
   tasks: model({

package/examples/quickstart.ts

@@ -6,8 +6,8 @@
  *   ABLO_API_KEY=sk_test_... npx tsx quickstart.ts
  */
 
-import Ablo from '@ablo/sync-engine';
-import { defineSchema, model, z } from '@ablo/sync-engine/schema';
+import Ablo from '@abloatai/ablo';
+import { defineSchema, model, z } from '@abloatai/ablo/schema';
 
 const schema = defineSchema({
   weatherReports: model({

package/llms.txt

@@ -103,7 +103,7 @@ Teach schema as model fields and relations first. Advanced schema helpers such a
 
 Do not add `databaseURL` to `Ablo(...)`. Application and agent code use `ABLO_API_KEY`.
 
-Every schema model has a backing store. By default, Ablo stores rows for declared models, so `ablo.<model>.create/update/delete` write to Ablo-managed state. If the customer database is canonical, add a Data Source URL in Ablo, store `ABLO_DATA_SOURCE_SIGNING_SECRET` in the app, then expose a signed `dataSource({ schema, signingSecret, load, list, commit, events })` route from the customer app. Customer-owned app database credentials stay private.
+Every schema model has a backing store. By default, Ablo stores rows for declared models, so `ablo.<model>.create/update/delete` write to Ablo-managed state. If the customer database is canonical, expose a Data Source endpoint and pass `apiKey: process.env.ABLO_API_KEY` to `dataSource({ schema, apiKey, load, list, commit, events })`. Customer-owned app database credentials stay private.
 
 Use `dataSource` from the root import:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/ablo",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "description": "State control API for AI agents and collaborative apps.",
   "license": "Apache-2.0",
   "type": "module",