@abloatai/ablo 0.12.0 → 0.14.0

package/AGENTS.md

@@ -31,7 +31,7 @@ Every model verb takes ONE options object. The common loop:
 
 1. **Read** the row — `await ablo.<model>.retrieve({ id })` (async; from the server) or `await ablo.<model>.list({ where })` for many. In React render, read synchronously with `useAblo((a) => a.<model>.get(id))`.
 2. **See who's active** (optional) — `ablo.<model>.claim.state({ id })` (synchronous; never blocks).
-3. **Claim** the row before changing it — `await using claim = await ablo.<model>.claim({ id, action?, ttl? })`. If someone else holds it, this waits for them, then gives you the fresh row on `claim.data`. The claim auto-releases when it goes out of scope (`await using`).
+3. **Claim** the row before changing it — `await using claim = await ablo.<model>.claim({ id, reason?, ttl? })`. If someone else holds it, this waits for them, then gives you the fresh row on `claim.data`. The claim auto-releases when it goes out of scope (`await using`).
 4. **Write** — `await ablo.<model>.update({ id: claim.data.id, data })`. Because you hold the claim, the write is rejected if the row changed underneath you.
 
 Keep coding assistants on this schema-backed path.
@@ -59,7 +59,7 @@ if (!report) throw new Error('Report not found');
 // row before resolving. Auto-released at the end of this scope (`await using`).
 await using claim = await ablo.weatherReports.claim({
   id: 'report_stockholm',
-  action: 'forecasting',
+  reason: 'forecasting',
   ttl: '2m',
 });
 const claimed = claim.data;

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 0.14.0
+
+### Minor Changes
+
+- Claim API consistency + coordination docs
+  - **React:** document `useWatch` (scoped presence + read-interest, with `claim`/`hydrate`/`paused` options) and `usePeers` (read-only presence) — previously exported but undocumented.
+  - **HTTP claim surface:** `HttpClaimApi` is now a mechanically derived async projection of the reactive `ClaimApi` (`AwaitedClaimMethod`), so the two transports can never drift. No behavior change — the only difference remains the `Promise` wrapper that statelessness forces on `state`/`queue`/`reorder`.
+  - **Naming:** unified the claim read verb to `state` across every layer (the internal `ModelCollaboration.observe` is now `state`, matching the public `ablo.<model>.claim.state({ id })`).
+  - **Docs:** corrected the `Claim` object reference — the field is `reason` (serialized on the wire as `action`), and `createdAt`/`expiresAt` are `number` (epoch-ms), not strings; corrected the claim options to `reason` and `queue`.
+
+## 0.13.0
+
+### Minor Changes
+
+- Schema authoring: split model routing into two orthogonal axes — `policy` (row access) and `groups` (sync-group routing).
+
+  **Breaking (schema authoring).** The flat, collision-prone model options are replaced by two namespaced ones:
+  - **`policy`** — row-access / tenant isolation (named after Postgres/Supabase RLS policies: the rule that scopes which rows a tenant may read). A discriminated union on `by` replaces the old `orgScoped` / `scopedVia` / `orgColumn` trio:
+    - `{ by: 'column' }` — row-local tenancy column (the default when omitted; column name still overridable).
+    - `{ by: 'parent', fk, parent }` — inherit tenancy through a foreign key when the table has no tenancy column of its own (e.g. `slide_layers` → `slides`).
+    - Type `TenancyInput` is renamed `PolicyInput`; `policyInputSchema` / `resolvePolicy` are now exported.
+  - **`groups: { root, grants, roles }`** — which delta channels a row fans into (orthogonal to `policy`, which governs read access). One namespaced object replaces the old flat `scope` / `grants` / `entityRoles`:
+    - `root` (was `scope`) — mark a model a scope root; its records form the group `<kind>:<id>`. Renamed so it no longer collides with the old `scopedVia` tenancy sugar or the inner `grants.scope` relation name.
+    - `grants` — a membership edge granting an identity access to a scope root.
+    - `roles` (was `entityRoles`) — explicit non-relational record→group roles; accepts one role or an array.
+    - `groupsInputSchema` / `GroupsInput` are now exported.
+
+  **CLI.** `config.json` now stores per-project profile key pairs (`profiles: Record<string, ProfileKeys>`) instead of a single top-level pair; older flat layouts are folded into the active profile automatically on read, so existing logins keep working. `login` / `projects` updated to the profile model.
+
 ## 0.12.0
 
 ### Minor Changes

package/README.md

@@ -274,7 +274,7 @@ ablo.weatherReports.claim.state({ id: 'report_stockholm' });
 ablo.weatherReports.claim.queue({ id: 'report_stockholm' });
 
 {
-  await using claim = await ablo.weatherReports.claim({ id, wait: false });
+  await using claim = await ablo.weatherReports.claim({ id, queue: false });
   /* do the held work */
 }
 
@@ -285,11 +285,11 @@ ablo.weatherReports.claim.queue({ id: 'report_stockholm' });
 ```
 
 `claim.state` returns the holder (or `null`); `claim.queue` returns the line waiting
-behind it. `wait: false` skips rather than waiting when the row is held;
+behind it. `queue: false` skips rather than waiting when the row is held;
 `maxQueueDepth: 2` bails when two or more are already ahead.
 
 Default reads keep working while a row is claimed. Server reads that need claimed
-semantics can opt in with `ifClaimed: 'return' | 'wait' | 'fail'`.
+semantics can opt in with `ifClaimed: 'return' | 'fail'`.
 
 Even an unclaimed write can't land on stale reasoning — the commit is guarded:
 

package/dist/BaseSyncedStore.js

@@ -781,47 +781,54 @@ export class BaseSyncedStore {
     startCredentialLifecycle(getToken) {
         this.stopCredentialLifecycle();
         this.setCredentialRefresher(getToken);
-        // A transient failure is swallowed: the engine keeps its current token and
-        // the next trigger — or the reactive `credential_stale` path — retries. We
-        // never tear down or sign out on a failed proactive roll.
+        // Re-mint through the SAME single-flight path the FSM's reactive probe uses
+        // (`performCredentialRefresh`) rather than calling `getToken()` directly. Two
+        // wins over the old direct call:
+        //   - SINGLE-FLIGHT: a wake nudge, an in-flight probe, and this proactive
+        //     roll share one in-flight promise — no double-mint thrash.
+        //   - The tri-state is HONOURED. The old code did `if (token) {…}` and
+        //     dropped a `null` on the floor — a zombie session that re-minted on
+        //     every tab focus and logged "signing out" forever without ever signing
+        //     out. `session_error` now drives the FSM to actually expire.
         const refresh = async () => {
-            try {
-                const token = await getToken();
-                if (token) {
-                    // Push into the shared credential source (read lazily by bootstrap
-                    // HTTP, probes, and the WS reconnect URL), then nudge a parked
-                    // connection to re-probe with the fresh key. Same two steps the
-                    // engine's `setAuthToken` wrapper performs.
-                    this.auth?.setAuthToken(token);
-                    this.nudgeReconnect();
-                }
+            const outcome = await this.performCredentialRefresh();
+            if (outcome === 'refreshed') {
+                // Fresh key already pushed into the credential source by
+                // `performCredentialRefresh`; nudge a parked connection to re-probe.
+                this.nudgeReconnect();
             }
-            catch {
-                // transient (offline / mint hiccup) — a later trigger retries.
+            else if (outcome === 'session_error') {
+                // The long-lived login is gone (mint answered 401/403). Surface it —
+                // the proactive path's job is to report this, not hide it. A no-op in
+                // FSM states that don't accept the event (the probe converges on
+                // sign-out there anyway); `session_expired`'s onEnter owns the log.
+                this.connectionManager?.send({ type: 'BOOTSTRAP_FAILED_SESSION' });
             }
+            // '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.
+        // 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)];
         if (typeof window !== 'undefined') {
-            const onTrigger = () => void refresh();
-            window.addEventListener('online', onTrigger);
-            // OS-wake: the desktop shell bridges Electron `powerMonitor` 'resume' to
-            // this DOM event (visibilitychange does NOT fire on wake-from-sleep, so a
-            // nap longer than the TTL would otherwise leave a dead key untouched).
-            window.addEventListener('ablo:wake', onTrigger);
-            teardowns.push(() => window.removeEventListener('online', onTrigger));
-            teardowns.push(() => window.removeEventListener('ablo:wake', onTrigger));
-        }
-        if (typeof document !== 'undefined') {
-            const onVisible = () => {
-                if (document.visibilityState === 'visible')
-                    void refresh();
-            };
-            document.addEventListener('visibilitychange', onVisible);
-            teardowns.push(() => document.removeEventListener('visibilitychange', onVisible));
+            // 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
+            // and — unlike `online`/`visibilitychange` — the ConnectionManager's own
+            // browser listeners (`setupBrowserListeners`) don't cover wake.
+            //
+            // The `online` and `visibilitychange` listeners that used to live here
+            // were REMOVED: the FSM already re-probes on NETWORK_ONLINE / TAB_VISIBLE
+            // through this exact credential path, so registering them here too only
+            // fired a second, null-swallowing mint per focus — the "session-key
+            // POSTed on every tab focus" spam in the console.
+            const onWake = () => void refresh();
+            window.addEventListener('ablo:wake', onWake);
+            teardowns.push(() => window.removeEventListener('ablo:wake', onWake));
         }
         this.credentialLifecycleTeardown = () => {
             for (const t of teardowns)

package/dist/batching/index.d.ts

@@ -0,0 +1,57 @@
+/**
+ * `@abloatai/ablo/batching` — a dependency-free batch-coalescing primitive.
+ *
+ * Accumulate items issued close together (the canonical case: a synchronous
+ * burst, e.g. `Promise.all([ a(), b(), c() ])` in one event-loop tick) and
+ * dispatch them as ONE atomic batch instead of one call each. This is the
+ * scheduling essence of Ablo's `TransactionQueue` (and Linear's sync engine) —
+ * microtask same-tick staging, size/cost/delay flush triggers, and in-flight
+ * backpressure — distilled to a pure state machine with NO dependency on
+ * models, MobX, IndexedDB, or the wire. Consumers inject the actual dispatch.
+ *
+ * Guarantees:
+ *   - a batch is ONE `dispatchBatch(items)` call → **atomic** (all-or-nothing).
+ *   - on dispatch failure, **every** enqueued promise in that batch rejects
+ *     with the same error.
+ *   - items dispatch in enqueue order (optionally reordered by `compare` just
+ *     before a batch is cut); batches run FIFO under a `maxInFlight` cap.
+ *
+ * The slides-sdk wraps this to coalesce `commits.create` calls; the stateful
+ * `TransactionQueue` MAY adopt it later (it would supply `compare` for FK
+ * ordering and keep its merge/confirm/retry logic in its own hooks).
+ */
+export interface BatchSchedulerOptions<T> {
+    /** Master switch. When false, every `enqueue` dispatches solo immediately. Default true. */
+    readonly enabled?: boolean;
+    /** Coalescing window in ms. `0` (default) → flush on the next microtask (zero added latency). */
+    readonly windowMs?: number;
+    /** Max items per batch before a forced flush. Default 256. */
+    readonly maxBatchSize?: number;
+    /** Max accumulated `costOf` per batch before a forced flush. Default `Infinity` (disabled). */
+    readonly maxBatchCost?: number;
+    /** Per-item cost used by `maxBatchCost` (e.g. serialized bytes). Default `() => 0`. */
+    readonly costOf?: (item: T) => number;
+    /** Max dispatches in flight at once (backpressure). Default 1 → strictly ordered. */
+    readonly maxInFlight?: number;
+}
+export interface BatchSchedulerHooks<T, R> {
+    /** The single dispatch for one batch. One call → atomic at this layer. */
+    dispatchBatch(items: T[]): Promise<R>;
+    /**
+     * Optional ordering applied to the staged items immediately before a batch
+     * is cut (e.g. FK-priority). Omit for FIFO. Does not affect which items share
+     * a batch — only their order within the dispatched array.
+     */
+    compare?(a: T, b: T): number;
+}
+export interface BatchScheduler<T, R> {
+    /** Stage one item; resolves with its batch's dispatch result, or rejects with the batch error. */
+    enqueue(item: T): Promise<R>;
+    /** Stage an item that must dispatch in its OWN batch (e.g. it carries an explicit idempotency key). */
+    enqueueSolo(item: T): Promise<R>;
+    /** Force-flush the pending batch and resolve once everything in flight has settled. */
+    flush(): Promise<void>;
+    /** Stop scheduling and clear timers. Pending/in-flight promises still settle. */
+    dispose(): void;
+}
+export declare function createBatchScheduler<T, R>(hooks: BatchSchedulerHooks<T, R>, options?: BatchSchedulerOptions<T>): BatchScheduler<T, R>;

package/dist/batching/index.js

@@ -0,0 +1,150 @@
+/**
+ * `@abloatai/ablo/batching` — a dependency-free batch-coalescing primitive.
+ *
+ * Accumulate items issued close together (the canonical case: a synchronous
+ * burst, e.g. `Promise.all([ a(), b(), c() ])` in one event-loop tick) and
+ * dispatch them as ONE atomic batch instead of one call each. This is the
+ * scheduling essence of Ablo's `TransactionQueue` (and Linear's sync engine) —
+ * microtask same-tick staging, size/cost/delay flush triggers, and in-flight
+ * backpressure — distilled to a pure state machine with NO dependency on
+ * models, MobX, IndexedDB, or the wire. Consumers inject the actual dispatch.
+ *
+ * Guarantees:
+ *   - a batch is ONE `dispatchBatch(items)` call → **atomic** (all-or-nothing).
+ *   - on dispatch failure, **every** enqueued promise in that batch rejects
+ *     with the same error.
+ *   - items dispatch in enqueue order (optionally reordered by `compare` just
+ *     before a batch is cut); batches run FIFO under a `maxInFlight` cap.
+ *
+ * The slides-sdk wraps this to coalesce `commits.create` calls; the stateful
+ * `TransactionQueue` MAY adopt it later (it would supply `compare` for FK
+ * ordering and keep its merge/confirm/retry logic in its own hooks).
+ */
+export function createBatchScheduler(hooks, options) {
+    const enabled = options?.enabled ?? true;
+    const windowMs = options?.windowMs ?? 0;
+    const maxBatchSize = options?.maxBatchSize ?? 256;
+    const maxBatchCost = options?.maxBatchCost ?? Infinity;
+    const costOf = options?.costOf ?? (() => 0);
+    const maxInFlight = options?.maxInFlight ?? 1;
+    let pending = null;
+    let timer = null;
+    let microtaskScheduled = false;
+    const ready = [];
+    let inFlight = 0;
+    let idleWaiters = [];
+    let disposed = false;
+    function scheduleFlush() {
+        if (microtaskScheduled || timer)
+            return;
+        if (windowMs > 0) {
+            timer = setTimeout(() => {
+                timer = null;
+                flushPending();
+            }, windowMs);
+        }
+        else {
+            microtaskScheduled = true;
+            queueMicrotask(() => {
+                microtaskScheduled = false;
+                flushPending();
+            });
+        }
+    }
+    function flushPending() {
+        if (timer) {
+            clearTimeout(timer);
+            timer = null;
+        }
+        microtaskScheduled = false;
+        if (!pending)
+            return;
+        if (hooks.compare)
+            pending.items.sort(hooks.compare);
+        ready.push(pending);
+        pending = null;
+        pump();
+    }
+    function pump() {
+        while (inFlight < maxInFlight && ready.length > 0) {
+            const batch = ready.shift();
+            if (!batch)
+                break;
+            inFlight++;
+            let dispatched;
+            try {
+                dispatched = hooks.dispatchBatch(batch.items);
+            }
+            catch (error) {
+                dispatched = Promise.reject(error);
+            }
+            dispatched
+                .then((result) => {
+                for (const d of batch.deferreds)
+                    d.resolve(result);
+            }, (error) => {
+                for (const d of batch.deferreds)
+                    d.reject(error);
+            })
+                .finally(() => {
+                inFlight--;
+                pump();
+                notifyIdleIfDrained();
+            });
+        }
+    }
+    function notifyIdleIfDrained() {
+        if (inFlight === 0 && ready.length === 0 && idleWaiters.length > 0) {
+            const waiters = idleWaiters;
+            idleWaiters = [];
+            for (const w of waiters)
+                w();
+        }
+    }
+    function enqueueSolo(item) {
+        return new Promise((resolve, reject) => {
+            ready.push({ items: [item], deferreds: [{ resolve, reject }], cost: costOf(item) });
+            pump();
+        });
+    }
+    function enqueue(item) {
+        if (disposed)
+            return Promise.reject(new Error('batch scheduler disposed'));
+        if (!enabled)
+            return enqueueSolo(item);
+        const cost = costOf(item);
+        return new Promise((resolve, reject) => {
+            const deferred = { resolve, reject };
+            // Rollover: if appending would blow a cap, flush the current batch first.
+            if (pending && (pending.items.length + 1 > maxBatchSize || pending.cost + cost > maxBatchCost)) {
+                flushPending();
+            }
+            if (!pending)
+                pending = { items: [], deferreds: [], cost: 0 };
+            pending.items.push(item);
+            pending.deferreds.push(deferred);
+            pending.cost += cost;
+            if (pending.items.length >= maxBatchSize || pending.cost >= maxBatchCost) {
+                flushPending();
+            }
+            else {
+                scheduleFlush();
+            }
+        });
+    }
+    async function flush() {
+        flushPending();
+        while (ready.length > 0 || inFlight > 0) {
+            await new Promise((resolve) => idleWaiters.push(resolve));
+        }
+    }
+    function dispose() {
+        disposed = true;
+        if (timer) {
+            clearTimeout(timer);
+            timer = null;
+        }
+        microtaskScheduled = false;
+    }
+    return { enqueue, enqueueSolo, flush, dispose };
+}