@abloatai/ablo 0.17.0 → 0.19.0

package/dist/client/ApiClient.js

@@ -6,23 +6,11 @@
  * nouns directly to HTTP routes on sync-server.
  */
 import { AbloClaimedError, AbloAuthenticationError, AbloConnectionError, AbloValidationError, claimedError, translateHttpError, } from '../errors.js';
-import { assertBrowserSafety, readProcessEnv, resolveApiKey, resolveApiKeyValue, resolveAuthToken, resolveBaseURL, resolveBootstrapBaseUrl, resolveDatabaseUrl, warnIfDatabaseUrlEnvIgnored, } from './auth.js';
+import { assertBrowserSafety, readProcessEnv, resolveApiKey, resolveApiKeyValue, resolveAuthToken, resolveBaseURL, resolveBootstrapBaseUrl, resolveDatabaseUrl, warnIfCliKeyMismatch, warnIfDatabaseUrlEnvIgnored, warnIfDatabaseUrlDeprecated, } from './auth.js';
 import { registerDataSource } from './registerDataSource.js';
 import { toSeconds } from '../utils/duration.js';
 import { mintSession } from './sessionMint.js';
 import { assertWriteOptions } from './writeOptionsSchema.js';
-/**
- * The `/v1/claims` and model-query routes still emit the wire field `action`
- * for the claim phase; the public `Claim` / `ModelClaim` expose it as `reason`.
- * Heal on read so the SDK shape is consistent without a coordinated server
- * deploy — `reason ?? action`. When the server adopts `reason`, this is a no-op.
- */
-function healClaimPhase(claim) {
-    const raw = claim;
-    if (raw.reason !== undefined)
-        return claim;
-    return { ...claim, reason: raw.action ?? 'editing' };
-}
 const DEFAULT_AGENT_LEASE = '10m';
 export function createProtocolClient(options) {
     const env = readProcessEnv();
@@ -33,6 +21,8 @@ export function createProtocolClient(options) {
     // Nudge (once) if a stray DATABASE_URL is in the env but `databaseUrl` wasn't
     // passed — no logger on this path, so the helper falls back to console.warn.
     warnIfDatabaseUrlEnvIgnored(authInput);
+    warnIfDatabaseUrlDeprecated(authInput);
+    void warnIfCliKeyMismatch(authInput);
     assertBrowserSafety({
         apiKey: configuredApiKey,
         databaseUrl: configuredDatabaseUrl,
@@ -185,8 +175,8 @@ export function createProtocolClient(options) {
         const suffix = params.toString();
         const body = await requestJson(`/v1/claims${suffix ? `?${suffix}` : ''}`, { method: 'GET' });
         return {
-            active: (body.claims ?? []).map(healClaimPhase),
-            queue: (body.queue ?? []).map(healClaimPhase),
+            active: body.claims ?? [],
+            queue: body.queue ?? [],
         };
     }
     function delay(ms, signal) {
@@ -272,7 +262,7 @@ export function createProtocolClient(options) {
                 body: JSON.stringify({
                     clientTxId,
                     idempotencyKey: clientTxId,
-                    claim: normalizeClaimId(commitOptions.claimRef) ?? claim?.claimId,
+                    claim: normalizeClaimId(commitOptions.claimRef) ?? claim?.id,
                     operations,
                 }),
             });
@@ -389,8 +379,7 @@ export function createProtocolClient(options) {
                 body: JSON.stringify({
                     claimId,
                     target: claimOptions.target,
-                    // Wire field stays `action`; public option is `reason`.
-                    action: claimOptions.reason,
+                    reason: claimOptions.reason,
                     ttl: claimOptions.ttl,
                     queue: claimOptions.queue,
                 }),
@@ -415,9 +404,16 @@ export function createProtocolClient(options) {
             };
             return {
                 object: 'claim',
-                claimId: id,
+                id,
                 reason: claimOptions.reason,
-                target: claimOptions.target,
+                target: {
+                    type: claimOptions.target.model,
+                    id: claimOptions.target.id,
+                    ...(claimOptions.target.field ? { field: claimOptions.target.field } : {}),
+                    ...(claimOptions.target.path ? { path: claimOptions.target.path } : {}),
+                    ...(claimOptions.target.range ? { range: claimOptions.target.range } : {}),
+                    ...(claimOptions.target.meta ? { meta: claimOptions.target.meta } : {}),
+                },
                 release,
                 revoke: () => {
                     void release().catch(() => { });
@@ -467,7 +463,7 @@ export function createProtocolClient(options) {
         return {
             data,
             stamp: query.stamp ?? 0,
-            claims: (query.claims ?? []).map(healClaimPhase),
+            claims: query.claims ?? [],
         };
     }
     /**
@@ -501,13 +497,13 @@ export function createProtocolClient(options) {
         const claimHandle = typeof options?.claim === 'object' &&
             options?.claim !== null &&
             options.claim.object === 'claim' &&
-            typeof options.claim.claimId === 'string'
+            typeof options.claim.id === 'string'
             ? options.claim
             : undefined;
         const readAt = options?.readAt ?? claimHandle?.readAt;
         const requestBody = {
             idempotencyKey: clientTxId,
-            claim: normalizeClaimId(options?.claimRef) ?? claimHandle?.claimId,
+            claim: normalizeClaimId(options?.claimRef) ?? claimHandle?.id,
             onStale: options?.onStale ?? (claimHandle?.readAt !== undefined ? 'reject' : undefined),
             readAt,
         };
@@ -538,7 +534,7 @@ export function createProtocolClient(options) {
         const isClaimHandle = (value) => typeof value === 'object' &&
             value !== null &&
             value.object === 'claim' &&
-            typeof value.claimId === 'string' &&
+            typeof value.id === 'string' &&
             typeof value.release === 'function';
         const claimMeta = (options) => {
             if (!options?.description)
@@ -549,8 +545,7 @@ export function createProtocolClient(options) {
             const body = await requestJson(claimPath(params.id), {
                 method: 'POST',
                 body: JSON.stringify({
-                    // Wire field stays `action`; public option is `reason`.
-                    action: params.reason ?? 'editing',
+                    reason: params.reason ?? 'editing',
                     ...(params.ttl !== undefined ? { ttl: params.ttl } : {}),
                     ...(params.description !== undefined ? { description: params.description } : {}),
                     ...(claimMeta(params) ? { meta: claimMeta(params) } : {}),
@@ -563,7 +558,7 @@ export function createProtocolClient(options) {
                 throw new AbloClaimedError(`Target ${name}/${params.id} is held; queued at position ${body.position ?? 0}. ` +
                     `The HTTP client cannot await the grant without a WebSocket.`, { code: 'claim_queued' });
             }
-            return body.claim?.id ?? body.id ?? body.claimId ?? createClaimId();
+            return body.claim?.id ?? body.id ?? body.id ?? createClaimId();
         };
         const releaseClaim = (params) => requestJson(claimPath(isClaimHandle(params) ? params.target.id : params.id), { method: 'DELETE' }).then(() => undefined);
         async function claimImpl(params) {
@@ -572,10 +567,10 @@ export function createProtocolClient(options) {
             const release = () => releaseClaim(params);
             return {
                 object: 'claim',
-                claimId,
+                id: claimId,
                 readAt: stamp,
                 target: {
-                    model: name,
+                    type: name,
                     id: params.id,
                     ...(params.field ? { field: params.field } : {}),
                     ...(params.path ? { path: params.path } : {}),
@@ -598,11 +593,11 @@ export function createProtocolClient(options) {
             state: async (params) => {
                 const res = await claimsForEntity(params);
                 const first = res.claims?.[0];
-                return first ? healClaimPhase(first) : null;
+                return first ?? null;
             },
             queue: async (params) => {
                 const res = await claimsForEntity(params);
-                return { object: 'list', data: (res.queue ?? []).map(healClaimPhase) };
+                return { object: 'list', data: res.queue ?? [] };
             },
             reorder: async (params) => {
                 await requestJson(`${claimPath(params.id)}/reorder`, {
@@ -618,7 +613,7 @@ export function createProtocolClient(options) {
             if (!claimInput)
                 return run(input);
             if (isClaimHandle(claimInput)) {
-                return run({ ...input, claimRef: { id: claimInput.claimId }, claim: undefined });
+                return run({ ...input, claimRef: { id: claimInput.id }, claim: undefined });
             }
             const claimId = await acquireClaim({ id, ...claimInput });
             try {

package/dist/client/auth.d.ts

@@ -49,6 +49,29 @@ export interface AuthResolveInput {
 export declare function readProcessEnv(): Record<string, string | undefined>;
 export declare function resolveApiKey(input: AuthResolveInput): string | ApiKeySetter | null;
 export declare function resolveAuthToken(input: AuthResolveInput): string | null;
+type CliMode = 'sandbox' | 'production';
+type StaticApiKeySource = 'option' | 'env';
+interface StaticApiKey {
+    readonly key: string;
+    readonly source: StaticApiKeySource;
+}
+interface CliCredentialSnapshot {
+    readonly mode: CliMode;
+    readonly activeProfile: string;
+    readonly storedKey?: string;
+}
+export interface CliKeyMismatch {
+    readonly source: StaticApiKeySource;
+    readonly configuredKeyPrefix: string;
+    readonly configuredMode?: CliMode;
+    readonly cliMode: CliMode;
+    readonly storedKeyPrefix?: string;
+    readonly kind: 'mode_mismatch' | 'key_override';
+    readonly message: string;
+}
+/** Infer sandbox/production from Ablo key prefixes without importing CLI code. */
+export declare function modeFromApiKey(key: string): CliMode | undefined;
+export declare function describeCliKeyMismatch(configured: StaticApiKey, cli: CliCredentialSnapshot): CliKeyMismatch | null;
 /**
  * Resolve the direct-URL connector's Postgres connection string.
  *
@@ -63,6 +86,8 @@ export declare function resolveAuthToken(input: AuthResolveInput): string | null
  */
 export declare function resolveDatabaseUrl(input: AuthResolveInput): string | null;
 export declare function warnIfDatabaseUrlEnvIgnored(input: AuthResolveInput, warn?: (message: string) => void): void;
+export declare function warnIfDatabaseUrlDeprecated(input: AuthResolveInput, warn?: (message: string) => void): void;
+export declare function warnIfCliKeyMismatch(input: AuthResolveInput, warn?: (message: string) => void): Promise<void>;
 export declare const ABLO_HOSTED_API_DOMAIN = "api.abloatai.com";
 export declare const ABLO_HOSTED_HTTP_BASE_URL = "https://api.abloatai.com";
 export declare const ABLO_DEFAULT_BASE_URL = "https://api.abloatai.com";
@@ -108,3 +133,4 @@ export declare function resolveBootstrapBaseUrl(input: {
     readonly url: string;
     readonly bootstrapBaseUrl?: string;
 }): string;
+export {};

package/dist/client/auth.js

@@ -28,6 +28,160 @@ export function resolveApiKey(input) {
 export function resolveAuthToken(input) {
     return input.options.authToken ?? null;
 }
+function keyPrefix(key) {
+    return `${key.slice(0, 12)}…`;
+}
+/** Infer sandbox/production from Ablo key prefixes without importing CLI code. */
+export function modeFromApiKey(key) {
+    if (/^(sk|rk)_test_/.test(key))
+        return 'sandbox';
+    if (/^(sk|rk)_live_/.test(key))
+        return 'production';
+    return undefined;
+}
+function resolveStaticApiKey(input) {
+    if (typeof input.options.apiKey === 'string') {
+        return { key: input.options.apiKey, source: 'option' };
+    }
+    if (input.options.apiKey !== undefined && input.options.apiKey !== null) {
+        return null;
+    }
+    const envKey = input.env.ABLO_API_KEY;
+    if (typeof envKey === 'string' && envKey.length > 0) {
+        return { key: envKey, source: 'env' };
+    }
+    return null;
+}
+function readProfileKeys(value) {
+    if (!value || typeof value !== 'object')
+        return {};
+    const profiles = {};
+    for (const [name, raw] of Object.entries(value)) {
+        if (!raw || typeof raw !== 'object')
+            continue;
+        const row = raw;
+        const sandbox = row.sandbox;
+        const production = row.production;
+        profiles[name] = {
+            sandbox: sandbox && typeof sandbox === 'object' ? sandbox : undefined,
+            production: production && typeof production === 'object' ? production : undefined,
+        };
+    }
+    return profiles;
+}
+function legacyProfileKeys(value) {
+    if (!value)
+        return { sandbox: undefined, production: undefined };
+    const sandbox = value.sandbox;
+    const production = value.production;
+    if ((sandbox && typeof sandbox === 'object') ||
+        (production && typeof production === 'object')) {
+        return {
+            sandbox: sandbox && typeof sandbox === 'object' ? sandbox : undefined,
+            production: production && typeof production === 'object' ? production : undefined,
+        };
+    }
+    if (typeof value.apiKey === 'string') {
+        return { sandbox: { apiKey: value.apiKey }, production: undefined };
+    }
+    return { sandbox: undefined, production: undefined };
+}
+function normalizeCliMode(value) {
+    return value === 'sandbox' || value === 'production' ? value : undefined;
+}
+function activeProjectSlug(value) {
+    if (!value || typeof value !== 'object')
+        return undefined;
+    const slug = value.slug;
+    return typeof slug === 'string' && slug.length > 0 ? slug : undefined;
+}
+function importNodeBuiltin(specifier) {
+    return import(specifier);
+}
+async function readJsonIfPresent(path) {
+    try {
+        const { readFile } = await importNodeBuiltin('node:fs/promises');
+        const text = await readFile(path, 'utf8');
+        const parsed = JSON.parse(text);
+        return parsed && typeof parsed === 'object' ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function readCliCredentialSnapshot(env) {
+    const processLike = globalThis.process;
+    if (!processLike?.versions?.node)
+        return null;
+    if (typeof window !== 'undefined')
+        return null;
+    const [{ homedir }, { join }] = await Promise.all([
+        importNodeBuiltin('node:os'),
+        importNodeBuiltin('node:path'),
+    ]);
+    const dir = env.ABLO_CONFIG_DIR
+        ?? (env.XDG_CONFIG_HOME ? join(env.XDG_CONFIG_HOME, 'ablo') : join(homedir(), '.config', 'ablo'));
+    const [cfg, creds] = await Promise.all([
+        readJsonIfPresent(join(dir, 'config.json')),
+        readJsonIfPresent(join(dir, 'credentials.json')),
+    ]);
+    const mode = normalizeCliMode(cfg?.mode) ?? normalizeCliMode(creds?.mode);
+    const activeProfile = activeProjectSlug(cfg?.activeProject) ?? 'default';
+    const profiles = {
+        ...readProfileKeys(creds?.profiles),
+        ...readProfileKeys(cfg?.profiles),
+    };
+    if (!profiles[activeProfile]) {
+        const legacy = { ...legacyProfileKeys(cfg), ...legacyProfileKeys(creds) };
+        if (legacy.sandbox?.apiKey || legacy.production?.apiKey) {
+            profiles[activeProfile] = legacy;
+        }
+    }
+    const effectiveMode = mode ?? (Object.keys(profiles).length > 0 ? 'sandbox' : undefined);
+    if (!effectiveMode)
+        return null;
+    return {
+        mode: effectiveMode,
+        activeProfile,
+        ...(profiles[activeProfile]?.[effectiveMode]?.apiKey
+            ? { storedKey: profiles[activeProfile][effectiveMode].apiKey }
+            : {}),
+    };
+}
+export function describeCliKeyMismatch(configured, cli) {
+    const configuredMode = modeFromApiKey(configured.key);
+    const configuredKeyPrefix = keyPrefix(configured.key);
+    const storedKeyPrefix = cli.storedKey ? keyPrefix(cli.storedKey) : undefined;
+    const sourceLabel = configured.source === 'env' ? 'ABLO_API_KEY' : 'configured apiKey';
+    if (configuredMode && configuredMode !== cli.mode) {
+        return {
+            source: configured.source,
+            configuredKeyPrefix,
+            configuredMode,
+            cliMode: cli.mode,
+            ...(storedKeyPrefix ? { storedKeyPrefix } : {}),
+            kind: 'mode_mismatch',
+            message: `${sourceLabel} is a ${configuredMode} key (${configuredKeyPrefix}) but the Ablo CLI is in ` +
+                `${cli.mode} mode${storedKeyPrefix ? ` (active stored key ${storedKeyPrefix})` : ''}. ` +
+                `Requests will use ${configuredMode}. Use the ${cli.mode} key, unset ABLO_API_KEY, ` +
+                `or run \`ablo mode ${configuredMode}\` intentionally.`,
+        };
+    }
+    if (configured.source === 'env' && cli.storedKey && configured.key !== cli.storedKey) {
+        return {
+            source: configured.source,
+            configuredKeyPrefix,
+            ...(configuredMode ? { configuredMode } : {}),
+            cliMode: cli.mode,
+            storedKeyPrefix,
+            kind: 'key_override',
+            message: `ABLO_API_KEY (${configuredKeyPrefix}) overrides the CLI's stored active ${cli.mode} key ` +
+                `(${storedKeyPrefix}). Requests will use the environment key. Unset ABLO_API_KEY to use ` +
+                '`ablo status` / `ablo mode` credentials.',
+        };
+    }
+    return null;
+}
 /**
  * Resolve the direct-URL connector's Postgres connection string.
  *
@@ -83,7 +237,61 @@ export function warnIfDatabaseUrlEnvIgnored(input, warn) {
     if (warn)
         warn(message);
     else if (typeof console !== 'undefined')
-        console.warn('[sync]', message);
+        console.warn('[Ablo]', message);
+}
+/**
+ * One-time deprecation nudge for the `databaseUrl` direct connector.
+ *
+ * `databaseUrl` registers the `dedicated` storage mode — Ablo opens a pool INTO
+ * the caller's Postgres and writes into it directly. That is the operate-their-
+ * database posture we are moving off. Ablo is Stripe-shaped: it hosts only the
+ * transaction log (the ordered sync_deltas) + coordination, never your data — your
+ * rows always live in your own database. The supported path is the signed Data
+ * Source endpoint (`dataSource(...)`), where your app owns the write and your
+ * credentials never leave it. See docs/plans/stripe-shaped-storage-posture.md.
+ *
+ * Still honored at runtime so existing integrations keep working; this only warns
+ * once per process (so it never spams) and falls back to `console.warn` when no
+ * logger is supplied (the `transport: 'http'`/`'api'` client has none).
+ */
+let warnedDatabaseUrlDeprecated = false;
+export function warnIfDatabaseUrlDeprecated(input, warn) {
+    if (warnedDatabaseUrlDeprecated)
+        return;
+    if (input.options.databaseUrl == null)
+        return;
+    warnedDatabaseUrlDeprecated = true;
+    const message = '`databaseUrl` (the direct connector) is deprecated and will be removed from ' +
+        'the supported path. It lets Ablo dial into your database; we are moving off ' +
+        'that. Ablo hosts only the transaction log — your data stays in your DB. Expose ' +
+        'a signed Data Source endpoint (`dataSource(...)`) so your app owns the write, ' +
+        'or self-host the engine to keep the log in your infra too. ' +
+        'See docs/plans/stripe-shaped-storage-posture.md.';
+    if (warn)
+        warn(message);
+    else if (typeof console !== 'undefined')
+        console.warn('[Ablo]', message);
+}
+let warnedCliKeyMismatch = false;
+export async function warnIfCliKeyMismatch(input, warn) {
+    if (warnedCliKeyMismatch)
+        return;
+    if (input.env.NODE_ENV === 'production')
+        return;
+    const configured = resolveStaticApiKey(input);
+    if (!configured)
+        return;
+    const cli = await readCliCredentialSnapshot(input.env);
+    if (!cli)
+        return;
+    const mismatch = describeCliKeyMismatch(configured, cli);
+    if (!mismatch)
+        return;
+    warnedCliKeyMismatch = true;
+    if (warn)
+        warn(mismatch.message);
+    else if (typeof console !== 'undefined')
+        console.warn('[Ablo]', mismatch.message);
 }
 export const ABLO_HOSTED_API_DOMAIN = 'api.abloatai.com';
 export const ABLO_HOSTED_HTTP_BASE_URL = `https://${ABLO_HOSTED_API_DOMAIN}`;

package/dist/client/createModelProxy.d.ts

@@ -22,7 +22,7 @@ import type { HydrationCoordinator } from '../sync/HydrationCoordinator.js';
 import type { JoinedParticipant } from '../sync/participants.js';
 import type { LoadWhere } from '../query/types.js';
 import { ModelScope } from '../types/index.js';
-import type { Duration, Claim, ClaimHandle, ClaimWaitOptions, Snapshot, TargetRange } from '../types/streams.js';
+import type { Duration, Claim, ClaimWaitOptions, Snapshot, TargetRange } from '../types/streams.js';
 export interface ModelClientMeta {
     readonly key: string;
     readonly typename: string;
@@ -90,7 +90,7 @@ export interface ModelCollaboration<T> {
             range?: TargetRange;
             meta?: Record<string, unknown>;
         };
-        /** Human-readable phase (`'editing'`); wire field is `action`. */
+        /** Human-readable phase (`'editing'`). */
         reason: string;
         ttl?: Duration;
         /**
@@ -101,7 +101,7 @@ export interface ModelCollaboration<T> {
         queue?: boolean;
         /** Reject (don't wait) if the queue is already this deep when we join. */
         maxQueueDepth?: number;
-    }): Promise<ClaimHandle>;
+    }): Promise<Claim>;
     createSnapshot(modelKey: string, id: string): Snapshot;
     /**
      * Current coordination state on a target — who (if anyone) holds it.
@@ -185,7 +185,7 @@ export interface ModelCollaboration<T> {
 }
 export interface ClaimTargetOptions<T = Record<string, unknown>> {
     /** Human-readable phase shown to observers while held. Defaults to
-     *  `'editing'`. The same word on every claim surface; wire field is `action`. */
+     *  `'editing'`. The same word on every claim surface. */
     reason?: string;
     /** Peer-visible explanation of the work being performed. */
     description?: string;
@@ -258,7 +258,7 @@ export interface ClaimReorderParams<T = Record<string, unknown>> extends ClaimLo
  * `ablo.<model>.update({ id, data, claim })` verb — the handle carries the
  * lease id and snapshot watermark for attribution + stale protection.
  */
-export type { ClaimHandle };
+export type { Claim };
 export type ClaimOptions<T = Record<string, unknown>> = ClaimTargetOptions<T>;
 /**
  * The coordination surface for a model, exposed as a callable namespace.
@@ -312,7 +312,7 @@ export interface ClaimReadApi<T = Record<string, unknown>> {
      */
     reorder(params: ClaimReorderParams<T>): void;
     /** Release a manual claim handle early. Single-write claims auto-release. */
-    release(params: ClaimLookupParams<T> | ClaimHandle<T>): Promise<void>;
+    release(params: ClaimLookupParams<T> | Claim<T>): Promise<void>;
 }
 /**
  * The awaited form of a claim method: a synchronous return becomes a `Promise`,
@@ -321,8 +321,13 @@ export interface ClaimReadApi<T = Record<string, unknown>> {
  */
 export type AwaitedClaimMethod<F> = F extends (...args: infer A) => infer R ? R extends Promise<unknown> ? (...args: A) => R : (...args: A) => Promise<R> : F;
 export interface ClaimApi<T> extends ClaimReadApi<T> {
-    /** Take a claim and get an explicit held-work handle back. */
-    (params: ClaimParams<T>): Promise<ClaimHandle<T>>;
+    /**
+     * Take a claim and get an explicit held-work handle back. Returns a
+     * {@link Claim} — `data` (and `readAt`) are guaranteed present
+     * because this door always re-reads the row under the lease, so callers use
+     * `handle.data` directly without a guard.
+     */
+    (params: ClaimParams<T>): Promise<Claim<T>>;
 }
 export interface ModelRetrieveParams extends ServerRetrieveOptions {
     readonly id: string;
@@ -330,16 +335,16 @@ export interface ModelRetrieveParams extends ServerRetrieveOptions {
 export interface ModelCreateParams<T, CreateInput> extends MutationOptions {
     readonly data: CreateInput;
     readonly id?: string | null;
-    readonly claim?: ClaimHandle<T> | ClaimTargetOptions<T> | null;
+    readonly claim?: Claim<T> | ClaimTargetOptions<T> | null;
 }
 export interface ModelUpdateParams<T> extends MutationOptions {
     readonly id: string;
     readonly data: Partial<T>;
-    readonly claim?: ClaimHandle<T> | ClaimTargetOptions<T> | null;
+    readonly claim?: Claim<T> | ClaimTargetOptions<T> | null;
 }
 export interface ModelDeleteParams<T> extends MutationOptions {
     readonly id: string;
-    readonly claim?: ClaimHandle<T> | ClaimTargetOptions<T> | null;
+    readonly claim?: Claim<T> | ClaimTargetOptions<T> | null;
 }
 /** Options for the WebSocket-only `ablo.<model>.watch(ids, options?)`. */
 export interface WatchOptions {

package/dist/client/createModelProxy.js

@@ -39,7 +39,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
     // with the commit op's model name; a lease recorded under the schema key
     // never collides with it — which silently disarmed the guard for every
     // model whose schema key differs from its typename (i.e. nearly all of
-    // them, plural key vs singular typename). Public surfaces (ClaimHandle.
+    // them, plural key vs singular typename). Public surfaces (Claim.
     // target.model) keep the schema key; only the wire/coordination targets
     // use this.
     const wireModel = registeredModelName.toLowerCase();
@@ -90,7 +90,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
     const isClaimHandle = (value) => typeof value === 'object' &&
         value !== null &&
         value.object === 'claim' &&
-        typeof value.claimId === 'string' &&
+        typeof value.id === 'string' &&
         typeof value.release === 'function';
     const claimMeta = (options) => {
         if (!options?.description)
@@ -131,7 +131,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
         if (!held)
             return;
         activeClaims.delete(id);
-        await held.lease.release();
+        await held.lease.release?.();
     };
     const takeClaim = async (params) => {
         if (!collaboration) {
@@ -214,7 +214,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
         }
         const snapshot = collaboration.createSnapshot(schemaKey, id);
         const reason = options?.reason ?? 'editing';
-        // The self-claim's `EntityRef` mirrors what a peer's `claim.state` would
+        // The self-claim's `ClaimTarget` mirrors what a peer's `claim.state` would
         // report (`state` maps `held.target.model` → `type`), so a holder and a
         // peer see the SAME target.type for one row — the wire model token.
         const selfTarget = {
@@ -235,7 +235,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
             expiresAt,
         });
         const target = {
-            model: schemaKey,
+            type: schemaKey,
             id,
             ...(options?.field ? { field: options.field } : {}),
             ...(options?.path ? { path: options.path } : {}),
@@ -245,7 +245,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
         const release = () => releaseClaim(id);
         return {
             object: 'claim',
-            claimId: lease.claimId,
+            id: lease.id,
             readAt: snapshot.stamp,
             target,
             reason,
@@ -278,7 +278,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
             if (own) {
                 return {
                     object: 'claim',
-                    id: own.lease.claimId,
+                    id: own.lease.id,
                     status: 'active',
                     target: own.target,
                     reason: own.reason,
@@ -403,7 +403,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
             const effective = {
                 ...opts,
                 ...(autoLease ? { claim: autoLease } : {}),
-                ...(isClaimHandle(claim) ? { claim: { id: claim.claimId } } : {}),
+                ...(isClaimHandle(claim) ? { claim: { id: claim.id } } : {}),
             };
             try {
                 syncClient.add(model, effective);
@@ -411,7 +411,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
                 return modelAsRow(model);
             }
             finally {
-                await autoLease?.release().catch(() => { });
+                await autoLease?.release?.().catch(() => { });
             }
         }),
         update: guard(async (params) => {
@@ -422,7 +422,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
                     return await operations.update({ ...params, claim: handle });
                 }
                 finally {
-                    await handle.release();
+                    await handle.release?.();
                 }
             }
             const { id } = params;
@@ -439,7 +439,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
                     wait: 'confirmed',
                     readAt: claimed.snapshot.stamp,
                     onStale: 'reject',
-                    claimRef: { id: claimed.lease.claimId },
+                    claimRef: { id: claimed.lease.id },
                     ...opts,
                 }
                 : {
@@ -454,7 +454,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
                         }
                         : {}),
                     ...opts,
-                    ...(handle ? { claim: { id: handle.claimId } } : {}),
+                    ...(handle ? { claim: { id: handle.id } } : {}),
                 };
             // Local user update: `applyChanges` keeps change tracking ON so
             // the edited fields land in `modifiedProperties` and actually get
@@ -473,7 +473,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
                     await operations.delete({ ...params, claim: handle });
                 }
                 finally {
-                    await handle.release();
+                    await handle.release?.();
                 }
                 return;
             }
@@ -489,7 +489,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
                     wait: 'confirmed',
                     readAt: claimed.snapshot.stamp,
                     onStale: 'reject',
-                    claimRef: { id: claimed.lease.claimId },
+                    claimRef: { id: claimed.lease.id },
                     ...opts,
                 }
                 : {
@@ -501,7 +501,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
                         }
                         : {}),
                     ...opts,
-                    ...(handle ? { claim: { id: handle.claimId } } : {}),
+                    ...(handle ? { claim: { id: handle.id } } : {}),
                 };
             syncClient.delete(model, effective);
             await waitForMutation(model, effective);

package/dist/client/sessionMint.d.ts

@@ -6,6 +6,16 @@ export interface MintSessionContext {
     readonly apiKey: string;
     readonly baseUrl: string;
     readonly fetch?: typeof fetch;
+    /**
+     * Schema-key → wire typename map, supplied ONLY by the schema client
+     * (`Ablo`). A capability is scoped by the lowercased TYPENAME the Hub
+     * checks, but `can` is keyed by schema key — so `can: { documents: ['update'] }`
+     * on a model whose `typename` is overridden to `Document` must mint
+     * `document.update`, not `documents.update` (else the Hub denies it with
+     * `capability_scope_denied`). The schemaless `ApiClient` omits this map:
+     * there the `can` key already IS the wire token, so no translation applies.
+     */
+    readonly modelTypenames?: Readonly<Record<string, string>>;
 }
 /**
  * Mint a session token from an already-resolved `sk_` credential + base URL.