@abloatai/ablo 0.25.0 → 0.27.0

package/dist/sync/awaitClaimGrant.d.ts

@@ -1,30 +1,30 @@
 /**
- * `awaitClaimGrant` — the client side of the fair-queue handover.
+ * Waits for a queued claim to reach the head of the line — the client side of
+ * the fair-queue handover. When a claim is contended, the server puts it in a
+ * queue and replies that it is queued (HTTP 202 on `/v1/claims`, or a
+ * `claim_queued` frame over the WebSocket). The grant is delivered later, when
+ * the claim reaches the head, as a `claim_granted` frame. This resolves once
+ * that frame arrives for the given `claimId`, so the caller's `claim` promise
+ * stays pending — event-driven, with no polling — until it is actually the
+ * caller's turn. It rejects if the claim is lost (`claim_lost`: taken away by a
+ * TTL lapse on disconnect, or revoked) or if an optional timeout elapses.
  *
- * When a `claim` is contended, the server enqueues it and replies `queued`
- * (HTTP 202 on `/v1/claims`, or `claim_queued` over WS). The grant is then
- * PUSHED later over the WS as `claim_granted` when the claim reaches the head.
- * This resolves once that frame arrives for our `claimId` — so the caller's
- * `claim` promise stays pending (event-driven; no poll, no race) until it's
- * actually our turn. Rejects on `claim_lost` (surfaced as `claim_lost`: the claim was taken away — TTL
- * lapse on disconnect, revoke) or an optional timeout.
- *
- * Takes only a minimal `{ subscribe }` transport so it unit-tests against a
- * fake; `SyncWebSocket` satisfies it structurally.
+ * It needs only a minimal `{ subscribe }` transport, so it can be tested
+ * against a fake; {@link SyncWebSocket} satisfies it.
  */
 export interface GrantTransport {
     subscribe(event: 'claim_acquired' | 'claim_granted' | 'claim_lost' | 'claim_queued' | 'claim_rejected', handler: (payload: Record<string, unknown>) => void): () => void;
 }
 export interface ClaimGrantInfo {
     /**
-     * True when the grant arrived as `claim_granted` — i.e. the target was
-     * HELD when we asked and we waited in the FIFO line behind the holder.
-     * False for the immediate `claim_acquired` (target was free).
+     * True when the grant arrived as `claim_granted` — the target was held when
+     * the caller asked, and the caller waited in the FIFO line behind the holder.
+     * False for the immediate `claim_acquired`, where the target was free.
      *
-     * Callers use this to know the row may have changed while we queued:
-     * claim VISIBILITY is entity-scoped (org-wide subscriptions receive no
-     * presence/claim fan-out — see Hub.broadcastPresenceChange), so the
-     * local coordination snapshot cannot be trusted to detect "we waited".
+     * Callers read this to know the row may have changed while they queued. Claim
+     * visibility is scoped to the entity, so a broad, organization-wide
+     * subscription receives no presence or claim fan-out, and the local
+     * coordination snapshot cannot be trusted to tell whether the caller waited.
      * The grant frame itself is the authoritative signal.
      */
     readonly waited: boolean;

package/dist/sync/awaitClaimGrant.js

@@ -1,16 +1,16 @@
 /**
- * `awaitClaimGrant` — the client side of the fair-queue handover.
+ * Waits for a queued claim to reach the head of the line — the client side of
+ * the fair-queue handover. When a claim is contended, the server puts it in a
+ * queue and replies that it is queued (HTTP 202 on `/v1/claims`, or a
+ * `claim_queued` frame over the WebSocket). The grant is delivered later, when
+ * the claim reaches the head, as a `claim_granted` frame. This resolves once
+ * that frame arrives for the given `claimId`, so the caller's `claim` promise
+ * stays pending — event-driven, with no polling — until it is actually the
+ * caller's turn. It rejects if the claim is lost (`claim_lost`: taken away by a
+ * TTL lapse on disconnect, or revoked) or if an optional timeout elapses.
  *
- * When a `claim` is contended, the server enqueues it and replies `queued`
- * (HTTP 202 on `/v1/claims`, or `claim_queued` over WS). The grant is then
- * PUSHED later over the WS as `claim_granted` when the claim reaches the head.
- * This resolves once that frame arrives for our `claimId` — so the caller's
- * `claim` promise stays pending (event-driven; no poll, no race) until it's
- * actually our turn. Rejects on `claim_lost` (surfaced as `claim_lost`: the claim was taken away — TTL
- * lapse on disconnect, revoke) or an optional timeout.
- *
- * Takes only a minimal `{ subscribe }` transport so it unit-tests against a
- * fake; `SyncWebSocket` satisfies it structurally.
+ * It needs only a minimal `{ subscribe }` transport, so it can be tested
+ * against a fake; {@link SyncWebSocket} satisfies it.
  */
 import { AbloClaimedError, formatClaimedErrorMessage, claimTargetLabel, } from '../errors.js';
 import { getContext } from '../context.js';
@@ -31,7 +31,7 @@ export function awaitClaimGrant(transport, claimId, options) {
         unsubs.push(transport.subscribe('claim_acquired', (p) => {
             if (p?.claimId === claimId) {
                 getContext().logger.debug(`claim: acquired ${claimId} (target was free)`);
-                settle(() => resolve({ waited: false }));
+                settle(() => { resolve({ waited: false }); });
             }
         }));
         unsubs.push(transport.subscribe('claim_granted', (p) => {
@@ -39,7 +39,7 @@ export function awaitClaimGrant(transport, claimId, options) {
                 // Promoted to the head of the line — the creator's "it's the agent's
                 // turn now" moment after waiting behind a holder.
                 getContext().logger.info(`claim: granted ${claimId} — your turn (waited in queue)`);
-                settle(() => resolve({ waited: true }));
+                settle(() => { resolve({ waited: true }); });
             }
         }));
         if (options?.maxQueueDepth !== undefined) {
@@ -49,7 +49,9 @@ export function awaitClaimGrant(transport, claimId, options) {
                     return;
                 const position = typeof p.position === 'number' ? p.position : 0;
                 if (position >= max) {
-                    settle(() => reject(new AbloClaimedError(`Claim queue for ${claimId} is ${position} deep (max ${max}).`, { code: 'queue_too_deep' })));
+                    settle(() => {
+                        reject(new AbloClaimedError(`Claim queue for ${claimId} is ${position} deep (max ${max}).`, { code: 'queue_too_deep' }));
+                    });
                 }
             }));
         }
@@ -64,29 +66,35 @@ export function awaitClaimGrant(transport, claimId, options) {
                     field: rejection.target.field,
                 })
                 : claimId;
-            settle(() => reject(new AbloClaimedError(formatClaimedErrorMessage({
-                targetLabel: target,
-                heldBy: rejection.heldBy,
-                claim: rejection.heldByClaim,
-                policyReason: rejection.policyReason,
-                fallback: `Claim rejected for ${target}.`,
-            }), {
-                code: rejection.reason === 'conflict'
-                    ? 'claim_conflict'
-                    : 'claim_lease_unavailable',
-                claims: rejection.heldByClaim ? [rejection.heldByClaim] : undefined,
-            })));
+            settle(() => {
+                reject(new AbloClaimedError(formatClaimedErrorMessage({
+                    targetLabel: target,
+                    heldBy: rejection.heldBy,
+                    claim: rejection.heldByClaim,
+                    policyReason: rejection.policyReason,
+                    fallback: `Claim rejected for ${target}.`,
+                }), {
+                    code: rejection.reason === 'conflict'
+                        ? 'claim_conflict'
+                        : 'claim_lease_unavailable',
+                    claims: rejection.heldByClaim ? [rejection.heldByClaim] : undefined,
+                }));
+            });
         }));
         unsubs.push(transport.subscribe('claim_lost', (p) => {
             if (p?.claimId === claimId) {
-                settle(() => reject(new AbloClaimedError(`Claim lost while queued for ${claimId}.`, {
-                    code: 'claim_lost',
-                })));
+                settle(() => {
+                    reject(new AbloClaimedError(`Claim lost while queued for ${claimId}.`, {
+                        code: 'claim_lost',
+                    }));
+                });
             }
         }));
         if (options?.timeoutMs && options.timeoutMs > 0) {
             timer = setTimeout(() => {
-                settle(() => reject(new AbloClaimedError(`Timed out waiting for the queue grant on claim ${claimId}.`, { code: 'grant_timeout' })));
+                settle(() => {
+                    reject(new AbloClaimedError(`Timed out waiting for the queue grant on claim ${claimId}.`, { code: 'grant_timeout' }));
+                });
             }, options.timeoutMs);
         }
     });

package/dist/sync/bootstrapApply.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Applies a bootstrap result to the in-memory object pool. When a client
+ * connects, the server sends either a full snapshot of the models it can see or
+ * a partial catch-up of the deltas it missed. These functions route that result
+ * into the pool, protect entities that arrived mid-bootstrap from being swept
+ * away as stale, and replay any deltas that queued while the bootstrap was in
+ * flight.
+ *
+ * The functions here reach their host store only through the small
+ * {@link PoolContext} interface, not the store's concrete class, so the two can
+ * reference each other without forming an import cycle. The pool writes
+ * themselves — creating models, healing partial rows, upserting, and removing
+ * stale local copies the server no longer reports — are performed by the sync
+ * client behind that interface.
+ */
+import type { BootstrapResult } from '../Database.js';
+import type { SyncDelta } from './SyncWebSocket.js';
+/** Counts describing what applying a bootstrap changed in the pool: entities
+ *  added, updated, removed, skipped, and healed, plus the elapsed time. */
+export interface RehydrationStats {
+    added: number;
+    updated: number;
+    removed: number;
+    skipped: number;
+    healed: number;
+    elapsedMs: number;
+}
+/**
+ * The methods the bootstrap-apply functions call back into on the host store.
+ * The two data-application methods arrive with relation enrichment already
+ * bound by the host, so a subclass override of how relations are enriched still
+ * takes effect through this interface.
+ */
+export interface PoolContext {
+    /** Applies persisted delta results to the in-memory pool, with the host's relation enrichment bound. */
+    applyDeltaBatchToPool(results: NonNullable<BootstrapResult['deltaResults']>): void;
+    /** Writes bootstrap data into the pool: creates models, heals partial rows, upserts, and removes stale local copies the server no longer reports. */
+    applyBootstrapDataToPool(bootstrapData: {
+        models?: Record<string, unknown[]>;
+        failedModels?: string[];
+    }, protectedIds?: ReadonlySet<string>): {
+        added: number;
+        updated: number;
+        removed: number;
+        skipped: number;
+        healed: number;
+    };
+    /** Pool size — for the completion log line. */
+    getPoolSize(): number;
+    /** Every id currently in the pool, used to work out which entities must survive the stale-sweep (see {@link collectDeltaProtectedIds}). */
+    getAllPoolIds(): string[];
+    /** Deltas that queued while a bootstrap was in flight; null when no bootstrap
+     *  is running. The host backs this with a field exposed through accessors. */
+    bootstrapDeltaQueue: SyncDelta[] | null;
+    /** Applies a complete set of deltas to the pool atomically — one write, one
+     *  re-render. This entry point lives on the host, not in this module. */
+    applyDeltaFrame(deltas: SyncDelta[]): void;
+}
+/**
+ * Applies a bootstrap result to the in-memory pool and returns what changed.
+ * A full bootstrap creates, heals, and upserts models and removes stale local
+ * copies the server no longer reports; a partial bootstrap routes the missed
+ * deltas through the delta-apply path so deletions evict their entities. See
+ * {@link RehydrationStats} for the returned counts.
+ */
+export declare function applyBootstrapToPool(ctx: PoolContext, bootstrapResult: BootstrapResult, protectedIds?: ReadonlySet<string>): RehydrationStats;
+/** Collects the ids that must survive the post-bootstrap stale-sweep: entities added by deltas that arrived while the bootstrap was in flight. */
+export declare function collectDeltaProtectedIds(ctx: PoolContext, preBootstrapIds: ReadonlySet<string>): Set<string>;
+/** Replays the deltas that queued while a bootstrap was in flight, applying them as one atomic frame. */
+export declare function replayQueuedDeltas(ctx: PoolContext): void;

package/dist/sync/bootstrapApply.js

@@ -0,0 +1,73 @@
+/**
+ * Applies a bootstrap result to the in-memory object pool. When a client
+ * connects, the server sends either a full snapshot of the models it can see or
+ * a partial catch-up of the deltas it missed. These functions route that result
+ * into the pool, protect entities that arrived mid-bootstrap from being swept
+ * away as stale, and replay any deltas that queued while the bootstrap was in
+ * flight.
+ *
+ * The functions here reach their host store only through the small
+ * {@link PoolContext} interface, not the store's concrete class, so the two can
+ * reference each other without forming an import cycle. The pool writes
+ * themselves — creating models, healing partial rows, upserting, and removing
+ * stale local copies the server no longer reports — are performed by the sync
+ * client behind that interface.
+ */
+import { getContext } from '../context.js';
+/**
+ * Applies a bootstrap result to the in-memory pool and returns what changed.
+ * A full bootstrap creates, heals, and upserts models and removes stale local
+ * copies the server no longer reports; a partial bootstrap routes the missed
+ * deltas through the delta-apply path so deletions evict their entities. See
+ * {@link RehydrationStats} for the returned counts.
+ */
+export function applyBootstrapToPool(ctx, bootstrapResult, protectedIds) {
+    const { bootstrapData } = bootstrapResult;
+    // Partial bootstrap: the missed deltas are already written to the local
+    // store. Route the same results through the delta-apply path so the
+    // in-memory pool also evicts deleted entities and updates modified ones.
+    // Without this, a reconnect delete persists locally but its stale copy
+    // lingers in the pool until a full reload.
+    if (bootstrapData.type === 'partial') {
+        const deltaResults = bootstrapResult.deltaResults;
+        if (deltaResults && deltaResults.length > 0) {
+            ctx.applyDeltaBatchToPool(deltaResults);
+        }
+        return { added: 0, updated: 0, removed: 0, skipped: 0, healed: 0, elapsedMs: 0 };
+    }
+    if (!bootstrapData.models) {
+        return { added: 0, updated: 0, removed: 0, skipped: 0, healed: 0, elapsedMs: 0 };
+    }
+    const start = typeof performance !== 'undefined' ? performance.now() : Date.now();
+    // Creates models, heals partial rows, upserts, and removes stale local copies.
+    const stats = ctx.applyBootstrapDataToPool(bootstrapData, protectedIds);
+    const elapsedMs = Math.round((typeof performance !== 'undefined' ? performance.now() : Date.now()) - start);
+    getContext().logger.info('[BaseSyncedStore] Bootstrap applied', {
+        ...stats, elapsedMs, poolSize: ctx.getPoolSize(),
+    });
+    return { ...stats, elapsedMs };
+}
+/** Collects the ids that must survive the post-bootstrap stale-sweep: entities added by deltas that arrived while the bootstrap was in flight. */
+export function collectDeltaProtectedIds(ctx, preBootstrapIds) {
+    const protectedIds = new Set();
+    for (const id of ctx.getAllPoolIds()) {
+        if (!preBootstrapIds.has(id))
+            protectedIds.add(id);
+    }
+    for (const delta of ctx.bootstrapDeltaQueue ?? []) {
+        if (delta.actionType !== 'D' && delta.modelId)
+            protectedIds.add(delta.modelId);
+    }
+    return protectedIds;
+}
+/** Replays the deltas that queued while a bootstrap was in flight, applying them as one atomic frame. */
+export function replayQueuedDeltas(ctx) {
+    const queue = ctx.bootstrapDeltaQueue;
+    ctx.bootstrapDeltaQueue = null;
+    if (!queue || queue.length === 0)
+        return;
+    // Deltas that landed during bootstrap are a complete frame — apply
+    // them atomically (one flush, one re-render) rather than dribbling
+    // each back through the live debounce path.
+    ctx.applyDeltaFrame(queue);
+}

package/dist/sync/commitFrames.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Builds the outgoing frames the sync WebSocket sends on the commit path, and
+ * provides the single place claim events are traced. These are stateless
+ * helpers that hold no socket state, so both the transport and its frame
+ * dispatch can share them.
+ */
+import type { CommitMessage } from '../wire/index.js';
+import type { MutationOperation, ClaimEvent } from '../interfaces/index.js';
+import type { StaleNotification, ReadDependency } from '../coordination/schema.js';
+/**
+ * The value a commit acknowledgement resolves to. `notifications` is present
+ * only when a guarded write (`onStale: 'notify'`) met a concurrent change; it
+ * carries the advisory signal that lets the writer self-heal, and the same
+ * signal also arrives on the `conflict:notified` event.
+ */
+export interface CommitAck {
+    lastSyncId: number;
+    notifications?: StaleNotification[];
+}
+/**
+ * Converts the client's list of {@link MutationOperation} values into the wire
+ * {@link CommitMessage} the server accepts. This is the one place the loosely
+ * typed operation — its `type` is a string, and it carries client-only
+ * `options` the server never reads — becomes the strict wire contract. Mapping
+ * each field by hand means a change to {@link CommitOperation} fails to compile
+ * here; the single `as` cast narrows the validated `type` to the wire union and
+ * is the only place that loosening happens.
+ */
+export declare function buildCommitFrame(operations: readonly MutationOperation[], clientTxId: string, causedByTaskId?: string | null, reads?: readonly ReadDependency[] | null): CommitMessage;
+/**
+ * Defensively validate the optional `notifications` array off a commit ack.
+ * Untrusted wire data — a malformed entry is dropped rather than throwing,
+ * so a bad notification never sinks an otherwise-successful commit.
+ */
+export declare function parseNotifications(raw: unknown): StaleNotification[] | undefined;
+/**
+ * The single place claim events are traced. Every `claim_*` frame passes
+ * through here, so a developer debugging a collision gets one consistent record
+ * — a console line and a structured capture — without each frame case
+ * re-deriving the row and holder shape. The wire payload is loosely typed
+ * (`Record<string, unknown>`), so this is the one place that narrows it into a
+ * {@link ClaimEvent}.
+ */
+export declare function recordClaim(phase: ClaimEvent['phase'], payload: Record<string, unknown>): void;

package/dist/sync/commitFrames.js

@@ -0,0 +1,94 @@
+/**
+ * Builds the outgoing frames the sync WebSocket sends on the commit path, and
+ * provides the single place claim events are traced. These are stateless
+ * helpers that hold no socket state, so both the transport and its frame
+ * dispatch can share them.
+ */
+import { getContext } from '../context.js';
+import { staleNotificationSchema, wireParticipantKindSchema, } from '../coordination/schema.js';
+import { formatClaim } from '../coordination/trace.js';
+/**
+ * Converts the client's list of {@link MutationOperation} values into the wire
+ * {@link CommitMessage} the server accepts. This is the one place the loosely
+ * typed operation — its `type` is a string, and it carries client-only
+ * `options` the server never reads — becomes the strict wire contract. Mapping
+ * each field by hand means a change to {@link CommitOperation} fails to compile
+ * here; the single `as` cast narrows the validated `type` to the wire union and
+ * is the only place that loosening happens.
+ */
+export function buildCommitFrame(operations, clientTxId, causedByTaskId, reads) {
+    const payload = {
+        operations: operations.map((op) => ({
+            type: op.type,
+            model: op.model,
+            id: op.id,
+            input: op.input,
+            transactionId: op.transactionId,
+            readAt: op.readAt,
+            onStale: op.onStale,
+        })),
+        clientTxId,
+    };
+    if (causedByTaskId)
+        payload.causedByTaskId = causedByTaskId;
+    // The read set the batch was premised on: the rows or groups the writer read before committing.
+    if (reads && reads.length > 0)
+        payload.reads = [...reads];
+    return { type: 'commit', payload };
+}
+/**
+ * Defensively validate the optional `notifications` array off a commit ack.
+ * Untrusted wire data — a malformed entry is dropped rather than throwing,
+ * so a bad notification never sinks an otherwise-successful commit.
+ */
+export function parseNotifications(raw) {
+    if (!Array.isArray(raw) || raw.length === 0)
+        return undefined;
+    const out = [];
+    for (const entry of raw) {
+        const parsed = staleNotificationSchema.safeParse(entry);
+        if (parsed.success)
+            out.push(parsed.data);
+    }
+    return out.length > 0 ? out : undefined;
+}
+/**
+ * The single place claim events are traced. Every `claim_*` frame passes
+ * through here, so a developer debugging a collision gets one consistent record
+ * — a console line and a structured capture — without each frame case
+ * re-deriving the row and holder shape. The wire payload is loosely typed
+ * (`Record<string, unknown>`), so this is the one place that narrows it into a
+ * {@link ClaimEvent}.
+ */
+export function recordClaim(phase, payload) {
+    const str = (v) => typeof v === 'string' ? v : undefined;
+    // Targets arrive flat ({ entityType, entityId }) or nested under `target`.
+    const target = payload.target && typeof payload.target === 'object'
+        ? payload.target
+        : payload;
+    const kind = wireParticipantKindSchema.safeParse(payload.participantKind);
+    const event = {
+        phase,
+        claimId: str(payload.claimId),
+        model: str(target.entityType) ?? str(target.model),
+        id: str(target.entityId) ?? str(target.id),
+        field: str(target.field),
+        actor: str(payload.actor) ?? str(payload.heldBy),
+        participantKind: kind.success ? kind.data : undefined,
+        position: typeof payload.position === 'number' ? payload.position : undefined,
+        reason: str(payload.policyReason) ?? str(payload.reason),
+    };
+    const message = formatClaim(event);
+    // A rejection or lost lease is the collision a developer is actively
+    // debugging → warn (shows at the default log level). The routine events
+    // (acquired/queued/granted/expired) are debug-only so they never drown the
+    // console until you opt in with `new Ablo({ debug: true })`.
+    const isCollision = phase === 'rejected' || phase === 'lost';
+    const ctx = getContext();
+    if (isCollision)
+        ctx.logger.warn(message);
+    else
+        ctx.logger.debug(message);
+    ctx.observability.breadcrumb(message, 'sync.coordination', isCollision ? 'warning' : 'info');
+    ctx.observability.captureClaim(event);
+}

package/dist/sync/createClaimStream.d.ts

@@ -1,25 +1,25 @@
 /**
- * Transport-driven ClaimStream factory.
+ * Creates a {@link ClaimStream} over a live sync connection. A claim is a
+ * short-lived, advisory lease a participant takes on an entity (or a field of
+ * one) to signal "I'm working on this"; the stream lets you take claims, see
+ * everyone else's, and watch the wait queue when a claim is contended.
  *
- * Mirrors `createPresenceStream` — built directly on `SyncWebSocket`,
- * no SyncAgent wrapper. Claims derive their `others` view from the
- * same `presence_update` frames the presence stream consumes (the
- * Hub piggybacks `activeClaims` on every presence frame). Outbound
- * announce/revoke ride the same socket via `claim_begin` /
+ * The stream is built directly on the sync WebSocket and shares that one
+ * connection. It learns about other participants' claims from the same
+ * `presence_update` frames the {@link createPresenceStream} presence stream
+ * consumes — the server piggybacks each participant's `activeClaims` on every
+ * presence frame — and sends its own claims as `claim_begin` and
  * `claim_abandon` frames.
  *
- * Wire contract (apps/sync-server/src/hub/types.ts):
- *   • Outbound: `{ type: 'claim_begin', payload: { claimId,
- *       entityType, entityId, reason, field?, estimatedMs? } }`
- *   • Outbound: `{ type: 'claim_abandon', payload: { claimId,
- *       entityType?, entityId? } }`
- *   • Inbound (via presence): `event.activeClaims: Claim[]`
- *     stamped with `declaredAt`, `expiresAt`.
- *   • Inbound: `claim_rejected` event with conflict metadata.
- *
- * After the dual-engine collapse (step #36), this is the only
- * ClaimStream factory in the SDK; the older compatibility path
- * deletes.
+ * Wire frames:
+ *   • Outbound `claim_begin` — announce a claim: `{ claimId, entityType,
+ *       entityId, reason, field?, estimatedMs? }`.
+ *   • Outbound `claim_abandon` — release it: `{ claimId, entityType?,
+ *       entityId? }`.
+ *   • Inbound, via presence — `event.activeClaims`, each stamped with
+ *       `declaredAt` and `expiresAt`.
+ *   • Inbound `claim_rejected` — the server refused the claim, with conflict
+ *       metadata.
  */
 import type { SyncWebSocket } from './SyncWebSocket.js';
 import type { ClaimOptions, Claim, ClaimStream, PresenceTarget } from '../types/streams.js';
@@ -29,10 +29,11 @@ export interface ClaimStreamConfig {
 }
 export interface AttachableClaimStream extends ClaimStream {
     /**
-     * INTERNAL lease mint — sends the `claim_begin` frame and returns a held
-     * {@link Claim} (no row `data`; the model door reads the row and stamps it).
-     * Not part of the public `ClaimStream` surface: the only public way to take a
-     * claim is `ablo.<model>.claim({ id })`, which builds on this.
+     * Mints a lease directly: sends the `claim_begin` frame and returns a held
+     * {@link Claim} that carries no row `data` (the resource layer reads the row
+     * and stamps it). This is an internal entry point, not part of the public
+     * {@link ClaimStream}; application code takes a claim through
+     * `ablo.<model>.claim({ id })`, which is built on this.
      */
     claim(target: PresenceTarget, opts?: ClaimOptions): Claim;
     attach(transport: SyncWebSocket): void;