# Architecture

PageLens keeps byte safety, format interpretation, cross-page analysis, and
presentation separate.

## Data flow

1. The CLI reads a file into immutable Bytes using moonbitlang/x/fs.
2. BinaryReader establishes a bounded range and checks every seek and read.
3. DatabaseImage validates the SQLite header and converts page numbers to
   checked offsets.
4. Page and B-tree parsers decode headers, pointer arrays, cells, records,
   overflow payloads, and freelists.
5. WalFile validates the WAL checksum chain and discovers commit boundaries.
6. SnapshotView overlays only the latest valid committed occurrence of a page.
7. IntegrityReport catches local parser failures and emits stable diagnostics.
8. Report functions serialize the same model as readable text or JSON.

## Safety invariants

- A parser indexes bytes only after a range check.
- SQLite page numbers are one-based and validated before offset conversion.
- Overflow and freelist chains keep visited-page sets to stop loops.
- WAL frames influence snapshots only when salt and cumulative checksum checks
  pass and a valid later commit includes them.
- No core type owns a writable file handle.
- The CLI imports read functions only; it exposes no write command.

## Package layout

The root package is the reusable parser library. Tests next to each module are
black-box consumers of its public API. cmd/pagelens is the executable package.
tests verifies that another package can import the library. Generated fixture
binaries are deliberately outside the published archive; the deterministic
generator is included.

## Error model

ParseError represents unsafe or impossible local input: truncation, invalid
ranges, illegal values, page bounds, integer overflow, and unsupported
features. Diagnostic represents a finding that can coexist with more analysis.
The checker converts recoverable ParseError values into INFO, WARNING, or ERROR
items, allowing multiple defects to be reported in one pass.

## Determinism

Page and frame traversal follows on-disk order. Diagnostics are appended in
validation order. JSON fields and arrays therefore remain stable for identical
input bytes and options, which makes the CLI suitable for CI comparisons.