@abloatai/humans 0.37.0

package/dist/local/client/createModelProxy.js

@@ -0,0 +1,880 @@
+/**
+ * Builds the typed client for a single schema model — the object reached as
+ * `ablo.<model>`.
+ *
+ * Each schema model gets one {@link ModelOperations}: the async server reads
+ * `get` and `list`, with the same point lookup restricted to the local graph under
+ * `local`, the writes `create`, `update`, and `delete`, the coordination
+ * namespace `claim` (callable as `claim({ id })`, plus `claim.state`,
+ * `claim.queue`, `claim.release`, and `claim.reorder`), `join`, and `onChange`.
+ * The factory returns a plain object; the client assembles the `ablo.<model>`
+ * lookup table from one of these per model.
+ */
+import { autorun } from 'mobx';
+import { AbloClaimedError, AbloValidationError, toAbloError, } from '@abloatai/transaction/errors';
+import { reconcileFunctionalUpdate, } from '@abloatai/transaction/resources/functionalUpdate';
+import { claimDescription, } from '@abloatai/transaction/coordination/schema';
+import { Model, modelAsRow } from '../Model.js';
+import { toMs } from '@abloatai/transaction/utils/duration';
+import { LEASE_TTL_MS } from '@abloatai/transaction/wire/protocol';
+import { heartbeatCadenceMs, resolveHeartbeatOptions, resolveHeartbeatPlan, startClaimHeartbeatLoop, } from '@abloatai/transaction/coordination/claimHeartbeatLoop';
+import { assertWriteOptions } from '@abloatai/transaction/resources/writeOptionsSchema';
+import { subTarget } from '@abloatai/transaction/coordination';
+// A named claim-meta crossing (see `claim-meta-crossings-are-enumerated` in
+// .dependency-cruiser.cjs): the reactive proxy's self-claim targets are
+// decodes that build a public claim, so their `meta` converts wire→declared
+// here like the other enumerated crossings.
+import { declaredMeta } from '@abloatai/transaction/coordination/claimMeta';
+import { ModelScope } from '@abloatai/transaction/types';
+const modelClientMeta = new WeakMap();
+export function getModelClientMeta(modelClient) {
+    if (typeof modelClient !== 'object' || modelClient === null)
+        return undefined;
+    return modelClientMeta.get(modelClient);
+}
+export function createModelProxy(schemaKey, registeredModelName, objectPool, syncClient, registry, 
+/**
+ * The one thing this factory asks of the loader: fetch rows for a model.
+ *
+ * Declared as the slice rather than the whole `OnDemandLoader` because the
+ * whole is a class, and a parameter typed as a class can only ever be
+ * satisfied by an instance of it — so every caller that has a narrower
+ * collaborator, a test most of all, is pushed into a cast through `unknown`
+ * to supply the one method that is actually read.
+ */
+hydration, collaboration, 
+/** The client-wide `wait` default; a per-call `wait` still wins over it. */
+defaultWait) {
+    /**
+     * Resolve a row **this** resource owns.
+     *
+     * The pool is one id space, so `objectPool.get(id)` happily returns another
+     * model's row. Every write path below addresses rows by bare id, so without
+     * this an id from a sibling model resolves and gets written — silently
+     * corrupting a row the caller never named.
+     *
+     * `undefined` means genuinely absent. A row belonging to another model throws:
+     * unlike a read, a cross-model *write* is never a legitimate outcome, and
+     * naming both models turns a silent corruption into a one-line diagnosis.
+     */
+    const ownRowOrThrow = (id) => {
+        const own = objectPool.getOfType(id, registeredModelName);
+        if (own)
+            return own;
+        const foreign = objectPool.get(id);
+        if (!foreign)
+            return undefined;
+        const owner = foreign.getModelName();
+        throw new AbloValidationError(`No ${registeredModelName} with id ${id} — that id belongs to a ${owner}. ` +
+            `Read or write it through ${owner}.`, { code: 'entity_not_found' });
+    };
+    const ModelClass = registry.getModelByName(registeredModelName);
+    if (!ModelClass) {
+        throw new AbloValidationError(`Ablo: schema model "${schemaKey}" resolved to "${registeredModelName}", ` +
+            'but no matching constructor was registered.', { code: 'model_not_registered' });
+    }
+    // The coordination plane must speak the same wire dialect as the commit
+    // plane: the lowercased typename (`task`), not the schema key (`tasks`). The
+    // server's commit-time claim guard probes the lease store with the commit
+    // operation's model name, so a lease recorded under the schema key never
+    // matches — which would silently disarm the guard for every model whose
+    // schema key differs from its typename (a plural key against a singular
+    // typename, i.e. nearly all of them). Public surfaces such as
+    // `Claim.target.model` keep the schema key; only the wire and coordination
+    // targets use this.
+    const wireModel = registeredModelName.toLowerCase();
+    // Last-line guarantee for the public surface: any rejection from a lower
+    // layer (transport timeout, IndexedDB failure, a third-party throw) is
+    // coerced to an AbloError before it reaches the consumer. The SDK's
+    // contract is that callers only ever catch tagged errors — `instanceof
+    // AbloError` / `e.type` always hold. Internal helpers stay unwrapped; only
+    // the methods exposed on `operations` are guarded.
+    const guard = (fn) => {
+        return async (...args) => {
+            try {
+                return await fn(...args);
+            }
+            catch (err) {
+                throw toAbloError(err);
+            }
+        };
+    };
+    const load = async (options) => {
+        const rows = await hydration.fetch(schemaKey, options);
+        return rows.map((row) => modelAsRow(row));
+    };
+    const waitForMutation = async (model, options) => {
+        // A per-call `wait` wins; otherwise the client-wide default decides. This
+        // is the single point that turns "confirmed" into actually waiting, so a
+        // client configured that way rejects on a refused write everywhere rather
+        // than in the one place a caller remembered to ask.
+        if ((options?.wait ?? defaultWait) !== 'confirmed')
+            return;
+        // Let sibling writes from the same synchronous burst enter the mutation
+        // queue before forcing a drain. Without this yield, every confirmed
+        // create/update calls syncNow() alone, defeating the queue's microtask
+        // coalescer and producing one SQL transaction per delta.
+        await Promise.resolve();
+        await syncClient.syncNow();
+        await syncClient.waitForConfirmation(model.getModelName(), model.id);
+    };
+    // Claims this proxy currently holds, keyed by entity id. Lets the flat
+    // `release({ id })` and `update({ id, data })` find the lease and snapshot a
+    // `claim({ id })` took, without a per-call handle. Released on dispose,
+    // explicit release, or TTL expiry.
+    //
+    // `target`, `description`, and `expiresAt` are kept alongside the lease so
+    // `claim.state` can synthesize a self-claim: the server excludes a holder's
+    // own presence frames, so this proxy is the only place that knows the client
+    // holds the row. `expiresAt` is the client's best estimate from the requested
+    // TTL (a real epoch-millisecond expiry, not a fabricated watermark), defaulting
+    // to the server's keepalive lease window when no TTL was requested.
+    const activeClaims = new Map();
+    // Server keepalive lease window — the same `LEASE_TTL_MS` the wire protocol
+    // declares, so the client's estimate and the server's lease cannot drift.
+    // This is the fallback expiry estimate when a claim is taken without an
+    // explicit TTL.
+    const DEFAULT_LEASE_TTL_MS = LEASE_TTL_MS;
+    const isClaimHandle = (value) => typeof value === 'object' &&
+        value !== null &&
+        value.object === 'claim' &&
+        typeof value.id === 'string' &&
+        typeof value.release === 'function';
+    const mutationOptions = (params) => {
+        const rest = {
+            idempotencyKey: params.idempotencyKey,
+            label: params.label,
+            wait: params.wait,
+            readAt: params.readAt,
+            onStale: params.onStale,
+            fenceToken: params.fenceToken,
+            claimRef: params.claimRef,
+            reads: params.reads,
+            track: params.track,
+        };
+        // The write-options schema — the runtime twin of the compile-time params.
+        // Catches plain-JavaScript callers (for example `onStale: 'rejct'`) at the
+        // call site with a typed error instead of a silent no-op or a server 400.
+        assertWriteOptions(rest, `${schemaKey} write`);
+        return rest;
+    };
+    const releaseClaim = async (id) => {
+        const held = activeClaims.get(id);
+        if (!held)
+            return;
+        activeClaims.delete(id);
+        await held.lease.release?.();
+    };
+    const takeClaim = async (params) => {
+        if (!collaboration) {
+            throw new AbloValidationError(`Model "${schemaKey}" was built without the collaboration runtime, so claim() is unavailable here. Claiming needs no per-model config — use the standard Ablo({ schema, apiKey }) client and every model is claimable.`, { code: 'model_claim_not_configured' });
+        }
+        const { id, ...options } = params;
+        // Is someone else already on this target? Read the local coordination
+        // snapshot up front — it decides whether a re-read is needed after the
+        // claim (a free or already-held target cannot have changed underneath us).
+        const held = collaboration.state({ model: wireModel, id });
+        const contended = !!held && held.heldBy !== collaboration.selfParticipantId;
+        const failFast = options.queue === false;
+        // The try-claim (`queue: false`): a held target is an expected outcome,
+        // not an error, so it resolves `null` — the caller reads `if (!claim)`
+        // and moves on; who holds it stays readable via `claim.state`. Best-effort
+        // at the client (a racing claim not yet synced into our snapshot slips
+        // through here) — the commit-time claim guard is the authoritative
+        // backstop that rejects the loser's first write. For work-distribution
+        // dedup that's exactly right: don't wait (that would double-process), skip.
+        if (failFast && contended) {
+            return null;
+        }
+        // Ensure the row exists locally before claiming.
+        let model = ownRowOrThrow(id);
+        if (!model) {
+            await load({ where: [['id', id]] });
+            model = ownRowOrThrow(id);
+        }
+        if (!model) {
+            throw new AbloValidationError(`Entity not found: ${registeredModelName}/${id}`, { code: 'entity_not_found' });
+        }
+        // Write intent: enter the entity scope before acquiring the lease so the
+        // holder's claim presence broadcasts to everyone in this entity group,
+        // including a peer that subscribed just before us. Pinning before the lease
+        // rather than after closes the subscribe-versus-broadcast race: the server
+        // fans presence out at claim time, so this client must be in the group when
+        // the claim lands. Awaited because the broadcast ordering depends on it;
+        // still best-effort (the store swallows reconcile errors).
+        await collaboration.pinScope?.({ [schemaKey]: id });
+        // Acquire the lease. By default (`queue` is not false) this goes through the
+        // server's fair FIFO queue: `queue: true` resolves only once the lease is
+        // genuinely ours, blocking behind any current holder, with no check-then-act
+        // gap because the server orders contenders. Fail-fast skips the queue: an
+        // observed conflict was already rejected above, so this just records the lease.
+        const lease = await collaboration.createClaim({
+            target: {
+                model: wireModel,
+                id,
+                // The whole sub-entity locator in one move — listing its members here
+                // is what let `fields` die between the caller and the lease, so the
+                // claim covered the whole row while the caller believed it named parts.
+                ...subTarget(options, schemaKey),
+            },
+            description: claimDescription(options),
+            ttl: options.ttl,
+            queue: !failFast,
+            maxQueueDepth: options.maxQueueDepth,
+            // The one wait cap, declared once on ClaimTargetOptions — the socket
+            // wait and the HTTP poll-wait both honor it as `grant_timeout`.
+            waitTimeoutMs: options.waitTimeoutMs,
+            signal: options.signal,
+        });
+        // Only when the claim actually waited behind another holder can the row have
+        // changed underneath us — re-read so the claimed snapshot reflects what that
+        // holder committed before releasing. Either of two signals suffices:
+        //   - `lease.waited` — the server granted the claim after the client
+        //     provably queued behind a holder. Authoritative; it works even when the
+        //     local snapshot is blind, since claim fan-out is entity-scoped and a
+        //     broadly-subscribed client never observes peers' claims.
+        //   - `contended` — the local snapshot saw a holder up front. Kept for the
+        //     no-queue paths, where no grant frame exists.
+        if ((contended || lease.waited === true) && !failFast) {
+            // `type: 'complete'` forces the round-trip: the hydration ledger would
+            // otherwise serve the local row for an already-hydrated id, and the
+            // holder's final write may not have fanned out yet — the exact
+            // stale-snapshot race this re-read closes.
+            await load({ where: [['id', id]], type: 'complete' });
+            model = ownRowOrThrow(id) ?? model;
+        }
+        const snapshot = collaboration.createSnapshot(schemaKey, id);
+        const description = claimDescription(options);
+        // The self-claim's `ClaimTarget` mirrors what a peer's `claim.state` would
+        // report (`state` maps `held.target.model` to `type`), so a holder and a
+        // peer see the same `target.type` for one row — the wire model token.
+        // Its `meta` is the DECLARED shape (the handle is a public claim), so the
+        // wire-shaped projection converts back through `declaredMeta` — the same
+        // crossing the HTTP handle assembly makes.
+        const { meta: selfMeta, ...selfNarrowed } = subTarget(options, schemaKey);
+        const selfTarget = {
+            type: wireModel,
+            id,
+            ...selfNarrowed,
+            ...(selfMeta !== undefined ? { meta: declaredMeta(selfMeta) } : {}),
+        };
+        const ttlMs = options.ttl !== undefined ? toMs(options.ttl) : DEFAULT_LEASE_TTL_MS;
+        const expiresAt = Date.now() + ttlMs;
+        activeClaims.set(id, {
+            lease,
+            snapshot,
+            target: selfTarget,
+            description,
+            expiresAt,
+        });
+        const { meta: targetMeta, ...targetNarrowed } = subTarget(options, schemaKey);
+        const target = {
+            type: schemaKey,
+            id,
+            ...targetNarrowed,
+            ...(targetMeta !== undefined ? { meta: declaredMeta(targetMeta) } : {}),
+        };
+        // One reading of the heartbeat options — cadence and callbacks from
+        // whichever spelling the caller used (plan object, shorthand, or the
+        // deprecated flat callbacks).
+        const plan = resolveHeartbeatPlan(options);
+        // A beat resolves with the server's extended expiry; keep the local
+        // self-claim estimate in step so `claim.state` renders the real window,
+        // and surface every answer through the plan's `onBeat` (pressure signal).
+        const heartbeat = async (beatOptions) => {
+            if (!lease.heartbeat) {
+                throw new AbloValidationError('This claim handle has no heartbeat wiring, which the standard Ablo({ schema, apiKey }) client provides on every claim. This appears only when a claim is minted through an internal path that predates heartbeats.', { code: 'claim_not_wired' });
+            }
+            const resolved = resolveHeartbeatOptions(beatOptions);
+            const beat = await lease.heartbeat({
+                ttl: resolved.ttl ?? options.ttl,
+                ...(resolved.details !== undefined ? { details: resolved.details } : {}),
+            });
+            const held = activeClaims.get(id);
+            if (held)
+                held.expiresAt = beat.expiresAt;
+            plan.onBeat?.(beat);
+            return beat;
+        };
+        // Opt-in auto-heartbeat: the loop beats until release, and a definitive
+        // loss stops it and surfaces through the plan's `onLost`.
+        const stopHeartbeatLoop = plan.loop
+            ? startClaimHeartbeatLoop({
+                beat: () => heartbeat(),
+                intervalMs: heartbeatCadenceMs(ttlMs, plan.cadence),
+                ...(plan.onLost ? { onLost: plan.onLost } : {}),
+            })
+            : undefined;
+        const release = () => {
+            stopHeartbeatLoop?.();
+            return releaseClaim(id);
+        };
+        return {
+            object: 'claim',
+            id: lease.id,
+            readAt: snapshot.stamp,
+            // The fencing token the server minted for this grant, forwarded from the
+            // lease so writes taken under this handle carry it (Option B).
+            ...(lease.fenceToken !== undefined ? { fenceToken: lease.fenceToken } : {}),
+            target,
+            description,
+            data: modelAsRow(model),
+            release,
+            revoke: () => {
+                void release();
+            },
+            heartbeat,
+            [Symbol.asyncDispose]: release,
+        };
+    };
+    // The row-free sibling of `takeClaim`: locks a key by id alone, for a row that
+    // lives only in the customer's own database and was never synced into Ablo.
+    // Everything about the lease — the fail-fast contention check, the scope pin,
+    // the `createClaim` grant, the heartbeat wiring, and the `activeClaims`
+    // bookkeeping — is identical; what's dropped is the object-pool `load` (and its
+    // `entity_not_found` throw), the post-grant re-read, and the `.data` field,
+    // since there is no local row to hydrate or return.
+    const takeRowFreeClaim = async (id, options) => {
+        if (!collaboration) {
+            throw new AbloValidationError(`Model "${schemaKey}" was built without the collaboration runtime, so claim() is unavailable here. Claiming needs no per-model config — use the standard Ablo({ schema, apiKey }) client and every model is claimable.`, { code: 'model_claim_not_configured' });
+        }
+        // Is someone else already on this target? Read the local coordination
+        // snapshot up front so a `queue: false` caller can reject before announcing
+        // a claim the server would refuse.
+        const held = collaboration.state({ model: wireModel, id });
+        const contended = !!held && held.heldBy !== collaboration.selfParticipantId;
+        const failFast = options.queue === false;
+        // The try-claim (`queue: false`): resolve `null` if a holder is already
+        // visible — an expected outcome, not an error. Best-effort at the client —
+        // a row this participant never synced usually carries no local claim state
+        // either, so a peer gets the deterministic `null` only once it has
+        // observed the holder (entered the row's entity scope). The server's
+        // queue is the backstop for the queuing path.
+        if (failFast && contended) {
+            return null;
+        }
+        // Enter the entity scope before acquiring the lease so the holder's claim
+        // presence broadcasts to everyone in this entity group — the same ordering
+        // the row-bearing path relies on. No pool `load` and no `entity_not_found`
+        // throw: the row lives only in the customer's database, so there is nothing
+        // to hydrate here and nothing to re-read after the grant.
+        await collaboration.pinScope?.({ [schemaKey]: id });
+        const lease = await collaboration.createClaim({
+            target: {
+                model: wireModel,
+                id,
+                // The whole sub-entity locator in one move — listing its members here
+                // is what let `fields` die between the caller and the lease, so the
+                // claim covered the whole row while the caller believed it named parts.
+                ...subTarget(options, schemaKey),
+            },
+            description: claimDescription(options),
+            ttl: options.ttl,
+            queue: !failFast,
+            maxQueueDepth: options.maxQueueDepth,
+            // The one wait cap, declared once on ClaimTargetOptions — the socket
+            // wait and the HTTP poll-wait both honor it as `grant_timeout`.
+            waitTimeoutMs: options.waitTimeoutMs,
+            signal: options.signal,
+        });
+        // A watermark-only snapshot: `createSnapshot` still reads the engine's
+        // current `lastSyncId` even though the pool holds no row (the bucket is
+        // empty). It costs nothing extra and gives a write taken under this lease a
+        // real `readAt` to guard against changes since the lease was acquired.
+        const snapshot = collaboration.createSnapshot(schemaKey, id);
+        const description = claimDescription(options);
+        const selfTarget = {
+            type: wireModel,
+            id,
+            ...subTarget(options, schemaKey),
+        };
+        const ttlMs = options.ttl !== undefined ? toMs(options.ttl) : DEFAULT_LEASE_TTL_MS;
+        const expiresAt = Date.now() + ttlMs;
+        activeClaims.set(id, {
+            lease,
+            snapshot,
+            target: selfTarget,
+            description,
+            expiresAt,
+        });
+        const target = {
+            type: schemaKey,
+            id,
+            ...subTarget(options, schemaKey),
+        };
+        // One reading of the heartbeat options — cadence and callbacks from
+        // whichever spelling the caller used.
+        const plan = resolveHeartbeatPlan(options);
+        // A beat resolves with the server's extended expiry; keep the local
+        // self-claim estimate in step so `claim.state` renders the real window.
+        const heartbeat = async (beatOptions) => {
+            if (!lease.heartbeat) {
+                throw new AbloValidationError('This claim handle has no heartbeat wiring, which the standard Ablo({ schema, apiKey }) client provides on every claim. This appears only when a claim is minted through an internal path that predates heartbeats.', { code: 'claim_not_wired' });
+            }
+            const resolved = resolveHeartbeatOptions(beatOptions);
+            const beat = await lease.heartbeat({
+                ttl: resolved.ttl ?? options.ttl,
+                ...(resolved.details !== undefined ? { details: resolved.details } : {}),
+            });
+            const held = activeClaims.get(id);
+            if (held)
+                held.expiresAt = beat.expiresAt;
+            plan.onBeat?.(beat);
+            return beat;
+        };
+        const stopHeartbeatLoop = plan.loop
+            ? startClaimHeartbeatLoop({
+                beat: () => heartbeat(),
+                intervalMs: heartbeatCadenceMs(ttlMs, plan.cadence),
+                ...(plan.onLost ? { onLost: plan.onLost } : {}),
+            })
+            : undefined;
+        const release = () => {
+            stopHeartbeatLoop?.();
+            return releaseClaim(id);
+        };
+        return {
+            object: 'claim',
+            id: lease.id,
+            readAt: snapshot.stamp,
+            // Forward the grant's fencing token so writes under this row-free lease
+            // carry it (Option B), exactly as the row-bearing claim does.
+            ...(lease.fenceToken !== undefined ? { fenceToken: lease.fenceToken } : {}),
+            target,
+            description,
+            release,
+            revoke: () => {
+                void release();
+            },
+            heartbeat,
+            [Symbol.asyncDispose]: release,
+        };
+    };
+    // `claim` overloads on its first argument: an options object claims a synced
+    // row and resolves to a HeldClaim (carrying `.data`); a bare id claims a key
+    // whose row Ablo doesn't hold and resolves to a HeldLease (no `.data`). Both
+    // route their throws through `toAbloError` via the guarded takers, so the
+    // two-signature shape survives — wrapping the dispatcher itself in `guard`
+    // would collapse the overloads to one.
+    const guardedTakeClaim = guard(takeClaim);
+    const guardedTakeRowFreeClaim = guard(takeRowFreeClaim);
+    function claim(arg, opts) {
+        return typeof arg === 'string'
+            ? guardedTakeRowFreeClaim(arg, opts ?? {})
+            : guardedTakeClaim(arg);
+    }
+    // `claim` is a callable namespace: invoke it to take a claim, reach its
+    // members to read/steer the coordination plane. Attach the readers to the
+    // callable so `ablo.<model>.claim(...)` and `ablo.<model>.claim.state(...)`
+    // are the same object.
+    // `state` and `queue` take a caller-named `meta` shape. The runtime cannot
+    // check it and is not meant to: `target.meta` is application data the
+    // protocol carries verbatim and never interprets, so naming its type is the
+    // caller asserting what it put there — the same bargain as parsing your own
+    // JSON into an interface. These read as `Claim` here, and the one assertion
+    // that applies the caller's parameter is on the assignment below, in one
+    // place rather than at every call site.
+    /**
+     * This client's own claim on a row, as a claim-state object.
+     *
+     * The server excludes a holder's own presence frames and the client skips
+     * them, so a row this client holds is absent from every peer-derived read.
+     * Both `state` and `list` therefore synthesize it from the stored lease, and
+     * they do it through here so the two answers cannot describe the same
+     * holding differently.
+     */
+    const ownClaimState = (id) => {
+        const own = activeClaims.get(id);
+        if (!own)
+            return null;
+        return {
+            object: 'claim',
+            id: own.lease.id,
+            status: 'active',
+            target: own.target,
+            description: own.description,
+            heldBy: collaboration?.selfParticipantId ?? '',
+            participantKind: collaboration?.selfParticipantKind ?? 'user',
+            expiresAt: own.expiresAt,
+            // Symmetric with the peer projection: a holder reading its own claim
+            // sees the same `meta` an observer does.
+            ...(own.target.meta !== undefined ? { meta: own.target.meta } : {}),
+        };
+    };
+    const claimReaders = {
+        state(params) {
+            // Read interest: a passive observer of a row's claim state must enter that
+            // row's entity scope, or it sits only on broader `org:`/`user:` groups and
+            // never receives the holder's entity-scoped claim presence. Best-effort
+            // and fire-and-forget — it never blocks or rejects the read.
+            void collaboration?.enterScope?.({ [schemaKey]: params.id });
+            // Self-awareness: the server excludes a holder's own presence frames and
+            // the client skips them, so `state` would return null for a row this client
+            // holds. Synthesize the active claim from the stored lease so the holder
+            // sees its own claim, honoring the documented contract on `claim.state`.
+            return (ownClaimState(params.id) ??
+                collaboration?.state({ model: wireModel, id: params.id }) ??
+                null);
+        },
+        /**
+         * Every claim on the row, holders first. Sub-row claims on disjoint parts
+         * are all granted, so a row can have several holders at once and
+         * {@link state} answers with one of them — this is the read that renders
+         * all of them. Same list envelope as {@link queue}, reactive on the same
+         * snapshot, so a render reads it inline.
+         */
+        list(params) {
+            void collaboration?.enterScope?.({ [schemaKey]: params.id });
+            const own = ownClaimState(params.id);
+            const peers = collaboration?.holders({ model: wireModel, id: params.id }) ?? [];
+            return {
+                object: 'list',
+                // Own claim first: the server excludes a holder's own presence frames,
+                // so it is never among `peers` and the two never duplicate.
+                data: own ? [own, ...peers] : [...peers],
+            };
+        },
+        queue(params) {
+            return {
+                object: 'list',
+                data: collaboration?.queue({ model: wireModel, id: params.id }) ?? [],
+            };
+        },
+        reorder(params) {
+            collaboration?.reorder({ model: wireModel, id: params.id }, params.order);
+        },
+        release: guard((params) => releaseClaim(isClaimHandle(params) ? params.target.id : params.id)),
+    };
+    // The one place the caller's `meta` parameter is applied — see the note on
+    // `claimReaders`. Everything else about this object is checked structurally.
+    const claimApi = Object.assign(claim, claimReaders);
+    const local = {
+        get(id) {
+            // Scoped to this model: an id belonging to a sibling model reads as
+            // absent rather than being handed back as if it were a `T`.
+            return objectPool.getOfType(id, registeredModelName);
+        },
+        list(options) {
+            const all = objectPool.getByType(ModelClass, (options?.state ?? ModelScope.live));
+            let result = all;
+            if (options?.where) {
+                const where = options.where;
+                result = result.filter((item) => {
+                    for (const [key, value] of Object.entries(where)) {
+                        if (item[key] !== value)
+                            return false;
+                    }
+                    return true;
+                });
+            }
+            if (options?.filter) {
+                result = result.filter(options.filter);
+            }
+            const orderEntry = options?.orderBy ? Object.entries(options.orderBy)[0] : undefined;
+            if (orderEntry) {
+                const [field, dir] = orderEntry;
+                result = [...result].sort((a, b) => {
+                    const av = a[field];
+                    const bv = b[field];
+                    if (av == null || bv == null)
+                        return 0;
+                    const cmp = av < bv ? -1 : av > bv ? 1 : 0;
+                    return dir === 'desc' ? -cmp : cmp;
+                });
+            }
+            if (options?.offset)
+                result = result.slice(options.offset);
+            if (options?.limit)
+                result = result.slice(0, options.limit);
+            return result;
+        },
+        count(options) {
+            return local.list(options).length;
+        },
+    };
+    const get = guard(async (params) => {
+        // Read-interest enrolment: authoritative point reads enter the same
+        // entity scope as the claim stream, while remaining settled reads.
+        void collaboration?.enterScope?.({ [schemaKey]: params.id });
+        const rows = await load({
+            ...params,
+            where: [['id', params.id]],
+            limit: 1,
+        });
+        return rows[0];
+    });
+    const operations = {
+        local,
+        get,
+        retrieve: get,
+        // No automatic scope enrolment on bulk `list`: that would subscribe to an
+        // unbounded set of rows' entity groups.
+        list: guard(load),
+        create: guard(async (params) => {
+            const id = params.id ?? Model.generateId();
+            const opts = mutationOptions(params);
+            const claim = params.claim;
+            let autoLease;
+            if (claim && !isClaimHandle(claim)) {
+                if (!collaboration) {
+                    throw new AbloValidationError(`Model "${schemaKey}" was built without the collaboration runtime, so claim() is unavailable here. Claiming needs no per-model config — use the standard Ablo({ schema, apiKey }) client and every model is claimable.`, { code: 'model_claim_not_configured' });
+                }
+                // Write intent: enter the new row's entity scope before acquiring the
+                // create-claim so the holder's claim presence broadcasts to everyone
+                // already in this entity group (closing the subscribe-versus-broadcast
+                // race — see `takeClaim`). Released with the lease in the `finally`
+                // below. Awaited for broadcast ordering; still best-effort.
+                await collaboration.pinScope?.({ [schemaKey]: id });
+                autoLease = await collaboration.createClaim({
+                    target: {
+                        model: wireModel,
+                        id,
+                        ...subTarget(claim, schemaKey),
+                    },
+                    description: claimDescription(claim, 'creating'),
+                    ttl: claim.ttl,
+                    queue: claim.queue !== false,
+                    maxQueueDepth: claim.maxQueueDepth,
+                });
+            }
+            // Default `organizationId` from the client's identity, matching the other
+            // write path — without this, a caller that omits it would create an
+            // org-unscoped row on one write path but not the other. An explicit value
+            // in `data` still wins via the spread.
+            const orgDefault = params.data.organizationId ??
+                syncClient.getOrganizationId();
+            const model = new ModelClass({
+                id,
+                ...(orgDefault != null ? { organizationId: orgDefault } : {}),
+                ...params.data,
+                createdAt: new Date(),
+                updatedAt: new Date(),
+            });
+            const effective = {
+                ...opts,
+                ...(autoLease ? { claim: autoLease } : {}),
+                ...(isClaimHandle(claim) ? { claim: { id: claim.id } } : {}),
+            };
+            try {
+                syncClient.add(model, effective);
+                await waitForMutation(model, effective);
+                return modelAsRow(model);
+            }
+            finally {
+                await autoLease?.release?.().catch(() => { });
+            }
+        }),
+        // `update` is overloaded — classic `update({ id, data })` + functional
+        // `update(id, current => next)`. The IIFE keeps the shared error-guard
+        // wrapping while exposing the two public signatures (a plain `guard(...)`
+        // would collapse them to one).
+        update: (() => {
+            const updateImpl = guard(async (arg, updater, contention) => {
+                // Functional form: update(id, current => next). Same guarantee as the
+                // HTTP client (shared reconcile loop), implemented with this transport's
+                // own read-fresh + confirmed compare-and-swap. A forced server round-trip
+                // gets the latest row + watermark; the write is stale-guarded by it, so
+                // concurrent writers reconcile instead of clobbering — no claim needed.
+                if (typeof arg === 'string') {
+                    const id = arg;
+                    if (typeof updater !== 'function') {
+                        throw new AbloValidationError(`${registeredModelName}.update('${id}', updater): the second argument must ` +
+                            `be an updater function (current) => next. To write a fixed value, use ` +
+                            `update({ id, data }).`, { code: 'write_options_invalid' });
+                    }
+                    if (!collaboration) {
+                        throw new AbloValidationError(`${registeredModelName}.update(id, updater) needs the collaboration runtime ` +
+                            `(a live WebSocket) to read the row's watermark for its compare-and-swap. ` +
+                            `Use the standard Ablo({ schema, apiKey }) client.`, { code: 'model_claim_not_configured' });
+                    }
+                    return reconcileFunctionalUpdate(updater, contention, {
+                        model: registeredModelName,
+                        id,
+                        readFresh: async () => {
+                            // `type: 'complete'` forces the round-trip — the hydration ledger
+                            // would otherwise serve a possibly-stale local row for a hydrated id.
+                            await load({ where: [['id', id]], type: 'complete' });
+                            const fresh = ownRowOrThrow(id);
+                            const snapshot = collaboration.createSnapshot(schemaKey, id);
+                            return {
+                                data: fresh ? modelAsRow(fresh) : undefined,
+                                stamp: snapshot.stamp,
+                            };
+                        },
+                        writeNext: async (patch, readAt) => {
+                            const model = ownRowOrThrow(id);
+                            if (!model) {
+                                throw new AbloValidationError(`Entity not found: ${registeredModelName}/${id}`, { code: 'entity_not_found' });
+                            }
+                            const effective = {
+                                wait: 'confirmed',
+                                readAt,
+                                onStale: 'reject',
+                            };
+                            model.applyChanges(patch);
+                            syncClient.update(model, effective);
+                            await waitForMutation(model, effective);
+                            return modelAsRow(model);
+                        },
+                    });
+                }
+                const params = arg;
+                const autoClaim = params.claim && !isClaimHandle(params.claim) ? params.claim : null;
+                if (autoClaim) {
+                    const handle = await takeClaim({ ...autoClaim, id: params.id });
+                    // A declined try-claim is `null` only on the standalone verb; a
+                    // write that could not take its claim is a failed write.
+                    if (!handle) {
+                        throw new AbloClaimedError(`${registeredModelName}/${params.id} is held by another participant, so this update's claim could not be taken.`, { code: 'entity_claimed' });
+                    }
+                    try {
+                        return await operations.update({ ...params, claim: handle });
+                    }
+                    finally {
+                        await handle.release();
+                    }
+                }
+                const { id } = params;
+                const model = ownRowOrThrow(id);
+                if (!model)
+                    throw new AbloValidationError(`Entity not found: ${registeredModelName}/${id}`, { code: 'entity_not_found' });
+                // If we hold a claim on this row, guard the write with its snapshot
+                // watermark + lease so it's stale-rejected and attributed to the claim.
+                const claimed = activeClaims.get(id);
+                const opts = mutationOptions(params);
+                const handle = isClaimHandle(params.claim) ? params.claim : undefined;
+                const effective = claimed
+                    ? {
+                        wait: 'confirmed',
+                        readAt: claimed.snapshot.stamp,
+                        onStale: 'reject',
+                        claimRef: { id: claimed.lease.id },
+                        ...opts,
+                    }
+                    : {
+                        // A carried handle engages the same stale guard as a claim this
+                        // proxy took itself — the watermark rides on the handle, so it
+                        // works across clients (HTTP-minted handles included).
+                        ...(handle?.readAt !== undefined
+                            ? {
+                                wait: 'confirmed',
+                                readAt: handle.readAt,
+                                onStale: 'reject',
+                                ...(handle.fenceToken !== undefined
+                                    ? { fenceToken: handle.fenceToken }
+                                    : {}),
+                            }
+                            : {}),
+                        ...opts,
+                        ...(handle ? { claim: { id: handle.id } } : {}),
+                    };
+                // Local user update: `applyChanges` keeps change tracking on so the
+                // edited fields land in `modifiedProperties` and are actually sent to
+                // the server. (`updateFromData` is the hydration path and would discard
+                // the tracking, producing an empty `input: {}` no-op mutation.)
+                model.applyChanges(params.data);
+                syncClient.update(model, effective);
+                await waitForMutation(model, effective);
+                return modelAsRow(model);
+            });
+            function update(arg, updater, contention) {
+                return updateImpl(arg, updater, contention);
+            }
+            return update;
+        })(),
+        delete: guard(async (params) => {
+            const autoClaim = params.claim && !isClaimHandle(params.claim) ? params.claim : null;
+            if (autoClaim) {
+                const handle = await takeClaim({ ...autoClaim, id: params.id });
+                // Same rule as update: a write that could not take its claim fails.
+                if (!handle) {
+                    throw new AbloClaimedError(`${registeredModelName}/${params.id} is held by another participant, so this delete's claim could not be taken.`, { code: 'entity_claimed' });
+                }
+                try {
+                    await operations.delete({ ...params, claim: handle });
+                }
+                finally {
+                    await handle.release();
+                }
+                return;
+            }
+            const { id } = params;
+            // Scoped: "ensure absent" stays idempotent for an id this model simply
+            // doesn't hold, but an id owned by a sibling model throws rather than
+            // deleting a row the caller never addressed.
+            const model = ownRowOrThrow(id);
+            // Idempotent delete: "ensure absent". A row that isn't in this client's
+            // replicated view is already gone from its perspective, so a delete is a
+            // no-op success rather than an `entity_not_found` error. This matches the
+            // HTTP client and makes delete safe to retry or race (two actors deleting
+            // the same row).
+            if (!model)
+                return;
+            const claimed = activeClaims.get(id);
+            const opts = mutationOptions(params);
+            const handle = isClaimHandle(params.claim) ? params.claim : undefined;
+            const effective = claimed
+                ? {
+                    wait: 'confirmed',
+                    readAt: claimed.snapshot.stamp,
+                    onStale: 'reject',
+                    claimRef: { id: claimed.lease.id },
+                    ...(claimed.lease.fenceToken !== undefined
+                        ? { fenceToken: claimed.lease.fenceToken }
+                        : {}),
+                    ...opts,
+                }
+                : {
+                    ...(handle?.readAt !== undefined
+                        ? {
+                            wait: 'confirmed',
+                            readAt: handle.readAt,
+                            onStale: 'reject',
+                        }
+                        : {}),
+                    ...opts,
+                    ...(handle ? { claim: { id: handle.id } } : {}),
+                };
+            syncClient.delete(model, effective);
+            await waitForMutation(model, effective);
+        }),
+        // `claim` is a callable namespace (take a claim) carrying the coordination
+        // readers (`claim.state` / `claim.queue` / `claim.release` / `claim.reorder`).
+        claim: claimApi,
+        track: guard(async (params) => {
+            const dep = {
+                model: wireModel,
+                id: params.id,
+                ...(params.readAt !== undefined ? { readAt: params.readAt } : {}),
+            };
+            // A track carries no write, so it rides the commit lane as a zero-operation
+            // commit: the queue tolerates disconnects and de-dupes replays, and the
+            // server's track-only path registers the premise and reports anything
+            // that already fired. Reuse the same lane the batch `commits.create` door
+            // uses rather than opening a bespoke transport.
+            const clientTxId = typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function'
+                ? crypto.randomUUID()
+                : `tx_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
+            const queue = syncClient.getMutationQueue();
+            await queue.enqueueCommit(clientTxId, [], { track: [dep] });
+            const { notifications } = await queue.waitForCommitReceipt(clientTxId);
+            return notifications && notifications.length > 0 ? { notifications } : {};
+        }),
+        join: guard((ids, options) => {
+            if (!collaboration?.createJoin) {
+                throw new AbloValidationError(`Model "${schemaKey}" was built without a WebSocket runtime, so join() is unavailable here. Presence needs a live socket — use the standard Ablo({ schema, apiKey }) client (not the HTTP transport).`, { code: 'model_join_not_configured' });
+            }
+            return collaboration.createJoin(schemaKey, ids, options);
+        }),
+        onChange(callback, options) {
+            return autorun(() => {
+                callback(local.list(options));
+            });
+        },
+    };
+    modelClientMeta.set(operations, {
+        key: schemaKey,
+        typename: registeredModelName,
+    });
+    return operations;
+}