@abloatai/ablo 0.51.0 → 0.52.0

package/AGENTS.md

@@ -90,7 +90,7 @@ Claims live on a callable namespace beside `create` / `update` / `get`. Every me
 Keep admission behavior together for anything beyond the default wait:
 
 ```ts
-const claim = await ablo.tasks.claim({
+const claim = await ablo.records.claim({
   id,
   contention: {
     mode: 'skip', // use 'wait' with maxDepth / timeoutMs when waiting is useful

package/CHANGELOG.md

@@ -1,23 +1,93 @@
 # Changelog
 
+## 0.52.0
+
+### Models carry only `id`
+
+`createdAt`, `updatedAt`, `organizationId`, and `createdBy` are no longer added
+to every model. Declare them as ordinary fields wherever you want them, and
+declare them to keep reading and writing them if you relied on Ablo supplying
+them. Ablo still records who made each change in its own transaction log, and
+still owns the tenancy value on every write.
+
+A model can point at a table Ablo did not create, naming the columns that
+differ:
+
+```ts
+import { defineSchema, field, model } from '@abloatai/ablo/schema';
+
+export const schema = defineSchema({
+  itemEvents: model(
+    {
+      itemId: field.string().from('item_id'),
+      createdAt: field.number().from('created_at'),
+    },
+    { tableName: 'item_events' }
+  ),
+});
+```
+
+Database adapters accept identifiers the database generates and return them as
+canonical string ids, taking the id type from the connection rather than from
+the model.
+
+### Updates can carry a precondition
+
+An update operation accepts `where`. The database changes the row only while its
+current values still match. On a mismatch the commit fails with
+`precondition_failed` and the whole batch declines, leaving every operation in it
+unapplied. The Kysely source adapter supports preconditions; the Drizzle,
+Prisma, and memory adapters report `source_adapter_misconfigured`.
+
+### Commit receipts return the rows the database wrote
+
+Receipts carry `operationResults`, pairing each operation's `transactionId` with
+its outcome and the authoritative row the database transaction returned,
+including identifiers and timestamps the database generated.
+
+### Two error codes renamed
+
+`task_id_missing` is now `item_id_missing`, and `task_id_required` is now
+`item_id_required`. Neither old code was ever returned by a request, so a caller
+matching on error codes has nothing to change unless it names one directly.
+
+### CLI
+
+`ablo setup` reads the repository and the current Ablo target, then prints the
+decisions, actions, blockers, and postconditions a verified setup requires. It
+reports and leaves the project untouched.
+
+`ablo init --plan` shows every file action before any of it happens.
+
+`ablo telemetry` controls limited CLI usage analytics. Collection is on by
+default and stays off in continuous integration and whenever `DO_NOT_TRACK=1` or
+`ABLO_TELEMETRY_DISABLED=1` is set. Run `ablo telemetry status` to see the
+current state, `ablo telemetry disable` to turn collection off, and
+`ablo telemetry reset` to rotate the local installation identity.
+
 ## 0.51.0
 
-### Minor Changes
+### One platform schema can serve every customer organization
 
-- 3a25ab4: Default cross-organization user sessions to the platform key's schema project.
-  Customer data remains isolated in the target organization, while one pushed
-  schema can describe every customer tenant. `sessions.create` also accepts an
-  explicit `schemaProject` override for migrations and advanced routing.
+Platforms no longer need to copy the same schema into every customer
+organization. When a platform key creates a session for another organization,
+Ablo now reads the schema from the platform's project while keeping every row
+inside the customer's organization.
 
-  The sessions guide now distinguishes policy-scoped customers from structurally
-  isolated customer organizations and makes clear that sync-group routing is not
-  read authorization.
+```ts
+const { token } = await ablo.sessions.create({
+  user: { id: userId },
+  organizationId: customerOrganizationId,
+  can: { records: ['read', 'update'] },
+});
+```
 
-### Patch Changes
+Most platforms need no schema option at all. Migrations and advanced routing can
+still select one explicitly with `schemaProject`.
 
-- Updated dependencies [3a25ab4]
-  - @abloatai/transaction@0.51.0
-  - @abloatai/humans@0.51.0
+The sessions guide now draws a firm line between policy-scoped customers and
+separate customer organizations. Sync groups decide which changes travel; they
+do not authorize reads.
 
 ## 0.50.0
 
@@ -31,14 +101,14 @@ and carries exact Ablo rows into `ctx.reads` for the write that follows.
 const ctx = await context({
   ablo,
   data: {
-    task: ablo.tasks.get({ id: taskId }),
-    documents: ablo.documents.list({ where: { taskId } }),
-    memory: loadMemories(taskId),
+    record: ablo.records.get({ id: recordId }),
+    records: ablo.records.list({ where: { recordId } }),
+    memory: loadMemories(recordId),
   },
 });
 
-await ablo.tasks.update({
-  id: taskId,
+await ablo.records.update({
+  id: recordId,
   data: result,
   reads: ctx.reads,
 });
@@ -64,11 +134,11 @@ write lands anyway, on top of a decision that is no longer true. Pass the rows
 the decision was based on:
 
 ```ts
-const task = await ablo.tasks.get({ id: taskId });
-await ablo.tasks.update({
-  id: task.id,
-  data: { status: 'done', result: `Completed: ${task.title}` },
-  reads: [task],
+const record = await ablo.records.get({ id: recordId });
+await ablo.records.update({
+  id: record.id,
+  data: { status: 'done', result: `Completed: ${record.title}` },
+  reads: [record],
 });
 ```
 
@@ -89,7 +159,7 @@ turn or skips, expires on its own, and keeps itself alive with a heartbeat while
 the agent works.
 
 If an agent loses its claim during a model call, its final write is refused. Two
-agents cannot both believe they own the same task and both write, and a slow
+agents cannot both believe they own the same record and both write, and a slow
 agent cannot land its answer on top of whoever picked the work up after it. Ablo
 decides who holds the claim, so an agent cannot assert one it does not have.
 
@@ -114,7 +184,7 @@ database you connected.
 
 An agent holding a key can now ask what that key permits and get the answer from
 Ablo, whether it keeps a connection open or calls over HTTP for a single turn.
-An agent that mints a narrower key for a sub-task can confirm what it handed
+An agent that mints a narrower key for a sub-record can confirm what it handed
 over.
 
 ### A refused action says which permission was missing
@@ -307,7 +377,7 @@ New clients can pin their intended project and branch with `projectId` /
 `ABLO_PROJECT_ID` and `branchId` / `ABLO_BRANCH_ID`. `ablo dev` writes both
 immutable coordinates beside its branch-bound key, and `ready()` compares them
 with the key's server-resolved target before opening the sync connection. A mail
-deployment carrying a slides key now fails with `project_scope_denied`; a
+deployment carrying an unrelated key now fails with `project_scope_denied`; a
 same-project key for the wrong environment fails with `branch_scope_denied`.
 
 ### Pre-existing rows arrive on their own
@@ -350,7 +420,7 @@ end-to-end regression pins the behavior.
 The new `contention` option names what happens when the row is already held:
 
 ```ts
-const claim = await ablo.tasks.claim({
+const claim = await ablo.records.claim({
   id,
   contention: {
     mode: 'skip',

package/NOTICE

@@ -2,7 +2,7 @@
 Copyright 2025-2026 Lukas Andersson
 
 This product includes software developed by Lukas Andersson
-(https://ablo.finance).
+(https://abloatai.com).
 
 "Ablo" is a trademark of Lukas Andersson. This license does not grant
 permission to use the Ablo name, logo, or trademarks. Third parties

package/docs/agents.md

@@ -14,8 +14,8 @@ plugin — get the live plane (WebSocket: presence, optimistic, sub-100ms).
 other*.**
 
 <Note>
-Agents transact against your **pushed schema**, same as everyone — `ablo.tasks`
-exists because you defined a `task` model and ran `ablo push`. The key
+Agents transact against your **pushed schema**, same as everyone — `ablo.records`
+exists because you defined a `record` model and ran `ablo push`. The key
 authenticates; the [schema](/quickstart) defines what you can call.
 </Note>
 
@@ -32,13 +32,13 @@ const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY, transport: "http"
 
 // Reads + writes, fully typed off your schema.
 // `get` resolves to the row, or `undefined` when none matches.
-const open = await ablo.tasks.list({ where: { status: "todo" } });
+const open = await ablo.records.list({ where: { status: "todo" } });
 
-const task = await ablo.tasks.get({ id: open[0].id });
-if (!task) throw new Error("task not found");
+const record = await ablo.records.get({ id: open[0].id });
+if (!record) throw new Error("record not found");
 
-console.log(task.title);
-await ablo.tasks.update({ id: task.id, data: { status: "done" } });
+console.log(record.title);
+await ablo.records.update({ id: record.id, data: { status: "done" } });
 ```
 
 It exposes `get` / `list` / `create` / `update` / `delete`, plus `commits`
@@ -61,27 +61,27 @@ import {
 } from '@abloatai/ablo/ai-sdk';
 
 const tools = {
-  getTask: readTool(ablo.tasks, {
-    description: 'Read the current task.',
-    inputSchema: z.object({ taskId: z.string() }),
-    id: ({ taskId }) => taskId,
+  getTask: readTool(ablo.records, {
+    description: 'Read the current record.',
+    inputSchema: z.object({ recordId: z.string() }),
+    id: ({ recordId }) => recordId,
   }),
-  createTask: createTool(ablo.tasks, {
-    description: 'Create a task.',
+  createTask: createTool(ablo.records, {
+    description: 'Create a record.',
     inputSchema: z.object({ requestId: z.string(), title: z.string() }),
     id: ({ requestId }) => requestId,
     data: ({ title }) => ({ title, status: 'todo' }),
   }),
-  updateTask: updateTool(ablo.tasks, {
-    description: 'Update a task without overwriting concurrent work.',
-    inputSchema: z.object({ taskId: z.string(), status: z.string() }),
-    id: ({ taskId }) => taskId,
+  updateTask: updateTool(ablo.records, {
+    description: 'Update a record without overwriting concurrent work.',
+    inputSchema: z.object({ recordId: z.string(), status: z.string() }),
+    id: ({ recordId }) => recordId,
     apply: (_current, { status }) => ({ status }),
   }),
-  deleteTask: deleteTool(ablo.tasks, {
-    description: 'Delete a task after taking its claim.',
-    inputSchema: z.object({ taskId: z.string() }),
-    id: ({ taskId }) => taskId,
+  deleteTask: deleteTool(ablo.records, {
+    description: 'Delete a record after taking its claim.',
+    inputSchema: z.object({ recordId: z.string() }),
+    id: ({ recordId }) => recordId,
     // Destructive tools require AI SDK approval by default.
   }),
 };
@@ -102,18 +102,18 @@ clobber the same record.
 
 ```ts
 // Acquire a lease, do work with the held row, release on scope exit:
-await using claim = await ablo.tasks.claim({ id: taskId });
-const task = claim.data;
+await using claim = await ablo.records.claim({ id: recordId });
+const record = claim.data;
 // …no one else can hold this row while you work…
-await ablo.tasks.update({
-  id: task.id,
+await ablo.records.update({
+  id: record.id,
   data: { status: "in_review" },
   claim,
 });
 
-await ablo.tasks.claim.state({ id: taskId });   // who holds it now (or null)
-await ablo.tasks.claim.queue({ id: taskId });   // the FIFO wait-line behind the holder
-await ablo.tasks.claim.reorder({ id: taskId, order: line }); // re-rank the line (privileged)
+await ablo.records.claim.state({ id: recordId });   // who holds it now (or null)
+await ablo.records.claim.queue({ id: recordId });   // the FIFO wait-line behind the holder
+await ablo.records.claim.reorder({ id: recordId, order: line }); // re-rank the line (privileged)
 ```
 
 Think of it as a queue per row — a durable, inspectable, reorderable lease

package/docs/api-keys.md

@@ -119,9 +119,9 @@ knobs, and you set exactly one.
 
 | Mint | Call | Result |
 |---|---|---|
-| Human end-user session | `await server.sessions.create({ user: { id }, can: { tasks: ['read'] } })` | `ek_` (scoped to `can`) |
-| Ready agent client | `await server.agents.create({ can: { tasks: ['update'] } })` | Auto-refreshing client scoped to `can` |
-| Raw delegated agent token | `await server.sessions.create({ agent: { id }, can: { tasks: ['update'] } })` | `rk_` for another runtime |
+| Human end-user session | `await server.sessions.create({ user: { id }, can: { records: ['read'] } })` | `ek_` (scoped to `can`) |
+| Ready agent client | `await server.agents.create({ can: { records: ['update'] } })` | Auto-refreshing client scoped to `can` |
+| Raw delegated agent token | `await server.sessions.create({ agent: { id }, can: { records: ['update'] } })` | `rk_` for another runtime |
 
 The principal kind comes from *which* shape you pass — `{ user, can }` → `user`, `{ agent, can }` → `agent`.
 
@@ -217,6 +217,12 @@ restricted to exactly those grants:
 - `project:manage` — list, create, and rename projects.
 - `branch:manage` — list, create, and delete child branches and mint their
   temporary credentials.
+- `ephemeral:mint-any-org` — cross-organization authority to mint a short-lived
+  user session into a customer organization. It follows the Stripe Connect shape:
+  the request names the customer organization, but the resulting session is
+  still bounded by its `can` grant and expiry. A key restricted to this scope
+  cannot directly read or write customer organizations' rows, push schema, or
+  manage projects.
 
 Both management scopes are explicit grants on `mk_` credentials. Runtime
 `sk_`, `rk_`, `pk_`, and `ek_` credentials cannot become management
@@ -226,6 +232,27 @@ Branch binding remains an authority boundary even when a key has no granular
 scope strings: a temporary child key can act only inside that child. It cannot
 manage siblings or gain root authority.
 
+### Cross-organization mint keys
+
+Most applications do not need `ephemeral:mint-any-org`: their backend key mints
+users into its own organization. A multi-organization backend needs it only
+when each customer is a separate Ablo organization and one trusted service
+mints sessions for all of them.
+
+Treat that key as a dedicated minting credential:
+
+- keep it in a server-side secret manager, never a browser or repository;
+- grant only `ephemeral:mint-any-org`, with no data or schema scopes;
+- mint short-lived sessions with the smallest typed `can` grant;
+- rotate it on a schedule and revoke it immediately after suspected exposure;
+- log the target `organizationId`, minted session id, and request id for audit.
+
+The scope's broad name describes the cross-organization check it passes, not
+the authority of each resulting session. The session can act only inside the
+named customer organization and only for the models/verbs in `can`. See
+[Customer Organizations](./customer-organizations.md) for the complete
+integration.
+
 ## Current and legacy key spellings
 
 New credentials use one spelling per capability class:

package/docs/api.md

@@ -173,7 +173,7 @@ The SDK is a convenience wrapper over a model-scoped HTTP surface — the same
 noun (`model`) and verbs as `ablo.<model>.…`. Non-JS callers (or curl) use it
 directly. The table below shows the shape with `{model}` as a placeholder; the
 [OpenAPI spec](./openapi.json) expands it into one **typed** path per model
-(`/api/v1/models/task`, `/api/v1/models/workspace`, …, generated from your schema) so each
+(`/api/v1/models/record`, `/api/v1/models/workspace`, …, generated from your schema) so each
 endpoint documents that model's real field contract instead of a generic blob.
 
 | SDK call | HTTP |

package/docs/cli.md

@@ -189,7 +189,7 @@ streams production. You never pass a project or branch. Follows by default;
 
 ```bash
 npx ablo logs                      # last 50, then stream
-npx ablo logs -n 100 --model task  # backfill 100, one model
+npx ablo logs -n 100 --model record  # backfill 100, one model
 npx ablo logs --since 15m --json   # last 15m as NDJSON, then stream
 ```
 
@@ -237,7 +237,7 @@ DATABASE_URL=postgres://… npx ablo check
 ```
 
 ```text
-  ✓ tasks     → tasks (id, organization_id ok)
+  ✓ records     → records (id, organization_id ok)
   ✗ projects  → projects
       • missing "organization_id" — add it, or move this model behind a Data Source
   2 models · 1 ok · 1 error
@@ -308,7 +308,7 @@ that broke and the Postgres SQLSTATE, not just "migration failed".
 ```txt
 [migrate] migration plan failed {
   code: 'migration_failed',
-  failedStatement: 'ALTER TABLE "public"."tasks" RENAME COLUMN a TO b;',
+  failedStatement: 'ALTER TABLE "public"."records" RENAME COLUMN a TO b;',
   failedStatementIndex: 4,
   pgCode: '42P01',
   durationMs: 133

package/docs/concurrency-convention.md

@@ -13,7 +13,7 @@ you declared and nothing else.
 A plain write has no stale premise:
 
 ```ts
-await ablo.tasks.update({ id, data: { status: 'done' } });
+await ablo.records.update({ id, data: { status: 'done' } });
 ```
 
 If no active claim conflicts with it, the write is last-write-wins. That is a
@@ -26,14 +26,14 @@ once in its `conflict` setting instead of at every call site.
 Pass the exact returned rows when a write is based on values previously read:
 
 ```ts
-const task = await ablo.tasks.get({ id });
+const record = await ablo.records.get({ id });
 const policy = await ablo.policies.get({ id: policyId });
-if (!task || !policy) throw new Error('required input is missing');
+if (!record || !policy) throw new Error('required input is missing');
 
-await ablo.tasks.update({
-  id: task.id,
+await ablo.records.update({
+  id: record.id,
   data: { status: 'done' },
-  reads: [task, policy],
+  reads: [record, policy],
 });
 ```
 
@@ -83,7 +83,7 @@ See [Coordination](./coordination.md#claims) for the API.
 ## Cross-row and batch premises
 
 Model writes and lower-level commits can declare rows they read even when the
-write targets somewhere else. This protects decisions such as “update the task
+write targets somewhere else. This protects decisions such as “update the record
 only if the deal I inspected has not changed.” A stale batch premise applies to
 the whole batch so atomicity is preserved.
 

package/docs/context.md

@@ -21,13 +21,13 @@ import { generateText } from 'ai';
 const ctx = await context({
   ablo,
   data: {
-    task: ablo.tasks.get({ id: taskId }),
-    documents: ablo.documents.list({ where: { taskId } }),
-    memory: loadMemories(taskId),
+    record: ablo.records.get({ id: recordId }),
+    records: ablo.records.list({ where: { recordId } }),
+    memory: loadMemories(recordId),
   },
 });
 
-if (!ctx.data.task) throw new Error('Task not found');
+if (!ctx.data.record) throw new Error('Record not found');
 
 const result = await generateText({
   model,
@@ -35,8 +35,8 @@ const result = await generateText({
   tools,
 });
 
-await ablo.tasks.update({
-  id: ctx.data.task.id,
+await ablo.records.update({
+  id: ctx.data.record.id,
   data: parseTaskUpdate(result.text),
   reads: ctx.reads,
 });
@@ -80,7 +80,7 @@ This distinction is visible in `sources`:
 ```ts
 ctx.sources;
 // [
-//   { key: 'task', kind: 'ablo', guarantee: 'guardable', cursor: 42 },
+//   { key: 'record', kind: 'ablo', guarantee: 'guardable', cursor: 42 },
 //   { key: 'memory', kind: 'value', guarantee: 'informational', cursor: null },
 // ]
 ```
@@ -89,7 +89,7 @@ A top-level value may contain both kinds. It is then marked `mixed` and only
 its exact Ablo rows appear in `ctx.reads`:
 
 ```ts
-// data: { briefing: { task, memory } }
+// data: { briefing: { record, memory } }
 // sources: [
 //   { key: 'briefing', kind: 'mixed', guarantee: 'partial', cursor: 42 },
 // ]
@@ -108,10 +108,10 @@ Reducto, or another system behind their own interfaces.
 const ctx = await context({
   ablo,
   data: {
-    task: ablo.tasks.get({ id: taskId }),
+    record: ablo.records.get({ id: recordId }),
     memory: loadMemories({ query, userId }),
     related: findRelatedChunks({ projectId, query }),
-    evidence: extractEvidence({ documentId }),
+    evidence: extractEvidence({ recordId }),
   },
 });
 ```
@@ -141,7 +141,7 @@ await generateText({
   model,
   messages: [
     ...history,
-    contextMessage(ctx, { include: ['task', 'documents', 'memory'] }),
+    contextMessage(ctx, { include: ['record', 'documents', 'memory'] }),
   ],
   tools,
 });

package/docs/coordination.md

@@ -9,7 +9,7 @@ meaning. Choose the narrowest one that matches the operation.
 |---|---|---|
 | Set an independent value | `update({ id, data })` | Last-write-wins when no claim applies. |
 | Compute a value from the current row | `update(id, current => next)` | Re-reads and retries if the row changes concurrently. |
-| Write only if earlier rows are still current | `reads: [task, policy]` | Rejects when an explicitly named dependency changed. |
+| Write only if earlier rows are still current | `reads: [record, policy]` | Rejects when an explicitly named dependency changed. |
 | Read, call a model, then write | `claim({ id })` | Other participants cannot write the claimed target by default until your claim ends. |
 
 **If a model call sits between the read and the write, take a claim.** A stale
@@ -25,16 +25,16 @@ does not carry a stale premise. It is intentionally last-write-wins.
 Pass the exact rows that produced a decision on the write:
 
 ```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 });
-if (!task || !policy) throw new Error('required input is missing');
+if (!record || !policy) throw new Error('required input is missing');
 
-const result = await model({ task, policy });
+const result = await model({ record, policy });
 
-await ablo.tasks.update({
-  id: task.id,
+await ablo.records.update({
+  id: record.id,
   data: result,
-  reads: [task, policy],
+  reads: [record, policy],
 });
 ```
 
@@ -57,7 +57,7 @@ When the next value is a function of the current one, pass an updater rather
 than fixed data:
 
 ```ts
-const document = await ablo.documents.update(documentId, (current) => ({
+const document = await ablo.records.update(recordId, (current) => ({
   revision: current.revision + 1,
   content: revise(current.content),
 }));
@@ -75,8 +75,8 @@ effect inside it.
 You can bound or cancel reconciliation:
 
 ```ts
-await ablo.documents.update(
-  documentId,
+await ablo.records.update(
+  recordId,
   (current) => ({ revision: current.revision + 1 }),
   { retries: 8, signal: request.signal },
 );
@@ -184,8 +184,8 @@ protect the row version rather than a participant-held claim.
 For deduplicated jobs, skip work when another participant already owns it:
 
 ```ts
-const claim = await ablo.tasks.claim({
-  id: taskId,
+const claim = await ablo.records.claim({
+  id: recordId,
   contention: { mode: 'skip' },
 });
 
@@ -201,8 +201,8 @@ try {
 To wait with limits, keep the policy together:
 
 ```ts
-const claim = await ablo.tasks.claim({
-  id: taskId,
+const claim = await ablo.records.claim({
+  id: recordId,
   contention: {
     mode: 'wait',
     maxDepth: 3,
@@ -217,9 +217,9 @@ const claim = await ablo.tasks.claim({
 Narrow a claim when independent fields may be edited concurrently:
 
 ```ts
-await using claim = await ablo.tasks.claim({
-  id: taskId,
-  fields: (task) => task.status,
+await using claim = await ablo.records.claim({
+  id: recordId,
+  fields: (record) => record.status,
 });
 ```
 
@@ -239,8 +239,8 @@ The target options are:
 Read current claim state without blocking:
 
 ```ts
-const holder = ablo.tasks.claim.state({ id: taskId });
-const queue = ablo.tasks.claim.queue({ id: taskId });
+const holder = ablo.records.claim.state({ id: recordId });
+const queue = ablo.records.claim.queue({ id: recordId });
 ```
 
 Use this state for presence and progress UI. Do not use an observed `null` as a