@abloatai/ablo 0.53.0 → 0.54.0

package/CHANGELOG.md

@@ -1,5 +1,135 @@
 # Changelog
 
+## 0.54.0
+
+### A scoped session is scoped everywhere it is read
+
+Seven surfaces each answered "which sync groups may this request see", and two of
+them consulted only `effectiveSyncGroups` before falling back to an
+organization-wide anchor. `syncGroups` is the only field an `ek_` session key
+populates, so a session scoped to one workspace was correctly narrowed on five
+surfaces and read organization-wide on the other two. Nothing failed while they
+disagreed, because each surface's tests pinned that surface to itself.
+
+One module now owns the precedence, and a plane states its difference as an
+argument rather than as another copy of the rule. A declared set that is empty
+means nothing rather than everything, so a session minted with no groups closes
+instead of widening.
+
+### A change reaches the clients watching it, whatever the column is called
+
+Deltas were written in two key shapes. The commit path wrote declared schema
+field names; the replication echo wrote the customer's physical column names
+undecoded. Neither reader reconciled them, because the client applies a delta
+onto the model verbatim.
+
+For a source whose columns are renamed, by `.from(...)` or simply by being
+snake_case, every change reached subscribers keyed wrong, and the lookup that
+stamps a scope-root group found nothing on a physical row. Such a delta kept only
+its organization group, so a client joined to `workspace:<id>` was never sent a
+change it was watching: the write landed, and nothing was announced to anyone
+listening. Rows are renamed once now, where they enter, and one spelling holds
+below that seam.
+
+### Reordering a claim queue takes effect
+
+A reorder took effect for nobody. The route addressed the frame to an
+organization group, which entity-scoped fan-out removes, so the frame was built
+and then dropped as having no audience. A queue change now goes to the waiters in
+that line, each of which recorded what it listens on when it enqueued.
+
+### A commit costs a fixed number of round trips
+
+A direct write paid three round trips to the customer's database plus one per
+row. Sharing a region that is a few milliseconds, but across continents it
+dominated the wait: an engine in `eu-north-1` against a database in `us-east-2`
+measured about four seconds per confirmed write, most of it in trips nobody had
+counted.
+
+Three changes remove trips without altering what the database sees. The session
+bundle is one statement over parallel name and value arrays rather than eleven
+settings awaited in turn, and is still transaction-scoped. The ledger completion
+and the replication marker travel as one data-modifying statement, which Postgres
+runs to completion whether or not the primary query reads it. And a direct commit
+dispatches its operations before awaiting any of them, so the driver pipelines
+them.
+
+Ordering is unchanged: Postgres still runs those operations in order on the
+connection, so a later one still sees an earlier one's write, two writes to the
+same row stay well-defined last-write-wins, and each operation keeps its own
+error so a failure still names itself.
+
+### Engine-reserved groups have a constructor
+
+`identityAnchor` builds the sync groups the engine reserves, so the `kind:id`
+convention has one home instead of being spelled inline:
+
+```ts
+import { identityAnchor } from '@abloatai/ablo/schema';
+
+identityAnchor('org', organizationId);
+identityAnchor('user', participantId);
+identityAnchor('project', projectId);
+```
+
+`IDENTITY_ANCHOR_KINDS` and `IdentityAnchorKind` are exported alongside it.
+Schema-declared roles continue to extend this vocabulary per application; these
+three are the kinds the engine reserves.
+
+### The cross-organization scope is `organization:act-as`
+
+The scope authorizing a secret key to mint a session into another organization is
+now `organization:act-as`, and it names what it grants rather than the mechanism
+it was first attached to. Keys already carrying `ephemeral:mint-any-org` keep
+working, because the old spelling resolves to the new one.
+
+### An outbox event carries declared field names
+
+A hand-written `events` handler must key its `data` by the model's declared
+schema fields rather than by the table's columns. A field named `reviewStatus`
+arrives as `reviewStatus` even when it reads from a `review_status` column:
+
+```ts
+// the model declares reviewStatus from a review_status column
+data: { id: row.id, reviewStatus: row.review_status },
+```
+
+Ablo's own adapters rename the row before writing the outbox, so a source built
+on one of them is already in this shape. Ablo reads that spelling and never falls
+back to the physical one: two namespaces that can collide have no safe merge, and
+a key read as the wrong field would route a change into another scope root.
+
+### CLI: report what got in your way
+
+`ablo feedback` is the channel for the two things no counter can carry, because
+neither is a sentence: the doc that was missing, and the thing that worked but
+was hard.
+
+```
+ablo feedback docs "no example of paging a filtered list" --yes
+```
+
+`<kind>` is `bug`, `docs`, `feature`, or `friction`. Add `--detail <text>` for
+the long version, where `-` reads stdin, and `--command` or `--error-code` to
+pre-group the report from what you just saw. `--yes` sends without confirming
+and `--json` returns a machine-readable receipt, so a non-interactive caller
+needs no terminal.
+
+It is never automatic. Nothing sends unless the command is run, and nothing
+rides the telemetry queue, so turning telemetry off does not also turn off bug
+reporting, and leaving it on does not start sending prose. The text is redacted
+before it leaves, by the same rule error observations already pass through, and
+on a terminal you see the redacted version before it is sent. Nothing is read
+from your repository, and there is no flag to attach a file.
+
+### Removed
+
+`normalizeAbloHostedBaseUrl` is removed, as 0.53.0 announced. Use
+`normalizeAbloBaseUrl`, which the old name has resolved to since then.
+
+`CapabilityExchangeResponse` is announced for removal in 0.55.0. Use
+`CapabilityMintResponse`; both already resolve to the same contract.
+
 ## 0.53.0
 
 ### A collection read says where the collection ends

package/docs/api-keys.md

@@ -217,7 +217,7 @@ restricted to exactly those grants:
 - `project:manage` — list, create, and rename projects.
 - `branch:manage` — list, create, and delete child branches and mint their
   temporary credentials.
-- `ephemeral:mint-any-org` — cross-organization authority to mint a short-lived
+- `organization:act-as` — cross-organization authority to mint a short-lived
   user session into a customer organization. It follows the Stripe Connect shape:
   the request names the customer organization, but the resulting session is
   still bounded by its `can` grant and expiry. A key restricted to this scope
@@ -234,7 +234,7 @@ manage siblings or gain root authority.
 
 ### Cross-organization mint keys
 
-Most applications do not need `ephemeral:mint-any-org`: their backend key mints
+Most applications do not need `organization:act-as`: their backend key mints
 users into its own organization. A multi-organization backend needs it only
 when each customer is a separate Ablo organization and one trusted service
 mints sessions for all of them.
@@ -242,7 +242,7 @@ mints sessions for all of them.
 Treat that key as a dedicated minting credential:
 
 - keep it in a server-side secret manager, never a browser or repository;
-- grant only `ephemeral:mint-any-org`, with no data or schema scopes;
+- grant only `organization:act-as`, with no data or schema scopes;
 - mint short-lived sessions with the smallest typed `can` grant;
 - rotate it on a schedule and revoke it immediately after suspected exposure;
 - log the target `organizationId`, minted session id, and request id for audit.

package/docs/customer-organizations.md

@@ -26,7 +26,7 @@ user session names that customer organization.
 
 - An owning project containing the schema every customer uses.
 - The schema pushed to that project's production root.
-- A server-side `sk_` carrying only `ephemeral:mint-any-org`.
+- A server-side `sk_` carrying only `organization:act-as`.
 - A customer `organizationId` resolved from your authenticated application
   membership, never accepted unchecked from the browser.
 - A model-by-model `can` grant for the UI being opened.
@@ -159,7 +159,7 @@ through the control-plane process you use for provisioning.
 ## Security checklist
 
 - Store the cross-organization key only in the backend secret manager.
-- Give it only `ephemeral:mint-any-org`; do not combine minting with schema or
+- Give it only `organization:act-as`; do not combine minting with schema or
   data authority.
 - Resolve `organizationId` from authenticated membership server-side.
 - Keep `can` to the smallest model/verb set the UI needs.
@@ -175,7 +175,7 @@ through the control-plane process you use for provisioning.
 ### The mint is forbidden
 
 The presenting credential must be a secret `sk_` with
-`ephemeral:mint-any-org`. A normal project key can mint users into its own
+`organization:act-as`. A normal project key can mint users into its own
 organization but cannot name another one. Run `npx ablo whoami --json` in the
 backend environment to confirm which project and branch the configured key
 actually belongs to; the command never prints the full secret.

package/docs/identity.md

@@ -238,7 +238,7 @@ shared schema only *describes* the shape; the data plane stays the customer's an
 can't cross-leak. `schemaProject: { organizationId, projectId }` remains
 available as an explicit override for migrations or advanced routing. Omit
 `organizationId` for the single-organization default above. Requires a dedicated
-`sk_` with `ephemeral:mint-any-org`; see
+`sk_` with `organization:act-as`; see
 [Customer Organizations](./customer-organizations.md).
 
 ## The two halves of scoping

package/docs/sessions.md

@@ -154,7 +154,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 `ephemeral:mint-any-org`. |
+| `organizationId` | user | Mint into a customer organization instead of the key's own. Requires `organization:act-as`. |
 | `schemaProject` | user | Override the schema project for a cross-org mint. Usually omitted because the owning key's project is the default. |
 | `syncGroups` | both | Narrow the session below its default scope. Omit to inherit. |
 | `ttlSeconds` | both | Lifetime in seconds. Defaults to `900` (15m). |
@@ -286,7 +286,7 @@ plane (connection + row-level isolation) stays the customer's. A shared schema
 can't leak data across orgs.
 
 <Note>
-This requires a dedicated `sk_` carrying the `ephemeral:mint-any-org` scope —
+This requires a dedicated `sk_` carrying the `organization:act-as` scope —
 only a trusted cross-organization key can mint a session into another org. Omit
 `organizationId` and you get the default above: one project, one schema, all
 your users in the key's own organization.

package/llms.txt

@@ -243,4 +243,20 @@ Do not teach `/api`, `/agent`, `/core`, `/realtime`, or internal subpaths. (`/so
 
 - `npx ablo docs` lists every documentation page; `npx ablo docs <page>` prints one as markdown. These pages ship INSIDE the installed package, so they describe the version in `node_modules` and need no network. Prefer them over a docs URL whenever the project pins a version: a website always describes the newest release, so on an older pin it will hand you a call your package does not have (`retrieve`/`list` replaced `get`/`getAll`/`getCount` in 0.35.0). One-shot, safe to run unattended.
 
-Canonical docs to read before integrating: `quickstart`, `branch-development`, `schema-contract`, `integration-guide`, `deployment`, `guarantees`, `client-behavior`, `data-sources`, `examples/existing-python-backend`, `api`, `examples/ai-sdk-tool`, and `examples/server-agent` — read each with `npx ablo docs <page>`. When upgrading an existing integration, read `migration` — every breaking change, what to change, and which version introduced it. When the customer's database has row-level-security policies, read `session-settings` — the identity context Ablo sets before every write, and how to map it to the setting names those policies already read.
+## Documentation
+
+Canonical docs to read before integrating, in this order. Read each with `npx ablo docs <page>` when the project pins a version; the links describe the newest release.
+
+- [Quickstart](https://docs.abloatai.com/quickstart)
+- [Branch-first development](https://docs.abloatai.com/branch-development)
+- [Schema Contract](https://docs.abloatai.com/schema-contract)
+- [Integration Guide](https://docs.abloatai.com/integration-guide)
+- [Deployment](https://docs.abloatai.com/deployment)
+- [Guarantees](https://docs.abloatai.com/guarantees)
+- [Client Behavior](https://docs.abloatai.com/client-behavior)
+- [Connect Your Database](https://docs.abloatai.com/data-sources)
+- [API](https://docs.abloatai.com/api)
+- Examples: [Existing Python Backend](https://docs.abloatai.com/examples/existing-python-backend), [AI SDK Tool](https://docs.abloatai.com/examples/ai-sdk-tool), [Server Agent](https://docs.abloatai.com/examples/server-agent)
+- [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).

package/package.json

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