Epic: Hydration System Refactor #153

New issue

Open

opened 2026-03-15 23:08:32 +00:00 by freemo · 0 comments

freemo commented

2026-03-15 23:08:32 +00:00

Owner

Background and Context

The current Hydration module uses a class variable @@volatile that is shared across the entire inheritance hierarchy. When Publisher declares volatile :@local_registrations and Player declares volatile :@help_library, :@player, both write to the same @@volatile array. This leaks volatile declarations across unrelated classes — any class that includes Hydration sees every other class's volatiles.

The specification (Persistence and Storage section) prescribes replacing @@volatile with @_volatile_vars (a per-class instance variable), adding ancestor chain traversal via collect_volatile_vars, and protecting the dehydrate/rehydrate cycle with a SERIALIZATION_MUTEX.

Demonstrable Outcome

Volatile variable declarations are per-class, collected via ancestor chain traversal, and protected by a mutex during serialization. No class sees another class's volatile declarations unless it is a descendant.

Acceptance Criteria

@@volatile replaced with @_volatile_vars per-class instance variable
collect_volatile_vars walks ancestor chain to build union of volatile sets
SERIALIZATION_MUTEX guards dehydrate/rehydrate cycle
No volatile declaration leaks between unrelated classes
All persistence and serialization tests pass

## Background and Context The current `Hydration` module uses a class variable `@@volatile` that is shared across the entire inheritance hierarchy. When `Publisher` declares `volatile :@local_registrations` and `Player` declares `volatile :@help_library, :@player`, both write to the same `@@volatile` array. This leaks volatile declarations across unrelated classes — any class that includes Hydration sees every other class's volatiles. The specification (Persistence and Storage section) prescribes replacing `@@volatile` with `@_volatile_vars` (a per-class instance variable), adding ancestor chain traversal via `collect_volatile_vars`, and protecting the dehydrate/rehydrate cycle with a `SERIALIZATION_MUTEX`. ## Demonstrable Outcome Volatile variable declarations are per-class, collected via ancestor chain traversal, and protected by a mutex during serialization. No class sees another class's volatile declarations unless it is a descendant. ## Acceptance Criteria - `@@volatile` replaced with `@_volatile_vars` per-class instance variable - `collect_volatile_vars` walks ancestor chain to build union of volatile sets - `SERIALIZATION_MUTEX` guards dehydrate/rehydrate cycle - No volatile declaration leaks between unrelated classes - All persistence and serialization tests pass