write-false-prevents-persistence

IN premise

Functions using `_with_network(write=False)` can mutate the in-memory network (as `what_if_retract` does) but changes are never saved to SQLite; write-or-not is declared upfront and never conditional.

Summary

When a function opens the belief network in read-only mode, any changes it makes to the in-memory copy are silently discarded — they never reach the database. This is by design: the write flag is set once at the start and cannot be flipped later, which means read-only operations like what-if analysis can freely modify the in-memory state without risk of accidentally persisting those exploratory changes.

Dependents

These beliefs depend on this one:

api-layer-ensures-atomic-isolated-mutations — The API layer enforces mutation safety through four mechanisms: context-managed load/save, per-function transaction scope, write-flag gating to prevent unintended persistence, and dict-only returns that prevent callers from holding live network references.
both-backends-support-safe-hypothetical-reasoning — Both storage backends enable hypothetical what-if reasoning without permanent mutation: PgApi performs real mutations inside a transaction then rolls back, while the in-memory backend uses write-flag gating to discard speculative changes after analysis

Details

Source

entries/2026/04/23/reasons_lib-api.md