@abloatai/ablo 0.64.1 → 0.64.3

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,14 +1,120 @@
 # Changelog
 
+## 0.64.3
+
+### Existing connections make room for new tables
+
+`ablo connect apply --tables` now checks the requested tables even when an
+existing connection reports ready. It reconciles publication membership before
+returning, keeping existing credentials intact. If a snapshot needs recovery,
+the requested tables are reconciled before that recovery begins; a snapshot
+already in progress is left undisturbed.
+
+Generated PostgreSQL setup also includes the replica identity needed to retain
+old row values for updates and deletes. The companion sync-server changes track
+snapshot coverage against the active schema, so adding a model cannot inherit
+an older snapshot's readiness. Those server changes require a runtime rollout;
+upgrading the CLI alone does not deploy them.
+
+### One session mint at browser startup
+
+A cold reactive client now uses its first session credential to resolve identity,
+avoiding a second call to the application's session endpoint and its membership
+checks. Later refreshes still obtain a fresh credential. The React guide also
+clarifies application-owned disposal, account switching and startup retry.
+
+The browser packages now include their event emitter dependency. Applications
+can bundle the React entry with an ordinary browser bundler without supplying a
+Node `events` polyfill themselves.
+
+### A clearer boundary for customer accounts
+
+The customer-isolation guide now follows one application connection, explicit
+model subject rules and sessions minted from verified membership. It separates
+your application's account IDs from Ablo organization, project and branch scope,
+and explains what must change in writers, existing rows and database policies
+when adopting that model. Session and API-key guidance use the same distinction.
+
+### Prepare schema SQL without a connection
+
+`ablo migrate --offline` generates schema SQL without database credentials or an
+Ablo API key. It prints the SQL or writes it with `--output`, using the same
+planner as a connected migration. The output is explicitly unvalidated: applying
+a migration still requires the connected deployment checks, as do previews that
+omit `--offline`.
+
+This release introduces no breaking API changes. Ablo, Transaction, Humans and
+the CLI are published together at 0.64.3.
+
+## 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
 
-The React read and write boundaries are now explicit: `useAbloClient()` returns the writable client and `useAblo(selector)` returns render snapshots. The zero-argument `useAblo()` overload is removed. `ablo upgrade` reports migration hints; see [Upgrade Guide](./docs/migration.md).
+### 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.
 
-Public schema registration reaches Transaction and Humans across emitted package declarations. Ambient mutators without a registered schema now report a schema diagnostic; prefer explicit-schema overloads. Internal package dependencies are exact, and CLI/SDK compatibility is checked as one release family.
+### One release, with an explicit upgrade path
 
-`usePresence(..., { excludeSelf: true })` and `presence.forModel(model, id, { excludeSelf: true })` omit the current session. `useMutationFailure` owns React subscription cleanup. Custom framework adapters use `getAbloStore(client)` from `/client`. Generic collaboration subscriptions preserve their declared event tuples; attributed handlers use `collaboration.subscribe` (or transport `subscribeCollaboration`).
+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.
 
-`AbloProvider` is now the sole provider vocabulary. Advanced framework adapters use `useAbloStoreContext` and `AbloStoreContextValue`; the missing-provider error code is `ablo_context_missing_provider`.
+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
 

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/docs/api-keys.md

@@ -234,7 +234,7 @@ Both management scopes are explicit grants on `mk_` credentials. Runtime
 `sk_`, `rk_`, `pk_`, and `ek_` credentials cannot become management
 credentials through an empty scope set or a CLI fallback.
 
-Branch binding remains an authority boundary even when a key has no granular
+For ordinary application keys, branch binding remains an authority boundary even when a key has no granular
 scope strings: a temporary child key can act only inside that child. It cannot
 manage siblings or gain root authority.
 
@@ -253,11 +253,23 @@ Treat that key as a dedicated minting credential:
 - rotate it on a schedule and revoke it immediately after suspected exposure;
 - log the target `organizationId`, minted session id, and request id for audit.
 
-The scope's broad name describes the cross-organization check it passes, not
-the authority of each resulting session. The session can act only inside the
-named customer organization and only for the models/verbs in `can`. See
-[Customer Organizations](./customer-organizations.md) for the complete
-integration.
+The issuer's `organization:act-as` grant can target **any organization**. Ablo
+does not enforce an application-customer allowlist for that authority. A resulting
+session is restricted by its target organization, model operations and expiry,
+but restricting a session does not narrow the issuer's power to mint another.
+Cross-organization mints select the target organization's root branch, including
+when the issuer is bound to a child branch.
+
+Normal dashboard key provisioning does not grant this scope. Ablo operators
+provision it using `apps/sync-server/scripts/provision-platform-key.ts` with
+`--org=<issuer-org> --branch=<issuer-branch> --env=sandbox` (or `production`). The
+script requires control-plane database access and emits a new secret once.
+The environment flag controls the credential prefix; it does not force target
+sessions onto a staging branch.
+
+For customers sharing one application, use model subject rules and verified
+session groups with an ordinary application key. See
+[Serving Many Customers](./customer-organizations.md).
 
 ## Current and legacy key spellings
 

package/docs/cli.md

@@ -133,7 +133,7 @@ branch-bound runtime credential before starting application code.
 | `ablo branch list\|status\|check\|create\|ensure\|credential\|delete` | Manage and diagnose immutable branch planes and expiring credentials.                          | Run `ablo branch --help`; use `--json` for automation.                                                   |
 | `ablo logs`                        | Tail the resolved runtime credential's branch activity. Follows by default.                                                                          | `-n, --tail <N>`, `--since <dur\|ts>`, `--model`, `--op`, `--json`, `--no-follow` |
 | `ablo push`                        | **Hosted**: upload the schema to Ablo; the server diffs, migrates, and activates it.                                                         | `--force`, `--rename old:new`, `--backfill model.field=value`, `--schema`, `--export`, `--url`         |
-| `ablo migrate`                     | **Direct Postgres**: provision just the synced models (plus the adapter's `ablo_outbox` / `ablo_idempotency`) in your own `DATABASE_URL`. Leaves your other tables alone.                                                          | `--dry-run`, `--output <file>`, `--schema`, `--export`                                                 |
+| `ablo migrate`                     | **Direct Postgres**: provision just the synced models (plus the adapter's `ablo_outbox` / `ablo_idempotency`) in your own `DATABASE_URL`. Leaves your other tables alone.                                                          | `--offline`, `--dry-run`, `--output <file>`, `--schema`, `--export`                                                 |
 | `ablo pull`                        | **Direct Postgres**: generate `defineSchema(...)` from your existing tables (read-only, like `prisma db pull`).                              | `--out <path>`, `--app-schema <name>`, `--import <pkg>`, `--force`                                     |
 | `ablo check`                       | **Direct Postgres**: verify your _existing_ tables fit the schema (read-only, no schema changes).                                                       | `--schema <path>`, `--export <name>`, `--app-schema <name>`                                            |
 | `ablo connect plan\|apply\|check\|rotate\|deregister` | **Direct Postgres**: register and maintain a database plane. Here `--schema` means the existing PostgreSQL namespace, never a TypeScript file. | `--url <postgres-url>`, `--schema <postgres-schema>`, `--env-file <path>`, `--yes` |
@@ -266,9 +266,16 @@ server applies the change and version-gates connecting clients.
 ```bash
 ablo migrate --dry-run            # preview the exact SQL
 ablo migrate                      # apply to DATABASE_URL
-ablo migrate --output schema.sql  # write SQL to a file
+ablo migrate --output schema.sql  # write SQL to a file after connected validation
+ablo migrate --offline --output schema.sql  # generate SQL without credentials
 ```
 
+`--offline` uses the same schema SQL generator without reading database or Ablo
+credentials. Omit `--output` to print SQL. This is schema generation, not a
+validated deployment plan: it cannot detect existing-data conflicts or drift.
+Run `ablo migrate` with credentials to validate and apply; `--dry-run` and
+`--output` without `--offline` retain connected validation.
+
 ### One database, two schemas
 
 `ablo migrate` does **not** own your whole database. It creates exactly the

package/docs/customer-organizations.md

@@ -1,184 +1,147 @@
 # Serving Many Customers
 
-> One account, one schema, and a session scoped to the customer whose data it may read.
+> One application connection, customer subject rules, and sessions minted from verified membership.
 
-Serving many customers from one backend has two shapes, and the first question
-is whether isolating them is a security boundary or a routing convenience.
+For a multi-account application, keep one Ablo organization, one project for the
+application, and one branch per environment. Your customers remain rows in your
+own database. Their existing account IDs can identify the subjects authorized by
+Ablo; they do not need corresponding Ablo account registrations.
 
-**Use a model `subject` rule for account isolation inside one project.** Bind
-`accountId` to the `account` group, mint sessions only after verifying membership,
-and use those scoped sessions for server operations too. The complete
-[account multiplayer walkthrough](./examples/account-multiplayer.md) shows this
-composition and its verification path.
+## What each layer owns
 
-A separate Ablo organization per customer is another tenant boundary. It is not
-required merely because your application has accounts.
+| Layer | Meaning | Boundary |
+| --- | --- | --- |
+| Ablo organization | Your team's Ablo account | Outer organization authority |
+| Project | Your application and its schema | Application data plane |
+| Branch | An environment of that application | Connection, retained log and branch-bound credentials |
+| Customer subject | An account in your application | A model rule checks the row against verified session groups |
+| Session | One human or agent's granted access | Subject membership, model operations and expiry |
 
-**Sync-group routing alone is not subject authorization.** The older routing-only
-example below illustrates delivery configuration; add subject rules before using
-that pattern as a customer security boundary. The limitations below describe
-models without subject rules, not subject-protected models.
+`organizationId` on a session names the outer Ablo organization. It does not
+select an account inside your application. A model's `subject` declares that
+inner boundary; session `groups` supplies the authenticated membership needed
+to pass it. Routing groups alone are not row authorization.
 
-```ts
-// 1. src/ablo/schema.ts — your customer table is a scope root.
-import { defineSchema, identityRole, relation, model, z } from '@abloatai/ablo/schema';
-
-export const schema = defineSchema(
-  {
-    // Its rows form the group `customer:<id>`; the kind comes from `groups.root`.
-    customers: model(
-      { name: z.string() },
-      { groups: { root: 'customer' } },
-    ),
-    // A child inherits its customer's group through the `parent` edge.
-    decks: model(
-      { customerId: z.string(), title: z.string() },
-      { relations: { customer: relation.belongsTo('customers', 'customerId', { parent: true }) } },
-    ),
-  },
-  {
-    identityRoles: [
-      identityRole({ kind: 'org', source: 'organizationId' }),
-      identityRole({ kind: 'user', source: 'userId' }),
-    ],
-  },
-);
-```
+## Declare the customer boundary
+
+Use an explicit required account field on every customer-protected model:
 
 ```ts
-// 2. app/api/ablo-session/route.ts — mint for one customer, on your backend.
-import { syncGroup } from '@abloatai/ablo/schema';
-import { sessions } from '@/ablo/sessions';
-
-export const POST = sessions.handler({
-  authenticate: () => currentSignedInMember(),
-  grant: ({ principal: member }) => ({
-    user: { id: member.userId },
-    can: { customers: ['read'], decks: ['read', 'create', 'update'] },
-    groups: [syncGroup('customer', member.customerId)],
-  }),
+import { defineSchema, model, z } from '@abloatai/ablo/schema';
+
+export const schema = defineSchema({
+  conversationSummaries: model({
+    accountId: z.string().min(1),
+    title: z.string(),
+  }, { subject: { field: 'accountId', group: 'account' }, load: 'instant' }),
 });
 ```
 
-That is the whole integration. The rest of this page is why each line is where
-it is.
-
-## What each layer is
-
-Four things carry a name in this arrangement, and mixing two of them up is the
-one mistake worth spending a page to prevent.
-
-| Layer | What it is | Where it lives |
-|---|---|---|
-| Your account | The organization you signed up with. Colleagues join it with their own logins and share one bill. | Ablo |
-| Your application | A project. One per app you run, bound to one schema in your database. | Ablo |
-| Your customer | A row in your own table, with your own id on it. | Your database |
-| One person's session | An `ek_` your backend mints, cut to one customer's group. | Minted per sign-in |
-
-Your customers sit in the third row. They are not accounts, because an account
-is something you invite colleagues into. They are not projects, because a
-project binds to a Postgres schema and you run one application, not one per
-customer.
-
-Your `sk_` already carries your account, so a session never names it. What the
-session adds is which customer the person in front of it may read.
-
-## Where the boundary is enforced
+The subject rule requires the session to hold `account:<row.accountId>`. Keep
+account IDs from Better Auth, or another membership system, in this field.
+The outer tenancy column `organization_id` retains the owning Ablo organization;
+it is not a second name for the customer account field.
 
-Two mechanisms do different jobs, and the difference is the whole of this page.
+Push the schema to the application branch and apply subject policies through
+[supported connection setup](./data-sources.md). Updating TypeScript alone does
+not update the server schema, existing rows or database policies. For an existing
+projection, migrate its writer and backfill as well as its model declaration.
 
-**Your account is the tenant boundary.** Every row Ablo stores carries your
-organization, project, and branch, and all three are compared on every read and
-every write, from the credential rather than the request. A client cannot reach
-past them by asking. This is the boundary that holds unconditionally.
+## Mint after verifying membership
 
-**Without a subject rule, sync groups are a routing cut inside your account.** They decide which changes are delivered and which rows a
-log-served read returns. That is routing. It is not a universal authorization
-boundary, and the gaps are specific:
-
-| Path | Group cut applied |
-|---|---|
-| Live delivery and fan-out | Yes |
-| HTTP read on a log-served plane (a connected database) | Yes |
-| HTTP read on a hosted or direct-query plane | **No.** Scoped by organization |
-| Writes | **No.** The groups are recorded on the change, never checked against the row |
-| Claim listings and presence | Yes |
-
-So a session cut to one customer, on a hosted plane, can read another
-customer's rows over HTTP; and on any plane it can write to them. What stops it
-today is the organization, which both customers share under this shape.
-
-If isolating your customers is a security requirement, give each one its own
-Ablo organization. The stronger row-and-subject authorization that would make
-this shape safe on every path is not in the engine yet.
-
-## Naming a group
-
-Build a group with the `syncGroup(kind, id)` helper rather than a string. The
-kind is the one you declared in `groups.root`, and the id is your own
-identifier for the customer.
+Your backend authenticates the person and verifies membership in the requested
+account on every mint. Use the verified account ID, never an unchecked request
+parameter:
 
 ```ts
-groups: [syncGroup('customer', member.customerId)]
+import Sessions from '@abloatai/ablo/sessions';
+import { syncGroup } from '@abloatai/ablo/schema';
+import { schema } from './schema';
+
+const sessions = Sessions({ schema, apiKey: process.env.ABLO_API_KEY! });
+const session = await sessions.create({
+  user: { id: verifiedMember.userId },
+  groups: [syncGroup('account', verifiedMember.accountId)],
+  can: { conversationSummaries: ['read'] },
+  ttlSeconds: 300,
+});
 ```
 
-Resolve `member.customerId` from the membership you just authenticated on the
-server. A signed-in person can put any value in a request body, and the session
-you mint is what decides what they can read.
+This session inherits the issuer's organization, project and branch. No
+`organizationId` override or `organization:act-as` grant is needed. The model's
+subject rule authorizes rows; `can` authorizes operations. A list filter merely
+selects a view.
 
-## When a customer should be its own organization
+The [account multiplayer walkthrough](./examples/account-multiplayer.md) contains
+the complete server membership handler, browser lifecycle and scoped server
+writes. A secret-key singleton must not substitute for a subject-scoped session
+when performing customer operations.
 
-Whenever their isolation has to hold. Give each customer its own Ablo
-organization when one of them reading or writing another's rows would be an
-incident rather than a bug, when you cannot audit group coverage across every
-model, or when a customer is a separate paying business that signs in to Ablo
-itself and invites its own developers.
+## Share one database connection
 
-Your backend then names the customer's organization on the mint, which takes a
-secret key carrying `organization:act-as`. The customer never sees Ablo; the
-scope exists because the session leaves the organization the key belongs to.
+Customers with subject-protected rows in the same application branch use that
+branch's connected database and schema. There is no per-customer connection
+registration. Ablo serves connected-plane reads from its retained log, populated
+from the database; readiness and snapshot coverage still need verification.
 
-## Onboarding a customer
+A Data Source is selected by organization, project and branch. Neither a subject
+ID nor a routing group selects a different connection.
 
-Insert the row. There is nothing to register with Ablo, because the group is
-derived from the row's id, and the first session minted against it is delivered
-its data.
+## Where isolation is enforced
 
-Add a project only when you add an application. `npx ablo projects create` takes
-a management credential from `ablo login`, and one project holds one schema.
+For models with subject rules, the server checks subject membership beneath the
+UI across bootstrap, known-ID and list HTTP reads, live delivery and catch-up.
+Write authorization checks the row's subject too. Routing membership in another
+group does not bypass the subject rule. Models without subject rules do not gain
+customer isolation merely because a session names an account group.
 
-## Troubleshooting
+Before enabling browser reads, test two real accounts against the deployed SDK,
+server and connection configuration:
 
-### A session reads nothing
+- Bootstrap exposes only the authorized account's rows.
+- Reading another account's known row ID over HTTP is denied.
+- Live updates and reconnect catch-up do not expose foreign rows.
+- Switching accounts disposes the previous client and does not display its
+  IndexedDB data in the newly authorized account.
 
-Check the groups the session was minted with against the kind in `groups.root`.
-A group whose kind is not declared matches nothing, which reads as an empty
-database rather than an error.
+The maintained example and authorization journeys provide runnable checks;
+local tests are not evidence that a deployed fleet has the same behavior.
+[Groups and shared context](./groups.md) describes cache clearing and membership
+changes. An external membership change does not automatically revoke every
+already-issued session, and offline cached copies cannot be remotely retracted.
 
-### A session reads another customer's rows
+## When to use separate Ablo organizations
 
-Check that the model declares a `parent` edge up to the scope root. A model with
-no group of its own and no parent belongs to no group, so a group cut does not
-narrow it.
+Choose separate organizations when customers own separate Ablo accounts or need
+separate outer data planes. The engine can use an unregistered organization
+scope ID; this does not register an Ablo billing account or connect a database.
 
-### The mint is refused
+Cross-organization minting requires a secret key explicitly granted
+`organization:act-as`. That authority can target any organization; there is no
+application-customer allowlist on the grant. Normal dashboard key creation does
+not grant it. It is operator-provisioned platform authority, not a prerequisite
+for serving customers through the shared-application pattern above.
 
-Naming `organizationId` reaches into a different account and takes
-`organization:act-as`. A platform serving its own customers names groups
-instead, and its key needs no scope at all.
+A cross-organization session uses the target organization's default project and
+root branch. It does **not** inherit the issuer's staging branch. Its schema may
+come from the issuer's project, but its data connection does not: every target
+plane needs its own supported data-source setup. Sharing a schema artifact alone
+does not establish shared Aurora reads.
 
-## See it yourself
+See [Sessions](./sessions.md) for schema binding and [API keys](./api-keys.md) for
+the authority and lifecycle of a platform mint key.
 
-```
-npx ablo whoami --json
-```
+## Troubleshooting
 
-The `syncGroups` it reports are the cut the engine will apply. If a customer's
-group is missing there, no read will show its rows.
+**The mint is refused.** For customers inside one application, omit
+`organizationId`, declare subject rules and grant verified account groups. Do
+not remove the override without migrating a model that currently uses the
+customer ID as its outer tenancy column.
 
-## Related guides
+**A session reads nothing.** Check the branch, pushed subject rule, stored account
+field, granted groups and connection readiness. A schema shared across
+organizations does not share the source connection.
 
-- [Identity & Sync Groups](/identity) — how groups are declared and resolved.
-- [Sessions](/sessions) — session lifetime, refresh, and revocation.
-- [API Keys](/api-keys) — credential classes and scopes.
-- [Projects](/projects) — one project per application.
+**A session reads another customer's row.** Check the actual pushed model's
+subject declaration and the session's verified groups. A parent edge, routing
+group or client filter alone is not an authorization rule.

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
@@ -47,7 +50,8 @@ Your application authenticates the person and verifies membership on every
 mint. The subject rule authorizes rows; `groups` proves membership; `can`
 authorizes operations. Synchronization delivers the authorized data. A list
 filter helps select a view but does not establish any of these permissions.
-The provider's `userId` prop is informational, not an authentication mechanism.
+React reads application identity from your auth context; the provider accepts
+no `userId` prop.
 
 ## Browser reads and server writes share the scope
 

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>
 ```

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).
 

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

@@ -110,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.                                          |
 
@@ -146,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
@@ -182,6 +181,12 @@ for the requested account on every mint; the URL itself grants no access.
 See the [account multiplayer walkthrough](./examples/account-multiplayer.md)
 for the complete ownership boundary and runnable component.
 
+Use `onError` to show a startup failure outside the bootstrap gate. After a
+transient failure, remount the provider with the same client to retry readiness;
+failed `ready()` attempts are retryable. After logout or an account change,
+create a fresh client instead. Strict Mode may create two client instances in
+development; each instance owns its own credential lifecycle.
+
 ## Render immediately with connection status
 
 `useAblo(ablo => ablo.status)` works during provider startup, in passthrough children and in

package/docs/sessions.md

@@ -182,7 +182,7 @@ for the actor.
 |---|---|---|
 | `user` / `agent` | both | The actor. `id` becomes the token's `participantId`. Pass exactly one. |
 | `can` | both | Required non-empty per-model operation allowlist, typed off the schema. |
-| `organizationId` | user | Mint into a customer organization instead of the key's own. Requires `organization:act-as`. |
+| `organizationId` | user | Select another Ablo organization, not an application account. Requires `organization:act-as`; uses the target root branch. |
 | `schemaProject` | user | Override the schema project for a cross-org mint. Usually omitted because the owning key's project is the default. |
 | `groups` | both | Narrow the session below its default scope. Omit to inherit. |
 | `ttlSeconds` | both | Lifetime in seconds. Defaults to `900` (15m). |
@@ -273,34 +273,24 @@ Some apps need each customer to be its **own** tenant — a hard data boundary
 scoping. The law-firm shape (Legora): every firm is its own org, many users
 inside it.
 
-Choose the boundary before minting sessions:
+For customers sharing one application connection, declare a model `subject`
+rule and mint verified account `groups` with the ordinary application key. Keep
+its organization, project and branch. The [customer guide](./customer-organizations.md)
+owns the complete tenancy model, migration requirements and isolation checks.
 
-| Customer model | Isolation guarantee | Use when |
-|---|---|---|
-| One Ablo organization, customer scope roots | Every model's declared `policy` | Cross-customer access is intentional or every model explicitly partitions by the customer root |
-| One Ablo organization per customer | Structural organization filtering and RLS on every row | Customers must be isolated even when a model has no customer policy |
-
-Sync-group routing controls which changes are delivered; it does not grant or
-deny reads. Do not use scope roots as a tenant security boundary unless every
-model declares the matching policy. If that invariant is difficult to audit,
-use one organization per customer.
-
-For the complete key, backend-route, browser, lifecycle, and troubleshooting
-flow, see [Customer Organizations](./customer-organizations.md).
-
-The problem that creates: if each customer is a separate org, a naïve setup would
-make you re-push your schema into every new customer's org. You don't have to.
-Keep **one** project as the home of your schema. When its key mints into another
-organization, Ablo automatically resolves the session's *schema* from that key's
-project while its *data* stays in the customer's own org:
+Separate Ablo organizations are separate data planes. A cross-organization user
+session can reuse the issuer's schema artifact, but it uses the target
+organization's default project and root branch. It does not inherit the issuer's
+staging branch or database connection. Each target plane needs its own supported
+data-source setup.
 
 ```ts
-const ablo = Ablo({ schema, apiKey: process.env.ABLO_PLATFORM_KEY });
-const { token } = await sessions.create({
+const sessions = Sessions({ schema, apiKey: process.env.ABLO_PLATFORM_KEY! });
+const session = await sessions.create({
   user: { id: userId },
-  organizationId, // DATA → this customer's isolated org
+  organizationId, // A separate Ablo organization and data plane.
   can: { records: ['read', 'update'] },
-  ttlSeconds: 3600,
+  ttlSeconds: 300,
 });
 ```
 
@@ -322,10 +312,10 @@ your users in the key's own organization.
 
 ## Security
 
-The whole safety argument is the short TTL: a session token leaked from a
-browser (XSS) is valid for minutes, scoped to one actor's data, and can't mint
-anything or touch the control plane. Contrast `sk_`, which would be a full org
-compromise — which is exactly why it never leaves your server.
+Session authority combines the organization/project/branch boundary, model
+subject rules, verified groups, the `can` allowlist and expiry. A short TTL limits
+exposure; it does not create row isolation. Keep issuer secret keys on the
+server and verify membership whenever issuing or renewing customer sessions.
 
 ## User vs. agent sessions
 

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.1",
+  "version": "0.64.3",
   "description": "The public Ablo SDK for coordinated reads, commits, claims, observation, and reactive applications.",
   "license": "Apache-2.0",
   "type": "module",
@@ -120,6 +120,7 @@
     "verify:context-package": "node scripts/verify-context-package.mjs",
     "typecheck": "tsc --noEmit && tsc -p typetests/tsconfig.json && tsc -p examples/tsconfig.json",
     "test": "vitest run",
+    "test:browser-bundle": "node scripts/check-browser-bundle.mjs",
     "generate:errors": "tsx --conditions=@ablo/source scripts/generate-error-docs.mts",
     "lint:errors": "tsx --conditions=@ablo/source scripts/check-error-docs.mts",
     "generate:pricing": "tsx scripts/generate-pricing-docs.mts",
@@ -146,8 +147,8 @@
     "directory": "packages/ablo"
   },
   "dependencies": {
-    "@abloatai/humans": "0.64.1",
-    "@abloatai/transaction": "0.64.1",
+    "@abloatai/humans": "0.64.3",
+    "@abloatai/transaction": "0.64.3",
     "zod": "^4.4.3"
   },
   "peerDependencies": {