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 b8d7caff502ed172e6dab2f86d6a445034b0506f
Author: chaokunyang <[email protected]>
AuthorDate: Mon Jul 27 09:27:58 2026 +0000

    🔄 synced local 'docs/specification/' with remote 'docs/specification/'
---
 docs/specification/xlang_implementation_guide.md | 90 ++++++++++++++++++++++++
 docs/specification/xlang_type_mapping.md         |  6 ++
 2 files changed, 96 insertions(+)

diff --git a/docs/specification/xlang_implementation_guide.md 
b/docs/specification/xlang_implementation_guide.md
index 1f7be2a828..7a71637346 100644
--- a/docs/specification/xlang_implementation_guide.md
+++ b/docs/specification/xlang_implementation_guide.md
@@ -219,6 +219,96 @@ The ownership split is:
 - `Fory` owns root framing and operation setup/reset
 - `TypeResolver` owns registration and dynamic lookup
 
+#### C# target-keyed external serializers
+
+C# external-type serialization uses the target-keyed serializer resolver.
+
+`ForyStructAttribute` and `ForyEnumAttribute` carry an optional `Target` type.
+A local non-generic abstract class supplies an external struct schema, while an
+empty non-generic static class selects an external enum target:
+
+```csharp
+[ForyStruct(Target = typeof(ThirdParty.User))]
+internal abstract class UserSerializer
+{
+    [ForyField(1)]
+    public abstract string Name { get; }
+}
+
+[ForyEnum(Target = typeof(ThirdParty.Status))]
+internal static class StatusSerializer
+{
+}
+```
+
+These declarations are compile-time generator input only. They are never
+instantiated, reflected over by the runtime, registered, reference-published,
+or used as wire identities. The generator emits the canonical
+`Serializer<ThirdParty.User>` structural form and registers its generated
+factory under `ThirdParty.User`. External enums reuse
+`EnumSerializer<ThirdParty.Status>`. Application registration uses the target
+APIs:
+
+```csharp
+fory.Register<ThirdParty.User>(100);
+fory.Register<ThirdParty.Status>("example.Status");
+```
+
+The C# generator model must separate declaration identity from target identity,
+then reuse one structural serializer emitter for both ordinary and external
+targets. Runtime type positions, construction, member access, `TypeInfo`,
+compatible metadata, graph-memory ownership, reference publication, generated
+factory keys, root lookup, and dynamic lookup use the target. The declaration
+supplies only field names, IDs, schema descriptors, nullability, and the
+structural `Evolving` setting.
+
+Every generated ordinary or external struct uses
+`TypeResolver.RegisterGeneratedStruct<T, TSerializer>(bool evolving)` to carry
+generator-owned `Evolving` into the target `TypeInfo`. Generated enums and
+unions use `TypeResolver.RegisterGenerated<T, TSerializer>()`. `TypeInfo` does
+not recover structural metadata by reflecting a target attribute. The runtime
+must not reflect the external declaration, add a serializer capability
+interface, or create a second metadata registry. Multiple generated
+declarations for one target are rejected during generation when visible in one
+compilation and fail deterministically on the cold generated-factory
+registration path across assemblies. Explicit manual serializer registration
+uses the resolver's target replacement rules.
+
+External structural targets require an accessible concrete class or struct,
+legal parameterless construction, and directly readable and assignable
+members. Schema properties match target fields or properties by case-sensitive
+name and exact CLR/generic type. Explicit nullability must match; when target
+metadata is nullable-oblivious, the declaration supplies schema nullability.
+Immutable, constructor-only, factory-only, init-only, readonly, renamed,
+converted, or inaccessible shapes use a manual `Serializer<T>`. Generated
+class reads allocate and publish the final target before recursive children;
+target structs are inline values. The declaration is never a temporary graph
+owner.
+
+C# carrier composition is target-based. The resolver recursively
+binds `Nullable<T>`, one-dimensional `T[]`, `List<T>`, `LinkedList<T>`,
+`Queue<T>`, `Stack<T>`, `HashSet<T>`, `SortedSet<T>`,
+`ImmutableHashSet<T>`, `Dictionary<TKey, TValue>`,
+`SortedDictionary<TKey, TValue>`, `SortedList<TKey, TValue>`,
+`ConcurrentDictionary<TKey, TValue>`, and
+`NullableKeyDictionary<TKey, TValue>`. Ordinary generated targets, external
+structural serializers, manual serializers, fields, and roots use the same
+carrier bodies. External-type serialization has no carrier-provider family,
+field selector, root selector, callback, schema tree, per-element external
+dispatch, or additional allocation. Collection-interface, tuple, fixed-array,
+multidimensional-array, memory, and reference-wrapper families are unsupported.
+
+Dynamic `object` values and unions resolve concrete target types through
+`TypeResolver`. Arbitrary statically typed interface or base-class polymorphism
+is unsupported.
+
+External and equivalent ordinary generated hot bodies must be
+instruction-shape equivalent apart from target/member metadata tokens. Target
+selection is compile-time only. Cold duplicate-target error construction must
+stay out of successful hot-path inlining, and any dedicated cold error entrance
+must be marked no-inline. Successful serializer dispatch must not be marked
+cold.
+
 Rust names these serializer operation boundaries explicitly:
 
 - `Serializer::write` and `Serializer::read` process a complete value,
diff --git a/docs/specification/xlang_type_mapping.md 
b/docs/specification/xlang_type_mapping.md
index a3e877710a..800360f215 100644
--- a/docs/specification/xlang_type_mapping.md
+++ b/docs/specification/xlang_type_mapping.md
@@ -112,6 +112,12 @@ FDL spells them as an encoding modifier plus a semantic 
integer type.
 
 Notes:
 
+- C# external-type serialization maps a third-party class/struct or enum
+  through a local
+  `ForyStruct(Target = typeof(...))` or
+  `ForyEnum(Target = typeof(...))` serializer declaration. The runtime target
+  still uses the C# mapping shown above; declaration ownership is not a wire
+  distinction.
 - Python `pyfory.Float16` and `pyfory.BFloat16` are reserved annotation 
markers; scalar values deserialize as native Python `float`.
 - Python `BoolArray`, `Int8Array`, `Int16Array`, `Int32Array`, `Int64Array`, 
`UInt8Array`, `UInt16Array`, `UInt32Array`, `UInt64Array`, `Float16Array`, 
`BFloat16Array`, `Float32Array`, and `Float64Array` are public dense-array 
wrappers with list-like sequence behavior.
 - JavaScript `BoolArray`, fallback `Float16Array`, and `BFloat16Array` are 
public dense-array wrappers backed by `Uint8Array` or `Uint16Array`. Scalar 
`float16` and `bfloat16` values use `number`. A JavaScript environment with 
native `Float16Array` may return that native carrier for `array<float16>`.


---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]

Reply via email to