typed_eav 0.5.0 → 0.7.0

data/lib/typed_eav/bulk_write.rb

@@ -16,7 +16,8 @@ module TypedEAV
   # allocate field UUIDs, and then hand off to `execute_pairs(pairs,
   # effective_grouping, field_uuids)` — a single shared loop that takes
   # ordered `[record, vbn]` pairs and runs the outer-transaction-plus-
-  # savepoint-per-record envelope.
+  # savepoint-per-record envelope; `transaction: :chunks` repeats that
+  # envelope per chunk so completed chunks can commit independently.
   #
   # Pair-shaped (not Hash-shaped) so `execute`'s `[record, vbn]` list can
   # carry duplicate in-memory instances of the same persisted row without
@@ -24,19 +25,25 @@ module TypedEAV
   # `execute`'s byte-for-byte behavior contract.
   module BulkWrite
     class << self
-      def execute(host_class:, records:, values_by_field_name:, version_grouping: :default)
-        validate_inputs!(records, values_by_field_name, version_grouping)
+      # rubocop:disable Metrics/ParameterLists -- transaction controls are explicit API contract.
+      def execute(
+        host_class:, records:, values_by_field_name:, version_grouping: :default, transaction: :all, chunk_size: nil
+      )
+        validate_inputs!(records, values_by_field_name, version_grouping, transaction, chunk_size)
 
         records = records.to_a
         return { successes: [], errors_by_record: {} } if records.empty?
 
         validate_record_classes!(host_class, records)
+        ensure_connection_owner!(host_class)
 
         effective_grouping = resolve_grouping(version_grouping)
         vbn = values_by_field_name.transform_keys(&:to_s)
         field_uuids = effective_grouping == :per_field ? vbn.keys.index_with { SecureRandom.uuid } : nil
 
-        execute_pairs(records.map { |r| [r, vbn] }, effective_grouping, field_uuids)
+        execute_pairs(
+          host_class, records.map { |r| [r, vbn] }, effective_grouping, field_uuids, transaction, chunk_size
+        )
       end
 
       # Per-record-varying sibling to `execute`. Accepts a `Hash<host_record,
@@ -45,12 +52,15 @@ module TypedEAV
       #
       # Empty `values_by_record` short-circuits to the empty result without
       # opening a transaction (matches `execute`'s empty-records contract).
-      def execute_per_record(host_class:, values_by_record:, version_grouping: :default)
-        validate_per_record_inputs!(values_by_record, version_grouping)
+      def execute_per_record(
+        host_class:, values_by_record:, version_grouping: :default, transaction: :all, chunk_size: nil
+      )
+        validate_per_record_inputs!(values_by_record, version_grouping, transaction, chunk_size)
 
         return { successes: [], errors_by_record: {} } if values_by_record.empty?
 
         validate_record_classes!(host_class, values_by_record.keys, method: :bulk_set_typed_eav_values_per_record)
+        ensure_connection_owner!(host_class)
 
         effective_grouping = resolve_grouping(version_grouping)
         pairs = values_by_record.map { |record, vbn| [record, vbn.transform_keys(&:to_s)] }
@@ -58,15 +68,11 @@ module TypedEAV
                         pairs.flat_map { |(_record, vbn)| vbn.keys }.uniq.index_with { SecureRandom.uuid }
                       end
 
-        execute_pairs(pairs, effective_grouping, field_uuids)
+        execute_pairs(host_class, pairs, effective_grouping, field_uuids, transaction, chunk_size)
       end
+      # rubocop:enable Metrics/ParameterLists
 
       def apply_record_save(record:, vbn:, effective_grouping:, uuids:, accumulator:)
-        push_uuid = case effective_grouping
-                    when :per_record then uuids[:record]
-                    when :per_field  then uuids[:field].values.first
-                    end
-
         do_save = lambda do
           record.typed_eav_attributes = vbn.map { |name, value| typed_eav_entry_for(name, value) }
           stamp_pending_version_group_ids(record, effective_grouping, uuids)
@@ -79,11 +85,7 @@ module TypedEAV
           end
         end
 
-        if push_uuid
-          TypedEAV.with_context(version_group_id: push_uuid, &do_save)
-        else
-          do_save.call
-        end
+        do_save.call
       end
 
       private
@@ -97,26 +99,31 @@ module TypedEAV
       # the same persisted row iterate each instance separately — matters
       # for `execute`'s byte-for-byte behavior contract on
       # `[Entity.find(1), Entity.find(1)]`-shaped input.
-      def execute_pairs(pairs, effective_grouping, field_uuids)
+      # rubocop:disable Metrics/MethodLength -- transaction wrapper retains one readable semantic loop.
+      # rubocop:disable Metrics/ParameterLists -- internal transaction controls stay explicit.
+      def execute_pairs(host_class, pairs, effective_grouping, field_uuids, transaction, chunk_size)
         successes = []
         errors_by_record = {}
 
         with_bulk_definitions_memo do
-          ActiveRecord::Base.cache do
-            ActiveRecord::Base.transaction do
-              pairs.each do |(record, vbn)|
-                record_uuid = effective_grouping == :per_record ? SecureRandom.uuid : nil
-                record_field_uuids = record_scoped_field_uuids(field_uuids, vbn)
-
-                with_record_scope(record) do
-                  ActiveRecord::Base.transaction(requires_new: true) do
-                    apply_record_save(
-                      record: record,
-                      vbn: vbn,
-                      effective_grouping: effective_grouping,
-                      uuids: { record: record_uuid, field: record_field_uuids },
-                      accumulator: { successes: successes, errors_by_record: errors_by_record },
-                    )
+          host_class.cache do
+            units = transaction == :all ? [pairs] : pairs.each_slice(chunk_size)
+            units.each do |unit|
+              host_class.transaction do
+                unit.each do |(record, vbn)|
+                  record_uuid = effective_grouping == :per_record ? SecureRandom.uuid : nil
+                  record_field_uuids = record_scoped_field_uuids(field_uuids, vbn)
+
+                  with_record_scope(record) do
+                    host_class.transaction(requires_new: true) do
+                      apply_record_save(
+                        record: record,
+                        vbn: vbn,
+                        effective_grouping: effective_grouping,
+                        uuids: { record: record_uuid, field: record_field_uuids },
+                        accumulator: { successes: successes, errors_by_record: errors_by_record },
+                      )
+                    end
                   end
                 end
               end
@@ -126,6 +133,8 @@ module TypedEAV
 
         { successes: successes, errors_by_record: errors_by_record }
       end
+      # rubocop:enable Metrics/ParameterLists
+      # rubocop:enable Metrics/MethodLength
 
       # For `:per_field`, the global `field_uuids` map covers the union of
       # field names across all records' value hashes. The per-record save
@@ -184,7 +193,7 @@ module TypedEAV
         ActiveRecord::Type::Boolean.new.cast(flag)
       end
 
-      def validate_inputs!(records, values_by_field_name, version_grouping)
+      def validate_inputs!(records, values_by_field_name, version_grouping, transaction, chunk_size)
         if records.nil?
           raise ArgumentError,
                 "bulk_set_typed_eav_values requires an Enumerable of records, got nil"
@@ -197,9 +206,17 @@ module TypedEAV
         end
 
         validate_grouping!(version_grouping)
+        validate_transaction!(transaction, chunk_size)
       end
 
-      def validate_per_record_inputs!(values_by_record, version_grouping)
+      def ensure_connection_owner!(host_class)
+        pools = [host_class.connection_pool, TypedEAV::Value.connection_pool, TypedEAV::Field::Base.connection_pool]
+        return if pools.map(&:object_id).uniq.one?
+
+        raise ArgumentError, "bulk_write requires host, value, and field connections to share a pool"
+      end
+
+      def validate_per_record_inputs!(values_by_record, version_grouping, transaction, chunk_size)
         unless values_by_record.is_a?(Hash)
           raise ArgumentError,
                 "bulk_set_typed_eav_values_per_record requires a Hash of values_by_record, " \
@@ -215,6 +232,14 @@ module TypedEAV
         end
 
         validate_grouping!(version_grouping)
+        validate_transaction!(transaction, chunk_size)
+      end
+
+      def validate_transaction!(transaction, chunk_size)
+        return if transaction == :all
+        return if transaction == :chunks && chunk_size.is_a?(Integer) && chunk_size.positive?
+
+        raise ArgumentError, "transaction must be :all or :chunks with a positive chunk_size"
       end
 
       def validate_grouping!(version_grouping)
@@ -225,11 +250,12 @@ module TypedEAV
                 "Supported values: #{valid_grouping.map(&:inspect).join(", ")}."
         end
 
-        return unless %i[per_record per_field].include?(version_grouping) && !TypedEAV.config.versioning
+        return unless %i[per_record per_field].include?(version_grouping) &&
+                      !TypedEAV::Versioning.atomic_callbacks_installed?
 
         raise ArgumentError,
-              "version_grouping: #{version_grouping.inspect} was passed but versioning is disabled. " \
-              "Set TypedEAV.config.versioning = true in your initializer, or pass " \
+              "version_grouping: #{version_grouping.inspect} was passed but versioning is disabled or not installed. " \
+              "Enable versioning at boot, or pass " \
               "version_grouping: :none to opt out explicitly, or omit the kwarg to silently no-op."
       end
 
@@ -244,7 +270,7 @@ module TypedEAV
 
       def resolve_grouping(version_grouping)
         if version_grouping == :default
-          TypedEAV.config.versioning ? :per_record : :none
+          TypedEAV::Versioning.atomic_callbacks_installed? ? :per_record : :none
         else
           version_grouping
         end

data/lib/typed_eav/config.rb

@@ -122,10 +122,9 @@ module TypedEAV
       end
       attr_writer :require_scope # rubocop:disable Style/AccessorGrouping
 
-      # Master kill-switch for Phase 04 versioning. When false (default), the
-      # Phase 04 internal subscriber is NOT registered with EventDispatcher
-      # at engine boot — zero overhead for apps that don't use versioning.
-      # When true, the subscriber registers but only writes a version row
+      # Boot-time switch for transactional versioning. When false (default),
+      # Value's version callbacks are not installed. When true, the callbacks
+      # install after the host configuration is loaded, but only write a row
       # when value.entity_type belongs to a host model that opted in via
       # `has_typed_eav versioned: true` (per-entity opt-in flows through
       # Registry; both layers land in plan 04-02).
@@ -138,7 +137,7 @@ module TypedEAV
       # Default false because the schema migration only matters for apps that
       # opt in. A v0.1.x deployment that pulls in Phase 04 without changing
       # any config or model declarations sees no behavior change — the
-      # subscriber doesn't register, no version rows are written, no perf
+      # callbacks don't register, no version rows are written, no perf
       # impact at all. The migration is still copied (idempotent), but the
       # table sits empty.
       def versioning
@@ -186,13 +185,13 @@ module TypedEAV
       #
       # Errors raised inside this proc are rescued by EventDispatcher and
       # logged via Rails.logger.error — they do NOT propagate to the
-      # user's save call (the row is already committed). Internal subscribers
-      # (Phase 04 versioning, Phase 07 matview) fire BEFORE this proc and
+      # user's save call (the row is already committed). Generic internal
+      # observers fire BEFORE this proc and
       # their errors DO propagate. See 03-CONTEXT.md §User-callback error policy.
       #
-      # Reassignment after gem initialization does NOT disable internal
-      # subscribers — those live on EventDispatcher.value_change_internals,
-      # not here.
+      # Reassigning this public callback does NOT disable transactional
+      # versioning callbacks; they are installed on Value at boot and are
+      # independent of this public slot.
       attr_accessor :on_value_change
 
       # Public single-proc slot for field-change events.
@@ -207,7 +206,8 @@ module TypedEAV
       #
       # :rename fires when `name` is among Field#saved_changes, even
       # combined with other attr changes (sort_order, options, etc.) —
-      # Phase 07 matview needs the rename signal to regenerate column names
+      # Registered consumers may use the rename signal to refresh their own
+      # name-to-field mappings.
       # even when the rename was bundled with other edits.
       attr_accessor :on_field_change
 
@@ -215,7 +215,7 @@ module TypedEAV
       # Field::Image-typed Value gains (or replaces) an attachment. Receives
       # `(value, blob)`. Default nil — no-op when not configured.
       #
-      # Hook ordering: fires AFTER versioning (Phase 04) and AFTER
+      # Hook ordering: fires AFTER the transactional version write and AFTER
       # on_value_change (Phase 03). The hook is informational ("an image
       # was attached"), not mutational; running it last avoids polluting
       # earlier hooks' snapshots / context with attachment-derived state.
@@ -259,22 +259,20 @@ module TypedEAV
         self.field_types = BUILTIN_FIELD_TYPES.dup
         self.scope_resolver = DEFAULT_SCOPE_RESOLVER
         self.require_scope = true
-        # Phase 04 versioning master switch + actor resolver. Reset to defaults
+        # Transactional versioning boot switch + actor resolver. Reset to defaults
         # (false / nil) so test isolation matches `Config.on_value_change` / etc.
-        # Internal subscribers (TypedEAV::Versioning::Subscriber, registered
-        # at engine load by plan 04-02) are deliberately NOT cleared here —
-        # they live on EventDispatcher.value_change_internals and survive
+        # Transactional Value callbacks are deliberately NOT cleared here —
+        # callback installation is boot-latched and survives
         # Config.reset! by design (the snapshot/restore split is locked at
         # 03-CONTEXT.md §Reset split). Test teardown that needs to clear
-        # subscribers too calls EventDispatcher.reset!.
+        # generic observers too calls EventDispatcher.reset!.
         self.versioning = false
         self.actor_resolver = nil
         # Test isolation: scoping_spec/field_spec/etc. call Config.reset! in
         # `after` hooks — this ensures user procs set in earlier tests don't
-        # leak across examples. Internal subscribers
-        # (EventDispatcher.value_change_internals/field_change_internals) are
-        # deliberately NOT reset here — they're populated at engine load by
-        # Phase 04+ and must persist across Config.reset!. Test teardown
+        # leak across examples. Generic EventDispatcher observers
+        # (value_change_internals/field_change_internals) are deliberately NOT
+        # reset here — they persist across Config.reset!. Test teardown
         # that needs to clear EVERYTHING calls EventDispatcher.reset! too.
         self.on_value_change = nil
         self.on_field_change = nil

data/lib/typed_eav/csv_mapper.rb

@@ -70,7 +70,7 @@ module TypedEAV
     # `errors.empty?`. Callers that need to combine multiple row Results
     # into a batch view do so by composing the immutable Hashes in their
     # own code (e.g., `results.flat_map(&:errors).reduce({}, :merge)`); the
-    # mapper does not provide a "merge" helper in v0.6.0.
+    # mapper does not provide a "merge" helper.
     class Result
       attr_reader :attributes, :errors
 

data/lib/typed_eav/engine.rb

@@ -8,12 +8,10 @@ module TypedEAV
       require_relative "field/typed_storage"
       require_relative "config"
       require_relative "registry"
-      # Eager-loaded (not autoloaded) — Phase 04 versioning will register on
-      # EventDispatcher at engine boot, before any model reference triggers
-      # autoload. Without this require_relative, Phase 04's engine-time
-      # `register_internal_value_change` call would const-resolve the module
-      # for the first time and run a fresh `@value_change_internals = []`
-      # AFTER versioning had already pushed onto a different instance.
+      # Eager-loaded (not autoloaded) — transactional versioning registers its
+      # Value callbacks at engine boot, before any model reference triggers
+      # autoload. Keeping the dispatcher loaded early gives public and
+      # generic observers one stable broker instance.
       require_relative "event_dispatcher"
     end
 
@@ -24,11 +22,11 @@ module TypedEAV
       end
     end
 
-    # Phase 04 versioning subscriber registration.
+    # Transactional versioning callback registration.
     #
     # CONDITIONAL on TypedEAV.config.versioning. When false (the default
-    # for apps that don't enable versioning), no subscriber is registered:
-    # zero callable in EventDispatcher.value_change_internals, zero per-write
+    # for apps that don't enable versioning), no Value callback is registered:
+    # zero transactional callback overhead.
     # dispatch overhead, zero config reads on the hot path. This is the
     # locked CONTEXT contract — line 17 says "zero overhead for apps that
     # don't use versioning", which means literally no callable, not "callable
@@ -46,21 +44,17 @@ module TypedEAV
     # has fired (e.g., a Rails console session that monkey-patches Config,
     # or a feature-flag flip mid-process) will NOT get versioning until
     # process restart. Runtime toggle is not a documented use case — adding
-    # a register/deregister API is out of scope for Phase 04. The Risk §1
+    # a register/deregister API is out of scope for boot-latched versioning. The Risk §1
     # late-toggle concern from RESEARCH is acceptably narrowed by this
     # trade-off.
     #
-    # Slot 0 ordering: Phase 07 (future matview) will register its
-    # subscriber via its own `config.after_initialize` block declared LATER
-    # in this same engine file. Rails runs `after_initialize` blocks in
-    # declaration order within a single Engine class, so versioning's block
-    # fires first → slot 0. The regression spec (plan 04-03 P03) is the
-    # ongoing guard.
+    # Version rows are written in the source transaction. Public and generic
+    # observer ordering remains owned by EventDispatcher after commit.
     #
     # Why a one-line callable to a class method (not inline registration):
     # `TypedEAV::Versioning.register_if_enabled` is the testable seam. The
-    # slot-0 regression spec (plan 04-03 P03) and the zero-overhead
-    # verification spec (this plan, subscriber_spec) cannot reboot the Rails
+    # callback-chain regression spec and the zero-overhead verification spec
+    # cannot reboot the Rails
     # process inside RSpec — but they CAN call the helper directly against
     # a fresh internals array to exercise both branches (versioning on/off)
     # in-process. Inlining the `if` here would force tests to either reboot
@@ -78,7 +72,7 @@ module TypedEAV
     # that don't use Image/File field types pay zero overhead, AND the
     # gemspec stays free of an activestorage hard-dependency.
     #
-    # When AS IS loaded (Rails 7.1+ with the rails meta-gem, or an
+    # When AS is loaded (on supported Rails versions with the rails meta-gem, or an
     # explicit `gem 'activestorage'` line), TypedEAV::Value gains a
     # single :attachment has_one_attached association that covers BOTH
     # Field::Image and Field::File typed Values. The Image vs File
@@ -94,20 +88,15 @@ module TypedEAV
     # Value row (Text, Integer, etc.), even when no attachment is in
     # play. RESEARCH §Risk 3 documents this rationale.
     #
-    # Second after_initialize block (versioning's is the first): Rails
-    # runs after_initialize blocks in declaration order within a single
-    # Engine class. Versioning's slot-0 dispatcher position at the
-    # EventDispatcher level is preserved (dispatcher slots are an
-    # EventDispatcher-internal concern; the engine's after_initialize
-    # ordering is independent). Phase 07 matview will append its own
-    # block after this one.
+    # This second after_initialize block is independent of transactional
+    # versioning; it only handles Active Storage association setup.
     #
     # Why a one-line callable to a class method (testable seam): the
     # active_storage_soft_detect_spec cannot reboot Rails inside RSpec
     # to exercise both branches. By extracting the body into
     # `Engine.register_attachment_associations!`, specs call the helper
     # directly with whatever ::ActiveStorage state they need to test.
-    # Pattern matches Phase 04's `Versioning.register_if_enabled`.
+    # Pattern matches `Versioning.register_if_enabled`.
     config.after_initialize do
       TypedEAV::Engine.register_attachment_associations!
     end

data/lib/typed_eav/entity_query.rb

@@ -75,7 +75,15 @@ module TypedEAV
     # short: meaningful only with `:is_null` (Reading A "no non-NULL
     # value," includes no-row hosts), no-op with `:is_not_null`, silently
     # ignored otherwise.
-    def with_field(name, operator_or_value = nil, value = nil, scope: UNSET_SCOPE, parent_scope: UNSET_SCOPE, include_missing: false)
+    # rubocop:disable Metrics/ParameterLists -- preserves the public positional and partition keyword API.
+    def with_field(
+      name,
+      operator_or_value = nil,
+      value = nil,
+      scope: UNSET_SCOPE,
+      parent_scope: UNSET_SCOPE,
+      include_missing: false
+    )
       filter = if value.nil? && !operator_or_value.is_a?(Symbol)
                  # Two-arg form: with_field("name", "value") implies :eq
                  { name: name, op: :eq, value: operator_or_value }
@@ -84,6 +92,7 @@ module TypedEAV
                end
       where_typed_eav(filter, scope: scope, parent_scope: parent_scope, include_missing: include_missing)
     end
+    # rubocop:enable Metrics/ParameterLists
 
     # Returns field definitions for this entity type.
     #
@@ -111,22 +120,26 @@ module TypedEAV
     end
 
     # Bulk write API. Sets the same `values_by_field_name` Hash on every
-    # record in `records` inside ONE outer ActiveRecord transaction with a
-    # SAVEPOINT-PER-RECORD failure-isolation envelope. See `TypedEAV::BulkWrite`
-    # for the transaction shape, error-aggregation contract, and the
-    # `version_grouping:` semantics.
-    def bulk_set_typed_eav_values(records, values_by_field_name, version_grouping: :default)
+    # record in `records` using an outer transaction with per-record savepoints
+    # (`transaction: :all`) or one such envelope per committed chunk
+    # (`transaction: :chunks`). See `TypedEAV::BulkWrite` for the error and
+    # `version_grouping:` contracts.
+    def bulk_set_typed_eav_values(
+      records, values_by_field_name, version_grouping: :default, transaction: :all, chunk_size: nil
+    )
       TypedEAV::BulkWrite.execute(
         host_class: self,
         records: records,
         values_by_field_name: values_by_field_name,
         version_grouping: version_grouping,
+        transaction: transaction,
+        chunk_size: chunk_size,
       )
     end
 
     # Per-record-varying bulk write API. Sibling to `bulk_set_typed_eav_values`
     # for callers (sync importers, per-row updaters) where each record carries
-    # its own values hash. Routes through the same outer-transaction-plus-
+    # its own values hash. Routes through the same transaction/chunk and
     # savepoint envelope and returns the same
     # `{ successes: [...], errors_by_record: { record => errors_hash } }`
     # shape. See `TypedEAV::BulkWrite` for the transaction shape and the
@@ -186,11 +199,32 @@ module TypedEAV
     # write `"name"` share one UUID for that cell; a record writing
     # `"city"` (that no other record writes) gets its own UUID for
     # `"city"`. Overlapping fields share a version group across records.
-    def bulk_set_typed_eav_values_per_record(values_by_record, version_grouping: :default)
+    def bulk_set_typed_eav_values_per_record(
+      values_by_record, version_grouping: :default, transaction: :all, chunk_size: nil
+    )
       TypedEAV::BulkWrite.execute_per_record(
         host_class: self,
         values_by_record: values_by_record,
         version_grouping: version_grouping,
+        transaction: transaction,
+        chunk_size: chunk_size,
+      )
+    end
+
+    # Reduced-semantics SQL bulk upsert. This deliberately separate API
+    # requires `acknowledge_reduced_semantics: true`; it retains Value
+    # prevalidation/casting and domain/partition checks while skipping host and
+    # Value persistence lifecycle callbacks, versioning, and delete shorthand.
+    def bulk_upsert_typed_eav_values(
+      records, values_by_field_name, acknowledge_reduced_semantics: false, transaction: :all, chunk_size: nil
+    )
+      TypedEAV::BulkUpsert.execute(
+        host_class: self,
+        records: records,
+        values_by_field_name: values_by_field_name,
+        acknowledge_reduced_semantics: acknowledge_reduced_semantics,
+        transaction: transaction,
+        chunk_size: chunk_size,
       )
     end
 

data/lib/typed_eav/event_dispatcher.rb

@@ -2,8 +2,8 @@
 
 module TypedEAV
   # In-process event-dispatch hub for Value and Field after_commit lifecycle
-  # events. Implements the contract that Phase 04 versioning and Phase 07
-  # materialized index both depend on.
+  # events. It carries public callbacks and generic in-gem observers;
+  # durable version rows are written by transactional Value callbacks.
   #
   # ## Contract surface
   #
@@ -11,20 +11,15 @@ module TypedEAV
   #   proc slots (nil-default), backed by ActiveSupport::Configurable. Users
   #   set them via `TypedEAV.configure { |c| c.on_value_change = ->(...) }`.
   # - `register_internal_value_change(callable)` / `register_internal_field_change(callable)`
-  #   are FIRST-PARTY hooks for in-gem features (Phase 04 versioning, Phase 07
-  #   matview DDL regen). They are not private_class_method because Phase 04
-  #   lives in `TypedEAV::Versioning::*` and cannot reach a truly-private class
-  #   method — the `register_internal_*` naming + this comment block signal
-  #   first-party-only intent.
+  #   are FIRST-PARTY hooks for in-gem observers. The explicit registration
+  #   names signal their intended scope.
   # - Internal subscribers fire FIRST, in registration order. User proc fires
-  #   LAST. Phase 04 reserves slot 0 of `value_change_internals` by convention.
+  #   LAST. Durable ValueVersion writing is installed on Value transactions;
+  #   this dispatcher does not own that write.
   #
   # ## Error policy (split, locked at 03-CONTEXT.md §User-callback error policy)
   #
-  # - Internal subscribers: exceptions PROPAGATE (fail-closed). Versioning
-  #   corruption must be loud — silent failure leaves typed_eav_value_versions
-  #   inconsistent with the live row. Without propagation, Phase 04 bugs
-  #   would be invisible until someone audited the version table.
+  # - Internal observers: exceptions PROPAGATE (fail-closed).
   # - User proc: rescued via `rescue StandardError`, logged via
   #   `Rails.logger.error`, and SWALLOWED. The Value/Field row is already
   #   committed by the time the after_commit fires, so re-raising here would
@@ -43,9 +38,8 @@ module TypedEAV
   # design decisions this module implements.
   module EventDispatcher
     class << self
-      # Internal subscribers for Value lifecycle events. Populated at engine
-      # boot by Phase 04 versioning (slot 0) and Phase 07 matview (subsequent
-      # slots). Exposed as a reader for test introspection — first-party
+      # Internal subscribers for Value lifecycle observers. Exposed as a
+      # reader for test introspection — first-party
       # registration goes through `register_internal_value_change`.
       def value_change_internals
         @value_change_internals ||= []
@@ -57,15 +51,12 @@ module TypedEAV
         @field_change_internals ||= []
       end
 
-      # Register an in-gem value-change subscriber. Called at engine boot by
-      # Phase 04 versioning and Phase 07 matview. Subscribers are invoked in
+      # Register an in-gem value-change observer. Observers are invoked in
       # registration order with `(value, change_type, context)`. Exceptions
-      # raised here PROPAGATE — fail-closed because versioning corruption
-      # must be loud. See module-level comment §"Error policy".
+      # raised here PROPAGATE. See module-level comment §"Error policy".
       #
-      # NOT private_class_method: Phase 04 lives in TypedEAV::Versioning::*
-      # and cannot call a truly-private class method. The `register_internal_*`
-      # naming + this comment signal first-party-only intent.
+      # NOT private_class_method: first-party code uses this named seam, and
+      # the `register_internal_*` naming signals its intended scope.
       def register_internal_value_change(callable)
         value_change_internals << callable
       end
@@ -87,9 +78,10 @@ module TypedEAV
       # `change_type` is one of `:create | :update | :destroy`.
       def dispatch_value_change(value, change_type)
         context = TypedEAV.current_context
-        # Internals fire first, in registration order. Exceptions propagate —
-        # versioning failure (Phase 04) must surface, never be silent.
-        value_change_internals.each { |cb| cb.call(value, change_type, context) }
+        # Internals fire first, in registration order. Exceptions propagate.
+        value_change_internals.each do |cb|
+          cb.call(value, change_type, context)
+        end
 
         user = TypedEAV::Config.on_value_change
         return unless user
@@ -137,11 +129,10 @@ module TypedEAV
       # `Config.on_value_change` / `Config.on_field_change` — `Config.reset!`
       # owns the user-proc state.
       #
-      # Splitting reset is load-bearing: Phase 04 versioning registers on the
-      # internal list at engine load. Calling `EventDispatcher.reset!` must
-      # NOT require re-running engine load to restore versioning. Test
-      # teardown that needs to clear EVERYTHING calls Config.reset! AND
-      # EventDispatcher.reset! — see 03-CONTEXT.md §"Reset split".
+      # Transactional versioning callbacks are independently boot-latched on
+      # Value; resetting this dispatcher only resets observer registrations.
+      # Test teardown that needs to clear EVERYTHING calls Config.reset! AND
+      # EventDispatcher.reset!.
       def reset!
         @value_change_internals = []
         @field_change_internals = []