feat: add container memory budget

.agents/docs-and-formatting.md

@@ -45,10 +45,9 @@ Load this file when changing documentation, public APIs, protocol specs, benchma
 - Python code, including `compiler/`, `benchmarks/`, `integration_tests/`, and `python/`:
   `python -m ruff format <changed-python-files>` and
   `python -m ruff check --fix <changed-python-files>`
-- JavaScript/TypeScript under `javascript/`: use the package's ESLint-owned formatting path
-  (`npm run lint -- --fix` when fixing style, `npm run lint -- --quiet` when checking). Do not run
-  Prettier on JavaScript or TypeScript files unless that package has an explicit Prettier config or
-  script; otherwise it creates unrelated formatting churn.
+- JavaScript/TypeScript under `javascript/`: use the package formatter scripts
+  (`npm run format` when fixing style, `npm run format-check` when checking). They run Prettier
+  before ESLint; do not use raw ESLint as the formatting gate.
 - Repo-wide format and lint sweep: `bash ci/format.sh --all`
 
 When code changes touch `compiler/` or `benchmarks/`, format those changed source files with the

.agents/languages/cpp.md

@@ -17,6 +17,29 @@ Load this file when changing `cpp/`, Cython build plumbing, or C++ xlang behavio
 - Do not redesign alias-based or low-level public type shapes to add convenience methods unless the user explicitly asks for that API change.
 - For cross-language feature ports, match protocol behavior but use idiomatic C++ ownership and layering instead of mirroring Java structure literally.
 - Compatible scalar, list-array, and binary/uint8-array adaptations are immediate-field-only. Recursive matched-field comparison for collection elements, array elements, map keys, and map values must require exact nullability, ref tracking, generic arity, and type shape except documented user-type family normalization.
+- Root deserialization graph budgets are owned by `ReadContext` and initialized by the root
+  `Fory::deserialize` overload. Keep `max_graph_memory_bytes` as a fixed-default graph limit:
+  unset/default is `128 MiB`, positive explicit values override it, and explicit non-positive
+  values are invalid at config creation. Byte and stream roots use the same
+  configured/default budget behavior. Root `Fory` overloads reset the budget only; they must not
+  pre-reserve root type or root self bytes.
+  Do not mirror the configured max into a second active-limit field; use config plus mutable
+  remaining budget.
+  Reserve estimated shallow graph-owner memory before allocation while preserving existing
+  byte-availability checks and their non-empty metadata ordering. `ReadContext` may expose only raw
+  byte reservation; collection, map, array, struct, and object
+  formulas belong in serializer owners. Skip dedicated string, binary, primitive scalar, primitive
+  vector, and primitive dense-array leaf owners; `std::vector<bool>` charges rounded packed-bit
+  storage. General `std::vector<T>` for non-primitive `T` is inline value storage and must be
+  reserved by the vector owner.
+- C++ graph budget formulas must be portable lower-bound estimates, not STL heap-layout accounting.
+  Generic collection-like containers reserve `count_or_capacity * sizeof(value_type)`, map-like
+  containers reserve `count * (sizeof(key_type) + sizeof(mapped_type))`, and set-like containers
+  reserve `count * sizeof(key_type)`. Root struct/product owners and smart-pointer/box allocation
+  owners reserve shallow self storage exactly once; nested value serializers reserve only dynamic
+  storage they allocate, not their own inline self storage again. Do not add guessed
+  node/header/debug-STL overhead, red-black-tree fields, allocator probing, object-layout
+  inspection, generic per-entry pointer overhead, or unordered bucket-table guesses.
 
 ## Key Paths
 

.agents/languages/csharp.md

@@ -12,6 +12,26 @@ Load this file when changing `csharp/` or C# xlang behavior.
 - Generated C# gRPC service companions are compiler-owned files that depend on application-provided gRPC packages, not `csharp/src/Fory`. Keep gRPC package references out of the Fory runtime package.
 - C# generated schema modules are source-file owners. Service companions must use that module's `ThreadSafeFory` and must not introduce namespace-owned aliases or duplicate serializer registration paths.
 - Compatible scalar, list-array, and binary/uint8-array adaptations are immediate-field-only. Recursive matched-field comparison for collection elements, array elements, map keys, and map values must require exact nullability, ref tracking, generic arity, and type shape except documented user-type family normalization.
+- Root deserialization graph memory budget state belongs to `ReadContext`. C# public roots are
+  memory-backed today, but the graph budget uses the same fixed default for every root shape.
+  Root APIs reset the budget only; they must not pre-reserve root type or root self bytes.
+  Do not mirror the configured max into a second active-limit field; use config plus mutable
+  remaining budget.
+  `ReadContext` may expose only raw byte reservation; concrete serializers and generated
+  serializers must compute list, array, map, struct, and object byte formulas before calling it.
+- `ReadContext` must not expose ref-publication pause/resume APIs or any non-budget owner
+  controls. Concrete serializers and generated serializers own ref publication timing directly,
+  and must not publish temporary owners.
+- For C# graph budget formulas, distinguish inline value storage from reference storage: use cheap
+  value-type size for `List<T>`/`T[]` value paths and the 4-byte reference fallback for reference
+  paths. Class/reference serializers reserve their own shallow self cost plus field storage when
+  materialized; struct/value serializers reserve self storage only on standalone serializer,
+  dynamic/boxed, or root materialization entries because field, list, array, map, set, and box
+  holders reserve the inline storage they own. Maps reserve key plus value storage, linked/hash/tree
+  conversions must not add guessed node or entry overhead, and independently materialized
+  collection/map/array owners reserve nonzero shallow self cost.
+  Dedicated string, binary, primitive scalar, and primitive dense-array serializers stay skipped and
+  rely on byte availability checks.
 - When extending C# tests from Java references, prioritize xlang spec behavior and the public C# contract before adding complex Java-specific parity cases.
 
 ## Commands

.agents/languages/dart.md

@@ -14,6 +14,21 @@ Load this file when changing `dart/`.
 - Keep root numeric wrapper defaults separate from generated field metadata. Root wrapper resolution belongs in the builtin resolver, while annotations and generated metadata choose fixed, tagged, or declared-field encodings.
 - Dart 64-bit carriers are optimized for each platform. Do not replace native extension-type wrappers with allocation-heavy classes or route web/native hot paths through `BigInt` unless the user approves a representation change.
 - In `Buffer`, cursor, serializer, and generated-code hot paths, prefer direct byte/local integer operations and conditional import/export files over callbacks, records, holder objects, wrapper round-trips, or runtime platform branches.
+- Root deserialization graph memory budgets are owned by `ReadContext`;
+  `maxGraphMemoryBytes` defaults to fixed `128 MiB`, positive explicit values override it, and
+  explicit non-positive values are invalid at config creation. Do not derive the budget from
+  `buffer.readableBytes`. `ReadContext` may expose only raw byte reservation; list, set, map, array,
+  struct, and object formulas
+  belong in serializer owners. Reserve Dart list/set/object-array reference
+  slots plus nonzero owner self cost, map key/value slots plus nonzero owner
+  self cost, compatible array-to-list materialization, and generated object reads before
+  allocation. Compatible list-to-typed-array reads skip the dense primitive-array leaf owner while
+  preserving byte checks. Object/struct
+  owners reserve nonzero shallow self memory plus shallow field storage. Skip
+  only dedicated string, binary, primitive scalar, `BoolList`, and typed-array
+  dense owner paths with byte checks. Do not add stream bytes-read accounting,
+  per-element accounting, extra hot-path allocations, or stale narrower-scope
+  formulas.
 - Do not add parallel header-low/header-high slot caches or multi-slot recent caches in TypeMeta hot paths to chase benchmark gaps. Header-cache hits must use the concrete checked cache owner directly; if a hit hint is needed, cache one TypeInfo/TypeMeta object and compare the validated header identity on that object, not separate low/high header fields or benchmark-pattern state.
 - If Dart TypeMeta cache ownership changes, keep the invariant in a source comment near the hit path: a checked metadata-cache hit skips the body and must not grow low-bit sentinels, accepted-header fields, parallel header slots, or benchmark-pattern state.
 - Dart expected-type TypeDef reads should compare the expected `TypeInfo` object's cached local TypeDef header before consulting the parsed-metadata map. A match is a direct local-schema hit: skip the remote body, add the expected type to the per-read shared type table, and do not publish to `ParsedTypeMetaCache`, record a remote schema version, or parse/hash the body.

.agents/languages/go.md

@@ -7,6 +7,23 @@ Load this file when changing `go/fory/` or Go xlang behavior.
 - Run Go commands from within `go/fory/`.
 - Changes under `go/` must pass formatting and tests.
 - The Go implementation focuses on reflection-based and codegen-based serialization.
+- Root deserialization graph memory budgets are owned by `ReadContext`.
+  `WithMaxGraphMemoryBytes` uses a fixed `128 MiB` default; positive explicit
+  values override it, and explicit non-positive values are invalid at config creation.
+  Byte-slice and stream roots use the same
+  configured/default budget behavior. Root APIs reset the budget only; they must not pre-reserve
+  root type or root self bytes. Do not mirror the configured max into a second active-limit field;
+  root setup should update only the mutable remaining budget. `ReadContext` may expose only raw byte
+  reservation; slice, map, array, struct, and object
+  formulas belong in handwritten or generated serializer owners. Reserve Go
+  slices as `len * elemBytes`, maps as `len * (keyBytes + valueBytes)`,
+  map-backed sets, and LIST-encoded inline/value slices in the owner that
+  allocates that storage. Struct root materialization paths, pointer allocations, and generated
+  allocation entries reserve shallow value storage exactly once; nested inline
+  struct serializers do not charge their own self storage again. Fixed arrays
+  are caller-owned unless a read path materializes a temporary owner. Skip
+  dedicated string, binary, BufferObject, primitive scalar, primitive ARRAY
+  slice, and primitive array owners with byte checks.
 - Set `FORY_PANIC_ON_ERROR=1` when debugging a failing Go test so you get the full call stack.
 - Do not set `FORY_PANIC_ON_ERROR=1` when running the full Go test suite, because some tests assert on error contents.
 

.agents/languages/java.md

@@ -14,6 +14,25 @@ Load this file when changing anything under `java/` or when Java drives a cross-
   values; use qualified names only when a real name conflict requires it.
 - If you run temporary tests with `java -cp`, run `mvn -T16 install -DskipTests` first so local Fory jars are current.
 - `WriteContext`, `ReadContext`, and `CopyContext` must stay explicit. Do not reintroduce `ThreadLocal` or ambient runtime-context patterns.
+- Java root deserialization graph memory budgeting belongs to `ReadContext`
+  and is initialized by `Fory` root APIs. Public config is `maxGraphMemoryBytes`
+  with fixed `128 MiB` default. Positive explicit values override the default;
+  explicit non-positive values are invalid and must be rejected at config creation.
+  Byte-array, memory-buffer, and stream roots use the same configured/default
+  budget behavior. Root APIs reset the budget only; they must not pre-reserve
+  root type or root self bytes. Do not mirror the configured max into a second
+  active-limit field; use config plus mutable remaining budget. `ReadContext`
+  may expose only raw byte reservation;
+  collection, map, array, struct, and object formulas belong in the concrete
+  serializer or generated serializer owner. Java collection, map, and
+  object-array owners reserve nonzero shallow self cost plus reference storage;
+  referenced object serializers reserve their own nonzero shallow self memory
+  plus shallow field storage when materialized.
+  Reference fields use the 4-byte fallback when the JVM reference size is not
+  queried cheaply; primitive fields use their encoded storage width. Preserve
+  existing `checkReadableBytes` guards before backing allocation or capacity
+  reservation. Do not add nested serializer-path `try/finally`, per-element
+  work, dynamic stream bytes-read accounting, or stale narrower-scope formulas.
 - Generated serializers must not retain runtime context fields. `Fory` should stay a root-operation facade rather than accumulating serializer or convenience state.
 - When the serializer class and constructor shape are known at the call site, prefer direct constructor lambdas or direct instantiation over reflective `Serializers.newSerializer(...)`.
 - For GraalVM, use `fory codegen` to generate serializers when building native images. Do not add reflection configuration except for JDK `proxy`.

.agents/languages/javascript.md

@@ -14,6 +14,18 @@ Load this file when changing `javascript/`.
 - Runtime value carriers such as decimal or reduced-precision numeric types belong under the core `types/` ownership boundary, with imports, exports, and codegen externals updated together.
 - Keep `TypeInfo` as schema metadata. Compatibility-sensitive decisions belong on `TypeResolver` or explicit operations, not as retained resolver state on metadata objects.
 - Normalize optional boolean config values at config construction; do not carry `null` through runtime paths when it means `false`.
+- JavaScript root deserialization graph memory budgeting belongs to `ReadContext`.
+  `maxGraphMemoryBytes` uses a fixed `128 MiB` default, positive explicit limits override it, and
+  explicit non-positive values are invalid at config creation. Do not derive the budget from the
+  `Uint8Array` root length. `ReadContext` may expose only raw
+  byte reservation; generated and dynamic
+  list/set/map/array/struct/object readers must reserve before allocation while preserving existing
+  byte checks. Lists/sets/object arrays reserve nonzero owner self cost plus 4-byte reference slots,
+  maps reserve nonzero owner self cost plus key/value reference storage, object/struct readers
+  reserve nonzero shallow self memory plus shallow field storage, compatible array-to-list reads
+  reserve target list materialization, and compatible list-to-typed-array reads skip the dense
+  primitive-array leaf owner while preserving byte checks. Keep dedicated string, binary, primitive
+  scalar, and dense typed-array leaf owners out of this budget.
 - Regenerated compatible read serializers are remote-schema-specific. After classification marks a field as direct, compatible scalar, or skip, generated JavaScript should emit straight-line remote-field-order code. Do not add an outer matched-id switch unless the current regenerated shape cannot preserve those semantics.
 - Compatible scalar codegen must decide the exact remote/local scalar pair before emitting source. Generate the concrete `reader.readXxx()` call plus inline trivial conversions such as boolean-to-string or numeric widening, and keep helpers only for semantic validation such as range checks, exactness checks, decimal parsing/formatting, and string-to-bool. Do not call a generic hot-path converter that redispatches on `remoteTypeId`, `localTypeId`, field descriptors, or field names.
 - Compatible scalar conversion is immediate-field-only. Recursive schema comparison for collection elements, array elements, map keys, and map values must reject scalar mismatches instead of applying the top-level scalar conversion matrix.

.agents/languages/python.md

@@ -13,6 +13,20 @@ Load this file when changing `python/`, Cython serialization, or Python xlang be
 - Cython mode owns the hot runtime path. Do not duplicate core runtime types between Python and Cython, tunnel Python facade methods into hidden Cython internals, or keep dead shims unless the user explicitly needs a compatibility module path.
 - Use explicit Cython fields and methods for fixed hot-path shapes. Avoid `__getattr__`, generic `object` fields, public bridge internals, or `Fory` backreferences where ownership can stay explicit.
 - Keep Python and Cython context/ref-tracking branch conditions and stack mutations semantically aligned unless a documented intentional difference exists.
+- Root deserialization graph memory budgets are owned by pure-Python and Cython `ReadContext`.
+  Keep `max_graph_memory_bytes` public on `pyfory.Fory`/`Config`; the default effective limit is
+  fixed `128 MiB`, positive explicit values override it, and explicit non-positive values are
+  invalid at config creation. Byte and stream roots use the same
+  configured/default budget behavior. Do not mirror the configured max into a
+  second active-limit field; keep one configured max plus mutable remaining
+  budget. `ReadContext` may expose only raw
+  byte reservation; collection, dict, array, struct, and object
+  formulas belong in the pure-Python or Cython serializer owner. Lists, tuples, sets, and
+  object-dtype ndarray item storage reserve nonzero owner self cost plus `count * PyObject*`; dicts
+  reserve nonzero owner self cost plus `entryCount * 2 * PyObject*`. Python object owners reserve a
+  nonzero shallow self cost plus shallow field/reference storage. Keep string, bytes, primitive
+  scalar, `array.array`, primitive dense array, and primitive ndarray owners skipped, and preserve
+  byte-availability checks after budget reservation.
 - Public value constructors should accept normal Python values. Raw-bit, raw-buffer, and memoryview entry points should be explicit low-level APIs, and packed carriers should expose the buffer protocol from the actual storage owner when appropriate.
 - When debugging runtime or benchmark behavior, install the local package into the exact interpreter under test instead of relying on mixed `PYTHONPATH` state.
 - For wheel or extension pipeline changes, derive extension-module paths from current build targets, packaging config, or wheel payload discovery rather than historical module names.