js-bao 0.4.1 → 0.5.0

package/dist/client.d.ts

@@ -353,6 +353,7 @@ declare class BaseModel implements StringSetChangeTracker {
         permissionHint: DocumentPermissionHint;
     }>;
     protected static documentYMaps: Map<string, Y.Map<any>>;
+    private static _observedStringSetMaps;
     private _localChanges;
     private _isDirty;
     private _isLoadingFromYjs;
@@ -427,7 +428,17 @@ declare class BaseModel implements StringSetChangeTracker {
         added: Record<string, any>;
         modified: Record<string, any>;
         removed: string[];
+        stringSetChanges: Record<string, {
+            additions: Set<string>;
+            removals: Set<string>;
+        }>;
     };
+    /**
+     * Apply a stringset change set to the parent record's Y.Map by mutating a
+     * nested Y.Map keyed by member. Migrates from a legacy plain-object value
+     * if the field hasn't been touched since the wire-format change in #561.
+     */
+    private applyStringSetChangeToYMap;
     /**
      * Deep equality check for comparing field values
      */
@@ -529,6 +540,20 @@ declare class BaseModel implements StringSetChangeTracker {
      * Execute a callback with automatic transaction handling for all modified models
      */
     static withTransaction<T>(callback: () => Promise<T> | T): Promise<T>;
+    /**
+     * Attach a one-shot observer to a nested-Y.Map stringset field. Calls
+     * notifyListeners() when the nested map's keys change (i.e. when a remote
+     * member arrives via Y.applyUpdate, or a local per-member set/delete).
+     * Idempotent — re-calling on the same Y.Map is a no-op.
+     */
+    protected static observeStringSetMapOnce(nestedMap: Y.Map<any>): void;
+    /**
+     * Walk the schema's stringset fields on `recordYMap` and observe any nested
+     * Y.Map values. Called from observer setup and from the parent observer body
+     * so newly-arrived stringset Y.Maps (local migration or remote create) get
+     * an observer too.
+     */
+    protected static attachStringSetObserversToRecord(recordYMap: Y.Map<any>, schema: any): void;
     /**
      * Sets up deep observation on a nested YMap to sync field-level changes to the database
      */

package/dist/cloudflare-do.d.cts

@@ -1635,6 +1635,7 @@ declare class BaseModel implements StringSetChangeTracker {
         permissionHint: DocumentPermissionHint;
     }>;
     protected static documentYMaps: Map<string, Y.Map<any>>;
+    private static _observedStringSetMaps;
     private _localChanges;
     private _isDirty;
     private _isLoadingFromYjs;
@@ -1709,7 +1710,17 @@ declare class BaseModel implements StringSetChangeTracker {
         added: Record<string, any>;
         modified: Record<string, any>;
         removed: string[];
+        stringSetChanges: Record<string, {
+            additions: Set<string>;
+            removals: Set<string>;
+        }>;
     };
+    /**
+     * Apply a stringset change set to the parent record's Y.Map by mutating a
+     * nested Y.Map keyed by member. Migrates from a legacy plain-object value
+     * if the field hasn't been touched since the wire-format change in #561.
+     */
+    private applyStringSetChangeToYMap;
     /**
      * Deep equality check for comparing field values
      */
@@ -1811,6 +1822,20 @@ declare class BaseModel implements StringSetChangeTracker {
      * Execute a callback with automatic transaction handling for all modified models
      */
     static withTransaction<T>(callback: () => Promise<T> | T): Promise<T>;
+    /**
+     * Attach a one-shot observer to a nested-Y.Map stringset field. Calls
+     * notifyListeners() when the nested map's keys change (i.e. when a remote
+     * member arrives via Y.applyUpdate, or a local per-member set/delete).
+     * Idempotent — re-calling on the same Y.Map is a no-op.
+     */
+    protected static observeStringSetMapOnce(nestedMap: Y.Map<any>): void;
+    /**
+     * Walk the schema's stringset fields on `recordYMap` and observe any nested
+     * Y.Map values. Called from observer setup and from the parent observer body
+     * so newly-arrived stringset Y.Maps (local migration or remote create) get
+     * an observer too.
+     */
+    protected static attachStringSetObserversToRecord(recordYMap: Y.Map<any>, schema: any): void;
     /**
      * Sets up deep observation on a nested YMap to sync field-level changes to the database
      */

package/dist/cloudflare-do.d.ts

@@ -1635,6 +1635,7 @@ declare class BaseModel implements StringSetChangeTracker {
         permissionHint: DocumentPermissionHint;
     }>;
     protected static documentYMaps: Map<string, Y.Map<any>>;
+    private static _observedStringSetMaps;
     private _localChanges;
     private _isDirty;
     private _isLoadingFromYjs;
@@ -1709,7 +1710,17 @@ declare class BaseModel implements StringSetChangeTracker {
         added: Record<string, any>;
         modified: Record<string, any>;
         removed: string[];
+        stringSetChanges: Record<string, {
+            additions: Set<string>;
+            removals: Set<string>;
+        }>;
     };
+    /**
+     * Apply a stringset change set to the parent record's Y.Map by mutating a
+     * nested Y.Map keyed by member. Migrates from a legacy plain-object value
+     * if the field hasn't been touched since the wire-format change in #561.
+     */
+    private applyStringSetChangeToYMap;
     /**
      * Deep equality check for comparing field values
      */
@@ -1811,6 +1822,20 @@ declare class BaseModel implements StringSetChangeTracker {
      * Execute a callback with automatic transaction handling for all modified models
      */
     static withTransaction<T>(callback: () => Promise<T> | T): Promise<T>;
+    /**
+     * Attach a one-shot observer to a nested-Y.Map stringset field. Calls
+     * notifyListeners() when the nested map's keys change (i.e. when a remote
+     * member arrives via Y.applyUpdate, or a local per-member set/delete).
+     * Idempotent — re-calling on the same Y.Map is a no-op.
+     */
+    protected static observeStringSetMapOnce(nestedMap: Y.Map<any>): void;
+    /**
+     * Walk the schema's stringset fields on `recordYMap` and observe any nested
+     * Y.Map values. Called from observer setup and from the parent observer body
+     * so newly-arrived stringset Y.Maps (local migration or remote create) get
+     * an observer too.
+     */
+    protected static attachStringSetObserversToRecord(recordYMap: Y.Map<any>, schema: any): void;
     /**
      * Sets up deep observation on a nested YMap to sync field-level changes to the database
      */

package/dist/cloudflare.d.cts

@@ -353,6 +353,7 @@ declare class BaseModel implements StringSetChangeTracker {
         permissionHint: DocumentPermissionHint;
     }>;
     protected static documentYMaps: Map<string, Y.Map<any>>;
+    private static _observedStringSetMaps;
     private _localChanges;
     private _isDirty;
     private _isLoadingFromYjs;
@@ -427,7 +428,17 @@ declare class BaseModel implements StringSetChangeTracker {
         added: Record<string, any>;
         modified: Record<string, any>;
         removed: string[];
+        stringSetChanges: Record<string, {
+            additions: Set<string>;
+            removals: Set<string>;
+        }>;
     };
+    /**
+     * Apply a stringset change set to the parent record's Y.Map by mutating a
+     * nested Y.Map keyed by member. Migrates from a legacy plain-object value
+     * if the field hasn't been touched since the wire-format change in #561.
+     */
+    private applyStringSetChangeToYMap;
     /**
      * Deep equality check for comparing field values
      */
@@ -529,6 +540,20 @@ declare class BaseModel implements StringSetChangeTracker {
      * Execute a callback with automatic transaction handling for all modified models
      */
     static withTransaction<T>(callback: () => Promise<T> | T): Promise<T>;
+    /**
+     * Attach a one-shot observer to a nested-Y.Map stringset field. Calls
+     * notifyListeners() when the nested map's keys change (i.e. when a remote
+     * member arrives via Y.applyUpdate, or a local per-member set/delete).
+     * Idempotent — re-calling on the same Y.Map is a no-op.
+     */
+    protected static observeStringSetMapOnce(nestedMap: Y.Map<any>): void;
+    /**
+     * Walk the schema's stringset fields on `recordYMap` and observe any nested
+     * Y.Map values. Called from observer setup and from the parent observer body
+     * so newly-arrived stringset Y.Maps (local migration or remote create) get
+     * an observer too.
+     */
+    protected static attachStringSetObserversToRecord(recordYMap: Y.Map<any>, schema: any): void;
     /**
      * Sets up deep observation on a nested YMap to sync field-level changes to the database
      */

package/dist/cloudflare.d.ts

@@ -353,6 +353,7 @@ declare class BaseModel implements StringSetChangeTracker {
         permissionHint: DocumentPermissionHint;
     }>;
     protected static documentYMaps: Map<string, Y.Map<any>>;
+    private static _observedStringSetMaps;
     private _localChanges;
     private _isDirty;
     private _isLoadingFromYjs;
@@ -427,7 +428,17 @@ declare class BaseModel implements StringSetChangeTracker {
         added: Record<string, any>;
         modified: Record<string, any>;
         removed: string[];
+        stringSetChanges: Record<string, {
+            additions: Set<string>;
+            removals: Set<string>;
+        }>;
     };
+    /**
+     * Apply a stringset change set to the parent record's Y.Map by mutating a
+     * nested Y.Map keyed by member. Migrates from a legacy plain-object value
+     * if the field hasn't been touched since the wire-format change in #561.
+     */
+    private applyStringSetChangeToYMap;
     /**
      * Deep equality check for comparing field values
      */
@@ -529,6 +540,20 @@ declare class BaseModel implements StringSetChangeTracker {
      * Execute a callback with automatic transaction handling for all modified models
      */
     static withTransaction<T>(callback: () => Promise<T> | T): Promise<T>;
+    /**
+     * Attach a one-shot observer to a nested-Y.Map stringset field. Calls
+     * notifyListeners() when the nested map's keys change (i.e. when a remote
+     * member arrives via Y.applyUpdate, or a local per-member set/delete).
+     * Idempotent — re-calling on the same Y.Map is a no-op.
+     */
+    protected static observeStringSetMapOnce(nestedMap: Y.Map<any>): void;
+    /**
+     * Walk the schema's stringset fields on `recordYMap` and observe any nested
+     * Y.Map values. Called from observer setup and from the parent observer body
+     * so newly-arrived stringset Y.Maps (local migration or remote create) get
+     * an observer too.
+     */
+    protected static attachStringSetObserversToRecord(recordYMap: Y.Map<any>, schema: any): void;
     /**
      * Sets up deep observation on a nested YMap to sync field-level changes to the database
      */

package/dist/codegen-v2.cjs

@@ -533,7 +533,8 @@ function renderModelFile(input) {
   lines.push(`export interface ${className}Attrs {`);
   for (const [fieldName, opts] of Object.entries(fields)) {
     const tsType = tsTypeForFieldType(opts.type);
-    const optional = opts.required === true ? "" : "?";
+    const isRequired = opts.required === true || opts.autoAssign === true && fieldName === "id";
+    const optional = isRequired ? "" : "?";
     lines.push(`  ${fieldName}${optional}: ${tsType};`);
   }
   lines.push(`}`);
@@ -642,7 +643,9 @@ function renderBarrel(input) {
   lines.push(`  }`);
   lines.push(`}`);
   lines.push("");
-  lines.push(`export const allModels: unknown[] = _modelPairs.map((m) => m.class);`);
+  lines.push(
+    `export const allModels: Array<typeof BaseModel> = _modelPairs.map((m) => m.class);`
+  );
   lines.push("");
   return lines.join("\n");
 }
@@ -1062,10 +1065,18 @@ function parseDefineModelSchemaArg(obj, sf) {
     if (opts && opts.type === "id") {
       fd.severity = "info";
       opts.autoAssign = true;
+      if (fd.field === "id") {
+        opts.required = true;
+      }
     } else {
       fd.severity = "warn";
     }
   }
+  for (const [fieldName, opts] of Object.entries(fields)) {
+    if (fieldName === "id" && opts.autoAssign === true && opts.required !== false) {
+      opts.required = true;
+    }
+  }
   return { modelName, fields, relationships, uniqueConstraints, functionDefaults };
 }
 function parseFields(obj, sf) {
@@ -1477,7 +1488,7 @@ var Logger2 = class _Logger {
 // package.json
 var package_default = {
   name: "js-bao",
-  version: "0.4.1",
+  version: "0.5.0",
   description: "A library providing data modeling capabilities which support live updates and queries.",
   types: "dist/index.d.ts",
   type: "module",

package/dist/codegen.cjs

@@ -1181,7 +1181,7 @@ var SchemaExtractor = class {
 // package.json
 var package_default = {
   name: "js-bao",
-  version: "0.4.1",
+  version: "0.5.0",
   description: "A library providing data modeling capabilities which support live updates and queries.",
   types: "dist/index.d.ts",
   type: "module",

package/dist/index.cjs

@@ -1858,6 +1858,9 @@ var init_BaseModel = __esm({
       static connectedDocuments = /* @__PURE__ */ new Map();
       static documentYMaps = /* @__PURE__ */ new Map();
       // Maps docId to YMap for that document
+      // Tracks nested-Y.Map stringset fields we've already attached observers to,
+      // so attachStringSetObserversToRecord() is idempotent across re-entry.
+      static _observedStringSetMaps = /* @__PURE__ */ new WeakSet();
       // Copy-on-write state management
       _localChanges = null;
       _isDirty = false;
@@ -2317,7 +2320,7 @@ var init_BaseModel = __esm({
       validateBeforeSave() {
         const schema = this.constructor.getSchema();
         for (const [fieldKey, fieldOptions] of schema.fields.entries()) {
-          const currentValue = this.getValue(fieldKey);
+          const currentValue = fieldKey === "id" ? this.id : this.getValue(fieldKey);
           if (fieldOptions.required && (currentValue === null || currentValue === void 0)) {
             throw new Error(`Field ${fieldKey} is required before save`);
           }
@@ -2377,16 +2380,15 @@ var init_BaseModel = __esm({
         this._isDirty = true;
       }
       getStringSetCurrentValues(fieldName) {
-        const yjsData = this.getFromYjs(fieldName);
-        if (yjsData && typeof yjsData === "object") {
-          return Object.keys(yjsData);
-        }
-        return [];
+        return this.getStringSetFromYjs(fieldName);
       }
       getStringSetFromYjs(fieldName) {
         const yjsData = this.getFromYjs(fieldName);
+        if (yjsData instanceof Y2.Map) {
+          return Array.from(yjsData.keys());
+        }
         if (yjsData && typeof yjsData === "object") {
-          return Object.keys(yjsData);
+          return Object.keys(yjsData).filter((k) => Boolean(yjsData[k]));
         }
         return [];
       }
@@ -2997,7 +2999,7 @@ var init_BaseModel = __esm({
           Logger.debug(
             `[_diffWithYjsData] No unsaved changes, returning empty diff`
           );
-          return { added: {}, modified: {}, removed: [] };
+          return { added: {}, modified: {}, removed: [], stringSetChanges: {} };
         }
         const modelConstructor = this.constructor;
         const schema = modelConstructor.getSchema();
@@ -3028,6 +3030,7 @@ var init_BaseModel = __esm({
         const added = {};
         const modified = {};
         const removed = [];
+        const stringSetChanges = {};
         if (!recordYMap) {
           Logger.debug(
             `[_diffWithYjsData] No existing recordYMap, treating all local changes as 'added'`
@@ -3036,11 +3039,12 @@ var init_BaseModel = __esm({
             for (const [key, value] of Object.entries(this._localChanges)) {
               Logger.debug(`[_diffWithYjsData] Adding field '${key}': ${value}`);
               if (value && value.type === "stringset") {
-                const stringSetData = {};
-                for (const addition of value.additions) {
-                  stringSetData[addition] = true;
+                if (value.additions.size > 0 || value.removals.size > 0) {
+                  stringSetChanges[key] = {
+                    additions: value.additions,
+                    removals: value.removals
+                  };
                 }
-                added[key] = stringSetData;
               } else {
                 added[key] = value;
               }
@@ -3049,9 +3053,10 @@ var init_BaseModel = __esm({
           Logger.debug(`[_diffWithYjsData] Final diff for new record:`, {
             added,
             modified: {},
-            removed: []
+            removed: [],
+            stringSetChanges
           });
-          return { added, modified, removed: [] };
+          return { added, modified, removed: [], stringSetChanges };
         }
         Logger.debug(
           `[_diffWithYjsData] Existing record found, comparing local changes with Y.js data`
@@ -3068,21 +3073,11 @@ var init_BaseModel = __esm({
               `[_diffWithYjsData] Processing field '${key}' with local value: ${localValue}`
             );
             if (localValue && localValue.type === "stringset") {
-              const currentYjsData = recordYMap.get(key) || {};
-              const newStringSetData = {
-                ...currentYjsData
-              };
-              for (const addition of localValue.additions) {
-                newStringSetData[addition] = true;
-              }
-              for (const removal of localValue.removals) {
-                delete newStringSetData[removal];
-              }
-              const yjsValue = recordYMap.get(key);
-              if (yjsValue === void 0) {
-                added[key] = newStringSetData;
-              } else if (!this._deepEqual(yjsValue, newStringSetData)) {
-                modified[key] = newStringSetData;
+              if (localValue.additions.size > 0 || localValue.removals.size > 0) {
+                stringSetChanges[key] = {
+                  additions: localValue.additions,
+                  removals: localValue.removals
+                };
               }
             } else {
               const yjsValue = recordYMap.get(key);
@@ -3108,14 +3103,43 @@ var init_BaseModel = __esm({
         Logger.debug(`[_diffWithYjsData] Final diff result:`, {
           added,
           modified,
-          removed
+          removed,
+          stringSetChanges
         });
         Logger.verbose(`[${modelConstructor.name}] Diff for ${this.id}:`, {
           added: Object.keys(added),
           modified: Object.keys(modified),
-          removed
+          removed,
+          stringSetChanges: Object.keys(stringSetChanges)
         });
-        return { added, modified, removed };
+        return { added, modified, removed, stringSetChanges };
+      }
+      /**
+       * Apply a stringset change set to the parent record's Y.Map by mutating a
+       * nested Y.Map keyed by member. Migrates from a legacy plain-object value
+       * if the field hasn't been touched since the wire-format change in #561.
+       */
+      applyStringSetChangeToYMap(recordYMap, fieldName, change) {
+        let nested = recordYMap.get(fieldName);
+        if (!(nested instanceof Y2.Map)) {
+          const migrated = new Y2.Map();
+          if (nested && typeof nested === "object") {
+            for (const [member, marker] of Object.entries(
+              nested
+            )) {
+              if (Boolean(marker)) migrated.set(member, true);
+            }
+          }
+          recordYMap.set(fieldName, migrated);
+          nested = migrated;
+        }
+        const target = nested;
+        for (const member of change.additions) {
+          target.set(member, true);
+        }
+        for (const member of change.removals) {
+          target.delete(member);
+        }
       }
       /**
        * Deep equality check for comparing field values
@@ -3354,7 +3378,7 @@ var init_BaseModel = __esm({
           Logger.debug(`[${modelName}.save] About to calculate diff`);
           const diff = this._diffWithYjsData();
           Logger.debug(`[${modelName}.save] Diff result:`, diff);
-          const hasChanges = Object.keys(diff.added).length > 0 || Object.keys(diff.modified).length > 0 || diff.removed.length > 0;
+          const hasChanges = Object.keys(diff.added).length > 0 || Object.keys(diff.modified).length > 0 || diff.removed.length > 0 || Object.keys(diff.stringSetChanges).length > 0;
           Logger.debug(`[${modelName}.save] hasChanges: ${hasChanges}`);
           if (!hasChanges && isUpdate) {
             Logger.verbose(
@@ -3472,6 +3496,16 @@ var init_BaseModel = __esm({
             Logger.debug(`[${modelName}.save] Removing field '${key}'`);
             recordYMap.delete(key);
           }
+          for (const [fieldName, change] of Object.entries(diff.stringSetChanges)) {
+            Logger.debug(
+              `[${modelName}.save] Applying stringset change to field '${fieldName}':`,
+              {
+                additions: Array.from(change.additions),
+                removals: Array.from(change.removals)
+              }
+            );
+            this.applyStringSetChangeToYMap(recordYMap, fieldName, change);
+          }
           Logger.debug(
             `[${modelName}.save] After applying changes, recordYMap contents:`,
             Object.fromEntries(recordYMap.entries())
@@ -4656,6 +4690,39 @@ var init_BaseModel = __esm({
           _BaseModel.prototype.setValue = originalSetValue;
         }
       }
+      /**
+       * Attach a one-shot observer to a nested-Y.Map stringset field. Calls
+       * notifyListeners() when the nested map's keys change (i.e. when a remote
+       * member arrives via Y.applyUpdate, or a local per-member set/delete).
+       * Idempotent — re-calling on the same Y.Map is a no-op.
+       */
+      static observeStringSetMapOnce(nestedMap) {
+        if (_BaseModel._observedStringSetMaps.has(nestedMap)) return;
+        _BaseModel._observedStringSetMaps.add(nestedMap);
+        const modelConstructor = this;
+        nestedMap.observe(() => {
+          Logger.verbose(
+            `[${modelConstructor.name}] Nested stringset Y.Map changed; notifying listeners`
+          );
+          modelConstructor.notifyListeners();
+        });
+      }
+      /**
+       * Walk the schema's stringset fields on `recordYMap` and observe any nested
+       * Y.Map values. Called from observer setup and from the parent observer body
+       * so newly-arrived stringset Y.Maps (local migration or remote create) get
+       * an observer too.
+       */
+      static attachStringSetObserversToRecord(recordYMap, schema) {
+        if (!schema?.fields) return;
+        for (const [fieldKey, fieldOptions] of schema.fields) {
+          if (fieldOptions?.type !== "stringset") continue;
+          const value = recordYMap.get(fieldKey);
+          if (value instanceof Y2.Map) {
+            this.observeStringSetMapOnce(value);
+          }
+        }
+      }
       /**
        * Sets up deep observation on a nested YMap to sync field-level changes to the database
        */
@@ -4672,11 +4739,13 @@ var init_BaseModel = __esm({
         Logger.verbose(
           `[${modelName}] Setting up nested YMap observer for record ${recordId}`
         );
+        modelConstructor.attachStringSetObserversToRecord(recordYMap, schema);
         recordYMap.observe(async (event) => {
           Logger.verbose(
             `[${modelName}] Nested YMap change detected for record ${recordId}:`,
             event
           );
+          modelConstructor.attachStringSetObserversToRecord(recordYMap, schema);
           const currentDbInstance = _BaseModel.dbInstance;
           if (!currentDbInstance) {
             Logger.error(
@@ -4750,11 +4819,13 @@ var init_BaseModel = __esm({
         Logger.verbose(
           `[${modelName}] Setting up nested YMap observer for record ${recordId} in document ${docId}`
         );
+        modelConstructor.attachStringSetObserversToRecord(recordYMap, schema);
         recordYMap.observe(async (event) => {
           Logger.verbose(
             `[${modelName}] Nested YMap change detected for record ${recordId} in document ${docId}:`,
             event
           );
+          modelConstructor.attachStringSetObserversToRecord(recordYMap, schema);
           const currentDbInstance = _BaseModel.dbInstance;
           if (!currentDbInstance) {
             Logger.error(

package/dist/index.d.cts

@@ -488,6 +488,7 @@ declare class BaseModel implements StringSetChangeTracker {
         permissionHint: DocumentPermissionHint;
     }>;
     protected static documentYMaps: Map<string, Y.Map<any>>;
+    private static _observedStringSetMaps;
     private _localChanges;
     private _isDirty;
     private _isLoadingFromYjs;
@@ -562,7 +563,17 @@ declare class BaseModel implements StringSetChangeTracker {
         added: Record<string, any>;
         modified: Record<string, any>;
         removed: string[];
+        stringSetChanges: Record<string, {
+            additions: Set<string>;
+            removals: Set<string>;
+        }>;
     };
+    /**
+     * Apply a stringset change set to the parent record's Y.Map by mutating a
+     * nested Y.Map keyed by member. Migrates from a legacy plain-object value
+     * if the field hasn't been touched since the wire-format change in #561.
+     */
+    private applyStringSetChangeToYMap;
     /**
      * Deep equality check for comparing field values
      */
@@ -664,6 +675,20 @@ declare class BaseModel implements StringSetChangeTracker {
      * Execute a callback with automatic transaction handling for all modified models
      */
     static withTransaction<T>(callback: () => Promise<T> | T): Promise<T>;
+    /**
+     * Attach a one-shot observer to a nested-Y.Map stringset field. Calls
+     * notifyListeners() when the nested map's keys change (i.e. when a remote
+     * member arrives via Y.applyUpdate, or a local per-member set/delete).
+     * Idempotent — re-calling on the same Y.Map is a no-op.
+     */
+    protected static observeStringSetMapOnce(nestedMap: Y.Map<any>): void;
+    /**
+     * Walk the schema's stringset fields on `recordYMap` and observe any nested
+     * Y.Map values. Called from observer setup and from the parent observer body
+     * so newly-arrived stringset Y.Maps (local migration or remote create) get
+     * an observer too.
+     */
+    protected static attachStringSetObserversToRecord(recordYMap: Y.Map<any>, schema: any): void;
     /**
      * Sets up deep observation on a nested YMap to sync field-level changes to the database
      */

package/dist/index.d.ts

@@ -488,6 +488,7 @@ declare class BaseModel implements StringSetChangeTracker {
         permissionHint: DocumentPermissionHint;
     }>;
     protected static documentYMaps: Map<string, Y.Map<any>>;
+    private static _observedStringSetMaps;
     private _localChanges;
     private _isDirty;
     private _isLoadingFromYjs;
@@ -562,7 +563,17 @@ declare class BaseModel implements StringSetChangeTracker {
         added: Record<string, any>;
         modified: Record<string, any>;
         removed: string[];
+        stringSetChanges: Record<string, {
+            additions: Set<string>;
+            removals: Set<string>;
+        }>;
     };
+    /**
+     * Apply a stringset change set to the parent record's Y.Map by mutating a
+     * nested Y.Map keyed by member. Migrates from a legacy plain-object value
+     * if the field hasn't been touched since the wire-format change in #561.
+     */
+    private applyStringSetChangeToYMap;
     /**
      * Deep equality check for comparing field values
      */
@@ -664,6 +675,20 @@ declare class BaseModel implements StringSetChangeTracker {
      * Execute a callback with automatic transaction handling for all modified models
      */
     static withTransaction<T>(callback: () => Promise<T> | T): Promise<T>;
+    /**
+     * Attach a one-shot observer to a nested-Y.Map stringset field. Calls
+     * notifyListeners() when the nested map's keys change (i.e. when a remote
+     * member arrives via Y.applyUpdate, or a local per-member set/delete).
+     * Idempotent — re-calling on the same Y.Map is a no-op.
+     */
+    protected static observeStringSetMapOnce(nestedMap: Y.Map<any>): void;
+    /**
+     * Walk the schema's stringset fields on `recordYMap` and observe any nested
+     * Y.Map values. Called from observer setup and from the parent observer body
+     * so newly-arrived stringset Y.Maps (local migration or remote create) get
+     * an observer too.
+     */
+    protected static attachStringSetObserversToRecord(recordYMap: Y.Map<any>, schema: any): void;
     /**
      * Sets up deep observation on a nested YMap to sync field-level changes to the database
      */