rubydb 0.1.0

data/adapters/activerecord/rubydb-activerecord.gemspec

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+Gem::Specification.new do |spec|
+  spec.name = "rubydb-activerecord"
+  spec.version = "0.1.0"
+  spec.authors = ["Aldane Hutchinson"]
+  spec.email = ["aldanehutchinson5@gmail.com"]
+
+  spec.summary = "ActiveRecord adapter for RubyDB"
+  spec.description = "ActiveRecord adapter for the RubyDB database"
+  spec.homepage = "https://github.com/aldanedev-create/rubydb"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.2.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+
+  spec.files = Dir.glob("lib/**/*.rb") + %w[README.md]
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "activerecord", ">= 7.1", "< 8.1"
+  spec.add_dependency "rubydb", "~> 0.1.0"
+
+  spec.add_development_dependency "rake", "~> 13.2"
+  spec.add_development_dependency "rspec", "~> 3.13"
+  spec.add_development_dependency "rubocop", "~> 1.60"
+end

data/adapters/activerecord/spec/rubydb_adapter_integration_spec.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require "tmpdir"
+
+$LOAD_PATH.unshift(File.expand_path("../../../lib", __dir__))
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+
+require "rubydb"
+require "active_record"
+require "active_record/connection_adapters/rubydb_adapter"
+
+RSpec.describe ActiveRecord::ConnectionAdapters::RubyDBAdapter do
+  def migration_version
+    "#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}"
+  end
+
+  let(:model) do
+    Class.new(ActiveRecord::Base) do
+      self.table_name = "accounts"
+    end
+  end
+
+  around do |example|
+    Dir.mktmpdir("rubydb-active-record") do |directory|
+      engine = RubyDB::Storage::Engine.new(File.join(directory, "accounts.rdb"), auto_cleanup: false, auto_vacuum: false)
+      ActiveRecord::Base.establish_connection(adapter: "rubydb", engine: engine)
+      example.run
+    ensure
+      ActiveRecord::Base.connection_pool.disconnect! if ActiveRecord::Base.connected?
+      engine&.close
+    end
+  end
+
+  it "creates and finds an ActiveRecord model through the embedded engine" do
+    connection = ActiveRecord::Base.connection
+    connection.execute("CREATE TABLE accounts (id INTEGER PRIMARY KEY, email VARCHAR(255) NOT NULL, active BOOLEAN NOT NULL)")
+
+    created = model.create!(id: 1, email: "ada@example.test", active: true)
+    loaded = model.find(created.id)
+
+    expect(loaded.attributes).to include("id" => 1, "email" => "ada@example.test", "active" => true)
+  end
+
+  it "runs a Rails migration that creates a table, adds a column, and adds an index" do
+    migration = Class.new(ActiveRecord::Migration[migration_version]) do
+      def change
+        create_table :projects do |table|
+          table.string :name, null: false
+        end
+        add_column :projects, :active, :boolean, default: true, null: false
+        add_index :projects, :name, unique: true
+      end
+    end
+
+    migration.new.migrate(:up)
+    connection = ActiveRecord::Base.connection
+
+    expect(connection.table_exists?(:projects)).to be(true)
+    expect(connection.columns(:projects).map(&:name)).to include("id", "name", "active")
+    expect(connection.indexes(:projects)).to include(an_object_having_attributes(name: "idx_projects_name", unique: true))
+    schema = connection.dump_schema
+    expect(schema).to include('t.boolean "active", default: true, null: false')
+    expect(schema).to include('add_index "projects", ["name"], unique: true')
+    expect(schema).not_to include('t.integer "id"')
+
+    migration.new.migrate(:down)
+    expect(connection.table_exists?(:projects)).to be(false)
+  end
+
+  it "executes an ActiveRecord association join with qualified filtering" do
+    stub_const("RubydbAccount", Class.new(ActiveRecord::Base) do
+      self.table_name = "accounts"
+      has_many :rubydb_projects, class_name: "RubydbProject", foreign_key: :account_id
+    end)
+    stub_const("RubydbProject", Class.new(ActiveRecord::Base) do
+      self.table_name = "projects"
+      belongs_to :rubydb_account, class_name: "RubydbAccount", foreign_key: :account_id
+    end)
+
+    connection = ActiveRecord::Base.connection
+    connection.execute("CREATE TABLE accounts (id INTEGER PRIMARY KEY, email VARCHAR(255) NOT NULL)")
+    connection.execute("CREATE TABLE projects (id INTEGER PRIMARY KEY, account_id INTEGER NOT NULL, name VARCHAR(255) NOT NULL)")
+    account = RubydbAccount.create!(id: 1, email: "ada@example.test")
+    RubydbProject.create!(id: 10, account_id: account.id, name: "RubyDB")
+
+    projects = RubydbProject.joins(:rubydb_account).where(accounts: { email: "ada@example.test" }).to_a
+
+    expect(projects.map(&:attributes)).to include(hash_including("id" => 10, "name" => "RubyDB", "account_id" => 1))
+  end
+
+  it "loads nested associations and ordered join results from populated tables" do
+    stub_const("RubydbAuthor", Class.new(ActiveRecord::Base) do
+      self.table_name = "authors"
+      has_many :rubydb_books, class_name: "RubydbBook", foreign_key: :author_id
+    end)
+    stub_const("RubydbBook", Class.new(ActiveRecord::Base) do
+      self.table_name = "books"
+      belongs_to :rubydb_author, class_name: "RubydbAuthor", foreign_key: :author_id
+      has_many :rubydb_reviews, class_name: "RubydbReview", foreign_key: :book_id
+    end)
+    stub_const("RubydbReview", Class.new(ActiveRecord::Base) do
+      self.table_name = "reviews"
+      belongs_to :rubydb_book, class_name: "RubydbBook", foreign_key: :book_id
+    end)
+
+    connection = ActiveRecord::Base.connection
+    connection.execute("CREATE TABLE authors (id INTEGER PRIMARY KEY, email VARCHAR(255) NOT NULL)")
+    connection.execute("CREATE TABLE books (id INTEGER PRIMARY KEY, author_id INTEGER NOT NULL, title VARCHAR(255) NOT NULL)")
+    connection.execute("CREATE TABLE reviews (id INTEGER PRIMARY KEY, book_id INTEGER NOT NULL, rating INTEGER NOT NULL)")
+    author = RubydbAuthor.create!(id: 1, email: "ada@example.test")
+    other = RubydbAuthor.create!(id: 2, email: "other@example.test")
+    first = RubydbBook.create!(id: 10, author_id: author.id, title: "A")
+    second = RubydbBook.create!(id: 11, author_id: author.id, title: "B")
+    RubydbBook.create!(id: 12, author_id: other.id, title: "C")
+    RubydbReview.create!(id: 20, book_id: first.id, rating: 5)
+    RubydbReview.create!(id: 21, book_id: second.id, rating: 4)
+
+    loaded = RubydbAuthor.includes(rubydb_books: :rubydb_reviews)
+                          .where(email: "ada@example.test").to_a
+    joined_titles = RubydbBook.joins(:rubydb_author)
+                              .where(rubydb_authors: { email: "ada@example.test" })
+                              .order(title: :desc).pluck(:title)
+
+    expect(loaded.first.rubydb_books.map(&:title)).to contain_exactly("A", "B")
+    expect(loaded.first.rubydb_books.flat_map { |book| book.rubydb_reviews.map(&:rating) })
+      .to contain_exactly(5, 4)
+    expect(joined_titles).to eq(["B", "A"])
+  end
+
+  it "round-trips a migration on a populated table" do
+    connection = ActiveRecord::Base.connection
+    connection.execute("CREATE TABLE accounts (id INTEGER PRIMARY KEY, email VARCHAR(255) NOT NULL)")
+    connection.execute("INSERT INTO accounts (id, email) VALUES (1, 'ada@example.test')")
+
+    migration = Class.new(ActiveRecord::Migration[migration_version]) do
+      def change
+        add_column :accounts, :status, :string, default: "new", null: false
+        add_index :accounts, :status
+      end
+    end
+
+    migration.new.migrate(:up)
+    loaded = connection.select_one("SELECT status FROM accounts WHERE id = 1")
+
+    expect(loaded["status"] || loaded[:status]).to eq("new")
+    expect(connection.indexes(:accounts)).to include(an_object_having_attributes(columns: ["status"]))
+
+    migration.new.migrate(:down)
+    expect(connection.columns(:accounts).map(&:name)).not_to include("status")
+  end
+end

data/adapters/ruby/README.md

@@ -0,0 +1,18 @@
+# RubyDB Ruby adapter
+
+The Ruby adapter is the direct Ruby API for embedded and client/server use.
+For one owning process, open an embedded engine:
+
+```ruby
+require "rubydb"
+
+engine = RubyDB::Storage::Engine.new("tmp/app.rdb")
+engine.execute("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)")
+engine.execute("INSERT INTO users (id, name) VALUES (1, 'Aldane')")
+engine.close
+```
+
+An embedded path has exclusive ownership. Multiple application processes must
+connect to a managed RubyDB server through `RubyDB::Client::Client`. Validate
+the exact RubyDB SQL subset, backup, restore, workload, and recovery procedure
+before using important data. See the root README and `docs/production-readiness.md`.

data/adapters/sequel/README.md

@@ -0,0 +1,11 @@
+# RubyDB Sequel adapter
+
+The Sequel adapter is an integration surface for applications that use Sequel.
+It should be configured with a RubyDB connection and kept within the SQL and
+schema features documented by RubyDB. Use one embedded owner or point all
+processes at a RubyDB server; never open the same embedded path independently
+from multiple workers.
+
+Before production use, run the application's Sequel schema, query, transaction,
+pool, migration, backup, restore, and failure tests. Compatibility is feature-
+specific and is not a claim of complete PostgreSQL, MySQL, or SQLite behavior.

data/bin/rubydb

@@ -0,0 +1,19 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# RubyDB CLI - Main entry point for database management commands
+
+require_relative "../lib/rubydb"
+require_relative "../lib/rubydb/cli/application"
+
+# Load the CLI application and run it
+begin
+  RubyDB::CLI::Application.start(ARGV)
+rescue Interrupt
+  puts "\nInterrupted. Exiting..."
+  exit 0
+rescue StandardError => e
+  $stderr.puts "Error: #{e.message}"
+  $stderr.puts e.backtrace if ENV["RUBYDB_DEBUG"]
+  exit 1
+end

data/bin/rubydb-server

@@ -0,0 +1,126 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# RubyDB Server - Production database server
+
+require "optparse"
+require_relative "../lib/rubydb"
+require_relative "../lib/rubydb/server"
+
+# Parse command line options
+options = {
+  host: "localhost",
+  port: 7432,
+  database: nil,
+  config: nil,
+  daemonize: false,
+  pid_file: nil,
+  log_file: nil,
+  debug: false
+}
+
+OptionParser.new do |opts|
+  opts.banner = "Usage: rubydb-server [options]"
+
+  opts.on("-h", "--host HOST", "Bind to host (default: localhost)") do |h|
+    options[:host] = h
+  end
+
+  opts.on("-p", "--port PORT", Integer, "Bind to port (default: 7432)") do |p|
+    options[:port] = p
+  end
+
+  opts.on("-d", "--database PATH", "Path to database file") do |db|
+    options[:database] = db
+  end
+
+  opts.on("-c", "--config FILE", "Configuration file path") do |config|
+    options[:config] = config
+  end
+
+  opts.on("-D", "--daemonize", "Run as daemon") do
+    options[:daemonize] = true
+  end
+
+  opts.on("--pid-file FILE", "PID file location") do |pid|
+    options[:pid_file] = pid
+  end
+
+  opts.on("--log-file FILE", "Log file location") do |log|
+    options[:log_file] = log
+  end
+
+  opts.on("--debug", "Enable debug mode") do
+    options[:debug] = true
+  end
+
+  opts.on("-v", "--version", "Print version") do
+    require_relative "../lib/rubydb/version"
+    puts "RubyDB Server v#{RubyDB::VERSION}"
+    exit 0
+  end
+
+  opts.on("-h", "--help", "Print this help") do
+    puts opts
+    exit 0
+  end
+end.parse!
+
+# Validate required options
+if options[:database].nil? && options[:config].nil?
+  $stderr.puts "Error: --database or --config is required"
+  exit 1
+end
+
+# Start the server
+begin
+  if options[:daemonize]
+    Process.daemon(true, true) if Process.respond_to?(:daemon)
+  end
+
+  # Write PID file if specified
+  if options[:pid_file]
+    File.write(options[:pid_file], Process.pid.to_s)
+  end
+
+  # Load configuration
+  config = if options[:config]
+    RubyDB::Configuration.load(options[:config])
+  else
+    RubyDB::Configuration.new do |c|
+      c.host = options[:host]
+      c.port = options[:port]
+      c.database = options[:database]
+      c.debug = options[:debug]
+    end
+  end
+
+  # Initialize and start server
+  server = RubyDB::Server.new(config)
+  
+  trap("INT") do
+    puts "\nShutting down RubyDB server..."
+    server.stop
+    exit 0
+  end
+
+  trap("TERM") do
+    puts "Terminating RubyDB server..."
+    server.stop
+    exit 0
+  end
+
+  puts "RubyDB Server v#{RubyDB::VERSION} starting..."
+  puts "Listening on #{config.host}:#{config.port}"
+  puts "Database: #{config.database}"
+  puts "Press Ctrl+C to stop"
+  
+  server.start
+
+rescue StandardError => e
+  $stderr.puts "Fatal error: #{e.message}"
+  $stderr.puts e.backtrace if options[:debug]
+  exit 1
+ensure
+  File.delete(options[:pid_file]) if options[:pid_file] && File.exist?(options[:pid_file])
+end

data/config/monitoring/prometheus-alerts.yml

@@ -0,0 +1,39 @@
+groups:
+  - name: rubydb-production
+    rules:
+      - alert: RubyDBNotReady
+        expr: rubydb_health_ready == 0
+        for: 2m
+        labels:
+          severity: critical
+        annotations:
+          summary: RubyDB is not ready to serve traffic
+          description: Readiness has been false for more than two minutes.
+      - alert: RubyDBConnectionsNearLimit
+        expr: rubydb_connections_active / rubydb_connections_max > 0.85
+        for: 10m
+        labels:
+          severity: warning
+        annotations:
+          summary: RubyDB connection capacity is nearly exhausted
+      - alert: RubyDBRequestFailures
+        expr: increase(rubydb_requests_failed_total[5m]) > 0
+        for: 5m
+        labels:
+          severity: warning
+        annotations:
+          summary: RubyDB requests are failing
+      - alert: RubyDBReplicationLag
+        expr: rubydb_replication_lag_seconds > 10
+        for: 2m
+        labels:
+          severity: critical
+        annotations:
+          summary: RubyDB replica lag exceeds the promotion threshold
+      - alert: RubyDBDiskSpaceLow
+        expr: rubydb_disk_free_ratio < 0.15
+        for: 5m
+        labels:
+          severity: critical
+        annotations:
+          summary: RubyDB storage is running low

data/config/production.yml

@@ -0,0 +1,36 @@
+server:
+  host: <%= ENV.fetch("RUBYDB_HOST", "127.0.0.1").to_json %>
+  port: <%= ENV.fetch("RUBYDB_PORT", "7432") %>
+  max_connections: <%= ENV.fetch("RUBYDB_MAX_CONNECTIONS", "100") %>
+  min_workers: <%= ENV.fetch("RUBYDB_MIN_WORKERS", "2") %>
+  max_workers: <%= ENV.fetch("RUBYDB_MAX_WORKERS", "20") %>
+  worker_queue_size: <%= ENV.fetch("RUBYDB_WORKER_QUEUE_SIZE", "1000") %>
+  read_timeout: <%= ENV.fetch("RUBYDB_READ_TIMEOUT", "30") %>
+  write_timeout: <%= ENV.fetch("RUBYDB_WRITE_TIMEOUT", "30") %>
+  idle_timeout: <%= ENV.fetch("RUBYDB_IDLE_TIMEOUT", "300") %>
+  max_request_size: <%= ENV.fetch("RUBYDB_MAX_REQUEST_SIZE", "10485760") %>
+  daemonize: false
+  pid_file: <%= ENV.fetch("RUBYDB_PID_FILE", "rubydb.pid").to_json %>
+
+storage:
+  data_dir: <%= ENV.fetch("RUBYDB_DATA_DIR", "/var/lib/rubydb/data").to_json %>
+  fsync: true
+  wal_enabled: true
+
+logging:
+  log_dir: <%= ENV.fetch("RUBYDB_LOG_DIR", "/var/log/rubydb").to_json %>
+  log_level: <%= ENV.fetch("RUBYDB_LOG_LEVEL", "info").to_json %>
+
+auth:
+  method: password
+  credentials:
+    username: <%= ENV.fetch("RUBYDB_USERNAME").to_json %>
+    password: <%= ENV.fetch("RUBYDB_PASSWORD").to_json %>
+
+ssl:
+  enabled: <%= ENV.fetch("RUBYDB_SSL_ENABLED", "true") %>
+  cert_file: <%= ENV.fetch("RUBYDB_SSL_CERT_FILE", "/etc/rubydb/tls/server.crt").to_json %>
+  key_file: <%= ENV.fetch("RUBYDB_SSL_KEY_FILE", "/etc/rubydb/tls/server.key").to_json %>
+  ca_file: <%= ENV.fetch("RUBYDB_SSL_CA_FILE", "/etc/rubydb/tls/ca.crt").to_json %>
+  verify_peer: <%= ENV.fetch("RUBYDB_SSL_VERIFY_PEER", "false") %>
+  min_version: TLS1_2

data/docs/README.md

@@ -0,0 +1,71 @@
+# RubyDB documentation index
+
+Start here:
+
+- [Developer guide](developer-guide.md)
+- [Troubleshooting](troubleshooting.md)
+- [Debugging playbook](debugging.md)
+- [Production operations guide](operations/production-guide.md)
+- [Quick start](getting-started/quickstart.md)
+- [Local development to production](getting-started/local-to-production.md)
+- [First database](getting-started/first-database.md)
+- [First query](getting-started/first-query.md)
+- [Rails installation](rails/installation.md)
+- [Rails production guidance](rails/production.md)
+- [SQLite compatibility profile](sql/sqlite-compatibility.md)
+- [SQL compatibility contract](sql/compatibility.md)
+- [SQL compatibility guide](sql/compatibility-guide.md)
+- [Rails compatibility guide](rails/compatibility-guide.md)
+- [Production validation](production_validation.md)
+- [Production-readiness audit](production-readiness.md)
+- [Production runbook](operations/production-runbook.md)
+- [CLI guide](cli.md)
+- [CLI cheat sheet](cli-cheatsheet.md)
+- [Disaster recovery](operations/disaster-recovery.md)
+- [Monitoring and alerting](operations/monitoring.md)
+- [Workload testing](operations/workload-testing.md)
+- [Release checklist](release.md)
+- [Lessons learned](lessons-learned.md)
+
+Architecture and development:
+
+- [Current-state audit](architecture/current-state.md)
+- [Production roadmap](architecture/production-roadmap.md)
+- [Architecture overview](architecture/overview.md)
+- [Storage engine](architecture/storage-engine.md)
+- [Transactions](architecture/transactions.md)
+- [MVCC](architecture/mvcc.md)
+- [WAL](architecture/wal.md)
+- [Query planner](architecture/query-planner.md)
+- [Testing guide](contributing/testing.md)
+- [Release process](contributing/release-process.md)
+- [Branching](developer/branching.md)
+
+The root [README](../README.md) is the public project overview. The current
+production claim is intentionally bounded by the tested features and the
+deployment-specific validation described above.
+
+## Documentation map
+
+Use the guides for the complete workflow and the smaller pages for focused
+reference:
+
+* `getting-started/` gets a new Ruby or Rails application running.
+* `sql/` defines syntax, types, expressions, transactions, joins, functions,
+  and compatibility boundaries.
+* `architecture/` explains storage, WAL, recovery, MVCC, indexes, planning,
+  execution, server ownership, and replication.
+* `developer/` covers local development, snapshots, branches, temporal data,
+  database diffs, and implementation workflows.
+* `rails/` covers installation, configuration, migrations, production use,
+  compatibility, and troubleshooting.
+* `server/` covers deployment, authentication, TLS, pooling, protocol, and
+  operational behavior.
+* `operations/` covers backups, restore drills, monitoring, workload tests,
+  production procedures, and incident response.
+* `contributing/` and the root policy files cover testing, release, governance,
+  support, security, and contribution requirements.
+
+If a topic page and an implementation disagree, treat executable tests and the
+documented compatibility contract as the source of truth, then open an issue
+to reconcile the documentation.

data/docs/architecture/concurrency.md

@@ -0,0 +1,14 @@
+# Concurrency architecture
+
+Threads coordinate through locks, transaction ownership, the lock manager,
+buffer-pool synchronization, and server worker/connection limits. Transactions
+have connection-scoped state in server mode; the embedded owner remains one
+process.
+
+The lock manager detects wait-for cycles and selects a victim. The transaction
+manager rolls the victim back, releases its locks, and returns a retryable
+deadlock error. Timeouts and cancellation are distinct: a timeout stops a
+request deadline, while wire cancellation actively marks an in-flight request.
+
+Validate concurrency with the production soak, multi-process workload, latency
+percentiles, deadlock checks, resource limits, and durable reopen verification.

data/docs/architecture/current-state.md

@@ -0,0 +1,125 @@
+# RubyDB current-state audit
+
+> This document is a dated architecture audit, not a statement that every
+> finding remains open. For current validation evidence, see
+> [production validation](../production_validation.md) and the latest CI runs.
+
+## Executive summary
+
+RubyDB is a broad database project with integrated storage, WAL, MVCC,
+transactions, catalog, security, server, replication, backup, Rails, and
+monitoring paths. The implementation now has substantial focused validation,
+but several deployment-level capabilities remain environment-specific or
+intentionally bounded.
+
+The primary risk is not that the code is absent; it is that multiple components exist without being integrated into a consistent, correct, durable engine. Existing code needs additional hardening before it can safely store user data.
+
+## Repository audit
+
+### Runtime and package state
+
+- Ruby runtime in the development container: Ruby 3.4.7
+- Package metadata targets Ruby >= 3.3.0; CI covers Ruby 3.3 and 3.4 on Linux,
+  macOS, and Windows.
+- The top-level library entrypoint and gem packaging are covered by
+  `require "rubydb"` and release-artifact tests.
+- The project uses Bundler and RSpec as the base test stack.
+- The repository is organized around a large `lib/rubydb` module tree and includes docs, examples, chaos, and fuzz directories.
+
+### Architectural reality
+
+The project already contains modules for:
+
+- storage engine and page manager
+- buffer pool and file management
+- WAL and recovery components
+- transactions and MVCC
+- catalog, indexes, and constraints
+- SQL parser and planner
+- server and protocol layers
+- security and authorization
+- replication, backups, and monitoring
+- Rails integration
+
+The remaining risk is uneven validation breadth: many capabilities are proven
+by focused tests, but multi-host operations, capacity limits, and complete
+external-database dialect compatibility are not yet certified.
+
+## High-risk findings
+
+### 1. Library loading (resolved)
+
+The standard Ruby consumer path is now tested:
+
+```ruby
+require "rubydb"
+```
+
+Release metadata and the local gem build verify that this loads correctly.
+
+### 2. Storage layer (partially resolved)
+
+The storage engine now has page validation, corruption detection, WAL/recovery,
+fsync paths, restart tests, subprocess crash tests, filesystem fault injection,
+and compaction/reopen coverage. Real disk-quota and power-loss validation on
+deployment filesystems remains open.
+
+### 3. Transaction and MVCC semantics (validated foundation)
+
+The transaction manager and visibility map exist, transaction rollback restores
+update/delete before-images, and read-committed, repeatable-read, serializable
+conflict, deadlock, and concurrency workload paths have regression coverage.
+Distributed isolation and deployment-specific contention limits remain open.
+
+### 4. SQL engine is a documented subset
+
+The parser, planner, and executor are covered through end-to-end tests for the
+documented RubyDB SQL subset, including joins, aggregates, CTEs, subqueries,
+set operations, upserts, and window functions. A common SQLite-style profile
+is tested for new Ruby/Rails applications; full PostgreSQL/MySQL/SQLite dialect
+and file-format compatibility remains intentionally out of scope for this
+phase.
+
+### 5. Security (validated foundation)
+
+Authentication, TLS, SCRAM, authorization, framing limits, deadlines, and
+resource-limit startup checks are tied to server/query execution and tested.
+An independent security review and production certificate/secret lifecycle
+validation remain open.
+
+### 6. Production posture is intentionally bounded
+
+The README and production documents now distinguish tested behavior from
+deployment work. RubyDB still needs environment-specific capacity, filesystem,
+multi-host failover, certificate lifecycle, and independent security validation
+before broader production claims are appropriate.
+
+## Current production posture
+
+RubyDB is best understood as:
+
+- a serious Ruby database foundation with repeatable local validation,
+- suitable for controlled workloads within the documented feature set,
+- not a drop-in general-purpose database or automatic high-availability service.
+
+The correct short-term operating posture is to treat the project as a pre-production, high-potential codebase that needs disciplined validation and narrower, correctness-first milestones.
+
+## Immediate action items
+
+1. Run the hosted Ruby/Rails/OS compatibility matrix and retain its evidence.
+2. Validate real disk quota, power-loss, and filesystem behavior on deployment targets.
+3. Validate multi-host partition, split-brain, fencing, and operator failover procedures.
+4. Complete an independent security review and certificate/secret rotation drill.
+5. Implement or intentionally reject unsupported features with explicit errors.
+6. Establish workload-specific capacity baselines and release sign-off records.
+
+The latest local audit passed 270 examples with zero failures. Hosted matrix,
+container, filesystem quota/power-loss, multi-host fencing, and independent
+security-review evidence must still be retained for a production deployment.
+
+## Conclusion
+
+RubyDB has a substantial production-oriented foundation and repeatable local
+validation. Operators must stay within the documented feature set and complete
+deployment-specific capacity, filesystem, security, and multi-host failover
+validation before entrusting critical data to it.

data/docs/architecture/execution-engine.md

@@ -0,0 +1,25 @@
+# Execution engine
+
+The execution pipeline is:
+
+`SQL text -> lexer -> parser/AST -> binder -> planner -> executor -> result`
+
+The planner selects scans, index scans, joins, filters, aggregates, sorting,
+limits, set operations, CTEs, subqueries, and window operations supported by
+the documented dialect. DML is routed through transaction-aware executors and
+the engine's durable mutation path.
+
+Unsupported syntax must produce an explicit parser or execution error. New
+operators and functions require type-checking, null behavior, transaction
+coverage, and compatibility documentation.
+
+## Execution invariants
+
+The executor must consume a bound plan, check cancellation and deadlines at
+bounded points, and return either a complete result or an error that leaves the
+transaction in a documented state. DML goes through the same transaction and
+WAL path as the Ruby API; a server response must never bypass durable commit.
+
+When diagnosing a result, compare parser output, bound parameters, selected
+plan, row visibility, and final serialization. See the [developer guide](../developer-guide.md)
+and [debugging playbook](../debugging.md).