typed_eav 0.8.0 → 0.8.1

data/docs/guides/architecture.md

@@ -0,0 +1,125 @@
+---
+title: "Architecture"
+nav_group: Project
+---
+
+# Architecture
+
+[Documentation home](../index.md)
+
+Current internal module layout. Most consumers never reach for these directly — the public surface is the `has_typed_eav` macro and the instance/class methods it installs — but the split matters if you're extending the gem, debugging an integration, or evaluating it for production. Decisions are anchored by ADR-0001 through ADR-0013.
+
+## Macro entry: `HasTypedEav`
+
+`lib/typed_eav/has_typed_eav.rb` (~120 LOC) is the macro shell. When you call `has_typed_eav` on an AR model, it:
+
+1. `extend`s `TypedEAV::EntityQuery` onto the class (class-level query methods).
+2. `include`s `TypedEAV::HasTypedEav::InstanceMethods` (per-record accessors).
+3. Wires scope/parent-scope kwargs into the model's class-level configuration.
+4. Registers the model with `TypedEAV::Registry`.
+
+The macro is intentionally thin. All real behavior lives in the modules it pulls in.
+
+## Class-level reads: two-altitude query pattern
+
+```
+Contact.where_typed_eav(...)         ← public class method
+       │
+       ▼
+TypedEAV::EntityQuery                 ← high altitude: orchestrator
+  • resolves scope/parent_scope from ambient context or explicit kwargs
+  • owns the UNSET_SCOPE / ALL_SCOPES sentinels
+  • delegates to FilterQuery
+       │
+       ▼
+TypedEAV::FilterQuery                 ← multi-filter composition
+  • normalizes filter input shapes (positional, hash, hash-of-hashes)
+  • looks up field definitions via TypedEAV::Partition
+  • per filter, asks QueryBuilder for the SQL fragment
+  • unions/intersects per-field entity-id sets
+  • returns an ActiveRecord::Relation scoped to the host model
+       │
+       ▼
+TypedEAV::QueryBuilder                ← low altitude: per-field SQL primitive
+  • turns a single (field, op, value) into a WHERE clause against typed_eav_values
+  • knows about typed-column projections (integer_value, string_value, etc.)
+  • knows about operator-specific column choice (currency-cents vs currency-code)
+```
+
+`QueryBuilder` is the single place that decides "given this field and this operator, which column and which SQL fragment?" `FilterQuery` never builds SQL fragments directly; `EntityQuery` never touches columns. Splitting the two altitudes keeps custom field types extending only the column-mapping surface (`value_column`, `operators`, `operator_column`) without ever subclassing `FilterQuery`.
+
+Scalar ordering and summaries are a separate `EntityQuery` delegation to
+`ScalarQuery`: it resolves one winning definition, checks scalar support, and
+builds SQL over the field's declared native column. It does not add operators
+to the filter DSL or load the host/Value graph to calculate summaries.
+
+## Per-record reads/writes: `InstanceMethods`
+
+`lib/typed_eav/has_typed_eav/instance_methods.rb` (~250 LOC) holds the per-record API:
+
+- `typed_eav_value(name)` / `typed_eav_hash` — reads
+- `set_typed_eav_value(name, value)` / `typed_eav_attributes=` (aliased as `typed_eav=`) — writes
+- `typed_eav_definitions` — resolved field-definitions map for the host record
+- `typed_eav_scope` / `typed_eav_parent_scope` — scope resolution per record
+
+Every method uses `TypedEAV::Partition.definitions_by_name` so the collision-precedence rules for ambient/explicit/parent scopes are computed in one place.
+
+## Partition visibility: `Partition`
+
+Host applications that need to inspect effective schema should use the
+documented-public `TypedEAV::Partition` seam rather than rebuilding tuple
+predicates. It exposes `visible_fields`, `effective_fields_by_name`,
+`definitions_by_name`, `definitions_multimap_by_name`, `visible_sections`,
+and `find_visible_section!`. These methods preserve global, scope-only, and
+full-tuple precedence; ADR-0006 additionally fixes include-missing set
+composition at the `FilterQuery` altitude.
+
+## Field types and storage: `Field::TypedStorage`
+
+`TypedEAV::Field::Base` is the STI parent of every field type. The shared storage surface lives in the `TypedEAV::Field::TypedStorage` concern (`lib/typed_eav/field/typed_storage.rb`, ~200 LOC), auto-included on `Field::Base`. Per [ADR-0001](../adr/0001-collapse-column-mapping-stack.md), it provides:
+
+- **Class DSL**: `value_column`, `value_columns`, `operators`, `operator_column`, `supported_operators` — describe where typed values live and which operators they support.
+- **Instance override points**: `read_value(record)`, `write_value(record, casted)`, `apply_default(record)` — the three methods a multi-cell field type overrides.
+- **Concrete snapshot helpers**: `value_changed?`, `before_snapshot`, `after_snapshot` — derived automatically from `value_columns`; not overridable.
+
+Custom multi-cell field types subclass `Field::Base` directly and override only the three instance methods. See [Multi-cell field types](fields.md#multi-cell-field-types) for `Currency` as the canonical worked example.
+
+## Field families: intermediate STI bases
+
+Per [ADR-0004](../adr/0004-field-family-intermediate-bases.md), three intermediate STI parents factor shared validation behavior out of `Field::Base`:
+
+- **`TypedEAV::Field::ValidatedString`** — parent of `Text`, `Email`, `Url`. Owns string-length and pattern-validation helpers including `max_gte_min_length` (which now covers Email/Url, not just Text).
+- **`TypedEAV::Field::RangeBounded`** — parent of `Integer`, `Decimal`, `Date`, `DateTime` (and `Percentage < Decimal`). Owns range-validation helpers including `validates :max, comparison: { greater_than_or_equal_to: :min }` (which now covers Date/DateTime, not just Integer/Decimal).
+- **`TypedEAV::Field::Optionable`** — a Rails concern included by `Select` and `MultiSelect`. Owns the public-facing sorted `allowed_values` reader and the option-inclusion validators.
+
+`Color`, `Boolean`, `Json`, and the array field types (`TextArray`, `IntegerArray`, `DecimalArray`, `DateArray`) remain direct children of `Field::Base`. See [Family intermediate bases](fields.md#family-intermediate-bases-extension-points) for extension examples.
+
+## Scope tuple normalization: `ScopeTuple`
+
+`TypedEAV::ScopeTuple` (`lib/typed_eav/scope_tuple.rb`, ~120 LOC) is the canonical source of truth for the `(scope, parent_scope)` partition tuple. It provides:
+
+- `normalize_permissive(scope)` — coerces input to a tuple; tolerates bare scalars (used by `with_scope`, `normalize_scope`, `Field#validate_parent_scope_invariant`).
+- `normalize_strict(scope)` — same shape, but raises on bare-scalar input (used by `current_scope`; preserves Phase-1's asymmetric contract that `Config.scope_resolver` must return a tuple).
+- `invariant_satisfied?(scope, parent_scope)` — Boolean check for the orphan-parent invariant (`parent_scope` set without `scope` = invalid).
+
+Each calling site keeps its own response policy (raise / AR error / silent narrow) using the Boolean return — `ScopeTuple` is a predicate, not an enforcer.
+
+## Partition tuple helpers: `Partition`
+
+`TypedEAV::Partition` (`lib/typed_eav/partition.rb`, ~100 LOC) owns the `(entity_type, scope, parent_scope)` precedence rules:
+
+- `definitions_by_name(model, scope, parent_scope)` — returns the field-definitions map for a single resolved partition.
+- `definitions_multimap_by_name(model)` — returns the cross-partition multimap used by `unscoped { }` blocks.
+- `visible_fields(model, scope, parent_scope)` / `visible_sections(...)` — scope-respecting field/section iteration with the orphan-parent invariant inlined via `ScopeTuple.invariant_satisfied?`.
+
+The definitions helpers used to live as class methods on `HasTypedEav` before 0.3.0. They moved to `Partition` per [ADR-0002](../adr/0002-entity-query-orchestration.md) because they describe the partition domain, not the macro.
+
+## Events: `EventDispatcher`
+
+`TypedEAV::EventDispatcher` (`lib/typed_eav/event_dispatcher.rb`, ~150 LOC) is the broker for `on_value_change` and `on_field_change` callbacks. Per [ADR-0003](../adr/0003-keep-event-dispatcher-broker.md), it intentionally stays a broker rather than getting absorbed into either `Value` or `Field` — its multi-publisher / multi-subscriber shape doesn't belong on either model. See [Event hooks](events-and-versioning.md#event-hooks) for the public callback contract.
+
+## Schema portability and CSV: independent modules
+
+`TypedEAV::SchemaPortability` and `TypedEAV::CSVMapper` (Phase-6 modules) are deliberately decoupled from the core read/write path per [ADR-0005](../adr/0005-keep-phase-six-modules-independent.md). They depend on the public `has_typed_eav` macro surface, never on internal modules.
+
+See [Bulk operations](bulk-operations.md) for bulk reads, writes, and their guarantees.

data/docs/guides/bulk-operations.md

@@ -0,0 +1,205 @@
+---
+title: "Bulk operations"
+---
+
+# Bulk operations
+
+[Documentation home](../index.md)
+
+## Bulk reads: `BulkRead`
+
+`typed_eav_hash_for(records)` (the plural read) routes through `TypedEAV::BulkRead`. Given a record collection and an effective `(scope, parent_scope)`, it:
+
+1. Resolves visible definitions and groups the requested field IDs.
+2. Loads definitions, values, and field associations through one batched
+   definition query, one values query, and one field-association preload
+   (three SQL queries total; no host-table query).
+3. Returns a `{record_id => {field_name => value}}` map while skipping orphaned
+   values and preserving logical missingness.
+
+Definitions, filters, reads, registry entries, and writes all use the host's
+Rails `polymorphic_name`, so an STI leaf class reads and queries the same rows
+written under its base-class polymorphic type.
+
+The final production characterization reduced the 1,002 SQL statements observed
+across 1,000 scopes to three for the same BulkRead shape. This is a statement-
+count result, not a representative throughput claim; applications should still
+measure their own scope cardinality, selected fields, hydration, and contention.
+
+Single-record reads (`typed_eav_value`, `typed_eav_hash`) live on `InstanceMethods` and use the same partition helpers but without batching.
+
+Use `fields:` to load only the values needed by a view or export:
+
+```ruby
+Contact.typed_eav_hash_for(contacts, fields: [:name, :score])
+# => {123 => {"name" => "Ada", "score" => 42}, ...}
+```
+
+Omitting `fields:` (or passing `nil`) retains the all-fields behavior. A single
+String/Symbol or an enumerable of names is accepted; duplicates are removed.
+Unknown names and names unavailable in an individual record's partition are
+omitted, as are missing value rows. An explicitly stored NULL remains `nil`.
+`fields: []` returns an empty inner hash for each record without definition or
+value queries (the supplied collection itself may still need loading). Selected
+winning field IDs constrain the value query before hydration, so unrequested
+values and their field readers are not loaded or evaluated. Definition lookup
+remains batched across the records' partitions.
+
+To explicitly reuse already-loaded values:
+
+```ruby
+contacts = Contact.where(tenant_id: "t1").includes(typed_values: :field).to_a
+Contact.typed_eav_hash_for(contacts, fields: [:name], source: :preloaded)
+```
+
+The default `source: :database` still fetches persisted values afresh, even
+when associations are loaded or edited in memory. `:preloaded` uses the caller's
+association targets, including unsaved Value builds/assignments, without saving
+or mutating them. It performs one fresh batched definition query to choose
+current winners, but no Value or field-association preload queries. This is a
+value snapshot, not a guarantee of current database contents or frozen schema.
+
+Every host's `typed_values` association must be loaded, as must each retained
+Value's `field` association; incomplete preloads raise `ArgumentError` instead
+of silently issuing N+1 queries. With `fields:`, unselected Values need no field
+preload. With all fields selected, all field associations must be loaded
+(including loaded `nil` for orphans). `fields: []` needs neither associations
+nor definition/value queries. Only `:database` and `:preloaded` are valid sources.
+
+## Bulk writes: `BulkWrite`
+
+`bulk_set_typed_eav_values(records, attrs)` routes through `TypedEAV::BulkWrite`,
+and `bulk_set_typed_eav_values_per_record(values_by_record)` is its sibling for
+record-varying hashes. Both are semantic writers that:
+
+1. Memoize field definitions for the call via `Thread.current[:typed_eav_bulk_defs_memo]`.
+2. Validate each attribute against its field type's cast contract.
+3. Save each host through the normal callback/validation path inside an outer
+   transaction with per-record savepoints.
+
+`bulk_set_typed_eav_values_per_record` uses records as Hash keys, so two AR
+instances of the same persisted row collapse to one entry; sequence separate
+calls for two ordered updates, while the uniform Array API preserves duplicate
+instances and caller order.
+
+Under the default `transaction: :all`, per-record validation failures are captured at their
+savepoints while other successes can commit, but an uncaught exception rolls
+the entire outer transaction back.
+`transaction: :chunks, chunk_size: N` commits completed chunks while isolating
+later failures, preserving earlier committed chunks. Both forms require the
+host, Field, and Value pools to match.
+`bulk_upsert_typed_eav_values` is a separate reduced-semantics fast path: it
+casts and validates typed values, then performs one PostgreSQL upsert while
+omitting host saves, persistence callbacks, delete shorthand, and versioning.
+
+Callers must pass `acknowledge_reduced_semantics: true`. The same values hash
+applies to every record; records must be persisted and unique, and string or
+symbol field keys that normalize to the same name are rejected. The return
+value is the integer number of value rows upserted, not a semantic
+`successes`/`errors_by_record` result. Value casting, domain/entity/partition
+checks, and Value validation callbacks remain; host callbacks and validations,
+Value persistence callbacks, versioning, delete shorthand, and per-record
+savepoint isolation are skipped.
+
+Within each `transaction: :all` unit—or each requested chunk—the upsert path
+resolves every record partition through one batched field-definition SELECT.
+It shares BulkRead's internal tuple resolver, retaining global, scope-only, and
+full-tuple precedence independently for each record without broadening tenant
+visibility.
+
+`BulkWrite` and `BulkRead` are siblings — one read path, one write path — but they don't share a base class. Per [ADR-0005](../adr/0005-keep-phase-six-modules-independent.md), keeping them independent preserves the option to evolve each on its own schedule.
+
+## Writing a batch and handling results
+
+```ruby
+contacts = Contact.where(tenant_id: "t1").to_a
+result = Contact.bulk_set_typed_eav_values(contacts, { score: 10 })
+result[:successes].map(&:id)
+result[:errors_by_record].each do |record, errors|
+  Rails.logger.info(contact_id: record.id, errors: errors)
+end
+
+# Different sparse updates for each record:
+result = Contact.bulk_set_typed_eav_values_per_record(
+  { alice => { score: 12 }, bob => { nickname: { _destroy: true } } },
+  transaction: :chunks, chunk_size: 100
+)
+
+# Explicit fast path; returns a count of Value rows:
+rows_written = Contact.bulk_upsert_typed_eav_values(
+  contacts, { score: 10 }, acknowledge_reduced_semantics: true
+)
+```
+
+Semantic results are a symbol-keyed Hash with `successes` (host instances) and
+`errors_by_record` (host-instance keys, string-keyed validation-message hashes).
+An empty batch returns empty collections. Unlisted fields are untouched; the
+`{ _destroy: true }` value removes the named Value through normal destruction.
+Input errors and uncaught save exceptions propagate instead of becoming result
+entries. Check `errors_by_record` even when `transaction: :all` is used: ordinary
+validation failures do not make this an all-or-nothing batch.
+
+Records can span partitions; each scoped record resolves its own definitions.
+Filter and authorize the records before handing them to the writer. `chunk_size:`
+must be a positive Integer with `transaction: :chunks`; it is ignored with
+`:all`. An enclosing application transaction can still roll back work described
+as committed chunks. Host saves also run validations/callbacks for other pending
+host changes, so use records whose pending state you intend to save.
+
+### Version grouping
+
+Both semantic APIs accept `version_grouping:`:
+
+| Value | Behavior |
+| --- | --- |
+| `:default` | Groups changes per record when versioning callbacks are installed; otherwise does no grouping. |
+| `:per_record` | Assigns a group UUID for each record's pending typed-value changes. |
+| `:per_field` | Shares a UUID for each written field name across the batch, including across chunks. Per-record hashes use the union of their field names. |
+| `:none` | Adds no bulk grouping; normal enabled versioning still runs. |
+
+Explicit `:per_record` or `:per_field` requires versioning installed at boot and
+raises `ArgumentError` otherwise. Unknown grouping values also raise. Grouping
+controls audit identity, not transaction atomicity. See
+[events and versioning](events-and-versioning.md) for enabling history.
+
+## Bulk operation guarantees
+
+`bulk_upsert_typed_eav_values` is an explicit reduced-semantics API: it
+prevalidates/casts values and performs a PostgreSQL upsert, while intentionally
+omitting host callbacks and versioning. Use the regular bulk writer when those
+semantics are required; chunked semantic transactions are opt-in.
+
+The fast path still casts and runs domain, entity, partition, and validation
+callbacks before its single upsert against the exact entity/field conflict
+target; it omits host saves/host callbacks, Value persistence callbacks,
+delete shorthand, and versioning. It requires one shared connection pool and
+returns validation errors before SQL. `:all` is one unit; `:chunks` commits
+completed chunks before a later failure. Semantic writes retain host saves,
+per-record savepoint/error isolation, and one outer `:all` transaction.
+
+BulkWrite evidence is intentionally bounded to the exercised 100- and 1,000-host
+lanes. It does not establish 10,000- or 100,000-host throughput, nor does it
+justify a universal batch size or storage choice.
+
+## Operational guarantees
+
+The semantic writer preserves the caller's transaction and callback/versioning
+contract. Version rows are written in the source transaction, so a rollback
+rolls back the Value mutation and its audit row together. The reduced-semantics
+upsert is intentionally separate and does not claim those callbacks or audit
+guarantees.
+
+Field deletion has a callback-preserving, keyset-batched path that locks and
+destroys only the exact field's Values before bounded finalization. It scales by
+bounded primary-key batches and preserves the Field if a batch fails; it is not
+a claim of unbounded deletion throughput.
+
+## Default backfill narrowing
+
+`Field::Base#backfill_default!` optionally accepts an exact-host
+`ActiveRecord::Relation` to SQL-narrow eligible entities before batching. The default
+all-host behavior remains unchanged; partition checks, batch transactions,
+callbacks, validations, idempotence, versions, and errors remain in force.
+Typed storage defines logical missingness across all declared cells, so a
+partially populated multi-cell value is present while a fully empty Currency
+value is missing.

data/docs/guides/csv-import.md

@@ -0,0 +1,88 @@
+---
+title: "Mapping and importing CSV rows"
+---
+
+# Mapping and importing CSV rows
+
+[Documentation home](../index.md)
+
+`TypedEAV::CSVMapper` transforms one CSV row into field-name attributes. It does
+not read files, create records, resolve tenants, or save values. Your application
+owns those steps and can use the normal bulk writer for persistence.
+
+## Map headers and validate casts
+
+```ruby
+require "csv"
+
+mapping = { "Nickname" => :nickname, "Age" => :age }
+fields = TypedEAV::Partition.effective_fields_by_name(
+  entity_type: Contact.polymorphic_name, scope: "t1", parent_scope: nil
+)
+unknown = mapping.values.map(&:to_s) - fields.keys
+raise ArgumentError, "Unknown mapped fields: #{unknown.join(', ')}" if unknown.any?
+
+row = CSV::Row.new(["Nickname", "Age"], ["Ada", "37"])
+result = TypedEAV::CSVMapper.row_to_attributes(row, mapping, fields_by_name: fields)
+result.attributes # => {"nickname" => "Ada", "age" => 37}
+result.errors     # => {}
+result.success?   # => true
+
+# Once your application has selected an authorized destination record:
+if result.success?
+  saved = Contact.bulk_set_typed_eav_values_per_record({ contact => result.attributes })
+  saved[:errors_by_record] # Check full model/value validation failures here too.
+end
+```
+
+Resolve definitions for the destination record's partition. If a file spans
+partitions, resolve the appropriate map for each destination. Use the effective
+map so inherited same-name fields follow normal precedence.
+
+Typed mode calls each field's `cast`; it does not run the complete persistence
+validation pipeline. For example, an integer may cast successfully but violate
+its field's minimum or the host's validations when saved. A successful mapping
+therefore does not guarantee a successful save.
+
+## Headerless files and raw previews
+
+```ruby
+TypedEAV::CSVMapper.row_to_attributes(
+  ["Ada", "37"], { 0 => :nickname, 1 => :age }, fields_by_name: fields
+).attributes
+# => {"nickname" => "Ada", "age" => 37}
+
+# Omit fields_by_name for a raw mapping preview without casts:
+TypedEAV::CSVMapper.row_to_attributes(row, mapping).attributes
+# => {"nickname" => "Ada", "age" => "37"}
+```
+
+Mapping keys must be all String header names (for `CSV::Row`) or all Integer
+column indexes (for Arrays). Mixed or unsupported key types raise `ArgumentError`
+before processing. An empty mapping is valid. Field-name values may be Strings
+or Symbols; result keys are Strings. Match the key style to the row shape.
+
+## Errors and empty cells
+
+```ruby
+bad_row = CSV::Row.new(["Nickname", "Age"], ["Ada", "not-a-number"])
+result = TypedEAV::CSVMapper.row_to_attributes(bad_row, mapping, fields_by_name: fields)
+result.attributes # => {"nickname" => "Ada"}
+result.errors     # => {"age" => ["is invalid"]}
+result.failure?   # => true
+```
+
+Cast failures are collected per field and the invalid cell is omitted from
+`attributes`. Do not persist the partial attributes unless your import policy
+explicitly allows partial rows. Empty cells (`nil` or an empty String) cast to
+`nil` without a cast error; required-field checks still happen when saving.
+Missing headers/indexes that return `nil` follow that same path, so validate the
+file's expected columns before importing if omission must be an error.
+
+In typed mode, unknown field names are silently skipped without an error; the
+upfront mapping check above prevents accidental omissions. In raw mode, every
+mapped cell passes through unchanged. `attributes` and `errors` are frozen
+Hashes; `success?` means only that `errors` is empty. Row numbering, logging,
+file parsing errors, transactions, and retry policy remain application concerns.
+See [bulk operations](bulk-operations.md#writing-a-batch-and-handling-results)
+for save results and transaction options.

data/docs/guides/development.md

@@ -0,0 +1,73 @@
+---
+title: "Development and test isolation"
+nav_group: Project
+---
+
+# Development and test isolation
+
+[Documentation home](../index.md)
+
+These examples use metadata and hooks defined in this gem’s `spec/spec_helper.rb`. Host applications need equivalent test setup.
+
+## Event-hook tests
+
+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.
+
+## Versioning tests
+
+Specs that exercise versioning should opt into the `:event_callbacks`
+and `:real_commits` metadata flags (see [Event hooks](events-and-versioning.md#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
+    # Transactional Value callbacks are boot-latched and remain installed;
+    # the hook isolates only public and generic EventDispatcher observers.
+  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` snapshots and
+restores `Config.versioning`, `Config.actor_resolver`, and generic
+EventDispatcher observer lists around each example. Transactional Value
+callback installation is tested independently through callback-chain and
+boot-latch specs. The
+`:real_commits` hook disables transactional fixtures (so `after_commit`
+fires durably) and cleans up `TypedEAV::ValueVersion` rows in
+FK-respecting order between examples.