New -nestpreserve- Module for Nested Dataset-State Management

[smith Jason]

Thanks as always to Kit Baum, the new -nestpreserve- module is now available on SSC.


-nestpreserve- provides nested dataset-state management for Stata. It implements a disk-backed, last-in-first-out stack of checkpoints, allowing users to preserve, inspect, and restore multiple analytical states rather than being limited to a single preserve/restore cycle. The module is designed for workflows in which a dataset passes through multiple temporary transformations and intermediate states, while keeping restoration order explicit and auditable.

The main components are:

1. -nestpreserve-: creates a new dataset-state checkpoint. Multiple checkpoints may be nested, with each checkpoint belonging to the frame in which it was created.
2. -nestrestore-: restores checkpoints in last-in-first-out order, helping prevent accidental restoration of the wrong analytical state.
3. -neststatus-: inspects the current checkpoint stack and reports information about stored states.
4. -nesttransaction-: runs a Stata command as a temporary dataset transaction. Dataset changes made by the command are automatically rolled back after either successful execution or failure.
5. -nestrecover- and -nestclear-: provide recovery and cleanup for checkpoint stacks left behind after a Stata process terminates. Recovery is deliberately fail-closed: automatic action is taken only when a single intact abandoned stack can be identified and its originating process is confirmed to be no longer running. Ambiguous, live, corrupt, legacy, or otherwise unverifiable checkpoint stacks are not modified automatically.

For each checkpoint, -nestpreserve- records information such as dataset dimensions, changes in variables and observations, dataset signatures, and transaction history. Checkpoints are disk-backed and are managed separately for individual Stata frames. The module manages dataset state, rather than attempting to snapshot the complete Stata session. This distinction is intentional.

To install:
ssc inst nestpreserve

To update an existing installation:
. ssc inst nestpreserve, replace

The help file, accessible with

help nestpreserve

includes numerous worked examples covering typical workflows and common use cases, intended to make the package easy to learn and apply in practice.

Comments, bug reports, and suggestions are very welcome.