@abloatai/ablo 0.64.0 → 0.64.2

package/AGENTS.md

@@ -4,6 +4,12 @@ Ablo lets AI agents and humans safely edit the same typed data without clobberin
 
 Claims don't lock. If another writer holds the row, `claim` waits for them and re-reads the fresh row before handing it to you — so two writers serialize instead of clobbering.
 
+Groups structure which shared state reaches each person or agent. Declare the
+data's scope and participant authority, then let authorized subscriptions keep
+reactive views current; HTTP agents explicitly read or observe changes. Start
+with [Groups and shared context](./docs/groups.md) to connect membership, access,
+loading and updates.
+
 ## Start here — scaffold with `ablo init`
 
 Before choosing among identifier claims, row claims, captured reads, atomic

package/CHANGELOG.md

@@ -1,5 +1,75 @@
 # Changelog
 
+## 0.64.2
+
+### More complete upgrade guidance
+
+`ablo upgrade` now identifies removed `SyncProvider` imports and the removed
+`AbloProvider` `userId` prop, including aliased imports. Its guidance points to
+the current provider and authenticated client session. React examples and
+identity documentation now use the supported props consistently.
+
+### Registration examples match the scaffold
+
+The quickstart now includes the empty type import from `@abloatai/ablo` that
+`ablo init` already generates. It loads the SDK declaration before augmenting
+`Register`, so applications copying the example retain the existing module's
+types. The groups guide also explains how shared context relates to membership
+and subscription changes.
+
+This patch introduces no new API changes.
+
+## 0.64.1
+
+### A schema that survives the journey into a package
+
+Sharing a schema through a compiled package could leave an application facing
+pages of empty-object and unknown-type errors. The schema was present, but its
+registration no longer reached the parts of Ablo that needed it. Registration
+now carries through the published declarations into Transaction and Humans.
+When it is missing, schema-free mutators report what the application needs to
+supply.
+
+Passing the schema explicitly is the recommended approach for mutators. The
+integration guide also explains how to share a schema and React bindings across
+packages, so a monorepo's source imports and its consumers' compiled imports
+agree about the same application.
+
+### React makes the difference between reading and writing visible
+
+A component reading a snapshot and an event handler issuing a write now ask for
+different things. `useAblo(selector)` returns the render snapshot;
+`useAbloClient()` returns the client used for operations. The zero-argument
+`useAblo()` call is removed, making that choice visible at the call site.
+
+Mutation failures have a dedicated hook again. `useMutationFailure` manages the
+subscription and its cleanup, removing the effect each application otherwise
+had to maintain. Framework adapters can obtain the supported store contract
+through `getAbloStore(client)` from `@abloatai/ablo/client`.
+
+### Presence can leave the current session out
+
+A view of who else is working on a record can now request
+`{ excludeSelf: true }` through `usePresence` or `presence.forModel`. The filter
+removes the current session; another tab belonging to the same person remains
+visible. Applications no longer need to repeat that distinction themselves.
+
+Generic collaboration subscriptions also retain the event arguments declared
+by their adapters. Handlers that need authenticated sender context use
+`collaboration.subscribe` on the session or `subscribeCollaboration` on the
+transport.
+
+### One release, with an explicit upgrade path
+
+Ablo, Transaction, Humans and the CLI now declare exact compatibility
+requirements, keeping their versions together. Provider terminology is
+consistently `AbloProvider`, including the context used by framework adapters.
+
+Despite the patch number, 0.64.1 includes API removals. `ablo upgrade` reports
+migration hints, and the
+[upgrade guide](https://github.com/Abloatai/ablo/blob/v0.64.1/packages/ablo/docs/migration.md)
+covers the hook replacements, provider context, presence fields and claims.
+
 ## 0.64.0
 
 React reads the same core objects as ordinary Ablo code. Read connection state with `ablo.status` outside React and `useAblo(ablo => ablo.status)` inside React; its type is `Ablo.Status`. Presence reads through `useAblo(ablo => ablo.presence.others)` or `ablo.presence.forModel(model, id)` now react to activity changes. The unregistered-schema selector also preserves core properties and methods.

package/README.md

@@ -29,6 +29,12 @@ Every write goes through it, so authority, idempotency, conflicts, ordering,
 and confirmation are enforced in one place. Your Postgres remains the source of
 truth.
 
+Groups structure which shared state reaches each person or agent. Declare the
+data's scope and participant authority, then let authorized subscriptions keep
+reactive views current; HTTP agents explicitly read or observe changes. Start
+with [Groups and shared context](./docs/groups.md) to connect membership, access,
+loading and updates.
+
 ## Why Ablo
 
 Software used to have one writer: a human clicking through an application. AI

package/dist/index.d.ts

@@ -8,4 +8,12 @@ export { Ablo as default } from '@abloatai/transaction';
  */
 export { noopLogger } from '@abloatai/transaction/logger';
 export type { Logger } from '@abloatai/transaction/logger';
+/** Application registration, owned here so augmentation survives re-exports. */
+export interface Register {
+}
+type PublicRegister = Register;
+declare module '@abloatai/transaction/types/global' {
+    interface Register extends PublicRegister {
+    }
+}
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC;AACtC,OAAO,EAAE,IAAI,IAAI,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAExD;;;;;GAKG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAC1D,YAAY,EAAE,MAAM,EAAE,MAAM,8BAA8B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC;AACtC,OAAO,EAAE,IAAI,IAAI,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAExD;;;;;GAKG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAC1D,YAAY,EAAE,MAAM,EAAE,MAAM,8BAA8B,CAAC;AAE3D,gFAAgF;AAEhF,MAAM,WAAW,QAAQ;CAAG;AAC5B,KAAK,cAAc,GAAG,QAAQ,CAAC;AAI/B,OAAO,QAAQ,oCAAoC,CAAC;IAClD,UAAU,QAAS,SAAQ,cAAc;KAAG;CAC7C"}

package/dist/react.d.ts

@@ -1,4 +1,4 @@
 /** Core client and the explicitly supported React bindings. */
 export { Ablo, humans } from '@abloatai/humans';
-export { AbloProvider, createAbloReact, useAblo, usePresence, useMutators, useUndoScope, } from '@abloatai/humans/react';
+export { AbloProvider, createAbloReact, useAblo, useAbloClient, useMutationFailure, usePresence, useMutators, useUndoScope, } from '@abloatai/humans/react';
 //# sourceMappingURL=react.d.ts.map

package/dist/react.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,EACL,YAAY,EACZ,eAAe,EACf,OAAO,EACP,WAAW,EACX,WAAW,EACX,YAAY,GACb,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,EACL,YAAY,EACZ,eAAe,EACf,OAAO,EACP,aAAa,EACb,kBAAkB,EAClB,WAAW,EACX,WAAW,EACX,YAAY,GACb,MAAM,wBAAwB,CAAC"}

package/dist/react.js

@@ -1,4 +1,4 @@
 /** Core client and the explicitly supported React bindings. */
 export { Ablo, humans } from '@abloatai/humans';
-export { AbloProvider, createAbloReact, useAblo, usePresence, useMutators, useUndoScope, } from '@abloatai/humans/react';
+export { AbloProvider, createAbloReact, useAblo, useAbloClient, useMutationFailure, usePresence, useMutators, useUndoScope, } from '@abloatai/humans/react';
 //# sourceMappingURL=react.js.map

package/dist/react.js.map

@@ -1 +1 @@
-{"version":3,"file":"react.js","sourceRoot":"","sources":["../src/react.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,EACL,YAAY,EACZ,eAAe,EACf,OAAO,EACP,WAAW,EACX,WAAW,EACX,YAAY,GACb,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"react.js","sourceRoot":"","sources":["../src/react.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,EACL,YAAY,EACZ,eAAe,EACf,OAAO,EACP,aAAa,EACb,kBAAkB,EAClB,WAAW,EACX,WAAW,EACX,YAAY,GACb,MAAM,wBAAwB,CAAC"}

package/docs/examples/account-multiplayer.md

@@ -7,6 +7,9 @@ The maintained reference lives in
 Start at `src/index.ts`, then follow its owned `accounts`, `agent` and `workspace`
 boundaries. Its README contains the install, isolated-branch setup and test commands.
 
+For the full participant lifecycle and its current cache behavior, see
+[Groups and shared context](../groups.md).
+
 ## One account, one authorization rule
 
 “People in this account can see its chats” requires both a row rule and a

package/docs/examples/scoped-agent.md

@@ -104,7 +104,7 @@ const ablo = Ablo({
 });
 
 // The agent run is mounted on behalf of its triggering user.
-<AbloProvider client={ablo} userId={triggeringUser.id}>
+<AbloProvider client={ablo}>
   {children}
 </AbloProvider>
 ```
@@ -115,11 +115,11 @@ the agent can never reach a workspace its triggering user couldn't.
 
 ## 3. Write: it fans out to everyone on that workspace
 
-Inside any component under the provider, grab the scoped client with `useAblo()`
+Inside any component under the provider, grab the scoped client with `useAbloClient()`
 and write. The connection is already narrowed to `workspace:<workspaceId>` from Step 2.
 
 ```ts
-const ablo = useAblo();
+const ablo = useAbloClient();
 
 // Other participants subscribed to workspace:<workspaceId> — a reviewer agent, a
 // person watching in the UI — receive this delta in realtime. Participants on

package/docs/groups.md

@@ -1,16 +1,137 @@
-# Change Propagation
+# Groups and shared context
 
-> How one row's change reaches the rows and actors that depend on it.
+> Structure which shared state reaches each participant, and how their view stays current.
 
-> How a change to one row reaches the rows and actors that depend on it, and how
-> to keep a chain of dependent work fresh. This is the propagation half of sync
-> groups; [`identity.md`](./identity.md) is the access half (who may read a
-> group), and [`concurrency-convention.md`](./concurrency-convention.md) is the
-> convention this rests on.
+Groups connect the structure of your data to the people and agents who receive
+it. A group names a shared context, such as `account:acme` or `workspace:abc`.
+Membership and authorization determine the eligible view; subscriptions and
+client loading determine how that view reaches a participant.
 
----
+Start here to understand **why this participant receives this record**. Use
+[Identity](./identity.md) for authentication and credential issuance, and the
+[account multiplayer walkthrough](./examples/account-multiplayer.md) for the
+maintained application that puts these pieces together.
+
+## One context, several decisions
+
+Ablo has existing declarations for these decisions; there is no single group
+object that configures all of them.
+
+| Decision | Existing declaration or behavior |
+| --- | --- |
+| Which records form a context? | Model `groups.root` creates a group per root record; children inherit through `belongsTo` relationships marked `parent: true`. Ordinary references do not propagate membership. `groups.roles` supplies explicit field-based routes. |
+| Who belongs? | Schema `groups.grants` declares a membership edge through its `subject` and `scope` relations within an organization. A trusted backend can also issue session `groups` after verifying application membership. |
+| Which rows may they access? | Model `policy` establishes the read/tenant boundary; `subject` requires a matching credential group for the named row field. Delivery routing alone is not a read policy. |
+| What may they do? | Session `can` grants model operations. Read membership does not grant update or claim authority. |
+| Which changes reach them? | Server-authorized subscriptions match the row's delivery groups. Requested groups cannot widen credential authority. |
+| What is local? | Reactive clients bootstrap and maintain local state; HTTP clients explicitly fetch data. Client loading is distinct from permission to read. |
+
+For a model with `subject`, its subject group is the **exclusive delivery
+route**. Parent groups, explicit roles and additional routes cannot provide an
+alternate path to that row. For other routed models, delivery matches any
+eligible group; declaring a narrow route does not narrow an otherwise broad
+read policy. `groups.routingOnly: true` acknowledges that deliberate difference,
+not an authorization grant.
+
+## Follow one conversation
+
+The account multiplayer reference declares this model:
+
+```ts
+import { defineSchema, model, z } from '@abloatai/ablo/schema';
+
+const schema = defineSchema({
+  conversations: model({
+    accountId: z.string().min(1),
+    title: z.string(),
+    executionOwner: z.string().nullable(),
+    executionState: z.enum(['idle', 'generating']),
+  }, { subject: { field: 'accountId', group: 'account' } }),
+});
+```
+
+A conversation whose `accountId` is `acme` requires `account:acme`. The
+application verifies Alice's membership before issuing her browser session with
+that group and `can: { conversations: ['read'] }`. The agent gets the same group
+with `read` and `update` authority. The reference verifies account membership in
+application code; it does not use a schema `groups.grants` membership model.
+
+Both can read the conversation. Alice's browser cannot update it with its
+read-only credential: the reference performs human writes through a separately
+scoped server client. The agent may update it, subject to the write's claims and
+read checks. An outsider cannot gain access by supplying `accountId: 'acme'` in
+a filter or by requesting an unauthorized subscription.
+
+```mermaid
+flowchart TD
+    R["Conversation: accountId = acme"] --> S["Subject: account:acme"]
+    S --> G["Trusted groups + operation grants"]
+    G -->|Bootstrap and live updates| H["Alice's reactive local view"]
+    G -->|Explicit reads or log requests| A["Agent's working context"]
+```
 
-## Start from the problem
+The diagram describes data flow. Group membership does not prove that a
+participant is connected, has loaded every record, or has acted on an update.
+Presence describes activity; it does not grant authority or locate cached bytes.
+
+## A participant's lifecycle
+
+| Event | What happens today |
+| --- | --- |
+| Join | The backend authenticates the participant and verifies membership before minting a scoped session. Issuance does not itself load records. |
+| Load | Alice's reactive client loads its authorized baseline and consumes updates. An HTTP agent calls model reads/lists or observes the ordered log; it has no reactive local graph. |
+| Change | A confirmed conversation change routes through `account:acme` to eligible subscribers. An HTTP agent must explicitly read again or consume log changes to update its working context. |
+| Gain a group | On the incremental group-added path, the reactive client records membership and receives covering deltas for newly visible rows. The full-diff path instead requests re-bootstrap. |
+| Reconnect | The reactive client compares current server-issued groups with stored subscription metadata. Detected shrinkage clears local storage and memory and marks a full bootstrap as required; otherwise normal catch-up applies. |
+| Lose a group | On a group-removal notification, the reactive client clears its managed database and object pool, updates subscription metadata and requests re-bootstrap. It does not selectively evict that group's rows. |
+| Switch account | The reference disposes the previous account client and creates a client using the newly authorized account endpoint. |
+
+Group-change handling is a runtime path, not a promise that every change in an
+external membership database immediately invalidates every issued credential.
+The application must connect its membership and credential lifecycle to Ablo.
+An offline participant cannot process a revocation notification until it
+reconnects; managed-cache clearing cannot retract copies retained by application
+code or an agent. Clients configured without automatic bootstrap do not fetch
+a full baseline after a group-change notification; they rely on covering deltas or
+explicit reads for data.
+
+Consider a participant authorized for both `account:acme` and `account:beta`.
+Losing Acme currently clears the client's whole managed cache, including cached
+Beta records, before rebuilding the remaining authorized view. Beta records
+remain eligible for loading. For non-subject routing where one row belongs to
+several groups, losing one matching group likewise does not alone establish
+that the row is inaccessible; remaining authorization and routes matter.
+
+## Understand the living system
+
+Inspect a participant through three separate questions: **what may they see,
+what are they subscribed to, and what have they loaded?** To explain an individual
+record, follow its model's subject or routing declaration, the participant's
+trusted groups and operation grants, then its client transport and lifecycle.
+
+These distinctions also help assess a group design:
+
+| Symptom | Design question |
+| --- | --- |
+| Many irrelevant updates | Is the delivery group broader than the participant's work? |
+| One task needs many groups | Has the shared context been fragmented too far? |
+| One change reaches many subscribers | Is that fan-out useful, and do all subscribers need live delivery? |
+| Frequent group-premise rejection | Does the decision depend on the whole group, or only particular rows/fields? |
+| Slow loading or catch-up | How much authorized state is being materialized, and how much changed while offline? |
+
+These are evaluation questions, not a built-in group score or per-participant
+cache dashboard. A group does not configure blob prefetch, cache placement or
+selective eviction. Those would be additional capabilities built on these scope
+and update signals.
+
+## Changes and decisions
+
+Receiving an update keeps a live view current. Declaring a read premise checks
+whether a particular decision is still valid when written. A group can serve
+both purposes, but membership alone neither locks records nor makes them
+mutually consistent.
+
+### Protect a decision based on a group
 
 An agent reads workspace `A` to write document `B`. A moment later it reads `B` to write
 block `C`. Between those steps someone else edits `A`. The agent is now building
@@ -74,18 +195,17 @@ does not retain the row contents as read evidence.
 for you and leaves the third to you — on purpose.
 
 **Routing — who hears about a change.** Every row belongs to one or more sync
-groups, and a write fans out to all of them. A row also inherits its ancestors'
-groups: editing a block stamps the delta with `block:…`, `document:…`, *and*
-`workspace:…`, so everyone watching the workspace sees the block move. This is delivery,
+groups, and a write fans out to its delivery groups. For a model without an
+exclusive `subject` route, declared scope roots and
+relationships can route a block change to `block:…`, `document:…`, and
+`workspace:…`, so authorized workspace subscribers receive it. This is delivery,
 resolved by walking the ownership tree at commit time. It routes the change; it
 never recomputes a value.
 
-**Structural cascade — what disappears with a change.** Deleting a workspace removes
-its documents and blocks. The database does that through `ON DELETE CASCADE`, but a
-database-level cascade emits no delta, so open clients would quietly hold rows
-that no longer exist. The engine closes that gap: before the delete it snapshots
-the subtree and emits a tombstone for each descendant, routed to the right
-group. Watchers see the whole subtree vanish.
+**Structural cascade — what disappears with a change.** A declared ownership
+relationship can make deleting a parent remove its descendants. Clients need
+routed deletion deltas to remove those records from their views. This follows
+the relationship and delete path; sharing a group alone does not cascade deletes.
 
 **Value recomputation — what a change implies for derived state.** If `B` holds a
 number rolled up from `A`, the engine does not recompute `B` when `A` changes. It
@@ -116,8 +236,8 @@ decides what that means for its own state, commits, and *its* commit is what
 reaches `C`.
 
 The direction matters. The signal flows forward, A to B to C, and each hop is a
-real write an actor chose to make. The engine supplies the edges (group
-membership) and a stale signal on each edge (the premise check); the actors are
+real write an actor chose to make. Group routing supplies the delivery edges, and declared read premises add
+stale-work checks to writes; the actors are
 the runtime that walks them. It is closer to a dataset an analyst
 recalculates cell by cell than to a reactive engine that recomputes the whole
 column for you.
@@ -167,11 +287,10 @@ group premise fires when *anything* in the group moves — so a group that is to
 broad wakes actors for changes they don't care about, and one that is too narrow
 misses the dependency you meant to track.
 
-The rule of thumb: **make a group the smallest set of rows that must stay
-mutually consistent.** A workspace and its documents belong together because editing one
-changes what the others mean; two unrelated workspaces do not. Reach for finer,
-overlapping groups when you genuinely have a dependency chain to track, and keep
-them coarse everywhere else.
+Choose groups around shared work and authorized audiences. Use a group premise
+when a decision depends on that whole context; use row or field premises when
+it depends on less. Overlapping routing groups can express useful audiences,
+but do not create transaction boundaries or a consistency guarantee.
 
 ---
 

package/docs/identity.md

@@ -1,7 +1,11 @@
-# Identity & Sync Groups
+# Identity and credentials
 
 > Who is connecting, and which slice of state they are allowed to see.
 
+Start with [Groups and shared context](./groups.md) for how data membership,
+authorization, subscriptions and local state fit together. This guide owns
+authentication, credential issuance and the schema wiring behind that view.
+
 This is the doc the Quickstart skips: **who is connecting, and which slice
 of shared state do they get?** If you've wired `<AbloProvider client={ablo}>`
 and wondered where org / team / user actually come from — start here.
@@ -15,7 +19,7 @@ Ablo is not an identity provider. It has no login, no password store, no
 session of its own. You keep whatever you already use — Clerk, Auth0,
 NextAuth, WorkOS, your own session table. Ablo's job begins **after** you've
 authenticated the user: you hand Ablo the already-authenticated identity, and
-Ablo decides which **sync groups** that identity may read and write.
+Ablo enforces that credential's groups, model read policies and operation grants.
 
 ## Inspect the credential the application is actually using
 
@@ -75,13 +79,12 @@ that.
 
 ## What a sync group is
 
-A **sync group** is a named channel of shared state — a string like
-`org:acme` or `workspace:abc123`. It is simultaneously:
-
-- **the unit of fan-out:** a confirmed write to a row publishes a delta to
-  every participant subscribed to that row's sync group(s), and
-- **the unit of access:** a participant receives a row's deltas *only if* the
-  row's sync group is in their allowed set.
+A **sync group** names shared state, such as `org:acme` or `workspace:abc123`.
+The server checks allowed groups for delivery; model `policy` and `subject`
+rules govern row access, and capability operations govern permitted actions.
+Routing a row to a group does not itself authorize an HTTP read or write.
+See [the group lifecycle](./groups.md#a-participants-lifecycle) for loading,
+updates, reconnects and removal.
 
 There is no built-in `org` / `team` / `user` concept in the engine. Those are
 *your* domain words. Ablo only knows sync-group strings. The mapping from "this
@@ -133,7 +136,7 @@ export const schema = defineSchema(
 // 2. app/providers.tsx — a HUMAN gets their full org / team scope.
 // teamIds is set on the client you build (Ablo({ schema, teamIds: user.teamIds })),
 // not passed to the provider; the provider just takes that client.
-<AbloProvider client={ablo} userId={user.id}>
+<AbloProvider client={ablo}>
   {children}
 </AbloProvider>
 ```
@@ -255,9 +258,11 @@ Delivery scoping is two declarations that meet in the middle. One describes the
 changes when the row's sync groups intersect the participant's allowed set.
 
 That intersection does not itself authorize an HTTP read. A model's `policy`
-governs read access. Treat sync-groups as change routing and `policy` (plus the
-organization boundary beneath it) as authorization; declaring one never
-silently creates the other.
+governs read access, while `subject` can require a credential group for a row
+field. Operation grants bound the actions. A subject-scoped row uses only its
+subject delivery group; other routes cannot bypass that boundary. See
+[Groups and shared context](./groups.md#one-context-several-decisions) for how
+these declarations fit together.
 
 ### Half 1 (`identityRoles`): identity → allowed groups
 
@@ -408,8 +413,7 @@ server, never by the browser.**
 
 ## Wiring the provider
 
-The identity your server resolved is carried by the client you build and the
-`userId` prop. In a Next.js app, resolve the user in a Server Component and pass
+The identity your server resolved is carried by the authenticated client session. In a Next.js app, resolve the user in a Server Component and pass
 it down. Build the client once (the schema, `teamIds`, and the `apiKey` resolver
 live here; entity narrowing rides the minted session's `groups`), then hand
 it to the provider:
@@ -450,7 +454,7 @@ export function Providers({
 }) {
   const ablo = useMemo(() => makeAblo(user), [user.id]);
   return (
-    <AbloProvider client={ablo} userId={user.id} fallback={<AppSkeleton />}>
+    <AbloProvider client={ablo} fallback={<AppSkeleton />}>
       {children}
     </AbloProvider>
   );
@@ -461,11 +465,11 @@ What carries identity — and just as importantly, what does *not* set the bound
 
 | Where        | Purpose                                                                                          |
 | ------------ | ------------------------------------------------------------------------------------------------ |
-| `userId` prop | App-level participant id, used for app-owned fields and read by your `identityRole` `source`. **Not** the security boundary: the server enforces scope from the authenticated request. |
+| Application authentication context | Supplies identity for app-owned fields and UI. The provider has no `userId` prop; the server enforces scope from the authenticated session. |
 | `teamIds` (on the client) | Team ids expanded into team sync groups via your `identityRoles`.                   |
 | `groups` (at session mint) | Optional. **Narrows** a minted session's subscription to a subset of what auth already allows: it can never widen it. Passed to `sessions.create({ user \| agent, groups })`; build entries with `syncGroup(kind, id)`. Use it to scope an agent (or a focused page's session) to one entity, e.g. `[syncGroup('workspace', 'abc123')]`. |
 
-Because the server is the boundary, a client that changes `userId` to another
+Because the server is the boundary, a client that changes application identity state to another
 user's id does not gain their data — the server resolves and enforces the real
 identity on the connection. These are how your app *tells* Ablo who it
 already authenticated, not how it *proves* it.
@@ -644,9 +648,9 @@ The best practices Ablo inherits from that lineage:
    the line precisely: [token parameters are trusted and usable for access
    control; client parameters are not](https://docs.powersync.com/usage/sync-rules/advanced-topics/client-parameters).
    In Ablo terms, the identity your server vouches for — and the session's
-   `groups`, minted server-side — are the *trusted* claims that set scope; the
-   `userId` prop is *untrusted client input* — convenient for app-owned fields, but
-   never the boundary. This is why changing `userId` in the browser grants nothing.
+   `groups`, minted server-side — are the *trusted* claims that set scope; application
+   identity state is *untrusted client input* — convenient for app-owned fields, but
+   never the boundary. Changing that state in the browser grants nothing.
 
 3. **Scope by a hierarchical naming convention, declared once.** Ablo's `kind:id`
    group naming (`org:…` / `team:…` from `identityRoles`, `workspace:…` from a model's

package/docs/index.md

@@ -27,6 +27,10 @@ interfaces.
     Keep the authoritative transaction, locks, constraints, and direct SQL paths your application already owns.
   </Card>
 
+  <Card title="Groups and shared context" icon="share-2" href="/groups">
+    Structure which state reaches each participant, from membership and access to loading, updates and removal.
+  </Card>
+
   <Card title="Participant identity" icon="fingerprint" href="/identity">
     Give agents, people, and services distinct scoped credentials instead of treating every worker as the same caller.
   </Card>

package/docs/integration-guide.md

@@ -172,7 +172,7 @@ export const ablo = Ablo({
 
 Browser apps should use the React provider or a scoped session token, not a
 server API key in the bundle. Build the client first, then hand it to the
-provider — `AbloProvider` takes `{ client, userId?, onError?, fallback? }`, and
+provider — `AbloProvider` takes `{ client, onError?, fallback? }`, and
 nothing else (`schema`, `teamIds`, and `apiKey` all live on the
 client now).
 
@@ -287,7 +287,7 @@ In React, selector `useAblo` is the public read API:
 ```tsx
 'use client';
 
-import { useAblo } from '@abloatai/ablo/react';
+import { useAblo, useAbloClient } from '@abloatai/ablo/react';
 
 export function ReportRow({
   report: serverReport,
@@ -301,10 +301,10 @@ export function ReportRow({
 }
 ```
 
-Use zero-argument `useAblo()` only in callbacks and effects:
+Call `useAbloClient()` during render, then use its client in callbacks and effects:
 
 ```tsx
-const ablo = useAblo();
+const ablo = useAbloClient();
 ```
 
 ## 4. Write State

package/docs/migration.md

@@ -3,7 +3,100 @@
 > A safe workflow for upgrading the pre-1.0 SDK.
 
 Ablo is pre-1.0, so a minor release may contain a breaking API change. Patch
-releases remain compatible within the same minor line.
+releases normally remain compatible within the same minor line. The 0.64.1
+release includes the explicit React and collaboration migrations below.
+
+## React and package boundaries after 0.64
+
+Run `npx ablo upgrade` for migration hints before editing. It previews changes;
+`--write` applies only mechanical rewrites. React changes requiring application
+judgment are reported with their replacements.
+
+| Previous API | Current API |
+| --- | --- |
+| `useSync()` or zero-argument `useAblo()` | `useAbloClient()` for actions; await `client.ready()` when initialization is required |
+| `useSyncStatus()` | `useAblo(client => client.status)` |
+| `usePeers()` | `useAblo(client => client.presence.others)` |
+| Scoped peers | `usePresence(client => client.records, id, { excludeSelf: true })` |
+| `useMutationFailureListener(listener)` | `useMutationFailure(listener)` |
+| `useErrorListener()` | `AbloProvider`'s `onError` prop for startup errors |
+| `useCurrentUserId()` | Your application's authentication context |
+| `useSDKSyncStore()` / `useSyncStore()` | Public client operations; `getAbloStore(client)` from `/client` for custom local-store adapters |
+| `ClientSideSuspense` / `DefaultFallback` | Application UI through the provider's `fallback` prop |
+| `GroupScope` for presence | Model and record arguments |
+
+`useAblo(selector)` returns detached snapshots for rendering. They have no model
+methods or relation accessors. `useAbloClient()` returns the writable client and
+does not subscribe to row changes. Do not perform writes inside a selector.
+
+### Presence, activities and claims
+
+`Activity` is replaced by `Ablo.PresenceActivity`, including for agents. A session
+is `Ablo.PresenceSession`: identify the execution with `presenceSessionId` and its
+actor with `participant.id` and `participant.kind`. A participant can have several
+sessions, so exclude self by session rather than user ID.
+
+`presence.active` contains this session's activities; `presence.others` contains
+other sessions, each with an `activities` array. `forModel(model, id)` includes
+self by default; pass `{ excludeSelf: true }` as its third argument to omit self.
+The same option on `usePresence` still announces the component's reading activity
+and cleans it up on unmount.
+
+An activity has `operation`, `target`, `source`, and ISO timestamp fields.
+Read the model and row from `activity.target.model` and `.id`; field-specific
+activity uses `.field` or `.fields` (never both, and always with a row ID).
+Activities describe visible work; they do not grant write authority.
+
+Claims are acquired through `await using claim = await client.records.claim({ id })`.
+The protected row is `claim.data`; pass `claim` to the write. Claim lookup uses
+`client.records.claim.state({ id })` and `.queue({ id })`. Claim metadata is on
+`claim.target.meta`, and a multi-field claim uses `fields` in the claim target.
+Do not reconstruct a claim handle from a presence activity. See [Claims](./claims.md).
+
+### Imports and schema ownership
+
+The root factory creates a headless client; `/client` creates the reactive client.
+Import the `Ablo` type namespace beside the factory you use. Both expose the
+shared schema, presence-activity and claim types. Reactive-only types such as
+`Ablo.Status`, `Ablo.Reads`, `Ablo.Store`, and `Ablo.Mutator` belong to `/client`
+(or `/react` for its re-exported reactive factory).
+
+Prefer explicit schema inference:
+
+```ts
+import { defineMutators } from '@abloatai/ablo/client';
+import { useMutators, useUndoScope } from '@abloatai/ablo/react';
+import { schema } from './schema';
+
+const definitions = defineMutators(schema, {
+  records: {
+    rename: async ({ tx, args }: {
+      tx: import('@abloatai/ablo/client').Ablo.Mutator.Transaction<typeof schema>;
+      args: { id: string; title: string };
+    }) => tx.mutations.records.update({ id: args.id, title: args.title }),
+  },
+});
+
+function useRecordActions() {
+  const { scope } = useUndoScope(schema, 'record-editor');
+  return useMutators(schema, definitions, { undoScope: scope });
+}
+```
+
+Ambient registration remains available for a single application. Its module must
+be included in that TypeScript program and import `@abloatai/ablo` before
+augmenting `Register`. The public registration now reaches the downstream
+Transaction and Humans resolvers through the emitted declarations. A package
+compiled independently cannot inherit a consuming app's ambient declaration.
+
+### Structural collaboration adapters
+
+Generic `subscribe(event, handler)` preserves exactly the argument tuples in your
+event map. Receive optional server attribution through the session's
+`collaboration.subscribe(event, (payload, context) => ...)`; low-level transport
+adapters use `subscribeCollaboration`. Model-scoped `client.records.events.on`
+continues to supply authenticated context as its second callback argument.
+Legacy servers may omit context on application events; handle `undefined` there.
 
 ## Upgrade safely
 
@@ -14,7 +107,7 @@ releases remain compatible within the same minor line.
 5. Run the three-state deployment plan, then push the exact reviewed plan.
 
 ```bash
-npm install @abloatai/ablo@0.48
+npm install --save-exact @abloatai/ablo@<version> @abloatai/cli@<version>
 npx ablo docs
 npx ablo docs api
 npx ablo plan

package/docs/quickstart.md

@@ -16,6 +16,12 @@ schema** — your migration tool stays in charge of the shape of your database.
 > or separate database, and connect your production one when you're ready for it
 > to be the system of record.
 
+Groups structure which shared state reaches each person or agent. Declare the
+data's scope and participant authority, then let authorized subscriptions keep
+reactive views current; HTTP agents explicitly read or observe changes. Start
+with [Groups and shared context](./groups.md) to connect membership, access,
+loading and updates.
+
 ## 1. Install and initialize
 
 ```bash
@@ -82,6 +88,7 @@ every type is one parameter away — no `typeof schema` re-stating, anywhere:
 
 ```ts
 // ablo/register.ts — scaffolded by `npx ablo init`, sits beside ablo/schema.ts
+import type {} from '@abloatai/ablo';
 import type { schema } from './schema';
 declare module '@abloatai/ablo' {
   interface Register { Schema: typeof schema }
@@ -89,11 +96,11 @@ declare module '@abloatai/ablo' {
 export {};
 ```
 
-It's a regular `.ts` module, not a hand-authored `.d.ts`. The top-level
-`import type { schema }` makes the `declare module` block *merge* into (augment)
-the SDK's `Register` interface instead of colliding with it — the same shape
-[TanStack Router uses in `src/router.tsx`](https://tanstack.com/router/latest/docs/framework/react/guide/type-safety). Any `.ts` file in your
-`tsconfig` `include` works; it never needs to be imported.
+It's a regular `.ts` module, not a hand-authored `.d.ts`. The empty
+`import type {} from '@abloatai/ablo'` loads the SDK's module declaration so the
+`declare module` block augments its existing `Register` interface. The schema
+import supplies your schema's type. Both imports are erased at runtime. Any `.ts`
+file in your `tsconfig` `include` works; it never needs a runtime import.
 
 ```ts
 import type { Model } from '@abloatai/ablo/schema';

package/docs/react.md

@@ -13,7 +13,7 @@ agents, start with [Integration Guide](/docs/integration-guide).
 The React bindings ship with the main package — no extra install.
 
 ```ts
-import { useAblo } from '@abloatai/ablo/react';
+import { useAblo, useAbloClient } from '@abloatai/ablo/react';
 ```
 
 React uses the same objects and operations as core Ablo. Read `ablo.status`
@@ -21,11 +21,12 @@ with `useAblo(ablo => ablo.status)`, select `ablo.presence.others` for other
 sessions, and call ordinary model methods from event handlers. React owns the
 subscription or component lifetime; the client owns the behavior.
 
-For mutation failures, subscribe to the core event in an effect:
+For mutation failures, let the hook own the subscription:
 
 ```tsx
-const ablo = useAblo();
-useEffect(() => ablo?.onMutationFailure(reportFailure), [ablo, reportFailure]);
+import { useMutationFailure } from '@abloatai/ablo/react';
+
+useMutationFailure(reportFailure);
 ```
 
 `reportFailure` receives `Ablo.MutationFailure`. Read application identity from
@@ -85,12 +86,12 @@ export const ablo = Ablo({
 });
 
 // The typed binding: capture the schema once, and every component imports
-// born-typed hooks from this file — `useAblo()` takes no type arguments,
+// born-typed hooks from this file — `useAbloClient()` takes no type arguments,
 // and a selector's `ablo` parameter knows your models.
-export const { AbloProvider, useAblo, usePresence } = createAbloReact(schema);
+export const { AbloProvider, useAblo, useAbloClient, usePresence, useMutationFailure } = createAbloReact(schema);
 ```
 
-Import `AbloProvider`, `useAblo`, and `usePresence` from `lib/ablo` rather than from the
+Import `AbloProvider`, `useAbloClient`, `useAblo`, and `usePresence` from `lib/ablo` rather than from the
 package, and the schema generic never appears at a call site again — the
 same one-binding-file convention as tRPC's `createTRPCReact` or
 react-redux's typed hooks.
@@ -109,25 +110,24 @@ import { ablo } from '@/lib/ablo';
 
 export function Providers({
   children,
-  user, // resolved server-side from YOUR auth
 }: {
   children: React.ReactNode;
-  user: { id: string };
 }) {
   return (
-    <AbloProvider client={ablo} userId={user.id} fallback={<AppSkeleton />}>
+    <AbloProvider client={ablo} fallback={<AppSkeleton />}>
       {children}
     </AbloProvider>
   );
 }
 ```
 
-`client` is the only required prop. The rest are situational:
+`client` is the only required prop. The removed `userId` prop is no longer accepted;
+read application identity from your authentication context. Ablo authority comes
+from the client session. The remaining props are situational:
 
 | Prop        | Default          | Purpose                                                                                                   |
 | ----------- | ---------------- | --------------------------------------------------------------------------------------------------------- |
 | `client`    |: | **Required.** The `Ablo({ schema, apiKey })` instance. It carries the schema and connection config. |
-| `userId`    | resolved from auth | App participant id for app-owned fields and your `identityRoles`. Not the security boundary.            |
 | `fallback`  | neutral spinner  | Rendered during the *first* bootstrap only. Pass a branded skeleton, `null`, or `'passthrough'`.          |
 | `onError`   |: | Engine / WebSocket / bootstrap errors. Wire to Sentry / Datadog.                                          |
 
@@ -145,7 +145,7 @@ session owner calls `await ablo.dispose()` on logout or before replacing that
 client. Provider remounts can reuse it. Never share a browser singleton across
 server requests. When changing accounts, remove the old account UI and create a
 fresh client whose session endpoint grants the newly verified membership.
-A query filter and the provider's `userId` prop do not change authorization.
+Query filters and application identity state do not change authorization.
 
 For a component-owned client, create and dispose the instance in the same effect.
 React Strict Mode can replay setup and cleanup, so each setup creates a fresh
@@ -252,7 +252,7 @@ Use the zero-argument form only when you need the full client for callbacks,
 effects, or writes:
 
 ```tsx
-const abloClient = useAblo();
+const abloClient = useAbloClient();
 ```
 
 Prefer selector reads like `useAblo((ablo) => ablo.<model>.local.get(id))`. Older hooks
@@ -302,7 +302,7 @@ For client event handlers, get the application-owned client and call the same
 model client:
 
 ```tsx
-const ablo = useAblo();
+const ablo = useAbloClient();
 
 async function markReady() {
   if (!ablo) return;
@@ -376,7 +376,7 @@ signals. The model and record choose the authorized sync group; the payload
 does not need routing fields or caller-authored identity.
 
 ```tsx
-const ablo = useAblo();
+const ablo = useAbloClient();
 
 useEffect(() => {
   if (!ablo) return;
@@ -431,3 +431,46 @@ its returned cleanup function.
 
 The Next.js [App Router landing](./examples/nextjs.md) walks through Server Components
 + Server Actions + `useAblo` together.
+
+## Separate packages and monorepos
+
+Put the schema in an application-owned package, with a public export for its
+value and type. Put the React binding in a client module which imports that
+schema, and export its inferred declarations. Components import their hooks from
+that binding package. Build the schema package before its dependents and test the
+emitted declarations without workspace source aliases.
+
+```ts
+'use client';
+import { createAbloReact } from '@abloatai/ablo/react';
+import { schema } from '@app/schema';
+
+export const { AbloProvider, useAbloClient, useAblo, usePresence, useMutationFailure } =
+  createAbloReact(schema);
+```
+
+Use one binding per schema, and mount its hooks under a provider for that schema.
+The binding specializes types; it does not create an isolated runtime context or
+validate that a different binding's provider has the same schema. Keep React and
+the Ablo package family deduplicated across packages. Reusable libraries should
+accept a schema or typed binding rather than declare an application-global schema.
+An app's ambient registration cannot retroactively change a separately compiled
+library. Use `defineMutators(schema, definitions)`, `useMutators(schema, definitions)`
+and `useUndoScope(schema, name)` across those boundaries.
+
+## Mutation failures and scoped collaborators
+
+```tsx
+const peers = usePresence(client => client.records, id, { excludeSelf: true });
+useMutationFailure(({ error }) => showToast(error.message));
+```
+
+`useMutationFailure` uses the latest committed callback, moves its subscription
+when the provider client changes, and unsubscribes on unmount. For non-React
+callers, `client.onMutationFailure` returns the cleanup function.
+
+For a custom framework adapter, `getAbloStore(client)` from
+`@abloatai/ablo/client` returns the supported `Ablo.Store` contract: local pool
+access, mutation observation, and scope management. Ordinary writes, confirmation,
+reconnection and model events already have public client methods; they do not
+require a store adapter.

package/llms.txt

@@ -174,7 +174,7 @@ coordination until the app reports it through Data Source events.
 
 ## Change propagation
 
-A change to one row reaches other rows three ways. ROUTING: a write fans out to every sync group the row belongs to, INCLUDING its ancestors' groups (editing a block routes to `block:` + `document:` + `workspace:`), so everyone watching the workspace sees it — delivery, not recomputation. DELETE CASCADE: deleting a parent emits explicit tombstone deltas for its descendants, so open clients never silently hold rows that are gone. VALUE: derived values are NOT recomputed server-side — Ablo surfaces that the source moved and the actor decides. To keep dependent work fresh, pass rows returned by `ablo.<model>.read({ id })` in the mutation's `reads` array. Ablo records compact model/id/readAt evidence, not row contents. At commit the server checks whether anything moved past the read watermark; if so, the mutation does not land. Use `get` when no such relationship exists. To chain A→B→C, put A+B in one group and B+C in another: A's change reaches B, and C hears it only once B ITSELF writes. No transitive auto-recompute, no convergence guarantee for cycles.
+A change to one row reaches other rows three ways. ROUTING: a write fans out to every sync group the row belongs to, including declared ancestor routes for models without `subject`; subject-scoped rows route exclusively through their required subject group, so only eligible subscribers receive them — delivery, not recomputation. DELETE CASCADE: deleting a parent emits explicit tombstone deltas for its descendants, so open clients never silently hold rows that are gone. VALUE: derived values are NOT recomputed server-side — Ablo surfaces that the source moved and the actor decides. To keep dependent work fresh, pass rows returned by `ablo.<model>.read({ id })` in the mutation's `reads` array. Ablo records compact model/id/readAt evidence, not row contents. At commit the server checks whether anything moved past the read watermark; if so, the mutation does not land. Use `get` when no such relationship exists. To chain A→B→C, put A+B in one group and B+C in another: A's change reaches B, and C hears it only once B ITSELF writes. No transitive auto-recompute, no convergence guarantee for cycles.
 
 ## Nouns
 
@@ -322,3 +322,7 @@ Canonical docs to read before integrating, in this order. Read each with `npx ab
 - [Upgrade Guide](https://docs.abloatai.com/migration): when upgrading an existing integration; every breaking change, what to change, and which version introduced it.
 - [Session Settings](https://docs.abloatai.com/session-settings): when the customer's database has row-level-security policies; the identity context Ablo sets before every write, and how to map it to the setting names those policies read.
 - [Every page, one line each](https://docs.abloatai.com/llms.txt), or [the full docs as one file](https://docs.abloatai.com/llms-full.txt).
+
+## Groups and shared context
+
+Groups connect data membership to authorized participant subscriptions. Model roots, relations and grants describe routing and membership; policy, subject and capability operations establish access. Subject-scoped rows route exclusively through their subject group. Reactive clients load and maintain local state; HTTP agents read or observe changes explicitly. Group removal currently clears the managed client cache and requests re-bootstrap, rather than selectively evicting rows. Membership does not imply loaded data, activity, or a lock. Start with `ablo docs groups` for the lifecycle and the account multiplayer example; use `ablo docs identity` for authentication and credential issuance.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/ablo",
-  "version": "0.64.0",
+  "version": "0.64.2",
   "description": "The public Ablo SDK for coordinated reads, commits, claims, observation, and reactive applications.",
   "license": "Apache-2.0",
   "type": "module",
@@ -132,7 +132,8 @@
     "build:docs": "node scripts/build-blume-docs.mjs",
     "lint:docs-site": "node scripts/build-blume-docs.mjs --check",
     "lint:docs": "node scripts/check-doc-drift.mjs",
-    "lint:pkg": "publint"
+    "lint:pkg": "publint",
+    "verify:package-contract": "node scripts/package-contract/index.mjs"
   },
   "publishConfig": {
     "access": "public",
@@ -145,8 +146,8 @@
     "directory": "packages/ablo"
   },
   "dependencies": {
-    "@abloatai/humans": "^0.64.0",
-    "@abloatai/transaction": "^0.64.0",
+    "@abloatai/humans": "0.64.2",
+    "@abloatai/transaction": "0.64.2",
     "zod": "^4.4.3"
   },
   "peerDependencies": {