pluckr 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 490833f6b37ba16885bf0e67d69cea3aebaa12e932e88460815bab02c0db42da
+  data.tar.gz: c152bdeb70d2c0c99546e24c1c5055d8d6db2701bee263cfda9d34806b6cdc4f
+SHA512:
+  metadata.gz: a4e3e9ebce285dd7399aebc26958f9deff15cc6cd786876c82698b491f42759cf083e1ccd005311e1f610cb11fc40c608fbcc78b4710e09e4f0dcc62faa778a4
+  data.tar.gz: 46f29188b91f8942ba06ff1ca353d03e1f02be3bd80d8772a3ade972e757bd880a3446601fe6ed79273b95b5451b0e3cb06089ae9f845fc0248f99cef7f64439

data/CHANGELOG.md

@@ -0,0 +1,66 @@
+# Changelog
+
+## 0.1.0 (unreleased)
+
+- Initial MVP: `source`, `field` (+ `as:`), `one` (+ `via:`, nested), `exists`,
+  `count`/`sum`/`min`/`max` (correlated and independent), `where`/`order`/`limit`/`offset`,
+  `find`, `fetch`, `to_sql`, immutable result objects.
+- Compiles on PostgreSQL, MySQL and SQLite; values cast with the model's column types.
+- Reflection support: custom foreign/primary keys, custom table names,
+  self-referential associations, STI type conditions.
+- `where:` and `scope:` on `exists`/`count`/`sum`/`min`/`max`, correlated or independent.
+- `where.not` on root queries.
+- Raises `Pluckr::UnsupportedAssociation` for :through, polymorphic `belongs_to`,
+  scoped and `default_scope`d associations instead of generating wrong SQL;
+  polymorphic `has_many ..., as:` and STI children are supported.
+- `exists` compiles to `EXISTS (... LIMIT 1 OFFSET 0)`; the fence keeps PostgreSQL
+  from hashing the subquery into a full scan of the child table.
+- Scoped correlated aggregates read through a derived table, so a scope may join
+  (or be) the table it correlates to.
+- `Pluckr.batch { |b| b.count relation, as: :name }` - ad-hoc aggregates over
+  relations the caller already built, in one statement. Respects everything
+  ActiveRecord applied, including `:through`, polymorphic, scoped and
+  `default_scope`d associations.
+- Result objects serialise as their data: `as_json`, `to_json` and `to_hash`, so
+  `render json: result` no longer emits `{"attributes": {...}}`.
+- `Query.for(record)`, `.for(records)` and `.for(relation)` fetch a read model
+  for records already in memory, in one statement. Collections keep input order;
+  an unloaded relation becomes a subquery of its conditions alone, a paginated
+  one is resolved to primary keys first (two statements, its own page and order),
+  and `group`/`having` raises instead of generating invalid SQL.
+- `last`/`last!`/`take`/`take!` and a count for `first`/`last`/`take`
+  (`first(10)`), read with a `LIMIT` rather than by hydrating the chain and
+  throwing most of it away.
+- `count`/`size`/`exists?`/`any?`/`none?`/`empty?`/`one?`/`many?` ask the database (`COUNT(*)`,
+  `SELECT 1`) instead of letting Enumerable build every result object first; a
+  block still sends `any?`/`none?` back to Enumerable.
+- `find_by`/`find_by!` (ActiveRecord's arity: a condition is required) and
+  `explain`, which explains the statement Pluckr runs.
+- `find` takes several ids (or an array) and returns them in the order asked,
+  sends a block to Enumerable, and treats `find(nil)` as `RecordNotFound` -
+  ActiveRecord's behaviour in each case.
+- `find_each`/`in_batches` read a whole chain in pages, seeking by primary key
+  rather than paging with `OFFSET`. Needs `field` on the primary key; refuses a
+  chain that already has a `limit`/`offset`.
+- Every statement publishes an `ActiveSupport::Notifications` `fetch.pluckr`
+  event with `:name`, `:sql` and `:rows`, covering `fetch`, `find`, `first`,
+  `for` and `Pluckr.batch`.
+- Composite primary keys no longer break `first`; `find`/`for` raise a descriptive
+  error for them.
+- Query subclasses inherit `source` and `schema` from the query they subclass.
+- `first` orders by primary key when the relation has no order, like ActiveRecord.
+- Reading two connection pools in one statement raises instead of producing a
+  confusing SQL error.
+- `order:` directions are case-insensitive; `:ASC` used to reach Arel unchanged.
+- `first`/`last` select one row of a collection (`last :comment, via: :comments,
+  order: :created_at do ... end`), compiled as one correlated `LIMIT 1` subquery
+  per column, with the primary key as a tiebreaker so every column comes from the
+  same row.
+- `avg` (alias `average`) alongside `count`/`sum`/`min`/`max`, correlated,
+  independent and in `Pluckr.batch`. Returns a BigDecimal, or nil over no rows,
+  matching `relation.average`.
+- `sum` returns 0 rather than nil when nothing matched, matching
+  `relation.sum(:column)`; `min`/`max` still return nil.
+- `where:` accepts a callable returning a Hash, evaluated on every compilation,
+  so `-> { { created_at: 1.week.ago.. } }` is not frozen at class-load time.
+- Benchmarks in `benchmarks/read_models.rb`, results in `BENCHMARKS.md`.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Igor Kasyanchuk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/PROMPT.md

@@ -0,0 +1,112 @@
+# Pluckr — prompt for AI assistants
+
+Copy everything below the line into a system prompt or project instructions when generating or reviewing Rails code that uses Pluckr.
+
+---
+
+You are working in a Rails app that uses **Pluckr** (`gem "pluckr"`): a declarative read-query layer for ActiveRecord. A `Pluckr::Query` subclass declares the shape of the data; Pluckr compiles it into **exactly one SQL statement** and returns frozen, ActiveRecord-free result objects.
+
+## When to use it
+
+Use Pluckr for read models: index/show payloads, admin tables, dashboards, job payloads. Do not use it for writes, nested collections (`has_many` arrays), or as a serializer framework.
+
+Do **not** load ActiveRecord models and then project them. Do **not** add `has_pluckr` / `user.user_card` on models — that is N+1.
+
+## Define a query
+
+```ruby
+class UserCard < Pluckr::Query
+  source User
+
+  schema do
+    field :id
+    field :email
+
+    one :subscription do
+      field :id
+      field :name
+    end
+
+    exists :photos
+    count :videos
+    last :comment, via: :comments, order: :created_at do
+      field :body
+    end
+  end
+end
+```
+
+Lists and filters live on the query, not on `User`:
+
+```ruby
+UserCard.where(active: true).order(created_at: :desc).limit(50).fetch
+UserCard.find(id)
+UserCard.find_by(email: "a@b.c")       # nil if absent; find_by! raises
+UserCard.first                         # also first(n) / last / last(n) / take(n)
+UserCard.where(active: true).count     # COUNT(*) - also exists?/any?/none?/empty?/one?/many?
+UserCard.find_each { |row| ... }       # the whole table, a page at a time
+```
+
+## Records you already have (`.for`)
+
+When Ruby already holds AR records (or a relation of them), use `.for`. It is **one statement** for a collection (two for a paginated relation), and keeps array order.
+
+```ruby
+UserCard.for(user)            # one object (RecordNotFound if gone)
+UserCard.for(users)           # array, same order as `users`
+UserCard.for(User.active)     # relation filtered in SQL, not loaded into Ruby
+```
+
+Rules for `.for`:
+
+- a collection requires `field :id` (or `field :id, as: ...`) on the schema, so rows can be aligned to the input order; empty collection gives `[]`, a missing row raises `ActiveRecord::RecordNotFound`
+- the query's own `where` still applies, so `Query.where(active: true).for(inactive_record)` raises `RecordNotFound`
+- an unloaded relation is passed as a subquery, so only its conditions count: order and row count are the query's, not the relation's, and `lock` is dropped
+- a paginated relation (`limit`/`offset`) instead reads its primary keys first and the read model second - two statements, and the page and its order are the relation's own. No records are instantiated unless the relation joins to preload (`includes`/`eager_load`), whose `LIMIT` counts parent rows, so ActiveRecord pages it. Rows the query's own `where` excludes are absent rather than `RecordNotFound`; that is reserved for records you hand over yourself
+- `group`/`having` on a relation raises `Pluckr::ConfigurationError` - load it instead (`for(relation.to_a)`)
+- do not pass a Pluckr query to `.for`; it takes AR records. Use `fetch`
+- wrong model, or a composite primary key: `Pluckr::ConfigurationError`. Composite keys use `where(...).first`
+
+Never do this:
+
+```ruby
+users.each { |u| UserCard.for(u) }   # N queries
+users.map { |u| UserCard.find(u.id) }
+```
+
+## Dashboards and ad-hoc aggregates
+
+No `source` → one object of independent subqueries:
+
+```ruby
+class DashboardStats < Pluckr::Query
+  schema do
+    count :users, from: User
+    sum :paid, from: Order, column: :amount, where: { status: "paid" }
+  end
+end
+DashboardStats.fetch
+```
+
+Runtime / association-scoped aggregates (including `:through`, scoped associations): `Pluckr.batch`.
+
+```ruby
+Pluckr.batch do |b|
+  b.count user.videos, as: :video_count
+  b.exists user.photos, as: :has_photos
+end
+```
+
+## DSL rules
+
+- `field` / `one` / `exists` / `count`/`sum`/`avg`/`min`/`max` / `first`/`last`
+- `one` is singular only (`belongs_to` / `has_one`). `has_one` needs a unique index on the FK or `fetch` duplicates parent rows
+- `has_many` is never joined; use `exists`, `count`, or `first`/`last` (fields only; no `where:`/`scope:` on pick nodes yet)
+- `where:` on aggregates is a Hash or a **zero-argument** lambda `-> { { created_at: 1.week.ago.. } }`. Use `scope: ->(rel) { ... }` to receive the relation
+- `:through`, polymorphic `belongs_to`, association scopes, and `default_scope` on the target raise `Pluckr::UnsupportedAssociation` — use `Pluckr.batch` instead
+- Do not write SQL against joined table names (`subscriptions.name`); Pluckr aliases them (`pluckr_subscription`)
+- Results: frozen objects, `to_h` / `as_json` / `to_json`. Not ActiveRecord. Missing `one` is `nil`
+
+## SQL budget
+
+Every `fetch` / `find` / `first` / `last` / `take` / `for` is one statement, no matter how many nodes the schema has. Two only for `.for(paginated_relation)` (keys, then the read) and one per page for `find_each` / `in_batches`. `count` / `exists?` / `any?` / `none?` / `empty?` / `one?` / `many?` are one statement each and build no result objects. If you emit more than one Pluckr query per request for the same screen, you are using it wrong — widen the schema or use `Pluckr.batch`.

data/README.md

@@ -0,0 +1,436 @@
+# Pluckr
+
+![Query → one SQL statement → frozen result](docs/demo.gif)
+
+A declarative read-query layer for ActiveRecord. Declare the shape, get one SQL
+statement and a frozen, ActiveRecord-free object.
+
+```ruby
+user.id
+user.email
+user.subscription.name   # +1 query
+user.photos.exists?      # +1 query
+user.videos.count        # +1 query
+```
+
+becomes:
+
+```ruby
+class UserSummary < Pluckr::Query
+  source User
+
+  schema do
+    field :id
+    field :email
+
+    one :subscription do
+      field :id
+      field :name
+    end
+
+    exists :photos
+    count :videos
+  end
+end
+
+user = UserSummary.find(1)
+
+user.id             # => 1
+user.email          # => "user@example.com"
+user.subscription   # => #<UserSummary.subscription id=5, name="Pro"> (nil if none)
+user.photos_exists  # => true
+user.videos_count   # => 2
+user.to_h           # => {id: 1, email: "...", subscription: {...}, photos_exists: true, videos_count: 2}
+```
+
+```sql
+SELECT "users"."id"                    AS "id",
+       "users"."email"                 AS "email",
+       "pluckr_subscription"."id"      AS "__pluckr.subscription.present",
+       "pluckr_subscription"."id"      AS "subscription.id",
+       "pluckr_subscription"."name"    AS "subscription.name",
+       EXISTS (SELECT 1 FROM "photos" "pluckr_sub_1"
+                WHERE "pluckr_sub_1"."user_id" = "users"."id"
+                LIMIT 1 OFFSET 0)      AS "photos_exists",
+       (SELECT COUNT(*) FROM "videos" "pluckr_sub_2"
+         WHERE "pluckr_sub_2"."user_id" = "users"."id") AS "videos_count"
+  FROM "users"
+  LEFT OUTER JOIN "subscriptions" "pluckr_subscription"
+    ON "pluckr_subscription"."user_id" = "users"."id"
+```
+
+## Is it worth it?
+
+PostgreSQL, 50k users, one page of this read model ([full results](BENCHMARKS.md)):
+
+| rows | ActiveRecord, N+1 | ActiveRecord, preloaded + grouped | Pluckr |
+| ---: | ---: | ---: | ---: |
+| 10 | 49 SQL / 5.00 ms | 5 SQL / 0.85 ms | **1 SQL / 0.36 ms** |
+| 100 | 481 SQL / 49.1 ms | 5 SQL / 2.89 ms | **1 SQL / 0.96 ms** |
+| 1,000 | 4,801 SQL / 493 ms | 5 SQL / 23.6 ms | **1 SQL / 12.3 ms** |
+| 10,000 | 48,001 SQL / 4,882 ms | 5 SQL / 290 ms | **1 SQL / 98.3 ms** |
+
+2–3× faster than careful ActiveRecord, 10–51× faster than a forgotten preload.
+One statement, always.
+
+## Install
+
+```ruby
+gem "pluckr"
+```
+
+Ruby 3.2+, ActiveRecord 7.1+. PostgreSQL, MySQL, SQLite.
+
+## Querying
+
+```ruby
+UserSummary.find(1)                       # raises ActiveRecord::RecordNotFound
+UserSummary.fetch                         # array
+UserSummary.where(active: true)
+           .order(created_at: :desc)
+           .limit(50)
+           .offset(100)
+           .fetch
+UserSummary.where(active: true).to_sql
+
+UserSummary.for(user)                     # one record you already have
+UserSummary.for(users)                    # those records, one statement, same order
+UserSummary.for(User.active)              # a relation, still one statement
+
+UserSummary.find_by(email: "a@b.c")       # first match, or nil (find_by! raises)
+UserSummary.last                          # first(n) / last(n) / take(n) too
+UserSummary.where(active: true).count     # SELECT COUNT(*)
+UserSummary.where(active: true).exists?   # SELECT 1
+UserSummary.find_each { |row| ... }       # keyset pages, never OFFSET
+UserSummary.where(active: true).explain
+```
+
+`where` / `where.not` / `order` / `limit` / `offset` pass through to the root
+relation. Chains are immutable. A read is one statement.
+
+Exceptions: paginated `.for` is two (keys, then the read model). A preloaded
+page (`includes` / `eager_load`) is loaded the way ActiveRecord loads it.
+`find_each` / `in_batches` are one per page. `count` / `exists?` / `any?` /
+`none?` / `empty?` / `one?` / `many?` compile no nodes.
+
+`.for` a collection or multi-id `find` needs `field :id`. A record you handed
+over that is gone raises `RecordNotFound`; a relation just omits the row.
+`group` / `having` raises — load it (`for(relation.to_a)`).
+
+Do not loop `.for`. Lists you do not already have as AR objects stay
+`UserSummary.where(...).fetch`.
+
+`find_each` / `in_batches` need `field :id`, ignore your `order`, and refuse a
+chain that already has `limit` / `offset`.
+
+## Dashboards
+
+No `source` — one object of independent aggregates:
+
+```ruby
+class DashboardStats < Pluckr::Query
+  schema do
+    count :users,    from: User
+    count :comments, from: Comment
+    count :active_accounts, from: Account, where: { active: true }
+
+    sum :paid_revenue, from: Order, column: :amount, where: { status: "paid" }
+    max :last_signup,  from: User,  column: :created_at
+  end
+end
+
+stats = DashboardStats.fetch
+stats.users            # => 1520
+stats.active_accounts  # => 904
+stats.to_h             # => {users: 1520, comments: 48203, ...}
+```
+
+```sql
+SELECT (SELECT COUNT(*) FROM "users") AS "users",
+       (SELECT COUNT(*) FROM "comments") AS "comments",
+       (SELECT COUNT(*) FROM "accounts" WHERE "accounts"."active" = TRUE) AS "active_accounts"
+```
+
+## Ad-hoc aggregates
+
+Runtime aggregates over relations you already have — one statement:
+
+```ruby
+stats = Pluckr.batch do |b|
+  b.count  user.videos,                           as: :video_count
+  b.sum    user.videos.where(size: 100..), :size, as: :big_video_bytes
+  b.avg    user.videos, :size,                    as: :average_size
+  b.exists user.photos,                           as: :has_photos
+  b.count  Account.active,                        as: :active_accounts
+end
+
+stats.video_count      # => 3
+stats.has_photos       # => true
+```
+
+Each entry wraps the relation's own SQL, so `default_scope`, `:through`, STI,
+`joins`, `merge`, `distinct`, `group`, `limit` all apply. `as:` is required.
+`count` / `sum` / `avg` (`average`) / `min` / `max` / `exists`. A model class
+works (`b.count User, as: :users`). `Pluckr::Batch.build { ... }` is the
+unexecuted form (`#to_sql`, `#fetch`).
+
+A batch answers one subject. For a column on every row of an index page, define
+a query.
+
+## DSL
+
+| Node | Result | SQL |
+| --- | --- | --- |
+| `field :email` | `email` | selected column |
+| `field :email, as: :contact` | `contact` | selected column |
+| `one :subscription do ... end` | `subscription` (or `nil`) | `LEFT OUTER JOIN` |
+| `one :plan, via: :subscription do ... end` | `plan` | `LEFT OUTER JOIN` |
+| `first :comment, via: :comments do ... end` | `comment` (or `nil`) | correlated `LIMIT 1` |
+| `last :comment, via: :comments, order: :created_at do ... end` | `comment` | correlated `LIMIT 1` |
+| `exists :photos` | `photos_exists` | correlated `EXISTS` |
+| `exists :photos, as: :has_photos` | `has_photos` | correlated `EXISTS` |
+| `count :videos` | `videos_count` | scalar subquery |
+| `count :videos, as: :n_videos` | `n_videos` | scalar subquery |
+| `count :users, from: User` | `users` | scalar subquery |
+| `sum/avg/min/max ..., column: :amount` | `<name>_sum`, `<name>_avg`, ... | scalar subquery |
+
+`exists` / `count` / `sum` / `avg` / `min` / `max` take `where:` and `scope:`
+(`average` aliases `avg`, output is still `<name>_avg`):
+
+```ruby
+count :active_accounts, from: Account, where: { active: true }
+count :active_accounts, from: Account, scope: ->(rel) { rel.active }
+
+count  :big_videos, via: :videos, scope: ->(rel) { rel.where(size: 100..) }
+exists :recent_photos, via: :photos, scope: -> { Photo.where(created_at: 1.week.ago..) }
+```
+
+`where:` is a Hash **or** a zero-argument callable returning one. A Hash is
+frozen at class load:
+
+```ruby
+count :recent_orders, from: Order, where: { created_at: 1.week.ago.. }      # week before boot, forever
+count :recent_orders, from: Order, where: -> { { created_at: 1.week.ago.. } }  # what you meant
+```
+
+`scope:` receives the relation (or nothing) and must return one for the same
+model. `limit` / `offset` / `group` inside a scope raise.
+
+`one` nests:
+
+```ruby
+one :subscription do
+  field :name
+  one :plan do
+    field :name
+  end
+end
+
+user.subscription.plan.name
+```
+
+Joins come from ActiveRecord reflection. `has_many` is never joined — use
+`exists` / `count` / `first` / `last`. Leave the `OFFSET 0` on `EXISTS` alone
+([why](BENCHMARKS.md#why-exists-carries-limit-1-offset-0)).
+
+### One row out of many
+
+```ruby
+class UserSummary < Pluckr::Query
+  source User
+
+  schema do
+    field :email
+
+    last :comment, via: :comments do          # newest by primary key
+      field :body
+      field :created_at
+    end
+
+    last :signup_order, via: :orders, order: :created_at do
+      field :amount
+    end
+  end
+end
+
+user.comment.body        # => "the latest one"   (nil if none)
+user.signup_order.amount
+```
+
+`last` matches `relation.order(...).last`. No `order:` → primary key. Blocks
+are fields only in v0.1; no `where:` / `scope:` yet. Index `[foreign_key, order_column]`.
+
+### `has_one` needs a unique index
+
+`one` is a `LEFT OUTER JOIN`. Duplicate child rows duplicate the parent — unique
+the FK:
+
+```ruby
+add_index :subscriptions, :user_id, unique: true
+add_index :profiles, :owner_id, unique: true       # has_one :profile, foreign_key: :owner_id
+```
+
+### Missing vs NULL
+
+```ruby
+user.subscription        # => nil     no row
+user.subscription.name   # => nil     row exists, name is NULL
+```
+
+## Result objects
+
+Frozen, ActiveRecord-free, one reader per declared output:
+
+```ruby
+user.class.ancestors.include?(ActiveRecord::Base) # => false
+user.frozen?                                      # => true
+user[:email]
+user.to_h          # nested, internal aliases stripped
+user.created_at    # NoMethodError - not selected
+```
+
+Cast with the model's column types. `count` / `sum` over no rows are `0`;
+`min` / `max` / `avg` are `nil`. `avg` is a `BigDecimal`.
+
+```ruby
+result.to_json   # => {"id":1,"email":"...","subscription":{"name":"Pro"},"videos_count":2}
+result.as_json   # => {"id" => 1, ...}
+result.to_hash   # => {id: 1, ...}, so **result works too
+```
+
+## Errors, early
+
+Schema mistakes raise at class-definition time:
+
+```ruby
+field :does_not_exist  # Pluckr::UnknownField: User does not have column `does_not_exist`
+one :unknown           # Pluckr::UnknownAssociation: User does not have association `unknown`
+one :photos            # Pluckr::InvalidAssociation: `User#photos` is a has_many association
+                       #   and cannot be used with `one`
+field :id              # Pluckr::MissingSource (no `source` declared)
+schema { }             # Pluckr::ConfigurationError: `schema` block is empty
+count :x, scope: {}    # Pluckr::ConfigurationError: `scope:` expects a callable
+```
+
+Compile-time checks (`scope:` return value, alias length, one connection) raise
+on first `to_sql` / `fetch`.
+
+## Instrumentation
+
+```ruby
+ActiveSupport::Notifications.subscribe("fetch.pluckr") do |*args|
+  event = ActiveSupport::Notifications::Event.new(*args)
+
+  event.payload[:name]  # => "UserSummary" (or "Pluckr::Batch")
+  event.payload[:sql]   # => "SELECT ..."
+  event.payload[:rows]  # => 100
+  event.duration        # => 0.96 (ms)
+end
+```
+
+Covers every statement Pluckr compiles. `count` / `exists?` and the key `pluck`
+for a paginated `.for` are ActiveRecord's (`sql.active_record`).
+
+## How it works
+
+```
+DSL -> schema AST -> reflection -> SQL compiler -> flat row -> result object
+```
+
+[AGENTS.md](AGENTS.md) is the internals.
+
+## Not in v0.1
+
+- `many` (nested collections)
+- raw SQL fields, manual joins
+- `has_many :through`, polymorphic `belongs_to`, scoped associations, and
+  associations whose model has a `default_scope` (raise
+  `Pluckr::UnsupportedAssociation`). Polymorphic `has_many ..., as:` and STI
+  children work; so does `Pluckr.batch` for everything ActiveRecord can SQL
+- `where:` / `scope:` on `first` / `last`
+- composite primary keys are readable, and `first` orders by every key column,
+  but `find` / `for` need a single-column key
+- writes, serializers, pagination beyond `limit` / `offset`, caching
+
+## What Pluckr is not
+
+Not an ORM, not a serializer, not GraphQL, not a replacement for ActiveRecord.
+Use it for API read models, index tables, dashboards, reports, job payloads.
+
+## Benchmarks
+
+```bash
+bundle exec ruby benchmarks/read_models.rb            # PostgreSQL
+DB=sqlite bundle exec ruby benchmarks/read_models.rb  # SQLite
+PAGES=25,250 USERS=200000 bundle exec ruby benchmarks/read_models.rb
+```
+
+[BENCHMARKS.md](BENCHMARKS.md) has plans, scaling, and what a missing FK index
+costs (123×).
+
+## Try it locally
+
+```bash
+git clone https://github.com/igorkasyanchuk/pluckr && cd pluckr
+bundle install
+bin/setup      # database, schema, seeds
+bin/console    # IRB with models, seeds, example queries
+```
+
+```
+>> UserSummary.find(2).to_h
+=> {id: 2, email: "user1@example.com",
+    subscription: {id: 1, name: "sub-1", plan: {name: "Pro", price_cents: 2900}},
+    photos_exists: true, videos_count: 3}
+
+>> statements { UserSummary.where(active: true).limit(5).fetch }
+1. SELECT "users"."id" AS "id", ...
+=> 1
+
+>> DashboardStats.fetch.to_h
+=> {users: 21, active_users: 16, comments: 49, active_accounts: 5,
+    paid_revenue: 1641, last_signup: 2026-08-12 21:14:14 UTC}
+```
+
+| | |
+| --- | --- |
+| `sql(query)` | print the SQL |
+| `explain(query)` | `EXPLAIN` (`analyze: true` on PostgreSQL) |
+| `statements { ... }` | print and count statements |
+| `reload!` | pick up `lib/` and `dev/` edits |
+| `reseed!(users: 500)` | wipe and re-seed |
+| `reset!` | rebuild schema, then re-seed |
+| `Dev.log!(false)` | stop echoing SQL |
+| `Dev.counts` | row counts |
+
+```bash
+DB=postgres bin/setup && DB=postgres bin/console
+DB=mysql    bin/setup && DB=mysql    bin/console
+SEED_USERS=5000 DB=postgres bin/setup
+```
+
+| Variable | Default | Meaning |
+| --- | --- | --- |
+| `DB` | `sqlite` | `sqlite`, `postgres` or `mysql` |
+| `SEED_USERS` | `20` | users to seed |
+| `PLUCKR_DEV_DATABASE` | `pluckr_dev` | database name (file name on SQLite) |
+| `PGHOST` / `PGPORT` / `PGUSER` / `PGPASSWORD` | `postgres` user | PostgreSQL |
+| `MYSQL_HOST` / `MYSQL_PORT` / `MYSQL_USER` / `MYSQL_PASSWORD` | `root@127.0.0.1` | MySQL |
+
+## Development
+
+```bash
+bundle exec rspec              # SQLite (default)
+DB=postgres bundle exec rspec
+DB=mysql bundle exec rspec
+```
+
+CI: Ruby 3.2 and 3.4 × SQLite, PostgreSQL, MySQL. Pass SQLite and PostgreSQL
+locally before pushing.
+
+[AGENTS.md](AGENTS.md) is the internals. [PROMPT.md](PROMPT.md) is a system
+prompt for generating Pluckr queries.
+
+## License
+
+MIT.

data/lib/pluckr/aliases.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Pluckr
+  # Single source of truth for the flat column aliases used in generated SQL.
+  #
+  # The SQL stays flat; nesting lives in the alias path:
+  #
+  #   users.id                 AS "id"
+  #   subscriptions.name       AS "subscription.name"
+  #   subscriptions.id         AS "__pluckr.subscription.present"
+  #
+  # The result builder reads the same helpers back, so the encoding is never
+  # duplicated between the compiler and the hydrator.
+  module Aliases
+    SEPARATOR = "."
+    PRESENCE_PREFIX = "__pluckr"
+    PRESENCE_SUFFIX = "present"
+    TABLE_PREFIX = "pluckr"
+
+    module_function
+
+    # Output alias for a value node, e.g. ["subscription"], :name => "subscription.name"
+    def output(path, name)
+      (path + [name]).join(SEPARATOR)
+    end
+
+    # Hidden marker telling the hydrator whether a nested `one` row exists at all.
+    def presence(path)
+      ([PRESENCE_PREFIX] + path + [PRESENCE_SUFFIX]).join(SEPARATOR)
+    end
+
+    # Table alias for a joined singular association.
+    def table(path)
+      ([TABLE_PREFIX] + path).join("_")
+    end
+  end
+end