This is an automated email from the ASF dual-hosted git repository. chaokunyang pushed a commit to branch main in repository https://gitbox.apache.org/repos/asf/fory-site.git
commit 10fe5918efa36fd7c7847d0ae482ec1d559ef459 Author: chaokunyang <[email protected]> AuthorDate: Mon Jul 27 03:02:44 2026 +0000 🔄 synced local 'docs/specification/' with remote 'docs/specification/' --- docs/specification/xlang_implementation_guide.md | 34 ++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/docs/specification/xlang_implementation_guide.md b/docs/specification/xlang_implementation_guide.md index 06cdf5c618..b336d83a8e 100644 --- a/docs/specification/xlang_implementation_guide.md +++ b/docs/specification/xlang_implementation_guide.md @@ -984,6 +984,40 @@ The public helper should be a thin generated wrapper around the Fory registration API, not a public global registry or a second unrelated registration API family. +### Dart External Structural Serializers + +Dart external-type serialization extends `ForyStruct` with an optional +compile-time `target` and named generative `constructor`. The annotated +`abstract final` class is a schema declaration only. It has no runtime value or +registration identity. + +The generator must analyze ordinary and external structs through one struct +model and one emitter. Private generated symbol names come from the declaration +name. Every runtime type position uses the target type: `Serializer<Target>`, +`GeneratedStructSchema<Target>`, read and write signatures, constructor calls, +schema `type`, and generated-module dispatch. + +For each declaration field, resolve an accessible target getter with the same +name and exact instantiated Dart type. Constructor parameters and any +post-construction setter must also match exactly. A public named generative +constructor is selected only when the annotation names it. Factory +constructors, abstract targets, open target types, and constructor-based +reference-tracked paths back to the target are rejected during generation. +The recursive check includes target elements, keys, and values nested in the +supported list, set, and map field metadata. + +Generated code reads getters and invokes target constructors or setters +directly. It must not allocate the declaration, copy values through an +intermediate object, invoke runtime callbacks, perform member-name lookup, or +branch on whether the struct is external. The existing generated struct, +registration, resolver, field, collection, map, compatible-read, and reference +paths remain the only runtime paths. + +Registration is keyed by `Target` through the generated module and the existing +generated registration API. Direct roots, generated fields, dynamic values, +and recursive collection/map children resolve the same target registration. +Dart root collections retain their existing untyped outer runtime shapes. + ## Directory Layout Under each Dart package `lib/` tree, only one nested source layer is allowed. --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
