@abloatai/ablo 0.16.3 → 0.18.0

package/CHANGELOG.md

@@ -1,5 +1,72 @@
 # Changelog
 
+## 0.18.0
+
+### Minor Changes
+
+- **Client observability — `debug` / `logLevel`, off by default.** The SDK used to
+  emit a `debug` line per model and per property during schema registration (a
+  firehose). It now defaults to a quiet `warn` threshold and exposes two new
+  `Ablo()` options to opt back in:
+  - `logLevel: 'debug' | 'info' | 'warn' | 'error' | 'silent'` — `'info'` surfaces
+    coordination and connection events without the per-model registration noise;
+    `'debug'` is everything. Precedence: explicit `logLevel` → `debug: true` →
+    `ABLO_LOG_LEVEL` env → default `warn`. Supplying your own `logger` bypasses both.
+  - `debug: boolean` — shorthand for `logLevel: 'debug'`.
+
+  Coordination is now traceable at `info`: claims that are **rejected** or **lost**
+  (preempted/expired), and your position **advancing in a claim queue**, each log
+  once per change with a readable target (`documents:abc.title`) — quiet lowercase
+  lines, no shouty tags.
+
+  **New: canonical wire-egress contract export.** `errorEnvelope`, `statusForType`,
+  and the `ErrorEnvelope` type are now exported from the package root. Server
+  consumers (e.g. a self-hosted sync server) can assert against the one source of
+  truth for the error-envelope shape and the `AbloError`-subclass→HTTP-status
+  table instead of keeping a copy that silently drifts.
+
+  **Structured CLI error rendering.** CLI failures render as a titled block with a
+  reason code and per-code remediation (`--verbose` for the stack) instead of a
+  console wall-of-text; `AbloError.toString()` produces a leak-proof one-liner.
+
+  **`ABLO_API_KEY` resolution + sandbox key scopes.** The key is now resolved from
+  `.env.local` / `.env` (not just the process env), and sandbox keys are granted
+  `schema:push` by default so `ablo push` works out of the box in a fresh sandbox.
+
+## 0.17.0
+
+### Minor Changes
+
+- **Bring-your-own database is now one model.** Ablo connects to your Postgres and
+  never operates it. There used to be two confusing BYO paths, and the
+  connection-string one would create roles, force row-level security, transfer
+  table ownership, and push you to run `ablo migrate` before anything worked. That
+  cascade is gone. Ablo now follows the shape every serious "sync over your own
+  Postgres" engine uses (ElectricSQL, PowerSync, Zero): it reads your database via
+  Postgres logical replication and never runs DDL, creates roles, forces RLS, or
+  rewrites your `DATABASE_URL`. You own your schema; Ablo reads it.
+  - **New: `ablo connect`.** One command prints the exact, copy-pasteable setup for
+    your own Postgres — enable `wal_level=logical`, create the `ablo_publication`
+    publication and a least-privilege `ablo_replicator` role — and
+    `ablo connect --check` validates readiness (wal level, publication, replication
+    grant, replica identity). This is the single supported way to connect a real
+    database.
+  - **`ablo migrate` left the happy path.** It no longer creates roles, transfers
+    ownership, or rewrites your connection string, and `ablo dev` no longer attempts
+    a scoped-role creation on every watch loop. `migrate` is now an optional escape
+    hatch for generating starter DDL (`--dry-run` prints the SQL).
+  - **Clearer failures.** `ablo push` permission errors lead with the server's actual
+    reason code and per-code remediation instead of a generic "needs `schema:push`
+    scope," and the schema-conflict message names which environment/version a prior
+    push came from and when.
+  - **Logical-replication runtime is in Preview.** The setup (`ablo connect`) and the
+    connection model are live; the server-side WAL consumer that streams your changes
+    is implemented and journey-tested but not yet generally available.
+
+  The previous connection-string-operate and adapter/outbox modes are demoted to a
+  clearly-labeled **Legacy / not recommended** section — they still work, but new
+  integrations should use logical replication.
+
 ## 0.16.3
 
 ### Patch Changes

package/dist/BaseSyncedStore.d.ts

@@ -505,10 +505,11 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
      *   1. REACTIVE — register `getToken` as the re-mint hook the FSM calls when a
      *      probe finds the key stale (`credential_stale`) or on a nudge.
      *   2. PROACTIVE — keep the short-lived key fresh ahead of trouble: a refresh
-     *      timer inside the TTL, plus re-mint on OS wake / network-online / tab
-     *      focus. Browser-only triggers are env-gated, so Node/agent hosts get
-     *      only the timer (a no-op there — agents use a static `apiKey`, no
-     *      resolver, so this is never called for them).
+     *      timer inside the TTL, plus re-mint on OS wake. The ENTIRE proactive
+     *      block is browser-gated (`typeof window`): server/SSR has no socket to
+     *      keep warm and the resolver is browser-oriented, so arming it in Node
+     *      would fire a relative-URL fetch and throw. (Agents pass a static
+     *      `apiKey` with no resolver, so this method is never called for them.)
      *
      * Config-driven and invisible, like Supabase's `autoRefreshToken` — consumers
      * never call a refresh method. Idempotent (a second call replaces the first);
@@ -702,7 +703,9 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
      * sync-group mutations). Does NOT schedule a flush — callers decide
      * whether to debounce (live) or flush atomically (catch-up frame).
      */
-    protected enqueueDelta(delta: SyncDelta): boolean;
+    protected enqueueDelta(delta: SyncDelta, options?: {
+        authoritative?: boolean;
+    }): boolean;
     /** Debounce a flush for live single-delta traffic. */
     protected scheduleDeltaFlush(): void;
     /**

package/dist/BaseSyncedStore.js

@@ -739,9 +739,21 @@ export class BaseSyncedStore {
                 // A throw = transient (offline / mint endpoint unreachable / 5xx). The
                 // login may be perfectly valid; never sign out for this — back off and
                 // retry. Mirrors the `getToken` throw-vs-null contract end-to-end.
-                getContext().logger.warn('[BaseSyncedStore] Access-credential re-mint failed (transient)', {
-                    error: error?.message,
-                });
+                const message = error?.message ?? String(error);
+                // A relative-URL resolver invoked server-side (Node fetch has no origin
+                // to resolve against) emits the opaque "Failed to parse URL" / "Only
+                // absolute URLs are supported". Translate it into something actionable
+                // instead of a mystery transient blip — the proactive refresh is now
+                // browser-only, so hitting this means the resolver fired from SSR/RSC or
+                // a server route.
+                if (typeof window === 'undefined' && /parse URL|absolute URLs?/i.test(message)) {
+                    getContext().logger.warn('credential resolver ran on the server with a relative URL — Node fetch needs an absolute URL. ' +
+                        'Refresh the Ablo client in the browser, or build an absolute URL server-side ' +
+                        "(e.g. new URL('/api/ablo-session', process.env.NEXT_PUBLIC_APP_URL)).", { error: message });
+                }
+                else {
+                    getContext().logger.warn('access-credential re-mint failed (transient)', { error: message });
+                }
                 return 'network_error';
             }
         })();
@@ -769,10 +781,11 @@ export class BaseSyncedStore {
      *   1. REACTIVE — register `getToken` as the re-mint hook the FSM calls when a
      *      probe finds the key stale (`credential_stale`) or on a nudge.
      *   2. PROACTIVE — keep the short-lived key fresh ahead of trouble: a refresh
-     *      timer inside the TTL, plus re-mint on OS wake / network-online / tab
-     *      focus. Browser-only triggers are env-gated, so Node/agent hosts get
-     *      only the timer (a no-op there — agents use a static `apiKey`, no
-     *      resolver, so this is never called for them).
+     *      timer inside the TTL, plus re-mint on OS wake. The ENTIRE proactive
+     *      block is browser-gated (`typeof window`): server/SSR has no socket to
+     *      keep warm and the resolver is browser-oriented, so arming it in Node
+     *      would fire a relative-URL fetch and throw. (Agents pass a static
+     *      `apiKey` with no resolver, so this method is never called for them.)
      *
      * Config-driven and invisible, like Supabase's `autoRefreshToken` — consumers
      * never call a refresh method. Idempotent (a second call replaces the first);
@@ -807,14 +820,25 @@ export class BaseSyncedStore {
             // 'network_error' → transient (offline / mint hiccup); the next timer tick
             // or the FSM's own probe retries. Never sign out for it.
         };
-        // Comfortably inside the 15m `ek_` TTL; a missed (background-throttled) tick
-        // is recovered by the next, or by the reactive probe. The timer is the sole
-        // proactive PRE-ROLL — it keeps the key warm ahead of expiry even while the
-        // socket sits healthy-`connected` (a state the FSM never probes unprompted).
-        const REFRESH_INTERVAL_MS = 10 * 60 * 1000;
-        const timer = setInterval(() => void refresh(), REFRESH_INTERVAL_MS);
-        const teardowns = [() => clearInterval(timer)];
+        const teardowns = [];
+        // The ENTIRE proactive pre-roll is BROWSER-ONLY. On the server (Next.js
+        // SSR/RSC evaluating the `providers` module) there is no live socket to keep
+        // warm AND the scaffolded credential resolver is browser-oriented (a
+        // relative-URL `fetch('/api/ablo-session')`). Arming the timer server-side
+        // fires that resolver in Node, where fetch has no origin to resolve a
+        // relative URL against → "Failed to parse URL" on every tick. Browser-only
+        // refresh is the unanimous vendor model (Supabase `autoRefreshToken: isBrowser()`,
+        // Clerk/Ably/Stripe refresh client-side). The reactive re-mint hook
+        // (`setCredentialRefresher` above) stays UNCONDITIONAL: it only fires on a
+        // real connection probe, which can't happen during a bare SSR module eval.
         if (typeof window !== 'undefined') {
+            // Comfortably inside the 15m `ek_` TTL; a missed (background-throttled)
+            // tick is recovered by the next, or by the reactive probe. The timer is
+            // the sole proactive PRE-ROLL — it keeps the key warm ahead of expiry even
+            // while the socket sits healthy-`connected` (a state the FSM never probes).
+            const REFRESH_INTERVAL_MS = 10 * 60 * 1000;
+            const timer = setInterval(() => void refresh(), REFRESH_INTERVAL_MS);
+            teardowns.push(() => clearInterval(timer));
             // OS-wake (desktop only): the Electron shell bridges `powerMonitor`
             // 'resume' to this DOM event. This is the ONE event-trigger the lifecycle
             // still owns, because `visibilitychange` does NOT fire on wake-from-sleep
@@ -1713,7 +1737,25 @@ export class BaseSyncedStore {
     applyDeltaFrame(deltas) {
         let enqueuedAny = false;
         for (const delta of deltas) {
-            if (this.enqueueDelta(delta))
+            // A delta_batch frame is the server's AUTHORITATIVE, ordered answer to
+            // "everything in my stream after cursor C" (reconnect/catch-up replay or
+            // post-bootstrap drain). Apply every delta it carries — do NOT subject it
+            // to the live-traffic watermark dedup (`id <= applied`).
+            //
+            // That watermark is only valid under in-order delivery, and reconnect
+            // breaks the assumption: an in-flight LIVE broadcast for a gap delta can
+            // land out of order BEFORE the catch-up fills the ids below it (e.g. the
+            // server acks a write, then the test/client reconnects, then that write's
+            // pending broadcast arrives on the fresh socket — id 4 live before the
+            // catch-up's [2,3,4]). Applying id 4 advances `applied` to 4, and the
+            // watermark would then drop 2 and 3 from the catch-up as "already seen" —
+            // a poisoned gap and a cursor that lies (applied=4 with rows 2,3 absent).
+            //
+            // Re-applying a delta the live path already applied is safe: the
+            // downstream `Database.processDeltaBatch` + `SyncClient.applyDeltaBatchToPool`
+            // are idempotent (echo detection, no row resurrection, conflict
+            // resolution), so the redundant id 4 is a no-op while 2 and 3 land.
+            if (this.enqueueDelta(delta, { authoritative: true }))
                 enqueuedAny = true;
         }
         if (!enqueuedAny)
@@ -1734,10 +1776,15 @@ export class BaseSyncedStore {
      * sync-group mutations). Does NOT schedule a flush — callers decide
      * whether to debounce (live) or flush atomically (catch-up frame).
      */
-    enqueueDelta(delta) {
-        // Dedup guard — skip already-processed deltas
-        if (delta.id > 0 && delta.id <= this.highestProcessedSyncId)
+    enqueueDelta(delta, options = {}) {
+        // Dedup guard — skip already-processed deltas. The `applied` watermark is a
+        // valid skip threshold ONLY for in-order live traffic; an authoritative
+        // catch-up frame bypasses it (see `applyDeltaFrame`) so an out-of-order
+        // live delta that advanced the watermark can't cause the frame's lower ids
+        // to be silently dropped.
+        if (!options.authoritative && delta.id > 0 && delta.id <= this.highestProcessedSyncId) {
             return false;
+        }
         // Confirm awaiting transactions via sync ID threshold (before batching)
         this.syncClient.onDeltaReceived(delta.id);
         // Update version vector

package/dist/NetworkMonitor.js

@@ -31,7 +31,9 @@ export class NetworkMonitor extends EventEmitter {
         const wasOnline = this.isOnline;
         this.isOnline = false;
         if (wasOnline) {
-            getContext().logger.warn('Network connection lost');
+            // Symmetric with 'Network connection restored' (info) — expected,
+            // transient connectivity state, not an actionable warning.
+            getContext().logger.info('Network connection lost');
             this.emit('offline');
         }
     };