@abloatai/ablo 0.59.2 → 0.61.0

package/CHANGELOG.md

@@ -1,5 +1,82 @@
 # Changelog
 
+## 0.61.0
+
+### Existing database connections repair in place
+
+`ablo connect apply` is now the single repeatable operation for both a new
+database connection and an existing registration. A healthy connection is a
+no-op. When a registration predates current publication, replica-identity,
+grant, or row-level-security requirements, the same command reconciles those
+database-owned invariants through the transient owner URL while preserving
+Ablo's working scoped passwords.
+
+If that repair means an earlier initial snapshot may have omitted rows, the
+operation requests the required fresh snapshot and subsequent reruns report its
+loading or ready state. Automation can select `--json` for stable lifecycle and
+per-step codes instead of parsing human output. Credential rotation remains an
+explicit operation for an actually incomplete or invalid role pair.
+
+## 0.60.0
+
+### Sessions are the connection boundary for people and agents
+
+`Sessions({ schema, apiKey })` is now the dedicated session issuer. Backends create scoped
+agent sessions with `sessions.create({ agent, can, groups })` and expose browser
+sessions with `sessions.handler({ authenticate, grant })`. Both return the same
+short-lived session contract, and both are supplied to clients through
+`Ablo({ schema, session })`:
+
+```ts
+const workerAccess = {
+  records: ['read', 'update'],
+} as const;
+
+import Sessions from '@abloatai/ablo/sessions';
+
+const sessions = Sessions({ schema, apiKey: process.env.ABLO_API_KEY });
+
+const session = () =>
+  sessions.create({
+    agent: { id: stableWorkerId },
+    groups: [workspaceGroup],
+    can: workerAccess,
+  });
+
+const agent = Ablo({ schema, session });
+```
+
+Session clients default to one reconnecting WebSocket for commits, claims,
+observation, presence, and collaboration. API-key clients remain HTTP by
+default, and bounded session work can select `transport: 'http'` explicitly.
+Model calls do not open additional sockets.
+
+An async session provider represents one renewable logical identity. The client
+caches each short-lived credential until it approaches `expiresAt`, pre-mints a
+replacement, and reconnects with that replacement when necessary. Durable
+observation resumes from its acknowledged cursor across socket replacement.
+A provider resolving `null` means the application login ended and terminates the
+session; a thrown error remains transient. A static session object cannot renew
+itself and ends when its bearer expires. In-flight commits whose outcome became
+ambiguous still reject and can be retried with their original idempotency key.
+
+The browser client now names its session route as
+`session: { endpoint: '/api/ablo-session' }`; `authEndpoint` is removed. Public
+connection scope is `groups`; public `syncGroups` is removed. The overlapping
+`agents.create`, `join`, and `useJoin` lifecycles are also removed: connection
+groups define visibility, `usePeers` reads presence, and row claims own
+exclusion.
+
+Internally, session contract, creation, handler, source normalization, and
+credential renewal now live beneath one `sessions` boundary. HTTP bootstrap and
+the live socket consume the same normalized session access, so credential
+identity and renewal policy cannot diverge.
+
+Session issuance no longer occupies a property on `Ablo(...)`. That client owns
+the schema model namespace, so an application model named `sessions` works as
+`ablo.sessions` like any other model. Issuance and lifecycle administration stay
+server-only behind the explicit `@abloatai/ablo/sessions` import.
+
 ## 0.59.2
 
 ### Patch Changes

package/README.md

@@ -127,7 +127,7 @@ flattening the implementation into `packages/ablo`:
 - `packages/ablo` is the branded public facade. Its files mostly re-export the
   package that owns each API.
 - `packages/transaction` owns the shared model-operation contracts and the
-  stateless HTTP implementation.
+  headless HTTP/WebSocket transport implementation.
 - `packages/humans` owns the reactive WebSocket/local/React implementation.
 
 That means searching only inside `packages/ablo/src` will not find the

package/dist/ai-sdk.js.map

@@ -1 +1 @@
-{"version":3,"file":"ai-sdk.js","sourceRoot":"","sources":["../src/ai-sdk.ts"],"names":[],"mappings":"AAAA,cAAc,8BAA8B,CAAC;AAE7C,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,MAAM,2BAA2B,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3C,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;CACnD,CAAC,CAAC;AAYH,kFAAkF;AAClF,MAAM,UAAU,cAAc,CAC5B,KAA2B,EAC3B,OAAO,GAAiC,EAAE;IAE1C,MAAM,EAAE,OAAO,EAAE,GAAG,2BAA2B,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAC/D,MAAM,IAAI,GAAG,OAAO,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAChD,MAAM,QAAQ,GAAG,MAAM,CAAC,WAAW,CACjC,IAAI,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CACzE,CAAC;IACF,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAC5B,QAAQ,EACR,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,IAAI,EACjE,CAAC,CACF,CAAC;IACF,OAAO;QACL,IAAI,EAAE,MAAM;QACZ,OAAO,EAAE,0DAA0D,OAAO,EAAE;KAC7E,CAAC;AACJ,CAAC"}
+{"version":3,"file":"ai-sdk.js","sourceRoot":"","sources":["../src/ai-sdk.ts"],"names":[],"mappings":"AAAA,cAAc,8BAA8B,CAAC;AAE7C,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,MAAM,2BAA2B,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3C,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;CACnD,CAAC,CAAC;AAYH,kFAAkF;AAClF,MAAM,UAAU,cAAc,CAC5B,KAA2B,EAC3B,UAAwC,EAAE;IAE1C,MAAM,EAAE,OAAO,EAAE,GAAG,2BAA2B,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAC/D,MAAM,IAAI,GAAG,OAAO,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAChD,MAAM,QAAQ,GAAG,MAAM,CAAC,WAAW,CACjC,IAAI,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CACzE,CAAC;IACF,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAC5B,QAAQ,EACR,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,IAAI,EACjE,CAAC,CACF,CAAC;IACF,OAAO;QACL,IAAI,EAAE,MAAM;QACZ,OAAO,EAAE,0DAA0D,OAAO,EAAE;KAC7E,CAAC;AACJ,CAAC"}

package/dist/sessions.d.ts

@@ -0,0 +1,3 @@
+export { Sessions, Sessions as default } from '@abloatai/transaction/sessions';
+export type { AbloSession, CreateAgentSessionParams, CreateSessionParams, CreateUserSessionParams, RevokeSessionParams, RotateSessionParams, SessionCredential, SessionEndpoint, SessionHandler, SessionHandlerOptions, SessionProvider, SessionProviderResult, SessionRevocation, SessionRotation, SessionScope, SessionSource, SessionsClient, SessionsOptions, } from '@abloatai/transaction/sessions';
+//# sourceMappingURL=sessions.d.ts.map

package/dist/sessions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessions.d.ts","sourceRoot":"","sources":["../src/sessions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,QAAQ,IAAI,OAAO,EAAE,MAAM,gCAAgC,CAAC;AAC/E,YAAY,EACV,WAAW,EACX,wBAAwB,EACxB,mBAAmB,EACnB,uBAAuB,EACvB,mBAAmB,EACnB,mBAAmB,EACnB,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,qBAAqB,EACrB,eAAe,EACf,qBAAqB,EACrB,iBAAiB,EACjB,eAAe,EACf,YAAY,EACZ,aAAa,EACb,cAAc,EACd,eAAe,GAChB,MAAM,gCAAgC,CAAC"}

package/dist/sessions.js

@@ -0,0 +1,2 @@
+export { Sessions, Sessions as default } from '@abloatai/transaction/sessions';
+//# sourceMappingURL=sessions.js.map

package/dist/sessions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessions.js","sourceRoot":"","sources":["../src/sessions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,QAAQ,IAAI,OAAO,EAAE,MAAM,gCAAgC,CAAC"}

package/docs/agent-messaging.md

@@ -75,11 +75,12 @@ await ablo.ready();
 ```
 
 The secret `apiKey` is server-only. Browser clients must not receive it; live UIs
-use the default WebSocket transport with a minted user/session token.
+use the reactive client with `session.endpoint`, which owns their WebSocket and
+short-lived user-session renewal.
 
 If your backend mints restricted agent tokens, register the database once from a
 secret-key server process as above. Workers using the restricted token can then
-construct `Ablo({ schema, authToken, transport: "http" })` because the project
+construct `Ablo({ schema, session, transport: "http" })` because the project
 already has a registered data plane.
 
 ## Link a message to a claim

package/docs/agents.md

@@ -22,21 +22,33 @@ These are observational reads. Use `read({ id })` only when a later Ablo write
 depends on that exact version and will pass it through `reads`.
 
 Most agents wake on a trigger, read what they need, write a result, and go idle.
-That is a request/response workload, so they use plain HTTP. A resident agent
-that needs pushed deltas, queued-claim grants, or presence selects
-`transport: 'websocket'`. The credential is the identity on both carriers; the
-server resolves the org, scope, and actor from it.
-
-Short-lived agents use HTTP. Long-running agents may add a multiplexed
-WebSocket without installing the human materializer. People add the `humans()`
-plugin for a local reactive graph. All three operate on the same typed,
+Trusted service work uses an API key and plain HTTP. An agent that needs its own
+scoped identity receives a session; session clients use one reconnecting
+WebSocket by default. The server resolves the org, scope, and actor from the
+credential on both carriers.
+
+Create scoped credentials with the server-only issuer:
+
+```ts
+import Sessions from '@abloatai/ablo/sessions';
+
+const sessions = Sessions({ schema, apiKey: process.env.ABLO_API_KEY });
+```
+
+API-key services use HTTP. Session agents use a multiplexed WebSocket without
+installing the human materializer. People add the `humans()` plugin for a local reactive graph. All three operate on the same typed,
 coordinated state and enter the same server-side commit and claim paths.
 
 ```ts
+const session = () => sessions.create({
+  agent: { id: stableWorkerId },
+  can: workerAccess,
+  groups: [workspaceGroup],
+});
+
 const ablo = Ablo({
   schema,
-  apiKey: process.env.ABLO_API_KEY,
-  transport: 'websocket',
+  session,
   cursorStore,
 });
 
@@ -73,14 +85,14 @@ authenticates; the [schema](/installation) defines what you can call.
 
 ## The agent client
 
-Same `Ablo()` entry point as everywhere else — pass `transport: 'http'`. No
-socket, no connection state — just your schema (for types) and an API key.
+Same `Ablo()` entry point as everywhere else. An API-key client is HTTP: no
+socket or connection state, just your schema and service credential.
 
 ```ts
 import Ablo from "@abloatai/ablo";
 import { schema } from "./schema";
 
-const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY, transport: "http" });
+const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
 
 // Reads + writes, fully typed off your schema.
 // `get` resolves to the row, or `undefined` when none matches.
@@ -99,12 +111,12 @@ and `claim`. It does **not** expose stateful-only `local` reads or model
 selected WebSocket transport, or holds one POST/SSE response until the context
 changes on the HTTP transport.
 
-## Managed scoped agents
+## Scoped agent sessions
 
-When this process owns the secret client and also runs the agent, prefer
-`agents.create`. It mints the restricted credential, returns a schema-typed
-client, and renews that credential for a long run. `sessions.create({ agent })`
-is the raw-token path for handing identity to another runtime.
+`Sessions(...).create({ agent })` is the one issuance path. It returns a restricted
+credential; construct the schema-typed client in the runtime that executes the
+agent. This keeps session minting, revocation, and rotation under one resource
+for both people and agents.
 
 Derive identity and groups from the run row or trusted job payload—not from
 model output or an HTTP request body. A serverless handler normally creates and
@@ -114,12 +126,14 @@ disposes one child per invocation:
 const run = await control.runs.read({ id: verifiedRunId });
 if (!run) throw new Error('run not found');
 
-const agent = await control.agents.create({
-  id: `run:${run.id}`,
-  name: 'run-worker',
+const session = await sessions.create({
+  agent: { id: `run:${run.id}` },
   can: { records: ['read', 'update'] },
-  syncGroups: [`workspace:${run.workspaceId}`],
+  groups: [`workspace:${run.workspaceId}`],
+  userMeta: { name: 'run-worker' },
 });
+
+const agent = Ablo({ schema, session, transport: 'http' });
 try {
   await executeRun(agent, run);
 } finally {
@@ -128,29 +142,32 @@ try {
 ```
 
 Use a stable id only when one logical run is serialized; two concurrent workers
-that share an id appear as the same participant. For independent concurrent
-work, omit `id` and let Ablo create distinct identities.
+that share an id appear as the same participant. Generate a different id for
+each independent concurrent run.
 
-A long-running worker may cache one managed client per stable scope, but the
-cache owns lifecycle: evict idle clients, call `dispose()` on eviction, and
-dispose every client during graceful shutdown. Never cache a client and later
-reuse it for a different workspace or capability set.
+A long-running worker may cache one client per stable scope and provide an
+async credential resolver that re-mints the same session identity. The cache
+owns lifecycle: evict idle clients, call `dispose()` on eviction, and dispose
+every client during graceful shutdown. Never reuse a client for a different
+workspace or capability set.
 
 ```ts
 const agents: Record<
   string,
-  Awaited<ReturnType<typeof control.agents.create>> | undefined
+  ReturnType<typeof Ablo> | undefined
 > = {};
 
 async function agentFor(run: Run) {
   const key = `${run.workspaceId}:${run.workerSlot}`;
   const cached = agents[key];
   if (cached) return cached;
-  const created = await control.agents.create({
-    id: `worker:${key}`,
+  const agentId = `worker:${key}`;
+  const session = () => sessions.create({
+    agent: { id: agentId },
     can: { records: ['read', 'update'] },
-    syncGroups: [`workspace:${run.workspaceId}`],
+    groups: [`workspace:${run.workspaceId}`],
   });
+  const created = Ablo({ schema, session });
   agents[key] = created;
   return created;
 }

package/docs/api-keys.md

@@ -28,7 +28,7 @@ and remap them before each command.
 | Prepare a branch once, including CI | expiring `sk_` bound to that branch | `npx ablo dev --no-watch --branch <ref>`; headless CI supplies an `mk_` credential through `ABLO_API_KEY`. |
 | Run the production backend | `sk_` bound to the production root | Store it as the deployment's `ABLO_API_KEY`. |
 | Read in a browser | `pk_` | Publishable, read-only key. |
-| Write in a browser as a user | short-lived `ek_` | Your backend exposes `authEndpoint` and mints it. |
+| Write in a browser as a user | short-lived `ek_` | Your backend exposes a session endpoint and mints it. |
 
 The everyday loop is therefore:
 
@@ -71,16 +71,18 @@ already carries the target.
 
 ## Which credential to pass to the SDK
 
-There's **one field — `apiKey`** — and what you pass depends on **where the code runs**.
-Pick your row:
+There are two ordinary identity inputs: `apiKey` for a key the process owns and
+`session` for a scoped actor. Pick your row:
 
 | Where your code runs | What to pass | Example |
 |---|---|---|
 | **Server / worker / agent** (can hold a secret) | your secret `sk_`: it defaults to `ABLO_API_KEY`, so usually pass **nothing** | `Ablo({ schema })` |
 | **Browser: read-only** | a publishable `pk_` (safe to ship) | `Ablo({ schema, apiKey: process.env.NEXT_PUBLIC_ABLO_PUBLISHABLE_KEY })` |
-| **Browser: writing as the signed-in user** | `authEndpoint`: the route on your own backend that mints a short-lived per-user token | `Ablo({ schema, authEndpoint: '/api/ablo-session' })` |
+| **Browser: writing as the signed-in user** | `session.endpoint`: the route on your own backend that mints a short-lived per-user token | `Ablo({ schema, session: { endpoint: '/api/ablo-session' } })` |
 
-That's the whole story: one knob, filled by audience.
+The names follow ownership: a process owns an API key; an actor runs through a
+session, regardless of whether that session is already minted, renewable, or
+fetched from a browser endpoint.
 
 The `mk_` credential created by `ablo login` is different: it is a CLI
 control-plane credential, not an application API key. It can manage projects
@@ -104,24 +106,28 @@ For an `ek_`, the server mints and the client holds the short-lived result.
 public `pk_` is **read-only** — it can't carry one specific user's write authority. So when
 the browser writes *as the logged-in user*, your backend (which holds the secret `sk_` and
 knows who's signed in) mints a short-lived per-user token with `sessions.create({ user, can })`,
-and the browser's `apiKey` function fetches it. You don't manage refresh — the SDK calls the
+and the browser's `session.endpoint` fetches it. You don't manage refresh — the SDK calls the
 function once before connecting and then keeps the token fresh (re-mint before expiry, and on
 tab-focus / network-online / device-wake). For a read-only app you don't need
 any of this — just the `pk_` above.
 
 Server-side, because `apiKey` defaults to `process.env.ABLO_API_KEY`, most backend and agent
 code passes nothing. The secret `sk_` is **server-only** — never in a
-browser bundle. There is no `getToken` or `as` option — `apiKey` (the key a server holds)
-and `authEndpoint` (the mint route a browser points at) are the two credential
-knobs, and you set exactly one.
+browser bundle. There is no `getToken`, `as`, or separate auth-endpoint option:
+`apiKey` is the key a process owns, while `session` is a minted resource, a
+renewal provider, or `{ endpoint }`. Set exactly one identity input.
 
 ### Minting per-user / agent tokens (server-side, with your `sk_`)
 
+Construct the dedicated issuer with
+`Sessions({ schema, apiKey: process.env.ABLO_API_KEY })` from
+`@abloatai/ablo/sessions`. It is server-only and does not create a participant
+connection.
+
 | Mint | Call | Result |
 |---|---|---|
-| Human end-user session | `await server.sessions.create({ user: { id }, can: { records: ['read'] } })` | `ek_` (scoped to `can`) |
-| Ready agent client | `await server.agents.create({ can: { records: ['update'] } })` | Auto-refreshing client scoped to `can` |
-| Raw delegated agent token | `await server.sessions.create({ agent: { id }, can: { records: ['update'] } })` | `rk_` for another runtime |
+| Human end-user session | `await sessions.create({ user: { id }, can: { records: ['read'] } })` | `ek_` (scoped to `can`) |
+| Agent session | `await sessions.create({ agent: { id }, can: { records: ['update'] } })` | Scoped `rk_` for the agent runtime |
 
 The principal kind comes from *which* shape you pass — `{ user, can }` → `user`, `{ agent, can }` → `agent`.
 

package/docs/cli.md

@@ -136,6 +136,7 @@ branch-bound runtime credential before starting application code.
 | `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 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` |
 | `ablo generate`                    | Emit TypeScript types from the schema.                                                                                                        | `--out <path>`, `--schema`, `--export`                                                                 |
 | `ablo docs`                        | Read these pages for the version you installed: offline, no network (see [`ablo docs`](#ablo-docs)).                                          | `--json`                                                                                               |
 

package/docs/client-behavior.md

@@ -28,10 +28,12 @@ const ablo = Ablo({
 });
 ```
 
-The package-root export is the stateless HTTP client for agents, workers, route
-handlers, and other server operations. See [Options](./options.md) for its exact
-constructor reference. Live state and local reads are added through the
-[React client](./react.md).
+The package-root export is the headless coordination client for agents, workers,
+route handlers, and other server operations. Trusted API-key clients use HTTP.
+Scoped session clients use one reconnecting WebSocket for commits and live
+coordination; point reads and administration remain HTTP. See [Transports](./transports.md)
+for the lifecycle and [Options](./options.md) for the constructor. A human-facing
+local graph is added through the [React client](./react.md).
 
 Your database connects out of band — through logical replication (`npx ablo
 connect`), or the signed [Data Source](./data-sources.md) endpoint as the

package/docs/coordination.md

@@ -206,11 +206,15 @@ same credential represent the same participant and do not exclude one another.
 Mint a distinct scoped session for each independently coordinated agent:
 
 ```ts
-const { token } = await server.sessions.create({
+import Sessions from '@abloatai/ablo/sessions';
+
+const sessions = Sessions({ schema, apiKey: process.env.ABLO_API_KEY });
+const session = await sessions.create({
   agent: { id: `forecast-agent-${workerId}` },
+  can: { records: ['read', 'update'] },
 });
 
-const agent = Ablo({ schema, apiKey: token });
+const agent = Ablo({ schema, session });
 ```
 
 Functional updates do not require distinct participant identities because they
@@ -305,7 +309,6 @@ The main methods are:
 | `claim.state({ id })` | Read the current holder without blocking. |
 | `claim.queue({ id })` | Read the current wait order. |
 | `claim.release({ id })` | Release early when you do not hold a handle. |
-| `join({ scope })` | Observe presence for a broader scope. |
 
 This page owns row-backed claims: `model.claim({ id })` reads and claims an Ablo
 model row, and the handle carries fresh data. Identifier-only claims before an

package/docs/customer-organizations.md

@@ -47,27 +47,16 @@ export const schema = defineSchema(
 ```ts
 // 2. app/api/ablo-session/route.ts — mint for one customer, on your backend.
 import { syncGroup } from '@abloatai/ablo/schema';
-import { credentialEndpointSuccessSchema } from '@abloatai/ablo/auth';
-import { ablo } from '@/ablo/server';
+import { sessions } from '@/ablo/sessions';
 
-export async function POST() {
-  const member = await requireSignedInMember();
-
-  const session = await ablo.sessions.create({
+export const POST = sessions.handler({
+  authenticate: () => currentSignedInMember(),
+  grant: ({ principal: member }) => ({
     user: { id: member.userId },
     can: { customers: ['read'], decks: ['read', 'create', 'update'] },
-    syncGroups: [syncGroup('customer', member.customerId)],
-  });
-
-  return Response.json(
-    credentialEndpointSuccessSchema.parse({
-      token: session.token,
-      expiresAt: session.expiresAt,
-      credentialKind: 'ephemeral',
-    }),
-    { headers: { 'Cache-Control': 'no-store' } },
-  );
-}
+    groups: [syncGroup('customer', member.customerId)],
+  }),
+});
 ```
 
 That is the whole integration. The rest of this page is why each line is where
@@ -130,7 +119,7 @@ kind is the one you declared in `groups.root`, and the id is your own
 identifier for the customer.
 
 ```ts
-syncGroups: [syncGroup('customer', member.customerId)]
+groups: [syncGroup('customer', member.customerId)]
 ```
 
 Resolve `member.customerId` from the membership you just authenticated on the

package/docs/data-sources.md

@@ -132,6 +132,27 @@ npx ablo connect apply --env-file .env.local --yes
 The explicit flag makes the credential choice visible and loads both the
 branch-bound key and database URL. Shell environment variables take precedence.
 
+### Two schema flags, two ownership boundaries
+
+`migrate` and `push` read your Ablo TypeScript contract. `connect apply` also
+reads it to derive the mapped Postgres tables; `--tables` is an explicit
+override:
+
+```bash
+# TypeScript contract and export; app-schema selects its Postgres namespace.
+npx ablo migrate --schema ablo/schema.ts --export schema --app-schema public
+
+# Existing Postgres namespace only. Never pass ablo/schema.ts here.
+npx ablo connect apply --schema public --yes
+
+# Activate the TypeScript contract after the database is connected.
+npx ablo push --schema ablo/schema.ts --export schema
+```
+
+If the database uses its default namespace, omit `connect --schema`; it defaults
+to `public`. Keep the three operations in this order in deployment automation:
+expand tables, connect the database, then activate the hosted schema.
+
 ### One database, several projects
 
 Provider database URLs and Postgres schemas solve different isolation jobs:
@@ -190,13 +211,18 @@ npx ablo connect apply --url postgres://admin:...@host:5432/db --schema mail
 ```
 
 Pass an admin connection string with `--url` and select the application namespace
-with `--schema` (default `public`). It creates a per-binding publication, two
-per-binding scoped roles, and the grants, turns on logical decoding where it can, registers
-both scoped roles with Ablo, and proves the setup by reconnecting and reading back.
+with `--schema` (default `public`). It inspects and reconciles a per-binding
+publication, two per-binding scoped roles, grants, replica identity,
+registration, and the initial snapshot. On an existing healthy registration it
+is a no-op and preserves both passwords. A policy-only repair also preserves
+them; credential rotation happens only through the explicit `connect rotate`
+operation.
+
 The admin credential is used on this machine only and never persisted — nothing is
-written to your `.env`, which keeps holding only `ABLO_API_KEY`. Pass `--show-sql`
-to see every statement first, or drop `--apply` to print the SQL and run it
-yourself. Rotate the scoped passwords any time with `ablo connect rotate`.
+written to your `.env`, which keeps holding only `ABLO_API_KEY`. Pass
+`--show-sql` to see every statement first, `--json` for stable result and step
+codes, or drop `--apply` to print the SQL and run it yourself. Rotate the scoped
+passwords any time with `ablo connect rotate`.
 
 The rest of this page is what that command sets up, step by step, for when you want
 to run it by hand or review exactly what changes.
@@ -215,19 +241,20 @@ the row to be visible already, and touching application rows is neither necessar
 nor a safe bootstrap mechanism.
 
 If a connection was snapshotted with an older replication role whose row-level
-security hid historical rows, repair that role and request the load again without
-deregistering or rotating credentials:
+security hid historical rows, rerun the same operation. It repairs the owned
+policy and requests the necessary fresh load without deregistering or rotating
+credentials:
 
 ```bash
-npx ablo connect rotate      # reasserts BYPASSRLS and safely re-registers both roles
-npx ablo connect resnapshot  # recreates only the slot; the load is asynchronous
-npx ablo connect check       # repeat until the existing-row load is complete
+npx ablo connect apply --url postgres://owner:...@host/db --yes --json
+# Rerun the same command: loading becomes ready; a healthy rerun is a no-op.
 ```
 
-Use the same `resnapshot` step after adding an existing populated table to the
-publication. Following its future WAL changes is not enough to load rows written
-before publication membership; the snapshot coverage guard therefore refuses to
-record completion when even one mapped table is absent. Relation matching is
+Rerun `connect apply` after adding an existing populated table to the contract.
+Following its future WAL changes is not enough to load rows written before
+publication membership, so reconciliation updates membership and requests the
+fresh snapshot together. The snapshot coverage guard refuses to record
+completion when even one mapped table is absent. Relation matching is
 schema-qualified using the DataSource's configured `schema` (default `public`):
 an identically named table in another Postgres schema neither counts as coverage
 nor enters the snapshot or WAL stream for your model.

package/docs/deployment.md

@@ -120,16 +120,17 @@ is genuinely unavailable.
 
 ## 2. The credential each runtime holds
 
-There is one field, `apiKey`, and what goes in it follows from where the code
-runs. In production that resolves to four rows:
+Credential configuration follows the runtime. Long-lived root keys use
+`apiKey`; scoped actors use `session`; browser login exchange uses
+`session.endpoint`:
 
 | Runtime | Credential | Notes |
 |---|---|---|
 | Server, worker, agent, cron | `sk_` in `ABLO_API_KEY` | Defaults from the environment, so most code passes nothing. |
-| Serverless function | `sk_` in `ABLO_API_KEY`, with `transport: 'http'` | Stateless request/response; nothing held open across invocations. |
-| Resident agent | restricted `rk_` or agent-scoped credential, with `transport: 'websocket'` | One multiplexed WebSocket per client and Ablo cell; checkpoint durable deltas before acknowledging. |
+| Serverless function | `sk_` in `ABLO_API_KEY` | Stateless request/response; nothing held open across invocations. |
+| Long-running agent | `session: () => sessions.create(...)` | One renewable identity and one multiplexed WebSocket per client and Ablo cell; checkpoint durable deltas before acknowledging. |
 | Browser, read-only | root-bound `pk_` | Publishable, safe to ship, and read-only. |
-| Browser, writing as the signed-in user | `authEndpoint` | A route on your backend mints a short-lived `ek_` per user. |
+| Browser, writing as the signed-in user | `session: { endpoint }` | A route on your backend mints a short-lived `ek_` per user. |
 
 [API Keys](./api-keys.md) covers the model; [Sessions](./sessions.md) covers
 minting. Two things bite specifically at deploy time.
@@ -284,7 +285,7 @@ and what each promises.
    browser bundle.
 3. `ablo plan` reviewed, followed by fingerprint-gated `ablo push --yes`.
 4. `ablo status --json` gating the deploy on an empty `blockers` array.
-5. Browser clients on a root-bound `pk_` or an `authEndpoint`, not a secret key.
+5. Browser clients on a root-bound `pk_` or `session.endpoint`, not a secret key.
 6. Webhook endpoints registered at their deployed URLs, with the signing secret
    in your environment.
 

package/docs/examples/existing-python-backend.md

@@ -48,12 +48,18 @@ export const schema = defineSchema({
 ```ts
 // web/ablo.ts — SERVER-ONLY client (holds the sk_ key; never imported in the browser).
 import Ablo from '@abloatai/ablo';
+import Sessions from '@abloatai/ablo/sessions';
 import { schema } from './ablo/schema';
 
 export const ablo = Ablo({
   schema,
   apiKey: process.env.ABLO_API_KEY,
 });
+
+export const sessions = Sessions({
+  schema,
+  apiKey: process.env.ABLO_API_KEY,
+});
 ```
 
 Mount the React provider near the app root. Build the browser client first —
@@ -69,11 +75,11 @@ import { Ablo } from '@abloatai/ablo/react';
 import { AbloProvider } from '@abloatai/ablo/react';
 import { schema } from '@/ablo/schema';
 
-// Browser client: no secret key — `authEndpoint` points at the session route
+// Browser client: no secret key — `session.endpoint` points at the session route
 // your server exposes (below); the SDK fetches and refreshes the token.
 const ablo = Ablo({
   schema,
-  authEndpoint: '/api/ablo-session',
+  session: { endpoint: '/api/ablo-session' },
 });
 
 export function Providers({ children }: { children: React.ReactNode }) {
@@ -86,26 +92,17 @@ browser only ever sees the short-lived token:
 
 ```ts
 // web/app/api/ablo-session/route.ts
-import { ablo } from '@/ablo';
-import { credentialEndpointSuccessSchema } from '@abloatai/ablo/auth';
+import { sessions } from '@/ablo';
 
 export const runtime = 'nodejs';
 
-export async function POST() {
-  const userId = await currentUserId(); // your auth
-  const { token, expiresAt } = await ablo.sessions.create({
-    user: { id: userId },
+export const POST = sessions.handler({
+  authenticate: () => currentUser(), // your auth; null when signed out
+  grant: ({ principal: user }) => ({
+    user: { id: user.id },
     can: { records: ['read', 'update'] },
-  });
-  return Response.json(
-    credentialEndpointSuccessSchema.parse({
-      token,
-      expiresAt,
-      credentialKind: 'ephemeral',
-    }),
-    { headers: { 'Cache-Control': 'no-store' } },
-  );
-}
+  }),
+});
 ```
 
 ## 2. Add Live Reads In The UI