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 054358bf2c9b9f1ae60e6a970a083097a1943309
Author: chaokunyang <[email protected]>
AuthorDate: Sun Jul 26 16:15:33 2026 +0000

    πŸ”„ synced local 'docs/guide/' with remote 'docs/guide/'
---
 docs/guide/rust/basic-serialization.md  |  26 +-
 docs/guide/rust/custom-serializers.md   | 176 ----------
 docs/guide/rust/external-types.md       | 558 ++++++++++++++++++++++++++++++++
 docs/guide/rust/index.md                |   6 +-
 docs/guide/rust/manual-serializers.md   | 204 ++++++++++++
 docs/guide/rust/native-serialization.md |  62 +++-
 docs/guide/rust/polymorphism.md         | 308 ++++++++----------
 docs/guide/rust/schema-evolution.md     |  42 ++-
 docs/guide/rust/schema-metadata.md      |  48 ++-
 docs/guide/rust/troubleshooting.md      |  56 +++-
 docs/guide/rust/type-registration.md    |  24 +-
 docs/guide/rust/xlang-serialization.md  |  47 ++-
 12 files changed, 1184 insertions(+), 373 deletions(-)

diff --git a/docs/guide/rust/basic-serialization.md 
b/docs/guide/rust/basic-serialization.md
index f45049d087..a0253dce93 100644
--- a/docs/guide/rust/basic-serialization.md
+++ b/docs/guide/rust/basic-serialization.md
@@ -180,6 +180,29 @@ let mut reader = Reader::new(&buf);
 let decoded: MyStruct = fory.deserialize_from(&mut reader)?;
 ```
 
+When the Rust value type uses an external structural serializer or manual
+serializer, select it explicitly at the root:
+
+```rust
+let bytes = fory.serialize_with::<UserSerializer>(&user)?;
+let decoded: third_party::User =
+    fory.deserialize_with::<UserSerializer>(&bytes)?;
+```
+
+Carrier serializers compose the same selection for a root container:
+
+```rust
+use fory::VecSerializer;
+
+let bytes =
+    fory.serialize_with::<VecSerializer<UserSerializer>>(&users)?;
+let decoded: Vec<third_party::User> =
+    fory.deserialize_with::<VecSerializer<UserSerializer>>(&bytes)?;
+```
+
+See [External-Type Serialization](external-types.md) for field annotations,
+all supported carriers, and registration.
+
 ## Performance Tips
 
 - **Zero-Copy Deserialization**: Row format enables direct memory access 
without copying
@@ -192,4 +215,5 @@ let decoded: MyStruct = fory.deserialize_from(&mut reader)?;
 
 - [Type Registration](type-registration.md) - Registering types
 - [References](references.md) - Shared and circular references
-- [Custom Serializers](custom-serializers.md) - Manual serialization
+- [Manual Serializers](manual-serializers.md) - Customized serialization
+- [External-Type Serialization](external-types.md) - Third-party values and 
carrier roots
diff --git a/docs/guide/rust/custom-serializers.md 
b/docs/guide/rust/custom-serializers.md
deleted file mode 100644
index e5c273e0ab..0000000000
--- a/docs/guide/rust/custom-serializers.md
+++ /dev/null
@@ -1,176 +0,0 @@
----
-title: Custom Serializers
-sidebar_position: 10
-id: custom_serializers
-license: |
-  Licensed to the Apache Software Foundation (ASF) under one or more
-  contributor license agreements.  See the NOTICE file distributed with
-  this work for additional information regarding copyright ownership.
-  The ASF licenses this file to You under the Apache License, Version 2.0
-  (the "License"); you may not use this file except in compliance with
-  the License.  You may obtain a copy of the License at
-
-     http://www.apache.org/licenses/LICENSE-2.0
-
-  Unless required by applicable law or agreed to in writing, software
-  distributed under the License is distributed on an "AS IS" BASIS,
-  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-  See the License for the specific language governing permissions and
-  limitations under the License.
----
-
-For types that don't support `#[derive(ForyStruct)]`, implement the 
`Serializer` trait manually.
-
-## When to Use Custom Serializers
-
-- External types from other crates
-- Types with special serialization requirements
-- Existing data format compatibility
-- Performance-critical custom encoding
-
-## Implementing the Serializer Trait
-
-```rust
-use fory::{Error, Fory, ForyDefault, ReadContext, Serializer, TypeResolver, 
WriteContext};
-use std::any::Any;
-
-#[derive(Debug, PartialEq, Default)]
-struct CustomType {
-    value: i32,
-    name: String,
-}
-
-impl Serializer for CustomType {
-    fn fory_write_data(&self, context: &mut WriteContext) -> Result<(), Error> 
{
-        context.writer.write_i32(self.value);
-        context.writer.write_var_u32(self.name.len() as u32);
-        context.writer.write_utf8_string(&self.name);
-        Ok(())
-    }
-
-    fn fory_read_data(context: &mut ReadContext) -> Result<Self, Error> {
-        let value = context.reader.read_i32()?;
-        let len = context.reader.read_var_u32()? as usize;
-        let name = context.reader.read_utf8_string(len)?;
-        Ok(Self { value, name })
-    }
-
-    fn fory_type_id_dyn(&self, type_resolver: &TypeResolver) -> 
Result<fory::TypeId, Error> {
-        Self::fory_get_type_id(type_resolver)
-    }
-
-    fn as_any(&self) -> &dyn Any {
-        self
-    }
-}
-
-// ForyDefault delegates to Default
-impl ForyDefault for CustomType {
-    fn fory_default() -> Self {
-        Self::default()
-    }
-}
-```
-
-> **Note**: When implementing `ForyDefault` manually, ensure your type also 
implements `Default` if you use `Self::default()`.
-> Alternatively, you can construct a default instance directly in 
`fory_default()`.
->
-> **Tip**: If your type supports `#[derive(ForyStruct)]`, you can use 
`#[fory(generate_default)]` to automatically generate both `ForyDefault` and 
`Default` implementations.
-
-## Manual Serializers and Arc Any
-
-If a manually registered serializer needs its type to round-trip behind
-`Arc<dyn Any + Send + Sync>` or preserve `UnknownCase` payloads, implement the
-send-sync Any reader and return the concrete value as a boxed `Any` value:
-
-```rust
-impl Serializer for CustomType {
-    fn fory_read_data_as_send_sync_any(
-        context: &mut ReadContext,
-    ) -> Result<Box<dyn Any + Send + Sync>, Error> {
-        Ok(Box::new(Self::fory_read_data(context)?))
-    }
-
-    // Implement the ordinary Serializer methods as shown above.
-    // ...
-}
-```
-
-Do not override this method for values that contain fields whose types are not
-`Send + Sync`, such as `Rc<T>`, `RcWeak<T>`, `RefCell<T>`, or `Cell<T>`.
-
-## Registering Custom Serializers
-
-```rust
-let mut fory = Fory::builder().xlang(false).build();
-fory.register_serializer::<CustomType>(100)?;
-
-let custom = CustomType {
-    value: 42,
-    name: "test".to_string(),
-};
-let bytes = fory.serialize(&custom)?;
-let decoded: CustomType = fory.deserialize(&bytes)?;
-assert_eq!(custom, decoded);
-```
-
-## WriteContext and ReadContext
-
-The `WriteContext` and `ReadContext` provide access to:
-
-- **writer/reader**: Binary buffer operations
-- **type_resolver**: Type registration information
-- **ref_resolver**: Reference tracking (for shared/circular references)
-
-### Common Writer Methods
-
-```rust
-// Primitive types
-context.writer.write_i8(value);
-context.writer.write_i16(value);
-context.writer.write_i32(value);
-context.writer.write_i64(value);
-context.writer.write_f32(value);
-context.writer.write_f64(value);
-context.writer.write_bool(value);
-
-// Variable-length integers
-context.writer.write_var_i32(value);
-context.writer.write_var_u32(value);
-
-// Strings
-context.writer.write_utf8_string(&string);
-```
-
-### Common Reader Methods
-
-```rust
-// Primitive types
-let value = context.reader.read_i8();
-let value = context.reader.read_i16();
-let value = context.reader.read_i32();
-let value = context.reader.read_i64();
-let value = context.reader.read_f32();
-let value = context.reader.read_f64();
-let value = context.reader.read_bool();
-
-// Variable-length integers
-let value = context.reader.read_var_i32();
-let value = context.reader.read_var_u32();
-
-// Strings
-let string = context.reader.read_utf8_string(len);
-```
-
-## Best Practices
-
-1. **Use variable-length encoding** for integers that may be small
-2. **Write length first** for variable-length data
-3. **Handle errors properly** in read methods
-4. **Implement ForyDefault** for schema evolution support
-
-## Related Topics
-
-- [Type Registration](type-registration.md) - Registering serializers
-- [Basic Serialization](basic-serialization.md) - Using ForyStruct derive
-- [Schema Evolution](schema-evolution.md) - Compatible mode
diff --git a/docs/guide/rust/external-types.md 
b/docs/guide/rust/external-types.md
new file mode 100644
index 0000000000..354c37123d
--- /dev/null
+++ b/docs/guide/rust/external-types.md
@@ -0,0 +1,558 @@
+---
+title: External-Type Serialization
+sidebar_position: 14
+id: external_types
+license: |
+  Licensed to the Apache Software Foundation (ASF) under one or more
+  contributor license agreements.  See the NOTICE file distributed with
+  this work for additional information regarding copyright ownership.
+  The ASF licenses this file to You under the Apache License, Version 2.0
+  (the "License"); you may not use this file except in compliance with
+  the License.  You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+---
+
+Rust external-type serialization lets an application serialize a type owned by
+another crate without a wrapper value. Use a derived external structural
+serializer for an accessible public schema, or a manual serializer for an
+opaque or invariant-bearing type.
+
+## One serializer model
+
+A serializer implementation declares the Rust value type it handles:
+
+```rust
+pub trait Serializer {
+    type Target;
+
+    fn write_data(
+        value: &Self::Target,
+        context: &mut WriteContext,
+    ) -> Result<(), Error>;
+
+    fn read_data(context: &mut ReadContext) -> Result<Self::Target, Error>;
+}
+```
+
+For an ordinary local type, the type provides itself. For an external type, a
+local serializer supplies the behavior without wrapping or converting the
+application value. These methods handle body data; Fory's complete-value
+`write` and `read` operations add the requested reference and type-information
+envelopes.
+
+When a root is a container such as `Vec<third_party::User>`, compose
+Fory-owned carrier serializers such as `VecSerializer<UserSerializer>`. These 
are
+compile-time types and are never instantiated.
+
+There is no separate public field serializer, adapter, encoder, or decoder
+trait.
+
+## External structural serializers
+
+Use an external structural serializer when every target field or enum variant 
is publicly
+accessible and the target can be constructed directly with the same shape:
+
+```rust
+use fory::ForyStruct;
+
+#[derive(ForyStruct)]
+#[fory(target = third_party::User)]
+struct UserSerializer {
+    name: String,
+    age: u32,
+}
+```
+
+The external structural serializer is a schema and code-generation declaration.
+Fory never constructs a `UserSerializer` value. Generated code reads fields
+from `third_party::User` and constructs `third_party::User` directly.
+
+For an external enum or union, the external structural serializer declaration
+defines the wire schema. In xlang mode, explicit Fory IDs and declaration-order
+fallbacks define ENUM or UNION tags. Native data enums retain the existing
+local `ForyUnion` tag rules; external-type serialization does not give explicit
+IDs a new native meaning. The external enum's source declaration order does
+not define the schema. Generated exhaustive matching still verifies the target
+variant names and shapes.
+
+External structural serializers for structs and pure enums retain the existing
+STRUCT and ENUM formats. Xlang-compatible data enums retain UNION, while
+native struct-style enums retain the existing `xlang = false` Rust enum format.
+The serializer declaration does not appear on the wire.
+
+Private, invariant-bearing, or `#[non_exhaustive]` targets are not eligible for
+an external structural serializer.
+
+An xlang-compatible data enum uses `ForyUnion` and the existing union case
+rules:
+
+```rust
+use fory::{ForyUnion, UnknownCase};
+
+#[derive(ForyUnion)]
+#[fory(target = third_party::Value<UnknownCase>)]
+enum ValueSerializer {
+    #[fory(default)]
+    Null,
+    Text(String),
+    Count(i64),
+    #[fory(unknown)]
+    Unknown(UnknownCase),
+}
+```
+
+The target must represent the same runtime unknown carrier for lossless xlang
+union reads. A third-party crate can remain independent of Fory by declaring a
+generic enum such as `Value<U>`; the application sets the serializer target to
+`Value<UnknownCase>`. A target that cannot carry unknown cases is not eligible
+for lossless external xlang-union serialization.
+
+### Native struct-style enums
+
+With `xlang = false`, an external structural serializer supports the complete
+Rust data-enum surface: unit variants, tuple variants with one or more fields,
+named variants with one or more fields, and any mixture of those shapes.
+
+```rust
+use fory::ForyUnion;
+
+#[derive(ForyUnion)]
+#[fory(target = third_party::Command)]
+enum CommandSerializer {
+    #[fory(default)]
+    Idle,
+    Create {
+        #[fory(with = UuidSerializer)]
+        id: uuid::Uuid,
+        label: String,
+    },
+    Move(i32, i32),
+}
+```
+
+`ForyUnion` remains the one derive for data-carrying Rust enums; there is no
+separate native-enum macro. Direct, carrier, list-element, map key/value, and
+heterogeneous tuple-position serializer annotations also work inside tuple and
+named variant payloads.
+Native struct-style enums work with both compatible and schema-consistent
+native serialization.
+
+An xlang union case can carry at most one alternative value. Consequently, a
+multi-field tuple or named Rust variant is native-only. Registering a 
serializer
+for such an enum while `xlang = true` returns an error before registration is
+published. Fory does not discard fields, synthesize hidden variant structs, or
+silently encode the type as EXT.
+
+## Manual serializers
+
+Use a manual serializer for opaque types such as UUID or Jiff values:
+
+```rust
+use fory::{Error, ReadContext, Serializer, WriteContext};
+use std::any::Any;
+use std::sync::Arc;
+
+struct UuidSerializer;
+
+#[cold]
+#[inline(never)]
+fn invalid_uuid(error: uuid::Error) -> Error {
+    Error::invalid_data(error.to_string())
+}
+
+impl Serializer for UuidSerializer {
+    type Target = uuid::Uuid;
+
+    fn write_data(
+        value: &uuid::Uuid,
+        context: &mut WriteContext,
+    ) -> Result<(), Error> {
+        context.writer.write_bytes(value.as_bytes());
+        Ok(())
+    }
+
+    fn read_data(context: &mut ReadContext) -> Result<uuid::Uuid, Error> {
+        let bytes = context.reader.read_bytes(16)?;
+        uuid::Uuid::from_slice(bytes).map_err(invalid_uuid)
+    }
+
+    // Required only for sync Arc dynamic carriers.
+    fn read_arc_any(
+        context: &mut ReadContext,
+    ) -> Result<Arc<dyn Any + Send + Sync>, Error> {
+        let value: Arc<dyn Any + Send + Sync> =
+            Arc::new(Self::read_data(context)?);
+        Ok(value)
+    }
+}
+```
+
+Manual serializers use the existing EXT or NAMED_EXT wire kinds. Their internal
+body evolution is application-owned. If a body length controls an allocation,
+the manual serializer must use the read context's byte-availability and 
graph-memory
+checks before reserving or allocating that storage.
+
+When a manual serializer is composed under a variable-size carrier, the
+carrier's complete bytes after its count must average at least one byte per
+declared element or map entry. Fory checks this once after writing the carrier
+and returns an error for a body that is too compact for the paired
+allocation-safety check. Fixed arrays, and zero-sized elements in `Vec`,
+`VecDeque`, or `BinaryHeap`, do not allocate storage from that count and are
+exempt.
+
+Fory invokes the optional `read_arc_any` method only after reserving the final
+Arc owner; the method shown above performs that allocation once and must not
+reserve the same outer owner again. A manual serializer that does not need sync
+Arc dynamic carriers omits it and remains valid for typed, Box, and Rc uses;
+attempting sync Arc materialization then returns an unsupported error.
+
+## Fields and nested values
+
+A static external value names its serializer explicitly:
+
+```rust
+use fory::{ForyStruct, MutexSerializer, RefCellSerializer};
+use std::cell::RefCell;
+use std::sync::Mutex;
+
+#[derive(ForyStruct)]
+struct Request {
+    #[fory(with = UuidSerializer)]
+    request_id: uuid::Uuid,
+
+    #[fory(with = UserSerializer)]
+    user: third_party::User,
+
+    #[fory(with = RefCellSerializer<UserSerializer>)]
+    mutable_user: RefCell<third_party::User>,
+
+    #[fory(with = MutexSerializer<UserSerializer>)]
+    locked_user: Mutex<third_party::User>,
+}
+```
+
+`with` selects one serializer whose target is the exact declared field type.
+For `Option`, `Box`, `Rc`, `Arc`, Fory weak-reference carriers, `RefCell`, and
+`Mutex`, select the corresponding carrier serializer around the child
+serializer. For example, use `OptionSerializer<UserSerializer>` for
+`Option<third_party::User>` and `ArcSerializer<UserSerializer>` for
+`Arc<third_party::User>`. `RefCell` and `Mutex` retain the child wire shape;
+serialization of these direct fields uses one borrow or lock, and
+deserialization constructs the holder directly without an additional heap
+owner. Compatible schema evolution remains active for an external structural
+serializer nested behind any of these wrappers.
+
+In a non-skipped derived field, keep every carrier constructor's canonical name
+visible, optionally with its module path. This applies both to the field's Rust
+type and to a `with` serializer tree. For example, write
+`Vec<third_party::User>` and `VecSerializer<UserSerializer>` directly instead
+of hiding either carrier tree behind a type alias or renamed import. Leaf
+serializer aliases remain valid. Carrier aliases also remain valid at roots,
+where Rust resolves the serializer type without field code generation. A
+skipped field may also use a carrier alias because it emits no field schema and
+uses only the selected serializer's default.
+
+A skipped external field can use `#[fory(skip, with = UserSerializer)]`. In 
that
+case the serializer is used only for its fallible construction default; the
+field contributes no schema or body bytes. Registration is unnecessary when
+that skipped default is the serializer's only use. The default receives the
+active read context and must reserve graph memory before any owned allocation.
+Skipped list/map/tuple fields can retain recursive child serializer 
annotations,
+although an empty container default does not invoke its children.
+
+List elements, map children, and tuple positions select serializers at their 
own
+recursive schema nodes:
+
+```rust
+use fory::{ForyStruct, VecSerializer};
+use std::collections::HashMap;
+
+#[derive(ForyStruct)]
+struct Directory {
+    #[fory(with = VecSerializer<UserSerializer>)]
+    direct_users: Vec<third_party::User>,
+
+    #[fory(list(element(with = UserSerializer)))]
+    users: Vec<third_party::User>,
+
+    #[fory(map(
+        key(with = ExternalKeySerializer),
+        value(with = UserSerializer)
+    ))]
+    by_key: HashMap<third_party::Key, third_party::User>,
+
+    #[fory(tuple(
+        element(index = 0, with = ExternalKeySerializer),
+        element(index = 1, list(element(with = UserSerializer)))
+    ))]
+    entry: (third_party::Key, Vec<third_party::User>),
+}
+```
+
+Tuple indexes are zero-based. Unmentioned tuple positions use their ordinary
+serializer, and tuple elements can contain the same recursive list, map, or
+tuple metadata. Tuples are supported from arity 1 through 22.
+
+Recursive field selection covers `Vec`, `VecDeque`, `LinkedList`, `HashSet`,
+`BTreeSet`, `BinaryHeap`, fixed arrays, `HashMap`, `BTreeMap`, and tuple
+arities 1 through 22. `direct_users` selects a carrier serializer for the exact
+Vec node; `users` selects the element serializer recursively. Both forms use 
the
+same built-in Vec implementation and structural LIST representation. A 
serializer
+annotation applies only to its declared node; it never silently propagates
+through a composite.
+
+A node-local `#[fory(with = PackedUsersSerializer)]` may instead select one
+manual serializer whose exact target is the whole `Vec`, map, set, array, or
+tuple. That field uses opaque EXT/NAMED_EXT encoding and has no child schema.
+It cannot also use `list`, `map`, `tuple`, `array`, `bytes`, or `encoding`.
+Recursive list/map/tuple annotations are the distinct choice when the composite
+should retain its structural wire kind and only its children need selected
+serializers. This opaque customization is not a user-declared carrier
+serializer and cannot compose child serializers.
+
+If that exact whole-container manual serializer is registered, erased 
polymorphic values
+of the exact target use it. Ordinary unannotated typed fields and roots whose
+children self-provide keep using the built-in structural container format;
+explicit carrier serializer roots also keep their declared structural format.
+Registration does not redirect those static paths.
+
+## Root values
+
+Ordinary local roots retain `serialize`, `serialize_to`, `deserialize`, and
+`deserialize_from`.
+
+An external root selects its serializer:
+
+```rust
+let bytes = fory.serialize_with::<UserSerializer>(&user)?;
+let decoded =
+    fory.deserialize_with::<UserSerializer>(&bytes)?;
+```
+
+The complete serializer-selected root family is:
+
+- `serialize_with`;
+- `serialize_to_with`;
+- `deserialize_with`;
+- `deserialize_from_with`.
+
+The serializer is a compile-time type parameter. No serializer instance, 
wrapper,
+or mirror value is passed at runtime.
+
+For a container root, compose the corresponding Fory-owned carrier serializer:
+
+```rust
+use fory::VecSerializer;
+
+fory.register::<UserSerializer>(100)?;
+
+let users: Vec<third_party::User> = load_users();
+let bytes =
+    fory.serialize_with::<VecSerializer<UserSerializer>>(&users)?;
+let decoded: Vec<third_party::User> =
+    fory.deserialize_with::<VecSerializer<UserSerializer>>(&bytes)?;
+```
+
+`VecSerializer<UserSerializer>` targets `Vec<third_party::User>` and keeps the
+normal LIST format. Register selected external structural serializers such as
+`UserSerializer`; do not register the carrier serializer itself.
+
+Map keys, map values, and nested containers compose recursively:
+
+```rust
+use fory::{HashMapSerializer, VecSerializer};
+
+type DirectorySerializer =
+    HashMapSerializer<ExternalKeySerializer, VecSerializer<UserSerializer>>;
+
+let bytes =
+    fory.serialize_with::<DirectorySerializer>(&directory)?;
+```
+
+For nested lists, `VecSerializer<VecSerializer<UserSerializer>>` targets
+`Vec<Vec<third_party::User>>`.
+
+Heterogeneous tuple roots compose by position:
+
+```rust
+use fory::Tuple2Serializer;
+
+type EntrySerializer =
+    Tuple2Serializer<String, UserSerializer>;
+
+let bytes =
+    fory.serialize_with::<EntrySerializer>(&entry)?;
+```
+
+`EntrySerializer` targets `(String, third_party::User)`. The tuple carrier 
serializer
+keeps the same native or heterogeneous LIST representation as an ordinary
+two-position tuple.
+
+The complete carrier serializer family is:
+
+- `OptionSerializer`, `BoxSerializer`, `RcSerializer`, `ArcSerializer`,
+  `RcWeakSerializer`, `ArcWeakSerializer`, `RefCellSerializer`, and
+  `MutexSerializer`;
+- `VecSerializer`, `VecDequeSerializer`, `LinkedListSerializer`,
+  `HashSetSerializer`, `BTreeSetSerializer`, `BinaryHeapSerializer`, and
+  `ArraySerializer`;
+- `HashMapSerializer` and `BTreeMapSerializer`;
+- `Tuple1Serializer` through `Tuple22Serializer`.
+
+There is no `Tuple0Serializer`: `()` has no child and remains self-provided.
+`PhantomData<T>` also has no serialized child and needs no serializer
+composition.
+
+`Cell<T>` is not a currently supported Rust serialization carrier and does not
+have a `CellSerializer`. `RefCell<T>` is the supported interior-mutability
+carrier. Standard-library `Weak<T>` is also not an alias for Fory's
+`RcWeak<T>` or `ArcWeak<T>`.
+
+Every child argument is another serializer type. It can be an ordinary 
serializer targeting itself,
+an external structural serializer, a manual leaf serializer, or another 
Fory-owned carrier
+serializer. All four forms preserve the carrier's built-in encoding. An 
ordinary
+local type is its own serializer, so
+`HashMapSerializer<String, UserSerializer>` targets
+`HashMap<String, third_party::User>`.
+`ArraySerializer<S, N>` uses the same carrier selection as the chosen child
+serializer. A canonical primitive serializer such as `i32` retains its
+dense-array format, while an external structural or manual child serializer
+uses LIST even if its target is a primitive Rust type.
+
+`VecSerializer<S>` also preserves the ordinary Vec format selected by its
+child. `VecSerializer<i32>` uses `INT32_ARRAY`,
+`VecSerializer<u8>` uses `BINARY`, and
+`VecSerializer<UserSerializer>` uses LIST. A nested
+`VecSerializer<VecSerializer<i32>>` uses an outer LIST whose element type is
+the ordinary `INT32_ARRAY` representation. Serializer composition never turns a
+canonical primitive vector into an object LIST.
+
+Generated fields keep their declared field schema. An unannotated `Vec<i32>`
+field is `LIST<VARINT32>`, and
+`#[fory(list(element(encoding = fixed)))] Vec<i32>` is `LIST<INT32>`.
+`#[fory(array)]` selects a dense array and `#[fory(bytes)]` selects BINARY. All
+of these forms, including `VecSerializer<S>` roots, preserve the built-in Vec
+encoding selected by their declared schema.
+
+Fory never infers a serializer composition from a target type or from
+registration. Name every external child serializer explicitly in the carrier 
serializer
+type. A field can select an exact carrier serializer with `with`, such as
+`#[fory(with = VecSerializer<UserSerializer>)]`. Use the inline
+`list(element(...))` or `map(key(...), value(...))` grammar, or indexed
+`tuple(element(...))` grammar, when serializers are selected at recursive child
+nodes.
+
+An exact whole-container or whole-tuple manual serializer remains a valid 
opaque
+root, but it uses EXT/NAMED_EXT instead of the built-in structural
+representation and does not select child serializers.
+
+The `_with` method suffix means its generic argument selects the serializer,
+matching `#[fory(with = UserSerializer)]`.
+
+## Registration
+
+Structural and manual serializers use the existing registration categories.
+Choose one identity style for each serializer.
+
+Numeric registration:
+
+```rust
+fory.register::<UserSerializer>(100)?;
+fory.register::<CommandSerializer>(101)?; // Native struct-style enum.
+fory.register_union::<ValueSerializer>(102)?; // Xlang-compatible union.
+fory.register_serializer::<UuidSerializer>(103)?;
+```
+
+Name registration:
+
+```rust
+fory.register_by_name::<UserSerializer>("example.User")?;
+fory.register_by_name::<CommandSerializer>("example.Command")?;
+fory.register_union_by_name::<ValueSerializer>("example.Value")?;
+fory.register_serializer_by_name::<UuidSerializer>("example.Uuid")?;
+```
+
+Registration associates the wire identity with the serializer's target. One
+`Fory` instance accepts only one registered dynamic serializer for a given
+target. Registering it does not replace an ordinary static serializer or
+implicitly select it for an unannotated field or root. Complete registration
+before the first serialization operation. Register each structural or manual
+external child; never register a carrier serializer.
+
+Carrier composition does not make the entire container a dynamic `Any` target.
+If the exact whole container must participate in erased dynamic dispatch,
+register a manual exact-target serializer and use its EXT/NAMED_EXT
+representation.
+
+## Polymorphism
+
+Registered external targets participate in `Box<dyn Any>` and `Rc<dyn Any>`
+through their target identity. A `Send + Sync` target also participates in
+`Arc<dyn Any + Send + Sync>` when its structural derive generated the Arc
+materializer or its manual serializer implemented `read_arc_any`.
+
+These erased carriers work in native and xlang modes when the selected concrete
+serializer supports that mode. The Rust carrier and application trait name are
+not written; xlang mode still requires each concrete target to have an
+xlang-representable structural or EXT identity.
+
+Application traits extend a small object-safe `ForyObject` trait instead of
+`Serializer`:
+
+```rust
+use fory::{register_trait_type, ForyObject};
+
+trait Animal: ForyObject {
+    fn name(&self) -> &str;
+}
+
+register_trait_type!(Animal, Dog, third_party::Cat);
+```
+
+The concrete target list is closed and explicit. Each target can use an
+ordinary serializer, an external structural serializer, or a manual serializer.
+
+For `Arc<dyn Trait>`, the sync form requires the trait and listed targets to
+implement `Send + Sync`:
+
+```rust
+use fory::{register_trait_type, ForyObject};
+
+trait Animal: ForyObject + Send + Sync {
+    fn name(&self) -> &str;
+}
+
+register_trait_type!(sync Animal, Dog, third_party::Cat);
+```
+
+Use either the non-sync or sync declaration and macro invocation for a given
+trait, not both.
+
+Generated trait-root serializer names are private to the macro's module by
+default. A library can export them with
+`register_trait_type!(pub Animal, ...)` or
+`register_trait_type!(pub sync Animal, ...)`; the trait and listed targets must
+be visible at least as broadly.
+
+`Box<dyn Animal>` remains a direct root. The macro generates zero-sized
+serializer types for `Rc<dyn Animal>` and, for the sync macro form,
+`Arc<dyn Animal>` roots. It does not generate Rc/Arc value wrappers or perform
+wrapper conversions.
+
+The trait carrier serializers are not registered by ID or name. Applications
+register each allowed concrete target through its ordinary serializer,
+external structural serializer, or manual serializer.
+
+## Related Topics
+
+- [Manual Serializers](manual-serializers.md)
+- [Polymorphism](polymorphism.md)
+- [Type Registration](type-registration.md)
+- [Schema Evolution](schema-evolution.md)
diff --git a/docs/guide/rust/index.md b/docs/guide/rust/index.md
index 27a44e2153..e519a95fec 100644
--- a/docs/guide/rust/index.md
+++ b/docs/guide/rust/index.md
@@ -100,7 +100,7 @@ fn main() -> Result<(), Error> {
 
 Use xlang mode for cross-language payloads and schemas shared with other Fory 
implementations. Xlang mode is the default Rust wire mode, and Rust examples 
that use it set `.xlang(true)` explicitly so the mode choice is visible.
 
-Use native mode for Rust-only traffic. Native mode is selected with 
`.xlang(false)` and keeps Rust object serialization in Rust-native form. It is 
optimized for Rust's type system and covers Rust-specific object features such 
as trait objects and shared-reference patterns that are not portable xlang 
payloads. Compatible mode is enabled by default. Set `.compatible(false)` only 
when every reader and writer uses the same Rust schema and you want faster 
serialization and smaller size.
+Use native mode for Rust-only traffic. Native mode is selected with 
`.xlang(false)` and keeps Rust object serialization in Rust-native form. It 
supports native-only concrete targets and data-enum shapes that have no xlang 
representation. Dynamic `Any`, application trait, and shared-reference carriers 
can also be used in xlang mode when every selected concrete target is 
xlang-compatible. Compatible mode is enabled by default. Set 
`.compatible(false)` only when every reader and writer uses [...]
 
 See [Xlang Serialization](xlang-serialization.md) for Rust xlang registration 
and interoperability rules, and [Native Serialization](native-serialization.md) 
for Rust-only payloads.
 
@@ -196,6 +196,8 @@ fory-derive/           # Procedural macros
 - [Native Serialization](native-serialization.md) - Rust-only serialization
 - [References](references.md) - Shared and circular references
 - [Polymorphism](polymorphism.md) - Trait object serialization
-- [Custom Serializers](custom-serializers.md) - Extend serialization behavior
+- [Manual Serializers](manual-serializers.md) - Implement customized 
serialization behavior
+- [External-Type Serialization](external-types.md) - External structural and 
manual serializers
+  plus carrier composition
 - [Row Format](row-format.md) - Zero-copy row-based format
 - [gRPC Support](grpc-support.md) - Fory payloads over tonic
diff --git a/docs/guide/rust/manual-serializers.md 
b/docs/guide/rust/manual-serializers.md
new file mode 100644
index 0000000000..c68071f954
--- /dev/null
+++ b/docs/guide/rust/manual-serializers.md
@@ -0,0 +1,204 @@
+---
+title: Manual Serializers
+sidebar_position: 10
+id: manual_serializers
+license: |
+  Licensed to the Apache Software Foundation (ASF) under one or more
+  contributor license agreements.  See the NOTICE file distributed with
+  this work for additional information regarding copyright ownership.
+  The ASF licenses this file to You under the Apache License, Version 2.0
+  (the "License"); you may not use this file except in compliance with
+  the License.  You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+---
+
+Use a manual serializer when derive cannot express the type's serialized
+representation or when an opaque encoding is intentional. A serializer is a
+type-level implementation and names the value it handles through `Target`.
+
+For a public third-party struct or enum whose schema should remain structural,
+prefer [External-Type Serialization](external-types.md).
+
+## Implement a Manual Serializer
+
+This example uses a local type as its own serializer:
+
+```rust
+use fory::{Error, Fory, ReadContext, Serializer, WriteContext};
+
+#[derive(Debug, PartialEq)]
+struct Point {
+    value: i32,
+}
+
+impl Serializer for Point {
+    type Target = Self;
+
+    fn write_data(value: &Self, context: &mut WriteContext) -> Result<(), 
Error> {
+        context.writer.write_i32(value.value);
+        Ok(())
+    }
+
+    fn read_data(context: &mut ReadContext) -> Result<Self, Error> {
+        Ok(Self {
+            value: context.reader.read_i32()?,
+        })
+    }
+
+    fn default_value(_context: &mut ReadContext) -> Result<Self, Error> {
+        Ok(Self { value: 0 })
+    }
+}
+
+let mut fory = Fory::builder().xlang(false).build();
+fory.register_serializer::<Point>(100)?;
+
+let value = Point { value: 42 };
+let bytes = fory.serialize(&value)?;
+let decoded: Point = fory.deserialize(&bytes)?;
+assert_eq!(decoded, value);
+# Ok::<(), Error>(())
+```
+
+`write_data` and `read_data` handle the EXT body. Fory's complete-value
+`write` and `read` operations supply the root or field reference and
+type-information framing.
+
+`default_value` is optional. Implement it only when a null or missing
+compatible field has a meaningful value. It receives the active `ReadContext`,
+so a default that allocates can apply the same deserialization limits as a
+normal read.
+
+## Serialize a Third-Party Opaque Type
+
+A separate serializer can target a type from another crate:
+
+```rust
+use fory::{Error, ReadContext, Serializer, WriteContext};
+
+struct UuidSerializer;
+
+#[cold]
+#[inline(never)]
+fn invalid_uuid(error: uuid::Error) -> Error {
+    Error::invalid_data(error.to_string())
+}
+
+impl Serializer for UuidSerializer {
+    type Target = uuid::Uuid;
+
+    fn write_data(
+        value: &uuid::Uuid,
+        context: &mut WriteContext,
+    ) -> Result<(), Error> {
+        context.writer.write_bytes(value.as_bytes());
+        Ok(())
+    }
+
+    fn read_data(context: &mut ReadContext) -> Result<uuid::Uuid, Error> {
+        let bytes = context.reader.read_bytes(16)?;
+        uuid::Uuid::from_slice(bytes).map_err(invalid_uuid)
+    }
+}
+```
+
+Register the serializer, then select it at the root or field:
+
+```rust
+fory.register_serializer::<UuidSerializer>(101)?;
+
+let bytes = fory.serialize_with::<UuidSerializer>(&uuid)?;
+let decoded =
+    fory.deserialize_with::<UuidSerializer>(&bytes)?;
+```
+
+```rust
+#[derive(ForyStruct)]
+struct Request {
+    #[fory(with = UuidSerializer)]
+    id: uuid::Uuid,
+}
+```
+
+Manual serializer bodies are opaque. Compatible mode does not map fields
+inside them.
+
+## Support `Arc<dyn Any + Send + Sync>`
+
+If a manual serializer's target must be materialized behind
+`Arc<dyn Any + Send + Sync>` or a synchronized application trait, implement
+`read_arc_any`:
+
+```rust
+use std::any::Any;
+use std::sync::Arc;
+
+impl Serializer for Point {
+    type Target = Self;
+
+    // Implement write_data, read_data, and any desired default as above.
+
+    fn read_arc_any(
+        context: &mut ReadContext,
+    ) -> Result<Arc<dyn Any + Send + Sync>, Error> {
+        Ok(Arc::new(Self::read_data(context)?))
+    }
+}
+```
+
+The target must implement `Send + Sync`. If this method is omitted, typed,
+`Box`, and `Rc` operations remain available, while synchronized `Arc`
+materialization returns an error.
+
+## Registration by Name
+
+Use name registration when the serialized identity is a qualified name:
+
+```rust
+fory.register_serializer_by_name::<UuidSerializer>(
+    "example.Uuid",
+)?;
+```
+
+One `Fory` instance can register at most one serializer for a target.
+
+## Context Access
+
+`WriteContext` and `ReadContext` expose the binary writer and reader:
+
+```rust
+context.writer.write_i8(value);
+context.writer.write_i32(value);
+context.writer.write_var_u32(value);
+context.writer.write_f64(value);
+
+let value = context.reader.read_i8()?;
+let value = context.reader.read_i32()?;
+let value = context.reader.read_var_u32()?;
+let value = context.reader.read_f64()?;
+```
+
+For variable-size bodies, validate readable bytes and graph-memory limits
+before allocating from an encoded length.
+
+When a manual serializer is selected as a child of a variable-size carrier,
+the carrier must emit at least one aggregate byte per declared element or map
+entry after its count. Fory rejects serialization when the carrier's complete
+header, metadata, framing, and child bodies are shorter than that count, so it
+never emits bytes that the paired allocation-safety check cannot read. Fixed
+arrays are exempt because their validated count does not control an
+allocation; zero-sized elements in `Vec`, `VecDeque`, and `BinaryHeap` are also
+exempt because those carriers allocate no backing storage for them.
+
+## Related Topics
+
+- [External-Type Serialization](external-types.md)
+- [Type Registration](type-registration.md)
+- [Schema Evolution](schema-evolution.md)
diff --git a/docs/guide/rust/native-serialization.md 
b/docs/guide/rust/native-serialization.md
index d00c1408e2..40a164ac25 100644
--- a/docs/guide/rust/native-serialization.md
+++ b/docs/guide/rust/native-serialization.md
@@ -32,8 +32,9 @@ Kotlin, or another non-Rust Fory implementation.
 Use native serialization when:
 
 - A payload is produced and consumed only by Rust applications.
-- The data model uses Rust-specific object graph features such as `Rc<T>`, 
`Arc<T>`, weak
-  pointers, `RefCell<T>`, `Mutex<T>`, trait objects, or `dyn Any`.
+- The data model uses Rust-specific object graph features such as typed 
`Rc<T>`, `Arc<T>`, weak
+  pointers, `RefCell<T>`, or `Mutex<T>`, or uses native-only concrete targets 
behind trait objects
+  or `dyn Any`.
 - You want faster serialization and smaller size, and every reader uses the 
same schema as the
   writer.
 - You need compatible schema evolution for Rust-only rolling deployments.
@@ -87,8 +88,11 @@ every reader and writer always uses the same Rust schema.
 Register application structs and enum-like types before serialization:
 
 ```rust
+// Choose a numeric ID:
 fory.register::<Order>(100)?;
-fory.register_by_name::<Order>("example.Order")?;
+
+// Or, on a different Fory instance, choose a qualified name:
+// fory.register_by_name::<Order>("example.Order")?;
 ```
 
 Use explicit numeric IDs for compact payloads and stable deployments. Use 
named registration
@@ -106,8 +110,9 @@ Native serialization owns the Rust-specific object surface:
 - Trait objects such as `Box<dyn Trait>`, `Rc<dyn Trait>`, and `Arc<dyn 
Trait>`.
 - Runtime type dispatch with `Box<dyn Any>`, `Rc<dyn Any>`, and
   `Arc<dyn Any + Send + Sync>` for registered non-container payloads. Wrap
-  containers in registered structs, enums, or unions before using them behind
-  erased `Any` carriers.
+  containers in registered structs, enums, or unions, or register an
+  exact-target manual serializer when an opaque EXT/NAMED_EXT representation
+  is appropriate.
 - Date and time carriers, including optional `chrono` support.
 
 Use [Basic Serialization](basic-serialization.md), 
[References](references.md), and
@@ -144,12 +149,13 @@ when the target has been dropped.
 
 ## Trait Objects
 
-Trait objects are Rust language features and belong in native serialization:
+Trait objects are Rust language features, but their registered concrete targets
+can use either native or xlang serialization. This example uses native mode:
 
 ```rust
-use fory::{register_trait_type, Error, Fory, ForyStruct, Serializer};
+use fory::{register_trait_type, Error, Fory, ForyObject, ForyStruct};
 
-trait Animal: Serializer {
+trait Animal: ForyObject {
     fn name(&self) -> &str;
 }
 
@@ -180,6 +186,36 @@ fn main() -> Result<(), Error> {
 
 Register every concrete implementation that can appear behind the trait object.
 
+## Third-Party Struct-Style Enums
+
+Native mode supports external structural serializers for Rust enums with unit,
+tuple, and named multi-field variants:
+
+```rust
+use fory::{Fory, ForyUnion};
+
+#[derive(ForyUnion)]
+#[fory(target = third_party::Command)]
+enum CommandSerializer {
+    #[fory(default)]
+    Idle,
+    Move(i32, i32),
+    Create { id: u128, label: String },
+}
+
+let mut fory = Fory::builder()
+    .xlang(false)
+    .compatible(true)
+    .build();
+fory.register::<CommandSerializer>(101)?;
+```
+
+The same serializer works with `compatible(false)` when both peers use the
+same schema. Multi-field tuple and named variants have no xlang union mapping,
+so registering this serializer with `xlang(true)` returns an error. See
+[External-Type Serialization](external-types.md) for field, carrier, root, and
+manual serializer composition.
+
 ## Performance Guidelines
 
 - Reuse a configured `Fory` instance and register types before concurrent use.
@@ -195,12 +231,16 @@ Register every concrete implementation that can appear 
behind the trait object.
 | -------------------------------------- | ------------------------ | 
----------------------- |
 | Rust-only payloads                     | Yes                      | Optional 
               |
 | Non-Rust readers or writers            | No                       | Yes      
               |
-| `Rc`, `Arc`, weak pointers             | Yes                      | No       
               |
-| Trait objects and `dyn Any`            | Yes                      | No       
               |
-| Same-schema compact payloads           | Yes                      | No       
               |
+| Typed shared and weak references       | Yes                      | No       
               |
+| Trait objects and `dyn Any`            | Yes                      | 
Conditional             |
+| Same-schema compact payloads           | Yes                      | Yes      
               |
 | Compatible schema evolution by default | Yes                      | Yes      
               |
 | Portable type mapping across languages | No                       | Yes      
               |
 
+Trait objects and `dyn Any` work in xlang mode only when every selected
+concrete target has an xlang-compatible structural or EXT identity. The Rust
+trait or erased-carrier identity is not written to the wire.
+
 ## Troubleshooting
 
 ### A non-Rust implementation cannot read the payload
diff --git a/docs/guide/rust/polymorphism.md b/docs/guide/rust/polymorphism.md
index c0dbaf4539..49251da3d5 100644
--- a/docs/guide/rust/polymorphism.md
+++ b/docs/guide/rust/polymorphism.md
@@ -19,249 +19,221 @@ license: |
   limitations under the License.
 ---
 
-Apache Foryβ„’ supports polymorphic serialization through trait objects, 
enabling dynamic dispatch and type flexibility.
+Apache Fory supports dynamic values through registered application traits and
+the standard `Any` trait.
 
-## Supported Trait Object Types
+## Application Traits
 
-- `Box<dyn Trait>` - Owned trait objects
-- `Rc<dyn Trait>` - Reference-counted trait objects
-- `Arc<dyn Trait>` - Thread-safe reference-counted trait objects
-- `Vec<Box<dyn Trait>>`, `HashMap<K, Box<dyn Trait>>` - Collections of trait 
objects
-
-## Basic Trait Object Serialization
+An application trait extends `ForyObject`. List every concrete target accepted
+by the trait in `register_trait_type!`:
 
 ```rust
-use fory::{Fory, register_trait_type};
-use fory::Serializer;
-use fory::ForyStruct;
+use fory::{
+    register_trait_type, Fory, ForyObject, ForyStruct,
+};
 
-trait Animal: Serializer {
-    fn speak(&self) -> String;
+trait Animal: ForyObject {
     fn name(&self) -> &str;
 }
 
 #[derive(ForyStruct)]
-struct Dog { name: String, breed: String }
+struct Dog {
+    name: String,
+}
 
 impl Animal for Dog {
-    fn speak(&self) -> String { "Woof!".to_string() }
-    fn name(&self) -> &str { &self.name }
+    fn name(&self) -> &str {
+        &self.name
+    }
 }
 
 #[derive(ForyStruct)]
-struct Cat { name: String, color: String }
+struct Cat {
+    name: String,
+}
 
 impl Animal for Cat {
-    fn speak(&self) -> String { "Meow!".to_string() }
-    fn name(&self) -> &str { &self.name }
+    fn name(&self) -> &str {
+        &self.name
+    }
 }
 
-// Register trait implementations
 register_trait_type!(Animal, Dog, Cat);
+```
 
-#[derive(ForyStruct)]
-struct Zoo {
-    star_animal: Box<dyn Animal>,
-}
+The concrete list contains runtime value types. Each type must also be
+registered with the `Fory` instance:
 
+```rust
 let mut fory = Fory::builder().xlang(false).build();
 fory.register::<Dog>(100)?;
 fory.register::<Cat>(101)?;
-fory.register::<Zoo>(102)?;
+```
 
-let zoo = Zoo {
-    star_animal: Box::new(Dog {
-        name: "Buddy".to_string(),
-        breed: "Labrador".to_string(),
-    }),
-};
+A listed third-party target can be registered through an external structural
+serializer or manual serializer. The list still names the target, not that
+serializer.
 
-let bytes = fory.serialize(&zoo)?;
-let decoded: Zoo = fory.deserialize(&bytes)?;
+The generated names are private to the macro's module by default. A library
+that exports the generated root serializers adds normal Rust visibility:
 
-assert_eq!(decoded.star_animal.name(), "Buddy");
-assert_eq!(decoded.star_animal.speak(), "Woof!");
+```rust
+register_trait_type!(pub Animal, Dog, Cat);
 ```
 
-## Serializing dyn Any Trait Objects
-
-Apache Foryβ„’ supports serializing `Box<dyn Any>`, `Rc<dyn Any>`, and
-`Arc<dyn Any + Send + Sync>` for dynamic type dispatch:
+The trait and listed types must be visible at least as broadly as the generated
+serializers. `pub(crate)` and restricted visibility are also supported.
 
-**Key points:**
+## Trait Object Fields
 
-- Works with registered concrete non-container types that implement 
`Serializer`
-- Requires downcasting after deserialization to access the concrete type
-- Type information is preserved during serialization
-- Useful for plugin systems and dynamic type handling
+`Box<dyn Trait>` and `Rc<dyn Trait>` work directly in derived fields and nested
+containers:
 
 ```rust
+use std::collections::HashMap;
 use std::rc::Rc;
-use std::any::Any;
 
-let dog_any: Rc<dyn Any> = Rc::new(Dog {
-    name: "Rex".to_string(),
-    breed: "Golden".to_string()
-});
-
-// Serialize the Any wrapper
-let bytes = fory.serialize(&dog_any)?;
-let decoded: Rc<dyn Any> = fory.deserialize(&bytes)?;
-
-// Downcast back to the concrete type
-let unwrapped = decoded.downcast_ref::<Dog>().unwrap();
-assert_eq!(unwrapped.name, "Rex");
+#[derive(ForyStruct)]
+struct Shelter {
+    featured: Box<dyn Animal>,
+    shared: Rc<dyn Animal>,
+    animals: Vec<Box<dyn Animal>>,
+    by_name: HashMap<String, Rc<dyn Animal>>,
+}
 ```
 
-For thread-safe scenarios, use `Arc<dyn Any + Send + Sync>`:
+Fory checks the closed concrete list before materializing a value. Do not add
+`#[fory(with = ...)]` to a trait-object node; its concrete serializer is chosen
+dynamically from the registered target.
+
+For `Arc<dyn Trait>`, the trait must be thread-safe and the macro uses its sync
+form:
 
 ```rust
 use std::sync::Arc;
-use std::any::Any;
-
-let dog_any: Arc<dyn Any + Send + Sync> = Arc::new(Dog {
-    name: "Buddy".to_string(),
-    breed: "Labrador".to_string()
-});
-
-let bytes = fory.serialize(&dog_any)?;
-let decoded: Arc<dyn Any + Send + Sync> = fory.deserialize(&bytes)?;
 
-// Downcast to concrete type
-let unwrapped = decoded.downcast_ref::<Dog>().unwrap();
-assert_eq!(unwrapped.name, "Buddy");
-```
+trait SharedAnimal: ForyObject + Send + Sync {
+    fn name(&self) -> &str;
+}
 
-`Box<dyn Any>`, `Rc<dyn Any>`, and `Arc<dyn Any + Send + Sync>` are supported
-erased `Any` carriers for registered concrete non-container payloads.
-Use `Arc<dyn Any + Send + Sync>` when the erased payload must be shareable
-across threads; the concrete payload type must also satisfy `Send + Sync`.
-Registered structs, enums, and unions that satisfy those bounds can be used as
-the erased payload.
+impl SharedAnimal for Dog {
+    fn name(&self) -> &str {
+        &self.name
+    }
+}
 
-The unsupported case is a generic container used directly as the top-level
-erased payload. This applies to all erased `Any` carriers: `Box<dyn Any>`,
-`Rc<dyn Any>`, and `Arc<dyn Any + Send + Sync>`. Unsupported direct payloads
-include list-, map-, and set-like containers such as `Vec<T>`, `Vec<u8>`,
-`HashMap<K, V>`, `HashSet<T>`, and `LinkedList<T>`.
+impl SharedAnimal for Cat {
+    fn name(&self) -> &str {
+        &self.name
+    }
+}
 
-If you need to put a container in an erased `Any` payload, wrap it in a
-registered struct, enum, or union and use that wrapper as the erased payload:
-
-```rust
-use fory::{Fory, ForyStruct};
-use std::any::Any;
-use std::sync::Arc;
+register_trait_type!(sync SharedAnimal, Dog, Cat);
 
 #[derive(ForyStruct)]
-struct IntList {
-    values: Vec<i32>,
+struct SharedShelter {
+    featured: Arc<dyn SharedAnimal>,
 }
-
-let mut fory = Fory::builder().xlang(false).build();
-fory.register::<IntList>(100)?;
-
-let value: Arc<dyn Any + Send + Sync> = Arc::new(IntList {
-    values: vec![1, 2, 3],
-});
-let bytes = fory.serialize(&value)?;
-let decoded: Arc<dyn Any + Send + Sync> = fory.deserialize(&bytes)?;
 ```
 
-The wrapper makes the erased payload a concrete registered type while the
-container remains a normal typed field. The same wrapper model is the supported
-path for `Box<dyn Any>` and `Rc<dyn Any>`.
+Every listed target in a sync declaration must implement `Send + Sync`.
+Use `register_trait_type!(pub sync SharedAnimal, Dog, Cat)` when a library
+exports the generated root serializers.
 
-## Rc/Arc-Based Trait Objects in Structs
+## Trait Object Roots
 
-For fields with `Rc<dyn Trait>` or `Arc<dyn Trait>`, Fory automatically 
handles the conversion:
+`Box<dyn Trait>` is an ordinary root:
 
 ```rust
-use std::sync::Arc;
-use std::rc::Rc;
-use std::collections::HashMap;
+let animal: Box<dyn Animal> = Box::new(Dog {
+    name: "Rex".to_string(),
+});
 
-#[derive(ForyStruct)]
-struct AnimalShelter {
-    animals_rc: Vec<Rc<dyn Animal>>,
-    animals_arc: Vec<Arc<dyn Animal>>,
-    registry: HashMap<String, Arc<dyn Animal>>,
-}
+let bytes = fory.serialize(&animal)?;
+let decoded: Box<dyn Animal> = fory.deserialize(&bytes)?;
+assert_eq!(decoded.name(), "Rex");
+```
 
-let mut fory = Fory::builder().xlang(false).build();
-fory.register::<Dog>(100)?;
-fory.register::<Cat>(101)?;
-fory.register::<AnimalShelter>(102)?;
-
-let shelter = AnimalShelter {
-    animals_rc: vec![
-        Rc::new(Dog { name: "Rex".to_string(), breed: "Golden".to_string() }),
-        Rc::new(Cat { name: "Mittens".to_string(), color: "Gray".to_string() 
}),
-    ],
-    animals_arc: vec![
-        Arc::new(Dog { name: "Buddy".to_string(), breed: 
"Labrador".to_string() }),
-    ],
-    registry: HashMap::from([
-        ("pet1".to_string(), Arc::new(Dog {
-            name: "Max".to_string(),
-            breed: "Shepherd".to_string()
-        }) as Arc<dyn Animal>),
-    ]),
-};
+Rust's orphan rules prevent an ordinary serializer implementation directly on
+`Rc<dyn Trait>` and `Arc<dyn Trait>`. The macro generates serializer types for
+those roots:
 
-let bytes = fory.serialize(&shelter)?;
-let decoded: AnimalShelter = fory.deserialize(&bytes)?;
+```rust
+let animal: Rc<dyn Animal> = Rc::new(Dog {
+    name: "Milo".to_string(),
+});
 
-assert_eq!(decoded.animals_rc[0].name(), "Rex");
-assert_eq!(decoded.animals_arc[0].speak(), "Woof!");
+let bytes =
+    fory.serialize_with::<AnimalRcSerializer>(&animal)?;
+let decoded =
+    fory.deserialize_with::<AnimalRcSerializer>(&bytes)?;
+assert_eq!(decoded.name(), "Milo");
 ```
 
-## Standalone Trait Object Serialization
+```rust
+let animal: Arc<dyn SharedAnimal> = Arc::new(Dog {
+    name: "Luna".to_string(),
+});
+
+let bytes =
+    fory.serialize_with::<SharedAnimalArcSerializer>(&animal)?;
+let decoded =
+    fory.deserialize_with::<SharedAnimalArcSerializer>(&bytes)?;
+assert_eq!(decoded.name(), "Luna");
+```
+
+These APIs serialize the original `Rc` or `Arc`; there is no conversion 
wrapper.
+The generated serializer types are not registered by ID or name.
+
+## Dynamic `Any`
 
-Due to Rust's orphan rule, `Rc<dyn Trait>` and `Arc<dyn Trait>` cannot 
implement `Serializer` directly. For standalone serialization (not inside 
struct fields), the `register_trait_type!` macro generates wrapper types.
+Fory supports:
 
-**Note:** If you don't want to use wrapper types for concrete non-container 
payloads, you can serialize as `Box<dyn Any>`, `Rc<dyn Any>`, or `Arc<dyn Any + 
Send + Sync>` instead (see the dyn Any section above).
+- `Box<dyn Any>`;
+- `Rc<dyn Any>`;
+- `Arc<dyn Any + Send + Sync>`.
 
-The `register_trait_type!` macro generates `AnimalRc` and `AnimalArc` wrapper 
types:
+The concrete target must be registered:
 
 ```rust
-// For Rc<dyn Trait>
-let dog_rc: Rc<dyn Animal> = Rc::new(Dog {
+use std::any::Any;
+
+let value: Rc<dyn Any> = Rc::new(Dog {
     name: "Rex".to_string(),
-    breed: "Golden".to_string()
 });
-let wrapper = AnimalRc::from(dog_rc);
 
-let bytes = fory.serialize(&wrapper)?;
-let decoded: AnimalRc = fory.deserialize(&bytes)?;
+let bytes = fory.serialize(&value)?;
+let decoded: Rc<dyn Any> = fory.deserialize(&bytes)?;
+let dog = decoded.downcast_ref::<Dog>().unwrap();
+assert_eq!(dog.name, "Rex");
+```
 
-// Unwrap back to Rc<dyn Animal>
-let unwrapped: Rc<dyn Animal> = decoded.unwrap();
-assert_eq!(unwrapped.name(), "Rex");
+Use `Arc<dyn Any + Send + Sync>` when the erased value must be shared across
+threads:
 
-// For Arc<dyn Trait>
-let dog_arc: Arc<dyn Animal> = Arc::new(Dog {
+```rust
+let value: Arc<dyn Any + Send + Sync> = Arc::new(Dog {
     name: "Buddy".to_string(),
-    breed: "Labrador".to_string()
 });
-let wrapper = AnimalArc::from(dog_arc);
 
-let bytes = fory.serialize(&wrapper)?;
-let decoded: AnimalArc = fory.deserialize(&bytes)?;
-
-let unwrapped: Arc<dyn Animal> = decoded.unwrap();
-assert_eq!(unwrapped.name(), "Buddy");
+let bytes = fory.serialize(&value)?;
+let decoded: Arc<dyn Any + Send + Sync> =
+    fory.deserialize(&bytes)?;
+let dog = decoded.downcast_ref::<Dog>().unwrap();
+assert_eq!(dog.name, "Buddy");
 ```
 
-## Best Practices
+Derived serializers support synchronized `Arc` materialization when their
+targets satisfy `Send + Sync`. A manual serializer that needs this path
+implements `read_arc_any`.
 
-1. **Use `register_trait_type!`** to register all trait implementations
-2. **Keep compatible mode enabled** for trait objects
-3. **Register all concrete types** before serialization
-4. **Prefer dyn Any** for simpler standalone serialization
+Generic LIST, SET, and MAP identities do not identify one exact Rust generic
+target behind `Any`. Put such a container in a registered struct, or register 
an
+exact whole-container manual serializer when an opaque EXT representation is
+intentional.
 
 ## Related Topics
 
-- [References](references.md) - Rc/Arc shared references
-- [Schema Evolution](schema-evolution.md) - Compatible mode
-- [Type Registration](type-registration.md) - Registering types
+- [External-Type Serialization](external-types.md)
+- [References](references.md)
+- [Type Registration](type-registration.md)
diff --git a/docs/guide/rust/schema-evolution.md 
b/docs/guide/rust/schema-evolution.md
index 199e684ade..f48f58782a 100644
--- a/docs/guide/rust/schema-evolution.md
+++ b/docs/guide/rust/schema-evolution.md
@@ -117,6 +117,32 @@ struct SameSchemaMessage {
 }
 ```
 
+## External Types
+
+An external structural serializer is the local schema for its target. 
Compatible
+mode matches its declared fields and variants exactly as it does for an
+equivalent locally derived type:
+
+```rust
+#[derive(ForyStruct)]
+#[fory(target = third_party::User)]
+struct UserSerializer {
+    name: String,
+    age: u32,
+}
+
+let mut fory = Fory::builder().xlang(false).compatible(true).build();
+fory.register::<UserSerializer>(100)?;
+
+let decoded: third_party::User =
+    fory.deserialize_with::<UserSerializer>(&bytes)?;
+```
+
+Peers must use the same numeric ID or registered name for the logical type.
+Adding or removing fields follows the normal compatible-mode rules. A manual
+serializer owns an opaque EXT body instead, so its implementation must define
+any versioning inside that body.
+
 ## Enum Support
 
 Apache Foryβ„’ supports three types of enum variants with full schema evolution 
in Compatible mode:
@@ -157,8 +183,9 @@ locally before deserializing unknown cases you need to 
preserve.
 
 `UnknownCase` stores its payload as `Arc<dyn Any + Send + Sync>`, so preserved
 payload types must satisfy `Send + Sync`. Direct generic containers are not
-supported as erased `Any` payloads; wrap the container in a registered derived
-type if an unknown case needs to preserve it.
+supported as erased `Any` payloads by their structural carrier registration.
+Wrap the container in a registered derived type, or register an exact-target
+manual serializer when an opaque EXT/NAMED_EXT body is intentional.
 
 ### Enum Schema Evolution
 
@@ -187,13 +214,17 @@ enum NewEvent {
     KeyPress(String),  // New variant
 }
 
-let mut fory = Fory::builder().xlang(false).build();
+let mut writer = Fory::builder().xlang(false).build();
+writer.register::<OldEvent>(100)?;
+
+let mut reader = Fory::builder().xlang(false).build();
+reader.register::<NewEvent>(100)?;
 
 // Serialize with old schema
-let old_bytes = fory.serialize(&OldEvent::Click { x: 100, y: 200 })?;
+let old_bytes = writer.serialize(&OldEvent::Click { x: 100, y: 200 })?;
 
 // Deserialize with new schema - timestamp gets default value (0)
-let new_event: NewEvent = fory.deserialize(&old_bytes)?;
+let new_event: NewEvent = reader.deserialize(&old_bytes)?;
 assert!(matches!(new_event, NewEvent::Click { x: 100, y: 200, timestamp: 0 }));
 ```
 
@@ -248,3 +279,4 @@ assert_eq!(data, decoded);
 - [Configuration](configuration.md) - Compatible mode settings
 - [Polymorphism](polymorphism.md) - Trait objects with schema evolution
 - [Xlang Serialization](xlang-serialization.md) - Schema evolution across 
languages
+- [External-Type Serialization](external-types.md) - Compatible schemas for 
third-party values
diff --git a/docs/guide/rust/schema-metadata.md 
b/docs/guide/rust/schema-metadata.md
index 4aa3a892cf..1b81d3717b 100644
--- a/docs/guide/rust/schema-metadata.md
+++ b/docs/guide/rust/schema-metadata.md
@@ -221,9 +221,50 @@ struct Data {
 }
 ```
 
+An unannotated `Vec<i32>` field is `list<int32>` with the default varint
+element encoding. The `fixed_values` field above remains a LIST and changes 
only
+its element encoding to fixed-width `int32`. Use `#[fory(array)]` when the 
field
+schema itself is a dense primitive array, or `#[fory(bytes)]` for binary
+`Vec<u8>`.
+
 `compress` has been removed. Use `encoding = varint` or `encoding = fixed`
 directly.
 
+### External-Type Field Selection
+
+Use `with` to select a serializer whose target is the exact field type. The
+serializer can be external structural, manual, or a carrier composition:
+
+```rust
+use fory::{ForyStruct, VecSerializer};
+use std::collections::HashMap;
+
+#[derive(ForyStruct)]
+struct Envelope {
+    #[fory(with = UserSerializer)]
+    user: third_party::User,
+
+    #[fory(with = VecSerializer<UserSerializer>)]
+    direct_users: Vec<third_party::User>,
+
+    #[fory(list(element(with = UserSerializer)))]
+    users: Vec<third_party::User>,
+
+    #[fory(map(value(with = UserSerializer)))]
+    by_name: HashMap<String, third_party::User>,
+
+    #[fory(tuple(element(index = 1, with = UserSerializer)))]
+    selected: (String, third_party::User),
+}
+```
+
+`with` selects a serializer whose target is the exact field node, so
+`direct_users` uses a carrier serializer for the whole Vec. Each recursive
+annotation applies only at its child node. For example, a map key and value can
+select different serializers. Tuple indices are zero-based. See
+[External-Type Serialization](external-types.md) for the complete recursive
+grammar and supported carriers.
+
 ## Type Classification
 
 Fory classifies field types to determine default behavior:
@@ -449,11 +490,14 @@ struct User {
 | `nullable` | `nullable` or `nullable = bool`  | Control null flag writing    
        | All fields                 |
 | `ref`      | `ref` or `ref = bool`            | Control reference tracking   
        | `Rc`, `Arc`, weak types    |
 | `encoding` | `encoding = varint/fixed/tagged` | Integer encoding method      
        | `i32`, `u32`, `i64`, `u64` |
-| `list`     | `list(element(...))`             | Element schema metadata      
        | `Vec<T>`                   |
-| `map`      | `map(key(...), value(...))`      | Key/value schema metadata    
        | `HashMap<K, V>`            |
+| `list`     | `list(element(...))`             | Element schema metadata      
        | Lists, sets, arrays        |
+| `map`      | `map(key(...), value(...))`      | Key/value schema metadata    
        | `HashMap`, `BTreeMap`      |
+| `tuple`    | `tuple(element(index = N, ...))` | Tuple-position schema 
metadata       | Tuples                     |
+| `with`     | `with = Serializer`              | Select a field serializer    
        | External target nodes      |
 
 ## Related Topics
 
 - [Basic Serialization](basic-serialization.md) - Getting started with Fory 
serialization
 - [Schema Evolution](schema-evolution.md) - Compatible mode and schema 
evolution
 - [Xlang Serialization](xlang-serialization.md) - Interoperability with Java, 
C++, Go, Python
+- [External-Type Serialization](external-types.md) - Selecting serializers for 
third-party fields
diff --git a/docs/guide/rust/troubleshooting.md 
b/docs/guide/rust/troubleshooting.md
index 6f25c1f927..75a55d9667 100644
--- a/docs/guide/rust/troubleshooting.md
+++ b/docs/guide/rust/troubleshooting.md
@@ -38,8 +38,20 @@ fory.register::<MyStruct>(100)?;  // Register before use
 
 Confirm that:
 
-- Every serializable struct or trait implementation calls 
`fory.register::<T>(type_id)`
-- The same IDs are reused on the deserialize side
+- Every concrete dynamic target is registered through the matching structural,
+  union, or manual serializer API.
+- The same ID or name mapping is reused on the deserialize side.
+
+For external-type serialization, register the selected external structural or
+manual serializer, not its third-party target:
+
+```rust
+fory.register::<UserSerializer>(100)?;
+```
+
+Do not register `VecSerializer<UserSerializer>` or another carrier serializer.
+Register `UserSerializer`, then use recursive `list`, `map`, or `tuple`
+annotations at fields, or select the carrier serializer at a root.
 
 ### Type Mismatch Errors
 
@@ -57,6 +69,45 @@ let fory = Fory::builder()
     .build();
 ```
 
+### External-Type Serialization Selection Errors
+
+If derive reports that `with` targets the wrong type, verify that the selected
+serializer declares the exact field target:
+
+```rust
+impl Serializer for UserSerializer {
+    type Target = third_party::User;
+    // ...
+}
+```
+
+For a transparent holder, select the carrier serializer whose target is the
+exact field type:
+
+```rust
+#[fory(with = OptionSerializer<UserSerializer>)]
+user: Option<third_party::User>
+```
+
+For an exact container field, a carrier serializer is also valid:
+
+```rust
+#[fory(with = VecSerializer<UserSerializer>)]
+users: Vec<third_party::User>
+```
+
+Use recursive collection syntax when selecting an element, map child, or tuple
+position:
+
+```rust
+#[fory(list(element(with = UserSerializer)))]
+users: Vec<third_party::User>
+```
+
+If registration fails only in xlang mode, check whether the external structural
+serializer contains a native Rust enum variant with multiple fields. That shape
+has no xlang UNION representation; use native mode or change the shared schema.
+
 ## Debugging Techniques
 
 ### Enable Panic on Error for Backtraces
@@ -165,3 +216,4 @@ This keeps diagnostics consistent and makes opt-in panics 
work correctly.
 - [Configuration](configuration.md) - Fory options
 - [Type Registration](type-registration.md) - Registration best practices
 - [Schema Evolution](schema-evolution.md) - Compatible mode
+- [External-Type Serialization](external-types.md) - Field and root serializer 
selection
diff --git a/docs/guide/rust/type-registration.md 
b/docs/guide/rust/type-registration.md
index d2830b99f0..0bb260ea4c 100644
--- a/docs/guide/rust/type-registration.md
+++ b/docs/guide/rust/type-registration.md
@@ -59,15 +59,30 @@ let mut fory = Fory::builder().xlang(true).build();
 fory.register_by_name::<MyStruct>("com.example.MyStruct")?;
 ```
 
-## Register Custom Serializer
+## Register a Manual Serializer
 
-For types that need custom serialization logic:
+For types that need customized serialization logic, register the manual
+serializer:
 
 ```rust
 let mut fory = Fory::builder().xlang(false).build();
-fory.register_serializer::<CustomType>(100)?;
+fory.register_serializer::<UuidSerializer>(100)?;
 ```
 
+An external structural serializer uses the ordinary structural registration
+API:
+
+```rust
+fory.register::<UserSerializer>(101)?;
+```
+
+The serializer's `Target` is the runtime value type. Registration does not
+require a separate external-type API. At fields, `with` can select an exact
+carrier serializer such as `VecSerializer<UserSerializer>`, while recursive
+`list`, `map`, or `tuple` annotations select serializers at child nodes. At
+roots, compose the same carrier serializers. Carrier serializers are not
+registered.
+
 ## Registration Consistency
 
 Rust registration APIs use explicit IDs or explicit names. Keep the same 
registration mapping on serializer and deserializer peers:
@@ -122,4 +137,5 @@ let handles: Vec<_> = (0..4)
 
 - [Configuration](configuration.md) - Fory builder options
 - [Xlang Serialization](xlang-serialization.md) - xlang mode registration
-- [Custom Serializers](custom-serializers.md) - Custom serialization
+- [Manual Serializers](manual-serializers.md) - Customized serialization
+- [External-Type Serialization](external-types.md) - Third-party targets and 
carrier roots
diff --git a/docs/guide/rust/xlang-serialization.md 
b/docs/guide/rust/xlang-serialization.md
index 0f83e18224..b9e6664932 100644
--- a/docs/guide/rust/xlang-serialization.md
+++ b/docs/guide/rust/xlang-serialization.md
@@ -35,8 +35,8 @@ let mut fory = Fory::builder().xlang(true).build();
 // Register types with consistent IDs across languages
 fory.register::<MyStruct>(100)?;
 
-// Or use name-based registration
-fory.register_by_name::<MyStruct>("com.example.MyStruct")?;
+// Or, on a different Fory instance, use name-based registration
+// fory.register_by_name::<MyStruct>("com.example.MyStruct")?;
 ```
 
 ## Type Registration for Xlang
@@ -86,6 +86,48 @@ let bytes = fory.serialize(&person)?;
 // bytes can be deserialized by Java, Python, etc.
 ```
 
+### Third-Party Rust Types
+
+An external structural serializer gives a third-party Rust type the same xlang
+schema as an equivalent local derive:
+
+```rust
+#[derive(ForyStruct)]
+#[fory(target = third_party::User)]
+struct UserSerializer {
+    name: String,
+    age: u32,
+}
+
+let mut fory = Fory::builder().xlang(true).build();
+fory.register::<UserSerializer>(100)?;
+
+let bytes = fory.serialize_with::<UserSerializer>(&user)?;
+```
+
+Container roots compose with carrier serializers and keep the ordinary xlang
+LIST, MAP, tuple, or array representation:
+
+```rust
+use fory::VecSerializer;
+
+let bytes =
+    fory.serialize_with::<VecSerializer<UserSerializer>>(&users)?;
+```
+
+Only xlang-representable schemas are accepted. A native Rust enum variant with
+multiple tuple or named fields is supported with `xlang(false)`, but its
+serializer registration is rejected in xlang mode. See
+[External-Type Serialization](external-types.md).
+
+### Dynamic Rust Carriers
+
+`Box<dyn Any>`, `Rc<dyn Any>`, `Arc<dyn Any + Send + Sync>`, and application
+`dyn Trait` carriers can be used in xlang mode when every selected concrete
+target has an xlang-compatible structural or EXT identity. Fory writes the
+concrete registered target identity; the Rust trait or erased-carrier identity
+does not appear on the wire.
+
 ### Java (Deserializer)
 
 ```java
@@ -188,3 +230,4 @@ explicit array field attribute when the schema is dense 
`array<T>`.
 - [Configuration](configuration.md) - xlang mode configuration
 - [Schema Evolution](schema-evolution.md) - Compatible mode
 - [Type Registration](type-registration.md) - Registration methods
+- [External-Type Serialization](external-types.md) - Third-party values in 
xlang mode


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

Reply via email to