@libredb/libredb 0.0.3 → 0.1.0

package/README.md

@@ -1,326 +1,309 @@
 # LibreDB
 
-> Status: pre-alpha. The kernel (`core.ts`) and all three lenses — `lens/kv.ts` (key-value), `lens/document.ts` (JSON documents), and `lens/relational.ts` (typed tables) — are implemented and tested.
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/img/01-hero-dark.png">
+  <img alt="LibreDB - Multi-model without the magic. One core, three lenses, every line tested." src="docs/img/01-hero-light.png" width="100%">
+</picture>
+
+**Multi-model without the magic. One core, three lenses, every line tested.**
+
+[![npm version](https://img.shields.io/npm/v/@libredb/libredb.svg)](https://www.npmjs.com/package/@libredb/libredb)
+[![CI](https://github.com/libredb/libredb-database/actions/workflows/ci.yml/badge.svg)](https://github.com/libredb/libredb-database/actions/workflows/ci.yml)
+[![Quality Gate](https://sonarcloud.io/api/project_badges/measure?project=libredb_libredb-database&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=libredb_libredb-database)
+[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=libredb_libredb-database&metric=coverage)](https://sonarcloud.io/summary/new_code?id=libredb_libredb-database)
+[![license](https://img.shields.io/npm/l/@libredb/libredb.svg)](./LICENSE)
+[![types: included](https://img.shields.io/badge/types-included-blue.svg)](https://www.typescriptlang.org/)
+[![dependencies: 0](https://img.shields.io/badge/dependencies-0-brightgreen.svg)](./package.json)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/@libredb/libredb)](https://bundlephobia.com/package/@libredb/libredb)
+[![status: pre-alpha](https://img.shields.io/badge/status-pre--alpha-orange.svg)](#project-status--roadmap)
+
+LibreDB is a small, readable, embeddable, multi-model database written in TypeScript. It is built on
+one idea: a database can be powerful and still be understood by opening its source. A single ordered
+key-value core handles durability and transactions; key-value, document, and relational APIs are thin
+*lenses* over that one core — not three separate engines. It runs in-memory for tests or file-backed
+for durability, ships **zero runtime dependencies**, and proves its crash recovery with deterministic
+simulation testing. Today it is pre-alpha, aimed at test and development environments — small enough to
+learn how a database actually works, and serious enough to grow into more.
+
+## Highlights
+
+- **One small core, three lenses** — key-value, document, and relational over a single ordered
+  key-value engine (FoundationDB-style), not three engines bolted together.
+- **Multi-model** — raw strings, JSON documents, and schema-validated typed tables in the same
+  database, even the same file.
+- **Readable by design** — the kernel is under 600 lines; open the source and learn how a database
+  actually works.
+- **Embeddable, zero dependencies** — `bun add @libredb/libredb` and go; nothing else to install or
+  run.
+- **In-memory or durable** — `open()` for tests, `open({ path })` for a crash-safe, WAL-backed,
+  fsync-on-commit file.
+- **TypeScript-native** — full types shipped, ESM-only, tree-shakeable, under 4 kB min+brotli.
+- **Crash recovery you can trust** — 100% line coverage on the core, plus deterministic simulation
+  testing that tortures the write-ahead log under a simulated crashing filesystem.
+- **Nothing hidden** — queries are plain in-engine scans, errors surface, and costs are obvious (O(n)
+  scans, no secret indexes).
+
+## Quick start
 
-**LibreDB is a small, readable, embeddable database.**
-
-It is built on one idea: a database can be powerful and still remain understandable. You should be able to open its source, learn how a database actually works, and embed it into your own product in an afternoon.
-
-- A single small storage core (`core.ts`), with relational, document, and key-value as thin *lenses* on top — not three separate engines (FoundationDB-style architecture).
-- Written in TypeScript, shipped on npm.
-- Open at the edges, guarded at the durability core. Every line of the core is tested.
-
-LibreDB is the database in a three-product family that shares one spine:
-
-- **LibreDB** — the database (this repository).
-- **LibreDB Studio** — the open-source IDE for every database (Postgres, MySQL, MongoDB, Redis, and more). LibreDB is one database it supports natively, not a requirement.
-- **LibreDB Platform** — the managed, team-oriented form of data.
-
-## Usage — the key-value lens
+```sh
+bun add @libredb/libredb
+# or: npm install @libredb/libredb
+```
 
-The first lens is `kv`: a durable, ordered, string-keyed map over the kernel. You `open` a kernel database and put a `kv` lens over it.
+LibreDB is ESM-only, ships zero runtime dependencies, and targets Bun (the development runtime) and
+Node 22+. The same database speaks all three lenses — here they are in one file:
 
 ```ts
-import { open, kv } from "libredb";
+import { open, kv, doc, table } from "@libredb/libredb";
 
-// In-memory: the natural fit for tests and ephemeral use.
+// In-memory for tests, or open({ path: "data.libredb" }) for a durable, crash-safe file.
 const db = open();
 
-// Or file-backed and durable. Every write is appended to a write-ahead
-// log and fsync'd before it returns, so a committed write survives a
-// crash; reopening the same path reconstructs exactly the committed state:
-//
-//   const db = open({ path: "data.libredb" });
-
-const store = kv(db);
+// 1. Key-value: a durable, ordered, string-keyed map.
+const cache = kv(db);
+cache.set("user:1", "Ada");
+cache.get("user:1"); // "Ada"
 
-store.set("user:1", "Ada");
-store.set("user:2", "Grace");
+// 2. Document: a collection of JSON documents under string ids.
+const logs = doc(db, "logs");
+logs.put("l1", { level: "info", message: "started", at: 1 });
+logs.find({ level: "info" }).toArray(); // [{ id: "l1", doc: { ... } }]
 
-store.get("user:1"); // "Ada"
-store.get("missing"); // undefined
+// 3. Relational: a schema-validated, typed table with where / select / join.
+const users = table(db, "users", {
+  primaryKey: "id",
+  columns: { id: "string", name: "string", age: "number" },
+});
+users.insert({ id: "1", name: "Ada", age: 36 });
+users.where({ name: "Ada" }).select("id", "age").toArray(); // [{ id: "1", age: 36 }]
 
 db.close();
 ```
 
-### Writes report what they changed
+Each lens has its own guide: [key-value](./docs/guides/key-value.md) ·
+[document](./docs/guides/document.md) · [relational](./docs/guides/relational.md) ·
+[catalog](./docs/guides/catalog.md).
 
-Every write returns a `WriteResult` (`{ changed }`), so a caller can always see what the write actually did:
+## Install elsewhere: JSR, CDN, and the browser
 
-```ts
-store.set("user:1", "Ada Lovelace").changed; // 1 (overwrote the existing value)
-
-store.delete("user:2").changed; // 1 (it existed)
-store.delete("user:2").changed; // 0 (already gone)
-```
-
-### Ordered scans
-
-Keys are ordered by byte order, so reads come back in ascending key order. `range(start, end)` scans the half-open interval `[start, end)` — `start` included, `end` excluded:
-
-```ts
-store.set("a", "1");
-store.set("b", "2");
-store.set("c", "3");
-
-store.range("a", "c").toArray();
-// [{ key: "a", value: "1" }, { key: "b", value: "2" }] — "c" is excluded
-```
+LibreDB is the same ESM-only package everywhere; only how you reach it changes.
 
-`prefix(p)` scans every key beginning with `p` — the canonical ordered-KV query:
-
-```ts
-store.prefix("user:").toArray();
-// [{ key: "user:1", value: "Ada Lovelace" }]
-```
+**JSR** — published to [jsr.io](https://jsr.io/@libredb/libredb) alongside npm:
 
-A read returns a `Result`, which is **lazy and re-iterable**: nothing runs until you iterate it (or call `toArray()`), and each pass re-runs the scan against the current state. Iterate it directly or materialize it:
-
-```ts
-for (const { key, value } of store.prefix("user:")) {
-  console.log(key, value);
-}
-```
-
-### Multi-key atomicity
-
-Each `kv` operation auto-commits in its own transaction. When you need several writes to apply atomically, drop to the kernel's `transact` directly — it commits all of the body's writes together, or nothing if the body throws:
-
-```ts
-const encode = new TextEncoder();
-
-db.transact((tx) => {
-  tx.set(encode.encode("from"), encode.encode("90"));
-  tx.set(encode.encode("to"), encode.encode("110"));
-}); // both writes commit together, or neither does
+```sh
+bunx jsr add @libredb/libredb
+# or: npx jsr add @libredb/libredb / deno add jsr:@libredb/libredb
 ```
 
-The kernel speaks raw bytes on purpose; the `kv` lens is the string-ergonomic face over it.
-
-## Usage — the document lens
-
-The `doc` lens is the JSON face over the same kernel: a *collection* of JSON documents, each stored under a string `id`. Where `kv` stores strings, `doc` stores objects — numbers stay numbers, and nested objects and arrays survive the round-trip.
+**CDN** — every release is served from the npm registry by the usual CDNs. Pin a version:
 
 ```ts
-import { open, doc } from "libredb";
-
-const db = open(); // or open({ path: "data.libredb" }) for durability
-
-const users = doc(db, "users");
-
-users.put("1", { name: "Ada", age: 36, active: true });
-users.put("2", { name: "Grace", age: 45, active: false });
-
-users.get("1"); // { name: "Ada", age: 36, active: true }
-users.get("missing"); // undefined
-
-db.close();
+import { open, kv } from "https://esm.sh/@libredb/libredb@0.1.0";
 ```
 
-Documents are scoped to their collection: `doc(db, "users")` never sees a `doc(db, "orders")` document — and the boundary is exact, so `users` and `users2` stay fully separate.
-
-### Writes report what they changed
-
-Like the kv lens, every write returns a `WriteResult` (`{ changed }`):
+**Browser** — a dedicated entry that imports nothing from `node:`, so it bundles for the browser
+cleanly. Its `open` carries no default filesystem: an in-memory database works anywhere, and a
+path-backed open takes a filesystem you inject (e.g. the OPFS adapter shown below).
 
 ```ts
-users.put("1", { name: "Ada Lovelace", age: 36 }).changed; // 1 (overwrote the existing document)
+import { open, kv } from "@libredb/libredb/browser";
 
-users.delete("2").changed; // 1 (it existed)
-users.delete("2").changed; // 0 (already gone)
+const db = open(); // in-memory
+kv(db).set("greeting", "hello");
 ```
 
-### Scanning and finding
-
-`all()` returns every document in the collection as `{ id, doc }` rows, in ascending `id` (byte) order:
+For durable storage in the browser, run inside a Web Worker and back the database with an OPFS sync
+access handle (the kernel stays synchronous — no async core):
 
 ```ts
-const people = doc(open(), "people");
-
-people.put("1", { name: "Ada", team: "research", active: true });
-people.put("2", { name: "Grace", team: "research", active: false });
-people.put("3", { name: "Edsger", team: "ops", active: true });
-
-people.all().toArray();
-// [
-//   { id: "1", doc: { name: "Ada", team: "research", active: true } },
-//   { id: "2", doc: { name: "Grace", team: "research", active: false } },
-//   { id: "3", doc: { name: "Edsger", team: "ops", active: true } },
-// ]
-```
+import { open, opfsFileSystem } from "@libredb/libredb/browser";
 
-`find(predicate)` returns the documents whose top-level fields all equal the predicate's. Multiple fields are AND'd, and equality is deep and type-sensitive — `1` does not match `"1"`:
-
-```ts
-people.find({ team: "research", active: true }).toArray();
-// [{ id: "1", doc: { name: "Ada", team: "research", active: true } }]
+const root = await navigator.storage.getDirectory();
+const file = await root.getFileHandle("app.libredb", { create: true });
+const handle = await file.createSyncAccessHandle();
+const db = open({ path: "app.libredb", fs: opfsFileSystem(handle) });
 ```
 
-`find` is an O(n) full collection scan with an in-engine predicate — there are no secondary indexes (a deliberate v1 omission, so you can read exactly what a query costs). Like every read it returns a lazy, re-iterable `Result`, so you can iterate it directly or call `toArray()`.
-
-## Usage — the relational lens
+A browser-targeting bundler resolves the browser build automatically via the package's `browser`
+export condition, so importing the main `@libredb/libredb` entry works too.
 
-The `table` lens is the *typed* face over the same kernel: a table is a schema-validated collection of rows. Where `doc` accepts any JSON object, `table` declares its columns and their types up front and enforces them at insert. A row is stored under `<table>:<pk>`, so a table is literally a schema-validated document collection — it reuses the document codec and the same collection-isolation boundary.
+## Command-line tool
 
-You declare a schema (the columns, their types, and which one is the primary key) when you open the table:
+The package ships a `libredb` bin for inspecting and editing `.libredb` files — no code required:
 
-```ts
-import { open, table } from "libredb";
-
-const db = open(); // or open({ path: "data.libredb" }) for durability
-
-const users = table(db, "users", {
-  primaryKey: "id",
-  columns: { id: "string", name: "string", age: "number", active: "boolean" },
-});
-
-users.insert({ id: "1", name: "Ada", age: 36, active: true });
-users.insert({ id: "2", name: "Grace", age: 45, active: false });
-
-users.get("1"); // { id: "1", name: "Ada", age: 36, active: true }
-users.get("missing"); // undefined
-
-db.close();
+```sh
+npx libredb inspect data.libredb          # namespaces, kinds, and table schemas
+npx libredb stats data.libredb            # file size and namespace counts
+npx libredb get data.libredb user:1       # print one value
+npx libredb scan data.libredb user:       # print key=value under a prefix
+npx libredb set data.libredb user:1 Ada   # set a key
+npx libredb delete data.libredb user:1    # remove a key
+npx libredb import data.libredb seed.json # bulk-set from a JSON object, atomically
 ```
 
-A column type is one of `"string"`, `"number"`, `"boolean"`, or `"object"` (a plain JSON object). The `primaryKey` must name a declared `"string"` column — it becomes the kernel key.
-
-### Validation is strict at insert
+Read commands open the file read-only, so inspection never mutates it. Write commands take an
+advisory `<path>.lock` to refuse a second concurrent writer; pass `--force` to override a stale lock.
 
-Insert rejects a row that is missing a declared column, has a wrong-typed value, or carries a field the schema does not declare — there is no silent coercion or field-dropping:
+Prefer a standalone binary with no Node or Bun installed? Each release attaches self-contained
+executables (Linux, macOS, Windows; x64 and arm64) with `.sha256` checksums on its
+[GitHub Release](https://github.com/libredb/libredb-database/releases). Or build one locally with
+`bun run compile`.
 
-```ts
-users.insert({ id: "3", name: "Edsger" });
-// throws: missing required column "age"
+Or run the CLI from a container (multi-arch, published to GHCR) — mount your data and pass a command:
 
-users.insert({ id: "3", name: "Edsger", age: "old", active: true });
-// throws: column "age" expected number, got string
-
-users.insert({ id: "3", name: "Edsger", age: 40, active: true, role: "ops" });
-// throws: unknown column "role" (not declared in the table schema)
+```sh
+docker run --rm -v "$PWD:/data" ghcr.io/libredb/libredb inspect /data/app.libredb
 ```
 
-### Writes report what they changed
-
-Like the other lenses, every write returns a `WriteResult` (`{ changed }`):
-
-```ts
-users.insert({ id: "1", name: "Ada Lovelace", age: 36, active: true }).changed; // 1 (overwrote)
-
-users.delete("2").changed; // 1 (it existed)
-users.delete("2").changed; // 0 (already gone)
+The image is a CLI shell, not a server: LibreDB stays an embedded, in-process database.
+
+## How it works: one core, three lenses
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/img/02-lenses-dark.png">
+  <img alt="One core, three lenses: kv, document, and relational APIs over a single ordered key-value core (core.ts), reaching disk through one FileSystem seam." src="docs/img/02-lenses-light.png" width="100%">
+</picture>
+
+LibreDB has a single ordered byte key-value kernel (`src/core.ts`). Key-value, document, and relational
+are thin typed *lenses* over it — three faces of the same store. A relational table is physically a
+JSON document collection, which is physically ordered key-value entries built from composite keys like
+`users:42`. The kernel reaches the disk through one injectable filesystem seam, which is also what
+makes deterministic crash testing possible.
+
+```mermaid
+flowchart TB
+    subgraph consumers [Consumers]
+        App[Your app]
+        Studio[LibreDB Studio]
+        Platform[LibreDB Platform]
+    end
+
+    API["Public API · index.ts<br/>open · kv · doc · table · catalog"]
+
+    subgraph lenses [Lenses and shared edges - open, fast to contribute]
+        KV[kv<br/>strings]
+        DOC[document<br/>JSON]
+        REL[relational<br/>typed tables]
+        CAT[catalog<br/>self-describing registry]
+    end
+
+    CORE["core.ts - THE KERNEL<br/>ordered byte KV · serializable txns · WAL · crash recovery"]
+    FS["FileSystem seam<br/>node:fs adapter - or SimFS for crash tests"]
+
+    App --> API
+    Studio --> API
+    Platform --> API
+    API --> KV
+    API --> DOC
+    API --> REL
+    API --> CAT
+    REL --> DOC
+    KV --> CORE
+    DOC --> CORE
+    REL --> CORE
+    CAT --> CORE
+    CORE --> FS
 ```
 
-### Querying — where, select, join
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/img/03-trust-dark.png">
+  <img alt="Open at the edges, guarded at the core: lenses, query surface, catalog, adapters, Studio, and docs are open to contribute; core.ts is guarded with 100% line coverage, deterministic crash tests, and heavy review - everything reaches the store through one narrow transact() port." src="docs/img/03-trust-light.png" width="100%">
+</picture>
 
-Reads return a chainable `Query` (which is itself a lazy, re-iterable `Result`). `where(predicate)` keeps the rows whose top-level fields all equal the predicate's — deep and type-sensitive, just like document `find`, so `36` does not match `"36"`. `select(...columns)` projects each row down to the named columns. They compose in any order:
+**The file boundary is the trust boundary.** Below the line (`core.ts`) is guarded: heavy review and
+deterministic crash tests, because a bug there corrupts data. Above the line (lenses, query, catalog)
+is open and fast to contribute to, because the worst a bug can do is present a bad *view* — it reaches
+the store only through one narrow `transact` port. For the full tour, read
+[`ARCHITECTURE.md`](./ARCHITECTURE.md).
 
-```ts
-const people = table(open(), "people", {
-  primaryKey: "id",
-  columns: { id: "string", name: "string", team: "string", active: "boolean" },
-});
+## When to use LibreDB
 
-people.insert({ id: "1", name: "Ada", team: "research", active: true });
-people.insert({ id: "2", name: "Grace", team: "research", active: false });
-people.insert({ id: "3", name: "Edsger", team: "ops", active: true });
+**Reach for it when you want to:**
 
-people.where({ team: "research", active: true }).select("name").toArray();
-// [{ name: "Ada" }]
-```
+- Back tests and local development with a real, durable, multi-model store instead of mocks.
+- Embed a small database directly in a TypeScript / Bun / Node app with zero infrastructure.
+- Learn how a database works by reading — and hacking — a small, honest codebase.
+- Prototype across key-value, document, and relational shapes without standing up three systems.
 
-`join(other, leftField, rightField)` is an inner equi-join via nested loop: it pairs each left row with every right row whose `rightField` equals the left row's `leftField`. The result rows carry every column of both sides, qualified as `table.column`, so the two sides never collide — and `select`/`where` name a qualified column the same way as any other:
+**Do not use it (yet) when you need:**
 
-```ts
-const orders = table(db, "orders", {
-  primaryKey: "id",
-  columns: { id: "string", userId: "string", total: "number" },
-});
-
-orders.insert({ id: "o1", userId: "1", total: 42 });
-orders.insert({ id: "o2", userId: "1", total: 7 });
-
-users.join(orders, "id", "userId").select("users.name", "orders.total").toArray();
-// [
-//   { "users.name": "Ada Lovelace", "orders.total": 42 },
-//   { "users.name": "Ada Lovelace", "orders.total": 7 },
-// ]
-```
-
-`where` is O(n) in the table size and `join` is O(n*m) — nested-loop, no indexes (the same deliberate v1 omission as the document lens). Unmatched rows on either side are dropped (inner join), and a left key matching several right rows fans out to several result rows.
-
-## The catalog — what a database holds
+- A hardened production datastore at scale — it is **pre-alpha**; today's beachhead is test/dev.
+- Secondary indexes or a query planner — queries are O(n) scans by design in v1 (on the roadmap).
+- Concurrent multi-process access, replication, or a networked client/server — it is embedded and
+  in-process.
+- SQL wire compatibility or an existing-driver ecosystem.
 
-Open a LibreDB file cold and the bytes alone don't say which lens each namespace belongs to. The catalog records that as you write: a `table` registers `{ kind: "relational", schema }` when its handle is built, and a `doc` collection registers `{ kind: "document" }` on its first write. `catalog(db)` reads the whole registry — a `Map` from namespace name to its entry — so a tool can render faithful per-kind views without guessing:
+These limits are deliberate v1 scope, not hidden gaps — LibreDB's strength comes from what it refuses.
+See the [Manifesto](./MANIFESTO.md).
 
-```ts
-import { open, table, doc, catalog } from "libredb";
+## Reliability
 
-const db = open();
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/img/04-reliability-dark.png">
+  <img alt="Crash recovery you can trust: a length-framed, CRC-32-checksummed write-ahead log fsync'd before commit; recovery truncates the last un-fsync'd record so what remains is always a valid committed prefix - proven by deterministic simulation testing." src="docs/img/04-reliability-light.png" width="100%">
+</picture>
 
-table(db, "users", { primaryKey: "id", columns: { id: "string", age: "number" } });
-doc(db, "logs").put("l1", { message: "hello" });
+A transaction that returns has been written to a length-framed, CRC-32-checksummed write-ahead log and
+`fsync`'d *before* the commit becomes visible — so a committed write survives a crash, and a crash can
+only ever damage the last, un-fsync'd record (which recovery detects and truncates). This is not just
+asserted: the kernel's crash/recovery path is proven by **deterministic simulation testing**, running
+the real engine against a seeded in-memory filesystem that tears, corrupts, and crashes the log on
+command, then checking that recovery is always a valid committed prefix.
 
-const registry = catalog(db);
-registry.get("users");
-// { kind: "relational", schema: { primaryKey: "id", columns: { id: "string", age: "number" } } }
-registry.get("logs");
-// { kind: "document" }
-[...registry.keys()].sort();
-// ["logs", "users"]
+```sh
+bun run test    # includes a bounded 50-seed DST run
 ```
 
-The catalog lives under a reserved key prefix that sorts below all user data, so its entries never appear in a `kv`, `doc`, or `table` scan — and no user row leaks into the registry. `kv` namespaces are deliberately not cataloged: `kv` is the raw layer with full keyspace access.
-
-A tool that renders the raw `kv` layer (so it sees everything, including the catalog) should hide those engine-internal keys. Rather than hardcode the byte layout, import the contract: `isReservedKey(key)` is true for any key in the reserved namespace, and `RESERVED_MARKER` / `CATALOG_PREFIX` are the underlying constants if you need to build a range.
-
-```ts
-import { open, kv, isReservedKey } from "libredb";
-
-const db = open();
-// ... user writes through doc/table, which also write catalog entries ...
-
-const visible = kv(db).range("", "￿").toArray().filter((e) => !isReservedKey(e.key));
-// only user keys; catalog entries (under the reserved marker) are filtered out
-```
+The full durability and DST walkthrough is in [`docs/RELIABILITY.md`](./docs/RELIABILITY.md).
 
-## Reliability — deterministic simulation testing
+## Documentation
 
-Durability is the trust-critical promise: a transaction that returns has been fsync'd, and a crash can only ever damage the last, un-fsync'd record. LibreDB proves this with **deterministic simulation testing (DST)** — the WAL's crash/recovery path is tortured under a seeded, in-memory simulated filesystem. The kernel reaches the disk only through an injectable FS seam (`open({ path, fs })`), so a test can run the real engine on a `SimFS` that crashes on command, tears the un-fsync'd tail at a seeded point, and injects CRC corruption or short reads.
+| Topic | Where |
+|-------|-------|
+| Lens guides (kv, document, relational, catalog) | [`docs/guides/`](./docs/guides/) |
+| Architecture — the guided tour under the hood | [`ARCHITECTURE.md`](./ARCHITECTURE.md) |
+| Design — the locked engineering decisions | [`docs/DESIGN.md`](./docs/DESIGN.md) |
+| Reliability — durability and crash recovery | [`docs/RELIABILITY.md`](./docs/RELIABILITY.md) |
+| Manifesto — what LibreDB is and refuses to be | [`MANIFESTO.md`](./MANIFESTO.md) |
+| LibreDB Studio integration | [`docs/STUDIO.md`](./docs/STUDIO.md) |
 
-Every run is driven by one integer seed and a seeded workload of `set`/`delete`/`transact` operations. After the crash and reopen, recovery must reproduce **a valid committed prefix** of the workload — every transaction that returned successfully, and never a torn or un-committed one. An independent committed-map model (sharing no code with the engine) is the oracle the recovered state is compared against.
+## Project status & roadmap
 
-The DST suite runs as part of the normal gate:
+LibreDB is **pre-alpha** (`0.0.x`). The architecture is in place and every line of the core is tested,
+but the API may still change and it is not yet meant for production data.
 
-```sh
-bun run test            # runs a bounded 50 seeds (fast, CI-friendly)
-```
+- **Done:** the ordered key-value kernel (transactions, WAL, crash recovery); the key-value, document,
+  and relational lenses; the self-describing catalog; the deterministic simulation testing harness;
+  100% line/function/statement coverage on the core.
+- **Next:** secondary indexes and a richer query surface; more query operators; additional lenses;
+  production-hardening milestones (directory fsync on first create, WAL compaction/checkpointing).
 
-Run a longer soak by raising the seed count (and optionally the base seed):
+## The LibreDB family
 
-```sh
-LIBREDB_DST_SEEDS=5000 bun test src/sim/dst.test.ts
-LIBREDB_DST_BASE=1000000 LIBREDB_DST_SEEDS=5000 bun test src/sim/dst.test.ts
-```
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/img/05-family-dark.png">
+  <img alt="The LibreDB family: LibreDB (the database, this repo), LibreDB Studio (the open-source IDE for every database), and LibreDB Platform (the managed, team-oriented form of data) - three products, one access-model spine." src="docs/img/05-family-light.png" width="100%">
+</picture>
 
-When a seed fails, the suite prints the exact replay hint — `Replay with runSeed(<seed>)`. Because everything is seed-driven, one seed reproduces the whole run byte-for-byte:
+LibreDB is the database in a three-product family that shares one access-model spine:
 
-```ts
-import { runSeed } from "./src/sim/dst.ts";
+- **LibreDB** — the database (this repository).
+- **LibreDB Studio** — the open-source IDE for *every* database (Postgres, MySQL, MongoDB, Redis, and
+  more). LibreDB is one database it supports natively, not a requirement.
+- **LibreDB Platform** — the managed, team-oriented form of data.
 
-const result = runSeed(42);
-result.passed;     // true — recovered state is a valid committed prefix
-result.recovered;  // Map of the recovered committed key-value state
-result.expected;   // the model oracle's committed state
-```
+## Contributing
 
-The DST harness lives in `src/sim/` and is excluded from the published package — it is test machinery, not shipped code.
+Contributions are welcome. LibreDB is open at the edges and guarded at the durability core — see
+[`CONTRIBUTING.md`](./CONTRIBUTING.md) for how to get set up, the `bun run gate` bar every change must
+pass, and where contributions land fastest. Please also read the
+[`CODE_OF_CONDUCT.md`](./CODE_OF_CONDUCT.md).
 
-## Read first
+## Security
 
-- [`MANIFESTO.md`](./MANIFESTO.md) — what LibreDB is and what it refuses to be.
-- [`DESIGN.md`](./DESIGN.md) — the engineering decision record behind the manifesto.
+To report a security vulnerability, see [`SECURITY.md`](./SECURITY.md) — please do not open a public
+issue.
 
 ## License
 
-Open source and free under the MIT License.
+Open source and free under the [MIT License](./LICENSE).

package/dist/adapter/node-fs.d.ts

@@ -0,0 +1,3 @@
+import type { FileSystem } from "../core.ts";
+/** Build the default node:fs-backed {@link FileSystem}. */
+export declare function nodeFileSystem(): FileSystem;

package/dist/adapter/node-fs.js

@@ -0,0 +1,49 @@
+/**
+ * adapter/node-fs.ts — the default {@link FileSystem} for Node and Bun.
+ *
+ * This is an edge, not the kernel (DESIGN.md section 5): it holds the one place
+ * LibreDB touches `node:fs`. The kernel (`core.ts`) is runtime-agnostic and
+ * imports nothing from `node:`; it reaches the disk only through the injected
+ * {@link FileSystem} seam. Keeping the node dependency HERE — and out of the
+ * kernel — is what lets the browser entry (`browser.ts`) ship without dragging
+ * `node:fs` into its import graph. The default Node entry (`index.ts`) wires this
+ * adapter in as the default `fs`, so production behaviour is unchanged.
+ *
+ * Each method is the obvious synchronous syscall, so the adapter adds an
+ * interface boundary, not behaviour. Appends go through one append-mode
+ * descriptor (creating the file if missing); reads, size and truncate work by
+ * path, matching how the WAL has always reached the disk.
+ */
+import { closeSync, fsyncSync, openSync, readFileSync, statSync, truncateSync, writeSync } from "node:fs";
+/** Build the default node:fs-backed {@link FileSystem}. */
+export function nodeFileSystem() {
+    return {
+        open(path) {
+            const fd = openSync(path, "a"); // append-only; creates the file if missing
+            return {
+                size() {
+                    return statSync(path).size;
+                },
+                read(offset, length) {
+                    // A fresh Uint8Array so the returned slice is an independent copy, not
+                    // a view aliasing a shared Buffer pool.
+                    return new Uint8Array(readFileSync(path)).subarray(offset, offset + length);
+                },
+                append(bytes) {
+                    for (let written = 0; written < bytes.length;) {
+                        written += writeSync(fd, bytes, written);
+                    }
+                },
+                fsync() {
+                    fsyncSync(fd);
+                },
+                truncate(length) {
+                    truncateSync(path, length);
+                },
+                close() {
+                    closeSync(fd);
+                },
+            };
+        },
+    };
+}