typed_eav 0.1.0 → 0.2.1

data/README.md

@@ -333,7 +333,12 @@ TypedEAV.configure do |c|
 end
 ```
 
-The resolver can return a raw value (`"t1"`, `42`) or an AR record — TypedEAV calls `.id.to_s` when the return value responds to `#id`.
+The resolver MUST return a 2-element Array `[scope, parent_scope]`. Each slot
+accepts a raw value (`"t1"`, `42`), an AR record (TypedEAV calls `.id.to_s`
+on anything that responds to `#id`), or `nil`. If you don't use parent_scope,
+return `[scope, nil]`. A bare scalar return raises `ArgumentError` at the
+next ambient query — see [Migrating from v0.1.x](#migrating-from-v01x) for
+the upgrade path.
 
 ### Block APIs
 
@@ -385,6 +390,87 @@ If your app has existing typed-eav queries that don't yet pass scope, flip `requ
 
 To intentionally query across every partition (admin tools, migrations, cross-tenant audits), use the explicit escape hatch `TypedEAV.unscoped { ... }` rather than relying on `require_scope = false`.
 
+### Two-level scoping (`parent_scope`)
+
+When a single tenant axis isn't enough — say, `tenant_id` for the customer AND
+`workspace_id` for an in-tenant partition — declare both:
+
+```ruby
+class Project < ApplicationRecord
+  has_typed_eav scope_method: :tenant_id, parent_scope_method: :workspace_id
+end
+```
+
+Field (and section) definitions partition on the tuple `(entity_type, scope,
+parent_scope)`. A `Project` record reads field definitions in three precedence
+layers: a full-triple `(scope, parent_scope)` match wins, then `(scope, nil)`
+(tenant-wide), then `(nil, nil)` (truly global). The same precedence applies
+to the class-level query path.
+
+`parent_scope_method:` requires `scope_method:` — declaring it without a scope
+method raises at macro-expansion time (no host can have a parent partition
+without a scope partition).
+
+Both `with_scope` and the configured `scope_resolver` carry the tuple now:
+
+```ruby
+TypedEAV.with_scope(["t1", "w1"]) do
+  Project.where_typed_eav({ name: "status", value: "active" })
+end
+
+# Single-axis call still works (parent_scope = nil):
+TypedEAV.with_scope("t1") do
+  Contact.where_typed_eav({ name: "age", op: :gt, value: 21 })
+end
+
+# Custom resolver — MUST return [scope, parent_scope]:
+TypedEAV.configure do |c|
+  c.scope_resolver = -> { [Current.tenant&.id, Current.workspace&.id] }
+end
+```
+
+Per-query overrides accept `parent_scope:` alongside `scope:` on
+`where_typed_eav`, `with_field`, and `typed_eav_definitions`:
+
+```ruby
+Project.where_typed_eav(
+  { name: "priority", value: "high" },
+  scope: "t1",
+  parent_scope: "w1",
+)
+```
+
+When `acts_as_tenant` is loaded, the auto-detected `DEFAULT_SCOPE_RESOLVER`
+returns `[ActsAsTenant.current_tenant, nil]` — the parent_scope slot is `nil`
+because the tenant gem has no parent-scope analog. Configure your own resolver
+when you need both axes.
+
+### Migrating from v0.1.x
+
+The resolver-callable contract is a **breaking change**: any custom
+`Config.scope_resolver` lambda must now return `[scope, parent_scope]` (a
+2-element Array) instead of a bare scalar. A scalar return raises
+`ArgumentError` at the next ambient query so the failure is loud, not silent.
+If you don't use parent_scope, return `[scope, nil]`.
+
+Run `bin/rails typed_eav:install:migrations` to copy the new
+`AddParentScopeToTypedEavPartitions` migration into your app, then
+`bin/rails db:migrate`. The migration is safe on production: it adds a
+nullable `parent_scope` column (catalog-only, instantaneous) and uses
+`CREATE INDEX CONCURRENTLY` for all index changes, so existing rows aren't
+rewritten. Existing fields end up with `parent_scope = NULL` (the
+global-parent shape) and continue to work for every single-scope caller.
+
+See the [CHANGELOG](CHANGELOG.md) for the full upgrade checklist.
+
+### Orphan-parent invariant
+
+A `Field` or `Section` row with `parent_scope` set and `scope` blank is
+invalid — model-level validation rejects it on save. Reason: a "global field
+within one workspace" has no semantic resolution path; the row would never
+match any record's resolver. The paired partial unique indexes rely on this
+invariant.
+
 ### Name collisions across scopes
 
 When both a global field (`scope: nil`) and a scoped field share a name, the **scoped definition wins** for the partition that owns it: forms render exactly one input (the scoped one), reads return the scoped value, and writes target the scoped row.
@@ -412,6 +498,11 @@ When both a global field (`scope: nil`) and a scoped field share a name, the **s
 | `Url` | `string_value` | String | strips whitespace |
 | `Color` | `string_value` | String | hex color values |
 | `Json` | `json_value` | Hash/Array | arbitrary JSON |
+| `Currency` | `decimal_value` + `string_value` | `{amount: BigDecimal, currency: String}` | `default_currency`, `allowed_currencies` |
+| `Percentage` | `decimal_value` | BigDecimal (0..1 range) | `decimal_places`, `display_as: :fraction \| :percent` |
+| `Image` | `string_value` (signed_id) + `:attachment` has_one_attached | String (Active Storage signed_id) | `allowed_content_types`, `max_size_bytes` |
+| `File` | `string_value` (signed_id) + `:attachment` has_one_attached | String (Active Storage signed_id) | `allowed_content_types`, `max_size_bytes` |
+| `Reference` | `integer_value` (FK) | Integer (target record ID) | `target_entity_type`, `target_scope` |
 
 ## Sections (Optional UI Grouping)
 
@@ -464,6 +555,129 @@ TypedEAV.configure do |c|
 end
 ```
 
+### Multi-cell field types
+
+External field types may store their logical value across multiple typed
+columns. Storage behavior is exposed through `field.storage_contract`,
+which keeps callers from knowing whether a field is single-cell or
+multi-cell. The contract covers:
+
+- `value_columns` - the native typed cells used for storage, snapshots,
+  reverting, and update change detection.
+- `read(value_record)` / `write(value_record, casted)` - logical value
+  reads and writes.
+- `apply_default(value_record)` - default application across the field's
+  storage cells.
+- `query_column(operator)` - query routing for each supported operator.
+- `before_snapshot(value_record, change_type)` /
+  `after_snapshot(value_record, change_type)` - version row jsonb shape.
+- `changed?(value_record)` - update event gating across every storage
+  cell the field owns.
+
+Single-cell field types inherit the default contract. For multi-cell
+fields, create a `TypedEAV::FieldStorageContract` subclass and select it
+from the field class:
+
+```ruby
+class MoneyStorageContract < TypedEAV::FieldStorageContract
+  def self.value_columns = %i[decimal_value string_value]
+  def self.query_column(operator) = operator == :currency_eq ? :string_value : :decimal_value
+
+  def read(value_record)
+    amount = value_record[:decimal_value]
+    currency = value_record[:string_value]
+    amount.nil? && currency.nil? ? nil : { amount: amount, currency: currency }
+  end
+
+  def write(value_record, casted)
+    value_record[:decimal_value] = casted&.fetch(:amount, nil)
+    value_record[:string_value] = casted&.fetch(:currency, nil)
+  end
+
+  def apply_default(value_record)
+    default = field.default_value
+    return unless default.is_a?(Hash)
+
+    value_record[:decimal_value] = default[:amount] || default["amount"]
+    value_record[:string_value] = default[:currency] || default["currency"]
+  end
+end
+
+class Fields::Money < TypedEAV::Field::Base
+  value_column :decimal_value
+  storage_contract_class MoneyStorageContract
+end
+```
+
+Compatibility helpers such as `self.value_columns` and
+`self.operator_column(operator)` may delegate to the selected contract
+when older callers still use those class methods.
+
+Defaults delegate to `value_column` for single-cell storage, so existing
+single-cell types are unchanged. The built-in `Field::Currency` is the
+canonical multi-cell consumer of these extension points.
+
+### Built-in field types
+
+- **`Currency`:** Stores `{amount: BigDecimal, currency: String}` across two typed columns (`decimal_value` for the amount; `string_value` for the ISO 4217 currency code) through `CurrencyStorageContract`. Operators: `:eq`, `:gt`, `:lt`, `:gteq`, `:lteq`, `:between` target the amount; `:currency_eq` targets the currency code; `:is_null` / `:is_not_null` target the amount column (a Currency value is null when its amount is null). Cast input MUST be a hash with `:amount` and/or `:currency` keys — bare numeric/string values are rejected with `:invalid` to enforce explicit currency dimension at write time. Options: `default_currency` (String ISO code, applied as fallback only when an amount is given without an explicit currency), `allowed_currencies` (Array of ISO codes; `validate_typed_value` enforces inclusion). Versioning snapshots automatically capture both columns through the storage contract. The `:currency_eq` operator is registered ONLY on `Field::Currency`; the QueryBuilder operator-validation gate rejects it with a clear `ArgumentError` if invoked on any other field type.
+
+  ```ruby
+  Contact.where_typed_eav(name: "price", op: :currency_eq, value: "USD")
+  Contact.where_typed_eav(name: "price", op: :between,     value: [50, 150])
+  ```
+
+- **`Percentage`:** A `Field::Decimal` subclass storing the underlying fraction in 0..1 (inclusive). The `:percent` representation is a format-time concern — call `field.format(value)` with `display_as: :percent` to render `0.75` as `"75.0%"`. Options: `decimal_places` (Integer >= 0, default 2; format-time precision only — does NOT alter what's stored in `decimal_value`), `display_as` (`:fraction` default, or `:percent`). Validation: out-of-range values (e.g., `1.5`) fail with the message `"must be between 0.0 and 1.0"`. Storage and operator semantics inherit from `Field::Decimal`.
+
+  ```ruby
+  pf = TypedEAV::Field::Percentage.create!(
+    name: "discount", entity_type: "Order", scope: tenant_id,
+    options: { display_as: :percent, decimal_places: 1 },
+  )
+  pf.format(BigDecimal("0.755")) # => "75.5%"
+  ```
+
+- **`Image`:** Active Storage-backed field type. Stores the attached blob's `signed_id` (a String) in `string_value`. Operators: `:eq`, `:is_null`, `:is_not_null`. Options: `allowed_content_types` (Array of strings; supports exact matches like `"image/png"` and `image/*` family wildcards), `max_size_bytes` (Integer; nil disables the cap). The single `:attachment` has_one_attached association is declared on `TypedEAV::Value` at engine boot when Active Storage is loaded; otherwise `Field::Image#cast` raises `NotImplementedError` with an actionable install message. The `:attachment` association is shared with `Field::File` — Image vs File is a class-identity distinction (used by the `on_image_attached` hook), not a separate association.
+
+  ```ruby
+  field = TypedEAV::Field::Image.create!(
+    name: "avatar", entity_type: "Contact",
+    options: { allowed_content_types: %w[image/png image/jpeg image/webp], max_size_bytes: 5_000_000 },
+  )
+  value = TypedEAV::Value.create!(entity: contact, field: field)
+  value.attachment.attach(io: file_io, filename: "avatar.png", content_type: "image/png")
+  value.update!(string_value: value.attachment.blob.signed_id)
+  value.value # => the signed_id String
+  ```
+
+- **`File`:** Same shape as `Field::Image` but without image-specific semantics. Stores `signed_id` in `string_value`; same operator set; same options (`allowed_content_types`, `max_size_bytes`). The Image vs File distinction is by `value.field.class` at runtime — apps that want strict image-only validation set `allowed_content_types: ["image/*"]` on `Field::Image`; `Field::File` is a general-purpose attachment slot.
+
+- **Active Storage dependency:** Lazy soft-detect via `defined?(::ActiveStorage::Blob)`. The gem does NOT add Active Storage as a hard dependency — apps that never use Image/File never need to install it. To use Image or File fields, add `gem "activestorage"` to your Gemfile (already included in Rails 7.1+ via the `rails` meta-gem) and run `bin/rails active_storage:install` to create the `active_storage_blobs` / `active_storage_attachments` / `active_storage_variant_records` tables. The mirror precedent is `acts_as_tenant`, which is also soft-detected (see `Config::DEFAULT_SCOPE_RESOLVER`).
+
+- **`on_image_attached` hook:** Fires from `after_commit` on `TypedEAV::Value` when a `Field::Image`-typed Value's attachment is added or replaced. Receives `(value, blob)`. Configure via `TypedEAV.configure { |c| c.on_image_attached = ->(v, b) { ... } }`. Hook ordering: runs AFTER versioning (Phase 4) and AFTER `on_value_change` (Phase 3) so it sees the persisted version row and the user-callback context. File attachments do NOT fire this hook — the name is image-specific by design. Use `on_value_change` for a generic value-mutation signal that covers File-typed Values too.
+
+  ```ruby
+  TypedEAV.configure do |c|
+    c.on_image_attached = ->(value, blob) {
+      ProcessImageJob.perform_later(value.id, blob.id)
+    }
+  end
+  ```
+
+- **`Reference`:** Foreign-key field type. Stores the target record's integer ID in `integer_value`. Operators: `:eq`, `:is_null`, `:is_not_null`, `:references` (explicit narrowing — does NOT inherit `:integer_value`'s `:gt`/`:lt`/`:between` defaults; arithmetic comparisons on FKs don't carry useful semantics). The `:references` operator accepts AR record instances OR Integer IDs at query time, normalizing via `field.cast` (a class-mismatched record routes to `base.none` rather than `:is_null`). Options: `target_entity_type` (REQUIRED — String class name of the target model, validated to constantize at field save), `target_scope` (OPTIONAL — when set, the field is REJECTED at save time if `target_entity_type` is not registered with `has_typed_eav scope_method:` (Gating Decision 2); when set with a scoped target, value-time validation rejects writes whose target's `typed_eav_scope` does not match `target_scope` via a `target_partition_matches?` helper structurally parallel to Phase 1's `entity_partition_axis_matches?` but on the target axis). Cross-scope safety mirrors the existing `Value#validate_field_scope_matches_entity` guard pattern applied to the target rather than the source.
+
+  ```ruby
+  rf = TypedEAV::Field::Reference.create!(
+    name: "manager", entity_type: "Contact", scope: tenant_id,
+    options: { target_entity_type: "Contact", target_scope: tenant_id },
+  )
+  TypedEAV::Value.create!(entity: alice, field: rf, value: bob)         # accepts AR record
+  TypedEAV::Value.create!(entity: alice, field: rf, value: bob.id)      # accepts Integer FK
+  Contact.where_typed_eav(name: "manager", op: :references, value: bob) # filter by record
+  Contact.where_typed_eav(name: "manager", op: :references, value: 42)  # filter by FK
+  ```
+
+- **Summary:** The built-in field types **Image, File, Reference, Currency, Percentage** all preserve the cast-tuple contract (`[casted, invalid?]`), the operator-dispatch model (`supported_operators` + `operator_column` for multi-cell types), and the no-hardcoded-attribute-references foundational principle. The multi-cell extension surface (`read_value`, `apply_default_to`, `operator_column`, and `write_value`) is the canonical way to build any future external multi-cell field type.
+
 ## Validation Behavior
 
 A few non-obvious contracts worth knowing about up front:
@@ -474,12 +688,430 @@ A few non-obvious contracts worth knowing about up front:
 - **`Json` parses string input**: a JSON string posted from a form is parsed; parse failures surface as `:invalid` rather than being stored as the literal string.
 - **`TextArray` does not support `:contains`**: it backs a jsonb column where SQL `LIKE` doesn't apply. Use `:any_eq` for "array contains element".
 - **Orphaned values are skipped**: if a field row is deleted while values remain, `typed_eav_value` and `typed_eav_hash` silently skip the orphans rather than raising.
-- **Cross-scope writes are rejected**: assigning a `Value` to a record whose `typed_eav_scope` doesn't match the field's `scope` adds a validation error on `:field`.
+- **Cross-scope writes are rejected**: assigning a `Value` to a record whose `typed_eav_scope` doesn't match the field's `scope` adds a validation error on `:field`. The same guard covers the `parent_scope` axis.
+- **Orphan-parent rows rejected**: a `Field` or `Section` row with `parent_scope` set but `scope` blank is invalid. The `Value`-side guard rejects cross-`(scope, parent_scope)` writes too.
+- **Event hooks fire from `after_commit`**: the `on_value_change` and `on_field_change` callbacks fire after the database write is durable; their exceptions never break a save. See §"Event hooks" for the full contract.
+- **Versioning is opt-in**: When enabled (`TypedEAV.config.versioning = true` on the gem; `versioned: true` per host), every `:create` / `:update` / `:destroy` event on a Value writes an append-only audit row in `typed_eav_value_versions`. See §"Versioning" for the full contract.
+
+## Event hooks
+
+`typed_eav` fires `after_commit` events for value and field changes. Use them
+for audit logs, search-index synchronization, cache invalidation, or any
+out-of-band reaction that must wait until the database write is durable.
+
+### Public callback slots
+
+```ruby
+TypedEAV.configure do |c|
+  c.on_value_change = ->(value, change_type, context) {
+    # change_type ∈ [:create, :update, :destroy]
+    # context is a frozen Hash (see `with_context` below) — read-only
+  }
+
+  c.on_field_change = ->(field, change_type) {
+    # change_type ∈ [:create, :update, :destroy, :rename]
+    # NOTE: no context arg — field changes are CRUD-on-config, not
+    # per-entity user actions
+  }
+end
+```
+
+The `:rename` change_type fires whenever the field's `name` column changed
+in the just-committed save, even when bundled with other attribute changes
+(options, sort_order, default_value, etc.). The detection is intentionally
+escalating — Phase 7's materialized index needs to regenerate column DDL on
+every rename.
+
+`:update` on Value fires only when the typed value column changed. Saving
+a Value record without modifying its typed column (e.g., touching only
+bookkeeping columns) is a no-op for event dispatch.
+
+`field_dependent: :nullify` cascades produce **no** Value `:destroy`
+events. The FK `ON DELETE SET NULL` runs at the database level and
+bypasses AR callbacks. Only the Field `:destroy` event fires. Use
+`field_dependent: :destroy` if your consumer needs per-Value events on
+field deletion.
+
+### Thread-local context with `with_context`
+
+```ruby
+TypedEAV.with_context(request_id: request.uuid, actor_id: current_user.id) do
+  contact.update!(typed_eav: { phone: "555-1234" })
+  # on_value_change receives { request_id: "...", actor_id: 42 } as context
+end
+```
+
+`with_context` is a thread-local stack with shallow per-key merge:
+
+```ruby
+TypedEAV.with_context(request_id: "abc") do
+  TypedEAV.with_context(source: :bulk) do
+    # current context: { request_id: "abc", source: :bulk }
+  end
+  # current context: { request_id: "abc" }
+end
+# current context: {}
+```
+
+The current-context hash is frozen — callbacks cannot mutate it. Outer
+context is restored on exit even if the inner block raises.
+
+`TypedEAV.current_context` returns the current frozen Hash (or a shared
+frozen `{}` when no `with_context` block is active). It's safe to call
+from any code path; it never returns nil.
+
+### Error policy
+
+User callbacks (`Config.on_value_change`, `Config.on_field_change`) are
+rescued — exceptions are logged via `Rails.logger.error` and **do not
+propagate** to the user's save call. The save row is already committed
+when `after_commit` fires; re-raising would surface a misleading
+"save failed" error.
+
+This is the deliberate split with first-party features. Internal
+subscribers used by `typed_eav` itself (Phase 4 versioning, Phase 7
+materialized index) follow a different rule: their exceptions
+**propagate**. Versioning corruption must be loud.
+
+### Ordering guarantee
+
+When multiple subscribers are registered, they fire in this order:
+
+1. First-party internal subscribers (versioning, matview, etc.), in
+   registration order. Errors propagate.
+2. The user proc on `Config.on_value_change` / `Config.on_field_change`,
+   last. Errors are rescued and logged.
+
+Reassigning `Config.on_value_change` after gem initialization does **not**
+disable internal subscribers — they live on a separate dispatcher list
+and survive `Config.reset!`.
+
+### Test isolation
+
+Test files that exercise event hooks should opt in to the `:event_callbacks`
+metadata:
+
+```ruby
+RSpec.describe "my feature", :event_callbacks do
+  it "fires the hook" do
+    captured = []
+    TypedEAV::Config.on_value_change = ->(v, t, _ctx) { captured << [v.id, t] }
+    contact.update!(typed_eav: { phone: "555-1234" })
+    expect(captured).to include([be_a(Integer), :update])
+  end
+end
+```
+
+The `:event_callbacks` around hook in `spec/spec_helper.rb` snapshots and
+restores Config user procs and the internal-subscriber lists around each
+example, so test mutations don't leak across examples and engine-load
+registrations from later phases stay intact.
+
+Integration specs that create real AR records and need `after_commit` to
+fire durably should additionally opt in to `:real_commits`:
+
+```ruby
+RSpec.describe "my model", :event_callbacks, :real_commits do
+  # ...
+end
+```
+
+`:real_commits` disables transactional fixtures for the example and
+manually deletes typed_eav rows in FK order after.
+
+### Reset semantics
+
+| Method | What it resets |
+|---|---|
+| `TypedEAV::Config.reset!` | User procs (`on_value_change`, `on_field_change`) plus `field_types`, `scope_resolver`, `require_scope`. Does **not** clear internal subscribers. |
+| `TypedEAV::EventDispatcher.reset!` | Internal subscribers only. Does **not** touch Config. |
+
+Production code rarely calls either — they exist for test isolation and
+for the rare case where a host app wants to fully unwire the gem in a
+specific request lifecycle.
+
+## Versioning
+
+`typed_eav` ships an opt-in append-only audit log for changes to typed
+values. When enabled, each `:create` / `:update` / `:destroy` event on
+a Value writes a row to `typed_eav_value_versions` capturing the
+before-state, after-state, actor, context, and timestamp.
+
+Default off. Apps that don't enable it pay zero overhead — the Phase 04
+internal subscriber is not registered with `EventDispatcher.value_change_internals`
+at all when `Config.versioning = false`. Zero callable in the dispatcher
+chain, zero per-write method dispatch, zero per-write config read.
+
+### Enabling versioning
+
+Two steps:
+
+```ruby
+# 1. Set the gem-level master switch in an initializer.
+#    config/initializers/typed_eav.rb
+TypedEAV.configure do |c|
+  c.versioning = true
+  c.actor_resolver = -> { Current.user }   # optional; nil is permissive
+end
+
+# 2. Opt the host model in. Either via the kwarg form:
+class Contact < ApplicationRecord
+  has_typed_eav scope_method: :tenant_id, versioned: true
+end
+
+# Or via the concern (equivalent — pick whichever fits your conventions):
+class Contact < ApplicationRecord
+  has_typed_eav scope_method: :tenant_id
+  include TypedEAV::Versioned
+end
+```
+
+The two opt-in forms produce identical Registry state. The kwarg form is
+preferred for new code; the concern form fits codebases with established
+mixin-based feature wiring.
+
+### Querying history
+
+```ruby
+contact.typed_eav_attributes = [{ name: "age", value: 41 }]
+contact.save!
+contact.typed_eav_attributes = [{ name: "age", value: 42 }]
+contact.save!
+
+value = contact.typed_values.find_by(field: age_field)
+value.history          # most-recent-first relation
+# => [<ValueVersion change_type: "update" before: {"integer_value" => 41} after: {"integer_value" => 42}>,
+#     <ValueVersion change_type: "create" before: {} after: {"integer_value" => 41}>]
+
+value.history.first.changed_by   # => "42" (User#42 — coerced to id.to_s)
+value.history.first.context      # => { "request_id" => "abc-123" } if with_context was active
+```
+
+`value.history` is a chainable relation. Filter, paginate, pluck:
+
+```ruby
+value.history.where(change_type: "update").pluck(:changed_at, :changed_by)
+value.history.limit(5).each { |v| ... }
+```
+
+### Querying full audit history (including destroy events)
+
+`Value#history` returns versions where `value_id` matches the live Value
+record. After the live Value is destroyed, the FK `ON DELETE SET NULL`
+nullifies `value_id` on the existing version rows, and the new `:destroy`
+version is also written with `value_id: nil` (the parent
+`typed_eav_values` row is gone by `after_commit on: :destroy` time —
+writing a non-nil `value_id` would FK-fail at INSERT). So `Value#history`
+cannot surface destroy versions, and after Value destruction it can no
+longer be called at all.
+
+To query the FULL audit history for a given (entity, field), including
+destroy events and post-destruction lookup, use the entity-scoped query
+directly:
+
+```ruby
+TypedEAV::ValueVersion
+  .where(entity_type: contact.class.name, entity_id: contact.id, field_id: age_field.id)
+  .order(changed_at: :desc, id: :desc)
+# => [<ValueVersion change_type: "destroy" before: {"integer_value" => 42} after: {} value_id: nil>,
+#     <ValueVersion change_type: "update"  before: {"integer_value" => 41} after: {"integer_value" => 42} value_id: nil>,
+#     <ValueVersion change_type: "create"  before: {} after: {"integer_value" => 41} value_id: nil>]
+```
+
+This pattern is the canonical way to surface "what happened to this
+field on this entity" across the full lifecycle, including post-destroy.
+The `entity_type` + `entity_id` columns remain the durable identity even
+after the parent Value row is gone, and `field_id` survives because
+destroying a Value does not destroy its Field.
+
+For broader audit views — "show all version history across all fields
+for a given entity" (e.g., admin entity-history pages, compliance
+exports) — drop the `field_id` filter:
+
+```ruby
+TypedEAV::ValueVersion
+  .where(entity_type: contact.class.name, entity_id: contact.id)
+  .order(changed_at: :desc, id: :desc)
+# => all version rows for every typed field on this contact, most-recent-first.
+# Includes :create, :update, and :destroy events across every field the
+# entity has ever had a typed value for.
+```
+
+The field-scoped query (with `field_id:`) is the common case for
+"history of a single field"; the entity-scoped query (without `field_id:`)
+is the broad-audit case for "all version history across all fields for
+this entity".
+
+### Version row jsonb shape
+
+`before_value` and `after_value` are jsonb hashes keyed by typed-column
+name:
+
+| Field type | Snapshot shape (single key) |
+|---|---|
+| `text`, `email`, `url`, `color` | `{"string_value": "..."}` |
+| `long_text` | `{"text_value": "..."}` |
+| `integer` | `{"integer_value": 42}` |
+| `decimal` | `{"decimal_value": "10.5"}` |
+| `boolean` | `{"boolean_value": true}` |
+| `date` | `{"date_value": "2026-05-05"}` |
+| `date_time` | `{"datetime_value": "2026-05-05T12:00:00Z"}` |
+| `select` | `{"string_value": "..."}` |
+| `multi_select`, `*_array`, `json` | `{"json_value": [...]}` |
+
+Multi-cell field types (e.g., `Currency`) produce two-key snapshots:
+`{"decimal_value": "99.99", "string_value": "USD"}`. The version row's
+snapshot asks the field's storage contract for its cells, so new field
+types get the right shape automatically.
+
+`{}` (empty hash) and `{"<col>": null}` are distinct semantics:
+
+- `{}` means **no recorded value** — typical of `before_value` on a
+  `:create` event, or `after_value` on a `:destroy` event.
+- `{"<col>": null}` means **recorded nil** — the user explicitly
+  cleared the cell.
+
+### Reverting
+
+```ruby
+target = value.history.find_by(change_type: "update")
+value.revert_to(target)
+# value's typed columns now match target.before_value.
+# A NEW version row is written capturing the revert (append-only).
+```
+
+`revert_to` writes the targeted version's `before_value` columns back
+via `self[col] = …` and `save!`. The existing `after_commit` chain
+fires; the versioning subscriber writes a NEW version row whose
+`after_value` reflects the targeted version's `before_value`. The
+audit log is append-only — every revert is itself versioned.
+
+To record the intent of the revert, wrap the call in `with_context`:
+
+```ruby
+TypedEAV.with_context(reverted_from_version_id: target.id, actor: current_user) do
+  value.revert_to(target)
+end
+# The new version row's `context` column captures both keys.
+```
+
+`revert_to` raises `ArgumentError` in three documented conditions, checked in order:
+
+- when `version.value_id` is nil (the source Value was destroyed — destroy
+  versions have `value_id: nil` per the locked subscriber contract; you
+  can't restore a destroyed AR record by `save!`);
+- when the version's `before_value` is empty (the version represents a
+  `:create` event with no before-state to revert to);
+- when the version belongs to a different Value (`value_id` mismatch).
+
+In practice only `:update` versions are revertable. To restore a
+destroyed entity's typed values, create a new `TypedEAV::Value` record
+manually using `version.before_value` as the seed state.
+
+### Hook ordering guarantee
+
+Versioning is registered as an internal subscriber on
+`TypedEAV::EventDispatcher`. It runs **first** (slot 0) for every Value
+event. Your `Config.on_value_change` user proc fires **last**, after
+the version row is persisted:
+
+```
+Value#save! → after_commit → EventDispatcher.dispatch_value_change:
+  1. TypedEAV::Versioning::Subscriber.call  # writes version row
+  2. ... any other internal subscribers (Phase 7 matview, etc.) ...
+  3. Config.on_value_change user proc        # sees the persisted version
+```
+
+Internal subscriber errors propagate (versioning corruption is loud).
+User proc errors are rescued and logged via `Rails.logger.error` —
+the save itself already committed.
+
+### Actor resolution
+
+`Config.actor_resolver` mirrors `Config.scope_resolver`'s callable shape
+but returns whatever the app chooses (an AR record, a string, an integer,
+nil). The subscriber coerces non-nil returns via `id.to_s` (for AR
+records) or `to_s` (for scalars) before storing in the `changed_by`
+column (string, nullable).
+
+`nil` is the documented permissive sentinel: system writes, migrations,
+console-without-actor, and background jobs without a `with_context(actor:
+...)` wrap all flow through with `changed_by: nil`. This is intentional —
+forcing every Versioned write to have an actor would reject every console
+save and every migration backfill, which is hostile-by-default for a gem.
+
+Apps that need stricter enforcement do it inside the resolver:
+
+```ruby
+c.actor_resolver = -> { Current.user || raise(MyApp::ActorRequired) }
+```
+
+`Config.reset!` (documented in §"Event hooks") also resets `Config.versioning`
+to `false` and `Config.actor_resolver` to `nil`.
+
+### What versioning does not do
+
+- **No branching/merging across version chains.** Phase 4 ships event-log
+  shape only. Roadmap explicitly defers branching to a future design.
+- **No snapshot storage by default.** `typed_eav_value_versions` is an
+  event log — one row per change, not a full-row snapshot. For
+  high-volume apps that want snapshot storage, extend `ValueVersion` in
+  your own code (the gem keeps the event-log shape canonical so future
+  upgrades don't break your extension).
+- **No automatic `reverted_from_version_id` injection.** Use
+  `with_context` to record revert intent; the gem captures whatever
+  context the caller set.
+- **No per-Field versioning toggle.** Opt-in is per-entity (host model)
+  in Phase 4. Per-field granularity may land later if a real need
+  surfaces.
+- **No GIN indexes on `before_value` / `after_value` content.** Apps
+  that need to query inside the snapshot jsonb add their own indexes.
+  Phase 4 ships only the temporal indexes (`changed_at DESC` keyed on
+  `value_id`, `(entity_type, entity_id)`, and `field_id`).
+
+### Test isolation
+
+Specs that exercise versioning should opt into the `:event_callbacks`
+and `:real_commits` metadata flags (see §"Event hooks" — same pattern):
+
+```ruby
+RSpec.describe "my versioning behavior", :event_callbacks, :real_commits do
+  before do
+    TypedEAV.registry.register("Contact", versioned: true)
+    TypedEAV::Config.versioning = true
+    # CRITICAL: the :event_callbacks hook clears
+    # EventDispatcher.value_change_internals at example entry, so the
+    # engine-boot-registered subscriber is gone for the duration of
+    # the example. Re-register explicitly inside the before block.
+    # The hook's ensure block restores the snapshot — no leak.
+    TypedEAV::EventDispatcher.register_internal_value_change(
+      TypedEAV::Versioning::Subscriber.method(:call),
+    )
+  end
+  after { TypedEAV.registry.register("Contact", versioned: false) }
+
+  it "writes a version row" do
+    # ...
+  end
+end
+```
+
+The `:event_callbacks` around hook in `spec/spec_helper.rb` snapshot/
+restores `Config.versioning`, `Config.actor_resolver`, and the
+EventDispatcher subscriber lists around each example, so your changes
+don't leak to subsequent tests. The snapshot/restore CLEARS the
+internals list at example entry — that's why the re-registration
+above is required for any spec that needs the subscriber to fire. The
+`:real_commits` hook disables transactional fixtures (so `after_commit`
+fires durably) and cleans up `TypedEAV::ValueVersion` rows in
+FK-respecting order between examples.
 
 ## Database Support
 
 Requires PostgreSQL. The `text_pattern_ops` index on `string_value` and the jsonb `@>` containment operator are Postgres-specific. MySQL/SQLite support would require removing those index types and changing the array query operators.
 
+As of v0.2.0, the paired partial unique indexes cover the three-key partition tuple `(entity_type, scope, parent_scope)`. The orphan-parent invariant means the `WHERE scope IS NULL` partials don't include `parent_scope` — a global row always has `parent_scope` NULL too.
+
 ## Schema
 
 The gem creates four tables: