rubydb 0.1.0

data/docs/contributing/release-process.md

@@ -0,0 +1,49 @@
+# Releasing RubyDB to RubyGems
+
+1. Update `CHANGELOG.md`, bump the semantic version, and confirm the Ruby/Rails support matrix for the release. The version must have a top-level `## <version>` changelog entry; the release preflight fails closed when it is missing.
+2. Run the complete verification suite and workload test. The release workflow independently builds and validates the gem on a version tag.
+3. Create a RubyGems API key with the minimum scope needed to push this gem. Store it as the `RUBYGEMS_API_KEY` GitHub Actions secret or in RubyGems' protected credentials file; never commit it.
+4. Create and push an annotated `v<version>` tag. The compatibility workflow
+   must pass its SimpleCov line-coverage gate, and the release workflow
+   publishes only when that tag's version matches `RubyDB::VERSION` and the
+   secret is available.
+5. To build, verify, and publish manually:
+
+```sh
+RUBYDB_PUBLISH=1 GEM_HOST_API_KEY=<RubyGems API key> ruby scripts/release
+```
+
+Without `RUBYDB_PUBLISH=1`, `ruby scripts/release` only rebuilds and verifies the gem/checksum. Manual publication must also set `RUBYDB_RELEASE_VERSION=<version>`; tagged CI obtains that identity from `GITHUB_REF_NAME`.
+
+The tag workflow also creates a signed GitHub build-provenance attestation for
+the exact gem artifact. Verify that attestation in the repository's Actions or
+Releases UI before distributing the package; the SHA-512 file remains available
+for an independent byte-for-byte check.
+
+For the tag release workflow, provision base64-encoded
+`RUBYDB_GEM_SIGNING_KEY_B64` and `RUBYDB_GEM_CERT_B64` repository secrets. The
+release job materializes them only on the ephemeral runner and passes the
+protected paths to `gem build`; it never stores them in the repository. GitHub
+release notes are generated from the tag history after publication, so review
+the generated release before announcing it.
+
+The tag workflow fails closed when the signing secrets or RubyGems publication
+key are missing. Local unsigned builds remain available through `rake build`
+and are not publication artifacts.
+
+Pull requests also run the supported Ruby 3.3/3.4 matrix on Linux, macOS, and
+Windows, plus the ActiveRecord adapter suite on Rails 7.1, 7.2, and 8.0. A scheduled bounded fuzz job runs
+the SQL parser, WAL, storage, transaction, and query-engine fuzzers. Increase
+`RUBYDB_FUZZ_ITERATIONS` locally when investigating a failure, retaining the
+reported `RUBYDB_FUZZ_SEED` for reproduction.
+
+The scheduled operations workflow runs `ruby scripts/restore_drill`, which
+creates a live backup, verifies its manifest/checksums, restores it into a
+separate directory, and reopens the restored database before succeeding.
+
+After publication, install the exact released version in a clean environment and run a smoke test:
+
+```sh
+gem install rubydb --version 0.1.0
+ruby -e "require 'rubydb'; puts RubyDB::VERSION"
+```

data/docs/contributing/testing.md

@@ -0,0 +1,16 @@
+# Testing guide
+
+The test layers are complementary:
+
+- unit specs validate isolated algorithms and invariants;
+- integration specs run the real parser, planner, executor, storage, server,
+  client, adapter, or replication path;
+- chaos/fault specs inject write, crash, corruption, and network failures;
+- workload scripts measure concurrency, latency, cancellation, capacity, and
+  durable reopen behavior;
+- CI covers supported Ruby/Rails/OS combinations, security scans, fuzzing, and
+  release preflight.
+
+Run `bundle exec rspec` for the complete local gate. Preserve the random seed
+when reproducing failures. A passing local suite does not replace hosted
+multi-host, physical-filesystem, or independent security validation.

data/docs/debugging.md

@@ -0,0 +1,229 @@
+# Debugging RubyDB
+
+This playbook is for finding defects without destroying the evidence needed
+to recover data. Use it in development and staging first. Production
+diagnostics must follow the application’s privacy, access, and change-control
+policies.
+
+## Debugging principles
+
+1. Reproduce on a copy or a new temporary directory.
+2. Identify the layer: API, session, protocol, parser, planner, executor,
+   transaction, storage, WAL, filesystem, or deployment.
+3. Reduce the input while preserving the failure.
+4. Record versions, configuration names, seed, timing, and request IDs.
+5. Add a regression test before changing behavior.
+
+A database that returns an error is often safer than one that silently repairs,
+retries, or acknowledges unknown state. Keep fail-closed behavior intact while
+diagnosing.
+
+## Reproducible diagnostic baseline
+
+```sh
+git rev-parse HEAD
+ruby -v
+bundle exec ruby -Ilib exe/rubydb --version
+bundle exec rspec --format progress
+git diff --check
+```
+
+Use a fresh directory for each reproduction. Save the command and, for random
+or concurrent tests, the seed:
+
+```sh
+RUBYDB_FUZZ_SEED=12345 RUBYDB_FUZZ_ITERATIONS=1000 ruby scripts/fuzz
+bundle exec rspec spec/path/to/failing_spec.rb:42 --format doc
+```
+
+## CLI inspection
+
+The CLI is the first diagnostic interface:
+
+```sh
+bundle exec ruby -Ilib exe/rubydb status --config config/rubydb.yml
+bundle exec ruby -Ilib exe/rubydb doctor --config config/rubydb.yml
+bundle exec ruby -Ilib exe/rubydb inspect --config config/rubydb.yml
+bundle exec ruby -Ilib exe/rubydb shell --config config/rubydb.yml
+```
+
+Use `status` for ownership, lifecycle, and health; `doctor` for non-destructive
+checks and safe repairs; and `inspect` for metadata, schema, WAL, and storage
+facts. Capture JSON output when the command supports it so an incident can be
+compared over time. Read [CLI guide](cli.md) before using maintenance commands.
+
+## Logging and safe verbosity
+
+Use the normal structured logs first. Increase verbosity only for a bounded
+reproduction. `--verbose` is useful for CLI execution, while `RUBYDB_DEBUG=1`
+enables development backtraces in command wrappers. Debug logs can contain SQL
+shapes, paths, identifiers, and timing; they must be access-controlled and
+sanitized before sharing.
+
+When adding logs, include stable fields such as request ID, transaction ID,
+connection ID, LSN, operation, duration, and outcome. Never log passwords,
+SCRAM secrets, bearer tokens, private keys, or unredacted customer values.
+
+## Layer isolation
+
+### API versus engine
+
+Run the same operation through the direct Ruby API and the server/client path.
+If only server mode fails, inspect protocol framing, authentication, session
+state, serialization, and timeout handling. If both fail, reduce to engine SQL
+and storage.
+
+### Parser versus executor
+
+First parse/bind a statement without committing data. Then execute it against a
+minimal schema. A parser failure should identify token position and expected
+construct. A binder failure should identify parameter count/type context. An
+executor failure should preserve transaction rollback and identify the table,
+index, or constraint involved.
+
+### Planner versus semantics
+
+Compare an optimized plan with a simple scan where possible. Verify row IDs,
+duplicates, `NULL`, ordering, grouping, and snapshot visibility. Optimizer
+changes require equivalence tests, not only performance numbers.
+
+### Storage versus filesystem
+
+Test the storage operation with a real temporary filesystem first. Then inject
+failures at write, flush, rename, allocation, and close boundaries. A Ruby
+exception around a filesystem call is not equivalent to a process termination
+after the filesystem accepted the write.
+
+## Transaction and deadlock diagnosis
+
+Capture transaction lifecycle events: begin, snapshot, lock wait, lock grant,
+savepoint, statement error, rollback, commit request, durable commit, and
+connection close. For a deadlock, draw a wait-for graph from transaction IDs
+and locks. Verify the selected victim’s before-images were applied and that
+all locks and snapshots were released.
+
+For a timeout or cancellation, answer three questions:
+
+1. Did the server stop executing the request?
+2. Did the transaction commit, roll back, or remain unknown?
+3. Were connection, lock, snapshot, and temporary resources released?
+
+Do not retry a write with an unknown outcome unless it is idempotent or the
+application can query the request/transaction outcome.
+
+## WAL and recovery diagnosis
+
+Preserve the complete database directory, WAL, metadata, and service logs.
+Record file sizes, modification times, checksums, checkpoint LSN, last
+acknowledged LSN, and the process termination reason. Run inspection and
+restore against a copy. Compare:
+
+```text
+checkpoint LSN <= durable WAL end LSN
+last acknowledged commit <= durable WAL end LSN
+restored checksum == manifest checksum
+replayed transaction set == committed transaction set
+```
+
+For corruption, stop writes and escalate rather than repeatedly reopening the
+original. For a compaction issue, compare row counts, indexes, checksums, and
+reopen behavior before and after compaction on a copy.
+
+## Wire and protocol debugging
+
+Use a local test endpoint and sanitized packet/frame logging. Validate one
+request at a time: handshake, authentication, capability negotiation, query,
+result frames, cancellation, and close. Check frame length, request ID,
+sequence, status, and error payload. Test partial reads and writes because a
+single `read` or `write` is not guaranteed to transfer a complete frame.
+
+For an in-flight cancellation race, log the request ID and server state at
+cancel receipt, executor stop, transaction decision, and response emission.
+The client must distinguish cancellation accepted, cancellation too late, and
+unknown connection loss.
+
+## Rails debugging
+
+Enable Rails SQL logging in a non-production reproduction and redact bind
+values before sharing. Compare the generated SQL with a direct RubyDB query.
+For adapter bugs, create the smallest model and migration that shows the
+problem, then test both a fresh schema and a populated table. Inspect:
+
+* quoting and bind parameter order;
+* transaction/savepoint boundaries;
+* affected rows and last-insert ID;
+* schema introspection and default values;
+* pool checkout/checkin and leaked transactions; and
+* exception class and retry behavior.
+
+Use the Rails example under `examples/rails_app` as a smoke harness before
+reproducing inside a large application.
+
+## Ruby-level tools
+
+For a focused local reproduction, Ruby’s standard tools are usually enough:
+
+```sh
+RUBYOPT="-d" bundle exec rspec spec/path/to/failing_spec.rb
+bundle exec ruby -w -Ilib path/to/reproduction.rb
+```
+
+`TracePoint` can observe method calls and exceptions without modifying the
+engine. Use it only in a short-lived reproduction because tracing changes
+timing and can invalidate concurrency conclusions. Capture thread backtraces
+when a process appears hung, and include the thread roles (acceptor, worker,
+checkpoint, replication, application).
+
+## Performance debugging
+
+Separate CPU, lock, I/O, and queue time. Record p50/p95/p99 latency, throughput,
+errors, WAL growth, checkpoint duration, memory, file descriptors, and active
+transactions. Change one variable per run and repeat enough times to expose
+variance. A faster benchmark with weaker durability is not an equivalent
+optimization.
+
+Use:
+
+```sh
+RUBYDB_BENCHMARK_ITERATIONS=100 ruby -Ilib benchmarks/basic_workload.rb
+ruby benchmarks/concurrent_workload.rb
+ruby scripts/production_soak
+```
+
+Keep benchmark artifacts out of commits unless they are intentional fixtures.
+
+## Fuzzing and property failures
+
+Save the seed, generated SQL/input, Ruby version, commit, and failing database
+directory. Reduce the number of operations while preserving the seed. Check
+the invariant: no crash, no invalid state, rollback equivalence, parser
+round-trip, or index/table agreement. Add the minimized case as a deterministic
+spec, then keep the fuzz run as a secondary guard.
+
+## What not to do
+
+Do not delete WAL or lock files, edit database bytes manually, disable checksum
+validation, run repair on the only copy, force a replica promotion without
+fencing, or publish sanitized logs that still contain secrets. These actions
+can turn a diagnosable incident into irreversible data loss or a security
+incident.
+
+## Diagnostic report template
+
+```text
+Summary:
+First observed (UTC):
+RubyDB version/commit:
+Ruby/Rails/OS/filesystem:
+Topology and ownership mode:
+Configuration names/checksum:
+Command or request shape:
+Request/transaction/LSN IDs:
+Expected result:
+Actual result:
+Reproduction and seed:
+Logs/metrics/checksums:
+Actions already taken:
+Data impact and current containment:
+```
+

data/docs/developer/branching.md

@@ -0,0 +1,10 @@
+# Branching
+
+RubyDB branches represent database snapshots and development lines in the
+engine. Create and inspect branches with the CLI, verify the target state, and
+retain a backup before merging or checking out a branch containing important
+data.
+
+Branch operations are not a substitute for backups or replication. Test branch
+diff, merge, checkout, conflict handling, and reopen behavior before using them
+in an operational workflow.

data/docs/developer/database-diff.md

@@ -0,0 +1,10 @@
+# Database diff
+
+Database diff compares schema and supported state between database snapshots or
+branches. Use it to review migration impact and branch changes before applying
+them. A diff is evidence for review, not an automatic guarantee that every
+application query remains compatible.
+
+For production changes, take a verified backup, inspect the diff, apply it to a
+staging restore with representative data, run migrations and smoke queries, and
+retain the original for rollback.

data/docs/developer/local-development.md

@@ -0,0 +1,17 @@
+# Local development
+
+```sh
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+Use `tmp/` or `Dir.mktmpdir` for databases. The server/client examples are
+appropriate when testing process boundaries. Do not open one embedded path from
+multiple processes. Use the reported fuzz seed and commit when reproducing a
+failure.
+
+Start with the [developer guide](../developer-guide.md). For failures, use a
+fresh copy, preserve WAL and metadata, run the narrowest spec first, then the
+full suite. The [debugging playbook](../debugging.md) describes safe logging,
+thread dumps, protocol isolation, and diagnostic reports.

data/docs/developer/snapshots.md

@@ -0,0 +1,9 @@
+# Snapshots
+
+Snapshots capture a consistent RubyDB state for inspection, backup validation,
+branching, or staging. Create snapshots through the supported CLI/API and keep
+the snapshot with its metadata and checksum.
+
+Validate a snapshot by opening it in a separate directory. Do not treat a
+snapshot as a replacement for an independently verified backup or replication.
+Keep retention and deletion policies explicit for production data.

data/docs/developer/temporal-data.md

@@ -0,0 +1,10 @@
+# Temporal data
+
+MVCC keeps row versions long enough for active transaction visibility and safe
+vacuum. Readers observe a transaction-consistent view according to the selected
+isolation behavior; uncommitted changes are not published to other readers.
+
+Long-running transactions retain old versions and can increase storage. Monitor
+transaction age and vacuum/compaction duration, and terminate or redesign stale
+work before it affects the workload. Test temporal behavior with restart and
+rollback, not only a single read.

data/docs/developer-guide.md

@@ -0,0 +1,297 @@
+# RubyDB developer guide
+
+This is the implementation guide for contributors who need to change RubyDB
+safely. It explains the repository, the request path, the storage invariants,
+the test strategy, and the debugging workflow. Read it together with the
+topic specifications under `spec/`; the specifications are the behavioral
+contract, while this guide explains how the pieces fit together.
+
+## 1. Scope and support promise
+
+RubyDB is a Ruby-native relational database with two ownership modes:
+
+* embedded mode, where one Ruby process owns a database directory; and
+* server mode, where the server owns the directory and application processes
+  use the client protocol.
+
+The supported surface is the behavior exercised by the test suite and listed
+in [SQL compatibility](sql/compatibility.md). Similar syntax does not imply
+complete PostgreSQL, MySQL, or SQLite compatibility. A change that broadens
+syntax must also specify its semantics, errors, types, transactions, and
+adapter behavior.
+
+## 2. Repository orientation
+
+The important directories are:
+
+| Path | Responsibility |
+| --- | --- |
+| `lib/rubydb` | Engine, SQL, storage, transactions, server, client, adapters |
+| `spec` | Unit, integration, protocol, SQL, recovery, and adapter contracts |
+| `benchmarks` | Repeatable throughput and concurrency measurements |
+| `scripts` | Soak tests, durability drills, fuzzing, and release checks |
+| `config` | Example configuration and monitoring rules |
+| `examples` | Runnable Ruby and Rails applications |
+| `docs` | User, operator, developer, and compatibility documentation |
+| `packaging` | Container and deployment examples |
+| `exe` and `bin` | Public command-line entry points |
+
+Start with `lib/rubydb.rb` and follow the public API into the engine. For a
+feature, locate the nearest existing spec before editing implementation code.
+Avoid adding a second abstraction when an existing subsystem already owns the
+invariant.
+
+## 3. Local setup
+
+Use a supported Ruby version from the project CI matrix and install the locked
+dependencies:
+
+```sh
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+Use a temporary database for experiments. Never use a production path in a
+test or run a destructive command against an unknown directory:
+
+```ruby
+require "tmpdir"
+require "rubydb"
+
+Dir.mktmpdir("rubydb-dev-") do |dir|
+  engine = RubyDB::Storage::Engine.new(File.join(dir, "dev.rdb"))
+  engine.execute("CREATE TABLE items (id INTEGER PRIMARY KEY, name TEXT)")
+  engine.close
+end
+```
+
+The server/client path is required when testing process boundaries. Multiple
+independent embedded owners must never open the same database directory.
+
+## 4. The request lifecycle
+
+A typical SQL request follows this sequence:
+
+```text
+Ruby API or client
+  -> connection/session and authentication
+  -> SQL tokenizer/parser
+  -> binder and type/parameter validation
+  -> planner and executor
+  -> transaction/MVCC read or write set
+  -> table/index mutation
+  -> WAL append and durable commit
+  -> result encoding and protocol response
+```
+
+Keep failures at the layer that owns them. Parser errors should not be turned
+into storage errors. A failed WAL append must not report a committed schema or
+row change. A client timeout must not silently convert an unknown commit into
+a rollback; the caller must be able to determine whether a request was
+committed before retrying.
+
+## 5. Storage and durability invariants
+
+The storage directory contains data pages, metadata, WAL state, and recovery
+artifacts. Changes must preserve these invariants:
+
+1. A page has valid framing and checksum before it is trusted.
+2. WAL records are validated before replay and are applied in LSN order.
+3. A commit acknowledgement is emitted only after the configured durability
+   point has succeeded.
+4. Schema publication and its dependent indexes are visible atomically.
+5. Recovery is idempotent: replaying a committed record does not duplicate a
+   row or corrupt an index.
+6. Torn, truncated, or corrupted input fails closed with a useful error.
+7. Temporary files are not mistaken for a completed checkpoint or backup.
+
+When changing page layout or record encoding, update the format specification,
+versioning/upgrade path, compatibility tests, and recovery fixtures. Do not
+silently reinterpret old bytes. If a format cannot be read, return an explicit
+upgrade or corruption error and preserve the original files for diagnosis.
+
+## 6. WAL, checkpoints, and recovery
+
+The WAL is the source of truth between checkpoints. A checkpoint copies safe
+state to durable pages and advances the recovery boundary only after all
+required data and metadata have been flushed. Recovery should:
+
+1. open the directory read-only where possible;
+2. validate metadata and the last known checkpoint;
+3. scan WAL frames, stopping only at a valid end boundary;
+4. reject checksum, sequence, length, or transaction inconsistencies;
+5. replay committed work and discard incomplete transactions;
+6. rebuild or validate indexes before accepting writes; and
+7. publish a recovery result with the replayed LSN and warnings.
+
+Tests must cover normal reopen, a process terminated during a write, an
+interrupted checkpoint, truncated WAL, invalid checksums, missing metadata,
+full-disk behavior, and restore into a new directory. Fault injection belongs
+around filesystem calls, not only around Ruby methods, because failures occur
+at `fsync`, rename, allocation, and close boundaries.
+
+## 7. Transactions, MVCC, and locking
+
+Every statement executes in a transaction context, whether it is explicit or
+implicit. The context owns the snapshot, read view, write set, lock state,
+savepoints, and commit result. A transaction must not leak locks or snapshots
+when it raises, times out, is cancelled, or loses its connection.
+
+MVCC readers use a stable visibility point. Writers create new versions and
+retain the before-image needed by active readers and rollback. Vacuum may
+reclaim a version only after the global safe point has passed it. A new feature
+must define behavior for:
+
+* read committed, repeatable read, and serializable transactions;
+* concurrent update of the same row;
+* unique and foreign-key conflicts;
+* deadlock detection and victim rollback;
+* lock wait timeouts and request cancellation; and
+* commit acknowledgement followed by client disconnect.
+
+Deadlock resolution must abort a complete victim transaction, release all of
+its locks, and leave other transactions able to progress. Never fix a deadlock
+by globally disabling locking or by releasing a lock without undoing the
+corresponding write set.
+
+## 8. SQL implementation workflow
+
+For a new statement or expression:
+
+1. write the syntax and semantic contract in `spec/sql`;
+2. add parser acceptance and rejection examples;
+3. add binder/type/nullability behavior;
+4. add planner and executor tests;
+5. test transaction, constraint, index, and error interactions;
+6. test the Ruby API and server protocol path; and
+7. test the ActiveRecord-generated SQL when the feature is adapter-visible.
+
+Prefer parameter binding to string interpolation. Every expression needs
+defined behavior for `NULL`, booleans, numeric coercion, text comparison,
+collation, and invalid input. Every DDL operation needs idempotence or an
+explicit error contract. Every optimizer rewrite must have a semantic
+equivalence test against the non-optimized execution path.
+
+The documented common SQLite-style profile is intentionally narrower than
+SQLite itself. Do not label a feature “SQLite compatible” until its syntax,
+results, types, error behavior, and migration behavior are tested.
+
+## 9. Tables, indexes, and constraints
+
+Table mutations and index mutations are one logical operation. If an index
+write fails, the statement must fail visibly and the transaction must either
+roll back or retain a recoverable pending state; it must not acknowledge a row
+that cannot be found by a required index.
+
+For each index type, test empty and populated tables, duplicate keys, `NULL`,
+deep splits, reopen, recovery replay, deletion/merge, and concurrent readers.
+For each constraint, test direct SQL, prepared parameters, ActiveRecord
+inserts/updates, rollback, and the exact error class/message contract where
+callers may depend on it.
+
+## 10. Server, client, and wire protocol
+
+The server is the single owner of the database directory. A client session
+handles authentication, capability negotiation, request IDs, deadlines,
+cancellation, result framing, and connection shutdown. Protocol changes must
+be backward-compatible or carry an explicit protocol version and rejection
+path.
+
+Wire cancellation is part of correctness. A cancelled request must stop
+execution at safe checkpoints, release transaction resources, and return a
+definitive cancellation response. If cancellation races with commit, the
+server must preserve the commit outcome and expose enough request identity for
+the client to query status rather than blindly retrying.
+
+Test malformed lengths, unknown message types, duplicate request IDs, partial
+frames, client disconnects, server shutdown, timeout races, authentication
+failure, TLS negotiation, and cancellation during a long scan.
+
+## 11. Rails and adapter work
+
+The ActiveRecord adapter translates Rails schema and query APIs into RubyDB
+SQL. Adapter code must preserve Rails expectations for quoting, bind
+parameters, affected-row counts, last-insert IDs, transactions, savepoints,
+schema introspection, migration versions, and exceptions.
+
+When changing adapter behavior, run the example app and test at least:
+
+* `where`, ordering, limits, scopes, joins, and aggregate relations;
+* eager loading, nested associations, and inverse relationships;
+* connection pools with multiple threads;
+* schema dump/load and populated-table migrations;
+* rollback, retry, and migration checksum behavior; and
+* every supported Ruby/Rails combination in CI.
+
+The adapter is not proof of complete SQLite or PostgreSQL compatibility. An
+application should run its own generated-SQL and migration suite before a
+cutover.
+
+## 12. Testing pyramid
+
+Use the smallest test that proves the invariant:
+
+* unit specs for parsing, encoding, types, and isolated algorithms;
+* component specs for storage, WAL, indexes, transactions, and protocol;
+* integration specs for engine-to-SQL and server-to-client behavior;
+* process specs for crash recovery, pooling, and failover;
+* workload tests for sustained concurrency and resource limits; and
+* example applications for real Rails and Ruby workflows.
+
+Useful commands include:
+
+```sh
+bundle exec rspec
+bundle exec rspec spec/sql spec/storage spec/transactions
+ruby scripts/durability_drill
+ruby scripts/production_soak
+ruby scripts/fuzz
+RUBYDB_BENCHMARK_ITERATIONS=100 ruby -Ilib benchmarks/basic_workload.rb
+```
+
+Record the Ruby version, commit, OS, command, seed, database configuration,
+and artifact paths for every non-trivial run. A green unit suite does not
+replace a restore drill, multi-process soak, or deployment test.
+
+## 13. Debugging a failing change
+
+Start with [Debugging RubyDB](debugging.md). Reproduce on a fresh temporary
+directory, reduce the schema and SQL, rerun with the reported seed, and save
+logs plus the WAL metadata. Compare embedded and server/client execution when
+ownership or protocol is suspected. Use [Troubleshooting](troubleshooting.md)
+for operator symptoms and evidence-preserving recovery steps.
+
+Never “repair” a failing test by deleting WAL, disabling checksums, loosening a
+constraint, or turning off synchronization. Preserve the failing directory,
+copy it, and investigate the copy.
+
+## 14. Performance and capacity work
+
+Benchmark one variable at a time and report latency percentiles, throughput,
+concurrency, payload shape, cache size, WAL/checkpoint settings, and storage
+medium. Track p50, p95, p99, error rate, lock wait time, WAL growth, checkpoint
+duration, memory, file descriptors, and CPU.
+
+Capacity limits are workload-specific. A benchmark result is not a guarantee
+for a Rails application with different indexes, query shapes, or connection
+pool settings. Add a regression threshold only after the benchmark is stable
+across repeated runs and environments.
+
+## 15. Safe contribution checklist
+
+Before opening a pull request:
+
+1. Explain the invariant and compatibility impact.
+2. Add focused tests, including failure paths.
+3. Run the relevant focused suite and the full suite.
+4. Run formatting/lint and `git diff --check`.
+5. Update the appropriate spec and user/operator documentation.
+6. Note migrations, format changes, recovery implications, and rollback plan.
+7. Include benchmark or soak evidence for hot-path and concurrency changes.
+8. Remove debug output, secrets, temporary data, and generated artifacts.
+
+See [Contributing](../CONTRIBUTING.md), [testing](contributing/testing.md),
+and [release process](contributing/release-process.md) for the repository
+workflow.
+

data/docs/getting-started/first-database.md

@@ -0,0 +1,16 @@
+# First database
+
+```ruby
+require "rubydb"
+
+path = "tmp/first-database.rdb"
+engine = RubyDB::Storage::Engine.new(path)
+engine.execute("CREATE TABLE accounts (id INTEGER PRIMARY KEY, email TEXT UNIQUE NOT NULL)")
+engine.execute("INSERT INTO accounts (id, email) VALUES (1, 'ada@example.test')")
+puts engine.execute("SELECT id, email FROM accounts").inspect
+engine.close
+```
+
+The engine creates durable storage and WAL state under the selected path. Close
+the engine cleanly and keep the database, WAL, and lock files together. A single
+embedded path has one owner; use a server for multiple processes.