GPU resident checkpoints

Current controllers create schema-v4 checkpoints; v1 noncommunication and v2 communication checkpoints remain restart-compatible. Resident communication is a concrete-only closed-map barrier: communication runs before optional prescribed volume evolution, and both invalidate saturation ratio only.

The barrier resources and executor are direct imports under particula.execution; they are not package or top-level exports. Schema-v2 restart creates fresh communication arrays and bindings rather than reusing source identities.

The direct-import-only checkpoint boundary is available from particula.execution.checkpoint; it is deliberately not exported by particula.execution or the top-level package. Create a ResidentCheckpointController for one active ResidentSession, its pinned GPUResourceRegistry, and its ResidentStepGuard, or use the session's checkpoint(registry, guard) and finalize(registry, guard) methods.

checkpoint() is nonterminal and returns a fresh immutable host snapshot. finalize() is terminal and idempotent only when called again with the exact bound session, pinned registry, and closed guard. After its first successful call the session is FINALIZED and later calls with that matching binding return the cached snapshot without device work; mismatched or invalid bindings are rejected. Checkpoints are explicit in-memory, same-device recovery only. They do not serialize to disk, select or migrate a device, synchronize implicitly during restart, or provide rollback after a device writer has launched.

The snapshot owns immutable canonical bytes for primary arrays and acquired sidecars, plus detached CPU inspection carriers. Inspection GasData is intentionally lossy because CPU gas carriers do not contain GPU vapor pressure; restart uses canonical bytes and restores vapor pressure exactly. Snapshotting requires approximately one additional host copy of resident payload bytes plus the detached inspection copies. Restart explicitly requires the compatible target Device through restart_resident_session(checkpoint, device). restart_checkpoint is an equivalent concrete-only alias; both require the same exact compatible device and create fresh session, registry, guard, and resident-array identities.

Restart compatibility is intentionally exact and fail-closed. It accepts ResidentCheckpoint records with carrier type "ResidentSession", lifecycle ACTIVE, complete valid canonical payload descriptors, and an exactly equal target Device. Schema-v1 checkpoints must be noncommunication checkpoints. Schema-v2 checkpoints may contain no communication family or exactly one complete closed-map GAS or PARTICLES communication family with matching metadata and payloads. Schema-v3-and-later records always require continuation metadata, though their published-stream payload collection may be empty when neither canonical coagulation nor wall-loss resource family is acquired. Their immutable current uint32 words are restart authority; normal dispatch and reacquisition neither read them back nor reset them, and only explicit stream reset derives new words from the root seed for a restored published stream. This does not prevent normal first acquisition from deriving words for a stream that was absent from the checkpoint. Finalization terminalizes its source session but returns an ACTIVE, restartable checkpoint record. Restart creates fresh session, registry, guard, resident arrays, and communication bindings; it never reuses source identities or provides fallback. It rejects other versions or carrier schemas, malformed, incomplete, partial, mixed, or mismatched communication payloads, non-ACTIVE checkpoint records, and device mismatches; it does not promise forward or backward compatibility.

Schema-v3-and-later continuation covers the canonical published coagulation and wall_loss streams; schema-v4 is the current format. Each retained record includes schema-versioned stable logical-ID, root-seed, and namespace metadata plus immutable current uint32 words. Those words are the sole continuation authority, rather than lossy CPU inspection carriers or ordinary resource payloads. Checkpoint capture is the sole explicit synchronization/readback boundary for this continuation. Normal scheduling and reacquisition do not inspect, transfer, synchronize, seed, or reset streams. Before setup, the checkpoint validates exact bidirectional pairing between acquired coagulation/ wall-loss process families and continuation payloads; continuation-only and resource-only forms reject. Normal first acquisition initializes a stream only when its resource family was absent from the checkpoint.

Split-run continuation requires a manual restart into a fresh session with a frozen configuration and exactly equal supported Device. It excludes CPU, Warp, CUDA, or other cross-backend replay, cross-device migration; durable serialization; automatic restart; implicit reseeding, and hidden transfer; fallback; and rollback after a writer launch.

Normal resident scheduler calls never checkpoint, finalize, or restart. Those operations remain this explicit, concrete-only exact-device boundary; see the GPU-resident deterministic timestep contract for normal-step limits.

For a lazy lifecycle-only walkthrough that does not schedule or launch physics, see the GPU-resident session lifecycle source.

Validate documentation with:

pytest particula/execution/tests/rng_test.py \
  particula/execution/tests/rng_invariance_test.py \
  particula/execution/tests/checkpoint_test.py -q
pytest particula/execution/tests/gpu_resident_session_docs_test.py -q
mkdocs build --strict

Warp CPU is the installed-Warp baseline. CUDA evidence is optional and skips cleanly when unavailable.