diamond-orm 0.1.0

data/lib/diamond/dsl/default.rb

@@ -0,0 +1,419 @@
+module Diamond
+  module DSL
+    module Default
+      # Triple form, all lazy and chainable:
+      #   where { age > 10 }              # block: pure column predicates
+      #   where(status: 'active')         # hash: AND across columns
+      #   where([{ a: 1 }, { b: 2 }])     # array of hashes: OR across hashes
+      # Blocks stay exactly as before (columns + literals only, no
+      # locals); hashes take runtime values without parsing.
+      def where(*args, &block)
+        if block
+          unless args.empty?
+            raise ArgumentError, "where takes a Hash, Array of Hashes, or a block — not both"
+          end
+          _build_where(&block)
+        elsif args.size == 1
+          dispatch_where_arg(args.first)
+        else
+          raise ArgumentError, "where expects a Hash, Array of Hashes, or a block, got #{args.size} positional args"
+        end
+      end
+
+      # chain `.or { condition }` to OR the last where clause with the new one
+      # `Users.where { name == 'Arle' }.or { age > 10 }` => `WHERE name = ? OR age > ?`
+      def or(&block)
+        _build_or_where(&block)
+      end
+
+      def find(id = nil, &block)
+        # Block form is Enumerable#find (Ruby-side search). Bare form is the
+        # SQL PK lookup. Never bare `super`: DSL sits after Enumerable in the
+        # chain, so bind explicitly (same reason as QueryObject#any?).
+        if block
+          return id.nil? ? Enumerable.instance_method(:find).bind_call(self, &block) : Enumerable.instance_method(:find).bind_call(self, id, &block)
+        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)
+      end
+
+      # like find, but raises RecordNotFound instead of returning an
+      # empty chain. find stays lazy so it keeps chaining.
+      def find!(id)
+        record = find(id).first
+        raise Diamond::RecordNotFound, "No record found with id #{id.inspect}" if record.nil?
+
+        record
+      end
+
+      # `where_in(:col, query)` creates a WHERE col IN (SELECT ...) condition.
+      # `Users.where_in(:id, Posts.derive(:user_id))` compiles to
+      # `SELECT * FROM users WHERE id IN (SELECT user_id FROM posts)`.
+      def where_in(column, subquery)
+        col_node = AST::Column.new(column)
+        sub_node = AST::Subquery.new(subquery)
+        condition = AST::In.new(col_node, sub_node)
+        _build_where_node(condition)
+      end
+
+      # `left UNION ALL right`. both sides must project the same width
+      # (`*` counts as the table's width). terminal: the result supports
+      # materialize/each/to_sql/explain, but chaining more clauses after
+      # a union raises — aggregates need wrapping.
+      def union(other)
+        raise ArgumentError, "union needs a QueryObject, got #{other.class}" unless other.is_a?(Diamond::QueryObject)
+
+        left = _wrap
+        width = ->(q) {
+          proj = q.ast.find { |n| n.is_a?(AST::Projection) }
+          proj ? proj.columns.size : q.table.schema[:columns].size
+        }
+        lw, rw = width.call(left), width.call(other)
+        unless lw == rw
+          raise ArgumentError, "union needs equal widths, got #{lw} vs #{rw}"
+        end
+
+        Diamond::QueryObject.new(left.table, [AST::Union.new(left, other)])
+      end
+
+      # Build a projection. Accepts column symbols, AST nodes, or a block
+      # that yields bare columns, function calls, and window chains. Also
+      # used to shape a subquery for `where_in`:
+      #   Users.where_in(:id, Posts.derive(:user_id))
+      def derive(*args, &block)
+        _build_projection(*args, &block)
+      end
+
+      def join(table_name, on: nil, type: :inner, eager: false, as: nil)
+        _build_join(table_name, type, on, eager: eager, as: as)
+      end
+
+      # `.includes(:posts, :comments)` eager-loads child relations.
+      # sugar for `.join(:posts, eager: true).join(:comments, eager: true)`.
+      def includes(*tables, **opts)
+        _build_includes(*tables, **opts)
+      end
+
+      def define_relation(name, &block)
+        ast = _build_relation(name, &block)
+        sql, params = Diamond::Compiler::DDL.compile(ast)
+        Diamond.engine.db.execute(sql, *params)
+
+        # indexes go after the table exists. needs PRAGMA foreign_keys=ON
+        # for cascades (wake_up turns it on).
+        ast.columns.select { |c| c.is_a?(Diamond::AST::IndexDefinition) }.each do |idx|
+          idx_sql, idx_params = Diamond::Compiler::DDL.compile_index(idx, name)
+          Diamond.engine.db.execute(idx_sql, *idx_params)
+        end
+
+        Diamond.engine.load_one_table!(name)
+
+        # bind a frozen top-level constant immediately. without this, a
+        # worker Ractor would have to fall through `const_missing`, which
+        # calls `Object.const_set` and is illegal from non-main Ractors.
+        const_name = name.to_s.split('_').map(&:capitalize).join
+        unless Object.const_defined?(const_name, false)
+          proxy = Diamond::Table.new(name).freeze
+          Object.const_set(const_name, proxy)
+          Diamond.note_bound_table(const_name)
+        end
+
+        ast
+      end
+
+      def create_index(table_name, columns, unique: false, name:)
+        raise ArgumentError, "create_index requires `name:` kwarg" unless name
+        cols = Array(columns)
+        raise ArgumentError, "create_index requires at least one column" if cols.empty?
+        idx = Diamond::AST::IndexDefinition.new(name, cols, unique: !!unique)
+        sql, params = Diamond::Compiler::DDL.compile_index(idx, table_name)
+        Diamond.engine.db.execute(sql, *params)
+        Diamond.engine.load_one_table!(table_name)
+        idx
+      end
+
+      # Safe migrations: add columns to a live table. Only `add_column`
+      # statements allowed in the block (indexes have create_index;
+      # SQLite can't ADD COLUMN a primary key or foreign key).
+      #
+      #   Diamond.alter_table(:widgets) do |t|
+      #     t.add_column :bio, String
+      #     t.add_column :stock, Integer, default: 0
+      #   end
+      def alter_table(table_name, &block)
+        raise ArgumentError, "alter_table requires a block" unless block
+        nodes = Diamond::Parser.parse_ddl(block)
+        nodes.each do |node|
+          unless node.is_a?(Diamond::AST::ColumnDefinition)
+            raise ArgumentError, "alter_table only supports `add_column`, got #{node.class}"
+          end
+          sql, params = Diamond::Compiler::DDL.compile_add_column(table_name, node)
+          Diamond.engine.db.execute(sql, *params)
+        end
+        Diamond.engine.load_one_table!(table_name)
+        nodes
+      end
+
+      def create(**kwargs)
+        returning = kwargs.delete(:returning) || []
+        _build_create(kwargs, returning: returning)
+      end
+
+      def update(returning: [], &block)
+        result = _build_update(returning: returning, &block)
+        @cached_result = nil if defined?(@cached_result) && @cached_result
+        result
+      end
+
+      def delete(returning: [])
+        result = _build_delete(returning: returning)
+        @cached_result = nil if defined?(@cached_result) && @cached_result
+        result
+      end
+
+      def from_cte(alias_name)
+        Diamond::QueryObject.new(self, [Diamond::AST::From.new(alias_name)])
+      end
+
+      # --- Chaining + terminals ---
+
+      def order(*args, **kwargs)
+        _build_order(*args, **kwargs)
+      end
+
+      def limit(n)
+        _build_limit(n)
+      end
+
+      def offset(n)
+        _build_offset(n)
+      end
+
+      def distinct
+        _chain(AST::Distinct.new)
+      end
+
+      def group(*columns)
+        _build_group(columns)
+      end
+
+      def having(&block)
+        _build_having(&block)
+      end
+
+      def pluck(*columns)
+        _wrap.pluck(*columns)
+      end
+
+      def pick(*columns)
+        _wrap.pick(*columns)
+      end
+
+      def ids
+        _wrap.ids
+      end
+
+      def exists?(filter = nil)
+        _wrap.exists?(filter)
+      end
+
+      def any?(*args, &block)
+        _wrap.any?(*args, &block)
+      end
+
+      def none?(*args, &block)
+        _wrap.none?(*args, &block)
+      end
+
+      def empty?
+        _wrap.empty?
+      end
+
+      def count(column = nil)
+        _wrap.count(column)
+      end
+
+      def sum(column = nil, &block)
+        _wrap.sum(column, &block)
+      end
+
+      def minimum(column)
+        _wrap.minimum(column)
+      end
+
+      def maximum(column)
+        _wrap.maximum(column)
+      end
+
+      def average(column)
+        _wrap.average(column)
+      end
+
+      alias avg average
+
+      def min(column = nil, &block)
+        _wrap.min(column, &block)
+      end
+
+      def max(column = nil, &block)
+        _wrap.max(column, &block)
+      end
+
+      def first(n = 1)
+        _wrap.first(n)
+      end
+
+      def first!
+        _wrap.first || raise(Diamond::RecordNotFound, "No record found for #{_wrap.table.name}")
+      end
+
+      def last(n = 1)
+        _wrap.last(n)
+      end
+
+      def last!
+        _wrap.last || raise(Diamond::RecordNotFound, "No record found for #{_wrap.table.name}")
+      end
+
+      # exactly one row or RecordNotFound (on zero AND on two-plus).
+      # Bounds the work with LIMIT 2 unless the chain already limits.
+      def sole
+        q = _wrap
+        q = q.limit(2) unless q.ast.any? { |n| n.is_a?(AST::Limit) }
+        results = q.materialize
+        unless results.size == 1
+          raise Diamond::RecordNotFound, "Expected exactly one record, got #{results.size}"
+        end
+        results.first
+      end
+
+      # Lazy shorthand for the unchained scope (`SELECT * FROM table`).
+      # Returns a QueryObject so further chains (where/order/etc.) keep working.
+      def all
+        _wrap
+      end
+
+      # Eagerly materialize all records. Same SQL as `.all` but
+      # returns an Array (not a lazy QueryObject).
+      def all!
+        all.to_a
+      end
+
+      # First row(s) with no implicit ordering (first/last inject
+      # ORDER BY pk). Same single-vs-array shape as first.
+      def head(n = 1)
+        results = _wrap.limit(n).materialize
+        n == 1 ? results.first : results
+      end
+
+      def each(&block)
+        _wrap.each(&block)
+      end
+
+      def as_hash
+        _wrap.as_hash
+      end
+
+      def as_array
+        _wrap.as_array
+      end
+
+      def as_splat
+        _wrap.as_splat
+      end
+
+      def to_json_array(*columns)
+        _wrap.to_json_array(*columns)
+      end
+
+      # pk-ordered batched iteration. Returns an enumerator without a
+      # block. Appends the pk as a final tiebreak so batches are
+      # 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)
+        offset = 0
+        loop do
+          batch = scope.limit(batch_size).offset(offset).materialize
+          break if batch.empty?
+          batch.each(&block)
+          break if batch.size < batch_size
+          offset += batch_size
+        end
+        nil
+      end
+
+      def find_by(**attrs)
+        raise ArgumentError, "find_by requires at least one attribute" if attrs.empty?
+        where(attrs).first
+      end
+
+      # First match in the current scope, else create with exactly the
+      # given attributes (scope conditions are NOT auto-merged). No
+      # locking — same caveat as anywhere without a unique index.
+      def find_or_create_by(**attrs)
+        raise ArgumentError, "find_or_create_by requires at least one attribute" if attrs.empty?
+        where(attrs).first || create(**attrs)
+      end
+
+      # Like order, but replaces any existing ordering instead of
+      # merging. Bare `reorder` clears ordering entirely.
+      def reorder(*args, **kwargs)
+        _build_reorder(*args, **kwargs)
+      end
+
+            def delete_all(returning: [])
+        delete(returning: returning)
+      end
+
+      # Bulk update with a runtime hash — no block, no parsing.
+      # Returns the row count, a flat array of values (single Symbol
+      # returning), or an array of structs (Array returning).
+      def update_all(returning: [], **hash)
+        raise ArgumentError, "update_all requires at least one column" if hash.empty?
+        hash.each_key { |c| Diamond::Parser.validate_column!(c, _schema_for_dsl) }
+        result = _wrap.batch_update(hash, returning: returning)
+        @cached_result = nil if defined?(@cached_result) && @cached_result
+        result
+      end
+
+      def increment!(id, column, by = 1)
+        column = column.to_sym
+        Diamond::Parser.validate_column!(column, _schema_for_dsl)
+        record = find!(id)
+        new_value = record.public_send(column) + by
+        find(id).update_all(column => new_value)
+        new_value
+      end
+
+      def decrement!(id, column, by = 1)
+        increment!(id, column, -by)
+      end
+
+      # Flips 0/1-int columns (1/true read as on). Narrow by design —
+      # Diamond has no boolean convention beyond SQLite ints.
+      def toggle!(id, column)
+        column = column.to_sym
+        Diamond::Parser.validate_column!(column, _schema_for_dsl)
+        record = find!(id)
+        current = record.public_send(column)
+        new_value = (current == true || current == 1) ? 0 : 1
+        find(id).update_all(column => new_value)
+        new_value
+      end
+
+      private
+
+      def _wrap
+        is_a?(Diamond::Table) ? Diamond::QueryObject.new(self) : self
+      end
+    end
+  end
+end

data/lib/diamond/engine.rb

@@ -0,0 +1,226 @@
+require 'extralite'
+
+module Diamond
+  # Engine wraps an Extralite database connection. Schema introspection happens
+  # at boot; everything derived from the schema (table proxies, FK caches)
+  # lives on the engine instance. Extralite 3.0 enables WAL, foreign_keys and
+  # synchronous=NORMAL by default; no PRAGMA setup needed at wake_up.
+  class Engine
+    attr_reader :db, :schema_cache, :foreign_keys, :prepared_cache
+
+    def initialize(db_path, busy_timeout: nil, gvl_release_threshold: nil,
+                   on_progress: nil, extensions: [])
+      @db = Extralite::Database.new(db_path)
+      @schema_cache = {}
+      @foreign_keys = {}
+      @prepared_cache = {}     # Phase 7: per-engine, mutable (frozen engines are fine)
+
+      @busy_timeout = busy_timeout
+      @db.busy_timeout = busy_timeout if busy_timeout
+      @db.gvl_release_threshold = gvl_release_threshold if gvl_release_threshold
+      # Progress-hook precedence: an explicit proc always wins; `false`
+      # is an explicit opt-out (see wake_up's auto_fiber_yield: false);
+      # otherwise auto-install the yield hook when a Fiber::Scheduler
+      # is present at boot. No scheduler → no hook, so standard
+      # threaded/Ractor apps pay nothing and behave exactly as before.
+      @explicit_progress_hook = !on_progress.nil?
+      @scheduler_hook_installed = false
+      unless on_progress == false
+        @db.on_progress(&on_progress) if on_progress
+        # `Kernel.` prefix is load-bearing in spirit: never let this
+        # resolve to anything but Kernel#sleep.
+        if on_progress.nil? && Fiber.scheduler
+          @db.on_progress { Kernel.sleep(0); nil }
+          @scheduler_hook_installed = true
+        end
+      end
+      Array(extensions).each { |path| @db.load_extension(path) }
+
+      load_schema!
+    end
+
+    # Late-bind the yield hook when a scheduler appears after boot
+    # (e.g. engines booted pre-reactor, fibers later). Idempotent and
+    # safe under concurrent first touch (GVL-atomic sets of an
+    # identical hook); never overrides an explicit hook or an opt-out,
+    # never uninstalls. Called from Diamond.engine on every access —
+    # two ivar reads once settled.
+    def sync_scheduler_hook!
+      return if @explicit_progress_hook || @scheduler_hook_installed
+      return unless Fiber.scheduler
+      @db.on_progress { Kernel.sleep(0); nil }
+      @scheduler_hook_installed = true
+    end
+
+    def reload_schema!
+      @schema_cache = {}
+      @foreign_keys = {}
+      @prepared_cache.clear
+      load_schema!
+      Diamond.clear_caches!
+      freeze!
+    end
+
+    # freeze the schema-derived state so the engine is shareable across
+    # Ractors. the underlying Extralite database handle remains live; only
+    # the cached metadata gets sealed. prepared_cache stays mutable so
+    # queries can cache new statements after freeze.
+    def freeze!
+      @schema_cache.freeze
+      @foreign_keys.freeze
+      @schema_cache.each_value do |schema|
+        schema.freeze
+        schema[:columns].freeze
+        schema[:types].freeze
+        schema[:types].each_value(&:freeze)
+        schema[:nullable].freeze
+        schema[:nullable].each_value(&:freeze)
+        schema[:defaults].freeze
+        schema[:required].freeze
+        schema[:required].each_value(&:freeze)
+      end
+      @foreign_keys.each_value(&:freeze)
+      self
+    end
+
+    # refresh one table instead of rescanning everything.
+    def load_one_table!(table_name)
+      sym = table_name.to_sym
+      new_schema = @schema_cache.merge(sym => parse_table_schema(sym))
+      new_fks    = @foreign_keys.merge(sym => parse_foreign_keys(sym))
+      @schema_cache = new_schema
+      @foreign_keys = new_fks
+      @prepared_cache.clear
+      freeze!
+    end
+
+    # --- Phase 7 concurrency tuning pass-throughs ---
+    # SQLite exposes no busy_timeout read, so the engine tracks the
+    # last-set value itself (nil until first set).
+    def busy_timeout; @busy_timeout; end
+    def busy_timeout=(val); @busy_timeout = val; @db.busy_timeout = val; end
+    def gvl_release_threshold; @db.gvl_release_threshold; end
+    def gvl_release_threshold=(val); @db.gvl_release_threshold = val; end
+
+    # --- Phase 7 progress hook ---
+    def on_progress(&block); @db.on_progress(&block); end
+
+    # --- Phase 7 extension loading ---
+    def load_extension(path); @db.load_extension(path); end
+
+    # --- Phase 7 prepared-statement cache ---
+    # Returns a cached Extralite::Query (prepared statement) for the given
+    # SQL, creating it on first use. Each engine has its own cache; each
+    # Ractor gets its own engine, so cache state stays per-Ractor.
+    #
+    # Cache key includes the fetch mode: a statement fixed to :array
+    # must never be handed to a hash-mode caller and vice versa.
+    def prepared(sql, mode = :hash)
+      key = [sql, mode]
+      @prepared_cache[key] ||= case mode
+                               when :array then @db.prepare_array(sql)
+                               else @db.prepare(sql)
+                               end
+    end
+
+    # --- Phase 7 status / limit introspection ---
+    DBSTATUS_CODES = {
+      lookaside_used:    Extralite::SQLITE_DBSTATUS_LOOKASIDE_USED,
+      cache_used:        Extralite::SQLITE_DBSTATUS_CACHE_USED,
+      schema_used:       Extralite::SQLITE_DBSTATUS_SCHEMA_USED,
+      stmt_used:         Extralite::SQLITE_DBSTATUS_STMT_USED,
+      cache_hit:         Extralite::SQLITE_DBSTATUS_CACHE_HIT,
+      cache_miss:        Extralite::SQLITE_DBSTATUS_CACHE_MISS,
+      deferred_fks:      Extralite::SQLITE_DBSTATUS_DEFERRED_FKS
+    }.freeze
+
+    LIMIT_CODES = {
+      length:            Extralite::SQLITE_LIMIT_LENGTH,
+      sql_length:        Extralite::SQLITE_LIMIT_SQL_LENGTH,
+      column:            Extralite::SQLITE_LIMIT_COLUMN,
+      expr_depth:        Extralite::SQLITE_LIMIT_EXPR_DEPTH,
+      compound_select:   Extralite::SQLITE_LIMIT_COMPOUND_SELECT,
+      function_arg:      Extralite::SQLITE_LIMIT_FUNCTION_ARG,
+      attached:          Extralite::SQLITE_LIMIT_ATTACHED,
+      variable_number:   Extralite::SQLITE_LIMIT_VARIABLE_NUMBER,
+      trigger_depth:     Extralite::SQLITE_LIMIT_TRIGGER_DEPTH,
+      worker_threads:    Extralite::SQLITE_LIMIT_WORKER_THREADS
+    }.freeze
+
+    # db.status(code) → [current, high_watermark]
+    def status(code)
+      @db.status(DBSTATUS_CODES.fetch(code))
+    end
+
+    # db.limit(code) → current
+    # db.limit(code, value) → set + return value
+    def limit(code, value = nil)
+      if value.nil?
+        @db.limit(LIMIT_CODES.fetch(code))
+      else
+        @db.limit = [LIMIT_CODES.fetch(code), value]
+        value
+      end
+    end
+
+    private
+
+    def load_schema!
+      tables = @db.query("SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'")
+
+      tables.each do |row|
+        table_name = row[:name].to_sym
+        @schema_cache[table_name] = parse_table_schema(table_name)
+        @foreign_keys[table_name] = parse_foreign_keys(table_name)
+      end
+    end
+
+    def parse_table_schema(table_name)
+      columns = []
+      types = {}
+      nullable = {}
+      defaults = {}
+      required = {}
+      primary_key = nil
+
+      @db.query("PRAGMA table_info(#{Diamond.quote_ident(table_name)})").each do |col|
+        col_name = col[:name].to_sym
+        columns << col_name
+        types[col_name] = col[:type]
+        # PRAGMA table_info returns :notnull as 1 (NOT NULL) / 0 (nullable).
+        # Invert into :nullable so the meaning matches the variable name.
+        nullable[col_name] = col[:notnull] == 0
+        # :dflt_value is the SQL literal for the default (String), or NULL
+        # for no default. We keep the raw string so callers can re-emit it.
+        defaults[col_name] = col[:dflt_value]
+        # SQLite quirk: PRIMARY KEY columns return notnull=0 even though
+        # they're implicitly NOT NULL. Mark them required explicitly so
+        # validators don't have to know the SQLite PRAGMA shape.
+        # 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
+      end
+
+      {
+        columns: columns,
+        types: types,
+        nullable: nullable,
+        defaults: defaults,
+        required: required,
+        primary_key: primary_key
+      }
+    end
+
+    def parse_foreign_keys(table_name)
+      rows = @db.query("PRAGMA foreign_key_list(#{Diamond.quote_ident(table_name)})")
+      rows.map do |row|
+        {
+          local: row[:from].to_sym,
+          ref_table: row[:table].to_sym,
+          ref_col: row[:to].to_sym
+        }
+      end
+    end
+  end
+end

data/lib/diamond/json_string.rb

@@ -0,0 +1,13 @@
+require 'json'
+
+module Diamond
+  # Pre-encoded JSON response body. Returned by QueryObject#to_json_array
+  # so Rutile's Response.format can pass it straight to the Rack body
+  # with zero further processing — no re-parse, no re-encode, no Hash
+  # allocation. A String subclass so the body array carries it as-is;
+  # Rutile matches it with an explicit first branch (behind a defined?
+  # guard, so Rutile stays loadable without Diamond) before its generic
+  # String → text/html branch.
+  class JsonString < String
+  end
+end

data/lib/diamond/null_table.rb

@@ -0,0 +1,10 @@
+module Diamond
+  class NullTable
+    attr_reader :name, :schema
+
+    def initialize(name = nil)
+      @name = name
+      @schema = { columns: [], types: {}, primary_key: nil }
+    end
+  end
+end

data/lib/diamond/operator.rb

@@ -0,0 +1,31 @@
+module Diamond
+  # Operator contract — modules under lib/diamond/operators/ implement this.
+  #
+  # Three registries consult operators at dispatch time:
+  #
+  #   Parser::WhereOperators  — Prism node -> AST::Node (where blocks)
+  #   Parser::DeriveOperators — Prism node -> AST::Node (derive blocks)
+  #   Compiler::Operators     — AST::Node  -> SQL fragment (SQL rendering)
+  #
+  # Built-in operators are the fallthrough (implicit priority 0). External
+  # operators run first, sorted by descending priority; first non-nil result
+  # wins. AST::Column and AST::Literal are primitives, not operators — the
+  # foundation stays stable across extensions.
+  #
+  # Canonical implementation: lib/diamond/operators/like.rb.
+  module Operator
+    # An operator module exposes:
+    #
+    #   PRIORITY            - Integer. Higher runs first. Built-ins are 0.
+    #   priority            - class method returning PRIORITY
+    #   parse_where(node, schema)  -> AST::Node | nil
+    #   parse_derive(node, schema) -> AST::Node | nil
+    #   handles?(node) -> Bool
+    #   render(node, params) -> String  (mutates params)
+    #
+    # Register by calling:
+    #   Parser::WhereOperators.register(MyOp)
+    #   Parser::DeriveOperators.register(MyOp)  # optional
+    #   Compiler::Operators.register(MyOp)
+  end
+end