typed_eav 0.8.0 → 0.8.1

data/docs/guides/schema.md

@@ -0,0 +1,134 @@
+---
+title: "Database schema and portability"
+---
+
+# Database schema and portability
+
+[Documentation home](../index.md)
+
+## 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 five tables:
+
+- `typed_eav_fields` - field definitions (STI, one row per field per entity type)
+- `typed_eav_values` - values (one row per entity per field, with typed columns)
+- `typed_eav_options` - allowed values for select/multi-select fields
+- `typed_eav_sections` - optional UI grouping
+- `typed_eav_value_versions` - opt-in, append-only audit history for Value
+  create, update, and destroy events; it retains durable entity identity even
+  when the live Value row is later removed
+
+## Exporting and importing definitions
+
+Use the portable export to copy field and section definitions between databases:
+
+```ruby
+schema = TypedEAV::SchemaPortability.export_schema(
+  entity_type: Contact.polymorphic_name, scope: "t1", parent_scope: nil
+)
+File.write("contact-schema.json", JSON.pretty_generate(schema))
+
+# In the destination application, after installing the gem's migrations:
+schema = JSON.parse(File.read("contact-schema.json"))
+result = TypedEAV::SchemaPortability.import_schema(schema, on_conflict: :error)
+result # => {"created" => 3, "updated" => 0, "skipped" => 0,
+       #     "unchanged" => 0, "errors" => []} (example counts)
+```
+
+The string-keyed envelope has `schema_version: 1`, `entity_type`, `scope`,
+`parent_scope`, `fields`, and `sections`. Export selects the **exact tuple**;
+it does not merge inherited global definitions. Export each required partition
+separately. It includes field types, raw labels, defaults, options, option rows,
+and section properties. It excludes host records, Value rows, audit history,
+database IDs, and field-to-section associations. It is not a database backup.
+Custom field classes used by an export must also exist in the receiving app.
+
+Import matches fields by name and partition, and sections by code and partition.
+Identical entries increment `unchanged`. Divergent entries raise `ArgumentError`
+under the default `:error` policy; `:skip` increments `skipped`, and `:overwrite`
+updates the definition and increments `updated`. New entries increment `created`.
+Counts combine fields and sections. Overwriting an optionable field replaces
+its option rows; omitted definitions are retained. Existing values are neither
+converted nor backfilled when defaults or constraints change.
+
+Import runs in one transaction. Unsupported schema versions or conflict policies,
+divergent definitions under `:error`, and all field type swaps raise
+`ArgumentError`; model validation failures raise Active Record exceptions.
+Failures roll back the import and propagate: `errors` is currently an empty
+compatibility slot, **not** a collected failure report.
+
+The importer uses each entry's partition identity. To deliberately copy to a
+different tenant, update `entity_type`, `scope`, and `parent_scope` in both the
+envelope and **every** field and section entry before previewing/importing.
+Changing only the envelope does not retarget the imported rows. Preview first
+when importing into an existing partition.
+
+## Snapshot schema for application exports
+
+```ruby
+snapshot = TypedEAV::SchemaPortability.export_snapshot_schema(
+  entity_type: Contact.polymorphic_name, scope: "t1"
+)
+snapshot["snapshot_schema_version"] # => 1
+snapshot["fields"].map { |field| [field["name"], field["display_name"]] }
+```
+
+This read-only Hash is a smaller projection for applications packaging typed
+values with enough field metadata to render or interpret them later. Each field
+contains `name`, `field_type_name`, resolved `display_name`, `required`,
+`sort_order`, and `options`; optionable fields also contain `options_data`.
+Non-optionable fields omit that key. Fields are ordered by `sort_order`.
+
+Unlike the portable export, the snapshot omits sections, partition identity,
+STI class names, defaults, and `field_dependent`. Capture the owning partition
+and values separately if your application needs them. Consumers should check
+`snapshot_schema_version`; `field_type_name` survives namespace moves but changes
+if a field's leaf class is renamed. There is no matching snapshot-import API:
+use `export_schema` / `import_schema` for definition round trips.
+
+## Read-only schema previews
+
+```ruby
+schema = TypedEAV::SchemaPortability.export_schema(
+  entity_type: "Contact", scope: "t1"
+)
+schema["fields"].first["required"] = true
+preview = TypedEAV::SchemaPortability.preview_schema(schema, on_conflict: :overwrite)
+preview["fields"].first["changes"]
+# => {"required" => {"from" => false, "to" => true}}
+preview["risks"] # => ["required_false_to_true"]
+```
+
+The preview compares a version-1 portable export with the database's exact
+target partition. It requires the envelope's `entity_type`, `scope`, and
+`parent_scope` to match every entry; mixed-target payloads and duplicate
+identities are rejected. This intentionally stricter preview input does not
+change `import_schema` or silently retarget definitions.
+
+The plain Hash result contains envelope metadata, `summary`, `fields`,
+`sections`, `risks`, and `importable`. Each entry includes its exact `identity`,
+`status` (`unchanged`, `added`, `changed`, or `conflict`), conditional `action`,
+and attribute `changes` with `from`/`to` values. Field entries also contain
+option-row `added`, `removed`, and `changed` lists, matched by option value.
+Raw option ordering and key-presence differences remain visible because the
+importer compares the complete exported payload, not just equivalent settings.
+
+`on_conflict: :error` blocks divergent definitions; `:skip` leaves them alone;
+`:overwrite` predicts an update. Type swaps always produce an error action,
+even under skip/overwrite. Risks flag type changes, removed options, newly
+required fields, and changes to options, defaults, or field dependencies.
+Omitted target definitions are **not deletions** and are not listed as such.
+
+`importable: true` means no known conflict-policy/type-swap blocker was found,
+not that validation or a later import is guaranteed to succeed. Actions are
+conditional predictions: a blocking error aborts the existing transactional
+import, including otherwise acceptable additions. Previewing does not save
+definitions, run mutation/validation callbacks, enqueue jobs, execute DDL, or
+convert values. It is an advisory snapshot, not a lock or reservation; model
+validations and concurrent changes still apply to the actual import.

data/docs/guides/scoping.md

@@ -0,0 +1,254 @@
+---
+title: "Multi-tenant scoping"
+---
+
+# Multi-tenant scoping
+
+[Documentation home](../index.md)
+
+**Scope selects field definitions; it does not authorize or filter host records. Apply tenant and authorization filters to the host relation.**
+
+## Multi-Tenant Scoping
+
+Field definitions are partitioned by a `scope` column so multiple tenants (or accounts, workspaces, orgs — any partition key your app uses) can each define their own fields without collisions. Fields with `scope = NULL` are global, visible to every partition.
+
+### Declaring a scoped model
+
+```ruby
+class Contact < ApplicationRecord
+  has_typed_eav scope_method: :tenant_id
+end
+```
+
+`scope_method:` names an instance method on your model. When the record reads its own field definitions (e.g., in a form), that method tells TypedEAV which partition the record belongs to.
+
+### Class-level queries resolve scope automatically
+
+Queries like `Contact.where_typed_eav(...)` consult an **ambient scope resolver** — no need to pass `scope:` on every call:
+
+```ruby
+# The resolver tells TypedEAV which partition is active.
+Contact.where_typed_eav({ name: "age", op: :gt, value: 21 })
+```
+
+The resolver chain (highest priority first):
+
+1. Explicit `scope:` keyword argument on the query
+2. Active `TypedEAV.with_scope(value) { ... }` block
+3. Configured `TypedEAV.config.scope_resolver` callable
+4. `nil`
+
+If every step returns `nil` and the model declared `scope_method:`, queries raise `TypedEAV::ScopeRequired` — the **fail-closed default**. This is the whole point: forgetting to set scope can't silently leak other partitions' data.
+
+### Wiring the resolver
+
+Pick the pattern that matches your app and set it once in `config/initializers/typed_eav.rb`:
+
+```ruby
+TypedEAV.configure do |c|
+  # acts_as_tenant (auto-detected — no config needed if loaded)
+  # c.scope_resolver = -> { [ActsAsTenant.current_tenant&.id, nil] }
+
+  # Rails CurrentAttributes
+  # c.scope_resolver = -> { [Current.account&.id, nil] }
+
+  # Custom class
+  # c.scope_resolver = -> { [MyApp::Tenancy.current_workspace_id, nil] }
+
+  # Subdomain / session / thread-local
+  # c.scope_resolver = -> { [Thread.current[:org_id], nil] }
+
+  # Disable ambient resolution entirely
+  # c.scope_resolver = nil
+
+  c.require_scope = true  # fail-closed (default). Set false for gradual adoption.
+end
+```
+
+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](upgrading.md#migrating-from-v01x) for
+the upgrade path.
+
+### Block APIs
+
+```ruby
+# Run a block with a specific ambient scope (background jobs, console, rake tasks):
+TypedEAV.with_scope(tenant_id) do
+  Contact.where_typed_eav({ name: "status", op: :eq, value: "active" })
+end
+
+# Escape hatch for admin tools, migrations, or cross-tenant audits:
+TypedEAV.unscoped do
+  Contact.where_typed_eav({ name: "status", op: :eq, value: "active" })
+  # returns matches across ALL partitions
+end
+```
+
+Both are exception-safe via `ensure` and nest cleanly.
+
+`unscoped` is an explicit administrative/analytics escape hatch, not the
+ordinary tenant request path. It keeps every same-name definition across the
+visible partitions and unions their matches for each filter. For broad audits
+or migrations, bound the definition universe to the work you actually need and
+batch the job at an application-owned boundary. TypedEAV does not prescribe a
+universal limit or batch size; measure generated SQL, planning/execution,
+memory, and workload interference in your application. Keep normal request
+traffic on scoped resolution so global, scope-only, and full-tuple definitions
+collapse to the most-specific match.
+
+### Explicit `scope:` override
+
+Any query method accepts `scope:` as an override for admin tools and tests:
+
+```ruby
+Contact.where_typed_eav({ name: "status", value: "active" }, scope: "t1")
+Contact.with_field("age", :gt, 21, scope: "t1")
+```
+
+Explicit wins over ambient. Passing `scope: nil` explicitly (as opposed to omitting the kwarg) means "filter to global fields only" — useful for admin UIs that want to see unscoped field definitions without activating `unscoped` mode.
+
+### Background jobs
+
+ActiveJob (including Sidekiq via the ActiveJob adapter) wraps every `perform` in Rails' executor, which already clears `ActiveSupport::CurrentAttributes` between jobs — so if your resolver reads from `Current.account`, each job starts clean. For raw `Sidekiq::Job` (no ActiveJob), wrap the job body manually:
+
+```ruby
+class ExportJob
+  include Sidekiq::Job
+
+  def perform(tenant_id, ...)
+    TypedEAV.with_scope(tenant_id) do
+      Contact.where_typed_eav(...)
+    end
+  end
+end
+```
+
+### Disabling enforcement for gradual adoption
+
+If your app has existing typed-eav queries that don't yet pass scope, flip `require_scope` to `false` in the initializer. When no scope resolves, queries fall back to **global fields only** (definitions stored with `scope: nil`) instead of raising — they do **not** return all partitions' fields. Audit and fix callers, then flip back to `true`.
+
+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.
+
+### 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.
+
+The shipped migration chain also includes
+`EnforceParentScopeInvariant`, which declares the database check constraints
+nontransactionally and validates them after its preflight, and
+`UsePartialCoveringScalarIndexes`, which creates the six `*_present` indexes
+before removing their legacy counterparts. Both migrations use
+`disable_ddl_transaction!`; run them through the normal migration command and
+do not wrap them in an application transaction.
+
+### 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.
+
+`TypedEAV.unscoped { Contact.where_typed_eav(...) }` OR-across every partition's matching `field_id` per filter (still AND-ing across filters), so cross-tenant audit queries see every partition's matches — they don't collapse to a single tenant.
+
+Because that administrative path constructs work for every matching
+definition, applications should narrow and batch high-cardinality audits rather
+than treating `unscoped` as tenant-request routing. No built-in numeric
+threshold is implied; choose operational bounds from measurements of the
+consuming workload. See [ADR 0012](../adr/0012-cross-scope-administrative-query-policy.md).
+
+## Partition helpers for custom management interfaces
+
+These helpers take an **explicit, already-resolved tuple**; they do not consult
+ambient scope or apply application authorization. For example, after authorizing
+access to a tenant's field management page:
+
+```ruby
+partition = {
+  entity_type: Contact.polymorphic_name,
+  scope: current_tenant.id.to_s,
+  parent_scope: nil
+}
+visible = TypedEAV::Partition.visible_fields(**partition) # AR relation
+fields = TypedEAV::Partition.effective_fields_by_name(**partition) # name => Field
+sections = TypedEAV::Partition.visible_sections(**partition).active.sorted
+section = TypedEAV::Partition.find_visible_section!(params[:section_id], **partition)
+```
+
+`visible_fields` includes global, scope-only, and full-tuple definitions.
+`effective_fields_by_name` collapses same-name collisions to the most specific
+field. If you already loaded a visibility-filtered collection, use
+`definitions_by_name(collection)` for the same collapse or
+`definitions_multimap_by_name(collection)` for a name-to-array grouping. Those
+two collection helpers do not filter the input for you.
+
+Sections use the same visibility layers, without name-based collision collapse.
+`find_visible_section!` returns a section by ID within those layers and raises
+`ActiveRecord::RecordNotFound` for missing, blank, or out-of-partition IDs.
+Visibility includes inherited definitions; before editing a global definition,
+apply your application's permission policy for changing shared schema.
+
+The visibility helpers accept `mode: :all_partitions` as an explicit admin bypass.
+In that mode `effective_fields_by_name` returns arrays per name, not single fields.
+Always supply `entity_type` for an interface serving one model: `visible_fields`
+alone allows it to be omitted. Under ordinary `mode: :partition`, `scope: nil`
+means global-only; a nonblank parent without a scope raises `ArgumentError`.
+Unknown modes raise `ArgumentError` as well.

data/docs/guides/upgrading.md

@@ -0,0 +1,26 @@
+---
+title: "Upgrading"
+nav_group: Project
+---
+
+# Upgrading
+
+[Documentation home](../index.md)
+
+### 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](https://github.com/dchuk/typed_eav/blob/main/CHANGELOG.md) for the full upgrade checklist.

data/docs/guides/usage.md

@@ -0,0 +1,259 @@
+---
+title: "Reading, writing, and forms"
+---
+
+# Reading, writing, and forms
+
+[Documentation home](../index.md)
+
+## Model setup
+
+```ruby
+class Contact < ApplicationRecord
+  has_typed_eav
+end
+
+# With multi-tenant scoping:
+class Contact < ApplicationRecord
+  has_typed_eav scope_method: :tenant_id
+end
+
+# With restricted field types:
+class Contact < ApplicationRecord
+  has_typed_eav types: [:text, :integer, :boolean, :select]
+end
+```
+
+## Field definitions
+
+```ruby
+# Simple fields
+TypedEAV::Field::Text.create!(
+  name: "nickname",
+  entity_type: "Contact"
+)
+
+TypedEAV::Field::Integer.create!(
+  name: "age",
+  entity_type: "Contact",
+  required: true,
+  options: { min: 0, max: 150 }
+)
+
+TypedEAV::Field::Date.create!(
+  name: "birthday",
+  entity_type: "Contact",
+  options: { max_date: Date.today.to_s }
+)
+
+# Select field with options
+status = TypedEAV::Field::Select.create!(
+  name: "status",
+  entity_type: "Contact",
+  required: true
+)
+status.field_options.create!([
+  { label: "Active",   value: "active",   sort_order: 1 },
+  { label: "Inactive", value: "inactive", sort_order: 2 },
+  { label: "Lead",     value: "lead",     sort_order: 3 },
+])
+
+# Multi-select (stored as json array)
+tags = TypedEAV::Field::MultiSelect.create!(
+  name: "tags",
+  entity_type: "Contact"
+)
+tags.field_options.create!([
+  { label: "VIP",      value: "vip" },
+  { label: "Partner",  value: "partner" },
+  { label: "Prospect", value: "prospect" },
+])
+```
+
+When deriving `entity_type` from a model class, use
+`Contact.polymorphic_name`. Rails stores polymorphic associations under that
+canonical name, which is the base-class type for STI hosts and respects the
+application's namespaced-polymorphism setting.
+
+## Reading and writing
+
+```ruby
+contact = Contact.new(name: "Darrin")
+
+# Individual assignment
+contact.set_typed_eav_value("age", 40)
+contact.set_typed_eav_value("status", "active")
+
+# Bulk assignment by field NAME (ergonomic for scripting / seeds)
+contact.typed_eav_attributes = [
+  { name: "age", value: 40 },
+  { name: "status", value: "active" },
+  { name: "tags", value: ["vip", "partner"] },
+]
+
+# Bulk assignment by field ID (standard Rails form contract).
+# Your form templates emit this shape when you use fields_for :typed_values.
+contact.typed_values_attributes = [
+  { id: 12, field_id: 4, value: "40" },
+  { field_id: 7, value: "active" },
+]
+
+contact.save!
+
+# Reading
+contact.typed_eav_value("age")    # => 40 (Ruby Integer)
+contact.typed_eav_value("status") # => "active"
+contact.typed_eav_hash              # => { "age" => 40, "status" => "active", ... }
+```
+
+## Defaults for new and existing records
+
+```ruby
+field = TypedEAV::Field::Integer.create!(
+  name: "score", entity_type: Contact.polymorphic_name,
+  default_value: 10, options: { min: 0 }
+)
+contact = Contact.new(name: "Ada")
+contact.initialize_typed_values
+contact.typed_eav_value("score") # => 10
+contact.save!
+
+# Apply this field's default to an existing population:
+field.backfill_default!(relation: Contact.where(active: true))
+```
+
+Set the record's tenant/workspace before initializing values.
+`initialize_typed_values` builds one unsaved Value for each effective definition
+that has no row yet, using that field's default (possibly `nil`). It returns
+the `typed_values` association, leaves existing values alone, and saves nothing
+until the host is saved. The form helper uses this initialization behavior.
+Creating a field or reading a missing value does not populate existing hosts.
+
+When building a Value directly, omitting `value:` applies the field default;
+passing `value: nil` explicitly stores NULL instead:
+
+```ruby
+contact.typed_values.build(field: field)             # default of 10
+contact.typed_values.build(field: field, value: nil) # explicit NULL
+# These illustrate alternatives; do not create both for the same host/field.
+```
+
+Defaults are cast and validated when the field is saved. Backfill is synchronous
+and idempotent: it creates missing rows or replaces fully NULL typed values,
+while preserving existing non-NULL values, including `false` and zero. Multi-cell
+fields count as present if any declared typed cell is non-NULL. A `nil` default
+performs no writes.
+
+Without `relation:`, backfill scans the field's host class. A supplied relation
+must belong to that exact host class (an Array or a subclass relation raises
+`ArgumentError`); it narrows the population before batches of 1,000. Partition
+checks still apply. Each batch uses a transaction and normal Value validations,
+callbacks, and enabled versioning. Failures propagate and roll back the current
+batch; previous batches remain committed unless enclosed in a caller transaction.
+The method has no documented count/result report. For background processing,
+call it from an application-owned job. See [bulk operations](bulk-operations.md)
+for related write guarantees.
+
+## Forms
+
+Wire typed fields into Rails forms via nested attributes:
+
+```erb
+<%= form_with model: @contact do |f| %>
+  <%= f.text_field :name %>
+
+  <%= render_typed_value_inputs(form: f, record: @contact) %>
+
+  <%= f.submit %>
+<% end %>
+```
+
+The helper emits one input per available field, including the hidden `id` / `field_id` markers required by `accepts_nested_attributes_for`. Permit the nested shape in your controller — the `value: []` form is required for array/multi-select types:
+
+```ruby
+def contact_params
+  params.require(:contact).permit(
+    :name,
+    typed_values_attributes: [
+      :id, :field_id, :_destroy, :value, { value: [] }
+    ]
+  )
+end
+```
+
+For list pages, preload the field association to avoid N+1:
+
+```ruby
+@contacts = Contact.includes(typed_values: :field).all
+```
+
+## Admin Scaffold
+
+To manage field definitions through a UI, run the scaffold generator:
+
+```bash
+bin/rails g typed_eav:scaffold
+bin/rails db:migrate
+```
+
+This copies a controller, views, helper, Stimulus controllers, and an initializer into your app, and adds routes mounted at `/typed_eav_fields`.
+
+**Security**: the generated controller ships with `authorize_typed_eav_admin!` returning `head :not_found` by default — fail-closed. Edit the method directly in `app/controllers/typed_eav_controller.rb` to wire it to your auth system:
+
+```ruby
+def authorize_typed_eav_admin!
+  return if current_user&.admin?
+  head :not_found
+end
+```
+
+Defining `authorize_typed_eav_admin!` in `ApplicationController` does **not** override it — the scaffold sets it on its own controller.
+
+## In-memory typed-value changes
+
+```ruby
+contact.set_typed_eav_value("age", 41)
+contact.typed_eav_changes # => {"age" => [40, 41]}
+contact.save!
+contact.typed_eav_changes # => {}
+```
+
+`typed_eav_changes` reports logical `[before, after]` pairs for pending changes
+on this host's in-memory `typed_values` target. It covers named setters,
+`typed_eav_attributes=`, nested `typed_values_attributes=`, association builds,
+edits to target Values, and `mark_for_destruction`/nested `_destroy`. Multi-cell
+fields such as Currency retain their logical shape; returned hashes, pairs,
+and mutable values are copies. Same-value assignments, reversions, and logical
+`nil`-to-`nil` changes are omitted, including creating/removing a NULL value row.
+Invalid input reports the cast logical result without discarding validation errors.
+
+Failed saves retain pending state; successful saves and reload clear it. An
+outer rollback follows Active Record's restored child dirty state. The API
+resolves effective field names using this record's partition precedence, and
+does not load all persisted Values merely to inspect an untouched host.
+
+After saving, `saved_typed_eav_changes` exposes the most recent successful
+host save's logical pairs:
+
+```ruby
+contact.set_typed_eav_value("age", 42)
+contact.save!
+contact.saved_typed_eav_changes # => {"age" => [41, 42]}
+contact.typed_eav_changes       # => {}
+```
+
+Saved changes are available in normal host `after_save` callbacks, including
+values assigned by `before_save`. Each successful save replaces the snapshot;
+a no-op save replaces it with `{}`. Failed validation or a save-callback
+exception preserves the previous successful snapshot. Reload and an outer
+transaction rollback clear saved changes. These are successful-save semantics,
+not proof of a durable commit: use `after_commit` when external effects must
+wait for commit. Exceptions after a transaction has already committed cannot
+undo persisted data. Neither dirty API requires versioning or adds audit rows.
+
+This is in-memory editing state, not audit history. Independently loaded/saved
+Values, reassignment of an existing Value's field identity, SQL/`delete_all`,
+and collection operations that immediately remove rows from the host target
+are not tracked. Use nested destruction or `mark_for_destruction` for tracked
+removal. Reduced `BulkUpsert` does not update unrelated in-memory host objects;
+reload them after external writes. Bulk reads do not create dirty state.