typed_eav 0.1.0 → 0.2.1

data/db/migrate/20260430000000_add_parent_scope_to_typed_eav_partitions.rb

@@ -0,0 +1,188 @@
+class AddParentScopeToTypedEAVPartitions < ActiveRecord::Migration[7.1]
+  # Production deployments may carry millions of rows in `typed_eav_fields` /
+  # `typed_eav_sections` by the time they upgrade. Concurrent index DDL keeps
+  # writes online during the rebuild — but it cannot run inside a DDL
+  # transaction, so we drop the implicit per-migration transaction and
+  # explicitly implement `up`/`down` (since `algorithm: :concurrently` is
+  # not auto-reversible from a `change` block).
+  disable_ddl_transaction!
+
+  def up
+    # 1. Add the nullable `parent_scope` column on both partition tables.
+    #    Postgres treats `ADD COLUMN ... NULL` as a catalog-only change — no
+    #    table rewrite, instantaneous regardless of row count, safe outside a
+    #    transaction.
+    add_column :typed_eav_fields, :parent_scope, :string
+    add_column :typed_eav_sections, :parent_scope, :string
+
+    # 2. Drop the existing scope-only paired-partial indexes plus the fields
+    #    lookup index. `if_exists: true` keeps re-runs idempotent (e.g., after
+    #    a partial failure on a long index drop).
+    remove_index :typed_eav_fields, name: :idx_te_fields_unique_scoped,
+                                    if_exists: true, algorithm: :concurrently
+    remove_index :typed_eav_fields, name: :idx_te_fields_unique_global,
+                                    if_exists: true, algorithm: :concurrently
+    remove_index :typed_eav_fields, name: :idx_te_fields_lookup,
+                                    if_exists: true, algorithm: :concurrently
+    remove_index :typed_eav_sections, name: :idx_te_sections_unique_scoped,
+                                      if_exists: true, algorithm: :concurrently
+    remove_index :typed_eav_sections, name: :idx_te_sections_unique_global,
+                                      if_exists: true, algorithm: :concurrently
+
+    # 3. Create the new triple-aware paired-partial unique indexes
+    #    (Option B split — see migration header) plus refreshed lookup
+    #    indexes.
+    #
+    #    Why three partials per table instead of two: Postgres unique
+    #    indexes treat NULL as distinct from NULL. A single partial
+    #    `(name, entity_type, scope, parent_scope) WHERE scope IS NOT NULL`
+    #    would NOT prevent two rows with `(name='f', entity_type='X',
+    #    scope='t1', parent_scope=NULL)` from coexisting — both satisfy
+    #    `scope IS NOT NULL` and `NULL ≠ NULL` keeps them distinct in the
+    #    unique key. Splitting into `_scoped_full` (parent_scope set) and
+    #    `_scoped_only` (parent_scope NULL) closes the hole using only
+    #    standard semantics, so we don't need `NULLS NOT DISTINCT` (PG ≥ 15).
+    #
+    #    Option A (`nulls_not_distinct: true`) was rejected because the
+    #    gemspec floor is `rails >= 7.1` and there is no PG-server-version
+    #    pin — consumer apps may run PG 12/13/14 where the option does
+    #    not exist.
+    #
+    #    The global partials (`scope IS NULL`) deliberately omit
+    #    `parent_scope` from the column list: the orphan-parent invariant
+    #    enforced at the model layer (plans 03/04) guarantees
+    #    `parent_scope IS NULL` whenever `scope IS NULL`, so a fourth
+    #    `(parent_scope NOT NULL, scope NULL)` partial would never be
+    #    populated.
+
+    # Fields — three partial unique indexes
+    add_index :typed_eav_fields,
+              %i[name entity_type scope parent_scope],
+              unique: true,
+              where: "scope IS NOT NULL AND parent_scope IS NOT NULL",
+              name: :idx_te_fields_uniq_scoped_full,
+              algorithm: :concurrently,
+              if_not_exists: true
+
+    add_index :typed_eav_fields,
+              %i[name entity_type scope],
+              unique: true,
+              where: "scope IS NOT NULL AND parent_scope IS NULL",
+              name: :idx_te_fields_uniq_scoped_only,
+              algorithm: :concurrently,
+              if_not_exists: true
+
+    add_index :typed_eav_fields,
+              %i[name entity_type],
+              unique: true,
+              where: "scope IS NULL",
+              name: :idx_te_fields_uniq_global,
+              algorithm: :concurrently,
+              if_not_exists: true
+
+    # Sections — three partial unique indexes
+    add_index :typed_eav_sections,
+              %i[entity_type code scope parent_scope],
+              unique: true,
+              where: "scope IS NOT NULL AND parent_scope IS NOT NULL",
+              name: :idx_te_sections_uniq_scoped_full,
+              algorithm: :concurrently,
+              if_not_exists: true
+
+    add_index :typed_eav_sections,
+              %i[entity_type code scope],
+              unique: true,
+              where: "scope IS NOT NULL AND parent_scope IS NULL",
+              name: :idx_te_sections_uniq_scoped_only,
+              algorithm: :concurrently,
+              if_not_exists: true
+
+    add_index :typed_eav_sections,
+              %i[entity_type code],
+              unique: true,
+              where: "scope IS NULL",
+              name: :idx_te_sections_uniq_global,
+              algorithm: :concurrently,
+              if_not_exists: true
+
+    # Lookup indexes — refreshed `idx_te_fields_lookup` with parent_scope and
+    # a brand-new `idx_te_sections_lookup` for parity. Section ordering helpers
+    # ship in Phase 2; adding the index now is one extra concurrent CREATE and
+    # avoids a follow-on migration.
+    add_index :typed_eav_fields,
+              %i[entity_type scope parent_scope sort_order name],
+              name: :idx_te_fields_lookup,
+              algorithm: :concurrently,
+              if_not_exists: true
+
+    add_index :typed_eav_sections,
+              %i[entity_type scope parent_scope sort_order name],
+              name: :idx_te_sections_lookup,
+              algorithm: :concurrently,
+              if_not_exists: true
+  end
+
+  def down
+    # 1. Drop the eight new indexes (six paired-partial + two lookup).
+    remove_index :typed_eav_fields, name: :idx_te_fields_uniq_scoped_full,
+                                    if_exists: true, algorithm: :concurrently
+    remove_index :typed_eav_fields, name: :idx_te_fields_uniq_scoped_only,
+                                    if_exists: true, algorithm: :concurrently
+    remove_index :typed_eav_fields, name: :idx_te_fields_uniq_global,
+                                    if_exists: true, algorithm: :concurrently
+    remove_index :typed_eav_fields, name: :idx_te_fields_lookup,
+                                    if_exists: true, algorithm: :concurrently
+    remove_index :typed_eav_sections, name: :idx_te_sections_uniq_scoped_full,
+                                      if_exists: true, algorithm: :concurrently
+    remove_index :typed_eav_sections, name: :idx_te_sections_uniq_scoped_only,
+                                      if_exists: true, algorithm: :concurrently
+    remove_index :typed_eav_sections, name: :idx_te_sections_uniq_global,
+                                      if_exists: true, algorithm: :concurrently
+    remove_index :typed_eav_sections, name: :idx_te_sections_lookup,
+                                      if_exists: true, algorithm: :concurrently
+
+    # 2. Restore the original five indexes verbatim from
+    #    db/migrate/20260330000000_create_typed_eav_tables.rb (using
+    #    `algorithm: :concurrently` for production safety; the original
+    #    migration ran inside a transaction without it, but the resulting
+    #    index definitions are identical).
+    add_index :typed_eav_fields,
+              %i[name entity_type scope],
+              unique: true,
+              where: "scope IS NOT NULL",
+              name: :idx_te_fields_unique_scoped,
+              algorithm: :concurrently,
+              if_not_exists: true
+    add_index :typed_eav_fields,
+              %i[name entity_type],
+              unique: true,
+              where: "scope IS NULL",
+              name: :idx_te_fields_unique_global,
+              algorithm: :concurrently,
+              if_not_exists: true
+    add_index :typed_eav_fields,
+              %i[entity_type scope sort_order name],
+              name: :idx_te_fields_lookup,
+              algorithm: :concurrently,
+              if_not_exists: true
+    add_index :typed_eav_sections,
+              %i[entity_type code scope],
+              unique: true,
+              where: "scope IS NOT NULL",
+              name: :idx_te_sections_unique_scoped,
+              algorithm: :concurrently,
+              if_not_exists: true
+    add_index :typed_eav_sections,
+              %i[entity_type code],
+              unique: true,
+              where: "scope IS NULL",
+              name: :idx_te_sections_unique_global,
+              algorithm: :concurrently,
+              if_not_exists: true
+
+    # 3. Drop the parent_scope columns last — sections first, then fields,
+    #    matching the inverse of `add_column` order in `up`.
+    remove_column :typed_eav_sections, :parent_scope
+    remove_column :typed_eav_fields, :parent_scope
+  end
+end

data/db/migrate/20260501000000_add_cascade_policy_to_typed_eav_fields.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+class AddCascadePolicyToTypedEAVFields < ActiveRecord::Migration[7.1]
+  def up
+    # Cascade policy column. String (not enum) for forward-compat with future
+    # policies; default "destroy" preserves v0.1.0 behavior. NOT NULL because
+    # the AR validator narrows to a closed set and the model relies on a
+    # non-nil value at every read.
+    add_column :typed_eav_fields, :field_dependent, :string,
+               null: false, default: "destroy"
+
+    # Allow Value rows to outlive their Field row when field_dependent is
+    # "nullify". The existing read-path orphan guards in
+    # InstanceMethods#typed_eav_value / typed_eav_hash already skip
+    # field-nil rows silently — see CONCERNS.md.
+    change_column_null :typed_eav_values, :field_id, true
+
+    # Drop and recreate the FK to switch ON DELETE CASCADE → ON DELETE SET
+    # NULL. PG requires drop-and-recreate for an ON DELETE policy change.
+    # Using the column-form helpers so we don't hardcode the auto-generated
+    # fk_rails_* constraint name.
+    remove_foreign_key :typed_eav_values, column: :field_id
+    add_foreign_key :typed_eav_values, :typed_eav_fields,
+                    column: :field_id, on_delete: :nullify
+  end
+
+  def down
+    # Reverse FK first (must precede NOT NULL restoration because any orphan
+    # rows would otherwise block change_column_null).
+    remove_foreign_key :typed_eav_values, column: :field_id
+    add_foreign_key :typed_eav_values, :typed_eav_fields,
+                    column: :field_id, on_delete: :cascade
+
+    # Re-impose NOT NULL. If any field_id IS NULL rows exist (created while
+    # the up-version was live), this raises — operator must clean them up
+    # before rolling back. Document in CHANGELOG when shipping.
+    change_column_null :typed_eav_values, :field_id, false
+
+    remove_column :typed_eav_fields, :field_dependent
+  end
+end

data/db/migrate/20260505000000_create_typed_eav_value_versions.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+class CreateTypedEAVValueVersions < ActiveRecord::Migration[7.1]
+  def change
+    # Append-only audit log of TypedEAV::Value mutations. Phase 04 versioning
+    # writes one row per :create / :update / :destroy event when the host
+    # entity opted in (via `has_typed_eav versioned: true` — landing in plan
+    # 04-02) AND the gem-level master switch is on (`config.versioning = true`).
+    #
+    # Storage shape decisions:
+    #   - before_value / after_value are jsonb keyed by typed-column name
+    #     (e.g., {"integer_value": 42}). Single-cell field types produce
+    #     one-key hashes; Phase 05 Currency will produce two-key hashes
+    #     ({"decimal_value": 99.99, "string_value": "USD"}). The {} default
+    #     means "no recorded value" (e.g., the before snapshot of a :create
+    #     event); {"<column>": null} means "recorded nil" (e.g., user
+    #     cleared the cell). Distinct semantics on purpose.
+    #   - changed_by is a plain string. Per Lead's plan-time decision (see
+    #     Plan §Plan-time decisions §1), the gem coerces actor_resolver
+    #     returns via the same `normalize_one`-style coercion that Phase 1
+    #     uses for scope (lib/typed_eav.rb:239-243). Apps that need
+    #     polymorphic actor querying resolve `changed_by` to a model on the
+    #     read side — `User.find_by(id: version.changed_by)`.
+    #   - context is jsonb so apps can store arbitrary `with_context`
+    #     payloads (request_id, source, anything the caller passed).
+    #     Default {} matches `TypedEAV.current_context`'s frozen-empty
+    #     return shape when no with_context block is active.
+    #   - changed_at is a separate column from created_at because callers
+    #     may want to record event-time vs persistence-time distinctly
+    #     (e.g., backfilling a historical version row from an external
+    #     audit log). Default to `Time.current` at write time in the
+    #     subscriber (plan 04-02); migration just declares NOT NULL.
+    create_table :typed_eav_value_versions do |t|
+      # Source row references. Both nullable + ON DELETE SET NULL so the
+      # audit log survives Value/Field destruction. Phase 02 made
+      # typed_eav_values.field_id ON DELETE SET NULL using exactly this
+      # pattern (db/migrate/20260501000000 lines 22-24). Same rationale:
+      # losing audit history because the live row was destroyed defeats
+      # the "append-only audit log" contract from 04-CONTEXT.md.
+      t.references :value,
+                   null: true,
+                   foreign_key: { to_table: :typed_eav_values, on_delete: :nullify }
+      t.references :field,
+                   null: true,
+                   foreign_key: { to_table: :typed_eav_fields, on_delete: :nullify }
+
+      # Polymorphic entity reference. Mirrors the typed_eav_values.entity
+      # pair exactly (Value belongs_to :entity polymorphic). NOT NULL
+      # because the entity tuple is the durable identity of a version
+      # row even after the Value (live cell) is destroyed — Phase 04
+      # consumers query history by `(entity_type, entity_id)`, not by
+      # value_id (which may be NULL). The polymorphic _type/_id columns
+      # default to NOT NULL via the t.references helper when null: false.
+      t.references :entity, polymorphic: true, null: false
+
+      # Actor identifier. Nullable per 04-CONTEXT.md §"actor_resolver
+      # returning nil" — system writes, migrations, console-without-actor,
+      # background jobs without `with_context(actor: ...)` all produce
+      # nil. Apps that need strict enforcement do it in their own
+      # actor_resolver lambda (`-> { Current.user || raise }`).
+      t.string :changed_by
+
+      # Snapshot columns. Default {} (NOT null) so the subscriber never
+      # writes nil — distinguishes "no recorded value" ({}) from "recorded
+      # nil" ({"<col>": null}). The change_type semantic is:
+      #   :create  → before_value: {},                after_value: {"<col>": <new>}
+      #   :update  → before_value: {"<col>": <old>},  after_value: {"<col>": <new>}
+      #   :destroy → before_value: {"<col>": <old>},  after_value: {}
+      # Phase 05 Currency emits two-key snapshots automatically when its
+      # `value_columns` override returns [:decimal_value, :string_value]
+      # (subscriber loops over value_columns).
+      t.jsonb :before_value, null: false, default: {}
+      t.jsonb :after_value,  null: false, default: {}
+
+      # `with_context` payload at write time (TypedEAV.current_context).
+      # Frozen Hash captured by EventDispatcher.dispatch_value_change
+      # (event_dispatcher.rb:89). Default {} matches the empty-context
+      # return shape; subscriber stores the captured Hash verbatim.
+      t.jsonb :context, null: false, default: {}
+
+      # Lifecycle metadata. change_type is a string (not enum) for forward
+      # compat — same rationale as Phase 02's field_dependent column
+      # (string-not-enum keeps schema migrations additive). Validator on
+      # the AR model narrows to the locked closed set.
+      t.string :change_type, null: false
+
+      # Event-time. Distinct from created_at to allow backfill scenarios
+      # where the subscriber writes a historical event-time. The :create
+      # / :update / :destroy normal path sets changed_at = Time.current
+      # in the subscriber (plan 04-02).
+      t.datetime :changed_at, null: false
+
+      t.timestamps
+    end
+
+    # Indexes — ship three at initial migration per Lead's plan-time
+    # decision (see Plan §Plan-time decisions §2). All use idx_te_vvs_*
+    # naming convention (matches CHANGELOG.md / Phase 1-2 idx_te_*
+    # precedent). DESC on changed_at because Value#history (plan 04-03)
+    # returns most-recent-first by default.
+    #
+    # No GIN index on before_value/after_value — deferred per CONTEXT.
+    # No partial unique indexes — multiple version rows per value_id are
+    # the whole point of the audit log.
+    add_index :typed_eav_value_versions,
+              %i[value_id changed_at],
+              order: { changed_at: :desc },
+              name: "idx_te_vvs_value"
+
+    add_index :typed_eav_value_versions,
+              %i[entity_type entity_id changed_at],
+              order: { changed_at: :desc },
+              name: "idx_te_vvs_entity"
+
+    add_index :typed_eav_value_versions,
+              %i[field_id changed_at],
+              order: { changed_at: :desc },
+              name: "idx_te_vvs_field"
+  end
+end

data/db/migrate/20260506000001_add_version_group_id_to_typed_eav_value_versions.rb

@@ -0,0 +1,76 @@
+class AddVersionGroupIdToTypedEAVValueVersions < ActiveRecord::Migration[7.1]
+  # Phase 06 — Bulk operations correlation tag.
+  #
+  # Adds a nullable, indexed `version_group_id` UUID column to
+  # `typed_eav_value_versions`. A bulk-write API (Plan 06-03) will inject
+  # the correlation tag via `TypedEAV.with_context(version_group_id: uuid)
+  # { ... }` and the Phase 04 versioning subscriber forwards it onto each
+  # ValueVersion row written during the bulk operation. Non-bulk writes
+  # leave the column NULL — backward-compatible with every row written
+  # by Phase 04's initial migration (`20260505000000_create_typed_eav_value_versions.rb`).
+  #
+  # ## Type rationale (uuid, not bigint or string)
+  #
+  # The correlation tag has no shared sequence — there's no parent
+  # `bulk_operations` row to FK to, and we deliberately do NOT introduce
+  # one (locked at 06-CONTEXT.md §version_group_id mechanism). UUID is the
+  # idiomatic choice for an unkeyed correlation token: 16 bytes vs 36 for
+  # a `:string` UUID, native Postgres equality / btree, and
+  # `SecureRandom.uuid` is the canonical Ruby generator. Postgres-only
+  # commitment is binding (ROADMAP §Cross-cutting requirements) so the
+  # `:uuid` column type is portable across all supported deployments.
+  #
+  # ## Nullability rationale
+  #
+  # Every existing version row was written without this column. Adding
+  # `null: false` would force a backfill, but there is no defensible
+  # value to backfill with — a per-row UUID would create a misleading
+  # signal that those historical rows were part of a bulk operation when
+  # they were not. Locked at 06-CONTEXT.md §version_grouping default:
+  # non-bulk writes leave the column NULL.
+  #
+  # ## Concurrent index DDL
+  #
+  # Mirrors the production-safety pattern from
+  # `db/migrate/20260430000000_add_parent_scope_to_typed_eav_partitions.rb:1-8`:
+  # `algorithm: :concurrently` cannot run inside a DDL transaction, so we
+  # `disable_ddl_transaction!` and implement explicit `up` / `down`
+  # methods (the auto-reverse from a `change` block does not understand
+  # `algorithm: :concurrently`). `if_not_exists:` / `if_exists:` keep
+  # re-runs idempotent on partial-failure recovery.
+  #
+  # ## Index naming
+  #
+  # `idx_te_vvs_group` joins the existing `idx_te_vvs_*` family on this
+  # table (CONVENTIONS.md §Naming line 117 — `vvs` = "value versions"
+  # keeps the four-character partition fits in Postgres' 63-byte limit).
+  disable_ddl_transaction!
+
+  def up
+    # 1. Add the nullable `version_group_id` UUID column. Postgres treats
+    #    `ADD COLUMN ... NULL` as a catalog-only change — no table rewrite,
+    #    instantaneous regardless of row count, safe outside a transaction.
+    add_column :typed_eav_value_versions, :version_group_id, :uuid
+
+    # 2. Concurrent btree index. The dominant read pattern (Plan 06+ /
+    #    consumer queries) is `WHERE version_group_id = ?` to fetch all
+    #    rows produced by a single bulk operation; a plain btree on the
+    #    column suffices. Composite indexes (e.g., `[entity_type,
+    #    version_group_id]`) are deferred until a workload justifies them.
+    add_index :typed_eav_value_versions,
+              :version_group_id,
+              name: "idx_te_vvs_group",
+              algorithm: :concurrently,
+              if_not_exists: true
+  end
+
+  def down
+    # Drop the index first, then the column — inverse of `up` order.
+    remove_index :typed_eav_value_versions,
+                 name: "idx_te_vvs_group",
+                 if_exists: true,
+                 algorithm: :concurrently
+
+    remove_column :typed_eav_value_versions, :version_group_id
+  end
+end

data/lib/generators/typed_eav/scaffold/templates/config/initializers/typed_eav.rb

@@ -3,8 +3,9 @@
 # TypedEAV configuration.
 #
 # `scope_resolver` is the single integration point for multi-tenancy /
-# partitioning. It's a callable that returns the current partition value
-# (a tenant id, account id, workspace id — whatever your app uses) or nil.
+# partitioning. It's a callable that returns `[scope, parent_scope]`
+# (tenant id, workspace id — whatever axes your app uses) or nil.
+# If you only use one partition axis, return `[scope, nil]`.
 #
 # Class-level queries like `Contact.where_typed_eav(...)` consult this
 # resolver when no explicit `scope:` kwarg or `TypedEAV.with_scope(...)`
@@ -21,13 +22,14 @@ TypedEAV.configure do |c|
   # no change is needed here.
 
   # --- Rails CurrentAttributes ---
-  # c.scope_resolver = -> { Current.account&.id }
+  # c.scope_resolver = -> { [Current.account&.id, nil] }
+  # c.scope_resolver = -> { [Current.account&.id, Current.workspace&.id] }
 
   # --- Custom Current-like class ---
-  # c.scope_resolver = -> { MyApp::Tenancy.current_workspace_id }
+  # c.scope_resolver = -> { [MyApp::Tenancy.current_tenant_id, MyApp::Tenancy.current_workspace_id] }
 
   # --- Subdomain / session / thread-local ---
-  # c.scope_resolver = -> { Thread.current[:org_id] }
+  # c.scope_resolver = -> { [Thread.current[:org_id], nil] }
 
   # --- Disable ambient resolution entirely (explicit `scope:` kwarg only) ---
   # c.scope_resolver = nil