@abloatai/ablo 0.51.0 → 0.53.0

package/docs/sessions.md

@@ -13,13 +13,13 @@ One resource mints both:
 // A logged-in person's browser session — only the operations this UI needs.
 const userSession = await ablo.sessions.create({
   user: { id: currentUser.id },
-  can: { tasks: ['read', 'update'], workspaces: ['read'] },
+  can: { records: ['read', 'update'], workspaces: ['read'] },
 });
 
 // Recommended agent path — returns a ready, scoped client.
 const agent = await ablo.agents.create({
-  name: 'task-writer',
-  can: { tasks: ['read', 'update'], workspaces: ['read'] },
+  name: 'record-writer',
+  can: { records: ['read', 'update'], workspaces: ['read'] },
 });
 ```
 
@@ -51,7 +51,7 @@ import { credentialEndpointSuccessSchema } from '@abloatai/ablo/auth';
 
 const { token, expiresAt } = await ablo.sessions.create({
   user: { id: currentUser.id },   // who the session acts as
-  can: { tasks: ['read', 'update'] },
+  can: { records: ['read', 'update'] },
   // syncGroups: [...],           // optional; defaults to the user's org + user
 });
 return Response.json(
@@ -104,18 +104,18 @@ error, not a silent over-grant:
 
 ```ts
 const agent = await ablo.agents.create({
-  name: 'task-writer',
-  can: { tasks: ['update'] },  // typed off the schema — no magic strings
+  name: 'record-writer',
+  can: { records: ['update'] },  // typed off the schema — no magic strings
   ttlSeconds: 600,
 });
 
-await agent.tasks.update({ id, data });
+await agent.records.update({ id, data });
 await agent.dispose();
 ```
 
 The returned client refreshes its own short-lived credential. A write grant
 automatically includes the corresponding read, so
-`can: { tasks: ['update'] }` is enforced as `task.update` plus `task.read`.
+`can: { records: ['update'] }` is enforced as `record.update` plus `record.read`.
 Operations are `'read' | 'create' | 'update' | 'delete'`.
 
 For a reusable grant, use TypeScript's `satisfies`. It checks the object against
@@ -126,14 +126,14 @@ second permission model:
 import type { CapabilityGrant } from '@abloatai/ablo/auth';
 import { schema } from './ablo.schema';
 
-const taskWriterCan = {
-  tasks: ['update'],
+const recordWriterCan = {
+  records: ['update'],
 } satisfies CapabilityGrant<typeof schema>;
 
-const agent = await ablo.agents.create({ can: taskWriterCan });
+const agent = await ablo.agents.create({ can: recordWriterCan });
 ```
 
-`documents` instead of `tasks`, or `'write'` instead of `'update'`, is a compile
+`documents` instead of `records`, or `'write'` instead of `'update'`, is a compile
 error. At runtime the SDK parses the same grant with the schema-bound Zod
 contract before minting, and the server validates it again against the active
 pushed schema.
@@ -154,6 +154,8 @@ for the actor.
 |---|---|---|
 | `user` / `agent` | both | The actor. `id` becomes the token's `participantId`. Pass exactly one. |
 | `can` | both | Required non-empty per-model operation allowlist, typed off the schema. |
+| `organizationId` | user | Mint into a customer organization instead of the key's own. Requires `ephemeral:mint-any-org`. |
+| `schemaProject` | user | Override the schema project for a cross-org mint. Usually omitted because the owning key's project is the default. |
 | `syncGroups` | both | Narrow the session below its default scope. Omit to inherit. |
 | `ttlSeconds` | both | Lifetime in seconds. Defaults to `900` (15m). |
 | `userMeta` | both | Opaque identity blob echoed back to the client. |
@@ -217,7 +219,7 @@ errors.
 
 A user session carries the user's **base** sync-groups (`org:`/`user:`/`team:`),
 derived from the identity you minted it for. **Dynamic, relation-driven
-membership** (e.g. a `dataroom:<id>` the user was just added to) is resolved
+membership** (e.g. a `archive:<id>` the user was just added to) is resolved
 **server-side at connect** and unioned on top — so scope stays live, not frozen
 at mint time. Pass `syncGroups` only when you want to *narrow* below the default.
 
@@ -255,6 +257,9 @@ deny reads. Do not use scope roots as a tenant security boundary unless every
 model declares the matching policy. If that invariant is difficult to audit,
 use one organization per customer.
 
+For the complete key, backend-route, browser, lifecycle, and troubleshooting
+flow, see [Customer Organizations](./customer-organizations.md).
+
 The problem that creates: if each customer is a separate org, a naïve setup would
 make you re-push your schema into every new customer's org. You don't have to.
 Keep **one** project as the home of your schema. When its key mints into another
@@ -266,7 +271,7 @@ const ablo = Ablo({ schema, apiKey: process.env.ABLO_PLATFORM_KEY });
 const { token } = await ablo.sessions.create({
   user: { id: userId },
   organizationId, // DATA → this customer's isolated org
-  can: { tasks: ['read', 'update'] },
+  can: { records: ['read', 'update'] },
   ttlSeconds: 3600,
 });
 ```
@@ -281,8 +286,8 @@ plane (connection + row-level isolation) stays the customer's. A shared schema
 can't leak data across orgs.
 
 <Note>
-This requires a platform `sk_` carrying the `ephemeral:mint-any-org` scope —
-only a trusted platform key can mint a session into another org. Omit
+This requires a dedicated `sk_` carrying the `ephemeral:mint-any-org` scope —
+only a trusted cross-organization key can mint a session into another org. Omit
 `organizationId` and you get the default above: one project, one schema, all
 your users in the key's own organization.
 </Note>

package/docs/webhooks.md

@@ -39,7 +39,7 @@ Every delivery is a batch of events. Each event:
 
 | field | meaning |
 |---|---|
-| `type` | `"<model>.<verb>"` with the model name lowercased, e.g. `task.updated` |
+| `type` | `"<model>.<verb>"` with the model name lowercased, e.g. `record.updated` |
 | `model` | the model name exactly as declared in your schema: the table to write |
 | `objectId` | the changed row's id |
 | `data` | the post-change row, or `null` on delete |
@@ -127,7 +127,7 @@ Scope which models fire and label the endpoint at creation with `--events` and
 
 ```bash
 npx ablo webhooks create https://yourapp.com/api/ablo/[...all] \
-  --events task,project --description "prod mirror"
+  --events record,project --description "prod mirror"
 ```
 
 Manage and inspect endpoints:

package/examples/README.md

@@ -30,13 +30,13 @@ For read-reason-write work, pass the exact returned rows that informed the
 decision. Their watermarks stay opaque:
 
 ```ts
-const task = await ablo.tasks.get({ id: taskId });
+const record = await ablo.records.get({ id: recordId });
 const policy = await ablo.policies.get({ id: policyId });
-const result = await model({ task, policy });
-await ablo.tasks.update({
-  id: task.id,
+const result = await model({ record, policy });
+await ablo.records.update({
+  id: record.id,
   data: result,
-  reads: [task, policy],
+  reads: [record, policy],
 });
 ```
 
@@ -61,7 +61,7 @@ root and a bare `quickstart.ts` won't be found.
 ```bash
 cd packages/ablo
 ABLO_API_KEY=sk_... npx tsx examples/quickstart.ts
-ABLO_API_KEY=sk_... TASK_ID=task_... npx tsx examples/agent-turn.ts
+ABLO_API_KEY=sk_... RECORD_ID=record_... npx tsx examples/agent-turn.ts
 ABLO_API_KEY=sk_... JOB_ID=job_... npx tsx examples/expensive-agent-turn.ts
 ```
 

package/examples/agent-turn.ts

@@ -2,36 +2,36 @@
  * Canonical cheap turn: explicitly attach the exact rows used to decide the
  * write. Ablo keeps their watermarks opaque and checks them at commit time.
  *
- * Run: ABLO_API_KEY=sk_... TASK_ID=task_... npx tsx examples/agent-turn.ts
+ * Run: ABLO_API_KEY=sk_... RECORD_ID=record_... npx tsx examples/agent-turn.ts
  */
 import { Ablo } from '@abloatai/ablo';
 import { defineSchema, model, z } from '@abloatai/ablo/schema';
 
 const schema = defineSchema({
-  tasks: model({
+  records: model({
     title: z.string(),
     status: z.enum(['pending', 'done']),
     result: z.string().optional(),
   }),
 });
 
-const taskId = process.env.TASK_ID;
-if (!taskId) throw new Error('TASK_ID is required');
+const recordId = process.env.RECORD_ID;
+if (!recordId) throw new Error('RECORD_ID is required');
 
 const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
 try {
   await ablo.ready();
-  const task = await ablo.tasks.get({ id: taskId });
-  if (!task) throw new Error(`Task ${taskId} was not found`);
-  const commitId = `task:${taskId}:cheap`;
-  await ablo.tasks.update({
-    id: task.id,
-    data: { status: 'done', result: `Completed: ${task.title}` },
-    reads: [task],
+  const record = await ablo.records.get({ id: recordId });
+  if (!record) throw new Error(`Record ${recordId} was not found`);
+  const commitId = `record:${recordId}:cheap`;
+  await ablo.records.update({
+    id: record.id,
+    data: { status: 'done', result: `Completed: ${record.title}` },
+    reads: [record],
     idempotencyKey: commitId,
   });
-  const record = await ablo.commits.get({ id: commitId });
-  console.log({ identity: ablo.identity, commit: record });
+  const commit = await ablo.commits.get({ id: commitId });
+  console.log({ identity: ablo.identity, commit });
 } finally {
   await ablo.dispose();
 }

package/examples/data-source/README.md

@@ -93,9 +93,9 @@ createServer(async (req, res) => {
 Replace the `Map`-based store in `customer-server.ts` with your real
 data layer. The handler shape stays the same:
 
-- `tasks.load({ id })` -> `db.task.findUnique({ where: { id } })`
-- `tasks.list({ query })` -> `db.task.findMany({ take, cursor })`
-- `tasks.commit({ operations, clientTxId })` -> `db.$transaction` that
+- `records.load({ id })` -> `db.record.findUnique({ where: { id } })`
+- `records.list({ query })` -> `db.record.findMany({ take, cursor })`
+- `records.commit({ operations, clientTxId })` -> `db.$transaction` that
   applies each `op` and writes an outbox marker with `clientTxId` before commit
 - `events({ cursor, limit })` -> read from your outbox table, return
   rows with their `clientTxId` (Ablo dedupes its own commits) and the

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

@@ -23,7 +23,7 @@ import {
 } from '@abloatai/ablo/source';
 import { schema } from './schema';
 
-type TaskRow = {
+type RecordRow = {
   id: string;
   title: string;
   status: 'todo' | 'doing' | 'done';
@@ -31,9 +31,9 @@ type TaskRow = {
 };
 
 // Stand-in for the customer's real database. Map keyed by row id.
-const taskStore = new Map<string, TaskRow>();
+const recordStore = new Map<string, RecordRow>();
 
-// Outbox table. In production this is a `tasks_outbox` Postgres table
+// Outbox table. In production this is a `records_outbox` Postgres table
 // populated in the same transaction as the app-row write. Ablo polls `events`
 // to fan out changes that bypassed Ablo, and to repair SDK-origin writes if
 // Ablo's immediate post-commit append failed.
@@ -41,8 +41,8 @@ const outbox: SourceEvent[] = [];
 let outboxSequence = 0;
 
 // Seed one row so the example's first `load` returns something.
-taskStore.set('task_seed', {
-  id: 'task_seed',
+recordStore.set('record_seed', {
+  id: 'record_seed',
   title: 'Seeded by customer database',
   status: 'todo',
 });
@@ -91,13 +91,13 @@ export const handleAbloSource = dataSource({
     return {};
   },
 
-  tasks: {
+  records: {
     load({ id }) {
-      return taskStore.get(id) ?? null;
+      return recordStore.get(id) ?? null;
     },
 
     list({ query }) {
-      const all = Array.from(taskStore.values());
+      const all = Array.from(recordStore.values());
       const start = query.cursor ? Number(query.cursor) : 0;
       const limit = query.limit ?? 50;
       const page = all.slice(start, start + limit);
@@ -115,7 +115,7 @@ export const handleAbloSource = dataSource({
     // update; the surrounding `apply` helper shows where you would
     // open `db.transaction(async (tx) => { ... })`.
     commit({ operations, clientTxId }) {
-      const rows: TaskRow[] = [];
+      const rows: RecordRow[] = [];
       for (const op of operations) {
         const row = applyOperation(op, clientTxId);
         if (row) rows.push(row);
@@ -145,38 +145,38 @@ export const handleAbloSource = dataSource({
 function applyOperation(
   op: SourceOperation,
   clientTxId: string | undefined,
-): TaskRow | null {
-  if (op.model !== 'tasks') return null;
-  const id = op.id ?? `task_${Math.random().toString(36).slice(2, 10)}`;
+): RecordRow | null {
+  if (op.model !== 'records') return null;
+  const id = op.id ?? `record_${Math.random().toString(36).slice(2, 10)}`;
 
   if (op.type === 'CREATE') {
-    const row: TaskRow = {
+    const row: RecordRow = {
       id,
       title: String(op.input?.title ?? ''),
       status:
-        (op.input?.status as TaskRow['status'] | undefined) ?? 'todo',
+        (op.input?.status as RecordRow['status'] | undefined) ?? 'todo',
       ...(op.input?.assignee
         ? { assignee: String(op.input.assignee) }
         : {}),
     };
-    taskStore.set(id, row);
+    recordStore.set(id, row);
     appendOutbox({ operation: op, entityId: id, data: row, clientTxId });
     return row;
   }
 
   if (op.type === 'UPDATE') {
-    const existing = taskStore.get(id);
+    const existing = recordStore.get(id);
     if (!existing) return null;
-    const next: TaskRow = { ...existing, ...(op.input as Partial<TaskRow>) };
-    taskStore.set(id, next);
+    const next: RecordRow = { ...existing, ...(op.input as Partial<RecordRow>) };
+    recordStore.set(id, next);
     appendOutbox({ operation: op, entityId: id, data: next, clientTxId });
     return next;
   }
 
   if (op.type === 'DELETE') {
-    const existing = taskStore.get(id);
+    const existing = recordStore.get(id);
     if (!existing) return null;
-    taskStore.delete(id);
+    recordStore.delete(id);
     appendOutbox({ operation: op, entityId: id, data: null, clientTxId });
     return existing;
   }
@@ -187,7 +187,7 @@ function applyOperation(
 function appendOutbox(input: {
   operation: SourceOperation;
   entityId: string;
-  data: TaskRow | null;
+  data: RecordRow | null;
   clientTxId: string | undefined;
 }): void {
   outboxSequence += 1;
@@ -205,11 +205,11 @@ function appendOutbox(input: {
 // Exposed for the orchestrator's `run.ts`. A real customer doesn't
 // need this — it's a back door for the demo to verify state.
 export function _inspectStore(): {
-  rows: TaskRow[];
+  rows: RecordRow[];
   outboxSize: number;
 } {
   return {
-    rows: Array.from(taskStore.values()),
+    rows: Array.from(recordStore.values()),
     outboxSize: outbox.length,
   };
 }

package/examples/data-source/run.ts

@@ -36,7 +36,7 @@ async function main() {
   });
 
   log('--- 1. load (existing seeded row) ---');
-  const seeded = await driver.load('tasks', 'task_seed');
+  const seeded = await driver.load('records', 'record_seed');
   log('loaded:', seeded);
 
   log('\n--- 2. commit (CREATE + UPDATE in one batch) ---');
@@ -44,14 +44,14 @@ async function main() {
     [
       {
         type: 'CREATE',
-        model: 'tasks',
-        id: 'task_new',
+        model: 'records',
+        id: 'record_new',
         input: { title: 'Wire the data source', status: 'todo' },
       },
       {
         type: 'UPDATE',
-        model: 'tasks',
-        id: 'task_seed',
+        model: 'records',
+        id: 'record_seed',
         input: { status: 'doing', assignee: 'alice' },
       },
     ],
@@ -59,8 +59,8 @@ async function main() {
   );
   log('committed rows:', committed);
 
-  log('\n--- 3. list (all tasks after commit) ---');
-  const listed = await driver.list('tasks');
+  log('\n--- 3. list (all records after commit) ---');
+  const listed = await driver.list('records');
   log('listed:', listed);
 
   log('\n--- 4. events (outbox feed for cross-channel writes) ---');
@@ -73,7 +73,7 @@ async function main() {
     apiKey: 'sk_wrong_example_key',
   });
   try {
-    await badDriver.load('tasks', 'task_seed');
+    await badDriver.load('records', 'record_seed');
     throw new Error('expected signature failure');
   } catch (err) {
     log('rejected as expected:', (err as Error).message);

package/examples/data-source/schema.ts

@@ -3,7 +3,7 @@
  *
  * The schema is the contract between three sides:
  *
- *   1. The application UI — `ablo.tasks.update(...)`.
+ *   1. The application UI — `ablo.records.update(...)`.
  *   2. The Ablo Cloud — translates writes into signed POSTs.
  *   3. The customer's Data Source endpoint — applies them to its own
  *      database.
@@ -15,7 +15,7 @@
 import { defineSchema, model, z } from '@abloatai/ablo/schema';
 
 export const schema = defineSchema({
-  tasks: model({
+  records: model({
     title: z.string(),
     status: z.enum(['todo', 'doing', 'done']),
     assignee: z.string().optional(),

package/examples/lease-outlives-the-machine.ts

@@ -0,0 +1,66 @@
+/**
+ * A lease outlives the process that took it.
+ *
+ * Run in two terminals against your own project. The `holder` takes a claim
+ * and is killed without releasing it, exactly as a sandbox that is torn down
+ * mid-turn would be. The `successor`, already queued, is granted the claim when
+ * the lease lapses and reads the row as it stands then.
+ *
+ * Terminal 1: ABLO_API_KEY=sk_... JOB_ID=job_... npx tsx examples/lease-outlives-the-machine.ts holder
+ * Terminal 2: ABLO_API_KEY=sk_... JOB_ID=job_... npx tsx examples/lease-outlives-the-machine.ts successor
+ *
+ * Start the successor first, then the holder, so the queue is populated before
+ * the lease lapses.
+ */
+import { Ablo } from '@abloatai/ablo';
+import { defineSchema, model, z } from '@abloatai/ablo/schema';
+
+const schema = defineSchema({
+  jobs: model({
+    prompt: z.string(),
+    status: z.enum(['pending', 'complete']),
+    answer: z.string().optional(),
+  }),
+});
+
+const role = process.argv[2];
+if (role !== 'holder' && role !== 'successor') {
+  throw new Error('Pass "holder" or "successor" as the first argument');
+}
+
+const jobId = process.env.JOB_ID;
+if (!jobId) throw new Error('JOB_ID is required');
+
+const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
+await ablo.ready();
+
+if (role === 'holder') {
+  // A short TTL and no heartbeat: this process takes the lease and then stops
+  // proving it is alive, which is what a machine that disappears looks like
+  // from the server's side.
+  const claim = await ablo.jobs.claim({
+    id: jobId,
+    description: 'drafting the summary',
+    ttl: '10s',
+  });
+  console.log('holder: lease taken, status is', claim.data.status);
+  console.log('holder: exiting without releasing it');
+  // Deliberately skip release and skip dispose. `process.exit` runs no
+  // cleanup, so the server never hears from this participant again.
+  process.exit(0);
+}
+
+console.log('successor: queueing behind whoever holds the lease');
+const started = Date.now();
+await using claim = await ablo.jobs.claim({
+  id: jobId,
+  description: 'taking over the draft',
+  ttl: '30s',
+  heartbeat: { every: '10s' },
+});
+console.log(`successor: granted after ${Math.round((Date.now() - started) / 1000)}s`);
+console.log('successor: read the row as it stands now —', {
+  status: claim.data.status,
+  answer: claim.data.answer,
+});
+await ablo.dispose();

package/examples/tsconfig.json

@@ -1,16 +1,10 @@
 {
+  "extends": "../tsconfig.json",
   "compilerOptions": {
-    "target": "ES2022",
-    "module": "ESNext",
-    "moduleResolution": "bundler",
-    "lib": ["ES2022", "DOM"],
-    "strict": true,
     "noEmit": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "forceConsistentCasingInFileNames": true,
-    "types": ["node"]
+    "rootDir": "..",
+    "lib": ["ES2022", "ESNext.Disposable"]
   },
   "include": ["**/*.ts"],
-  "exclude": ["node_modules"]
+  "exclude": ["node_modules", "dist"]
 }

package/llms.txt

@@ -85,6 +85,17 @@ second verb to learn — `local.` is the only difference. The query reads accept
 and `state`; state defaults to `'live'`, with `'archived'` and `'all'` to include
 retired rows.
 
+`where` takes operators, not only equality: an array value is an `IN`
+(`{ status: ['draft', 'review'] }`), and tuple form spells the rest out
+(`[['title', 'ILIKE', '%storm%'], ['createdAt', '>=', cutoff]]`). Clauses combine
+with AND; for OR, run two reads and union them.
+
+`list` returns a page, not always the whole collection. The result is an array,
+so it maps and iterates as usual, and it carries `hasMore` and `nextCursor`
+beside the rows. Pass `nextCursor` back as `cursor`, keeping `where` and
+`orderBy` the same, to walk the rest. Check `hasMore` before treating a result
+as complete.
+
 Workers import the same app schema and select `transport: 'http'`. The transport
 changes; the typed `ablo.<model>` contract does not. There is no public
 schema-less or string-keyed model client.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/ablo",
-  "version": "0.51.0",
+  "version": "0.53.0",
   "description": "The public Ablo SDK for coordinated reads, commits, claims, observation, and reactive applications.",
   "license": "Apache-2.0",
   "type": "module",
@@ -112,7 +112,7 @@
     "prepack": "npm run build && node scripts/strip-source-condition.mjs",
     "postpack": "node scripts/restore-source-condition.mjs",
     "pack:check": "node scripts/pack-check.mjs",
-    "typecheck": "tsc --noEmit && tsc -p typetests/tsconfig.json",
+    "typecheck": "tsc --noEmit && tsc -p typetests/tsconfig.json && tsc -p examples/tsconfig.json",
     "test": "vitest run",
     "generate:errors": "tsx scripts/generate-error-docs.mts",
     "lint:errors": "tsx scripts/check-error-docs.mts",
@@ -137,8 +137,8 @@
     "directory": "packages/ablo"
   },
   "dependencies": {
-    "@abloatai/humans": "^0.51.0",
-    "@abloatai/transaction": "^0.51.0",
+    "@abloatai/humans": "^0.53.0",
+    "@abloatai/transaction": "^0.53.0",
     "zod": "^4.4.3"
   },
   "peerDependencies": {