feat(ground-study): persist seeded variation requests (#4273)

AGENT_HANDOFF.md

@@ -1,5 +1,44 @@
 # AGENT_HANDOFF — Tools
 
+## 2026-08-11 local #4273 seeded-request persistence
+
+The unpublished `codex/4273-ground-variation-persistence` branch starts from
+exact published PR #4365 documentation head
+`27d2a68d3738d61307af9235f3f97f7bd400e0f3`. A read-only persistence audit
+found a clean composition seam: the existing immutable seeded request,
+`VariationPlan` and regional-plan object serializers, shared canonical numeric
+JSON, duplicate-key-rejecting ground parser, bounded UTF-8 snapshot reader, and
+native atomic text writer. No alternate storage or physics contract was needed.
+
+The new UI-neutral v1 envelope persists the exact variation plan, exact
+regional material plan, result/source/series identifiers, and row cap. It has a
+1 MiB UTF-8 bound and deterministic compact canonical text suitable for the
+existing browser-download model. Import requires exact fields and current
+schema versions before delegating nested objects to their existing parsers.
+Duplicate fields, nonfinite or cross-runtime-unsafe numbers, Boolean numeric
+substitutes, surrogate text, malformed identifiers/caps, oversized documents,
+and invalid nested plans fail closed. Import registers the two Rate extension
+variables explicitly; merely importing the module still does not mutate the
+shared registry.
+
+Native reads take one sentinel-bounded strict UTF-8 snapshot. Writes serialize
+and validate before reusing the existing flush/fsync/atomic-replace seam;
+cancellation is a no-op and a failed replacement preserves the last-known-good
+file. No UI, browser filesystem claim, or physics execution is added.
+
+RED captured the missing persistence module. Twenty-two focused tests and 82
+composition tests pass. The relevant Rate adapter/file plus complete shared
+flight/ground/variation selection passes 545 tests with six expected
+missing-Rust-wheel skips and one environment-only Hypothesis warning. Ruff,
+import-skipping MyPy, Bandit, campaign-manifest validation and its eight tests,
+documentation governance, blocking-quality, minimum-test, module-size,
+changed-test assertion, placeholder, structural, and diff gates are green.
+
+This is not a #4273/#4267 completion claim. UI/editor integration, workspace
+embedding, regional-overlay variation, solver/capability consumption, wind,
+compiled/downstream parity, protected review, publication, and release remain
+open. No branch was pushed and no GitHub state was changed.
+
 ## 2026-08-11 PR #4365 seeded regional-ground material variation
 
 Ready PR [#4365](https://github.com/D-sorganization/Tools/pull/4365) is stacked

SPEC.md

@@ -26,8 +26,8 @@
 | **Owner**               | D-sorganization                            |
 | **Primary Language(s)** | Python 3.11+, Rust, JavaScript, TypeScript |
 | **License**             | MIT                                        |
-| **Current Version**     | 1.14.56                                    |
-| **Spec Version**        | 1.14.56                                    |
+| **Current Version**     | 1.14.57                                    |
+| **Spec Version**        | 1.14.57                                    |
 | **Last Spec Update**    | 2026-08-11                                 |
 
 ## 2. Purpose & Mission
@@ -46,6 +46,26 @@ Comprehensive monorepo housing 45+ utility tools for data processing, scientific
 
 ## 3. Goals & Non-Goals
 
+### 2026-08-11 Seeded Regional-Ground Request Persistence
+
+- A strict v1 application envelope stores the existing immutable seeded
+  variation request: current `VariationPlan`, exact regional material plan,
+  result/source/optional-series identifiers, and maximum output rows. It does
+  not define another simulation or storage model.
+- Deterministic compact canonical JSON enforces cross-runtime-safe numbers,
+  Unicode scalar text, exact nested shapes, duplicate-key rejection, current
+  schema versions, and a 1 MiB UTF-8 limit. The same text is suitable for
+  browser downloads without claiming browser atomic replacement.
+- Native files reuse the shared sentinel-bounded UTF-8 reader and
+  flush/fsync/atomic-replace writer. Cancellation changes nothing, and failed
+  replacement preserves the prior file.
+- Loading explicitly registers the two Rate-owned ground variables before the
+  existing variation parser runs, constructs the existing exact request, and
+  never executes physics.
+- This slice excludes UI/editor wiring, workspace embedding, regional-overlay
+  variation, solver/capability use, wind, compiled/downstream parity, protected
+  release, and issue/epic completion.
+
 ### 2026-08-11 Seeded Regional-Ground Material Variation
 
 - A UI-neutral adapter samples base-surface normal restitution and rolling

docs/development/RATE_OF_CLOSURE_CAMPAIGN_HANDOFF.md

@@ -1,5 +1,33 @@
 # Rate of Closure Ball-Flight Campaign Handoff
 
+## 2026-08-11 local #4273 seeded-request persistence
+
+- The unpublished `codex/4273-ground-variation-persistence` branch starts from
+  exact published PR #4365 docs head
+  `27d2a68d3738d61307af9235f3f97f7bd400e0f3`. Audit confirmed that the
+  immutable seeded request, existing nested serializers, canonical safe-number
+  JSON, strict duplicate-key parser, bounded reader, and atomic writer form a
+  complete persistence seam without a parallel schema or storage mechanism.
+- A UI-neutral v1 envelope persists the exact variation and regional plans,
+  result/source/series identities, and row cap as deterministic compact JSON.
+  The 1 MiB UTF-8 contract is portable to existing browser-download behavior;
+  native reads and writes reuse sentinel-bounded snapshots and atomic replace.
+- Exact field and current-version checks precede existing nested parsers.
+  Duplicate keys, unsafe/nonfinite/Boolean numbers, surrogate text, malformed
+  identities/caps, invalid nested contracts, and oversize payloads fail closed.
+  Parsing explicitly registers the Rate ground variables and never runs
+  physics.
+- RED captured the absent module. Twenty-two focused, 82 composition, and 545
+  relevant Rate/shared tests pass. The broad run has six expected missing-Rust-
+  wheel skips and one environment-only warning. Ruff, import-skipping MyPy,
+  Bandit, campaign manifest and eight tests, documentation, blocking-quality,
+  minimum-test, module-size, changed-test assertion, placeholder, structural,
+  and diff gates pass.
+- This candidate is local and unpushed. UI/editor wiring, workspace embedding,
+  browser filesystem claims, overlay variation, solver/capability use, wind,
+  compiled/downstream parity, protected review, publication, and release remain
+  open; #4273/#4267 are not complete.
+
 ## 2026-08-11 PR #4365 seeded regional-ground material variation
 
 - Ready PR [#4365](https://github.com/D-sorganization/Tools/pull/4365) starts

docs/release/rate_of_closure_campaign.v1.json

@@ -1390,6 +1390,10 @@
           "kind": "repository_path",
           "value": "src/rate_of_closure/variation/regional_ground_variation.py"
         },
+        {
+          "kind": "repository_path",
+          "value": "src/rate_of_closure/application/regional_ground_variation_request.py"
+        },
         {
           "kind": "repository_path",
           "value": "src/rate_of_closure/simulation/ground_playback.py"
@@ -1443,12 +1447,12 @@
         "ground-regional-ui-helper-local-d217",
         "ground-regional-io-local-8e1c"
       ],
-      "evidence_gap": "The contract, flight-transfer, impact/bounce, static-plane skid/roll, regional-surface, regional-plan wire, regional-editor, regional request-I/O, regional execution, evidence-readback, complete-result, ledger-inspection, trajectory-export, repeated-bounce result-wire, repeated-bounce request-wire, UI-neutral repeated-bounce execution, flight-to-bounce composition, full flight-through-regional-ground composition, qualified study-adapter, matched ground-playback, post-ground target, and seeded base-material variation carriers remain open on PRs 4285, 4288, 4302, 4304, 4332, 4335, 4339, 4342, 4350, 4351, 4352, 4353, 4354, 4355, 4356, 4357, 4359, 4360, 4361, 4363, 4364, and 4365. PR 4361 adds a UI-neutral complete-rest-only adapter into existing flight metrics and scalar ensembles while retaining partial, censored, cancelled, failed, non-settled, missing-summary, and transfer-failure outcomes as typed nullable rows. PR 4363 adds matched import-only PyQt6 and React playback with phase-safe absolute time, bounded presentation, and no physics. PR 4364 maps only qualified final x/z through the sole target frame, substitutes declared surface elevation once, reuses SpatialTarget miss geometry, and emits bounded typed target rows. PR 4365 varies only base normal restitution and rolling resistance with deterministic plan-bound provenance and qualified nullable scalar outputs. Fresh protected evidence, regional-overlay variation, solver/capability invocation, variation UI, UI pipeline invocation, direct editor handoff, persistence, workspace model-input persistence, measured calibration, changing geometry, rendered visual QA, camera presets/tracking, compiled-runtime physics, and downstream parity remain absent.",
+      "evidence_gap": "The contract, flight-transfer, impact/bounce, static-plane skid/roll, regional-surface, regional-plan wire, regional-editor, regional request-I/O, regional execution, evidence-readback, complete-result, ledger-inspection, trajectory-export, repeated-bounce result-wire, repeated-bounce request-wire, UI-neutral repeated-bounce execution, flight-to-bounce composition, full flight-through-regional-ground composition, qualified study-adapter, matched ground-playback, post-ground target, and seeded base-material variation carriers remain open on PRs 4285, 4288, 4302, 4304, 4332, 4335, 4339, 4342, 4350, 4351, 4352, 4353, 4354, 4355, 4356, 4357, 4359, 4360, 4361, 4363, 4364, and 4365. PR 4361 adds a UI-neutral complete-rest-only adapter into existing flight metrics and scalar ensembles while retaining partial, censored, cancelled, failed, non-settled, missing-summary, and transfer-failure outcomes as typed nullable rows. PR 4363 adds matched import-only PyQt6 and React playback with phase-safe absolute time, bounded presentation, and no physics. PR 4364 maps only qualified final x/z through the sole target frame, substitutes declared surface elevation once, reuses SpatialTarget miss geometry, and emits bounded typed target rows. PR 4365 varies only base normal restitution and rolling resistance with deterministic plan-bound provenance and qualified nullable scalar outputs. An unpublished exact-#4365 local child adds strict canonical 1 MiB seeded-request JSON plus bounded native atomic persistence, but has no UI, browser file operation, carrier, or protected evidence. Fresh protected evidence, regional-overlay variation, solver/capability invocation, variation UI, UI pipeline invocation, direct editor handoff, workspace embedding, measured calibration, changing geometry, rendered visual QA, camera presets/tracking, compiled-runtime physics, and downstream parity remain absent.",
       "limitations": [
         "Airborne flight must first terminate against physical terrain and preserve terminal angular velocity.",
         "Current UpstreamDrift terrain and putting implementations are reference inputs rather than the qualified authority.",
         "The #4270 rigid impact law does not consume firmness, grass, compressibility, moisture, or rolling-resistance fields.",
-        "Published open PR #4365 supports seeded variation only on the base surface; regional overlays, UI, persistence, and solver/capability consumption remain absent.",
+        "Published open PR #4365 supports seeded variation only on the base surface; an unpublished child adds canonical request persistence only, while regional overlays, UI, workspace embedding, browser file operations, and solver/capability consumption remain absent.",
         "Published open PR #4304 qualifies one immutable planar profile and optional finite tangent-axis edge; open PR #4332 adds bounded coplanar material overlays; open PR #4335 adds a strict Python/TypeScript plan wire boundary and Python resolver; open PR #4339 adds matched PyQt6/React request editors; open PR #4342 adds editor-qualified canonical request import/export with native atomic semantics and explicit browser limitations; open PR #4350 adds UI-neutral Python regional execution plus an embedded-plan-bound result/provenance envelope with validated transition crossings; open PR #4351 adds matched strict plan-bound evidence import/readback; open PR #4352 completes all frozen summary/result fields, warnings, calibration, provider identity, and observed-phase readback; open PR #4353 adds bounded ground-event and regional-transition ledger inspection; open PR #4354 adds bounded raw trajectory inspection plus native-atomic and browser-download canonical evidence export; open PR #4355 adds strict import-only Python/TypeScript RepeatedBounceResult evidence serialization and parsing with exact nested invariants, a 1 MiB bound, and canonical SHA parity; open PR #4356 adds the strict paired request envelope; open PR #4357 adds the UI-neutral Python request-to-solver binding; open PR #4359 adds strict composition from qualified flight output through the existing transfer and request boundaries to that executor; open PR #4360 composes the existing flight, bounce, regional skid/roll, and complete-result authorities behind one strict non-fabricating evidence contract; open PR #4361 adds a complete-rest-only Python adapter into existing metric and scalar-ensemble contracts without promoting censored numeric endpoints; open PR #4363 adds strict phase-safe import-only playback to matched PyQt6/React workspaces; and open PR #4364 evaluates only qualified landing targets while retaining typed nulls for aerial and every unqualified outcome. Changing normals, height or velocity discontinuities, terrain deformation, torsional-spin damping, roll-to-skid transitions, direct editor handoff, persistence, aerial target trajectory evaluation, measured calibration, workspace model-input persistence, rendered visual QA, camera presets/tracking, compiled or TypeScript regional physics, solver/capability invocation, variation UI, wind strategy, and downstream surface adapters remain unimplemented."
       ],
       "depends_on_issues": [

src/rate_of_closure/AGENT_HANDOFF.md

@@ -1,5 +1,36 @@
 # AGENT_HANDOFF — rate_of_closure
 
+## 2026-08-11 local #4273 seeded-request persistence
+
+The unpublished `codex/4273-ground-variation-persistence` child starts from
+exact PR #4365 docs head `27d2a68d3738d61307af9235f3f97f7bd400e0f3`.
+The new application-layer contract composes existing authorities into one
+strict v1 seeded-study request envelope: exact `VariationPlan`, exact regional
+plan, result/source/series identifiers, and the bounded row cap. Canonical
+numeric JSON is compact, deterministic, cross-runtime safe, and suitable for a
+browser download; native persistence reuses the existing bounded UTF-8 reader
+and atomic writer.
+
+Import rejects duplicate or unknown fields, unsupported outer or nested
+versions, nonfinite/unsafe/Boolean numbers, surrogate text, malformed
+identifiers and caps, invalid nested contracts, and payloads above 1 MiB. It
+explicitly registers the Rate ground variables only when parsing a request.
+Successful import returns the existing immutable request and executes no
+physics. Native cancellation is a no-op; failed replacement retains the prior
+file and removes its temporary file.
+
+RED captured the absent module. Twenty-two focused tests, 82 composition tests,
+and 545 relevant Rate/shared flight-ground-variation tests pass; the broad set
+has six expected missing-Rust-wheel skips and one environment warning. Ruff,
+import-skipping MyPy, Bandit, campaign manifest and its eight tests,
+documentation, blocking-quality, minimum-test, module-size, changed-test
+assertion, placeholder, structural, and diff gates pass.
+
+No UI/editor, browser filesystem behavior, workspace embedding, overlay
+variation, solver/capability invocation, wind, compiled runtime, downstream
+parity, protected review, publication, or release is included. Keep #4273 and
+#4267 open. This branch has not been pushed.
+
 ## 2026-08-11 PR #4365 seeded regional-ground material variation
 
 Ready PR [#4365](https://github.com/D-sorganization/Tools/pull/4365) is stacked

src/rate_of_closure/application/__init__.py

@@ -6,6 +6,15 @@
     CommandAvailability,
     CommandUnavailableError,
 )
+from .regional_ground_variation_request import (
+    MAX_REGIONAL_GROUND_VARIATION_REQUEST_BYTES,
+    REGIONAL_GROUND_VARIATION_REQUEST_SCHEMA,
+    REGIONAL_GROUND_VARIATION_REQUEST_SCHEMA_VERSION,
+    read_regional_ground_variation_request,
+    regional_ground_variation_request_from_json,
+    regional_ground_variation_request_to_json,
+    write_regional_ground_variation_request_atomic,
+)
 from .regional_surface_plan_files import (
     read_regional_surface_plan_request,
     write_regional_surface_plan_request_atomic,
@@ -24,6 +33,9 @@
 
 __all__ = [
     "APP_COMMAND_IDS",
+    "MAX_REGIONAL_GROUND_VARIATION_REQUEST_BYTES",
+    "REGIONAL_GROUND_VARIATION_REQUEST_SCHEMA",
+    "REGIONAL_GROUND_VARIATION_REQUEST_SCHEMA_VERSION",
     "WORKSPACE_SCHEMA",
     "WORKSPACE_SCHEMA_VERSION",
     "AppCommandId",
@@ -34,9 +46,13 @@
     "WorkspaceLayout",
     "WorkspaceMetadata",
     "read_workspace",
+    "read_regional_ground_variation_request",
     "read_regional_surface_plan_request",
     "workspace_from_json",
     "workspace_to_json",
+    "regional_ground_variation_request_from_json",
+    "regional_ground_variation_request_to_json",
     "write_workspace_atomic",
     "write_regional_surface_plan_request_atomic",
+    "write_regional_ground_variation_request_atomic",
 ]