js-bao 0.7.0-alpha.6 → 0.7.0-alpha.7

package/dist/browser.cjs

@@ -5225,6 +5225,19 @@ var init_OrmContext = __esm({
       format2Documents = /* @__PURE__ */ new Map();
       /** Format-2 epoch moves in flight (#2816). */
       format2Transitions = /* @__PURE__ */ new Map();
+      /**
+       * This instance's document observers' database writes that have not finished
+       * yet, by document id (#3023).
+       *
+       * A Yjs observer fires synchronously with the update but writes to the
+       * database asynchronously, so an update that has been APPLIED to a document
+       * is not yet QUERYABLE. Whoever needs the difference — an `open()` that
+       * promises its caller the synced records — waits on
+       * {@link whenDocumentIndexed}. Per instance, not process-wide: two clients
+       * holding the same document id write to their own engines, and neither
+       * should be held up by the other's writes.
+       */
+      documentIndexingWork = /* @__PURE__ */ new Map();
       /**
        * Who this ORM instance is in a format-2 store's unacknowledged-write log
        * (#3431).
@@ -5402,6 +5415,56 @@ var init_OrmContext = __esm({
           release();
         }
       }
+      /**
+       * Record one observer's asynchronous write of `docId` (#3023), so a caller
+       * that needs the document queryable can wait for it. Failures are the
+       * observer's own to log; a tracked promise never rejects, because the point
+       * of the barrier is only to know when the write is over.
+       *
+       * A destroyed context tracks nothing: its observers are already inert, and a
+       * torn-down instance must not leave a barrier that never drains.
+       */
+      trackDocumentIndexing(docId, work) {
+        if (this.destroyed) return;
+        let inFlight = this.documentIndexingWork.get(docId);
+        if (!inFlight) {
+          inFlight = /* @__PURE__ */ new Set();
+          this.documentIndexingWork.set(docId, inFlight);
+        }
+        const pending = work.catch(() => {
+        }).then(() => {
+          inFlight.delete(pending);
+          if (inFlight.size === 0 && this.documentIndexingWork.get(docId) === inFlight) {
+            this.documentIndexingWork.delete(docId);
+          }
+        });
+        inFlight.add(pending);
+      }
+      /**
+       * Resolve once `docId`'s applied changes have reached this instance's query
+       * tables (#3023). Answers `true` when the work drained, `false` when it gave
+       * up waiting — the caller owns the logging, because this module holds no
+       * runtime imports.
+       *
+       * An update applied to the Y.Doc is visible to a reader of the document
+       * immediately, but the query tables only catch up when the observers' writes
+       * land. An `open()` that waited for the initial sync waits for this too —
+       * otherwise it resolves on the sync signal and the caller's first `query()`
+       * sees a partly-written table.
+       *
+       * A write can enqueue more work (a nested map observed as it arrives), so
+       * this drains in passes rather than once, and gives up after enough of them
+       * that only a document under continuous change could still be busy — a
+       * barrier is not a reason to hang.
+       */
+      async whenDocumentIndexed(docId) {
+        for (let pass = 0; pass < 50; pass++) {
+          const inFlight = this.documentIndexingWork.get(docId);
+          if (!inFlight || inFlight.size === 0) return true;
+          await Promise.all([...inFlight]);
+        }
+        return false;
+      }
       /** Notify `subscribe()` callbacks registered on this context for `modelName`. */
       notifyListeners(modelName, log, onError) {
         const listeners = this.listenersMap.get(modelName);
@@ -5527,6 +5590,7 @@ var init_OrmContext = __esm({
         this.modelDocMappingChangedListeners.clear();
         this.format2Documents.clear();
         this.format2Transitions.clear();
+        this.documentIndexingWork.clear();
         this.observedStringSetMaps = /* @__PURE__ */ new WeakSet();
         liveOrmContexts.delete(this);
         if (defaultOrmContext === this) {
@@ -5897,6 +5961,10 @@ var init_ModelRegistry = __esm({
        * undefined the legacy session semantics are kept exactly: the global
        * registry is SNAPSHOT at init time, so a model registered afterwards is not
        * silently adopted by an already-running instance.
+       *
+       * The one way a running instance's registry grows is {@link adoptModel},
+       * behind `registerModel` on the init result (#3615): an EXPLICIT call on the
+       * instance the app means, not a relaxation of the snapshot rule.
        */
       static createInstanceRegistry(modelClasses) {
         const registry = new _ModelRegistry();
@@ -5920,6 +5988,64 @@ var init_ModelRegistry = __esm({
         registry.setExplicitModelsForSession(modelClasses);
         return registry;
       }
+      /**
+       * The name `modelClass` may be adopted under on THIS instance, or a refusal
+       * that names what to change (#3615).
+       *
+       * Both checks are made before anything is mutated, so a registration that
+       * cannot go through leaves the registry exactly as it was.
+       */
+      assertAdoptable(modelClass, instanceId) {
+        const schema = modelClass?.getSchema?.();
+        const modelName = modelClass?.modelName ?? schema?.options?.name;
+        if (!modelName || !schema?.options?.name || !schema?.resolvedUniqueConstraints) {
+          throw new Error(
+            `[initJsBao] Cannot register a model class with no name. Build it with defineModelSchema and attachAndRegisterModel (or createModelClass) so it carries a static modelName and a schema with resolvedUniqueConstraints.`
+          );
+        }
+        const existing = this.models.get(modelName);
+        if (existing && existing !== modelClass) {
+          throw new Error(
+            `[initJsBao] Model '${modelName}' is already registered on js-bao instance #${instanceId} with a different class. Register the existing class, or give the new model a different name.`
+          );
+        }
+        return modelName;
+      }
+      /**
+       * Adopt `modelClass` into THIS instance's registry at runtime (#3615).
+       *
+       * The counterpart to the snapshot rule on
+       * {@link ModelRegistry.createInstanceRegistry}: an instance grows only where
+       * the app says so, and the global singleton is deliberately not touched —
+       * registering here makes the model visible to this instance and to no other.
+       *
+       * Returns `{ added: false }` when the very same class is already ACTIVE on
+       * this instance, which is what makes a repeat `registerModel` a no-op rather
+       * than a warning about overwriting. Active, not merely present: an instance
+       * built with `models: []` carries the whole global registry in `models` with
+       * nothing active, and a class only the backing snapshot holds has neither
+       * been validated for this session nor bound to its context, so it still has
+       * an adoption to go through.
+       */
+      adoptModel(modelClass, options = {}) {
+        const modelName = this.assertAdoptable(modelClass, options.instanceId);
+        if (this.getActiveModels().get(modelName) === modelClass) {
+          return { added: false };
+        }
+        const candidate = new Map(this.getActiveModels());
+        candidate.set(modelName, modelClass);
+        this.validateModels(candidate);
+        const schema = modelClass.getSchema?.();
+        this.models.set(modelName, modelClass);
+        if (schema?.options) this.modelOptions.set(modelName, schema.options);
+        if (this.activeSessionModels) {
+          this.activeSessionModels.set(modelName, modelClass);
+        }
+        Logger.debug(
+          `[ModelRegistry] Model "${modelName}" adopted by instance #${options.instanceId} at runtime.`
+        );
+        return { added: true };
+      }
       registerModel(modelClass, options, fields) {
         if (!options.name) {
           throw new Error(
@@ -6122,7 +6248,8 @@ var init_ModelRegistry = __esm({
         Logger.debug(`[ModelRegistry] Data removal complete for document ${docId}`);
       }
       // New method to initialize relationships
-      async initializeRelationships() {
+      async initializeRelationships(fallbackDbEngine) {
+        if (!this.dbEngine && fallbackDbEngine) this.dbEngine = fallbackDbEngine;
         if (!this.dbEngine) {
           console.error(
             "[ModelRegistry] DB engine not available for initializing relationships. Ensure initializeAll has been called."
@@ -6274,7 +6401,16 @@ var init_ModelRegistry = __esm({
         return this.activeSessionModels || this.models;
       }
       validateSessionModels() {
-        const activeModels = this.getActiveModels();
+        this.validateModels(this.getActiveModels());
+      }
+      /**
+       * Every relationship of `activeModels` names a model that is also in it.
+       *
+       * Taken as an argument rather than read off the registry so a runtime
+       * adoption can be validated against what the instance WOULD hold before it
+       * holds it (#3615).
+       */
+      validateModels(activeModels) {
         if (!activeModels || activeModels.size === 0) {
           return;
         }
@@ -6726,6 +6862,14 @@ var init_IncludeResolver = __esm({
 function generateULID() {
   return (0, import_ulid2.ulid)();
 }
+function reindexFailure(modelConstructor, modelName, recordId, docId, error) {
+  const message = error instanceof Error ? error.message : String(error);
+  const failure = new Error(
+    `[${modelConstructor.name}] Error re-indexing ${modelName}/${recordId} of document ${docId}: ${message}`
+  );
+  failure.cause = error;
+  return failure;
+}
 var Y7, import_ulid2, FORMAT2_ROW_PAGE, UniqueConstraintViolationError, RecordNotFoundError, SCHEMA_ACCESSORS_KEY, BaseModel2;
 var init_BaseModel = __esm({
   "src/models/BaseModel.ts"() {
@@ -7598,19 +7742,31 @@ var init_BaseModel = __esm({
         if (fieldOptions?.default === void 0) return void 0;
         return typeof fieldOptions.default === "function" ? fieldOptions.default() : fieldOptions.default;
       }
-      getStringSetFromYjs(fieldName) {
-        const yjsData = this.getFromYjs(fieldName);
-        if (yjsData instanceof Y7.Map) {
-          return Array.from(yjsData.keys());
+      /**
+       * The members of a stringset as it is STORED, in stored order.
+       *
+       * Static and value-only so that the two readers of a stored stringset — the
+       * instance's `getStringSetFromYjs`, which feeds the value a save builds its
+       * unique key from, and `_readableUniqueOwner`, which rebuilds another
+       * record's key from the map — cannot drift apart (#3252).
+       */
+      static _stringSetMembersFromStored(stored) {
+        if (stored instanceof Y7.Map) {
+          return Array.from(stored.keys());
         }
-        if (Array.isArray(yjsData)) {
-          return yjsData.filter((member) => typeof member === "string");
+        if (Array.isArray(stored)) {
+          return stored.filter((member) => typeof member === "string");
         }
-        if (yjsData && typeof yjsData === "object") {
-          return Object.keys(yjsData).filter((k) => Boolean(yjsData[k]));
+        if (stored && typeof stored === "object") {
+          return Object.keys(stored).filter((k) => Boolean(stored[k]));
         }
         return [];
       }
+      getStringSetFromYjs(fieldName) {
+        return this.constructor._stringSetMembersFromStored(
+          this.getFromYjs(fieldName)
+        );
+      }
       getOrCreateStringSet(fieldName) {
         if (!this._stringSetFields.has(fieldName)) {
           const initialValues = this.getStringSetFromYjs(fieldName);
@@ -7639,6 +7795,30 @@ var init_BaseModel = __esm({
           `[${this.name}] initialize(yDoc, db) is no longer supported. Use initializeForDocument(yDoc, db, docId, permission)`
         );
       }
+      /**
+       * Record one observer's asynchronous write of `docId` on this class's ORM
+       * instance (#3023), so a caller that needs the document queryable can wait
+       * for it. The observers themselves track through the context they captured
+       * at install time; this static is for callers that only hold a model class.
+       */
+      static trackDocumentIndexing(docId, work) {
+        resolveOrmContext(this).trackDocumentIndexing(docId, work);
+      }
+      /**
+       * Resolve once `docId`'s applied changes have reached this class's instance
+       * of the query tables (#3023). See
+       * {@link OrmContext.whenDocumentIndexed} — an `open()` that waited for the
+       * initial sync waits for this too, otherwise it resolves on the sync signal
+       * and the caller's first `query()` sees a partly-written table.
+       */
+      static async whenDocumentIndexed(docId) {
+        const drained = await resolveOrmContext(this).whenDocumentIndexed(docId);
+        if (!drained) {
+          Logger.warn(
+            `[BaseModel] Document ${docId} is still indexing after 50 drain passes; not waiting any longer`
+          );
+        }
+      }
       /**
        * Initialize this model for a connected document.
        *
@@ -7985,7 +8165,7 @@ var init_BaseModel = __esm({
           return recordIdsToDiscard;
         };
         const observerContext = resolveOrmContext(this);
-        const documentYMapObserver = async (event) => {
+        const indexDocumentYMapChange = async (event) => {
           if (observerContext.destroyed) return;
           Logger.verbose(
             `[${this.name}] Document YMap change detected for ${modelName}/${docId}:`,
@@ -8154,6 +8334,12 @@ var init_BaseModel = __esm({
           );
           observerContext.notifyListeners(modelName);
         };
+        const documentYMapObserver = (event) => {
+          observerContext.trackDocumentIndexing(
+            docId,
+            indexDocumentYMapChange(event)
+          );
+        };
         documentYMap.observe(documentYMapObserver);
         observerContext.registerObserverDisposer(
           docId,
@@ -8179,6 +8365,116 @@ var init_BaseModel = __esm({
           `[${this.name}] Model ${modelName} initialization complete for document ${docId}.`
         );
       }
+      /**
+       * Re-index ONE record of a document from its current Y.Map state (#3615).
+       *
+       * A legacy document's initial load walks the Y.Map before the permanent
+       * observers are installed, so an update that lands in that window reaches
+       * Yjs and misses the query tables. For a document connected long ago — which
+       * is exactly what a model registered at runtime is initialized against —
+       * that window is open on a live document. `registerModel` collects the
+       * record ids touched while it runs and brings each of them here afterwards,
+       * writing the same row the permanent per-record observer would have written.
+       *
+       * A record the window DELETED is deleted here for the same reason.
+       *
+       * A storage failure REJECTS rather than being logged and passed over, the
+       * way the permanent observers' writes are: this write is part of what a
+       * registration promises before it resolves, so swallowing it would resolve a
+       * registration whose query tables are missing the very updates this call
+       * exists to catch, and mark the pair complete so no retry would repair it.
+       */
+      static async reindexDocumentRecord(docId, recordId) {
+        const modelConstructor = this;
+        const schema = modelConstructor.getSchema?.();
+        const modelName = schema?.options?.name;
+        if (!modelName) return;
+        const ctx = resolveOrmContext(modelConstructor);
+        if (ctx.destroyed) return;
+        const documentYMap = modelConstructor.documentYMaps.get(
+          `${docId}_${modelName}`
+        );
+        if (!documentYMap) return;
+        const engine = ctx.dbEngine ? await modelConstructor.queryEngineFor([docId], modelName) : null;
+        if (!engine) return;
+        const recordData = documentYMap.get(recordId);
+        if (recordData === void 0 || recordData === null) {
+          try {
+            await engine.delete(modelName, recordId);
+          } catch (error) {
+            throw reindexFailure(
+              modelConstructor,
+              modelName,
+              recordId,
+              docId,
+              error
+            );
+          }
+          ctx.notifyListeners(modelName);
+          return;
+        }
+        const entries = recordData instanceof Y7.Map ? Array.from(recordData.entries()) : Object.entries(recordData);
+        const rowData = {};
+        for (const [fieldKey, value] of entries) {
+          const fieldOptions = schema.fields?.get(fieldKey);
+          if (!fieldOptions || fieldOptions.type === "stringset") continue;
+          if (value === void 0) continue;
+          rowData[fieldKey] = isYjsComposite(value) ? normalizeYjsValueForStorage(value) : value;
+        }
+        if (!rowData.id) return;
+        const permissionHint = modelConstructor.connectedDocuments.get(docId)?.permissionHint ?? "read-write";
+        try {
+          await engine.insert(modelName, {
+            ...rowData,
+            type: modelName,
+            _meta_doc_id: docId,
+            _meta_permission_hint: permissionHint
+          });
+        } catch (error) {
+          throw reindexFailure(
+            modelConstructor,
+            modelName,
+            recordId,
+            docId,
+            error
+          );
+        }
+        ctx.notifyListeners(modelName);
+      }
+      /**
+       * Withdraw ONE document's registration of this model (#3615).
+       *
+       * A `registerModel` that fails part-way through a document keeps the class
+       * registered, because retrying is the recovery. This is what keeps that
+       * half-finished pair from LOOKING finished in the meantime: without the
+       * Y.Map mapping a save raises the same `YMap not found` an unregistered
+       * model raises, instead of writing into a document whose observers were
+       * never installed, and clearing the rows the failed load managed to write
+       * keeps a query from answering out of a document nothing is watching. The
+       * retry's `initializeForDocument` publishes both again.
+       *
+       * `connectedDocuments` is deliberately left alone: it is the CONTEXT's map,
+       * shared by every model on the instance, so the document itself is still
+       * connected for everything else.
+       */
+      static async withdrawDocumentRegistration(docId) {
+        const modelConstructor = this;
+        const schema = modelConstructor.getSchema?.();
+        const modelName = schema?.options?.name;
+        if (!modelName) return;
+        modelConstructor.documentYMaps.delete(`${docId}_${modelName}`);
+        const ctx = resolveOrmContext(modelConstructor);
+        if (ctx.destroyed || !ctx.dbEngine) return;
+        try {
+          const engine = await modelConstructor.queryEngineFor([docId], modelName);
+          await engine.deleteByDocumentId(modelName, docId);
+        } catch (error) {
+          Logger.warn(
+            `[${modelConstructor.name}] Could not clear ${modelName} rows of document ${docId} while withdrawing an incomplete registration:`,
+            error
+          );
+        }
+      }
       // New method to clean up data for a disconnected document
       static async cleanupDocumentData(docId) {
         const modelConstructor = this;
@@ -8437,6 +8733,48 @@ var init_BaseModel = __esm({
           constraintName
         );
       }
+      /**
+       * The record that READABLY owns `uniqueKey` under `constraint` in one
+       * document's model map, or `null`.
+       *
+       * The `_uniqueIdx_` map is a cache over the records, not the record store,
+       * and the two can disagree (#3252): a replica can hold an index entry for a
+       * record whose structs have not landed yet, or an entry a field change or
+       * delete left behind. `save()` used to take the entry at its word, so the
+       * app saw a `query` that returned no row for a value and a save refused for
+       * that same value — the index knew a row nothing else could read.
+       *
+       * An entry counts only when its owner is readable: the record map exists
+       * under that id in `modelYMap`, and the key built from the record's stored
+       * fields is `uniqueKey`. Anything else is a stale entry, and the caller
+       * treats it as an index miss — the engine fallback decides, exactly as it
+       * does for a missing entry — so the write that follows lands and rewrites
+       * the entry to the record that really holds the value.
+       *
+       * "The key built from the record's stored fields" has to mean the key that
+       * record's own save built, so the stored value is read the way the save
+       * read it: a stringset is stored as a nested Y.Map of its members but keyed
+       * as the array `getCurrentJSState` puts in `dataToSave` (finding 3252-01).
+       * Comparing the raw Y.Map would call every readable owner of a unique
+       * stringset stale and let a duplicate straight through the constraint.
+       */
+      static _readableUniqueOwner(modelYMap, constraintMap, constraint, uniqueKey, modelName) {
+        const ownerId = constraintMap.get(uniqueKey);
+        if (!ownerId) return null;
+        const recordYMap = modelYMap?.get(ownerId);
+        if (!(recordYMap instanceof Y7.Map)) return null;
+        const fields = this.getSchema?.()?.fields;
+        const heldKey = this._buildKeyFromValues(
+          constraint.fields,
+          constraint.fields.map((field) => {
+            const stored = recordYMap.get(field);
+            return fields?.get(field)?.type === "stringset" ? this._stringSetMembersFromStored(stored) : stored;
+          }),
+          modelName,
+          constraint.name
+        );
+        return heldKey === uniqueKey ? ownerId : null;
+      }
       /**
        * The connected format-2 document that holds this instance's record, for an
        * instance the constructor could not resolve (#3429, finding 3429-03).
@@ -8634,7 +8972,14 @@ var init_BaseModel = __esm({
           const constraintMap = yDoc.getMap(
             uniqueIndexMapName(modelName, constraint.name)
           );
-          if (!constraintMap.get(newUniqueKey)) {
+          const readableOwner = modelConstructor._readableUniqueOwner(
+            targetYMap,
+            constraintMap,
+            constraint,
+            newUniqueKey,
+            modelName
+          );
+          if (!readableOwner) {
             const constraintKeyValues = constraint.fields.map(
               (field) => dataToSave[field]
             );
@@ -8652,7 +8997,13 @@ var init_BaseModel = __esm({
           if (upsertOnConstraint && upsertOnKey) {
             const constraintMapName = `_uniqueIdx_${modelName}_${upsertOnConstraint.name}`;
             const constraintMap = yDoc.getMap(constraintMapName);
-            const existingId = constraintMap.get(upsertOnKey);
+            const existingId = modelConstructor._readableUniqueOwner(
+              targetYMap ?? void 0,
+              constraintMap,
+              upsertOnConstraint,
+              upsertOnKey,
+              modelName
+            );
             if (existingId) {
               if (this._constructorProvidedId && this.id !== existingId) {
                 throw new Error(
@@ -8752,7 +9103,13 @@ var init_BaseModel = __esm({
                 50
               )}'`
             );
-            const existingRecordIdWithNewKey = constraintMap.get(newUniqueKey);
+            const existingRecordIdWithNewKey = modelConstructor._readableUniqueOwner(
+              targetYMap ?? void 0,
+              constraintMap,
+              constraint,
+              newUniqueKey,
+              modelName
+            );
             Logger.verbose(
               `[${modelName}] Save Check (Item '${this.id}'): Found Existing ID: '${existingRecordIdWithNewKey}' for Key '${newUniqueKey.substring(
                 0,
@@ -10890,7 +11247,7 @@ var init_BaseModel = __esm({
         );
         modelConstructor.attachStringSetObserversToRecord(recordYMap, schema, docId);
         const observerContext = resolveOrmContext(modelConstructor);
-        const recordObserver = async (event) => {
+        const indexNestedYMapChange = async (event) => {
           if (observerContext.destroyed) return;
           Logger.verbose(
             `[${modelName}] Nested YMap change detected for record ${recordId} in document ${docId}:`,
@@ -10966,6 +11323,12 @@ var init_BaseModel = __esm({
           }
           observerContext.notifyListeners(modelName);
         };
+        const recordObserver = (event) => {
+          observerContext.trackDocumentIndexing(
+            docId,
+            indexNestedYMapChange(event)
+          );
+        };
         recordYMap.observe(recordObserver);
         observerContext.registerObserverDisposer(
           docId,
@@ -11041,6 +11404,7 @@ __export(browser_exports, {
   encodeOverlayMutation: () => encodeOverlayMutation,
   estimateMaterializedBytes: () => estimateMaterializedBytes,
   features: () => features,
+  findReservedFieldNameInToml: () => findReservedFieldNameInToml,
   foldFormat2Overlay: () => foldFormat2Overlay,
   followEpoch: () => followEpoch,
   format2ClientDDL: () => format2ClientDDL,
@@ -14664,6 +15028,31 @@ var Format2DocumentBinding = class _Format2DocumentBinding {
    * hydration scope; an uncapped one answers with the models this instance
    * registered, which is every model whose rows could be here.
    */
+  /**
+   * Hydrate ONE model's derived query tables for a bound large document
+   * (#3615).
+   *
+   * What a model registered on a running instance needs: the merged view
+   * already holds its rows — the fold and the overlay observer are keyed by
+   * the model name the overlay carries, not by the registry — but the derived
+   * tables `query()` reads were never built, because the model was not in the
+   * registry when the document was connected.
+   *
+   * Forced, because the point is a rebuild: whatever mark a previous session
+   * left says nothing about tables this instance has never projected into.
+   */
+  async hydrateModel(docId, modelName) {
+    const store = this.opened.get(docId);
+    if (!store) return;
+    if (!store.isHydrated(modelName)) {
+      Logger.warn(
+        `[DocumentManager] Large document ${docId} does not hold model '${modelName}' on this device (its hydration scope excludes it), so the query tables for '${modelName}' were not hydrated. Reads of '${modelName}' on ${docId} answer as they do for any model this device declined.`
+      );
+      return;
+    }
+    await this.hydrateQueryTables(docId, store, { only: modelName });
+    await this.whenProjectionSettled();
+  }
   localModels(docId) {
     const store = this.ormContext.getFormat2StoreAsync(docId);
     if (!store) return null;
@@ -15199,12 +15588,70 @@ var DocumentManagerImpl = class {
   modelRegistry;
   /** The ORM instance this manager belongs to (#3039). */
   ormContext;
+  /**
+   * The registration gate (#3615).
+   *
+   * `connectDocument` finishes its model loop BEFORE it publishes the document
+   * in `connectedDocuments`, so a registration that read the map in that
+   * interval would miss the document while its own loop had already run —
+   * leaving it connected with no table, no rows and no observer for the new
+   * model. Registrations therefore run one at a time on this chain; a connect,
+   * a rebind and a disconnect wait for it at entry, and a registration waits
+   * for the connects that got in before it ({@link activeConnects}) before it
+   * reads the map. Connects of different documents that no registration
+   * overlaps still run concurrently, as they always have.
+   */
+  registrationChain = Promise.resolve();
+  /** Connects past the gate and not yet published — what a registration waits for. */
+  activeConnects = /* @__PURE__ */ new Set();
+  /**
+   * The `(model, document)` pairs whose initialization for this instance
+   * COMPLETED (#3615).
+   *
+   * Registry membership alone cannot say it: a document-level failure leaves
+   * the class registered but that document unusable, and `initializeForDocument`
+   * clears a document's rows and installs a fresh observer on every run, so a
+   * blanket retry would wipe the documents that had succeeded and double their
+   * observers. A retry resumes with the pairs that are not in here.
+   */
+  runtimeInitialized = /* @__PURE__ */ new Map();
+  /**
+   * Pass the registration gate, then run `work` as an in-flight connect
+   * (#3615).
+   *
+   * The re-read after the await is what closes the window: a registration
+   * publishes its chain synchronously when it is called, so a caller that
+   * waited on the chain it saw first has to check whether another one was
+   * queued behind it. Joining {@link activeConnects} happens with no await in
+   * between, so nothing can slip between the check and the join.
+   */
+  async enterConnect(work) {
+    for (; ; ) {
+      const chain = this.registrationChain;
+      await chain;
+      if (this.registrationChain === chain) break;
+    }
+    let settle;
+    const ticket = new Promise((resolve) => settle = resolve);
+    this.activeConnects.add(ticket);
+    try {
+      return await work();
+    } finally {
+      this.activeConnects.delete(ticket);
+      settle();
+    }
+  }
   async connectDocument(docId, yDoc, permissionHint, options) {
+    return this.enterConnect(
+      () => this.connectDocumentInner(docId, yDoc, permissionHint, options)
+    );
+  }
+  async connectDocumentInner(docId, yDoc, permissionHint, options) {
     if (this.connectedDocuments.has(docId)) {
       console.warn(
         `[DocumentManager] Document ${docId} is already connected. Disconnecting old version.`
       );
-      await this.disconnectDocument(docId);
+      await this.disconnectDocumentInner(docId);
     }
     const documentFormat = options?.documentFormat ?? 1;
     const connectedDoc = {
@@ -15231,6 +15678,9 @@ var DocumentManagerImpl = class {
       await this.format2.connect(docId, yDoc, options?.epoch);
     }
     this.connectedDocuments.set(docId, connectedDoc);
+    for (const modelName of this.modelRegistry.getActiveModels().keys()) {
+      this.markRuntimeInitialized(modelName, docId);
+    }
     this.notifyConnectionChange({
       type: "connect",
       docId,
@@ -15249,6 +15699,11 @@ var DocumentManagerImpl = class {
    * models read and write through is exchanged.
    */
   async rebindEpochDocument(docId, yDoc, options = {}) {
+    return this.enterConnect(
+      () => this.rebindEpochDocumentInner(docId, yDoc, options)
+    );
+  }
+  async rebindEpochDocumentInner(docId, yDoc, options = {}) {
     const connected = this.connectedDocuments.get(docId);
     if (!connected) {
       throw new Error(
@@ -15363,6 +15818,9 @@ var DocumentManagerImpl = class {
     return await this.format2.recordPresence(docId, records);
   }
   async disconnectDocument(docId) {
+    return this.enterConnect(() => this.disconnectDocumentInner(docId));
+  }
+  async disconnectDocumentInner(docId) {
     const connectedDoc = this.connectedDocuments.get(docId);
     if (!connectedDoc) {
       Logger.warn(`[DocumentManager] Document ${docId} is not connected`);
@@ -15379,6 +15837,9 @@ var DocumentManagerImpl = class {
       wipeModels ? { wipeIfLastModels: wipeModels } : {}
     );
     this.connectedDocuments.delete(docId);
+    for (const docIds of this.runtimeInitialized.values()) {
+      docIds.delete(docId);
+    }
     this.ormContext.disposeObserversForDocument(docId);
     this.ormContext.clearMappingsForDocId(docId);
     this.notifyConnectionChange({
@@ -15389,10 +15850,150 @@ var DocumentManagerImpl = class {
       `[DocumentManager] Document ${docId} disconnected successfully`
     );
   }
+  markRuntimeInitialized(modelName, docId) {
+    let docIds = this.runtimeInitialized.get(modelName);
+    if (!docIds) {
+      docIds = /* @__PURE__ */ new Set();
+      this.runtimeInitialized.set(modelName, docIds);
+    }
+    docIds.add(docId);
+  }
+  /**
+   * Add a model to this running instance (#3615). See
+   * {@link InitJsBaoResult.registerModel}.
+   */
+  async registerModel(modelClass) {
+    const previous = this.registrationChain;
+    let release;
+    this.registrationChain = new Promise((resolve) => release = resolve);
+    try {
+      await previous;
+      while (this.activeConnects.size > 0) {
+        await Promise.all(Array.from(this.activeConnects));
+      }
+      await this.runRegistration(modelClass);
+    } finally {
+      release();
+    }
+  }
+  async runRegistration(modelClass) {
+    if (this.ormContext.destroyed) {
+      throw new Error(
+        `[initJsBao] Cannot register model on destroyed js-bao instance #${this.ormContext.instanceId}. Create a new instance with initJsBao.`
+      );
+    }
+    const modelName = this.modelRegistry.assertAdoptable(
+      modelClass,
+      this.ormContext.instanceId
+    );
+    const boundTo = modelClass?._ormContext;
+    if (boundTo && boundTo !== this.ormContext && !boundTo.destroyed) {
+      throw new Error(
+        `[initJsBao] Model '${modelName}' is bound to live js-bao instance #${boundTo.instanceId}. Give instance #${this.ormContext.instanceId} its own model class (a fresh createModelClass / attachAndRegisterModel result).`
+      );
+    }
+    const { added } = this.modelRegistry.adoptModel(modelClass, {
+      instanceId: this.ormContext.instanceId
+    });
+    bindModelClass(this.ormContext, modelName, modelClass, "throw");
+    let didDocumentWork = false;
+    for (const connected of Array.from(this.connectedDocuments.values())) {
+      if (this.runtimeInitialized.get(modelName)?.has(connected.docId)) {
+        continue;
+      }
+      didDocumentWork = true;
+      try {
+        await this.initializeModelForConnectedDocument(
+          modelClass,
+          modelName,
+          connected
+        );
+      } catch (error) {
+        await modelClass.withdrawDocumentRegistration(connected.docId);
+        const message = error instanceof Error ? error.message : String(error);
+        const wrapped = new Error(
+          `[initJsBao] registerModel('${modelName}') failed on document ${connected.docId}; registration is incomplete and can be retried: ` + message
+        );
+        wrapped.cause = error;
+        throw wrapped;
+      }
+      this.markRuntimeInitialized(modelName, connected.docId);
+    }
+    if (added || didDocumentWork) {
+      await this.modelRegistry.initializeRelationships(this.dbEngine);
+    }
+  }
+  /**
+   * Initialize one model for one already-connected document (#3615).
+   *
+   * The legacy half carries the window `initializeForDocument` leaves open: it
+   * loads the Y.Map as records in an asynchronous transaction and installs its
+   * observers afterwards, which on a document the app connected long ago is a
+   * live document still receiving peer updates. A temporary deep observer
+   * collects the record ids touched while that runs; once the instance's
+   * indexing for the document has drained, each of them is written from its
+   * CURRENT state, so the call resolves with the query tables holding every
+   * update that arrived before it did.
+   */
+  async initializeModelForConnectedDocument(modelClass, modelName, connected) {
+    const { docId, yDoc, permissionHint } = connected;
+    const documentFormat = connected.documentFormat ?? 1;
+    if (documentFormat === 2) {
+      await modelClass.initializeForDocument(
+        yDoc,
+        this.dbEngine,
+        docId,
+        permissionHint,
+        2
+      );
+      await this.format2.hydrateModel(docId, modelName);
+      return;
+    }
+    const touched = /* @__PURE__ */ new Set();
+    const documentYMap = yDoc.getMap(modelName);
+    const collect2 = (events) => {
+      for (const event of events) {
+        if (event.target === documentYMap) {
+          for (const key of event.changes.keys.keys()) touched.add(key);
+        } else if (event.path.length > 0) {
+          touched.add(String(event.path[0]));
+        }
+      }
+    };
+    documentYMap.observeDeep(collect2);
+    try {
+      await modelClass.initializeForDocument(
+        yDoc,
+        this.dbEngine,
+        docId,
+        permissionHint,
+        1
+      );
+      await this.whenDocumentIndexed(docId);
+      for (const recordId of touched) {
+        await modelClass.reindexDocumentRecord(docId, recordId);
+      }
+    } finally {
+      documentYMap.unobserveDeep(collect2);
+    }
+  }
   /** Resolves once every enqueued query-projection refresh has been applied. */
   whenFormat2ProjectionSettled() {
     return this.format2.whenProjectionSettled();
   }
+  /**
+   * Resolves once THIS instance's query tables have caught up with `docId`
+   * (#3023). Scoped to the instance's own context, so a second client holding
+   * the same document id never waits on this one's writes.
+   */
+  async whenDocumentIndexed(docId) {
+    const drained = await this.ormContext.whenDocumentIndexed(docId);
+    if (!drained) {
+      Logger.warn(
+        `[DocumentManager] Document ${docId} is still indexing after 50 drain passes; not waiting any longer`
+      );
+    }
+  }
   getConnectedDocuments() {
     return new Map(this.connectedDocuments);
   }
@@ -15420,22 +16021,33 @@ var DocumentManagerImpl = class {
 };
 function bindSessionModels(ctx, registry) {
   for (const [modelName, modelClass] of registry.getActiveModels()) {
-    const current = modelClass?._ormContext;
-    if (current === ctx) continue;
-    if (!current || current.destroyed) {
-      Object.defineProperty(modelClass, "_ormContext", {
-        value: ctx,
-        writable: true,
-        configurable: true,
-        enumerable: false
-      });
-      ctx.boundModels.add(modelClass);
-      continue;
-    }
-    console.warn(
-      `[initJsBao] Model '${modelName}' is already bound to a live js-bao instance #${current.instanceId} and stays with it; instance #${ctx.instanceId}'s queries, writes and subscriptions for '${modelName}' will route to instance #${current.instanceId}. Give each client its own model classes (the schemaToml path already does) if you need them isolated.`
+    bindModelClass(ctx, modelName, modelClass, "warn");
+  }
+}
+function bindModelClass(ctx, modelName, modelClass, onLiveConflict) {
+  const current = modelClass?._ormContext;
+  if (current === ctx) {
+    ctx.boundModels.add(modelClass);
+    return;
+  }
+  if (!current || current.destroyed) {
+    Object.defineProperty(modelClass, "_ormContext", {
+      value: ctx,
+      writable: true,
+      configurable: true,
+      enumerable: false
+    });
+    ctx.boundModels.add(modelClass);
+    return;
+  }
+  if (onLiveConflict === "throw") {
+    throw new Error(
+      `[initJsBao] Model '${modelName}' is bound to live js-bao instance #${current.instanceId}. Give instance #${ctx.instanceId} its own model class (a fresh createModelClass / attachAndRegisterModel result).`
     );
   }
+  console.warn(
+    `[initJsBao] Model '${modelName}' is already bound to a live js-bao instance #${current.instanceId} and stays with it; instance #${ctx.instanceId}'s queries, writes and subscriptions for '${modelName}' will route to instance #${current.instanceId}. Give each client its own model classes (the schemaToml path already does) if you need them isolated.`
+  );
 }
 async function initJsBaoCore(options, getEngine) {
   const { databaseConfig, models: modelClasses } = options;
@@ -15464,6 +16076,7 @@ async function initJsBaoCore(options, getEngine) {
       destroy: () => ormContext.destroy(),
       connectDocument: docManager.connectDocument.bind(docManager),
       disconnectDocument: docManager.disconnectDocument.bind(docManager),
+      registerModel: docManager.registerModel.bind(docManager),
       format2SyncMarks: (docId) => format2SyncMarks(docId, ormContext),
       format2StoredEpoch: (docId) => format2StoredEpoch(dbEngine, docId, ormContext),
       // The pre-bind epoch read opens the same pool the bind will, so it needs
@@ -15496,6 +16109,7 @@ async function initJsBaoCore(options, getEngine) {
       // queue updates after it). The transport awaits it before an update
       // from the room counts as applied.
       whenFormat2ProjectionSettled: docManager.whenFormat2ProjectionSettled.bind(docManager),
+      whenDocumentIndexed: docManager.whenDocumentIndexed.bind(docManager),
       format2LoadSnapshot: docManager.loadSnapshot.bind(docManager),
       format2LocalModels: (docId) => docManager.localModels(docId),
       format2RecordPresence: (docId, records) => docManager.recordPresence(docId, records),
@@ -15899,6 +16513,26 @@ function schemaToToml(schema) {
 
 // src/models/tomlLoader.ts
 var import_smol_toml = require("smol-toml");
+
+// src/utils/reservedFields.ts
+function checkReservedFieldName(fieldName) {
+  if (fieldName === "id") return null;
+  if (fieldName === "type") {
+    return `Field 'type' is reserved (maps to internal _type column in queries)`;
+  }
+  if (fieldName.startsWith("_")) {
+    return `Field '${fieldName}' is reserved (fields starting with '_' are internal)`;
+  }
+  return null;
+}
+var ReservedFieldNameError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ReservedFieldNameError";
+  }
+};
+
+// src/models/tomlLoader.ts
 var VALID_FIELD_TYPES = /* @__PURE__ */ new Set([
   "string",
   "number",
@@ -16045,6 +16679,7 @@ function parseRelationship(raw, context, strict) {
 }
 function loadSchemaFromTomlString(tomlString, options = {}) {
   const strict = options.strict !== false;
+  const rejectReserved = options.rejectReservedFieldNames === true;
   const parsed = (0, import_smol_toml.parse)(tomlString);
   const models = parsed.models;
   if (!models || typeof models !== "object") {
@@ -16061,11 +16696,14 @@ function loadSchemaFromTomlString(tomlString, options = {}) {
     const fields = {};
     if (modelDef.fields) {
       for (const [fieldName, fieldDef] of Object.entries(modelDef.fields)) {
-        fields[fieldName] = parseFieldOptions(
-          fieldDef,
-          `[models.${modelName}.fields.${fieldName}]`,
-          strict
-        );
+        const context = `[models.${modelName}.fields.${fieldName}]`;
+        if (rejectReserved) {
+          const reserved = checkReservedFieldName(fieldName);
+          if (reserved) {
+            throw new ReservedFieldNameError(`${context}: ${reserved}`);
+          }
+        }
+        fields[fieldName] = parseFieldOptions(fieldDef, context, strict);
       }
     }
     let relationships;
@@ -16112,6 +16750,18 @@ function loadSchemaFromTomlString(tomlString, options = {}) {
   }
   return schemas;
 }
+function findReservedFieldNameInToml(tomlString) {
+  try {
+    loadSchemaFromTomlString(tomlString, {
+      strict: false,
+      rejectReservedFieldNames: true
+    });
+    return null;
+  } catch (error) {
+    if (error instanceof ReservedFieldNameError) return error.message;
+    return null;
+  }
+}
 
 // src/browser.ts
 init_metaSync();