diamond-orm 0.1.0

data/lib/diamond/api_catalog.rb

@@ -0,0 +1,676 @@
+# gems/diamond/lib/diamond/api_catalog.rb — hand-maintained call-form
+# catalog backing bin/dump_api.
+#
+# VARIATIONS is { method_name => Array<String> }. Each string is a
+# compact example call (no trailing meaning; the user knows). Order is
+# pedagogical: simplest → most specific, with block forms before hash
+# forms where both exist. Methods with no VARIATIONS entry fall back to
+# `Users.<method>` placeholder.
+#
+# SQL is { method_name => { example => sql, ... } } for forms that
+# compile to a deterministic short SQL (no DB boot; static strings only).
+# Block forms and value-dependent ones are intentionally omitted from SQL.
+#
+# Update contract: when a method gains a new accepted call form, add
+# the example here and run `rake api:check`. CI fails if a frozen
+# surface method is missing from VARIATIONS or if SQL keys reference
+# unknown examples.
+module Diamond
+  module ApiCatalog
+    VARIATIONS = {
+      # --- Filtering ---
+      'where' => [
+        # block: bare comparisons
+        'Users.where { age > 10 }',
+        'Users.where { id == 1 }',
+        'Users.where { id != 5 }',
+        'Users.where { name == "Arle" }',
+        'Users.where { age >= 25 }',
+        # block: logical
+        'Users.where { (age > 15) & (name == "Arle") }',
+        'Users.where { (age > 15) && (name == "Arle") }',
+        # block: membership
+        'Users.where { id.in(1, 2) }',
+        'Users.where { id.in(5) }',
+        'Users.where { id.in() }',
+        'Users.where { id == [1, 2] }',
+        'Users.where { id == [] }',
+        'Users.where { id != [1, 2] }',
+        'Users.where { id != [] }',
+        # block: range
+        'Users.where { age.between?(16, 25) }',
+        'Users.where { age.between?(10, 30) }',
+        # block: null
+        'Users.where { parent_id == nil }',
+        'Users.where { parent_id != nil }',
+        # block: pattern (LIKE)
+        'Users.where { name =~ /a+/ }',
+        'Users.where { name =~ /^Ar/ }',
+        'Users.where { name =~ /a{2,3}/ }',
+        'Users.where { name =~ /colou?r/ }',
+        'Users.where { name =~ /^A.le$/ }',
+        'Users.where { name =~ /foo|bar/ }',
+        'Users.where { name =~ /(foo)/ }',
+        # block: qualified (join first)
+        'Users.where { posts.title == "hi" }',
+        'Users.where { tags.tag == "x" }',
+        # hash: AND scalars
+        'Users.where(name: "Arle")',
+        'Users.where(name: "Arle", age: 16)',
+        # hash: operators
+        'Users.where(age: { gt: 10 })',
+        'Users.where(age: { gte: 18, lte: 65 })',
+        'Users.where(age: { lt: 100 })',
+        'Users.where(age: { lte: 0 })',
+        'Users.where(age: { in: [16, 25] })',
+        'Users.where(age: { nin: [16, 25] })',
+        'Users.where(name: { not: "Arle" })',
+        'Users.where(name: { like: "A%" })',
+        # hash: range, array, nil
+        'Users.where(age: 16..20)',
+        'Users.where(age: 20..150)',
+        'Users.where(age: [16, 25])',
+        'Users.where(age: [])',
+        'Users.where(name: nil)',
+        # hash: array of hashes → OR
+        'Users.where([{ age: 16 }, { age: 25 }])',
+        'Users.where([{ name: "Arle" }, { age: 100 }])',
+        'Users.where([{ age: { gt: 100 } }, { name: { in: %w[Arle Sig] } }])'
+      ],
+      'or' => [
+        'Users.where { name == "Arle" }.or { age > 20 }',
+        'Users.where(name: "Arle").or { age > 20 }'
+      ],
+      'find' => [
+        'Users.find(1)',
+        'Users.find(1).name',
+        'Users.find(99999).name',
+        'Users.find { |r| r.age > 20 }',
+        'Widgets.find(some_uuid)' # uses custom primary_key
+      ],
+      'find!' => [
+        'Users.find!(1).name',
+        'Users.find!(999)' # raises RecordNotFound
+      ],
+      'where_in' => [
+        'Users.where_in(:id, Posts.derive(:user_id))',
+        'Users.where_in(:id, subquery)',
+        'Users.where_in(:id, subquery).includes(:posts)'
+      ],
+      'by_*' => [
+        'Users.by_name("Sig")',
+        'Users.by_name_and_age("Sig", 25)',
+        'Users.by_name("Arle").derive(:age)'
+      ],
+      'find_by' => [
+        'Users.find_by(name: "Sig")',
+        'Users.find_by(name: "Nope")'
+      ],
+      'find_or_create_by' => [
+        'Users.find_or_create_by(name: "New", age: 5)'
+      ],
+
+      # --- Shaping ---
+      'derive' => [
+        'Users.derive(:name)',
+        'Users.derive(:name, :age)',
+        'Users.derive { name }',
+        'Users.derive { age }',
+        'Users.derive { id; name }',
+        'Users.derive { count(id) }',
+        'Users.derive { id; count(age) }',
+        'Users.derive { count(id); max(age); min(age) }',
+        'Users.derive { row_number.over(order: :id) }',
+        'Users.derive { row_number.over(partition_by: :age, order: :id) }',
+        'Users.derive([:tags, :tag])',
+        'Users.derive(:title, [:tags, :tag])'
+      ],
+      'join' => [
+        'Users.join(:posts)',
+        'Users.join(:posts, on: { id: :user_id })',
+        'Users.join(:posts, on: { id: :user_id }, type: :left)',
+        'Users.join(:order_items, on: { user_id: :id })',
+        'Users.join(:posts, eager: true)',
+        'Users.join(:categories)' # raises TableNotFound
+      ],
+      'includes' => [
+        'Users.includes(:posts)',
+        'Users.includes(:posts, :comments)',
+        'Users.includes(:posts).group(:age)'
+      ],
+      'order' => [
+        'Users.order(:age)',
+        'Users.order(:name, :age)',
+        'Users.order(age: :desc)',
+        'Users.order(name: :asc, age: :desc)',
+        'Users.order(:name, age: :desc)',
+        'Users.order([:age, :desc])',
+        'Users.order([:tags, :tag])',
+        'Users.order([:tags, :tag, :desc])',
+        'Users.order(:a).order(:b)'
+      ],
+      'reorder' => [
+        'Users.order(:age).reorder(:name)',
+        'Users.order(:age).reorder(age: :desc)',
+        'Users.order(:age).reorder'
+      ],
+      'limit' => [
+        'Users.limit(5)',
+        'Users.limit(5).limit(10)',
+        'Users.limit(-1)' # raises
+      ],
+      'offset' => [
+        'Users.offset(2)',
+        'Users.offset(-5)' # raises
+      ],
+      'distinct' => [
+        'Users.derive(:name).distinct'
+      ],
+      'group' => [
+        'Users.group(:age)',
+        'Users.group(:age, :name)',
+        'Users.group([:tags, :tag])'
+      ],
+      'having' => [
+        'Users.group(:age).having { count(id) > 1 }'
+      ],
+      'union' => [
+        'Users.where(age: 16).union(Users.where(age: 25))',
+        'Users.where { age > 18 }.union(Users.where { age < 5 })'
+      ],
+      'from_cte' => [
+        'Categories.from_cte(:tree)'
+      ],
+
+      # --- Terminals ---
+      'materialize' => [
+        'Users.where { age > 15 }.materialize',
+        'Users.order(:id).materialize'
+      ],
+      'first' => [
+        'Users.first',
+        'Users.first(2)',
+        'Users.first(1)',
+        'Users.order(:age).first',
+        'Users.first(2).map(&:name)'
+      ],
+      'first!' => [
+        'Users.first!',
+        'Users.where(age: 999).first!' # raises
+      ],
+      'last' => [
+        'Users.last',
+        'Users.last(2)'
+      ],
+      'last!' => [
+        'Users.last!',
+        'Users.where(age: 999).last!' # raises
+      ],
+      'sole' => [
+        'Users.where(age: 16).sole',
+        'Users.where(age: 999).sole' # raises
+      ],
+      'head' => [
+        'Users.head',
+        'Users.head(2)'
+      ],
+      'all' => [
+        'Users.all',
+        'Users.all.where { age > 15 }',
+        'Users.all.order(:id).materialize'
+      ],
+      'all!' => [
+        'Users.all!',
+        'Users.all.where { age > 15 }.all!',
+        'Users.all!.size'
+      ],
+      'each' => [
+        'Users.each { |r| puts r.name }',
+        'Users.each',
+        'Users.includes(:posts).each { |u| collected << u }'
+      ],
+      'find_each' => [
+        'Users.find_each(batch_size: 1000) { |r| puts r.name }',
+        'Users.find_each(batch_size: 1000)'
+      ],
+      'count' => [
+        'Users.count',
+        'Users.count(:age)',
+        'Users.where(age: 16).count'
+      ],
+      'sum' => [
+        'Users.sum(:age)',
+        'Users.where(age: 16).sum(:age)',
+        'Users.where(age: 999).sum(:age)', # nil
+        'Users.sum { |r| r.age }'
+      ],
+      'minimum' => [
+        'Users.minimum(:age)',
+        'Users.where(age: 999).minimum(:age)' # nil
+      ],
+      'maximum' => [
+        'Users.maximum(:age)'
+      ],
+      'average' => [
+        'Users.average(:age)',
+        'Users.where(age: 999).average(:age)' # nil
+      ],
+      'avg' => [
+        'Users.avg(:age)'
+      ],
+      'min' => [
+        'Users.min(:age)',
+        'Users.min',
+        'Users.min(2)',
+        'Users.min { |a, b| a <=> b }'
+      ],
+      'max' => [
+        'Users.max(:age)',
+        'Users.max',
+        'Users.max(2)',
+        'Users.max { |a, b| a <=> b }'
+      ],
+      'pluck' => [
+        'Users.pluck(:name)',
+        'Users.pluck(:name, :age)',
+        'Users.where(age: 16).pluck(:name)',
+        'Users.order(:id).pluck(:name)',
+        'Users.order(:id).pluck(:name, :age)'
+      ],
+      'pick' => [
+        'Users.where(age: 16).pick(:name)',
+        'Users.where(age: 16).pick(:age)',
+        'Users.where(age: 16).pick(:name, :age)',
+        'Users.where(age: 999).pick(:name)' # nil
+      ],
+      'ids' => [
+        'Users.ids',
+        'Users.where(age: 16).ids'
+      ],
+      'exists?' => [
+        'Users.exists?',
+        'Users.exists?(1)',
+        'Users.exists?(999)',
+        'Users.exists?(name: "Sig")',
+        'Users.exists?(name: "Nope")',
+        'Users.where(age: 25).exists?'
+      ],
+      'any?' => [
+        'Users.any?',
+        'Users.where(age: 999).any?',
+        'Users.any? { |r| r.age > 20 }'
+      ],
+      'none?' => [
+        'Users.none?',
+        'Users.where(age: 999).none?',
+        'Users.none? { |r| r.age > 20 }'
+      ],
+      'empty?' => [
+        'Users.empty?',
+        'Users.where(age: 999).empty?'
+      ],
+      'as_hash' => [
+        'Users.where(age: 16).as_hash.materialize'
+      ],
+      'as_array' => [
+        'Users.where(age: 16).as_array.materialize'
+      ],
+      'as_splat' => [
+        'Users.derive(:name).as_splat.materialize'
+      ],
+      'to_json_array' => [
+        'Users.to_json_array(:name)',
+        'Users.order(:id).to_json_array(:id)',
+        'Users.order(:id).to_json_array(:id, :name, :age)',
+        'Users.order(:id).to_json_array',
+        'Users.order(:id).to_json_array(:name, :id)',
+        'Users.order(id: :desc).limit(2).to_json_array(:id, :name)'
+      ],
+      'to_sql' => [
+        'Users.where(age: 16).to_sql',
+        'Users.order(:age).reorder(:name).to_sql',
+        'Users.order(:age).reorder.to_sql'
+      ],
+      'explain' => [
+        'Users.where(age: 16).explain'
+      ],
+      'ast_tree' => [
+        'puts Users.where(age: 16).ast_tree'
+      ],
+      '[]' => [
+        'Users[1].name',
+        'Users[999]', # nil on miss
+        'Widgets[some_uuid]' # custom primary_key
+      ],
+      'columns' => [
+        'Users.columns'
+      ],
+      'primary_key' => [
+        'Users.primary_key'
+      ],
+      'name' => [
+        'Users.name'
+      ],
+      'schema' => [
+        'Users.schema[:columns]'
+      ],
+
+      # --- Writes ---
+      'create' => [
+        'Users.create(id: 1, name: "Arle", age: 16)',
+        'Users.create(name: "Lemres", age: 30)',
+        'Users.create(name: "Ret", age: 40, returning: [:id, :name])',
+        'Users.create(id: 3, name: "Carbuncle", age: 16)'
+      ],
+      'insert_all' => [
+        'Users.insert_all([{ name: "A", age: 1 }, { name: "B", age: 2 }])'
+      ],
+      'batch_create' => [
+        'Users.batch_create([{ name: "A" }, { name: "B" }])'
+      ],
+      'update' => [
+        'Users.where { id == 1 }.update { age 17 }',
+        'Users.where { id == 2 }.update { age 200; name "Carby" }',
+        'Users.where { id == 3 }.update { age 26 }'
+      ],
+      'update_all' => [
+        'Users.update_all(age: 30)'
+      ],
+      'batch_update' => [
+        'Users.where { id == 1 }.batch_update({ age: 2 }, returning: [:id])'
+      ],
+      'delete' => [
+        'Users.where(age: 16).delete',
+        'Users.where(age: 16).delete(returning: [:id])'
+      ],
+      'delete_all' => [
+        'Users.where(age: 30).delete_all'
+      ],
+      'increment!' => [
+        'Users.increment!(1, :age)',
+        'Users.increment!(1, :age, 2)'
+      ],
+      'decrement!' => [
+        'Users.decrement!(1, :age)',
+        'Users.decrement!(1, :age, 2)'
+      ],
+      'toggle!' => [
+        'Flags.toggle!(1, :flag)'
+      ],
+
+      # --- DDL ---
+      'define_relation' => [
+        '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 }'
+      ],
+      'alter_table' => [
+        'Diamond.alter_table(:users) { |t| t.add_column :nickname, String }',
+        'Diamond.alter_table(:users) { |t| t.add_column :bad, Integer, primary_key: true }' # raises
+      ],
+      'create_index' => [
+        'Diamond.create_index(:users, :name, name: "idx_users_name")',
+        'Diamond.create_index(:users, [:name, :age], name: "idx_users_pair", unique: true)'
+      ]
+    }.freeze
+
+    # { method => { example_string => sql_string } }. Examples must
+    # match VARIATIONS exactly. SQL strings are static and may include
+    # `?` placeholders (params are runtime; not shown).
+    SQL = {
+      'where' => {
+        'Users.where { age > 10 }'         => 'SELECT * FROM users WHERE age > ?',
+        'Users.where { id == 1 }'          => 'SELECT * FROM users WHERE id = ?',
+        'Users.where { id != 5 }'          => 'SELECT * FROM users WHERE id != ?',
+        'Users.where { name == "Arle" }'   => 'SELECT * FROM users WHERE name = ?',
+        'Users.where { (age > 15) & (name == "Arle") }' => 'SELECT * FROM users WHERE (age > ?) AND (name = ?)',
+        'Users.where { (age > 15) && (name == "Arle") }' => 'SELECT * FROM users WHERE (age > ?) AND (name = ?)',
+        'Users.where { id.in(1, 2) }'      => 'SELECT * FROM users WHERE id IN (?, ?)',
+        'Users.where { id == [] }'         => 'SELECT * FROM users WHERE 1=0',
+        'Users.where { id != [] }'         => 'SELECT * FROM users WHERE 1=1',
+        'Users.where { id == [1, 2] }'     => 'SELECT * FROM users WHERE id IN (?, ?)',
+        'Users.where { id != [1, 2] }'     => 'SELECT * FROM users WHERE id NOT IN (?, ?)',
+        'Users.where { age.between?(16, 25) }' => 'SELECT * FROM users WHERE age BETWEEN ? AND ?',
+        'Users.where { parent_id == nil }' => 'SELECT * FROM users WHERE parent_id IS NULL',
+        'Users.where { name =~ /a+/ }'     => 'SELECT * FROM users WHERE name LIKE ?',
+        'Users.where { name =~ /^Ar/ }'    => 'SELECT * FROM users WHERE name LIKE ?',
+        'Users.where(name: "Arle")'        => 'SELECT * FROM users WHERE name = ?',
+        'Users.where(name: "Arle", age: 16)' => 'SELECT * FROM users WHERE name = ? AND age = ?',
+        'Users.where(age: { gt: 10 })'     => 'SELECT * FROM users WHERE age > ?',
+        'Users.where(age: { gte: 18, lte: 65 })' => 'SELECT * FROM users WHERE age >= ? AND age <= ?',
+        'Users.where(age: { in: [16, 25] })' => 'SELECT * FROM users WHERE age IN (?, ?)',
+        'Users.where(age: { nin: [16, 25] })' => 'SELECT * FROM users WHERE age NOT IN (?, ?)',
+        'Users.where(name: { not: "Arle" })' => 'SELECT * FROM users WHERE name != ?',
+        'Users.where(age: 16..20)'         => 'SELECT * FROM users WHERE age BETWEEN ? AND ?',
+        'Users.where(age: [16, 25])'       => 'SELECT * FROM users WHERE age IN (?, ?)',
+        'Users.where(age: [])'             => 'SELECT * FROM users WHERE 1=0',
+        'Users.where(name: nil)'           => 'SELECT * FROM users WHERE name IS NULL',
+        'Users.where([{ age: 16 }, { age: 25 }])' => 'SELECT * FROM users WHERE (age = ?) OR (age = ?)'
+      },
+      'order' => {
+        'Users.order(:age)'                  => 'SELECT * FROM users ORDER BY age ASC',
+        'Users.order(:name, :age)'           => 'SELECT * FROM users ORDER BY name ASC, age ASC',
+        'Users.order(age: :desc)'            => 'SELECT * FROM users ORDER BY age DESC',
+        'Users.order(name: :asc, age: :desc)' => 'SELECT * FROM users ORDER BY name ASC, age DESC',
+        'Users.order(:name, age: :desc)'     => 'SELECT * FROM users ORDER BY name ASC, age DESC'
+      },
+      'limit' => {
+        'Users.limit(5)' => 'SELECT * FROM users LIMIT 5'
+      },
+      'offset' => {
+        'Users.offset(2)' => 'SELECT * FROM users OFFSET 2'
+      },
+      'find' => {
+        'Users.find(1)' => 'SELECT * FROM users WHERE id = ?'
+      },
+      'where_in' => {
+        'Users.where_in(:id, Posts.derive(:user_id))' => 'SELECT * FROM users WHERE id IN (SELECT user_id FROM posts)'
+      },
+      'count' => {
+        'Users.count'      => 'SELECT count(id) AS count_id FROM users',
+        'Users.count(:age)' => 'SELECT count(age) AS count_age FROM users'
+      },
+      'sum' => {
+        'Users.sum(:age)' => 'SELECT sum(age) AS sum_age FROM users'
+      },
+      'minimum' => {
+        'Users.minimum(:age)' => 'SELECT min(age) AS min_age FROM users'
+      },
+      'maximum' => {
+        'Users.maximum(:age)' => 'SELECT max(age) AS max_age FROM users'
+      },
+      'average' => {
+        'Users.average(:age)' => 'SELECT avg(age) AS avg_age FROM users'
+      },
+      'avg' => {
+        'Users.avg(:age)' => 'SELECT avg(age) AS avg_age FROM users'
+      },
+      'distinct' => {
+        'Users.derive(:name).distinct' => 'SELECT DISTINCT name FROM users'
+      },
+      'group' => {
+        'Users.group(:age)' => 'SELECT * FROM users GROUP BY age'
+      }
+    }.freeze
+
+    # Methods with NO documentation entry (intentionally — the user
+    # shouldn't see them in the default dump; their only purpose is
+    # as a non-method data accessor). Currently empty.
+    HIDDEN = [].freeze
+
+    # Diamond singleton meanings (one-line each). Values are displayed
+    # after the signature; if the value is an Array, each element is
+    # rendered as an `e.g.` example (matches the table/qo form).
+    DIAMOND = {
+      'wake_up'                 => 'boot engine (:memory: or file path)',
+      'fiber_yield_on_progress' => 'control Fiber autoyield on progress',
+      'engine'                  => 'per-Ractor engine handle (escape hatch: .db)',
+      'transaction'             => 'block transaction (nest via savepoint)',
+      'savepoint'               => 'nested savepoint inside transaction',
+      'backup'                  => 'hot backup to file',
+      'query_with_timeout'      => 'run block with progress timeout',
+      'track_changes'           => 'changeset capture (needs session ext)',
+      'trace'                   => 'tap every SQL string',
+      'tables'                  => 'sorted list of defined table names',
+      'limit'                   => 'sqlite PRAGMA limit get/set',
+      'status'                  => 'sqlite PRAGMA status pair',
+      'runtime_status'          => 'sqlite runtime value',
+      'busy_timeout'            => 'sqlite busy_timeout get',
+      'busy_timeout='           => 'sqlite busy_timeout set',
+      'gvl_release_threshold'   => 'GVL release threshold get',
+      'gvl_release_threshold='  => 'GVL release threshold set',
+      'on_progress'             => 'install progress callback',
+      'load_extension'          => 'load sqlite extension',
+      'sleep'                   => 'interruptible sleep (yields to engine)',
+      'quote_ident'             => 'quote an identifier safely',
+      'validate_ident!'         => 'raise unless name matches identifier rules',
+      'clear_caches!'           => 'drop parser/struct/finder caches',
+      'with'                    => [
+        'Diamond.with(teens: Users.where { age < 20 }) { |d| d.from(:teens) }',
+        'Diamond.with(over10: Users.where { age > 10 }) { |d| d.from(:over10).where { ... } }'
+      ],
+      'with_recursive'          => [
+        'Diamond.with_recursive(:tree, base, recursive)'
+      ]
+    }.freeze
+
+    # Per-method notes (one-line, printed under the signature).
+    # 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',
+      'derive'          => 'one Projection per chain — a second derive raises',
+      'reorder'         => 'replaces existing ORDER BY; bare reorder clears it',
+      'limit'           => 'replaces previous limit (last wins)',
+      'offset'          => 'replaces previous offset (last wins)',
+      'distinct'        => 'replaces previous distinct; idempotent',
+      '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',
+      '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',
+      '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)',
+      'as_splat'        => 'mode carries; single-column values out (the ultimate pluck)',
+      'to_json_array'   => 'rejects eager joins and WITH/CTE chains; one JSON string crosses the Ruby/C boundary',
+      'sleep'           => 'interruptible — yields to the engine progress hook, not plain Kernel.sleep',
+      'query_with_timeout' => 'uses sqlite progress handler; raises QueryInterruptedError on timeout',
+      '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',
+      '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.',
+      'alter_table'     => 'block must use t.add_column only (SQLite cannot ADD COLUMN a primary key or foreign key). t is a scratch DSL proxy. See BLOCK_GRAMMAR.',
+      'create_index'    => 'no block form — call directly with column(s) and name: kwarg. Equivalent to t.index(...) inside define_relation, but for existing tables.'
+    }.freeze
+
+    # DDL block grammar. Each key is a method name callable inside the
+    # block passed to define_relation / alter_table. The receiver is
+    # conventionally named `t` but the variable is just a scratch DSL
+    # proxy — see the T_PROXY_NOTE constant below.
+    BLOCK_GRAMMAR = {
+      'attribute' => {
+        signature: 't.attribute(name, type, primary_key: false, nullable: true, default: <none>)',
+        summary:   'column declaration (CREATE TABLE)',
+        kwargs: [
+          'primary_key: Bool, default false — emits PRIMARY KEY (overrides nullable)',
+          'nullable: Bool, default true — nullable: false emits NOT NULL',
+          'default: Numeric | true | false | String | nil — emits DEFAULT <value>'
+        ],
+        types: 'Integer / String / Float / TrueClass / FalseClass (compiler-enforced)',
+        available_in: 'define_relation',
+        examples: [
+          't.attribute :id, Integer, primary_key: true, nullable: false',
+          't.attribute :name, String, nullable: false',
+          't.attribute :age, Integer',
+          't.attribute :price, Float',
+          't.attribute :tagline, String, default: "new blog"'
+        ],
+        source: 'parser.rb:429-433 / proxy.rb:378-382'
+      },
+      'add_column' => {
+        signature: 't.add_column(name, type, primary_key: false, nullable: true, default: <none>)',
+        summary:   'column declaration for ALTER TABLE — same shape as attribute',
+        kwargs: [
+          'primary_key: Bool (REJECTED at compile time — SQLite cannot ADD COLUMN a primary key)',
+          'nullable: Bool, default true',
+          'default: Numeric | true | false | String | nil'
+        ],
+        types: 'Integer / String / Float / TrueClass / FalseClass',
+        available_in: 'alter_table (only)',
+        examples: [
+          't.add_column :bio, String',
+          't.add_column :level, Integer, default: 0'
+        ],
+        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)',
+        available_in: 'define_relation',
+        examples: [
+          't.primary_key :id'
+        ],
+        source: 'parser.rb:439-442 / proxy.rb:390-393'
+      },
+      'foreign_key' => {
+        signature: 't.foreign_key(local, ref_table, ref_col = :id, on_delete: nil, on_update: nil)',
+        summary:   'table-level foreign key (CREATE TABLE child line)',
+        kwargs: [
+          'on_delete: :cascade | :set_null | :set_default | :restrict | :no_action',
+          'on_update: same set as on_delete'
+        ],
+        available_in: 'define_relation (FKs are not allowed in alter_table)',
+        examples: [
+          't.foreign_key :user_id, :users',
+          't.foreign_key :owner_id, :owners, on_delete: :cascade',
+          't.foreign_key :post_id, :posts, on_delete: :cascade'
+        ],
+        source: 'parser.rb:443-465 / proxy.rb:395-403'
+      },
+      'index' => {
+        signature: 't.index(col1, col2, ..., name: <required>, unique: false)',
+        summary:   'inline index (CREATE INDEX) emitted right after CREATE TABLE',
+        kwargs: [
+          'name: required (Symbol or identifier string) — used as the index name',
+          'unique: Bool, default false — emits CREATE UNIQUE INDEX'
+        ],
+        available_in: 'define_relation (use Diamond.create_index for existing tables)',
+        examples: [
+          't.index :name, unique: true, name: :idx_widgets_name',
+          't.index :a, :b, name: :idx_w2_ab',
+          't.index :parent_id, :position, unique: true, name: :idx_media_nodes_parent_position'
+        ],
+        source: 'parser.rb:466-471 / proxy.rb:405-410'
+      }
+    }.freeze
+
+    # Explanation of the `t` (or any other) block parameter. The
+    # receiver is purely a scratch DSL proxy: in console paths the block
+    # runs via instance_exec against a fresh DdlRecorder; in Prism
+    # file-backed parsing the receiver is never examined at all — only
+    # the method names and their arguments matter.
+    T_PROXY_NOTE = <<~NOTE.freeze
+      `t` is a scratch DSL proxy — the variable name is convention only.
+      In console paths the block runs via instance_exec against a fresh
+      DdlRecorder; in the Prism file-backed path the receiver is never
+      examined (only the method names and args matter). Any block
+      parameter name works (`|t|`, `|x|`, `|tbl|`), and the no-arg
+      bare form (`do ... end`) is also accepted.
+    NOTE
+  end
+end