typed_eav 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 255a937ce445032caf1880728a75a7363dda1323f8d20650bb2c73380cdb0c82
-  data.tar.gz: 3ff1c84f019c73902ae18812b19e8ab254d30813128f80fc7878adf0b43e21d1
+  metadata.gz: 37b913418c998e4620c90efb72a0be8c93b838a2977db0347c9198b743ced2f3
+  data.tar.gz: 0a8a7f3a622712cc29b5738b8b0f4a54e3df3ffc56657277a69ebb956d3c46bf
 SHA512:
-  metadata.gz: f0dc18a3c981530aba9c5be15acf07a1ce1a766845464aaa656876856f113d2b874e70173e9feb51bc2f88596c6bb9deea8a4b473d058e266c8ebc4e4584689c
-  data.tar.gz: 1d76a14b8ad44f7f17aee8e7973a6a468536711ddfd299cf376cd9d4d41e643c0e84e4b648df1b75bb961cb93764789c9ff9e3c15baffea8f7c323ff64a8f566
+  metadata.gz: c5bdc06300d8bb92538c93cfe23ac3afb6bed9719a29f6f7590740e6d4f56ac14998e21b4230c58fa2eed10e89dfe053af86144f3cbcf9637049c3d5b811d90b
+  data.tar.gz: 4760251616a62f91b7ed931dafc8b92a25653047cab8fcbd21dd027fe6353fdd2e7209a0629233306c69f77ec8eec08459854e8cc81443595d0b68e0503f4e8b

data/CHANGELOG.md

@@ -7,6 +7,148 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+No unreleased changes.
+
+## [0.7.0] - 2026-08-18
+
+This release hardens TypedEAV's correctness and operational behavior, replaces
+the highest-impact read N+1 path, and adds explicitly bounded bulk-maintenance
+APIs. It keeps the typed-column architecture and existing semantic write path;
+it does not claim that one storage design or batch size wins every workload.
+
+### Highlights
+
+- Batch partition resolution in `typed_eav_hash_for(records)` so the accepted
+  1,000-scope BulkRead shape executes three SQL statements instead of 1,002.
+- Replace the six scalar value indexes with smaller partial-covering indexes
+  that omit irrelevant NULL cells while preserving index-only entity reads.
+- Add an explicit reduced-semantics PostgreSQL bulk-upsert API and opt-in
+  chunked transactions for applications that knowingly prefer throughput or
+  bounded commits over the full semantic write envelope.
+- Write `ValueVersion` audit rows in the same source transaction as each
+  `Value`, so either both persist or both roll back.
+- Add SQL-narrowed default backfills and resumable, callback-preserving,
+  keyset-batched field deletion.
+
+### Changed
+
+- Query operands are normalized and validated by the owning Field before SQL is
+  built. This keeps scalar, range, array, Currency, Reference, and text-search
+  operands aligned with write semantics; Active Record remains responsible for
+  SQL bind plumbing.
+- `typed_eav_hash_for(records)` resolves all effective partition definitions in
+  one batched query, loads values once, and preloads field associations once.
+  Its public return shape, logical-missing behavior, partition precedence, and
+  orphan filtering are unchanged.
+- Versioning now installs synchronous `Value` lifecycle callbacks instead of
+  writing audit rows from an internal after-commit subscriber. A failed audit
+  insert now rolls back the source mutation instead of leaving an unversioned
+  committed `Value`.
+- The six scalar indexes now use `(field_id, value) INCLUDE (entity_id) WHERE
+  value IS NOT NULL`. The migration creates every replacement concurrently
+  before dropping its legacy index; rollback recreates legacy indexes before
+  removing replacements.
+- Field and Section partition mutations validate their own pending tuple rather
+  than leaking scope changes through shared lookup state. Value pending state is
+  also preserved across validation and lifecycle boundaries.
+- JSONB and TypedEAV are documented as workload-dependent storage choices.
+  Applications can own expression B-tree indexes for stable JSONB paths and GIN
+  indexes for containment; TypedEAV supplies stable typed columns and ordinary
+  per-type indexes. No final storage winner is claimed without representative
+  workload evidence.
+
+### Added
+
+- SQL-narrowed default backfills through an exact-host relation, while retaining
+  partition checks, batching, callbacks, validations, idempotence, versions,
+  error reporting, and Field-owned logical-missing detection across multi-cell
+  storage.
+- `Field::Base#destroy_with_values_in_batches!`, a callback-preserving,
+  keyset-batched exact-field deletion path with locked bounded finalization. A
+  failed batch leaves the Field available for inspection and retry.
+- `bulk_upsert_typed_eav_values`, an explicitly reduced-semantics PostgreSQL
+  upsert. Callers must pass `acknowledge_reduced_semantics: true`; values are
+  cast and validated before SQL, while host saves, persistence callbacks,
+  versioning, delete shorthand, and per-record savepoints are intentionally
+  skipped.
+- `transaction: :chunks, chunk_size: N` for both semantic BulkWrite and the
+  reduced upsert. Completed chunks remain committed if a later chunk fails;
+  `transaction: :all` remains the default.
+
+### Fixed
+
+- Validate Field defaults through the same typed domain rules used by ordinary
+  writes, including range, option, reference, array, Currency, and multi-cell
+  logical-missing semantics.
+- Fail closed when versioning callbacks are missing, duplicated, installed on
+  the wrong lifecycle kind, or configured across different connection pools.
+- Lock and drain only the exact Field's remaining Values during deletion,
+  preserving callback/version ordering across retry and race boundaries.
+- Keep Strong Migrations-compatible constraint validation outside a migration
+  transaction while preserving the generated-consumer migration path.
+- Reject normalized duplicate bulk-upsert keys such as `:age` and `"age"`
+  before issuing SQL.
+
+### Performance
+
+- BulkRead characterization reduced the 1,002 statements observed across 1,000
+  scopes to three for the same shape. This is a statement-count result, not a
+  representative throughput claim.
+- BulkWrite evidence remains bounded to the exercised 100- and 1,000-host
+  lanes; no 10k/100k throughput or universal batch-size claim is made.
+- Representative PostgreSQL 15, 16, and 18 migration/catalog checks passed for
+  the partial-covering indexes. PostgreSQL 17 planner and benchmark timings are
+  retained as co-tenant diagnostic evidence rather than portable latency
+  promises.
+
+### Reliability
+
+- ValueVersion rows are written in the source transaction, preserving atomic
+  rollback with the Value mutation and avoiding a false after-commit rollback
+  assumption.
+- The parent-scope check-constraint migration validates existing rows before
+  adding constraints with Strong Migrations-compatible nontransactional DDL;
+  the unchanged consumer migration canary passed.
+
+### Upgrade notes
+
+- Copy/install the latest engine migrations and run the application's normal
+  migration command. The parent-scope validation and scalar-index migrations
+  use `disable_ddl_transaction!`; do not wrap them in an application-level
+  transaction. Concurrent create-before-drop ordering avoids an index-coverage
+  gap during normal PostgreSQL deployment.
+- Versioned applications should expect an audit-write failure to abort the
+  `Value` mutation. `Value` and `ValueVersion` must share one connection pool;
+  versioning fails closed when they do not.
+- Semantic BulkWrite still runs host validations/callbacks, Value persistence
+  callbacks, and versioning. Under the default `transaction: :all`, individual
+  validation/save failures are isolated by savepoints and successful records
+  may commit, while an uncaught exception rolls back the outer transaction.
+  `transaction: :chunks` deliberately permits earlier chunks to remain
+  committed after a later failure.
+- `bulk_set_typed_eav_values_per_record` uses records as Hash keys; duplicate
+  Active Record instances for the same persisted row collapse to one entry.
+  Use ordered separate calls when two updates to the same row must both occur.
+- The reduced bulk upsert accepts persisted, unique records and one uniform
+  values Hash, returns the number of upserted value rows, and intentionally does
+  not provide semantic successes/errors or callback/version guarantees.
+- The supported runtime contract remains Ruby 3.3–4.0, Rails 7.2–8.1, and
+  PostgreSQL 15–18.
+
+### Evidence boundaries
+
+- The BulkRead result is an exact SQL-statement-count improvement for the
+  characterized public path, not a universal throughput or latency guarantee.
+- BulkWrite measurements cover 100- and 1,000-host lanes only. Applications
+  should choose chunk sizes from their own callback cost, transaction duration,
+  lock contention, and failure-recovery needs.
+- Public chained-IN multi-filter SQL remains the supported strategy. Optional
+  `pg_trgm` and dependency statistics stay application-owned and measured;
+  TypedEAV does not automatically install extensions, specialized indexes, or
+  extended statistics.
+- No representative storage tournament selected TypedEAV, JSONB, per-type EAV,
+  or conventional columns as a universal winner.
+
 ## [0.6.0] - 2026-07-13
 
 Hardens correctness, query efficiency, installation confidence, and release
@@ -307,6 +449,17 @@ internal helper relocation (see "Changed" below). Anchored by ADRs
 
 ### Internal
 
+- Added the opt-in `Field#destroy_with_values_in_batches!` API for exact-field,
+  callback-preserving keyset deletion. It commits bounded Value destroy batches,
+  retains the Field across failure, and performs locked bounded finalization;
+  ordinary Field destruction and dependency policies remain unchanged.
+
+- Atomic ValueVersion writes are installed from the Value callback chains at
+  boot, with an identical-pool guard and idempotent recovery if a callback is
+  removed. BulkWrite keeps caller context unchanged while correlating version
+  groups through its pending marker; EventDispatcher remains a public and
+  generic observer broker.
+
 - `TypedEAV::EventDispatcher` is retained as the synchronous broker
   between `TypedEAV::Hooks` and `ActiveSupport::Notifications`. The
   cleanup arc explicitly considered collapsing it and rejected that:
@@ -427,7 +580,11 @@ worked examples.
 
 Initial release.
 
+[Unreleased]: https://github.com/dchuk/typed_eav/compare/v0.7.0...HEAD
+[0.7.0]: https://github.com/dchuk/typed_eav/releases/tag/v0.7.0
 [0.6.0]: https://github.com/dchuk/typed_eav/releases/tag/v0.6.0
+[0.5.0]: https://github.com/dchuk/typed_eav/releases/tag/v0.5.0
+[0.4.0]: https://github.com/dchuk/typed_eav/releases/tag/v0.4.0
 [0.3.2]: https://github.com/dchuk/typed_eav/releases/tag/v0.3.2
 [0.3.1]: https://github.com/dchuk/typed_eav/releases/tag/v0.3.1
 [0.3.0]: https://github.com/dchuk/typed_eav/releases/tag/v0.3.0