Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 28 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -86,6 +86,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
string-matches error output is affected, including the interactive REPL's
printed error messages and all 7 language-binding repos (Python, Node,
WASM, Java, Android, Swift, C).
- **Storage/file-format errors now surface their real `STG-0xx` code** (#359,
part of #277's rollout): all 27 documented `STG-0xx` codes are wired up
across `src/storage/{mod,persistent_facts,btree,btree_v6,packed_pages}.rs`
and `src/storage/backend/file.rs` — header validation (`STG-001`–`STG-009`),
header re-read failures (`STG-010`), on-disk B+tree/packed-page corruption
(`STG-011`–`STG-015`), a poisoned backend mutex (`STG-016`), page-count
arithmetic overflow guards (`STG-017`–`STG-024`), and the three lock
conflict errors (`STG-025`–`STG-027`). `docs/ERROR_REFERENCE.md`'s STG
section's "Error text" lines were rewritten from one-off example values to
canonical `{}`-placeholder templates so they byte-for-byte match the
`REGISTRY` entries the sync test checks against.
`FileBackend::open_with` no longer collapses a more specific header-parse
failure (e.g. a bad magic number) into the generic `STG-010` — it now
propagates a `CodedError` already present in the chain as-is, only falling
back to `STG-010` for a genuinely uncoded (e.g. raw I/O) failure.
Not covered by a dedicated regression test: `STG-011`'s call site is
guarded by a `debug_assert!` that always fires first in a debug/test
build, so it's release-build-only and unreachable under `cargo test`; the
8 arithmetic-overflow guards (`STG-017`–`STG-024`) and `STG-027` (a
filesystem that refuses locking outright — no CI runner provides one) are
covered by the registry↔doc sync test and code review but have no
dedicated trigger test, consistent with their own "should not occur under
normal operation" documentation. Two `bail!` sites with no matching
documented `STG` code ("Header checksum mismatch", reached on a genuine
on-disk corruption of an otherwise-valid header, and `into_backend`'s
multiple-owners precondition) were deliberately left uncoded (`INT-000`)
rather than assigned an undocumented code — left for the final API+INT
audit PR.
- **`src/wal.rs`'s errors now carry real `WAL-0xx` codes instead of falling
back to `INT-000`** (#360, toward #277): a bad `.wal` magic number is
`WAL-001`, an unsupported WAL version is `WAL-002`, a fact whose serialised
Expand Down
34 changes: 17 additions & 17 deletions docs/ERROR_REFERENCE.md
Original file line number Diff line number Diff line change
Expand Up @@ -1620,7 +1620,7 @@ See the [file format section in README](../README.md#file-format) for version hi

### STG-001 Invalid header: too short

**Error text**: `Invalid header: too short (got 12 bytes, need 64)`
**Error text**: `Invalid header: too short (got {} bytes, need 64)`

**Cause**: The `.graph` file is truncated — shorter than the minimum header size. Happens if the file was partially written (e.g. a crash during the initial `save()`) or if a non-Minigraf file was passed by mistake.

Expand All @@ -1642,7 +1642,7 @@ See the [file format section in README](../README.md#file-format) for version hi

### STG-003 Invalid v4/v5/v6 header too short

**Error text**: `Invalid v4/v5/v6 header: expected at least 72 bytes, got 40`
**Error text**: `Invalid v4/v5/v6 header: expected at least 72 bytes, got {}`

**Cause**: A file identified as format version 4, 5, or 6 is too short to hold a valid header of that version. The file is truncated at the header.

Expand All @@ -1653,7 +1653,7 @@ See the [file format section in README](../README.md#file-format) for version hi

### STG-004 Invalid v6 header too short

**Error text**: `Invalid v6 header: expected 80 bytes, got 64`
**Error text**: `Invalid v6 header: expected 80 bytes, got {}`

**Cause**: A file identified as format version 6 is shorter than the required 80-byte v6 header. The file is truncated.

Expand All @@ -1664,7 +1664,7 @@ See the [file format section in README](../README.md#file-format) for version hi

### STG-005 Invalid v7 header too short

**Error text**: `Invalid v7 header: expected 84 bytes, got 80`
**Error text**: `Invalid v7 header: expected 84 bytes, got {}`

**Cause**: A file identified as format version 7 (current format) is shorter than the required 84-byte header. The file is truncated.

Expand All @@ -1675,7 +1675,7 @@ See the [file format section in README](../README.md#file-format) for version hi

### STG-006 Unsupported format version

**Error text**: `Unsupported format version: 8 (supported: 1-7)`
**Error text**: `Unsupported format version: {} (supported: 1-{})`

**Cause**: The file was written by a newer version of Minigraf than is currently installed. The format version number in the header is outside the range this library can read.

Expand All @@ -1697,7 +1697,7 @@ See the [file format section in README](../README.md#file-format) for version hi

### STG-008 eavt_root_page must be less than page_count

**Error text**: `eavt_root_page (500) must be less than page_count (100)`
**Error text**: `eavt_root_page ({}) must be less than page_count ({})`

**Cause**: The EAVT B+tree root page index in the header points beyond the file's page count. The header is internally inconsistent — a sign of file corruption.

Expand All @@ -1708,7 +1708,7 @@ See the [file format section in README](../README.md#file-format) for version hi

### STG-009 fact_page_count cannot exceed page_count

**Error text**: `fact_page_count (200) cannot exceed page_count (100)`
**Error text**: `fact_page_count ({}) cannot exceed page_count ({})`

**Cause**: The fact page count in the header is larger than the total page count. The header is internally inconsistent.

Expand All @@ -1719,7 +1719,7 @@ See the [file format section in README](../README.md#file-format) for version hi

### STG-010 Failed to read header from existing file

**Error text**: `Failed to read header from existing file: permission denied`
**Error text**: `Failed to read header from existing file: {}`

**Cause**: A low-level I/O error prevented reading the file header. Common causes: file permissions, file moved or deleted between open and read, disk I/O error.

Expand All @@ -1741,7 +1741,7 @@ See the [file format section in README](../README.md#file-format) for version hi

### STG-012 Expected index page at page N

**Error text**: `Expected index page at page 42`
**Error text**: `Expected index page at page {}`

**Cause**: The B+tree traversal expected an index page at a specific page number, but the page found has a different type tag. This indicates index corruption or file truncation.

Expand All @@ -1752,7 +1752,7 @@ See the [file format section in README](../README.md#file-format) for version hi

### STG-013 range_scan expected leaf

**Error text**: `range_scan: expected leaf at page_id=87`
**Error text**: `range_scan: expected leaf at page_id={}`

**Cause**: A range scan of the B+tree expected a leaf page at a given position but found a non-leaf page. Indicates corruption of the B+tree structure.

Expand All @@ -1763,7 +1763,7 @@ See the [file format section in README](../README.md#file-format) for version hi

### STG-014 Expected packed page type

**Error text**: `Expected packed page (0x02), got 0x01`
**Error text**: `Expected packed page (0x02), got 0x{}`

**Cause**: A page expected to contain packed facts has a different page type tag. Indicates that the page layout in the file does not match the header's page allocation records.

Expand All @@ -1774,7 +1774,7 @@ See the [file format section in README](../README.md#file-format) for version hi

### STG-015 Record extends beyond page boundary

**Error text**: `Record at slot 14 extends beyond page boundary`
**Error text**: `Record at slot {} extends beyond page boundary`

**Cause**: A fact record at the given slot in a packed-facts page extends past the 4KB page boundary. This indicates corruption of the page's internal offset table.

Expand Down Expand Up @@ -1829,7 +1829,7 @@ See the [file format section in README](../README.md#file-format) for version hi

### STG-020 Fact index exceeds u16::MAX

**Error text**: `fact index 65536 exceeds u16::MAX`
**Error text**: `fact index {} exceeds u16::MAX`

**Cause**: The number of facts on a single packed page exceeded 65535 (u16::MAX). This is a theoretical limit that should not be reached in practice — a single 4KB page holds roughly 20–30 facts.

Expand Down Expand Up @@ -1862,7 +1862,7 @@ See the [file format section in README](../README.md#file-format) for version hi

### STG-023 Page index exceeds u64::MAX

**Error text**: `page index 18446744073709551616 exceeds u64::MAX`
**Error text**: `page index {} exceeds u64::MAX`

**Cause**: A page index computation produced a value larger than u64::MAX. This is practically unreachable — would require a database with more pages than u64 can represent.

Expand All @@ -1886,7 +1886,7 @@ See the [file format section in README](../README.md#file-format) for version hi

### STG-025 Database already open in this process

**Error text**: `Database is already open in this process ({path}). A second handle on one file would give each its own page table and corrupt both — reuse the existing handle instead. \`Minigraf\` is cheap to clone and all clones share the same database.`
**Error text**: `Database is already open in this process ({}). A second handle on one file would give each its own page table and corrupt both — reuse the existing handle instead. `Minigraf` is cheap to clone and all clones share the same database.`

**Cause**: This process already holds an open handle on this file. Two `FileBackend` instances on one file each cache their own `header.page_count`, allocate new pages from that count, and bounds-check reads against it, so the two page tables diverge and produce intermittent `Page N out of bounds` errors.

Expand All @@ -1900,7 +1900,7 @@ See the [file format section in README](../README.md#file-format) for version hi

### STG-026 Database locked by another process

**Error text**: `Database is locked by another process ({path}). The lock is held on the file itself and is released automatically when the holding process exits, so there is no lock file to clean up.`
**Error text**: `Database is locked by another process ({}). The lock is held on the file itself and is released automatically when the holding process exits, so there is no lock file to clean up.`

**Cause**: Another process holds the kernel file lock on this `.graph` file. Minigraf is single-writer: one process at a time. This is reported only after a bounded retry (up to ~375ms) rules out a transient `fork`-related false positive — see the Unreleased CHANGELOG entry on the bounded retry.

Expand All @@ -1915,7 +1915,7 @@ See the [file format section in README](../README.md#file-format) for version hi

### STG-027 Filesystem does not support file locking

**Error text**: `Failed to lock database at {path}: {e}. This filesystem does not support file locking (common on NFSv3 without lockd, and on some FUSE mounts). Set \`allow_unlocked\` in \`OpenOptions\` to open anyway — that accepts the risk that concurrent writers corrupt the file.`
**Error text**: `Failed to lock database at {}: {}. This filesystem does not support file locking (common on NFSv3 without lockd, and on some FUSE mounts). Set `allow_unlocked` in `OpenOptions` to open anyway — that accepts the risk that concurrent writers corrupt the file.`

**Cause**: The underlying filesystem rejected the lock outright. Common on NFSv3 mounts with no `lockd` running, and on some FUSE filesystems. Because the file must exist before it can be locked, this refusal can leave a 0-byte `.graph` file behind; the next open sees `is_new` and initialises normally.

Expand Down
Loading
Loading