# RatDB Overnight Engineering Report
**2026-11-06 | RatDB 0.1.0 | Alpha | code checkpoint 5974dcc**

## Executive summary
RatDB can now commit a related set of records atomically in embedded applications, page through a growing den, and restore a verified offline backup into a fresh instance. The work retains v1 storage and tightens recovery: ordinary callers cannot continue on a visibly ambiguous header. The principal remaining scaling limit is writes: even 16 tiny replacements in a 100,000-record database rewrote 4.8 MB.

## Completed work
- Storage: audited both banks and all barriers, added read-only inspection, strict existing-file access and exclusive creation, indexed range seeks, atomic sorted batches and configurable sparse-index size. New Unix files default to owner-only access.
- Applications: durable empty warrens/dens, guarded drop, insert-if-absent, field updates, ordered cursor pages, embedded handles and atomic cross-den write sets. Script mode emits JSON; interactive reconnect never retries an uncertain write.
- Operations: document-aware integrity checks, status/stats/version, locked offline copy with no-overwrite publication, independent format inspector. Frame limits apply before body allocation. Slow or broken sessions are tested. Passwords stay local and remote traffic requires an encrypted tunnel.
- Clients and examples: typed Rust and Python sessions; reproducible website identity/session and CRM data workflows; Asterhold and constrained-memory workloads. Learning exercises and the frontier design review are in docs/learning and FRONTIER_DESIGN.md.

## Verification
All counts below are this run. Windows used GNU Rust 1.99.1; Ubuntu under WSL2 used Linux x86_64 Rust 1.90.0. Both ran debug Rust tests and exercised the actual optimized host CLI, server and crash worker. WSL2 provides Linux runtime evidence, not native Linux power-loss evidence.

|Final gate|Windows x86_64|Linux x86_64|
|---|---|---|
|cargo test --locked --workspace --all-targets|50 passed, 0 failed|50 passed, 0 failed|
|cargo test --locked -p ratdb-core --no-default-features --lib|16 passed, 0 failed|16 passed, 0 failed|
|Workspace doctests|Passed, 0 examples|Passed, 0 examples|
|rustfmt, strict all-targets Clippy, locked release builds|Passed|Passed|
|Release CLI, default paths, server/shell, crash, backup, independent inspector, Python client|7 suites passed|7 suites passed|
|Real PTY password entry|Not applicable: POSIX PTY harness; native Windows echo not verified in this run|Passed (8th release suite)|
|Machine power loss, real Asterhold/target hardware, Linux ARM64 runtime|Not run|Not run|

The 50 comprise 4 CLI unit, 2 CLI workflow, 18 core, 4 adapter, 9 document and 13 server/auth/client tests. Release suites include 20 process termination/reopen cases per OS, 3 backup tests and 4 Python client tests per OS. The core model uses 1,200 reproducible mutations. Additional checks compile the no_std library for thumbv7em-none-eabi and x86_64-unknown-none; neither target was executed. The initial default Windows MSVC build failed at the linker; the installed GNU toolchain passed. No tests were disabled to obtain these results.

Reproduce using **python -B scripts/verify.py stable-x86_64-pc-windows-gnu** on this Windows machine, or **python3 -B scripts/verify.py** with Linux Cargo on PATH. The script lists exact commands, honors CARGO_TARGET_DIR, and launches each release suite against disposable databases. For ARM use **cargo check --locked -p ratdb-core --no-default-features --lib --target thumbv7em-none-eabi**.

## Storage and recovery
The writer invalidates and syncs the inactive header, streams and syncs a complete new snapshot, then writes and syncs its header before acknowledging. Only then does it publish the new in-memory generation and offsets. Crashes during publication can leave either complete generation, or a visibly ambiguous header that refuses normal open. A failed write may already have committed; inspect/reconcile before retrying. The tests cover 65 publication prefixes, 65 invalidation prefixes, short writes, partially persisted resizes, failed barriers including durable-but-failed sync, successive interruptions and 32 seeded scattered-write schedules. They do not prove a device honors flush or isolates torn sectors. Complete erasure of the newest header remains indistinguishable from intentional invalidation. See [recovery audit](RECOVERY_AUDIT.md).

Existing v1 databases need no migration. Legacy collections remain in the default warren. Physical v1 layout stays unchanged; W1 and catalog C1 are document-level encodings. Do not downgrade after using new namespace encodings. Never mix arbitrary core binary records into a document instance. No migration to a page format was attempted.

## Resource consumption
- Final release executable: Windows GNU **853,504 bytes**; Linux GNU **978,512 bytes**. Windows imports system/UCRT DLLs; Linux build requires glibc and libgcc_s. Not qualified on older OS versions.
- File-backed core, 200 binary records: **512 B** incremental steady heap, **1,416 B** peak, **1,920 KiB** maximum process RSS. Mean durable update around **8.1 ms** on Linux /tmp. [Workload and SQLite comparison](MEASUREMENTS_V1.md).
- Local server, 1,000 documents: **2,580 KiB** ready RSS, **21,696 KiB** peak during authentication, **0.142 ms** median point read. Zero CPU ticks charged in one five-second idle sample. These figures reflect the profiled development build and workload. [Server and JSON heap profiles](RESOURCE_PROFILE_V1.md).
- Memory adapter, 100 to 100,000 records: point reads averaged **1.21 to 121.79 us**; batch updates wrote **4,928 to 4,800,128 bytes**. No device flush latency is represented. [Full measurements](STORAGE_SCALING_V1.md). No strict total-RSS cap is claimed.

## Application readiness
Suitable for evaluating a small local application: stable ID namespace, insert-only ID uniqueness, atomic field updates, bounded equality queries/pages, backup/restore, and real clients. Separate cursor requests observe current committed data; they do not share a snapshot. Only embedded write sets are atomic across documents; shell batch is a sequence of independent commands. There are no unique secondary fields, foreign keys, network transactions, per-warren roles, or online backup. Test the expected write rate, recovery and backup policy before relying on it for a live website or CRM.

## Asterhold readiness
The no_std + alloc core, exact-I/O contract, block and filesystem examples, and transport-independent dispatch are available. Asterhold must provide exclusive ownership, allocator, durable flush and length semantics, error propagation and a startup/recovery path independent of RatDB. A resident service may use native IPC; TCP is optional. The dispatch/document implementation uses host std; do not assume the whole server is bare-metal compatible. [Integration contract](ASTERHOLD_INTEGRATION_V1.md). No Asterhold code changed.

## Release status and known limitations
Alpha. Internal review and automated tests support evaluation, not a general production or durability certification. V1 still has fixed capacity and O(live bytes) writes/reopen. CRC cannot detect every media failure or valid stale-record replay. All clients share one administrator and a serialized database; Argon2, JSON trees and thread stacks sit outside core buffer limits. Offline copies require hard links at the destination and fresh credentials after restore. No native hardware power-cut campaign, native Windows console echo automation, Linux ARM64 runtime or extended endurance run was performed. No shell history or tab completion. There is no external repository, deployment or background engineering job.

## Next engineering priorities
1. Verify acknowledged commits under physical power cuts on named device/filesystem combinations, including flush and header erasure behavior.
2. Prototype a separate copy-on-write page format with bounded reclaim and a crash-tested migration; benchmark it against v1 before adoption.
3. Run the adapter tests against Asterhold's actual storage and IPC services.
4. Measure tail latency, amplification and memory under sustained, nearly-full workloads on native Linux and Windows machines.
5. Validate application needs for conditional multi-record network writes, secondary uniqueness and snapshot-consistent pagination.

## Getting started
From the checkout, install with **cargo install --locked --path crates/ratdb-cli** (use **cargo +stable-x86_64-pc-windows-gnu install --locked --path crates/ratdb-cli** on this Windows host). The release binary also runs directly. For the default instance use **ratdb init**, then **ratdb serve**. Init provisions the default administrator; **ratdb setup** finishes an interrupted default credential setup. Do not initialize over an existing instance.

For a disposable named example, run these shell commands in a private directory, on Windows PowerShell or Bash:

~~~text
ratdb init ./demo.ratdb
ratdb setup ./demo.ratdb admin
ratdb serve ./demo.ratdb
~~~

In a second terminal run **ratdb**, authenticate, then enter:

~~~text
create warren garage
use garage
create den cars
use cars
insert car:001 {"make":"Ford","year":2021}
update car:001 {"year":2022}
get car:001
find make=Ford
page 10
exit
~~~

Stop the server with Ctrl+C. Use fresh destination names:

~~~text
ratdb status ./demo.ratdb
ratdb backup ./demo.ratdb ./nightly.ratdb
ratdb restore ./nightly.ratdb ./restored.ratdb
ratdb check ./restored.ratdb
ratdb setup ./restored.ratdb admin
ratdb serve ./restored.ratdb
~~~

See [Rust](RUST_CLIENT.md), [Python](PYTHON_CLIENT.md), [embedded batches](EMBEDDED_DOCUMENTS.md) and [learning exercises](learning/README.md). Existing shiny.ratdb and its credential registry were excluded from Git and never used as test fixtures.

## Git checkpoints
Local history in chronological order; the final documentation commit follows the tested code checkpoint.
- 0a2b2fa Baseline existing RatDB workspace without instance data or credentials
- d8efbb2 Add a Python protocol client and exercise website and CRM workloads
- 6cee3db Refuse ambiguous recovery and preserve damaged media for inspection
- 03ccf07 Demonstrate Asterhold block and filesystem storage contracts
- b526db4 Add locked and verified offline backup and restore commands
- 2e8a93c Seek with bounded sparse offsets and commit sorted batches atomically
- ffce743 Accept every provisionable password within a bounded authentication frame
- 52cef10 Add atomic document edits, cursor pages and a scriptable authenticated shell
- db5946f Teach RatDB through a verified store, query and restore exercise
- 7797923 Expose authenticated Rust document sessions and paged client workflows
- 1cf4d7d Bound sparse index memory and independently verify v1 files
- 0f896ae Add embedded document batches and exercise torn invalidation and resize
- 3c14703 Measure Linux server resources and constrained JSON heap usage
- e303d7e Persist explicit namespaces and refuse drops with children or documents
- 8698f3f Bound whole client replies and verify slow and incomplete connection recovery
- 858d7f9 Allow smaller server request, document and lookup budgets
- 98e9ac7 Validate document and catalog semantics during integrity checks and backup
- 5974dcc Test scattered persistence failures and automate host release checks