docs: VIV predeclare — crossing predicate, seed time level, block windows, counting, stop and dual caps

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs/validation/leontini_viv_predeclare.md

@@ -43,7 +43,7 @@ this page is jointly agreed.
   zeta = 0. Equation of motion uses the structural mass only.
 - Per-step sequence (binding): known (y_n, v_n) and the last completed force
   F_last → candidate (y_{n+1}, v_{n+1}) by the update below → `set_body` with
-  offset y_{n+1} and wall velocity (y_{n+1} − y_n)/dt (interval average; a
+  offset y_{n+1} and wall velocity (y_{n+1} − y_n)/dt with lattice dt = 1 (interval average; a
   different quantity from the endpoint v_{n+1}) → `run(1)` → only on success:
   commit y_n ← y_{n+1}, v_n ← v_{n+1}, F_last ← force read for that step. Any
   failure leaves the Simulation failed (existing lifecycle). Whether the
@@ -63,41 +63,51 @@ this page is jointly agreed.
 
 ## Window, failure semantics, acceptance (engineering, development stage)
 
+Clocks: lattice dt = 1; T_n = 1/f_n = 5,000 steps. Response cycles are
+counted from the measured signal; T_n is used only for the seed check.
+
 - Start (source-faithful): fluid at rest except the uniform inlet, body at
-  rest at the declared centre, y(0) = v(0) = 0.
+  rest at the declared centre, y_0 = v_0 = 0, F_last = 0.
-- Seed policy (conditional, declared): exact mirror symmetry can suppress
+- Seed (conditional, one time, declared): at step n_seed = 200,000
-  lift. If max |y| over the last 5 T_n before t = 40 T_n (200,000 steps) is
+  (t = 40 T_n), if max |y| over steps [175,000, 200,000) is below .01 D, then
-  below .01 D, apply one labelled seed at that step as a structural velocity
+  in that step, after the check and before the candidate update, set
-  increment v += 2 pi f_n (.01 D) (amplitude ≈ .01 D), so the geometry then
+  v_n += 2 pi f_n (.01 D) (F_last unchanged) and proceed normally; the
-  moves continuously through the update (never a jump);
+  geometry moves continuously through the update. `seed_applied`, step and
-  `seed_applied=true`, its step and size logged; the run continues under the
+  size are logged; never repeated or changed.
-  same caps. Missing shedding is a diagnostic, never an
+- Cycle boundary (discrete): step n closes a cycle iff y[n−1] < m and
-  "A = 0 pass"; the seed is not changed or repeated after seeing results.
+  y[n] ≥ m, where m = time-mean of y over the previous completed cycle
-- Response cycles: delimited by consecutive upward crossings of y through the
+  (m = 0 before the first completed cycle); y_0 = 0 is not a crossing, and no
-  mean of the previous completed cycle (0 for the first). Per cycle: positive
+  boundary is accepted fewer than 2 samples after the previous one.
-  peak max(y), negative peak min(y), mean offset, amplitude (max − min)/2.
+- Per cycle: positive peak max(y), negative peak min(y), mean offset
-  Window value = mean amplitude over 10 cycles; window change =
+  (time-mean of y), amplitude a = (max − min)/2.
-  |W_k − W_{k−1}| / W_{k−1}.
+- Budget counting: a completed cycle counts toward the 150-cycle budget only
-- Settled when the per-cycle peak changes ≤ 2 % between consecutive 10-cycle
+  if a ≥ .01 D (pre-seed numerical chatter does not consume it).
-  windows and the last 5 cycle peaks agree within 1 %. Budget: 150 response
+- Windows: adjacent non-overlapping blocks of 10 counted cycles
-  cycles from the start of motion, including the 20 scoring cycles, so
+  (1–10, 11–20, ...); W_k = mean amplitude of block k.
-  settling must complete by response cycle 130; the score uses the first 20
+- Settled at the end of block k (k ≥ 2) iff W_{k−1} ≥ 1e-6 D and
-  cycles after settling. Hard native cap 1,000,000 steps (= 200 T_n) in case
+  |W_k − W_{k−1}| / W_{k−1} ≤ .02, and the last 5 cycle amplitudes lie
-  response cycles cannot be detected. Either cap missed → FAIL-CLOSED
+  within 1 % of their mean. Otherwise not yet settled (no NaN pass).
-  (timeout).
+- Scoring: the 20 counted cycles after settling. They must remain settled:
-- Durations reported: total steps, t U/D, N_resp, measured T_resp (mean
+  each 10-cycle block of the 20 satisfies the same 2 % (against the previous
-  upward-crossing interval); N_resp / f_n only as a labelled secondary clock,
+  block) and 1 % rules, else FAIL-CLOSED. Success stop: after the 20th
-  never as the settling unit.
+  scoring cycle; the run does not continue to 150.
-- Growth is not a failure: initial VIV growth is physical. Checked every step
+- Caps (both always armed; the first hit wins and is reported): 150 counted
-  (FAIL-CLOSED): non-finite y, v or force; |y| > 1.0 D (about twice the
+  response cycles including the 20 scoring cycles (so settling must complete
-  largest reference peak, .551 D) or the offset box reached; no_donor > 0;
+  by counted cycle 130) → `timeout_response_cycles`; 1,000,000 native steps
-  a failed upload/step/sync. Timeout = a cap missed (above).
+  (200 T_n) → `timeout_native_steps`.
+- Durations reported: total steps, t U/D, counted and uncounted cycles,
+  measured T_resp (mean boundary interval); N_resp / f_n only as a labelled
+  secondary clock.
+- Growth is not a failure: initial VIV growth is physical. Checked every
+  step (FAIL-CLOSED): non-finite y, v or force; |y| > 1.0 D (the tighter
+  gate; about twice the largest reference peak, .551 D) or the ±1.5 D offset
+  box reached; no_donor > 0; a failed upload/step/sync.
 - All failures are reported as they are (no sub-iteration, no RHS or
   parameter retune, no automatic second case).
-- Score over the 20 cycles after settling: target metric A_max/D =
+- Target metric over the 20 scoring cycles: A_max/D = max over those cycles
-  max over those cycles of max(|positive peak|, |negative peak|) about y = 0
+  of max(|positive peak|, |negative peak|) about y = 0 (Qin reports "maximum
-  (Qin reports "maximum amplitude"); also reported: mean amplitude, positive
+  amplitude"); also reported: mean amplitude, positive and negative peaks,
-  and negative peaks, mean offset, f/f_n (no target).
+  mean offset, f/f_n (no target).
 - Acceptance: |A_max − .520 D| ≤ .052 D (±10 %), stated together with the
   boundary mismatch and the absence of a quoted reference uncertainty. A pass
   is "reasonably close" for the stage: not grid convergence, not force-RHS