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 79507744f2cc8ad91a4e39140ddbfd8df4e7a063 Author: chaokunyang <[email protected]> AuthorDate: Sun Jun 7 17:33:56 2026 +0000 🔄 synced local 'docs/specification/' with remote 'docs/specification/' --- docs/specification/xlang_implementation_guide.md | 36 ++++++++++++++++++--- docs/specification/xlang_serialization_spec.md | 40 +++++++++++++++++++----- docs/specification/xlang_type_mapping.md | 13 ++++++-- 3 files changed, 75 insertions(+), 14 deletions(-) diff --git a/docs/specification/xlang_implementation_guide.md b/docs/specification/xlang_implementation_guide.md index 60ed45ef63..9ad0ec1189 100644 --- a/docs/specification/xlang_implementation_guide.md +++ b/docs/specification/xlang_implementation_guide.md @@ -306,8 +306,8 @@ In Dart that internal owner is `StructSerializer`. - caching compatible read layouts - skipping unknown compatible fields - passing compatible read layouts explicitly to generated serializers -- classifying matched compatible fields that require top-level scalar - conversion and routing those fields through cold conversion helpers +- classifying matched compatible fields as exact direct reads, compatible + conversions, or remote-only skips before generated dispatch When `Config.compatible` is enabled and the struct is marked evolving: @@ -316,9 +316,20 @@ When `Config.compatible` is enabled and the struct is marked evolving: - reads map incoming fields by identifier and skip unknown fields - generated serializers apply matched fields directly while preserving their own object construction and default-value rules +- exact matched field schemas use the same direct read shape as same-schema + reads and must not receive remote compatible metadata - matched scalar fields may use compatible scalar conversion only when the layout has classified a remote/local top-level scalar pair as lossless convertible and both field schemas have `trackingRef = false` +- compatible scalar conversion applies only to the immediate matched field. + Nested collection, array, map key, and map value schemas must not be accepted + by recursively applying scalar conversion to child schemas. +- direct top-level `list<T?>` to dense `array<T>` matched fields must be + classified as compatible when element domains match; the nullable element + schema bit alone is not a schema-pair rejection. Actual null element payloads + fail in the dense-array reader. Ref-tracked list-element framing is separate + and may remain rejected when the runtime cannot materialize it without + generic/reference paths. When `compatible` is disabled and `checkStructVersion` is enabled: @@ -334,8 +345,25 @@ decision and value adaptation stay with the serializer-owned compatible field layout. Layout classification must reject top-level scalar conversions when either matched schema has `trackingRef = true` and must reject same scalar type pairs whose top-level `trackingRef` framing differs; converters must not add a -reference-table path for scalar mismatches. Same-schema readers with matching -reference and null/optional framing must keep direct scalar read paths without conversion branches or per-field conversion +reference-table path for scalar mismatches. Recursive schema comparison inside +containers must reject scalar mismatches instead of reusing the top-level scalar +conversion matrix. Generated serializers should consume the classified layout +decision directly: + +- source-generated serializers use the layout's matched-field dispatch key to + select exact direct field code, compatible conversion code, or skip code +- regenerated serializers may instead compile a remote-schema-specific + straight-line reader after classification, without a second outer matched-id + switch, when the generated source still has pure direct, pure conversion, and + explicit skip operations +- compatible scalar conversion cases must read the concrete remote wire scalar + selected by classification and compose only the required lossless conversion; + they must not call a generic runtime converter that redispatches by remote and + local scalar type IDs, field descriptors, field names, or schema eligibility + helpers + +Same-schema readers with matching reference and null/optional framing must keep +direct scalar read paths without conversion branches or per-field conversion objects. Same raw scalar types with different null/optional framing may still use the compatible nullable/optional composition path when both fields are not reference-tracked. diff --git a/docs/specification/xlang_serialization_spec.md b/docs/specification/xlang_serialization_spec.md index 27b8e19ee4..cf46904344 100644 --- a/docs/specification/xlang_serialization_spec.md +++ b/docs/specification/xlang_serialization_spec.md @@ -196,14 +196,31 @@ and `array<T>` as distinct kinds. The adaptation is limited to the immediate schema of the matched compatible field. It does not apply when `list<T>` or `array<T>` appears inside another field type, including collection elements, map keys or values, array elements, -union alternatives, or other generic/container positions. A peer `list<T>` -TypeDef element may be declared nullable or ref-tracked; that declaration alone -does not prevent a local matched `array<T>` field from reading the value. The -reader must decide from the collection payload. If the payload actually carries -a null element or reference-tracked element encoding that cannot be represented -as a dense array element value, the local `array<T>` field must raise a +union alternatives, or other generic/container positions. A peer `list<T?>` +TypeDef element schema is not immediate schema incompatibility for a local +matched `array<T>` field. Classification must accept the matched field when the +element domains match and the only element-schema difference is nullable +metadata. The reader must decide from the collection payload: if the payload +actually carries a null element, the local `array<T>` field must raise a compatible-read error. Null list elements must not be coerced to dense-array -default values. +default values. Reference-tracked list-element framing is separate from +nullable element schema. A runtime that cannot materialize ref-tracked list +elements into a dense array without generic/reference paths may reject that +field during compatible classification; if it accepts the field, reference +payloads that cannot be represented as dense array element values must fail +during read. + +The dense-array error rule applies to dense-array targets. A matched +`list<T?>` field read into a local `list<T?>` target must keep using list +semantics and preserve actual null elements; implementations must not route that +payload through a dense primitive-array materialization path that rejects nulls. + +In schema-compatible mode only, a matched struct/class field may read between +direct top-level `binary` and direct top-level `array<uint8>` schemas. This is a +byte-sequence adaptation only: it does not merge TypeDef/ClassDef type IDs, +schema fingerprints, dynamic root serialization, same-schema mode, or nested +collection/map/array/union/generic positions. `array<int8>` is not part of this +adapter. In schema-compatible mode only, a matched struct/class field may also read between direct top-level scalar schemas when the remote value can be represented @@ -329,6 +346,12 @@ action, an invalid payload value MUST be reported through the implementation's data-error path with enough context to identify the remote type, local type, and field when that path has the information. +Unknown-field skipping applies only when the remote field has no matching local +field identity. If a local field matches by tag ID or name but its schema is +outside the exact-read and compatible-adaptation rules, the reader MUST reject +the compatible layout instead of treating the field as missing, remote-only, or +skippable. + Users can also provide meta hints for fields of a type, or the type whole. Here is an example in java which use annotation to provide such information. @@ -1673,6 +1696,9 @@ MurmurHash3 x64_128 of the struct fingerprint string: - `LIST` / `SET`: `<type_id>,<ref>,<nullable>[<element_fingerprint>]` - `MAP`: `<type_id>,<ref>,<nullable>[<key_fingerprint>|<value_fingerprint>]` - Nested container element/key/value fingerprints include nested type ID, container shape, and effective integer encoding, but nested `nullable` and `ref` policy are always hashed as `0`. Only the root field `nullable` and `ref` bits participate in schema hash, because nested reads honor the wire null/ref flags directly. +- This schema-hash rule is only for same-schema mode without TypeDef metadata. It + does not permit compatible-mode matched-field classification to accept nested + nullability or reference-tracking mismatches. Field values are serialized in Fory order. Primitive fields are written as raw values (nullable primitives include a null flag). Non-primitive fields write ref/null flags as needed and then the diff --git a/docs/specification/xlang_type_mapping.md b/docs/specification/xlang_type_mapping.md index bb8d49785d..1e7976fa06 100644 --- a/docs/specification/xlang_type_mapping.md +++ b/docs/specification/xlang_type_mapping.md @@ -141,9 +141,16 @@ Notes: field, and a direct top-level `array<T>` field may be read as a direct top-level `list<T>` field, when `T` is one of the dense bool/numeric array domains. Integer list element encodings in the same signedness and width domain match the corresponding dense array element domain. The rule does - not apply inside nested collection, map, array, union, or generic positions. A peer `list<T>` - payload that declares nullable or ref-tracked elements must raise a compatible-read error when the - local matched field is `array<T>`. + not apply inside nested collection, map, array, union, or generic positions. A peer `list<T?>` + element schema is still a compatible schema match for a local `array<T>` field; if the actual + payload contains a null element, the dense-array reader raises a compatible-read error instead of + coercing the value. Reference-tracked list-element framing is separate from nullable element + schema and may be rejected during compatible field classification when the local matched field is + `array<T>` and the runtime cannot materialize it without generic/reference paths. +- `binary` and `array<uint8>` remain distinct schema kinds. In schema-compatible struct/class field + matching only, a direct top-level `binary` field may be read as a direct top-level `array<uint8>` + field and the reverse may be read as the same byte sequence. This rule does not apply inside + nested collection, map, array, union, or generic positions, and it does not include `array<int8>`. - The table above remains the canonical xlang schema mapping. Compatible readers may apply the scalar field adaptation rules defined by `xlang_serialization_spec.md` during schema-compatible struct/class field matching. Those rules do not change TypeDef metadata, dynamic root type --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
