api-mutating-ops-use-before-after-diffing

IN premise

Mutating operations (`retract_node`, `assert_node`, `what_if_retract`, `what_if_assert`) snapshot all truth values before the operation and diff afterward to classify changes into `went_out`/`went_in` lists.

Summary

When the system changes something — like retracting or adding a belief — it takes a snapshot of every truth value beforehand, performs the operation, then compares the new state to the old one. This before-and-after diffing is how the API reports exactly which beliefs changed status, giving callers a clear picture of the ripple effects of any mutation.

Dependents

These beliefs depend on this one:

every-mutation-reports-its-effects — All mutating operations report their effects as structured data: retract returns the full changed set, add_justification returns a change dict with old/new truth values, and API mutating operations use before/after truth-value diffing to capture deltas.
mutations-are-observable-audited-and-index-consistent — Every network mutation achieves triple-layered traceability: callers receive structured before/after diffs at the API level, the internal audit log records timestamped events for historical analysis, and the dependents index is simultaneously maintained — providing both external and internal observability.

Details

Source

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