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 8ec2706c1bc16299079c02d317612f5e96925c48
Author: chaokunyang <[email protected]>
AuthorDate: Mon Jul 27 10:36:20 2026 +0000

    🔄 synced local 'docs/specification/' with remote 'docs/specification/'
---
 docs/specification/xlang_implementation_guide.md | 49 +++++++++++++++++-------
 1 file changed, 36 insertions(+), 13 deletions(-)

diff --git a/docs/specification/xlang_implementation_guide.md 
b/docs/specification/xlang_implementation_guide.md
index 7a71637346..85d2fd8f86 100644
--- a/docs/specification/xlang_implementation_guide.md
+++ b/docs/specification/xlang_implementation_guide.md
@@ -260,7 +260,13 @@ 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.
+structural `Evolving` setting for wire fields. An ignored declaration field
+supplies only graph-memory storage and has no wire metadata or target access.
+For external classes, the shallow graph estimate includes declared wire
+fields, ignored declaration fields, and discoverable public instance target
+fields. An ignored declaration does not require its target storage to be
+visible to the generator. When it resolves to the same public field, the field
+symbol is used only to avoid counting that storage twice.
 
 Every generated ordinary or external struct uses
 `TypeResolver.RegisterGeneratedStruct<T, TSerializer>(bool evolving)` to carry
@@ -276,14 +282,15 @@ 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.
+wire 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. Ignored properties are declaration-owned budget hints and
+do not bind or access target members. Immutable, constructor-only,
+factory-only, init-only, readonly, renamed, converted, or inaccessible wire
+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>`,
@@ -575,6 +582,12 @@ manual serializer; the implementation must not use 
reflection, unsafe layout
 access, unavailable-overload tricks, schema mirror values, conversion wrappers,
 or builders as a fallback.
 
+Swift macros cannot inspect another type's stored layout. An external class's
+shallow graph-memory formula therefore uses its declaration fields only.
+`@ForyField(ignore: true)` adds a budget-only declaration field without schema,
+target access, construction, or wire code. Applications must use this form for
+substantial omitted storage.
+
 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`
@@ -1278,6 +1291,10 @@ In Java:
 - `@ForyEnumId` can override that with a stable explicit tag
 - `serializeEnumByName(true)` affects native Java mode, not xlang mode
 
+In C#, the enum's underlying numeric value is the xlang tag. Java peers for
+sparse C# enums must declare matching `@ForyEnumId` values instead of relying
+on declaration ordinals.
+
 Other language implementations should preserve the same wire rule even if the 
configuration or
 annotation surface differs.
 
@@ -1334,15 +1351,21 @@ name. Every runtime type position uses the target type: 
`Serializer<Target>`,
 `GeneratedStructSchema<Target>`, read and write signatures, constructor calls,
 schema `type`, and generated-module dispatch.
 
-For each declaration field, resolve an accessible target getter with the same
-name and exact instantiated Dart type. Constructor parameters and any
-post-construction setter must also match exactly. A public named generative
-constructor is selected only when the annotation names it. Factory
+For each serialized declaration field, resolve an accessible target getter
+with the same name and exact instantiated Dart type. Constructor parameters
+and any post-construction setter must also match exactly. A public named
+generative constructor is selected only when the annotation names it. Factory
 constructors, abstract targets, open target types, and constructor-based
 reference-tracked paths back to the target are rejected during generation.
 The recursive check includes target elements, keys, and values nested in the
 supported list, set, and map field metadata.
 
+An external object's shallow graph-memory formula is the union of declaration
+fields and public instance fields discovered on the target, its superclasses,
+and applied mixins. A public target field represented by a declaration is
+counted once. `@ForyField(ignore: true)` adds budget-only declaration storage
+without target access, construction, metadata, or wire code.
+
 Generated code reads getters and invokes target constructors or setters
 directly. It must not allocate the declaration, copy values through an
 intermediate object, invoke runtime callbacks, perform member-name lookup, or


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

Reply via email to