@abloatai/ablo 0.64.3 → 0.64.5

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # Changelog
 
+## 0.64.5
+
+### Authoritative queries preserve freshness through reload
+
+Complete browser queries now keep their freshness requirement when a local-first
+read is already running. Empty server results remain empty, and snapshots
+rejected as older than resident data no longer overwrite the local cache.
+Network query results wait for accepted rows, including expanded relations, to
+finish their storage writes. Storage failures now reject the read instead of
+silently reporting success. The client behavior guide distinguishes query
+hydration, exact point reads and the limits of IndexedDB durability.
+
+### Storage failures leave bootstrap unfinished
+
+IndexedDB transactions that abort now reject their pending writes, allowing
+browser startup to report a storage failure instead of waiting indefinitely.
+Bootstrap no longer marks incomplete rows as persisted or advances its checkpoint
+past changes that could not be stored. Applications can retry after local storage
+recovers without treating a partial snapshot as complete.
+
+### Bootstrap allows time for capacity to recover
+
+The browser client now honours the server's retry interval when bootstrap is
+temporarily refused for capacity. These responses use a bounded recovery window
+without consuming the attempts reserved for fetch failures. Cancelling bootstrap
+also cancels its retry wait. Companion replication-lease and admission changes
+require a separate sync-server rollout; installing this release does not deploy
+them.
+
+### Clearer connection checks and diagnostics
+
+`ablo connect check` still exits with a nonzero status while existing rows are
+loading, but treats that state as an expected polling result. CLI error reports
+retain their stack frames and use valid release identifiers while continuing to
+sanitize diagnostic data.
+
+## 0.64.4
+
+### Cached rows follow account authority
+
+The reactive client now separates IndexedDB replicas and offline bootstrap snapshots by authenticated groups and operation grants, alongside user, organization, project and branch. Disposing a client and opening another account in the same organization no longer restores the previous account's rows before reconciliation. Reloading the same authority retains its warm cache.
+
+Existing caches start cold because their older namespace cannot establish account ownership. Older IndexedDB files, including pending writes, are retained but are not automatically imported or replayed into the new namespace. A replica widened by live group additions is rejected when reopened under narrower authority, preserving its pending writes.
+
 ## 0.64.3
 
 ### Existing connections make room for new tables

package/docs/client-behavior.md

@@ -70,6 +70,61 @@ to read.
 lifecycle filter defaults to `'live'`; pass `'archived'` or `'all'` when you
 intentionally want non-live rows.
 
+## Browser read freshness and persistence
+
+These modes apply after `await ablo.ready()` on the reactive browser client.
+Reads before initialization provide no persistence guarantee. A headless HTTP client has no
+local graph or IndexedDB replica; its reads go to the server.
+
+| Read | Can return cached data? | Network | Reactive graph | Offline / missing | Persistence when resolved |
+| --- | --- | --- | --- | --- | --- |
+| `local.get`, `local.list`, `local.count` | Yes; memory only | None | Read only | Available offline; `undefined`, `[]`, or `0` means absent locally | No write or durability barrier |
+| `list` with omitted `type` or `type: 'unknown'` | Yes; memory, then IndexedDB | Cold queries block; warm queries confirm in the background once per connection | Hydrates accepted rows | Warm data can be stale; cold network failure rejects; a successful empty network answer returns `[]` | A local hit does not wait for background writes; a network result waits for its accepted rows' storage transactions |
+| `list({ type: 'complete' })` | Never substitutes cached rows for an empty server answer; newer resident versions can supersede returned snapshots | Always awaits a query, including when local data exists | Hydrates accepted rows | Network failure rejects without stale fallback; missing matches return `[]` | Waits for accepted primary and expanded rows' storage transactions; storage failure rejects |
+| `get({ id, type? })`, `read({ id, type? })` | The query hydration stage follows the `list` policy | Also performs an authoritative point read after hydration | The query stage updates the graph; the additional point response does not | Point-read failure rejects even with warm data; missing row returns `undefined` | Query-stage writes finish first; the separate point response is not itself persisted |
+
+An unhydrated query with `expand` waits for the network even when its parent is
+cached: a parent alone cannot establish that its children are loaded. Omitted
+`type` is local-first for every model load strategy. Reconnecting clears the
+query hydration ledger. `complete` describes freshness, not an unlimited result
+set; keep queries bounded and inspect the collection's `hasMore`.
+
+Query responses meet resident rows by server log position, not `updatedAt`. A
+snapshot known to precede an accepted subscription version cannot replace that
+resident row or overwrite its persisted data. Pending local edits remain visible.
+An empty query result does not delete cached rows: filtered or limited query
+absence is not a deletion event. Synchronized deletes remove rows from the graph;
+a local selector then observes their absence.
+
+For a reload-sensitive external publication, explicitly hydrate the desired rows:
+
+```ts
+await ablo.ready();
+// The application server has already confirmed its publication.
+await ablo.sourceSnapshots.list({ where: { id: snapshotId }, type: 'complete' });
+await ablo.sourceHeads.list({ where: { id: headId }, type: 'complete' });
+// Accepted query rows have reached the configured local storage.
+```
+
+Configure `persistence: 'indexeddb'` on the browser client for reload persistence.
+Memory persistence cannot survive a reload. IndexedDB completion here means a
+completed browser transaction, using relaxed durability; it is not a guarantee
+against power loss, browser eviction, or a later authorized update or deletion.
+The barrier covers these queries' accepted writes, not every pending subscription
+or mutation. `waitForFlush()` waits for server mutation confirmation and is not a
+local persistence barrier. If a storage write fails, the graph may already show
+the result; retry the complete read before relying on reload persistence.
+
+Use `read` when a later write needs exact captured read evidence. Use a complete
+`list` query when the purpose is to populate and persist the reactive working
+set. A `get`/`read` result and the local graph are distinct snapshots and can differ
+if the row changes between the query and point requests.
+
+Account changes require disposing the old client and constructing a new scoped
+client, as shown in [React](./react.md). Do not reuse an old request's result as
+initial data for the new account. The same user, project and branch do not make
+two accounts the same persistence authority.
+
 ## Multiplayer Behavior
 
 Two writers both try to mark `report_stockholm` ready at the same time. To stop

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/ablo",
-  "version": "0.64.3",
+  "version": "0.64.5",
   "description": "The public Ablo SDK for coordinated reads, commits, claims, observation, and reactive applications.",
   "license": "Apache-2.0",
   "type": "module",
@@ -147,8 +147,8 @@
     "directory": "packages/ablo"
   },
   "dependencies": {
-    "@abloatai/humans": "0.64.3",
-    "@abloatai/transaction": "0.64.3",
+    "@abloatai/humans": "0.64.5",
+    "@abloatai/transaction": "0.64.5",
     "zod": "^4.4.3"
   },
   "peerDependencies": {