Implement RESET ALL with startup snapshots and atomic validation

[apstndb]

Updated scope

RESET ALL remains missing, while varDef.resettable/noReset and SET LOCAL already exist. Restore the initialized connection values, not hard-coded factory defaults. This ticket owns the shared capture/reset primitive used by the separate single-variable RESET issue.

Implementation contract

• Capture the reset baseline after defaults, config, flags and --set, before --init-command/interactive input. Treat init commands as SQL that may later be reset; document this boundary.

• Use varDef metadata to exclude read-only, init-only, noReset and unsupported/placeholder variables. Avoid treating every ListVariables string as round-trippable; opaque graphs, multi-value state and side-effect variables need explicit support or exclusion.

• Validate the complete operation before changing live state. A guarded/invalid reset must not leave half the variables reset. Preserve descriptor state, output/file handles and connection identity rather than replaying arbitrary setters destructively.

• Ordinary RESET is persistent like ordinary SET: after the entire reset succeeds, retire LOCAL undo entries only for each targeted canonical variable. Unrelated LOCAL undo must remain intact. This applies even when the live value already equals the startup snapshot; an equal-valued reset can still change what COMMIT would restore.

• Expose one reusable Reset(name)/ResetAll core, with parser/help in the appropriate PR. Keep System-variable schema metadata model (varDef): declarative defs feeding registry, flags, guards, RESET ALL, SET LOCAL, and docs #725 as architectural context, not an unimplemented prerequisite.

Design clarification (2026-09-14)

• Capture after initializeSystemVariables (including feature flags and --set), before --init-command and --init-command-add. Both init-command forms already exist at the audited baseline.
• Distinguish value assignment from LOCAL undo effects. Skip unchanged value assignments before transaction/manual-batch policy checks, but still retire the targeted LOCAL undo after the whole operation succeeds. If a changed guarded variable would fail, neither values nor undo entries may change. Current transaction guards include READONLY, DIRECTED_READ and CLI_SAVEPOINT_SUPPORT; the last also has a manual-batch guard.
• Implement one small prepare/commit mechanism: obtain explicit supported startup snapshots, parse/validate all changed values without live mutation, then apply assignments and the corresponding undo updates. Reuse VarHandler's existing parse/validate structure; do not clone the live systemVariables/registry/callback/resource graph.
• The first reset PR excludes file-backed descriptor/template reload, opaque descriptor graphs, stream/output handles, connection identity and unimplemented placeholders. Custom in-memory or derived-state values require explicit tested capture/prepare/commit support, otherwise an explicit documented exclusion. Do not turn a displayed path/graph into a resource-loading reset.
• Regression example: startup CLI_VERBOSE=false; SET CLI_VERBOSE=true; BEGIN; SET LOCAL CLI_VERBOSE=false; RESET CLI_VERBOSE; COMMIT must leave false. Without retiring the equal-valued reset's undo, COMMIT incorrectly restores true. Apply the same per-variable rule to RESET ALL. Tests for a rejected RESET ALL must also prove that its undo entries were not partially retired.

Acceptance

• Startup flag/--set values survive RESET ALL; only resettable variables change.

• Alias, custom/multi-value variable, unknown placeholder and failed-policy cases have tests proving no partial mutation.

• Transaction-local restoration, manual batch guards and an active output stream are covered.

References: mycli reset metadata, Java state reset.

Verification and delivery

Plan refreshed on 2026-09-14 against a8fa2418b65af9b889cf92e02190366b3e6e02ea. This body supersedes obsolete implementation suggestions in earlier comments; history is retained. Tracked with #47.

For each implementation PR, capture focused test output to a file and check the exit code, then run make check before pushing; run make check-race for transaction concurrency/lifecycle changes. Keep the coverage gate at 80%. Update user docs and the compatibility matrix with the resulting behavior. No database/sql migration or unrelated dependency upgrade.

[apstndb]

Implementation note: "iterate over all resettable variables and restore defaults" has two problems — the registry carries no per-variable default metadata (adding it touches ~80 registrations), and "factory defaults" is the wrong target anyway: java-spanner's RESET ALL restores connection-initial values, so flag-provided values must survive. Both are solved by snapshotting registry.ListVariables() once after startup initialization (post-defaults, post-flags) and having RESET ALL replay registry.Set from that snapshot for writable variables. Near-zero new code and the correct semantics.

[apstndb]

Groundwork landed: the varDef model now exposes resettable() and the noReset opt-out (var_defs.go), so the remaining work is the RESET ALL client-side statement that iterates resettable vars and restores session-startup values. Scheduled as PR5 of the #725 varDef series. Keeping #47 as the sub-issue parent (compat umbrella); #725 tracks the implementation phasing.