rubydb 0.1.0

data/docs/production_validation.md

@@ -0,0 +1,150 @@
+# Production validation checkpoint
+
+This checkpoint validates the embedded RubyDB engine and ActiveRecord adapter
+against a focused, repeatable set of production-relevant paths. Passing it is
+evidence for these paths; it is not a claim of universal SQL or Rails
+compatibility.
+
+## Validated paths
+
+- ActiveRecord 7.2 embedded CRUD, Arel bind compilation, qualified columns,
+  association-generated `INNER JOIN`, and `LEFT OUTER JOIN` SQL execution.
+- Reversible Rails migrations covering `create_table`, automatic integer `id`,
+  `add_column` with a default, unique `add_index`, and their `down` operations.
+- Repeated threaded insert workloads with row-count and close/reopen durability
+  verification.
+- Four independent network clients concurrently inserting through the live
+  server, with request metrics and post-restart durable-row verification.
+- Independent concurrent client transactions are isolated by connection:
+  committed work remains visible while a sibling transaction's work is rolled
+  back.
+- Two-engine logical replication of an insert followed by explicit, manual
+  promotion of the synchronized replica. Promotion retains the replicated row
+  and starts a fenced primary listener. Replicas reject local engine mutations
+  while allowing the internal logical replay path; explicit promotion restores
+  local writes. Replication TCP input is newline-frame buffered, rejects
+  oversized incomplete frames, bootstraps a new replica's catalog before row
+  replay, and persists the replay position before ack.
+- A stopped primary closes established replication sockets; a replica detects
+  the interruption, reconnects after the listener returns, and catches up from
+  the durable replication log. A caught-up disconnected replica may be
+  explicitly promoted, while lagging or never-synchronized replicas remain
+  ineligible.
+- The process-level failover drill runs an independent primary and replica,
+  kills and replaces the primary process, uses a separate process to advance
+  the fencing epoch, verifies the stale writer is rejected, and confirms a
+  fresh primary continues the log and the replica reaches both committed rows.
+- The network partition drill routes the live replication stream through a
+  fault-injecting TCP proxy, drops and heals the stream while the primary stays
+  running, verifies replica catch-up, fences the stale primary, and promotes a
+  synchronized replica.
+- Engine transaction integration: a committed transaction containing multiple
+  row mutations is emitted as one replication envelope only after its local
+  WAL commit and flush complete.
+- Persistence safety at the engine boundary: malformed metadata and failed WAL
+  recovery abort startup, metadata publishes are fsynced before atomic rename,
+  and the maintenance worker is joined before storage closes.
+- SQL window ranking (`ROW_NUMBER`, `RANK`, `DENSE_RANK`) and partition-wide
+  aggregate windows have focused regression coverage.
+- The SQLite compatibility profile covers common schema, CRUD, transaction,
+  grouped-join, aggregate, and targeted-upsert application paths.
+
+## Run before a release
+
+```powershell
+bundle exec rspec
+
+# Short CI-style repeatability check
+bundle exec rspec spec/concurrent_soak_harness_spec.rb
+
+# Deployment-sized threaded durability soak (adjust to the target hardware)
+$env:RUBYDB_SOAK_ROUNDS = "10"
+$env:RUBYDB_SOAK_THREADS = "16"
+$env:RUBYDB_SOAK_OPERATIONS = "10000"
+$env:RUBYDB_SOAK_PAYLOAD_BYTES = "512"
+ruby benchmarks/concurrent_soak.rb
+
+# Network server/client durability and latency smoke. Increase these values on
+# target hardware and archive the JSON p50/p95/p99 result with the release.
+$env:RUBYDB_SERVER_WORKLOAD_CLIENTS = "16"
+$env:RUBYDB_SERVER_WORKLOAD_OPERATIONS = "1000"
+ruby -Ilib benchmarks/server_workload.rb
+
+# Independent client processes through the server. This validates process
+# isolation and durable rows; scale processes/operations for the deployment.
+$env:RUBYDB_SERVER_WORKLOAD_PROCESSES = "8"
+$env:RUBYDB_SERVER_WORKLOAD_OPERATIONS = "1000"
+$env:RUBYDB_SERVER_WORKLOAD_CHILD_TIMEOUT = "120"
+ruby benchmarks/multiprocess_server_workload.rb
+
+# The parent supervises and reaps every child; a timed-out worker fails the run
+# instead of leaving orphaned workload processes behind.
+
+# Combined production concurrency/resilience gate: traffic latency, deadline,
+# real wire cancellation, connection capacity rejection, and deadlock detection
+$env:RUBYDB_PRODUCTION_SOAK_CLIENTS = "16"
+$env:RUBYDB_PRODUCTION_SOAK_OPERATIONS = "2000"
+$env:RUBYDB_PRODUCTION_SOAK_CANCEL_ROWS = "250000"
+ruby benchmarks/production_soak.rb
+
+# Independent primary/replica processes, crash replacement, and stale-writer fencing
+ruby scripts/replication_failover_drill
+
+# Live TCP partition, catch-up, fencing, and promotion
+ruby scripts/replication_network_failover_drill
+
+# Real two-engine replication and promotion validation
+bundle exec rspec spec/replication_failover_integration_spec.rb
+
+# SQLite-style application compatibility profile
+bundle exec rspec spec/sqlite_compatibility_spec.rb
+
+# Durability, crash, corruption, compaction, and restore release gate
+ruby scripts/durability_drill
+```
+
+The scheduled/manual GitHub Actions workflow `.github/workflows/workload.yml`
+also runs the threaded durability, server latency, and multi-process client
+workloads and uploads their JSON results as an artifact. Treat those results as
+environment-specific evidence, not a universal capacity guarantee.
+
+Archive the JSON output from the soak run with the Ruby version, RubyDB commit,
+host resources, and elapsed time. The harness creates a fresh temporary
+database for every round and fails if any round loses durable rows.
+
+## Current boundaries
+
+- Embedded databases now require exclusive ownership by one engine. A second
+  engine or process opening the same path receives an error. Multiple application
+  processes should connect through the server. The adjacent `.lock` file is
+  intentionally retained after close; the operating system releases ownership
+  on close or process exit. Never delete it while the database is open. This
+  requires a filesystem that implements file locking correctly. Hard-linked
+  database aliases and shared custom WAL/metadata paths are unsupported.
+
+- Failed metadata publication rolls back the in-memory schema and leaves the
+  durable catalog unchanged; callers receive an error and may retry the
+  mutation. Exercise disk-full and interrupted-rename fault injection on the
+  target filesystem before release.
+
+- Join support currently covers qualified `INNER`, `LEFT [OUTER]`, `RIGHT`, and
+  `FULL [OUTER] JOIN` with `ON` predicates. Join reordering is limited to safe
+  inner-join plans; correlated subqueries, advanced set-operation ordering,
+  and broader dialect-specific SQL still require dedicated compatibility tests.
+- The ActiveRecord migration test is intentionally scoped. Complex table
+  rebuilds, `change_column`, polymorphic references, generated columns, and
+  adapter-specific schema dumps require dedicated compatibility tests before
+  relying on them.
+- The soak harness and multi-process server workload cover distinct concurrency
+  paths, but they do not provide a universal capacity certification; perform
+  environment-specific load, crash, and operational recovery testing.
+- Failover is manual and requires an operator to confirm the replica is caught
+  up and that the old primary is fenced. Automatic leader election is not
+  enabled.
+- The replica fence covers engine schema, row, branch, vacuum, and compaction
+  mutation entry points. Empty-replica catalog bootstrap, transaction-integrated
+  replication, and reconnect catch-up are covered; true multi-host partition,
+  split-brain, and automated-election validation remain deployment work.
+
+RubyDB reports unsupported features as unsupported rather than advertising CTE
+or bulk-alter capability to ActiveRecord.

data/docs/rails/active-record.md

@@ -0,0 +1,11 @@
+# ActiveRecord adapter
+
+The `rubydb-activerecord` adapter connects ActiveRecord models to RubyDB. The
+tested surface includes CRUD, quoted identifiers, binds, associations, joins,
+eager loading, nested associations, schema inspection, transactions, indexes,
+defaults, schema dumps, and populated-table migration paths.
+
+Run the adapter suite from `adapters/activerecord` for the target Rails version.
+Use server mode when multiple Rails processes share a database. The adapter is
+not a complete PostgreSQL, MySQL, or SQLite compatibility layer; validate any
+application-specific Arel, extension, callback, migration, or SQL behavior.

data/docs/rails/compatibility-guide.md

@@ -0,0 +1,90 @@
+# Rails compatibility and integration guide
+
+RubyDB’s ActiveRecord adapter is intended for applications that stay within
+the documented RubyDB SQL and schema surface. It is not a claim of complete
+Rails compatibility or complete SQLite compatibility. Validate the exact
+Rails/Ruby versions, gems, queries, migrations, and deployment topology used
+by your application.
+
+## Choose the ownership mode
+
+Embedded mode is appropriate for a single-owner development process or a
+deliberately single-process application. Rails web servers, job workers,
+console sessions, and migration commands must not independently open the same
+embedded path.
+
+For multiple processes, start one RubyDB server and configure every Rails
+process to use the client/server adapter. Size the Rails connection pool below
+the server’s connection limit and leave headroom for deploys and health
+checks.
+
+## First application
+
+Use the maintained example as a smoke harness:
+
+```sh
+cd examples/rails_app
+bundle install
+bundle exec ruby bin/rails db:migrate
+bundle exec ruby bin/rails runner 'puts User.count'
+bundle exec ruby bin/rails server -b 127.0.0.1 -p 3001
+```
+
+Set `RUBYDB_DATABASE` to choose the database path in the embedded example.
+Before production, replace the local path with the managed server configuration
+and test the same migration and query flow through the network adapter.
+
+## Supported application patterns to validate
+
+Test the application’s real use of:
+
+* model creation, updates, deletes, validations, and transactions;
+* `where`, scopes, ordering, limits, offsets, projections, and bind values;
+* inner/left/multi-table joins, aliases, grouped aggregates, and `HAVING`;
+* eager loading, nested associations, and inverse association behavior;
+* connection pools, checkout timeouts, reconnects, and shutdown;
+* savepoints, rollback, retry, and deadlock handling;
+* schema dump/load, defaults, indexes, foreign keys, and constraints; and
+* fresh and populated-table migrations with rollback plans.
+
+Generated SQL is part of the compatibility surface. Capture representative
+queries and compare results, affected rows, exceptions, and transaction state.
+
+## Migration discipline
+
+Treat migrations as deployment code. Review generated SQL, run against a fresh
+database and a realistic populated copy, measure locks and duration, and
+define the rollback/backfill plan. Do not assume that a migration that creates
+a table on an empty database is safe on a large live table.
+
+Record the migration version and checksum. A changed migration should be
+treated as a new migration or an explicit controlled repair, not silently
+accepted. Take a verified backup before destructive schema changes.
+
+## Pooling and concurrency
+
+The pool must return connections with no open transaction, savepoint, lock, or
+pending cancellation. Test pool exhaustion and a server restart while Rails
+threads are active. Set bounded checkout and request timeouts. A client
+timeout does not automatically prove that a write rolled back; use an
+idempotency key or query the outcome before retrying.
+
+Run a multi-process workload with web-like reads, writes, jobs, migrations, and
+connection churn. Track p95/p99 latency, lock waits, deadlocks, cancellations,
+pool utilization, WAL growth, and error classes.
+
+## Version matrix
+
+The repository must run its Rails compatibility suite against every supported
+combination, for example Rails 7.1, 7.2, and 8.0 with the Ruby versions declared
+by the project. A local pass on one version is not evidence for the matrix.
+Record unsupported combinations explicitly in release documentation.
+
+## Debugging adapter failures
+
+Start with [Rails troubleshooting](troubleshooting.md) and
+[Debugging RubyDB](../debugging.md). Capture sanitized generated SQL, bind
+count/order, transaction boundaries, pool state, Ruby/Rails versions, and the
+smallest model/migration that reproduces the failure. Test direct SQL to
+separate Rails query generation from engine behavior.
+

data/docs/rails/database-yml.md

@@ -0,0 +1,92 @@
+# Rails database configuration
+
+Embedded single-owner configuration:
+
+```yaml
+development:
+  adapter: rubydb
+  database: tmp/development.rdb
+  embedded: true
+```
+
+For multiple web or worker processes, use a managed RubyDB server and configure
+the host, port, credentials, timeout, pool size, TLS, and database name through
+protected deployment configuration. Do not put passwords, replication tokens,
+or private keys in `database.yml` committed to source control.
+
+Match the total Rails pool size to the server connection limit and leave headroom
+for migrations, monitoring, and replication. Test the exact configuration with
+the Rails matrix before release.
+
+## Production server/client configuration
+
+For a multi-process Rails deployment, keep the server private and put only
+non-secret connection settings in source control. This is a complete example;
+the `RUBYDB_*` values are supplied by the deployment environment or secret
+manager:
+
+```yaml
+production:
+  adapter: rubydb
+  embedded: false
+  host: <%= ENV.fetch("RUBYDB_HOST") %>
+  port: <%= ENV.fetch("RUBYDB_PORT", "7432") %>
+  database: <%= ENV.fetch("RUBYDB_DATABASE", "rubydb") %>
+  username: <%= ENV.fetch("RUBYDB_USERNAME") %>
+  password: <%= ENV.fetch("RUBYDB_PASSWORD") %>
+  timeout: <%= ENV.fetch("RUBYDB_TIMEOUT", "30") %>
+  pool: <%= ENV.fetch("RAILS_MAX_THREADS", "5") %>
+  ssl:
+    enabled: <%= ENV.fetch("RUBYDB_SSL_ENABLED", "true") == "true" %>
+    ca_file: <%= ENV.fetch("RUBYDB_SSL_CA_FILE") %>
+    verify_peer: <%= ENV.fetch("RUBYDB_SSL_VERIFY_PEER", "true") == "true" %>
+```
+
+Deploy the application with values similar to:
+
+```sh
+RUBYDB_HOST=db.internal.example
+RUBYDB_PORT=7432
+RUBYDB_DATABASE=app
+RUBYDB_USERNAME=app_rw
+RUBYDB_PASSWORD='provided-by-secret-manager'
+RUBYDB_SSL_ENABLED=true
+RUBYDB_SSL_CA_FILE=/etc/rubydb/tls/ca.crt
+RUBYDB_SSL_VERIFY_PEER=true
+```
+
+The exact variable names are application conventions; Rails reads them because
+`database.yml` maps them into adapter settings. Do not put the password in a
+committed YAML file, Docker image, URL, shell history, or log. The server must
+be configured separately with its own data directory, authentication, TLS
+certificate/key, and resource limits; see [server configuration](../server/configuration.md).
+
+## One connection URL
+
+The adapter also accepts a RubyDB-specific URL through `url`. This is useful
+when a hosting provider gives the application one connection string:
+
+```yaml
+production:
+  adapter: rubydb
+  embedded: false
+  url: <%= ENV.fetch("RUBYDB_URL") %>
+  pool: <%= ENV.fetch("RAILS_MAX_THREADS", "5") %>
+```
+
+Example URL with TLS verification:
+
+```text
+rubydbs://app_user:password@db.example.com:7432/app?verify_peer=true&ca_file=%2Fetc%2Frubydb%2Fca.crt
+```
+
+Supported schemes are `rubydb://` and `rubydbs://`; `rubydbs` enables TLS.
+The URL supports percent-encoded username/password/database values and query
+options including `ssl`, `sslmode`, `verify_peer`, `ca_file`, `cert_file`,
+`key_file`, `min_version`, `timeout`, `pool_size`, `compress`, and `format`.
+Use a secret manager to inject `RUBYDB_URL`; URLs containing passwords must not
+be committed, printed, or placed in public issue reports. This is RubyDB’s
+URL format, not a PostgreSQL wire-protocol or generic `DATABASE_URL` promise.
+
+Use the documented mapping above and run a real migration plus smoke query
+through the network path before production.

data/docs/rails/installation.md

@@ -0,0 +1,17 @@
+# Rails adapter installation
+
+From the repository adapter directory:
+
+```sh
+cd adapters/activerecord
+bundle install
+bundle exec rspec
+```
+
+Add the adapter gem to the application bundle according to the release being
+tested. Configure `adapter: rubydb` and a database path or server endpoint. Run
+`db:migrate`, schema dump/load, representative joins, eager loading, nested
+associations, and rollback tests before deployment.
+
+The CI matrix currently exercises Rails 7.1, 7.2, and 8.0 with the supported
+Ruby versions. Hosted results are the release evidence for a combination.

data/docs/rails/migrations.md

@@ -0,0 +1,17 @@
+# Rails migrations
+
+RubyDB supports the documented ActiveRecord migration surface, including table
+creation, integer primary keys, columns, defaults, indexes, constraints, and
+populated-table round trips covered by the adapter suite.
+
+Before production migration:
+
+1. verify a full backup and WAL chain;
+2. restore into a new staging directory with representative data;
+3. run the migration, schema dump/load, application queries, and rollback path;
+4. confirm the migration checksum and schema status;
+5. retain the pre-migration directory until rollback is no longer needed.
+
+RubyDB fails closed when an applied migration changes or disappears. Unsupported
+table rebuilds, generated columns, polymorphic references, and dialect-specific
+extensions require explicit validation.

data/docs/rails/production.md

@@ -0,0 +1,82 @@
+# Rails production guidance
+
+RubyDB can serve Rails applications that stay within the documented RubyDB SQL
+and ActiveRecord adapter surface. Validate the exact Rails, Ruby, operating
+system, schema, workload, and deployment topology before handling important
+data. The compatibility workflow currently exercises Rails 7.1, 7.2, and 8.0
+with Ruby 3.3; hosted workflow results are required before declaring a release
+combination supported.
+
+## Choose the topology
+
+An embedded database path has exclusive ownership. Use it only when one Rails
+process owns the database, such as a single-process development or controlled
+worker deployment. Do not point multiple independent Rails processes at the
+same embedded path.
+
+For multiple web/worker processes, run a separately managed RubyDB server and
+configure clients to use its network endpoint. Size the server connection
+limit for the Rails pool total, keep application and replication traffic on
+private networks, and enable TLS and authentication. A Rails connection pool
+does not make an embedded file safe for concurrent process ownership.
+
+## Migrations and releases
+
+Before a migration:
+
+1. Run the complete test suite and the adapter suite for the target Rails
+   version.
+2. Create and verify a full backup, including the WAL chain when applicable.
+3. Restore the backup into a separate staging directory and run the migration
+   against the restored copy with a representative populated dataset.
+4. Test schema dump/load, indexes, defaults, foreign keys, eager loading,
+   nested associations, joins, and application write/read smoke queries.
+
+Stop writes or use the deployment's migration lock. RubyDB fails closed when an
+already-applied migration changes checksum or disappears. Keep the pre-release
+backup and old data directory until the rollback window closes; do not delete
+or overwrite the live directory during rollback.
+
+## Operations
+
+Collect request rate/error rate/latency, active connections, WAL and checkpoint
+health, filesystem space, recovery-required acknowledgements, and replication
+received/replayed LSNs. Alert on readiness failure, repeated errors, failed
+flush/checkpoint, low disk space, excessive pool wait, authentication failures,
+and replication lag beyond the application RPO.
+
+Run `scripts/restore_drill`, the threaded and multi-process workloads, and
+`scripts/replication_failover_drill` on target-like staging infrastructure.
+Archive the Ruby version, RubyDB commit, Rails version, host resources, result
+JSON, and recovery time with the release record.
+
+## Current boundaries
+
+The adapter is not a complete PostgreSQL, MySQL, or SQLite compatibility layer.
+The tested common SQLite-style profile is documented in
+[`docs/sql/sqlite-compatibility.md`](../sql/sqlite-compatibility.md). Complex
+table rebuilds, generated columns, polymorphic references, adapter-specific
+schema features, and dialect-specific SQL require explicit validation before
+use. Automatic high-availability election is disabled; failover is an
+operator-controlled, fenced procedure described in
+[`docs/operations/failover.md`](../operations/failover.md).
+
+## Environment-based deployment
+
+The Rails application normally points at RubyDB through `config/database.yml`.
+For a production server, set `embedded: false` and map protected environment
+values to `host`, `port`, `database`, `username`, `password`, `timeout`, and
+the `ssl` hash. See the copy-paste example in
+[Rails database configuration](database-yml.md). The application connects to
+the RubyDB server endpoint; it does not open the server’s data directory.
+
+If the deployment platform provides one connection string, set
+`RUBYDB_URL` to the documented `rubydb://` or `rubydbs://` format and use the
+`url:` form in `database.yml`. Do not assume a PostgreSQL `DATABASE_URL` will
+work; RubyDB uses its own protocol and URL scheme.
+
+Deploy the RubyDB server separately with its own persistent volume and
+`config/production.yml`. Verify TLS hostname/CA validation, authentication,
+readiness, migration status, and a read/write smoke query from the same network
+path as the Rails application. Use a secret manager for credentials and never
+commit or print them.

data/docs/rails/troubleshooting.md

@@ -0,0 +1,18 @@
+# Rails troubleshooting
+
+## Connection or ownership errors
+
+Confirm the database path exists, the process has permission, and no second
+embedded owner is using it. Multiple Rails processes must use server mode.
+
+## Migration failures
+
+Stop writes, preserve the database and WAL, inspect migration status and
+checksums, and retry only after restoring a verified staging copy. Do not delete
+WAL or overwrite the original directory.
+
+## Query failures
+
+Capture the RubyDB version, Rails/Ruby versions, generated SQL without secrets,
+and a minimal schema/query reproduction. Check the documented SQL and adapter
+compatibility surface before changing application behavior.

data/docs/release.md

@@ -0,0 +1,59 @@
+# RubyDB release checklist
+
+The release workflow is intentionally fail-closed. A maintainer must configure
+these protected GitHub Actions secrets:
+
+- `RUBYGEMS_API_KEY`: a RubyGems API key scoped to the gem
+- `RUBYDB_GEM_SIGNING_KEY_B64`: base64-encoded private signing key
+- `RUBYDB_GEM_CERT_B64`: base64-encoded certificate chain
+
+Create the signing key and certificate outside the repository, store them in a
+secret manager, and rotate them according to the organization's key policy.
+Never commit the private key or write it to a persistent workspace.
+
+To publish, review `CHANGELOG.md`, commit the version, create a matching tag,
+and let `.github/workflows/release.yml` run the full suite, build the gem,
+verify its SHA-512 checksum, attest provenance, sign it, and publish it. A
+local artifact check is:
+
+```sh
+ruby scripts/release_check
+ruby scripts/release
+```
+
+The local command does not publish unless `RUBYDB_PUBLISH=1` and
+`GEM_HOST_API_KEY` are explicitly set. Publishing also requires the release
+version to be supplied when you are not running from a matching Git tag.
+
+On Windows PowerShell, run this from the repository root:
+
+```powershell
+$env:RUBYDB_RELEASE_VERSION = "0.1.0"
+$env:RUBYDB_PUBLISH = "1"
+$env:GEM_HOST_API_KEY = "YOUR_RUBYGEMS_API_KEY"
+ruby scripts/release
+```
+
+Instead of `GEM_HOST_API_KEY`, RubyGems can read a credentials file. With the
+RubyGems version bundled with Ruby 4 on Windows, create this file:
+`C:\Users\<your-user>\.local\share\gem\credentials`
+
+```yaml
+---
+:rubygems_api_key: YOUR_RUBYGEMS_API_KEY
+```
+
+Then omit `GEM_HOST_API_KEY`; `scripts/release` and `gem push` will use the
+file automatically. Keep the file private and never commit it.
+
+On macOS/Linux, use:
+
+```sh
+RUBYDB_RELEASE_VERSION=0.1.0 \
+RUBYDB_PUBLISH=1 \
+GEM_HOST_API_KEY="YOUR_RUBYGEMS_API_KEY" \
+ruby scripts/release
+```
+
+Never commit the API key or put it in a tracked file. Review the generated
+GitHub release notes and uploaded checksum before announcing a version.

data/docs/server/architecture.md

@@ -0,0 +1,10 @@
+# Server architecture
+
+The server owns one embedded engine and exposes client sessions over the RubyDB
+protocol. A listener accepts bounded connections, a connection pool tracks
+active sessions, and a worker pool handles requests under configured limits.
+
+Lifecycle shutdown stops acceptance, closes connections, joins workers, flushes
+the engine, and removes the PID file. Multiple application processes should
+share the server, not the embedded path. Use health/readiness and Prometheus
+metrics to decide whether to route traffic.

data/docs/server/authentication.md

@@ -0,0 +1,10 @@
+# Server authentication
+
+Configure authentication explicitly for production. Password/SCRAM-SHA-256,
+authorization, peer replication tokens, bounded frames, TLS, and server
+signature verification are covered by the security suite.
+
+Use high-entropy credentials from a secret manager. Bind to a private address,
+enable TLS 1.2 or newer, validate the CA and hostname, and rotate credentials
+through a drain/reconnect procedure. Missing or incomplete authentication
+configuration must fail startup rather than silently downgrade security.

data/docs/server/configuration.md

@@ -0,0 +1,16 @@
+# Server configuration
+
+Run with an explicit database and resource limits:
+
+```sh
+rubydb-server --host 127.0.0.1 --port 7432 --database /var/lib/rubydb/app.rdb
+```
+
+Production configuration should set host/port, data and log directories, PID
+file, max connections, worker and queue limits, request/frame size, read/write
+and idle timeouts, authentication, and TLS. Keep configuration outside source
+control when it contains secrets.
+
+Validate configuration before startup and monitor readiness, active/rejected
+connections, request errors, disk space, WAL/checkpoint state, and recovery-
+required acknowledgements.

data/docs/server/connection-pooling.md

@@ -0,0 +1,10 @@
+# Connection pooling
+
+The server limits active connections and queues work through its connection and
+worker pools. Rails/client pool totals must fit below the server limit with
+headroom for administrative and replication traffic.
+
+Set finite acquisition, read, write, idle, and query timeouts. Alert on pool
+wait, rejected connections, request failures, and saturation. Load-test pool
+behavior with the multi-process and production soak harness; a successful local
+connection does not prove capacity under application traffic.

data/docs/server/deployment.md

@@ -0,0 +1,10 @@
+# Server deployment
+
+Run RubyDB under a dedicated least-privilege service account with protected
+data, WAL, logs, TLS, and backup paths. Use the packaged systemd unit or the
+non-root Docker image, private networking, TLS, authentication, resource
+limits, health checks, and persistent storage.
+
+Before accepting traffic, run status/readiness, smoke queries, backup/restore,
+workload, and recovery checks. Keep one writable primary, fence before
+promotion, and retain the previous data directory during upgrades.

data/docs/server/protocol.md

@@ -0,0 +1,12 @@
+# RubyDB server protocol
+
+The client/server protocol uses bounded framed requests and responses with
+handshake, authentication, query, prepared statement, transaction, health, and
+metrics operations. Frames must be size-limited and malformed input must be
+rejected without taking down the server.
+
+Query deadlines and in-flight cancellation are request-scoped. Cancellation is
+cooperative and must be checked by long-running execution paths. Do not expose
+the listener publicly; use TLS/private networking and rotate credentials through
+the documented operations procedure. The normative notes are in
+`spec/wire/protocol.md` and `spec/protocol/protocol.md`.