@abloatai/ablo 0.25.0 → 0.27.0

package/dist/client/Ablo.js

@@ -1,11 +1,11 @@
 /**
- * Ablo — The one-liner consumer API.
- *
- * Hides all internal wiring (ObjectPool, Database, SyncClient, WebSocket,
- * bootstrap, offline queue, DI adapters) behind a single function call.
+ * `Ablo` — the one-call entry point to the sync engine client. It hides the
+ * internal wiring — the object pool, local database, sync client, WebSocket,
+ * bootstrap, and offline queue — behind a single function that returns a typed
+ * client with one property per model in your schema.
  *
  * Usage:
- *   import { Ablo } from '@abloatai/ablo/client';
+ *   import { Ablo } from '@abloatai/ablo';
  *   import { schema } from './schema';
  *
  *   const sync = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
@@ -18,21 +18,18 @@
  *   });
  *   await sync.reports.delete({ id: reportId });
  */
-import { z } from 'zod';
-import { baseFieldsSchema } from '../schema/schema.js';
-import { schemaHash } from '../schema/serialize.js';
-import { AbloError, AbloAuthenticationError, AbloConnectionError, AbloValidationError, AbloNotFoundError, translateHttpError, toAbloError, claimedError } from '../errors.js';
+import { AbloAuthenticationError, AbloConnectionError, AbloValidationError, AbloNotFoundError, translateHttpError, toAbloError, claimedError } from '../errors.js';
 import { descriptionFromMeta } from '../coordination/schema.js';
-import { LoadStrategy, PropertyType } from '../types/index.js';
 import { initSyncEngine } from '../context.js';
 import { noopObservability, browserOnlineStatus, defaultSessionErrorDetector, noopAnalytics, } from '../SyncEngineContext.js';
 import { alwaysOnline } from '../adapters/alwaysOnline.js';
 import { validateAbloOptions } from './validateAbloOptions.js';
+import { InstanceCache } from '../InstanceCache.js';
+import {} from '../auth/index.js';
 import { mintSession } from './sessionMint.js';
 import { createAuthCredentialSource } from '../auth/credentialSource.js';
 import { createInternalComponents } from './createInternalComponents.js';
 import { resolveParticipantIdentity } from './identity.js';
-import { Model } from '../Model.js';
 import { BaseSyncedStore } from '../BaseSyncedStore.js';
 import { createPresenceStream } from '../sync/createPresenceStream.js';
 import { createClaimStream } from '../sync/createClaimStream.js';
@@ -41,688 +38,35 @@ import { createSnapshot } from '../sync/createSnapshot.js';
 import { reconcileFunctionalUpdate } from './functionalUpdate.js';
 import { createParticipantManager } from '../sync/participants.js';
 import { createProtocolClient, } from './ApiClient.js';
-// Value import is cycle-safe: httpClient.js only value-imports ApiClient.js,
-// which imports this module type-only.
+// Value import is cycle-safe: httpClient.js and ApiClient.js take the client
+// types from the `options`/`resourceTypes` leaves, never from this module.
 import { createAbloHttpClient, } from './httpClient.js';
 import { assertBrowserSafety, readProcessEnv, resolveApiKey, resolveApiKeyValue, resolveAuthToken, resolveBaseURL, resolveBootstrapBaseUrl, resolveDatabaseUrl, warnIfCliKeyMismatch, warnIfDatabaseUrlEnvIgnored, warnIfDatabaseUrlDeprecated, } from './auth.js';
 import { registerDataSource } from './registerDataSource.js';
-import { shouldUseInMemoryPersistence, } from './persistence.js';
+import { shouldUseInMemoryPersistence } from './persistence.js';
+import { deriveConfigFromSchema } from './schemaConfig.js';
+import { registerModelsFromSchema } from './modelRegistration.js';
+import { createConsoleLogger, resolveLogLevel } from './consoleLogger.js';
+import { createDefaultMutationExecutor } from './wsMutationExecutor.js';
+export { computeFKDepthPriority } from './schemaConfig.js';
 import { createModelProxy } from './createModelProxy.js';
 import { assertWriteOptions } from './writeOptionsSchema.js';
-// ── Config derivation from schema ─────────────────────────────────────────
-/**
- * Compute a create-priority map from schema `belongsTo` relations using
- * Tarjan's strongly-connected-components algorithm.
- *
- * The FK graph has an edge `child → parent` for every `belongsTo`. Tarjan
- * runs a single linear DFS that simultaneously (a) detects cycles by
- * grouping mutually-reachable nodes into SCCs and (b) emits those SCCs
- * in reverse topological order of the condensation graph. In this edge
- * convention a "sink" SCC has no outgoing edges — i.e. no parents — so
- * it is an *FK root* (`organizations`, `themes`, etc.). Tarjan emits
- * roots first and leaves last, exactly the order in which rows must be
- * inserted to satisfy FK constraints.
- *
- * Priorities are assigned by emit order: SCC #0 → 10, SCC #1 → 20, …
- * Members of the same SCC share a priority, so insertion order wins the
- * tiebreak inside a cycle (this matters for cyclic schemas like
- * `slideDecks ↔ layouts`, where one direction is the user's chosen
- * "soft" edge — only the consumer's mutator sequence knows which one).
- *
- * This algorithm is iteration-order-independent: starting the DFS from
- * any node yields the same SCC partitioning, and SCCs always come out
- * in valid topological order. The previous DFS-with-memoization
- * heuristic broke under cycles by treating the back-edge as depth 0,
- * which made priorities depend on which node the walk happened to
- * enter the cycle at.
- *
- * Schema authors can mark one side of a cycle with
- * `belongsTo(target, fk, { defer: true })`. Those edges are excluded
- * from the dependency graph entirely, which deterministically breaks
- * the cycle and turns the SCC into a chain — the marked child gets a
- * strictly higher priority than its parent instead of being tied with
- * it. Pair with a Postgres `DEFERRABLE INITIALLY DEFERRED` constraint
- * if you want the database side of the cycle to also relax. See
- * {@link BelongsToOptions.defer}.
- *
- * The returned map is keyed by {@link ModelDef.typename} (falling back
- * to the schema key), because that is what `Model.getModelName()`
- * returns at transaction time — keying by schema key would silently
- * miss the lookup and every model would fall through to
- * `defaultCreatePriority`.
- *
- * Reference: Tarjan, R. (1972), "Depth-first search and linear graph
- * algorithms." Linear in V + E.
- */
-export function computeFKDepthPriority(schema) {
-    // schemaKey → typename (wire name used at transaction time)
-    const keyToTypename = new Map();
-    for (const [key, def] of Object.entries(schema.models)) {
-        keyToTypename.set(key, def.typename ?? key);
-    }
-    // Adjacency: schemaKey → parent schema keys pulled from `belongsTo`.
-    // Parents not in the schema (e.g. external types) are dropped so the
-    // graph stays closed. Edges marked `{ defer: true }` are also
-    // dropped — the schema author has declared this side of a cycle to
-    // be the "soft" one (insert with null FK, patch later), so the
-    // dependency-graph walker treats it as if the edge weren't there.
-    // That breaks the cycle deterministically and lets the other side
-    // become a strict topological predecessor.
-    const parentsOf = new Map();
-    for (const [key, def] of Object.entries(schema.models)) {
-        const out = [];
-        for (const rel of Object.values(def.relations)) {
-            if (rel.type !== 'belongsTo')
-                continue;
-            if (!keyToTypename.has(rel.target))
-                continue;
-            if (rel.options?.defer === true)
-                continue;
-            out.push(rel.target);
-        }
-        parentsOf.set(key, out);
-    }
-    // Tarjan SCC bookkeeping
-    const dfsIndex = new Map();
-    const lowlink = new Map();
-    const onStack = new Set();
-    const stack = [];
-    const sccs = [];
-    let counter = 0;
-    function strongconnect(v) {
-        dfsIndex.set(v, counter);
-        lowlink.set(v, counter);
-        counter++;
-        stack.push(v);
-        onStack.add(v);
-        for (const w of parentsOf.get(v) ?? []) {
-            if (!dfsIndex.has(w)) {
-                strongconnect(w);
-                lowlink.set(v, Math.min(lowlink.get(v), lowlink.get(w)));
-            }
-            else if (onStack.has(w)) {
-                // Back-edge into the active DFS path — w is in the same SCC as v.
-                lowlink.set(v, Math.min(lowlink.get(v), dfsIndex.get(w)));
-            }
-        }
-        // v is the root of an SCC: pop everything down to v inclusive.
-        if (lowlink.get(v) === dfsIndex.get(v)) {
-            const component = [];
-            let w;
-            do {
-                w = stack.pop();
-                onStack.delete(w);
-                component.push(w);
-            } while (w !== v);
-            sccs.push(component);
-        }
-    }
-    for (const key of keyToTypename.keys()) {
-        if (!dfsIndex.has(key))
-            strongconnect(key);
-    }
-    // Tarjan emits SCCs in reverse topological order of the condensation.
-    // In our edge convention (child→parent), reverse-topo of the
-    // condensation means root-SCCs (no outgoing edges = no parents)
-    // first, leaf-SCCs (deepest descendants) last. We could just use
-    // emit-order as the priority — but that gives independent sibling
-    // SCCs different priorities, which is semantically wrong: siblings
-    // don't depend on each other and shouldn't be ordered relative to
-    // each other.
-    //
-    // Instead, do one more pass to compute *longest-path depth* on the
-    // condensation DAG: depth(SCC) = max(depth(parent SCC)) + 1, or 0
-    // for SCCs with no in-schema parents. SCCs at the same depth get
-    // the same priority — siblings stay tied, insertion order in the
-    // queue breaks the tie. Priority = (depth + 1) * 10.
-    //
-    // We can compute this in a single pass over the SCCs because
-    // Tarjan's emit-order *is* a valid topological order of the
-    // condensation: when we process sccs[i], every parent SCC has
-    // already been assigned a depth.
-    const nodeToSccIdx = new Map();
-    sccs.forEach((scc, i) => {
-        for (const node of scc)
-            nodeToSccIdx.set(node, i);
-    });
-    const sccDepth = new Map();
-    sccs.forEach((scc, i) => {
-        let maxParentDepth = -1;
-        for (const node of scc) {
-            for (const parent of parentsOf.get(node) ?? []) {
-                const parentSccIdx = nodeToSccIdx.get(parent);
-                if (parentSccIdx === undefined)
-                    continue;
-                if (parentSccIdx === i)
-                    continue; // intra-SCC edge — not a dep
-                const d = sccDepth.get(parentSccIdx);
-                if (d !== undefined && d > maxParentDepth)
-                    maxParentDepth = d;
-            }
-        }
-        sccDepth.set(i, maxParentDepth + 1);
-    });
-    const out = new Map();
-    sccs.forEach((scc, i) => {
-        const priority = (sccDepth.get(i) + 1) * 10;
-        for (const key of scc) {
-            out.set(keyToTypename.get(key), priority);
-        }
-    });
-    return out;
-}
-function deriveConfigFromSchema(schema) {
-    // Commit payload projection is done directly inside `TransactionQueue`
-    // — see `projectCommitPayload` there. Each model's field metadata
-    // rides on `ModelRegistry` (populated by `registerModelsFromSchema`),
-    // so there's no config-layer shim: the queue asks the registry for
-    // the declared fields and serializes accordingly.
-    return {
-        modelCreatePriority: computeFKDepthPriority(schema),
-        defaultCreatePriority: 40,
-        defaultNonCreatePriority: 50,
-        essentialFields: {},
-        classNameFallbackMap: {},
-        // Hash this client's schema once so bootstrap can detect drift against the
-        // server's active hash (same `schemaHash` the CLI push + server compute).
-        expectedSchemaHash: schemaHash(schema),
-    };
-}
-// ── Auto model registration from schema ───────────────────────────────────
-function registerModelsFromSchema(schema, registry) {
-    registry.startBatch();
-    for (const [schemaKey, modelDef] of Object.entries(schema.models)) {
-        // Use typename as the model name — this is the wire-format name that
-        // the server sends in bootstrap responses and sync deltas. The pool's
-        // typeIndex, the ModelRegistry, and getModelName() all use this name.
-        // Schema key (camelCase plural) is only for the consumer-facing proxy API.
-        const modelName = modelDef.typename ?? schemaKey;
-        // Collect JSON sub-property fields to generate ${field}Json getters
-        const jsonSubFields = [];
-        for (const [fieldName, zodType] of Object.entries(modelDef.shape)) {
-            const inner = unwrapZodType(zodType);
-            if (isZodObject(inner)) {
-                jsonSubFields.push({ fieldName, subSchema: inner });
-            }
-        }
-        // Create a dynamic Model subclass with JSON sub-property getters.
-        //
-        // Field-level MobX observability is ON BY DEFAULT. A reactive read like
-        // `useAblo((a) => a.documents.get(id))` must re-render when a remote delta
-        // mutates the row IN PLACE (the common collaborative case); without
-        // per-field observability that update fires no reaction and the UI silently
-        // goes stale. Models opt OUT with an explicit `lazyObservable: false` —
-        // appropriate only for very large read-only list models where per-field
-        // atoms cost more than the QueryView's entry-replaced reactivity already
-        // provides. json fields register as `observable.ref` (see
-        // `registerModelsFromSchema`), so the default is ~one atom per scalar field
-        // per loaded row — cheap — not a deep atom tree per blob.
-        const isLazy = modelDef.lazyObservable !== false;
-        // Base provenance fields (`organizationId`, `createdBy`) live in
-        // `baseFieldsSchema`, not the per-model `shape`. The server stamps + emits
-        // them (camelCased on the wire), but hydration (`Model.assignFieldsFromData`)
-        // only assigns keys that already exist as an own/prototype property — so
-        // without a slot here, `deck.createdBy` / `deck.organizationId` silently read
-        // `undefined` (this is why the profile decks tab showed nothing: it filters
-        // `decks.filter(d => d.createdBy === userId)`). `id`/`createdAt`/`updatedAt`
-        // are already seeded by the base Model constructor, so they're excluded.
-        const fieldNames = [
-            ...Object.keys(modelDef.shape),
-            ...Object.keys(baseFieldsSchema.shape).filter((f) => f !== 'id' && f !== 'createdAt' && f !== 'updatedAt' && !(f in modelDef.shape)),
-        ];
-        const computed = modelDef.computed;
-        const DynamicModel = createDynamicModelClass(modelName, jsonSubFields, fieldNames, computed, isLazy);
-        // Respect the schema's load strategy so lazy models skip IDB hydration + bootstrap
-        const loadStrategy = modelDef.load === 'lazy' || modelDef.load === 'manual'
-            ? LoadStrategy.lazy
-            : LoadStrategy.instant;
-        registry.registerModel(modelName, DynamicModel, {
-            loadStrategy,
-            fields: modelDef.fields,
-            autoFill: modelDef.autoFill,
-            requiredFields: modelDef.requiredFields,
-        });
-        // Collect the set of fields that should get an IDB secondary index.
-        //
-        // Matches Linear's opt-in model (see wzhudev/reverse-linear-sync-engine):
-        // `@Reference(..., { indexed: true })`. Only `belongsTo` relations that
-        // explicitly set `{ index: true }` in their options get an IDB secondary
-        // index. Every other FK (and every scalar) is resolved via in-memory
-        // ObjectPool scans, which are fast enough at org-scope sizes (~10k rows)
-        // and reactive via MobX.
-        //
-        // Auto-indexing every belongsTo was wrong: it bloated write amplification
-        // for the vast majority of FKs that are never queried by fk. Indexing
-        // every scalar (like the legacy Go backend did) is even worse.
-        const indexedFields = new Set();
-        for (const relDef of Object.values(modelDef.relations)) {
-            if (relDef.type === 'belongsTo' && relDef.foreignKey && relDef.options?.index === true) {
-                indexedFields.add(relDef.foreignKey);
-            }
-        }
-        // Register fields as properties (from Zod shape).
-        for (const [fieldName, rawZodType] of Object.entries(modelDef.shape)) {
-            const zodType = rawZodType;
-            const isOptional = zodType.isOptional?.() ?? false;
-            // A field is indexed if it's the FK of a `belongsTo({ index: true })`
-            // relation. Legacy `description === 'indexed'` still works for
-            // consumers using `field.*().indexed()`.
-            const isIndexed = indexedFields.has(fieldName) || zodType.description === 'indexed';
-            // JSON-typed fields (per the schema's wire-type tag) are opaque
-            // blobs from MobX's perspective — chart specs, ProseMirror docs,
-            // style maps. Deep observability on them recursively walks every
-            // nested property and creates an atom for each leaf, producing a
-            // microtask storm on every commit/streaming update. `ref` tracks
-            // only reassignment, which is how blob consumers actually use them.
-            const wireType = modelDef.fields?.[fieldName]?.type;
-            const observability = wireType === 'json' ? 'ref' : undefined;
-            registry.registerProperty(modelName, fieldName, {
-                type: PropertyType.property,
-                indexed: isIndexed,
-                optional: isOptional,
-                observability,
-            });
-        }
-        // Register relations
-        for (const [relName, relDef] of Object.entries(modelDef.relations)) {
-            if (relDef.type === 'belongsTo') {
-                registry.registerReference(modelName, relName, {
-                    referencedModel: () => {
-                        const targetModel = registry.getModelByName(relDef.target);
-                        return targetModel ?? DynamicModel;
-                    },
-                    indexed: true,
-                });
-            }
-            else if (relDef.type === 'hasMany') {
-                // Generate a getter on the parent model that returns all children
-                // matching the FK via Model.getStore().getByForeignKey(). The FK
-                // index on the target model is registered by deriveSyncPlanFromSchema.
-                const targetName = relDef.target;
-                const foreignKey = relDef.foreignKey;
-                const orderByField = relDef._orderBy;
-                // Resolve the target typename from the schema (might differ from the key)
-                const targetDef = schema.models[targetName];
-                const targetTypename = targetDef?.typename ?? targetName;
-                Object.defineProperty(DynamicModel.prototype, relName, {
-                    get() {
-                        const store = Model.getStore();
-                        if (!store)
-                            return [];
-                        const results = store.getByForeignKey(targetTypename, foreignKey, this.id);
-                        if (orderByField && results.length > 1) {
-                            return [...results].sort((a, b) => {
-                                // `orderByField` is a runtime string from the schema's
-                                // hasMany({ orderBy }) — Models have dynamic typed
-                                // fields produced by createDynamicModelClass, so the
-                                // static type doesn't carry an index signature for
-                                // arbitrary field reads. `Reflect.get` is the typed
-                                // bridge — returns `unknown`, narrowed below.
-                                const va = Reflect.get(a, orderByField);
-                                const vb = Reflect.get(b, orderByField);
-                                if (typeof va === 'number' && typeof vb === 'number')
-                                    return va - vb;
-                                if (typeof va === 'string' && typeof vb === 'string')
-                                    return va.localeCompare(vb);
-                                return 0;
-                            });
-                        }
-                        return results;
-                    },
-                    enumerable: true,
-                    configurable: true,
-                });
-            }
-        }
-    }
-    registry.endBatch();
-}
-// ── JSON sub-property helpers ─────────────────────────────────────────────
-/**
- * Unwrap a Zod schema through .optional(), .nullable(), .default(),
- * .readonly() to find the innermost type. Needed to detect whether a
- * field.json() call wraps a ZodObject (has sub-properties) or a plain
- * type (ZodUnknown, ZodArray, etc.).
- *
- * Uses Zod's public `.unwrap()` API per wrapper type — no `_def`
- * digging. Bounded loop guards against pathological self-referential
- * wrappers.
- */
-function unwrapZodType(schema) {
-    let current = schema;
-    for (let i = 0; i < 10; i++) {
-        if (current instanceof z.ZodOptional) {
-            current = current.unwrap();
-            continue;
-        }
-        if (current instanceof z.ZodNullable) {
-            current = current.unwrap();
-            continue;
-        }
-        if (current instanceof z.ZodDefault) {
-            // v4 deprecates removeDefault in favor of unwrap, but the
-            // installed @types declarations only expose removeDefault on
-            // ZodDefault. Use it — it's the same runtime function.
-            current = current.unwrap();
-            continue;
-        }
-        if (current instanceof z.ZodReadonly) {
-            current = current.unwrap();
-            continue;
-        }
-        break;
-    }
-    return current;
-}
-/** Type guard: is this a ZodObject with a .shape property? */
-function isZodObject(schema) {
-    return schema instanceof z.ZodObject;
-}
-/** Create a Model subclass for a schema-defined model */
-function createDynamicModelClass(modelName, jsonSubFields, fieldNames, computed, lazyObservable = false) {
-    const ModelClass = class extends Model {
-        _modelName = modelName;
-        constructor(data) {
-            super(data);
-            // Gate `propertyChanged`-via-`observe` tracking during initial
-            // hydration. M1 installs a MobX `observe()` listener per schema
-            // property that forwards writes to `propertyChanged()` so direct
-            // assignments like `layer.position = newPos` still round-trip
-            // through the transaction queue. During construction we're writing
-            // wire data, NOT user edits — flagging this as "constructing" lets
-            // the listener early-return on those writes so `modifiedProperties`
-            // doesn't get polluted with every field of every hydrated model.
-            //
-            // The listener is installed by `makeObservable()` below (inside
-            // M1), so writes that happen BEFORE that line won't fire it; this
-            // flag is defensive in case a subclass or call path reorders the
-            // steps later.
-            this._isConstructing = true;
-            // MobX 6 requires fields to exist as own properties BEFORE makeObservable().
-            // Model base only sets id/createdAt/updatedAt. Schema fields (title, userId, etc.)
-            // must be initialized here so M1's annotations can find them.
-            for (const field of fieldNames) {
-                if (!(field in this)) {
-                    this[field] = data?.[field] ?? undefined;
-                }
-            }
-            // Per-field MobX observability opt-in via `lazyObservable: true` on
-            // the model definition. Defaults to plain objects — reactivity comes
-            // from the QueryView "entry replaced" pattern, which is cheap for
-            // read-only list UIs but invisible to in-place field mutations.
-            //
-            // Multiplayer editors need live field-level reactivity so remote
-            // deltas AND local drag/resize/rename mutations surface through
-            // `observer()` components without the whole pool entry being
-            // replaced. Without observability, `layer.position.x = 500` emits
-            // nothing and the UI lags until some unrelated state change triggers
-            // a pass (toolbar close, deselect).
-            //
-            // Delegates to `Model.makeObservable()` (the inherited method) so
-            // MobX annotations are derived from the same registry that M1 reads.
-            // That means computed getters, reference collections, custom
-            // getters/setters, and property-change tracking all integrate
-            // correctly — reimplementing `makeObservable` inline here would miss
-            // those seams.
-            if (lazyObservable) {
-                this.makeObservable();
-            }
-            this._isConstructing = false;
-        }
-        getModelName() {
-            return this._modelName;
-        }
-    };
-    // Generate ${field}Json getters for JSON fields with sub-properties.
-    //
-    // The getter reads the raw JSON string from the instance (set via
-    // updateFromData), parses it, applies Zod defaults, and caches by
-    // raw value. This replaces the hand-coded metadataObject + sub-property
-    // getter pattern that 11+ Ablo models currently repeat.
-    //
-    // Example: field named 'metadata' with sub-schema { icon: z.string().default('presentation') }
-    // → model.metadataJson returns { icon: 'presentation', ... } (typed, cached)
-    for (const { fieldName, subSchema } of jsonSubFields) {
-        const getterName = `${fieldName}Json`;
-        const cacheKey = `__${fieldName}JsonCache`;
-        Object.defineProperty(ModelClass.prototype, getterName, {
-            get() {
-                const raw = this[fieldName];
-                // Cache check: same raw value → same parsed result
-                const cache = this[cacheKey];
-                if (cache && cache.raw === raw)
-                    return cache.parsed;
-                // Parse: handle string (from DB/wire), object (already parsed), null/undefined
-                let input;
-                try {
-                    if (typeof raw === 'string') {
-                        input = JSON.parse(raw);
-                    }
-                    else if (raw && typeof raw === 'object') {
-                        input = raw;
-                    }
-                    else {
-                        input = {};
-                    }
-                }
-                catch {
-                    input = {};
-                }
-                // Apply Zod parse for type coercion + defaults. safeParse so
-                // malformed metadata doesn't crash — falls back to all defaults.
-                const result = subSchema.safeParse(input);
-                const parsed = result.success ? result.data : subSchema.safeParse({}).data ?? {};
-                this[cacheKey] = { raw, parsed };
-                return parsed;
-            },
-            enumerable: true,
-            configurable: true,
-        });
-    }
-    // Install schema-declared computed getters on the prototype.
-    // Each getter receives `this` (the model instance) and returns the computed value.
-    if (computed) {
-        for (const [name, fn] of Object.entries(computed)) {
-            Object.defineProperty(ModelClass.prototype, name, {
-                get() {
-                    return fn(this);
-                },
-                enumerable: true,
-                configurable: true,
-            });
-        }
-    }
-    return ModelClass;
-}
-const LOG_LEVEL_RANK = { debug: 10, info: 20, warn: 30, error: 40, silent: 99 };
-/**
- * Resolve the effective level. Precedence: explicit `logLevel` option →
- * `debug: true` (⇒ debug) → `ABLO_LOG_LEVEL` env → default `warn`. `debug: false`
- * / omitted just means "don't raise the level" — it falls through to env/default
- * rather than force-silencing an ops-set env override.
- */
-function resolveLogLevel(opts) {
-    if (opts?.logLevel && opts.logLevel in LOG_LEVEL_RANK)
-        return opts.logLevel;
-    if (opts?.debug === true)
-        return 'debug';
-    // `globalThis.process` guard keeps this safe in browser/edge runtimes that
-    // have no `process` binding — there we fall through to the default.
-    const raw = globalThis.process?.env?.ABLO_LOG_LEVEL;
-    const normalized = raw?.toLowerCase();
-    if (normalized && normalized in LOG_LEVEL_RANK)
-        return normalized;
-    return 'warn';
-}
-/**
- * Build the default logger, gated at `level` and prefixed `[Ablo]` so a creator
- * with a console full of other tools' logs can see at a glance what's ours.
- */
-function createConsoleLogger(level) {
-    const threshold = LOG_LEVEL_RANK[level];
-    const emit = (lvl, fn, args) => {
-        if (typeof console === 'undefined' || LOG_LEVEL_RANK[lvl] < threshold)
-            return;
-        fn('[Ablo]', ...args);
-    };
-    return {
-        debug: (...args) => emit('debug', console.debug, args),
-        info: (...args) => emit('info', console.info, args),
-        warn: (...args) => emit('warn', console.warn, args),
-        error: (...args) => emit('error', console.error, args),
-    };
-}
 // `readProcessEnv` lives in `./auth` alongside the other resolvers
 // that read it. Re-exported there for use elsewhere in the file.
-// ── Default mutation executor (wire: `commit` frame over WebSocket) ──────
-/**
- * Derive a stable `Idempotency-Key` from the batch's operation set.
- *
- * Retries of the same batch compute the same key — a reconnecting
- * client that rebuilds the identical mutations from its offline queue
- * sends the identical key, so the server's `mutation_log` replay path
- * returns the cached response instead of re-executing the mutators.
- *
- * Content-addressed: sort operations by (model, id, type) then sha256
- * the serialized form. Separator-safe — adjacent fields are delimited
- * by a character (`\x1e`, the ASCII record separator) that cannot
- * appear in a JSON string literal. Output length is 70 chars — safely
- * under Stripe's documented 255-char cap.
- *
- * Uses the Web Crypto API (cross-runtime: Node 20+ and browsers), same
- * primitive as the offline queue's AES-GCM encryption.
- *
- * @internal — exported as unexported file-local; callers go through
- * the executor's own `Idempotency-Key` plumbing.
- */
-async function deriveOperationsIdempotencyKey(operations) {
-    const normalized = [...operations]
-        .map((op) => ({
-        type: op.type,
-        model: op.model,
-        id: op.id,
-        input: op.input ?? null,
-    }))
-        .sort((a, b) => {
-        if (a.model !== b.model)
-            return a.model < b.model ? -1 : 1;
-        if (a.id !== b.id)
-            return a.id < b.id ? -1 : 1;
-        return a.type < b.type ? -1 : a.type > b.type ? 1 : 0;
-    });
-    const encoded = new TextEncoder().encode(JSON.stringify(normalized));
-    const digest = await crypto.subtle.digest('SHA-256', encoded);
-    const bytes = new Uint8Array(digest);
-    let hex = '';
-    for (let i = 0; i < bytes.length; i++) {
-        hex += bytes[i].toString(16).padStart(2, '0');
-    }
-    return `batch-${hex}`;
-}
-/**
- * Default mutation executor: sends `{ type: 'commit', payload: ... }` over
- * the sync engine's own WebSocket.
- *
- * Transport ownership follows the Zero / Liveblocks pattern — the engine
- * owns its socket end-to-end and the executor is internal. Apps pass URLs
- * and auth; they do NOT inject transport callbacks. That's why this
- * factory takes a `getWs` closure instead of a full SyncWebSocket: the WS
- * doesn't exist when the executor is constructed (it's created later in
- * `Ablo` during `BaseSyncedStore` init), so we resolve it
- * lazily at commit time. Same trick Zero uses internally — see
- * `packages/zero-client/src/client/zero.ts` where `Pusher`/`Puller` are
- * constructed before the socket then wired up at connect time.
- *
-     * `options.idempotencyKey` becomes the wire-level `clientTxId` when set,
-     * matching Stripe-style retry semantics. Otherwise the SDK generates one.
-     */
-function createDefaultMutationExecutor(getWs) {
-    async function commit(operations, options) {
-        const ws = getWs();
-        if (!ws?.sendCommit) {
-            throw new AbloConnectionError('SyncWebSocket not ready for commit. The engine must finish bootstrap ' +
-                'before mutations can be sent.', { code: 'ws_not_ready' });
-        }
-        const clientTxId = options?.idempotencyKey ??
-            (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function'
-                ? crypto.randomUUID()
-                : `tx_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`);
-        try {
-            return await ws.sendCommit(operations, clientTxId, undefined, // use sendCommit's built-in 15s default; no per-call override
-            options?.causedByTaskId, options?.reads);
-        }
-        catch (err) {
-            // Wrap transport-level failures as connection errors so the
-            // TransactionQueue's retry classifier treats them as transient
-            // (matches the old HTTP path's network-error handling).
-            if (err instanceof AbloError)
-                throw err;
-            if (err instanceof Error) {
-                if (/not connected|timed out|connection|ECONN/i.test(err.message)) {
-                    const wrapped = new AbloConnectionError(err.message, { cause: err });
-                    // Preserve any `diagnostics` snapshot the underlying SyncWebSocket
-                    // attached to the rejection. Without this, the wrapped error
-                    // bottoms out at "AbloConnectionError: not connected" with no
-                    // attribution to which close code / heartbeat trip / session
-                    // error caused it. See SyncWebSocket.notConnectedError().
-                    if (err &&
-                        typeof err === 'object' &&
-                        'diagnostics' in err &&
-                        err.diagnostics) {
-                        wrapped.diagnostics = err.diagnostics;
-                    }
-                    throw wrapped;
-                }
-            }
-            throw err;
-        }
-    }
-    return {
-        commit,
-        executeCreate: (model, id, input, _txId, options) => commit([{ type: 'CREATE', model: model.toLowerCase(), id, input }], options).then(() => { }),
-        executeUpdate: (model, id, data, _txId, options) => commit([{ type: 'UPDATE', model: model.toLowerCase(), id, input: data }], options),
-        executeDelete: (model, id, _txId, options) => commit([{ type: 'DELETE', model: model.toLowerCase(), id }], options).then(() => { }),
-        executeArchive: (model, id, _txId, options) => commit([{ type: 'ARCHIVE', model: model.toLowerCase(), id }], options).then(() => { }),
-        executeUnarchive: (model, id, _txId, options) => commit([{ type: 'UNARCHIVE', model: model.toLowerCase(), id }], options).then(() => { }),
-    };
-}
-// ── Default mutation dispatcher (for offline flush) ───────────────────────
-function createDefaultMutationDispatcher(executor) {
-    return {
-        async dispatch(opName, variables) {
-            const prefixes = ['Create', 'Update', 'Delete', 'Archive', 'Unarchive'];
-            for (const prefix of prefixes) {
-                if (opName.startsWith(prefix)) {
-                    const model = opName.slice(prefix.length);
-                    const v = variables;
-                    const input = (prefix === 'Create' || prefix === 'Update')
-                        ? v.input
-                        : undefined;
-                    await executor.commit([{
-                            type: prefix.toUpperCase(),
-                            model: model.toLowerCase(),
-                            id: v.id ?? '',
-                            input,
-                        }]);
-                    return;
-                }
-            }
-        },
-    };
-}
 // ── Auth normalization ─────────────────────────────────────────────────────
 /**
- * The one resolver the credential lifecycle needs: an async `() => token | null`,
- * or `null` when auth is static (a plain long-lived `apiKey` STRING with no
- * refresh — the common case).
+ * The single resolver the credential lifecycle needs: an async
+ * `() => token | null`, or `null` when auth is static — a plain long-lived
+ * `apiKey` string with no refresh, which is the common case.
  *
- * The short-lived per-user browser path passes a FUNCTION `apiKey` (an
- * `ApiKeySetter`): the SDK then drives the full credential lifecycle off it —
- * mint-before-connect, the proactive refresh timer + wake/online/focus re-mint,
- * and the reactive `credential_stale` re-mint. The resolver's contract is the
- * `ApiKeySetter` contract end-to-end: resolve a token, resolve `null` when the
- * login is gone (terminal → `session_expired` → sign out), or THROW on a
- * transient failure (→ back off, never sign out).
+ * The short-lived per-user browser path passes a function `apiKey` (an
+ * {@link ApiKeySetter}), and the SDK then drives the whole credential lifecycle
+ * from it: mint-before-connect, the proactive refresh timer with its
+ * wake/online/focus re-mint, and the reactive `credential_stale` re-mint. The
+ * resolver follows the `ApiKeySetter` contract end to end: resolve a token,
+ * resolve `null` when the login is gone (terminal — surfaces `session_expired`
+ * and signs the user out), or throw on a transient failure (backs off, without
+ * signing out).
  */
 function resolveCredentialResolver(apiKey) {
     if (typeof apiKey === 'function')
@@ -743,12 +87,14 @@ export function Ablo(options) {
     const authInput = { options, env };
     const configuredApiKey = resolveApiKey(authInput);
     const configuredAuthToken = resolveAuthToken(authInput);
-    // The client OWNS its credential lifecycle (not the React layer): this resolver
-    // drives both the reactive re-mint (FSM `credential_stale`) and the proactive
-    // refresh timer + wake/online/focus triggers. Null for the common static
-    // `apiKey` path — no refresh needed.
+    // The client owns its credential lifecycle (not the React layer): this resolver
+    // drives both the reactive re-mint (the connection's `credential_stale` state)
+    // and the proactive refresh timer with its wake/online/focus triggers. Null for
+    // the common static `apiKey` path, which needs no refresh.
     const credentialResolver = resolveCredentialResolver(configuredApiKey);
-    const authCredentials = createAuthCredentialSource(internalOptions.capabilityToken ?? configuredAuthToken);
+    const authCredentials = createAuthCredentialSource(
+    // eslint-disable-next-line @typescript-eslint/no-deprecated -- load-bearing on the self-hosted path; server-internal cap-mint (Phase 3) not shipped
+    internalOptions.capabilityToken ?? configuredAuthToken);
     const configuredDatabaseUrl = resolveDatabaseUrl(authInput);
     assertBrowserSafety({
         apiKey: configuredApiKey,
@@ -761,9 +107,9 @@ export function Ablo(options) {
         createConsoleLogger(resolveLogLevel({ debug: options.debug, logLevel: options.logLevel }));
     // Nudge (once) if a stray DATABASE_URL is in the env but `databaseUrl` wasn't
     // passed — the env value is no longer auto-adopted (see resolveDatabaseUrl).
-    warnIfDatabaseUrlEnvIgnored(authInput, (m) => logger.warn(m));
-    warnIfDatabaseUrlDeprecated(authInput, (m) => logger.warn(m));
-    void warnIfCliKeyMismatch(authInput, (m) => logger.warn(m));
+    warnIfDatabaseUrlEnvIgnored(authInput, (m) => { logger.warn(m); });
+    warnIfDatabaseUrlDeprecated(authInput, (m) => { logger.warn(m); });
+    void warnIfCliKeyMismatch(authInput, (m) => { logger.warn(m); });
     const schema = options.schema;
     const url = resolveBaseURL(authInput);
     // 1. Derive config from schema
@@ -773,24 +119,19 @@ export function Ablo(options) {
         ...deriveConfigFromSchema(schema),
         ...internalOptions.configOverrides,
     };
-    // 2. Create the mutation executor + dispatcher.
+    // 2. Create the mutation executor and dispatcher.
     //
-    //    The default executor sends `{ type: 'commit', ... }` over the
-    //    engine's WebSocket. The WS doesn't exist yet at this point (it's
-    //    created later when `BaseSyncedStore` initializes), so the default
-    //    takes a lazy getter that resolves the live WS at commit time.
-    //    `storeForTransport` is captured by the closure and assigned below
-    //    once the store is built — JS closures close over bindings, not
-    //    values, so by the time the first commit fires the store is live.
+    //    The default executor sends `{ type: 'commit', ... }` over the engine's
+    //    WebSocket. The socket doesn't exist yet at this point (it's created later
+    //    when the store initializes), so the default takes a lazy getter that
+    //    resolves the live socket at commit time. `storeHolder` is captured by the
+    //    closure and assigned below once the store is built — JS closures close
+    //    over bindings, not values, so by the time the first commit fires the store
+    //    is live.
     //
-    //    Caller-supplied executors are still honored for advanced cases
-    //    (test mocks, alternative transports) but the public `<AbloProvider>`
-    //    surface will mark this option `@internal` — apps should almost
-    //    never need to override transport. See Zero's `ClientOptions`
-    //    (packages/zero-client/src/client/options.ts) and Liveblocks'
-    //    `ClientOptions` (packages/liveblocks-core/src/client.ts) for the
-    //    reference shape: URLs + auth + declarative mutators, never a
-    //    pluggable commit transport.
+    //    Caller-supplied executors are still honored for advanced cases (test
+    //    mocks, alternative transports), but apps should almost never need to
+    //    override the transport.
     // Captured-by-reference binding — assigned below after BaseSyncedStore
     // is constructed. The default executor's `getWs` closure reads it
     // lazily at commit time.
@@ -802,7 +143,6 @@ export function Ablo(options) {
             const ws = storeHolder.store?.getSyncWebSocket() ?? null;
             return ws;
         });
-    const dispatcher = internalOptions.mutationDispatcher ?? createDefaultMutationDispatcher(executor);
     // 3. Initialize SDK context (one call — hides all DI wiring).
     //    Each provider can be overridden individually; the noop defaults
     //    are preserved for the zero-config consumer path.
@@ -817,15 +157,13 @@ export function Ablo(options) {
                 : browserOnlineStatus),
         config,
         mutationExecutor: executor,
-        mutationDispatcher: dispatcher,
     });
     // 4. Create internal components (user never sees these). See
     //    `./createInternalComponents.ts` for the construction order
     //    and what each component does. Model registration happens
-    //    here because `registerModelsFromSchema` lives in this file —
-    //    the schema-to-Model-class translation depends on private
-    //    helpers (`createDynamicModelClass`, `unwrapZodType`, etc.)
-    //    that aren't worth pulling into the components module.
+    //    here (via `registerModelsFromSchema`, in `./modelRegistration.ts`)
+    //    because the schema-to-Model-class translation is client-construction
+    //    wiring that isn't worth pulling into the components module.
     const { modelRegistry, objectPool, bootstrapHelper, database, syncClient, hydration, } = createInternalComponents({
         schema,
         url,
@@ -853,25 +191,46 @@ export function Ablo(options) {
     });
     // Hand the credential lifecycle to the client (refresher + proactive refresh
     // timer + wake/online/focus re-mint). Installed once here so refresh works for
-    // ANY consumer of `Ablo({ auth })` — not only those who render `<AbloProvider>`.
+    // any consumer of `Ablo({ auth })`, not only those who render `<AbloProvider>`.
     // The first mint happens in `ready()` so the first connection carries a token.
+    //
+    // Long-lived server clients also get the pre-roll timer on windowless hosts
+    // (`proactiveInNode`): their socket must renew its `rk_` or `ek_` before the
+    // server's keepalive reaper closes it (4001 `credential_expired`). Two signals
+    // qualify — an agent or system participant, and an absolute endpoint-string
+    // `apiKey` (a relative one can't be fetched in Node, so an absolute URL is
+    // unambiguously a deliberate server client). User-kind clients in Node (an
+    // SSR/RSC module evaluating scaffolded browser code) stay reactive-only.
     if (credentialResolver) {
-        store.startCredentialLifecycle(credentialResolver);
+        const rawEndpoint = internalOptions.authEndpoint ?? internalOptions.apiKey;
+        const absoluteEndpoint = typeof rawEndpoint === 'string' && /^https?:\/\//i.test(rawEndpoint);
+        store.startCredentialLifecycle(credentialResolver, {
+            /* eslint-disable @typescript-eslint/no-deprecated -- `kind` gates the self-hosted proactive pre-roll; hosted path derives it from the apiKey scope */
+            proactiveInNode: internalOptions.kind === 'agent' ||
+                internalOptions.kind === 'system' ||
+                absoluteEndpoint,
+            /* eslint-enable @typescript-eslint/no-deprecated */
+        });
     }
+    // Put the lazy-query lane on the same auth-recovery path as the WebSocket probe
+    // and the proactive pre-roll: a 401 on `/sync/query` re-mints via the store's
+    // single-flight lifecycle and replays once, instead of silently returning empty
+    // rows against an expired `ek_` until the next proactive tick. Late-bound
+    // because the coordinator is constructed before the store exists.
+    hydration.setCredentialRecovery((recovery) => store.recoverFromAuthRejection(recovery));
     // Wire the store back into the default executor's lazy getter (see
     // `storeHolder` above). The executor was constructed before the store
     // existed; this late binding closes the loop so commits dispatch over
     // the engine's WebSocket once it opens.
     storeHolder.store = store;
-    // Bind THIS executor to THIS Ablo's TransactionQueue. Without this,
-    // the queue resolves `mutationExecutor` from the module-level
-    // `getContext()`, which `initSyncEngine()` overwrites on every Ablo
-    // construction. In multi-Ablo flows (e.g. agent-worker's worker +
-    // per-job peer) the second `initSyncEngine()` call would silently
-    // redirect the first Ablo's queue through the second Ablo's executor
-    // closure — and when the second Ablo disposes, its `storeHolder.store`
-    // becomes null, so the first Ablo's commits start throwing
-    // `ws_not_ready` forever (terminal AgentJob writes hang on retry).
+    // Bind this executor to this client's TransactionQueue. Without it, the queue
+    // resolves `mutationExecutor` from the module-level `getContext()`, which
+    // `initSyncEngine()` overwrites on every client construction. In multi-client
+    // flows (for example a worker plus a per-job peer) the second `initSyncEngine()`
+    // call would silently redirect the first client's queue through the second
+    // client's executor closure — and when the second client disposes, its
+    // `storeHolder.store` becomes null, so the first client's commits start throwing
+    // `ws_not_ready` forever.
     syncClient.getTransactionQueue().setMutationExecutor(executor);
     // Presence + claim streams — built eagerly so `engine.presence`
     // and `engine.claims` return the same reference for the engine's
@@ -883,10 +242,13 @@ export function Ablo(options) {
     // The server stamps `isAgent` on outbound presence frames from the
     // connection's authenticated identity prefix, but the local `self`
     // entry uses the kind we know at construction.
-    const participantId = (internalOptions.kind === 'agent' ? internalOptions.agentId : internalOptions.user?.id) ?? '';
+    const participantId = 
+    // eslint-disable-next-line @typescript-eslint/no-deprecated -- self-hosted identity fallback; hosted path derives identity from the apiKey scope
+    (internalOptions.kind === 'agent' ? internalOptions.agentId : internalOptions.user?.id) ?? '';
     const presenceStream = createPresenceStream({
         participantId,
         syncGroups: internalOptions.syncGroups ?? [],
+        // eslint-disable-next-line @typescript-eslint/no-deprecated -- local self-entry kind; server re-stamps isAgent from the authenticated identity
         isAgent: internalOptions.kind === 'agent',
     });
     const claimStream = createClaimStream({ participantId });
@@ -900,6 +262,7 @@ export function Ablo(options) {
     // 6. Validate options up front — fail loudly on obviously wrong inputs so
     //    strangers don't get silent empty results. Validation errors are written
     //    into `store.syncStatus` (the single source of truth).
+    // eslint-disable-next-line @typescript-eslint/no-deprecated -- self-hosted default; hosted path ignores it (server derives kind from the apiKey scope)
     const kind = internalOptions.kind ?? 'user';
     const _validationError = validateAbloOptions({
         options: internalOptions,
@@ -918,6 +281,7 @@ export function Ablo(options) {
     // trusting them is the trap (you think you're an agent; the key says user).
     // Warn loudly rather than removing the fields — `agentId` is still load-bearing
     // on the self-hosted path (no apiKey; paired with `capabilityToken`).
+    // eslint-disable-next-line @typescript-eslint/no-deprecated -- reads the deprecated fields precisely to warn callers off them under a configured apiKey
     if (configuredApiKey && (internalOptions.kind || internalOptions.agentId)) {
         logger.warn('Ablo: `kind` / `agentId` are ignored when an `apiKey` is configured — ' +
             'the server derives participant identity from the key’s scope. Remove ' +
@@ -945,13 +309,13 @@ export function Ablo(options) {
         }
         _readyPromise = (async () => {
             try {
-                // Mint the FIRST access credential before we connect, so the initial
-                // WebSocket upgrade + bootstrap carry a valid bearer (no tokenless first
-                // connect that has to self-heal). Only when a refreshing resolver is
-                // wired AND no static credential is already present. Contract mirrors
-                // the `apiKey` resolver: `null` ⇒ the login is gone (terminal — fail ready so the
-                // app shows sign-in); a THROW ⇒ transient (rethrown; autoStart swallows
-                // and the lifecycle's online/wake triggers retry).
+                // Mint the first access credential before we connect, so the initial
+                // WebSocket upgrade and bootstrap carry a valid bearer (no tokenless first
+                // connect that has to self-heal). Only when a refreshing resolver is wired
+                // and no static credential is already present. Follows the `apiKey`
+                // resolver contract: `null` means the login is gone (terminal — fail ready
+                // so the app shows sign-in); a throw means transient (rethrown; autoStart
+                // swallows it and the lifecycle's online/wake triggers retry).
                 if (credentialResolver && !authCredentials.getAuthToken()) {
                     const token = await credentialResolver();
                     if (!token) {
@@ -959,7 +323,7 @@ export function Ablo(options) {
                     }
                     authCredentials.setAuthToken(token);
                 }
-                // Register the caller's own database for write-back BEFORE bootstrap, so
+                // Register the caller's own database for write-back before bootstrap, so
                 // the server resolves this org's data plane to the customer's DB rather
                 // than serving an empty/wrong store. The org is derived server-side from
                 // the API key. Idempotent server-side (register-or-update). Skipped when
@@ -981,15 +345,15 @@ export function Ablo(options) {
                     url,
                     kind,
                     configuredApiKey,
-                    // Resolve identity against the LIVE token, not the construction-time
-                    // `configuredAuthToken`. Consumers using a function `apiKey` (apps/web)
-                    // never pass `authToken` at construction — the lifecycle mints the
-                    // first `ek_`/`rk_` and calls `setAuthToken()` before
-                    // `ready()`, which updates the shared credential source. Reading the frozen
-                    // `configuredAuthToken` here made `/auth/identity` fire with no Bearer
-                    // (→ `no_matching_provider` / `session_expired`) even though the JWT
-                    // was present. Mirrors every other transport by reading the shared
-                    // credential source.
+                    // Resolve identity against the live token, not the construction-time
+                    // `configuredAuthToken`. Consumers using a function `apiKey` never pass
+                    // `authToken` at construction — the lifecycle mints the first `ek_` or
+                    // `rk_` and calls `setAuthToken()` before `ready()`, which updates the
+                    // shared credential source. Reading the frozen `configuredAuthToken`
+                    // here made `/auth/identity` fire with no bearer (returning
+                    // `no_matching_provider` / `session_expired`) even though the token was
+                    // present. This reads the shared credential source, like every other
+                    // transport.
                     configuredAuthToken: authCredentials.getAuthToken() ?? configuredAuthToken,
                     bootstrapHelper,
                     auth: authCredentials,
@@ -997,11 +361,11 @@ export function Ablo(options) {
                 });
                 const { userId, accountScope, teamIds, capabilityToken, syncGroups, participantKind, } = resolved;
                 // Fail-loud guard: detect the degenerate "no real sync groups
-                // resolved" state before opening the WS. Same class of bug as
-                // the schema-drift `[commit] dropped stale field` warning —
+                // resolved" state before opening the socket. It is the same class of bug as
+                // a
                 // sensible-looking default that's functionally broken: the
                 // SDK ends up subscribing only to the server-side
-                // `['default']` fallback (bootstrap.ts:45, Hub.ts:480), no
+                // `['default']` fallback, no
                 // delta has that tag, live fan-out silently never delivers.
                 // For human users (kind:'user') this is almost certainly a
                 // misconfiguration upstream — either the caller didn't pass
@@ -1013,9 +377,9 @@ export function Ablo(options) {
                 if (participantKind === 'user' &&
                     (resolvedSyncGroups.length === 0 ||
                         (resolvedSyncGroups.length === 1 && resolvedSyncGroups[0] === 'default'))) {
-                    // Actionable and NOT self-healing (no live updates until fixed):
-                    // kept at warn, consumer register — engine jargon and the internal
-                    // file pointer stripped; forensic fields ride the debug companion.
+                    // Actionable and not self-healing (no live updates until fixed):
+                    // kept at warn level for consumers; the low-level diagnostic
+                    // fields ride the debug log below.
                     logger.warn('This client was started without sync groups, so it will not receive ' +
                         'live updates. Pass `syncGroups` (for example ' +
                         '`["org:<id>", "user:<id>"]`) or check that your auth provider supplies them.');
@@ -1087,15 +451,15 @@ export function Ablo(options) {
                     httpStatus: error.httpStatus,
                     error: error.message,
                 });
-                // Clear the memo so a FUTURE `ready()` re-attempts bootstrap instead of
-                // replaying this rejection forever. Bootstrap failures here are
-                // transient by nature — offline, an IndexedDB open timeout, a bootstrap
-                // fetch hiccup — and used to brick the engine until a full page reload
-                // because line ~2013 (`if (_readyPromise) return _readyPromise`) handed
-                // every later caller this same dead promise. Nulling it lets the
-                // provider's online/wake/retry triggers drive a clean re-bootstrap.
-                // (The terminal `_validationError` branch above intentionally stays
-                // cached — config can't change without recreating the engine.)
+                // Clear the memo so a future `ready()` re-attempts bootstrap instead of
+                // replaying this rejection forever. Bootstrap failures here are transient
+                // by nature — offline, an IndexedDB open timeout, a bootstrap fetch
+                // hiccup — and the early `if (_readyPromise) return _readyPromise` guard
+                // would otherwise hand every later caller this same dead promise, bricking
+                // the engine until a full page reload. Nulling it lets the provider's
+                // online/wake/retry triggers drive a clean re-bootstrap. (The terminal
+                // `_validationError` branch above intentionally stays cached — config
+                // can't change without recreating the engine.)
                 _readyPromise = null;
                 throw error;
             }
@@ -1202,27 +566,6 @@ export function Ablo(options) {
             },
         };
     }
-    function modelClaimFromQueued(claim) {
-        return {
-            id: claim.id,
-            actor: claim.heldBy ?? "",
-            participantKind: claim.participantKind ?? "user",
-            reason: claim.reason,
-            ...(claim.description ? { description: claim.description } : {}),
-            field: claim.target.field,
-            status: 'queued',
-            position: claim.position,
-            expiresAt: claim.expiresAt ?? 0,
-            target: {
-                model: claim.target.type,
-                id: claim.target.id,
-                path: claim.target.path,
-                range: claim.target.range,
-                field: claim.target.field,
-                meta: claim.target.meta,
-            },
-        };
-    }
     function targetMatchesModel(target, claim) {
         if (target.model &&
             claim.target.type.toLowerCase() !== target.model.toLowerCase()) {
@@ -1239,14 +582,6 @@ export function Ablo(options) {
             .filter((claim) => (target ? targetMatchesModel(target, claim) : true))
             .map(modelClaimFromActive);
     }
-    function listModelClaimQueue(target) {
-        if (!target?.model || !target.id)
-            return [];
-        return publicClaims
-            .queueFor({ type: target.model, id: target.id })
-            .filter((claim) => (target.field ? claim.target.field === target.field : true))
-            .map(modelClaimFromQueued);
-    }
     function waitForModelUnclaimed(target, options) {
         if (listModelClaims(target).length === 0)
             return Promise.resolve();
@@ -1274,10 +609,12 @@ export function Ablo(options) {
                 }
             };
             const onAbort = () => {
-                finish(() => reject(new AbloConnectionError('Claim wait aborted.', {
-                    code: 'claim_wait_aborted',
-                    cause: options?.signal?.reason,
-                })));
+                finish(() => {
+                    reject(new AbloConnectionError('Claim wait aborted.', {
+                        code: 'claim_wait_aborted',
+                        cause: options?.signal?.reason,
+                    }));
+                });
             };
             if (options?.signal?.aborted) {
                 onAbort();
@@ -1287,7 +624,9 @@ export function Ablo(options) {
             options?.signal?.addEventListener('abort', onAbort, { once: true });
             if (options?.timeout != null) {
                 timeoutId = setTimeout(() => {
-                    finish(() => reject(claimedError(target, listModelClaims(target), 'model_claimed_timeout')));
+                    finish(() => {
+                        reject(claimedError(target, listModelClaims(target), 'model_claimed_timeout'));
+                    });
                 }, options.timeout);
             }
         });
@@ -1314,6 +653,10 @@ export function Ablo(options) {
             waited,
             release,
             revoke: claim.revoke,
+            // The lease-control members are forwarded explicitly — this wrapper
+            // rebuilds the handle field by field, so anything not named here is
+            // silently dropped from the public claim.
+            heartbeat: claim.heartbeat,
             [Symbol.asyncDispose]: release,
         };
     }
@@ -1376,7 +719,7 @@ export function Ablo(options) {
             createSnapshot: (modelKey, id) => createSnapshot({
                 pool: objectPool,
                 transport: store.getSyncWebSocket(),
-                // `position.readFloor` is THE value claims/snapshots stamp as
+                // `position.readFloor` is the value claims and snapshots stamp as
                 // `readAt` (max of the pool-applied cursor and the acked
                 // watermark for our own writes — see sync/syncPosition.ts).
                 // Stamping a bare stream cursor made a claim taken right after
@@ -1387,7 +730,7 @@ export function Ablo(options) {
                 entities: { [modelKey]: id },
             }),
             queue: (target) => publicClaims.queueFor({ type: target.model, id: target.id }),
-            reorder: (target, order) => publicClaims.reorder({ type: target.model, id: target.id }, order),
+            reorder: (target, order) => { publicClaims.reorder({ type: target.model, id: target.id }, order); },
             state: (target) => {
                 // The live claim stream only tracks *open* (active) claims;
                 // terminal states (committed / expired / canceled) drop out of
@@ -1422,19 +765,18 @@ export function Ablo(options) {
             selfParticipantKind: kind,
             // Read-interest / write-intent enrolment for the typed surface.
             // `enterScope`/`pinScope` resolve the `{ [schemaKey]: id }` scope
-            // through the SAME resolver the claim path uses, landing this client in
+            // through the same resolver the claim path uses, landing this client in
             // the entity-scoped group the holder's claim presence fans out on.
-            // Return the store promise so the claim write path can AWAIT pinScope
-            // BEFORE acquiring the lease (closing the subscribe-vs-broadcast race);
+            // Returns the store promise so the claim write path can await pinScope
+            // before acquiring the lease (closing the subscribe-vs-broadcast race);
             // read-interest callers (`retrieve`/`claim.state`) still `void` it and
-            // stay fire-and-forget. SOFT either way — the store swallows reconcile
-            // errors so read interest never makes a read reject or stall.
+            // stay fire-and-forget. It's soft either way — the store swallows
+            // reconcile errors so read interest never makes a read reject or stall.
             enterScope: (scope) => store.enterScope(scope),
             pinScope: (scope) => store.pinScope(scope),
-            // `ablo.<model>.watch(ids, { ttl })` → a scoped participant join on
-            // this model's sync group(s). The model-scoped relocation of the old
-            // `ablo.participants.join({ scope: { <model>: ids } })`. WebSocket
-            // only — `join` throws AbloConnectionError if the socket isn't ready.
+            // `ablo.<model>.watch(ids, { ttl })` performs a scoped participant join
+            // on this model's sync group(s). WebSocket only — `join` throws
+            // `AbloConnectionError` if the socket isn't ready.
             createWatch: (modelKey, ids, options) => participantManager.join({
                 scope: { [modelKey]: ids },
                 ...(options?.ttl !== undefined ? { ttlSeconds: options.ttl } : {}),
@@ -1584,7 +926,7 @@ export function Ablo(options) {
                 const id = params.id ?? createModelId();
                 await applyClaimedPolicy({ model: name, id }, params);
                 // Confirm, then return the authoritative row (with framework defaults;
-                // the EXISTING row on an idempotent re-create) — mirrors the WS client.
+                // the existing row on an idempotent re-create) — mirrors the WebSocket client.
                 await commits.create({
                     claimRef: params.claimRef,
                     idempotencyKey: params.idempotencyKey,
@@ -1629,13 +971,13 @@ export function Ablo(options) {
         };
     }
     /**
-     * The CONTROL-PLANE credential: always the original configured secret key.
+     * The control-plane credential: always the original configured secret key.
      * Never reads `authCredentials` — that holds the exchanged sync credential
      * (a wide-scope `rk_` on the hosted path), which control-plane routes
      * rightly refuse (e.g. the user-session mint is sk_-gated). Counterpart to
      * `getAuthToken()`, which resolves the sync-plane token.
      *
-     * The sk_-only rule is enforced server-side; the credential KIND taxonomy
+     * The secret-key-only rule is enforced on the server; the credential-kind taxonomy
      * (secret/restricted/ephemeral/publishable) lives in `auth/credentialPolicy`.
      */
     async function controlPlaneApiKey() {
@@ -1643,7 +985,7 @@ export function Ablo(options) {
     }
     /**
      * Resolve the control-plane context a session/agent mint needs (sk_ +
-     * bootstrap base URL + the schema-key→typename map the Hub gates on).
+     * bootstrap base URL + the schema-key→typename map the server gates on).
      * Shared by `sessions.create` and `agents.create` so the two mint doors
      * can never drift on how a token is minted. Throws if no `sk_` is present —
      * minting is a backend-only operation.
@@ -1660,12 +1002,12 @@ export function Ablo(options) {
                 bootstrapBaseUrl: internalOptions.bootstrapBaseUrl,
             }),
             ...(internalOptions.fetch ? { fetch: internalOptions.fetch } : {}),
-            // Map every `can` schema-key to the wire typename the Hub gates on, so a
+            // Map every `can` schema-key to the wire typename the server gates on, so a
             // typename override (`documents` → `Document`) doesn't mint a capability
             // the server then denies. See `MintSessionContext`.
             modelTypenames: Object.fromEntries(Object.entries(schema.models).map(([key, def]) => [
                 key,
-                def.typename ?? key,
+                (def).typename ?? key,
             ])),
         };
     }
@@ -1688,9 +1030,9 @@ export function Ablo(options) {
             // The live short-lived bearer (set via `setAuthToken` / `apiKey`-resolver refresh)
             // is the canonical credential; fall back to a configured API key.
             //
-            // This is the SYNC-PLANE token (bootstrap, WS, query HTTP). Control-plane
+            // This is the sync-plane token (bootstrap, WebSocket, query HTTP). Control-plane
             // calls (sessions.create, datasource registration) never use it — they
-            // present the ORIGINAL secret key via `controlPlaneApiKey()` below. The
+            // present the original secret key via `controlPlaneApiKey()` below. The
             // split matters: after the startup exchange this resolver returns the
             // derived wide-scope `rk_`, a credential the control-plane routes
             // correctly refuse (an agent token must never mint humans).
@@ -1702,9 +1044,8 @@ export function Ablo(options) {
         setCredentialRefresher(refresher) {
             store.setCredentialRefresher(refresher);
         },
-        // The org this client resolved to — null until `ready()` completes.
-        // Integrators previously had no programmatic way to learn it (the Pulse
-        // agent regex-scraped `ablo status` output); now it's a property.
+        // The org this client resolved to — null until `ready()` completes. Exposed
+        // as a property so integrators can read it programmatically.
         get organizationId() {
             return _resolvedOrganizationId;
         },
@@ -1712,33 +1053,33 @@ export function Ablo(options) {
             store.nudgeReconnect();
         },
         sessions: {
-            // Stripe `ephemeralKeys.create` shape: a BACKEND (holding `sk_`) mints a
-            // short-lived scoped token for one end user OR one agent.
+            // A backend (holding `sk_`) mints a short-lived scoped token for one end
+            // user or one agent.
             //
-            // CONTROL-PLANE CREDENTIAL RULE: both arms authenticate with the
-            // ORIGINAL secret key (`controlPlaneApiKey()`), never the wide-scope
-            // `rk_` the startup exchange installed as the sync credential. A derived
-            // agent credential silently replacing the secret key on control-plane
-            // calls is how humans get minted as agents — attribution is the product.
+            // Both arms authenticate with the original secret key
+            // (`controlPlaneApiKey()`), never the wide-scope `rk_` the startup exchange
+            // installed as the sync credential. A derived agent credential silently
+            // replacing the secret key on control-plane calls is how humans would get
+            // minted as agents — and correct attribution is the point.
             async create(params) {
-                // Both mint doors (`{ user }` → /auth/ephemeral-keys → `ek_`,
+                // Both mint paths (`{ user }` → /auth/ephemeral-keys → `ek_`,
                 // `{ agent, can }` → /auth/capability → scoped `rk_`) resolve their
                 // control-plane context through the shared `buildMintContext`, so this
-                // client, `agents.create`, and the stateless HTTP client can never drift
-                // on how a token is minted.
+                // client, `agents.create`, and the stateless HTTP client can't drift on
+                // how a token is minted.
                 return mintSession(params, await buildMintContext('sessions.create'));
             },
         },
-        // Mint a scoped agent IDENTITY and hand back a connected client bound to it
-        // — `sessions.create({ agent })` + `Ablo({ apiKey })` fused into one call,
-        // for agents that run in THIS (sk_-holding) process. Omitting `id` yields a
-        // fresh uuid per call, so concurrent agents are distinct participants that
-        // queue behind each other (even when they share a `name`). Humans don't get
-        // a server-built client — ship them a token via `sessions.create({ user })`.
+        // Mint a scoped agent identity and hand back a connected client bound to it —
+        // `sessions.create({ agent })` plus `Ablo({ apiKey })` fused into one call,
+        // for agents that run in this (secret-key-holding) process. Omitting `id`
+        // yields a fresh uuid per call, so concurrent agents are distinct participants
+        // that queue behind each other (even when they share a `name`). Humans don't
+        // get a server-built client — ship them a token via `sessions.create({ user })`.
         agents: {
             async create(params) {
                 // Distinct participant by default: omit `id` → a fresh uuid, so even two
-                // agents that share a `name` are INDEPENDENT participants and queue
+                // agents that share a `name` are independent participants and queue
                 // behind one another. `name` is display only (→ userMeta.name); it never
                 // derives the id. Pass an explicit `id` only to re-attach an agent to
                 // its own held claims.
@@ -1752,7 +1093,7 @@ export function Ablo(options) {
                     ...(userMeta ? { userMeta } : {}),
                 };
                 // Re-mint the `rk_` on every resolver call so a long-lived agent client
-                // never hits token expiry; the `sk_` stays in THIS process — the child
+                // never hits token expiry; the `sk_` stays in this process — the child
                 // only ever sees its own short-lived `rk_`.
                 const mintToken = async () => (await mintSession(sessionParams, await buildMintContext('agents.create')))
                     .token;
@@ -1799,7 +1140,7 @@ export function Ablo(options) {
          * the session (WebSocket close code 1008/4001/4003 or a session_error
          * frame). Multiple subscribers supported; returns an unsubscribe
          * function. Consumers typically use this to trigger auth-failed UI
-         * flows (e.g., redirect to sign-in). Does NOT automatically purge the
+         * flows (e.g., redirect to sign-in). Does not automatically purge the
          * IndexedDB — call `engine.purge()` from the listener if you need
          * that behavior (the SDK's `<AbloProvider>` does this by default).
          */
@@ -1826,7 +1167,7 @@ export function Ablo(options) {
         // the pool). Prefixed with _ to signal "internal but stable."
         /** The BaseSyncedStore — implements SyncStoreContract for SyncContext.Provider. */
         get _store() { return store; },
-        /** The ObjectPool — for demand loaders that need pool.createFromData(). */
+        /** The InstanceCache — for demand loaders that need pool.createFromData(). */
         get _pool() { return objectPool; },
         /** The SyncWebSocket — for collaboration events (slide selection, cursors). */
         get _ws() { return store.getSyncWebSocket() ?? null; },