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 049b27f1fa517e1614db30261ee6c3e48b4fa686
Author: chaokunyang <[email protected]>
AuthorDate: Tue Jul 28 03:08:12 2026 +0000

    🔄 synced local 'docs/specification/' with remote 'docs/specification/'
---
 docs/specification/xlang_implementation_guide.md | 187 ++++++++++++++++++++++-
 1 file changed, 184 insertions(+), 3 deletions(-)

diff --git a/docs/specification/xlang_implementation_guide.md 
b/docs/specification/xlang_implementation_guide.md
index 311f69a657..8778a37414 100644
--- a/docs/specification/xlang_implementation_guide.md
+++ b/docs/specification/xlang_implementation_guide.md
@@ -1368,7 +1368,7 @@ The normal Dart integration path is:
 2. annotate field overrides with `@ForyField`
 3. run `build_runner`
 4. call the generated per-library helper, such as
-   `<InputFile>Fory.register(...)`, to bind private generated metadata and
+   `<InputFile>ForyModule.register(...)`, to bind private generated metadata 
and
    register generated types
 
 Generated code should emit:
@@ -1382,6 +1382,182 @@ The public helper should be a thin generated wrapper 
around the Fory
 registration API, not a public global registry or a second unrelated
 registration API family.
 
+### Dart Ordinary Struct Inheritance
+
+Ordinary Dart `ForyStruct` inheritance is a code-generation-time field
+discovery, normalization, access, construction, and flattening change. It does
+not redesign the runtime reference protocol.
+
+For a concrete annotated child, the generator walks the instantiated
+superclass and applied-mixin storage chain rather than only the child's direct
+`element.fields`. Each layer's `InterfaceType.element.fields` exposes its
+declared elements, including private declarations in another library. Dart
+privacy controls which generated expression can access an element; it does not
+control whether the element is discovered.
+
+The storage collector:
+
+1. visits the instantiated superclass;
+2. visits actually applied mixins in application order;
+3. visits the current class;
+4. collects concrete instance storage declared by each layer exactly once.
+
+It excludes `Object`, interfaces, mixin `on` constraints, abstract accessors,
+static fields, external fields, and synthetic members that do not own storage.
+A mixin slot is identified by its application site and declaring field, so
+multiple applications cannot be collapsed by spelling or `baseElement`.
+
+Every discovered storage field follows one pipeline:
+
+```text
+complete hierarchy discovery
+  -> declaration-owned @ForyField(ignore: true)
+  -> concrete generic substitution
+  -> direct or companion access resolution
+  -> constructor validation
+  -> one globally sorted child schema
+```
+
+`@ForyField(ignore: true)` on the declaring field is the only stage that may
+remove real ordinary storage. Ignored fields bypass type, access, construction,
+wire identity, and codec work but remain in the concrete object's shallow
+graph-memory field count. An inaccessible, private, final, hidden, unsupported,
+or otherwise unresolved non-ignored field is a generation error.
+
+Ownership is fixed:
+
+| Concern                          | Owner                                     
       |
+| -------------------------------- | 
------------------------------------------------ |
+| Field identity and annotations   | Declaring storage field                   
       |
+| Hierarchy discovery/substitution | Concrete-child generator                  
       |
+| Cross-library private permission | Public boundary in the field's declaring 
library |
+| Schema, sort, and codec          | Concrete annotated child                  
       |
+| Construction                     | Selected concrete-child generative 
constructor   |
+| Reference analysis/publication   | Existing concrete-child serializer path   
       |
+| Graph-memory self charge         | One concrete child object                 
       |
+| External target field list       | Explicit external serializer declaration  
       |
+
+Public inherited fields and private inherited fields declared in the child's
+library use direct generated access and require no parent annotation. A private
+field declared in another library remains discovered, but requires
+`ForyStruct(exposePrivateFields: true)` on a public hierarchy boundary in that
+field's declaring library. The option defaults to `false`, is invalid with
+`ForyStruct.target`, and authorizes only provider-library access generation. It
+does not enable discovery, alter same-library access, change field inclusion,
+or let a consumer authorize another library's private state.
+
+A public boundary may expose same-library private storage inherited from a
+private class or mixin. If private fields come from several Dart libraries,
+each declaring library must independently provide an opted-in public boundary
+and visible companion. The nearest qualifying child-visible boundary in the
+declaring library is selected.
+
+The provider's `.fory.dart` part emits a public `@nodoc` typed static access
+companion. It emits an exact getter for each exposed non-ignored private field,
+a setter only for mutable storage, and no setter for `final` or `late final`
+storage. The receiver is the public boundary type. Generic bounds and every
+type nested in a public signature must be nameable outside the provider
+library. The companion must not use `dynamic`, `Object?` bridge casts,
+reflection, callbacks, runtime lookup, a parent serializer, or stored runtime
+state.
+
+The child source must have a direct import or re-export namespace that exposes
+the public boundary and companion. Provider output must be generated and
+published before a dependent package is built. Missing permission, a hidden or
+ambiguous companion namespace, an unnameable signature, or dispatch that no
+longer reaches the exact storage slot is a generation error. A child must also
+validate the complete concrete hierarchy so field hiding below the boundary
+cannot redirect a generated getter or setter to another slot.
+
+Every non-ignored `final` or `late final` field must be initialized by a
+statically proven identity flow:
+
+```text
+selected concrete-child constructor parameter
+  -> redirect or super parameter
+  -> exact storage field
+```
+
+Accepted edges are exact field formals, super formals, direct parameter
+references in constructor field initializers, and direct parameter references
+in redirecting or super-constructor arguments. Types must remain identical
+after concrete generic substitution, including nullability. Calls, operators,
+casts, null assertions, constants, constructor-body assignment, and matching
+names without element identity are not proof. A declaration initializer on a
+non-ignored final field is unsupported because the decoded value cannot own
+that slot. There is no post-construction final write, reflection, or fallback.
+
+Mutable fields connected to selected constructor parameters are initialized
+once through the same exact identity flow. Remaining mutable fields require an
+exact setter and are restored after construction. Required constructor
+parameters must have one unambiguous field source. Optional named parameters
+may be omitted; an omitted optional positional parameter cannot be followed by
+a passed positional parameter. Constructor arguments and assignments are
+matched by resolved storage-field identity rather than field-name strings.
+
+The concrete child owns one `GeneratedStructSchema`, one canonical field sort,
+one serializer and descriptor cache, one reconstruction, one reference
+publication path, and one graph-memory owner. Parent serializers are neither
+nested nor invoked, and parent runtime registration is not required. A
+separately annotated concrete parent has its own independently flattened
+schema only for values of that exact type.
+
+Direct and inherited fields feed one normalized list into the existing
+recursive reference analysis and `needsRootRef` calculation. Inherited
+`ref: true` and nested container metadata behave like equivalent direct child
+fields. Inheritance adds no reference state, `ReadContext` API, serializer
+signature, call-contract change, runtime branch, slot, sentinel, callback,
+wrapper, compatible-layout state, or parent reference owner. A failure shared
+by the equivalent flat model is a separate reference-subsystem issue.
+
+Java provides only the flattened-model comparison for this feature: its object
+serializer extends one field-descriptor list across inheritance and adds no
+inheritance-specific reference state. Java's existing reference contract uses
+the `readRefIds` stack, real reference IDs, and its `-1` sentinel to associate
+`reference(obj)` with the current serializer invocation. That contract differs
+from Dart's current reference subsystem and is not a design to transplant as
+part of Dart hierarchy support. Dart inheritance is required only to match its
+own equivalent flat model.
+
+Hierarchy traversal, substitution, access validation, and constructor proofs
+run during generation. Existing flat serializers gain no runtime work, public
+and same-library inherited fields emit the same direct operations as equivalent
+flat fields, and cross-library private fields add only an inlineable typed
+static companion call. Generation must not introduce runtime hierarchy
+traversal, allocation, callbacks, reflection, or parent dispatch.
+
+The child's shallow graph-memory formula is:
+
+```text
+24 + 4 * actualConcreteStorageFieldCount
+```
+
+It counts every real inherited and ignored storage slot once and adds no parent
+self charge.
+
+Generated diagnostics must identify the concrete child, declaring field,
+declaring library, and failed access or constructor path, then give an
+actionable remedy. Typical remedies are adding
+`exposePrivateFields: true` to a public owner-library boundary, importing its
+generated companion, forwarding a constructor value unchanged, placing
+`@ForyField(ignore: true)` on the field declaration, or using a manual
+serializer. Diagnostics must state that hierarchy discovery is independent of
+cross-library access.
+
+This correction changes generated schemas for ordinary children that inherit
+storage. All affected `.fory.dart` files must be regenerated. Compatible mode
+uses normal missing/unknown-field handling; fixed schemas written while
+inherited fields were absent have no legacy reader. Implementations must not
+retain an alternative path limited to child declarations, constructor binding
+based only on names, a late-final setter path, compatibility shim, fallback
+access, or parent serializer delegation.
+
+Acceptance requires that every hierarchy storage slot is either explicitly
+ignored or represented exactly once with a valid type, access path, wire
+identity, and reconstruction path. Equivalent flat and inherited models must
+produce the same canonical schema, wire bytes, reference IDs, and round-trip
+behavior. External target declarations remain explicit and unaffected.
+
 ### Dart External Structural Serializers
 
 Dart external-type serialization extends `ForyStruct` with an optional
@@ -1404,6 +1580,11 @@ 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.
 
+The external declaration's fields are the complete schema. It may explicitly
+name an accessible property inherited by the target, but the generator does
+not automatically scan the external target hierarchy for schema fields.
+`exposePrivateFields` is invalid on an external declaration.
+
 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
@@ -1472,7 +1653,7 @@ For Dart implementation changes, run at minimum:
 
 ```bash
 cd dart
-dart run build_runner build --delete-conflicting-outputs
+dart run build_runner build
 dart analyze
 dart test
 ```
@@ -1481,6 +1662,6 @@ For generated consumer coverage, also run:
 
 ```bash
 cd dart/packages/fory-test
-dart run build_runner build --delete-conflicting-outputs
+dart run build_runner build
 dart test
 ```


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

Reply via email to