@abloatai/ablo 0.60.0 → 0.62.0

package/CHANGELOG.md

@@ -1,5 +1,59 @@
 # Changelog
 
+## 0.62.0
+
+Every live client now exposes one session-owned `ablo.presence` projection.
+`active` shows the current session's announced activity and `others` shows the
+other visible sessions. The reactive client adds `forModel(model, id?)` to
+narrow the same projection without opening another connection. Read, claim,
+create, update, and delete activity share one typed, model-addressable contract
+and remain attributable to their originating human or agent session.
+
+Claims and presence now have separate owners: the durable claim authority
+decides admission, queuing, fencing, expiry, and release, while presence
+projects that lifecycle for live collaborators. Cross-replica HTTP callers
+resolve and release claims against the shared authority instead of a
+process-local roster. An object-form claim also returns its protected row
+snapshot in the acquisition request, removing the post-grant read race and an
+extra round trip.
+
+This replaces the earlier participant-oriented presence stream and its raw
+wire event vocabulary. Migrate `PresenceStream`, `Peer`, `Activity`,
+`PresenceUpdate*`, and `PresenceKind` consumers to `Ablo.Presence`,
+`Ablo.PresenceSession`, and `Ablo.PresenceActivity`; read the projection through
+`ablo.presence.active`, `ablo.presence.others`, or
+`ablo.presence.forModel(model, id?)`. The low-level `presence_update` event,
+frame-handler members, presence schemas, and claim-stream participant setters
+are removed because session identity and typed presence snapshot/patch frames
+now own that lifecycle.
+
+Admission and other transient failures now expose machine-actionable
+`recovery`, `retryable`, and `retryAfterSeconds` fields through the branded
+package, including session issuance and headless model requests. The headless
+client automatically replays an admission-rejected request after the requested
+delay, without restarting the surrounding claim workflow. Queued HTTP claims
+heartbeat through their known model and row target, so one holder releasing
+cannot make the next queued ticket appear lost during promotion. A visibility
+miss while the fence is minted is retried only inside the ticket's last
+server-acknowledged lease window.
+
+## 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

package/dist/coordination.d.ts

@@ -2,9 +2,9 @@ export * from '@abloatai/transaction/coordination';
 /**
  * Coordination vocabulary that the streams module declares.
  *
- * A caller that holds a claim, watches presence, or types an activity feed
- * needs these names, and coordination is where they belong — so they are
+ * A caller that holds a claim needs these names, and coordination is where
+ * they belong — so they are
  * surfaced here rather than leaving callers to reach into the type module.
  */
-export type { Activity, Claim, ClaimTarget } from '@abloatai/transaction/types/streams';
+export type { Claim, ClaimTarget } from '@abloatai/transaction/types/streams';
 //# sourceMappingURL=coordination.d.ts.map

package/dist/coordination.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"coordination.d.ts","sourceRoot":"","sources":["../src/coordination.ts"],"names":[],"mappings":"AAAA,cAAc,oCAAoC,CAAC;AAEnD;;;;;;GAMG;AACH,YAAY,EAAE,QAAQ,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,qCAAqC,CAAC"}
+{"version":3,"file":"coordination.d.ts","sourceRoot":"","sources":["../src/coordination.ts"],"names":[],"mappings":"AAAA,cAAc,oCAAoC,CAAC;AAEnD;;;;;;GAMG;AACH,YAAY,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,qCAAqC,CAAC"}

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

@@ -157,13 +157,20 @@ see. Options on the claim:
 - `{ maxQueueDepth }` rejects if the wait line is already too deep.
 
 While waiting, schema clients learn when the claim clears from the live claim
-stream, so they never poll.
+stream, so they never poll. Headless HTTP clients poll the same durable queue;
+the model client keeps the row target on each heartbeat, so a holder releasing
+cannot make the queued ticket unresolvable by id. During fence minting, it also
+keeps polling through a visibility miss only while the server's last enqueue or
+heartbeat acknowledgement still guarantees that ticket is live.
 
 ## Errors
 
 All SDK errors extend `AbloError`. `type` is the class-name discriminator, such
 as `AbloStaleContextError`; `code` is the wire condition, such as
 `stale_context`. Use `instanceof` in-process and `type` after serialization.
+Every error also exposes a typed `recovery` classification and `retryable`
+boolean. When the server requests a minimum delay, `retryAfterSeconds` is
+present on the same error for both 429 and 503 responses.
 
 | Error | Typical cause |
 |---|---|
@@ -196,8 +203,14 @@ Model writes are retry-safe by default because the SDK attaches an idempotency
 key. If you provide your own key, keep it stable for retries of the same logical
 operation and never reuse it for a different payload.
 
-Retry transport failures and 5xx with backoff. Do not blindly retry validation,
-permission, idempotency, or stale-context errors without changing the request.
+Retry transport failures and 5xx with backoff. For example, an
+`instance_at_capacity` error has `recovery === 'transient'`; wait at least
+`retryAfterSeconds` before replaying the unchanged request. The headless HTTP
+client performs that exact replay within `timeoutMs`; importantly, it does not
+restart a larger claim/read/write workflow around the rejected request. If the
+deadline is exhausted, the same actionable error reaches the caller. Do not
+blindly retry validation, permission, idempotency, or stale-context errors
+without changing the request.
 
 ## Logging
 

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/integrations/inngest.md

@@ -242,7 +242,7 @@ examples/
   inngest-agent/              events, functions, steps, endpoint, AI composition
 ```
 
-Do not add Inngest to `packages/agent`. A dedicated `@abloatai/inngest` package
+Do not add Inngest orchestration to the Ablo core. A dedicated `@abloatai/inngest` package
 is justified only after multiple real applications reveal substantial
 reusable behavior beyond a small function or step wrapper.
 

package/docs/integrations/temporal.md

@@ -178,7 +178,7 @@ The repository's
 [`examples/temporal-agent`](../../../../examples/temporal-agent/README.md)
 contains a Workflow, Activities, Worker, client, durable AI SDK tool, and a
 simulated lost-response retry. It is a standalone application on purpose:
-Temporal stays out of Ablo's core packages and out of `packages/agent`.
+Temporal stays out of Ablo's core packages; applications own their agent composition.
 
 A dedicated `@abloatai/temporal` package should be introduced only after
 multiple production integrations reveal substantial, stable behavior that

package/package.json

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