@abloatai/ablo 0.9.3 → 0.9.4

package/dist/client/Ablo.js

@@ -1307,7 +1307,14 @@ export function Ablo(options) {
             createSnapshot: (modelKey, id) => createSnapshot({
                 pool: objectPool,
                 transport: store.getSyncWebSocket(),
-                getLastSyncId: () => store.getSyncWebSocket()?.getLastSyncId() ?? store.lastSyncId ?? 0,
+                // `position.readFloor` is THE value claims/snapshots stamp as
+                // `readAt` (max of the pool-applied cursor and the acked
+                // watermark for our own writes — see sync/syncPosition.ts).
+                // Stamping a bare stream cursor made a claim taken right after
+                // an ack-confirmed write stale against that write's own delta.
+                // The socket/store cursors are persistence-gated and therefore
+                // never ahead of `applied` — no extra max() needed here.
+                getLastSyncId: () => syncClient.position.readFloor,
                 entities: { [modelKey]: id },
             }),
             queue: (target) => publicIntents.queueFor({ type: target.model, id: target.id }),

package/dist/client/auth.d.ts

@@ -53,7 +53,7 @@ export declare function resolveAuthToken(input: AuthResolveInput): string | null
 export declare function resolveDatabaseUrl(input: AuthResolveInput): string | null;
 export declare const ABLO_HOSTED_API_DOMAIN = "api.abloatai.com";
 export declare const ABLO_HOSTED_HTTP_BASE_URL = "https://api.abloatai.com";
-export declare const ABLO_DEFAULT_BASE_URL = "wss://api.abloatai.com";
+export declare const ABLO_DEFAULT_BASE_URL = "https://api.abloatai.com";
 /**
  * Normalize old hosted aliases to the public API domain. Self-hosted/custom
  * URLs pass through unchanged; only first-party legacy hosts are rewritten.

package/dist/client/auth.js

@@ -40,7 +40,7 @@ export function resolveDatabaseUrl(input) {
 }
 export const ABLO_HOSTED_API_DOMAIN = 'api.abloatai.com';
 export const ABLO_HOSTED_HTTP_BASE_URL = `https://${ABLO_HOSTED_API_DOMAIN}`;
-export const ABLO_DEFAULT_BASE_URL = `wss://${ABLO_HOSTED_API_DOMAIN}`;
+export const ABLO_DEFAULT_BASE_URL = `https://${ABLO_HOSTED_API_DOMAIN}`;
 const LEGACY_HOSTED_API_HOSTS = new Set([
     'mesh.ablo.finance',
     'mesh-staging.ablo.finance',
@@ -65,13 +65,22 @@ export function normalizeAbloHostedBaseUrl(rawUrl) {
     const schemed = /^[a-z][a-z0-9+.-]*:\/\//i.test(trimmed) ? trimmed : `https://${trimmed}`;
     try {
         const url = new URL(schemed);
-        if (!LEGACY_HOSTED_API_HOSTS.has(url.hostname))
-            return schemed.replace(/\/+$/, '');
+        // Canonicalize the scheme to the HTTP family — the WHATWG WebSocket
+        // model: accept all four schemes (`http`/`https`/`ws`/`wss`), normalize
+        // ONCE at the entry point, and let each layer derive its own protocol
+        // (the socket layer maps http→ws / https→wss; fetch uses it as-is).
+        // Before this, a `ws://` baseURL reached HTTP consumers un-normalized
+        // and the client wedged at startup instead of connecting.
+        if (url.protocol === 'ws:')
+            url.protocol = 'http:';
+        if (url.protocol === 'wss:')
+            url.protocol = 'https:';
+        if (!LEGACY_HOSTED_API_HOSTS.has(url.hostname)) {
+            return url.toString().replace(/\/+$/, '');
+        }
         url.hostname = ABLO_HOSTED_API_DOMAIN;
         if (url.protocol === 'http:')
             url.protocol = 'https:';
-        if (url.protocol === 'ws:')
-            url.protocol = 'wss:';
         return url.toString().replace(/\/+$/, '');
     }
     catch {

package/dist/schema/ddl.js

@@ -315,6 +315,14 @@ export function generateMigrationPlan(steps, opts) {
     const qs = q(targetSchema);
     const statements = [];
     const concurrent = [];
+    // The app schema must exist before any statement targets it. On a fresh
+    // org's FIRST push (`prev = null`) the migration plan IS the provisioning —
+    // `app_<orgId>` has never been created, and skipping this line made every
+    // first push die with `3F000 invalid_schema_name` at statement 0. Idempotent
+    // (`IF NOT EXISTS`), so emitting it on every later migration is free.
+    if (steps.length > 0 && targetSchema !== 'public') {
+        statements.push(`CREATE SCHEMA IF NOT EXISTS ${qs};`);
+    }
     const qtFor = (table) => `${qs}.${q(table)}`;
     const tableOfModel = (schema, key) => {
         const m = schema?.models[key];
@@ -327,8 +335,8 @@ export function generateMigrationPlan(steps, opts) {
         switch (step.kind) {
             case 'create_model': {
                 // Reuse the provisioner for the full table (base cols + fields + enum
-                // checks + RLS), minus its `CREATE SCHEMA` (the schema already exists
-                // mid-migration).
+                // checks + RLS), minus its `CREATE SCHEMA` (the plan header above
+                // already emitted it once — don't repeat it per model).
                 const def = next.models[step.model];
                 if (!def)
                     break;

package/dist/schema/model.d.ts

@@ -188,14 +188,16 @@ export interface ModelOptions {
     entityRoles?: EntityRole | readonly EntityRole[];
     /**
      * Whether clients may issue CREATE/UPDATE/DELETE mutations for this
-     * model via the `commit` wire protocol. Default: false.
+     * model via the `commit` wire protocol. Default: **true** — declaring a
+     * model in the schema IS the opt-in; if you put an entity in your synced
+     * schema, you almost always want to write it (product decision
+     * 2026-06-10, reversing the earlier default-deny that made every fresh
+     * quickstart's first write die with `server_execute_unknown_model`).
      *
-     * Safety-by-default: a newly-declared schema entity is read-only from
-     * the client side until the author explicitly opts into wire mutability.
-     * Prevents the class of bug where adding a new entity to the schema
-     * silently exposes it as a write surface (the 2026-04-20 `AgentJob`
-     * incident) OR where internal tables (`sync_deltas`, `presences`,
-     * digest/ingestion tables) become writable by accident.
+     * Opt OUT for server-managed projections (stats, digests, audit views):
+     * `mutable: false`, or the `readOnly.*` sugar which sets it for you.
+     * That keeps the 2026-04-20 `AgentJob`-class protection available where
+     * it matters, as a deliberate marking instead of a silent default.
      *
      * The server's `buildModelMap` (src/server/commit.ts) derives
      * the mutation allowlist from this flag — no parallel hardcoded list.

package/dist/schema/model.js

@@ -99,7 +99,7 @@ export function model(shape, relations, options) {
         scope: options?.scope,
         grants: options?.grants,
         entityRoles: normalizeEntityRoles(options?.entityRoles),
-        mutable: options?.mutable,
+        mutable: options?.mutable ?? true,
         lazyObservable: options?.lazyObservable,
         computed: options?.computed,
         autoFill: options?.autoFill,

package/dist/schema/schema.js

@@ -167,7 +167,13 @@ export function defineSchema(models, options) {
         const persist = def.persist
             ? { ...def.persist, store: def.persist.store ?? typename }
             : undefined;
-        resolvedModels[name] = { ...def, typename, persist };
+        // Physical table defaults to the schema key — the SAME rule the
+        // provisioner/planner use (`tableName ?? key`), resolved here once so the
+        // serialized artifact always carries it. Required now that models are
+        // mutable by default: the server's `buildModelMap` rejects a mutable
+        // model with no `tableName`, which would otherwise break every commit.
+        const tableName = def.tableName ?? name;
+        resolvedModels[name] = { ...def, typename, tableName, persist };
     }
     validateSyncGroupSchema(resolvedModels);
     return {

package/dist/sync/syncPosition.d.ts

@@ -0,0 +1,78 @@
+/**
+ * THE sync-position structure — one typed object for "where is this client
+ * in the global delta order", replacing five scattered private counters
+ * (`lastSeenSyncId` on the queue, `highestProcessedSyncId` + `lastAckedId`
+ * on the store, ad-hoc acked watermarks, `max()` calls at snapshot sites).
+ *
+ * Three facts with DIFFERENT advance disciplines — flattening them was the
+ * historical bug source, so the structure models them explicitly:
+ *
+ *   - `persisted` — the resume/ack cursor. Advances ONLY after deltas have
+ *     committed to IndexedDB (the Replicache "lastMutationID read in the
+ *     same transaction as the client view" rule — see SyncWebSocket.sendAck).
+ *     This is what reconnect catch-up sends; it must never run ahead of
+ *     durable state or the server skips deltas that never landed.
+ *
+ *   - `applied` — the in-memory cursor: the last delta APPLIED to the
+ *     object pool. Drives delta dedup/replay guards. May run ahead of
+ *     `persisted` (pool applies before the IDB flush) and behind receipt
+ *     (bootstrap-queued deltas are received but not yet applied).
+ *
+ *   - `acked` — the highest server watermark ACKED to this client's OWN
+ *     commits. An ack at N means the server applied our write at N; the
+ *     optimistic pool already reflects it, so for entities we wrote we have
+ *     logically read through N even before the stream echo arrives.
+ *
+ * One derived read: `readFloor` = max(applied, acked) — the ONLY value
+ * snapshots/claims may stamp as `readAt`. The bare stream cursor made a
+ * claim taken right after an ack-confirmed write stale against that write's
+ * own delta; the bare ack would be wrong for read-only clients. Per-entity
+ * correct: a foreign change to an entity we just wrote necessarily lands
+ * ABOVE our ack and still stale-rejects.
+ *
+ * The Zod schema IS the state shape — the class holds exactly one
+ * `SyncPositionSnapshot` and applies monotonic merges to it, so
+ * snapshot/restore are identity-shaped and the schema is the single gate
+ * for anything loaded from disk (`parseSyncPosition`; a corrupted stored
+ * cursor "ahead of reality" is an existing, known failure mode).
+ */
+import { z } from 'zod';
+export declare const syncPositionSchema: z.ZodObject<{
+    persisted: z.ZodNumber;
+    applied: z.ZodNumber;
+    acked: z.ZodNumber;
+}, z.core.$strip>;
+export type SyncPositionSnapshot = z.infer<typeof syncPositionSchema>;
+/**
+ * PERSISTENCE DESIGN: only the `persisted` cursor is stored durably (as
+ * `WorkspaceMetadata.lastSyncId`, written by Database after each IDB delta
+ * commit and gated on load through `syncPositionSchema.shape.persisted` in
+ * `Database.requiredBootstrap`). Persisting `applied`/`acked` would be
+ * meaningless: on resume the pool is rebuilt FROM the persisted state, so
+ * the correct restore is exactly `advancePersisted(storedCursor)` — which
+ * implies `applied`, while `acked` starts at 0 (a dead session's acks carry
+ * no read authority; the offline queue re-acks its own replays).
+ */
+/** Validate a persisted/foreign value into a position snapshot. */
+export declare function parseSyncPosition(value: unknown): SyncPositionSnapshot | null;
+/** The live position. One instance per client (owned by SyncClient); the
+ *  three producers advance their own fact, consumers read. */
+export declare class SyncPosition {
+    #private;
+    /** Current state — the schema shape, frozen-by-copy. */
+    snapshot(): SyncPositionSnapshot;
+    get persisted(): number;
+    get applied(): number;
+    get acked(): number;
+    /** THE value snapshots/claims stamp as `readAt`. */
+    get readFloor(): number;
+    /** Deltas through `syncId` have COMMITTED to IndexedDB. Persisting
+     *  implies applied — the flush path applies before/with persisting. */
+    advancePersisted(syncId: number): void;
+    /** A delta was APPLIED to the in-memory pool. */
+    advanceApplied(syncId: number): void;
+    /** The server acked one of OUR commits at this watermark. */
+    noteAck(lastSyncId: number | undefined): void;
+    /** Restore from a VALIDATED snapshot (e.g. IDB resume). Monotonic. */
+    restore(snapshot: SyncPositionSnapshot): void;
+}

package/dist/sync/syncPosition.js

@@ -0,0 +1,111 @@
+/**
+ * THE sync-position structure — one typed object for "where is this client
+ * in the global delta order", replacing five scattered private counters
+ * (`lastSeenSyncId` on the queue, `highestProcessedSyncId` + `lastAckedId`
+ * on the store, ad-hoc acked watermarks, `max()` calls at snapshot sites).
+ *
+ * Three facts with DIFFERENT advance disciplines — flattening them was the
+ * historical bug source, so the structure models them explicitly:
+ *
+ *   - `persisted` — the resume/ack cursor. Advances ONLY after deltas have
+ *     committed to IndexedDB (the Replicache "lastMutationID read in the
+ *     same transaction as the client view" rule — see SyncWebSocket.sendAck).
+ *     This is what reconnect catch-up sends; it must never run ahead of
+ *     durable state or the server skips deltas that never landed.
+ *
+ *   - `applied` — the in-memory cursor: the last delta APPLIED to the
+ *     object pool. Drives delta dedup/replay guards. May run ahead of
+ *     `persisted` (pool applies before the IDB flush) and behind receipt
+ *     (bootstrap-queued deltas are received but not yet applied).
+ *
+ *   - `acked` — the highest server watermark ACKED to this client's OWN
+ *     commits. An ack at N means the server applied our write at N; the
+ *     optimistic pool already reflects it, so for entities we wrote we have
+ *     logically read through N even before the stream echo arrives.
+ *
+ * One derived read: `readFloor` = max(applied, acked) — the ONLY value
+ * snapshots/claims may stamp as `readAt`. The bare stream cursor made a
+ * claim taken right after an ack-confirmed write stale against that write's
+ * own delta; the bare ack would be wrong for read-only clients. Per-entity
+ * correct: a foreign change to an entity we just wrote necessarily lands
+ * ABOVE our ack and still stale-rejects.
+ *
+ * The Zod schema IS the state shape — the class holds exactly one
+ * `SyncPositionSnapshot` and applies monotonic merges to it, so
+ * snapshot/restore are identity-shaped and the schema is the single gate
+ * for anything loaded from disk (`parseSyncPosition`; a corrupted stored
+ * cursor "ahead of reality" is an existing, known failure mode).
+ */
+import { z } from 'zod';
+export const syncPositionSchema = z.object({
+    /** Resume/ack cursor — advances only after IDB persistence. */
+    persisted: z.number().int().nonnegative(),
+    /** In-memory cursor — last delta applied to the pool. */
+    applied: z.number().int().nonnegative(),
+    /** Highest server watermark acked to this client's own commits. */
+    acked: z.number().int().nonnegative(),
+});
+/**
+ * PERSISTENCE DESIGN: only the `persisted` cursor is stored durably (as
+ * `WorkspaceMetadata.lastSyncId`, written by Database after each IDB delta
+ * commit and gated on load through `syncPositionSchema.shape.persisted` in
+ * `Database.requiredBootstrap`). Persisting `applied`/`acked` would be
+ * meaningless: on resume the pool is rebuilt FROM the persisted state, so
+ * the correct restore is exactly `advancePersisted(storedCursor)` — which
+ * implies `applied`, while `acked` starts at 0 (a dead session's acks carry
+ * no read authority; the offline queue re-acks its own replays).
+ */
+/** Validate a persisted/foreign value into a position snapshot. */
+export function parseSyncPosition(value) {
+    const result = syncPositionSchema.safeParse(value);
+    return result.success ? result.data : null;
+}
+const ZERO = { persisted: 0, applied: 0, acked: 0 };
+/** Monotonic merge: each cursor only ever moves forward. */
+function advance(state, next) {
+    return {
+        persisted: Math.max(state.persisted, next.persisted ?? 0),
+        applied: Math.max(state.applied, next.applied ?? 0),
+        acked: Math.max(state.acked, next.acked ?? 0),
+    };
+}
+/** The live position. One instance per client (owned by SyncClient); the
+ *  three producers advance their own fact, consumers read. */
+export class SyncPosition {
+    #state = ZERO;
+    /** Current state — the schema shape, frozen-by-copy. */
+    snapshot() {
+        return { ...this.#state };
+    }
+    get persisted() {
+        return this.#state.persisted;
+    }
+    get applied() {
+        return this.#state.applied;
+    }
+    get acked() {
+        return this.#state.acked;
+    }
+    /** THE value snapshots/claims stamp as `readAt`. */
+    get readFloor() {
+        return Math.max(this.#state.applied, this.#state.acked);
+    }
+    /** Deltas through `syncId` have COMMITTED to IndexedDB. Persisting
+     *  implies applied — the flush path applies before/with persisting. */
+    advancePersisted(syncId) {
+        this.#state = advance(this.#state, { persisted: syncId, applied: syncId });
+    }
+    /** A delta was APPLIED to the in-memory pool. */
+    advanceApplied(syncId) {
+        this.#state = advance(this.#state, { applied: syncId });
+    }
+    /** The server acked one of OUR commits at this watermark. */
+    noteAck(lastSyncId) {
+        if (lastSyncId !== undefined)
+            this.#state = advance(this.#state, { acked: lastSyncId });
+    }
+    /** Restore from a VALIDATED snapshot (e.g. IDB resume). Monotonic. */
+    restore(snapshot) {
+        this.#state = advance(this.#state, snapshot);
+    }
+}

package/dist/transactions/TransactionQueue.d.ts

@@ -10,6 +10,7 @@
 import { EventEmitter } from 'events';
 import type { Database } from '../Database.js';
 import { Model } from '../Model.js';
+import { SyncPosition } from '../sync/syncPosition.js';
 import type { WriteOptions } from '../interfaces/index.js';
 export interface UserContext {
     userId: string;
@@ -82,6 +83,8 @@ interface ConflictResolution {
     resolver?: (local: MutationInput | undefined, remote: MutationInput) => MutationInput;
 }
 interface TransactionQueueConfig {
+    /** Shared client position (see sync/syncPosition.ts). One per client. */
+    position?: SyncPosition;
     maxBatchSize: number;
     batchDelay: number;
     maxRetries: number;
@@ -140,7 +143,17 @@ export declare class TransactionQueue extends EventEmitter {
     private deltaConfirmationRetries;
     private isConnectedFn;
     private commitOfflineGraceTimer;
-    private lastSeenSyncId;
+    /**
+     * THE client's place in the global delta order — the SHARED instance
+     * (injected by SyncClient; standalone construction gets its own). The
+     * queue advances `acked` on commit responses; the store advances
+     * `applied`/`persisted`; snapshots/claims read `readFloor`. Contract +
+     * rationale live in `sync/syncPosition.ts`.
+     */
+    readonly position: SyncPosition;
+    /** Applied-cursor alias, kept so the many internal read sites stay legible. */
+    private get lastSeenSyncId();
+    private noteAck;
     private static readonly DELTA_MAX_RETRIES;
     private static readonly DELTA_INITIAL_TIMEOUT_MS;
     private static readonly DELTA_MAX_TIMEOUT_MS;
@@ -414,6 +427,8 @@ export declare class TransactionQueue extends EventEmitter {
         totalTransactions: number;
         batchIndex: number;
         config: {
+            /** Shared client position (see sync/syncPosition.ts). One per client. */
+            position?: SyncPosition;
             maxBatchSize: number;
             batchDelay: number;
             maxRetries: number;

package/dist/transactions/TransactionQueue.js

@@ -13,6 +13,7 @@ import { getActiveRegistry } from '../ModelRegistry.js';
 import { MutationOperationType } from '../types/index.js';
 import { handleMutationError } from './mutation-error-handler.js';
 import { AbloError, AbloConnectionError, errorCodeSpec } from '../errors.js';
+import { SyncPosition } from '../sync/syncPosition.js';
 /**
  * Framework-internal keys added by `Model.toJSON()` that must never
  * reach the wire. The server treats each top-level key as a target
@@ -323,10 +324,21 @@ export class TransactionQueue extends EventEmitter {
     // cleared on `'connected'`. The reconnect-retry behavior of the queue
     // is preserved for brief blips; this only catches persistent disconnects.
     commitOfflineGraceTimer = null;
-    // Track the highest syncId received from WebSocket deltas
-    // Used to immediately confirm transactions when HTTP response arrives AFTER the delta
-    // (fixes race condition where WebSocket delta arrives before HTTP response)
-    lastSeenSyncId = 0;
+    /**
+     * THE client's place in the global delta order — the SHARED instance
+     * (injected by SyncClient; standalone construction gets its own). The
+     * queue advances `acked` on commit responses; the store advances
+     * `applied`/`persisted`; snapshots/claims read `readFloor`. Contract +
+     * rationale live in `sync/syncPosition.ts`.
+     */
+    position;
+    /** Applied-cursor alias, kept so the many internal read sites stay legible. */
+    get lastSeenSyncId() {
+        return this.position.applied;
+    }
+    noteAck(lastSyncId) {
+        this.position.noteAck(lastSyncId);
+    }
     // Delta confirmation retry config (Replicache-style exponential backoff)
     // Max retries before requesting full reconciliation
     static DELTA_MAX_RETRIES = 5;
@@ -346,6 +358,7 @@ export class TransactionQueue extends EventEmitter {
     confirmationResolvers = new Map();
     constructor(config) {
         super();
+        this.position = config?.position ?? new SyncPosition();
         if (config) {
             this.config = { ...this.config, ...config };
         }
@@ -972,6 +985,7 @@ export class TransactionQueue extends EventEmitter {
                         // the coalescing test's tight bound on batch count.
                         const result = await this.mutationExecutor.commit(operations);
                         const lastSyncId = result?.lastSyncId ?? 0;
+                        this.noteAck(lastSyncId);
                         // Detect server bug: lastSyncId 0 means mutation succeeded but no sync delta was emitted
                         if (lastSyncId === 0) {
                             getContext().observability.captureCommitZeroSyncId({
@@ -999,34 +1013,44 @@ export class TransactionQueue extends EventEmitter {
                                 });
                                 continue;
                             }
-                            // FIX: Check if delta already arrived before HTTP response (race condition)
-                            // WebSocket can be faster than HTTP, so the delta might already be here
-                            // Guard: only do immediate confirm if lastSyncId > 0 (valid server response)
-                            if (lastSyncId > 0 && this.lastSeenSyncId >= lastSyncId) {
-                                // Delta already arrived! Confirm immediately without timeout
+                            // ACK-BASED CONFIRMATION. A successful commit response with a
+                            // real watermark means the server durably applied the write —
+                            // that IS the confirmation (the documented `wait: 'confirmed'`
+                            // contract, and how Replicache/Zero treat the push response's
+                            // lastMutationID). The delta echo is NOT an acknowledgement
+                            // channel: it's replication for OTHER clients, and this
+                            // client's own echo is suppressed by the OptimisticEchoTracker
+                            // anyway. Gating confirmation on the echo coupled "did my
+                            // write land" to subscription-stream health — a bare-Node
+                            // client with no live delta stream hung forever in
+                            // `awaiting_delta` on a write the server had already applied.
+                            if (lastSyncId > 0) {
                                 this.store.updateStatus(tx.id, 'completed');
                                 this.emit('transaction:completed', tx);
                                 this.emit(`transaction:completed:${tx.id}`, tx);
                                 this.optimisticUpdates.delete(tx.id);
-                                getContext().logger.debug('tx:confirm_immediate', {
+                                getContext().logger.debug('tx:confirm_ack', {
                                     txId: tx.id.slice(0, 8),
                                     model: tx.modelName,
-                                    neededSyncId: lastSyncId,
+                                    serverSyncId: lastSyncId,
                                     lastSeenSyncId: this.lastSeenSyncId,
-                                    reason: 'delta_arrived_before_http',
                                 });
                             }
                             else {
-                                // Delta hasn't arrived yet, wait for it
+                                // lastSyncId === 0 on a non-DELETE: the server accepted the
+                                // commit but emitted no delta — a server-side anomaly
+                                // (already captured via captureCommitZeroSyncId above). Keep
+                                // the delta-wait + reconciliation timeout for THIS case
+                                // only, so the anomaly surfaces instead of silently
+                                // confirming a write with no watermark.
                                 this.store.updateStatus(tx.id, 'awaiting_delta');
                                 getContext().logger.debug('tx:awaiting_delta', {
                                     txId: tx.id.slice(0, 8),
                                     model: tx.modelName,
                                     neededSyncId: lastSyncId,
                                     lastSeenSyncId: this.lastSeenSyncId,
-                                    gap: lastSyncId - this.lastSeenSyncId,
+                                    reason: 'zero_sync_id_anomaly',
                                 });
-                                // Schedule timeout-based rollback for unconfirmed transactions
                                 this.scheduleDeltaConfirmationTimeout(tx, this.config.deltaConfirmationTimeout);
                             }
                         }
@@ -1153,16 +1177,9 @@ export class TransactionQueue extends EventEmitter {
      * @param syncId - The sync ID of the received delta
      */
     onDeltaReceived(syncId) {
-        const prevLastSeen = this.lastSeenSyncId;
-        // Track highest syncId seen (fixes race: delta arrives before HTTP response)
-        if (syncId > this.lastSeenSyncId) {
-            this.lastSeenSyncId = syncId;
-            getContext().logger.debug('tx:highwater_update', {
-                prev: prevLastSeen,
-                new: syncId,
-                delta: syncId - prevLastSeen,
-            });
-        }
+        // Cursor advancing happens where the delta is APPLIED (the store calls
+        // position.advanceApplied / advancePersisted); this hook only resolves
+        // confirmation thresholds against the incoming id.
         const awaitingTxs = this.store.getByStatus('awaiting_delta');
         const executingTxs = this.store.getByStatus('executing');
         // Debug: Show state when delta arrives
@@ -1409,6 +1426,7 @@ export class TransactionQueue extends EventEmitter {
                         causedByTaskId: tx.causedByTaskId ?? undefined,
                     });
                     tx.lastSyncId = result?.lastSyncId ?? 0;
+                    this.noteAck(tx.lastSyncId);
                     tx.status = 'completed';
                     this.commitLane.shift();
                     this.emit('transaction:completed', tx);

package/docs/api-keys.md

@@ -23,7 +23,7 @@ Use API keys from trusted (server-side) runtimes:
 
 Never ship a secret API key to a browser bundle.
 
-## Test mode and sandboxes
+## Sandboxes and production
 
 Test and live keys are the same shape; the prefix names the environment:
 
@@ -31,11 +31,11 @@ Test and live keys are the same shape; the prefix names the environment:
   to that sandbox and are invisible to live keys (and to other sandboxes).
 - `sk_live_…` — a key against your live data.
 
-Every org has a default **Test mode** sandbox, plus any number of additional
+Every org has a default sandbox, plus any number of additional
 sandboxes you create. **Data is isolated per sandbox; the schema is shared
 across the whole org.** A schema you push from a test key defines the same
 models your live keys see — only the rows differ. This mirrors how Stripe
-separates test and live data while keeping the API shape identical.
+separates sandbox and production data while keeping the API shape identical.
 
 ## Scopes
 
@@ -51,7 +51,7 @@ restricted to exactly those grants:
 - `sandbox:<id>` — identifies which sandbox the key belongs to. (The key's data
   isolation comes from that sandbox binding, not from this scope string.)
 
-A key minted from the default **Test mode** sandbox carries `schema:push`, so
+A key minted from the default sandbox carries `schema:push`, so
 `ablo dev` works out of the box. Keys from other sandboxes are **data-only** by
 default — enable "schema authoring" when minting if you want that key to push
 schema too. Hand data-only keys to embedded apps and CI agents; reserve

package/docs/cli.md

@@ -32,7 +32,7 @@ mirrors `stripe login`.
 | `ablo login`             | Authorize in the browser; provisions + stores a test and a live key.       |
 | `ablo logout`            | Remove the stored keys.                                                    |
 | `ablo status`            | Show the active org, mode, both keys (prefix + expiry), and server health. |
-| `ablo mode [test\|live]` | Switch the active mode. With no argument, prompts.                         |
+| `ablo mode [sandbox\|production]` | Switch the active environment. With no argument, prompts.                         |
 
 Keys are stored in `~/.config/ablo/config.json` (mode `0600`). In **CI**, don't
 log in — set `ABLO_API_KEY`, which always overrides the stored key.
@@ -41,11 +41,11 @@ log in — set `ABLO_API_KEY`, which always overrides the stored key.
 
 Like Stripe, every account has a **test** mode and a **live** mode, and a key
 belongs to one of them. Test keys are bound to an isolated sandbox: their reads
-and writes never touch live data. Switch with `ablo mode`; `ablo dev` is always
-test mode by design.
+and writes never touch production data. Switch with `ablo mode`; `ablo dev` is always
+the sandbox by design.
 
 The schema, however, is **shared** across the org — pushing a schema (from
-either mode) defines the same models test and live see; only the rows differ.
+either environment) defines the same models sandbox and production see; only the rows differ.
 
 ## Commands
 
@@ -53,9 +53,9 @@ either mode) defines the same models test and live see; only the rows differ.
 | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
 | `ablo init`                        | Scaffold `ablo/` (`schema.ts`, client, optional Data Source / agent / component), write `.env`, install the SDK. Offers to log in at the end. | —                                                                                                      |
 | `ablo login` / `logout` / `status` | Authentication & status (above).                                                                                                              | —                                                                                                      |
-| `ablo mode [test\|live]`           | Switch active mode.                                                                                                                           | —                                                                                                      |
+| `ablo mode [sandbox\|production]`   | Switch active environment.                                                                                                                           | —                                                                                                      |
 | `ablo dev`                         | **Hosted** — push the schema to your test sandbox, then watch `ablo/schema.ts` and re-push on save.                                           | `--no-watch`, `--schema <path>`, `--export <name>`, `--url <url>`                                      |
-| `ablo logs`                        | Tail your scope's commit activity (`stripe logs tail`). Follows by default.                                                                   | `-n, --tail <N>`, `--since <dur\|ts>`, `--model`, `--op`, `--json`, `--no-follow`, `--mode test\|live` |
+| `ablo logs`                        | Tail your scope's commit activity (`stripe logs tail`). Follows by default.                                                                   | `-n, --tail <N>`, `--since <dur\|ts>`, `--model`, `--op`, `--json`, `--no-follow`, `--mode sandbox\|production` |
 | `ablo push`                        | **Hosted** — upload the schema to Ablo; the server diffs, migrates, and activates it.                                                         | `--force`, `--rename old:new`, `--backfill model.field=value`, `--schema`, `--export`, `--url`         |
 | `ablo migrate`                     | **Direct Postgres** — provision just the synced models (plus the adapter's `ablo_outbox` / `ablo_idempotency`) in your own `DATABASE_URL`. Leaves your other tables alone.                                                          | `--dry-run`, `--output <file>`, `--schema`, `--export`                                                 |
 | `ablo pull`                        | **Direct Postgres** — generate `defineSchema(...)` from your existing tables (read-only, like `prisma db pull`).                              | `--out <path>`, `--app-schema <name>`, `--import <pkg>`, `--force`                                     |

package/docs/quickstart.md

@@ -87,7 +87,7 @@ from `Ablo(...)`.
 ```bash
 npx ablo migrate   # creates your synced-model tables (with row-level security)
                    # in YOUR database — your other tables are left untouched
-npx ablo dev       # pushes the schema (test mode), writes ABLO_API_KEY to
+npx ablo dev       # pushes the schema (sandbox), writes ABLO_API_KEY to
                    # .env.local, and re-pushes on every save — the dev loop
 ```
 

package/llms-full.txt

@@ -144,8 +144,11 @@ its service layer and DB credentials. Ablo gets a Data Source endpoint and uses
 
 ## Client Behavior
 
-Important options: `schema`, `apiKey`, `baseURL`, `persistence`, `fetch`,
-`defaultHeaders`, `defaultQuery`, `logger`, and `dangerouslyAllowBrowser`.
+The options that matter: `schema` and `apiKey`. Everything else
+(`persistence`, `logger`, transport tuning) has correct defaults — do NOT set
+`baseURL`; the default already routes to the hosted API, and overriding it
+breaks the connection. It exists only for self-hosted/proxy setups the human
+explicitly asks for.
 
 There is intentionally no `databaseURL` option on `Ablo(...)`. Application and
 agent code use `ABLO_API_KEY`. Customer-owned app databases stay private behind
@@ -171,7 +174,7 @@ There are two sandbox surfaces:
   making real Ablo calls. It is agent-first: it should expose a prompt that can
   be pasted into Claude Code or Codex to wire one real model through Ablo.
 - Authenticated org sandboxes are real test environments. The default sandbox is
-  the Stripe-style test mode for an org. It has an isolated sync group prefix,
+  the Stripe-style sandbox for an org. It has an isolated sync group prefix,
   can mint `sk_test_*` keys, and can be reset without touching live state.
 
 Additional org sandboxes can start blank or copy live configuration. Keep
@@ -190,8 +193,10 @@ Use these public environment names:
 - `ABLO_API_KEY` — SDK authentication for app and agent code. Where it comes
   from: the human runs `npx ablo login` once (browser; an agent must not run
   it), and `npx ablo dev` then writes `ABLO_API_KEY=sk_test_…` into
-  `.env.local` automatically. Check the environment and `.env.local` before
-  asking the human for a key.
+  `.env.local` automatically (and gitignores it). Check the environment and
+  `.env.local` for PRESENCE only (`grep -cq '^ABLO_API_KEY=' .env.local`)
+  before asking the human for a key — never print or echo the key value; a
+  secret in agent output lives in the conversation history forever.
 
 Do not ask customers to paste their app database URL into Ablo. If their app
 database is canonical, they expose a Data Source endpoint and keep database