poly 1.1.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b553ab920c023d3f1e23a5de23c35bc75798827f6dfe5db2bd9369e0875586b0
-  data.tar.gz: 7ce045f76258951d9b3a281f38c369c81b9decc2cbfaca7ce9a73279605ae792
+  metadata.gz: '07925273fda2c3e5292b1f56d776f448d7542c1c28bc5f210e6738e2d682fa39'
+  data.tar.gz: a5797ce40826d0f0ee5f3a9835e38ebaae0e85219e6b7c0877effac315640d0b
 SHA512:
-  metadata.gz: 7242fafe809c07f8b801ed5fd049519ffc7d403dd8254e1323fa7d794dffa549dd8c5070317a1ff6f2dd8f185b603baef121c2ab6eccced5dfd9e542dad006b3
-  data.tar.gz: 519f7047228088054991bd4288eb52f1e39b98839976dfaadb1c68b3f46a0b0d97c7f1c088543be9f58838978e989b048d622bef4a768e4df39a9733dee83098
+  metadata.gz: '01933f6479724033886a320905e2149d8487d3a3dcee193550cebe7b8b9b38fa38a4b477b9c92ba2fd455d83087dccec3a70b664fed5e603489d91e48ef33114'
+  data.tar.gz: cade850271da454356ecce2ac07e316ccf5c4b36b6f03f164827c27f2af986abc4c4804b9198115cbf38502111bd32fef8e08f3eec8cbcbfb8e7323bb87d1577

data/CHANGELOG.md

@@ -5,7 +5,75 @@ 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.3.0] - 2026-08-22
+
+### Changed
+
+- **Lowered the supported ActiveRecord/ActiveSupport floor from `>= 7.1` to
+  `>= 6.1`.** No library code changed: a full scan of `lib/poly/*.rb` found no
+  Rails 7.1+ APIs, and the only ActiveRecord internals Poly touches
+  (`arel_table`, `reflect_on_all_associations`, `reflect_on_association`,
+  `base_class`) have been stable since well before 6.1. The previous floor was
+  an end-of-life policy choice, not a technical constraint. Lowered so
+  hellodancerrails (Rails 6.1.7.10 / Ruby 3.3.11) can adopt Midas, which
+  depends on Poly.
+- CI gains a `6.1` cell on both the SQLite and PostgreSQL lanes, pinned to Ruby
+  3.3 -- the pairing hellodancerrails actually runs. 6.1 predates Ruby 3.4
+  entirely, so that combination is excluded.
+
+### Fixed
+
+- The PostgreSQL CI lane's `ruby/setup-ruby` step in `.gitea/workflows/ci.yml`
+  hardcoded `ruby-version: '3.4'` instead of reading `${{ matrix.ruby }}`, so
+  the matrix's Ruby axis was ignored on that lane.
+- `spec/models/poly/migration_spec.rb` hardcoded
+  `ActiveRecord::Migration[7.1]`, which raises `Unknown migration version` on
+  Rails 6.1. Test migrations now build against `POLY_MIGRATION_VERSION`,
+  derived from the ActiveRecord actually under test.
+- Shortened the `where:`-passthrough spec's table name, whose generated index
+  name (`index_poly_migration_where_indexes_on_resource_type_and_resource_id`,
+  67 chars) exceeded Rails 6.1's SQLite 64-character limit -- and PostgreSQL's
+  63-character limit on every version.
+
+### Development
+
+- The `6.1` bundle lane pins `concurrent-ruby < 1.3.5` (1.3.5 dropped the
+  implicit `require 'logger'` that ActiveSupport 6.1 relies on) and
+  `sqlite3 ~> 1.4` (Rails 6.1's SQLite3Adapter requires it; sqlite3 2.x needs
+  Rails 7.2+). Both are Gemfile-only -- neither is a runtime requirement of the
+  gem.
+
+## [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 +138,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

@@ -1,5 +1,10 @@
 # Poly
 
+[![Gem Version](https://img.shields.io/gem/v/poly)](https://rubygems.org/gems/poly)
+[![CI](https://github.com/whittakertech/poly/actions/workflows/ci.yml/badge.svg)](https://github.com/whittakertech/poly/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/whittakertech/poly/blob/master/LICENSE)
+[![Docs](https://img.shields.io/badge/docs-poly.whittakertech.com-blue)](https://poly.whittakertech.com)
+
 Type-safe joins, role identity, owner identity, and migration discipline for polymorphic `belongs_to` associations in Rails.
 
 ---
@@ -59,7 +64,35 @@ bundle install
 ## Requirements
 
 - Ruby >= 3.2
-- ActiveRecord >= 7.1
+- ActiveRecord >= 6.1
+
+Rails 6.1 is supported for legacy consumers and is exercised in CI on Ruby 3.3
+only (6.1 predates Ruby 3.4). On 6.1 the SQLite3 adapter enforces a 64-character
+index-name limit, so long table names may need an explicit `index_name:` on the
+`poly_*_index` helpers -- PostgreSQL applies a 63-character limit on every
+version, so this is good practice regardless.
+
+---
+
+## Supported Databases
+
+Poly is tested in CI against **SQLite** and **PostgreSQL** (both Ruby x
+ActiveRecord 6.1/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.
 
 ---
 
@@ -143,7 +176,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 +365,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 +511,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/Rakefile

@@ -6,4 +6,9 @@ require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
 RSpec::Core::RakeTask.new(:spec)
 
+require 'yard'
+namespace :docs do
+  YARD::Rake::YardocTask.new(:api)
+end
+
 task default: :spec

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.3.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: poly
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Lee Whittaker
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-07 00:00:00.000000000 Z
+date: 2026-08-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -16,28 +16,28 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.1'
+        version: '6.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.1'
+        version: '6.1'
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.1'
+        version: '6.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.1'
+        version: '6.1'
 description: Type-safe joins, role identity, owner stamping, and append-only golden-child
   history (Poly::Stack) for polymorphic belongs_to associations.
 email: