@abloatai/ablo 0.3.0

package/dist/client/Ablo.js

@@ -0,0 +1,1440 @@
+/**
+ * Ablo — The one-liner consumer API.
+ *
+ * Hides all internal wiring (ObjectPool, Database, SyncClient, WebSocket,
+ * bootstrap, offline queue, DI adapters) behind a single function call.
+ *
+ * Usage:
+ *   import { Ablo } from '@ablo/sync-engine/client';
+ *   import { schema } from './schema';
+ *
+ *   const sync = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
+ *
+ *   const tasks = sync.tasks.list({ where: { status: 'todo' } });
+ *   await sync.tasks.create({ title: 'Fix bug' });
+ *   await sync.tasks.update(taskId, { status: 'done' });
+ *   await sync.tasks.delete(taskId);
+ */
+import { z } from 'zod';
+import { AbloBusyError, AbloError, AbloConnectionError, AbloValidationError, translateHttpError } from '../errors.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 { 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 { createIntentStream } from '../sync/createIntentStream.js';
+import { createSnapshot } from '../sync/createSnapshot.js';
+import { createParticipantManager } from '../sync/participants.js';
+import { createProtocolClient, } from './ApiClient.js';
+import { assertBrowserSafety, readProcessEnv, resolveApiKey, resolveAuthToken, resolveBaseURL, } from './auth.js';
+import { shouldUseInMemoryPersistence, } from './persistence.js';
+import { createModelProxy } from './createModelProxy.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: {},
+    };
+}
+// ── 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
+        const isLazy = modelDef.lazyObservable === true;
+        const fieldNames = Object.keys(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;
+}
+// ── Default console logger ────────────────────────────────────────────────
+const consoleLogger = {
+    debug: (...args) => { if (typeof console !== 'undefined')
+        console.debug('[sync]', ...args); },
+    info: (...args) => { if (typeof console !== 'undefined')
+        console.info('[sync]', ...args); },
+    warn: (...args) => { if (typeof console !== 'undefined')
+        console.warn('[sync]', ...args); },
+    error: (...args) => { if (typeof console !== 'undefined')
+        console.error('[sync]', ...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, options?.timeout, options?.causedByTaskId);
+        }
+        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;
+                }
+            }
+        },
+    };
+}
+export function Ablo(options) {
+    if (options.schema == null) {
+        return createProtocolClient(options);
+    }
+    const internalOptions = options;
+    const env = readProcessEnv();
+    const authInput = { options, env };
+    const configuredApiKey = resolveApiKey(authInput);
+    const configuredAuthToken = resolveAuthToken(authInput);
+    assertBrowserSafety({
+        apiKey: configuredApiKey,
+        dangerouslyAllowBrowser: options.dangerouslyAllowBrowser,
+    });
+    const { logger = consoleLogger } = internalOptions;
+    const schema = options.schema;
+    const url = resolveBaseURL(authInput);
+    // 1. Derive config from schema
+    // 1. Derive config from schema, then layer caller-supplied overrides on top.
+    //    `configOverrides` is a shallow merge: caller takes precedence per key.
+    const config = {
+        ...deriveConfigFromSchema(schema),
+        ...internalOptions.configOverrides,
+    };
+    // 2. Create the mutation executor + 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.
+    //
+    //    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.
+    // Captured-by-reference binding — assigned below after BaseSyncedStore
+    // is constructed. The default executor's `getWs` closure reads it
+    // lazily at commit time.
+    // The store is created later with full generics (`Schema<S>`), so type
+    // it here as the same generic — narrower default doesn't accept it.
+    const storeHolder = { store: null };
+    const executor = internalOptions.mutationExecutor ??
+        createDefaultMutationExecutor(() => {
+            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.
+    initSyncEngine({
+        logger,
+        observability: internalOptions.observability ?? noopObservability,
+        analytics: internalOptions.analytics ?? noopAnalytics,
+        sessionErrorDetector: internalOptions.sessionErrorDetector ?? defaultSessionErrorDetector,
+        onlineStatus: internalOptions.onlineStatus ??
+            (shouldUseInMemoryPersistence(options)
+                ? alwaysOnline()
+                : 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.
+    const { modelRegistry, objectPool, bootstrapHelper, database, syncClient, hydration, } = createInternalComponents({ schema, url, options: internalOptions });
+    registerModelsFromSchema(schema, modelRegistry);
+    // 5. BaseSyncedStore handles the initialization orchestration
+    //    (open DB → hydrate IDB → connect WS → fetch bootstrap → hydrate again →
+    //    ready) and exposes the observable `syncStatus` we expose on the engine.
+    //
+    //    Phase 2: pass the schema into the store so `deriveSyncPlanFromSchema`
+    //    can auto-populate version vector keys, FK indexes, and enrichment
+    //    rules from the declarative `belongsTo({ index, enrich })` annotations.
+    //    Consumers using class-based subclasses with `new SyncedStore(...)`
+    //    directly can pass explicit config arrays instead.
+    const store = new BaseSyncedStore({
+        syncClient,
+        database,
+        objectPool,
+        modelRegistry,
+        schema,
+        url,
+    });
+    // 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).
+    syncClient.getTransactionQueue().setMutationExecutor(executor);
+    // Active turn id, set by `beginTurn(...)`, cleared on close. While
+    // set, every batch commit attaches `causedByTaskId` so server
+    // delta rows get stamped with it. Single-turn-at-a-time per Ablo
+    // — opening a second turn overwrites the active id without closing
+    // the prior. Callers who need parallel turns construct multiple
+    // Ablo instances, matching the SyncAgent semantics.
+    let activeTurnId = null;
+    // Presence + intent streams — built eagerly so `engine.presence`
+    // and `engine.intents` return the same reference for the engine's
+    // lifetime. The transport doesn't exist yet (BaseSyncedStore.initialize
+    // creates it during ready()), so both streams are constructed in
+    // deferred-attach mode and wired after initialize() resolves below.
+    // Calls before attach mutate local state but skip the wire send.
+    // Identity routing: agents identify by agentId, users by user.id.
+    // 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 presenceStream = createPresenceStream({
+        participantId,
+        syncGroups: internalOptions.syncGroups ?? [],
+        isAgent: internalOptions.kind === 'agent',
+    });
+    const intentStream = createIntentStream({ participantId });
+    const participantManager = createParticipantManager({
+        ready,
+        getTransport: () => store.getSyncWebSocket() ?? null,
+        presence: presenceStream,
+        intents: intentStream,
+        schema,
+    });
+    // 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).
+    const kind = internalOptions.kind ?? 'user';
+    const _validationError = validateAbloOptions({
+        options: internalOptions,
+        url,
+        configuredApiKey,
+        configuredAuthToken,
+    });
+    if (_validationError) {
+        logger.error(_validationError.message);
+        store.syncStatus.state = 'error';
+        store.syncStatus.error = _validationError;
+    }
+    // 7. The ready() promise drives the BaseSyncedStore.initialize() generator
+    //    to completion. First call kicks off the initialization; subsequent
+    //    calls return the same promise (idempotent).
+    //
+    //    Status is tracked in store.syncStatus (MobX observable) — the single
+    //    source of truth. No duplicate closure variables.
+    let _readyPromise = null;
+    let _refreshScheduler = null;
+    let currentCapabilityToken = internalOptions.capabilityToken ?? configuredAuthToken ?? undefined;
+    // Wire the cap token into HydrationCoordinator's HTTP path. Without
+    // this, `ablo.<model>.load(...)` / `ablo.<model>.retrieve(...)` go
+    // through `postQuery` with `credentials: 'include'` only — fine in
+    // browsers (session cookies), but Node consumers (agent-worker)
+    // have no cookies and the request lands with no credential at all.
+    // The WS path was already wired (token rides the upgrade URL); this
+    // closes the gap on HTTP. Closure-over-binding so cap rotation
+    // (`applyRotatedToken` in the refresh scheduler below) propagates.
+    hydration.setCapabilityTokenProvider(() => currentCapabilityToken ?? null);
+    async function ready() {
+        if (_readyPromise)
+            return _readyPromise;
+        if (_validationError) {
+            _readyPromise = Promise.reject(_validationError);
+            return _readyPromise;
+        }
+        _readyPromise = (async () => {
+            try {
+                // Resolve participant identity + scope. Three branches —
+                // hosted-cloud apiKey exchange, self-derived from capability
+                // token, or legacy explicit options. See `./identity.ts`.
+                const resolved = await resolveParticipantIdentity({
+                    options: internalOptions,
+                    internalOptions,
+                    url,
+                    kind,
+                    configuredApiKey,
+                    configuredAuthToken,
+                    bootstrapHelper,
+                    logger,
+                    applyRotatedToken: (token) => {
+                        currentCapabilityToken = token;
+                        bootstrapHelper.setAuthToken(token);
+                        const ws = store.getSyncWebSocket();
+                        ws?.setCapabilityToken(token);
+                    },
+                });
+                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 —
+                // 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
+                // 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
+                // `syncGroups`, or auth resolution didn't derive them, or
+                // both. Warn loudly so the next debugging session starts here
+                // instead of with "live updates don't work, hard reload fixes
+                // it."
+                const resolvedSyncGroups = syncGroups ?? [];
+                if (participantKind === 'user' &&
+                    (resolvedSyncGroups.length === 0 ||
+                        (resolvedSyncGroups.length === 1 && resolvedSyncGroups[0] === 'default'))) {
+                    logger.warn('Ablo({kind:"user"}) initialized with degenerate syncGroups — ' +
+                        'this client will receive zero deltas through the live WS path. ' +
+                        'Either pass `syncGroups` explicitly (typically ' +
+                        '`["org:${orgId}", "user:${userId}"]`) or verify your auth ' +
+                        'provider populates them. See packages/sync-engine/src/client/identity.ts.', { participantKind, resolvedSyncGroups });
+                }
+                currentCapabilityToken = capabilityToken;
+                bootstrapHelper.setAuthToken(capabilityToken);
+                if (resolved.refreshScheduler) {
+                    _refreshScheduler = resolved.refreshScheduler;
+                }
+                // Drive the generator to completion. Each yielded promise is awaited
+                // then fed back — this is standard generator consumption.
+                //
+                // The store.initialize() generator updates store.syncStatus as it
+                // progresses (syncing → idle on success, error on failure), so the
+                // consumer's `sync.syncStatus` observable reflects real-time state.
+                // Resolve bootstrap mode: explicit option wins; otherwise
+                // agents default to 'none' (transactional participant — see
+                // option doc) and everyone else defaults to 'full'.
+                const resolvedBootstrapMode = internalOptions.bootstrapMode ?? (participantKind === 'agent' ? 'none' : 'full');
+                const gen = store.initialize({
+                    userId,
+                    organizationId: accountScope,
+                    teamIds,
+                    kind: participantKind,
+                    capabilityToken,
+                    syncGroups,
+                    bootstrapMode: resolvedBootstrapMode,
+                });
+                let current = gen.next();
+                while (!current.done) {
+                    const yielded = current.value;
+                    const resolved = yielded instanceof Promise ? await yielded : yielded;
+                    current = gen.next(resolved);
+                }
+                const result = current.value;
+                if (!result.success) {
+                    throw result.error ?? new Error('Sync engine initialization failed');
+                }
+                // Wire presence + intents to the now-open transport.
+                // `getSyncWebSocket()` returns non-null after a successful
+                // initialize() — the WS is created during the generator's
+                // connect step.
+                const ws = store.getSyncWebSocket();
+                if (ws) {
+                    presenceStream.attach(ws);
+                    intentStream.attach(ws);
+                }
+                logger.info('Sync engine ready', { models: Object.keys(schema.models).length });
+            }
+            catch (err) {
+                const error = err instanceof Error ? err : new Error(String(err));
+                // Make sure syncStatus reflects the failure for observer() components
+                store.syncStatus.state = 'error';
+                store.syncStatus.error = error;
+                logger.error('Sync engine failed to initialize', { error: error.message });
+                throw error;
+            }
+        })();
+        return _readyPromise;
+    }
+    // 9. Optional auto-start for convenience. Opt-in because silent background
+    //    init has historically been the #1 source of "why isn't my data loading"
+    //    bug reports. Explicit `await sync.ready()` is the default — errors
+    //    surface immediately instead of being swallowed.
+    if (!_validationError && internalOptions.autoStart) {
+        void ready().catch(() => {
+            // Error is captured in store.syncStatus; consumers should check
+            // `sync.syncStatus.state === 'error'` to detect failures.
+        });
+    }
+    // 9b. waitForFlush — drains pending mutations using the store's
+    //     pendingChanges counter (already maintained by BaseSyncedStore based
+    //     on TransactionQueue events). Polls every 50ms; uses the existing
+    //     observable rather than introducing a new event channel.
+    async function waitForFlush(timeoutMs) {
+        const start = Date.now();
+        while (store.syncStatus.pendingChanges > 0) {
+            if (timeoutMs !== undefined && Date.now() - start > timeoutMs) {
+                throw new AbloConnectionError(`Flush timeout: ${store.syncStatus.pendingChanges} pending mutations after ${timeoutMs}ms`, { code: 'flush_timeout' });
+            }
+            await new Promise((resolve) => setTimeout(resolve, 50));
+        }
+    }
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    function authHeaders() {
+        const headers = { 'Content-Type': 'application/json' };
+        if (currentCapabilityToken) {
+            headers.Authorization = `Bearer ${currentCapabilityToken}`;
+        }
+        else if (configuredAuthToken) {
+            headers.Authorization = `Bearer ${configuredAuthToken}`;
+        }
+        return headers;
+    }
+    function createClientTxId(idempotencyKey) {
+        if (idempotencyKey && idempotencyKey.length > 0)
+            return idempotencyKey;
+        return typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function'
+            ? crypto.randomUUID()
+            : `tx_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
+    }
+    function createResourceId() {
+        return typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function'
+            ? crypto.randomUUID()
+            : `id_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
+    }
+    function normalizeIntentId(intent) {
+        if (typeof intent === 'string')
+            return intent;
+        return intent?.id;
+    }
+    function normalizeCommitOperation(op, defaults) {
+        const resource = op.resource ?? op.target?.resource;
+        if (!resource) {
+            throw new AbloValidationError('Commit operation requires `resource` or `target.resource`.', { code: 'commit_operation_resource_required' });
+        }
+        const type = op.action.toUpperCase();
+        const id = op.id ?? op.target?.id ?? '';
+        return {
+            type,
+            model: resource.toLowerCase(),
+            id,
+            input: op.data ?? undefined,
+            transactionId: op.transactionId ?? undefined,
+            readAt: op.readAt ?? defaults.readAt ?? undefined,
+            onStale: op.onStale ?? defaults.onStale ?? undefined,
+        };
+    }
+    function normalizeCommitOperations(commitOptions) {
+        if (commitOptions.operation && commitOptions.operations) {
+            throw new AbloValidationError('Pass either `operation` or `operations`, not both.', { code: 'commit_operations_ambiguous' });
+        }
+        const inputOperations = commitOptions.operation
+            ? [commitOptions.operation]
+            : commitOptions.operations ?? [];
+        if (inputOperations.length === 0) {
+            throw new AbloValidationError('Commit requires at least one operation.', { code: 'commit_operation_required' });
+        }
+        return inputOperations.map((op) => normalizeCommitOperation(op, commitOptions));
+    }
+    function resourceIntentFromActive(intent) {
+        return {
+            id: intent.id,
+            actor: intent.heldBy,
+            participantKind: intent.participantKind,
+            action: intent.reason,
+            field: intent.target.field,
+            expiresAt: intent.expiresAt,
+            target: {
+                resource: intent.target.type,
+                id: intent.target.id,
+                path: intent.target.path,
+                range: intent.target.range,
+                field: intent.target.field,
+                meta: intent.target.meta,
+            },
+        };
+    }
+    function targetMatchesResource(target, intent) {
+        if (target.resource &&
+            intent.target.type.toLowerCase() !== target.resource.toLowerCase()) {
+            return false;
+        }
+        if (target.id && intent.target.id !== target.id)
+            return false;
+        if (target.field && intent.target.field !== target.field)
+            return false;
+        return true;
+    }
+    function listResourceIntents(target) {
+        return intentStream.others
+            .filter((intent) => (target ? targetMatchesResource(target, intent) : true))
+            .map(resourceIntentFromActive);
+    }
+    function busyError(target, intents, code) {
+        const label = [target.resource, target.id, target.field].filter(Boolean).join('/');
+        const holder = intents[0];
+        const suffix = holder
+            ? ` held by ${holder.actor} (${holder.action})`
+            : ' held by another participant';
+        return new AbloBusyError(`Resource is busy: ${label || 'target'}${suffix}.`, { code, intents });
+    }
+    function waitForResourceIdle(target, options) {
+        if (listResourceIntents(target).length === 0)
+            return Promise.resolve();
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            let timeoutId;
+            let unsubscribe;
+            const cleanup = () => {
+                if (timeoutId)
+                    clearTimeout(timeoutId);
+                if (unsubscribe)
+                    unsubscribe();
+                options?.signal?.removeEventListener('abort', onAbort);
+            };
+            const finish = (fn) => {
+                if (settled)
+                    return;
+                settled = true;
+                cleanup();
+                fn();
+            };
+            const check = () => {
+                if (listResourceIntents(target).length === 0) {
+                    finish(resolve);
+                }
+            };
+            const onAbort = () => {
+                finish(() => reject(new AbloConnectionError('Intent wait aborted.', {
+                    code: 'intent_wait_aborted',
+                    cause: options?.signal?.reason,
+                })));
+            };
+            if (options?.signal?.aborted) {
+                onAbort();
+                return;
+            }
+            unsubscribe = intentStream.subscribe(check);
+            options?.signal?.addEventListener('abort', onAbort, { once: true });
+            if (options?.timeout != null) {
+                timeoutId = setTimeout(() => {
+                    finish(() => reject(busyError(target, listResourceIntents(target), 'resource_busy_timeout')));
+                }, options.timeout);
+            }
+        });
+    }
+    async function applyBusyPolicy(target, options) {
+        const policy = options?.ifBusy ?? 'return';
+        if (policy === 'return')
+            return;
+        const current = listResourceIntents(target);
+        if (current.length === 0)
+            return;
+        if (policy === 'fail')
+            throw busyError(target, current, 'resource_busy');
+        await waitForResourceIdle(target, { timeout: options?.busyTimeout });
+    }
+    function wrapIntentHandle(claim) {
+        const release = async () => {
+            claim.revoke();
+        };
+        return {
+            id: claim.id,
+            release,
+            revoke: claim.revoke,
+            [Symbol.asyncDispose]: release,
+        };
+    }
+    const publicIntents = Object.assign(intentStream, {
+        async create(intentOptions) {
+            await ready();
+            const claim = intentStream.claim({
+                type: intentOptions.target.resource,
+                id: intentOptions.target.id,
+                path: intentOptions.target.path,
+                range: intentOptions.target.range,
+                field: intentOptions.target.field,
+                meta: intentOptions.target.meta,
+            }, { reason: intentOptions.action, ttl: intentOptions.ttl });
+            return wrapIntentHandle(claim);
+        },
+        list(target) {
+            return listResourceIntents(target);
+        },
+        waitFor(target, options) {
+            return waitForResourceIdle(target, options);
+        },
+    });
+    // Build the typed proxy — one property per model. Done after publicIntents
+    // exists so model resources can expose workflow helpers such as
+    // `ablo.files.edit(...)` without importing protocol wiring.
+    const modelProxies = {};
+    for (const [schemaKey, modelDef] of Object.entries(schema.models)) {
+        const registeredModelName = modelDef.typename ?? schemaKey;
+        modelProxies[schemaKey] = createModelProxy(schemaKey, registeredModelName, objectPool, syncClient, modelRegistry, hydration, {
+            createIntent: (intentOptions) => publicIntents.create(intentOptions),
+            createSnapshot: (modelKey, id) => createSnapshot({
+                pool: objectPool,
+                transport: store.getSyncWebSocket(),
+                getLastSyncId: () => store.getSyncWebSocket()?.getLastSyncId() ?? store.lastSyncId ?? 0,
+                entities: { [modelKey]: id },
+            }),
+        });
+    }
+    const commits = {
+        async create(commitOptions) {
+            await ready();
+            const clientTxId = createClientTxId(commitOptions.idempotencyKey);
+            const operations = normalizeCommitOperations(commitOptions);
+            const wait = commitOptions.wait ?? 'confirmed';
+            const intentId = normalizeIntentId(commitOptions.intent);
+            void intentId; // The current wire clears intents by entity after commit.
+            // Route through the TransactionQueue's commit lane so the call
+            // tolerates WS disconnects: the envelope stays in memory until
+            // reconnect, mutationExecutor.commit() owns transport-level
+            // retry, and `mutation_log` server-side dedupes replays by
+            // clientTxId. Replaces the direct ws.sendCommit /
+            // sendCommitQueued path that threw synchronously on
+            // `ws.readyState !== OPEN`. The queue lives on the internal
+            // SyncClient we already hold from createInternalComponents —
+            // no need to leak an accessor through BaseSyncedStore.
+            const queue = syncClient.getTransactionQueue();
+            queue.enqueueCommit(clientTxId, operations, {
+                causedByTaskId: activeTurnId,
+            });
+            if (wait === 'queued') {
+                return { id: clientTxId, status: 'queued' };
+            }
+            const { lastSyncId } = await queue.waitForCommitReceipt(clientTxId);
+            return { id: clientTxId, status: 'confirmed', lastSyncId };
+        },
+    };
+    async function retrieveResource(resourceName, id, options) {
+        await applyBusyPolicy({ resource: resourceName, id }, options);
+        await ready();
+        const res = await fetchImpl(`${bootstrapHelper.baseUrl}/sync/query`, {
+            method: 'POST',
+            headers: authHeaders(),
+            credentials: 'include',
+            body: JSON.stringify({
+                queries: [
+                    {
+                        model: resourceName,
+                        where: [['id', '=', id]],
+                        limit: 1,
+                    },
+                ],
+            }),
+        });
+        const bodyText = await res.text();
+        let body = bodyText;
+        if (bodyText.length > 0) {
+            try {
+                body = JSON.parse(bodyText);
+            }
+            catch {
+                // Keep raw body text.
+            }
+        }
+        if (!res.ok) {
+            throw translateHttpError(res.status, body || `Resource retrieve failed: ${res.status} ${res.statusText}`, res.headers.get('x-request-id') ?? undefined);
+        }
+        const parsed = body;
+        const slot = parsed.results?.[0];
+        const rows = Array.isArray(slot) ? slot : [];
+        const data = rows[0];
+        if (!data) {
+            throw new AbloValidationError(`Resource not found: ${resourceName}/${id}`, { code: 'resource_not_found' });
+        }
+        const stamp = typeof parsed.lastSyncId === 'number'
+            ? parsed.lastSyncId
+            : store.getSyncWebSocket()?.getLastSyncId() ?? store.lastSyncId ?? 0;
+        return {
+            data,
+            stamp,
+            intents: listResourceIntents({ resource: resourceName, id }),
+        };
+    }
+    function resource(name) {
+        return {
+            retrieve(id, options) {
+                return retrieveResource(name, id, options);
+            },
+            async create(data, mutationOptions) {
+                const id = mutationOptions?.id ?? createResourceId();
+                await applyBusyPolicy({ resource: name, id }, mutationOptions);
+                return commits.create({
+                    intent: mutationOptions?.intent,
+                    idempotencyKey: mutationOptions?.idempotencyKey,
+                    readAt: mutationOptions?.readAt,
+                    onStale: mutationOptions?.onStale,
+                    wait: mutationOptions?.wait,
+                    timeout: mutationOptions?.timeout,
+                    operations: [
+                        {
+                            action: 'create',
+                            resource: name,
+                            id,
+                            data,
+                        },
+                    ],
+                });
+            },
+            async update(id, data, mutationOptions) {
+                await applyBusyPolicy({ resource: name, id }, mutationOptions);
+                return commits.create({
+                    intent: mutationOptions?.intent,
+                    idempotencyKey: mutationOptions?.idempotencyKey,
+                    readAt: mutationOptions?.readAt,
+                    onStale: mutationOptions?.onStale,
+                    wait: mutationOptions?.wait,
+                    timeout: mutationOptions?.timeout,
+                    operations: [
+                        {
+                            action: 'update',
+                            resource: name,
+                            id,
+                            data,
+                        },
+                    ],
+                });
+            },
+            async delete(id, mutationOptions) {
+                await applyBusyPolicy({ resource: name, id }, mutationOptions);
+                return commits.create({
+                    intent: mutationOptions?.intent,
+                    idempotencyKey: mutationOptions?.idempotencyKey,
+                    readAt: mutationOptions?.readAt,
+                    onStale: mutationOptions?.onStale,
+                    wait: mutationOptions?.wait,
+                    timeout: mutationOptions?.timeout,
+                    operations: [
+                        {
+                            action: 'delete',
+                            resource: name,
+                            id,
+                        },
+                    ],
+                });
+            },
+        };
+    }
+    const engine = {
+        ...modelProxies,
+        ready,
+        waitForFlush,
+        async dispose() {
+            _refreshScheduler?.dispose();
+            _refreshScheduler = null;
+            try {
+                await store.disconnect();
+            }
+            catch (err) {
+                logger.warn('Error during sync engine disposal', { error: err.message });
+            }
+            presenceStream.dispose();
+            intentStream.dispose();
+            syncClient.dispose();
+        },
+        /**
+         * Destroy every IndexedDB database owned by this engine. Disconnects
+         * the WebSocket, releases timers, and deletes all `ablo_*` / `ablo-*`
+         * databases. Typically called on session expiry or explicit logout.
+         * Best-effort — errors from individual deletions are swallowed.
+         */
+        async purge() {
+            await store.purge();
+            syncClient.dispose();
+        },
+        /**
+         * Subscribe to session-error events. Fires when the server rejects
+         * 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
+         * IndexedDB — call `engine.purge()` from the listener if you need
+         * that behavior (the SDK's `<AbloProvider>` does this by default).
+         */
+        onSessionError(listener) {
+            return store.subscribeSessionError(listener);
+        },
+        onMutationFailure(listener) {
+            return store.subscribeMutationFailure(listener);
+        },
+        waitForConfirmation(modelName, modelId) {
+            return store.waitForConfirmation(modelName, modelId);
+        },
+        // Expose the store's MobX observable directly — single source of truth.
+        // React components using observer() will re-render automatically on
+        // any state change (syncing, error, offline, pendingChanges, progress).
+        get syncStatus() {
+            return store.syncStatus;
+        },
+        schema,
+        // ── Internal accessors for framework integration ─────────────────
+        // These expose internal components for consumers that need direct
+        // access (e.g., SyncEngineProvider wiring SyncContext, collaboration
+        // events accessing the WebSocket handle, demand loaders accessing
+        // 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(). */
+        get _pool() { return objectPool; },
+        /** The SyncWebSocket — for collaboration events (slide selection, cursors). */
+        get _ws() { return store.getSyncWebSocket() ?? null; },
+        /** Presence livestream — same socket as entity sync, no second
+         *  connection. Stable reference across the engine's lifetime. */
+        presence: presenceStream,
+        /** Intent livestream — same socket. Stable reference. */
+        intents: publicIntents,
+        commits,
+        resource,
+        /** Structured multiplayer participation — target-first, no
+     *  sync-group strings in the common path. */
+        participants: participantManager,
+        /** Context-staleness snapshot — see `engine.snapshot(...)` JSDoc. */
+        snapshot(entities) {
+            return createSnapshot({
+                pool: objectPool,
+                transport: store.getSyncWebSocket(),
+                getLastSyncId: () => store.getSyncWebSocket()?.getLastSyncId() ?? store.lastSyncId ?? 0,
+                entities,
+            });
+        },
+        // ── Turn handles ────────────────────────────────────────────────
+        //
+        // Open a turn — every commit issued while the returned handle is
+        // alive carries `caused_by_task_id` on the wire so the server
+        // stamps it onto each delta. The product surface this powers:
+        // `agent_tasks` audit trails ("which AI prompt produced this
+        // mutation"), parent/child turn chains, cost accounting per turn.
+        //
+        // POST /api/agent/turn (capability bearer) → returns turnId.
+        // POST /api/agent/turn/:id/close (capability bearer) → records
+        //   final cost stats. Idempotent.
+        async beginTurn(beginOptions) {
+            const baseUrl = url.replace(/\/+$/, '');
+            const turnUrl = `${baseUrl.replace(/^ws/, 'http')}/api/agent/turn`;
+            const headers = { 'Content-Type': 'application/json' };
+            if (currentCapabilityToken) {
+                headers.Authorization = `Bearer ${currentCapabilityToken}`;
+            }
+            const res = await fetch(turnUrl, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify({
+                    prompt: beginOptions.prompt,
+                    parentTaskId: beginOptions.parentTaskId,
+                    surface: beginOptions.surface,
+                    metadata: beginOptions.metadata,
+                }),
+            });
+            if (!res.ok) {
+                const body = await res.text().catch(() => '<no body>');
+                throw new AbloError(`beginTurn failed: ${res.status} ${body}`, { code: 'turn_open_failed', httpStatus: res.status });
+            }
+            const json = (await res.json());
+            const turnId = json.turnId;
+            activeTurnId = turnId;
+            let closed = false;
+            const close = async (stats) => {
+                if (closed)
+                    return;
+                closed = true;
+                if (activeTurnId === turnId)
+                    activeTurnId = null;
+                const closeUrl = `${turnUrl}/${encodeURIComponent(turnId)}/close`;
+                const closeRes = await fetch(closeUrl, {
+                    method: 'POST',
+                    headers,
+                    body: JSON.stringify({
+                        costInputTokens: stats?.costInputTokens ?? 0,
+                        costOutputTokens: stats?.costOutputTokens ?? 0,
+                        costComputeMs: stats?.costComputeMs ?? 0,
+                    }),
+                });
+                if (!closeRes.ok) {
+                    const body = await closeRes.text().catch(() => '<no body>');
+                    throw new AbloError(`closeTurn failed: ${closeRes.status} ${body}`, { code: 'turn_close_failed', httpStatus: closeRes.status });
+                }
+            };
+            const dispose = () => {
+                if (closed)
+                    return;
+                closed = true;
+                if (activeTurnId === turnId)
+                    activeTurnId = null;
+            };
+            return { turnId, close, dispose, [Symbol.asyncDispose]: () => close() };
+        },
+    };
+    return engine;
+}