typed_eav 0.8.0 → 0.8.1

data/docs/adr/0010-planner-statistics-policy.md

@@ -0,0 +1,109 @@
+---
+title: "ADR 0010: Application-owned evaluation of planner statistics"
+---
+
+# ADR 0010: Application-owned evaluation of planner statistics
+
+## Status
+
+Accepted
+
+## Context
+
+TypedEAV stores many logical fields in one physical table. A predicate such as
+`field_id = 42 AND integer_value = 7` can therefore violate the planner's
+default assumption that the two columns are independent. PostgreSQL extended
+statistics can describe a column group in three different ways:
+
+- `dependencies` describes functional dependencies between columns. PostgreSQL
+  can use it for compatible equality and `IN` clauses, but not range clauses.
+- `mcv` stores frequencies for common combinations of values. It can help when
+  a queried combination is represented in that list.
+- `ndistinct` estimates the number of distinct column combinations. It is
+  principally relevant to grouping cardinality, not the field/value `WHERE`
+  predicates exercised here.
+
+The Phase 4A benchmark created a separate object for each tested typed column,
+paired with `field_id`, and compared `dependencies`, `mcv`, `ndistinct`, and a
+combined object. Its deterministic 300,000-entity dataset ran ten trials and 50
+paired blocks on PostgreSQL 17.11. The target of 100 controlled this experiment;
+it is not a recommended target for every database.
+
+Dependencies improved aggregate equality-estimate accuracy in this synthetic
+workload, but did not apply to ranges. The combined object did not reproduce the
+dependencies-only aggregate result: for the four probes whose estimates
+changed, matching MCV groups supplied the estimate, so the combined candidate
+mirrored MCV instead. `ndistinct` did not change these `WHERE` estimates. No
+candidate changed a plan shape, introduced a sequential scan, or lost an
+index-only plan, and the experiment does not demonstrate execution-time benefit.
+
+One preregistered probe was mislabeled. `date_skewed_common_eq` queried
+`2024-01-01`, while the generated common dates begin at `2024-01-02`; the probe
+matched zero rows. It is absent-date estimation evidence, not common-date
+evidence. The retained artifact remains mechanically valid and discloses the
+query and row count, so it is not rewritten.
+
+## Decision
+
+TypedEAV will not create extended-statistics objects automatically and will not
+ship a migration, generator, or helper for them. Production schema, queries, and
+installation behavior remain unchanged.
+
+An application may evaluate application-owned `dependencies` statistics when
+its own plans show persistent field/value equality misestimates. The application
+must choose the typed columns and target from its workload; it must not copy the
+benchmark's target of 100 as a universal setting. `mcv`, `ndistinct`, or a
+combined object require their own workload evidence and must not be added merely
+because PostgreSQL supports them.
+
+For example, an application investigating integer equality could test an
+application-specific object in a representative preproduction database:
+
+```sql
+CREATE STATISTICS app_te_values_field_integer_dependencies (dependencies)
+ON field_id, integer_value
+FROM typed_eav_values;
+
+ALTER STATISTICS app_te_values_field_integer_dependencies
+SET STATISTICS <application-selected-target>;
+
+ANALYZE typed_eav_values;
+```
+
+Creation alone does not populate statistics; `ANALYZE` is required. Compare the
+same representative queries before and after with `EXPLAIN (ANALYZE, BUFFERS,
+WAL, SETTINGS)`, checking estimated versus actual rows, plan shape, planning and
+execution time, and workload-level latency. Also measure `ANALYZE` duration,
+catalog size, and maintenance effects. Repeat after realistic data churn and on
+every PostgreSQL version the application operates. Keep an object only when the
+observed benefit justifies those costs.
+
+The consuming application owns the DDL, stable names, deployment timing, and
+rollback. Before creating or dropping anything, inspect `pg_statistic_ext` and,
+when the role is permitted to read it, `pg_statistic_ext_data`; verify the name,
+table, columns, kinds, owner, and target. In a database shared by multiple
+applications, coordinate a single owner and do not alter or drop a statistics
+object merely because its name looks familiar. Removal is explicit and followed
+by another measurement cycle:
+
+```sql
+DROP STATISTICS IF EXISTS app_te_values_field_integer_dependencies;
+ANALYZE typed_eav_values;
+```
+
+Dropping the object removes the extended data; the follow-up `ANALYZE` refreshes
+ordinary statistics for a comparable post-removal baseline. Schedule creation,
+`ANALYZE`, and removal according to the application's table size and operational
+constraints rather than assuming the benchmark's costs transfer.
+
+## Consequences
+
+- TypedEAV adds no schema object or maintenance cost for applications that have
+  not demonstrated a planner-estimation problem.
+- Applications can test the narrow `field_id`/typed-column correlation without
+  changing TypedEAV query semantics.
+- Application owners must evaluate targets, PostgreSQL versions, data
+  distributions, and operational costs themselves.
+- Phase 4A remains bounded PostgreSQL 17 synthetic evidence. It supports this
+  evaluation policy, not a claim of runtime improvement or general planner
+  behavior.

data/docs/adr/0011-multi-filter-query-strategy.md

@@ -0,0 +1,111 @@
+---
+title: "ADR 0011: Retain chained-IN multi-filter queries"
+---
+
+# ADR 0011: Retain chained-IN multi-filter queries
+
+## Status
+
+Accepted
+
+## Context
+
+TypedEAV currently resolves every requested field before constructing SQL. It
+then builds one typed value subquery per filter, selects distinct `entity_id`
+values from each, and adds each result to the host relation as an `id IN (...)`
+predicate. This chained-`IN` shape preserves the host relation as the universe
+for complement and missing-value operations.
+
+Phase 4B compared that implementation with `INTERSECT`, correlated `EXISTS`,
+and direct grouped `HAVING`. `INTERSECT` and `EXISTS` reused the same resolved
+per-filter subqueries. Grouped `HAVING` was eligible only for compatible
+present-row predicates: without a host join or a separate complement it cannot
+represent missing or host-universe complement semantics, and a direct grouped
+value scan cannot return the unfiltered host relation for an empty filter set.
+
+The seed-4502 representative run used 100,000 primary hosts, more than 50 field
+definitions, 25 scenarios, three rotations, and ten attempts per eligible
+strategy group. It retained 2,940 uniformly capped attempts, 294 sorted
+host-identity oracles, and 75 scenario/trial summaries on PostgreSQL 17 under
+resource-capped co-tenancy. Of the attempts, 622 reached the 1,000 ms timeout
+and are right-censored lower bounds. Of the 294 non-retried 5,000 ms oracles,
+282 completed and 12 timed out; the timed-out identities are unknown, not equal
+or unequal. No completed oracle mismatched or errored. The embedded 2,000-host
+smoke completed all 98 eligible oracles with equal identities, but that does
+not establish representative-scale equivalence.
+
+The candidates did not produce a robust general winner. `INTERSECT`, `EXISTS`,
+and grouped `HAVING` strongly improved the high-selectivity 10-predicate case,
+but the mixed 10-predicate case regressed and many low-, mixed-, and
+skewed-selectivity large cases were censored or otherwise inconclusive.
+
+Two evidence defects further limit the result:
+
+- The artifact's derived buffer totals are false zeros because the extractor
+  split each multiword EXPLAIN block key into individual words. The retained
+  raw plans contain nonzero block counters and can be reparsed, but the
+  published derived zero values are not valid buffer evidence.
+- The 20-predicate scenarios repeat ten fields, while the skewed 10- and
+  20-predicate scenarios repeat five fields. The run therefore does not measure
+  20 distinct fields, and its skewed cases do not measure 10 distinct fields.
+
+Absolute timings and dispersion from the continuously busy co-tenant host are
+diagnostic. PostgreSQL 17 plan choices are not evidence for every supported
+PostgreSQL version or application distribution.
+
+## Decision
+
+Retain the current chained host `IN` query strategy. Production query code and
+public APIs do not change.
+
+`INTERSECT` and correlated `EXISTS` remain research-only alternatives. Direct
+grouped `HAVING` is also research-only for compatible present-row predicates
+and remains ineligible for missing-value, host-universe complement, and empty-
+filter semantics. No adaptive selector or production replacement is available
+or authorized.
+
+## Gates for future research
+
+Future adaptive or replacement work must pass all of these gates before a
+production change can be considered:
+
+1. **Semantic coverage.** Build every strategy from identical resolved fields,
+   typed operands, predicates, datasets, and host universes. Prove scope,
+   parent-scope, global/scoped shadowing, all-scope administration,
+   polymorphic host identity, arbitrary supported operators, explicit NULL,
+   missing and `include_missing` complements, duplicate internal matches,
+   empty filters, ordering where requested, and supported error behavior.
+   Grouped `HAVING` must stay ineligible where it cannot express the contract.
+2. **Representative equivalence.** Complete the sorted `(entity_type, id)`
+   count/checksum oracle for every eligible representative group. A timeout,
+   mismatch, or error cannot be treated as equality; no completed-only sample,
+   retry, imputation, or censored bound may authorize replacement.
+3. **Distinct-field scale.** Measure actual 10- and 20-distinct-field workloads
+   across high-, low-, mixed-, and skewed-selectivity families rather than
+   reaching those predicate counts by repeating five or ten fields.
+4. **Correct buffer evidence.** Re-extract separate shared/local/temp read,
+   hit, dirtied, and written block counters from every retained raw plan,
+   validate derived totals against the source EXPLAIN JSON, and obtain complete
+   comparable `ANALYZE` buffer evidence. The current derived zeros cannot be
+   used as a baseline.
+5. **Performance threshold.** Show uncensored improvement of at least 20% at
+   p95 for both 10- and 20-filter workloads in at least three workload families.
+   Preserve all scheduled repetitions and right-censored results; do not infer
+   a winner from completed attempts alone.
+6. **Planning and plan shape.** Pre-register material-regression bounds, then
+   show bounded planning-time and buffer behavior and no material plan-shape
+   regression, including index use and host-relation behavior, across the
+   eligible semantic matrix. Repeat planner evidence on the PostgreSQL versions
+   for which a production strategy would be claimed.
+Cross-scope planning at high tenant cardinality remains separate required
+Phase 4 evidence. Passing a favorable microbenchmark or repairing only one of
+the defects above is insufficient for Gate 4 or production authorization.
+
+## Consequences
+
+TypedEAV keeps the broadly exercised semantics and predictable public behavior
+of its current composition path. It also forgoes the strong improvements seen
+in one high-selectivity case until those gains survive the full semantic and
+operational evidence gates. The representative artifact remains useful as
+negative and retention evidence; it is not proof that alternatives are
+equivalent, eligible, adaptive, or generally slower.

data/docs/adr/0012-cross-scope-administrative-query-policy.md

@@ -0,0 +1,76 @@
+---
+title: "ADR 0012: Bound cross-scope administrative queries in applications"
+---
+
+# ADR 0012: Bound cross-scope administrative queries in applications
+
+## Status
+
+Accepted
+
+## Context
+
+`TypedEAV.unscoped` is the deliberate escape hatch for administration,
+analytics, migrations, and cross-tenant audits. It is not the ordinary tenant
+request path. Within a tenant tuple, field visibility considers global,
+scope-only, and full-tuple definitions and selects the most-specific definition
+for each name. Under `unscoped`, the same-name definitions across every
+partition remain visible and query construction unions their per-definition
+relations for each filter.
+
+Code-path analysis shows that the `ALL_SCOPES` branch eagerly materializes the
+visible definitions, groups them by name, constructs one relation per matching
+definition, and combines those relations with Arel OR nodes. Repeating that
+work across filters makes construction depend on the definitions visible to
+the administrative query as well as its filters. This behavior is distinct
+from bounded tenant specificity and must not be generalized to normal tenant
+traffic.
+
+Phase 4C attempted representative cross-scope measurement in T066 and T069.
+Neither execution produced an accepted representative artifact. T066 rejected
+at artifact validation without retaining the decisive rejection detail. T069
+then rejected at the required checkpoint gate, and runner ordering again lost
+the exported diagnostic before local retention. Local smoke exercised the
+intended semantics, but smoke evidence does not establish representative
+scaling or candidate equivalence. The rejected runs therefore support no
+latency, throughput, planner, cardinality-limit, or comparative-performance
+claim.
+
+## Decision
+
+Keep `TypedEAV.unscoped` as an explicit administrative and analytics surface.
+Applications should keep the definition universe for each administrative job
+as narrow as their use case permits and batch broad cross-partition work at an
+application-owned boundary. The appropriate relation, partition selection,
+batch size, scheduling, and operational limits depend on the consuming
+application and must be measured there.
+
+TypedEAV does not add a built-in threshold, warning, guardrail, batching API,
+query rewrite, schema object, or dependency. The benchmark-only homogeneous
+`field_id`-array prototype is not adopted. It lacked accepted representative
+semantic and performance evidence and was ineligible for mixed field casts,
+operators, and NULL/missing complement semantics.
+
+No numeric definition limit is recommended. Applications that operate across
+many partitions should inspect their own generated SQL, planning and execution
+behavior, memory use, and workload interference before selecting an operational
+boundary. Ordinary tenant requests should continue using scoped resolution,
+not `unscoped` as a shortcut around scope configuration.
+
+## Consequences
+
+- Tenant-scoped lookup retains most-specific global/scope/full-tuple behavior.
+- Cross-scope queries retain their existing union semantics and public API.
+- Administrative callers own bounding and batching for broad work.
+- No rejected benchmark output is published as representative evidence.
+- A future production optimization requires a new accepted protocol that
+  preserves polymorphism, field-owned casts, shadowing, supported operators,
+  explicit NULL, missing rows, and `include_missing` semantics.
+
+## Related decisions
+
+- ADR 0002 separates entity-query orchestration from per-field predicates.
+- ADR 0006 defines `include_missing` as host-level set complement, including
+  the `ALL_SCOPES` multimap branch.
+- ADR 0011 retains the chained-`IN` multi-filter strategy and requires complete
+  representative equivalence before replacement.

data/docs/adr/0013-durable-versioning-and-field-deletion.md

@@ -0,0 +1,125 @@
+---
+title: "ADR 0013: Durable versioning and callback-preserving field deletion"
+---
+
+# ADR 0013: Durable versioning and callback-preserving field deletion
+
+## Status
+
+Accepted and implemented by the atomic versioning boundary work.
+
+## Context
+
+The historical implementation wrote `ValueVersion` rows from an internal
+`after_commit` subscriber. That boundary was intentionally after the source transaction: a
+source `Value` create, update, or destroy can commit successfully and then the
+version writer can raise. The same applies when a field's `field_dependent:
+"destroy"` callback destroys its dependent Values. Real-commit regression
+coverage records this observable divergence: the source rows and field cascade
+remain committed while the attempted version rows are absent.
+
+This is not a rollback guarantee. An `after_commit` exception can be surfaced
+to the caller, but it cannot undo the already committed source mutation. Public
+application callbacks remain a separate concern and should remain best-effort
+after-commit hooks, rescued and logged rather than making source persistence
+fail closed.
+
+## Options
+
+| Option | Boundary | Strength | Cost and limitation |
+| --- | --- | --- | --- |
+| Historical after-commit delivery | `Value` committed, then subscriber wrote `ValueVersion` | Backward-compatible and simple | A subscriber failure left committed source state without a version row; retries and visibility were external concerns |
+| Synchronous source-transaction write | Write `ValueVersion` before the `Value` transaction commits | Source and version row succeed or roll back together; smallest durable boundary | Requires `Value` and `ValueVersion` to share the same connection pool; changes callback ordering and needs explicit recursion/rollback tests |
+| Generic outbox | Source transaction appends an event; a worker writes versions | Cross-process retry, replay, and operational observability | Adds schema, worker/queue, idempotency, retention, ordering, and deployment machinery before a cross-database or external-consumer requirement exists |
+
+## Decision
+
+Characterization selects synchronous `ValueVersion` writes inside the source
+transaction as the smallest follow-up boundary. Enablement remains
+boot-latched: when versioning is disabled at boot, no subscriber is registered
+and the disabled path adds no per-mutation hot-path predicate. When enabled,
+activation must fail closed unless
+`TypedEAV::Value.connection_pool.equal?(TypedEAV::ValueVersion.connection_pool)`
+is true. A pool mismatch is a startup/configuration error, not a permitted
+best-effort mode. This is the implemented production boundary documented by
+this ADR.
+
+The implementation uses actual Value callback-chain inspection as its
+boot-latch truth, reinstalls missing callbacks idempotently, and rejects a
+Value/ValueVersion pool mismatch before installation. BulkWrite preserves the
+caller context and carries version-group correlation through an internal
+pending marker. The implementation must preserve the existing write contract: registry opt-in,
+exact entity/field tuple and tenant/partition semantics, before/after typed
+snapshots, context, actor resolution, `changed_at`, version-group selection,
+and pending-marker cleanup on both commit and rollback. A source rollback must
+roll back its synchronous version rows; a successful source mutation produces
+exactly one corresponding version row. Public application callbacks remain
+best-effort, rescued and logged after commit, and must not be presented as
+durable or fail-closed delivery.
+
+The generic outbox is deferred. It becomes appropriate only if version events
+must cross a database/process boundary or require an independently operated
+consumer. Until then, its additional queue, retry, idempotency, ordering, and
+retention surface is not justified.
+
+## Durability boundaries and historical limits
+
+Idempotency is one version row per successful source mutation. A caller owns a
+whole-source retry: retry the complete source transaction after a rollback or
+connection failure, rather than replaying an individual version write. There is
+no asynchronous replay cursor, checkpoint protocol, or durable event identity
+in this boundary. Ordering is the order of mutations within one source
+transaction; no total order is promised across concurrent transactions or
+databases.
+
+The synchronous boundary does not repair historical gaps created by the
+historical after-commit path, and it does not infer or rewrite history after model,
+registry, tenant, field, or snapshot semantics drift. Existing gaps remain
+observable historical gaps and require a separately approved, application-owned
+repair process if a consumer needs one. Version rows remain append-only;
+retention, archival, and deletion are application-owned policies and are not
+automated here.
+
+## Implemented bounded Field deletion contract
+
+Field-dependent destruction must not use `delete_all`, broad unscoped deletes,
+or early Field removal. The explicit
+`Field#destroy_with_values_in_batches!(batch_size: 1_000)` API:
+
+1. identify the exact `field_id` and process dependent Values in bounded
+   primary-key keyset batches (`id > last_id`, ordered by `id`);
+2. destroy each Value through Active Record so Value callbacks and the selected
+   versioning boundary run, while retaining exact-field and source-transaction
+   isolation;
+3. commits each bounded batch independently; a retry re-derives the remaining
+   rows from the exact-field keyset without skipping or repeating committed
+   work;
+4. retry/resume until an exact-field query proves no dependent Values remain;
+5. destroy the Field only after the final drain proof, preserving its own
+   callbacks and policy semantics.
+
+The operation is idempotent and preserves ordering by keyset position. It is
+explicitly rejected inside an open transaction or when Field, Value, and
+ValueVersion do not share one connection pool. The final drain locks the Field,
+accepts at most one bounded residual batch, proves zero exact-field rows, and
+only then invokes ordinary Field destruction. It does not claim that an
+after-commit callback failure rolled back source data.
+
+After the final Field deletion, the foreign keys intentionally null both
+`ValueVersion.value_id` (when its Value is subsequently gone) and
+`ValueVersion.field_id` (when the Field is gone). The durable `entity_type`,
+`entity_id`, and payload can remain queryable, but direct Value/Field identity is
+then lost. This is an accepted identity tradeoff, not something the ADR hides
+or promises to reconstruct with a schema snapshot.
+
+## Evidence and limits
+
+The real-commit regressions establish current failure semantics for Value
+create/update/destroy and field-dependent cascades. They do not measure retry
+cost, batch size, queue latency, or cross-database behavior. Those questions
+require a separately approved implementation and protocol.
+
+## Related decisions
+
+- ADR 0003 keeps the EventDispatcher as the internal callback broker.
+- ADR 0012 keeps broad administrative work application-bounded.

data/docs/adr/index.md

@@ -0,0 +1,101 @@
+---
+title: "Design decisions"
+nav_group: Project
+nav_exclude: false
+---
+
+# Design decisions
+
+The choices below explain behavior you may encounter when integrating or
+extending TypedEAV. Each summary covers the decision, why it exists, and what
+it means for your application. Links lead to the full engineering rationale.
+
+## Fields and extension points
+
+- **Fields own typed storage.** A custom field declares its columns and implements
+  logical reads, writes, and defaults. Change detection and snapshots derive from
+  those column declarations, avoiding duplicate storage mappings that can drift.
+  Multi-column types use the same extension pattern as built-in Currency.
+  [Rationale](0001-collapse-column-mapping-stack.md)
+- **Related types share validation behavior.** String and range-bounded field
+  families, plus a shared option-handling concern, keep validation consistent.
+  Custom types can reuse these families instead of rebuilding length, range,
+  and option checks. [Rationale](0004-field-family-intermediate-bases.md)
+
+For implementation examples, see [custom field types](../guides/fields.md#custom-field-types).
+
+## Scoping and queries
+
+- **Field predicates and query composition are separate.** Per-field SQL handles
+  typed operands; higher-level queries handle filters and partition resolution.
+  This keeps type-specific behavior independent of how multiple filters combine.
+  Applications normally use the host model API rather than these internal classes.
+  [Rationale](0002-entity-query-orchestration.md)
+- **Missing values are an explicit query choice.** Ordinary `is_null` matches an
+  existing NULL value row. With `include_missing: true`, the query also includes
+  hosts without a value row, using the caller's host set and excluding non-NULL
+  matches. This supports “is empty” searches without changing the default SQL-like
+  NULL contract. [Rationale](0006-include-missing-via-set-complement.md)
+- **Visibility and mutation have different boundaries.** Reads may include global
+  and less-specific fallback definitions; ordering mutations target the exact
+  partition. Reordering a tenant's definitions therefore cannot renumber shared
+  fallback definitions or another partition's fields.
+  [Rationale](0007-visibility-versus-mutation-relations.md)
+- **Multiple filters retain the existing subquery strategy.** TypedEAV combines
+  per-field matches through host `IN` predicates. Alternative query shapes have
+  not demonstrated a sufficiently reliable, semantically equivalent improvement
+  to justify a replacement. There is no adaptive query-strategy switch.
+  [Rationale](0011-multi-filter-query-strategy.md)
+- **Cross-partition queries are an administrative tool.** `unscoped` considers
+  definitions across partitions, so broad queries can require substantially more
+  work. Applications own authorization, narrowing, and batching; the gem does not
+  claim a universal safe partition count. Normal tenant requests should use scoped
+  resolution. [Rationale](0012-cross-scope-administrative-query-policy.md)
+
+See [query behavior](../guides/queries.md) and [scoping](../guides/scoping.md)
+for the public contracts and examples.
+
+## Indexing and performance
+
+- **Default scalar indexes omit NULL cells.** Values normally populate only their
+  applicable typed columns. Partial covering indexes avoid indexing unrelated NULL
+  cells while supporting non-NULL scalar queries. Separate NULL indexes are not
+  installed automatically because their storage and write costs depend on the
+  workload. [Rationale](0008-partial-covering-scalar-indexes.md)
+- **Trigram indexes are application-owned.** The gem keeps its default string
+  B-tree and public `ILIKE` operators. Trigram indexing can help selected searches,
+  but short patterns and negative searches need different expectations. Applications
+  evaluate the extension, index, and write/storage costs on their own data.
+  [Rationale](0009-string-search-indexing.md)
+- **Extended planner statistics are opt-in.** Correlated field/value predicates
+  can benefit from better estimates, but better estimates do not necessarily
+  improve runtime. TypedEAV does not install statistics objects or prescribe a
+  universal target; applications add them only when their query plans justify it.
+  [Rationale](0010-planner-statistics-policy.md)
+
+These are workload choices, not universal speed guarantees. See
+[storage and performance](../guides/performance.md) for evaluation guidance.
+
+## Imports, events, and audit history
+
+- **Import utilities remain independently usable.** Schema portability moves
+  definitions, CSV mapping transforms rows, and bulk writing persists values.
+  Keeping them separate lets applications preview, validate, and save in the order
+  their workflow requires. Their different return values reflect different jobs;
+  there is no mandatory import pipeline.
+  [Rationale](0005-keep-phase-six-modules-independent.md)
+- **Public event hooks have a separate error policy.** Public callbacks run after
+  commit, and their errors are logged rather than making a committed save appear
+  to have failed. The event dispatcher preserves that boundary. Applications
+  needing reliable external delivery must provide their own delivery mechanism.
+  [Rationale](0003-keep-event-dispatcher-broker.md)
+- **Enabled audit history shares the value transaction.** Value changes and their
+  audit rows commit or roll back together, requiring a shared connection pool.
+  Public after-commit hooks remain separate. Large field deletions have an explicit
+  batched path that preserves value callbacks and versioning; committed batches
+  remain committed if a later batch fails, and the field is retained for retry.
+  [Rationale](0013-durable-versioning-and-field-deletion.md)
+
+See [CSV mapping](../guides/csv-import.md), [schema portability](../guides/schema.md),
+[bulk operations](../guides/bulk-operations.md), and
+[events and versioning](../guides/events-and-versioning.md) for usage details.

data/docs/getting-started.md

@@ -0,0 +1,79 @@
+---
+title: "Getting started"
+nav_group: Start here
+---
+
+# Getting started
+
+## Compatibility
+
+The canonical support contract lives in
+[`.github/compatibility.json`](https://github.com/dchuk/typed_eav/blob/main/.github/compatibility.json). Typed EAV supports:
+
+| Runtime | Supported versions |
+|---|---|
+| Ruby | 3.3 through 4.0 (`>= 3.3`, `< 4.1`) |
+| Rails | 7.2 through 8.1 (`>= 7.2`, `< 8.2`) |
+| PostgreSQL | 15 through 18 |
+
+CI proves representative floor, middle, and ceiling combinations rather than
+every Cartesian product. Versions outside these ranges and prerelease versions
+are outside the support guarantee. PostgreSQL compatibility claims assume the
+current minor release for each supported major version.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "typed_eav"
+```
+
+Run the install migration:
+
+```bash
+bin/rails typed_eav:install:migrations
+bin/rails db:migrate
+```
+
+PostgreSQL is required; MySQL and SQLite are not supported. For existing
+installations, see [Upgrading](guides/upgrading.md) and the
+[Changelog](https://github.com/dchuk/typed_eav/blob/main/CHANGELOG.md).
+
+## Quick Start
+
+Assuming your application already has a `Contact` model and table:
+
+```ruby
+class Contact < ApplicationRecord
+  has_typed_eav
+end
+
+TypedEAV::Field::Integer.create!(
+  name: "age",
+  entity_type: Contact.polymorphic_name,
+  options: { min: 0, max: 150 }
+)
+
+contact = Contact.new
+contact.set_typed_eav_value("age", "40")
+contact.save! # Supply any other attributes your Contact model requires.
+
+contact.typed_eav_value("age") # => 40 (Integer)
+contact.typed_eav_hash         # => { "age" => 40 }
+
+Contact.with_field("age", :gteq, 21)
+       .order_typed_eav("age", direction: :desc)
+       .limit(25)
+```
+
+Fields cast and validate both assigned values and query operands. Queries
+return Active Record relations, so you can combine them with ordinary host
+filters. Use `Contact.polymorphic_name` when creating definitions to respect
+Rails' STI and namespaced-polymorphism settings.
+
+See [Reading, writing, and forms](guides/usage.md) for bulk assignment,
+nested attributes, form helpers, and the admin scaffold, or
+[Querying typed fields](guides/queries.md) for operators, multi-field
+filters, sorting, distinct values, counts, and numeric aggregates.
+