@abloatai/ablo 0.11.1 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,54 @@
 # Changelog
 
+## 0.12.0
+
+### Minor Changes
+
+- Canonicalize the claim API to one vocabulary, plus DX fixes (breaking).
+  - BREAKING: claim phase field `action` → `reason` on every claim surface
+    (`Claim`, `ClaimHandle`, `ClaimCreateOptions`, `ModelClaim`, ...). The wire
+    is unchanged (still `action`, healed on read) — no server redeploy needed.
+  - BREAKING: claim contention flag `wait` → `queue` (one word everywhere).
+  - BREAKING: React hook `useParticipant` → `useWatch` (aligns with `ablo.<model>.watch`).
+  - `ClaimDeclaration.ttlSeconds` is now `number` (was a `Duration`).
+  - Docs: `retrieve` HTTP envelope (`.data`/`.stamp`) called out; `syncGroups`
+    reworded (provisional, not deprecated); `orgScoped` cross-tenant security
+    warning; React error strings point at `<AbloProvider>`.
+
+## 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

package/README.md

@@ -163,6 +163,8 @@ loses your model types. There is no bespoke client-type generic to import —
 
 ```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']),
@@ -318,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 (
@@ -371,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 />

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/ai-sdk/claim-broadcast.d.ts

@@ -58,10 +58,11 @@ export interface ClaimBroadcastMiddlewareOptions<R extends SchemaRecord = Schema
     /** Target entity. Null skips the broadcast (purely conversational). */
     readonly target: ClaimTarget | null;
     /**
-     * Action verb describing what the agent is doing. Convention:
-     * `'edit'`, `'read'`, `'review'`, `'generate'`. Default `'edit'`.
+     * Human-readable phase describing what the agent is doing. Convention:
+     * `'edit'`, `'read'`, `'review'`, `'generate'`. Default `'edit'`. The same
+     * `reason` field used on every claim surface.
      */
-    readonly action?: string;
+    readonly reason?: string;
     /**
      * Peer-visible explanation of the specific work this model call is about to
      * perform. Surfaces to other agents through `ActiveClaim.description`.

package/dist/ai-sdk/claim-broadcast.js

@@ -29,7 +29,7 @@
  */
 export function claimBroadcastMiddleware(options) {
     const { agent, target } = options;
-    const action = options.action ?? 'edit';
+    const reason = options.reason ?? 'edit';
     const description = options.description;
     const openClaim = () => {
         if (!agent || !target)
@@ -42,7 +42,7 @@ export function claimBroadcastMiddleware(options) {
             field: target.field,
             meta: target.meta,
         }, {
-            reason: action,
+            reason,
             description,
             ttl: target.estimatedMs ?? 60_000,
         });

package/dist/ai-sdk/wrap.d.ts

@@ -14,7 +14,7 @@
  *   model: anthropic('claude-opus-4-7'),
  *   agent,
  *   target: { entityType: 'SlideDeck', entityId: 'deck-abc' },
- *   action: 'renaming',
+ *   reason: 'renaming',
  *   description: 'Renaming the deck title to match the project brief.',
  * });
  *
@@ -40,10 +40,11 @@ export interface WrapWithMultiplayerOptions {
     /** Target entity. Null = pass-through wrap. */
     readonly target: ClaimTarget | null;
     /**
-     * Optional action verb for the broadcast. Default `'edit'`.
-     * Convention: `'edit'`, `'read'`, `'review'`, `'generate'`.
+     * Optional human-readable phase for the broadcast. Default `'edit'`.
+     * Convention: `'edit'`, `'read'`, `'review'`, `'generate'`. The same
+     * `reason` field used on every claim surface.
      */
-    readonly action?: string;
+    readonly reason?: string;
     /**
      * Peer-visible explanation of the specific work this model call is about to
      * perform. Other agents receive it in their coordination context.

package/dist/ai-sdk/wrap.js

@@ -14,7 +14,7 @@
  *   model: anthropic('claude-opus-4-7'),
  *   agent,
  *   target: { entityType: 'SlideDeck', entityId: 'deck-abc' },
- *   action: 'renaming',
+ *   reason: 'renaming',
  *   description: 'Renaming the deck title to match the project brief.',
  * });
  *
@@ -31,12 +31,12 @@ import { wrapLanguageModel } from 'ai';
 import { claimBroadcastMiddleware, } from './claim-broadcast.js';
 import { coordinationContextMiddleware } from './coordination-context.js';
 export function wrapWithMultiplayer(options) {
-    const { model, agent, target, action, description, excludeClaimIds, extraMiddleware } = options;
+    const { model, agent, target, reason, description, excludeClaimIds, extraMiddleware } = options;
     return wrapLanguageModel({
         model,
         middleware: [
             coordinationContextMiddleware({ agent, target, excludeClaimIds }),
-            claimBroadcastMiddleware({ agent, target, action, description }),
+            claimBroadcastMiddleware({ agent, target, reason, description }),
             ...(extraMiddleware ?? []),
         ],
     });

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,
+    };
+}