@carbonenginejs/runtime-utils 0.1.1 → 0.1.3

package/src/schema/CjsSchema.js

@@ -1,8 +1,20 @@
-const CLASS_SCHEMA = new WeakMap();
-const CONSTRUCTOR_BY_NAME = new Map();
-const ENUM_SCHEMA_BY_NAME = new Map();
-const ENUM_SCHEMA_BY_OBJECT = new WeakMap();
-const STAGE3_FIELD_METADATA = Symbol("carbonenginejs.schema.stage3Fields");
+const CLASS_SCHEMA = new WeakMap();
+
+// Exported schemas, memoized per class. SCHEMA_GENERATION is bumped by every
+// metadata definition (see getOrCreateClassSchema), which is what makes a stale
+// memo detectable without tracking which subclasses a base class change reaches.
+const SCHEMA_EXPORTS = new WeakMap();
+let SCHEMA_GENERATION = 0;
+
+const CONSTRUCTOR_BY_NAME = new Map();
+const ENUM_SCHEMA_BY_NAME = new Map();
+const ENUM_SCHEMA_BY_OBJECT = new WeakMap();
+const STAGE3_FIELD_METADATA = Symbol("carbonenginejs.schema.stage3Fields");
+
+// Declared here rather than beside describeDecorator: the CjsSchema class body
+// builds every decorator namespace in its static initializer, which runs before
+// any const declared after the class is initialized.
+const DECORATOR_METADATA = Symbol("carbonenginejs.schema.decoratorMetadata");
 
 export const CJS_ENUM_NAME = Symbol.for("carbonenginejs.enum.name");
 
@@ -56,32 +68,32 @@ export class CjsSchema
         return this;
     }
 
-    static defineMethod(Constructor, methodName, namespace, value)
-    {
-        defineMethodMetadata(Constructor, methodName, namespace, value);
-        return this;
-    }
-
-    static getField(Constructor, fieldName)
-    {
-        return getEffectiveFields(Constructor).find(field => field.name === fieldName) || null;
-    }
-
-    /**
-     * Excludes named inherited fields from the decorated class's schema surface.
-     */
-    static hideInherited(fieldNames)
-    {
-        return hiddenInheritedFieldsDecorator(normalizeHiddenInheritedFields(fieldNames));
-    }
-
-    /**
-     * Checks whether a field is hidden from a class by its inheritance chain.
-     */
-    static isFieldHidden(Constructor, fieldName)
-    {
-        return getHiddenInheritedFieldNames(Constructor).has(fieldName);
-    }
+    static defineMethod(Constructor, methodName, namespace, value)
+    {
+        defineMethodMetadata(Constructor, methodName, namespace, value);
+        return this;
+    }
+
+    static getField(Constructor, fieldName)
+    {
+        return getEffectiveFields(Constructor).find(field => field.name === fieldName) || null;
+    }
+
+    /**
+     * Excludes named inherited fields from the decorated class's schema surface.
+     */
+    static hideInherited(fieldNames)
+    {
+        return hiddenInheritedFieldsDecorator(normalizeHiddenInheritedFields(fieldNames));
+    }
+
+    /**
+     * Checks whether a field is hidden from a class by its inheritance chain.
+     */
+    static isFieldHidden(Constructor, fieldName)
+    {
+        return getHiddenInheritedFieldNames(Constructor).has(fieldName);
+    }
 
     static getMethod(Constructor, methodName)
     {
@@ -128,6 +140,9 @@ export class CjsSchema
         }
 
         CONSTRUCTOR_BY_NAME.set(name.trim(), Constructor);
+        // Buckets resolve class references by name, so a late registration
+        // changes how already-built schemas should have been bucketed.
+        SCHEMA_GENERATION += 1;
         return this;
     }
 
@@ -151,49 +166,40 @@ export class CjsSchema
         return name ? ENUM_SCHEMA_BY_NAME.get(name) || null : null;
     }
 
-    static getSchema(Constructor, options = {})
-    {
-        const schema = CLASS_SCHEMA.get(Constructor);
-        const namespaces = normalizeNamespaces(options.namespaces);
-        const fields = [];
-        const methods = [];
-
-        for (const field of getEffectiveFields(Constructor))
-        {
-            fields.push(enrichEnumField(exportField(field, namespaces), Constructor));
-        }
-
-        for (const method of schema?.methods || [])
-        {
-            methods.push(exportField(method, namespaces));
-        }
-
-        const result = {
-            className: CjsSchema.getClassName(Constructor),
-            fields: Object.freeze(fields)
-        };
-
-        const family = schema?.family || CjsSchema.getClassFamily(Constructor);
-        if (family)
-        {
-            result.family = family;
-        }
-
-        if (schema?.sourceClass && schema.sourceClass !== result.className)
-        {
-            result.sourceClass = schema.sourceClass;
-        }
-
-        if (schema?.aliases?.length)
-        {
-            result.aliases = Object.freeze([...schema.aliases]);
-        }
+    /**
+     * Return the exported schema for a class.
+     *
+     * The schema is the precomputed answer - collapsing the inheritance
+     * lineage and merging metadata - so building it per call would defeat its
+     * purpose. Callers traverse model graphs and ask once per node, so this is
+     * memoized per class and rebuilt only when class metadata is defined.
+     *
+     * Namespace-filtered exports are not memoized: they are a projection of the
+     * full schema requested by tooling, not the hot read path.
+     *
+     * The result is shared, not copied - treat it as read-only. It is not
+     * frozen: deep-cloning and freezing every field on the way out cost far
+     * more than the mistakes it guarded against.
+     *
+     * @param {Function} Constructor
+     * @param {object} [options={}]
+     * @param {string|Array<string>} [options.namespaces] Restricts exported metadata namespaces.
+     * @returns {object} Shared schema export.
+     */
+    static getSchema(Constructor, options = {})
+    {
+        const namespaces = normalizeNamespaces(options.namespaces);
+        if (namespaces) return buildSchema(Constructor, namespaces);
 
-        if (methods.length) result.methods = Object.freeze(methods);
+        const memo = SCHEMA_EXPORTS.get(Constructor);
+        if (memo && memo.generation === SCHEMA_GENERATION) return memo.schema;
 
-        return Object.freeze(result);
+        const schema = buildSchema(Constructor, null);
+        SCHEMA_EXPORTS.set(Constructor, { generation: SCHEMA_GENERATION, schema });
+        return schema;
     }
 
+
     static type = Object.freeze({
         array: itemType => fieldDecorator("type", { kind: "array", itemType }),
         boolean: fieldDecorator("type", { kind: "boolean" }),
@@ -307,7 +313,8 @@ export class CjsSchema
                 contextual: true,
                 contextTiers: Object.freeze(normalized)
             });
-            return function contextualMethodDecorator(targetOrValue, contextOrMethodName)
+            const described = getDecoratorMetadata(base);
+            return describeDecorator(function contextualMethodDecorator(targetOrValue, contextOrMethodName)
             {
                 // Contextual methods are validated context-first at decoration
                 // time: the first declared parameter must be the frame context.
@@ -320,7 +327,7 @@ export class CjsSchema
                     assertContextFirstMethod(targetOrValue[contextOrMethodName], contextOrMethodName);
                 }
                 return base(targetOrValue, contextOrMethodName);
-            };
+            }, described.namespace, described.value);
         }
     });
 
@@ -338,22 +345,46 @@ function createComponentsNamespace()
     return Object.freeze(components);
 }
 
-function fieldDecorator(namespace, value)
-{
-    return function schemaFieldDecorator(targetOrValue, contextOrFieldName)
-    {
-        if (contextOrFieldName && typeof contextOrFieldName === "object")
-        {
-            const context = contextOrFieldName;
-            if (context.kind !== "field") throw new TypeError("CjsSchema decorators only support class fields.");
-            recordStage3FieldMetadata(context, namespace, value);
-
-            // Register field metadata on instance construction. addInitializer covers
-            // spec-compliant runtimes; the returned field initializer covers runtimes (e.g.
-            // Deno/SWC) that do NOT fire field-decorator addInitializer. Both register the same
-            // metadata (idempotent via mergeNamespace), so whichever the runtime honours, the
-            // schema is populated. Registration is lazy (first construction); the class decorator
-            // still registers the class eagerly at definition time.
+// Every decorator carries the namespace and value it would install. That is
+// what lets one vocabulary serve both forms: `type.uint32` applied as a
+// decorator, and `type.uint32` written as data in a CjsSchema.define() member.
+// Without it the object form would need its own spelling of every namespace
+// value, and two spellings of `impl.adapted` will eventually disagree.
+function describeDecorator(decorator, namespace, value)
+{
+    Object.defineProperty(decorator, DECORATOR_METADATA, {
+        value: { namespace, value }
+    });
+    return decorator;
+}
+
+/**
+ * The namespace/value a decorator installs, or null when it is not one.
+ *
+ * @param {*} candidate Possible decorator.
+ * @returns {{namespace:string, value:*}|null} Installed metadata.
+ */
+function getDecoratorMetadata(candidate)
+{
+    return typeof candidate === "function" ? candidate[DECORATOR_METADATA] || null : null;
+}
+
+function fieldDecorator(namespace, value)
+{
+    return describeDecorator(function schemaFieldDecorator(targetOrValue, contextOrFieldName)
+    {
+        if (contextOrFieldName && typeof contextOrFieldName === "object")
+        {
+            const context = contextOrFieldName;
+            if (context.kind !== "field") throw new TypeError("CjsSchema decorators only support class fields.");
+            recordStage3FieldMetadata(context, namespace, value);
+
+            // The class decorator replays the Stage-3 metadata recorded above, so
+            // schema inspection works before the first instance is constructed.
+            // Keep both runtime initializers as fallbacks: addInitializer covers
+            // spec-compliant runtimes, while the returned field initializer covers
+            // runtimes that do not fire field-decorator addInitializer. All paths
+            // register the same metadata idempotently through mergeNamespace.
             context.addInitializer(function initializeSchemaField()
             {
                 defineFieldMetadata(this.constructor, context.name, namespace, value);
@@ -373,47 +404,47 @@ function fieldDecorator(namespace, value)
         }
 
         defineFieldMetadata(Constructor, contextOrFieldName, namespace, value);
-    };
+    }, namespace, value);
 }
 
-function classDefinitionDecorator(definition)
-{
-    return function schemaClassDefinitionDecorator(value, context)
-    {
-        if (context && typeof context === "object")
-        {
-            if (context.kind !== "class") throw new TypeError("CjsSchema type.define only supports classes.");
-            registerStage3FieldMetadata(value, context.metadata);
-            defineClassMetadata(value, normalizeClassDefinition(value, definition));
-            return;
-        }
+function classDefinitionDecorator(definition)
+{
+    return function schemaClassDefinitionDecorator(value, context)
+    {
+        if (context && typeof context === "object")
+        {
+            if (context.kind !== "class") throw new TypeError("CjsSchema type.define only supports classes.");
+            registerStage3FieldMetadata(value, context.metadata);
+            defineClassMetadata(value, normalizeClassDefinition(value, definition));
+            return;
+        }
 
         if (typeof value !== "function")
         {
             throw new TypeError("CjsSchema type.define requires a class constructor.");
         }
 
-        defineClassMetadata(value, normalizeClassDefinition(value, definition));
-    };
-}
-
-function hiddenInheritedFieldsDecorator(fieldNames)
-{
-    return function schemaHiddenInheritedFieldsDecorator(value, context)
-    {
-        if (context && typeof context === "object")
-        {
-            if (context.kind !== "class") throw new TypeError("CjsSchema.hideInherited only supports classes.");
-            registerStage3FieldMetadata(value, context.metadata);
-        }
-        else if (typeof value !== "function")
-        {
-            throw new TypeError("CjsSchema.hideInherited requires a class constructor.");
-        }
-
-        defineHiddenInheritedFields(value, fieldNames);
-    };
-}
+        defineClassMetadata(value, normalizeClassDefinition(value, definition));
+    };
+}
+
+function hiddenInheritedFieldsDecorator(fieldNames)
+{
+    return function schemaHiddenInheritedFieldsDecorator(value, context)
+    {
+        if (context && typeof context === "object")
+        {
+            if (context.kind !== "class") throw new TypeError("CjsSchema.hideInherited only supports classes.");
+            registerStage3FieldMetadata(value, context.metadata);
+        }
+        else if (typeof value !== "function")
+        {
+            throw new TypeError("CjsSchema.hideInherited requires a class constructor.");
+        }
+
+        defineHiddenInheritedFields(value, fieldNames);
+    };
+}
 
 const CONTEXT_FIRST_PARAMETER = /^\(?\s*_?(context|updateContext)\b/;
 
@@ -436,7 +467,7 @@ function assertContextFirstMethod(fn, methodName)
 
 function methodDecorator(namespace, value)
 {
-    return function schemaMethodDecorator(targetOrValue, contextOrMethodName)
+    return describeDecorator(function schemaMethodDecorator(targetOrValue, contextOrMethodName)
     {
         if (contextOrMethodName && typeof contextOrMethodName === "object")
         {
@@ -458,14 +489,14 @@ function methodDecorator(namespace, value)
         }
 
         defineMethodMetadata(Constructor, contextOrMethodName, namespace, value);
-    };
+    }, namespace, value);
 }
 
 function memberDecorator(namespace, value)
 {
     const forMethods = methodDecorator(namespace, value);
     const forFields = fieldDecorator(namespace, value);
-    return function schemaMemberDecorator(targetOrValue, contextOrMemberName)
+    return describeDecorator(function schemaMemberDecorator(targetOrValue, contextOrMemberName)
     {
         if (contextOrMemberName && typeof contextOrMemberName === "object")
         {
@@ -479,7 +510,7 @@ function memberDecorator(namespace, value)
         return targetOrValue && contextOrMemberName && typeof targetOrValue[contextOrMemberName] === "function"
             ? forMethods(targetOrValue, contextOrMemberName)
             : forFields(targetOrValue, contextOrMemberName);
-    };
+    }, namespace, value);
 }
 
 function defineFieldMetadata(Constructor, fieldName, namespace, value)
@@ -523,10 +554,10 @@ function defineMethodMetadata(Constructor, methodName, namespace, value)
     defineMemberMetadata(Constructor, "methods", "methodsByName", methodName, namespace, value);
 }
 
-function defineMemberMetadata(Constructor, listKey, mapKey, name, namespace, value)
-{
-    const schema = getOrCreateClassSchema(Constructor);
-    let item = schema[mapKey].get(name);
+function defineMemberMetadata(Constructor, listKey, mapKey, name, namespace, value)
+{
+    const schema = getOrCreateClassSchema(Constructor);
+    let item = schema[mapKey].get(name);
 
     if (!item)
     {
@@ -534,188 +565,324 @@ function defineMemberMetadata(Constructor, listKey, mapKey, name, namespace, val
         schema[listKey].push(item);
         schema[mapKey].set(name, item);
     }
-
-    item[namespace] = mergeNamespace(item[namespace], value);
-}
-
-function defineHiddenInheritedFields(Constructor, fieldNames)
-{
-    if (typeof Constructor !== "function")
-    {
-        throw new TypeError("CjsSchema.hideInherited requires a class constructor.");
-    }
-
-    const Parent = Object.getPrototypeOf(Constructor);
-    const inheritedFields = new Set(getEffectiveFields(Parent).map(field => field.name));
-    const className = CLASS_SCHEMA.get(Constructor)?.className || Constructor.name || "<anonymous>";
-
-    for (const fieldName of fieldNames)
-    {
-        if (!inheritedFields.has(fieldName))
-        {
-            throw new TypeError(
-                `CjsSchema.hideInherited cannot hide "${fieldName}" on ${className}: ` +
-                "the parent schema does not expose that field."
-            );
-        }
-    }
-
-    const schema = getOrCreateClassSchema(Constructor);
-    for (const fieldName of fieldNames)
-    {
-        schema.hiddenInherited.add(fieldName);
-    }
-}
-
-function getEffectiveFields(Constructor)
-{
-    const ordered = [];
-    const byName = new Map();
-    const hidden = new Set();
-
-    for (const current of getSchemaLineage(Constructor))
-    {
-        const schema = CLASS_SCHEMA.get(current);
-        for (const field of schema?.fields || [])
-        {
-            const existing = byName.get(field.name);
-            if (existing)
-            {
-                mergeMemberMetadata(existing, field);
-            }
-            else
-            {
-                const merged = mergeMemberMetadata({ name: field.name }, field);
-                ordered.push(merged);
-                byName.set(field.name, merged);
-            }
-        }
-
-        for (const fieldName of schema?.hiddenInherited || [])
-        {
-            hidden.add(fieldName);
-        }
-    }
-
-    return ordered.filter(field => !hidden.has(field.name));
-}
-
-function getHiddenInheritedFieldNames(Constructor)
-{
-    const hidden = new Set();
-    for (const current of getSchemaLineage(Constructor))
-    {
-        for (const fieldName of CLASS_SCHEMA.get(current)?.hiddenInherited || [])
-        {
-            hidden.add(fieldName);
-        }
-    }
-    return hidden;
-}
-
-function getSchemaLineage(Constructor)
-{
-    const lineage = [];
-    let current = Constructor;
-    while (typeof current === "function")
-    {
-        if (CLASS_SCHEMA.has(current)) lineage.push(current);
-        current = Object.getPrototypeOf(current);
-    }
-    return lineage.reverse();
-}
-
-function mergeMemberMetadata(target, source)
-{
-    for (const [namespace, value] of Object.entries(source))
-    {
-        if (namespace === "name") continue;
-        target[namespace] = mergeNamespace(target[namespace], value);
-    }
-    return target;
-}
-
-function getOrCreateClassSchema(Constructor)
-{
-    let schema = CLASS_SCHEMA.get(Constructor);
-    if (!schema)
+
+    item[namespace] = mergeNamespace(item[namespace], value);
+}
+
+function defineHiddenInheritedFields(Constructor, fieldNames)
+{
+    if (typeof Constructor !== "function")
+    {
+        throw new TypeError("CjsSchema.hideInherited requires a class constructor.");
+    }
+
+    const Parent = Object.getPrototypeOf(Constructor);
+    const inheritedFields = new Set(getEffectiveFields(Parent).map(field => field.name));
+    // Declared name only: Constructor.name does not survive minification, and a
+    // mangled name in an error reads as a real one and sends you chasing it.
+    const className = CLASS_SCHEMA.get(Constructor)?.className || "<undeclared>";
+
+    for (const fieldName of fieldNames)
+    {
+        if (!inheritedFields.has(fieldName))
+        {
+            throw new TypeError(
+                `CjsSchema.hideInherited cannot hide "${fieldName}" on ${className}: ` +
+                "the parent schema does not expose that field."
+            );
+        }
+    }
+
+    const schema = getOrCreateClassSchema(Constructor);
+    for (const fieldName of fieldNames)
+    {
+        schema.hiddenInherited.add(fieldName);
+    }
+}
+
+function getEffectiveFields(Constructor)
+{
+    const ordered = [];
+    const byName = new Map();
+    const hidden = new Set();
+
+    for (const current of getSchemaLineage(Constructor))
+    {
+        const schema = CLASS_SCHEMA.get(current);
+        for (const field of schema?.fields || [])
+        {
+            const existing = byName.get(field.name);
+            if (existing)
+            {
+                mergeMemberMetadata(existing, field);
+            }
+            else
+            {
+                const merged = mergeMemberMetadata({ name: field.name }, field);
+                ordered.push(merged);
+                byName.set(field.name, merged);
+            }
+        }
+
+        for (const fieldName of schema?.hiddenInherited || [])
+        {
+            hidden.add(fieldName);
+        }
+    }
+
+    return ordered.filter(field => !hidden.has(field.name));
+}
+
+function getHiddenInheritedFieldNames(Constructor)
+{
+    const hidden = new Set();
+    for (const current of getSchemaLineage(Constructor))
+    {
+        for (const fieldName of CLASS_SCHEMA.get(current)?.hiddenInherited || [])
+        {
+            hidden.add(fieldName);
+        }
+    }
+    return hidden;
+}
+
+function getSchemaLineage(Constructor)
+{
+    const lineage = [];
+    let current = Constructor;
+    while (typeof current === "function")
+    {
+        if (CLASS_SCHEMA.has(current)) lineage.push(current);
+        current = Object.getPrototypeOf(current);
+    }
+    return lineage.reverse();
+}
+
+function mergeMemberMetadata(target, source)
+{
+    for (const [namespace, value] of Object.entries(source))
+    {
+        if (namespace === "name") continue;
+        target[namespace] = mergeNamespace(target[namespace], value);
+    }
+    return target;
+}
+
+function buildSchema(Constructor, namespaces)
+{
+    const schema = CLASS_SCHEMA.get(Constructor);
+    const fields = [];
+    const methods = [];
+
+    for (const field of getEffectiveFields(Constructor))
+    {
+        fields.push(enrichEnumField(exportField(field, namespaces), Constructor));
+    }
+
+    // KNOWN DEFECT: methods are read from this class only, while fields resolve
+    // through the whole lineage above. A subclass therefore reports no inherited
+    // methods, and the decorated form hides that behind a second bug that
+    // cancels it out: method decorators register through addInitializer, where
+    // `this.constructor` is the *instance's* class, so constructing one
+    // Tr2LightProfileRes writes CjsResource's methods onto Tr2LightProfileRes.
+    // Which class owns which methods then depends on construction order, and
+    // before any instance exists a class reports no methods at all.
+    //
+    // Declaring metadata as data (CjsSchema.define fields/methods) registers on
+    // the declaring class at module load, so it is deterministic - and it makes
+    // the missing inheritance visible rather than accidentally papered over.
+    //
+    // Left unfixed deliberately: nothing reads .methods off a runtime schema
+    // today (tools-core classTool parses source documents, not these), and the
+    // fix - walking the lineage here as getEffectiveFields does - changes
+    // exported schemas for every decorator-using class in the org.
+    for (const method of schema?.methods || [])
+    {
+        methods.push(exportField(method, namespaces));
+    }
+
+    const result = {
+        className: CjsSchema.getClassName(Constructor),
+        fields
+    };
+
+    const family = schema?.family || CjsSchema.getClassFamily(Constructor);
+    if (family)
+    {
+        result.family = family;
+    }
+
+    if (schema?.sourceClass && schema.sourceClass !== result.className)
+    {
+        result.sourceClass = schema.sourceClass;
+    }
+
+    if (schema?.aliases?.length)
+    {
+        result.aliases = [ ...schema.aliases ];
+    }
+
+    if (methods.length) result.methods = methods;
+
+    addSchemaBuckets(result);
+    return result;
+}
+
+
+// Kinds that hold many values rather than one. `map` and `set` are included
+// because they are iterable collections of the referenced class, same as a list.
+const MANY_KINDS = new Set([ "list", "array", "set", "map" ]);
+
+// Kinds that can hold a child model. Bucketing on the KIND rather than on a
+// resolvable class reference keeps traversal conservative: `type.struct(Class)`
+// drops the reference during normalization, and a raw defineField may omit the
+// item type, so requiring a reference would silently stop visiting those.
+// Scalar and math kinds are excluded, which is where the saving comes from.
+const MODEL_KINDS = new Set([
+    "struct", "model", "rawStruct", "objectRef", "unknown",
+    "list", "array", "set", "map"
+]);
+
+
+/**
+ * Precompute the answers consumers would otherwise recompute per traversal.
+ *
+ * Graph walks ask the same two questions of every node - which fields hold
+ * child models, which hold resources - and answering them by scanning the field
+ * list and type-testing each value costs more than the walk itself. The class
+ * cannot change without rebuilding its schema, so this is solved once.
+ */
+function addSchemaBuckets(schema)
+{
+    const byName = new Map();
+    const children = [];
+    const resources = [];
+
+    for (const field of schema.fields)
+    {
+        byName.set(field.name, field);
+
+        const type = field.type;
+        // An undeclared field could hold anything, so it stays traversable.
+        const kind = type?.kind;
+        if (kind && !MODEL_KINDS.has(kind)) continue;
+
+        const entry = { name: field.name, many: MANY_KINDS.has(kind) };
+
+        if (type && resolveFieldClass(type)?.isResource === true)
+        {
+            resources.push(entry);
+            continue;
+        }
+
+        entry.owned = field.io?.ownership === "owned";
+        children.push(entry);
+    }
+
+    schema.byName = byName;
+    schema.children = children;
+    schema.resources = resources;
+}
+
+
+// Only string references survive normalization - type.struct(SomeClass) drops
+// the reference entirely - so a field can only be bucketed when it names a
+// class. The one field in the tree that named nothing was a missing
+// declaration, not a deliberate escape.
+function resolveFieldClass(type)
+{
+    const ref = type.className || type.itemType || type.valueType;
+    return typeof ref === "string" && ref ? CONSTRUCTOR_BY_NAME.get(ref) || null : null;
+}
+
+
+function getOrCreateClassSchema(Constructor)
+{
+    // The only route by which class metadata is mutated, and therefore the only
+    // place exported schemas can go stale. A single global counter rather than
+    // per-class invalidation because a base class change invalidates every
+    // subclass, and lineage is not tracked in reverse.
+    SCHEMA_GENERATION += 1;
+
+    let schema = CLASS_SCHEMA.get(Constructor);
+    if (!schema)
     {
         schema = {
             className: null,
             family: null,
             sourceClass: null,
-            aliases: null,
-            fields: [],
-            fieldsByName: new Map(),
-            hiddenInherited: new Set(),
-            methods: [],
-            methodsByName: new Map()
-        };
+            aliases: null,
+            fields: [],
+            fieldsByName: new Map(),
+            hiddenInherited: new Set(),
+            methods: [],
+            methodsByName: new Map()
+        };
         CLASS_SCHEMA.set(Constructor, schema);
     }
-    return schema;
-}
-
-function normalizeHiddenInheritedFields(fieldNames)
-{
-    if (!Array.isArray(fieldNames) || !fieldNames.length)
-    {
-        throw new TypeError("CjsSchema.hideInherited requires a non-empty array of field names.");
-    }
-
-    const normalized = fieldNames.map((fieldName, index) =>
-    {
-        if (typeof fieldName !== "string" || !fieldName.trim())
-        {
-            throw new TypeError(`CjsSchema.hideInherited fieldNames[${index}] must be a non-empty string.`);
-        }
-        return fieldName.trim();
-    });
-
-    return Object.freeze([...new Set(normalized)]);
-}
-
-function recordStage3FieldMetadata(context, namespace, value)
-{
-    const metadata = context?.metadata;
-    if (!metadata || typeof metadata !== "object") return;
-
-    let fields;
-    if (Object.prototype.hasOwnProperty.call(metadata, STAGE3_FIELD_METADATA))
-    {
-        fields = metadata[STAGE3_FIELD_METADATA];
-    }
-    else
-    {
-        fields = [];
-        Object.defineProperty(metadata, STAGE3_FIELD_METADATA, {
-            configurable: false,
-            enumerable: false,
-            value: fields,
-            writable: false
-        });
-    }
-
-    fields.push({
-        name: context.name,
-        namespace,
-        value
-    });
-}
-
-function registerStage3FieldMetadata(Constructor, metadata)
-{
-    if (!metadata || typeof metadata !== "object") return;
-    if (!Object.prototype.hasOwnProperty.call(metadata, STAGE3_FIELD_METADATA)) return;
-
-    for (const field of metadata[STAGE3_FIELD_METADATA])
-    {
-        defineFieldMetadata(Constructor, field.name, field.namespace, field.value);
-    }
-}
-
-function normalizeClassDefinition(Constructor, definition)
-{
+    return schema;
+}
+
+function normalizeHiddenInheritedFields(fieldNames)
+{
+    if (!Array.isArray(fieldNames) || !fieldNames.length)
+    {
+        throw new TypeError("CjsSchema.hideInherited requires a non-empty array of field names.");
+    }
+
+    const normalized = fieldNames.map((fieldName, index) =>
+    {
+        if (typeof fieldName !== "string" || !fieldName.trim())
+        {
+            throw new TypeError(`CjsSchema.hideInherited fieldNames[${index}] must be a non-empty string.`);
+        }
+        return fieldName.trim();
+    });
+
+    return Object.freeze([...new Set(normalized)]);
+}
+
+function recordStage3FieldMetadata(context, namespace, value)
+{
+    const metadata = context?.metadata;
+    if (!metadata || typeof metadata !== "object") return;
+
+    let fields;
+    if (Object.prototype.hasOwnProperty.call(metadata, STAGE3_FIELD_METADATA))
+    {
+        fields = metadata[STAGE3_FIELD_METADATA];
+    }
+    else
+    {
+        fields = [];
+        Object.defineProperty(metadata, STAGE3_FIELD_METADATA, {
+            configurable: false,
+            enumerable: false,
+            value: fields,
+            writable: false
+        });
+    }
+
+    fields.push({
+        name: context.name,
+        namespace,
+        value
+    });
+}
+
+function registerStage3FieldMetadata(Constructor, metadata)
+{
+    if (!metadata || typeof metadata !== "object") return;
+    if (!Object.prototype.hasOwnProperty.call(metadata, STAGE3_FIELD_METADATA)) return;
+
+    for (const field of metadata[STAGE3_FIELD_METADATA])
+    {
+        defineFieldMetadata(Constructor, field.name, field.namespace, field.value);
+    }
+}
+
+function normalizeClassDefinition(Constructor, definition)
+{
     if (typeof definition === "string")
     {
         definition = { className: definition };
@@ -740,27 +907,98 @@ function normalizeClassDefinition(Constructor, definition)
     return result;
 }
 
+/**
+ * Normalize a definition's `fields`/`methods` into internal member records.
+ *
+ * Two spellings are accepted. A name-keyed object is the one to write:
+ * declaration order is key order, which is what drives GetValues() export
+ * order, and the name appears once rather than as a property of its own record.
+ * The array of `{name, ...}` records predates it and still parses, because it
+ * is what the internal schema stores.
+ *
+ * @param {object|Array<object>|null} members Declared members.
+ * @param {string} memberType Either "fields" or "methods", for messages.
+ * @returns {Array<object>} Internal member records.
+ */
 function normalizeManualMembers(members, memberType)
 {
     if (members === undefined || members === null) return [];
-    if (!Array.isArray(members))
+
+    if (Array.isArray(members))
     {
-        throw new TypeError(`CjsSchema.define ${memberType} must be an array.`);
+        return members.map((member, index) =>
+        {
+            if (!isPlainObject(member) || typeof member.name !== "string" || !member.name.trim())
+            {
+                throw new TypeError(`CjsSchema.define ${memberType}[${index}] requires a non-empty name.`);
+            }
+            const { name, ...namespaces } = member;
+            return normalizeManualMember(name.trim(), namespaces, memberType);
+        });
+    }
+
+    if (!isPlainObject(members))
+    {
+        throw new TypeError(
+            `CjsSchema.define ${memberType} must be a name-keyed object or an array of named records.`
+        );
     }
 
-    return members.map((member, index) =>
+    return Object.entries(members).map(([ name, definition ]) =>
     {
-        if (!isPlainObject(member) || typeof member.name !== "string" || !member.name.trim())
+        if (!name.trim())
         {
-            throw new TypeError(`CjsSchema.define ${memberType}[${index}] requires a non-empty name.`);
+            throw new TypeError(`CjsSchema.define ${memberType} requires a non-empty name.`);
         }
-        return {
-            ...member,
-            name: member.name.trim()
-        };
+        return normalizeManualMember(name.trim(), definition, memberType);
     });
 }
 
+/**
+ * Collapse one member's declaration into a namespace map.
+ *
+ * A declaration is a decorator, a namespace object, or an array mixing both.
+ * Decorators are accepted as data so the object form reuses the vocabulary the
+ * decorators already define rather than restating it: `impl.adapted` written
+ * twice in two spellings is two things that can disagree.
+ *
+ * @param {string} name Member name.
+ * @param {*} definition Declared metadata.
+ * @param {string} memberType Either "fields" or "methods", for messages.
+ * @returns {object} Internal member record.
+ */
+function normalizeManualMember(name, definition, memberType)
+{
+    const member = { name };
+
+    for (const entry of Array.isArray(definition) ? definition : [ definition ])
+    {
+        if (entry === undefined || entry === null) continue;
+
+        const decorator = getDecoratorMetadata(entry);
+        if (decorator)
+        {
+            member[decorator.namespace] = mergeNamespace(member[decorator.namespace], decorator.value);
+            continue;
+        }
+
+        if (!isPlainObject(entry))
+        {
+            throw new TypeError(
+                `CjsSchema.define ${memberType} "${name}" accepts schema decorators, ` +
+                "namespace objects, or an array of them."
+            );
+        }
+
+        for (const [ namespace, value ] of Object.entries(entry))
+        {
+            member[namespace] = mergeNamespace(member[namespace], value);
+        }
+    }
+
+    return member;
+}
+
 function registerClassMetadata(Constructor, schema)
 {
     if (!Constructor || !schema?.className) return;
@@ -937,9 +1175,8 @@ function componentIndex(char)
 
 function mergeNamespace(existing, value)
 {
-    if (!existing) return cloneSchemaValue(value);
-    if (isPlainObject(existing) && isPlainObject(value)) return Object.freeze({ ...existing, ...value });
-    return cloneSchemaValue(value);
+    if (isPlainObject(existing) && isPlainObject(value)) return { ...existing, ...value };
+    return value;
 }
 
 // Resolves @schema.enum("X") through the owning class's PascalCase static so
@@ -984,10 +1221,10 @@ function exportField(field, namespaces)
     {
         if (key === "name") continue;
         if (namespaces && !namespaces.has(key)) continue;
-        result[key] = cloneSchemaValue(value);
+        result[key] = value;
     }
 
-    return Object.freeze(result);
+    return result;
 }
 
 function normalizeNamespaces(namespaces)