The feature was added to address this issue.
My expectation was that it’d be used internally by dfx so I didn’t plan to advertise it publicly here (and confuse people). But now that you’re interested in it, let me elaborate a bit on a concrete scenario showing why that feature might give unexpected results:
- a PocketIC instance is created and configured to persists its state in a state directory;
- a counter canister is deployed to the PocketIC instance;
- the current value of the counter is 41;
- a checkpoint is created and written to the state directory;
- an update call is executed and the value of the counter becomes 42;
- the PocketIC server is killed (no graceful shutdown);
- a new PocketIC instance is created and configured to use the same state directory;
- the value of the counter is 41 (although it was already observed to be 42).
The reason for the counter being 41 again is that the new PocketIC instance loads its state from the last checkpoint and all changes made between the last checkpoint and the (abrupt) kill are lost. (There are other “low-level” side-effects such as non-monotone time which result in crashes reported on the linked thread, but the one described above could actually be confusing to end-users which is why an option to enable “incomplete” state was introduced as opposed to silently adjusting time to avoid the reported crash.)