@abloatai/ablo 0.29.2 → 0.30.0

package/dist/client/Ablo.d.ts

@@ -30,7 +30,7 @@ import { type AbloHttpClient, type AbloHttpClientOptions } from './httpClient.js
 import type { AbloOptions } from './options.js';
 import type { AbloSession, CommitResource, CreateAgentClientParams, CreateSessionParams } from './resourceTypes.js';
 export type { ApiKeySetter, AbloOptions, InternalAbloOptions } from './options.js';
-export type { LocalCountOptions, LocalReadOptions, ModelListScope, ServerReadOptions, ModelRetrieveParams, ModelCreateParams, ModelUpdateParams, ModelDeleteParams, ClaimOptions, ClaimParams, ClaimLookupParams, ClaimReorderParams, Claim, ClaimHeartbeat, ClaimHeartbeatOptions, HeldClaim, ModelOperations, ModelOperationAction, CommitWait, IfClaimedPolicy, ClaimedOptions, ClaimWaitOptions, ModelReadOptions, ClaimCreateOptions, CommitOperationInput, CommitCreateOptions, CommitReceipt, CommitResource, ClaimResource, ModelMutationOptions, HttpClaimApi, SessionOperation, CreateUserSessionParams, CreateAgentSessionParams, CreateSessionParams, CreateAgentClientParams, AbloSession, } from './resourceTypes.js';
+export type { LocalCountOptions, LocalReadOptions, ModelListScope, ServerReadOptions, ModelRetrieveParams, ModelCreateParams, ModelUpdateParams, ModelDeleteParams, ClaimOptions, ClaimParams, ClaimLookupParams, ClaimReorderParams, Claim, ClaimHeartbeat, ClaimHeartbeatOptions, HeldClaim, HeldLease, ModelOperations, ModelOperationAction, CommitWait, IfClaimedPolicy, ClaimedOptions, ClaimWaitOptions, ModelReadOptions, ClaimCreateOptions, CommitOperationInput, CommitCreateOptions, CommitReceipt, CommitResource, ClaimResource, ModelMutationOptions, HttpClaimApi, SessionOperation, CreateUserSessionParams, CreateAgentSessionParams, CreateSessionParams, CreateAgentClientParams, AbloSession, } from './resourceTypes.js';
 export { computeFKDepthPriority } from './schemaConfig.js';
 import type { ModelOperations } from './createModelProxy.js';
 /**

package/dist/client/Ablo.js

@@ -20,7 +20,6 @@
  */
 import { durableCommitOperationSchema, } from '../transactions/commitEnvelope.js';
 import { AbloAuthenticationError, AbloConnectionError, AbloValidationError, toAbloError, claimedError } from '../errors.js';
-import { descriptionFromMeta } from '../coordination/schema.js';
 import { initSyncEngine } from '../context.js';
 import { noopObservability, browserOnlineStatus, defaultSessionErrorDetector, noopAnalytics, } from '../SyncEngineContext.js';
 import { alwaysOnline } from '../adapters/alwaysOnline.js';
@@ -40,8 +39,7 @@ import { createParticipantManager } from '../sync/participants.js';
 // Value import is cycle-safe: httpClient.js and httpTransport.js take the client
 // types from the `options`/`resourceTypes` leaves, never from this module.
 import { createAbloHttpClient, } from './httpClient.js';
-import { assertBrowserSafety, readProcessEnv, resolveApiKey, resolveApiKeyValue, resolveAuthToken, resolveBaseURL, resolveBootstrapBaseUrl, resolveDatabaseUrl, warnIfCliKeyMismatch, warnIfDatabaseUrlEnvIgnored, warnIfDatabaseUrlDeprecated, } from './auth.js';
-import { registerDataSource } from './registerDataSource.js';
+import { assertBrowserSafety, readProcessEnv, resolveApiKey, resolveApiKeyValue, resolveAuthToken, resolveBaseURL, resolveBootstrapBaseUrl, rejectRemovedDatabaseUrlOption, warnIfCliKeyMismatch, } from './auth.js';
 import { shouldUseInMemoryPersistence } from './persistence.js';
 import { deriveConfigFromSchema } from './schemaConfig.js';
 import { registerModelsFromSchema } from './modelRegistration.js';
@@ -89,20 +87,15 @@ export function Ablo(options) {
     const authCredentials = createAuthCredentialSource(
     // eslint-disable-next-line @typescript-eslint/no-deprecated -- load-bearing on the self-hosted path; server-internal cap-mint (Phase 3) not shipped
     internalOptions.capabilityToken ?? configuredAuthToken);
-    const configuredDatabaseUrl = resolveDatabaseUrl(authInput);
+    rejectRemovedDatabaseUrlOption(options);
     assertBrowserSafety({
         apiKey: configuredApiKey,
-        databaseUrl: configuredDatabaseUrl,
         dangerouslyAllowBrowser: options.dangerouslyAllowBrowser,
     });
     // Custom logger wins; otherwise build the default `[Ablo]` logger at the level
     // resolved from `debug`/`logLevel`/`ABLO_LOG_LEVEL` (default `warn`).
     const logger = internalOptions.logger ??
         createConsoleLogger(resolveLogLevel({ debug: options.debug, logLevel: options.logLevel }));
-    // Nudge (once) if a stray DATABASE_URL is in the env but `databaseUrl` wasn't
-    // passed — the env value is no longer auto-adopted (see resolveDatabaseUrl).
-    warnIfDatabaseUrlEnvIgnored(authInput, (m) => { logger.warn(m); });
-    warnIfDatabaseUrlDeprecated(authInput, (m) => { logger.warn(m); });
     void warnIfCliKeyMismatch(authInput, (m) => { logger.warn(m); });
     const schema = options.schema;
     const url = resolveBaseURL(authInput);
@@ -317,19 +310,6 @@ export function Ablo(options) {
                     }
                     authCredentials.setAuthToken(token);
                 }
-                // Register the caller's own database for write-back before bootstrap, so
-                // the server resolves this org's data plane to the customer's DB rather
-                // than serving an empty/wrong store. The org is derived server-side from
-                // the API key. Idempotent server-side (register-or-update). Skipped when
-                // no `databaseUrl` was configured (Ablo-managed storage).
-                if (configuredDatabaseUrl) {
-                    await registerDataSource({
-                        baseUrl: resolveBootstrapBaseUrl({ url }),
-                        apiKey: await resolveApiKeyValue(configuredApiKey),
-                        databaseUrl: configuredDatabaseUrl,
-                        ...(internalOptions.fetch ? { fetchImpl: internalOptions.fetch } : {}),
-                    });
-                }
                 // Resolve participant identity + scope. Three branches —
                 // hosted-cloud apiKey exchange, self-derived from capability
                 // token, or legacy explicit options. See `./identity.ts`.
@@ -490,7 +470,7 @@ export function Ablo(options) {
             ? crypto.randomUUID()
             : `tx_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
     }
-    function normalizeCommitOperation(op, defaults) {
+    function normalizeCommitOperation(op, defaults, fenceToken) {
         const type = op.action.toUpperCase();
         const id = op.id ?? '';
         return durableCommitOperationSchema.parse({
@@ -501,22 +481,23 @@ export function Ablo(options) {
             transactionId: op.transactionId ?? undefined,
             readAt: op.readAt ?? defaults.readAt ?? undefined,
             onStale: op.onStale ?? defaults.onStale ?? undefined,
+            // The batch's claim (if any) supplies one token for every op, mirroring
+            // how it supplies the batch `readAt`.
+            fenceToken: op.fenceToken ?? fenceToken ?? undefined,
         });
     }
-    function normalizeCommitOperations(commitOptions) {
+    function normalizeCommitOperations(commitOptions, fenceToken) {
         if (commitOptions.operations.length === 0) {
             throw new AbloValidationError('Commit requires a non-empty `operations` array.', { code: 'commit_operation_required' });
         }
-        return commitOptions.operations.map((op) => normalizeCommitOperation(op, commitOptions));
+        return commitOptions.operations.map((op) => normalizeCommitOperation(op, commitOptions, fenceToken));
     }
     function modelClaimFromActive(claim) {
-        const description = descriptionFromMeta(claim.target.meta);
         return {
             id: claim.id,
             actor: claim.heldBy ?? "",
             participantKind: claim.participantKind ?? "user",
-            reason: claim.reason,
-            ...(description ? { description } : {}),
+            description: claim.description,
             field: claim.target.field,
             status: 'active',
             expiresAt: claim.expiresAt ?? 0,
@@ -595,16 +576,21 @@ export function Ablo(options) {
             }
         });
     }
-    function wrapClaimHandle(claim, waited = false) {
+    function wrapClaimHandle(claim, waited = false, fenceToken) {
         const release = async () => {
             claim.revoke?.();
         };
+        // The token is server-stamped and arrives on the grant frame, so prefer
+        // the one `awaitClaimGrant` read there; fall back to any the local handle
+        // already carried (immediate, non-queued grants).
+        const resolvedFenceToken = fenceToken ?? claim.fenceToken;
         return {
             object: 'claim',
             id: claim.id,
-            reason: claim.reason,
+            description: claim.description,
             target: claim.target,
             waited,
+            ...(resolvedFenceToken !== undefined ? { fenceToken: resolvedFenceToken } : {}),
             release,
             revoke: claim.revoke,
             // The lease-control members are forwarded explicitly — this wrapper
@@ -625,7 +611,7 @@ export function Ablo(options) {
                 field: claimOptions.target.field,
                 meta: claimOptions.target.meta,
             }, {
-                reason: claimOptions.reason,
+                description: claimOptions.description,
                 ttl: claimOptions.ttl,
                 queue: claimOptions.queue,
             });
@@ -635,11 +621,12 @@ export function Ablo(options) {
             // callers — chiefly `ablo.<model>.claim` — get a handle that already
             // holds the lease, never a half-claimed one racing the queue.
             let waited = false;
+            let fenceToken;
             if (claimOptions.queue) {
                 const ws = store.getSyncWebSocket();
                 if (ws) {
                     try {
-                        ({ waited } = await awaitClaimGrant(ws, claim.id, {
+                        ({ waited, fenceToken } = await awaitClaimGrant(ws, claim.id, {
                             timeoutMs: claimOptions.waitTimeoutMs,
                             maxQueueDepth: claimOptions.maxQueueDepth,
                         }));
@@ -653,7 +640,7 @@ export function Ablo(options) {
                     }
                 }
             }
-            return wrapClaimHandle(claim, waited);
+            return wrapClaimHandle(claim, waited, fenceToken);
         },
         list(target) {
             return listModelClaims(target);
@@ -708,7 +695,7 @@ export function Ablo(options) {
                         ...(held.target.field ? { field: held.target.field } : {}),
                         ...(held.target.meta ? { meta: held.target.meta } : {}),
                     },
-                    reason: held.reason,
+                    description: held.description ?? 'editing',
                     heldBy: held.actor,
                     participantKind: held.participantKind,
                     expiresAt: held.expiresAt,
@@ -757,7 +744,7 @@ export function Ablo(options) {
                 ...commitOptions,
                 readAt: commitOptions.readAt ?? claim?.readAt ?? null,
                 onStale: commitOptions.onStale ?? (claim?.readAt !== undefined ? 'reject' : null),
-            });
+            }, claim?.fenceToken ?? null);
             const wait = commitOptions.wait ?? 'confirmed';
             // Route through the TransactionQueue's commit lane so the call
             // tolerates WS disconnects: the envelope stays in memory until
@@ -775,12 +762,13 @@ export function Ablo(options) {
             if (wait === 'queued') {
                 return { id: clientTxId, status: 'queued' };
             }
-            const { lastSyncId, notifications } = await queue.waitForCommitReceipt(clientTxId);
+            const { lastSyncId, notifications, missingIds } = await queue.waitForCommitReceipt(clientTxId);
             return {
                 id: clientTxId,
                 status: 'confirmed',
                 lastSyncId,
                 ...(notifications && notifications.length > 0 ? { notifications } : {}),
+                ...(missingIds && missingIds.length > 0 ? { missingIds } : {}),
             };
         },
     };

package/dist/client/auth.d.ts

@@ -30,7 +30,6 @@ export interface AuthResolveInput {
         readonly authEndpoint?: string | ApiKeySetter | null;
         readonly authToken?: string | null;
         readonly baseURL?: string | null;
-        readonly databaseUrl?: string | null;
         readonly dangerouslyAllowBrowser?: boolean;
     };
     readonly env: Record<string, string | undefined>;
@@ -66,22 +65,6 @@ export interface CliKeyMismatch {
 /** Infer the sandbox or production mode from an Ablo key's prefix. */
 export declare function modeFromApiKey(key: string): CliMode | undefined;
 export declare function describeCliKeyMismatch(configured: StaticApiKey, cli: CliCredentialSnapshot): CliKeyMismatch | null;
-/**
- * Resolves the Postgres connection string for the direct-connection option, or
- * `null` when none was given.
- *
- * `databaseUrl` is opt-in: the client registers a dedicated database only when
- * the caller passes it explicitly. It is never read from
- * `process.env.DATABASE_URL`, because this module treats `ABLO_API_KEY` as the
- * one environment fallback — an app's `DATABASE_URL`, commonly set for other
- * tools, must not silently switch the client into connection-string mode. The
- * default path leaves `DATABASE_URL` untouched and reads through `dataSource(...)`
- * instead, so this returns `null`. {@link warnIfDatabaseUrlEnvIgnored} nudges a
- * caller who set the environment variable but omitted the option.
- */
-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 { ABLO_HOSTED_API_DOMAIN, ABLO_HOSTED_HTTP_BASE_URL, ABLO_DEFAULT_BASE_URL } from './hostedEndpoints.js';
 /**
@@ -99,9 +82,16 @@ export declare function resolveBaseURL(input: AuthResolveInput): string;
  * server proxy. Throws {@link AbloAuthenticationError} when a secret key is
  * detected in a browser without opt-in.
  */
+/**
+ * Rejects the REMOVED `databaseUrl` dial-in option loudly. The option is gone
+ * from the types, but an untyped or stale caller could still pass it — and
+ * silently ignoring it would reroute their writes to Ablo-hosted storage,
+ * the opposite of what that option used to promise. A construction-time throw
+ * turns a wrong-storage surprise into a clear migration instruction.
+ */
+export declare function rejectRemovedDatabaseUrlOption(options: object): void;
 export declare function assertBrowserSafety(input: {
     apiKey: string | ApiKeySetter | null;
-    databaseUrl?: string | null;
     dangerouslyAllowBrowser: boolean | undefined;
 }): void;
 /**

package/dist/client/auth.js

@@ -223,94 +223,6 @@ export function describeCliKeyMismatch(configured, cli) {
     }
     return null;
 }
-/**
- * Resolves the Postgres connection string for the direct-connection option, or
- * `null` when none was given.
- *
- * `databaseUrl` is opt-in: the client registers a dedicated database only when
- * the caller passes it explicitly. It is never read from
- * `process.env.DATABASE_URL`, because this module treats `ABLO_API_KEY` as the
- * one environment fallback — an app's `DATABASE_URL`, commonly set for other
- * tools, must not silently switch the client into connection-string mode. The
- * default path leaves `DATABASE_URL` untouched and reads through `dataSource(...)`
- * instead, so this returns `null`. {@link warnIfDatabaseUrlEnvIgnored} nudges a
- * caller who set the environment variable but omitted the option.
- */
-export function resolveDatabaseUrl(input) {
-    return input.options.databaseUrl ?? null;
-}
-/**
- * Warns once when `DATABASE_URL` is set in the environment but `databaseUrl` was
- * not passed as an option.
- *
- * The client does not adopt `process.env.DATABASE_URL` on its own, because that
- * value is commonly set for other tools and switching the client into
- * connection-string mode behind the caller's back is surprising — and on
- * localhost it would try to register a database the hosted service cannot reach.
- * This warning points the developer at the explicit option instead. It fires at
- * most once per process and falls back to `console.warn` when no logger is
- * supplied.
- *
- * The warning is skipped entirely when an `apiKey` resolves (from the option or
- * `ABLO_API_KEY`): that caller has chosen the hosted, token-based transport,
- * which is separate from the direct `databaseUrl` connection. A `DATABASE_URL`
- * present in that environment belongs to unrelated infrastructure, not an omitted
- * option, so warning would be a false positive.
- */
-let warnedDatabaseUrlEnvIgnored = false;
-export function warnIfDatabaseUrlEnvIgnored(input, warn) {
-    if (warnedDatabaseUrlEnvIgnored)
-        return;
-    if (input.options.databaseUrl != null)
-        return;
-    // Hosted/token path → DATABASE_URL is unrelated infra, not an omitted option.
-    if (resolveApiKey(input) != null)
-        return;
-    const envUrl = input.env.DATABASE_URL;
-    if (typeof envUrl !== 'string' || envUrl.length === 0)
-        return;
-    warnedDatabaseUrlEnvIgnored = true;
-    const message = 'Found DATABASE_URL in the environment but `databaseUrl` was not passed to Ablo(...). ' +
-        'Ablo no longer auto-adopts DATABASE_URL — the environment value is ignored. ' +
-        'To register your Postgres directly, pass `databaseUrl: process.env.DATABASE_URL` explicitly; ' +
-        'otherwise ignore this (the hosted sandbox and signed Data Source endpoints need no databaseUrl).';
-    if (warn)
-        warn(message);
-    else if (typeof console !== 'undefined')
-        console.warn('[Ablo]', message);
-}
-/**
- * Warns once when the deprecated `databaseUrl` option is used.
- *
- * Passing `databaseUrl` opens a connection pool directly into your Postgres and
- * writes to it. That option is deprecated. Ablo is designed to host only the
- * ordered transaction log (the `sync_deltas` table) and coordination state,
- * never your rows — your data stays in your own database. The supported path is
- * a signed data-source endpoint (`dataSource(...)`), where your app owns the
- * write and your database credentials never leave it.
- *
- * The option still works at runtime so existing integrations keep running. This
- * warning fires at most once per process and falls back to `console.warn` when
- * no logger is supplied.
- */
-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)
@@ -392,6 +304,22 @@ export function resolveBaseURL(input) {
  * server proxy. Throws {@link AbloAuthenticationError} when a secret key is
  * detected in a browser without opt-in.
  */
+/**
+ * Rejects the REMOVED `databaseUrl` dial-in option loudly. The option is gone
+ * from the types, but an untyped or stale caller could still pass it — and
+ * silently ignoring it would reroute their writes to Ablo-hosted storage,
+ * the opposite of what that option used to promise. A construction-time throw
+ * turns a wrong-storage surprise into a clear migration instruction.
+ */
+export function rejectRemovedDatabaseUrlOption(options) {
+    const legacyValue = Reflect.get(options, 'databaseUrl');
+    if (legacyValue == null)
+        return;
+    throw new AbloValidationError('The `databaseUrl` option was removed. Your database connects through ' +
+        '`ablo connect` now: Ablo writes it directly with a scoped DML role and ' +
+        'confirms through its replication stream. Run `npx ablo connect` to ' +
+        'register it, then construct the client with your API key only.', { code: 'invalid_body' });
+}
 export function assertBrowserSafety(input) {
     const inBrowser = typeof window !== 'undefined';
     if (!input.dangerouslyAllowBrowser &&
@@ -405,14 +333,6 @@ export function assertBrowserSafety(input) {
             '`dangerouslyAllowBrowser` option to `true`, e.g.,\n\n' +
             '    Ablo({ schema, apiKey, dangerouslyAllowBrowser: true });\n', { code: 'browser_apikey_blocked' });
     }
-    // `databaseUrl` carries database credentials and is never browser-safe, so
-    // `dangerouslyAllowBrowser` does not override this check. Register your
-    // database from a server-side runtime.
-    if (inBrowser && typeof input.databaseUrl === 'string' && input.databaseUrl.length > 0) {
-        throw new AbloAuthenticationError('Ablo `databaseUrl` cannot be used in a browser-like environment — it ' +
-            'carries your database credentials. Initialize the client with ' +
-            '`databaseUrl` from a server-side runtime only.', { code: 'browser_database_url_blocked' });
-    }
 }
 /**
  * Resolves an {@link ApiKeySetter} callable to its current string value, or

package/dist/client/createModelProxy.d.ts

@@ -20,7 +20,7 @@ import type { OnDemandLoader } from '../sync/OnDemandLoader.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, ClaimHeartbeat, ClaimHeartbeatOptions, HeldClaim, ClaimWaitOptions, Snapshot, TargetRange } from '../types/streams.js';
+import type { Duration, Claim, ClaimHeartbeat, ClaimHeartbeatOptions, HeldClaim, HeldLease, ClaimWaitOptions, Snapshot, TargetRange } from '../types/streams.js';
 export interface ModelClientMeta {
     readonly key: string;
     readonly typename: string;
@@ -88,8 +88,8 @@ export interface ModelCollaboration<T> {
             range?: TargetRange;
             meta?: Record<string, unknown>;
         };
-        /** Human-readable phase (`'editing'`). */
-        reason: string;
+        /** Peer-visible description of the work (`'rewriting the risk section'`). */
+        description?: string;
         ttl?: Duration;
         /**
          * Block on the server's fair FIFO queue when the target is held, rather
@@ -179,10 +179,9 @@ export interface ModelCollaboration<T> {
     createWatch?(modelKey: string, ids: string | readonly string[], options?: WatchOptions): Promise<JoinedParticipant>;
 }
 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. */
-    reason?: string;
-    /** Peer-visible explanation of the work being performed. */
+    /** Peer-visible description of the work being performed — the sentence a
+     *  contending participant reads to decide whether to wait, work elsewhere, or
+     *  move on. Defaults to `'editing'`. The same field on every claim surface. */
     description?: string;
     /** Field-level target, for fine-grained claimed-state badges. */
     field?: string;
@@ -257,7 +256,6 @@ export interface ClaimReorderParams<T = Record<string, unknown>> extends ClaimLo
  * ```ts
  * const claim = await ablo.weatherReports.claim({
  *   id: 'report_stockholm',
- *   reason: 'forecasting',
  *   description: 'Fetching current weather before writing the forecast.',
  * });
  * try {
@@ -275,7 +273,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 and stale-write protection.
  */
-export type { Claim, ClaimHeartbeat, ClaimHeartbeatOptions, HeldClaim };
+export type { Claim, ClaimHeartbeat, ClaimHeartbeatOptions, HeldClaim, HeldLease };
 export type ClaimOptions<T = Record<string, unknown>> = ClaimTargetOptions<T>;
 /**
  * The coordination surface for a model, exposed as a callable namespace.
@@ -289,7 +287,6 @@ export type ClaimOptions<T = Record<string, unknown>> = ClaimTargetOptions<T>;
  *   data: { title },
  *   claim: {
  *     field: 'title',
- *     reason: 'renaming',
  *     description: 'Renaming the task to match the project brief.',
  *   },
  * });
@@ -345,6 +342,15 @@ export interface ClaimApi<T> extends ClaimReadApi<T> {
      * directly and `await using` works without a guard.
      */
     (params: ClaimParams<T>): Promise<HeldClaim<T>>;
+    /**
+     * Takes a claim by id alone, for a row that lives only in the customer's own
+     * database — Ablo has never seen it, so there is nothing to re-read. Returns a
+     * {@link HeldLease}: the same lease controls as {@link HeldClaim}
+     * (`release`, `revoke`, `heartbeat`, `await using`) but no `.data`. Locking a
+     * key you know by id is exactly this — serialize writers without first
+     * syncing the row into Ablo.
+     */
+    (id: string, opts?: ClaimOptions<T>): Promise<HeldLease>;
 }
 export interface ModelRetrieveParams extends ServerRetrieveOptions {
     readonly id: string;
@@ -440,7 +446,6 @@ export interface ModelOperations<T, CreateInput> {
      * ```ts
      * const claim = await ablo.weatherReports.claim({
      *   id: 'report_stockholm',
-     *   reason: 'forecasting',
      *   description: 'Fetching fresh weather before updating the report.',
      * });
      * const weather = await getWeather(claim.data.location);