fix: freeze registries and restore failed root state

.agents/languages/cpp.md

@@ -18,6 +18,18 @@ Load this file when changing `cpp/`, Cython build plumbing, or C++ xlang behavio
   resource amplification, publish reference or cache state that survives root cleanup, or return
   success past the required safepoint. Do not add per-field checks, cursor rollback, or tests that
   pin the first detection point solely to make an error earlier or more precise.
+- Every public `Fory` and `ThreadSafeFory` root serialization or deserialization overload freezes
+  explicit registration before codec work. Route facade and resolver registration through one
+  authoritative frozen flag for that registry. Do not add another lifecycle flag or a multi-state
+  machine around the existing read/write-context resolver construction.
+- A root freezes explicit registration before the existing read/write-context construction clones
+  the registered resolver tables. Context construction must not eagerly complete every registered
+  `TypeInfo`; complete metadata only when a context first uses that type for metadata,
+  struct-version, or skip behavior. Keep ordinary type lookup free of completion work.
+- Keep the registration check out of normal runtime lookup hot paths.
+- Direct `Fory` and its resolver are creator-thread-owned. Configure `ThreadSafeFory` before
+  concurrent use and let that facade own first-root synchronization; do not add a resolver mutex to
+  support concurrent registration that neither facade permits.
 - Put private methods last in class definitions, immediately before private fields.
 - 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.

.agents/languages/csharp.md

@@ -9,6 +9,15 @@ Load this file when changing `csharp/` or C# xlang behavior.
 - C# code must build without compiler or analyzer warnings. Treat warnings as blockers in project, test, and generated code.
 - Fory C# requires .NET SDK `8.0+` and C# `12+`.
 - Use `dotnet format` to keep C# code style consistent.
+- A direct C# `Fory` registry and the `ThreadSafeFory` public registration boundary each own one
+  authoritative frozen flag. The first root sets the owning flag before codec work and leaves it
+  set after failure. Explicit registration checks that flag before mutation. `ThreadSafeFory` keeps
+  its existing registration callbacks only to configure newly created child runtimes; do not
+  turn that list into another registry lifecycle state.
+- Generated or custom serializer construction and `TypeInfo` creation can execute application
+  code. Complete them before explicit ID or name publication, then recheck the same `Fory` flag
+  immediately before publishing that registration. Do not publish an intermediate unregistered
+  `TypeInfo` for a custom binding.
 - 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.
 - C# external-type serialization is target-keyed. A local

.agents/languages/dart.md

@@ -98,8 +98,8 @@ Load this file when changing `dart/`.
 - 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 protocol-defined top 52 header bits on that object, not separate low/high header fields or benchmark-pattern state.
 - The top 52 TypeDef/TypeMeta header bits are the schema identity. The full low 12 bits belong only to the current frame and must not participate in hit selection. On a hit, decode the current body size from its low eight bits and any extended-size varuint, prove those bytes readable, and skip exactly that body. Do not validate reserved/compress flags, compare cached or local low bits, parse or rehash the body, repeat schema or policy validation, or grow low-bit sentinels, accepted-header fields, parallel header slots, or benchmark-pattern state. The cold miss path owns low-flag validation.
 - Dart expected-type TypeDef reads should compare only the top 52 bits of the expected `TypeInfo` object's cached local TypeDef header before consulting the parsed-metadata map. A match is a direct local-schema hit: use the current frame's size encoding only for bounds and skip, add the expected type to the per-read shared type table, and do not validate its low flags, publish to `ParsedTypeMetaCache`, record a remote schema version, or parse/hash the body.
-- Dart local TypeDef construction is registration-owned: record registrations
-  and finalize their dependent TypeDefs and struct serializers before the first
+- Dart local TypeDef construction is registration-owned: each explicit registration constructs its
+  dependent TypeDefs and struct serializers before the first
   root read or write. The first `serialize`, `serializeTo`, `serializeBuiltin`,
   `serializeBuiltinTo`, `deserialize`, or `deserializeFrom` call permanently
   freezes that `Fory` instance's resolver;

.agents/languages/go.md

@@ -7,6 +7,12 @@ 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 fast serializers.
+- A Go `Fory` instance has one authoritative registry-frozen flag. The first root serialization or
+  deserialization sets it before codec work and leaves it set after failure. Explicit registration
+  checks that flag before mutation. Do not add another registry lifecycle state or alter existing
+  registration semantics beyond that boundary check.
+  `threadsafe.Fory` has no registration API or facade registry: configure every pooled child in the
+  factory passed to `NewWithFactory` before returning it.
 - Go `ReadContext` intentionally defers codec errors to existing `HasError` or `CheckError`
   boundaries. After an error, work may continue only while it remains panic- and bounds-safe and
   cannot cause disproportionate work or allocation, publish state that survives root cleanup, or

.agents/languages/java.md

@@ -33,6 +33,14 @@ 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 scoped meta-share TypeInfo occurrences are root-local, and the current table size is their
+  protocol visibility boundary. Reset tables of at most 8192 entries by setting the size to zero;
+  do not null retained slots. Only when the size exceeds 8192 may cleanup replace the backing array,
+  and it must restore a small eight-slot array instead of retaining or allocating 8192 slots. Keep
+  the normal root-cleanup path allocation-free, and do not add count-shape specializations.
+- Deserialization failures must not copy or retain the active reference table or materialized graph
+  in the exception. Root reset owns releasing operation-local graph state; keep failure reporting
+  bounded independently of graph size.
 - 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;
@@ -76,6 +84,41 @@ Load this file when changing anything under `java/` or when Java drives a cross-
   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(...)`.
+- Each natural Java registry or public facade boundary owns one authoritative lifecycle flag. A
+  concrete resolver owns its local frozen flag; a thread-safe facade uses the shared registry's
+  frozen flag for the facade-wide boundary. The first root serialization or deserialization sets the
+  owning fact before codec work and never clears it, including after failure. Every explicit type,
+  serializer, module, name, ID, or type-checker binding checks that fact before mutation.
+  Disallow-list changes use the bound checker's resolver listeners. Do not add another lifecycle
+  state or a parallel registration-commit path.
+- Direct and thread-safe facades expose module registration before their first root. Kotlin and
+  Scala registration extensions target `BaseFory`; do not narrow them to concrete `Fory` or make
+  builder installation the only thread-safe path. A thread-safe facade's shared registry owns its
+  registration boundary so a root started by any child closes the facade before registration can
+  mutate another child. Non-root `execute` and copy operations remain concurrent and do not freeze
+  registration. Complete facade registration before concurrent serialization, deserialization,
+  copy, or `execute` calls begin; do not serialize those operations behind a registration lock.
+- `ForyModule.install` is registration-only setup. It may install nested modules and construct
+  child-specific serializers, but must not start a root through the supplied child or a captured
+  direct or thread-safe facade. Do not propagate the facade lifecycle owner into raw child
+  registration to support this invalid reentrancy; frozen-facade replay needs the unexposed child
+  to remain governed by its local resolver until it adopts the shared snapshot.
+- Live thread-safe facade registration carries the existing `SharedRegistry` check through
+  application-controlled serializer preparation and runs it immediately before child publication.
+  Replay into a new, unexposed thread-local child instead uses that child's local resolver check,
+  then freezes the child onto the shared snapshot before exposure. Do not make every child resolver
+  consult the shared frozen flag: that would reject the required frozen-facade setup replay.
+- `ThreadSafeFory.execute` exposes one borrowed child only for the callback. Do not retain that
+  child or register through it; use the facade registration methods so every current and future
+  child receives the same setup.
+- Serializer completion used by lazy, JIT, and generated serializers is an internal resolver-owned
+  operation. It remains valid after registration freezes and must not be treated as explicit
+  registration.
+- Registration freeze does not disable native runtime type resolution. When class registration is
+  not required, native roots may discover an unregistered runtime class and materialize its
+  resolver-owned `TypeInfo`, descriptor, serializer, or JIT cache entry after freeze. This runtime
+  cache materialization must not create or change an explicit class, serializer, ID, name, or
+  policy registration.
 - For GraalVM, use `fory codegen` to generate serializers when building native images. Do not add reflection configuration except for JDK `proxy`.
 - In Java native mode (`xlang=false`), only `Types.BOOL` through `Types.STRING` share type IDs with xlang mode. Other native-mode type IDs differ.
 - Choose one serializer ownership location per logical Java type family. Add native/xlang serializer variants only when the wire format or constructor contract truly differs.

.agents/languages/javascript.md

@@ -11,6 +11,19 @@ Load this file when changing `javascript/`.
 - Preserve generated serializer hot paths that bind writer, reader, ref, resolver, and metadata locals in outer closures; do not replace them with per-call context lookups without a measured reason.
 - Do not add parallel header-low/header-high slot caches in TypeMeta hot paths to chase benchmark gaps. Header-cache hits must use the concrete checked cache owner directly; if a small hit hint is needed, cache TypeMeta objects themselves and compare `TypeMeta.headerHash`, not separate low/high header fields or benchmark-pattern state.
 - JavaScript TypeMeta header cache hits should compare the 52-bit TypeMeta header hash directly. The hash is precise in JS `Number` and already includes the low header bits as hash input; do not add extra low-bit fields, sentinel state, nullable accepted headers, or parallel slot arrays around it.
+- JavaScript `Fory` owns the one authoritative registration-frozen flag. The first root
+  serialization or deserialization sets it before codec work and leaves it set after failure.
+  `TypeResolver` owns registration maps, not a second lifecycle flag.
+- Codegen hooks can start a root while an explicit registration graph is being generated. Recheck
+  the `Fory`-owned flag before every later serializer publication in that graph; do not add a
+  lifecycle flag to `TypeResolver`, stage the graph, or roll registry entries back.
+- A failed root releases its operation-local reference and metadata state before the exception
+  escapes. The next root entry releases state retained by the previous successful operation before
+  reusing the context. Keep the successful root exit allocation-free and do not copy Java
+  backing-array retention policies onto native JavaScript arrays. Read-side metadata
+  occurrence arrays use native replacement reset. The MetaString and TypeMeta writer owner tables each have
+  their own logical size: reset active owner IDs and that table's logical size without clearing
+  bounded backing, and replace either backing only after its root has more than 8192 owners.
 - 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`.

.agents/languages/kotlin.md

@@ -14,6 +14,15 @@ Load this file when changing `kotlin/` or compiler code that generates Kotlin so
   Fory. Do not auto-install a new serializer for an existing type-registered Kotlin class unless the
   wire format matches the previous serializer family and old-payload/new-runtime compatibility is
   tested.
+- Kotlin registration extensions target `BaseFory` so direct and thread-safe facades share the same
+  pre-root registration API, including module installation. Complete thread-safe facade
+  registration before concurrent serialization, deserialization, copy, or execution begins.
+- Explicit type, serializer, enum, and union registration checks the receiving `BaseFory` facade or
+  natural registry owner's one frozen flag before mutation. Keep generated serializer construction
+  on the existing direct resolver path; do not add a parallel registration path or lifecycle state.
+- Combined generated structural registration attaches the serializer with `setSerializer` after
+  registering the canonical STRUCT `TypeInfo`; `registerSerializer` would incorrectly reclassify
+  that wire identity as EXT. Generated unions use `registerUnion`.
 - When adding Kotlin gRPC service companions, emit Kotlin source only. Reuse the generated schema
   module's `ThreadSafeFory` and KSP-generated schema serializers, and keep grpc-java/grpc-kotlin
   dependencies application-owned instead of adding them as hard `fory-kotlin` dependencies.

.agents/languages/python.md

@@ -11,6 +11,26 @@ Load this file when changing `python/`, Cython serialization, or Python xlang be
 - Python mode is the pure-Python xlang implementation and is mainly for debugging and testing.
 - Cython mode is the default high-performance implementation.
 - 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.
+- A direct Python `TypeResolver` owns one authoritative `_registry_frozen` flag. In Cython mode the
+  compiled `TypeResolver` is the active owner instead, and the Python resolver delegates explicit
+  registration checks to that compiled flag; do not mirror the flag between the two resolvers.
+  Roots set their active owner before codec work and never clear it, including after failure.
+  `ThreadSafeFory` owns its own `_registry_frozen` flag for the public registration boundary over
+  pooled children. Its existing callback list configures newly created children; it is not another
+  lifecycle state.
+- Explicit type, serializer, name, and ID registration checks the frozen flag before mutation.
+  Automatic IDs remain registration-owned and must not turn native runtime discovery into explicit
+  registration.
+- A Python wire name or user ID identifies one `TypeInfo`. Reject explicit or native-discovery
+  collisions before publishing resolver maps. Lazy TypeDef completion preserves a configured
+  serializer, does not retain partial state, and restores the prior serializer and TypeDef after
+  failed completion without adding a lifecycle state.
+- Registry freeze prohibits explicit type and serializer registration after the first root; it
+  does not prohibit native runtime type resolution. Non-strict native writes may discover runtime
+  classes or callables, and reads may resolve those authorized by the deserialization policy. Both
+  paths may materialize resolver-owned type information or serializer cache entries without
+  creating or changing an explicit type, serializer, ID, name, or policy registration. Do not
+  describe these operations as late registration.
 - 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 budget state belongs to pure-Python and Cython `ReadContext`.

.agents/languages/scala.md

@@ -9,6 +9,15 @@ Load this file when changing `scala/`.
 - Scala supports the JVM and GraalVM Native Image, not Android. Do not add Android-specific Scala
   sources, tests, resources, R8 metadata, compiler plugins, macros, dependencies, or compatibility
   design.
+- Scala registration extensions target `BaseFory` so direct and thread-safe facades share the same
+  pre-root registration API, including module installation. Complete thread-safe facade
+  registration before concurrent serialization, deserialization, copy, or execution begins.
+- Explicit type, serializer, enum, and union registration checks the receiving `BaseFory` facade or
+  natural registry owner's one frozen flag before mutation. Keep generated serializer construction
+  on the existing direct resolver path; do not add a parallel registration path or lifecycle state.
+- Combined generated structural registration attaches the serializer with `setSerializer` after
+  registering the canonical STRUCT `TypeInfo`; `registerSerializer` would incorrectly reclassify
+  that wire identity as EXT. Generated unions use `registerUnion`.
 
 ## Commands