@abloatai/ablo 0.9.2 → 0.9.4

package/AGENTS.md

@@ -8,7 +8,7 @@ Claims don't lock. If another writer holds the row, `claim` waits for them and r
 
 Don't hand-write the integration. Run the CLI; it generates the current-API schema, client, Data Source endpoint, and (for Next.js) the browser provider + session route:
 
-- **Scaffold:** `npx ablo init --yes` — flag-driven, never prompts. Override defaults with `--framework <nextjs|vite|remix|vanilla>`, `--auth <apikey|…>`, `--storage <datasource|managed>`, `--no-agent`, `--no-pull`, `--no-install`, `--no-login`. (Plain `ablo init` needs a TTY and will **HANG** in an agent/CI run — always pass `--yes`.)
+- **Scaffold:** `npx ablo init --yes` — flag-driven, never prompts. Override defaults with `--framework <nextjs|vite|remix|vanilla>`, `--auth <apikey|…>`, `--no-agent`, `--no-pull`, `--no-install`, `--no-login`. (Plain `ablo init` needs a TTY and will **HANG** in an agent/CI run — always pass `--yes`.)
 - **Auth:** set `ABLO_API_KEY` in the environment. Do **NOT** run `ablo login` — it opens a browser device flow and blocks an agent.
 - **Provision your DB (Data Source mode):** `npx ablo migrate` creates the tables for your Ablo models plus the adapter's bookkeeping tables (`ablo_outbox`, `ablo_idempotency`). It does **not** touch your other tables — keep your own migrations (drizzle-kit / prisma migrate) for auth and anything not in the Ablo schema.
 - **Adopt an existing DB schema:** `npx ablo pull prisma [path]` / `pull drizzle <module>` (lossless) or `pull` (live DB, lossy). Writes `ablo/schema.ts`.

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # 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
+
+- Onboarding: quickstart leads with your-own-database (Drizzle Data Source), drop Ablo-managed mode, add `ablo push` step; context7 library-claim config.
+
 ## 0.9.2
 
 ### Patch Changes

package/README.md

@@ -33,27 +33,43 @@ claims are visible while the work is still in progress.
 
 [Get started ↓](#quick-start) · point your coding agent at the shipped `llms.txt`
 
-It works with the auth and database you already have: realtime data is scoped to
-*sync groups* from your own identity, and your database can stay the source of
-truth via a Data Source.
+It works with the auth and database you already have. **Your database is the
+system of record — Ablo never hosts your data.** Ablo is the transaction layer
+on top of it: realtime data is scoped to *sync groups* from your own identity,
+and every committed row lives in your Postgres.
 
 **Built for** collaborative editors, AI agent workflows, and internal tools —
 anywhere people and agents change shared state and everyone has to see it live.
 
 ## Set up
 
+The CLI takes you from nothing to a synced schema — it handles the account,
+the key, and the env file. You bring one thing: a Postgres `DATABASE_URL`
+(local, Neon, RDS — any will do; **your database is the system of record,
+Ablo never hosts your data**).
+
 ```bash
 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 (sandbox), writes ABLO_API_KEY to .env.local, watches for changes
 ```
 
-**Keys & runtime.** Ablo needs Node 24+ and TypeScript 5+. Grab an `sk_test_*`
-key for a sandbox
-(`export ABLO_API_KEY=sk_test_...`); keep keys in trusted server runtimes only.
+After `ablo dev`, the [Quick Start](#quick-start) below runs as-is —
+`ABLO_API_KEY` is already in `.env.local` (frameworks load it automatically;
+plain Node: `node --env-file=.env.local app.ts`). `npx ablo status` shows
+what's configured at any time.
+
+**Keys & runtime.** Ablo needs Node 24+ and TypeScript 5+. Keys come in two of
+*your* environments — `sk_test_` and `sk_live_`, like Stripe — and `ablo login`
+mints both. Keep the key and the database URL in trusted server runtimes only.
 In the browser, `<AbloProvider>` authenticates with the signed-in user's
-session — never the raw key.
+session — never the raw key, never the database URL. Prefer the connection
+string never leaving your infrastructure? Expose a signed
+[Data Source endpoint](./docs/data-sources.md) instead and omit `databaseUrl`.
 
-Then wire it by hand — the [Quick Start](#quick-start) below is the shape to
-copy. For production (React, an existing backend, Data Source, agents), the
+For production (React, an existing backend, Data Source, agents), the
 [Integration Guide](./docs/integration-guide.md) is the deeper map.
 
 **Prefer to let an agent wire it?** The package ships an `llms.txt` — a precise
@@ -78,7 +94,8 @@ const schema = defineSchema({
 
 const ablo = Ablo({
   schema,
-  apiKey: process.env.ABLO_API_KEY,
+  apiKey: process.env.ABLO_API_KEY, // written to .env.local by `npx ablo dev`
+  databaseUrl: process.env.DATABASE_URL, // your Postgres — rows live here, never with Ablo
 });
 
 await ablo.ready();
@@ -99,7 +116,7 @@ const forecast = await fetchForecast(report.location); // slow: API or LLM call
 await ablo.weatherReports.update({ id: report.id, data: { status: 'ready', forecast } });
 
 const ready = ablo.weatherReports.get(created.id);
-console.log({ id: ready.id, status: ready.status });
+console.log({ id: ready?.id, status: ready?.status });
 
 await ablo.dispose();
 ```
@@ -324,34 +341,37 @@ curl https://api.abloatai.com/v1/commits \
 { "object": "commit_receipt", "status": "confirmed", "serverTxId": "tx_…", "lastSyncId": 1042, "ops": 1 }
 ```
 
-## Connect Your Database
+## Your Database
 
-Every schema model has a backing store. By default, Ablo stores rows for the
-models you declare, so `ablo.weatherReports.create({ data })` and `ablo.weatherReports.update({ id, data })`
-write to Ablo-managed state.
+Every schema model is backed by **your own database** — Ablo is the transaction
+layer on top of it, never the home for your rows. Two ways to connect it:
 
-If your existing database stays the source of truth, connect it as a Data
-Source: Ablo sends signed commit requests to an endpoint you host, and your app
-writes its own database. Your `DATABASE_URL` stays in your app — Ablo only ever
-sees the API key.
+| | How Ablo reaches your Postgres | Use when |
+| --- | --- | --- |
+| **Connection string** (default) | `databaseUrl` at init. Ablo registers the connection once (sent over TLS, stored sealed, never echoed back) and commits each write directly — through a non-superuser role, behind row-level security. | You can hand over a scoped connection string. |
+| **Signed endpoint** | Your app exposes one route built from an ORM adapter (`prismaDataSource` / `drizzleDataSource`); Ablo sends signed commit requests and your app writes its own database. | Database credentials must never leave your infrastructure. |
 
-See [Connect Your Database](./docs/data-sources.md) for the integration shape.
+Same product, same truth either way: your database is the system of record. See
+[Connect Your Database](./docs/data-sources.md) for both shapes.
 
 ## 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 |
-| `baseURL` | `string` | `wss://api.abloatai.com` | Point at a self-hosted or private API |
+| `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. |
 
 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
 
@@ -395,11 +415,11 @@ contract; there are no retry or timeout knobs to tune.
 - [Identity & Sync Groups](./docs/identity.md) — use your own authentication; tell Ablo who's connecting and how org / team / user map to sync-group scope.
 - [Schema Contract](./docs/schema-contract.md) — one schema becomes typed model clients, React reads, agent writes, Data Source shape, and schema push.
 - [Guarantees](./docs/guarantees.md) — confirmed writes, stale-write protection, claim coordination, and agent lifecycle.
-- [Integration Guide](./docs/integration-guide.md) — pick the backing mode and integrate React, Data Source, multiplayer, and agents.
+- [Integration Guide](./docs/integration-guide.md) — integrate React, your database, multiplayer, and agents.
 - [React](./docs/react.md) — `<AbloProvider>`, `useAblo`, presence, status, and bootstrap gating.
 - [Coordination](./docs/coordination.md) — `claim` / `claim.state` / `claim.queue` / `claim.release` reference: hold a row across slow agent work, and observe the line waiting behind it.
 - [Client Behavior](./docs/client-behavior.md) — options, errors, retries, timeouts, and public imports.
-- [Connect Your Database](./docs/data-sources.md) — keep canonical rows in your app database without giving Ablo database credentials.
+- [Connect Your Database](./docs/data-sources.md) — connect your Postgres by connection string (`databaseUrl`) or signed endpoint; your database is the system of record either way.
 - [Existing Python Backend](./docs/examples/existing-python-backend.md) — migrate existing Python endpoints to multiplayer and agent-safe writes gradually.
 - [AI SDK Tool](./docs/examples/ai-sdk-tool.md) — use Ablo inside an AI SDK tool call.
 - [Server Agent](./docs/examples/server-agent.md) — schema-backed worker.

package/dist/BaseSyncedStore.d.ts

@@ -21,7 +21,6 @@ import { QueryProcessor } from './core/QueryProcessor.js';
 import { Model } from './Model.js';
 import { ModelScope } from './ObjectPool.js';
 import type { Schema } from './schema/schema.js';
-import { type ReaderActions } from './mutators/readerActions.js';
 import type { LocalMutation } from './react/context.js';
 import type { AuthCredentialSource } from './auth/credentialSource.js';
 /** Constructor type for Model subclasses (accepts abstract classes) */
@@ -224,18 +223,6 @@ export declare function deriveSyncPlanFromSchema(schema: Schema): {
     enrichmentPlan: EnrichmentPlanEntry[];
     foreignKeyIndexes: ForeignKeyIndexSpec[];
 };
-/**
- * Schema-derived accessor namespace exposed on `store.query`. Each key is
- * a model name from the schema and resolves to a `ReaderActions<S, K>`
- * with `findById` / `findMany` / `findFirst` / `count`. Return types are
- * inferred from the schema (`InferModel<S, K>`) so callers don't need to
- * cast or pass class constructors.
- *
- * Prisma / Drizzle / Zero all use this shape: `store.query.<modelKey>.*`.
- */
-export type QueryNamespace<S extends Schema> = {
-    readonly [K in keyof S['models'] & string]: ReaderActions<S, K>;
-};
 export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaboration> = DefaultCollaborationEvents, TSchema extends Schema = Schema> {
     syncStatus: SyncStatus;
     protected readonly syncClient: SyncClient;
@@ -244,13 +231,10 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
     protected readonly modelRegistry: ModelRegistry;
     protected readonly auth?: AuthCredentialSource;
     /**
-     * Schema the store was constructed with. Persisted so the `query`
-     * accessor namespace can build typed per-model reader actions lazily
-     * without callers having to pass the schema at every lookup site.
+     * Schema the store was constructed with. Used by the schema-typed
+     * `create(key, data)` factory and model self-healing.
      */
     protected readonly schema?: TSchema;
-    /** Lazily-built `query.<modelKey>.*` accessor namespace. */
-    private _queryProxy?;
     protected syncWebSocket: SyncWebSocket<TCollaboration> | null;
     private _syncServerUrl?;
     /**
@@ -288,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>;
@@ -694,24 +681,6 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
         id: string;
         archivedAt?: Date | null;
     }>(entity: T): Promise<void>;
-    /**
-     * Schema-keyed accessor namespace — the primary type-safe lookup surface.
-     *
-     * ```ts
-     * const chat = store.query.chats.retrieve(chatId);  // Chat | undefined
-     * const slides = store.query.slides.findMany({ where: { deckId } });  // Slide[]
-     * ```
-     *
-     * Each `query.<modelKey>` is a `ReaderActions<Schema, K>` built lazily on
-     * first access via `createReaderActions`. The returned types are inferred
-     * from the schema (`InferModel<S, K>`), including `InferRelations` — so
-     * `chat.messages`, `slide.layers`, etc. are typed without a cast.
-     *
-     * Throws if the store was constructed without a schema (class-based
-     * subclasses that wire models via `modelRegistry.registerModel` directly
-     * don't have access to schema-derived inference).
-     */
-    get query(): QueryNamespace<TSchema>;
     /** Retrieve a single entity by id. Synchronous pool read. */
     retrieve(_modelClass: ModelConstructor<Model>, id: string): Model | undefined;
     /** Find any entity by ID regardless of type */

package/dist/BaseSyncedStore.js

@@ -22,7 +22,6 @@ import { getContext } from './context.js';
 import { SyncSessionError } from './errors.js';
 import { ModelScope } from './ObjectPool.js';
 import { LazyReferenceCollection } from './LazyReferenceCollection.js';
-import { createReaderActions } from './mutators/readerActions.js';
 /** Bootstrap timeout configuration */
 export const BOOTSTRAP_CONFIG = {
     OVERALL_TIMEOUT_MS: 15_000,
@@ -126,13 +125,10 @@ export class BaseSyncedStore {
     modelRegistry;
     auth;
     /**
-     * Schema the store was constructed with. Persisted so the `query`
-     * accessor namespace can build typed per-model reader actions lazily
-     * without callers having to pass the schema at every lookup site.
+     * Schema the store was constructed with. Used by the schema-typed
+     * `create(key, data)` factory and model self-healing.
      */
     schema;
-    /** Lazily-built `query.<modelKey>.*` accessor namespace. */
-    _queryProxy;
     // ── Real-time sync ──
     syncWebSocket = null;
     _syncServerUrl;
@@ -185,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;
@@ -961,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')
@@ -1561,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') {
@@ -1703,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 = [];
@@ -1789,53 +1788,9 @@ export class BaseSyncedStore {
         this.syncClient.update(model);
     }
     // ── Query API ────────────────────────────────────────────────────────────
-    /**
-     * Schema-keyed accessor namespace — the primary type-safe lookup surface.
-     *
-     * ```ts
-     * const chat = store.query.chats.retrieve(chatId);  // Chat | undefined
-     * const slides = store.query.slides.findMany({ where: { deckId } });  // Slide[]
-     * ```
-     *
-     * Each `query.<modelKey>` is a `ReaderActions<Schema, K>` built lazily on
-     * first access via `createReaderActions`. The returned types are inferred
-     * from the schema (`InferModel<S, K>`), including `InferRelations` — so
-     * `chat.messages`, `slide.layers`, etc. are typed without a cast.
-     *
-     * Throws if the store was constructed without a schema (class-based
-     * subclasses that wire models via `modelRegistry.registerModel` directly
-     * don't have access to schema-derived inference).
-     */
-    get query() {
-        if (!this.schema) {
-            throw new AbloValidationError('store.query requires a schema to be passed to the BaseSyncedStore constructor. ' +
-                'Pass `{ schema }` in the dependencies argument.', { code: 'store_query_schema_missing' });
-        }
-        if (!this._queryProxy) {
-            const schema = this.schema;
-            // BaseSyncedStore satisfies SyncStoreContract structurally via
-            // `findById` / `queryByClass` / `save` / `delete`. Pass `this`
-            // directly — `createReaderActions` accepts the contract shape.
-            const store = this;
-            const cache = new Map();
-            this._queryProxy = new Proxy({}, {
-                get: (_target, prop) => {
-                    if (typeof prop !== 'string')
-                        return undefined;
-                    const cached = cache.get(prop);
-                    if (cached)
-                        return cached;
-                    if (!(prop in schema.models)) {
-                        throw new AbloValidationError(`store.query: unknown model key "${prop}". Known keys: ${Object.keys(schema.models).join(', ')}`, { code: 'store_query_unknown_model' });
-                    }
-                    const actions = createReaderActions(schema, prop, store);
-                    cache.set(prop, actions);
-                    return actions;
-                },
-            });
-        }
-        return this._queryProxy;
-    }
+    // `store.query.<model>.*` was DELETED — `ablo.<model>.get/getAll` is the
+    // one read surface. Custom mutators still read transactionally through
+    // `tx.<model>` (mutators/Transaction.ts), which owns `createReaderActions`.
     /** Retrieve a single entity by id. Synchronous pool read. */
     retrieve(_modelClass, id) {
         return this.objectPool.get(id);
@@ -1953,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/NetworkMonitor.js

@@ -9,7 +9,10 @@
 import { EventEmitter } from 'events';
 import { getContext } from './context.js';
 export class NetworkMonitor extends EventEmitter {
-    isOnline = typeof navigator !== 'undefined' ? navigator.onLine : true;
+    // Only `navigator.onLine === false` means offline. Node 18+ exposes a global
+    // `navigator` with `onLine === undefined`, so the naive `navigator.onLine`
+    // would seed `false` (offline) on every server client — start optimistic.
+    isOnline = !(typeof navigator !== 'undefined' && navigator.onLine === false);
     lastOnlineCheck = new Date();
     constructor() {
         super();

package/dist/SyncClient.d.ts

@@ -13,7 +13,8 @@ import { EventEmitter } from 'events';
 import { TransactionQueue } from './transactions/TransactionQueue.js';
 import { type OptimisticEchoMetrics } from './transactions/OptimisticEchoTracker.js';
 import type { Database } from './Database.js';
-import type { MutationOptions } from './interfaces/index.js';
+import type { WriteOptions } from './interfaces/index.js';
+import { SyncPosition } from './sync/syncPosition.js';
 interface SyncObserver {
     onSync?: (event: SyncEvent) => void;
 }
@@ -38,7 +39,6 @@ export interface RehydrationStats {
     healed: number;
     elapsedMs: number;
 }
-type MutationWriteOptions = Pick<MutationOptions, 'readAt' | 'onStale'>;
 export declare class SyncClient extends EventEmitter {
     private objectPool;
     private database;
@@ -69,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
@@ -114,6 +121,12 @@ export declare class SyncClient extends EventEmitter {
      * Initialize sync client with authentication
      */
     initialize(userId: string, organizationId: string): Promise<void>;
+    /**
+     * The organization this client writes under (set by `initialize`).
+     * Read by the model proxy so `create()` defaults `organizationId` the
+     * same way the mutator path does — `null` until identity is wired.
+     */
+    getOrganizationId(): string | null;
     /**
      * Self-healing helper for individual model records.
      *
@@ -172,9 +185,9 @@ export declare class SyncClient extends EventEmitter {
      */
     private captureModelChanges;
     /** Add new model (CREATE) - works offline */
-    add(model: Model, options?: MutationWriteOptions): void;
+    add(model: Model, options?: WriteOptions): void;
     /** Update existing model (UPDATE) - works offline */
-    update(model: Model, options?: MutationWriteOptions): void;
+    update(model: Model, options?: WriteOptions): void;
     /**
      * Update existing model with pre-computed changes.
      * Used by saveManyOptimized when incoming models have empty change-tracking
@@ -186,7 +199,7 @@ export declare class SyncClient extends EventEmitter {
      *  but still need optimistic pool updates at the sync layer. */
     get gql(): import("./interfaces/index.js").MutationExecutor;
     /** Delete model (DELETE) - works offline */
-    delete(model: Model, options?: MutationWriteOptions): void;
+    delete(model: Model, options?: WriteOptions): void;
     /**
      * Clear all pending mutations for a specific model
      * Called before deletion to prevent "layer not found" errors on the server

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,
@@ -313,6 +322,14 @@ export class SyncClient extends EventEmitter {
             this.emit('sync:offline');
         }
     }
+    /**
+     * The organization this client writes under (set by `initialize`).
+     * Read by the model proxy so `create()` defaults `organizationId` the
+     * same way the mutator path does — `null` until identity is wired.
+     */
+    getOrganizationId() {
+        return this.organizationId;
+    }
     /**
      * Self-healing helper for individual model records.
      *
@@ -1311,7 +1328,61 @@ export class SyncClient extends EventEmitter {
      */
     onLocalTransaction(listener) {
         this.transactionQueue.on('transaction:created', listener);
-        return () => this.transactionQueue.off('transaction:created', listener);
+        // Commit-lane writes (`ablo.commits.create` — the agent/atomic door) ride
+        // their own `commit:created` event: they have no optimistic pool apply,
+        // so they must not feed the echo tracker's `transaction:created` path.
+        // Enrich each operation with previous state captured from the pool HERE
+        // (the queue is pool-free) and hand the synthesized transaction to the
+        // same listener, so undo observes every write door — one stream.
+        const onCommitCreated = (payload) => {
+            const TYPE_BY_WIRE = {
+                CREATE: 'create',
+                UPDATE: 'update',
+                DELETE: 'delete',
+                ARCHIVE: 'archive',
+                UNARCHIVE: 'unarchive',
+            };
+            payload.operations.forEach((op, index) => {
+                const type = TYPE_BY_WIRE[op.type];
+                if (!type || !op.id)
+                    return;
+                const resident = this.objectPool.get(op.id);
+                const snapshot = type === 'create' ? undefined : resident?.toJSON();
+                // A DELETE of a row the local graph never saw is not invertible —
+                // recording it would make undo "restore" an empty husk. Skip it.
+                if (type === 'delete' && !snapshot)
+                    return;
+                // UPDATE inverse must only revert the fields this op actually wrote;
+                // handing undo the FULL row would clobber concurrent edits to
+                // unrelated fields on revert.
+                const previousData = type === 'update' && snapshot && op.input
+                    ? Object.fromEntries(Object.keys(op.input).map((key) => [key, snapshot[key]]))
+                    : snapshot ?? null;
+                listener({
+                    id: `${payload.clientTxId}_op${index}`,
+                    type,
+                    modelName: op.model,
+                    modelId: op.id,
+                    modelKey: op.model,
+                    data: op.input ?? undefined,
+                    previousData,
+                    context: {
+                        userId: this.userId ?? '',
+                        organizationId: this.organizationId ?? '',
+                    },
+                    status: 'pending',
+                    createdAt: Date.now(),
+                    attempts: 0,
+                    priority: 'normal',
+                    priorityScore: 0,
+                });
+            });
+        };
+        this.transactionQueue.on('commit:created', onCommitCreated);
+        return () => {
+            this.transactionQueue.off('transaction:created', listener);
+            this.transactionQueue.off('commit:created', onCommitCreated);
+        };
     }
     /**
      * Wait for the latest in-flight transaction for (modelName, modelId)

package/dist/SyncEngineContext.js

@@ -43,7 +43,11 @@ export const noopAnalytics = {
 /** Browser-native online status provider */
 export const browserOnlineStatus = {
     isOnline() {
-        return typeof navigator !== 'undefined' ? navigator.onLine : true;
+        // Only `navigator.onLine === false` is the MDN-reliable "definitely offline"
+        // signal. Don't use `!navigator.onLine`: Node 18+ exposes a global
+        // `navigator` whose `onLine` is `undefined`, which `!` would read as offline —
+        // wedging every Node/server client (agents, worker, MCP) into a false offline.
+        return !(typeof navigator !== 'undefined' && navigator.onLine === false);
     },
 };
 /** Session error detector — delegates to SyncSessionError so detection is

package/dist/auth/index.js

@@ -15,7 +15,9 @@ import { parseCapabilityExchangeResponse, parseIdentityResolveResponse, } from '
 import { AbloAuthenticationError, hasWireCode, translateHttpError } from '../errors.js';
 export async function exchangeApiKey(options) {
     if (!options.apiKey) {
-        throw new AbloAuthenticationError('apiKey is required for capability exchange', { code: 'apikey_missing' });
+        throw new AbloAuthenticationError('No API key found. Set ABLO_API_KEY in your environment — `npx ablo login` ' +
+            'then `npx ablo dev` writes it into .env.local for you — or pass ' +
+            '`apiKey` to Ablo({ ... }) directly.', { code: 'apikey_missing' });
     }
     if (!options.baseUrl) {
         throw new AbloAuthenticationError('baseUrl is required for capability exchange', { code: 'base_url_missing' });