api-layer-ensures-atomic-isolated-mutations
IN derived (depth 1)
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.
Summary
Each API function operates in complete isolation — it opens the database, does its work, and closes — with four interlocking safeguards that prevent data corruption: a context manager guarantees changes are loaded and saved as a unit, a write flag declared upfront controls whether any mutations actually persist, and all results are returned as plain dictionaries so no caller can accidentally hold onto or modify live internal state.
Justifications
SL — Each API safety mechanism prevents a different class of state corruption: stale reads, cross-function leaks, accidental writes, and reference escapes
Antecedents (all must be IN):
- api-uses-with-network-context-manager — `api.py` uses a `_with_network` context manager to ensure load-operate-save atomicity for all network mutations.
- transaction-per-function — Every API function opens the database, does its work, and closes — no shared state, no connection pooling, no long-lived sessions; each invocation is fully independent.
- write-false-prevents-persistence — 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.
- api-functions-return-dicts — Every public API function returns a `dict` (or `str` for markdown/compact), never a `Network` or `Node` object, ensuring JSON-serializability at the boundary for CLI, HTTP, and tool-call consumers.
Dependents
These beliefs depend on this one:
- architecture-enforces-structural-and-operational-safety — Architectural safety is enforced along two independent dimensions: structurally, the central network dependency is contained within clean three-layer boundaries preventing cross-layer corruption; operationally, every mutation path is atomic and isolated preventing within-layer partial state — neither dimension alone is sufficient, but together they eliminate both classes of corruption.
- architecture-has-no-hidden-fragility — The system's architectural safety is robust end-to-end: structural containment via clean layer boundaries and operational atomicity via context-managed mutations leave no hidden consistency hazards across the persistence boundary.
- atomicity-is-backend-independent — Both storage backends enforce atomic isolated operations through backend-appropriate mechanisms: the SQLite backend uses context-managed load/save with write-flag gating and per-function transaction scope, while PostgreSQL uses per-method transactions with composite-key multi-tenancy — achieving the same transactional guarantee at different architectural levels
- dual-backend-atomicity-is-feature-complete — Both storage backends provide atomic isolated operations with complete API coverage — the SQLite backend's context-managed mutations and PgApi's per-method transactions cover the same full set of operations
- llm-driven-mutations-are-safely-bounded — LLM-driven belief derivation is safely bounded by defense in depth: the derive pipeline validates proposals with fail-soft filtering, Jaccard retraction guards, and environment stripping at the LLM boundary, while the API layer enforces atomic load/save with write-flag gating and dict-only returns at the persistence boundary — malformed or adversarial LLM output cannot corrupt the network.
- mutation-pipeline-is-atomic-snapshot — Every network mutation follows an atomic snapshot pipeline: API context management ensures load/save atomicity with write-flag gating, while storage performs full-replace persistence — no partial state is ever visible between operations.
- mutations-are-atomic-audited-and-index-consistent — Every network mutation achieves three simultaneous guarantees: transactional atomicity (context-managed load/save with write-flag gating), historical auditability (timestamped audit log entries), and structural consistency (dependents index updated synchronously) — forming a complete mutation-safety contract.