@abloatai/ablo 0.29.3 → 0.30.1

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## 0.30.1
+
+### Patch Changes
+
+- **Writes land in your own database on a connected source.** Once you register a database with `ablo connect`, the models you already read from its replication stream become writable: `ablo.<model>.create`, `.update`, and `.delete` route through Ablo's commit chokepoint and into your database, with no connection string in the client. Coordination travels with the write — a claim you hold is checked at the chokepoint before the change is applied, so agents and people serialize on a row whether they reach it by reading from Ablo or by writing back to your own database.
+
+  A write resolves as soon as it is durably accepted, which the receipt reports as `queued`. Ask for the authoritative outcome with `wait: 'confirmed'` — Ablo watches the change actually land in your database (the write-ahead-log echo for a replicated source, or the event feed for a signed data-source endpoint) and promotes the receipt to `confirmed` before the call returns. The client call is identical across both connection shapes; only the feed Ablo watches for the confirmation differs.
+
+- **A clear readiness error when a model's table isn't provisioned yet.** Registering a schema with `ablo push` records your models, but a plane's physical tables are created separately, out of band — so a model can exist in the registered schema before its table does. Reading or writing such a model now returns a typed `model_not_provisioned` error (HTTP 409) that names the gap and points you at provisioning the plane's tables, rather than surfacing as an opaque failure.
+
+## 0.30.0
+
+### Minor Changes
+
+- **Removed the deprecated `databaseUrl` client option — your database connects to Ablo out of band, not through the client.** Ablo is Stripe-shaped: the client only ever talks to the engine. You construct it with `Ablo({ schema, apiKey })` (add `transport: 'http'` for a stateless server worker), and it reaches Ablo over WebSocket or HTTP — it never opens a Postgres connection itself. How your data connects is a separate step, set up once, in one of two shapes:
+
+  - **Logical replication — the default.** `ablo connect` registers your database and Ablo tails its write-ahead log. Your rows stay in your database; Ablo reads the change stream and keeps its own transaction log. Nothing in the client holds a connection string.
+  - **Signed data-source endpoint — the fallback.** For a database that cannot grant a `REPLICATION` role, your app exposes a signed HTTP endpoint that Ablo calls. Same out-of-band principle: the credentials live with your app, not in the Ablo client.
+
+  Because the client no longer carries a connection string, `ablo init` no longer scaffolds the `--storage direct` connector — the last surface that emitted `databaseUrl: process.env.DATABASE_URL` into a generated client. Run `ablo init --storage replication` (the default) or `--storage endpoint` instead.
+
+- **The claim work label is `description`, not `reason`.** A claim is an advisory coordination lock: you take it on a row before editing so other participants — agents or people — see the row is held and back off. The free-text label that says _what_ you are doing is now `description`, the text a peer reads when it hits a row you hold: `ablo.<model>.claim({ id, description: 'Renaming the task to match the brief' })`. The former `reason` option is removed with no alias, so a call still passing `reason` no longer type-checks — rename it to `description`. This is a different field from the `reason` on a claim _rejection_ or _lost_ event (`'conflict'`, `'expired'`, `'preempted'`), which says _why_ coordination denied or ended a claim and is unchanged.
+
+- **Claim a key Ablo hasn't synced: `ablo.<model>.claim(id)`.** Claims now come in two shapes that mirror whether Ablo holds the row. The object form `claim({ id })` loads the row from Ablo's synced pool and returns a `HeldClaim<T>` carrying `.data`. The new string overload `claim(id)` locks a row that lives _only_ in your own database — Ablo has never synced it — so it skips the pool load and the `entity_not_found` throw and returns a `HeldLease`: a `HeldClaim` without `.data`. This is Rung 0 of the connect ladder — advisory coordination with no replication grant, no schema change, and no `organization_id` column, so you can coordinate agents against your database before wiring any sync. `await using` auto-releases either shape at end of scope, and the object form is unchanged, so no existing caller shifts.
+
+### Patch Changes
+
+- **`ablo push` defers provisioning instead of failing when the plane's role cannot run DDL.** When the engine role bound to a plane lacks the privilege to create or alter tables, `push` no longer aborts the whole command. It records the schema and defers the provisioning step, so your models still register and the table changes are applied later by a role that can run them — rather than blocking the push on a privilege the plane may never grant the engine directly.
+
+- **Schema-drift no longer false-alarms for `selectModels` / `omitModels` projection clients.** A projected client deliberately carries a subset of the full schema, so its schema hash legitimately differs from the unprojected one. The drift check now compares against the projection's own source hash, so a correctly-projected app no longer sees a spurious drift warning at bootstrap.
+
 ## 0.29.3
 
 ### Patch Changes

package/README.md

@@ -250,7 +250,9 @@ await ablo.weatherReports.update({
 If someone else holds the row, `claim()` waits in a fair queue, then re-reads —
 so `report` is the current row, never a stale snapshot. Reads stay open by
 default; only acting on the row serializes. The claim releases when the `await
-using` scope exits.
+using` scope exits — on return, and on a throw. That "on throw" is why `await
+using` earns its keep: if the agent call fails before the write, the row frees
+for the next in line and stays exactly as it was, with no cleanup of your own.
 
 See who's mid-edit before you act — decide to wait, or skip:
 
@@ -482,7 +484,6 @@ Every other option has correct defaults:
 | --- | --- | --- | --- |
 | `schema` | `Schema` | — (required) | Typed model proxies (`ablo.<model>.*`) |
 | `apiKey` | `string \| ApiKeySetter \| null` | `process.env.ABLO_API_KEY` | Server key — a string, or an async function for rotation |
-| `databaseUrl` | `string \| null` | `—` | Deprecated. Connect via `npx ablo connect` instead — see [Connect Your Database](./docs/data-sources.md). |
 
 Keep `apiKey` in trusted server runtimes. In the browser, `<AbloProvider>`
 authenticates with the signed-in user's session; the raw-key path is gated

package/dist/BaseSyncedStore.js

@@ -1405,7 +1405,9 @@ export class BaseSyncedStore {
             get highestProcessedSyncId() { return store.highestProcessedSyncId; },
             get lastAckedId() { return store.lastAckedId; },
             // SyncClient position/transaction bookkeeping.
-            onDeltaReceived: (syncId) => { this.syncClient.onDeltaReceived(syncId); },
+            onDeltaReceived: (syncId, transactionId, correlationId) => {
+                this.syncClient.onDeltaReceived(syncId, transactionId, correlationId);
+            },
             advanceApplied: (syncId) => { this.syncClient.position.advanceApplied(syncId); },
             advancePersisted: (syncId) => { this.syncClient.position.advancePersisted(syncId); },
             // Persistence + pool writes.

package/dist/Database.js

@@ -34,6 +34,11 @@ function isSameOutboxRecord(existing, candidate) {
             request: record.request,
             scopeNamespace: record.scopeNamespace,
         });
+        if (existing.correlationId !== undefined &&
+            candidate.correlationId !== undefined &&
+            existing.correlationId !== candidate.correlationId) {
+            return false;
+        }
         return JSON.stringify(identity(existing)) === JSON.stringify(identity(candidate));
     }
     if (existing.type === 'commit_envelope' &&
@@ -49,10 +54,23 @@ function isSameOutboxRecord(existing, candidate) {
             commitOptions: record.commitOptions,
             scope: record.scope,
         });
+        if (existing.correlationId !== undefined &&
+            candidate.correlationId !== undefined &&
+            existing.correlationId !== candidate.correlationId) {
+            return false;
+        }
         return JSON.stringify(identity(existing)) === JSON.stringify(identity(candidate));
     }
     return JSON.stringify(existing) === JSON.stringify(candidate);
 }
+function isAcceptedOutboxPromotion(existing, candidate) {
+    return (existing !== undefined &&
+        (existing.type === 'commit_envelope' ||
+            existing.type === 'http_commit_envelope') &&
+        existing.type === candidate.type &&
+        existing.acceptedAt === undefined &&
+        candidate.acceptedAt !== undefined);
+}
 export class Database {
     // Core database components
     databaseManager;
@@ -1266,6 +1284,9 @@ export class Database {
                     code: 'idempotency_conflict',
                 });
             }
+            if (isAcceptedOutboxPromotion(existing, record)) {
+                await store.put(record);
+            }
             if (!existing) {
                 const sources = await Promise.all(consumedRecordIds.map((id) => store.get(id)));
                 if (sources.some((source) => source === undefined)) {
@@ -1321,8 +1342,12 @@ export class Database {
                         tx.abort();
                         return;
                     }
-                    if (!existing)
+                    if (!existing) {
                         store.add(record);
+                    }
+                    else if (isAcceptedOutboxPromotion(existing, record)) {
+                        store.put(record);
+                    }
                     for (const id of sourceIds)
                         store.delete(id);
                 };
@@ -1370,7 +1395,9 @@ export class Database {
             // idempotency retention may already have elapsed, so silently deleting or
             // blindly replaying an old envelope would both be unsafe. Restoration
             // owns quarantine/reconciliation for these records.
-            if (tx.type === 'commit_envelope' || tx.type === 'pending_mutation') {
+            if (tx.type === 'commit_envelope' ||
+                tx.type === 'http_commit_envelope' ||
+                tx.type === 'pending_mutation') {
                 continue;
             }
             if (typeof tx.timestamp === 'number' && tx.timestamp < cutoff) {

package/dist/SyncClient.d.ts

@@ -348,11 +348,13 @@ export declare class SyncClient extends EventEmitter {
     dispose(): void;
     /**
      * Notify the {@link TransactionQueue} of an incoming delta so it can confirm
-     * transactions by sync-id threshold. A transaction is confirmed once any
-     * delta with an id at or beyond its `lastSyncId` threshold arrives.
+     * hosted writes by sync-id threshold and queued forwards by their echoed
+     * source-batch correlation id.
      * @param syncId - The sync id of the received delta.
+     * @param transactionId - Optional server echo of the originating local write.
+     * @param correlationId - Opaque batch identity decoded from a source WAL echo.
      */
-    onDeltaReceived(syncId: number): void;
+    onDeltaReceived(syncId: number, transactionId?: string, correlationId?: string): void;
     /**
      * Cancel pending transactions for child entities orphaned by a parent's
      * deletion. The store calls this when a delete delta arrives for a parent,

package/dist/SyncClient.js

@@ -1664,17 +1664,21 @@ export class SyncClient extends EventEmitter {
     }
     /**
      * Notify the {@link TransactionQueue} of an incoming delta so it can confirm
-     * transactions by sync-id threshold. A transaction is confirmed once any
-     * delta with an id at or beyond its `lastSyncId` threshold arrives.
+     * hosted writes by sync-id threshold and queued forwards by their echoed
+     * source-batch correlation id.
      * @param syncId - The sync id of the received delta.
+     * @param transactionId - Optional server echo of the originating local write.
+     * @param correlationId - Opaque batch identity decoded from a source WAL echo.
      */
-    onDeltaReceived(syncId) {
+    onDeltaReceived(syncId, transactionId, correlationId) {
         try {
-            this.transactionQueue.onDeltaReceived(syncId);
+            this.transactionQueue.onDeltaReceived(syncId, transactionId, correlationId);
         }
         catch (e) {
             getContext().observability.breadcrumb('Failed to notify delta received', 'sync.transaction', 'warning', {
                 syncId,
+                transactionId,
+                correlationId,
             });
         }
     }

package/dist/ai-sdk/coordinatedTool.d.ts

@@ -96,7 +96,6 @@ export interface CoordinatedToolOptions<TInput, T> {
     strategy?: CoordinationStrategy;
     /** Human-readable coordination metadata attached to the claim, used by the `'claim'` and `'queue'` strategies. */
     claim?: {
-        reason?: string;
         description?: string;
     };
     /** How many reconcile rounds `'merge'` may take before it gives up with `AbloContentionError`. */

package/dist/ai-sdk/coordinatedTool.js

@@ -84,7 +84,6 @@ export function coordinatedTool(model, options) {
                 const claim = await model.claim({
                     id,
                     queue: false,
-                    reason: options.claim?.reason,
                     description: options.claim?.description,
                 });
                 try {

package/dist/ai-sdk/coordinationContext.js

@@ -79,20 +79,16 @@ function formatCoordinationNote(claims, target) {
     const entityLabel = target.type.toLowerCase();
     const c = claims.length === 1 ? claims[0] : undefined;
     if (c) {
-        const details = c.description ? `Declared work: ${c.description}. ` : '';
         return (`<multiplayer_context>\n` +
             `Another participant is currently editing this ${entityLabel}. ` +
-            `Action declared: ${c.reason}. ` +
-            details +
+            `Declared work: ${c.description}. ` +
             `Defer to their concurrent changes when reasonable, or note your work as complementary to theirs. ` +
             `Avoid stomping their in-flight edits.\n` +
             `</multiplayer_context>`);
     }
-    const actions = Array.from(new Set(claims.map((c) => c.reason))).join(', ');
     const descriptions = Array.from(new Set(claims.map((c) => c.description).filter(Boolean))).join('; ');
     return (`<multiplayer_context>\n` +
         `${claims.length} other participants are currently editing this ${entityLabel}. ` +
-        `Active actions: ${actions}. ` +
         (descriptions ? `Declared work: ${descriptions}. ` : '') +
         `Coordinate with their in-flight work — defer where reasonable, ` +
         `or describe your work as complementary.\n` +