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.git
The following commit(s) were added to refs/heads/main by this push:
new bd0ca9825 feat(dart): allow omitting inherited private fields (#3894)
bd0ca9825 is described below
commit bd0ca9825b3206b1a53bf27bfb180a551ab39236
Author: Shawn Yang <[email protected]>
AuthorDate: Tue Jul 28 12:50:37 2026 +0800
feat(dart): allow omitting inherited private fields (#3894)
## Why?
## What does this PR do?
## Related issues
## AI Contribution Checklist
- [ ] Substantial AI assistance was used in this PR: `yes` / `no`
- [ ] If `yes`, I included a completed [AI Contribution
Checklist](https://github.com/apache/fory/blob/main/AI_POLICY.md#9-contributor-checklist-for-ai-assisted-prs)
in this PR description and the required `AI Usage Disclosure`.
- [ ] If `yes`, my PR description includes the required `ai_review`
summary and screenshot evidence or equivalent persisted links of the
final clean AI review results from both fresh reviewers described in
`AI_POLICY.md`, the Fory-guided reviewer and the independent general
reviewer, on the current PR diff or current HEAD after the latest code
changes.
## Does this PR introduce any user-facing change?
- [ ] Does this PR introduce any public API change?
- [ ] Does this PR introduce any binary protocol compatibility change?
## Benchmark
---
.agents/languages/dart.md | 48 +++--
dart/README.md | 8 +-
.../fory-test/lib/model/inheritance_models.dart | 8 +
.../fory-test/test/struct_inheritance_test.dart | 32 ++++
dart/packages/fory/CHANGELOG.md | 12 +-
dart/packages/fory/README.md | 79 ++------
.../fory/lib/src/annotation/fory_field.dart | 10 +-
.../fory/lib/src/annotation/fory_struct.dart | 16 ++
.../fory/lib/src/codegen/fory_generator.dart | 54 +++++-
.../fory/test/graph_memory_budget_test.dart | 20 +-
.../test/struct_inheritance_generator_test.dart | 80 ++++++++
.../struct_private_companion_generator_test.dart | 183 ++++++++++++++++--
.../inheritance-test-models/lib/base_models.dart | 23 +++
.../inheritance-test-models/lib/middle_models.dart | 14 ++
docs/guide/dart/code-generation.md | 93 +--------
docs/guide/dart/custom-serializers.md | 2 +-
docs/guide/dart/external-types.md | 8 +-
docs/guide/dart/grpc-support.md | 2 +-
docs/guide/dart/index.md | 7 +-
docs/guide/dart/inheritance.md | 211 +++++++++++++++++++++
docs/guide/dart/schema-evolution.md | 30 +--
docs/guide/dart/schema-metadata.md | 27 ++-
docs/guide/dart/supported-types.md | 26 ++-
docs/guide/dart/troubleshooting.md | 43 +++--
docs/guide/dart/type-registration.md | 6 +-
docs/guide/dart/web-platform-support.md | 13 +-
docs/guide/dart/xlang-serialization.md | 17 +-
docs/specification/xlang_implementation_guide.md | 111 ++++++-----
28 files changed, 851 insertions(+), 332 deletions(-)
diff --git a/.agents/languages/dart.md b/.agents/languages/dart.md
index 47613198b..f1edb4482 100644
--- a/.agents/languages/dart.md
+++ b/.agents/languages/dart.md
@@ -24,34 +24,46 @@ Load this file when changing `dart/`.
Dart accessibility. Enumerate each instantiated hierarchy layer's declared
fields; do not use only the child `element.fields`, `allSupertypes`, member
lookup, import visibility, or privacy as field discovery.
-- Process each discovered ordinary field through one owner path: apply only
- its declaration-owned `ForyField(ignore: true)`, substitute the concrete
- generic type, resolve direct or companion access, prove construction, then
- build the concrete child's one globally sorted flattened schema. Never omit
- a non-ignored field because it is private, inaccessible, final, hidden, or
- unsupported; report a generation error.
+- Process each discovered ordinary field through one owner path: apply its
+ declaration-owned `ForyField(ignore: true)`, then the concrete child's
+ `ignoreInheritedPrivateFields` policy, substitute the concrete generic type,
+ resolve direct or companion access, prove construction, then build the
+ concrete child's one globally sorted flattened schema. The child policy
+ omits every ancestor- or applied-mixin-declared private field, including
+ same-library fields, but never child-declared private or inherited public
+ fields. Never omit a remaining field because it is inaccessible, final,
+ hidden, or unsupported; report a generation error.
+- `ignoreInheritedPrivateFields` defaults to false, belongs only to an ordinary
+ concrete schema owner, and is not inherited from ancestor annotations.
+ Reject true on external and provider-only abstract, open-generic, or mixin
+ declarations. Filtering must happen before substitution and access
+ resolution, without changing complete hierarchy discovery.
- Public inherited fields and private inherited fields declared in the child's
library use direct generated access without a parent annotation.
- Cross-library private storage requires
+ Included cross-library private storage requires
`ForyStruct(exposePrivateFields: true)` on a public hierarchy boundary in
- that field's declaring library. That provider emits only public typed static
- getter/setter access for its own library's private state; it owns no schema,
+ that field's declaring library. The companion emits only public typed static
+ getter/setter access for its own library's private state and owns no schema,
serializer, construction, registration, reference, or graph-memory state.
- Each declaring library in a multi-library hierarchy must provide its own
- boundary. A consumer annotation cannot authorize another library's field.
-- A non-ignored ordinary `final` or `late final` field must receive its decoded
+ Companion generation is independent of a consumer's omission policy. Each
+ declaring library in a multi-library hierarchy must provide its own
+ boundary. A consumer exposure annotation cannot authorize another library's
+ field.
+- An included ordinary `final` or `late final` field must receive its decoded
value unchanged from the selected concrete-child constructor through
element-proven field formals, super formals, redirects, or explicit
initializer/super arguments. Names are not bindings. Do not post-set final
- state, use reflection, or fall back when identity flow cannot be proven.
+ state, invent a required constructor source after filtering, use reflection,
+ or fall back when identity flow cannot be proven.
- The concrete ordinary child owns one flattened schema, serializer,
constructor reconstruction, reference publication path, and graph-memory
- object charge. Inherited reference metadata enters the existing recursive
- reference analysis once. Do not add reference state, change `ReadContext` or
- serializer reference-call contracts, or invoke a parent serializer for
- inheritance.
+ object charge. Included inherited reference metadata enters the existing
+ recursive reference analysis once; omitted fields do not. Do not add
+ reference state, change `ReadContext` or serializer reference-call contracts,
+ or invoke a parent serializer for inheritance.
- Keep external target fields explicit. Ordinary hierarchy discovery and
- `exposePrivateFields` must never scan or expose an external target hierarchy.
+ `exposePrivateFields` must never scan or expose an external target hierarchy,
+ and `ignoreInheritedPrivateFields` is invalid with `target`.
- Across packages, generate and publish the provider library's `.fory.dart`
part before building a consumer that uses its private-field access companion.
A direct import or re-export must expose both the public boundary and
diff --git a/dart/README.md b/dart/README.md
index 531df21b5..9cc8ed727 100644
--- a/dart/README.md
+++ b/dart/README.md
@@ -96,12 +96,8 @@ final roundTrip = fory.deserialize<Person>(bytes);
```
Ordinary annotated classes serialize one flattened view of their concrete
-superclass and applied-mixin storage. Public and same-library private inherited
-fields need no parent annotation. A declaring library that intentionally
-exposes private state to generated serializers in other libraries marks a
-public hierarchy boundary with `@ForyStruct(exposePrivateFields: true)`.
-`@ForyField(ignore: true)` on the field declaration is the only way to omit
-ordinary storage.
+superclass and applied-mixin storage. See
+[Struct Inheritance](../docs/guide/dart/inheritance.md) for details.
## Development
diff --git a/dart/packages/fory-test/lib/model/inheritance_models.dart
b/dart/packages/fory-test/lib/model/inheritance_models.dart
index 716dc8b71..2c283adc5 100644
--- a/dart/packages/fory-test/lib/model/inheritance_models.dart
+++ b/dart/packages/fory-test/lib/model/inheritance_models.dart
@@ -39,6 +39,14 @@ final class CrossLibraryChild extends
middle.PublicMiddleBoundary {
String childMutable = '';
}
+@ForyStruct(ignoreInheritedPrivateFields: true)
+final class IgnoringPrivateChild extends middle.UnexposedPrivateMiddle {
+ IgnoringPrivateChild();
+
+ @ForyField(id: 10)
+ String childPublic = '';
+}
+
class OptionalMutableBase {
OptionalMutableBase([int decoded = 0])
: inheritedMutable = decoded,
diff --git a/dart/packages/fory-test/test/struct_inheritance_test.dart
b/dart/packages/fory-test/test/struct_inheritance_test.dart
index e210dc17f..36f57484f 100644
--- a/dart/packages/fory-test/test/struct_inheritance_test.dart
+++ b/dart/packages/fory-test/test/struct_inheritance_test.dart
@@ -99,6 +99,38 @@ void main() {
});
}
+ for (final compatible in <bool>[false, true]) {
+ test('omits inherited private fields compatible=$compatible', () {
+ final fory = Fory(compatible: compatible);
+ InheritanceModelsForyModule.register(
+ fory,
+ IgnoringPrivateChild,
+ id: compatible ? null : 407,
+ name: compatible ? 'inheritance.IgnoringPrivateChild' : null,
+ );
+
+ final input =
+ IgnoringPrivateChild()
+ ..setBasePrivate('base-private')
+ ..setMixinPrivate('mixin-private')
+ ..setMiddlePrivate('middle-private')
+ ..basePublic = 'base-public'
+ ..middlePublic = 'middle-public'
+ ..childPublic = 'child-public';
+
+ final result = fory.deserialize<IgnoringPrivateChild>(
+ fory.serialize(input),
+ );
+
+ expect(result.basePrivate, 'base-private-default');
+ expect(result.mixinPrivate, 'mixin-private-default');
+ expect(result.middlePrivate, 'middle-private-default');
+ expect(result.basePublic, 'base-public');
+ expect(result.middlePublic, 'middle-public');
+ expect(result.childPublic, 'child-public');
+ });
+ }
+
test('passes optional mutable state through construction', () {
final fory = Fory();
InheritanceModelsForyModule.register(fory, OptionalMutableChild, id:
405);
diff --git a/dart/packages/fory/CHANGELOG.md b/dart/packages/fory/CHANGELOG.md
index a7f2566b5..cdb0ac13e 100644
--- a/dart/packages/fory/CHANGELOG.md
+++ b/dart/packages/fory/CHANGELOG.md
@@ -10,9 +10,15 @@
concrete child's generated schema. Public and same-library private fields use
direct access; cross-library private fields require
`exposePrivateFields: true` on a public boundary in each declaring library.
-- Reject hidden, inaccessible, unsupported, or unconstructable inherited
- storage instead of omitting it. Non-ignored `final` and `late final` fields
- now require a proven identity-preserving constructor path.
+- Reject hidden, inaccessible, unsupported, or unconstructable included
+ inherited storage instead of silently omitting it. Included `final` and
+ `late final` fields now require a proven identity-preserving constructor
+ path.
+- Add `ForyStruct.ignoreInheritedPrivateFields`, defaulting to `false`, so a
+ concrete ordinary child can explicitly omit all private superclass and
+ applied-mixin storage from its own flattened schema. Child-declared private
+ fields and inherited public fields remain included; setting the option to
+ `true` on external and provider-only declarations is rejected.
- This inheritance correction is a breaking generated-schema change. Regenerate
all affected `.fory.dart` files; fixed-schema payloads written when inherited
fields were omitted are not supported by a compatibility reader. External
diff --git a/dart/packages/fory/README.md b/dart/packages/fory/README.md
index cda678654..9d66b5a69 100644
--- a/dart/packages/fory/README.md
+++ b/dart/packages/fory/README.md
@@ -93,67 +93,24 @@ dart run build_runner build
## Ordinary Struct Inheritance
-An ordinary `@ForyStruct()` includes all instance storage from its concrete
-superclass and applied-mixin chain. The concrete child has one flattened schema
-and one generated serializer; parent fields are globally ordered with child
-fields rather than encoded as a nested parent object.
-
-Public inherited fields and private inherited fields declared in the same Dart
-library need no annotation on the parent. Field metadata stays with the field
-declaration, and `@ForyField(ignore: true)` on that declaration is the only way
-to omit storage from the generated schema.
-
-Private fields declared in another Dart library require an explicit opt-in from
-that declaring library:
-
```dart
-// package:model_owner/base.dart
-import 'package:fory/fory.dart';
-
-part 'base.fory.dart';
-
-@ForyStruct(exposePrivateFields: true)
-abstract class AccountBase {
- AccountBase(String tenantId) : _tenantId = tenantId;
-
- final String _tenantId;
-
- String get tenantId => _tenantId;
+class MessageBase {
+ int sequence = 0;
}
-```
-
-The concrete child uses the normal annotation:
-
-```dart
-// lib/account.dart
-import 'package:fory/fory.dart';
-import 'package:model_owner/base.dart';
-
-part 'account.fory.dart';
@ForyStruct()
-final class Account extends AccountBase {
- Account(String tenantId) : super(tenantId);
+class TextMessage extends MessageBase {
+ TextMessage();
+
+ String text = '';
}
```
-Run code generation in the package that declares `AccountBase` before building
-a dependent package. The provider's published source must include its generated
-`.fory.dart` part. A barrel import is also valid when it re-exports both the
-public boundary and its generated access companion.
-
-`exposePrivateFields` controls only cross-library access to private state. It
-does not enable field discovery, affect same-library private fields, or grant a
-child permission to expose private state owned by another library. If private
-fields come from multiple libraries, each declaring library must opt in
-independently.
-
-Every non-ignored `final` or `late final` field must receive its decoded value
-unchanged through the concrete child's generative constructor chain. Fory
-accepts initializing formals, super formals, redirects, and direct constructor
-initializers that preserve the exact field value. A matching parameter name
-alone is not sufficient. Generation fails for inaccessible, hidden,
-unsupported, or unconstructable storage instead of silently dropping it.
+The generated `TextMessage` schema contains both `sequence` and `text`.
+Superclass and applied-mixin fields are flattened into one child serializer.
+See [Struct Inheritance](https://fory.apache.org/docs/guide/dart/inheritance)
+for private fields, mixins, constructors, and
+`ignoreInheritedPrivateFields`.
## External-Type Serialization
@@ -198,7 +155,8 @@ registration. Select a public named generative constructor
with
`constructor: 'name'` when the unnamed constructor is not appropriate.
External declarations remain explicit schemas: they may list an accessible
inherited target property, but Fory does not scan the external target's
-hierarchy automatically, and `exposePrivateFields` is not valid with `target`.
+hierarchy automatically. Neither `exposePrivateFields` nor
+`ignoreInheritedPrivateFields` is valid with `target`.
## Type Registration
@@ -266,8 +224,9 @@ class NodeList {
}
```
-Inherited field metadata enters this same reference analysis. Inheritance does
-not add a second reference owner or change the runtime reference protocol.
+Included inherited field metadata enters this same reference analysis.
+Inheritance does not add a second reference owner or change the runtime
+reference protocol.
## Field Annotations
@@ -393,9 +352,9 @@ The main exported API includes:
- `Fory` — main serialization facade
- `Config` — Fory configuration
-- `ForyStruct`, including `target`, `constructor`, and
- `exposePrivateFields`, plus `ForyField`, `ListField`, `SetField`, and
- `MapField` — struct annotations
+- `ForyStruct`, including `target`, `constructor`, `exposePrivateFields`, and
+ `ignoreInheritedPrivateFields`, plus `ForyField`, `ListField`, `SetField`,
+ and `MapField` — struct annotations
- `ForyUnion` — union type annotation
- `Serializer`, `UnionSerializer`, `EnumSerializer` — serializer base classes
- `Buffer`, `WriteContext`, `ReadContext` — low-level I/O
diff --git a/dart/packages/fory/lib/src/annotation/fory_field.dart
b/dart/packages/fory/lib/src/annotation/fory_field.dart
index a9b82e51a..0ad3f9887 100644
--- a/dart/packages/fory/lib/src/annotation/fory_field.dart
+++ b/dart/packages/fory/lib/src/annotation/fory_field.dart
@@ -22,13 +22,15 @@ import 'package:fory/src/annotation/type_spec.dart';
/// Configures serialization for the storage field on which it is declared.
///
/// Field metadata remains attached to its declaration when an ordinary
-/// `ForyStruct` inherits the field. Every discovered ordinary storage field is
-/// serialized unless that declaring field sets [ignore] to `true`.
+/// `ForyStruct` inherits the field. [ignore] is the declaration-owned,
+/// per-field omission option. A concrete child may separately omit all
+/// ancestor-declared private storage through
+/// `ForyStruct.ignoreInheritedPrivateFields`.
final class ForyField {
/// Whether to omit this field from the serialized schema.
///
- /// This is the only supported way to omit an ordinary instance storage
- /// field. Ignored storage still contributes to shallow graph-memory
+ /// This is the only declaration-owned way to omit an ordinary instance
+ /// storage field. Ignored storage still contributes to shallow graph-memory
/// accounting.
final bool ignore;
diff --git a/dart/packages/fory/lib/src/annotation/fory_struct.dart
b/dart/packages/fory/lib/src/annotation/fory_struct.dart
index 786aab085..fea22ac1a 100644
--- a/dart/packages/fory/lib/src/annotation/fory_struct.dart
+++ b/dart/packages/fory/lib/src/annotation/fory_struct.dart
@@ -48,11 +48,27 @@ final class ForyStruct {
/// used with [target].
final bool exposePrivateFields;
+ /// Whether this struct omits private storage declared by hierarchy
ancestors.
+ ///
+ /// This option belongs to the annotated concrete struct only. When enabled,
+ /// private instance fields declared by any superclass or applied mixin are
+ /// omitted from this struct's flattened schema, including fields from the
+ /// same library. Private fields declared by the annotated class and all
+ /// inherited public fields remain in the schema.
+ ///
+ /// This option defaults to `false` and is not inherited from an ancestor's
+ /// annotation. It is invalid with [target] and on provider-only
+ /// declarations. When a concrete boundary also enables
+ /// [exposePrivateFields], its provider companion is generated independently
+ /// of this schema option.
+ final bool ignoreInheritedPrivateFields;
+
/// Creates struct-level generation options.
const ForyStruct({
this.evolving = true,
this.target,
this.constructor,
this.exposePrivateFields = false,
+ this.ignoreInheritedPrivateFields = false,
});
}
diff --git a/dart/packages/fory/lib/src/codegen/fory_generator.dart
b/dart/packages/fory/lib/src/codegen/fory_generator.dart
index 619b5202e..8d4b240b2 100644
--- a/dart/packages/fory/lib/src/codegen/fory_generator.dart
+++ b/dart/packages/fory/lib/src/codegen/fory_generator.dart
@@ -147,14 +147,8 @@ final class ForyGenerator extends Generator {
);
for (final element in annotatedClasses) {
final options = _structOptions(element);
- final ownsSerializer =
- options.target != null ||
- (_ownsOrdinarySerializer(element) && element.typeParameters.isEmpty);
- if (!ownsSerializer) {
- _validateProviderOnly(element, options);
- }
- if (options.exposePrivateFields) {
- if (options.target != null) {
+ if (options.target != null) {
+ if (options.exposePrivateFields) {
throw InvalidGenerationSourceError(
'ForyStruct.exposePrivateFields cannot be used with '
'ForyStruct.target. External structural declarations retain an '
@@ -162,6 +156,22 @@ final class ForyGenerator extends Generator {
element: element,
);
}
+ if (options.ignoreInheritedPrivateFields) {
+ throw InvalidGenerationSourceError(
+ 'ForyStruct.ignoreInheritedPrivateFields cannot be used with '
+ 'ForyStruct.target. External structural declarations retain an '
+ 'explicit field model.',
+ element: element,
+ );
+ }
+ }
+ final ownsSerializer =
+ options.target != null ||
+ (_ownsOrdinarySerializer(element) && element.typeParameters.isEmpty);
+ if (!ownsSerializer) {
+ _validateProviderOnly(element, options);
+ }
+ if (options.exposePrivateFields) {
companionSpecs.add(
await _analyzePrivateAccessCompanion(element, buildStep),
);
@@ -260,6 +270,8 @@ final class ForyGenerator extends Generator {
final evolving = objectReader.peek('evolving')?.boolValue ?? true;
final exposePrivateFields =
objectReader.peek('exposePrivateFields')?.boolValue ?? false;
+ final ignoreInheritedPrivateFields =
+ objectReader.peek('ignoreInheritedPrivateFields')?.boolValue ?? false;
final targetReader = objectReader.peek('target');
final annotatedTarget =
targetReader == null || targetReader.isNull
@@ -275,6 +287,7 @@ final class ForyGenerator extends Generator {
target: annotatedTarget,
constructorName: constructorName,
exposePrivateFields: exposePrivateFields,
+ ignoreInheritedPrivateFields: ignoreInheritedPrivateFields,
);
_structOptionsByElement[element] = options;
return options;
@@ -291,6 +304,14 @@ final class ForyGenerator extends Generator {
element: element,
);
}
+ if (options.ignoreInheritedPrivateFields) {
+ throw InvalidGenerationSourceError(
+ 'ForyStruct.ignoreInheritedPrivateFields is valid only on an '
+ 'ordinary concrete declaration that owns a generated flattened '
+ 'schema. ${element.displayName} is provider-only.',
+ element: element,
+ );
+ }
if (!options.exposePrivateFields) {
throw InvalidGenerationSourceError(
'${element.displayName} does not own a concrete generated serializer. '
@@ -418,6 +439,16 @@ final class ForyGenerator extends Generator {
if (_isIgnored(field.declaration)) {
continue;
}
+ if (options.ignoreInheritedPrivateFields &&
+ field.declaration.isPrivate &&
+ // Declaration ownership determines whether storage is inherited;
+ // an applied mixin layer is never owned by the concrete child.
+ !identical(
+ field.declaration.enclosingElement.baseElement,
+ element.baseElement,
+ )) {
+ continue;
+ }
included.add(field);
includedNames.add(field.declaration.displayName);
}
@@ -1082,7 +1113,10 @@ final class ForyGenerator extends Generator {
'by ${field.library.uri}, while generating ${child.displayName} in '
'${child.library.uri}. $authorization$consumerPermission Import a '
'qualifying boundary together with its generated companion, mark the '
- 'field with @ForyField(ignore: true), or use a manual serializer.',
+ 'field with @ForyField(ignore: true), set '
+ '@ForyStruct(ignoreInheritedPrivateFields: true) on '
+ '${child.displayName} to omit all inherited private storage, or use a '
+ 'manual serializer.',
element: field,
);
}
@@ -5759,12 +5793,14 @@ final class _StructOptions {
final DartType? target;
final String? constructorName;
final bool exposePrivateFields;
+ final bool ignoreInheritedPrivateFields;
const _StructOptions({
required this.evolving,
required this.target,
required this.constructorName,
required this.exposePrivateFields,
+ required this.ignoreInheritedPrivateFields,
});
}
diff --git a/dart/packages/fory/test/graph_memory_budget_test.dart
b/dart/packages/fory/test/graph_memory_budget_test.dart
index bc2dba480..ef3611be8 100644
--- a/dart/packages/fory/test/graph_memory_budget_test.dart
+++ b/dart/packages/fory/test/graph_memory_budget_test.dart
@@ -102,19 +102,17 @@ class BudgetHierarchyBase {
@ForyField(id: 30, type: Int32Type())
int baseValue = 0;
- @ForyField(ignore: true)
- int ignoredBase = 0;
+ int _ignoredBase = 0;
}
mixin BudgetHierarchyMixin {
@ForyField(id: 10, type: Int32Type())
int mixinValue = 0;
- @ForyField(ignore: true)
- int ignoredMixin = 0;
+ int _ignoredMixin = 0;
}
-@ForyStruct()
+@ForyStruct(ignoreInheritedPrivateFields: true)
class BudgetHierarchyChild extends BudgetHierarchyBase
with BudgetHierarchyMixin {
BudgetHierarchyChild();
@@ -373,9 +371,9 @@ void main() {
final bytes = writer.serialize(
BudgetHierarchyChild()
..baseValue = 30
- ..ignoredBase = 31
+ .._ignoredBase = 31
..mixinValue = 10
- ..ignoredMixin = 11
+ .._ignoredMixin = 11
..childValue = 20,
);
final required = _objectGraphBytes(5);
@@ -393,8 +391,8 @@ void main() {
expect(roundTrip.baseValue, equals(30));
expect(roundTrip.mixinValue, equals(10));
expect(roundTrip.childValue, equals(20));
- expect(roundTrip.ignoredBase, isZero);
- expect(roundTrip.ignoredMixin, isZero);
+ expect(roundTrip._ignoredBase, isZero);
+ expect(roundTrip._ignoredMixin, isZero);
});
test('reserves map entries', () {
@@ -520,8 +518,8 @@ void main() {
expect(roundTrip.baseValue, isZero);
expect(roundTrip.mixinValue, isZero);
expect(roundTrip.childValue, equals(20));
- expect(roundTrip.ignoredBase, isZero);
- expect(roundTrip.ignoredMixin, isZero);
+ expect(roundTrip._ignoredBase, isZero);
+ expect(roundTrip._ignoredMixin, isZero);
});
test('skips strings binary and dense typed arrays', () {
diff --git a/dart/packages/fory/test/struct_inheritance_generator_test.dart
b/dart/packages/fory/test/struct_inheritance_generator_test.dart
index b5475416b..462379160 100644
--- a/dart/packages/fory/test/struct_inheritance_generator_test.dart
+++ b/dart/packages/fory/test/struct_inheritance_generator_test.dart
@@ -368,6 +368,86 @@ class PrivateFinalChild extends PrivateFinalParent {
);
});
+ test('filters inherited private storage before schema analysis', () async {
+ await _expectGenerationOutput(
+ source: '''
+class PolicyBase {
+ Object? _baseSecret;
+ Object? inheritedPublic;
+}
+
+mixin PolicyMixin {
+ @ForyField(ref: true)
+ Object? _mixinSecret;
+
+ Object? mixinPublic;
+}
+
+@ForyStruct(ignoreInheritedPrivateFields: true)
+class PolicyChild extends PolicyBase with PolicyMixin {
+ PolicyChild();
+
+ Object? _childPrivate;
+ Object? childPublic;
+}
+''',
+ output: allOf(
+ _wireFieldsInOrder(const <String>[
+ '_child_private',
+ 'child_public',
+ 'inherited_public',
+ 'mixin_public',
+ ]),
+ contains('needsRootRef: false,'),
+ isNot(contains("identifier: '_base_secret',")),
+ isNot(contains("identifier: '_mixin_secret',")),
+ isNot(contains('context.reference(value);')),
+ ),
+ );
+ });
+
+ test('does not inherit the parent omission policy', () async {
+ await _expectGenerationOutput(
+ source: '''
+class PolicyRoot {
+ Object? _rootSecret;
+}
+
+@ForyStruct(ignoreInheritedPrivateFields: true)
+class PolicyParent extends PolicyRoot {
+ PolicyParent();
+}
+
+@ForyStruct()
+class PolicyChild extends PolicyParent {
+ PolicyChild();
+}
+''',
+ output: allOf(
+ _containsOnce("identifier: '_root_secret',"),
+ contains('value._rootSecret'),
+ ),
+ );
+ });
+
+ test('keeps strict construction after private filtering', () async {
+ await _expectGenerationError(
+ source: '''
+class RequiredPrivateBase {
+ RequiredPrivateBase(int decoded) : _secret = decoded;
+
+ final int _secret;
+}
+
+@ForyStruct(ignoreInheritedPrivateFields: true)
+class RequiredPrivateChild extends RequiredPrivateBase {
+ RequiredPrivateChild(int decoded) : super(decoded);
+}
+''',
+ message: 'has no serialized field connected by an exact',
+ );
+ });
+
test(
'ignores only declaration-owned fields before access checks',
() async {
diff --git
a/dart/packages/fory/test/struct_private_companion_generator_test.dart
b/dart/packages/fory/test/struct_private_companion_generator_test.dart
index 0ec50e799..d328dd553 100644
--- a/dart/packages/fory/test/struct_private_companion_generator_test.dart
+++ b/dart/packages/fory/test/struct_private_companion_generator_test.dart
@@ -194,6 +194,36 @@ class ConcreteSurface {
expect(normal, isNot(contains(r'$ConcreteSurfaceForyFieldAccess')));
});
+ test(
+ 'keeps concrete omission and companion ownership independent',
+ () async {
+ const inputPath = 'test/concrete_omission_provider.dart';
+ final output = await _generate(
+ inputPath: inputPath,
+ source: _librarySource(inputPath, '''
+class ConcreteBase {
+ int _baseSecret = 0;
+}
+
+@ForyStruct(
+ exposePrivateFields: true,
+ ignoreInheritedPrivateFields: true,
+)
+class ConcreteBoundary extends ConcreteBase {
+ int _ownSecret = 0;
+}
+'''),
+ );
+
+ expect(output, contains("identifier: '_own_secret',"));
+ expect(output, isNot(contains("identifier: '_base_secret',")));
+ expect(output, contains('=> value._baseSecret;'));
+ expect(output, contains('value._baseSecret = fieldValue;'));
+ expect(output, contains('=> value._ownSecret;'));
+ expect(output, contains('value._ownSecret = fieldValue;'));
+ },
+ );
+
test('exposePrivateFields defaults to false', () async {
const inputPath = 'test/default_false.dart';
await _expectGenerationError(
@@ -208,27 +238,36 @@ abstract class Boundary {
);
});
- test('consumer annotation cannot authorize parent storage', () async {
- const inputPath = 'test/consumer_annotation.dart';
- await _expectGenerationError(
- inputPath: inputPath,
- source: _librarySource(inputPath, '''
-@ForyStruct(exposePrivateFields: true)
+ test('unexposed parent remains strict by default', () async {
+ const cases = <({String name, String annotation})>[
+ (name: 'default', annotation: '@ForyStruct()'),
+ (
+ name: 'consumer_exposure',
+ annotation: '@ForyStruct(exposePrivateFields: true)',
+ ),
+ ];
+ for (final testCase in cases) {
+ final inputPath = 'test/${testCase.name}_unexposed_parent.dart';
+ await _expectGenerationError(
+ inputPath: inputPath,
+ source: _librarySource(inputPath, '''
+${testCase.annotation}
class Child extends Boundary {
int _childSecret = 0;
}
''', directives: "import 'unexposed_parent.dart';"),
- additionalAssets: <String, String>{
- 'fory|test/unexposed_parent.dart': '''
+ additionalAssets: const <String, String>{
+ 'fory|test/unexposed_parent.dart': '''
abstract class Boundary {
int _parentSecret = 0;
}
''',
- },
- message:
- 'No public hierarchy boundary in the declaring library is '
- 'annotated with @ForyStruct(exposePrivateFields: true)',
- );
+ },
+ message:
+ 'No public hierarchy boundary in the declaring library is '
+ 'annotated with @ForyStruct(exposePrivateFields: true)',
+ );
+ }
});
test('external target cannot expose private fields', () async {
@@ -251,6 +290,26 @@ abstract final class TargetSchema {
);
});
+ test('external target cannot ignore inherited private fields', () async {
+ const inputPath = 'test/external_inherited_private_omission.dart';
+ await _expectGenerationError(
+ inputPath: inputPath,
+ source: _librarySource(inputPath, '''
+class Target {
+ int value = 0;
+}
+
+@ForyStruct(target: Target, ignoreInheritedPrivateFields: true)
+abstract final class TargetSchema {
+ late final int value;
+}
+'''),
+ message:
+ 'ForyStruct.ignoreInheritedPrivateFields cannot be used with '
+ 'ForyStruct.target',
+ );
+ });
+
test('empty or fully ignored provider is rejected', () async {
const inputPath = 'test/empty_provider.dart';
await _expectGenerationError(
@@ -331,6 +390,58 @@ abstract class Boundary {
);
}
});
+
+ test('provider-only declarations cannot own omission policy', () async {
+ const cases = <({String name, String declaration})>[
+ (
+ name: 'abstract',
+ declaration: '''
+@ForyStruct(
+ exposePrivateFields: true,
+ ignoreInheritedPrivateFields: true,
+)
+abstract class Boundary {
+ int _secret = 0;
+}
+''',
+ ),
+ (
+ name: 'generic',
+ declaration: '''
+@ForyStruct(
+ exposePrivateFields: true,
+ ignoreInheritedPrivateFields: true,
+)
+class Boundary<T> {
+ int _secret = 0;
+}
+''',
+ ),
+ (
+ name: 'mixin',
+ declaration: '''
+@ForyStruct(
+ exposePrivateFields: true,
+ ignoreInheritedPrivateFields: true,
+)
+mixin Boundary {
+ int _secret = 0;
+}
+''',
+ ),
+ ];
+
+ for (final testCase in cases) {
+ final inputPath = 'test/${testCase.name}_omission_provider.dart';
+ await _expectGenerationError(
+ inputPath: inputPath,
+ source: _librarySource(inputPath, testCase.declaration),
+ message:
+ 'ForyStruct.ignoreInheritedPrivateFields is valid only on an '
+ 'ordinary concrete declaration',
+ );
+ }
+ });
});
group('companion API', () {
@@ -491,6 +602,52 @@ abstract class Boundary {
group('consumer resolution', () {
final providerSource = _providerSource();
+ test('omits unexposed inherited private storage', () async {
+ const inputPath = 'test/omitting_unexposed_consumer.dart';
+ final output = await _generate(
+ inputPath: inputPath,
+ source: _librarySource(inputPath, '''
+@ForyStruct(ignoreInheritedPrivateFields: true)
+class Child extends UnexposedParent {
+ int _childSecret = 0;
+}
+''', directives: "import 'unexposed_parent.dart';"),
+ additionalAssets: const <String, String>{
+ 'fory|test/unexposed_parent.dart': '''
+class UnexposedParent {
+ int _secret = 0;
+ int inheritedPublic = 0;
+}
+''',
+ },
+ );
+
+ expect(output, contains("identifier: '_child_secret',"));
+ expect(output, contains("identifier: 'inherited_public',"));
+ expect(output, isNot(contains("identifier: '_secret',")));
+ expect(output, isNot(contains('ForyFieldAccess')));
+ });
+
+ test('omits private storage even when a companion exists', () async {
+ const inputPath = 'test/omitting_exposed_consumer.dart';
+ final output = await _generate(
+ inputPath: inputPath,
+ source: _librarySource(inputPath, '''
+@ForyStruct(ignoreInheritedPrivateFields: true)
+class Child extends Boundary {
+ int value = 0;
+}
+''', directives: "import 'private_provider.dart';"),
+ additionalAssets: <String, String>{
+ 'fory|test/private_provider.dart': providerSource,
+ },
+ );
+
+ expect(output, contains("identifier: 'value',"));
+ expect(output, isNot(contains("identifier: '_secret',")));
+ expect(output, isNot(contains(r'$BoundaryForyFieldAccess')));
+ });
+
test('resolves direct, prefixed, re-exported, and shown helpers', () async
{
final cases = <
({
diff --git a/dart/packages/inheritance-test-models/lib/base_models.dart
b/dart/packages/inheritance-test-models/lib/base_models.dart
index 2cc70ec57..b2b32db9e 100644
--- a/dart/packages/inheritance-test-models/lib/base_models.dart
+++ b/dart/packages/inheritance-test-models/lib/base_models.dart
@@ -90,3 +90,26 @@ abstract class XlangInheritanceBoundary {
_parentText = parentText;
}
}
+
+class UnexposedPrivateBase {
+ String _basePrivate = 'base-private-default';
+
+ @ForyField(id: 30)
+ String basePublic = '';
+
+ String get basePrivate => _basePrivate;
+
+ void setBasePrivate(String value) {
+ _basePrivate = value;
+ }
+}
+
+mixin UnexposedPrivateMixin {
+ String _mixinPrivate = 'mixin-private-default';
+
+ String get mixinPrivate => _mixinPrivate;
+
+ void setMixinPrivate(String value) {
+ _mixinPrivate = value;
+ }
+}
diff --git a/dart/packages/inheritance-test-models/lib/middle_models.dart
b/dart/packages/inheritance-test-models/lib/middle_models.dart
index 66f3c9019..3d48af3cf 100644
--- a/dart/packages/inheritance-test-models/lib/middle_models.dart
+++ b/dart/packages/inheritance-test-models/lib/middle_models.dart
@@ -50,3 +50,17 @@ abstract class PublicMiddleBoundary extends
PublicGenericBoundary<String>
_sharedName = value;
}
}
+
+class UnexposedPrivateMiddle extends UnexposedPrivateBase
+ with UnexposedPrivateMixin {
+ String _middlePrivate = 'middle-private-default';
+
+ @ForyField(id: 20)
+ String middlePublic = '';
+
+ String get middlePrivate => _middlePrivate;
+
+ void setMiddlePrivate(String value) {
+ _middlePrivate = value;
+ }
+}
diff --git a/docs/guide/dart/code-generation.md
b/docs/guide/dart/code-generation.md
index 63e5aee95..a3a06745e 100644
--- a/docs/guide/dart/code-generation.md
+++ b/docs/guide/dart/code-generation.md
@@ -58,87 +58,13 @@ For a class owned by another library, define an
## Inherited Fields
-For an ordinary struct, Fory follows the concrete superclass and applied-mixin
-storage chain. All non-static instance storage is flattened into the concrete
-child's one generated schema, globally ordered with fields declared directly
-on the child. Interfaces and abstract accessors do not add storage.
+An ordinary `@ForyStruct()` flattens its concrete superclass and applied-mixin
+fields into one generated child schema. Public inherited fields require no
+annotation on the parent.
-Field annotations belong to the field declaration. In particular,
-`@ForyField(ignore: true)` on the declaring field is the only way to omit
-ordinary storage. Fory reports a generation error instead of silently omitting
-a field that is inaccessible, hidden, unsupported, or cannot be reconstructed.
-
-| Inherited field | Requirement
|
-| --------------------------------------- |
------------------------------------------------------------------------- |
-| Public field | No parent annotation; generated
child code accesses it directly |
-| Private field in the child's library | No parent annotation; the
generated part accesses it directly |
-| Private field in another Dart library | A public boundary in that
declaring library uses `exposePrivateFields` |
-| Field marked `@ForyField(ignore: true)` | Omitted from the schema; no access
or construction requirement is checked |
-
-To expose private state from a library that owns a base class:
-
-```dart
-// package:model_owner/base.dart
-import 'package:fory/fory.dart';
-
-part 'base.fory.dart';
-
-@ForyStruct(exposePrivateFields: true)
-abstract class AccountBase {
- AccountBase(String tenantId) : _tenantId = tenantId;
-
- final String _tenantId;
-
- String get tenantId => _tenantId;
-}
-```
-
-The consumer annotates only its concrete type:
-
-```dart
-// lib/account.dart
-import 'package:fory/fory.dart';
-import 'package:model_owner/base.dart';
-
-part 'account.fory.dart';
-
-@ForyStruct()
-final class Account extends AccountBase {
- Account(String tenantId) : super(tenantId);
-}
-```
-
-`exposePrivateFields` defaults to `false` and authorizes only the generated
-private-field access companion owned by that library. It does not control field
-discovery or same-library private access. Placing it on `Account` cannot expose
-private fields owned by `model_owner`. If a hierarchy contains private fields
-from several libraries, each declaring library needs its own public opted-in
-boundary.
-
-The child source must import the provider namespace without hiding the
-generated companion. A barrel is valid when it re-exports both the public
-boundary and the companion. Across packages, generate and publish the
-provider's `.fory.dart` part before building a consumer.
-
-For example, a restrictive barrel for the model above must include both names:
-
-```dart
-export 'base.dart'
- show AccountBase, $AccountBaseForyFieldAccess;
-```
-
-Non-ignored `final` and `late final` fields require an identity-preserving path
-from a parameter of the concrete child's selected generative constructor to
-the exact field. Initializing formals, super formals, redirects, and direct
-constructor initializers are supported. A parameter with the same name is not
-proof if the constructor ignores or transforms it. Use
-`@ForyField(ignore: true)` or a manual serializer when the object cannot be
-reconstructed without custom logic.
-
-The concrete child is registered independently and owns the only serializer
-for its flattened schema. Parent serializers are not nested or invoked.
-Inherited reference annotations feed the existing reference behavior exactly
-like fields declared directly on the child.
+See [Struct Inheritance](inheritance.md) for private fields,
+`ignoreInheritedPrivateFields`, cross-library access, constructors, mixins, and
+schema compatibility.
## Step 2 — Run the Generator
@@ -150,7 +76,7 @@ dart run build_runner build
This emits a `.fory.dart` file next to your source file. Re-run this command
any
time you add or rename annotated types, change hierarchy storage, or change an
-exposure boundary.
+exposure boundary or `ignoreInheritedPrivateFields`.
## Step 3 — Register and Use
@@ -193,8 +119,8 @@ class Event {
When using evolving structs, also assign stable field IDs with `@ForyField(id:
...)` before you ship your first payload — those IDs are how Fory matches
fields after a schema change.
-Inherited and direct fields share this one ID namespace. Do not reuse an ID in
-another superclass, mixin, or child field.
+Included inherited and direct fields share this one ID namespace. Do not reuse
+an ID among fields included in the same child schema.
## Choosing Generated or Manual Serialization
@@ -205,6 +131,7 @@ field names, values, or construction need custom logic.
## Related Topics
+- [Struct Inheritance](inheritance.md)
- [Type Registration](type-registration.md)
- [External-Type Serialization](external-types.md)
- [Schema Metadata](schema-metadata.md)
diff --git a/docs/guide/dart/custom-serializers.md
b/docs/guide/dart/custom-serializers.md
index 14c677fde..c9714f60f 100644
--- a/docs/guide/dart/custom-serializers.md
+++ b/docs/guide/dart/custom-serializers.md
@@ -1,6 +1,6 @@
---
title: Manual Serializers
-sidebar_position: 10
+sidebar_position: 11
id: custom_serializers
license: |
Licensed to the Apache Software Foundation (ASF) under one or more
diff --git a/docs/guide/dart/external-types.md
b/docs/guide/dart/external-types.md
index 827c058e0..20540fad7 100644
--- a/docs/guide/dart/external-types.md
+++ b/docs/guide/dart/external-types.md
@@ -1,6 +1,6 @@
---
title: External-Type Serialization
-sidebar_position: 4
+sidebar_position: 5
id: external_types
license: |
Licensed to the Apache Software Foundation (ASF) under one or more
@@ -65,8 +65,9 @@ arguments, must exactly match an accessible getter on the
target.
The declaration's field list is the complete external schema. Fory does not
automatically add fields from the target, its superclass, or its mixins. You
may explicitly declare an accessible inherited target property just like any
-other schema field. `exposePrivateFields` applies only to ordinary Dart
-hierarchies and is invalid with `ForyStruct.target`.
+other schema field. `exposePrivateFields` and
+`ignoreInheritedPrivateFields` apply only to ordinary Dart hierarchies and are
+invalid with `ForyStruct.target`.
Public target fields count toward the graph-memory budget automatically, but
that accounting does not add them to the serialized schema. Use
@@ -314,6 +315,7 @@ setters.
## Related Topics
+- [Struct Inheritance](inheritance.md)
- [Code Generation](code-generation.md)
- [Type Registration](type-registration.md)
- [Schema Metadata](schema-metadata.md)
diff --git a/docs/guide/dart/grpc-support.md b/docs/guide/dart/grpc-support.md
index 58f77a2a1..c53530a59 100644
--- a/docs/guide/dart/grpc-support.md
+++ b/docs/guide/dart/grpc-support.md
@@ -1,6 +1,6 @@
---
title: gRPC Support
-sidebar_position: 13
+sidebar_position: 14
id: grpc_support
license: |
Licensed to the Apache Software Foundation (ASF) under one or more
diff --git a/docs/guide/dart/index.md b/docs/guide/dart/index.md
index 8097bc48e..2317e5aca 100644
--- a/docs/guide/dart/index.md
+++ b/docs/guide/dart/index.md
@@ -114,8 +114,8 @@ dart run build_runner build
An ordinary annotated class includes its concrete superclass and applied-mixin
storage. Public and same-library private inherited fields need no parent
-annotation. See [Code Generation](code-generation.md) for cross-library private
-fields and constructor requirements.
+annotation. See [Struct Inheritance](inheritance.md) for private fields,
+constructors, mixins, and field inclusion options.
## API Overview
@@ -125,6 +125,8 @@ fields and constructor requirements.
- `@ForyStruct()` — marks a class for code generation
- `@ForyStruct(exposePrivateFields: true)` — lets another library's generated
child serializer access private state owned by this library
+- `@ForyStruct(ignoreInheritedPrivateFields: true)` — omits all private
+ superclass and applied-mixin storage from this concrete child's schema
- `@ForyStruct(target: Type)` — generates an external structural serializer
- `@ForyField(...)` — per-field options and canonical `type:` overrides
- `@ListField(...)`, `@SetField(...)`, `@MapField(...)` — container sugar for
nested `type:` trees
@@ -140,6 +142,7 @@ fields and constructor requirements.
| [Configuration](configuration.md) | Fory options, compatible
mode, and safety limits |
| [Basic Serialization](basic-serialization.md) | `serialize`,
`deserialize`, generated registration, root graphs |
| [Code Generation](code-generation.md) | `@ForyStruct`, build
runner, and generated modules |
+| [Struct Inheritance](inheritance.md) | Superclasses, mixins,
private fields, and constructors |
| [External-Type Serialization](external-types.md) | Generated serializers for
classes owned by another package |
| [Xlang Serialization](xlang-serialization.md) | Interoperability rules
and field alignment |
| [Schema Metadata](schema-metadata.md) | `@ForyField`, field IDs,
nullability, references, polymorphism |
diff --git a/docs/guide/dart/inheritance.md b/docs/guide/dart/inheritance.md
new file mode 100644
index 000000000..4ca58612d
--- /dev/null
+++ b/docs/guide/dart/inheritance.md
@@ -0,0 +1,211 @@
+---
+title: Struct Inheritance
+sidebar_position: 4
+id: inheritance
+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.
+---
+
+Ordinary Dart `@ForyStruct()` classes serialize one flattened view of their
+concrete superclass and applied-mixin storage. The generated child schema does
+not nest or invoke a parent serializer.
+
+## Public Fields
+
+Public inherited fields need no annotation on the parent:
+
+```dart
+class MessageBase {
+ int sequence = 0;
+}
+
+@ForyStruct()
+class TextMessage extends MessageBase {
+ TextMessage();
+
+ String text = '';
+}
+```
+
+The generated `TextMessage` schema contains both `sequence` and `text`.
+Interfaces, abstract getters, static fields, and mixin `on` constraints do not
+add storage.
+
+## Field Inclusion
+
+Fory first discovers the complete concrete superclass and applied-mixin
+storage chain. It applies declaration-owned field omission first, followed by
+the concrete-child option:
+
+| Configuration | Scope
|
+| ------------------------------------------------- |
----------------------------------------------------------------------------------------------------
|
+| `@ForyField(ignore: true)` | Omits that declaring
field from every child schema
|
+| `@ForyStruct(ignoreInheritedPrivateFields: true)` | Omits every private
field declared by an ancestor or applied mixin from this concrete child's
schema |
+
+Every remaining field must have a supported type, an unambiguous access path,
+and a valid reconstruction path. Fory reports a generation error instead of
+silently dropping unresolved state.
+
+Both omission options are applied during code generation. They do not add a
+runtime flag, branch, or parent serializer.
+
+## Ignoring Inherited Private Fields
+
+`ignoreInheritedPrivateFields` defaults to `false`. Set it on a concrete child
+when that child's wire schema intentionally excludes all private ancestor
+state:
+
+```dart
+class FrameworkBase {
+ String _cache = '';
+ String publicLabel = '';
+}
+
+@ForyStruct(ignoreInheritedPrivateFields: true)
+class PublicMessage extends FrameworkBase {
+ PublicMessage();
+
+ String _localState = '';
+ String text = '';
+}
+```
+
+The `PublicMessage` schema contains `_localState`, `text`, and `publicLabel`.
+It does not contain `_cache`.
+
+The option has the following exact scope:
+
+- It applies to private fields declared by direct or transitive superclasses
+ and applied mixins.
+- It treats same-library and cross-library private fields identically.
+- It never omits a private field declared directly by the annotated child.
+- It never omits an inherited public field.
+- It belongs only to the annotated concrete child. A parent annotation does
+ not change a child's setting.
+- It filters matching fields before private access is resolved. An omitted
+ field does not require an access companion, even when one exists.
+- It is invalid on `ForyStruct.target` declarations and provider-only abstract,
+ open-generic, or mixin declarations.
+
+A concrete class may set both `exposePrivateFields: true` and
+`ignoreInheritedPrivateFields: true`. Its own serializer omits its private
+ancestor fields, while its generated access companion remains available to
+other child libraries.
+
+## Including Cross-Library Private Fields
+
+With the default `ignoreInheritedPrivateFields: false`, private fields declared
+in another Dart library remain part of the child schema. The declaring library
+must expose them through a public hierarchy boundary:
+
+```dart
+// package:model_owner/base.dart
+import 'package:fory/fory.dart';
+
+part 'base.fory.dart';
+
+@ForyStruct(exposePrivateFields: true)
+abstract class AccountBase {
+ String _tenant = '';
+
+ String get tenant => _tenant;
+}
+```
+
+The consumer uses the normal annotation:
+
+```dart
+// lib/account.dart
+import 'package:fory/fory.dart';
+import 'package:model_owner/base.dart';
+
+part 'account.fory.dart';
+
+@ForyStruct()
+class Account extends AccountBase {
+ Account();
+}
+```
+
+Generate and publish `base.fory.dart` before generating a dependent consumer.
+A direct import or barrel export must expose both the public boundary and its
+generated `$AccountBaseForyFieldAccess` companion. If private fields come from
+several libraries, each declaring library needs its own public boundary and
+companion.
+
+Private inherited fields declared in the same Dart library as the child need
+no parent annotation or companion.
+
+## Constructors and Final Fields
+
+Every included `final` or `late final` field must receive its decoded value
+unchanged through the selected concrete-child generative constructor. Fory can
+follow initializing formals, super formals, redirects, and direct constructor
+initializers. A parameter with the same name is not sufficient proof if the
+value is ignored or transformed.
+
+Filtering a private field does not let Fory invent constructor inputs. If a
+required child constructor parameter no longer has a serialized field source,
+generation fails. Use a reconstructing constructor, declaration-owned
+`@ForyField(ignore: true)` where appropriate, or a manual serializer.
+
+## Mixins, Generics, and Field IDs
+
+Applied mixin storage is flattened like superclass storage. Generic field types
+are specialized for the concrete child before schema metadata is generated.
+All included child, superclass, and mixin fields share one field-ID namespace
+and one canonical ordering.
+
+Field hiding is rejected when it prevents generated access from reaching an
+included physical storage slot. Omitting private ancestor storage does not
+relax validation for retained public or child-declared fields.
+
+## References and Graph Memory
+
+Included inherited `ref: true` fields and nested container reference metadata
+use the same reference behavior as equivalent fields declared directly on the
+child. Omitted fields do not enter generated reference analysis. Inheritance
+does not add a reference mode or parent-level reference state.
+
+Physical inherited storage still contributes to shallow graph-memory
+accounting when omitted, matching `@ForyField(ignore: true)` behavior.
+
+## External Types
+
+`ForyStruct.target` declarations retain their explicit field list. Fory does
+not scan an external target hierarchy automatically, and neither
+`exposePrivateFields` nor `ignoreInheritedPrivateFields` is valid with
+`target`.
+
+An external declaration may explicitly list an accessible property inherited
+by its target. See [External-Type Serialization](external-types.md).
+
+## Regeneration and Compatibility
+
+Regenerate affected `.fory.dart` files after changing hierarchy storage,
+`exposePrivateFields`, or `ignoreInheritedPrivateFields`.
+
+Changing `ignoreInheritedPrivateFields` changes the generated field set.
+Compatible mode uses its normal missing-field and unknown-field behavior.
+Fixed-schema peers must update together.
+
+## Related Topics
+
+- [Code Generation](code-generation.md)
+- [Schema Metadata](schema-metadata.md)
+- [Schema Evolution](schema-evolution.md)
+- [Type Registration](type-registration.md)
+- [Troubleshooting](troubleshooting.md)
diff --git a/docs/guide/dart/schema-evolution.md
b/docs/guide/dart/schema-evolution.md
index 741bf9cef..123fc9315 100644
--- a/docs/guide/dart/schema-evolution.md
+++ b/docs/guide/dart/schema-evolution.md
@@ -1,6 +1,6 @@
---
title: Schema Evolution
-sidebar_position: 9
+sidebar_position: 10
id: schema_evolution
license: |
Licensed to the Apache Software Foundation (ASF) under one or more
@@ -62,10 +62,9 @@ class UserProfile {
If you add field IDs after payloads are already in production, existing stored
messages won't have them and evolution won't work correctly.
-For an ordinary inherited struct, the concrete child's schema contains every
-non-ignored field from its superclass and applied-mixin storage chain. Assign
-IDs across that complete flattened hierarchy; an ID used by a parent or mixin
-cannot be reused by the child.
+For an ordinary inherited struct, assign IDs across every field included in
+the concrete child's flattened schema. An ID used by an included parent or
+mixin field cannot be reused by the child.
For an [external structural serializer](external-types.md), the local
serializer declaration supplies the evolving schema and each declaration field
@@ -113,20 +112,23 @@ final fory = Fory(compatible: false);
## Regenerating Inherited Schemas
Regenerate every affected `.fory.dart` part after adding inherited storage,
-changing a superclass or mixin, or changing `exposePrivateFields`. Generate a
-dependency package's provider part before building its consumers.
+changing a superclass or mixin, changing `exposePrivateFields`, or changing
+`ignoreInheritedPrivateFields`. Generate a dependency package's provider part
+before building consumers that include its private fields.
-Older Dart generated code did not include ordinary inherited fields. After
-regeneration, compatible schemas use their normal missing-field and
-unknown-field behavior. Fixed schemas written without the inherited fields are
-not compatible with the corrected flattened schema; Fory does not add a
-special legacy reader for those payloads.
+Enabling `ignoreInheritedPrivateFields` removes every private ancestor and
+applied-mixin field from that concrete child's generated schema. Disabling it
+adds those fields back and may require provider companions. Compatible schemas
+use their normal missing-field and unknown-field behavior. Fixed-schema peers
+must change together because the resulting field list is different. A parent
+annotation does not propagate this setting to children.
-This migration changes generated field discovery only. It does not change the
-runtime reference protocol.
+This option changes generated field selection only. It does not change the
+runtime reference protocol or add a compatibility reader.
## Related Topics
+- [Struct Inheritance](inheritance.md)
- [Configuration](configuration.md)
- [External-Type Serialization](external-types.md)
- [Schema Metadata](schema-metadata.md)
diff --git a/docs/guide/dart/schema-metadata.md
b/docs/guide/dart/schema-metadata.md
index 61f93c522..e874fbb05 100644
--- a/docs/guide/dart/schema-metadata.md
+++ b/docs/guide/dart/schema-metadata.md
@@ -1,6 +1,6 @@
---
title: Schema Metadata
-sidebar_position: 6
+sidebar_position: 7
id: schema_metadata
license: |
Licensed to the Apache Software Foundation (ASF) under one or more
@@ -23,7 +23,8 @@ Add `@ForyField(...)` to a field inside a `@ForyStruct()`
class to change how th
For ordinary inheritance, metadata stays with the storage declaration and is
applied when any concrete annotated child discovers that field. A child
-redeclaration does not replace or merge the ancestor field's metadata.
+redeclaration does not replace or merge the ancestor field's metadata. See
+[Struct Inheritance](inheritance.md) for inherited-field inclusion rules.
The same annotations apply to fields in an
[external structural serializer declaration](external-types.md).
@@ -43,10 +44,14 @@ The same annotations apply to fields in an
## `ignore`
Exclude the declaring field from serialization entirely. This is the only
-supported way to omit ordinary instance storage, including inherited storage.
-Useful examples include cached, computed, or UI-only values that should not
-land in a persisted or transmitted message. The field still contributes to
-graph-memory accounting; because it has no wire representation, do not combine
+per-field, declaration-owned omission and applies to every concrete child that
+discovers the field. Useful examples include cached, computed, or UI-only
+values that should not land in a persisted or transmitted message.
+
+For child-specific omission of all private ancestor fields, see
+[`ignoreInheritedPrivateFields`](inheritance.md#ignoring-inherited-private-fields).
+Omitted physical storage still contributes to shallow graph-memory accounting.
+Because a declaration-ignored field has no wire representation, do not combine
`ignore` with other `ForyField` options.
```dart
@@ -66,7 +71,8 @@ String name = '';
Once a payload is shared across services, never reuse an `id` for a different
field.
An ordinary child has one flattened field namespace. IDs must therefore be
-unique across its child, superclass, and applied-mixin declarations.
+unique across all fields included from its child, superclass, and
+applied-mixin declarations.
## `nullable`
@@ -90,9 +96,9 @@ List<Object?> sharedNodes = <Object?>[];
Note: scalar types like `int`, `double`, and `bool` never benefit from
reference tracking even if `ref: true` is set.
-An inherited `ref` annotation behaves exactly like the same annotation on a
-field declared directly by the concrete child. Inheritance does not introduce
-another reference-tracking mode or owner.
+An included inherited `ref` annotation behaves exactly like the same
+annotation on a field declared directly by the concrete child. See
+[Struct Inheritance](inheritance.md#references-and-graph-memory).
## `dynamic`
@@ -159,6 +165,7 @@ When the same model is defined in multiple languages:
## Related Topics
+- [Struct Inheritance](inheritance.md)
- [Code Generation](code-generation.md)
- [External-Type Serialization](external-types.md)
- [Schema Evolution](schema-evolution.md)
diff --git a/docs/guide/dart/supported-types.md
b/docs/guide/dart/supported-types.md
index 6af5f9377..91b8a0818 100644
--- a/docs/guide/dart/supported-types.md
+++ b/docs/guide/dart/supported-types.md
@@ -1,6 +1,6 @@
---
title: Supported Types
-sidebar_position: 8
+sidebar_position: 9
id: supported_types
license: |
Licensed to the Apache Software Foundation (ASF) under one or more
@@ -130,22 +130,19 @@ class User {
}
```
-Ordinary annotated classes may extend classes and apply mixins. Fory includes
-every concrete instance storage field from that hierarchy in one child schema,
-including inherited generic fields after specialization. Public fields and
-private fields in the child's Dart library are accessed directly.
-Cross-library private storage is supported only when its declaring library
-provides a public boundary annotated with
-`@ForyStruct(exposePrivateFields: true)`.
+Ordinary annotated classes may extend classes and apply mixins. Fory discovers
+every concrete instance storage field from that hierarchy, including inherited
+generic fields after specialization, then builds one child schema. See
+[Struct Inheritance](inheritance.md) for private-field access and omission.
Abstract getters, interfaces, static members, and other declarations without
-instance storage are not fields. A real non-ignored storage field must have a
-supported type, an unambiguous access path, and a valid reconstruction path;
-otherwise generation fails. In particular, each `final` or `late final` field
-must receive the decoded value unchanged through the concrete child's
-constructor chain.
+instance storage are not fields. Every field that remains after explicit
+omission must have a supported type, an unambiguous access path, and a valid
+reconstruction path; otherwise generation fails. In particular, each included
+`final` or `late final` field must receive the decoded value unchanged through
+the concrete child's constructor chain.
-See [Code Generation](code-generation.md).
+See [Code Generation](code-generation.md) for generator setup.
Classes owned by another library can use an
[external structural serializer](external-types.md) when their public fields
@@ -174,6 +171,7 @@ width is one of the most common cross-language bugs.
## Related Topics
+- [Struct Inheritance](inheritance.md)
- [Schema Metadata](schema-metadata.md)
- [Xlang Serialization](xlang-serialization.md)
- [Schema Evolution](schema-evolution.md)
diff --git a/docs/guide/dart/troubleshooting.md
b/docs/guide/dart/troubleshooting.md
index 5e184fe8d..c99fee9b6 100644
--- a/docs/guide/dart/troubleshooting.md
+++ b/docs/guide/dart/troubleshooting.md
@@ -1,6 +1,6 @@
---
title: Troubleshooting
-sidebar_position: 12
+sidebar_position: 13
id: troubleshooting
license: |
Licensed to the Apache Software Foundation (ASF) under one or more
@@ -57,24 +57,19 @@ Ordinary hierarchy discovery includes private storage even
when it is declared
in another Dart library. Privacy affects generated access, not whether the
field exists in the schema.
-- A private field declared in the same library as the child needs no parent
- annotation.
-- For a private field declared in another library, annotate a public hierarchy
- boundary in that declaring library with
- `@ForyStruct(exposePrivateFields: true)`.
-- Import that provider directly, or use a barrel that re-exports both the
- public boundary and its generated `$<Boundary>ForyFieldAccess` companion.
-- If several libraries declare private fields in the hierarchy, each library
- must provide its own boundary.
-
-Putting `exposePrivateFields: true` only on the consumer child cannot authorize
-another library's private state. To omit a field intentionally, place
-`@ForyField(ignore: true)` on its declaration. Fory does not silently omit an
-inaccessible inherited field.
+Same-library private fields need no parent annotation. For a cross-library
+field, expose it from its declaring library with `exposePrivateFields: true`
and
+make the generated companion visible to the child. If the child intentionally
+excludes all private ancestor state, set
+`ignoreInheritedPrivateFields: true` on that child instead.
+
+See [Struct Inheritance](inheritance.md) for complete access, omission, and
+multi-library rules.
## Final inherited field cannot be reconstructed
-A non-ignored `final` or `late final` field must receive its decoded value
+A final or `late final` field that remains in the schema must receive its
+decoded value
unchanged from a parameter of the concrete child's selected generative
constructor. Fory can follow initializing formals, super formals, redirects,
and direct constructor initializers across the hierarchy.
@@ -82,15 +77,20 @@ and direct constructor initializers across the hierarchy.
A parameter with the same name and type is insufficient if it is unused or its
value is cast, transformed, or passed through a function. Forward the decoded
value directly to the exact field, mark the field declaration with
-`@ForyField(ignore: true)`, or use a manual serializer.
+`@ForyField(ignore: true)`, or use a manual serializer. If
+`ignoreInheritedPrivateFields` removes the only serialized source for a
+required constructor parameter, Fory still reports this error rather than
+inventing a value. See
+[Constructors and Final Fields](inheritance.md#constructors-and-final-fields).
## Inherited field is hidden
-A subclass field or accessor can hide an ancestor storage slot while both
-physical slots remain on the object. Fory rejects this shape instead of
+A subclass field or accessor can hide an included ancestor storage slot while
+both physical slots remain on the object. Fory rejects this shape instead of
choosing one slot and losing the other. Rename or remove the hiding member,
-ignore the ancestor field at its declaration when omission is intentional, or
-use a manual serializer.
+ignore the ancestor field at its declaration, or use a manual serializer. For
+private ancestor state, setting `ignoreInheritedPrivateFields: true` omits all
+private ancestor storage from that child schema.
## External target generation fails
@@ -216,6 +216,7 @@ separate protobuf service endpoint for generic protobuf
clients.
## Related Topics
+- [Struct Inheritance](inheritance.md)
- [Xlang Serialization](xlang-serialization.md)
- [Code Generation](code-generation.md)
- [Manual Serializers](custom-serializers.md)
diff --git a/docs/guide/dart/type-registration.md
b/docs/guide/dart/type-registration.md
index 0a2f6bcae..938f0a046 100644
--- a/docs/guide/dart/type-registration.md
+++ b/docs/guide/dart/type-registration.md
@@ -1,6 +1,6 @@
---
title: Type Registration
-sidebar_position: 7
+sidebar_position: 8
id: type_registration
license: |
Licensed to the Apache Software Foundation (ASF) under one or more
@@ -73,7 +73,8 @@ it contributes fields.
Register an independently annotated concrete parent only when values whose
runtime type is that parent are also serialized. A provider-only
`@ForyStruct(exposePrivateFields: true)` boundary supplies generated field
-access and has no registration entry of its own.
+access and has no registration entry of its own. See
+[Struct Inheritance](inheritance.md) for boundary and child-schema options.
External structural serializers use the same generated registration API. Pass
the external target type:
@@ -118,6 +119,7 @@ The same numeric ID or name must be used in every peer that
reads or writes the
## Related Topics
+- [Struct Inheritance](inheritance.md)
- [Code Generation](code-generation.md)
- [External-Type Serialization](external-types.md)
- [Xlang Serialization](xlang-serialization.md)
diff --git a/docs/guide/dart/web-platform-support.md
b/docs/guide/dart/web-platform-support.md
index 0d0190d27..ece282921 100644
--- a/docs/guide/dart/web-platform-support.md
+++ b/docs/guide/dart/web-platform-support.md
@@ -1,6 +1,6 @@
---
title: Web Platform Support
-sidebar_position: 11
+sidebar_position: 12
id: web_platform_support
license: |
Licensed to the Apache Software Foundation (ASF) under one or more
@@ -84,12 +84,10 @@ The registration call is the same on VM/AOT, Flutter, and
web. Manual
serializers use `registerSerializer(...)`; generated structs use the generated
`register` wrapper.
-Inherited fields use the same statically generated code on every platform.
-Public and same-library private fields are accessed directly. A provider
-library annotated with `@ForyStruct(exposePrivateFields: true)` emits typed
-static access methods for its own private state; it does not use mirrors,
-callbacks, runtime member lookup, or a parent serializer. Generate a dependency
-provider before compiling its consumer.
+Included inherited fields use the same statically generated code on every
+platform. `ignoreInheritedPrivateFields` is applied during generation and adds
+no runtime branch. See [Struct Inheritance](inheritance.md) for cross-library
+provider setup.
## 64-Bit Integer Rules
@@ -234,6 +232,7 @@ JS-safe non-negative range.
## Related Topics
+- [Struct Inheritance](inheritance.md)
- [Supported Types](supported-types.md)
- [Schema Metadata](schema-metadata.md)
- [Code Generation](code-generation.md)
diff --git a/docs/guide/dart/xlang-serialization.md
b/docs/guide/dart/xlang-serialization.md
index 2bea4ca01..d66475a7f 100644
--- a/docs/guide/dart/xlang-serialization.md
+++ b/docs/guide/dart/xlang-serialization.md
@@ -1,6 +1,6 @@
---
title: Xlang Serialization
-sidebar_position: 5
+sidebar_position: 6
id: xlang_serialization
license: |
Licensed to the Apache Software Foundation (ASF) under one or more
@@ -194,12 +194,14 @@ Fory matches fields by name or by stable field ID. For
robust cross-language int
For an ordinary Dart class, Fory flattens concrete superclass and applied-mixin
storage into the annotated child's one struct schema. Parent and child fields
share one field-ID namespace and one canonical ordering, so the peer language
-should define the equivalent flat field set. A parent is not encoded as a
-nested object.
-
-Inherited `@ForyField(ref: true)` and nested container reference metadata use
-the same reference behavior as fields declared directly on the child.
-Inheritance does not change xlang reference framing or add parent-level
+should define the equivalent included flat field set. Fields omitted by
+`@ForyField(ignore: true)` or the concrete child's
+`ignoreInheritedPrivateFields` option are absent from that peer schema. A
+parent is not encoded as a nested object.
+
+Included inherited `@ForyField(ref: true)` and nested container reference
+metadata use the same reference behavior as fields declared directly on the
+child. Inheritance does not change xlang reference framing or add parent-level
reference state.
## Type Mapping Notes for Dart
@@ -253,6 +255,7 @@ dart test
## Related Topics
+- [Struct Inheritance](inheritance.md)
- [Type Registration](type-registration.md)
- [External-Type Serialization](external-types.md)
- [Schema Evolution](schema-evolution.md)
diff --git a/docs/specification/xlang_implementation_guide.md
b/docs/specification/xlang_implementation_guide.md
index 8778a3741..4bc8d414d 100644
--- a/docs/specification/xlang_implementation_guide.md
+++ b/docs/specification/xlang_implementation_guide.md
@@ -1412,17 +1412,22 @@ Every discovered storage field follows one pipeline:
```text
complete hierarchy discovery
-> declaration-owned @ForyField(ignore: true)
+ -> concrete-child ignoreInheritedPrivateFields policy
-> 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.
+`@ForyField(ignore: true)` is the declaration-owned, per-field omission.
+After that check, a concrete child with
+`ignoreInheritedPrivateFields: true` removes every private field declared by a
+superclass or applied mixin, including same-library, cross-library, direct, and
+transitive ancestors. It does not remove child-declared private fields or
+inherited public fields. Both omission forms bypass substitution, access,
+construction, wire identity, reference analysis, and codec work while their
+physical slots remain in the concrete object's shallow graph-memory field
+count. Any unresolved field that remains included is a generation error.
Ownership is fixed:
@@ -1430,6 +1435,7 @@ Ownership is fixed:
| -------------------------------- |
------------------------------------------------ |
| Field identity and annotations | Declaring storage field
|
| Hierarchy discovery/substitution | Concrete-child generator
|
+| Inherited-private omission | Concrete annotated child
|
| 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 |
@@ -1437,14 +1443,22 @@ Ownership is fixed:
| 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
+The concrete-child omission option defaults to `false`, is not inherited from
+ancestor annotations, and is valid only on an ordinary concrete declaration
+that owns a flattened schema. It is invalid on external target declarations
+and provider-only abstract, open-generic, or mixin boundaries. It is applied
+after complete storage discovery and before generic substitution or access
+resolution, so a matching field needs no direct access or companion even when
+a companion exists.
+
+For fields that remain included, 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 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.
+field's declaring library. `exposePrivateFields` 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,
@@ -1459,7 +1473,10 @@ 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.
+state. Companion generation is independent of every consumer child's
+`ignoreInheritedPrivateFields` value. A concrete boundary may enable both
+options: its own serializer applies the omission, while its provider companion
+continues to expose the declaring library's eligible private storage.
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
@@ -1469,7 +1486,7 @@ 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
+Every included `final` or `late final` field must be initialized by a
statically proven identity flow:
```text
@@ -1484,8 +1501,8 @@ 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.
+included 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
@@ -1493,7 +1510,10 @@ 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.
+matched by resolved storage-field identity rather than field-name strings. If
+omission removes the only serialized source for a required parameter,
+generation fails; the generator must not invent a value or relax identity
+proof.
The concrete child owns one `GeneratedStructSchema`, one canonical field sort,
one serializer and descriptor cache, one reconstruction, one reference
@@ -1502,13 +1522,14 @@ 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.
+Included direct and inherited fields feed one normalized list into the
+existing recursive reference analysis and `needsRootRef` calculation.
+Included inherited `ref: true` and nested container metadata behave like
+equivalent direct child fields; omitted fields do not enter that list.
+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
@@ -1522,9 +1543,10 @@ 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.
+flat fields, policy filtering emits no runtime check, and included
+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:
@@ -1540,21 +1562,23 @@ 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
+`@ForyField(ignore: true)` on the field declaration, setting
+`ignoreInheritedPrivateFields: true` on the concrete child when all private
+ancestor state should be omitted, or using a manual serializer. Diagnostics
+must state that hierarchy discovery is independent of cross-library access.
+
+Changes to hierarchy storage, exposure boundaries, or
+`ignoreInheritedPrivateFields` require regeneration of every affected
+`.fory.dart` file. Compatible mode uses normal missing/unknown-field handling;
+fixed-schema peers must change together. Implementations must not add a
+special legacy reader, retain an alternative path limited to child
+declarations, bind constructors only by name, use a late-final setter path,
+fall back to another access model, or delegate to a parent serializer.
+
+Acceptance requires that every hierarchy storage slot is either omitted by its
+declaration, omitted by the concrete-child inherited-private policy, or
+represented exactly once with a valid type, access path, wire identity, and
+reconstruction path. Equivalent included 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.
@@ -1583,7 +1607,8 @@ 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.
+`exposePrivateFields` and `ignoreInheritedPrivateFields` are 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,
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]