rubydb 0.1.4 → 0.1.6

data/docs/README.md

@@ -1,71 +1,77 @@
-# RubyDB documentation index
-
-Start here:
-
-- [Developer guide](developer-guide.md)
-- [Troubleshooting](troubleshooting.md)
-- [Debugging playbook](debugging.md)
-- [Production operations guide](operations/production-guide.md)
-- [Quick start](getting-started/quickstart.md)
-- [Local development to production](getting-started/local-to-production.md)
-- [First database](getting-started/first-database.md)
-- [First query](getting-started/first-query.md)
-- [Rails installation](rails/installation.md)
-- [Rails production guidance](rails/production.md)
-- [SQLite compatibility profile](sql/sqlite-compatibility.md)
-- [SQL compatibility contract](sql/compatibility.md)
-- [SQL compatibility guide](sql/compatibility-guide.md)
-- [Rails compatibility guide](rails/compatibility-guide.md)
-- [Production validation](production_validation.md)
-- [Production-readiness audit](production-readiness.md)
-- [Production runbook](operations/production-runbook.md)
-- [CLI guide](cli.md)
-- [CLI cheat sheet](cli-cheatsheet.md)
-- [Disaster recovery](operations/disaster-recovery.md)
-- [Monitoring and alerting](operations/monitoring.md)
-- [Workload testing](operations/workload-testing.md)
-- [Release checklist](release.md)
-- [Lessons learned](lessons-learned.md)
-
-Architecture and development:
-
-- [Current-state audit](architecture/current-state.md)
-- [Production roadmap](architecture/production-roadmap.md)
-- [Architecture overview](architecture/overview.md)
-- [Storage engine](architecture/storage-engine.md)
-- [Transactions](architecture/transactions.md)
-- [MVCC](architecture/mvcc.md)
-- [WAL](architecture/wal.md)
-- [Query planner](architecture/query-planner.md)
-- [Testing guide](contributing/testing.md)
-- [Release process](contributing/release-process.md)
-- [Branching](developer/branching.md)
-
-The root [README](../README.md) is the public project overview. The current
-production claim is intentionally bounded by the tested features and the
-deployment-specific validation described above.
-
-## Documentation map
-
-Use the guides for the complete workflow and the smaller pages for focused
-reference:
-
-* `getting-started/` gets a new Ruby or Rails application running.
-* `sql/` defines syntax, types, expressions, transactions, joins, functions,
-  and compatibility boundaries.
-* `architecture/` explains storage, WAL, recovery, MVCC, indexes, planning,
-  execution, server ownership, and replication.
-* `developer/` covers local development, snapshots, branches, temporal data,
-  database diffs, and implementation workflows.
-* `rails/` covers installation, configuration, migrations, production use,
-  compatibility, and troubleshooting.
-* `server/` covers deployment, authentication, TLS, pooling, protocol, and
-  operational behavior.
-* `operations/` covers backups, restore drills, monitoring, workload tests,
-  production procedures, and incident response.
-* `contributing/` and the root policy files cover testing, release, governance,
-  support, security, and contribution requirements.
-
-If a topic page and an implementation disagree, treat executable tests and the
-documented compatibility contract as the source of truth, then open an issue
-to reconcile the documentation.
+# RubyDB documentation index
+
+Start here:
+
+- [Developer guide](developer-guide.md)
+- [Troubleshooting](troubleshooting.md)
+- [Debugging playbook](debugging.md)
+- [Production operations guide](operations/production-guide.md)
+- [Quick start](getting-started/quickstart.md)
+- [Local development to production](getting-started/local-to-production.md)
+- [First database](getting-started/first-database.md)
+- [First query](getting-started/first-query.md)
+- [Rails installation](rails/installation.md)
+- [Rails production guidance](rails/production.md)
+- [SQLite compatibility profile](sql/sqlite-compatibility.md)
+- [SQL compatibility contract](sql/compatibility.md)
+- [SQL compatibility guide](sql/compatibility-guide.md)
+- [Rails compatibility guide](rails/compatibility-guide.md)
+- [Python adapter](../adapters/python/README.md)
+- [Production validation](production_validation.md)
+- [Production-readiness audit](production-readiness.md)
+- [Production runbook](operations/production-runbook.md)
+- [CLI guide](cli.md)
+- [CLI cheat sheet](cli-cheatsheet.md)
+- [Disaster recovery](operations/disaster-recovery.md)
+- [Monitoring and alerting](operations/monitoring.md)
+- [Workload testing](operations/workload-testing.md)
+- [Release checklist](release.md)
+- [Lessons learned](lessons-learned.md)
+- [Production journey](../lessons/01-foundations.md)
+- [Build a community adapter](../lessons/11-community-adapter.md)
+
+Architecture and development:
+
+- [Current-state audit](architecture/current-state.md)
+- [Production roadmap](architecture/production-roadmap.md)
+- [Architecture overview](architecture/overview.md)
+- [Ruby + Go accelerator](architecture/go-accelerator.md)
+- [Storage engine](architecture/storage-engine.md)
+- [Transactions](architecture/transactions.md)
+- [MVCC](architecture/mvcc.md)
+- [WAL](architecture/wal.md)
+- [Query planner](architecture/query-planner.md)
+- [Testing guide](contributing/testing.md)
+- [Release process](contributing/release-process.md)
+- [Branching](developer/branching.md)
+
+The root [README](../README.md) is the public project overview. The current
+production claim is intentionally bounded by the tested features and the
+deployment-specific validation described above.
+
+## Documentation map
+
+Use the guides for the complete workflow and the smaller pages for focused
+reference:
+
+* `getting-started/` gets a new Ruby or Rails application running.
+* `sql/` defines syntax, types, expressions, transactions, joins, functions,
+  and compatibility boundaries.
+* `architecture/` explains storage, WAL, recovery, MVCC, indexes, planning,
+  execution, server ownership, and replication.
+* `developer/` covers local development, snapshots, branches, temporal data,
+  database diffs, and implementation workflows.
+* `rails/` covers installation, configuration, migrations, production use,
+  compatibility, and troubleshooting.
+* `server/` covers deployment, authentication, TLS, pooling, protocol, and
+  operational behavior.
+* `operations/` covers backups, restore drills, monitoring, workload tests,
+  production procedures, and incident response.
+* `../lessons/` is a guided beginner-to-production journey that combines local
+  RubyDB, Rails, PostgreSQL, and hybrid microservice decisions.
+* `contributing/` and the root policy files cover testing, release, governance,
+  support, security, and contribution requirements.
+
+If a topic page and an implementation disagree, treat executable tests and the
+documented compatibility contract as the source of truth, then open an issue
+to reconcile the documentation.

data/docs/architecture/concurrency.md

@@ -1,14 +1,14 @@
-# Concurrency architecture
-
-Threads coordinate through locks, transaction ownership, the lock manager,
-buffer-pool synchronization, and server worker/connection limits. Transactions
-have connection-scoped state in server mode; the embedded owner remains one
-process.
-
-The lock manager detects wait-for cycles and selects a victim. The transaction
-manager rolls the victim back, releases its locks, and returns a retryable
-deadlock error. Timeouts and cancellation are distinct: a timeout stops a
-request deadline, while wire cancellation actively marks an in-flight request.
-
-Validate concurrency with the production soak, multi-process workload, latency
-percentiles, deadlock checks, resource limits, and durable reopen verification.
+# Concurrency architecture
+
+Threads coordinate through locks, transaction ownership, the lock manager,
+buffer-pool synchronization, and server worker/connection limits. Transactions
+have connection-scoped state in server mode; the embedded owner remains one
+process.
+
+The lock manager detects wait-for cycles and selects a victim. The transaction
+manager rolls the victim back, releases its locks, and returns a retryable
+deadlock error. Timeouts and cancellation are distinct: a timeout stops a
+request deadline, while wire cancellation actively marks an in-flight request.
+
+Validate concurrency with the production soak, multi-process workload, latency
+percentiles, deadlock checks, resource limits, and durable reopen verification.

data/docs/architecture/current-state.md

@@ -1,125 +1,125 @@
-# RubyDB current-state audit
-
-> This document is a dated architecture audit, not a statement that every
-> finding remains open. For current validation evidence, see
-> [production validation](../production_validation.md) and the latest CI runs.
-
-## Executive summary
-
-RubyDB is a broad database project with integrated storage, WAL, MVCC,
-transactions, catalog, security, server, replication, backup, Rails, and
-monitoring paths. The implementation now has substantial focused validation,
-but several deployment-level capabilities remain environment-specific or
-intentionally bounded.
-
-The primary risk is not that the code is absent; it is that multiple components exist without being integrated into a consistent, correct, durable engine. Existing code needs additional hardening before it can safely store user data.
-
-## Repository audit
-
-### Runtime and package state
-
-- Ruby runtime in the development container: Ruby 3.4.7
-- Package metadata targets Ruby >= 3.3.0; CI covers Ruby 3.3 and 3.4 on Linux,
-  macOS, and Windows.
-- The top-level library entrypoint and gem packaging are covered by
-  `require "rubydb"` and release-artifact tests.
-- The project uses Bundler and RSpec as the base test stack.
-- The repository is organized around a large `lib/rubydb` module tree and includes docs, examples, chaos, and fuzz directories.
-
-### Architectural reality
-
-The project already contains modules for:
-
-- storage engine and page manager
-- buffer pool and file management
-- WAL and recovery components
-- transactions and MVCC
-- catalog, indexes, and constraints
-- SQL parser and planner
-- server and protocol layers
-- security and authorization
-- replication, backups, and monitoring
-- Rails integration
-
-The remaining risk is uneven validation breadth: many capabilities are proven
-by focused tests, but multi-host operations, capacity limits, and complete
-external-database dialect compatibility are not yet certified.
-
-## High-risk findings
-
-### 1. Library loading (resolved)
-
-The standard Ruby consumer path is now tested:
-
-```ruby
-require "rubydb"
-```
-
-Release metadata and the local gem build verify that this loads correctly.
-
-### 2. Storage layer (partially resolved)
-
-The storage engine now has page validation, corruption detection, WAL/recovery,
-fsync paths, restart tests, subprocess crash tests, filesystem fault injection,
-and compaction/reopen coverage. Real disk-quota and power-loss validation on
-deployment filesystems remains open.
-
-### 3. Transaction and MVCC semantics (validated foundation)
-
-The transaction manager and visibility map exist, transaction rollback restores
-update/delete before-images, and read-committed, repeatable-read, serializable
-conflict, deadlock, and concurrency workload paths have regression coverage.
-Distributed isolation and deployment-specific contention limits remain open.
-
-### 4. SQL engine is a documented subset
-
-The parser, planner, and executor are covered through end-to-end tests for the
-documented RubyDB SQL subset, including joins, aggregates, CTEs, subqueries,
-set operations, upserts, and window functions. A common SQLite-style profile
-is tested for new Ruby/Rails applications; full PostgreSQL/MySQL/SQLite dialect
-and file-format compatibility remains intentionally out of scope for this
-phase.
-
-### 5. Security (validated foundation)
-
-Authentication, TLS, SCRAM, authorization, framing limits, deadlines, and
-resource-limit startup checks are tied to server/query execution and tested.
-An independent security review and production certificate/secret lifecycle
-validation remain open.
-
-### 6. Production posture is intentionally bounded
-
-The README and production documents now distinguish tested behavior from
-deployment work. RubyDB still needs environment-specific capacity, filesystem,
-multi-host failover, certificate lifecycle, and independent security validation
-before broader production claims are appropriate.
-
-## Current production posture
-
-RubyDB is best understood as:
-
-- a serious Ruby database foundation with repeatable local validation,
-- suitable for controlled workloads within the documented feature set,
-- not a drop-in general-purpose database or automatic high-availability service.
-
-The correct short-term operating posture is to treat the project as a pre-production, high-potential codebase that needs disciplined validation and narrower, correctness-first milestones.
-
-## Immediate action items
-
-1. Run the hosted Ruby/Rails/OS compatibility matrix and retain its evidence.
-2. Validate real disk quota, power-loss, and filesystem behavior on deployment targets.
-3. Validate multi-host partition, split-brain, fencing, and operator failover procedures.
-4. Complete an independent security review and certificate/secret rotation drill.
-5. Implement or intentionally reject unsupported features with explicit errors.
-6. Establish workload-specific capacity baselines and release sign-off records.
-
-The latest local audit passed 270 examples with zero failures. Hosted matrix,
-container, filesystem quota/power-loss, multi-host fencing, and independent
-security-review evidence must still be retained for a production deployment.
-
-## Conclusion
-
-RubyDB has a substantial production-oriented foundation and repeatable local
-validation. Operators must stay within the documented feature set and complete
-deployment-specific capacity, filesystem, security, and multi-host failover
-validation before entrusting critical data to it.
+# RubyDB current-state audit
+
+> This document is a dated architecture audit, not a statement that every
+> finding remains open. For current validation evidence, see
+> [production validation](../production_validation.md) and the latest CI runs.
+
+## Executive summary
+
+RubyDB is a broad database project with integrated storage, WAL, MVCC,
+transactions, catalog, security, server, replication, backup, Rails, and
+monitoring paths. The implementation now has substantial focused validation,
+but several deployment-level capabilities remain environment-specific or
+intentionally bounded.
+
+The primary risk is not that the code is absent; it is that multiple components exist without being integrated into a consistent, correct, durable engine. Existing code needs additional hardening before it can safely store user data.
+
+## Repository audit
+
+### Runtime and package state
+
+- Ruby runtime in the development container: Ruby 3.4.7
+- Package metadata targets Ruby >= 3.3.0; CI covers Ruby 3.3 and 3.4 on Linux,
+  macOS, and Windows.
+- The top-level library entrypoint and gem packaging are covered by
+  `require "rubydb"` and release-artifact tests.
+- The project uses Bundler and RSpec as the base test stack.
+- The repository is organized around a large `lib/rubydb` module tree and includes docs, examples, chaos, and fuzz directories.
+
+### Architectural reality
+
+The project already contains modules for:
+
+- storage engine and page manager
+- buffer pool and file management
+- WAL and recovery components
+- transactions and MVCC
+- catalog, indexes, and constraints
+- SQL parser and planner
+- server and protocol layers
+- security and authorization
+- replication, backups, and monitoring
+- Rails integration
+
+The remaining risk is uneven validation breadth: many capabilities are proven
+by focused tests, but multi-host operations, capacity limits, and complete
+external-database dialect compatibility are not yet certified.
+
+## High-risk findings
+
+### 1. Library loading (resolved)
+
+The standard Ruby consumer path is now tested:
+
+```ruby
+require "rubydb"
+```
+
+Release metadata and the local gem build verify that this loads correctly.
+
+### 2. Storage layer (partially resolved)
+
+The storage engine now has page validation, corruption detection, WAL/recovery,
+fsync paths, restart tests, subprocess crash tests, filesystem fault injection,
+and compaction/reopen coverage. Real disk-quota and power-loss validation on
+deployment filesystems remains open.
+
+### 3. Transaction and MVCC semantics (validated foundation)
+
+The transaction manager and visibility map exist, transaction rollback restores
+update/delete before-images, and read-committed, repeatable-read, serializable
+conflict, deadlock, and concurrency workload paths have regression coverage.
+Distributed isolation and deployment-specific contention limits remain open.
+
+### 4. SQL engine is a documented subset
+
+The parser, planner, and executor are covered through end-to-end tests for the
+documented RubyDB SQL subset, including joins, aggregates, CTEs, subqueries,
+set operations, upserts, and window functions. A common SQLite-style profile
+is tested for new Ruby/Rails applications; full PostgreSQL/MySQL/SQLite dialect
+and file-format compatibility remains intentionally out of scope for this
+phase.
+
+### 5. Security (validated foundation)
+
+Authentication, TLS, SCRAM, authorization, framing limits, deadlines, and
+resource-limit startup checks are tied to server/query execution and tested.
+An independent security review and production certificate/secret lifecycle
+validation remain open.
+
+### 6. Production posture is intentionally bounded
+
+The README and production documents now distinguish tested behavior from
+deployment work. RubyDB still needs environment-specific capacity, filesystem,
+multi-host failover, certificate lifecycle, and independent security validation
+before broader production claims are appropriate.
+
+## Current production posture
+
+RubyDB is best understood as:
+
+- a serious Ruby database foundation with repeatable local validation,
+- suitable for controlled workloads within the documented feature set,
+- not a drop-in general-purpose database or automatic high-availability service.
+
+The correct short-term operating posture is to treat the project as a pre-production, high-potential codebase that needs disciplined validation and narrower, correctness-first milestones.
+
+## Immediate action items
+
+1. Run the hosted Ruby/Rails/OS compatibility matrix and retain its evidence.
+2. Validate real disk quota, power-loss, and filesystem behavior on deployment targets.
+3. Validate multi-host partition, split-brain, fencing, and operator failover procedures.
+4. Complete an independent security review and certificate/secret rotation drill.
+5. Implement or intentionally reject unsupported features with explicit errors.
+6. Establish workload-specific capacity baselines and release sign-off records.
+
+The latest local audit passed 270 examples with zero failures. Hosted matrix,
+container, filesystem quota/power-loss, multi-host fencing, and independent
+security-review evidence must still be retained for a production deployment.
+
+## Conclusion
+
+RubyDB has a substantial production-oriented foundation and repeatable local
+validation. Operators must stay within the documented feature set and complete
+deployment-specific capacity, filesystem, security, and multi-host failover
+validation before entrusting critical data to it.

data/docs/architecture/execution-engine.md

@@ -1,25 +1,25 @@
-# Execution engine
-
-The execution pipeline is:
-
-`SQL text -> lexer -> parser/AST -> binder -> planner -> executor -> result`
-
-The planner selects scans, index scans, joins, filters, aggregates, sorting,
-limits, set operations, CTEs, subqueries, and window operations supported by
-the documented dialect. DML is routed through transaction-aware executors and
-the engine's durable mutation path.
-
-Unsupported syntax must produce an explicit parser or execution error. New
-operators and functions require type-checking, null behavior, transaction
-coverage, and compatibility documentation.
-
-## Execution invariants
-
-The executor must consume a bound plan, check cancellation and deadlines at
-bounded points, and return either a complete result or an error that leaves the
-transaction in a documented state. DML goes through the same transaction and
-WAL path as the Ruby API; a server response must never bypass durable commit.
-
-When diagnosing a result, compare parser output, bound parameters, selected
-plan, row visibility, and final serialization. See the [developer guide](../developer-guide.md)
-and [debugging playbook](../debugging.md).
+# Execution engine
+
+The execution pipeline is:
+
+`SQL text -> lexer -> parser/AST -> binder -> planner -> executor -> result`
+
+The planner selects scans, index scans, joins, filters, aggregates, sorting,
+limits, set operations, CTEs, subqueries, and window operations supported by
+the documented dialect. DML is routed through transaction-aware executors and
+the engine's durable mutation path.
+
+Unsupported syntax must produce an explicit parser or execution error. New
+operators and functions require type-checking, null behavior, transaction
+coverage, and compatibility documentation.
+
+## Execution invariants
+
+The executor must consume a bound plan, check cancellation and deadlines at
+bounded points, and return either a complete result or an error that leaves the
+transaction in a documented state. DML goes through the same transaction and
+WAL path as the Ruby API; a server response must never bypass durable commit.
+
+When diagnosing a result, compare parser output, bound parameters, selected
+plan, row visibility, and final serialization. See the [developer guide](../developer-guide.md)
+and [debugging playbook](../debugging.md).