rubydb 0.1.0

data/docs/operations/monitoring.md

@@ -0,0 +1,25 @@
+# Monitoring and alerting
+
+Expose the RubyDB health and Prometheus endpoints through the deployment’s
+authenticated monitoring path. Use liveness to decide whether a process
+exists; use readiness to decide whether it is safe to route traffic.
+
+At minimum, collect:
+
+- request count, error count, latency, and active connections;
+- WAL bytes/segments, checkpoint failures, flush failures, and recovery-required
+  commit acknowledgements;
+- table/index counts, row counts, storage bytes, and vacuum/compaction duration;
+- replication role, state, received/replayed LSN, lag, authentication failures,
+  and fencing epoch;
+- process memory, CPU, open files, and filesystem free space.
+
+Alert on readiness failure, repeated request errors, checkpoint or WAL flush
+failures, any recovery-required acknowledgement, filesystem space below the
+service threshold, replication lag beyond the application RPO, authentication
+failures, and a fencing epoch change.
+
+Dashboards must show rates and percentiles over time, not only current gauges.
+Set thresholds from staging workload measurements and review them after every
+capacity or schema change. A green liveness check alone is not evidence that
+the database can accept traffic.

data/docs/operations/production-guide.md

@@ -0,0 +1,295 @@
+# RubyDB production operations guide
+
+This guide describes a controlled production deployment for applications that
+fit RubyDB’s documented feature surface. It is an operational companion to
+the [production runbook](production-runbook.md), [disaster recovery guide](disaster-recovery.md),
+and [monitoring guide](monitoring.md). It does not turn the current project
+into a universal PostgreSQL, MySQL, or SQLite replacement.
+
+## Deployment decision
+
+Choose embedded mode only when one process owns the database directory and the
+application accepts process-local availability. Use server mode when web,
+worker, migration, or administrative processes need concurrent access. Put
+the database directory on storage with documented durability and rename/
+flush semantics. Do not place it on an untested shared filesystem.
+
+Before launch, validate the application’s schema, generated SQL, migrations,
+backup/restore path, concurrency profile, and failure behavior against the
+exact RubyDB version and configuration that will be deployed.
+
+## Reference topology
+
+```text
+clients/web/workers -> TLS -> RubyDB server -> private database volume
+                                      |-> WAL/checkpoints
+                                      |-> verified backup destination
+                                      |-> metrics/log sink
+optional replica --------------------^
+```
+
+A replica is not a backup. A backup is not a fencing system. An application
+load balancer health check is not proof that a primary is safe to write. Keep
+these responsibilities separate.
+
+## Complete first deployment
+
+The following is a reference deployment for a Rails or regular Ruby
+application. Replace paths, hostnames, users, and limits with values approved
+by your infrastructure team.
+
+### 1. Install and provision the server
+
+Pin the RubyDB gem version on the database host. Do not use an unpinned
+prerelease in a production deployment:
+
+```sh
+gem install rubydb -v 0.1.0
+useradd --system --home-dir /var/lib/rubydb --shell /usr/sbin/nologin rubydb
+install -d -o rubydb -g rubydb -m 0700 /var/lib/rubydb/data
+install -d -o rubydb -g rubydb -m 0750 /var/log/rubydb
+install -d -o root -g rubydb -m 0750 /etc/rubydb
+```
+
+Use a persistent local volume for `/var/lib/rubydb/data`. Keep backups on a
+separate failure domain. The server account should not own application source,
+certificate private keys, or unrelated host data.
+
+### 2. Configure the server
+
+Start from the repository’s `config/production.yml` and place a reviewed copy
+at `/etc/rubydb/production.yml`. Supply required secrets through the service
+manager or secret store. At minimum, configure:
+
+```text
+RUBYDB_HOST=0.0.0.0
+RUBYDB_PORT=7432
+RUBYDB_DATA_DIR=/var/lib/rubydb/data
+RUBYDB_LOG_DIR=/var/log/rubydb
+RUBYDB_USERNAME=app_rw
+RUBYDB_PASSWORD=<secret-manager-value>
+RUBYDB_SSL_ENABLED=true
+RUBYDB_SSL_CERT_FILE=/etc/rubydb/tls/server.crt
+RUBYDB_SSL_KEY_FILE=/etc/rubydb/tls/server.key
+RUBYDB_SSL_CA_FILE=/etc/rubydb/tls/ca.crt
+RUBYDB_SSL_VERIFY_PEER=true
+```
+
+The server’s TLS private key and application password must be readable only by
+the service or secret-management mechanism. Restrict port `7432` to the Rails
+and worker network; do not expose it to the public internet.
+
+### 3. Start and verify the server
+
+Run it under systemd, a supervised container, or an equivalent process
+manager. The CLI configuration options must appear before the command:
+
+```sh
+sudo -u rubydb env RUBYDB_USERNAME=app_rw RUBYDB_PASSWORD='from-secret-store' \
+  rubydb --config /etc/rubydb/production.yml --env production start
+```
+
+In a systemd unit, use an `EnvironmentFile` protected with mode `0600` or a
+native secret integration, then use:
+
+```ini
+ExecStart=/usr/local/bin/rubydb --config /etc/rubydb/production.yml --env production start
+Restart=on-failure
+```
+
+Verify from the application network, not only from the database host:
+
+```sh
+rubydb --config /etc/rubydb/production.yml --env production status --json
+rubydb --config /etc/rubydb/production.yml --env production doctor --json
+```
+
+Then run an authenticated TLS smoke query using the Ruby client and the same
+URL the application will use:
+
+```sh
+RUBYDB_URL='rubydbs://app_rw:URL_ENCODED_PASSWORD@db.example.com:7432/app?verify_peer=true&ca_file=%2Fetc%2Frubydb%2Ftls%2Fca.crt' \
+  ruby -rrubydb -e 'c=RubyDB::Client::Client.new(url: ENV.fetch("RUBYDB_URL")); p c.query("SELECT 1").to_hash; c.disconnect'
+```
+
+### 4. Configure a Rails application
+
+In the Rails application’s `config/database.yml`, select server mode and read
+the connection string from the deployment environment:
+
+```yaml
+production:
+  adapter: rubydb
+  embedded: false
+  url: <%= ENV.fetch("RUBYDB_URL") %>
+  pool: <%= ENV.fetch("RAILS_MAX_THREADS", "5") %>
+```
+
+Set `RUBYDB_URL` through the platform secret store:
+
+```text
+RUBYDB_URL=rubydbs://app_rw:URL_ENCODED_PASSWORD@db.example.com:7432/app?verify_peer=true&ca_file=%2Fetc%2Frubydb%2Ftls%2Fca.crt
+```
+
+Deploy the Rails application, then run the migration once using a controlled
+release job, not concurrently from every web process:
+
+```sh
+RAILS_ENV=production bundle exec rails db:migrate
+RAILS_ENV=production bundle exec rails runner 'puts User.count'
+```
+
+The web and job processes connect to the server endpoint. They never mount or
+open `/var/lib/rubydb/data`.
+
+### 5. Configure a regular Ruby application
+
+The regular client uses the same environment value:
+
+```ruby
+require "rubydb"
+
+client = RubyDB::Client::Client.new(url: ENV.fetch("RUBYDB_URL"))
+begin
+  client.query("SELECT 1")
+  client.query("INSERT INTO audit_events (event_name) VALUES (?)", ["boot"])
+ensure
+  client.disconnect
+end
+```
+
+Use application-level idempotency for retried writes. A network timeout does
+not by itself prove that a commit was rolled back.
+
+### 6. Accept traffic gradually
+
+Run a read/write smoke test, migration status check, backup, and representative
+workload before routing all traffic. Watch p95/p99 latency, errors, lock waits,
+active connections, WAL growth, checkpoint age, disk space, and memory during a
+canary period. Keep the previous application version and verified database
+backup available until the rollback window closes.
+
+The Rails URL example and URL option reference are also maintained in [Rails
+database configuration](../rails/database-yml.md).
+
+## Configuration and service identity
+
+Run the server as a dedicated least-privilege account. Give it access only to
+the database, WAL, temporary, certificate, and backup paths it needs. Store
+passwords, peer tokens, private keys, and API credentials in a secret manager.
+Do not put secrets in YAML committed to the repository, process arguments, or
+logs.
+
+Pin the RubyDB version and configuration for each deployment. Review changes to
+durability mode, WAL retention, checkpoint thresholds, memory, connection
+limits, request deadlines, lock timeouts, and TLS/authentication as production
+changes. Keep a configuration checksum in the deployment record.
+
+## Readiness checklist
+
+Before accepting traffic:
+
+* database directory is on approved storage with sufficient space and inodes;
+* service account and file permissions are verified;
+* TLS certificate, key, CA, hostname, and expiration are checked;
+* authentication and authorization deny an unauthenticated test client;
+* health and readiness checks exercise a real request path;
+* connection, request, lock, and shutdown timeouts are bounded;
+* schema/migrations have completed and version/checksum is recorded;
+* full backup has been created and restored into a fresh directory;
+* monitoring, alert routing, and log retention are active;
+* rollback and restore owners are named; and
+* a representative smoke query and write have passed.
+
+## Capacity and resource limits
+
+Set explicit limits for connections, request duration, lock waits, result size,
+memory, worker count, WAL size, backup space, and file descriptors. Size the
+application pool below the server limit, leaving room for migrations,
+replication, health checks, and administration. A pool that equals the server
+limit can starve the control plane.
+
+Alert before exhaustion, not after it. Watch CPU, RSS, open files, disk bytes,
+free inodes, WAL bytes, checkpoint age/duration, active transactions, lock
+waits, pool utilization, errors, cancellations, and p95/p99 latency.
+
+## Backup policy
+
+Define RPO and RTO with the application owner. At minimum, maintain verified
+full backups, protect them from the database host, encrypt them at rest and in
+transit, retain multiple generations, and record manifests/checksums. If using
+incremental or differential backups, retain their verified base and ordered
+chain.
+
+A successful backup command is not proof of recoverability. Regularly restore
+to an isolated directory, validate checksums and schema, run representative
+queries, compare critical row counts, and record elapsed restore time. Run a
+restore drill after format, backup, storage, or release changes.
+
+## Upgrade procedure
+
+1. Read the release notes, format compatibility, and migration notes.
+2. Create and verify a new full backup.
+3. Test the new version against a restored production-like copy.
+4. Run schema and application smoke tests, including populated-table writes.
+5. Drain or fence writes according to the deployment topology.
+6. Upgrade one controlled instance and verify health, WAL, and metrics.
+7. Re-enable traffic gradually and watch errors and latency.
+8. Keep the rollback binary and backup available until the validation window
+   closes.
+
+Never roll back by pointing an older binary at a directory whose format or
+metadata it cannot read. Use the documented restore/rollback path.
+
+## Failover procedure
+
+RubyDB’s safe failover model requires a synchronized candidate and a durable
+fencing decision. A manual operator sequence is:
+
+1. declare the incident and stop or isolate application writes;
+2. verify the primary’s last acknowledged LSN and fence epoch;
+3. confirm the candidate’s applied LSN and integrity;
+4. fence the old primary at the process, host, storage, or network layer;
+5. promote only after fencing is observable and durable;
+6. point clients at the new primary and run smoke writes/reads;
+7. monitor replication and stale-writer rejection; and
+8. recover the old primary as a replica only after its state is understood.
+
+Automatic election requires an independently validated quorum, fencing,
+partition behavior, stale-primary rejection, and recovery procedure. Do not
+enable election based solely on a successful same-host test.
+
+## Incident response
+
+Contain first: stop unsafe writes, protect the database directory, and record
+the timeline. Preserve logs, metrics, WAL, metadata, configuration, process
+state, and backup manifests. Use [troubleshooting](../troubleshooting.md) and
+[debugging](../debugging.md) for evidence collection.
+
+Classify the event as availability, durability, correctness, security, or
+capacity. Assign an incident owner and a recovery owner. Communicate whether
+commit outcomes are known, unknown, or confirmed rolled back. After recovery,
+verify application invariants rather than relying only on process health.
+
+## TLS and secret rotation
+
+Stage new certificates and CA material, validate the chain and hostname with a
+test client, then switch through an atomic deployment/configuration change.
+Maintain an overlap window only if clients support it. Confirm old material is
+no longer accepted before revoking it. Rotate database passwords and peer
+tokens through the secret manager; audit access and avoid printing values.
+
+## Maintenance
+
+Schedule vacuum, compaction, checkpoint, index maintenance, and backups with
+awareness of active readers and write load. Measure before and after. Use a
+copy for repair or compaction experiments. Verify reopen, checksums, row counts,
+indexes, and application smoke queries after maintenance.
+
+## Production evidence
+
+The release record should contain the RubyDB commit, Ruby/Rails versions,
+configuration checksum, schema/migration version, backup manifest, restore
+drill result, benchmark/soak result, monitoring link, security review status,
+and known limitations. See [production readiness](../production-readiness.md)
+for the project-level boundaries.

data/docs/operations/production-runbook.md

@@ -0,0 +1,45 @@
+# RubyDB production runbook
+
+## Before deployment
+
+1. Pin the RubyDB commit and Ruby version. Run `bundle exec rspec`, the
+   production soak, the durability drill, and the network failover drill.
+2. Place the database, WAL, lock file, replication state, and backups on
+   protected storage owned by the service account. Keep backups on a separate
+   failure domain.
+3. Enable TLS, use a private bind address, configure authentication and a
+   replication token from a secret manager, and set connection, frame, query,
+   worker, and disk-space limits.
+4. Install the alert rules in
+   `config/monitoring/prometheus-alerts.yml`. Test readiness, metrics, backup,
+   and restore from the deployment environment.
+
+## Backup and restore
+
+Run a full backup before upgrades and retain the matching WAL chain and
+manifest. Restore into a new inactive directory, run the restore drill, reopen
+the database, compare row counts/checksums, and only then switch traffic.
+Never overwrite the only copy during a restore.
+
+## Failover
+
+Stop writes, confirm the replica is synchronized, fence the old primary using
+the shared durable fence path, promote exactly one replica, and verify client
+writes and replication status. Automatic election is not enabled until the
+deployment provides an independently tested fencing lease. A network partition
+must never result in two writable primaries.
+
+## TLS and secret rotation
+
+Stage a new certificate/key and replication token in the secret manager,
+validate them on an inactive instance, restart or drain one peer at a time,
+verify TLS and replication authentication, then revoke the old credentials
+after the overlap window. Do not place secrets in repository files, command
+arguments, URLs, or logs.
+
+## Upgrade and incident response
+
+Run the upgrade-compatibility suite against a copy of production backups.
+Preserve the database, WAL, replication state, logs, metrics, and timestamps
+before repair, vacuum, restore, or promotion. If checksums, fencing, or
+replication diverge, stop writes and escalate; do not guess at a repair.

data/docs/operations/replication.md

@@ -0,0 +1,33 @@
+# Replication operations
+
+RubyDB replication is logical WAL row-mutation replication. Configure the
+primary and replica with separate data directories, explicit network addresses,
+and the same high-entropy `replication_auth_token`. Restrict the listener with
+firewall rules and use TLS or a trusted private network; the token is peer
+authentication, not a replacement for transport encryption.
+
+## Bootstrap and catch-up
+
+Start the primary first, then start the replica with its replica identifier and
+primary address. The primary sends catalog schema before row replay. Verify the
+replica reaches `SYNCED`, and compare received and replayed LSNs before routing
+reads to it.
+
+Monitor replication status continuously. A replica with a received/replayed
+gap is not eligible for promotion. Preserve the replication log and replica
+state files during an incident; do not manually edit LSN state.
+
+## Token rotation
+
+Drain replication, stop or disconnect the replica, update the protected token
+on both sides, restart the primary listener if required, and reconnect the
+replica. Confirm accepted handshakes and zero unexpected authentication
+failures before returning the replica to service. Never place tokens in source
+control or command histories.
+
+## Failure handling
+
+On a network partition, assume the old primary may still be reachable until it
+is fenced. Do not promote a lagging replica and do not run two writable primaries
+without a verified fencing lease. Re-bootstrap a divergent replica rather than
+guessing which WAL records are safe to apply.

data/docs/operations/restore.md

@@ -0,0 +1,6 @@
+## Restore verification
+
+Before treating a backup as recoverable, run the verification path that extracts
+it into an isolated temporary directory, opens the database with RubyDB, and
+compares the restored catalog and table row counts with the manifest. The
+verification removes its temporary database after the check.

data/docs/operations/runbook.md

@@ -0,0 +1,34 @@
+# RubyDB operator runbook
+
+## Start and health check
+
+Run the server with an explicit production configuration:
+
+```sh
+RUBYDB_ENV=production rubydb -c config/production.yml start
+```
+
+Confirm the process is listening, then run `rubydb status --json`. Treat a missing PID file, an invalid configuration, or a failed health check as a failed deployment; do not bypass startup validation.
+
+## Backup and restore
+
+Create a verified full backup before upgrades or maintenance. Retain the manifest and WAL chain together. Test restoration into a separate directory before replacing a live data directory. Never restore over an active database.
+
+## Upgrade and rollback
+
+Stop writes, create and verify a full backup, restore it into a staging directory, and run migration status plus application smoke queries. Promote the staged directory only after validation. Roll back by stopping RubyDB and switching back to the retained pre-upgrade directory; preserve the failed directory for diagnosis.
+
+## Incident boundaries
+
+On corruption, checksum failure, repeated crash recovery, or replication divergence, stop writes and preserve the data directory and logs. Do not delete WAL, run vacuum, or force promotion until a verified backup and incident copy exist. Automatic failover is intentionally disabled and promotion requires an operator decision.
+
+## Security operations
+
+Keep production credentials and TLS private keys outside the repository with restrictive permissions. Rotate certificates by staging the replacement, validating the chain, and restarting during a planned window. Keep TLS enabled and use peer verification when a trusted CA is available.
+
+For replication, configure the same high-entropy `replication_auth_token` on
+each primary and replica. A peer with a missing or incorrect token is rejected;
+rotate the token by draining replicas, updating the protected configuration on
+both sides, and reconnecting them. The replication listener is not a substitute
+for a private network or TLS termination, so restrict its port at the firewall
+and validate certificate/private-network controls during deployment.

data/docs/operations/upgrades.md

@@ -0,0 +1,14 @@
+# Upgrades
+
+RubyDB upgrades must be treated as storage migrations, not as an in-place binary replacement.
+
+Before upgrading:
+
+1. Stop writes and confirm the server is healthy.
+2. Create and verify a full backup, including WAL when available.
+3. Record the RubyDB version, storage page size, and backup manifest checksum.
+4. Test the new release against a restored copy of the backup.
+
+The current storage format is version 1. RubyDB refuses to open an unknown page format or a database whose page size differs from the configured page size. There is no automatic on-disk format conversion yet; a future incompatible format must provide an explicit export/import migration.
+
+After upgrading, reopen the restored or migrated database, run the migration status command, verify application queries, and retain the pre-upgrade backup until the rollback window closes. Never delete the original data directory as part of an upgrade.

data/docs/operations/workload-testing.md

@@ -0,0 +1,17 @@
+# Workload testing
+
+Run the deterministic concurrent workload from the repository root:
+
+```sh
+RUBYDB_WORKLOAD_THREADS=4 RUBYDB_WORKLOAD_OPERATIONS=250 ruby benchmarks/concurrent_workload.rb
+```
+
+It performs concurrent inserts against one engine, verifies the final row count, closes the database, reopens it, and verifies durable reads. It prints one JSON result and exits non-zero on any operation or durability failure.
+
+Use a temporary database by default. To retain an artifact for inspection, provide an explicit path:
+
+```sh
+RUBYDB_WORKLOAD_PATH=/var/lib/rubydb/workload.rdb RUBYDB_WORKLOAD_THREADS=16 RUBYDB_WORKLOAD_OPERATIONS=10000 ruby benchmarks/concurrent_workload.rb
+```
+
+Run this in a staging environment on the target filesystem before deployment. Establish acceptable latency, throughput, WAL growth, disk-space, recovery-time, and backup/restore targets for the expected workload; do not treat a successful smoke workload as capacity certification.

data/docs/production-readiness.md

@@ -0,0 +1,118 @@
+# Production-readiness audit
+
+## Status
+
+RubyDB has verified production-oriented foundations, but it is not yet a general-purpose production database. Supported behavior is backed by the RSpec suite in `spec/`.
+
+Latest local audit: 270 examples, 0 failures. Hosted CI and deployment-specific
+evidence remain separate release gates.
+
+The feature inventory below was written during an earlier checkpoint and its
+parenthetical historical count is not the current total. Use the latest audit
+line above and rerun the suite for release evidence.
+
+## Implemented features
+
+The repository contains substantial scaffolding for:
+
+- page-based storage
+- buffer pool caching
+- file and page management
+- WAL, recovery, and checkpoint modules
+- transactions and MVCC abstractions
+- SQL parser/planner infrastructure
+- server, protocol, and connection components
+- authentication and authorization modules
+- backup and replication APIs
+- monitoring and metrics interfaces
+- Rails integration adapters
+- ordered, locked migrations with durable version/checksum tracking
+
+## Tested features
+
+The current suite verifies storage reopen, subprocess crash recovery, MVCC isolation/vacuum, durable visibility version-history traversal, constraints including ON DELETE/ON UPDATE referential actions and nullable values, indexes including deep B-tree splits, SQL execution including idempotent database/table/index DDL and SQL foreign-key actions, schema DDL, views, trigger DDL and dispatch, CREATE TABLE, ALTER TABLE column and constraint changes, transaction before-image rollback and SQL savepoints, and VACUUM, live TCP sessions, TLS transport, password/SCRAM authentication and authorization, metrics updates including Prometheus export, liveness/readiness health reporting through the server request router, live CLI doctor checks with safe repair behavior, truthful CLI status reporting, live CLI branch diff/merge/checkout operations, live CLI inspection values, live CLI snapshot creation/listing and vacuum reporting, live CLI backup creation and restore dry-run validation, live CLI database creation and deletion, the documented SQL compatibility contract, full/snapshot/incremental/differential backup validation, logical replication, durable replica state, guarded failover promotion, durable fencing epochs, replication peer-token authentication, recovery resource checks, migration/schema-diff behavior including executable migration SQL serialization and changed-migration detection, atomic branch checkout, branch state/diff/merge behavior, foreign-key integrity lookup behavior, compound/null/boolean check-constraint evaluation, lock conflict/wait/timeout behavior, complete standalone and transaction-manager deadlock cycle detection with victim rollback, concurrency mutex initialization, Rails schema-builder SQL generation including defaults and foreign-key conventions, engine block-based table creation, adapter schema dumps preserving primary keys and defaults, ActiveRecord hash-form ordering and populated-table migration round trips, bounded multi-process workload supervision with child reaping, combined production traffic/deadline/cancellation/capacity/deadlock soak validation, release configuration, release tag/changelog preflight, upgrade guards, benchmark execution, executor query deadlines, wire-level cancellation of in-flight requests, standalone SCRAM verification, actual WAL checkpoint sizing, typed deserialization-corruption detection, preservation of stored false values when defaults are present, filesystem fault injection with descriptor cleanup, compaction/reopen validation, process-level replication failover with stale-writer fencing, and live TCP network-partition catch-up and promotion (268 examples, 0 failures at the latest audit).
+
+## Known limitations
+
+- The concurrent workload and regression suite verify parallel appends, point
+  reads, scans, durable reopen reads, multi-process server clients, and a
+  process-level replication failover drill. This does not certify universal
+  capacity; embedded ownership remains exclusive and multi-process clients must
+  use the server.
+
+- multi-row SQL `VALUES` inserts execute through the parser, binder, planner,
+  and executor, including per-row conflict handling and Rails insert IDs
+- incremental backups capture WAL mutations after a verified base LSN; differential backups capture the verified base-relative WAL delta and restore through the same validated delta path
+- replication is limited to the explicit logical row-mutation envelope API;
+  process replacement, live TCP partition/catch-up, and same-host fencing are
+  tested, while true multi-host partitions and split-brain recovery remain
+  deployment work
+- automatic failover is limited to synchronized candidates; fencing requires a shared durable fence path and still needs multi-host split-brain validation
+- the SQLite compatibility profile covers the documented common application
+  surface, but it is not SQLite file-format or extension compatibility
+- production CA lifecycle, independent security review, performance targets,
+  and large-scale workload behavior still require dedicated validation
+- branch state application and live target-branch merges are supported through the engine reconciliation hook
+
+## Unsupported SQL
+
+The supported dialect is defined in [docs/sql/compatibility.md](sql/compatibility.md) and enforced by parser/execution integration coverage. RubyDB provides a tested common SQLite-style profile, not complete SQLite file-format, extension, pragma, or error compatibility.
+
+## Durability guarantees
+
+WAL framing, reopen behavior, subprocess crash-recovery scenarios, actual checkpoint sizing, fail-closed visibility-map loading, filesystem fault injection, compaction/reopen behavior, networked replication failover, and verified restore drills are tested. This is not a substitute for real quota, power-loss, and filesystem-specific validation.
+
+## Transaction guarantees
+
+Transaction commit/rollback, MVCC visibility, snapshot isolation behavior, and vacuum safe-point handling are covered by focused tests. High-contention workload validation remains outstanding.
+
+## Isolation guarantees
+
+Read committed, repeatable read, and serializable conflict behavior are covered by focused tests; broader workload and distributed-isolation validation remains outstanding.
+
+## Backup guarantees
+
+Full compressed backups restore into a fresh directory and checksum tampering is detected. Incremental and differential backups validate the base, checksum the change set, and apply WAL row mutations during restore. Production-scale backup-chain and filesystem fault-injection testing remains outstanding.
+
+## Replication guarantees
+
+Logical row-mutation streaming, LSN deduplication, acknowledgments, acknowledged-LSN reporting, synchronized-candidate promotion verification, process replacement, live TCP partition/catch-up, and stale-primary rejection through durable fencing epochs are tested. Multi-host fencing and split-brain recovery still require dedicated validation.
+
+## TLS guarantees
+
+TLS 1.2 or newer is enforced when enabled. Certificate/key parsing, CA-file validation, TLS client connections, and the end-to-end SSL transport path are tested. Mutual TLS is configurable through client certificates; certificate rotation and production CA lifecycle procedures remain operational work.
+
+## Security model
+
+Password and SCRAM-SHA-256 authentication, server-signature verification, read/write authorization, and startup validation of incomplete auth configuration are tested through the server/session path.
+
+## Performance characteristics
+
+The repository includes a deterministic storage benchmark (`RUBYDB_BENCHMARK_ITERATIONS=100 ruby -Ilib benchmarks/basic_workload.rb`) and a concurrent write/durability workload (`ruby benchmarks/concurrent_workload.rb`). Both emit machine-readable JSON. Production-scale throughput, WAL, checkpoint, and concurrency targets still require workload-specific baselines.
+
+## Deployment requirements
+
+The project currently needs:
+
+- a validated Ruby support matrix
+- RubyGems publication credentials (`RUBYGEMS_API_KEY`) configured as a protected
+  GitHub Actions secret before pushing a release tag
+- a documented operator runbook for backups, upgrades, rollback, and incident preservation
+- explicit durability and crash-recovery validation
+- secure-by-default configuration development
+- a narrower set of supported features documented honestly
+
+## Remaining roadmap items
+
+Main remaining work is to complete the sequence laid out in the repository design:
+
+1. production CA lifecycle and certificate rotation
+2. broader SQL compatibility contract and workload benchmarks
+3. production-grade failover fencing and broader SQL compatibility
+4. operator runbooks and deployment validation
+
+## Bottom line
+
+RubyDB has a validated production-oriented foundation, but it does not yet meet
+the bar for unrestricted production use with real data outside its documented
+feature set and deployment-specific validation.