State Diff Test¶
Test or assessment — instantiates Declared Effect Boundary Enforcement
Runs an action and compares before/after state surfaces to detect undeclared changes.
State Diff Test snapshots the shared state surfaces an action is declared to touch, runs the action, snapshots them again, and flags any change that falls outside the declared set. Its defining trait is empirical detection: it does not trust the contract, enforce it, or repair a violation — it catches, by direct before/after comparison, the gap between what an action promised to change and what it actually changed. It turns "we believe this endpoint only writes these three tables" into a test that fails, loudly and specifically, the day the endpoint starts writing a fourth. Where a contract is a claim, the state diff is the check on that claim.
Example¶
A team owns an order service whose createOrder endpoint is declared to touch exactly three surfaces: the orders table, an inventory count, and a message outbox. They build a state diff test around that declaration. The harness snapshots all three surfaces, calls createOrder with a fixed input, snapshots them again, and diffs.
On a routine test run after an unrelated refactor, the diff reports a fourth change: a customer's loyalty-tier field was silently updated. Nobody declared that effect; a shared helper, reused in the new code path, wrote it as a side effect. The test fails and names the exact surface and field that changed out of contract, before the code ships. The action was not blocked and no state was repaired — but the boundary violation was caught at the one moment it is cheap to fix, and pinned to a specific undeclared write instead of surfacing later as an unexplained loyalty-tier bug in production.
How it works¶
- Snapshot the inventory. Before running, it reads every surface the action is declared to touch — and, deliberately, some it claims not to — capturing a baseline.
- Run and re-snapshot. The action executes against the captured baseline, and each surface is read again afterward.
- Diff against the declared set. Any observed change outside the declared effects is a failure; the test reports the specific surface and delta.
- Detection, not prevention. It runs in test or audit, before release or on a schedule — it surfaces the violation for a human to act on rather than blocking the action at runtime.
Tuning parameters¶
- Surface coverage — how many shared surfaces are snapshotted. Broader coverage catches more, but you can only diff surfaces you thought to include.
- Diff granularity — whole-table versus field-level comparison. Finer granularity pinpoints the offending write but produces more to interpret.
- Benign-churn tolerance — which incidental changes (timestamps, autoincrement ids) are filtered as expected noise versus flagged.
- Cadence — a blocking gate on every change versus a periodic audit run; gating catches violations earliest, auditing is cheaper.
When it helps, and when it misleads¶
Its strength is that it catches false purity empirically — the lazy write, the reused helper's side effect, the "read-only" action that isn't — by measuring real behavior rather than trusting the contract.[n1]
Its defining limit is that it only sees the surfaces it snapshots: a truly forgotten surface produces no diff and stays invisible, so a state that no one inventoried can be corrupted with the test showing green. A secondary failure is diff noise — unfiltered incidental churn breeds alert fatigue until real signals are ignored. The guarding discipline is to keep the surface inventory as complete as the risk demands and to filter benign churn deliberately, so a green result means "no undeclared change on the surfaces that matter," not "no change anywhere."
How it implements the components¶
shared_state_surface_inventory— it operationalizes the inventory by actually snapshotting each named surface; a surface not in the diff is, in practice, a surface not being checked.protected_invariant_set— each run asserts the invariant "no change occurs outside the declared effect set," failing when an action violates it.
It does NOT implement declared_effect_contract or mutation_gateway — the diff checks an action against a contract it neither writes nor enforces; writing the contract is Effect Contract Annotation and enforcing it at the write path is Command–Query Separation.
Related¶
- Instantiates: Declared Effect Boundary Enforcement — verifies that an action's actual effects stay inside its declared boundary.
- Consumes: Effect Contract Annotation supplies the declared effect set the diff is checked against.
- Sibling mechanisms: Audit Log and Trace · Command–Query Separation · Compensating Action Protocol · Effect Contract Annotation · Effect Review Checklist · Immutable Data or Copy-on-Write · Permission Scope or Capability Token · Sandbox or Staging Execution · Transaction Boundary
Editorial Notes¶
Form Classification¶
Form family: Experiment, Test & Rehearsal
Rationale: State Diff Test operates as an active test, trial, simulation, drill, or rehearsal that generates evidence through a deliberate attempt or perturbation because it runs an action and compares before/after state surfaces to detect undeclared changes.
Independent corroboration: The frozen evidence defines State Diff Test as 'Runs an action and compares before/after state surfaces to detect undeclared changes', so its operative form is Experiment, Test & Rehearsal.
Nearest alternative: Assessment, Review & Assurance — State Diff Test includes features of a bounded evaluation of existing evidence or work that produces a finding or disposition, but its defining operation is an active test, trial, simulation, drill, or rehearsal that generates evidence through a deliberate attempt or perturbation.
Review outcome: Independent reviewer agreement; medium confidence.
Origin Attribution¶
Primary origin: Computer Science & Software Engineering
Origin pattern: Single lineage
Present-day reach: Universal
Rationale: Before-after state comparison detects undeclared software effects.
Related originating lineages:
- Accounting & Auditing — Reconciliation exposes unauthorized changes.
- Engineering & Design — Engineering design, reliability, and systems-safety practice supplies a parallel or contributing lineage for the mechanism's defining operation: runs an action and compares before/after state surfaces to detect undeclared changes.
Review resolution: The blind reviewers agree that computer_science is the primary origin and differ only on alternate origin disagreement, domain reach disagreement. I preserve every independently explained alternate from both records rather than imposing a numeric cap. I retain single_lineage because the combined evidence shows one traceable formative lineage. The broader reach of universal records portability separately from historical provenance; encyclopedia_synthesis=false preserves the affirmative synthesis judgment where either reviewer identified one.
Review outcome: Reconciled after independent review; high confidence.
Notes¶
[n1] A characterization (or golden-master) test, as described by Michael Feathers, captures the actual behavior of code so that later changes are flagged against it. A state diff test applies the same idea to an action's effect surface: pin what it really does, and fail when the real effects drift from the declared ones. ↩