rubydb 0.1.3 → 0.1.5

data/docs/operations/production-runbook.md

@@ -1,45 +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.
+# 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

@@ -1,33 +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.
+# 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

@@ -1,6 +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.
+## 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

@@ -1,34 +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.
+# 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

@@ -1,14 +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.
+# 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

@@ -1,17 +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.
+# 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

@@ -1,118 +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.
+# 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.