@carbonenginejs/runtime 0.1.0-alpha.1 → 0.1.0-alpha.3

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":";;;;;;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAMA;AACO,MAAMA,mBAAmB,CAChC;AACI;AACJ;AACA;AACA;AACIC,EAAAA,OAAOA,CAACC,QAAQ,EAAEC,OAAO,GAAG,EAAE,EAC9B;AACI,IAAA,OAAOH,mBAAmB,CAACI,OAAO,CAACF,QAAQ,EAAEC,OAAO,CAAC;AACzD,EAAA;;AAEA;AACAE,EAAAA,WAAWA,CAACH,QAAQ,EAAEC,OAAO,GAAG,EAAE,EAClC;AACI,IAAA,OAAOH,mBAAmB,CAACM,WAAW,CAACJ,QAAQ,EAAEC,OAAO,CAAC;AAC7D,EAAA;;AAEA;EACA,OAAOC,OAAOA,CAACF,QAAQ,EAAEC,OAAO,GAAG,EAAE,EACrC;AACI,IAAA,MAAMI,UAAU,GAAGC,iBAAiB,CAACC,SAAS,CAACP,QAAQ,CAAC;IACxD,MAAMQ,QAAQ,GAAG,IAAIC,GAAG,CAACJ,UAAU,CAACK,KAAK,CAACC,GAAG,CAACC,IAAI,IAAI,CAACA,IAAI,CAACC,EAAE,EAAED,IAAI,CAAC,CAAC,CAAC;AACvE,IAAA,MAAME,YAAY,GAAG,IAAIL,GAAG,EAAE;IAC9B,MAAMM,OAAO,GAAG,EAAE;AAClB,IAAA,MAAMC,OAAO,GAAGC,uBAAuB,CAAChB,OAAO,CAAC;AAEhD,IAAA,KAAK,MAAMW,IAAI,IAAIP,UAAU,CAACK,KAAK,EACnC;AACII,MAAAA,YAAY,CAACI,GAAG,CAACN,IAAI,CAACC,EAAE,EAAEf,mBAAmB,CAACqB,gBAAgB,CAACP,IAAI,EAAEX,OAAO,EAAEc,OAAO,EAAEC,OAAO,CAAC,CAAC;AACpG,IAAA;AAEA,IAAA,KAAK,MAAMJ,IAAI,IAAIP,UAAU,CAACK,KAAK,EACnC;AACIZ,MAAAA,mBAAmB,CAACsB,eAAe,CAACN,YAAY,CAACO,GAAG,CAACT,IAAI,CAACC,EAAE,CAAC,EAAED,IAAI,EAAEE,YAAY,EAAEb,OAAO,EAAEe,OAAO,CAAC;AACxG,IAAA;;AAEA;AACA;AACA,IAAA,KAAK,MAAMJ,IAAI,IAAIP,UAAU,CAACK,KAAK,EACnC;MACIM,OAAO,CAACM,QAAQ,CAACR,YAAY,CAACO,GAAG,CAACT,IAAI,CAACC,EAAE,CAAC,EAAE;QAAEU,IAAI,EAAEX,IAAI,CAACW,IAAI;QAAEX,IAAI;AAAEX,QAAAA;AAAQ,OAAC,CAAC;AACnF,IAAA;IAEA,MAAMuB,KAAK,GAAGnB,UAAU,CAACmB,KAAK,CAACb,GAAG,CAACc,IAAI,KAAK;MACxCC,IAAI,EAAED,IAAI,CAACC,IAAI;MACfC,KAAK,EAAE7B,mBAAmB,CAAC8B,oBAAoB,CAACH,IAAI,CAACI,GAAG,EAAEf,YAAY,EAAEb,OAAO;AACnF,KAAC,CAAC,CAAC;IAEH,OAAO;MACHwB,IAAI,EAAED,KAAK,CAAC,CAAC,CAAC,EAAEG,KAAK,IAAI,IAAI;MAC7BH,KAAK;AACLxB,MAAAA,QAAQ,EAAEK,UAAU;MACpBU,OAAO;MACPM,GAAGA,CAACR,EAAE,EACN;QACI,OAAOC,YAAY,CAACO,GAAG,CAACS,MAAM,CAACjB,EAAE,CAAC,CAAC,IAAI,IAAI;MAC/C,CAAC;MACDkB,OAAOA,CAAClB,EAAE,EACV;QACI,OAAOL,QAAQ,CAACa,GAAG,CAACS,MAAM,CAACjB,EAAE,CAAC,CAAC,IAAI,IAAI;AAC3C,MAAA;KACH;AACL,EAAA;;AAEA;EACA,OAAOT,WAAWA,CAACJ,QAAQ,EAAEC,OAAO,GAAG,EAAE,EACzC;IACI,OAAOH,mBAAmB,CAACI,OAAO,CAACF,QAAQ,EAAEC,OAAO,CAAC,CAACwB,IAAI;AAC9D,EAAA;;AAEA;AACJ;AACA;AACA;EACI,OAAON,gBAAgBA,CAACP,IAAI,EAAEX,OAAO,EAAEc,OAAO,EAAEC,OAAO,EACvD;AACI,IAAA,IAAIA,OAAO,EACX;MACI,MAAMgB,KAAK,GAAGhB,OAAO,CAACiB,SAAS,CAACrB,IAAI,CAACW,IAAI,EAAE;QAAEA,IAAI,EAAEX,IAAI,CAACW,IAAI;QAAEX,IAAI;AAAEX,QAAAA;AAAQ,OAAC,CAAC;AAC9E,MAAA,IAAI+B,KAAK,KAAKE,SAAS,EAAE,OAAOF,KAAK;AACzC,IAAA;IAEA,MAAMG,gBAAgB,GAAGrC,mBAAmB,CAACsC,YAAY,CAACxB,IAAI,CAACW,IAAI,EAAEtB,OAAO,CAAC;AAC7E,IAAA,IAAIkC,gBAAgB,EACpB;MACI,OAAO,IAAIA,gBAAgB,EAAE;AACjC,IAAA;IAEA,MAAM,IAAIE,SAAS,CAAC,CAAA,2CAAA,EAA8CzB,IAAI,CAACW,IAAI,GAAG,CAAC;AACnF,EAAA;;AAEA;AACJ;AACA;AACA;EACI,OAAOH,eAAeA,CAACkB,MAAM,EAAE1B,IAAI,EAAEE,YAAY,EAAEb,OAAO,EAAEe,OAAO,EACnE;AACI,IAAA,MAAMuB,gBAAgB,GAAGD,MAAM,EAAEE,WAAW,GACtCC,SAAS,CAACC,SAAS,CAACJ,MAAM,CAACE,WAAW,CAAC,GACvC,IAAI;AACV,IAAA,MAAMG,KAAK,GAAGL,MAAM,EAAEM,YAAY,KAAKL,gBAAgB,EAAEM,SAAS,GAAGN,gBAAgB,GAAG,IAAI,CAAC;IAC7F,MAAMO,WAAW,GAAG,IAAIrC,GAAG,CAAC,CAACkC,KAAK,EAAEI,MAAM,IAAI,EAAE,EAAEpC,GAAG,CAACqC,KAAK,IAAI,CAACA,KAAK,CAACtB,IAAI,EAAEsB,KAAK,CAAC,CAAC,CAAC;IACpF,MAAMC,MAAM,GAAG,EAAE;AAEjB,IAAA,KAAK,MAAM,CAACC,GAAG,EAAEC,IAAI,CAAC,IAAIC,MAAM,CAACC,OAAO,CAACzC,IAAI,CAACmC,MAAM,IAAI,EAAE,CAAC,EAC3D;MACI,IAAIN,SAAS,CAACa,aAAa,CAAChB,MAAM,EAAEE,WAAW,EAAEU,GAAG,CAAC,EAAE;MACvD,MAAMF,KAAK,GAAGF,WAAW,CAACzB,GAAG,CAAC6B,GAAG,CAAC,IAAI,IAAI;AAC1CD,MAAAA,MAAM,CAACC,GAAG,CAAC,GAAGpD,mBAAmB,CAACyD,iBAAiB,CAACJ,IAAI,EAAEH,KAAK,EAAElC,YAAY,EAAEb,OAAO,CAAC;AAC3F,IAAA;;AAEA;AACA;AACA;AACA;AACA;IACA,MAAMuD,SAAS,GAAG,EAAE;AACpB,IAAA,KAAK,MAAM,CAACN,GAAG,EAAEC,IAAI,CAAC,IAAIC,MAAM,CAACC,OAAO,CAACzC,IAAI,CAAC6C,GAAG,IAAI,EAAE,CAAC,EACxD;MACI,IAAIhB,SAAS,CAACa,aAAa,CAAChB,MAAM,EAAEE,WAAW,EAAEU,GAAG,CAAC,EAAE;AACvDM,MAAAA,SAAS,CAACN,GAAG,CAAC,GAAGpD,mBAAmB,CAAC8B,oBAAoB,CAACuB,IAAI,EAAErC,YAAY,EAAEb,OAAO,CAAC;AAC1F,IAAA;AAEA,IAAA,MAAMyD,KAAK,GAAG1C,OAAO,IAAIC,uBAAuB,CAAChB,OAAO,CAAC;AACzDyD,IAAAA,KAAK,CAACC,WAAW,CAACrB,MAAM,EAAEW,MAAM,EAAE;MAC9B1B,IAAI,EAAEX,IAAI,CAACW,IAAI;MACfoB,KAAK;MACL/B,IAAI;MACJX,OAAO;AACP;AACA;AACA;AACA2D,MAAAA,QAAQ,EAAEnB,SAAS,CAACoB,YAAY,CAAC/D,mBAAmB,CAACsC,YAAY,CAACxB,IAAI,CAACW,IAAI,EAAEtB,OAAO,CAAC,CAAC,KAAK;AAC/F,KAAC,CAAC;AACFmD,IAAAA,MAAM,CAACU,MAAM,CAACxB,MAAM,EAAEkB,SAAS,CAAC;AAChC,IAAA,OAAOlB,MAAM;AACjB,EAAA;;AAEA;EACA,OAAOiB,iBAAiBA,CAAC5B,KAAK,EAAEqB,KAAK,EAAElC,YAAY,EAAEb,OAAO,EAC5D;IACI,MAAM8D,QAAQ,GAAGjE,mBAAmB,CAAC8B,oBAAoB,CAACD,KAAK,EAAEb,YAAY,EAAEb,OAAO,CAAC;IACvF,MAAM+D,UAAU,GAAGhB,KAAK,EAAEiB,IAAI,IAAIjB,KAAK,EAAEkB,MAAM,IAAI,IAAI;AACvD,IAAA,MAAM3C,IAAI,GAAGyC,UAAU,EAAEzC,IAAI;AAE7B,IAAA,IAAI,CAACA,IAAI,KAAK,OAAO,IAAIA,IAAI,KAAK,MAAM,KAAK4C,KAAK,CAACC,OAAO,CAACL,QAAQ,CAAC,EAAE,OAAOA,QAAQ;AACrF,IAAA,IAAI,CAACxC,IAAI,KAAK,OAAO,IAAIA,IAAI,KAAK,WAAW,IAAIA,IAAI,KAAK,QAAQ,IAAIA,IAAI,KAAK,WAAW,IAAIA,IAAI,KAAK,SAAS,KAAKwC,QAAQ,IAAI,OAAOA,QAAQ,KAAK,QAAQ,EAAE,OAAOA,QAAQ;IAC9K,IAAIjE,mBAAmB,CAACuE,4BAA4B,CAACN,QAAQ,EAAEC,UAAU,CAAC,EAAE,OAAOD,QAAQ;IAE3F,OAAOC,UAAU,GAAGM,oBAAoB,CAACP,QAAQ,EAAEC,UAAU,CAAC,GAAGD,QAAQ;AAC7E,EAAA;;AAEA;AACA,EAAA,OAAOnC,oBAAoBA,CAACD,KAAK,EAAEb,YAAY,EAAEb,OAAO,EACxD;AACI,IAAA,IAAIK,iBAAiB,CAACiE,KAAK,CAAC5C,KAAK,CAAC,EAClC;AACI,MAAA,MAAMd,EAAE,GAAGiB,MAAM,CAACH,KAAK,CAAC6C,IAAI,CAAC;AAC7B,MAAA,IAAI1D,YAAY,CAAC2D,GAAG,CAAC5D,EAAE,CAAC,EAAE,OAAOC,YAAY,CAACO,GAAG,CAACR,EAAE,CAAC;AACrD,MAAA,IAAIZ,OAAO,CAACyE,gBAAgB,EAAE,OAAO,IAAI;AACzC,MAAA,MAAM,IAAIrC,SAAS,CAAC,CAAA,mBAAA,EAAsBxB,EAAE,iBAAiB,CAAC;AAClE,IAAA;IAEA,IAAIsD,KAAK,CAACC,OAAO,CAACzC,KAAK,CAAC,EAAE,OAAOA,KAAK,CAAChB,GAAG,CAACwC,IAAI,IAAIrD,mBAAmB,CAAC8B,oBAAoB,CAACuB,IAAI,EAAErC,YAAY,EAAEb,OAAO,CAAC,CAAC;AACzH,IAAA,IAAI0B,KAAK,IAAI,OAAOA,KAAK,KAAK,QAAQ,EACtC;AACI,MAAA,OAAOyB,MAAM,CAACuB,WAAW,CAACvB,MAAM,CAACC,OAAO,CAAC1B,KAAK,CAAC,CAAChB,GAAG,CAAC,CAAC,CAACuC,GAAG,EAAEC,IAAI,CAAC,KAAK,CAACD,GAAG,EAAEpD,mBAAmB,CAAC8B,oBAAoB,CAACuB,IAAI,EAAErC,YAAY,EAAEb,OAAO,CAAC,CAAC,CAAC,CAAC;AACvJ,IAAA;AACA,IAAA,OAAO0B,KAAK;AAChB,EAAA;;AAEA;AACA,EAAA,OAAOS,YAAYA,CAACb,IAAI,EAAEtB,OAAO,EACjC;AACI,IAAA,MAAM2E,MAAM,GAAG3E,OAAO,CAAC4E,QAAQ,IAAIpC,SAAS;AAC5C,IAAA,OAAOmC,MAAM,CAACE,cAAc,CAACvD,IAAI,CAAC;AACtC,EAAA;;AAEA;AACJ;AACA;AACA;AACI,EAAA,OAAO8C,4BAA4BA,CAAC1C,KAAK,EAAEqC,UAAU,EACrD;AACI,IAAA,MAAMe,cAAc,GAAGf,UAAU,EAAEgB,MAAM;AACzC,IAAA,OAAOb,KAAK,CAACC,OAAO,CAACzC,KAAK,CAAC,IAAIG,MAAM,CAACmD,SAAS,CAACF,cAAc,CAAC,IAAIpD,KAAK,CAACqD,MAAM,KAAKD,cAAc;AACtG,EAAA;AACJ;;;;"}

package/dist/global/schema/CjsSchema.js

@@ -1,4 +1,4 @@
-import { defaultValueForCarbonField, coerceCarbonMathInto, coerceCarbonTypedArrayInto, normalizeCarbonValue, exportCarbonValue } from './types/carbonTypes.js';
+import { defaultValueForCarbonField, coerceCarbonMathInto, coerceCarbonTypedArrayInto, exportCarbonValue, cloneCarbonValue, normalizeCarbonValue } from './types/carbonTypes.js';
 import { composeNotifyDecorator } from '../compose/notify.js';
 import { cast, composeInterfaceDecorator } from '../compose/interface.js';
 import { createValuesTransport, composeValuesDecorator } from '../compose/values.js';
@@ -346,6 +346,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 +400,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,7 +418,7 @@ class CjsSchema {
   static #statelessTransport = createValuesTransport({
     GetFields: Constructor => getEffectiveFields(Constructor),
     Export: (value, field, options) => exportCarbonValue(value, field.type),
-    Import: (value, field) => 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
   });
@@ -399,6 +445,7 @@ 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);
   }
 
@@ -1213,6 +1260,48 @@ function defineHiddenInheritedFields(Constructor, fieldNames) {
     schema.hiddenInherited.add(fieldName);
   }
 }
+
+// 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 = [];
   const byName = new Map();
@@ -1767,5 +1856,14 @@ 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";
+}
+
 export { CJS_CLASS_NAME, CJS_ENUM_NAME, CJS_MODEL_BRAND, CjsSchema };
 //# sourceMappingURL=CjsSchema.js.map