diamond-orm 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 13c6999334b70e19afef786aa57f2ad0cc7835fafacc12f391d6414b3dc6309b
-  data.tar.gz: 30efa17f6e63476342f9101dabb0775ccc71ed3e63e91ea3e8604f6e118f675d
+  metadata.gz: 12bd9185ce557de9f864bbdeb245b70015b498f3cf2bab68a9d780b4b2e8dbe6
+  data.tar.gz: 6e8acbdebdd733244718aa6e4ba5b03d66832ce429f0eee177dba8d743757daf
 SHA512:
-  metadata.gz: 2e14c2e9937d10c70962f802f9a162d77ca71a74dbddfcf7ded4425079800afdfa6093b28af2bc37a78380e8720f442636ddd0f1a7a518bcd1cd6bba38f41e79
-  data.tar.gz: ed794d682668a04a47f93471168863ab650b0e4b71d6fd48a39b60d4847bc98f5b7b337dfd94ce78e6158c084bdd154ac6edfaac87ab0cf68b68471e5665798a
+  metadata.gz: c867fbbf67eefd91a8c90f3e6c803f6ff883caee436d22883d1bb52c785c4f0f4f4ea2e689fc0a46c5466f3eabd696008bd9b4a9b4a1da654710fcde60c7df55
+  data.tar.gz: fb00be24993be996c4f40499cb3407e549da03070bafa7efae21da287e89c0c74750939a491879ade554aa066a7c0caa431423cf13c64a2a3264984672ab7e2a

data/lib/diamond/api_catalog.rb

@@ -348,6 +348,9 @@ module Diamond
       'primary_key' => [
         'Users.primary_key'
       ],
+      'primary_keys' => [
+        'Users.primary_keys' # composite PK when defined; single column for single-PK
+      ],
       'name' => [
         'Users.name'
       ],
@@ -403,7 +406,8 @@ module Diamond
         'Diamond.define_relation(:users) { |t| t.attribute :id, Integer, primary_key: true, nullable: false }',
         'Diamond.define_relation(:users) { |t| t.attribute :name, String }',
         'Diamond.define_relation(:posts) { |t| t.attribute :user_id, Integer; t.foreign_key :user_id, :users }',
-        'Diamond.define_relation(:blogs) { |t| t.index :name, name: "idx_blogs_name", unique: true }'
+        'Diamond.define_relation(:blogs) { |t| t.index :name, name: "idx_blogs_name", unique: true }',
+        'Diamond.define_relation(:memberships) { |t| t.primary_key :tenant_id, :user_id; t.attribute :role, String }'
       ],
       'alter_table' => [
         'Diamond.alter_table(:users) { |t| t.add_column :nickname, String }',
@@ -539,9 +543,9 @@ module Diamond
     # Use for pk/version/etc. dependencies that don't fit in a single
     # example call.
     NOTES = {
-      '[]'    => 'uses the table primary_key (custom or :id)',
-      'find'  => 'uses the table primary_key (custom or :id); block form delegates to Enumerable#find',
-      'find!' => 'uses the table primary_key (custom or :id); raises RecordNotFound on miss',
+      '[]'    => 'uses the table primary_key (custom or :id); for composite-PK tables pass an Array or Hash',
+      'find'  => 'single-PK: scalar id; composite-PK: Array (positional) or Hash (named). Block form delegates to Enumerable#find',
+      'find!' => 'single-PK: scalar id; composite-PK: Array or Hash. Raises RecordNotFound on miss',
       'derive'          => 'one Projection per chain — a second derive raises',
       'reorder'         => 'replaces existing ORDER BY; bare reorder clears it',
       'limit'           => 'replaces previous limit (last wins)',
@@ -550,14 +554,15 @@ module Diamond
       'union'           => 'terminal — further chain calls raise (wrap in a subquery instead)',
       'from_cte'        => 'must run inside the Diamond.with block; queries a CTE alias',
       'sole'            => 'raises RecordNotFound on both zero rows AND two-plus',
-      'first'           => 'injects ORDER BY primary_key when no order is set; n==1 returns a struct, n>1 returns an Array',
-      'last'            => 'injects ORDER BY primary_key DESC when no order is set; n>1 reverses back to ascending',
+      'first'           => 'injects ORDER BY primary_key(s) when no order is set; n==1 returns a struct, n>1 returns an Array',
+      'last'            => 'injects ORDER BY primary_key(s) DESC when no order is set; n>1 reverses back to ascending',
+      'ids'             => 'flat Array of PK values; raises on composite-PK tables — use pluck(*primary_keys)',
       'each'            => 'no block returns an Enumerator (so .lazy and chains work); with block streams via a cursor',
       'all'             => 'lazy QueryObject (no SQL until chained/terminal); equivalent to bare Table but chainable',
       'all!'            => 'eagerly materializes all rows (same as .to_a); returns Array of structs',
       'pluck'           => 'one column -> flat Array; several -> Array of Arrays (no Struct overhead)',
       'pick'            => 'one column -> single value; several -> Array; nil on miss (no Struct)',
-      'count'           => 'COUNT(primary_key) when column is nil; COUNT(col) when given',
+      'count'           => 'COUNT(primary_key) when column is nil and PK is single; COUNT(*) for composite-PK; COUNT(col) when given',
       'materialize'     => 'result is memoized per QueryObject; same chain returns the same array',
       'as_hash'         => 'mode carries across chain calls (.as_hash.limit(5).materialize stays hashes)',
       'as_array'        => 'mode carries across chain calls (positional arrays, no Struct)',
@@ -568,9 +573,9 @@ module Diamond
       'track_changes'   => 'requires the extralite-bundle build (session extension); raises FeatureNotAvailableError otherwise',
       'transaction'     => 'nested calls run inside the outer transaction; use savepoint for explicit rollback points',
       'savepoint'       => 'only valid inside a transaction; rolls back to the named savepoint on raise',
-      'increment!'      => 'issues a SQL UPDATE; not atomic with concurrent writers — pair with a unique index if contention matters',
-      'decrement!'      => 'issues a SQL UPDATE; not atomic with concurrent writers — pair with a unique index if contention matters',
-      'toggle!'         => 'reads-then-writes — not atomic; pair with a unique index if contention matters',
+      'increment!'      => 'issues a SQL UPDATE; single-PK: scalar id, composite-PK: Array id. Not atomic with concurrent writers — pair with a unique index if contention matters',
+      'decrement!'      => 'issues a SQL UPDATE; single-PK: scalar id, composite-PK: Array id. Not atomic with concurrent writers — pair with a unique index if contention matters',
+      'toggle!'         => 'reads-then-writes; single-PK: scalar id, composite-PK: Array id. Not atomic; pair with a unique index if contention matters',
       'join'            => 'INNER by default; type: :left for LEFT OUTER; eager: true for nested structs (same SQL as includes, but flat results)',
       'includes'        => 'LEFT OUTER + eager loading; returns parent with nested child structs (sugar for join(..., eager: true))',
       'define_relation' => 'block captures an AST; t is a scratch DSL proxy (instance_exec in console, ignored by Prism file parser). Block return value is ignored. See BLOCK_GRAMMAR for the methods callable inside the block.',
@@ -619,13 +624,14 @@ module Diamond
         source: 'parser.rb:434-438 / proxy.rb:384-388'
       },
       'primary_key' => {
-        signature: 't.primary_key(name)',
-        summary:   'shorthand: Integer column with primary_key: true, nullable: false (no kwargs)',
+        signature: 't.primary_key(name, *more_names)',
+        summary:   'one arg: Integer column with primary_key: true, nullable: false (column-level PRIMARY KEY). 2+ args: table-level composite PRIMARY KEY (col1, col2, …)',
         available_in: 'define_relation',
         examples: [
-          't.primary_key :id'
+          't.primary_key :id',
+          't.primary_key :tenant_id, :user_id'
         ],
-        source: 'parser.rb:439-442 / proxy.rb:390-393'
+        source: 'parser.rb:439-447 / proxy.rb:390-398'
       },
       'foreign_key' => {
         signature: 't.foreign_key(local, ref_table, ref_col = :id, on_delete: nil, on_update: nil)',

data/lib/diamond/ast.rb

@@ -40,6 +40,12 @@ module Diamond
       def initialize(value); @value = value; end
     end
 
+    # `*` selector. Renders as a bare `*` in SQL, distinct from a
+    # column reference so function args (`COUNT(*)`) and projections
+    # can carry it without colliding with identifier names.
+    class Star < Node
+    end
+
     class BinaryOp < Node
       attr_reader :left, :right, :operator
       def initialize(left, right, operator)
@@ -277,6 +283,17 @@ module Diamond
       end
     end
 
+    # Table-level constraint (e.g. composite PRIMARY KEY). Sits in the
+    # CREATE TABLE body alongside ColumnDefinition. `columns` is the
+    # ordered list of column names (Symbols) the constraint applies to.
+    class TableConstraint < Node
+      attr_reader :kind, :columns
+      def initialize(kind:, columns:)
+        @kind = kind
+        @columns = columns
+      end
+    end
+
     # lifted into the AST so define_relation does CREATE TABLE then
     # CREATE INDEX in one go.
     class IndexDefinition < Node

data/lib/diamond/compiler/ddl.rb

@@ -13,10 +13,11 @@ module Diamond
         raise ArgumentError, "Expected AST::DefineRelation, got #{node.class}" unless node.is_a?(AST::DefineRelation)
         Diamond.validate_ident!(node.name, "table name")
 
-        column_clauses = node.columns.select { |c| c.is_a?(AST::ColumnDefinition) }.map { |c| render_column(c) }
-        fk_clauses    = node.columns.select { |c| c.is_a?(AST::ForeignKey) }.map { |c| render_foreign_key(c) }
+        column_clauses    = node.columns.select { |c| c.is_a?(AST::ColumnDefinition) }.map { |c| render_column(c) }
+        fk_clauses       = node.columns.select { |c| c.is_a?(AST::ForeignKey) }.map { |c| render_foreign_key(c) }
+        constraint_clauses = node.columns.select { |c| c.is_a?(AST::TableConstraint) }.map { |c| render_table_constraint(c) }
 
-        body = (column_clauses + fk_clauses).join(', ')
+        body = (column_clauses + fk_clauses + constraint_clauses).join(', ')
         sql  = "CREATE TABLE IF NOT EXISTS #{node.name} (#{body})"
         [sql, []]
       end
@@ -77,6 +78,15 @@ module Diamond
         sql
       end
 
+      # Table-level constraint — currently only composite PRIMARY KEY.
+      # Emitted at the end of the CREATE TABLE body so column-level
+      # column definitions aren't shadowed.
+      def self.render_table_constraint(node)
+        raise ArgumentError, "Unknown table constraint kind: #{node.kind}" unless node.kind == :primary_key
+        node.columns.each { |c| Diamond.validate_ident!(c, "primary_key column") }
+        "PRIMARY KEY (#{node.columns.join(', ')})"
+      end
+
       def self.format_action(sym)
         sym.to_s.upcase.tr('_', ' ')
       end

data/lib/diamond/compiler/dql.rb

@@ -193,9 +193,11 @@ module Diamond
             type = type_for_column(child_table, col)
             child_columns["#{child_table}.#{col}"] = { type: type }
           end
-          # mark primary key for dedup
-          pk = child_schema[:primary_key]
-          child_columns["#{child_table}.#{pk}"][:identity] = true if pk
+          # mark primary key(s) for dedup
+          pks = child_schema[:primary_keys] || [child_schema[:primary_key]].compact
+          pks.each do |pk|
+            child_columns["#{child_table}.#{pk}"][:identity] = true
+          end
 
           # use :as alias as struct member name if provided, else table name
           member_key = (j.as || child_table).to_s
@@ -215,9 +217,9 @@ module Diamond
           end
         end
 
-        # parent primary key for dedup at the parent level
-        pk = table.schema[:primary_key]
-        columns_spec[pk.to_s][:identity] = true if pk
+        # parent primary key(s) for dedup at the parent level
+        pks = table.schema[:primary_keys] || [table.schema[:primary_key]].compact
+        pks.each { |pk| columns_spec[pk.to_s][:identity] = true }
 
         { columns: columns_spec }
       end
@@ -340,6 +342,11 @@ module Diamond
         when AST::Function
           args_str = node.args.map { |a| translate_node(a, params, prefix: prefix) }.join(', ')
           "#{node.name}(#{args_str})"
+        when AST::Star
+          # Star only appears as a function arg (e.g. COUNT(*)). A
+          # bare SELECT * projection is the table's full column set,
+          # which compiles elsewhere.
+          '*'
         when AST::WindowFunction
           args_str = node.args.map { |a| translate_node(a, params, prefix: prefix) }.join(', ')
           func_str = "#{node.func_name}(#{args_str})"

data/lib/diamond/cursor.rb

@@ -6,11 +6,16 @@ module Diamond
   # finalizer is built by ::make_finalizer so it never closes over the cursor
   # itself. rows arrive as arrays (positions match the SELECT order), avoiding
   # hash allocation per row.
+  #
+  # Pass `owns_stmt: false` when the statement comes from
+  # `Diamond.engine.prepared` (the engine cache owns the lifetime).
+  # Default is true (legacy callers prepared an ephemeral stmt).
   class Cursor
     include Enumerable
 
-    def self.make_finalizer(stmt)
+    def self.make_finalizer(stmt, owns_stmt)
       ->(_id) {
+        next unless owns_stmt
         begin
           stmt.close unless stmt.closed?
         rescue StandardError
@@ -19,15 +24,16 @@ module Diamond
       }
     end
 
-    def initialize(table, stmt, projected_columns)
+    def initialize(table, stmt, projected_columns, owns_stmt: true)
       @table = table
       @stmt = stmt
       @projected_columns = projected_columns
+      @owns_stmt = owns_stmt
       # Pre-resolve the struct class once: per-row work stays at
       # splat + new + freeze (see StructFactory.bulk path).
       @factory = Diamond::StructFactory.factory_for(table, projected_columns)
 
-      ObjectSpace.define_finalizer(self, self.class.make_finalizer(@stmt))
+      ObjectSpace.define_finalizer(self, self.class.make_finalizer(@stmt, owns_stmt))
     end
 
     def each(&block)
@@ -41,10 +47,12 @@ module Diamond
           end
         end
       ensure
-        begin
-          @stmt.close unless @stmt.closed?
-        rescue StandardError
-          # ensure must not raise
+        if @owns_stmt
+          begin
+            @stmt.close unless @stmt.closed?
+          rescue StandardError
+            # ensure must not raise
+          end
         end
       end
     end

data/lib/diamond/dsl/default.rb

@@ -35,12 +35,7 @@ module Diamond
         end
         raise ArgumentError, "find requires an id" if id.nil?
 
-        pk = _schema_for_dsl[:primary_key] || :id
-        condition = Diamond::AST::Equality.new(
-          Diamond::AST::Column.new(pk),
-          Diamond::AST::Literal.new(id)
-        )
-        _build_where_node(condition)
+        _build_where_node(_pk_lookup_condition(id))
       end
 
       # like find, but raises RecordNotFound instead of returning an
@@ -337,8 +332,9 @@ module Diamond
       # stable even over user-ordered chains.
       def find_each(batch_size: 1000, &block)
         return to_enum(:find_each, batch_size: batch_size) unless block
-        pk = _schema_for_dsl[:primary_key] || :id
-        scope = _wrap.order(pk)
+        pks = _schema_for_dsl[:primary_keys] || []
+        pks = [pks.first || :id] if pks.empty?
+        scope = _wrap.order(*pks)
         offset = 0
         loop do
           batch = scope.limit(batch_size).offset(offset).materialize
@@ -409,6 +405,69 @@ module Diamond
         new_value
       end
 
+      # Builds the WHERE clause for a PK lookup.
+      # Single PK  + scalar  → pk = id  (one Equality)
+      # Composite PK + Array  → pk1 = a AND pk2 = b ...
+      # Composite PK + Hash   → pk1 = v1 AND pk2 = v2 ...
+      # Anything else (wrong arity, mixed scalar+array, mixed
+      # single+composite) raises. Returns an AST::Equality node for
+      # single, or an AST::And chain for composite.
+      def _pk_lookup_condition(id)
+        pks = _schema_for_dsl[:primary_keys] || []
+        # Back-compat with older schemas that lack :primary_keys.
+        pks = [pks.first || :id] if pks.empty?
+
+        if pks.size == 1
+          unless !id.is_a?(Array) && !id.is_a?(Hash)
+            raise ArgumentError,
+                  "find on a single-PK table expects a scalar id, got #{id.inspect}"
+          end
+          Diamond::AST::Equality.new(
+            Diamond::AST::Column.new(pks.first),
+            Diamond::AST::Literal.new(id)
+          )
+        else
+          pairs =
+            case id
+            when Array
+              if id.size != pks.size
+                raise ArgumentError,
+                      "find(#{id.inspect}) expects #{pks.size} values for composite PK #{pks.inspect}"
+              end
+              pks.zip(id)
+            when Hash
+              # hash form: { pk_col => value, ... }. Missing keys raise.
+              missing = pks - id.keys
+              unless missing.empty?
+                raise ArgumentError,
+                      "find(#{id.inspect}) missing PK column(s): #{missing.inspect}"
+              end
+              extra = id.keys - pks
+              unless extra.empty?
+                raise ArgumentError,
+                      "find(#{id.inspect}) has keys outside the PK columns #{pks.inspect}: #{extra.inspect}"
+              end
+              pks.map { |pk| [pk, id[pk]] }
+            else
+              raise ArgumentError,
+                    "find on a composite-PK table expects an Array or Hash, got #{id.inspect}"
+            end
+
+          # each_with_index yields [element, index]; destructure into
+          # (pair, idx) so pair gets the (col, val) tuple — then
+          # destructure pair into (col, val) for the Equality.
+          pairs.each_with_index.inject(nil) do |acc, (pair, _idx)|
+            col, val = pair
+            eq = Diamond::AST::Equality.new(
+              Diamond::AST::Column.new(col),
+              Diamond::AST::Literal.new(val)
+            )
+            acc.nil? ? eq : Diamond::AST::And.new(acc, eq)
+          end
+        end
+      end
+      private :_pk_lookup_condition
+
       private
 
       def _wrap

data/lib/diamond/engine.rb

@@ -181,7 +181,7 @@ module Diamond
       nullable = {}
       defaults = {}
       required = {}
-      primary_key = nil
+      pk_positions = [] # ordered, parallel to PRAGMA row order
 
       @db.query("PRAGMA table_info(#{Diamond.quote_ident(table_name)})").each do |col|
         col_name = col[:name].to_sym
@@ -199,16 +199,28 @@ module Diamond
         # A column is required when (NOT NULL OR pk > 0) AND has no default.
         required[col_name] =
           (col[:notnull] != 0 || col[:pk] > 0) && col[:dflt_value].nil?
-        primary_key = col_name if col[:pk] == 1
+        # PRAGMA table_info returns :pk as the column's POSITION in the
+        # primary key (1, 2, 3, ...). Single-PK tables always have one
+        # row with pk=1; composite PKs return multiple rows with pk>0.
+        # Capture each in declaration order to preserve the composite
+        # tuple shape.
+        pk_positions << [col[:pk], col_name] if col[:pk] > 0
       end
 
+      pk_positions.sort_by!(&:first)
+      primary_keys = pk_positions.map(&:last)
+      # Back-compat: `primary_key` (singular) is the first column of a
+      # composite PK, or nil for PK-less tables.
+      primary_key = primary_keys.first
+
       {
         columns: columns,
         types: types,
         nullable: nullable,
         defaults: defaults,
         required: required,
-        primary_key: primary_key
+        primary_key: primary_key,
+        primary_keys: primary_keys
       }
     end
 

data/lib/diamond/null_table.rb

@@ -4,7 +4,7 @@ module Diamond
 
     def initialize(name = nil)
       @name = name
-      @schema = { columns: [], types: {}, primary_key: nil }
+      @schema = { columns: [], types: {}, primary_key: nil, primary_keys: [] }
     end
   end
 end

data/lib/diamond/parser/proxy.rb

@@ -387,9 +387,14 @@ module Diamond
           @statements << AST::ColumnDefinition.new(name, type, opts)
         end
 
-        def primary_key(name)
-          check_name!(name, "primary_key")
-          @statements << AST::ColumnDefinition.new(name, Integer, primary_key: true, nullable: false)
+        def primary_key(*names)
+          raise ArgumentError, "primary_key requires at least one column" if names.empty?
+          names.each { |n| check_name!(n, "primary_key") }
+          if names.size == 1
+            @statements << AST::ColumnDefinition.new(names.first, Integer, primary_key: true, nullable: false)
+          else
+            @statements << AST::TableConstraint.new(kind: :primary_key, columns: names)
+          end
         end
 
         def foreign_key(local, ref_table, ref_col = :id, on_delete: nil, on_update: nil)

data/lib/diamond/parser.rb

@@ -438,8 +438,13 @@ module Diamond
         AST::ColumnDefinition.new(name, type, kwargs)
       when :primary_key
         raise "primary_key requires a name argument" if positional.empty?
-        name = symbol_value(positional[0])
-        AST::ColumnDefinition.new(name, Integer, primary_key: true, nullable: false)
+        names = positional.map { |a| symbol_value(a) }
+        names.each { |n| Diamond.validate_ident!(n, "primary_key column") }
+        if names.size == 1
+          AST::ColumnDefinition.new(names.first, Integer, primary_key: true, nullable: false)
+        else
+          AST::TableConstraint.new(kind: :primary_key, columns: names)
+        end
       when :foreign_key
         raise "foreign_key requires local column and ref table" if positional.size < 2
         local = symbol_value(positional[0])

data/lib/diamond/query_object.rb

@@ -94,7 +94,7 @@ module Diamond
     end
 
     def first(n = 1)
-      scope = has_order? ? self : order(resolve_pk!)
+      scope = has_order? ? self : order(*resolve_pks!)
       results = scope.limit(n).materialize
       n == 1 ? results.first : results
     end
@@ -115,7 +115,7 @@ module Diamond
         return
       end
 
-      stmt = Diamond.engine.db.prepare_array(compiled_sql)
+      stmt = Diamond.engine.prepared(compiled_sql, :array)
       stmt.bind(*compiled_params)
 
       union_node = @ast.find { |n| n.is_a?(AST::Union) }
@@ -123,13 +123,15 @@ module Diamond
       projection_node   = scope_ast.find { |n| n.is_a?(AST::Projection) }
       projected_columns = projection_node&.columns
 
-      cursor = Diamond::Cursor.new(@table, stmt, projected_columns)
+      cursor = Diamond::Cursor.new(@table, stmt, projected_columns, owns_stmt: false)
 
       cursor.each(&block)
     end
 
     def last(n = 1)
-      scope = has_order? ? self : order([resolve_pk!, :desc])
+      pks = resolve_pks!
+      desc_orders = pks.map { |pk| [pk, :desc] }
+      scope = has_order? ? self : order(*desc_orders)
       results = scope.limit(n).materialize
       n == 1 ? results.first : results.reverse
     end
@@ -159,8 +161,17 @@ module Diamond
     end
 
     # primary-key values. `Users.ids` ~ `SELECT id FROM users`.
+    # Raises on composite-PK tables since the flat-array shape is
+    # ambiguous for tuples — use `pluck(*primary_keys)` to get the
+    # full set as `[ [a1, b1], [a2, b2], ... ]` or per-column pluck.
     def ids
-      pluck(resolve_pk!)
+      pks = @table.schema[:primary_keys] || []
+      if pks.size > 1
+        raise ArgumentError,
+              "ids() is not supported on composite-PK tables " \
+              "(#{pks.inspect}); use pluck(*primary_keys) instead"
+      end
+      pluck(pks.first || :id)
     end
 
     # Zero-translation JSON fast path. Pushes serialization into
@@ -267,10 +278,37 @@ module Diamond
     end
 
     def count(column = nil)
-      col = column.nil? ? resolve_pk! : validate_aggregate_column!(column)
-      nodes = [AST::Function.new(:count, [AST::Column.new(col)])]
+      # Tier 3a: bare-table fast path. COUNT on a trivial scope becomes
+      # a one-shot `SELECT COUNT(...) FROM <table>` with no AST /
+      # Projection / struct overhead — closes the 50x gap to Extralite.
+      #
+      # SQLite has a `COUNT(*)` optimization that uses internal table
+      # stats; `COUNT(non_null_col)` forces a full row scan. For the
+      # no-column form (which the existing AST path translates to
+      # COUNT(pk_col) for single-PK and COUNT(*) for composite-PK), we
+      # always emit COUNT(*) since it gives the same answer for any
+      # row-count intent and gets the optimization.
+      if trivial_scope?
+        return fast_aggregate(:count, '*', 0) if column.nil?
+        return fast_aggregate(:count, validate_aggregate_column!(column), 0)
+      end
+
+      if column.nil?
+        if @table.schema[:primary_keys]&.size.to_i > 1
+          nodes = [AST::Function.new(:count, [AST::Star.new])]
+          member_name = :count_star
+        else
+          col = resolve_pk!
+          nodes = [AST::Function.new(:count, [AST::Column.new(col)])]
+          member_name = :"count_#{col}"
+        end
+      else
+        col = validate_aggregate_column!(column)
+        nodes = [AST::Function.new(:count, [AST::Column.new(col)])]
+        member_name = :"count_#{col}"
+      end
       filtered = @ast.reject { |n| n.is_a?(AST::Projection) } + [AST::Projection.new(nodes)]
-      Diamond::QueryObject.new(@table, filtered).materialize.first.public_send(:"count_#{col}")
+      Diamond::QueryObject.new(@table, filtered).materialize.first.public_send(member_name)
     end
 
     # Scalar aggregate terminals. Each builds one Function projection
@@ -287,18 +325,27 @@ module Diamond
       return enumerable_fallback(:sum) if column.nil?
       return enumerable_fallback(:sum, column) unless column.is_a?(Symbol) || column.is_a?(String)
 
+      # Tier 3a: trivial scope → direct SQL, skip AST/struct.
+      return fast_aggregate(:sum, column, 0) if trivial_scope?
+
       aggregate(:sum, column)
     end
 
     def minimum(column)
+      return fast_aggregate(:min, column, nil) if trivial_scope?
+
       aggregate(:min, column)
     end
 
     def maximum(column)
+      return fast_aggregate(:max, column, nil) if trivial_scope?
+
       aggregate(:max, column)
     end
 
     def average(column)
+      return fast_aggregate(:avg, column, nil) if trivial_scope?
+
       aggregate(:avg, column)
     end
 
@@ -404,19 +451,13 @@ module Diamond
     end
 
     def fetch_first_array_row(sql, params)
-      stmt = Diamond.engine.db.prepare_array(sql)
-      begin
-        stmt.bind(*params)
-        found = nil
-        stmt.each { |row| found = row; break }
-        found
-      ensure
-        begin
-          stmt.close unless stmt.closed?
-        rescue StandardError
-          # ensure must not raise
-        end
-      end
+      # NOTE: statement comes from the engine's shared prepared cache —
+      # do NOT close it. Cache lifetime is the engine's.
+      stmt = Diamond.engine.prepared(sql, :array)
+      stmt.bind(*params)
+      found = nil
+      stmt.each { |row| found = row; break }
+      found
     end
 
     # one Function projection (SUM(age) -> sum_age), scalar back.
@@ -448,6 +489,48 @@ module Diamond
       @ast.any? { |n| n.is_a?(AST::Order) }
     end
 
+    # Tier 3a: bare-table predicate. True when the current scope has no
+    # modifiers that would require the AST/compile path. Adding a new
+    # AST node that affects aggregates? Add it here too.
+    def trivial_scope?
+      @ast.none? do |n|
+        n.is_a?(AST::Projection) ||
+          n.is_a?(AST::Where) ||
+          n.is_a?(AST::Order) ||
+          n.is_a?(AST::Group) ||
+          n.is_a?(AST::Having) ||
+          n.is_a?(AST::Join) ||
+          n.is_a?(AST::Limit) ||
+          n.is_a?(AST::Offset) ||
+          n.is_a?(AST::Distinct) ||
+          n.is_a?(AST::Union) ||
+          n.is_a?(AST::With)
+      end
+    end
+
+    # Tier 3a: direct SQL aggregate over a trivial scope. Skips AST,
+    # compile, projection, struct — just emits `SELECT <FUNC>(<arg>)
+    # FROM <table>` and reads the scalar. `null_default` is returned
+    # when the result is NULL (empty scope): 0 for "row count-like"
+    # aggregates (count/sum/avg), nil for min/max.
+    #
+    # column may be:
+    #   - nil       → use '*' (COUNT(*) only — sum/min/max/avg pass a column)
+    #   - a Symbol  → validated against the schema
+    #   - the String '*' → passed through (used by count(*) fast path)
+    def fast_aggregate(func, column, null_default)
+      arg =
+        if column.nil? || column == :* || column == '*'
+          '*'
+        else
+          validate_aggregate_column!(column).to_s
+        end
+      sql = "SELECT #{func.to_s.upcase}(#{arg}) FROM #{Diamond.quote_ident(@table.name)}"
+      result = Diamond.engine.db.query_single_splat(sql)
+      result.nil? ? null_default : result
+    end
+    private :fast_aggregate
+
     # pk or :id, and it better exist. fail here with a column error
     # instead of letting sqlite complain about COUNT(missing). Also
     # the implicit ORDER BY column for first/last.
@@ -459,5 +542,26 @@ module Diamond
       pk
     end
 
+    # All PK columns, in declaration order. Single-PK tables return a
+    # one-element array. Used by composite-aware paths (first/last,
+    # find_each, dedup, count). Each column is validated via
+    # resolve_pk!'s check so composite typos fail loudly.
+    def resolve_pks!
+      pks = @table.schema[:primary_keys]
+      if pks.nil? || pks.empty?
+        pk = :id
+        unless @table.schema[:columns].include?(pk)
+          raise Diamond::UnknownColumnError.build(@table.schema, pk)
+        end
+        return [pk]
+      end
+      pks.each do |pk|
+        unless @table.schema[:columns].include?(pk)
+          raise Diamond::UnknownColumnError.build(@table.schema, pk)
+        end
+      end
+      pks
+    end
+
   end
 end

data/lib/diamond/struct_factory.rb

@@ -91,7 +91,7 @@ module Diamond
                               member_name
                             end
           child_schema = Diamond.engine.schema_cache[child_table_sym]
-          child_pk = child_schema[:primary_key]
+          child_pks = child_schema[:primary_keys] || [child_schema[:primary_key]].compact
 
           # strip table. prefix from each child row's keys
           stripped = value.map do |child_row|
@@ -105,15 +105,16 @@ module Diamond
           # children after a LEFT JOIN)
           stripped.reject! { |child_row| child_row.values.all?(&:nil?) }
 
-          # dedupe by primary key
-          if child_pk
+          # dedupe by primary key (single value for single-PK, tuple
+          # for composite-PK so two PK columns together identify a row).
+          unless child_pks.empty?
             seen = {}
             stripped = stripped.reject do |r|
-              pk_val = r[child_pk]
-              if seen[pk_val]
+              pk_key = child_pks.size == 1 ? r[child_pks.first] : child_pks.map { |pk| r[pk] }
+              if seen[pk_key]
                 true
               else
-                seen[pk_val] = true
+                seen[pk_key] = true
                 false
               end
             end
@@ -241,6 +242,7 @@ module Diamond
         first_arg = node.args.first
         suffix = case first_arg
                  when Diamond::AST::Column then first_arg.name
+                 when Diamond::AST::Star then 'star'
                  when Diamond::AST::Literal
                    val = first_arg.value
                    val.is_a?(String) ? val : (val.nil? ? 'nil' : val.to_s)

data/lib/diamond/table.rb

@@ -22,6 +22,13 @@ module Diamond
       @schema[:primary_key]
     end
 
+    # ordered list of primary-key columns. Empty for PK-less tables,
+    # one entry for single-PK, multiple entries for composite PKs (in
+    # the order SQLite stores them — typically declaration order).
+    def primary_keys
+      @schema[:primary_keys] || []
+    end
+
     # Sequel-style sugar: Users[1] → find(1).first. Returns the frozen
     # struct, or nil when no row matches (Hash-like miss semantics —
     # use find! when you want RecordNotFound instead).

data/lib/diamond/version.rb

@@ -1,3 +1,3 @@
 module Diamond
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: diamond-orm
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - GunsOrigins
@@ -89,7 +89,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.21
 specification_version: 4
 summary: Diamond, a relational algebra library for SQLite.
 test_files: []