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 2bc5c5e0362f7351905ea256d449078862458d59
Author: chaokunyang <[email protected]>
AuthorDate: Mon Jul 27 05:33:11 2026 +0000

    🔄 synced local 'docs/specification/' with remote 'docs/specification/'
---
 docs/specification/xlang_implementation_guide.md | 251 ++++++++++++++++++++++-
 docs/specification/xlang_serialization_spec.md   |   8 +-
 2 files changed, 256 insertions(+), 3 deletions(-)

diff --git a/docs/specification/xlang_implementation_guide.md 
b/docs/specification/xlang_implementation_guide.md
index b336d83a8e..1f7be2a828 100644
--- a/docs/specification/xlang_implementation_guide.md
+++ b/docs/specification/xlang_implementation_guide.md
@@ -367,6 +367,251 @@ feature must not invent `CellSerializer<S>` or treat 
`Cell` as `RefCell`.
 Likewise, standard-library weak pointers are not aliases for Fory's weak
 carriers.
 
+For Swift, `Serializer` follows the same exact-target ownership boundary with
+an associated `Target`. A self-provided structural or manual serializer uses
+`Target == Self`; a separately provided structural or manual serializer names
+another target type. Serializer operations are static and accept or return
+`Target`. Fory never instantiates a serializer object, and generated external
+structural code reads target properties and constructs the target directly.
+
+Static selection follows provider ownership uniformly. A target that itself
+conforms to `Serializer` with `Target == Self` is selected implicitly at roots,
+generated fields, optionals, arrays, sets, and dictionaries. This includes an
+external type with an intentional retroactive conformance. A serializer type
+whose `Target` is another type must be selected explicitly at every static node
+where it is required. Registration does not infer that serializer, even if it
+is the only registered provider for the target, because Swift cannot
+reverse-infer a unique `S: Serializer` from `S.Target == T`.
+
+A retroactive conformance is process-global. `@retroactive` acknowledges
+Swift's ownership warning but does not make duplicate `(Target, Protocol)`
+conformances safe. Applications may use it when they intentionally own the
+single global binding; public libraries should generally use a separate
+serializer so applications can choose the implementation explicitly.
+
+Swift `StructSerializer` covers every structural registration category.
+Ordinary and external `@ForyStruct`, `@ForyEnum`, and `@ForyUnion` expansions
+all conform; manual EXT serializers do not.
+
+Swift's doc-hidden `FieldCodec` extends value serialization for the same exact
+target. It owns `FieldType`, recursive field generics, field null/reference
+policy, compatible-field reads, scalar conversion, and annotation-selected
+field encodings. `Serializer` has no `FieldType`, compatible-field hook, or
+declared-generics argument. `FieldCodec` alone carries the
+`hasDeclaredChildren` mode that preserves canonical collection and map header
+decisions when enclosing field metadata owns the recursive child schema.
+`SerializerCodec<S>` is the generated leaf adapter and has target `S.Target`.
+Because `FieldCodec` extends `Serializer`, its value-level half must remain a
+valid root serializer, but root code cannot observe any field-only operation.
+In non-compatible mode, exact nonoptional selected leaves with no
+type-information envelope call `S.readData` when no reference envelope is
+required; tracked reference targets continue through `S.read`. Compatible or
+recursively retained metadata remains owned by `SerializerCodec<S>` and enters
+the selected serializer with that scope intact.
+Numeric field codecs delegate that value-level half to the canonical numeric
+serializer, and packed-array field codecs delegate it to the canonical LIST
+carrier. Only their field operations use fixed, tagged, or packed field
+representations. Root eligibility therefore adds no alternate numeric or
+packed-array wire mapping.
+
+Swift `Serializer.isWrapper` is a doc-hidden value-level property used only to
+reject Fory-owned transparent wrappers as independent EXT registrations.
+`OptionalSerializer` sets it; collection carriers do not. A manual serializer
+does not acquire wrapper status from target spelling and may own an independent
+opaque carrier body. Target-identity conflicts prevent it from replacing a
+seeded canonical dynamic builtin.
+
+The exhaustive Swift recursive carrier serializer surface is:
+
+- `OptionalSerializer<S>` with target `S.Target?`;
+- `ArraySerializer<S>` with target `[S.Target]` and LIST wire shape;
+- `SetSerializer<S>` with target `Set<S.Target>` where `S.Target: Hashable`;
+- `DictionarySerializer<KS, VS>` with target
+  `[KS.Target: VS.Target]` where `KS.Target: Hashable`.
+
+Each carrier serializer conditionally provides field-codec behavior when its
+children are field codecs. Root composition therefore contains serializers,
+while field composition contains recursively lowered field codecs, and both
+call the same carrier body, allocation, insertion, reference, and compatible
+implementation. Ordinary `Optional`, `Array`, `Set`, and `Dictionary`
+conformances delegate to the same owners under exact self-target constraints.
+Those constraints apply equally to user-declared and retroactively conforming
+external children. Carrier serializers are zero-state and unregistered.
+
+The transparent Swift `OptionalSerializer` has no independent field-metadata
+identity. Its field-codec metadata scope delegates recursively to the wrapped
+field codec, including nonnull reads, so accepted remote child metadata remains
+owned by the selected leaf or nested carrier.
+
+Swift `Array` is LIST for statically selected roots and carrier roots, 
including
+`[Int32]`. `@ArrayField` is a separate field-only dense bool/numeric selection,
+and exact primitive arrays hidden in dynamic `Any` use their canonical dynamic
+packed-array mapping. Only a canonical primitive field codec can select
+the packed form; a noncanonical selected child is rejected rather than gaining
+a mapping from its target syntax. `Data` remains the BINARY leaf.
+
+Swift has no supported generic tuple, fixed-length array, cell, box, weak,
+reference-holder, `ContiguousArray`, `ArraySlice`, result, range, deque,
+`NSSet`, or `NSDictionary` serializer. External-child composition must not
+invent those carriers. `AnyHashable`, `UnknownCase`, and `ByteBuffer` are a
+dynamic key holder, union value holder, and transport owner respectively, not
+recursive static carriers.
+
+Swift external structural declarations use the structural macros:
+
+```swift
+@ForyStruct(target: ThirdParty.User.self)
+struct UserSerializer {
+    var name: String
+    var age: UInt32
+}
+```
+
+Generated ordinary value declarations use `Target = Self`. Because Swift
+rejects a nested `Target = Self` type alias in a class, an ordinary generated
+class names the declaring class explicitly; both forms express the same exact
+self-target relationship.
+
+Equivalent target selection applies to `@ForyEnum` and `@ForyUnion`. A value
+schema declaration targets a value type and uses direct labeled construction.
+A class schema declaration targets a class, allocates the final target through
+an accessible zero-argument initializer, publishes it before reading child
+fields, and assigns accessible mutable properties. Generated Swift enforces
+the class target's `AnyObject` constraint. Swift has no negative generic
+constraint for the inverse case, so cold registration validation rejects a
+value-schema declaration that targets a class before publishing metadata. An
+inaccessible, immutable, invariant-bearing, or non-exhaustive target requires a
+manual serializer; the implementation must not use reflection, unsafe layout
+access, unavailable-overload tricks, schema mirror values, conversion wrappers,
+or builders as a fallback.
+
+An external structural union requires the target to expose a lossless
+`unknown(UnknownCase)` case. A dependency-free target module may expose a
+generic unknown payload and let the application select its `UnknownCase`
+specialization; a target may also use Fory's carrier directly. Fory does not
+convert another module's unknown representation. A third-party union without
+this shape requires a manual serializer and does not claim structural-union
+wire equivalence.
+
+An ordinary Swift generated field recursively selects a self-provided declared
+type without annotation. Swift field selection uses
+`@ForyField(with: S.self)` for one exact declared node and `.with(S.self)`
+inside `ForyFieldType` list, set, map, and union payload nodes when selecting a
+separate serializer or another deliberate override. A selected optional or
+whole collection node names its exact carrier serializer. Canonical
+whole-carrier syntax is recursively lowered to the same field-codec tree as the
+structural field DSL. The compiler enforces that the selected serializer target
+equals the declared field node.
+
+Swift root selection uses a serializer metatype:
+
+```swift
+fory.serialize(user, with: UserSerializer.self)
+fory.deserialize(bytes, with: UserSerializer.self)
+fory.serialize(users, with: ArraySerializer<UserSerializer>.self)
+```
+
+The `Data`, append-to-`Data`, and `ByteBuffer` forms share one root framing and
+the reusable contexts. Ordinary roots require `T.Target == T` and
+delegate to the same selected-serializer helper. This admits every
+self-provider, including an intentional retroactive external conformance, but
+does not infer a separate serializer from registration. There are no parallel
+serializer-selection aliases or application-declared structural container
+schemas. The root facade retains its existing module boundary and inlining
+policy; static specialization belongs to serializer, generated-code, and
+carrier owners below it. Do not expose resolver or reusable-context state as
+`@usableFromInline` merely to force the complete root flow into clients.
+Selected Swift read roots carry an inferred result generic constrained by
+`S.Target == T`. The call remains `deserialize(..., with: S.self)`, but the
+same-type generic lets the caller provide concrete target metadata and avoids
+an associated-target lookup and dynamic result-storage setup in every
+unspecialized root call.
+
+Generated value-struct `readData` owns target construction directly. When an
+external structural serializer has recursively selected carrier fields, that
+owner may be out of line to control code size, but a private large-value
+returning helper must not sit between `readData` and the final target result
+buffer. Generated class readers retain a private helper because the class
+allocation owner must publish a reserved reference before reading children.
+
+Swift `TypeResolver` indexes one immutable `TypeInfo` by both serializer
+identity and concrete target identity. Static schema and explicit selection use
+serializer identity; dynamic writes use target identity; wire reads use the
+numeric ID or name. All directions share one writer, exact reader, compatible
+reader, metadata, and registration owner. Public registration accepts the
+selected structural or manual serializer through the ID or name API. It rejects
+carrier, dynamic, builtin, and field codec identities before publication.
+
+Swift arbitrary application protocol existentials use a zero-state
+`DynamicSerializer<T>`. Dynamic writes resolve the registered concrete target,
+downcast once to its serializer's exact target, and invoke the shared
+`TypeInfo` harness. Dynamic reads materialize the final concrete target once
+and cast it to the requested existential. Normal target registration is the
+allowlist, so Swift needs no marker protocol, protocol-specific registry,
+closed target-list macro, protocol wire identity, serializer value, or wrapper
+collection. Protocol roots and root carriers select the dynamic serializer
+explicitly, for example `DynamicSerializer<any Animal>` and
+`ArraySerializer<DynamicSerializer<any Animal>>`. Swift retains direct `Any`
+and `AnyObject` root overloads for source compatibility. Those overloads
+forward to the same selected-serializer roots with `DynamicSerializer<Any>` or
+`DynamicSerializer<AnyObject>` and add no parallel codec, framing, lookup, or
+allocation path. Their append-to-Data and ByteBuffer forms follow the same
+rule. Because Swift permits every value to convert to `Any`, a concrete
+non-self-serializing value may enter registered dynamic-target lookup through
+the `Any` overload. Explicit `with:` selection names a separate static
+serializer when required. Swift exposes no unconstrained generic dynamic root,
+`any Serializer` root, or specialized heterogeneous-container root overload.
+
+`DynamicSerializer<T>` overrides complete-value reference handling. It resolves
+the concrete `TypeInfo` before deciding whether the target is a reference and
+uses conservative `isRefType == true` only for the outer dynamic field shape.
+The outer dynamic serializer owns nullability and type information. Its
+`TypeInfo` harness invokes body serialization for a value target and the
+concrete complete-value reference envelope for a class target. Dynamic slot
+accounting uses the declared existential layout rather than treating every
+value as a reference. `AnyObject` reads reject value-typed metadata before the
+cast so Swift cannot allocate a bridge object. An arbitrary nonoptional
+protocol has no synthetic default; optional protocol values compose through
+`OptionalSerializer`.
+
+An exact generated field whose selected codec has UNKNOWN static identity
+still writes and reads the concrete `TypeInfo`; carrier headers own this
+information for dynamic children and do not duplicate it. Dynamic map chunks
+retain the established key-type/value-type/key-body/value-body order and reuse
+the two resolved `TypeInfo` entries without another target lookup. A retained
+dynamic `TypeInfo` is scoped by the serializer that selected it, so
+`AnyHashable` and `DynamicSerializer<T>` share one implementation without
+substituting each other's scope identity.
+
+Swift rejects zero-sized non-null MAP chunks because they cannot advance the
+decoded entry count. A one-null entry encodes its non-null side as a complete
+field value: its reference envelope when present, then undeclared `TypeInfo`,
+then its body. The MAP writer, reader, and compatible-field skipper use that
+complete-field order rather than the shared type-prefix order of non-null
+chunks. Static and dynamic MAP branches use the same ordering and validation.
+
+Dynamic Any and protocol paths operate directly on final target values and
+containers. Static composition never enters target lookup; dynamic lookup
+occurs only at an explicit dynamic boundary.
+
+Swift heterogeneous dynamic collections use their exact supported target
+shapes: `[Any]`, `[String: Any]`, `[Int32: Any]`, and `[AnyHashable: Any]`.
+Assigning a homogeneous list or map to `Any` does not erase its concrete target
+identity and must not trigger a converted collection or a second collection
+codec. Homogeneous lists and maps use their ordinary or explicitly selected
+carrier serializer. Preseeded exact primitive arrays retain their packed
+dynamic mapping. A null dynamic key in `[AnyHashable: Any]` materializes as
+`AnyHashable(ForyAnyNullValue())`.
+
+When a carrier retains remote child metadata for a user-type field codec, the
+leaf codec enters the selected serializer without another envelope so its exact
+or compatible reader sees that retained `TypeInfo`. Builtin leaf codecs read
+their field bodies directly.
+
+Swift supports only the xlang wire mode. A known `@ForyUnion` case has zero or
+one associated value, and multiple logical fields use an explicit struct
+payload. There is no Swift-native multi-field enum encoding to preserve.
+
 Rust tuple field metadata selects sparse zero-based positions, while
 unmentioned positions use ordinary serializers. It lowers to the
 arity-specific tuple codec, while the root carrier recursively composes tuple
@@ -422,8 +667,10 @@ required child registration through its ordinary 
per-position type-metadata
 operation. A binding must not add an eager recursive root validation pass,
 reached-body check, selector tree, composed-target lookup, per-element
 serializer dispatch, allocation, callback, or hot-path branch to change that
-behavior. An exact manual serializer for the whole container remains a separate
-opaque EXT/NAMED_EXT choice.
+behavior. An exact manual serializer for a whole container remains a separate
+opaque EXT/NAMED_EXT choice. It owns registered dynamic target identity, while
+unregistered carrier serializers continue to own explicit static structural
+composition.
 
 Carrier serializers have no independent registered identity. Structural
 registration requires the existing structural serializer contract and matching
diff --git a/docs/specification/xlang_serialization_spec.md 
b/docs/specification/xlang_serialization_spec.md
index a91192d688..95ee241371 100644
--- a/docs/specification/xlang_serialization_spec.md
+++ b/docs/specification/xlang_serialization_spec.md
@@ -127,6 +127,11 @@ wire identity.
   MUST preserve the selected child type ID and recursive `FieldType`; 
serializer
   composition
   MUST NOT replace a canonical primitive-array or binary mapping with LIST.
+  Conversely, a Swift `Array` carrier serializer MUST remain LIST because that
+  is Swift's canonical statically selected `Array` mapping. Swift dense
+  `@ArrayField` and dynamic exact primitive-array mappings are separate
+  canonical selections; a serializer whose target happens to be numeric does
+  not acquire either mapping.
 - A heterogeneous tuple/product carrier serializer MUST preserve the binding's
   existing direct tuple encoding and its existing xlang LIST encoding. Selected
   child positions MUST NOT add a serializer name, position index, generic 
schema node,
@@ -1533,8 +1538,9 @@ The KV header is a single byte encoding metadata for both 
keys and values:
 
 #### Chunk Size
 
-- Maximum chunk size: 255 pairs (fits in 1 byte)
+- A non-null chunk size is from 1 through 255 pairs (fits in 1 byte); zero is 
invalid
 - When key or value is null, that entry is serialized as a separate chunk with 
implicit size 1 (chunk size byte is skipped)
+- For an entry with exactly one null side, the non-null side uses 
complete-field order: its reference envelope when present, then any type 
information not declared by the header, then its body
 - Reader tracks accumulated count against total map size to know when to stop 
reading chunks
 
 #### Why Chunk-Based Format?


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

Reply via email to