rubydb 0.1.4 → 0.1.6

data/docs/architecture/go-accelerator.md

@@ -0,0 +1,179 @@
+# Ruby + Go accelerator
+
+RubyDB installs as one Ruby package. Release gems include CGO-free Go
+executables for Windows amd64/arm64, Linux amd64/arm64, and macOS amd64/arm64. A
+developer needs Go only when building RubyDB itself or publishing a release;
+an application developer or production operator does not need Go installed.
+
+Ruby remains the database authority. It owns SQL meaning, physical-plan
+selection, transactions, MVCC visibility, locks, schema and constraints,
+permissions, WAL, recovery, and every commit decision. Go receives immutable
+read batches and returns data; it never writes database pages or decides what
+is committed.
+
+## Runtime boundary
+
+The Ruby process starts one long-lived private worker over stdin/stdout. The
+worker does not listen on a TCP port and is not reachable by application
+clients.
+
+```text
+application -> RubyDB parser/planner -> Ruby transaction and visibility checks
+                                      \-> Go binary read worker
+Ruby storage/WAL/MVCC/commit <--------- Ruby remains authoritative
+```
+
+The Go source is deliberately split by responsibility:
+
+```text
+accelerator/cmd/rubydb-accelerator/main.go   process entrypoint only
+accelerator/internal/runtime/                 request loop and dispatch
+accelerator/internal/protocol/                bounded frames and columnar batches
+accelerator/internal/execution/               filters, sorting, aggregates, joins
+accelerator/internal/storage/                 immutable snapshot page reads
+accelerator/internal/wal/                     checksums, compression, record batches
+accelerator/internal/parallel/                 bounded queues and worker scheduling
+accelerator/internal/memory/                  reusable arena and byte buffers
+accelerator/internal/metrics/                 operation counts and p95 timings
+```
+
+Each package has focused tests. The storage reader accepts only a page size,
+page list, and an immutable snapshot contract supplied by RubyDB; it does not
+open the catalog, WAL, or mutable page state by itself. This boundary is
+intentional: adding more Go code must not silently create a second transaction
+or recovery authority.
+
+Control messages use bounded JSON-lines. Large row operations use a versioned
+`RDBB` binary frame with a columnar batch: column names are sent once and
+values use typed, length-prefixed fields for NULL, booleans, integers, floats,
+strings, bytes, and JSON fallback values. Responses contain bounded metadata
+and one or more columnar result batches. This removes the old JSON/base64 row
+copy from the hot path while retaining a simple control protocol.
+
+Every frame has a request ID, protocol/version fields, a maximum size, and a
+structured error status. Startup verifies the binary against `SHA256SUMS`.
+Timeout, EOF, protocol mismatch, checksum failure, malformed data, or worker
+exit stops that worker. In `auto`, Ruby retries the operation on the Ruby
+executor; in `required`, the error is surfaced to the caller.
+
+## Accelerated work
+
+The current safe physical operators are:
+
+- immutable snapshot page and record decoding for eligible read-only scans;
+- immutable B-tree entry filtering for eligible indexed scans;
+- columnar serialization and deserialization;
+- deterministic parallel filtering for large batches;
+- filtering, projection, ordering, DISTINCT, and NULL-aware comparisons;
+- grouped `COUNT`, `SUM`, `AVG`, `MIN`, and `MAX`;
+- validated inner hash and merge joins;
+- portable `ROW_NUMBER`, `RANK`, `DENSE_RANK`, `LAG`, `LEAD`, and aggregate window operations;
+- SHA-256 checksums; and
+- gzip archive compression/decompression;
+- versioned WAL batch encoding, checksums, and optional compression; and
+- request-scoped cancellation, multiplexed requests, and bounded JSON result batches.
+
+WAL acceleration is deliberately a preparation boundary: Ruby assigns the
+transaction ID, LSN, commit order, and commit decision. Go returns an encoded
+and checksummed batch; Ruby is still responsible for writing the approved
+bytes, calling `fsync`, and publishing the durable acknowledgement. A failed
+or uncertain acknowledgement must remain a Ruby recovery error.
+
+The SQL executor delegates only plans it can describe with simple identifiers,
+literal predicates, and an eligible immutable read snapshot. Outer joins,
+complex expressions, writes, active transactions, and visibility-sensitive
+work stay in Ruby. The general row pipeline can also receive explicit
+projection, DISTINCT, HAVING, window, and merge-join specifications when the
+Ruby planner has already validated their semantics. Ruby applies every stage
+that was not delegated and remains the result authority through differential
+validation.
+
+### Immutable snapshot contract
+
+Before a snapshot scan Ruby flushes dirty pages, visibility metadata, and the
+table catalog while holding the engine lock. The default direct path records
+the page size/count, table page lists, schema, B-tree entries, and visibility
+exclusions in a manifest, then lets Go read the already-flushed database file
+while that lock remains held. This avoids copying and hashing the complete
+database for every read. `RUBYDB_ACCELERATOR_DIRECT_SNAPSHOT=off` (or
+`accelerator.direct_snapshot: false`) selects the detached fallback: Ruby
+copies the database to a short-lived private snapshot, records a SHA-256
+digest, and removes the copy after the request. Go verifies the file size,
+optional digest, page headers, record bounds, record flags, column count, and
+type lengths before returning rows.
+
+This path is intentionally conservative. Ruby declines it while the current
+thread has a transaction or any transaction is active. Go does not read WAL,
+catalog files, live indexes, or MVCC state and cannot publish writes. If a
+manifest, page, index entry, type, or result is invalid, `auto` falls back to
+the Ruby executor and `required` reports the error. The B-tree data is a
+consistent in-memory index snapshot because RubyDB rebuilds its indexes from
+metadata on open; it is not a new persisted index format.
+
+## Automatic selection
+
+The default is:
+
+```yaml
+accelerator:
+  mode: auto
+  read_pipeline: on
+  direct_snapshot: true
+  min_rows: 256
+```
+
+For each eligible snapshot scan, the first automatic operation is differentially
+checked against the Ruby implementation and timed. The result is recorded for
+both the physical snapshot scan and the row-batch scan family. Aggregate and
+join operations retain their own differential checks and timing. Utility
+operations record checksum, compression, and WAL-batch samples as well.
+`auto` keeps the Go operator only when it is faster and equivalent; otherwise
+that family falls back to Ruby for the lifetime of the worker. This avoids
+turning IPC overhead into a regression for small or already-optimized queries.
+The decision is process-local and is reset on restart, so it must be validated
+again after a deployment change.
+
+`mode: required` bypasses the speed decision and is intended for accelerator
+CI, release smoke tests, and deployments whose workload benchmark has already
+established a win. `mode: off` disables the worker entirely.
+
+```sh
+RUBYDB_ACCELERATOR=off rubydb doctor
+RUBYDB_ACCELERATOR=required rubydb accelerator --ping --json
+```
+
+The runtime reports capabilities, selected mode, checksum-verified binary,
+calibration decisions, and the last worker error in `rubydb accelerator
+--ping --json` and database statistics.
+
+## Building and packaging
+
+Release builds are cross-compiled with CGO disabled:
+
+```sh
+ruby scripts/build_accelerator
+RUBYDB_ACCELERATOR_TARGETS=current ruby scripts/build_accelerator
+bundle exec rake build:checksum
+```
+
+The gemspec packages the Ruby bridge, source module, six supported binaries,
+and the checksum manifest. A release preflight must run Go tests, Ruby
+accelerator tests, checksum verification, the extracted-gem handshake, and a
+representative workload benchmark before publishing.
+
+## Performance policy
+
+Go is intended to improve workloads dominated by scans, joins, aggregation,
+serialization, compression, or checksum work. It cannot promise that every
+query becomes seconds instead of minutes: indexes, disk latency, query shape,
+lock contention, and result size may dominate. The benchmark harness should
+report p50/p95/p99 latency, throughput, rows/sec, an RSS snapshot where the
+platform exposes it, worker/fallback metrics, and WAL-batch timing. CPU,
+process restarts, and host-level memory should be collected by the deployment
+monitor because those metrics are platform-specific. A speed claim is valid
+only for the measured workload and platform.
+
+Future shared immutable page snapshots and broader index/parallel operators
+must preserve the same contract: Go may read a versioned snapshot, but it may
+never mutate pages, indexes, catalog files, WAL, transaction state, or
+visibility state.

data/docs/architecture/indexes.md

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

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

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

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

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

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

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

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

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

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