@abloatai/ablo 0.9.3 → 0.9.4

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.9.4
+
+### Patch Changes
+
+- Sync-position correctness + CLI hardening. Consolidate five scattered sync cursors into one typed `syncPosition` (persisted/applied/acked with a derived `readFloor`), fixing a claim taken right after an ack-confirmed write reading stale against that write's own delta. Add transaction ack-confirmation, schema DDL-first-push, and a reworked CLI (config/dev/login/mode/drizzle-pull).
+
 ## 0.9.3
 
 ### Patch Changes

package/README.md

@@ -53,7 +53,7 @@ npm install @abloatai/ablo
 npx ablo login     # opens the browser: sign in (or sign up) → a sk_test_ key is saved locally
 npx ablo init      # scaffolds ablo/schema.ts (offers to log in if you skipped it)
 npx ablo migrate   # creates the synced tables in YOUR Postgres (reads DATABASE_URL)
-npx ablo dev       # pushes your schema (test mode), writes ABLO_API_KEY to .env.local, watches for changes
+npx ablo dev       # pushes your schema (sandbox), writes ABLO_API_KEY to .env.local, watches for changes
 ```
 
 After `ablo dev`, the [Quick Start](#quick-start) below runs as-is —
@@ -356,20 +356,22 @@ Same product, same truth either way: your database is the system of record. See
 
 ## Configuration
 
-`Ablo({ ... })` takes one required option and a couple of transport overrides:
+`Ablo({ ... })` takes three things: your schema, your key, and your database —
+the last either as `databaseUrl` here or as a signed
+[Data Source endpoint](./docs/data-sources.md) in your app. Every other option
+has correct defaults:
 
 | Option | Type | Default | Purpose |
 | --- | --- | --- | --- |
 | `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` | `process.env.DATABASE_URL` | Your Postgres, registered as the data plane. Server runtimes only — the SDK throws if it sees this in a browser. Omit it when your app exposes a signed [Data Source endpoint](./docs/data-sources.md) instead. |
-| `baseURL` | `string` | `wss://api.abloatai.com` | Point at a self-hosted or private API |
 
 Keep `apiKey` in trusted server runtimes. In the browser, `<AbloProvider>`
 authenticates with the signed-in user's session; the raw-key path is gated
-behind `dangerouslyAllowBrowser` for server-proxy setups only. Self-hosted
-deployments can pass `authToken` instead of `apiKey`. Advanced hooks (custom
-`fetch`, logging, observability) live in [Client Behavior](./docs/client-behavior.md).
+behind `dangerouslyAllowBrowser` for server-proxy setups only. Advanced hooks
+(custom `fetch`, logging, observability, transport overrides) live in
+[Client Behavior](./docs/client-behavior.md).
 
 ## Errors
 

package/dist/BaseSyncedStore.d.ts

@@ -272,8 +272,11 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
     protected pendingDeltas: SyncDelta[];
     protected batchTimer: ReturnType<typeof setTimeout> | null;
     protected syncPromise: Promise<void> | null;
-    protected lastAckedId: number;
-    protected highestProcessedSyncId: number;
+    /** Resume/ack cursor — delegates to the shared SyncPosition (see
+     *  sync/syncPosition.ts). Advances only after IDB persistence. */
+    protected get lastAckedId(): number;
+    /** Pool-applied cursor — delegates to the shared SyncPosition. */
+    protected get highestProcessedSyncId(): number;
     protected bootstrapDeltaQueue: SyncDelta[] | null;
     protected activeBootstrapCount: number;
     protected pendingDeletes: Set<string>;

package/dist/BaseSyncedStore.js

@@ -181,8 +181,15 @@ export class BaseSyncedStore {
     pendingDeltas = [];
     batchTimer = null;
     syncPromise = null;
-    lastAckedId = 0;
-    highestProcessedSyncId = 0;
+    /** Resume/ack cursor — delegates to the shared SyncPosition (see
+     *  sync/syncPosition.ts). Advances only after IDB persistence. */
+    get lastAckedId() {
+        return this.syncClient.position.persisted;
+    }
+    /** Pool-applied cursor — delegates to the shared SyncPosition. */
+    get highestProcessedSyncId() {
+        return this.syncClient.position.applied;
+    }
     // ── Delta queuing during bootstrap ──
     bootstrapDeltaQueue = null;
     activeBootstrapCount = 0;
@@ -957,8 +964,7 @@ export class BaseSyncedStore {
             }
             // Get sync baseline for WebSocket
             const lastSyncId = (yield this.database.getLastSyncId());
-            this.lastAckedId = Math.max(this.lastAckedId, lastSyncId || 0);
-            this.highestProcessedSyncId = this.lastAckedId;
+            this.syncClient.position.advancePersisted(lastSyncId || 0);
             try {
                 const versions = (yield this.database.getVersionVector());
                 if (versions && typeof versions === 'object')
@@ -1557,9 +1563,7 @@ export class BaseSyncedStore {
             return;
         }
         // Advance watermark
-        if (delta.id > this.highestProcessedSyncId) {
-            this.highestProcessedSyncId = delta.id;
-        }
+        this.syncClient.position.advanceApplied(delta.id);
         // Sync group added — handle immediately. Supports both legacy
         // (addedGroups/removedGroups) and incremental (group/userId) payloads.
         if (delta.actionType === 'G') {
@@ -1699,8 +1703,7 @@ export class BaseSyncedStore {
         const persistedSyncId = batch.persistedSyncId;
         if (persistedSyncId > this.lastAckedId) {
             this.syncWebSocket?.acknowledge?.(persistedSyncId);
-            this.lastAckedId = persistedSyncId;
-            this.highestProcessedSyncId = Math.max(this.highestProcessedSyncId, persistedSyncId);
+            this.syncClient.position.advancePersisted(persistedSyncId);
         }
         // Cache invalidation is automatic via SyncClient 'models:changed' event
         this.pendingDeltas = [];
@@ -1905,11 +1908,9 @@ export class BaseSyncedStore {
         }
         // Delegate pool writes to SyncClient (auto-invalidates cache via 'models:changed' event)
         this.syncClient.applyDeltaBatchToPool([dbResult], (name, data) => this.enrichRelations(name, data));
-        // Advance sync ID
-        if (delta.id > this.lastAckedId) {
-            this.lastAckedId = delta.id;
-            this.highestProcessedSyncId = Math.max(this.highestProcessedSyncId, delta.id);
-        }
+        // This path runs after the delta was written to IDB — advance both
+        // cursors through the shared position.
+        this.syncClient.position.advancePersisted(delta.id);
     }
     /** Handle bootstrap_required event */
     handleBootstrapRequired(_hint) {

package/dist/Database.js

@@ -8,6 +8,7 @@ import { LoadStrategy } from './types/index.js';
 import { getContext } from './context.js';
 import { AbloConnectionError, AbloValidationError } from './errors.js';
 import { InMemoryObjectStore } from './adapters/inMemoryStorage.js';
+import { syncPositionSchema } from './sync/syncPosition.js';
 export class Database {
     // Core database components
     databaseManager;
@@ -252,7 +253,12 @@ export class Database {
         const instantModels = this.modelRegistry.getModelsByLoadStrategy(LoadStrategy.instant);
         const lazyModels = this.modelRegistry.getModelsByLoadStrategy(LoadStrategy.lazy);
         const modelsToLoad = [...instantModels, ...lazyModels];
-        const metadataLastSyncId = metadata?.lastSyncId || 0;
+        // Gate the PERSISTED cursor through the sync-position schema field —
+        // the one trust boundary for resume state. IDB can hand back anything
+        // (a corrupted negative/float cursor would previously pass `|| 0`,
+        // which only catches falsy, and get sent to the server as the resume
+        // point). Invalid → 0 → full bootstrap, the safe degradation.
+        const metadataLastSyncId = syncPositionSchema.shape.persisted.safeParse(metadata?.lastSyncId).data ?? 0;
         const dataAge = metadata?.updatedAt ? Date.now() - metadata.updatedAt.getTime() : Infinity;
         // ── Zero-style cache-validity check ──────────────────────────
         //

package/dist/SyncClient.d.ts

@@ -14,6 +14,7 @@ import { TransactionQueue } from './transactions/TransactionQueue.js';
 import { type OptimisticEchoMetrics } from './transactions/OptimisticEchoTracker.js';
 import type { Database } from './Database.js';
 import type { WriteOptions } from './interfaces/index.js';
+import { SyncPosition } from './sync/syncPosition.js';
 interface SyncObserver {
     onSync?: (event: SyncEvent) => void;
 }
@@ -68,6 +69,13 @@ export declare class SyncClient extends EventEmitter {
     private offlineSince?;
     private maxRetries;
     private isDisposed;
+    /**
+     * THE client's place in the global delta order — the one canonical
+     * instance (see `sync/syncPosition.ts`). The store advances
+     * `applied`/`persisted` as deltas land; the queue advances `acked` on
+     * commit responses; snapshots/claims read `readFloor`.
+     */
+    readonly position: SyncPosition;
     constructor(objectPool: ObjectPool, database: Database);
     /**
      * Setup network monitoring handlers

package/dist/SyncClient.js

@@ -16,6 +16,7 @@ import { EventEmitter } from 'events';
 import { NetworkMonitor } from './NetworkMonitor.js';
 import { TransactionQueue } from './transactions/TransactionQueue.js';
 import { OptimisticEchoTracker, } from './transactions/OptimisticEchoTracker.js';
+import { SyncPosition } from './sync/syncPosition.js';
 export class SyncClient extends EventEmitter {
     objectPool;
     database;
@@ -50,6 +51,13 @@ export class SyncClient extends EventEmitter {
     // Configuration
     maxRetries = 3;
     isDisposed = false;
+    /**
+     * THE client's place in the global delta order — the one canonical
+     * instance (see `sync/syncPosition.ts`). The store advances
+     * `applied`/`persisted` as deltas land; the queue advances `acked` on
+     * commit responses; snapshots/claims read `readFloor`.
+     */
+    position = new SyncPosition();
     constructor(objectPool, database) {
         super();
         this.objectPool = objectPool;
@@ -57,6 +65,7 @@ export class SyncClient extends EventEmitter {
         this.networkMonitor = new NetworkMonitor();
         // Initialize TransactionQueue with proper configuration
         this.transactionQueue = new TransactionQueue({
+            position: this.position,
             maxBatchSize: 50, // Increased from 10 to reduce batch count for large operations
             // Lower delay for snappier dev UX; batching still happens via coalescing
             batchDelay: 150,