js-bao 0.4.0 → 0.4.2

package/dist/codegen-v2.d.cts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/codegen.cjs

@@ -1181,7 +1181,7 @@ var SchemaExtractor = class {
 // package.json
 var package_default = {
   name: "js-bao",
-  version: "0.4.0",
+  version: "0.4.2",
   description: "A library providing data modeling capabilities which support live updates and queries.",
   types: "dist/index.d.ts",
   type: "module",
@@ -1232,10 +1232,12 @@ var package_default = {
   },
   bin: {
     "js-bao-codegen": "./dist/codegen.cjs",
-    "jsbao-codegen": "./dist/codegen.cjs"
+    "jsbao-codegen": "./dist/codegen.cjs",
+    "js-bao-codegen-v2": "./dist/codegen-v2.cjs",
+    "jsbao-codegen-v2": "./dist/codegen-v2.cjs"
   },
   scripts: {
-    build: "pnpm build:cli && pnpm codegen && rm -f dist/index.* dist/node.* dist/browser.* dist/cloudflare.* dist/cloudflare-do.* dist/client.* && pnpm build:main",
+    build: "pnpm build:cli && pnpm build:cli-v2 && pnpm codegen && rm -f dist/index.* dist/node.* dist/browser.* dist/cloudflare.* dist/cloudflare-do.* dist/client.* && pnpm build:main",
     "build:main": "pnpm build:browser && pnpm build:node && pnpm build:universal && pnpm build:cloudflare && pnpm build:cloudflare-do && pnpm build:client",
     "build:browser": "tsup src/browser.ts --format esm,cjs --dts --platform browser --external better-sqlite3 --external sql.js --external async-mutex --external ulid --external yjs --external fs --no-splitting",
     "build:node": "tsup src/node.ts --format esm,cjs --dts --platform node --external better-sqlite3 --external sql.js --external async-mutex --external ulid --external yjs --no-splitting",
@@ -1244,6 +1246,7 @@ var package_default = {
     "build:cloudflare-do": "tsup src/cloudflare-do.ts --format esm,cjs --dts --platform neutral --external better-sqlite3 --external sql.js --external async-mutex --external ulid --external yjs --external fs --no-splitting",
     "build:client": "tsup src/client.ts --format esm,cjs --dts --platform browser --external better-sqlite3 --external sql.js --external async-mutex --external ulid --external yjs --external fs --no-splitting",
     "build:cli": "tsup src/cli/codegen.ts --format cjs --dts --platform node --target node18 --external commander --external typescript --external fs --external path --external util --no-splitting",
+    "build:cli-v2": "tsup src/cli/codegen-v2.ts --format cjs --dts --platform node --target node18 --external commander --external typescript --external fs --external path --external util --no-splitting",
     dev: 'pnpm build:cli && concurrently "pnpm codegen:watch" "pnpm dev:main"',
     "dev:main": 'concurrently "pnpm build:browser:dev --watch" "pnpm build:node:dev --watch" "pnpm build:universal:dev --watch"',
     "dev:simple": "pnpm build:cli && pnpm codegen && pnpm build:main --watch",
@@ -1297,13 +1300,7 @@ var package_default = {
     "workers"
   ],
   author: "Primitive LLC",
-  license: "UNLICENSED",
-  pnpm: {
-    onlyBuiltDependencies: [
-      "better-sqlite3",
-      "esbuild"
-    ]
-  }
+  license: "UNLICENSED"
 };
 
 // src/cli/codegen.ts

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;
@@ -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(
@@ -6901,6 +6972,7 @@ function defineModelSchema(input) {
   const { name, fields } = input;
   const options = {
     name,
+    className: input.options?.className,
     uniqueConstraints: input.options?.uniqueConstraints ? [...input.options.uniqueConstraints] : void 0,
     relationships: input.options?.relationships
   };
@@ -7000,18 +7072,13 @@ function resolveUniqueConstraints(modelName, fields, customConstraints) {
 function attachSchemaToClass(modelClass, schema) {
   modelClass.schema = schema;
   modelClass.modelName = schema.options.name;
-  if (!modelClass.getSchema) {
-    Object.defineProperty(modelClass, "getSchema", {
-      value: function() {
-        return schema.buildRuntimeShape(modelClass);
-      },
-      writable: false
-    });
-  } else {
-    modelClass.getSchema = function() {
+  Object.defineProperty(modelClass, "getSchema", {
+    value: function() {
       return schema.buildRuntimeShape(modelClass);
-    };
-  }
+    },
+    writable: false,
+    configurable: true
+  });
   const runtimeShape = schema.buildRuntimeShape(modelClass);
   BaseModel.attachFieldAccessors(modelClass, runtimeShape.fields);
   return runtimeShape;
@@ -7088,12 +7155,52 @@ var VALID_FIELD_TYPES = /* @__PURE__ */ new Set([
   "id",
   "stringset"
 ]);
-function parseFieldOptions(raw) {
+var KNOWN_FIELD_KEYS = /* @__PURE__ */ new Set([
+  "type",
+  "indexed",
+  "unique",
+  "required",
+  "auto_assign",
+  "max_length",
+  "max_count",
+  "default"
+]);
+var KNOWN_MODEL_KEYS = /* @__PURE__ */ new Set([
+  "fields",
+  "relationships",
+  "unique_constraints",
+  "class_name"
+]);
+var KNOWN_RELATIONSHIP_KEYS = /* @__PURE__ */ new Set([
+  "type",
+  "model",
+  "related_id_field",
+  "join_model",
+  "join_model_local_field",
+  "join_model_related_field",
+  "order_by_field",
+  "order_direction",
+  "join_model_order_by_field",
+  "join_model_order_direction"
+]);
+var KNOWN_UNIQUE_CONSTRAINT_KEYS = /* @__PURE__ */ new Set(["name", "fields"]);
+function checkUnknownKeys(raw, known, context, strict) {
+  if (!strict) return;
+  for (const key of Object.keys(raw)) {
+    if (!known.has(key)) {
+      throw new Error(
+        `${context}: unknown key "${key}". Allowed: ${[...known].join(", ")}`
+      );
+    }
+  }
+}
+function parseFieldOptions(raw, context, strict) {
   if (!raw.type || !VALID_FIELD_TYPES.has(raw.type)) {
     throw new Error(
       `Invalid field type "${raw.type}". Must be one of: ${[...VALID_FIELD_TYPES].join(", ")}`
     );
   }
+  checkUnknownKeys(raw, KNOWN_FIELD_KEYS, context, strict);
   const opts = { type: raw.type };
   if (raw.indexed === true) opts.indexed = true;
   if (raw.unique === true) opts.unique = true;
@@ -7109,8 +7216,9 @@ function requireField(raw, field, context) {
     throw new Error(`Relationship ${context}: missing required field "${field}"`);
   }
 }
-function parseRelationship(raw) {
+function parseRelationship(raw, context, strict) {
   const type = raw.type;
+  checkUnknownKeys(raw, KNOWN_RELATIONSHIP_KEYS, context, strict);
   if (type === "refersTo") {
     requireField(raw, "model", "refersTo");
     requireField(raw, "related_id_field", "refersTo");
@@ -7152,7 +7260,8 @@ function parseRelationship(raw) {
   }
   throw new Error(`Unknown relationship type: ${type}`);
 }
-function loadSchemaFromTomlString(tomlString) {
+function loadSchemaFromTomlString(tomlString, options = {}) {
+  const strict = options.strict !== false;
   const parsed = (0, import_smol_toml.parse)(tomlString);
   const models = parsed.models;
   if (!models || typeof models !== "object") {
@@ -7160,10 +7269,20 @@ function loadSchemaFromTomlString(tomlString) {
   }
   const schemas = [];
   for (const [modelName, modelDef] of Object.entries(models)) {
+    checkUnknownKeys(
+      modelDef,
+      KNOWN_MODEL_KEYS,
+      `[models.${modelName}]`,
+      strict
+    );
     const fields = {};
     if (modelDef.fields) {
       for (const [fieldName, fieldDef] of Object.entries(modelDef.fields)) {
-        fields[fieldName] = parseFieldOptions(fieldDef);
+        fields[fieldName] = parseFieldOptions(
+          fieldDef,
+          `[models.${modelName}.fields.${fieldName}]`,
+          strict
+        );
       }
     }
     let relationships;
@@ -7172,24 +7291,36 @@ function loadSchemaFromTomlString(tomlString) {
       for (const [relName, relDef] of Object.entries(
         modelDef.relationships
       )) {
-        relationships[relName] = parseRelationship(relDef);
+        relationships[relName] = parseRelationship(
+          relDef,
+          `[models.${modelName}.relationships.${relName}]`,
+          strict
+        );
       }
     }
     let uniqueConstraints;
     if (modelDef.unique_constraints) {
       uniqueConstraints = [];
       for (const raw of modelDef.unique_constraints) {
+        checkUnknownKeys(
+          raw,
+          KNOWN_UNIQUE_CONSTRAINT_KEYS,
+          `[[models.${modelName}.unique_constraints]]`,
+          strict
+        );
         uniqueConstraints.push({
           name: raw.name,
           fields: [...raw.fields]
         });
       }
     }
+    const className = typeof modelDef.class_name === "string" ? modelDef.class_name : void 0;
     schemas.push(
       defineModelSchema({
         name: modelName,
         fields,
         options: {
+          className,
           uniqueConstraints,
           relationships
         }
@@ -7198,10 +7329,10 @@ function loadSchemaFromTomlString(tomlString) {
   }
   return schemas;
 }
-async function loadSchemaFromToml(filePath) {
+async function loadSchemaFromToml(filePath, options = {}) {
   const { readFile } = await import("fs/promises");
   const content = await readFile(filePath, "utf-8");
-  return loadSchemaFromTomlString(content);
+  return loadSchemaFromTomlString(content, options);
 }
 
 // src/utils/yDocSchema.ts

package/dist/index.d.cts

@@ -40,6 +40,13 @@ interface UniqueConstraintConfig {
 }
 interface ModelOptions {
     name: string;
+    /**
+     * Optional PascalCase class name. Used by the v2 codegen to drive
+     * generated TypeScript class names (and relationship method names that
+     * derive from a target's class name). When absent, the v2 codegen
+     * falls back to suffix-based singularization of `name`.
+     */
+    className?: string;
     uniqueConstraints?: UniqueConstraintConfig[];
     relationships?: Record<string, RelationshipConfig>;
 }
@@ -481,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;
@@ -555,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
      */
@@ -657,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
      */
@@ -847,15 +879,27 @@ declare function syncInferredMeta(yDoc: Y.Doc, modelName: string, recordData: Re
  *  - Compound unique constraints are [[models.*.unique_constraints]]
  */
 
+interface LoadSchemaOptions {
+    /**
+     * When true (default), throw on unknown keys at the model, field,
+     * relationship, and unique-constraint level. When false, unknown
+     * keys are silently ignored (legacy behavior).
+     */
+    strict?: boolean;
+}
 /**
  * Parse a TOML string and return an array of DefinedModelSchema objects.
+ *
+ * By default operates in strict mode: unknown keys at the model, field,
+ * relationship, or unique-constraint level cause an error. Pass
+ * `{ strict: false }` to silently ignore unknown keys (legacy behavior).
  */
-declare function loadSchemaFromTomlString(tomlString: string): DefinedModelSchema[];
+declare function loadSchemaFromTomlString(tomlString: string, options?: LoadSchemaOptions): DefinedModelSchema[];
 /**
  * Read a TOML file from disk and return an array of DefinedModelSchema objects.
  * Only available in Node.js environments.
  */
-declare function loadSchemaFromToml(filePath: string): Promise<DefinedModelSchema[]>;
+declare function loadSchemaFromToml(filePath: string, options?: LoadSchemaOptions): Promise<DefinedModelSchema[]>;
 
 /**
  * YDoc Schema Discovery

package/dist/index.d.ts

@@ -40,6 +40,13 @@ interface UniqueConstraintConfig {
 }
 interface ModelOptions {
     name: string;
+    /**
+     * Optional PascalCase class name. Used by the v2 codegen to drive
+     * generated TypeScript class names (and relationship method names that
+     * derive from a target's class name). When absent, the v2 codegen
+     * falls back to suffix-based singularization of `name`.
+     */
+    className?: string;
     uniqueConstraints?: UniqueConstraintConfig[];
     relationships?: Record<string, RelationshipConfig>;
 }
@@ -481,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;
@@ -555,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
      */
@@ -657,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
      */
@@ -847,15 +879,27 @@ declare function syncInferredMeta(yDoc: Y.Doc, modelName: string, recordData: Re
  *  - Compound unique constraints are [[models.*.unique_constraints]]
  */
 
+interface LoadSchemaOptions {
+    /**
+     * When true (default), throw on unknown keys at the model, field,
+     * relationship, and unique-constraint level. When false, unknown
+     * keys are silently ignored (legacy behavior).
+     */
+    strict?: boolean;
+}
 /**
  * Parse a TOML string and return an array of DefinedModelSchema objects.
+ *
+ * By default operates in strict mode: unknown keys at the model, field,
+ * relationship, or unique-constraint level cause an error. Pass
+ * `{ strict: false }` to silently ignore unknown keys (legacy behavior).
  */
-declare function loadSchemaFromTomlString(tomlString: string): DefinedModelSchema[];
+declare function loadSchemaFromTomlString(tomlString: string, options?: LoadSchemaOptions): DefinedModelSchema[];
 /**
  * Read a TOML file from disk and return an array of DefinedModelSchema objects.
  * Only available in Node.js environments.
  */
-declare function loadSchemaFromToml(filePath: string): Promise<DefinedModelSchema[]>;
+declare function loadSchemaFromToml(filePath: string, options?: LoadSchemaOptions): Promise<DefinedModelSchema[]>;
 
 /**
  * YDoc Schema Discovery