@abloatai/ablo 0.36.0 → 0.37.0

package/dist/client/createModelProxy.js

@@ -1,884 +0,0 @@
-/**
- * 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
- * `retrieve` and `list`, the same verbs 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, formatClaimedErrorMessage, toAbloError, } from '../transaction/errors.js';
-import { reconcileFunctionalUpdate, } from '../transaction/resources/functionalUpdate.js';
-import { claimDescription, } from '../transaction/coordination/schema.js';
-import { Model, modelAsRow } from '../Model.js';
-import { toMs } from '../transaction/utils/duration.js';
-import { LEASE_TTL_MS } from '../transaction/wire/protocol.js';
-import { heartbeatCadenceMs, resolveHeartbeatOptions, resolveHeartbeatPlan, startClaimHeartbeatLoop, } from '../transaction/coordination/claimHeartbeatLoop.js';
-import { assertWriteOptions } from '../transaction/resources/writeOptionsSchema.js';
-import { modelTarget, subTarget } from '../transaction/coordination/index.js';
-// 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 '../transaction/coordination/claimMeta.js';
-import { ModelScope } from '../transaction/types/index.js';
-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);
-        // The coordinator returns Model instances. ModelOperations is
-        // typed against the schema-inferred row shape (`T`), which is
-        // structurally what the model exposes through its property
-        // accessors — cast at the boundary.
-        return rows;
-    };
-    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;
-        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 claimContextFromClaim = (claim) => {
-        return {
-            id: claim.id,
-            actor: claim.heldBy,
-            participantKind: claim.participantKind,
-            description: claim.description,
-            field: claim.target.field,
-            status: claim.status,
-            expiresAt: claim.expiresAt,
-            target: {
-                ...modelTarget(claim.target),
-                ...subTarget(claim.target),
-            },
-        };
-    };
-    const mutationOptions = (params) => {
-        const { id: _id, data: _data, claim: _claim, ...rest } = params;
-        // 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),
-            },
-            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);
-        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);
-        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),
-            },
-            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),
-        };
-        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),
-        };
-        // 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 = {
-        retrieve(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 operations = {
-        local,
-        retrieve: guard(async (params) => {
-            // Read-interest enrolment: reading a row enters its entity scope, so a
-            // client lands in the same group the holder's claim presence fans out
-            // on and `claim.state`/`claim.queue` report peers. Best-effort and
-            // fire-and-forget — it never makes the read reject or run slower.
-            void collaboration?.enterScope?.({ [schemaKey]: params.id });
-            const rows = await load({
-                ...params,
-                where: [['id', params.id]],
-                limit: 1,
-            });
-            return rows[0];
-        }),
-        // 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),
-                    },
-                    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;
-}