@abloatai/ablo 0.25.0 → 0.26.0

package/dist/client/Ablo.js

@@ -5,7 +5,7 @@
  * bootstrap, offline queue, DI adapters) behind a single function call.
  *
  * 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 { ObjectPool } from '../ObjectPool.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,675 +38,21 @@ 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`,
@@ -748,7 +91,9 @@ export function Ablo(options) {
     // refresh timer + wake/online/focus triggers. Null for the common static
     // `apiKey` path — no refresh needed.
     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 +106,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
@@ -802,7 +147,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 +161,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,
@@ -855,9 +197,34 @@ export function Ablo(options) {
     // timer + wake/online/focus re-mint). Installed once here so refresh works for
     // 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_`/`ek_` BEFORE the
+    // hub's keepalive reaper closes it (4001 `credential_expired`). Two signals
+    // qualify — agent/system participants (the axis `createConnectionManager`
+    // gates on; `kind` is deprecated but still what agent runtimes pass today),
+    // and an ABSOLUTE endpoint-string `apiKey` (a relative one can't fetch in
+    // Node at all, so an absolute URL is unambiguously a deliberate server
+    // client, kind or no kind). User-kind clients in Node (an SSR/RSC module
+    // eval of 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 backbone as the WS 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 (the
+    // "Could not load documents — apikey_expired" wedge). 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
@@ -883,10 +250,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 +270,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 +289,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 ' +
@@ -1274,10 +646,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 +661,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);
             }
         });
@@ -1387,7 +763,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
@@ -1665,7 +1041,7 @@ export function Ablo(options) {
             // the server then denies. See `MintSessionContext`.
             modelTypenames: Object.fromEntries(Object.entries(schema.models).map(([key, def]) => [
                 key,
-                def.typename ?? key,
+                (def).typename ?? key,
             ])),
         };
     }