@abloatai/ablo 0.3.0 → 0.4.0

package/docs/quickstart.md

@@ -9,7 +9,7 @@ Ablo-managed state versus a Data Source that calls your existing API service.
 ## 1. Install
 
 ```bash
-npm install @ablo/sync-engine
+npm install @abloatai/ablo
 ```
 
 ## 2. Set a Sandbox Key
@@ -26,8 +26,8 @@ provider with a scoped capability/session route, not a bundled API key.
 ## 3. Declare a Schema
 
 ```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({
@@ -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, `acquire()` 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.settled();
+
+// Claim it so other participants yield while we work.
+await report.acquire({ 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/docs/react.md

@@ -1,6 +1,6 @@
 # React
 
-The React bindings for `@ablo/sync-engine`. Use them when you want live
+The React bindings for `@abloatai/ablo`. Use them when you want live
 data on the client without writing fetch + WebSocket plumbing yourself.
 
 For the full app structure, including server loads, existing backends, and
@@ -11,7 +11,7 @@ agents, start with [Integration Guide](/docs/integration-guide).
 The React bindings ship with the main package — no extra install.
 
 ```ts
-import { useAblo } from '@ablo/sync-engine/react';
+import { useAblo } from '@abloatai/ablo/react';
 ```
 
 ## useAblo — model resource
@@ -19,7 +19,7 @@ import { useAblo } from '@ablo/sync-engine/react';
 ```tsx
 'use client';
 
-import { useAblo } from '@ablo/sync-engine/react';
+import { useAblo } from '@abloatai/ablo/react';
 
 export function TaskView({ task: serverTask }: { task: { id: string; title: string } }) {
   const task = useAblo((ablo) => ablo.tasks.retrieve(serverTask.id)) ?? serverTask;

package/docs/roadmap.md

@@ -8,7 +8,7 @@ What is shipped, what is next, and what we will not build.
 - **Capability tokens** — Biscuit-signed, scoped, attenuable, hot-revocable.
 - **Audit log** — hash-chained per principal, with `delegationChainRoot`.
 - **MCP transport** — HTTP server at `/api/mcp`.
-- **TypeScript SDK** — `@ablo/sync-engine`, with React bindings.
+- **TypeScript SDK** — `@abloatai/ablo`, with React bindings.
 - **Dashboard** — keys, audit, metrics, allowed origins.
 
 ## In flight

package/examples/README.md

@@ -1,11 +1,11 @@
-# @ablo/sync-engine Examples
+# @abloatai/ablo Examples
 
 The examples teach the same path as the README and docs: declare a schema,
 create or load typed models, and write through `ablo.<model>`.
 
 ```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/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

@@ -7,8 +7,8 @@ Use AI SDK for the agent loop. Use Ablo when agent reads and writes must persist
 ## Use this API
 
 ```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({
   tasks: model({
@@ -103,12 +103,12 @@ 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:
 
 ```ts
-import { dataSource } from '@ablo/sync-engine';
+import { dataSource } from '@abloatai/ablo';
 ```
 
 ## Sandboxes
@@ -133,10 +133,10 @@ two-writer stale/intent smoke test.
 
 Import from these public paths only:
 
-- `@ablo/sync-engine` — `Ablo`, errors, typed model resources, intents, `dataSource`, and advanced protocol resources.
-- `@ablo/sync-engine/schema` — schema DSL.
-- `@ablo/sync-engine/react` — React provider and hooks.
-- `@ablo/sync-engine/testing` — test harnesses and mocks.
+- `@abloatai/ablo` — `Ablo`, errors, typed model resources, intents, `dataSource`, and advanced protocol resources.
+- `@abloatai/ablo/schema` — schema DSL.
+- `@abloatai/ablo/react` — React provider and hooks.
+- `@abloatai/ablo/testing` — test harnesses and mocks.
 
 Do not teach `/api`, `/agent`, `/ai-sdk`, `/core`, `/realtime`, `/source`, or internal subpaths.
 

package/package.json

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