Repository navigation
enhancement (v3.0.0): expose open_with_options (read_only, page_cache_size, allow_unlocked) in every binding #465
Description
Follow-up to #429. PR #464 added read-only open to the Rust API on v3. This issue exposes it, and the other open options offline tools need, in every binding. Python comes first because it is Tier 1.
What landed in core (PR #464)
pub struct OpenOptions { // #[non_exhaustive]
pub wal_checkpoint_threshold: usize,
pub page_cache_size: usize, // pages of 4 KB; file_size / 4096 keeps the whole file resident
pub max_derived_facts: usize,
pub max_results: usize,
pub allow_unlocked: bool,
pub synchronous: SyncMode,
pub read_only: bool, // new
}
Minigraf::open_with_options(path, OpenOptions::new().read_only(true))read_onlytakes a shared lock. Read-only handles coexist, and a read-write handle refuses them, and they refuse it, with STG-025 or STG-026.- Nothing is written to the
.graphfile or its WAL. A WAL is applied in memory, and a v7 file is read without migrating. - A missing file is STG-042.
transact,retract,begin_write,checkpointandrebuild_indexesfail with API-014. Queries, cursors,fact_log,verifyand rules work.
Design: docs/superpowers/specs/2026-10-07-read-only-open-design.md.
Binding shape
Today the bindings expose only open(path), open_in_memory(), execute and checkpoint, with no options. Each binding adds:
open_with_options(path, options), whereoptionsis a record with every field optional and defaulting to the Rust default:read_onlypage_cache_sizeallow_unlockedwal_checkpoint_thresholdmax_derived_factsmax_resultssynchronous
- API-014, STG-042, STG-025 and STG-026 reach the caller as the binding's coded error, like every other code.
- Bindings should use their own idiom on top of this:
- Python:
minigraf.open(path, read_only=True, page_cache_size=...)keyword arguments. - Node: an options object.
- Java: a builder.
- Python:
Checklist
- minigraf-python (Tier 1)
- minigraf-node
- minigraf-java
- minigraf-android
- minigraf-swift
- minigraf-c
- minigraf-wasm:
read_onlyis file-backed only, so expose only what applies to the browser backend, or document why it does not apply
Each binding needs tests for:
- read-only open on an existing file, with queries working
- a write giving API-014
- a missing file giving STG-042
- two read-only handles on one file
Related: #462 (binding cursors), #430 (fact log), #431 (raw writer), temporal_reasoning#378.
🤖 Generated with Claude Code
Done (2026-10-07)
minigraf-python#6 (minigraf.open(path, read_only=True, ...)), minigraf-java#9 (Minigraf.options() builder), minigraf-android#6, minigraf-swift#6, minigraf-node#5 (options object), minigraf-c#4 (JSON options with error_out), and minigraf-wasm#4. In the wasm repo the README explains why the file-backed options don't apply to the IndexedDB-backed BrowserDb. Each binding tests read-only queries, API-014, STG-042 and two read-only handles. An unconvertible argument is the new API-017 (core #468). Also resolves #322.
Activity
Merge pull request #468 from project-minigraf/feat/binding-etl-surface
feat: open options, query cursors, fact log and log writer (v3) (#6)
feat: open options, query cursors, fact log and log writer (v3) (#9)
feat: open options, query cursors, fact log and log writer (v3) (#6)
feat: open options, query cursors, fact log and log writer (v3) (#6)
feat: open options, query cursors, fact log and log writer (v3) (#5)
feat: open options, query cursors, fact log and log writer (v3) (#4)
feat: BrowserDb query cursor and v3 core (v3) (#4)
adityamukho commentedon Oct 7, 2026
All checklist items done; see the 'Done' section in the description. Ships in v3.0.0.