feat: read-only open — OpenOptions::read_only (#429) - #464

Part of #429 (Rust API; exposing open_with_options with read_only, page_cache_size and allow_unlocked in the bindings is #465).

What

OpenOptions::read_only(true) opens a database so that nothing done through the handle writes to the .graph file or its WAL.

• Shared lock. The file is locked with try_lock_shared, so any number of read-only handles can hold it, in this process or in others. A read-only handle and a read-write handle refuse each other with the existing STG-025 or STG-026, with the same retry budget. While a reader is open, no writer can change the file or the WAL under it. The in-process registry (OPEN_PATHS) now records either one writer or a count of readers, so STG-025 still means "this process holds a conflicting handle". allow_unlocked admits many readers or one writer, never both.
• Same view, nothing written:
  • A WAL from an earlier session is applied in memory. It is not checkpointed or deleted, and no WAL is created.
  • A format v7 file is read into memory as uncheckpointed facts, not migrated. Its migration happens on the next read-write open. Memory is O(facts) for such files only.
  • An empty file (or a torn initial meta) opens as an empty database and is not initialised.
  • A torn page 0 after a migration is read through the backup meta and not restored.
  • A missing file is the new STG-042, and nothing is created.
• Refusals. transact, retract, begin_write, checkpoint and rebuild_indexes fail with the new API-014 before a tx count is taken. Queries, cursors, fact_log, verify, prepare, UDFs and rule registration (memory only) work. Dropping the handle does not checkpoint. The same refusals apply to read_only on an in-memory database.
• Backstop. The shared-mode backend refuses write_page and sync with the new INT-056. If a check is ever missed, the call fails rather than writing.
• page_cache_size already serves every committed page read, so it applies unchanged. The docs now say how to keep the whole file in memory (file_size / 4096 pages).

Design: docs/superpowers/specs/2026-10-07-read-only-open-design.md

Tests

1329 total (1320 passing, 9 ignored), up 20.

• tests/read_only_open_test.rs (13 tests):
  • On a file with checkpointed facts and a pending WAL, a read-only handle gives the same queries, tx_count and fact log as a read-write one.
  • Reads change no bytes or mtime and create no WAL.
  • API-014 for each write, also on an in-memory database and through the builder.
  • STG-042 for a missing file; an empty file stays 0 bytes.
  • Readers share a file, and a reader and a writer refuse each other (STG-025).
  • A file without write permission opens read-only.
  • The page cache works at 1 page and at the whole file.
• tests/golden_corpus_test.rs opens every golden file (v7 and v8, with pending and stale WALs) read-only first. It checks the manifest's tx_count and queries, and that neither the file nor its WAL changes.
• File backend unit tests:
  • A shared backend refuses writes and syncs (INT-056).
  • The registry counts readers, and the unlocked claim admits readers or one writer.
  • Across processes, a reader in a child process allows a reader here and refuses a writer here (STG-026).
• Storage unit tests: a read-only open of a v7 file at every point of an interrupted migration (clean and torn writes) sees every fact and writes nothing.

Docs updated: CHANGELOG, ROADMAP, README, CLAUDE.md, TEST_COVERAGE, ERROR_REFERENCE (STG-042, API-014, INT-056, plus notes on STG-025/026). The wiki is left for the v3.0.0 doc sync, as with the earlier v3 PRs.

🤖 Generated with Claude Code

https://claude.ai/code/session_015GgLEs8YozJjYhwPEYgTUn