@abloatai/ablo 0.11.0 → 0.11.2

package/CHANGELOG.md

@@ -1,5 +1,63 @@
 # Changelog
 
+## 0.11.2
+
+### Patch Changes
+
+- a35d935: Fix stream-recorded undo capturing the wrong "before" value for updates. A second
+  update to the same field before the first sync-ack re-captured the original
+  pre-session value (first-old-wins + clear-only-on-ack), so undo of a quick second
+  edit jumped all the way back instead of one step. The queue now re-baselines a
+  field's tracked `.old` once its before-image is frozen into the committed
+  transaction.
+
+  Also close the create/update undo asymmetry: an update whose written key had no
+  in-place mutation produced an empty `previousData`, which made the inverse
+  un-revertible (a create's `delete` inverse never is). Before-image capture now
+  falls back to the last loaded/acked snapshot.
+
+  Internally, the two undo paths (stream-recorded and manual `RecordingTransaction`)
+  now share one before-image implementation via `Model.capturePreviousValues` /
+  `Model.consumeModifiedFields`, so they can no longer drift.
+
+- One-correct-way consolidation (breaking; no external consumers yet, so released as a patch):
+  - Credentials collapse to a single `apiKey` — a string, or a `() => Promise<string | null>` that
+    fetches a per-user token. Removed `getToken` / `authEndpoint` / public `authToken`.
+  - `ablo.<model>.watch(ids, { ttl })` replaces the top-level `ablo.participants.join({ scope })` —
+    model-scoped read-interest + presence (WebSocket only).
+  - Read claim-gating is `ifClaimed: 'return' | 'fail'` (removed `'wait'`); waiting is the claim
+    primitive's job (`ablo.<model>.claim`).
+  - The stateless client is `Ablo({ transport: 'http' })`; `createAbloHttpClient` is no longer a
+    public export (the factory uses it internally).
+  - Read-option types renamed: `ServerReadOptions` (server `retrieve`/`list`) and `LocalReadOptions`
+    (local `get`/`getAll`).
+  - `defineSchema` throws a clear error on a reserved-field collision; the MCP/docs API surface is
+    now compile-time bound to the real exported types (can't drift).
+
+## 0.11.1
+
+### Patch Changes
+
+- 7f91f6e: DX hardening from a real onboarding session — onboarding, CLI, coordination, types, and docs.
+
+  **Client behavior**
+  - `databaseUrl` is now an explicit, server-only option: `Ablo(...)` no longer auto-reads `process.env.DATABASE_URL`. A stray `DATABASE_URL` (common — Prisma/Drizzle/docker set it) no longer silently flips the client into connection-string mode; a one-time warning points at the explicit option. Passing `databaseUrl: process.env.DATABASE_URL` explicitly is unchanged.
+  - Claims/presence are now observable from any client (including Node agents): reading a row enters its entity sync group (read-interest) and claiming pins it (write-intent), so `ablo.<model>.claim.state({ id })` reports co-participants without any manual subscribe step — whether the observer arrives before the claim (live delta) or after it (subscribe-time backfill). The claim **holder** now also sees its own claim via `claim.state`. **Requires a coordinated `sync-server` deploy** (the subscribe-time claim backfill + the entity-scope subscription gate that lets an org-authority agent key narrow into a row's group live server-side); the client package change alone does not deliver cross-client agent observation.
+
+  **CLI**
+  - `ablo init` detects the `src/app` layout (routes + the `@/ablo` import alias resolve correctly), writes the **real** stored sandbox key into `.env.local` instead of a placeholder, and scaffolds `ablo/register.ts` (a regular module, not a colliding `ablo.d.ts`).
+  - `ablo <command> --help` / `-h` now prints usage instead of erroring with "unknown flag", and `migrate` is listed in the top-level help.
+  - `ablo dev --no-watch` now exits after one push instead of watching forever.
+
+  **Types**
+  - Name the client with `typeof sync` (the value-inferred idiom, like tRPC's `typeof appRouter` / Drizzle's `typeof db`) — `ReturnType<typeof Ablo>` collapses to the untyped client and should not be used. No bespoke client-type generic is needed.
+  - `model_claim_not_configured` message clarified: claiming needs no per-model schema configuration; every model is claimable through the standard client.
+
+  **Docs**
+  - Reconciled the self-contradictory `databaseUrl` story (it is an explicit, server-only option, not auto-read from the environment; consistent casing), documented that the sandbox can host rows (apiKey only, no database), explained why a localhost Postgres can't be the system of record, and led the connect-your-database flow with `ablo pull`/`ablo check` over `ablo migrate`. Fixed stale `api.md` vocabulary (`object: 'claim'`, `participantKind: 'user' | 'agent' | 'system'`).
+
+- 7f91f6e: Docs: document the completed `intent` → `claim` rename. Adds a 0.11.0 migration entry (`useIntent` → `useClaim`, `Register.Intents` → `Register.Claims`, `Ablo.Intent.*` → `Ablo.Claim.*`, and the coordinated client/server deploy for the `claim_*` wire frames), a `useClaim` section in the React reference, and fixes the stale `participantKind` union to the canonical `'user' | 'agent' | 'system'`.
+
 ## 0.11.0
 
 ### Minor Changes

package/README.md

@@ -54,10 +54,12 @@ claims are visible while the work is still in progress.
 `llms.txt`  ·  **upgrading?** see the
 [Version History & Migration Guide](./docs/migration.md)
 
-It works with the auth and database you already have. **Your database is the
-system of record — Ablo never hosts your data.** Ablo is the transaction layer
-on top of it: realtime data is scoped to *sync groups* from your own identity,
-and every committed row lives in your Postgres.
+It works with the auth and database you already have. **In production, your
+database is the system of record.** Ablo is the transaction layer on top of it:
+realtime data is scoped to *sync groups* from your own identity, and every
+committed row lives in your Postgres. (Trying Ablo with no database yet? The
+hosted **sandbox** can host rows in Ablo's test plane — apiKey only, like
+Stripe test mode — so you can explore before pointing it at your Postgres.)
 
 **Built for** collaborative editors, AI agent workflows, and internal tools —
 anywhere people and agents change shared state and everyone has to see it live.
@@ -65,18 +67,24 @@ anywhere people and agents change shared state and everyone has to see it live.
 ## Set up
 
 The CLI takes you from nothing to a synced schema — it handles the account,
-the key, and the env file. You bring one thing: a Postgres `DATABASE_URL`
-(local, Neon, RDS — any will do; **your database is the system of record,
-Ablo never hosts your data**).
+the key, and the env file. You bring one thing: a Postgres you already have —
+the same `DATABASE_URL` (local, Neon, RDS — any will do) that backs your auth,
+audit, and log tables. Ablo syncs a *subset* of models against it; **in
+production, your database is the system of record**.
 
 ```bash
 npm install @abloatai/ablo
 npx ablo login     # opens the browser: sign in (or sign up) → a sk_test_ key is saved locally
 npx ablo init      # scaffolds ablo/schema.ts (offers to log in if you skipped it)
-npx ablo migrate   # creates the synced tables in YOUR Postgres (reads DATABASE_URL)
-npx ablo push       # pushes your schema (sandbox), writes ABLO_API_KEY to .env.local, watches for changes
+npx ablo push      # pushes your schema (sandbox), writes ABLO_API_KEY to .env.local, watches for changes
 ```
 
+Then point Ablo at the tables for your synced models. Most teams **already
+have those tables** (often Prisma- or Drizzle-managed) — adopt them with
+`npx ablo pull` / `npx ablo check`, the common case. Let Ablo own its own
+tables instead? `npx ablo migrate` provisions them in your Postgres (reads
+`DATABASE_URL`). Either way your other tables are left untouched.
+
 After `ablo push`, the [Quick Start](#quick-start) below runs as-is —
 `ABLO_API_KEY` is already in `.env.local` (frameworks load it automatically;
 plain Node: `node --env-file=.env.local app.ts`). `npx ablo status` shows
@@ -106,18 +114,24 @@ import Ablo from '@abloatai/ablo';
 import { defineSchema, model, z } from '@abloatai/ablo/schema';
 ```
 
-Register the schema once (init scaffolds this `ablo.d.ts`), and every type
-is one parameter away — no `typeof schema` re-stating, anywhere:
+The schema is registered once (init scaffolds `ablo/register.ts` for you), and
+every type is one parameter away — no `typeof schema` re-stating, anywhere:
 
 ```ts
-// ablo.d.ts — once per project
-import type { schema } from './ablo/schema';
+// ablo/register.ts — scaffolded by `npx ablo init`, sits beside ablo/schema.ts
+import type { schema } from './schema';
 declare module '@abloatai/ablo' {
   interface Register { Schema: typeof schema }
 }
 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.
+
 ```ts
 import type { Model } from '@abloatai/ablo/schema';
 
@@ -128,8 +142,29 @@ type WeatherReport = Model<'weatherReports'>; // fully typed from YOUR schema
 TanStack-Router pattern: declare the source of truth once, everything
 infers from it.)
 
+### Naming the client type
+
+When you need to pass the client around (a function parameter, a context value),
+**infer the type from the value** — `type Sync = typeof sync`:
+
+```ts
+export const sync = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
+export type Sync = typeof sync; // fully-typed, schema-aware
+
+function persist(client: Sync) { /* ... */ }
+```
+
+This is the same idiom as tRPC's `type AppRouter = typeof appRouter` and
+Drizzle's `typeof db` — the factory resolves the typed overload at the call
+site, so `typeof sync` carries your schema. Do **not** write
+`ReturnType<typeof Ablo>`: that collapses to the untyped last overload and
+loses your model types. There is no bespoke client-type generic to import —
+`typeof` your client value is the type.
+
 ```ts
 const schema = defineSchema({
+  // Reserved fields (id, createdAt, updatedAt, organizationId, createdBy) are
+  // provided automatically — don't declare them.
   weatherReports: model({
     location: z.string(),
     status: z.enum(['pending', 'ready']),
@@ -140,7 +175,7 @@ const schema = defineSchema({
 const ablo = Ablo({
   schema,
   apiKey: process.env.ABLO_API_KEY, // written to .env.local by `npx ablo push`
-  databaseUrl: process.env.DATABASE_URL, // your Postgres — rows live here, never with Ablo
+  databaseUrl: process.env.DATABASE_URL, // your Postgres, passed explicitly — rows live here
 });
 
 await ablo.ready();
@@ -285,7 +320,10 @@ import { AbloProvider, useAblo } from '@abloatai/ablo/react';
 import { schema } from './ablo/schema';
 
 // Build the client once — it authenticates via your session route, no key in the browser.
-const ablo = Ablo({ schema, authEndpoint: '/api/ablo-session' });
+const ablo = Ablo({
+  schema,
+  apiKey: () => fetch('/api/ablo-session').then((r) => r.text()),
+});
 
 function App() {
   return (
@@ -338,7 +376,10 @@ to sync-group strings.
 
 ```tsx
 // team membership is asserted server-side when the session route mints the token.
-const ablo = Ablo({ schema, authEndpoint: '/api/ablo-session' });
+const ablo = Ablo({
+  schema,
+  apiKey: () => fetch('/api/ablo-session').then((r) => r.text()),
+});
 
 <AbloProvider client={ablo} userId={user.id}>
   <App />
@@ -388,29 +429,35 @@ curl https://api.abloatai.com/v1/commits \
 
 ## Your Database
 
-Every schema model is backed by **your own database** — Ablo is the transaction
-layer on top of it, never the home for your rows. Two ways to connect it:
+In production, every schema model is backed by **your own database** — Ablo is
+the transaction layer on top of it. Two ways to connect it:
 
 | | How Ablo reaches your Postgres | Use when |
 | --- | --- | --- |
-| **Connection string** (default) | `databaseUrl` at init. Ablo registers the connection once (sent over TLS, stored sealed, never echoed back) and commits each write directly — through a non-superuser role, behind row-level security. | You can hand over a scoped connection string. |
+| **Connection string** (primary) | `databaseUrl` at init — passed explicitly, never auto-read from the environment. Ablo registers the connection once (sent over TLS, stored sealed, never echoed back) and commits each write directly — through a non-superuser role, behind row-level security. | You can hand over a scoped connection string. |
 | **Signed endpoint** | Your app exposes one route built from an ORM adapter (`prismaDataSource` / `drizzleDataSource`); Ablo sends signed commit requests and your app writes its own database. | Database credentials must never leave your infrastructure. |
 
-Same product, same truth either way: your database is the system of record. See
+(No database yet? The hosted **sandbox** can host rows in Ablo's test plane —
+omit `databaseUrl` and pass an `apiKey` only, like Stripe test mode — so you can
+try Ablo before connecting your Postgres.)
+
+Same product, same truth either way: in production your database is the system of
+record. See
 [Connect Your Database](./docs/data-sources.md) for both shapes.
 
 ## Configuration
 
-`Ablo({ ... })` takes three things: your schema, your key, and your database —
-the last either as `databaseUrl` here or as a signed
-[Data Source endpoint](./docs/data-sources.md) in your app. Every other option
-has correct defaults:
+`Ablo({ ... })` takes your schema, your key, and — in production — your database,
+either as an explicit `databaseUrl` here or as a signed
+[Data Source endpoint](./docs/data-sources.md) in your app. (`databaseUrl` is
+never auto-read from the environment; omit it to try Ablo against the hosted
+sandbox.) Every other option has correct defaults:
 
 | Option | Type | Default | Purpose |
 | --- | --- | --- | --- |
 | `schema` | `Schema` | — (required) | Typed model proxies (`ablo.<model>.*`) |
 | `apiKey` | `string \| ApiKeySetter \| null` | `process.env.ABLO_API_KEY` | Server key — a string, or an async function for rotation |
-| `databaseUrl` | `string \| null` | `process.env.DATABASE_URL` | Your Postgres, registered as the data plane. Server runtimes only — the SDK throws if it sees this in a browser. Omit it when your app exposes a signed [Data Source endpoint](./docs/data-sources.md) instead. |
+| `databaseUrl` | `string \| null` | `—` | Your Postgres, registered as the data plane. **Must be passed explicitly — it is not auto-read from the environment.** If you have a `DATABASE_URL` set for another tool (Prisma, Drizzle, docker-compose), `Ablo()` ignores it unless you pass `databaseUrl` explicitly. Server runtimes only — the SDK throws if it sees this in a browser. Omit it when your app exposes a signed [Data Source endpoint](./docs/data-sources.md) instead, or when trying Ablo against the hosted sandbox. |
 
 Keep `apiKey` in trusted server runtimes. In the browser, `<AbloProvider>`
 authenticates with the signed-in user's session; the raw-key path is gated

package/dist/Model.d.ts

@@ -183,6 +183,45 @@ export declare abstract class Model {
      * Clear tracked changes
      */
     clearChanges(): void;
+    /**
+     * Capture a before-image for `keys` — the SINGLE source of truth for the
+     * "previous value" that undo inverses are built from. Both undo paths call
+     * this so they can never drift: the stream path
+     * (`TransactionQueue.extractPreviousData`) and the manual-record path
+     * (`RecordingTransaction.snapshotFields`).
+     *
+     * Resolution order per key:
+     *   1. `modifiedProperties.get(key).old` — first-old-wins pre-session
+     *      baseline, set whenever the field was mutated in place before commit.
+     *   2. `getOriginalSnapshot()[key]` — the last loaded/acked row, the correct
+     *      before-image for a key written WITHOUT a prior in-place mutation
+     *      (e.g. a `precomputedChanges` write).
+     *   3. `fallbackToLive` only — the current live value. The manual-record path
+     *      wants this last resort; the stream path deliberately OMITS unresolved
+     *      keys so `buildUndoOps` drops an un-revertible inverse rather than
+     *      inventing one. The flag is the one intentional difference between the
+     *      two callers — do not collapse it.
+     *
+     * `id` is always skipped. Values are read out per-key, so the
+     * `getOriginalSnapshot()` "callers must not mutate" contract is preserved.
+     *
+     * Invariant this relies on: a given undo scope is EITHER stream-recorded
+     * (`recordFromStream: true`) OR manual (`useMutators({ undoScope })`), never
+     * both — otherwise a write would be captured twice. No surface sets both.
+     */
+    capturePreviousValues(keys: Iterable<string>, opts?: {
+        fallbackToLive?: boolean;
+    }): ModelData;
+    /**
+     * Drop the `modifiedProperties` entries for `keys` — re-baselines a field
+     * after its `.old` has been frozen into a committed transaction, so the NEXT
+     * write to the same field starts from this commit's result rather than the
+     * stale pre-session `.old` that {@link propertyChanged}'s first-old-wins
+     * policy preserves. Safe because the committed transaction owns its own
+     * frozen `data`/`previousData`; neither re-reads `modifiedProperties`. `id`
+     * is never consumed. With no `keys`, consumes every tracked field.
+     */
+    consumeModifiedFields(keys?: Iterable<string>): void;
     /**
      * Validate model
      */

package/dist/Model.js

@@ -223,6 +223,74 @@ export class Model {
             this._originalData = this.captureSnapshot();
         });
     }
+    /**
+     * Capture a before-image for `keys` — the SINGLE source of truth for the
+     * "previous value" that undo inverses are built from. Both undo paths call
+     * this so they can never drift: the stream path
+     * (`TransactionQueue.extractPreviousData`) and the manual-record path
+     * (`RecordingTransaction.snapshotFields`).
+     *
+     * Resolution order per key:
+     *   1. `modifiedProperties.get(key).old` — first-old-wins pre-session
+     *      baseline, set whenever the field was mutated in place before commit.
+     *   2. `getOriginalSnapshot()[key]` — the last loaded/acked row, the correct
+     *      before-image for a key written WITHOUT a prior in-place mutation
+     *      (e.g. a `precomputedChanges` write).
+     *   3. `fallbackToLive` only — the current live value. The manual-record path
+     *      wants this last resort; the stream path deliberately OMITS unresolved
+     *      keys so `buildUndoOps` drops an un-revertible inverse rather than
+     *      inventing one. The flag is the one intentional difference between the
+     *      two callers — do not collapse it.
+     *
+     * `id` is always skipped. Values are read out per-key, so the
+     * `getOriginalSnapshot()` "callers must not mutate" contract is preserved.
+     *
+     * Invariant this relies on: a given undo scope is EITHER stream-recorded
+     * (`recordFromStream: true`) OR manual (`useMutators({ undoScope })`), never
+     * both — otherwise a write would be captured twice. No surface sets both.
+     */
+    capturePreviousValues(keys, opts) {
+        const out = {};
+        const modified = this.modifiedProperties instanceof Map ? this.modifiedProperties : null;
+        const original = this.getOriginalSnapshot();
+        for (const key of keys) {
+            if (key === 'id')
+                continue;
+            const mod = modified?.get(key);
+            if (mod) {
+                out[key] = mod.old;
+            }
+            else if (original && key in original) {
+                out[key] = original[key];
+            }
+            else if (opts?.fallbackToLive) {
+                out[key] = Reflect.get(this, key);
+            }
+        }
+        return out;
+    }
+    /**
+     * Drop the `modifiedProperties` entries for `keys` — re-baselines a field
+     * after its `.old` has been frozen into a committed transaction, so the NEXT
+     * write to the same field starts from this commit's result rather than the
+     * stale pre-session `.old` that {@link propertyChanged}'s first-old-wins
+     * policy preserves. Safe because the committed transaction owns its own
+     * frozen `data`/`previousData`; neither re-reads `modifiedProperties`. `id`
+     * is never consumed. With no `keys`, consumes every tracked field.
+     */
+    consumeModifiedFields(keys) {
+        if (!(this.modifiedProperties instanceof Map) || this.modifiedProperties.size === 0) {
+            return;
+        }
+        const only = keys ? new Set(keys) : null;
+        for (const key of [...this.modifiedProperties.keys()]) {
+            if (key === 'id')
+                continue;
+            if (only && !only.has(key))
+                continue;
+            this.modifiedProperties.delete(key);
+        }
+    }
     /**
      * Validate model
      */

package/dist/auth/credentialPolicy.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Credential POLICY — the single source of truth for "what KIND of credential
+ * did the caller hand us, and what do we DO with it at connect time".
+ *
+ * Before this module the prefix-dispatch decision (`sk_`/`ek_`/`rk_`/`pk_`) was
+ * re-implemented with raw `startsWith()` sniffs in ~5 places (identity.ts ×3,
+ * auth.ts browser guard, cli/dev.ts, cli/push.ts) and the connect-time routing
+ * lived as a 4-branch if/elif tree inside `resolveParticipantIdentity`. Folding
+ * the policy here keeps the kind-taxonomy and the connect decision in ONE place;
+ * the consumers below just call into it.
+ *
+ * This module is deliberately POLICY-ONLY. It does NOT own the auth primitives
+ * (`exchangeApiKey` / `mintUserSessionKey` / `resolveIdentity`), the credential
+ * lifecycle (`startCredentialLifecycle` / refresh scheduler), or the connection
+ * FSM — those are correctly distributed consumers. `resolveCredential` DELEGATES
+ * to injected primitives rather than reimplementing any HTTP mint call.
+ *
+ * Browser-safe: `classifyCredentialKind` is a pure-string helper and MUST NOT
+ * import the Node-only `keys` module (`node:crypto`). The key-prefix contract it
+ * encodes mirrors `keys/index.ts`'s `KIND_BY_PREFIX` (the Stripe-style model:
+ * sk_=secret, rk_=restricted, ek_=ephemeral, pk_=publishable) but stays a plain
+ * prefix lookup so it can ship in the client bundle.
+ */
+import type { exchangeApiKey, mintUserSessionKey, resolveIdentity } from './index.js';
+import type { resolveApiKeyValue } from '../client/auth.js';
+/**
+ * The four Ablo API-key kinds (Stripe-style). Prefix contract — kept in lockstep
+ * with `keys/index.ts` `API_KEY_KINDS` / `KIND_BY_PREFIX`, but declared locally
+ * so this browser-safe module never pulls in `node:crypto`.
+ */
+export type CredentialKind = 'secret' | 'ephemeral' | 'restricted' | 'publishable';
+/**
+ * Lightweight, browser-safe prefix → kind classifier. The SINGLE source of truth
+ * for prefix dispatch across the SDK (connect routing, the browser guard, the
+ * CLI key-gating). Returns `null` for a value that carries no recognized Ablo
+ * key prefix (a caller-supplied capability/auth token, an empty/garbage value).
+ *
+ * Pure string check — does NOT validate the checksum or environment segment
+ * (that's `keys/index.ts` `parseApiKey`, which is Node-only). This is only the
+ * "which of the four buckets" decision.
+ */
+export declare function classifyCredentialKind(value: string): CredentialKind | null;
+/**
+ * Auth primitives injected into {@link resolveCredential}. Each is the canonical
+ * implementation from `auth/index.ts` / `client/auth.ts`; the policy DELEGATES to
+ * them so the HTTP mint logic stays in ONE place and only the routing decision
+ * lives here. `mintUserSessionKey` is carried for completeness of the primitive
+ * surface (the browser/session path mints it before connect); `resolveCredential`
+ * never re-mints it — a pre-minted `ek_` arrives ready to use.
+ */
+export interface CredentialPrimitives {
+    readonly exchangeApiKey: typeof exchangeApiKey;
+    readonly mintUserSessionKey: typeof mintUserSessionKey;
+    readonly resolveIdentity: typeof resolveIdentity;
+    readonly resolveApiKeyValue: typeof resolveApiKeyValue;
+}
+export interface ResolveCredentialContext {
+    readonly primitives: CredentialPrimitives;
+    /**
+     * Build the argument bag for the hosted exchange. identity.ts owns the baseUrl
+     * derivation + participant scope, so it supplies the args; the policy invokes
+     * `primitives.exchangeApiKey` with them. The `apiKey` is filled in by the policy
+     * from the resolved value.
+     */
+    readonly exchangeArgs: Omit<Parameters<typeof exchangeApiKey>[0], 'apiKey'>;
+}
+export interface ResolveCredentialInput {
+    /** Resolved string value of the configured `apiKey` (callable already invoked), or null. */
+    readonly apiKeyValue: string | null;
+    /** The configured `apiKey` (string or setter) — threaded onto the refresh path. */
+    readonly configuredApiKey: string | (() => Promise<string | null>) | null;
+    /** Explicit caller-supplied capability token (`options.capabilityToken`). */
+    readonly capabilityToken: string | undefined;
+    /** Configured static `authToken`. */
+    readonly authToken: string | null;
+    /** True once the caller knows its own identity (legacy explicit path). */
+    readonly hasExplicitIdentity: boolean;
+}
+/**
+ * The connect-time decision, expressed as a discriminated union over the routing
+ * kind (NOT the raw key kind — `ek_` and `rk_` collapse into the same
+ * `pre-minted` route, and a bare capability token routes the same way). The
+ * caller (`identity.ts`) switches on `kind` and performs the scope/side-effect
+ * wiring each route needs.
+ *
+ * Fields carry exactly what each branch in the old if/elif tree produced:
+ *   - `getBearer`        — the token to authenticate the bootstrap/`/auth/*` HTTP
+ *                          and to seed the credential source with.
+ *   - `expiresAtMs`      — exchange expiry (drives the refresh scheduler) or null
+ *                          when the credential never expires / nothing to refresh.
+ *   - `controlPlaneKey`  — the ORIGINAL configured apiKey when the route minted
+ *                          via exchange (so a refresh can re-mint), else null.
+ */
+export type ResolvedCredential = 
+/** `pk_` — long-lived browser-safe read-only project key. Used directly as the
+ *  bearer; never exchanged, never refreshed. Identity resolved via `/auth/identity`. */
+{
+    readonly kind: 'publishable';
+    readonly getBearer: string;
+    readonly expiresAtMs: null;
+    readonly controlPlaneKey: null;
+}
+/** `sk_` (no explicit cap token) — hosted-cloud. Exchanged for a capability
+ *  token via `exchangeApiKey`; the refresh scheduler re-mints before expiry. */
+ | {
+    readonly kind: 'exchange';
+    /** Result of the initial `exchangeApiKey` call. */
+    readonly exchange: Awaited<ReturnType<typeof exchangeApiKey>>;
+    readonly getBearer: string;
+    readonly expiresAtMs: number;
+    /** The configured apiKey (string or setter) — read fresh on each refresh. */
+    readonly controlPlaneKey: string | (() => Promise<string | null>);
+}
+/** Pre-minted `ek_`/`rk_` OR an explicit capability/auth token — used AS-IS as
+ *  the bearer (never exchanged). Identity resolved via `/auth/identity`. */
+ | {
+    readonly kind: 'pre-minted';
+    readonly getBearer: string;
+    readonly expiresAtMs: null;
+    readonly controlPlaneKey: null;
+}
+/** Legacy explicit — caller knows its own organizationId + user/agentId. No
+ *  server round-trip; the (optional) bearer is the initial cap token. */
+ | {
+    readonly kind: 'explicit';
+    readonly getBearer: string | undefined;
+    readonly expiresAtMs: null;
+    readonly controlPlaneKey: null;
+};
+/**
+ * Connect-time credential routing — absorbs the decision tree that used to live
+ * inline in `resolveParticipantIdentity`. Classifies the configured apiKey, then
+ * routes to one of four outcomes, DELEGATING the actual HTTP exchange to the
+ * injected `exchangeApiKey` primitive. The caller switches on
+ * `ResolvedCredential.kind` to perform scope wiring + scheduler setup.
+ *
+ * Routing (preserves the old branch order exactly):
+ *   0. `pk_` + no explicit cap token → `publishable` (direct bearer, no refresh).
+ *   1. exchangeable apiKey (any prefix that ISN'T a pre-minted `ek_`/`rk_`) +
+ *      no explicit cap token → `exchange` (hosted-cloud round-trip + scheduler).
+ *   2. otherwise, identity unknown → `pre-minted` (use the cap token as-is). Throws
+ *      `session_expired` when there is no token to authenticate `/auth/identity`.
+ *   3. otherwise (identity known) → `explicit` (legacy self-hosted, no round-trip).
+ */
+export declare function resolveCredential(input: ResolveCredentialInput, ctx: ResolveCredentialContext): Promise<ResolvedCredential>;

package/dist/auth/credentialPolicy.js

@@ -0,0 +1,130 @@
+/**
+ * Credential POLICY — the single source of truth for "what KIND of credential
+ * did the caller hand us, and what do we DO with it at connect time".
+ *
+ * Before this module the prefix-dispatch decision (`sk_`/`ek_`/`rk_`/`pk_`) was
+ * re-implemented with raw `startsWith()` sniffs in ~5 places (identity.ts ×3,
+ * auth.ts browser guard, cli/dev.ts, cli/push.ts) and the connect-time routing
+ * lived as a 4-branch if/elif tree inside `resolveParticipantIdentity`. Folding
+ * the policy here keeps the kind-taxonomy and the connect decision in ONE place;
+ * the consumers below just call into it.
+ *
+ * This module is deliberately POLICY-ONLY. It does NOT own the auth primitives
+ * (`exchangeApiKey` / `mintUserSessionKey` / `resolveIdentity`), the credential
+ * lifecycle (`startCredentialLifecycle` / refresh scheduler), or the connection
+ * FSM — those are correctly distributed consumers. `resolveCredential` DELEGATES
+ * to injected primitives rather than reimplementing any HTTP mint call.
+ *
+ * Browser-safe: `classifyCredentialKind` is a pure-string helper and MUST NOT
+ * import the Node-only `keys` module (`node:crypto`). The key-prefix contract it
+ * encodes mirrors `keys/index.ts`'s `KIND_BY_PREFIX` (the Stripe-style model:
+ * sk_=secret, rk_=restricted, ek_=ephemeral, pk_=publishable) but stays a plain
+ * prefix lookup so it can ship in the client bundle.
+ */
+import { AbloAuthenticationError } from '../errors.js';
+const KIND_BY_PREFIX = [
+    ['sk_', 'secret'],
+    ['ek_', 'ephemeral'],
+    ['rk_', 'restricted'],
+    ['pk_', 'publishable'],
+];
+/**
+ * Lightweight, browser-safe prefix → kind classifier. The SINGLE source of truth
+ * for prefix dispatch across the SDK (connect routing, the browser guard, the
+ * CLI key-gating). Returns `null` for a value that carries no recognized Ablo
+ * key prefix (a caller-supplied capability/auth token, an empty/garbage value).
+ *
+ * Pure string check — does NOT validate the checksum or environment segment
+ * (that's `keys/index.ts` `parseApiKey`, which is Node-only). This is only the
+ * "which of the four buckets" decision.
+ */
+export function classifyCredentialKind(value) {
+    for (const [prefix, kind] of KIND_BY_PREFIX) {
+        if (value.startsWith(prefix))
+            return kind;
+    }
+    return null;
+}
+/**
+ * Connect-time credential routing — absorbs the decision tree that used to live
+ * inline in `resolveParticipantIdentity`. Classifies the configured apiKey, then
+ * routes to one of four outcomes, DELEGATING the actual HTTP exchange to the
+ * injected `exchangeApiKey` primitive. The caller switches on
+ * `ResolvedCredential.kind` to perform scope wiring + scheduler setup.
+ *
+ * Routing (preserves the old branch order exactly):
+ *   0. `pk_` + no explicit cap token → `publishable` (direct bearer, no refresh).
+ *   1. exchangeable apiKey (any prefix that ISN'T a pre-minted `ek_`/`rk_`) +
+ *      no explicit cap token → `exchange` (hosted-cloud round-trip + scheduler).
+ *   2. otherwise, identity unknown → `pre-minted` (use the cap token as-is). Throws
+ *      `session_expired` when there is no token to authenticate `/auth/identity`.
+ *   3. otherwise (identity known) → `explicit` (legacy self-hosted, no round-trip).
+ */
+export async function resolveCredential(input, ctx) {
+    const { apiKeyValue, capabilityToken, authToken, hasExplicitIdentity } = input;
+    const kind = apiKeyValue != null ? classifyCredentialKind(apiKeyValue) : null;
+    // A pre-minted capability bearer (`ek_` ephemeral / `rk_` restricted) is NOT
+    // exchangeable — it was already minted into the credential source before
+    // connect and must be USED DIRECTLY as the bearer (Route 2), never sent through
+    // `exchangeApiKey` (Route 1, which expects an `sk_`).
+    const isPreMintedCapabilityBearer = kind === 'ephemeral' || kind === 'restricted';
+    const initialCapToken = capabilityToken ??
+        (isPreMintedCapabilityBearer ? apiKeyValue ?? undefined : undefined) ??
+        authToken ??
+        undefined;
+    // Route 0: publishable key (`pk_`) — long-lived, browser-safe, READ-ONLY. Used
+    // DIRECTLY as the bearer; never exchanged → never expires → nothing to refresh.
+    if (apiKeyValue != null && kind === 'publishable' && capabilityToken == null) {
+        return {
+            kind: 'publishable',
+            getBearer: apiKeyValue,
+            expiresAtMs: null,
+            controlPlaneKey: null,
+        };
+    }
+    // Route 1: hosted-cloud (secret/exchangeable apiKey, no caller-supplied cap
+    // token). A pre-minted `ek_`/`rk_` is NOT exchangeable → falls through.
+    if (apiKeyValue != null &&
+        capabilityToken == null &&
+        !isPreMintedCapabilityBearer) {
+        const exchange = await ctx.primitives.exchangeApiKey({
+            ...ctx.exchangeArgs,
+            apiKey: apiKeyValue,
+        });
+        return {
+            kind: 'exchange',
+            exchange,
+            getBearer: exchange.token,
+            expiresAtMs: Date.parse(exchange.expiresAt),
+            controlPlaneKey: input.configuredApiKey ?? apiKeyValue,
+        };
+    }
+    // Route 2: self-derived / pre-minted (use the cap token as-is). Reached when
+    // identity is NOT caller-supplied.
+    if (!hasExplicitIdentity) {
+        if (initialCapToken == null) {
+            // No apiKey to exchange (Route 1) and no caller-supplied identity (Route 3),
+            // so `initialCapToken` is the only thing that could authenticate
+            // `/auth/identity`. Absent — commonly the function `apiKey` resolver
+            // returning `null` (no/expired session) — surface the real, re-auth-able
+            // condition locally instead of making a doomed round-trip.
+            throw new AbloAuthenticationError('No auth token available to resolve identity — the session token is ' +
+                'missing or expired. Ensure your `apiKey` resolver returns a valid token, or ' +
+                'pass a static `apiKey` / `capabilityToken`.', { code: 'session_expired' });
+        }
+        return {
+            kind: 'pre-minted',
+            getBearer: initialCapToken,
+            expiresAtMs: null,
+            controlPlaneKey: null,
+        };
+    }
+    // Route 3: legacy explicit (self-hosted — caller knows its own
+    // organizationId + user/agentId).
+    return {
+        kind: 'explicit',
+        getBearer: initialCapToken,
+        expiresAtMs: null,
+        controlPlaneKey: null,
+    };
+}