typed_eav 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2584a7a3e9eab294e874931c8202f2dae2082be6a036bd419fce7df3fdd94f56
-  data.tar.gz: 7d24090e4969e89bb268f89510b46ce034d8f9f045054c0d6d80828c4cd3006c
+  metadata.gz: 37b913418c998e4620c90efb72a0be8c93b838a2977db0347c9198b743ced2f3
+  data.tar.gz: 0a8a7f3a622712cc29b5738b8b0f4a54e3df3ffc56657277a69ebb956d3c46bf
 SHA512:
-  metadata.gz: 4aeaa932e2dff4d5ab22ae95c66d98953b93163fc9580445f05a365ce1489a56cfdbaf998e47548d5fe468227341eec170409eafad5191449cb96201039900d0
-  data.tar.gz: 1b626f58647506b2d0317e382d0fd2d8ebf7daae1c11e84dc9d58b1929107af9c62854c19c39a6244e9957d1e20ccb7b3c924c7aee9a77aa19414453c356e534
+  metadata.gz: c5bdc06300d8bb92538c93cfe23ac3afb6bed9719a29f6f7590740e6d4f56ac14998e21b4230c58fa2eed10e89dfe053af86144f3cbcf9637049c3d5b811d90b
+  data.tar.gz: 4760251616a62f91b7ed931dafc8b92a25653047cab8fcbd21dd027fe6353fdd2e7209a0629233306c69f77ec8eec08459854e8cc81443595d0b68e0503f4e8b

data/CHANGELOG.md

@@ -5,6 +5,197 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [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
+safety while defining the supported runtime window. Existing public method
+signatures and valid-record behavior remain unchanged. The compatibility floor
+is intentionally raised to the release lines exercised by CI.
+
+### Changed
+
+- Define the supported runtime contract as Ruby 3.3–4.0, Rails 7.2–8.1, and
+  PostgreSQL 15–18. Runtime dependency bounds now reject unverified future
+  Ruby and Rails release lines; prereleases remain outside the support
+  guarantee. Issue #26.
+
+### Fixed
+
+- Prevent single-value reads from returning a stale value from a losing
+  partition, and enforce the parent-scope partition invariant in PostgreSQL.
+  Issues #22 and #23.
+- Exercise packaged migrations in a generated Rails consumer application so
+  missing or non-idempotent installation paths fail before release. Issue #25.
+
+### Performance
+
+- Remove obsolete option-cache invalidation and batch-load fields for already
+  loaded typed values. Issues #28 and #29.
+- Bound scaffold visibility queries and preload existing values during default
+  backfills. Issues #30 and #31.
+- Keep all-partitions filter unions inside SQL and batch schema-import lookups
+  and option writes. Issues #32 and #33.
+
+### Documentation
+
+- Refresh maintainer, schema, and architecture guidance for the 0.5+ behavior
+  and current database invariants. Issue #34.
+
+### Release engineering
+
+- Gate trusted publishing on the exact dereferenced tag commit, the complete
+  supported compatibility matrix, lint, package-content inspection, and a
+  real-host migration installation using the same checksummed gem artifact
+  that is sent to RubyGems. Issue #27.
+
+### References
+
+- Issues #22, #23, and #25–#34.
+
 ## [0.5.0] - 2026-06-01
 
 Adds a human display label for fields, distinct from the immutable machine
@@ -258,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:
@@ -378,6 +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