@carbonenginejs/runtime 0.1.0-alpha.2 → 0.1.0-alpha.4

package/dist/global/model/CjsModelState.js

@@ -9,15 +9,6 @@ import { RUNTIME_STATE_PROTOTYPE } from '../compose/runtimeState.js';
  *   pipeline is cooperative - anything mutating outside `SetValues`
  *   (direct writes, Object.assign, reader adapters) owes a `MarkDirty()`
  *   or an explicit `UpdateValues()` ("I made changes, apply please").
- * - `flags` holds lazy invalidations ("bounds is stale"). Written at
- *   mutation time from `@io.flag` field metadata or by class code; cleared
- *   ONLY by the getter that recomputes the derived value. Never
- *   auto-cleared - deferring until needed is their whole point.
- * - `rebuild` holds scheduled work requirements ("vertices need
- *   rebuilding"). Written at mutation time from `@io.rebuild` field
- *   metadata or by class code; cleared ONLY by the specific work method
- *   that succeeds (e.g. RebuildVertices), typically driven from Update /
- *   per-frame passes. Never auto-cleared.
  * - Future transient runtime state (lifecycle links, revision counters)
  *   lands here rather than growing new underscore properties.
  */
@@ -25,12 +16,6 @@ class CjsModelState {
   /** Something changed; the next settle applies it. @type {boolean} */
   dirty = false;
 
-  /** Lazy invalidations - consumers clear when they recompute. @type {Set<string>} */
-  flags = new Set();
-
-  /** Scheduled work requirements - work methods clear on success. @type {Set<string>} */
-  rebuild = new Set();
-
   /** Settle re-entrancy guard. @type {boolean} */
   updating = false;
 

package/dist/global/model/CjsModelState.js.map

@@ -1 +1 @@
-{"version":3,"file":"CjsModelState.js","sources":["../../../../src/global/model/CjsModelState.js"],"sourcesContent":["import { RUNTIME_STATE_PROTOTYPE } from \"../compose/runtimeState.js\";\r\n\r\n/**\r\n * Per-model runtime state. One instance per model at `__state`.\r\n *\r\n * Ownership and clearing rules (kb section 8):\r\n * - `dirty` is the only generically managed member: mutations mark it, and\r\n *   `UpdateValues` (the settle) is the only thing that clears it. The\r\n *   pipeline is cooperative - anything mutating outside `SetValues`\r\n *   (direct writes, Object.assign, reader adapters) owes a `MarkDirty()`\r\n *   or an explicit `UpdateValues()` (\"I made changes, apply please\").\r\n * - `flags` holds lazy invalidations (\"bounds is stale\"). Written at\r\n *   mutation time from `@io.flag` field metadata or by class code; cleared\r\n *   ONLY by the getter that recomputes the derived value. Never\r\n *   auto-cleared - deferring until needed is their whole point.\r\n * - `rebuild` holds scheduled work requirements (\"vertices need\r\n *   rebuilding\"). Written at mutation time from `@io.rebuild` field\r\n *   metadata or by class code; cleared ONLY by the specific work method\r\n *   that succeeds (e.g. RebuildVertices), typically driven from Update /\r\n *   per-frame passes. Never auto-cleared.\r\n * - Future transient runtime state (lifecycle links, revision counters)\r\n *   lands here rather than growing new underscore properties.\r\n */\r\nexport class CjsModelState\r\n{\r\n\r\n    /** Something changed; the next settle applies it. @type {boolean} */\r\n    dirty = false;\r\n\r\n    /** Lazy invalidations - consumers clear when they recompute. @type {Set<string>} */\r\n    flags = new Set();\r\n\r\n    /** Scheduled work requirements - work methods clear on success. @type {Set<string>} */\r\n    rebuild = new Set();\r\n\r\n    /** Settle re-entrancy guard. @type {boolean} */\r\n    updating = false;\r\n\r\n    /** Construction/teardown event gate (counted). @type {number} */\r\n    suppressEvents = 0;\r\n\r\n    /**\r\n     * Checks whether a settle is owed.\r\n     *\r\n     * @returns {boolean}\r\n     */\r\n    IsDirty()\r\n    {\r\n        return this.dirty;\r\n    }\r\n\r\n    /**\r\n     * Marks the model as changed (\"apply at the next settle\").\r\n     *\r\n     * @returns {CjsModelState} This state.\r\n     */\r\n    MarkDirty()\r\n    {\r\n        this.dirty = true;\r\n        return this;\r\n    }\r\n\r\n    /**\r\n     * Clears the dirty mark. The settle calls this; class code rarely should.\r\n     *\r\n     * @returns {CjsModelState} This state.\r\n     */\r\n    ClearDirty()\r\n    {\r\n        this.dirty = false;\r\n        return this;\r\n    }\r\n\r\n}\r\n\r\n\r\n// Models put a CjsModelState in the same __state slot a composed class fills\r\n// with a plain state object, so it answers the same questions - HasListener\r\n// first among them. Linking the prototypes rather than copying the method\r\n// means anything added to the shared state surface reaches models too.\r\nObject.setPrototypeOf(CjsModelState.prototype, RUNTIME_STATE_PROTOTYPE);\r\n"],"names":["CjsModelState","dirty","flags","Set","rebuild","updating","suppressEvents","IsDirty","MarkDirty","ClearDirty","Object","setPrototypeOf","prototype","RUNTIME_STATE_PROTOTYPE"],"mappings":";;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,MAAMA,aAAa,CAC1B;AAEI;AACAC,EAAAA,KAAK,GAAG,KAAK;;AAEb;AACAC,EAAAA,KAAK,GAAG,IAAIC,GAAG,EAAE;;AAEjB;AACAC,EAAAA,OAAO,GAAG,IAAID,GAAG,EAAE;;AAEnB;AACAE,EAAAA,QAAQ,GAAG,KAAK;;AAEhB;AACAC,EAAAA,cAAc,GAAG,CAAC;;AAElB;AACJ;AACA;AACA;AACA;AACIC,EAAAA,OAAOA,GACP;IACI,OAAO,IAAI,CAACN,KAAK;AACrB,EAAA;;AAEA;AACJ;AACA;AACA;AACA;AACIO,EAAAA,SAASA,GACT;IACI,IAAI,CAACP,KAAK,GAAG,IAAI;AACjB,IAAA,OAAO,IAAI;AACf,EAAA;;AAEA;AACJ;AACA;AACA;AACA;AACIQ,EAAAA,UAAUA,GACV;IACI,IAAI,CAACR,KAAK,GAAG,KAAK;AAClB,IAAA,OAAO,IAAI;AACf,EAAA;AAEJ;;AAGA;AACA;AACA;AACA;AACAS,MAAM,CAACC,cAAc,CAACX,aAAa,CAACY,SAAS,EAAEC,uBAAuB,CAAC;;;;"}
+{"version":3,"file":"CjsModelState.js","sources":["../../../../src/global/model/CjsModelState.js"],"sourcesContent":["import { RUNTIME_STATE_PROTOTYPE } from \"../compose/runtimeState.js\";\r\n\r\n/**\r\n * Per-model runtime state. One instance per model at `__state`.\r\n *\r\n * Ownership and clearing rules (kb section 8):\r\n * - `dirty` is the only generically managed member: mutations mark it, and\r\n *   `UpdateValues` (the settle) is the only thing that clears it. The\r\n *   pipeline is cooperative - anything mutating outside `SetValues`\r\n *   (direct writes, Object.assign, reader adapters) owes a `MarkDirty()`\r\n *   or an explicit `UpdateValues()` (\"I made changes, apply please\").\r\n * - Future transient runtime state (lifecycle links, revision counters)\r\n *   lands here rather than growing new underscore properties.\r\n */\r\nexport class CjsModelState\r\n{\r\n\r\n    /** Something changed; the next settle applies it. @type {boolean} */\r\n    dirty = false;\r\n\r\n    /** Settle re-entrancy guard. @type {boolean} */\r\n    updating = false;\r\n\r\n    /** Construction/teardown event gate (counted). @type {number} */\r\n    suppressEvents = 0;\r\n\r\n    /**\r\n     * Checks whether a settle is owed.\r\n     *\r\n     * @returns {boolean}\r\n     */\r\n    IsDirty()\r\n    {\r\n        return this.dirty;\r\n    }\r\n\r\n    /**\r\n     * Marks the model as changed (\"apply at the next settle\").\r\n     *\r\n     * @returns {CjsModelState} This state.\r\n     */\r\n    MarkDirty()\r\n    {\r\n        this.dirty = true;\r\n        return this;\r\n    }\r\n\r\n    /**\r\n     * Clears the dirty mark. The settle calls this; class code rarely should.\r\n     *\r\n     * @returns {CjsModelState} This state.\r\n     */\r\n    ClearDirty()\r\n    {\r\n        this.dirty = false;\r\n        return this;\r\n    }\r\n\r\n}\r\n\r\n\r\n// Models put a CjsModelState in the same __state slot a composed class fills\r\n// with a plain state object, so it answers the same questions - HasListener\r\n// first among them. Linking the prototypes rather than copying the method\r\n// means anything added to the shared state surface reaches models too.\r\nObject.setPrototypeOf(CjsModelState.prototype, RUNTIME_STATE_PROTOTYPE);\r\n"],"names":["CjsModelState","dirty","updating","suppressEvents","IsDirty","MarkDirty","ClearDirty","Object","setPrototypeOf","prototype","RUNTIME_STATE_PROTOTYPE"],"mappings":";;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,MAAMA,aAAa,CAC1B;AAEI;AACAC,EAAAA,KAAK,GAAG,KAAK;;AAEb;AACAC,EAAAA,QAAQ,GAAG,KAAK;;AAEhB;AACAC,EAAAA,cAAc,GAAG,CAAC;;AAElB;AACJ;AACA;AACA;AACA;AACIC,EAAAA,OAAOA,GACP;IACI,OAAO,IAAI,CAACH,KAAK;AACrB,EAAA;;AAEA;AACJ;AACA;AACA;AACA;AACII,EAAAA,SAASA,GACT;IACI,IAAI,CAACJ,KAAK,GAAG,IAAI;AACjB,IAAA,OAAO,IAAI;AACf,EAAA;;AAEA;AACJ;AACA;AACA;AACA;AACIK,EAAAA,UAAUA,GACV;IACI,IAAI,CAACL,KAAK,GAAG,KAAK;AAClB,IAAA,OAAO,IAAI;AACf,EAAA;AAEJ;;AAGA;AACA;AACA;AACA;AACAM,MAAM,CAACC,cAAc,CAACR,aAAa,CAACS,SAAS,EAAEC,uBAAuB,CAAC;;;;"}

package/dist/global/model/document/CjsDocumentHydrator.js

@@ -124,7 +124,11 @@ class CjsDocumentHydrator {
       kind: node.kind,
       shape,
       node,
-      options
+      options,
+      // The class this hydrator resolved for the kind, asked of the schema:
+      // does it declare fields to populate? A caller-supplied plain class
+      // does not, and keeps raw assignment.
+      declared: CjsSchema.getClassName(CjsDocumentHydrator.resolveClass(node.kind, options)) !== null
     });
     Object.assign(target, rawValues);
     return target;

package/dist/global/model/document/CjsDocumentHydrator.js.map

@@ -1 +1 @@
-{"version":3,"file":"CjsDocumentHydrator.js","sources":["../../../../../src/global/model/document/CjsDocumentHydrator.js"],"sourcesContent":["// DEPRECATED carbon.document boundary. The collapse into plain CjsModel\n// values is decided and partially executed - the envelope was\n// over-engineered, and a _type-tagged values graph carries everything it\n// did. Kept only until the interchange retirement completes its inventory\n// (docs/contracts/model-values-interchange.md owns the rule: no document\n// producer or consumer retires without inventory and replacement proof;\n// docs/research/schema-hydration-consolidation-plan-2026-09-05.md holds\n// the enumerated remaining surfaces). Do not add new consumers.\nimport { normalizeCarbonValue } from \"../../schema/types/index.js\";\r\nimport { CjsSchema } from \"../../schema/index.js\";\r\nimport { CjsCarbonDocument } from \"./CjsCarbonDocument.js\";\r\nimport { resolveHydrationAdapter } from \"../../schema/hydration.js\";\r\n\r\n/** Constructs runtime object graphs from neutral Carbon documents. */\r\nexport class CjsDocumentHydrator\r\n{\r\n    /**\r\n     * Hydrates every node in a Carbon document through the selected registry and\r\n     * adapter.\r\n     */\r\n    Hydrate(document, options = {})\r\n    {\r\n        return CjsDocumentHydrator.hydrate(document, options);\r\n    }\r\n\r\n    /** Hydrates a Carbon document and returns its first root. */\r\n    HydrateRoot(document, options = {})\r\n    {\r\n        return CjsDocumentHydrator.hydrateRoot(document, options);\r\n    }\r\n\r\n    /** Hydrates a normalized document into constructed runtime objects and roots. */\r\n    static hydrate(document, options = {})\r\n    {\r\n        const normalized = CjsCarbonDocument.normalize(document);\r\n        const nodeById = new Map(normalized.nodes.map(node => [node.id, node]));\r\n        const instanceById = new Map();\r\n        const reports = [];\r\n        const adapter = resolveHydrationAdapter(options);\r\n\r\n        for (const node of normalized.nodes)\r\n        {\r\n            instanceById.set(node.id, CjsDocumentHydrator.createNodeTarget(node, options, reports, adapter));\r\n        }\r\n\r\n        for (const node of normalized.nodes)\r\n        {\r\n            CjsDocumentHydrator.applyNodeValues(instanceById.get(node.id), node, instanceById, options, adapter);\r\n        }\r\n\r\n        // Phase 3: every instance is constructed and valued, so references are\r\n        // resolved - now let callers run their own post-graph init.\r\n        for (const node of normalized.nodes)\r\n        {\r\n            adapter.finalize(instanceById.get(node.id), { kind: node.kind, node, options });\r\n        }\r\n\r\n        const roots = normalized.roots.map(root => ({\r\n            name: root.name,\r\n            value: CjsDocumentHydrator.resolveDocumentValue(root.ref, instanceById, options)\r\n        }));\r\n\r\n        return {\r\n            root: roots[0]?.value ?? null,\r\n            roots,\r\n            document: normalized,\r\n            reports,\r\n            get(id)\r\n            {\r\n                return instanceById.get(Number(id)) || null;\r\n            },\r\n            getNode(id)\r\n            {\r\n                return nodeById.get(Number(id)) || null;\r\n            }\r\n        };\r\n    }\r\n\r\n    /** Returns the first hydrated root in document order. */\r\n    static hydrateRoot(document, options = {})\r\n    {\r\n        return CjsDocumentHydrator.hydrate(document, options).root;\r\n    }\r\n\r\n    /**\r\n     * Constructs the runtime target appropriate for one normalized document\r\n     * node.\r\n     */\r\n    static createNodeTarget(node, options, reports, adapter)\r\n    {\r\n        if (adapter)\r\n        {\r\n            const built = adapter.construct(node.kind, { kind: node.kind, node, options });\r\n            if (built !== undefined) return built;\r\n        }\r\n\r\n        const ClassConstructor = CjsDocumentHydrator.resolveClass(node.kind, options);\r\n        if (ClassConstructor)\r\n        {\r\n            return new ClassConstructor();\r\n        }\r\n\r\n        throw new TypeError(`No class is registered for hydratable type ${node.kind}.`);\r\n    }\r\n\r\n    /**\r\n     * Applies resolved field values to a constructed node through the hydration\r\n     * adapter.\r\n     */\r\n    static applyNodeValues(target, node, instanceById, options, adapter)\r\n    {\r\n        const registeredSchema = target?.constructor\r\n            ? CjsSchema.getSchema(target.constructor)\r\n            : null;\r\n        const shape = target?._sourceShape || (registeredSchema?.className ? registeredSchema : null);\r\n        const fieldByName = new Map((shape?.fields || []).map(field => [field.name, field]));\r\n        const values = {};\r\n\r\n        for (const [key, item] of Object.entries(node.fields || {}))\r\n        {\r\n            if (CjsSchema.isFieldHidden(target?.constructor, key)) continue;\r\n            const field = fieldByName.get(key) || null;\r\n            values[key] = CjsDocumentHydrator.hydrateFieldValue(item, field, instanceById, options);\r\n        }\r\n\r\n        // node.raw is enumerable NON-SCHEMA state, and its preservation is this\r\n        // deprecated path's documented contract (model-values-interchange.md).\r\n        // It is applied by direct assignment AFTER the adapter: a validated\r\n        // setter rightly ignores undeclared keys, so raw state is the\r\n        // hydrator's own job, exactly as it is for plain fallback carriers.\r\n        const rawValues = {};\r\n        for (const [key, item] of Object.entries(node.raw || {}))\r\n        {\r\n            if (CjsSchema.isFieldHidden(target?.constructor, key)) continue;\r\n            rawValues[key] = CjsDocumentHydrator.resolveDocumentValue(item, instanceById, options);\r\n        }\r\n\r\n        const apply = adapter || resolveHydrationAdapter(options);\r\n        apply.applyValues(target, values, { kind: node.kind, shape, node, options });\r\n        Object.assign(target, rawValues);\r\n        return target;\r\n    }\r\n\r\n    /** Hydrates one field value according to its schema descriptor. */\r\n    static hydrateFieldValue(value, field, instanceById, options)\r\n    {\r\n        const resolved = CjsDocumentHydrator.resolveDocumentValue(value, instanceById, options);\r\n        const descriptor = field?.type || field?.jsType || null;\r\n        const kind = descriptor?.kind;\r\n\r\n        if ((kind === \"array\" || kind === \"list\") && Array.isArray(resolved)) return resolved;\r\n        if ((kind === \"model\" || kind === \"objectRef\" || kind === \"struct\" || kind === \"rawStruct\" || kind === \"unknown\") && resolved && typeof resolved === \"object\") return resolved;\r\n        if (CjsDocumentHydrator.isShapeIncompatibleMathArray(resolved, descriptor)) return resolved;\r\n\r\n        return descriptor ? normalizeCarbonValue(resolved, descriptor) : resolved;\r\n    }\r\n\r\n    /** Recursively resolves document references and nested portable values. */\r\n    static resolveDocumentValue(value, instanceById, options)\r\n    {\r\n        if (CjsCarbonDocument.isRef(value))\r\n        {\r\n            const id = Number(value.$ref);\r\n            if (instanceById.has(id)) return instanceById.get(id);\r\n            if (options.allowMissingRefs) return null;\r\n            throw new TypeError(`CarbonDocument ref ${id} does not exist`);\r\n        }\r\n\r\n        if (Array.isArray(value)) return value.map(item => CjsDocumentHydrator.resolveDocumentValue(item, instanceById, options));\r\n        if (value && typeof value === \"object\")\r\n        {\r\n            return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, CjsDocumentHydrator.resolveDocumentValue(item, instanceById, options)]));\r\n        }\r\n        return value;\r\n    }\r\n\r\n    /** Resolves a node's serialized type through the active class registry. */\r\n    static resolveClass(kind, options)\r\n    {\r\n        const Schema = options.registry || CjsSchema;\r\n        return Schema.GetConstructor(kind);\r\n    }\r\n\r\n    /**\r\n     * Reports when source-shape metadata prevents coercion to a declared math\r\n     * container.\r\n     */\r\n    static isShapeIncompatibleMathArray(value, descriptor)\r\n    {\r\n        const expectedLength = descriptor?.length;\r\n        return Array.isArray(value) && Number.isInteger(expectedLength) && value.length !== expectedLength;\r\n    }\r\n}\r\n"],"names":["CjsDocumentHydrator","Hydrate","document","options","hydrate","HydrateRoot","hydrateRoot","normalized","CjsCarbonDocument","normalize","nodeById","Map","nodes","map","node","id","instanceById","reports","adapter","resolveHydrationAdapter","set","createNodeTarget","applyNodeValues","get","finalize","kind","roots","root","name","value","resolveDocumentValue","ref","Number","getNode","built","construct","undefined","ClassConstructor","resolveClass","TypeError","target","registeredSchema","constructor","CjsSchema","getSchema","shape","_sourceShape","className","fieldByName","fields","field","values","key","item","Object","entries","isFieldHidden","hydrateFieldValue","rawValues","raw","apply","applyValues","assign","resolved","descriptor","type","jsType","Array","isArray","isShapeIncompatibleMathArray","normalizeCarbonValue","isRef","$ref","has","allowMissingRefs","fromEntries","Schema","registry","GetConstructor","expectedLength","length","isInteger"],"mappings":"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"}
+{"version":3,"file":"CjsDocumentHydrator.js","sources":["../../../../../src/global/model/document/CjsDocumentHydrator.js"],"sourcesContent":["// DEPRECATED carbon.document boundary. The collapse into plain CjsModel\r\n// values is decided and partially executed - the envelope was\r\n// over-engineered, and a _type-tagged values graph carries everything it\r\n// did. Kept only until the interchange retirement completes its inventory\r\n// (docs/contracts/model-values-interchange.md owns the rule: no document\r\n// producer or consumer retires without inventory and replacement proof;\r\n// docs/research/schema-hydration-consolidation-plan-2026-09-05.md holds\r\n// the enumerated remaining surfaces). Do not add new consumers.\r\nimport { normalizeCarbonValue } from \"../../schema/types/index.js\";\r\nimport { CjsSchema } from \"../../schema/index.js\";\r\nimport { CjsCarbonDocument } from \"./CjsCarbonDocument.js\";\r\nimport { resolveHydrationAdapter } from \"../../schema/hydration.js\";\r\n\r\n/** Constructs runtime object graphs from neutral Carbon documents. */\r\nexport class CjsDocumentHydrator\r\n{\r\n    /**\r\n     * Hydrates every node in a Carbon document through the selected registry and\r\n     * adapter.\r\n     */\r\n    Hydrate(document, options = {})\r\n    {\r\n        return CjsDocumentHydrator.hydrate(document, options);\r\n    }\r\n\r\n    /** Hydrates a Carbon document and returns its first root. */\r\n    HydrateRoot(document, options = {})\r\n    {\r\n        return CjsDocumentHydrator.hydrateRoot(document, options);\r\n    }\r\n\r\n    /** Hydrates a normalized document into constructed runtime objects and roots. */\r\n    static hydrate(document, options = {})\r\n    {\r\n        const normalized = CjsCarbonDocument.normalize(document);\r\n        const nodeById = new Map(normalized.nodes.map(node => [node.id, node]));\r\n        const instanceById = new Map();\r\n        const reports = [];\r\n        const adapter = resolveHydrationAdapter(options);\r\n\r\n        for (const node of normalized.nodes)\r\n        {\r\n            instanceById.set(node.id, CjsDocumentHydrator.createNodeTarget(node, options, reports, adapter));\r\n        }\r\n\r\n        for (const node of normalized.nodes)\r\n        {\r\n            CjsDocumentHydrator.applyNodeValues(instanceById.get(node.id), node, instanceById, options, adapter);\r\n        }\r\n\r\n        // Phase 3: every instance is constructed and valued, so references are\r\n        // resolved - now let callers run their own post-graph init.\r\n        for (const node of normalized.nodes)\r\n        {\r\n            adapter.finalize(instanceById.get(node.id), { kind: node.kind, node, options });\r\n        }\r\n\r\n        const roots = normalized.roots.map(root => ({\r\n            name: root.name,\r\n            value: CjsDocumentHydrator.resolveDocumentValue(root.ref, instanceById, options)\r\n        }));\r\n\r\n        return {\r\n            root: roots[0]?.value ?? null,\r\n            roots,\r\n            document: normalized,\r\n            reports,\r\n            get(id)\r\n            {\r\n                return instanceById.get(Number(id)) || null;\r\n            },\r\n            getNode(id)\r\n            {\r\n                return nodeById.get(Number(id)) || null;\r\n            }\r\n        };\r\n    }\r\n\r\n    /** Returns the first hydrated root in document order. */\r\n    static hydrateRoot(document, options = {})\r\n    {\r\n        return CjsDocumentHydrator.hydrate(document, options).root;\r\n    }\r\n\r\n    /**\r\n     * Constructs the runtime target appropriate for one normalized document\r\n     * node.\r\n     */\r\n    static createNodeTarget(node, options, reports, adapter)\r\n    {\r\n        if (adapter)\r\n        {\r\n            const built = adapter.construct(node.kind, { kind: node.kind, node, options });\r\n            if (built !== undefined) return built;\r\n        }\r\n\r\n        const ClassConstructor = CjsDocumentHydrator.resolveClass(node.kind, options);\r\n        if (ClassConstructor)\r\n        {\r\n            return new ClassConstructor();\r\n        }\r\n\r\n        throw new TypeError(`No class is registered for hydratable type ${node.kind}.`);\r\n    }\r\n\r\n    /**\r\n     * Applies resolved field values to a constructed node through the hydration\r\n     * adapter.\r\n     */\r\n    static applyNodeValues(target, node, instanceById, options, adapter)\r\n    {\r\n        const registeredSchema = target?.constructor\r\n            ? CjsSchema.getSchema(target.constructor)\r\n            : null;\r\n        const shape = target?._sourceShape || (registeredSchema?.className ? registeredSchema : null);\r\n        const fieldByName = new Map((shape?.fields || []).map(field => [field.name, field]));\r\n        const values = {};\r\n\r\n        for (const [key, item] of Object.entries(node.fields || {}))\r\n        {\r\n            if (CjsSchema.isFieldHidden(target?.constructor, key)) continue;\r\n            const field = fieldByName.get(key) || null;\r\n            values[key] = CjsDocumentHydrator.hydrateFieldValue(item, field, instanceById, options);\r\n        }\r\n\r\n        // node.raw is enumerable NON-SCHEMA state, and its preservation is this\r\n        // deprecated path's documented contract (model-values-interchange.md).\r\n        // It is applied by direct assignment AFTER the adapter: a validated\r\n        // setter rightly ignores undeclared keys, so raw state is the\r\n        // hydrator's own job, exactly as it is for plain fallback carriers.\r\n        const rawValues = {};\r\n        for (const [key, item] of Object.entries(node.raw || {}))\r\n        {\r\n            if (CjsSchema.isFieldHidden(target?.constructor, key)) continue;\r\n            rawValues[key] = CjsDocumentHydrator.resolveDocumentValue(item, instanceById, options);\r\n        }\r\n\r\n        const apply = adapter || resolveHydrationAdapter(options);\r\n        apply.applyValues(target, values, {\r\n            kind: node.kind,\r\n            shape,\r\n            node,\r\n            options,\r\n            // The class this hydrator resolved for the kind, asked of the schema:\r\n            // does it declare fields to populate? A caller-supplied plain class\r\n            // does not, and keeps raw assignment.\r\n            declared: CjsSchema.getClassName(CjsDocumentHydrator.resolveClass(node.kind, options)) !== null\r\n        });\r\n        Object.assign(target, rawValues);\r\n        return target;\r\n    }\r\n\r\n    /** Hydrates one field value according to its schema descriptor. */\r\n    static hydrateFieldValue(value, field, instanceById, options)\r\n    {\r\n        const resolved = CjsDocumentHydrator.resolveDocumentValue(value, instanceById, options);\r\n        const descriptor = field?.type || field?.jsType || null;\r\n        const kind = descriptor?.kind;\r\n\r\n        if ((kind === \"array\" || kind === \"list\") && Array.isArray(resolved)) return resolved;\r\n        if ((kind === \"model\" || kind === \"objectRef\" || kind === \"struct\" || kind === \"rawStruct\" || kind === \"unknown\") && resolved && typeof resolved === \"object\") return resolved;\r\n        if (CjsDocumentHydrator.isShapeIncompatibleMathArray(resolved, descriptor)) return resolved;\r\n\r\n        return descriptor ? normalizeCarbonValue(resolved, descriptor) : resolved;\r\n    }\r\n\r\n    /** Recursively resolves document references and nested portable values. */\r\n    static resolveDocumentValue(value, instanceById, options)\r\n    {\r\n        if (CjsCarbonDocument.isRef(value))\r\n        {\r\n            const id = Number(value.$ref);\r\n            if (instanceById.has(id)) return instanceById.get(id);\r\n            if (options.allowMissingRefs) return null;\r\n            throw new TypeError(`CarbonDocument ref ${id} does not exist`);\r\n        }\r\n\r\n        if (Array.isArray(value)) return value.map(item => CjsDocumentHydrator.resolveDocumentValue(item, instanceById, options));\r\n        if (value && typeof value === \"object\")\r\n        {\r\n            return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, CjsDocumentHydrator.resolveDocumentValue(item, instanceById, options)]));\r\n        }\r\n        return value;\r\n    }\r\n\r\n    /** Resolves a node's serialized type through the active class registry. */\r\n    static resolveClass(kind, options)\r\n    {\r\n        const Schema = options.registry || CjsSchema;\r\n        return Schema.GetConstructor(kind);\r\n    }\r\n\r\n    /**\r\n     * Reports when source-shape metadata prevents coercion to a declared math\r\n     * container.\r\n     */\r\n    static isShapeIncompatibleMathArray(value, descriptor)\r\n    {\r\n        const expectedLength = descriptor?.length;\r\n        return Array.isArray(value) && Number.isInteger(expectedLength) && value.length !== expectedLength;\r\n    }\r\n}\r\n"],"names":["CjsDocumentHydrator","Hydrate","document","options","hydrate","HydrateRoot","hydrateRoot","normalized","CjsCarbonDocument","normalize","nodeById","Map","nodes","map","node","id","instanceById","reports","adapter","resolveHydrationAdapter","set","createNodeTarget","applyNodeValues","get","finalize","kind","roots","root","name","value","resolveDocumentValue","ref","Number","getNode","built","construct","undefined","ClassConstructor","resolveClass","TypeError","target","registeredSchema","constructor","CjsSchema","getSchema","shape","_sourceShape","className","fieldByName","fields","field","values","key","item","Object","entries","isFieldHidden","hydrateFieldValue","rawValues","raw","apply","applyValues","declared","getClassName","assign","resolved","descriptor","type","jsType","Array","isArray","isShapeIncompatibleMathArray","normalizeCarbonValue","isRef","$ref","has","allowMissingRefs","fromEntries","Schema","registry","GetConstructor","expectedLength","length","isInteger"],"mappings":"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"}

package/dist/global/model/index.js

@@ -1,4 +1,4 @@
-export { CjsModel, carbon, exportSourceValue, impl, importSourceValue, io, isModelInstance, jessica, schema, type } from './CjsModel.js';
+export { CjsModel, carbon, edit, exportSourceValue, impl, importSourceValue, isModelInstance, jessica, lifecycle, schema, type } from './CjsModel.js';
 export { CjsModelState } from './CjsModelState.js';
 export { CjsEventEmitter } from './CjsEventEmitter.js';
 export { asArray, clonePlain, collectionValues, firstDefined, getField, objectFromMap } from './sourceRecordUtils.js';

package/dist/global/schema/CjsSchema.js

@@ -1,7 +1,9 @@
-import { defaultValueForCarbonField, coerceCarbonMathInto, coerceCarbonTypedArrayInto, cloneCarbonValue, normalizeCarbonValue, exportCarbonValue } from './types/carbonTypes.js';
+import { defaultValueForCarbonField, coerceCarbonMathInto, coerceCarbonTypedArrayInto, exportCarbonValue, cloneCarbonValue, normalizeCarbonValue } from './types/carbonTypes.js';
+import { composeAbstractDecorator } from '../compose/abstract.js';
 import { composeNotifyDecorator } from '../compose/notify.js';
-import { cast, composeInterfaceDecorator } from '../compose/interface.js';
+import { cast, carbonMapInterfaceDecorator, carbonInheritDecorator } from '../compose/interface.js';
 import { createValuesTransport, composeValuesDecorator } from '../compose/values.js';
+import { blueEnums, CjsBlueEnumRegistry } from '../blue/enums/CjsBlueEnumRegistry.js';
 
 const CLASS_SCHEMA = new WeakMap();
 
@@ -14,8 +16,6 @@ const FIELD_INITIAL_DEFAULTS = new WeakMap();
 const FIELD_DECLARATION_METADATA = 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
@@ -140,7 +140,8 @@ class CjsSchema {
 
   /** Returns resolved schema metadata for a named field. */
   static getField(Constructor, fieldName) {
-    return getEffectiveFields(Constructor).find(field => field.name === fieldName) || null;
+    const field = getEffectiveFields(Constructor).find(field => field.name === fieldName);
+    return field ? enrichEnumField(field, Constructor) : null;
   }
 
   /**
@@ -346,6 +347,51 @@ class CjsSchema {
     return service ? service.getValues(target, out, options) : CjsSchema.getValuesFromSchema(target, out, options);
   }
 
+  /**
+   * The top-level values rule for from/set: a plain object, or null for "no
+   * values".
+   *
+   * SetValues and from exist for hydration and dehydration, so what arrives
+   * at the top is data. A live object there is refused rather than read as
+   * a bag: measured before this rule, `X.constructor.from(X)` built a new
+   * object that aliased X's children and flattened its Map-held models.
+   * Child fields are different - a non-plain value there is a reference, and
+   * the field's declared type decides that. The one rule lives here so every
+   * entry point asks the same question in the same place.
+   *
+   * @param {*} values Incoming top-level values.
+   * @param {string} label Entry point named in the error.
+   * @returns {boolean} False for null (nothing to apply), true for a plain bag.
+   * @throws {TypeError} For anything that is not a plain object or null.
+   */
+  static assertValues(values, label) {
+    if (values === null) return false;
+    if (!isPlainObject(values)) {
+      throw new TypeError(`${label} requires a plain values object; received ${describeValuesInput(values)}.`);
+    }
+    return true;
+  }
+
+  /**
+   * Copies a source's values into a target - the explicit copy helper.
+   *
+   * The top-level from/set rule refuses a live object as values, so copying
+   * one says so here instead: a plain source already IS values, anything
+   * else is exported first. Both then go through the target's validated
+   * setter, so the target keeps its own identity and in-place buffers. This
+   * is a value copy, not Carbon's Copier: no topology is preserved and
+   * reference fields carry the source's references across as references.
+   *
+   * @param {object} target The object receiving the values.
+   * @param {object} source A live object or a plain values object.
+   * @param {object} [options={}] Population options.
+   * @returns {Set<string>|boolean} Changed fields, or a boolean result.
+   */
+  static copy(target, source, options = {}) {
+    const values = isPlainObject(source) ? source : CjsSchema.getValues(source, {}, options);
+    return CjsSchema.setValues(target, values, options);
+  }
+
   /**
    * Applies a plain value bag to a target through its validated setter.
    *
@@ -355,6 +401,7 @@ class CjsSchema {
    * @returns {Set<string>|boolean} Changed fields, or a boolean result.
    */
   static setValues(target, values = {}, options = {}) {
+    if (!CjsSchema.assertValues(values, "CjsSchema.setValues")) return false;
     const service = CjsSchema.#valuesService;
     return service ? service.setValues(target, values, options) : CjsSchema.setValuesFromSchema(target, values, options);
   }
@@ -372,18 +419,7 @@ class CjsSchema {
   static #statelessTransport = createValuesTransport({
     GetFields: Constructor => getEffectiveFields(Constructor),
     Export: (value, field, options) => exportCarbonValue(value, field.type),
-    // A live instance of a registered class is ALIASED, never copied - the
-    // rule the model path applies through its brand (CjsModel.js, the
-    // isModelInstance early return). A class off the base carries no brand,
-    // so without this a reference field would receive a plain-object copy
-    // and shared identity across the graph would silently split.
-    Import: (value, field) => {
-      if (isLiveSchemaInstance(value)) return value;
-      if (Array.isArray(value) && value.some(isLiveSchemaInstance)) {
-        return value.map(item => isLiveSchemaInstance(item) ? item : cloneCarbonValue(item));
-      }
-      return normalizeCarbonValue(value, field.type);
-    },
+    Import: (value, field) => importDeclaredValue(value, field),
     CoerceInto: (current, incoming, field) => coerceCarbonMathInto(current, incoming, field.type) ?? coerceCarbonTypedArrayInto(current, incoming, field.type),
     IsEquivalent: (a, b) => a === b
   });
@@ -410,19 +446,20 @@ class CjsSchema {
    * @returns {object} The constructed instance.
    */
   static from(className, values = {}, options = {}) {
+    if (!CjsSchema.assertValues(values, "CjsSchema.from")) values = {};
     return CjsSchema.#requireValuesService("from").from(className, values, options);
   }
 
   /** Returns the stable registered name for an enum object. */
   static getEnumName(values) {
     if (typeof values === "string") return values;
-    return values && typeof values === "object" ? ENUM_SCHEMA_BY_OBJECT.get(values)?.name || values[CJS_ENUM_NAME] || values.Source?.name || values.name || null : null;
+    return values && typeof values === "object" ? blueEnums.GetEnumName(values) || blueEnums.GetEnumName(values.Type) || values[CJS_ENUM_NAME] || values.Source?.name || values.name || null : null;
   }
 
   /** Returns registered enum metadata by name or enum object. */
   static getEnum(values) {
     const name = CjsSchema.getEnumName(values);
-    return name ? ENUM_SCHEMA_BY_NAME.get(name) || null : null;
+    return name && blueEnums.HasEnum(name) ? blueEnums.GetEnumInfo(name) : null;
   }
 
   /**
@@ -614,59 +651,75 @@ class CjsSchema {
      */
     hideInherited: fieldNames => hiddenInheritedFieldsDecorator(normalizeHiddenInheritedFields(fieldNames))
   });
-  static io = Object.freeze({
-    always: fieldDecorator("io", {
-      always: true
-    }),
-    notify: fieldDecorator("io", {
-      notify: true
+
+  // Be::EDITFLAGS, exactly (`blueexposure/include/BlueTypes.h:282-311`).
+  // Every member below is one of Carbon's; nothing else belongs here. The
+  // namespace was called `io` until 2026-09-18, which named about a third of
+  // what it holds - only PERSIST and RPERSIST are I/O, NOTIFY is wiring,
+  // HIDDEN and FLAGS are editor hints, READ and WRITE are access control.
+  static edit = Object.freeze({
+    none: fieldDecorator("edit", {}),
+    // MODMASK 0x00F
+    read: fieldDecorator("edit", {
+      read: true
     }),
-    owned: fieldDecorator("io", {
-      ownership: "owned"
+    write: fieldDecorator("edit", {
+      write: true
     }),
-    persist: fieldDecorator("io", {
+    readwrite: fieldDecorator("edit", {
       read: true,
-      write: true,
-      persist: true
+      write: true
     }),
-    persistOnly: fieldDecorator("io", {
-      persist: true,
-      persistOnly: true
+    notify: fieldDecorator("edit", {
+      notify: true
     }),
-    read: fieldDecorator("io", {
-      read: true
+    hidden: fieldDecorator("edit", {
+      hidden: true
     }),
-    readwrite: fieldDecorator("io", {
-      read: true,
-      write: true
+    // SERMASK 0x0F0
+    persist: fieldDecorator("edit", {
+      persist: true
     }),
-    reference: fieldDecorator("io", {
-      ownership: "reference"
+    // RPERSIST 0x020 - "like PERSIST but only unserialize (read only)":
+    // the value loads from a document and is never written back out.
+    rpersist: fieldDecorator("edit", {
+      rpersist: true
     }),
-    // Declares the lazy-invalidation token(s) a change to this field
-    // implies ("bounds is stale"). Added to __state.flags at write time;
-    // cleared ONLY by the getter that recomputes the derived value.
-    flag: (...tokens) => fieldDecorator("io", {
-      flag: tokens.flat().map(String)
+    flags: fieldDecorator("edit", {
+      flags: true
     }),
-    // Declares the rebuild requirement token(s) a change to this field
-    // implies ("vertices need rebuilding"). Added to __state.rebuild at
-    // write time; cleared ONLY by the specific work method that succeeds
-    // (typically driven from Update / per-frame passes).
-    rebuild: (...tokens) => fieldDecorator("io", {
-      rebuild: tokens.flat().map(String)
+    enum: fieldDecorator("edit", {
+      enum: true
     }),
-    write: fieldDecorator("io", {
-      write: true
+    // PERSISTONLY = HIDDEN | PERSIST, for hidden attributes.
+    persistOnly: fieldDecorator("edit", {
+      persist: true,
+      persistOnly: true,
+      hidden: true
+    })
+  });
+
+  // Not EDITFLAGS and not type: WHO runs a child's construction, and later
+  // its teardown. `owned` marks a donor BY-VALUE member, destroyed with its
+  // parent; `reference` marks a borrowed one. Today only construction reads
+  // it - `entry.owned` (built below) gates the `ownedOnly` walk that runs
+  // Initialize in CjsModel.from - so the flag is half installed rather than
+  // unused: there is no teardown traversal yet to honour the other half.
+  static lifecycle = Object.freeze({
+    owned: fieldDecorator("lifecycle", {
+      ownership: "owned"
+    }),
+    reference: fieldDecorator("lifecycle", {
+      ownership: "reference"
     })
   });
 
-  // Composition decorators: type/io/carbon/impl/jessica DESCRIBE, compose
+  // Composition decorators: type/edit/carbon/impl/jessica DESCRIBE, compose
   // INSTALLS (design record, direction item 11). All three are live; the
   // migration of existing classes onto them is separate work.
   static compose = Object.freeze({
+    abstract: composeAbstractDecorator(Constructor => CjsSchema.getClassName(Constructor)),
     notify: composeNotifyDecorator,
-    interface: Contract => composeInterfaceDecorator(Contract, (Constructor, name) => CjsSchema.decorateMethod(Constructor, name, CjsSchema.impl.abstract)),
     values: composeValuesDecorator(CjsSchema.#statelessTransport)
   });
   static jessica = Object.freeze({
@@ -718,6 +771,11 @@ class CjsSchema {
       notSupported: true,
       status: "notSupported"
     }),
+    // Audit-only: names the state members invalidated by this field/method.
+    // The owning class retains all dirty-state, rebuild and timing behavior.
+    invalidates: (...members) => memberDecorator("impl", {
+      invalidates: members
+    }),
     note: text => memberDecorator("impl", {
       note: String(text)
     }),
@@ -725,7 +783,50 @@ class CjsSchema {
       reason: String(text)
     })
   });
+
+  /**
+   * What an installed interface member should be marked as on its consumer.
+   *
+   * CARBON'S INTERFACES ARE NOT UNIFORM, and that is the whole reason this
+   * exists. Some methods are pure virtual, and a consumer inheriting one
+   * without implementing it is genuinely unimplemented. Others are declared
+   * with an EMPTY BODY on purpose, so an implementer overrides only the half
+   * it cares about - `IBlueResManNotifications` has both callbacks empty in
+   * the donor. Marking that second kind `impl.abstract` on every consumer
+   * writes a divergence that does not exist, onto dozens of classes at once.
+   *
+   * So the interface's own declaration is carried across, and
+   * `impl.abstract` is only the fallback for a member the interface said
+   * nothing about. The chain is walked because `CollectMembers` does: a
+   * member may be declared on an ancestor of the contract named here.
+   *
+   * @param {Function} Contract The interface the member was installed from.
+   * @param {String} name The member.
+   * @returns {Array<Function>} Decorators for `decorateMethod`.
+   */
+  static #inheritedImplDecorators(Contract, name) {
+    let declared = null;
+    for (let base = Contract; typeof base === "function" && base.prototype && base !== Object; base = Object.getPrototypeOf(base)) {
+      declared = CjsSchema.getMethod(base, name)?.impl ?? null;
+      if (declared) break;
+    }
+    const status = declared?.status;
+    const decorator = status ? CjsSchema.impl[status] : null;
+    const decorators = [typeof decorator === "function" ? decorator : CjsSchema.impl.abstract];
+
+    // A reason the interface wrote belongs to the member wherever it lands;
+    // a consumer left holding the marking without it could not be reviewed.
+    if (declared?.reason) decorators.push(CjsSchema.impl.reason(declared.reason));
+    if (declared?.note) decorators.push(CjsSchema.impl.note(declared.note));
+    return decorators;
+  }
   static carbon = Object.freeze({
+    // Carbon's base list and Carbon's exposure table: two different facts,
+    // two decorators, both factual and so both here rather than in
+    // `compose`. See compose/interface.js for the black-reader branch that
+    // proves they cannot be collapsed into one.
+    inherit: (...Bases) => carbonInheritDecorator(Bases, (Constructor, name, Contract) => CjsSchema.decorateMethod(Constructor, name, ...CjsSchema.#inheritedImplDecorators(Contract, name))),
+    mapInterface: (...Interfaces) => carbonMapInterfaceDecorator(Interfaces),
     method: methodDecorator("carbon", {
       method: true
     }),
@@ -1114,13 +1215,43 @@ function hiddenInheritedFieldsDecorator(fieldNames) {
   };
 }
 const CONTEXT_FIRST_PARAMETER = /^\(?\s*_?(context|updateContext)\b/;
+
+/**
+ * Whether a function's source still carries the names it was written with.
+ *
+ * A minifier renames parameters to one or two characters, so `(context)`
+ * arrives as `(t)` and any assertion about the NAME becomes an assertion about
+ * the build. There is no way to tell a minified name from a wrongly chosen one
+ * by inspection, so the only sound thing is to stop asking once the names are
+ * gone - which a parameter list of nothing but short identifiers says plainly.
+ *
+ * @param {string} parameterList Source from the opening parenthesis.
+ * @returns {boolean} True when at least one parameter kept a real name.
+ */
+function hasReadableParameterNames(parameterList) {
+  const close = parameterList.indexOf(")");
+  const declared = close === -1 ? parameterList : parameterList.slice(0, close);
+  return /[A-Za-z_$][\w$]{2,}/u.test(declared);
+}
 function assertContextFirstMethod(fn, methodName) {
   if (typeof fn !== "function") {
     return;
   }
   const source = String(fn);
   const parameterList = source.slice(source.indexOf("("));
-  if (fn.length < 1 || !CONTEXT_FIRST_PARAMETER.test(parameterList)) {
+
+  // Arity is the contract and holds in any build: a contextual method that
+  // takes nothing cannot have been given a context.
+  if (fn.length < 1) {
+    throw new TypeError(`CjsSchema.carbon.contextual method "${String(methodName)}" must take a context as its first parameter.`);
+  }
+
+  // The NAME is an authoring convention, and it is only checkable while the
+  // names exist. Asserting it against a minified bundle threw on every
+  // contextual method in the shipped build and took the engine down at load
+  // - the failure is the assertion's, not the code's.
+  if (!hasReadableParameterNames(parameterList)) return;
+  if (!CONTEXT_FIRST_PARAMETER.test(parameterList)) {
     throw new TypeError(`CjsSchema.carbon.contextual method "${String(methodName)}" must be context-first ` + "(first parameter named context or updateContext).");
   }
 }
@@ -1225,11 +1356,46 @@ function defineHiddenInheritedFields(Constructor, fieldNames) {
   }
 }
 
-// A live instance of a registered class, from this copy or a sibling one -
-// getClassName reads the cross-copy stamp. Plain bags, arrays, typed arrays
-// and the reader's `{ _sourceClassName }` carriers all answer false.
-function isLiveSchemaInstance(value) {
-  return !!value && typeof value === "object" && !Array.isArray(value) && !ArrayBuffer.isView(value) && CjsSchema.getClassName(value.constructor) !== null;
+// The state-free transport's import. A declared REFERENCE field - model or
+// objectRef, or a list or Map of them - treats a non-plain object as the
+// reference itself and assigns it, Carbon's IRoot* member (operator ruling,
+// 2026-09-14). The DECLARED TYPE decides that the field holds references; the
+// value's class is never inspected. Plain bags, and every other field kind,
+// import by value exactly as before.
+function importDeclaredValue(value, field) {
+  const type = field.type;
+  switch (type?.kind) {
+    case "model":
+    case "objectRef":
+      if (isObjectReference(value)) return value;
+      break;
+    case "list":
+    case "array":
+      if (Array.isArray(value) && isReferenceType(type.itemType)) {
+        return value.map(item => isObjectReference(item) ? item : cloneCarbonValue(item));
+      }
+      break;
+    case "map":
+      if (value instanceof Map && isReferenceType(type.valueType)) {
+        return new Map(Array.from(value, ([key, item]) => [key, isObjectReference(item) ? item : cloneCarbonValue(item)]));
+      }
+      break;
+  }
+  return normalizeCarbonValue(value, type);
+}
+
+// A declared item type that holds references: a model or objectRef
+// descriptor, or a bare name registered as a class. "string" and "unknown"
+// are not registered, so they stay values.
+function isReferenceType(type) {
+  if (typeof type === "string") return CjsSchema.GetConstructor(type) !== null;
+  return type?.kind === "model" || type?.kind === "objectRef";
+}
+
+// Not a values bag: an object that is neither plain, an array nor a typed
+// array. Asks only what the value is made of, never which class built it.
+function isObjectReference(value) {
+  return value !== null && typeof value === "object" && !isPlainObject(value) && !Array.isArray(value) && !ArrayBuffer.isView(value);
 }
 function getEffectiveFields(Constructor) {
   const ordered = [];
@@ -1253,6 +1419,15 @@ function getEffectiveFields(Constructor) {
       hidden.add(fieldName);
     }
   }
+
+  // Enum chooser metadata carries the same ENUM fact as Blue's flag.
+  // Keep it visible under edit for comparisons without duplicating annotations.
+  for (const field of ordered) {
+    if (field.enum) field.edit = {
+      ...field.edit,
+      enum: true
+    };
+  }
   return ordered.filter(field => !hidden.has(field.name));
 }
 function getHiddenInheritedFieldNames(Constructor) {
@@ -1386,7 +1561,7 @@ function addSchemaBuckets(schema) {
       resources.push(entry);
       continue;
     }
-    entry.owned = field.io?.ownership === "owned";
+    entry.owned = field.lifecycle?.ownership === "owned";
     children.push(entry);
   }
   schema.byName = byName;
@@ -1610,13 +1785,7 @@ function registerClassMetadata(Constructor, schema) {
 }
 function defineEnumMetadata(values, schema) {
   if (!values || typeof values !== "object" || !schema?.name) return;
-  ENUM_SCHEMA_BY_NAME.set(schema.name, schema);
-  ENUM_SCHEMA_BY_OBJECT.set(values, schema);
-  if (Object.isExtensible(values) && !Object.prototype.hasOwnProperty.call(values, CJS_ENUM_NAME)) {
-    Object.defineProperty(values, CJS_ENUM_NAME, {
-      value: schema.name
-    });
-  }
+  blueEnums.RegisterEnum(schema.name, schema.type, schema);
 }
 function normalizeEnumSchema(values, definition) {
   const type = values?.Type || values;
@@ -1631,6 +1800,10 @@ function normalizeEnumSchema(values, definition) {
   if (definition.source) result.source = definition.source;
   if (definition.family) result.family = definition.family;
   if (definition.line !== undefined && definition.line !== null) result.line = definition.line;
+  if (definition.exposure !== undefined) result.exposure = definition.exposure;
+  if (definition.exposedName !== undefined) result.exposedName = definition.exposedName;
+  if (definition.chooserSource !== undefined) result.chooserSource = definition.chooserSource;
+  if (definition.chooser !== undefined) result.chooser = definition.chooser;
   return result;
 }
 function normalizeEnumDefinition(values) {
@@ -1741,6 +1914,20 @@ function mergeNamespace(existing, value) {
 function enrichEnumField(exported, Constructor) {
   const enumType = exported?.enum?.enumType;
   if (!enumType) return exported;
+  if (enumType.includes(".")) {
+    const info = blueEnums.GetEnumInfo(enumType);
+    return {
+      ...exported,
+      enum: {
+        ...exported.enum,
+        identity: info.name,
+        members: info.type,
+        ...(info.chooser === undefined ? {} : {
+          chooser: info.chooser
+        })
+      }
+    };
+  }
   const members = Constructor?.[enumType];
   if (!members || typeof members !== "object") return exported;
   let owner = Constructor;
@@ -1785,5 +1972,24 @@ function isPlainObject(value) {
   return Boolean(value) && typeof value === "object" && Object.getPrototypeOf(value) === Object.prototype;
 }
 
+// Names what arrived where a values bag was required, for assertValues' error.
+function describeValuesInput(value) {
+  if (value === undefined) return "undefined";
+  if (Array.isArray(value)) return "an array";
+  if (typeof value !== "object") return `a ${typeof value}`;
+  const name = value.constructor?.name;
+  return name ? `an instance of ${name}` : "an object without Object.prototype";
+}
+
+// Install provenance here, after the schema exists. The registry core cannot
+// import schema: both Blue and schema need its storage during module loading.
+CjsSchema.define(CjsBlueEnumRegistry, {
+  className: "CjsBlueEnumRegistry",
+  modelledOn: "BlueRegistration",
+  family: "blue",
+  fields: {},
+  methods: Object.fromEntries(["RegisterEnum", "HasEnum", "GetEnum", "GetEnumInfo", "GetEnumName", "GetNameFromValue", "GetNameFromBitmask"].map(name => [name, [CjsSchema.impl.adapted, CjsSchema.impl.reason("Combines BlueRegistration enum storage, EnumRegistration/EnumTypeRegistration and PyBlueEnumObject exposure; JS module execution replaces static registrars, qualified names replace module tables, and JS errors replace Python exceptions.")]]))
+});
+
 export { CJS_CLASS_NAME, CJS_ENUM_NAME, CJS_MODEL_BRAND, CjsSchema };
 //# sourceMappingURL=CjsSchema.js.map