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 5e7ba0cdfdab3b0a6fd51e3ee77e1edcce190944
Author: chaokunyang <[email protected]>
AuthorDate: Tue Aug 4 05:58:24 2026 +0000

    🔄 synced local 'docs/specification/' with remote 'docs/specification/'
---
 docs/specification/xlang_implementation_guide.md | 49 ++++++++++++------------
 docs/specification/xlang_serialization_spec.md   | 12 +++---
 docs/specification/xlang_type_mapping.md         |  4 +-
 3 files changed, 32 insertions(+), 33 deletions(-)

diff --git a/docs/specification/xlang_implementation_guide.md 
b/docs/specification/xlang_implementation_guide.md
index e749d37da4..9d60dc4e3d 100644
--- a/docs/specification/xlang_implementation_guide.md
+++ b/docs/specification/xlang_implementation_guide.md
@@ -21,12 +21,11 @@ license: |
 
 ## Overview
 
-This guide describes the current xlang implementation ownership model used by
-the xlang runtimes.
+This guide describes the current xlang ownership model used by Fory 
implementations.
 
 The wire format is defined by
 [Xlang Serialization Spec](xlang_serialization_spec.md). This document is about
-service boundaries, operation flow, and internal ownership. New language 
implementations do not
+service boundaries, operation flow, and internal ownership. New Fory 
implementations do not
 need the same class names, but they should preserve the same control flow:
 
 - root operations stay on the `Fory` facade
@@ -202,7 +201,7 @@ The ownership split is:
 
 - the serializer provider owns static serialization behavior and, for an
   external structural serializer, the local schema declaration
-- the target owns runtime values, host type identity, storage size, and
+- the target owns values of the target type, host type identity, storage size, 
and
   dynamic downcasts
 - the value serializer owns target bodies, complete root values, defaults,
   value type identity, root/dynamic type information, and value-level
@@ -298,8 +297,8 @@ internal static class StatusSerializer
 ```
 
 External declarations are compile-time generator input only. They are never
-instantiated, reflected over by the runtime, registered, reference-published,
-or used as wire identities. Runtime type positions, construction, `TypeInfo`,
+instantiated, reflected over at runtime, registered, reference-published,
+or used as wire identities. All serializer type positions, construction, 
`TypeInfo`,
 metadata, reference publication, generated factory keys, roots, fields,
 dynamic values, and carriers use the target type.
 
@@ -349,7 +348,7 @@ C# carrier composition remains target-based. The resolver 
recursively binds
 `Dictionary<TKey, TValue>`, `SortedDictionary<TKey, TValue>`,
 `SortedList<TKey, TValue>`, `ConcurrentDictionary<TKey, TValue>`, and
 `NullableKeyDictionary<TKey, TValue>`. Ordinary, external, and custom
-serializers use the same carrier bodies. There is no hierarchy runtime lookup,
+serializers use the same carrier bodies. There is no hierarchy lookup at 
runtime,
 provider object, callback, schema tree, per-element dispatch, or additional
 value allocation.
 
@@ -373,7 +372,7 @@ Rust represents immutable value-serializer properties with 
five associated
 constants on `Serializer`:
 
 - `IS_OPTIONAL` means the selected value shape carries Option semantics;
-- `IS_POLYMORPHIC` means its concrete target is selected from the runtime
+- `IS_POLYMORPHIC` means its concrete target is selected from the application
   value;
 - `IS_SHARED_REF` means it uses the existing shared-reference wire behavior;
 - `IS_WRAPPER` means it is a Fory-owned wrapper serializer without an
@@ -401,9 +400,9 @@ or forwards field framing without changing root or value 
composition.
 Serializer-provider identity is a host implementation detail and is never
 encoded. External structural serializers use the same STRUCT, ENUM, or UNION
 metadata and value format as an equivalent directly supported target. Custom
-serializers that are not the runtime's canonical implementation of an existing
+serializers that are not the Fory implementation's canonical serializer for an 
existing
 built-in use EXT or NAMED_EXT. Serializer-provider separation does not replace
-runtime-owned built-in mappings.
+implementation-owned built-in mappings.
 
 Static generated fields and serializer-selected roots should dispatch directly
 to the serializer selected by their schema. A Rust field `with = S` selects the
@@ -830,9 +829,9 @@ custom serializer targeting one of the same Rust shapes 
also keeps it false
 because it owns an independent opaque EXT body. Private built-in registration
 validates only its expected internal type ID. These semantic checks use the
 existing serializer contracts and wire categories. Custom EXT registration is
-the only runtime consumer of `IS_WRAPPER`.
+the only consumer of `IS_WRAPPER`.
 
-Dynamic values should resolve by the concrete target identity. When a runtime
+Dynamic values should resolve by the concrete target identity. When a Fory 
implementation
 needs both directions, its serializer-provider-to-type-info and 
target-to-type-info
 indexes must point to the same immutable registration metadata and serializer
 harness rather than creating parallel metadata or serialization paths.
@@ -1076,7 +1075,7 @@ This policy avoids three inefficient implementation 
shapes:
 
 Scratch buffers remain appropriate when the target representation is not a
 direct byte target, such as string transcoding, compression, byte-order
-conversion that is not performed in place, bit-packed values, or runtimes whose
+conversion that is not performed in place, bit-packed values, or 
implementations whose
 stream API cannot read into a caller-provided target.
 
 For fixed-width primitive arrays, the final result must not become visible to
@@ -1104,8 +1103,8 @@ memory budget before allocation or size hinting. The 
budget state belongs to
 state. Root facades set or reset the per-operation budget only; they must not
 pre-reserve root type or root self bytes. `maxGraphMemoryBytes` defaults to a
 fixed `128 MiB`; positive configuration overrides the default; explicit
-non-positive configuration is invalid and must be rejected when the runtime is
-created. Do not derive this budget from root input size, and do not add dynamic
+non-positive configuration is invalid and must be rejected during 
configuration or Fory instance
+creation. Do not derive this budget from root input size, and do not add 
dynamic
 stream bytes-read accounting for this budget.
 Because the budget is fixed per root, read state should not mirror the
 configured maximum into a second active-limit field. Use the existing
@@ -1136,13 +1135,13 @@ reserve the heap or boxed storage they allocate. Value 
serializers, including
 root and generated struct/product read paths, do not reserve their own self
 storage. Struct/record/POJO/tuple, compatible, generated, and dynamic object
 owners reserve a nonzero shallow self cost plus shallow field storage only in
-reference-object runtimes or dynamic/boxed materialization paths.
+reference-object implementations or dynamic/boxed materialization paths.
 Parents must not recursively include child object, collection, map, string,
 binary, or primitive dense-array contents. Skip enum/union as separate owners 
and
 skip dedicated string, binary, primitive scalar, primitive array, and primitive
 dense-array leaf owners, but do not skip general inline-value containers such 
as
 vectors or lists of value objects. If reference slot size is not cheap or
-reliable to query, use a 4-byte reference slot. Native runtimes may use
+reliable to query, use a 4-byte reference slot. Native-code implementations 
may use
 conservative lower-bound estimates instead of guessing non-portable object,
 container, allocator, table, node, entry, or debug-layout details. Reject
 arithmetic overflow before budget comparison or allocation, and keep the
@@ -1150,7 +1149,7 @@ existing `checkReadableBytes` proof before backing
 allocation or capacity reservation.
 Skipped leaf owners must still be gated by remaining input bytes. If unread
 bytes are insufficient for a string, binary value, primitive scalar, primitive
-array, or primitive dense array, the runtime must not read or create that leaf
+array, or primitive dense array, the reader must not read or create that leaf
 value.
 
 For TypeDef or TypeMeta bodies, first prove that the encoded metadata body 
bytes
@@ -1197,7 +1196,7 @@ The exact-local candidate must be derived inside the 
metadata owner path from
 the decoded metadata identity: `userTypeId` for id-registered metadata, or
 `(namespace, typeName)` for name-registered metadata. Do not thread extra
 expected-type parameters through read callers solely for this check. This rule
-applies to every runtime. Java and Python may lazy-build the local encoded
+applies to every Fory implementation. Java and Python may lazy-build the local 
encoded
 metadata only after this identity lookup selects a local class and the existing
 class, registration, and deserialization-policy checks for that class have run.
 
@@ -1270,7 +1269,7 @@ When `Config.compatible` is enabled and the struct is 
marked evolving:
   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
+  and may remain rejected when the implementation cannot materialize it without
   generic/reference paths.
 
 When `compatible` is disabled and `checkStructVersion` is enabled:
@@ -1339,7 +1338,7 @@ In C#, the enum's underlying numeric value is the xlang 
tag. Java peers for
 sparse C# enums must declare matching `@ForyEnumId` values instead of relying
 on declaration ordinals.
 
-Other language implementations should preserve the same wire rule even if the 
configuration or
+Other Fory implementations should preserve the same wire rule even if the 
configuration or
 annotation surface differs.
 
 A Rust data-carrying enum is an xlang union only when each known variant is 
unit
@@ -1386,7 +1385,7 @@ registration API family.
 
 Ordinary Dart `ForyStruct` inheritance is a code-generation-time field
 discovery, normalization, access, construction, and flattening change. It does
-not redesign the runtime reference protocol.
+not redesign the reference protocol.
 
 For a concrete annotated child, the generator walks the instantiated
 superclass and applied-mixin storage chain rather than only the child's direct
@@ -1518,7 +1517,7 @@ proof.
 The concrete child owns one `GeneratedStructSchema`, one canonical field sort,
 one serializer and descriptor cache, one reconstruction, one reference
 publication path, and one graph-memory owner. Parent serializers are neither
-nested nor invoked, and parent runtime registration is not required. A
+nested nor invoked, and parent type registration is not required. A
 separately annotated concrete parent has its own independently flattened
 schema only for values of that exact type.
 
@@ -1591,7 +1590,7 @@ registration identity.
 
 The generator must analyze ordinary and external structs through one struct
 model and one emitter. Private generated symbol names come from the declaration
-name. Every runtime type position uses the target type: `Serializer<Target>`,
+name. Every generated serializer type position uses the target type: 
`Serializer<Target>`,
 `GeneratedStructSchema<Target>`, read and write signatures, constructor calls,
 schema `type`, and generated-module dispatch.
 
@@ -1626,7 +1625,7 @@ paths remain the only runtime paths.
 Registration is keyed by `Target` through the generated module and the existing
 generated registration API. Direct roots, generated fields, dynamic values,
 and recursive collection/map children resolve the same target registration.
-Dart root collections retain their existing untyped outer runtime shapes.
+Dart root collections retain their existing untyped outer shapes.
 
 ## Directory Layout
 
diff --git a/docs/specification/xlang_serialization_spec.md 
b/docs/specification/xlang_serialization_spec.md
index 6ce845417c..9af0f9d2c2 100644
--- a/docs/specification/xlang_serialization_spec.md
+++ b/docs/specification/xlang_serialization_spec.md
@@ -145,9 +145,9 @@ wire identity.
   without adding a wire identity or repeated registration lookup; any
   containing schema metadata owns the prior identity validation. The carrier
   serializer itself remains unregistered in every case.
-- A custom serializer that is not the runtime's
+- A custom serializer that is not the Fory implementation's
   canonical implementation of an existing built-in MUST use the existing EXT
-  or NAMED_EXT form. This serializer-provider separation does not replace 
runtime-owned
+  or NAMED_EXT form. This serializer-provider separation does not replace 
implementation-owned
   built-in mappings.
 - Serializer-provider, external structural serializer, or generated-code type 
names MUST
   NOT change the encoded type ID, registered user ID or name, TypeDef, field 
order, schema hash,
@@ -261,7 +261,7 @@ 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. Reference-tracked list-element framing is separate from
-nullable element schema. A runtime that cannot materialize ref-tracked list
+nullable element schema. A Fory implementation 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
@@ -1597,7 +1597,7 @@ Date represents a date without timezone. It is encoded as:
 - `days` (varint64): signed count of days since the Unix epoch (`1970-01-01`)
 
 The value is reconstructed as `LocalDate.ofEpochDay(days)` or the equivalent 
calendar-date constructor in
-the target language implementation.
+the target Fory implementation.
 
 This `varint64` encoding applies to xlang serialization only. Native, 
language-specific local-date
 encodings are unchanged.
@@ -1850,7 +1850,7 @@ A union payload is:
 ```
 
 `case_id` is the union alternative tag number.
-Runtime APIs MAY expose zero-based ordinal indexes for generic union carriers;
+Fory APIs MAY expose zero-based ordinal indexes for generic union carriers;
 those ordinals are valid wire `case_id` values when they are the schema's
 alternative IDs.
 
@@ -1875,7 +1875,7 @@ numeric type IDs, the type ID byte is the complete value 
type metadata and the
 payload writer MAY use the stored wire type ID to preserve fixed, variable, or
 tagged integer encodings when the decoded value has the expected concrete 
value type.
 These scalar numeric payloads are not reference-tracked, so their ref metadata
-is `NotNullValue`. Otherwise it MUST fall back to the language implementation's
+is `NotNullValue`. Otherwise it MUST fall back to the Fory implementation's
 ordinary polymorphic Any-value writer. Unknown carriers are 
implementation-provided
 forward-compatibility containers, not entries in the local schema case table;
 schema-defined union cases MAY use `0..N`. When an unknown carrier is written
diff --git a/docs/specification/xlang_type_mapping.md 
b/docs/specification/xlang_type_mapping.md
index 800360f215..aa89ae8a85 100644
--- a/docs/specification/xlang_type_mapping.md
+++ b/docs/specification/xlang_type_mapping.md
@@ -115,7 +115,7 @@ Notes:
 - C# external-type serialization maps a third-party class/struct or enum
   through a local
   `ForyStruct(Target = typeof(...))` or
-  `ForyEnum(Target = typeof(...))` serializer declaration. The runtime target
+  `ForyEnum(Target = typeof(...))` serializer declaration. The target type
   still uses the C# mapping shown above; declaration ownership is not a wire
   distinction.
 - Python `pyfory.Float16` and `pyfory.BFloat16` are reserved annotation 
markers; scalar values deserialize as native Python `float`.
@@ -155,7 +155,7 @@ Notes:
   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.
+  `array<T>` and the Fory implementation 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


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

Reply via email to