poly 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b553ab920c023d3f1e23a5de23c35bc75798827f6dfe5db2bd9369e0875586b0
-  data.tar.gz: 7ce045f76258951d9b3a281f38c369c81b9decc2cbfaca7ce9a73279605ae792
+  metadata.gz: ba17496c0d7031f1877d3aa61200842efd24cb1381c12ecb597e5b4c80ac65d7
+  data.tar.gz: 9bf0d37b9106badbf5672f3b1534e5c8e8161e3934ead590b56415a17196eda5
 SHA512:
-  metadata.gz: 7242fafe809c07f8b801ed5fd049519ffc7d403dd8254e1323fa7d794dffa549dd8c5070317a1ff6f2dd8f185b603baef121c2ab6eccced5dfd9e542dad006b3
-  data.tar.gz: 519f7047228088054991bd4288eb52f1e39b98839976dfaadb1c68b3f46a0b0d97c7f1c088543be9f58838978e989b048d622bef4a768e4df39a9733dee83098
+  metadata.gz: bf46bda44abfaccfb137c84cf1a6da3a6d3a6d0ad901e5354b3a3031769454777a90d03b2b09f0a5d5f81d4d26fd91458a58ea1de4cb083756fa4cfae6328684
+  data.tar.gz: 62b7997d9a53c0ee472f745edaae46e78b6df6d54ff77af8ca4465bbb85afd642636c164863cf77eff4aaa537ed00c3779582203c935b34fa692853457c5b239

data/CHANGELOG.md

@@ -5,7 +5,37 @@ 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]
+## [1.2.0] - 2026-08-16
+
+### Added
+
+- `Poly::PolymorphicJoinError` (`lib/poly/polymorphic_join_error.rb`) — the
+  join-validation error raised from `lib/poly/joins.rb` is now namespaced
+  under `Poly`. The bare top-level `PolymorphicJoinError` constant remains as
+  a deprecated alias, so existing `rescue PolymorphicJoinError` call sites
+  keep working.
+- CI now covers a database axis (SQLite and PostgreSQL, the latter via a GitHub
+  Actions `services:` Postgres container) and an ActiveRecord/Rails version axis
+  (7.1, 7.2, 8.x), each matrix cell pinning the loaded AR version via the new
+  `ACTIVERECORD_VERSION` env var consumed by the `Gemfile`.
+- `spec/spec_helper.rb`'s database adapter is now parameterized via
+  `POLY_TEST_ADAPTER` (`sqlite3` default, or `postgresql`) instead of
+  hardcoding an in-memory SQLite connection.
+- README "Supported Databases" section documenting that MySQL is explicitly
+  unsupported (`AbstractMysqlAdapter` doesn't implement `supports_partial_index?`,
+  silently degrading `poly_prime_index` to a full-table unique index).
+- README and new specs (`spec/models/poly/stack_spec.rb`) documenting
+  `Poly::Stack`'s concurrency boundary — the `poly_stack_seize_prime`
+  demote-then-insert sequence in `lib/poly/stack.rb`, and the
+  `ActiveRecord::RecordNotUnique` failure mode it can hit under concurrent
+  writers. No new public API was added.
+
+### Fixed
+
+- README §5 ("Poly::Stack")'s "append-only" wording corrected: the contract
+  is immutable payload with mutable linkage/index metadata (`is_prime`,
+  `superseded_by_id` are mutated in place on supersession), not literally
+  immutable/append-only rows.
 
 ## [1.1.0] - 2026-07-07
 
@@ -70,7 +100,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   Creates methods like `joins_commentable(ClassName)` that validate the reverse
   `has_many`/`has_one` association before building the join SQL.
 
-[Unreleased]: https://github.com/whittakertech/poly/compare/v1.1.0...HEAD
+[1.2.0]: https://github.com/whittakertech/poly/compare/v1.1.0...v1.2.0
 [1.1.0]: https://github.com/whittakertech/poly/compare/v1.0.0...v1.1.0
 [1.0.0]: https://github.com/whittakertech/poly/compare/v0.2.0...v1.0.0
 [0.2.0]: https://github.com/whittakertech/poly/compare/v0.1.0...v0.2.0

data/README.md

@@ -63,6 +63,28 @@ bundle install
 
 ---
 
+## Supported Databases
+
+Poly is tested in CI against **SQLite** and **PostgreSQL** (both Ruby x
+ActiveRecord 7.1/7.2/8.x combinations -- see `.github/workflows/ci.yml`).
+
+**MySQL is explicitly not supported.** `Poly::Migration#poly_prime_index`
+(see below) relies on a partial/conditional unique index --
+`add_index table, [...], unique: true, where: 'is_prime'` -- to enforce
+"exactly one prime row per resource+role, many non-primes allowed."
+PostgreSQL's and SQLite3's ActiveRecord adapters both override
+`supports_partial_index?` to `true`; `ActiveRecord::ConnectionAdapters::AbstractMysqlAdapter`
+does **not** override it, so it inherits the abstract default of `false`.
+Because `schema_creation.rb` only emits the index's `WHERE` clause when
+`supports_partial_index?` is true, MySQL silently drops the clause instead
+of raising -- producing a full-table unique index instead of a partial one,
+and quietly breaking the single-prime-per-role invariant (it would instead
+forbid more than one row total per resource+role). This is a silent
+correctness bug, not just reduced support, so running Poly against MySQL is
+unsupported rather than merely uncautioned-against.
+
+---
+
 # Quickstart
 
 ### Migration
@@ -143,7 +165,7 @@ AND "comments"."commentable_type" = 'Post'
 > # has_one :comment, as: :commentable   — also valid
 > ```
 >
-> Otherwise `PolymorphicJoinError` is raised.
+> Otherwise `Poly::PolymorphicJoinError` is raised.
 
 ### Join Flow
 
@@ -332,13 +354,17 @@ Supports:
 # 5. Poly::Stack
 
 A polymorphic, role-discriminated **history** where one entry is the current
-**prime** — the top of an append-only stack. `Poly::Role` is
+**prime** — the top of the stack. `Poly::Role` is
 the same idea at cardinality 1; `Poly::Stack` opens it up to many entries per
 `(resource, role)`, with the most-recently created always prime.
 
-It is **append-only** and **payload agnostic**: it manages the prime marker and
-an audit edge only. The payload column, the actor, and the reason belong to your
-model — Poly::Stack never reads them.
+It is **payload agnostic** with an **immutable payload, mutable linkage/index
+metadata** contract: it manages the prime marker and an audit edge only. The
+payload column, the actor, and the reason belong to your model — Poly::Stack
+never reads or rewrites them. What Poly::Stack *does* mutate in place, on
+supersession, are the prior prime row's own `is_prime` and `superseded_by_id`
+columns — historical rows are never deleted, but their linkage/index metadata
+is updated, so this is not a literally append-only/immutable-row contract.
 
 ## Schema
 
@@ -474,6 +500,36 @@ scope :trashed, -> { where_status(:trash) }
 > [!NOTE]
 > Prefer explicit scopes over `default_scope` for soft-delete.
 
+## Concurrency Boundary
+
+`poly_stack_seize_prime` (the `before_create` callback that demotes the prior
+prime and claims the new one) is **not** wrapped in an explicit row lock or
+transaction. Two writers racing the same `(resource, role)` at the same time
+can both read the same prior prime, both demote it, and both attempt to
+insert with `is_prime: true`.
+
+When that happens, it is the partial unique index (`add_index ..., unique:
+true, where: 'is_prime'`, built by `poly_prime_index`) — not the
+callback — that enforces "at most one prime per `(resource, role)`". The
+losing writer's `INSERT` raises `ActiveRecord::RecordNotUnique`, at the
+`INSERT` itself, after the callback has already run.
+
+Poly::Stack does not catch or retry this internally. **Callers that may write
+concurrently to the same `(resource, role)` should be prepared to rescue
+`ActiveRecord::RecordNotUnique` around the create call and retry** — e.g.
+re-fetch the current prime and re-attempt the create — rather than assuming a
+single `create!` is race-safe:
+
+```ruby
+begin
+  post.statuses.create!(state: 'public')
+rescue ActiveRecord::RecordNotUnique
+  # another writer won the race for this (resource, role); re-fetch and
+  # decide whether to retry, merge, or surface a conflict to the caller.
+  retry_or_handle_conflict
+end
+```
+
 ## Priming Flow
 
 ```mermaid

data/lib/poly/joins.rb

@@ -19,12 +19,12 @@ module Poly::Joins
         next if singleton_class.method_defined?(method_name)
 
         define_singleton_method(method_name) do |klass|
-          raise PolymorphicJoinError, 'Expected an ActiveRecord model' unless klass <= ActiveRecord::Base
+          raise Poly::PolymorphicJoinError, 'Expected an ActiveRecord model' unless klass <= ActiveRecord::Base
 
           base_klass = klass.base_class
 
           unless join_allowed?(klass, as: assoc_name)
-            raise PolymorphicJoinError,
+            raise Poly::PolymorphicJoinError,
                   "Polymorphic join requires #{base_klass} to declare: " \
                   "has_many :#{name.underscore.pluralize}, as: :#{assoc_name}"
           end

data/lib/poly/polymorphic_join_error.rb

@@ -1,3 +1,8 @@
 # frozen_string_literal: true
 
-class PolymorphicJoinError < StandardError; end
+class Poly::PolymorphicJoinError < StandardError; end
+
+# Deprecated: use Poly::PolymorphicJoinError. Kept as an alias so existing
+# `rescue PolymorphicJoinError` / `is_a?(PolymorphicJoinError)` callers keep
+# working across the 1.2.0 rename.
+PolymorphicJoinError = Poly::PolymorphicJoinError

data/lib/poly/stack.rb

@@ -1,8 +1,12 @@
 # frozen_string_literal: true
 
 # Card-side concern. Turns a polymorphic, role-discriminated model (the "card"
-# model, e.g. Status) into an append-only stack where the most-recently created
-# card per (resource, role) is the current "prime" — the top of the stack.
+# model, e.g. Status) into a stack where the most-recently created card per
+# (resource, role) is the current "prime" — the top of the stack. The
+# contract is immutable payload, mutable linkage/index metadata: prior rows
+# are never deleted, but their `is_prime` and `superseded_by_id` columns are
+# mutated in place when a new card supersedes them — this is not a literally
+# append-only/immutable-row stack.
 #
 #   class Status < ApplicationRecord
 #     belongs_to :resource, polymorphic: true
@@ -50,6 +54,18 @@ module Poly::Stack
   # remember it so the supersession edge can be linked once we have an id.
   # Runs before insert: at INSERT time there is exactly one is_prime row, so
   # the partial unique index is satisfied (zero primes momentarily is legal).
+  #
+  # Concurrency boundary: this demote-then-insert sequence is NOT wrapped in
+  # an explicit row lock or transaction. Two concurrent writers racing the
+  # same (resource, role) can both read the same prior prime, both demote it
+  # via #update_columns, and both attempt to insert with is_prime: true. The
+  # second writer's INSERT then raises ActiveRecord::RecordNotUnique — not
+  # here in the callback, but afterward, once ActiveRecord issues the actual
+  # INSERT. It is the partial unique index (`poly_prime_index` /
+  # `index_#{table}_prime`, see lib/poly/migration.rb), not this callback,
+  # that actually enforces "at most one prime per (resource, role)" under a
+  # race. Poly::Stack does not retry internally; see README's "Poly::Stack"
+  # section for the recommended caller-side rescue-and-retry pattern.
   def poly_stack_seize_prime
     cols = self.class.poly_stack_columns
     @poly_stack_superseded = self.class

data/lib/poly/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Poly
-  VERSION = '1.1.0'
+  VERSION = '1.2.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: poly
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Lee Whittaker
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-07 00:00:00.000000000 Z
+date: 2026-08-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord