rubydb 0.1.0

data/docs/architecture/indexes.md

@@ -0,0 +1,19 @@
+# Indexes
+
+RubyDB provides B-tree indexes for supported table columns, including unique
+indexes. The executor can use indexes for eligible lookups while preserving
+correctness through table visibility and transaction rules.
+
+Index metadata is persisted with the catalog. Index creation, DML maintenance,
+rollback, deep splits, reopen, and failure handling must remain consistent. If
+index recovery fails, startup must fail visibly; never silently rebuild or claim
+an index is healthy without verification.
+
+## Change checklist
+
+Index changes require coverage for empty and populated tables, duplicate and
+null keys, deep splits, deletes, rollback, crash/replay, compaction, and
+concurrent readers. Compare an index lookup with a table scan before and after
+reopen. A required-index persistence error must abort the owning operation and
+be observable by the caller. See [troubleshooting](../troubleshooting.md) for
+the safe response to suspected index corruption.

data/docs/architecture/mvcc.md

@@ -0,0 +1,19 @@
+# MVCC support status
+
+RubyDB currently provides safe READ COMMITTED behavior for the storage engine.
+Uncommitted row versions are visible to their owning transaction and hidden
+from other transactions. Committed versions become visible after the durable
+COMMIT WAL record is written. Deleted physical records remain on pages until
+vacuum/compaction and are excluded from ordinary scans.
+
+REPEATABLE READ uses persisted historical row versions and transaction
+snapshots. SERIALIZABLE uses snapshot validation over tracked row read/write
+keys and conservative table predicates. A newer committed version intersecting
+the dependency set aborts commit with a serialization failure. Table-level
+predicate tracking prevents phantoms at the cost of false-positive conflicts;
+exact index-range predicate locking is a future optimization.
+
+The version store is persisted atomically and supports safe-point vacuuming.
+Vacuum never removes active versions and retains the newest committed base
+version needed by an active reader; older committed history is removable only
+when its commit ID precedes the oldest active transaction.

data/docs/architecture/overview.md

@@ -0,0 +1,13 @@
+# Architecture overview
+
+RubyDB separates logical query processing from durable state changes. SQL is
+lexed into tokens, parsed into an AST, bound against catalog metadata, planned,
+and executed against the storage engine. DML is coordinated with transactions
+and WAL before durable acknowledgement.
+
+The catalog defines tables, columns, constraints, views, and indexes. The page
+manager and buffer pool provide durable storage. Recovery replays valid WAL and
+rejects malformed or uncertain state. Server/client mode isolates application
+processes from the exclusive embedded owner.
+
+Read the [current-state audit](current-state.md) before relying on any feature.

data/docs/architecture/pages.md

@@ -0,0 +1,11 @@
+# Pages and file layout
+
+RubyDB stores fixed-size pages containing validated headers, checksums, and
+typed records. Page allocation, metadata, table data, and index pages are
+managed by the storage layer; callers must not edit database files directly.
+
+The page format is versioned. Unknown formats, invalid page sizes, malformed
+headers, and checksum failures fail closed during open or recovery. Keep the
+database, WAL, catalog metadata, and lock files together when copying or
+restoring a database. See [storage format](../../spec/storage/format.md) and
+[upgrade guidance](../operations/upgrades.md).

data/docs/architecture/production-roadmap.md

@@ -0,0 +1,82 @@
+# RubyDB production roadmap
+
+## Current baseline
+
+The project has a meaningful repository skeleton and substantial design intent. It already includes modules for storage, indexing, transactions, MVCC, SQL parts, server, replication, and backup flows. However, the implementation still lacks enough end-to-end proof for durable, crash-safe operation.
+
+## Prioritized roadmap
+
+### Phase 0 — Repository stabilization
+
+- fix library loading and Ruby compatibility metadata
+- verify the project loads via `require "rubydb"`
+- establish a truthful project health baseline
+- add characterization tests for current public behavior
+
+### Phase 1 — Storage durability
+
+- define a stable on-disk page format and file format
+- add checksums, header validation, and corruption detection
+- ensure WAL durability precedes page flush semantics
+- add real restart tests and crash tests
+
+### Phase 2 — Transaction correctness
+
+- complete transaction lifecycle handling
+- prove commit/rollback semantics under restart
+- validate isolation semantics and visibility rules
+- add deadlock and lock manager tests
+
+### Phase 3 — Catalog and indexes
+
+- persist catalog metadata consistently
+- maintain indexes correctly during DML
+- verify index consistency after crash and rollback
+- document supported SQL compatibility targets honestly
+
+### Phase 4 — SQL execution and optimizer
+
+- validate end-to-end SQL execution
+- ensure binder, planner, and executor are integrated
+- add integration tests for basic DML and queries
+- implement `EXPLAIN` only with real, honest plan output
+
+### Phase 5 — Server and security
+
+- harden server lifecycle and malformed-client handling
+- enforce connection limits and timeouts
+- check authorization before execution
+- validate auth flows and access controls
+
+### Phase 6 — Backup, recovery, and replication
+
+- prove full backup + restore works from a clean environment
+- validate point-in-time or incremental recovery only when implemented correctly
+- only add replication once WAL recovery is demonstrably correct
+
+### Phase 7 — Monitoring and production readiness
+
+- add structured logging and health/readiness checks
+- expose operational metrics
+- create a final production-readiness audit with limitations and unsupported features
+
+## Hard gates before declaring production readiness
+
+RubyDB should not claim production readiness until it demonstrates all of the following:
+
+- updated data survives restart
+- crash recovery is validated with subprocess termination tests
+- transactions preserve isolation semantics
+- WAL ordering is durable and replayed correctly
+- index and table data stay consistent
+- authZ/authN is enforced over real operations
+- backup and restore work in a clean environment
+- server operations handle failures safely without whole-process crashes
+
+## Decision rule
+
+The repository must prefer correctness over feature breadth. A smaller well-tested engine is more valuable than a broad but unsafe one.
+
+## Long-term target
+
+The final target is not a fake "PostgreSQL clone" or a marketing demo. The target is a Ruby-first, SQLite-like development experience paired with durable, crash-safe relational database semantics that can be validated under real workloads.

data/docs/architecture/query-planner.md

@@ -0,0 +1,20 @@
+# Query planner
+
+The planner binds identifiers to catalog columns, validates expressions, and
+builds executable plans. It supports sequential/index scans, safe inner-join
+reordering, outer joins, filters, grouping, sorting, limits, set operations,
+subqueries, CTEs, and window operations in the documented SQL surface.
+
+Plans must preserve SQL null, ordering, grouping, and transaction visibility
+semantics. `EXPLAIN` reports the actual selected plan; it is not a performance
+promise. Use the benchmark and workload harnesses to establish capacity on the
+target hardware.
+
+## Plan review
+
+For every rewrite, compare the optimized and baseline results on empty,
+duplicate, null, and concurrent data. Include joins with unmatched rows,
+grouping, limits, and repeated execution with bound parameters. Measure plan
+selection, execution, lock wait, and I/O separately. A plan that is faster but
+changes cardinality or ordering is incorrect; add the minimized query as a
+regression spec before merging.

data/docs/architecture/recovery.md

@@ -0,0 +1,18 @@
+# Recovery architecture
+
+Recovery validates the database format, page headers, checksums, metadata, and
+WAL before making state available. Valid committed WAL records may be replayed;
+malformed or ambiguous records fail closed and require operator investigation.
+
+Recovery procedures work from a preserved source or verified backup. Restore to
+a new directory, run dry-run and checksum checks, reopen the restored engine,
+compare schema/row evidence, and only then switch application traffic. See the
+[disaster recovery](../operations/disaster-recovery.md) procedure.
+
+## Failure handling
+
+Recovery is allowed to replay only validated, committed records. Truncated
+frames, invalid checksums, impossible LSNs, and incomplete metadata must stop
+startup with an actionable error. Preserve the original directory and WAL;
+repair or compaction experiments belong on a copy. The [debugging playbook](../debugging.md)
+lists the evidence to collect.

data/docs/architecture/sql-engine.md

@@ -0,0 +1,12 @@
+# SQL engine
+
+RubyDB implements a documented RubyDB SQL subset with a tested common
+SQLite-style application profile. Covered features include CRUD, constraints,
+joins, grouping/aggregates, transactions/savepoints, CTEs, subqueries, set
+operations, upserts, windows, indexes, views, and maintenance statements listed
+in [SQL compatibility](../sql/compatibility.md).
+
+This is not complete PostgreSQL, MySQL, or SQLite dialect/file-format
+compatibility. Unsupported syntax must fail explicitly. Applications migrating
+from another engine must run their own schema, query, migration, and error
+behavior suite.

data/docs/architecture/storage-engine.md

@@ -0,0 +1,14 @@
+# Storage engine
+
+The storage engine owns the database path, page manager, buffer pool, catalog,
+indexes, WAL, and recovery lifecycle. It serializes durable changes and exposes
+Ruby-native operations used by the SQL executor and adapters.
+
+Embedded ownership is exclusive and enforced with an operating-system lock.
+Multiple processes must use the server. On failure, callers should preserve the
+original directory and recover into a new destination; do not delete WAL or
+overwrite the source during investigation.
+
+Storage changes require reopen, crash, fault-injection, corruption, compaction,
+and backup/restore coverage. The [lessons learned](../lessons-learned.md) page
+explains why these are separate guarantees.

data/docs/architecture/transactions.md

@@ -0,0 +1,10 @@
+# Transactions
+
+Transactions group mutations into a commit or rollback boundary. WAL commit and
+flush ordering precede durable acknowledgement. MVCC determines visibility,
+while lock management protects conflicting writes and resolves wait-for cycles.
+
+Supported controls include `BEGIN`, `COMMIT`, `ROLLBACK`, savepoints, and
+rollback to savepoint. A deadlock victim is rolled back and must retry the whole
+application unit as appropriate. Test isolation and recovery together; a green
+single-thread transaction test does not prove concurrent correctness.

data/docs/architecture/wal.md

@@ -0,0 +1,28 @@
+# RubyDB WAL format
+
+Each WAL segment is a sequence of independently framed records:
+
+```text
+4-byte unsigned big-endian payload length
+16-byte ASCII SHA-256 checksum prefix
+UTF-8 JSON payload
+```
+
+The checksum covers the JSON payload only. A record's LSN offset is the byte
+offset of its frame header within the segment, so readers can advance exactly
+one frame at a time. If the final frame is incomplete, recovery stops at that
+tail and retains all complete preceding records.
+
+WAL data is flushed and fsynced before the storage engine flushes data pages
+when synchronous WAL mode is enabled (the default). A successful `write` is
+therefore durable only after the WAL sync completes; callers must still use
+the engine's transaction/close APIs to coordinate higher-level durability.
+
+## Transaction recovery records
+
+Mutation records include the transaction ID. UPDATE records include the
+previous column values, and DELETE records include the previous row values and
+columns. Recovery replays mutations for transactions with a durable COMMIT
+record. Transactions that have a BEGIN but no COMMIT are undone in reverse WAL
+order. Recovery uses the existing row version for DELETE undo and does not
+create a replacement row with a new identifier.

data/docs/cli-cheatsheet.md

@@ -0,0 +1,98 @@
+# RubyDB CLI cheat sheet
+
+Replace paths and names before running. Put global options before the command.
+
+## Global
+
+```sh
+rubydb --help
+rubydb --version
+rubydb --config config/production.yml --env production --no-color status --json
+```
+
+## Database lifecycle
+
+```sh
+rubydb init --name app --dir data
+rubydb create --database data/app.rdb
+rubydb status --json
+rubydb doctor --quick --json
+rubydb inspect --database data/app.rdb --stats --wal
+rubydb drop --database data/app.rdb              # prompts
+rubydb drop --database data/app.rdb --force      # destructive
+```
+
+## Server
+
+```sh
+rubydb --env production start --host 127.0.0.1 --port 7432 \
+  --data-dir /var/lib/rubydb/data --log-dir /var/log/rubydb \
+  --pid-file /run/rubydb.pid
+rubydb stop --pid-file /run/rubydb.pid
+rubydb restart --pid-file /run/rubydb.pid
+```
+
+## SQL shell
+
+```sh
+rubydb shell --database app --table
+rubydb shell --database app --json
+```
+
+Inside shell: `.help` `.tables` `.table users` `.schema users` `.status`
+`.begin` `.commit` `.rollback` `.explain SELECT ...` `.exit`.
+
+## Migrations
+
+```sh
+rubydb migrate --database data/app.rdb --path db/migrate --dry-run
+rubydb migrate --database data/app.rdb --path db/migrate
+rubydb migrate --database data/app.rdb --path db/migrate --down --steps 1
+```
+
+## Backups and restore
+
+```sh
+rubydb backup --database data/app.rdb --dir backups --type full --compress
+rubydb backup --database data/app.rdb --dir backups --type incremental
+rubydb backup --database data/app.rdb --dir backups --type differential
+rubydb restore --dir backups --latest --dry-run
+rubydb restore --dir backups --latest
+rubydb restore --dir backups --backup NAME --point-in-time 2026-09-09T12:00:00Z
+```
+
+## Snapshots and branches
+
+```sh
+rubydb snapshot --database data/app.rdb --dir snapshots --name before-change
+rubydb snapshot --database data/app.rdb --dir snapshots --list
+rubydb branch --database data/app.rdb --branch-dir branches --list
+rubydb branch --database data/app.rdb --branch-dir branches --create feature --from main
+rubydb checkout --database data/app.rdb --branch-dir branches feature
+rubydb diff --database data/app.rdb --branch-dir branches main feature --summary
+rubydb merge --database data/app.rdb --branch-dir branches feature --into main
+```
+
+## Maintenance and release checks
+
+```sh
+rubydb vacuum --database data/app.rdb --dry-run
+rubydb vacuum --database data/app.rdb --full --analyze
+ruby scripts/durability_drill
+ruby scripts/replication_failover_drill
+ruby scripts/replication_network_failover_drill
+ruby scripts/release
+```
+
+## Safety rules
+
+- Back up and verify before `migrate`, `merge`, `checkout`, `vacuum --full`, or
+  any restore.
+- Treat `drop --force`, `create --force`, restore `--force`, and process `--force`
+  stop as destructive operations.
+- Preserve database, WAL, lock, metadata, logs, and configuration together.
+- Use one embedded owner; use server/client mode for multiple processes.
+- Never put passwords, tokens, private keys, or API keys in commands committed
+  to source control or in captured output.
+- A successful CLI exit is not a universal production certification; retain the
+  workload, restore, failover, CI, and security evidence.

data/docs/cli.md

@@ -0,0 +1,275 @@
+# RubyDB CLI guide
+
+The `rubydb` command manages local databases, server processes, migrations,
+backups, snapshots, branches, inspection, maintenance, and health checks. Run
+`rubydb --help` or `rubydb <command> --help` for the installed command's live
+options.
+
+## Command shape
+
+```text
+rubydb [global options] <command> [command options]
+```
+
+Global options must appear before the command:
+
+```sh
+rubydb --version
+rubydb --no-color --env production status --json
+rubydb --config config/production.yml --env production doctor --json
+```
+
+Global options are `--config FILE`, `--env ENV`, `--verbose`, `--quiet`,
+`--no-color`, `--help`, and `--version`. Commands return zero on success and a
+non-zero status on failure. Keep `RUBYDB_DEBUG=1` available when a failed
+command needs a Ruby backtrace; never include secrets in captured logs.
+
+## Initialize or create a database
+
+`init` creates a named database under a data directory and installs the default
+RubyDB metadata/users/sessions tables:
+
+```sh
+rubydb init --name app --dir data
+```
+
+`create` creates an empty database file:
+
+```sh
+rubydb create --name app --dir data
+rubydb create --database /var/lib/rubydb/app.rdb
+```
+
+`--force` is destructive for an existing database. Use it only for a disposable
+development directory after verifying the path. It is not a production reset
+procedure.
+
+## Start, stop, restart, and status
+
+Start a foreground server for development or a service manager:
+
+```sh
+rubydb --env production start \
+  --host 127.0.0.1 \
+  --port 7432 \
+  --data-dir /var/lib/rubydb/data \
+  --log-dir /var/log/rubydb \
+  --pid-file /run/rubydb.pid
+```
+
+Use `--daemon` only when an external service manager is not supervising the
+process. Prefer systemd, a container supervisor, or an equivalent process
+manager for production. Stop gracefully first:
+
+```sh
+rubydb stop --pid-file /run/rubydb.pid
+rubydb restart --pid-file /run/rubydb.pid
+```
+
+`--force` sends a hard termination and can interrupt active work; reserve it
+for a confirmed hung process after preserving logs and checking recovery needs.
+
+Inspect local status:
+
+```sh
+rubydb --env production status
+rubydb --env production status --json > status.json
+```
+
+Use JSON status in monitoring, but combine it with the server readiness endpoint,
+Prometheus metrics, process state, disk-space checks, and application probes.
+
+## Doctor and inspect
+
+`doctor` runs health/integrity checks. Start with a read-only quick check:
+
+```sh
+rubydb doctor --quick --json
+rubydb doctor --json > doctor.json
+```
+
+`doctor --fix` may perform supported repairs. Take and verify a backup first,
+stop application writes, record the output, and review every proposed action:
+
+```sh
+rubydb doctor --fix
+```
+
+`inspect` reports storage internals without replacing a backup or integrity
+verification:
+
+```sh
+rubydb inspect --database data/app.rdb --stats --wal
+rubydb inspect --database data/app.rdb --pages --indexes
+rubydb inspect --database data/app.rdb --table users
+```
+
+Use `inspect --wal` to correlate WAL growth with checkpoint/backup incidents.
+Do not edit files based on an inspection result; use the documented recovery
+procedure.
+
+## SQL shell
+
+Open the configured local database shell:
+
+```sh
+rubydb shell --database app
+```
+
+Output modes include `--table`, `--json`, and `--csv`. The shell supports these
+dot-commands:
+
+| Command | Purpose |
+| --- | --- |
+| `.help`, `.?` | Show shell help |
+| `.exit`, `.quit` | Exit safely |
+| `.status` | Show connection/database status |
+| `.tables` | List tables |
+| `.table NAME` | Describe columns and constraints |
+| `.schema NAME` | Show a table definition |
+| `.db NAME` | Switch configured local database |
+| `.begin`, `.txn` | Begin a transaction |
+| `.commit` | Commit the active transaction |
+| `.rollback` | Roll back the active transaction |
+| `.explain SQL` | Show the selected query plan |
+| `.clear`, `.cls` | Clear the terminal |
+
+Example:
+
+```text
+users> .tables
+users> SELECT id, email FROM users ORDER BY id LIMIT 20;
+users> .begin
+users> UPDATE users SET active = TRUE WHERE id = 1;
+users> .rollback
+users> .exit
+```
+
+Use bound parameters from application/client APIs for untrusted values. The
+shell is an administrative tool, not a connection-pool substitute. For
+multiple application processes, use the managed server and client libraries;
+never open one embedded path concurrently from independent processes.
+
+## Migrations
+
+Run migrations from the default `db/migrate` directory:
+
+```sh
+rubydb migrate --database data/app.rdb --path db/migrate
+rubydb migrate --database data/app.rdb --path db/migrate --dry-run
+```
+
+To roll back, specify the number of steps and use a verified backup boundary:
+
+```sh
+rubydb migrate --database data/app.rdb --path db/migrate --down --steps 1
+```
+
+`--version VERSION` targets a migration version. Before applying migrations in
+production, stop or coordinate writes, create a verified backup, test against a
+populated restore, run schema dump/load and application smoke queries, and keep
+the pre-migration directory until rollback closes. Applied migration checksum
+changes fail closed.
+
+## Backups and restore
+
+Create a verified full backup:
+
+```sh
+rubydb backup --database data/app.rdb --dir backups --type full --compress
+```
+
+The supported types are `full`, `incremental`, and `differential`. Use
+`--no-verify` only for controlled diagnostics; a release or production backup
+should verify. Retain the manifest, checksum, database version, and required
+WAL chain together.
+
+List or dry-run a restore before changing a live path:
+
+```sh
+rubydb restore --dir backups --latest --dry-run
+rubydb restore --database data/app.rdb --dir backups --backup BACKUP_NAME --dry-run
+```
+
+Restore to a new inactive directory whenever possible. `--force` is destructive
+and must not overwrite the only source. After restore, reopen the engine, verify
+schema and row evidence, run application smoke queries, and record RPO/RTO.
+Point-in-time restore uses `--point-in-time TIME` only when the required WAL
+chain is present and verified.
+
+## Snapshots
+
+Snapshots are useful for staging, inspection, and branch workflows:
+
+```sh
+rubydb snapshot --database data/app.rdb --dir snapshots --name before-migration
+rubydb snapshot --database data/app.rdb --dir snapshots --list
+rubydb snapshot --database data/app.rdb --dir snapshots --restore before-migration
+rubydb snapshot --database data/app.rdb --dir snapshots --delete old-snapshot
+```
+
+Keep snapshot metadata/checksums and do not treat snapshots as the only backup.
+Restore into a separate destination before routing traffic.
+
+## Branches and database diff
+
+List or create a branch:
+
+```sh
+rubydb branch --database data/app.rdb --branch-dir branches --list
+rubydb branch --database data/app.rdb --branch-dir branches --create feature-x --from main
+rubydb checkout --database data/app.rdb --branch-dir branches feature-x
+rubydb checkout --database data/app.rdb --branch-dir branches --create experiment
+```
+
+Review changes before merging:
+
+```sh
+rubydb diff --database data/app.rdb --branch-dir branches main feature-x
+rubydb diff --database data/app.rdb --branch-dir branches --summary main feature-x
+rubydb diff --database data/app.rdb --branch-dir branches --table users main feature-x
+rubydb merge --database data/app.rdb --branch-dir branches feature-x --into main
+```
+
+`merge` supports the configured strategy and `--no-commit`. Take a verified
+backup, review the diff, test the target with representative data, and preserve
+the pre-merge state. Branches are not replication or backup replacements.
+
+## Vacuum and maintenance
+
+Preview maintenance first:
+
+```sh
+rubydb vacuum --database data/app.rdb --dry-run
+rubydb vacuum --database data/app.rdb --table users
+rubydb vacuum --database data/app.rdb --full --analyze
+```
+
+Run full vacuum only during an approved maintenance window. Long-running
+transactions may retain versions and prevent space reclamation. Monitor free
+space, WAL/checkpoint behavior, query latency, and active transaction age.
+
+## Production command sequences
+
+### Pre-deployment
+
+```sh
+rubydb --config config/production.yml --env production doctor --quick --json
+rubydb --config config/production.yml --env production status --json
+rubydb backup --database /var/lib/rubydb/app.rdb --dir /var/backups/rubydb --type full --compress
+rubydb migrate --database /var/lib/rubydb/app.rdb --path db/migrate --dry-run
+```
+
+### Incident preservation
+
+Stop writes, preserve the database/WAL/log/configuration set, copy it to an
+incident directory, and then use `doctor --quick`, `inspect --stats --wal`, and
+the restore procedure. Do not use `drop --force`, `create --force`, or vacuum as
+an attempted corruption repair.
+
+### Release evidence
+
+Archive command output with the RubyDB commit/version, Ruby version, OS,
+database path class, workload, backup name/checksum, restore time, and operator.
+The CLI is one part of the production evidence; CI, workload, failover, and
+security review records are also required.

data/docs/contributing/architecture.md

@@ -0,0 +1,9 @@
+# Architecture contribution guide
+
+Before changing a core subsystem, identify its ownership, durability boundary,
+failure behavior, and public compatibility contract. Changes to storage, WAL,
+recovery, transactions, replication, protocol, or adapters need focused tests
+and an end-to-end regression.
+
+Document invariants in the relevant architecture page and add a lesson when a
+new failure mode is discovered. Prefer explicit errors over silent fallback.

data/docs/contributing/benchmarking.md

@@ -0,0 +1,14 @@
+# Benchmarking guide
+
+Run deterministic and concurrent workloads from the repository root:
+
+```sh
+RUBYDB_BENCHMARK_ITERATIONS=100 ruby -Ilib benchmarks/basic_workload.rb
+RUBYDB_SOAK_THREADS=16 RUBYDB_SOAK_OPERATIONS=2000 ruby benchmarks/concurrent_soak.rb
+RUBYDB_PRODUCTION_SOAK_CLIENTS=16 RUBYDB_PRODUCTION_SOAK_OPERATIONS=2000 ruby benchmarks/production_soak.rb
+```
+
+Record commit, Ruby version, OS, CPU/memory/storage, dataset size, seed,
+throughput, p50/p95/p99 latency, WAL growth, and recovery time. Benchmarks are
+not universal capacity certification; compare against application-specific
+limits and repeat after schema or runtime changes.

data/docs/contributing/development.md

@@ -0,0 +1,16 @@
+# Development guide
+
+Install dependencies with `bundle install`. Run focused specs while developing,
+then run `bundle exec rspec` and `bundle exec rubocop` before opening a pull
+request. Keep test databases in temporary directories and close engines in
+`ensure` blocks.
+
+Never use production data or secrets in local tests. Changes that affect a
+stored format, SQL behavior, protocol, migration, or release process must update
+the corresponding documentation and changelog.
+
+For the complete change workflow, read the [developer guide](../developer-guide.md),
+[debugging playbook](../debugging.md), and [testing guide](testing.md). Every
+bug fix should include a regression test and an explanation of its invariant.
+Run fault, concurrency, or recovery tests when the change crosses a durable
+boundary; a unit test alone is not sufficient evidence.