poly 1.0.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 56f2e1989d5977256fd93964e07d62d3a26b696bc469baf3ddf477141eb7f383
-  data.tar.gz: 33239362e770c93e2871754f9697763c893960af1e0238aac59ddfd94a8b7399
+  metadata.gz: ba17496c0d7031f1877d3aa61200842efd24cb1381c12ecb597e5b4c80ac65d7
+  data.tar.gz: 9bf0d37b9106badbf5672f3b1534e5c8e8161e3934ead590b56415a17196eda5
 SHA512:
-  metadata.gz: 190707ca692b512d914adcd3b5cfbdfab79a14730ce14043a6c361642ebb6b193941ae75909e24a6405b9f96c23b746b61d9b66daa77255cb0a9241cc3b3be5a
-  data.tar.gz: 6ae262801aaab5a09416080fb36df87a9ee65918698ab08bc12e1e2b6c612c9d9bee288a396842bc89c6b165e6515d8b50f84009f5670b5111a2c1ff2be1735e
+  metadata.gz: bf46bda44abfaccfb137c84cf1a6da3a6d3a6d0ad901e5354b3a3031769454777a90d03b2b09f0a5d5f81d4d26fd91458a58ea1de4cb083756fa4cfae6328684
+  data.tar.gz: 62b7997d9a53c0ee472f745edaae46e78b6df6d54ff77af8ca4465bbb85afd642636c164863cf77eff4aaa537ed00c3779582203c935b34fa692853457c5b239

data/CHANGELOG.md

@@ -5,7 +5,56 @@ 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
+
+### Added
+
+- `Poly::Stack` — polymorphic, role-discriminated append-only history with a single
+  "prime" (golden-child) card per `(resource, role)`, enforced by a database-level
+  partial unique index. Payload-agnostic: manages only the prime marker
+  (`is_prime`) and audit edge (`superseded_by_id`); the payload column, actor, and
+  reason belong to the consuming model.
+- `where:` option on `poly_resource_index` and `poly_owner_index` migration
+  helpers — passes a partial-index condition through to `add_index`.
+
+### Changed
+
+- `poly_prime_index` is now implemented as sugar on top of `poly_resource_index`
+  (`where: 'is_prime'`) instead of duplicating its own `add_index` call. The
+  generated index name (`index_<table>_prime`) and indexed columns are
+  unchanged, so this is not a breaking change for existing schemas.
 
 ## [1.0.0] - 2026-02-18
 
@@ -51,7 +100,8 @@ 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/leewhittaker/poly/compare/v1.0.0...HEAD
-[1.0.0]: https://github.com/leewhittaker/poly/compare/v0.2.0...v1.0.0
-[0.2.0]: https://github.com/leewhittaker/poly/compare/v0.1.0...v0.2.0
-[0.1.0]: https://github.com/leewhittaker/poly/releases/tag/v0.1.0
+[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
+[0.1.0]: https://github.com/whittakertech/poly/releases/tag/v0.1.0

data/README.md

@@ -1,73 +1,192 @@
 # Poly
 
-Type-safe joins, role identity, and owner identity for polymorphic `belongs_to` associations in Rails.
+Type-safe joins, role identity, owner identity, and migration discipline for polymorphic `belongs_to` associations in Rails.
+
+---
+
+## What Is Poly?
+
+Poly is a structural identity substrate for Rails polymorphism.
+
+It provides:
+
+- Type-safe polymorphic joins
+- Role semantics for polymorphic relationships
+- Owner stamping for write-time identity projection
+- Migration helpers for consistent schema topology
+
+Poly does **not** implement tenancy, policy, or business logic.
+
+---
+
+## Mental Model
+
+```mermaid
+flowchart LR
+    A[ActiveRecord Model]
+    B[Polymorphic belongs_to]
+    C[Role Column]
+    D[Owner Columns]
+    E[Composite Indexes]
+
+    A --> B
+    B --> C
+    B --> D
+    C --> E
+    D --> E
+```
+
+Poly strengthens the edges around polymorphic identity.
+
+---
 
 ## Installation
 
 Add to your Gemfile:
 
 ```ruby
-gem 'poly'
+gem "poly"
 ```
 
-Then run `bundle install`.
+Then:
+
+```bash
+bundle install
+```
+
+---
 
 ## Requirements
 
 - Ruby >= 3.2
 - ActiveRecord >= 7.1
 
-## Usage
+---
+
+## Supported Databases
 
-### Poly::Joins
+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`).
 
-Generates type-safe `INNER JOIN` methods for polymorphic associations. Include the module in a model that has a polymorphic `belongs_to`, and it will define a `joins_<association>` class method for each one.
+**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
 
 ```ruby
-class Comment < ApplicationRecord
-  belongs_to :commentable, polymorphic: true
+class CreateItems < ActiveRecord::Migration[7.1]
+  include Poly::Migration
 
-  include Poly::Joins
+  def change
+    create_table :items do |t|
+      poly_resource t, :itemable, null: false
+      poly_role     t, :itemable, null: false
+      poly_owner    t, null: false
+      t.timestamps
+    end
+
+    poly_resource_index :items, :itemable
+    poly_owner_index    :items
+  end
 end
+```
 
-class Post < ApplicationRecord
-  has_many :comments, as: :commentable
+---
+
+### Model
+
+```ruby
+class Item < ApplicationRecord
+  belongs_to :itemable, polymorphic: true
+
+  include Poly::Role
+  include Poly::Owners
+
+  poly_role  :itemable
+  poly_owner :itemable, owner: -> { account }
 end
+```
+
+---
+
+# Modules
+
+---
+
+# 1. Poly::Joins
+
+Generates type-safe `INNER JOIN` methods for polymorphic associations.
+
+### Example
 
-class User < ApplicationRecord
-  has_many :comments, as: :commentable
+```ruby
+class Comment < ApplicationRecord
+  belongs_to :commentable, polymorphic: true
+  include Poly::Joins
 end
 ```
 
-Now you can join through the polymorphic association by passing the target class:
+Now:
 
 ```ruby
-# Join comments to the posts table
 Comment.joins_commentable(Post)
-# => SELECT "comments".* FROM "comments"
-#    INNER JOIN "posts"
-#    ON "comments"."commentable_id" = "posts"."id"
-#    AND "comments"."commentable_type" = 'Post'
+Comment.joins_commentable(User)
+```
 
-# Chainable with other scopes
-Comment.joins_commentable(Post).where(posts: { title: 'Hello' })
+Generated SQL:
 
-# Join to a different target type
-Comment.joins_commentable(User).where(users: { name: 'Lee' })
+```sql
+INNER JOIN "posts"
+ON "comments"."commentable_id" = "posts"."id"
+AND "comments"."commentable_type" = 'Post'
 ```
 
-**Safety:** The target class must declare the reverse association (`has_many` or `has_one` with `as: :commentable`). If it doesn't, a `PolymorphicJoinError` is raised:
-
-```ruby
-Comment.joins_commentable(Unrelated)
-# => PolymorphicJoinError: Unrelated must declare has_one/has_many as: :commentable
+> [!IMPORTANT]
+> The target class must declare the reverse association:
+>
+> ```ruby
+> has_many :comments, as: :commentable
+> # has_one :comment, as: :commentable   — also valid
+> ```
+>
+> Otherwise `Poly::PolymorphicJoinError` is raised.
+
+### Join Flow
+
+```mermaid
+sequenceDiagram
+    participant M as Model
+    participant PJ as Poly::Joins
+    participant T as Target
+
+    M->>PJ: joins_commentable(Post)
+    PJ->>T: Validate reverse association
+    PJ->>M: Generate INNER JOIN
 ```
 
-### Poly::Role
+---
 
-Adds a validated role column to a polymorphic association. This is useful when a single polymorphic relationship needs to distinguish between different roles or categories.
+# 2. Poly::Role
 
-Your table needs a `<association>_role` string column:
+Adds semantic identity to polymorphic relationships.
+
+## Schema
 
 ```ruby
 create_table :taggings do |t|
@@ -76,11 +195,12 @@ create_table :taggings do |t|
   t.timestamps
 end
 
-# Index: composite on (taggable_type, taggable_id, taggable_role) if uniqueness is required
-add_index :taggings, [:taggable_type, :taggable_id, :taggable_role], unique: true
+add_index :taggings,
+  [:taggable_type, :taggable_id, :taggable_role],
+  unique: true
 ```
 
-Then include the module and declare the role-enabled association:
+## Model
 
 ```ruby
 class Tagging < ApplicationRecord
@@ -89,80 +209,110 @@ class Tagging < ApplicationRecord
   include Poly::Role
 
   poly_role :taggable
-  # optionally:
-  # poly_role :taggable, max_length: 128
   # poly_role :taggable, immutable: true
 end
 ```
 
-This gives you:
+## What You Get
 
-- **Normalization** — roles are stripped and downcased before validation and before `for_role` queries
-- **Validation** — roles must match `/\A[a-z0-9_]+\z/` and be at most 64 characters (configurable via `max_length:`)
-- **Scope** — `for_role` queries by role, normalizing the input automatically
-- **Immutability** — `immutable: true` adds an `on: :update` validation that prevents role changes after create
+- Normalization (`strip + downcase`)
+- Format validation (`/\A[a-z0-9_]+\z/`)
+- Length validation (`max_length:`, default `64`)
+- `for_role` scope
+- Optional immutability
 
 ```ruby
-tagging = Tagging.new(taggable: post, taggable_role: '  Primary  ')
-tagging.valid?
-tagging.taggable_role # => "primary"
+Tagging.for_role("  PRIMARY ")
+# => matches "primary"
+```
 
-Tagging.for_role('  PRIMARY  ')
-# => normalizes to 'primary' before querying
+> [!NOTE]
+> `immutable: true` prevents role changes after create.
+
+### Role Identity Model
+
+```mermaid
+flowchart TD
+    A[Polymorphic Edge]
+    B[Role Column]
+    C[Semantic Meaning]
+
+    A --> B
+    B --> C
 ```
 
-### Poly::Owners
+---
+
+# 3. Poly::Owners
+
+Stamps root ownership at write time.
 
-Stamps `owner_type`/`owner_id` columns before validation. Useful for recording data ownership at write time without coupling the model to tenancy or policy logic.
+No traversal.
+No tenancy logic.
+Just identity projection.
 
-Your table needs `owner_type` and `owner_id` columns (in addition to your polymorphic resource columns):
+## Schema
 
 ```ruby
 create_table :coins do |t|
-  t.references :ledger, null: false
   t.references :resource, polymorphic: true, null: false
-  t.string :resource_role, null: false
-  t.string :owner_type
-  t.integer :owner_id
+  t.string  :owner_type
+  t.string  :owner_id
   t.timestamps
 end
 
-# Index: always composite — never index owner_type and owner_id separately
 add_index :coins, [:owner_type, :owner_id]
 ```
 
-Then declare how the owner should be resolved:
+> [!WARNING]
+> Never index `owner_type` and `owner_id` separately. Always composite.
+
+## Model
 
 ```ruby
 class Coin < ApplicationRecord
-  belongs_to :ledger
   belongs_to :resource, polymorphic: true
 
   include Poly::Owners
 
   poly_owner :resource, owner: -> { ledger&.account }
-  # optionally:
-  # poly_owner :resource, owner: -> { ledger&.account }, allow_nil: false
-  # poly_owner :resource, owner: -> { ledger&.account }, immutable: true
 end
 ```
 
-**`owner` resolution** — can be a `Proc` (evaluated in instance context), a `Symbol`/`String` (method name called on the record), or a direct `ActiveRecord::Base` instance. The owner must be persisted; an `ArgumentError` is raised otherwise.
+## Owner Resolution Options
+
+| Option         | Default       | Description                        |
+|----------------|---------------|------------------------------------|
+| `type_column:` | `:owner_type` | Column storing class name          |
+| `id_column:`   | `:owner_id`   | Column storing owner ID            |
+| `allow_nil:`   | `true`        | Allow owner to resolve to nil; if `false`, raise instead |
+| `immutable:`   | `false`       | Prevent owner changes after create |
+
+> [!IMPORTANT]
+> Owner must resolve to a persisted `ActiveRecord::Base`.
+>
+> Otherwise an `ArgumentError` is raised.
+
+### Ownership Flow
 
-**Options:**
+```mermaid
+sequenceDiagram
+    participant Record
+    participant PO as Poly::Owners
+    participant Owner
 
-| Option | Default | Description |
-|---|---|---|
-| `type_column:` | `:owner_type` | Column to store the owner class name |
-| `id_column:` | `:owner_id` | Column to store the owner id |
-| `allow_nil:` | `true` | When `false`, raises if the owner resolves to `nil` |
-| `immutable:` | `false` | When `true`, prevents owner changes after create via `on: :update` validation |
+    Record->>PO: before_validation
+    PO->>Owner: resolve owner
+    PO->>Record: stamp owner_type + owner_id
+```
+
+---
 
-### Poly::Migration
+# 4. Poly::Migration
 
-Adds migration helpers so polymorphic resource/role/owner columns are declared consistently.
+Migration helpers for consistent polymorphic topology.
 
-Use it in your migration base class:
+## Usage
 
 ```ruby
 class ApplicationMigration < ActiveRecord::Migration[7.1]
@@ -170,65 +320,272 @@ class ApplicationMigration < ActiveRecord::Migration[7.1]
 end
 ```
 
-Supported styles:
+Supports:
+
+- `create_table`
+- `change_table`
+- direct `add_column` style
+
+## Helpers
+
+| Helper | Purpose |
+|--------|----------|
+| `poly_resource` | Adds `<name>_type` + `<name>_id` |
+| `poly_role` | Adds `<name>_role` |
+| `poly_owner` | Adds owner columns |
+| `poly_stack` | Adds `is_prime` + `superseded_by_id` |
+| `poly_resource_index` | Composite resource index (supports `where:`, `unique:`, `index_name:`) |
+| `poly_owner_index` | Composite owner index (supports `where:`, `unique:`, `index_name:`) |
+| `poly_prime_index` | Partial unique index (one prime per resource/role); sugar for `poly_resource_index(..., where: 'is_prime')` |
+
+## ID Flexibility
+
+`id_type` defaults to `:string`.
+
+Supports:
+
+- UUID
+- ULID
+- bigint
+- custom identifiers
+
+---
+
+# 5. Poly::Stack
+
+A polymorphic, role-discriminated **history** where one entry is the current
+**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 **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
+
+```ruby
+create_table :statuses do |t|
+  t.references :resource, polymorphic: true, null: false
+  t.string  :resource_role, null: false
+  t.string  :state, null: false        # your payload — Poly::Stack is agnostic about it
+  t.boolean :is_prime, null: false, default: false
+  t.integer :superseded_by_id          # audit edge (unconstrained)
+  t.timestamps
+end
+
+# Exactly one prime per resource per role, enforced by the database.
+add_index :statuses, %i[resource_type resource_id resource_role],
+          unique: true, where: 'is_prime', name: 'index_statuses_prime'
+```
+
+Or with `Poly::Migration`:
 
-- `create_table` / `change_table` via a table builder (`t`)
-- direct existing-table operations via `add_column` style (pass table name)
+```ruby
+create_table :statuses do |t|
+  poly_resource t, :resource, null: false
+  poly_role t, :resource, null: false
+  t.string :state, null: false
+  poly_stack t
+  t.timestamps
+end
 
-#### Create Table / Change Table
+poly_prime_index :statuses, :resource
+```
+
+## The Entry Model
+
+`Poly::Stack` is an **entry-side** concern — the externality includes it, exactly
+as `Coin` includes `Poly::Role`:
 
 ```ruby
-class CreateCoins < ApplicationMigration
-  def change
-    create_table :coins do |t|
-      poly_resource t, :resource, null: false
-      poly_role t, :resource, null: false
-      poly_owner t, null: false
-      t.timestamps
-    end
+class Status < ApplicationRecord
+  belongs_to :resource, polymorphic: true
 
-    poly_resource_index :coins, :resource
-    poly_owner_index :coins
-  end
+  include Poly::Joins
+  include Poly::Stack
+
+  poly_stack :resource
 end
 ```
 
-#### Existing Table (add_column style)
+That gives the `prime` scope and append-only priming — the newest entry per
+`(resource, role)` becomes prime, the prior prime is demoted, and its
+`superseded_by_id` is linked:
 
 ```ruby
-class AddPolyColumnsToCoins < ApplicationMigration
-  def change
-    poly_resource :coins, :resource, null: false
-    poly_role :coins, :resource, null: false
-    poly_owner :coins, null: false
+Status.create!(resource: post, resource_role: 'status', state: 'draft')
+Status.create!(resource: post, resource_role: 'status', state: 'public')
+
+Status.where(resource: post, resource_role: 'status').prime  # => the 'public' entry
+```
+
+## Wiring a Parent
+
+Poly ships **only the entry concern**. The parent-side accessor macro is yours to
+write — the way Midas writes `has_coin` on `Poly::Role`. It's just `for_role`
+(from `Poly::Role`) plus the `prime` scope, composed into associations and
+scopes:
 
-    poly_resource_index :coins, :resource
-    poly_owner_index :coins
+```ruby
+# in your app — a Stackable concern providing a has_stack macro
+module Stackable
+  extend ActiveSupport::Concern
+
+  class_methods do
+    def has_stack(name, class_name: name.to_s.classify, value: :state, dependent: :destroy)
+      label  = name.to_s
+      plural = label.pluralize.to_sym
+      stamp  = :"stack_stamp_#{name}"
+
+      # so `post.statuses << Status.new(...)` stamps the role on add
+      define_method(stamp) do |entry|
+        entry.resource_role = label if entry.respond_to?(:resource_role=) && entry.resource_role.blank?
+      end
+
+      has_many plural, -> { for_role(label).order(created_at: :desc) },
+               as: :resource, class_name: class_name, dependent: dependent, before_add: stamp
+      has_one name, -> { for_role(label).prime },
+              as: :resource, class_name: class_name
+
+      entries = -> { class_name.constantize }
+      scope :"where_#{name}",   ->(*v) { joins(name).merge(entries.call.where(value => v.flatten)) }
+      scope :"ever_#{name}",    ->(*v) { where(id: joins(plural).merge(entries.call.where(value => v.flatten)).select(:id)) }
+      scope :"without_#{name}", ->(*v) { where.not(id: public_send(:"where_#{name}", *v).select(:id)) }
+      scope :"never_#{name}",   ->(*v) { where.not(id: public_send(:"ever_#{name}", *v).select(:id)) }
+    end
   end
 end
+
+class Post < ApplicationRecord
+  include Stackable
+
+  has_stack :status
+  has_stack :visibility, class_name: 'Status'  # second stack, same table, own prime
+end
 ```
 
-#### Helper Reference
+Which gives you:
 
-| Helper | Purpose |
-|---|---|
-| `poly_resource(table_or_builder, name, null: true, id_type: :string)` | Adds `<name>_type` and `<name>_id` |
-| `poly_role(table_or_builder, name, null: true)` | Adds `<name>_role` |
-| `poly_owner(table_or_builder, type_column: :owner_type, id_column: :owner_id, id_type: :string, null: true)` | Adds owner type/id columns |
-| `poly_resource_index(table, name, unique: false)` | Adds index on `<name>_type`, `<name>_id` |
-| `poly_owner_index(table, type_column: :owner_type, id_column: :owner_id, unique: false)` | Adds index on owner columns |
+```ruby
+post.status                          # => prime Status entry (preloadable has_one)
+post.statuses                        # => full stack, newest-first (has_many)
+
+post.statuses.create!(state: 'trash')        # append an entry; it becomes prime
+post.statuses << Status.new(state: 'public') # also appends; role stamped on add
 
-`id_type` defaults to `:string` so owner/resource IDs can store bigint, UUID, ULID, or other identifier formats consistently.
+Post.where_status('public')          # prime state = public
+Post.without_status('trash')         # prime != trash, OR no entry yet
+Post.ever_status('trash')            # any entry in history = trash (de-duped)
+Post.never_status('trash')           # no entry ever = trash
 
-## Development
+Post.includes(:status)               # preload the prime to avoid N+1
+```
+
+## Soft-Delete
+
+`Poly::Stack` is the primitive behind soft-delete-as-history: a `trash` entry is a
+deletion, a later entry is a restore, and the stack is the audit trail. The
+*meaning* stays in your app — one-liners over your `has_stack` scopes:
+
+```ruby
+scope :live,    -> { without_status(:trash) }
+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
+sequenceDiagram
+    participant Entry as New Entry
+    participant PS as Poly::Stack
+    participant Prior as Prior Prime
+
+    Entry->>PS: before_create
+    PS->>Prior: demote (is_prime = false)
+    PS->>Entry: claim prime (is_prime = true)
+    Entry->>PS: after_create
+    PS->>Prior: link superseded_by_id
+```
+
+---
+
+# Design Principles
+
+Poly is intentionally minimal.
+
+It does not:
+
+- Implement tenancy
+- Infer ownership
+- Traverse associations
+- Inject business logic
+- Generate constraints automatically
+- Enforce policy
+
+It provides structure only.
+
+---
+
+# Development
 
 ```bash
-bundle install              # Install dependencies
-bundle exec rspec           # Run tests
-bundle exec rubocop         # Lint
-COVERAGE=true bundle exec rspec  # Run tests with coverage report
+bundle install
+bundle exec rspec
+bundle exec rubocop
+COVERAGE=true bundle exec rspec
 ```
 
-## License
+---
+
+# Stability
+
+Poly v1.0.0 declares:
+
+- Public API is stable
+- Breaking changes follow SemVer
+- New features are additive
+- No structural refactors planned
+
+---
+
+# License
 
-Released under the [MIT License](https://opensource.org/licenses/MIT).
+MIT — see [LICENSE](LICENSE)

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
@@ -54,5 +54,3 @@ module Poly::Joins
     end
   end
 end
-
-class PolymorphicJoinError < StandardError; end

data/lib/poly/migration.rb

@@ -40,12 +40,37 @@ module Poly::Migration
     end
   end
 
-  def poly_resource_index(table, name, unique: false)
-    add_index table, [:"#{name}_type", :"#{name}_id"], unique: unique
+  # Stack columns (golden-child history): the prime marker and the audit edge.
+  # Table-builder helper (create_table/change_table):
+  #   poly_stack t
+  # Direct helper (add_column style):
+  #   poly_stack :statuses
+  def poly_stack(table_or_builder, id_type: :string)
+    if table_builder?(table_or_builder)
+      table_or_builder.boolean :is_prime, null: false, default: false
+      table_or_builder.public_send(id_type, :superseded_by_id, null: true)
+    else
+      add_column table_or_builder, :is_prime, :boolean, null: false, default: false
+      add_column table_or_builder, :superseded_by_id, id_type, null: true
+    end
+  end
+
+  def poly_resource_index(table, name, unique: false, where: nil, index_name: nil, columns: nil)
+    add_index table, columns || [:"#{name}_type", :"#{name}_id"],
+              unique: unique, where: where, name: index_name
+  end
+
+  # Partial unique index enforcing exactly one prime per (resource, role).
+  def poly_prime_index(table, name = :resource)
+    poly_resource_index table, name,
+                        unique: true, where: 'is_prime',
+                        index_name: "index_#{table}_prime",
+                        columns: [:"#{name}_type", :"#{name}_id", :"#{name}_role"]
   end
 
-  def poly_owner_index(table, type_column: :owner_type, id_column: :owner_id, unique: false)
-    add_index table, [type_column, id_column], unique: unique
+  def poly_owner_index(table, type_column: :owner_type, id_column: :owner_id, unique: false, where: nil,
+                       index_name: nil)
+    add_index table, [type_column, id_column], unique: unique, where: where, name: index_name
   end
 
   private

data/lib/poly/polymorphic_join_error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+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

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+# Card-side concern. Turns a polymorphic, role-discriminated model (the "card"
+# 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
+#     include Poly::Joins
+#     include Poly::Stack
+#     poly_stack :resource
+#   end
+#
+# Poly::Stack builds on Poly::Role (the resource_role discriminator) and adds
+# only `is_prime` (the enforced golden-child marker) and `superseded_by_id`
+# (an unconstrained audit edge). It is deliberately payload agnostic: it does
+# not define the payload column, the actor, or the reason — those belong to the
+# host model. The parent-side accessor macro (`has_stack`) is the consumer's to
+# write, the way Midas writes `has_coin` on Poly::Role — see the README.
+module Poly::Stack
+  extend ActiveSupport::Concern
+  include Poly::Role
+
+  included do
+    class_attribute :poly_stack_association, instance_accessor: false
+  end
+
+  class_methods do
+    # Declares the stack. `assoc_name` is the polymorphic belongs_to whose
+    # *_role column discriminates independent stacks on the same table.
+    def poly_stack(assoc_name, max_length: 64)
+      poly_role(assoc_name, max_length: max_length)
+      self.poly_stack_association = assoc_name.to_sym
+
+      scope :prime, -> { where(is_prime: true) }
+
+      before_create :poly_stack_seize_prime
+      after_create  :poly_stack_chain_superseded
+    end
+
+    def poly_stack_columns
+      assoc = poly_stack_association
+      { type: :"#{assoc}_type", id: :"#{assoc}_id", role: :"#{assoc}_role" }
+    end
+  end
+
+  private
+
+  # Demote the current prime (if any) so this card can take its place, and
+  # 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
+                                 .where(cols[:type] => self[cols[:type]],
+                                        cols[:id] => self[cols[:id]],
+                                        cols[:role] => self[cols[:role]])
+                                 .prime
+                                 .first
+    @poly_stack_superseded&.update_columns(is_prime: false)
+    self.is_prime = true
+  end
+
+  # Audit edge (decoration, unconstrained): the old prime points forward to the
+  # card that replaced it. Safe to run after insert since it carries no index.
+  def poly_stack_chain_superseded
+    @poly_stack_superseded&.update_columns(superseded_by_id: id)
+  end
+end

data/lib/poly/version.rb

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

data/lib/poly.rb

@@ -2,9 +2,11 @@
 
 require 'active_support/concern'
 require 'poly/version'
+require 'poly/polymorphic_join_error'
 require 'poly/joins'
 require 'poly/role'
 require 'poly/owners'
+require 'poly/stack'
 require 'poly/migration'
 
 module Poly

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: poly
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Lee Whittaker
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-02-19 00:00:00.000000000 Z
+date: 2026-08-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -38,7 +38,8 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '7.1'
-description: Type-safe joins and role identity for polymorphic belongs_to associations.
+description: Type-safe joins, role identity, owner stamping, and append-only golden-child
+  history (Poly::Stack) for polymorphic belongs_to associations.
 email:
 - lee@whittakertech.com
 executables: []
@@ -53,15 +54,17 @@ files:
 - lib/poly/joins.rb
 - lib/poly/migration.rb
 - lib/poly/owners.rb
+- lib/poly/polymorphic_join_error.rb
 - lib/poly/role.rb
+- lib/poly/stack.rb
 - lib/poly/version.rb
-homepage: https://github.com/leewhittaker/poly
+homepage: https://github.com/whittakertech/poly
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/leewhittaker/poly
-  source_code_uri: https://github.com/leewhittaker/poly
-  changelog_uri: https://github.com/leewhittaker/poly/blob/main/CHANGELOG.md
+  homepage_uri: https://github.com/whittakertech/poly
+  source_code_uri: https://github.com/whittakertech/poly
+  changelog_uri: https://github.com/whittakertech/poly/blob/master/CHANGELOG.md
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []