@inventure71/paddockjs 4.1.0 → 4.3.0

package/docs/racing_ai_improvements.md

@@ -0,0 +1,145 @@
+# Racing-driver AI improvements: arcade and advanced
+
+## Goal and acceptance
+
+Improve both built-in drivers relative to the September 9 advanced-AI closeout. Measure braking, corner exit and traffic decisions under unchanged physics. Preserve arcade defaults, public actions/observations, deterministic stepping, recovery, pits and package layout. Faster solo driving is insufficient if representative full fields become substantially less reliable. No claim of globally optimal driving.
+
+## Checkable plan
+
+- [x] Preserve a source snapshot and inspect current dirty Git state and driver ownership.
+- [x] Complete baseline package gate and matched solo/full-field measurements for both modes.
+- [x] Diagnose concrete pace losses; compare bounded independent candidates in isolated source copies.
+- [x] Select changes on lap times, contacts, off-road time and finish rate; reject fragile gains.
+- [x] Integrate feature-owned controls, meaningful production regressions and authoritative docs.
+- [x] Repeat accepted races, compare unchanged raw physics, measure CPU cost with paired existing benchmarks.
+- [x] Pass package/release/browser/packed-consumer gates; update Linear and report read-only Git status.
+
+## Ownership and design gate
+
+`driver/racingControls.js` dispatches modes and preserves its existing internal exports. Arcade `arcadeRacingControls.js` owns target-line composition, geometric steering, edge guarding and pedals; `arcadeRacePace.js` owns preview and corner-line planning. `driverController.js` owns the backward-facing recovery transition. Advanced `advancedRacingControls.js` composes geometric steering, existing traffic planning and `advancedRacePace.js` speed envelopes; `advancedPathControls.js` also serves recovery/safety driving, which must remain stable. `racingLinePlan.js` owns shared overtaking intentions. Vehicle modules exclusively own physical forces/integration and the analytic arcade tarmac corner-capacity estimate; physical laws and constants are not tuning targets.
+
+Inputs are track geometry, vehicle capability/state, existing traffic and racing intentions. Outputs remain bounded steering/throttle/brake. Candidate logic must have a narrow feature owner, no whole-app helper or hidden persistent state. The racing-driver hypotheses are braking too early or too late, unnecessary coasting, failing to unwind steering on exit, and confusing overtaking intention with available space. Each must be supported by simulation traces before adoption.
+
+Risks: corner-entry understeer, exit oversteer, oscillatory controls, unsafe passing, tire wear, pit-coordinate mismatches and procedural-track overfitting. Evaluate development and held-out tracks, complete ten-car races with wear/pits, recovery regressions and deterministic repeats. Any structural or behavior change requires evidence and matching documentation.
+
+## Baseline and artifacts
+
+Baseline source: `/tmp/paddockjs-racing-ai-20260909/baseline`. Earlier ongoing work, including the first advanced AI improvement, is preserved. No Git/GitHub mutations are authorized or performed.
+
+## Verified findings and candidate decisions
+
+- Arcade speed preview (`driver/racingControls.js`): the sharpest future curvature became the current corner target, ignoring braking distance. In track 20260427, the car slowed from 283 km/h at 239 m to 151 km/h at 432 m while the road was still straight; the first bend began around 540 m. A distance-aware envelope avoids unnecessary early braking while retaining conservative reaction distance.
+- Arcade steering combined target-point angle, future-heading feedforward and lateral correction. On track 7110 at 1319 m, the target required negative steering, but the combined controller commanded positive steering before any tire saturation. Pure pursuit inverted through arcade's own bicycle yaw relation points toward the intended path and compensates tire condition, avoiding contradictory corrections.
+- Arcade corner targets barely responded to tire wear. Its physical lateral capacity scales static grip with tire factor squared and downforce with tire factor. Worn tires therefore require much lower corner speeds than the old 96 km/h corner floor. The driver must respect a physical ceiling after intentional pace floors and DRS bonuses.
+- Baseline arcade full fields finished 44/60: all 16 retirements were stalled off track. Worn-tire gravel drive capacity can be lower than rolling resistance even at maximum drive, so simply raising recovery throttle cannot fix these departures. The accepted direction prevents avoidable departures instead of altering physics.
+- Advanced: tighter/longer geometric pursuit and a corner-profile offset did not give useful repeatable gains. Aggressively later braking was faster alone but slower and less clean in traffic. These variants are rejected. The accepted advanced change restrains lateral lane movement under corner load, releasing it on exit. Combined with a modest braking-preview reserve change from 50% to 55%, it improves solo pace and field reliability; the 60% corner reserve, steering model and recovery controls remain unchanged.
+
+Baseline `npm run check` passed with 1043 fast tests and 88 slow skips, plus types, packing, consumer/build and browser gates. There were no pre-existing gate failures. Both modes completed all 16 wear-disabled solo stints. Arcade accumulated 273.733 seconds off road; advanced had zero. Advanced baseline full fields finished 60/60.
+
+## Accepted implementation and limits
+
+Arcade uses inverse bicycle-model pursuit with tire-condition compensation, a 12 m sampled speed preview and conservative braking/reaction distance. Existing rating, aggression, DRS, edge and traffic inputs remain, but they cannot exceed the worn-tire corner ceiling. The old generic control profile and discarded additive steering calculations were removed. Recovery handles backward-facing placements; it does not alter the physical ability to escape a surface.
+
+Advanced keeps the existing pursuit model and following-distance safety. Its selected lane target interpolates from the actual chassis center toward the planned lane according to unused cornering budget, preventing abrupt lateral moves while heavily loaded. The braking preview uses 55% of estimated available capacity after lateral demand, still below the longitudinal control limit. The shared 60% racing corner reserve remains unchanged. There are no persistent new state owners, caches, added grip, position corrections or public API changes.
+
+Both controllers remain deterministic heuristic drivers. Results do not establish global optimality or guarantee clean racing on every procedural track, setup or user placement. Nonzero contacts and brief field excursions remain. Arcade's physical worn-tire gravel stall limitation is unchanged.
+
+## Driving measurements
+
+Same Node v24.13.0, Darwin arm64, fixed 1/60 s step, seeds, tracks, drivers, entries and rules before/after. Solo tests use race seed 100, one bundled driver, three laps, no standing-start sequence and tire wear disabled. Flying time is the mean of laps two and three. The first eight tracks are development cases; the remaining eight are held-out cases. All 32 final solo runs finish without off-road time or DNFs.
+
+| Track seed | Arcade before (s) | Arcade after (s) | Quicker | Advanced before (s) | Advanced after (s) | Quicker |
+| --- | ---: | ---: | ---: | ---: | ---: | ---: |
+| 7109 | 137.150 | 123.317 | 10.09% | 144.167 | 143.550 | 0.43% |
+| 7110 | 173.533 | 138.183 | 20.37% | 168.150 | 167.050 | 0.65% |
+| 7200 | 149.911 | 129.508 | 13.61% | 150.284 | 149.227 | 0.70% |
+| 7201 | 161.142 | 136.633 | 15.21% | 169.517 | 168.683 | 0.49% |
+| 12 | 138.833 | 122.031 | 12.10% | 139.349 | 138.300 | 0.75% |
+| 26 | 131.171 | 107.467 | 18.07% | 123.000 | 122.083 | 0.75% |
+| 61 | 178.065 | 148.900 | 16.38% | 179.783 | 178.733 | 0.58% |
+| 20260427 | 151.693 | 132.901 | 12.39% | 155.567 | 154.983 | 0.37% |
+| 28 | 167.533 | 140.450 | 16.17% | 176.150 | 174.817 | 0.76% |
+| 62 | 161.783 | 136.908 | 15.38% | 161.267 | 160.250 | 0.63% |
+| 69 | 147.695 | 131.817 | 10.75% | 158.598 | 157.742 | 0.54% |
+| 7202 | 141.001 | 117.417 | 16.73% | 138.433 | 137.667 | 0.55% |
+| 7203 | 104.985 | 96.867 | 7.73% | 104.033 | 102.988 | 1.00% |
+| 101 | 134.817 | 118.967 | 11.76% | 136.767 | 136.267 | 0.37% |
+| 9099 | 182.923 | 156.383 | 14.51% | 199.017 | 198.400 | 0.31% |
+| 12345 | 153.847 | 127.745 | 16.97% | 149.667 | 148.783 | 0.59% |
+
+Full fields use the six actual demo configurations with ten driver/entry pairs, normal tire wear, pits and interactions. Hero runs five laps; others run three. **Arcade baseline retires 16 cars, so its field-duration differences are not equal-completion race comparisons.** Finish counts, incidents and clean solo pace must be considered together.
+
+### Arcade full fields
+
+| Field | Finishers before → after | Last finish before → after (s) | Mean finish before → after (s) | Contacts | Off-road (car-seconds) |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| hero | 8 → 10 | 796.733 → 724.667 | 776.554 → 701.100 | 82 → 50 | 279.933 → 0.000 |
+| components | 7 → 10 | 627.967 → 501.733 | 584.274 → 482.592 | 73 → 65 | 542.517 → 2.467 |
+| dashboard | 5 → 10 | 530.417 → 445.800 | 503.560 → 433.562 | 70 → 43 | 371.350 → 0.000 |
+| timing-overlay | 6 → 10 | 618.467 → 497.467 | 568.528 → 479.483 | 82 → 52 | 381.100 → 0.000 |
+| compact-race | 8 → 10 | 509.283 → 407.633 | 478.856 → 393.245 | 75 → 57 | 228.617 → 0.167 |
+| full-dashboard | 10 → 10 | 350.583 → 329.283 | 336.478 → 311.360 | 57 → 38 | 79.733 → 1.067 |
+
+Total finishers: 44/60 → 60/60. Contacts: 439 → 305. Aggregate off-road time: 1883.250 → 3.700 car-seconds.
+
+### Advanced full fields
+
+| Field | Finishers before → after | Last finish before → after (s) | Mean finish before → after (s) | Contacts | Off-road (car-seconds) |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| hero | 10 → 10 | 864.083 → 887.817 | 846.897 → 839.533 | 10 → 12 | 5.650 → 0.000 |
+| components | 10 → 10 | 601.567 → 597.350 | 590.820 → 586.737 | 7 → 3 | 0.100 → 0.300 |
+| dashboard | 10 → 10 | 532.883 → 528.933 | 520.068 → 516.378 | 5 → 1 | 0.000 → 0.467 |
+| timing-overlay | 10 → 10 | 609.700 → 604.583 | 595.245 → 591.433 | 6 → 3 | 0.100 → 0.767 |
+| compact-race | 10 → 10 | 491.167 → 486.567 | 478.878 → 475.007 | 7 → 3 | 0.000 → 0.433 |
+| full-dashboard | 10 → 10 | 370.817 → 356.183 | 353.282 → 345.350 | 9 → 6 | 3.917 → 0.000 |
+
+Total finishers: 60/60 → 60/60. Contacts: 44 → 28. Aggregate off-road time: 9.767 → 1.967 car-seconds.
+
+Advanced mean finishing times improve in every field, but hero's last-car completion is 2.75% slower (864.083 → 887.817 s). This is an explicit tradeoff, not a universal race-duration improvement. Five other fields finish sooner. The tight full-dashboard field improves from 370.817 to 356.183 s. Arcade's baseline means include only its surviving finishers; they are shown for context rather than treated as a matched population speed claim.
+
+## Measurement integrity
+
+The two existing AI harnesses now accept validated `--physics-mode arcade|advanced`; advanced remains the default for existing invocations. Solo records include source fingerprints. Field benchmark v2 derives lap intervals from canonical timing-line crossings, because pit movement can advance completed-lap counters before `lastLapTime` updates. Each finished car's lap intervals reconcile with its finish time within one fixed step. Completed pit exits are read from `pitStop.stopsCompleted` and checked against pit-exit events; pit service completion is a separate event. This corrects reporting only and leaves trajectory/event hashes unchanged.
+
+All final solo trajectories match the accepted isolated candidates exactly. Both modes' six full fields are repeated twice with exact deterministic result hashes. Source fingerprint for the final simulation/data tree: `29c71119c480dfca686dc479545ad4b7e4098af9738c63e85100067ba83a6998`.
+
+## Verification and runtime cost
+
+- Baseline package gate passed without pre-existing failures.
+- Focused AI suite: 44 passed, including worn-tire/DRS/braking/steering/wrong-way cases, loaded-corner lane restraint, clean stints and complete fields. Existing advanced full-field assertions were strengthened.
+- An initial release run failed the old assertion that a particular 30-second approach must reach over 7 m lateral offset. The new faster line reaches 6.181 m there, but reaches 8.085 m on the tight demo circuit with legal kerb use. The original pace fixture and all its speed/off-road thresholds remain; the unchanged 7 m threshold now has a dedicated 90-second tight-circuit test, additionally requiring actual kerb contact, legal surfaces and average speed above 180 km/h. All 10 driver-controller tests passed after this coverage separation; no runtime change or relaxed numeric threshold was used to pass it.
+- Raw physics: 216 combinations across both modes, three surfaces, three tire states, three speeds and four control patterns, each integrated for 120 steps. Complete vehicle states match baseline exactly.
+- Package `npm run check` passed on the final runtime source: 1051 fast tests, 92 slow skips, docs, public types, dry pack, packed-consumer install/build and bundle checks, showcase/demo builds, quick Chromium and demo smoke. Final `npm run check:release` passed with all 1144 tests across 62 files, public types, pack/consumer/build checks, the full Chromium matrix and demo smoke (desktop runtime, public surfaces, presets, expert, headless, search and mobile layout).
+- Twelve paired runs (two batches of six, alternating before/after order) of all 23 standard runtime workloads passed `--verify`. Same Apple M4 Pro host, Node v24.13.0 and settings; our test/benchmark processes were otherwise stopped. The unchanged local-preview source dependency was copied into the frozen baseline to run the common harness. The measured field workloads include setup, instrumentation and 180 steps for 16 cars; these are not browser frame timings.
+
+| CPU workload | Before median (ms) | After median (ms) | Before range (ms) | After range (ms) |
+| --- | ---: | ---: | ---: | ---: |
+| Arcade field | 46.916 | 52.846 | 45.239–69.124 | 50.845–154.979 |
+| Advanced field | 174.944 | 163.604 | 167.632–250.340 | 159.241–400.565 |
+| Headless vector | 140.565 | 134.068 | 132.149–163.235 | 127.945–275.706 |
+
+Arcade has a consistent planning cost: the two batch median comparisons are +13.26% and +13.11%; the pooled comparison is +12.64% (about 5.93 ms per whole field workload). Advanced's batch signs disagree (+17.38% versus −7.17%), with overlapping ranges/outliers; the pooled −6.48% median is **not a reliable throughput improvement claim**. The headless-vector batches likewise disagree. No CPU speedup is claimed or speculative cache introduced. All raw runs and per-workload comparisons remain in the task artifacts.
+
+## Changed files and closeout
+
+Runtime: `src/simulation/driver/racingControls.js`, new `arcadeRacingControls.js` and `arcadeRacePace.js`, `driverController.js`, `advancedRacingControls.js`, `advancedRacePace.js`, and `src/simulation/vehicle/vehiclePhysics.js` (analytic planning helper only). Tests: new `src/__tests__/arcadeAIRacing.test.js`, updated `advancedAIRacing.test.js`, and a separated kerb-use characterization in `driverController.test.js`. Measurement: `scripts/benchmark-advanced-ai.mjs`, `benchmark-advanced-ai-fields.mjs`, `runtimeEfficiencyBenchmarks.mjs`. Documentation: `docs/rules.md`, `architecture.md`, a historical follow-up link in `advanced_ai_pace.md`, and this report.
+
+Artifacts: `/tmp/paddockjs-racing-ai-20260909/`, including frozen baseline, accepted/rejected source copies, JSONL measurements, physics comparison and gate logs. Reproduce:
+
+```sh
+node scripts/benchmark-advanced-ai.mjs . 7109,7110,7200,7201,12,26,61,20260427,28,62,69,7202,7203,101,9099,12345 --physics-mode arcade
+node scripts/benchmark-advanced-ai.mjs . 7109,7110,7200,7201,12,26,61,20260427,28,62,69,7202,7203,101,9099,12345 --physics-mode advanced
+node scripts/benchmark-advanced-ai-fields.mjs . --physics-mode arcade --repeats 2
+node scripts/benchmark-advanced-ai-fields.mjs . --physics-mode advanced --repeats 2
+node scripts/benchmark-runtime-efficiency.mjs --profile=standard --json --verify
+npm run check
+npm run check:release
+```
+
+Git remains approval-gated. Existing dirty work is preserved; this task does not establish repository-wide cleanliness. Review the bounded changes against the task snapshot and the combined working diff before proposing exact staging/commit actions. No Git/GitHub mutation is authorized or performed.
+
+Work log: [Racing-driver AI improvements: arcade and advanced](https://linear.app/mgiorgetti/document/racing-driver-ai-improvements-arcade-and-advanced-9dac1149e8ab).
+
+Current read-only Git inspection: branch `v11`, HEAD `fedff4e`, recorded `origin/v11` at 0 ahead/0 behind without fetching; index empty, 123 modified tracked paths and 50 untracked entries. Earlier work is preserved.
+
+Subsequent skill-dependent physical-envelope tuning, timing-line boundary repair and measured limitations are documented in [limit driving, 2026-10-14](limit_driving_2026-10-14.md). Earlier results above describe their recorded candidate.

package/docs/rules.md

@@ -1,5 +1,9 @@
 # Race Rules
 
+## Optional Grid Walk presentation
+
+[Grid Walk](grid_walk.md) holds normal browser playback before the existing start sequence. The first Race transition clears the crew before simulation time advances; reduced/paused motion clears immediately. Returning later pauses the race and renders original starting poses without writing them into physics. Resuming preserves time, laps, RNG, cars, tires, pits and order. Rolling starts remain rolling starts. Only explicit restart creates a fresh race.
+
 This file documents the rules currently implemented by the simulator. If the race engine changes, update this file with the behavior change.
 
 ## Default Race Rules
@@ -190,6 +194,8 @@ The simulation builds hidden timing lines around every track at an F1-style mini
 
 Seconds gaps are the difference between when two cars crossed the same timing line. The race engine falls back to timing-history interpolation only before the cars have a shared timing-line sample. The timing tower can switch at runtime between `Int` mode, which displays interval to the car ahead, and `Gap` mode, which displays direct gap to the leader. When the relevant gap is one or more whole laps, the tower shows `+1`, `+2`, and so on instead of a misleading seconds estimate. Timing continues to be calculated during pre-start, safety-car, and post-finish states even when the UI shows state labels such as `Grid`, `SC`, or `FIN`.
 
+Lap telemetry clamps `completedLaps` to the configured `totalLaps`, including overshoot in large or accelerated fixed steps, so post-finish snapshots cannot report more completed laps than the race distance contract allows.
+
 ## Units
 
 The race engine uses simulator units internally. `src/simulation/units.js` converts simulator distance and speed to public meter and km/h values. Public timer, lap-time, sector-time, gap-time, penalty-time, and service-countdown values are seconds. Public distance values with a `Meters` suffix are meters. The current speed calibration maps the simulation maximum speed to an F1-like `330 km/h`; rendered car sprite dimensions are a visual scale and are not used as the physical distance scale.
@@ -198,7 +204,23 @@ The race engine uses simulator units internally. `src/simulation/units.js` conve
 
 The default `physicsMode` is `'arcade'`, which preserves the existing forgiving vehicle behavior for current browser hosts and demos.
 
-`physicsMode: 'advanced'` is opt-in for more believable F1-style limits. It still accepts only normal steering, throttle, brake, and pit-intent inputs, but the vehicle integrator keeps a real 2D world velocity, derives speed from that velocity, and applies a traction budget between longitudinal and lateral demand. Steering changes yaw through a rate-limited response, while body slip is derived from the difference between the car heading and actual velocity direction instead of being an artificial movement offset. External state placement through simulator APIs rejects non-finite numeric values and resynchronizes `velocityX/Y` whenever speed or heading is changed without an explicit velocity vector, so scenario/reset placement cannot leave stale advanced-mode velocity behind. Kerbs remain legal racing surface, but high-load kerb use is less stable and slower than track asphalt. Gravel and grass are averaged per wheel so one wheel over the edge creates partial grip/drag loss, while all-wheel runoff still costs major time. The rendered barrier wall is the hard outer runoff boundary in both physics modes; cars whose footprint reaches the wall's inner face are marked `destroyed`, stopped, removed from active collision and sensor participation, and placed in DNF timing order. Barrier destruction, stalled DNF, pre-start grid hold, red-flag hold, and pit-queue hold freeze scalar speed and advanced-mode velocity together; clearing a red flag resynchronizes active cars to the release speed and heading before the next observation while DNF/out-of-race cars remain frozen. `physicsMode` changes vehicle integration and grip behavior, not barrier consequences. Advanced mode does not teleport cars, magnetize them to the track, or bypass physics with hidden pose correction.
+`physicsMode: 'advanced'` is an opt-in planar Formula-style handling model. Four contact patches produce longitudinal/lateral forces from local wheel velocity, surface grip and load. A nonlinear lateral brush curve shares each tire's friction circle with rear-wheel drive or braking. Centered 50/50 static mass, longitudinal and lateral load transfer, tire load sensitivity, front brake bias, aerodynamic downforce and drag affect the available forces. Force and moment sums integrate world velocity and yaw inertia at internal steps no larger than 1/240 s. Steering commands set a rate-limited physical wheel angle; speed-dependent keyboard conditioning belongs to the human input layer, not vehicle physics or policy actions. Tire forces create steering resistance through their directions; the old synthetic steering-scrub and target-yaw formulas are removed.
+
+The demo advanced lab applies human-only keyboard assistance: key travel ramps before speed-dependent steering lock, and observed tire overload reduces the digital accelerator demand to reserve turning grip. It does not steer toward the track or change the physical forces. Its host scheduler caps stepping at 60 Hz independently of display refresh and discards catch-up debt after a stall. External policy action scaling and the general controller-loop scheduler contract are unchanged.
+
+The existing setup ratings remain intact. For the baseline car, `powerNewtons` times 0.5 sets peak rear drive force, transitioning at 28 m/s to constant power (602 kW for the default 43000 N rating). `brakeNewtons` is apportioned 57% front / 43% rear before tire adhesion; full default braking can hold the car against full throttle. Braking and rolling resistance share a contact stopping-impulse budget so they cannot create reverse motion or energy at rest. DRS reduces aerodynamic drag and downforce. The existing 330 km/h integration envelope is retained. These are explicit simulation calibrations, not proprietary F1 data.
+
+Body slip is actual velocity direction minus body heading. Kerbs are legal but reduce available grip; a slipping car can lose steering authority rather than always losing more scalar speed. Gravel and grass affect each contact patch separately, including asymmetric resistance and yaw moments. Wheel load transfer is quasi-static: no suspension travel, vertical motion, tire carcass/temperature model or individual wheel rotational state is simulated. Brake demand beyond adhesion is approximated as a contact sliding against its actual velocity; gear shifts, wheel-spin dynamics and a full collision manifold are outside this model.
+
+Advanced car contacts use mass/inertia-dependent normal impulses with a contact point approximated from opposing oriented body support features. They do not directly rotate the heading. Arcade contact response is unchanged. Existing fixed pit-car ownership, contact event deduplication and stewarding remain authoritative. Rendered barriers still destroy cars at the same footprint boundary; advanced physics does not soften that race rule.
+
+External state placement rejects non-finite values and resynchronizes world velocity when speed/heading changes without an explicit velocity vector. Grid/red-flag/queue/terminal holds freeze velocity, yaw and acceleration together. Pit routing remains the existing bounded route movement and service model. Advanced racing AI follows the velocity direction and adds the front tire slip needed to produce its requested turning force. Its race-specific speed planner uses dynamically transferred contact loads and the weaker yaw-balanced axle rather than a fixed share of static total grip. It solves upcoming corner limits using downforce at the candidate corner speed, then works backward through a sampled braking envelope that reserves lateral grip. The actual overtaking/correction path can impose a tighter limit than the centerline. A bounded force controller compensates drag and rolling resistance and responds quickly enough to follow that braking envelope. The 330 km/h package envelope is a ceiling, not a guaranteed speed: engine force, drag, tires, traffic and track geometry determine the achieved pace.
+
+The advanced racing controller matches a slower car's speed and physical following gap until there is actual lateral clearance, even when a pass is planned. It retains the existing lane selection, traffic penalties and recovery/safety-car controllers. All changes produce ordinary steering/throttle/brake commands; there are no pose writes or extra grip. Pace and racecraft determine control ability; consistency determines bounded continuous line and speed-judgement variation. Risk tolerance and aggression independently reduce the chosen margins. Skill does not add physical grip or power, and mistakes are not scheduled accidents. Advanced corner force budgets range from 74% to 96% of the predicted dynamically loaded balanced-axle bound; longitudinal budgets range from 86% to 98%. These policy budgets are not measured utilization of every tire. The current vehicle, tires, surfaces, DRS and traffic remain limiting.
+
+Advanced braking preview inspects contiguous geometry from the current position. It reserves the steering pursuit distance, the controller yaw-response and driver anticipation distances, and one sampling interval before counting available braking distance. It must not shift its sampling origin past nearby bends. Pedals reserve lateral adhesion and account for rear-drive allocation, brake bias, load transfer and resistance. The bounded brake solver handles a feasible nonzero braking window even when zero braking overloads the front axle. Arcade racing uses its own actual yaw and longitudinal limits, with a shorter smooth pursuit horizon in tight geometry; it does not introduce an advanced friction circle. Recovery, safety-car and automatic pit controllers retain their separate ownership.
+
+Measured pace, incidents, rejected alternatives and limitations are recorded in [the first advanced AI pace report](advanced_ai_pace.md), [the both-mode racing AI report](racing_ai_improvements.md), and [the skill-dependent limit-driving report](limit_driving_2026-10-14.md).
 
 Simulator snapshots and environment observations expose additional vehicle telemetry: `lateralG`, `longitudinalG`, `gripUsage`, `slipAngleRadians`, `tractionLimited`, and `stabilityState`. These fields are optional public telemetry; existing `speedKph`, wheel-surface, steering, throttle, and brake fields remain unchanged.
 
@@ -206,11 +228,13 @@ Simulator snapshots and environment observations expose additional vehicle telem
 
 Lap is computed from each car's cumulative race distance over the track length. Total laps are provided by mount options and default to `10`.
 
+Hidden timing-line crossings use exact forward `(previousDistance, currentDistance]` boundaries and the same representable line distance for indexing and recording. A car infinitesimally before a line must still record that crossing; no tolerance band may silently drop a lap timestamp.
+
 Each track is automatically divided into three equal sectors. Sector and lap telemetry is recorded when a car's cumulative race distance crosses a sector boundary or start/finish boundary. Completed current-lap sector split times before the active sector are exposed as `currentSectors`, while `liveSectors` keeps only the active sector's elapsed time updated before the boundary is crossed and clears any future-sector values. `sectorProgress` is recomputed every snapshot as the live S1/S2/S3 fill state for the current lap, so sector-map UI does not derive progress from completed split state or keep stale future sectors lit. Timing values are stored in seconds and exposed on each car snapshot as `lapTelemetry`.
 
 Each car is marked `finished` when it reaches `track.length * totalLaps`. It receives a frozen provisional `finishRank`, exposes `raceStatus: 'waved-flag'` / `wavedFlag: true`, and emits a `car-finish` event. The first finisher becomes provisional `winner`, but the race keeps running until every race participant has either crossed the finish distance or is currently DNF. While the field is still finishing, timing order keeps already-finished cars in provisional finish order ahead of cars still running, and DNF cars sit below active cars in the order they retired. A car that has already crossed the finish line keeps that result even if it later touches the barrier or satisfies stalled-off-track detection while the rest of the field is still finishing; post-finish retirement checks do not turn it into DNF. A DNF car restored before final classification re-enters the live order and must finish before the race can complete; restoring it after final classification does not reopen the race.
 
-When all cars have finished or reached DNF, the simulator records `finishedAt` and final `classification`, emits a `race-finish` event, freezes order to the classified result after outstanding penalties and classification consequences, deploys the safety car, and switches race mode to `safety-car`. DNF classification entries appear after finishers with `finished: false`, no finish time, and DNF reason/time/order metadata. Finished cars keep circulating under safety-car behavior instead of hard-stopping. The current implementation does not yet implement championship scoring.
+When all cars have finished or reached DNF, the simulator records `finishedAt` and final `classification`, emits a `race-finish` event, freezes order to the classified result after outstanding penalties and classification consequences, deploys the safety car, and switches race mode to `safety-car`. DNF classification entries appear after finishers with `finished: false`, no finish time, and DNF reason/time/order metadata. Finished cars keep circulating under safety-car behavior instead of hard-stopping. Timing presentation derives its final state from `raceControl.finished`, so winner and `FIN` labels remain final even though circulation mode is now `safety-car`. The current implementation does not yet implement championship scoring.
 
 ## DRS
 
@@ -263,7 +287,7 @@ The AI has separate behavior for:
 - Off-track rejoin.
 - Safety-car queueing.
 
-Green-flag behavior uses:
+Arcade green-flag behavior uses:
 
 - Driver aggression.
 - Racecraft.
@@ -271,22 +295,22 @@ Green-flag behavior uses:
 - Patience.
 - Current tire energy.
 - Track curvature.
-- Capped preview curvature for braking decisions.
-- Forward track-heading feed-forward for corner entry.
+- Distance to upcoming bends and available braking distance.
+- Geometric pursuit of a forward lane target, adjusted for tire response.
 - Nearby traffic.
 - Preferred and available lane offsets.
 
-The built-in racing controller still drives through normal vehicle inputs only. It chooses a forward racing target, blends steering from the target angle, upcoming track heading, lateral offset, edge recovery pressure, outward edge motion, and a corner-apex racing-line offset, then sends clamped steering/throttle/brake values into the vehicle physics integrator. It is expected to use the available track width and kerbs on generated circuits, including sharp generated turns. When heading alignment, steering load, or outward edge motion shows the car cannot yet carry throttle through a corner, throttle is cut before braking is requested so the controller does not fight itself. It does not snap car position, override heading, or bypass steering-rate/yaw-rate limits.
+The arcade racing controller drives through normal vehicle inputs only. It chooses a forward racing target using lane intentions, corner offsets and edge pressure, then inverts the arcade bicycle yaw response to steer toward that target. This avoids contradictory target-angle and future-heading steering commands. The driver samples upcoming corners and retains speed until braking distance requires a slowdown, reserving reaction distance and conservative deceleration. Driver ratings and DRS influence desired pace, but a tire-condition-aware yaw-capacity ceiling takes precedence over corner and maneuvering speed floors. Heading/edge/steering-load penalties and bounded pedal controls remain active. A backward-facing car enters the existing recovery controller before forward racing pursuit resumes. No position, heading, force or steering-rate limit is overridden.
 
-In advanced mode, the built-in controller uses separate tuning: earlier lookahead for braking, smaller high-speed steering requests, stronger edge recovery before the legal limit, throttle reduction when grip and slip telemetry show the car is overloaded, a higher legal-road speed floor so the baseline AI does not crawl through generated bends, and lower rejoin targets from kerb, grass, or gravel states. Extra stability braking is applied only when upcoming corner load, edge pressure, outward drift, high straight speed, or near-target speed makes it useful; ordinary below-target straight-line correction should not trigger brake pulses. This is intentionally a baseline driver, not a trained policy.
+Advanced green-flag driving uses velocity-oriented pursuit with inverse tire-slip steering, a candidate-speed corner/braking envelope and bounded force control described under [Physics Modes](#physics-modes). The additional following limit uses actual chassis-center spacing and the speed of a physically blocking car; lane selection alone is not evidence that a pass has cleared it. While cornering consumes the racing grip budget, the driver reduces lateral movement toward the planned lane and holds a consistent line. It progressively releases the lane change as corner load falls on exit. Driver ability and risk determine the chosen lateral and longitudinal margins within the four-contact physical envelope; braking reserves lateral demand and the pursuit/response/anticipation distance. The former fixed 60% corner and 55% braking shares are superseded by this policy. The built-in driver is a deterministic heuristic policy, not a trained model or a globally optimal racing-line solver.
 
-Traffic decisions use real meter-scaled gaps and lateral spacing, not raw simulator-size constants. A trailing car inside the attack window commits toward a visible passing lane instead of sitting on the centerline. A leading car with a close rear threat can defend the threatened side before the rival is fully alongside. Side-by-side overlap still creates spacing pressure so defensive and attacking moves are expressed as target-line choices and normal steering/brake/throttle inputs, not as collision avoidance teleports or artificial position overrides.
+Traffic decisions use wrapped physical track gaps and chassis-center lateral spacing in the retained main-track frame. A lapped car or a car across the start line can be the nearest physical passing/following target regardless of classification rank. Retired, destroyed and collision-disabled participants do not create blocking or defensive pressure; separate pit-lane traffic is excluded from tactical lane targets while overlapping pit-entry traffic still counts. Race classification and timing gaps keep their existing cumulative-distance meaning. Current measured comparisons and limitations are recorded in [the v11 improvement evidence](v11_improvements.md).
 
-Rejoin behavior also remains physics-driven. When a car leaves the legal racing surface, the controller enters a short recovery hold and keeps using rejoin controls after the center point first reaches track or kerb until heading and edge margin are stable. That prevents the car from immediately returning to full racing throttle while still pointed across the track. Recovery targets look forward along the racing surface, bias inward from the edge, and request bounded surface-specific speeds for track, kerb, grass, and gravel states. In advanced mode, rejoin controls also watch signed outward velocity relative to the track normal: a car sliding farther into runoff cuts throttle or brakes before trying to accelerate out, while very low-speed gravel/grass recovery limits steering lock and caps throttle when the heading is still outward so steering scrub does not pin the car in place. Barrier contact is not a recovery state; it destroys the car.
+Both modes match a physically blocking car's speed and following gap until lateral clearance exists. This limit takes precedence over arcade maneuvering speed floors, so stopped traffic can require stopping. A committed pass suppresses conflicting rear-defense movement, and a driver does not defend against a physically rearward car that is lapping it. Arcade drivers hold their current chassis line during loaded turns with nearby traffic and release that hold on exit; inward edge recovery takes priority. Advanced drivers constrain their final target to the lateral corridor available beside overlapping cars, rather than checking only an intermediate lane intention. Their corner line hold also permits inward correction near the road edge. These choices remain ordinary steering/brake/throttle inputs with no physics overrides.
 
-Advanced-mode steering scrub is dissipative in both forward and reverse motion. It opposes the signed forward velocity instead of always applying negative forward acceleration, so a car sliding backward with zero throttle cannot gain speed from steering scrub.
+Rejoin behavior remains physics-driven. A recovery hold prevents a car from immediately returning to racing pace while heading or edge margin is unstable. Arcade recovery uses inward-biased targets and outward-edge-motion checks. Advanced recovery follows a centerline target ahead at reduced surface-dependent speed, budgets lateral tire capacity and arrests a large sideways/backward slide before accelerating toward the track. At crawling speed, worn-tire runoff recovery includes rolling resistance within the rear tires' available adhesion so the car is not held below the force needed to move. Barrier contact still destroys the car; recovery does not soften that rule.
 
-Tire energy can degrade to 1%. The vehicle physics layer converts tire energy into a nonlinear grip factor, so degradation has a visible performance cost across the full 100% to 1% range while still leaving a damaged car controllable enough to return to the pits.
+Tire energy can degrade to 1%. The vehicle physics layer converts tire energy into a nonlinear grip factor, so degradation has a visible performance cost across the full 100% to 1% range. Recovery is not guaranteed on every surface: in arcade mode, sufficiently worn tires at rest in gravel can have less available drive acceleration than rolling resistance. The racing AI accounts for remaining corner capacity to avoid unnecessary departures; it does not add recovery force.
 
 ## Vehicle Physics
 
@@ -323,11 +347,13 @@ Track state can classify a car as on:
 
 Surface affects grip, drag, and rolling resistance.
 
-Surface physics is wheel-based. `src/simulation/vehicle/wheelSurface.js` classifies each wheel contact patch against the track model and the car uses the worst current surface for physics: `barrier > gravel > grass > kerb > pit-box > pit-lane > pit-entry/pit-exit > track`. Normal main-track running uses an analytic signed-offset fast path from cached wheel geometry, and pit connectors first resolve wheel centers through local connector geometry before falling back to full patch sampling only for genuinely ambiguous pit-road overlap. One wheel on gravel slows the car with gravel behavior even if the other three wheels are on asphalt. In addition, `vehiclePhysics.js` compares left-side and right-side wheel resistance and applies a small capped yaw-rate bias toward the slower side, so asymmetric gravel/grass/kerb contact can tug the car toward the dirty side without becoming a full tire-force simulation. One wheel on kerb reports `kerb` and applies kerb-level grip/drag without causing a track-limit violation by itself. If the car footprint reaches the rendered barrier wall's inner face, every physics mode marks the car destroyed instead of treating the wall as recoverable low-grip road. Pit entry, pit lane, pit exit, and pit-box surfaces remain legal drivable surfaces and do not count toward stalled off-track DNF timing.
+`src/simulation/vehicle/wheelSurface.js` classifies each wheel contact patch against the shared track model. Its worst-surface classification (`barrier > gravel > grass > kerb > pit-box > pit-lane > pit-entry/pit-exit > track`) remains the car's reported surface and arcade grip/drag input. Arcade also retains its capped asymmetric wheel-resistance yaw bias. Advanced physics instead uses each wheel's own surface and normal load to calculate forces; one wheel on gravel is not equivalent to four wheels on gravel.
+
+Normal main-track wheel queries use the existing analytic signed-offset path; pit connectors resolve wheel centers locally and use full patch sampling for ambiguous overlap. One wheel on a kerb does not itself violate track limits. Reaching the rendered barrier wall's inner face destroys the car in either mode. Pit entry, lane, exit and box remain legal surfaces and do not count toward stalled off-track DNF timing.
 
 Rendered material bands use those same thresholds. The visible gravel band starts at the outer kerb edge and ends at the simulated gravel edge; the visible runoff band starts at the gravel edge and ends at the barrier centerline; the barrier wall is drawn from the same `track.barrierWidth` used by destruction. Rendering, ray surface hits, wheel-surface classification, and barrier destruction must stay on this shared geometry contract.
 
-When pit stops are enabled, each team is assigned one shared service area in the working lane plus two garage boxes. Driver pairs share the service area, and the service area, queue slot, and garage boxes inherit the team color from `driver.team.color` when present, otherwise the lead driver's color. The current automatic stop plan distributes pit calls across available race laps as bounded pit trains, then lets opportunistic cars join the entry only when fewer than `pitStops.maxConcurrentPitLaneCars` are active and the nearest active pit-lane car is at least `pitStops.minimumPitLaneGapMeters` ahead; committed cars enter at the next pit-entry window and can queue in the working lane if their team service area is busy. Built-in AI cars also request stops from tire condition: below `pitStops.tirePitRequestThresholdPercent` they request `pitIntent: 1`, and below `pitStops.tirePitCommitThresholdPercent` they request `pitIntent: 2`. Expert-controlled cars do not receive those tire-threshold automatic calls; their model or host must request the stop with `pitIntent`. Hosts and expert actions can change a pending stop with `pitIntent`: `0` clears the pending call, `1` stays active until a free-enough pit-entry window appears, and `2` commits to entering at the next pit-entry window even if capacity or gap checks would block mode `1`. The same request may include a target compound, either through `setPitIntent(driverId, intent, targetCompound)` or expert action `pitCompound`; invalid compounds are rejected. Pit intent and target compound are locked while the car is entering, queued, servicing, or exiting, and intent resets to `0` after pit exit. Completed stops can be re-armed by later tire condition or host intent, so pit stops are not one-use per race. Safety-car mode does not block pit intent. Closed pit-lane race-control state keeps pending calls on track until `setPitLaneOpen(true)`, while red-flag state freezes cars and closes the effective pit lane until cleared. If the gap is too small for mode `1`, the following car stays on the main track and retries later rather than being forced to stop in the lane. Allowed cars steer through a forward main-track approach into the pit-entry road, slow to the configured limiter speed before the main pit-lane start, follow the main fast lane, pass through the team-colored queue point, hold for any pit-served penalties, hold for the resolved tire-service time, change to the requested compound or default alternate compound, add that compound to `usedTireCompounds`, then steer back to the racing surface through `pit-exit`. While a car is stationary in service, the browser renderer shows a small countdown above it: red `+Ns` for pit-served penalty hold time and yellow `Ns` for normal pit-service time. The queue point is a rolling gate when the active service area is free, so the car continues into service without a full stop. If a team-mate is already servicing or still exiting from the active service area, the arriving car targets the queue point behind that service area, holds a bounded approach speed until the final capture distance, waits without obstructing the main fast lane, then follows a short queue-release route only after the active service area is physically clear; this keeps both the queue stop and the move into service continuous instead of snapping the car between slots or crawling through the last several meters. Cars whose position is controlled by pit entry, queue, service, or exit logic are not laterally displaced by generic collision correction; if another car overlaps one, the movable car is corrected away while the pit-controlled car stays on its authored route or stop point. `pitStops.variability.enabled` optionally adjusts service time from `team.pitCrew.speed`, `team.pitCrew.consistency`, and `team.pitCrew.reliability`; `pitStops.variability.perfect: true` forces `pitStops.defaultStopSeconds` for training. The pit limiter applies only on the straight main pit lane and working lane between the lane start and lane end; the pit-entry connector road and pit-exit connector road are legal pit-lane surfaces but are not speed-limited by `pitStops.pitLaneSpeedLimitKph`, although automatic entry routing caps connector overspeed so worn-tire cars can still reach the limiter and assigned service area.
+When pit stops are enabled, each team is assigned one shared service area in the working lane plus two garage boxes. Driver pairs share the service area, and the service area, queue slot, and garage boxes inherit the team color from `driver.team.color` when present, otherwise the lead driver's color. The current automatic stop plan distributes pit calls across available race laps as bounded pit trains, then lets opportunistic cars join the entry only when fewer than `pitStops.maxConcurrentPitLaneCars` are active and the nearest active pit-lane car is at least `pitStops.minimumPitLaneGapMeters` ahead; committed cars enter at the next pit-entry window and can queue in the working lane if their team service area is busy. Built-in AI cars also request stops from tire condition: below `pitStops.tirePitRequestThresholdPercent` they request `pitIntent: 1`, and below `pitStops.tirePitCommitThresholdPercent` they request `pitIntent: 2`. Expert-controlled cars do not receive those tire-threshold automatic calls; their model or host must request the stop with `pitIntent`. Hosts and expert actions can change a pending stop with `pitIntent`: `0` clears the pending call, `1` stays active until a free-enough pit-entry window appears, and `2` commits to entering at the next pit-entry window even if capacity or gap checks would block mode `1`. The same request may include a target compound, either through `setPitIntent(driverId, intent, targetCompound)` or expert action `pitCompound`; invalid compounds are rejected. Pit intent and target compound are locked while the car is entering, queued, servicing, or exiting, and intent resets to `0` after pit exit. Completed stops can be re-armed by later tire condition or host intent, so pit stops are not one-use per race. When tire condition automatically re-arms a completed stop, it chooses a different available compound instead of silently reusing the current tire; an explicit host/model target compound is preserved. Safety-car mode does not block pit intent. Closed pit-lane race-control state keeps pending calls on track until `setPitLaneOpen(true)`, while red-flag state freezes cars and closes the effective pit lane until cleared. If the gap is too small for mode `1`, the following car stays on the main track and retries later rather than being forced to stop in the lane. Allowed cars steer through a forward main-track approach into the pit-entry road, slow to the configured limiter speed before the main pit-lane start, follow the main fast lane, pass through the team-colored queue point, hold for any pit-served penalties, hold for the resolved tire-service time, change to the requested compound or default alternate compound, add that compound to `usedTireCompounds`, then steer back to the racing surface through `pit-exit`. While a car is stationary in service, the browser renderer shows a small countdown above it: red `+Ns` for pit-served penalty hold time and yellow `Ns` for normal pit-service time. The queue point is a rolling gate when the active service area is free, so the car continues into service without a full stop. If a team-mate is already servicing or still exiting from the active service area, the arriving car targets the queue point behind that service area, holds a bounded approach speed until the final capture distance, waits without obstructing the main fast lane, then follows a short queue-release route only after the active service area is physically clear; this keeps both the queue stop and the move into service continuous instead of snapping the car between slots or crawling through the last several meters. Cars whose position is controlled by pit entry, queue, service, or exit logic are not laterally displaced by generic collision correction; if another car overlaps one, the movable car is corrected away while the pit-controlled car stays on its authored route or stop point. `pitStops.variability.enabled` optionally adjusts service time from `team.pitCrew.speed`, `team.pitCrew.consistency`, and `team.pitCrew.reliability`; `pitStops.variability.perfect: true` forces `pitStops.defaultStopSeconds` for training. The pit limiter applies only on the straight main pit lane and working lane between the lane start and lane end; the pit-entry connector road and pit-exit connector road are legal pit-lane surfaces but are not speed-limited by `pitStops.pitLaneSpeedLimitKph`, although automatic entry routing caps connector overspeed so worn-tire cars can still reach the limiter and assigned service area.
 
 ## Contact And Collision Handling
 
@@ -363,3 +389,7 @@ These are not currently implemented:
 - Race finish ceremony.
 - Multiplayer controls.
 - Official timing rules, licensing, or real-world team identities.
+
+## Penalty Snapshot Ownership
+
+Public penalty snapshots copy supported consequence and diagnostic arrays. Changing a returned consequence cannot change live pit-service seconds or enforcement; future ledger updates likewise do not mutate earlier snapshots. This ownership rule does not alter penalty calculation or service sequencing.

package/docs/sense_contract.md

@@ -43,7 +43,10 @@ while the vector oracle uses schema names and object fields rather than calling
   the same active observation values. Debug-only precision may exist only when
   clearly labeled and must not be presented as model input.
 - `getObservationSpec()` is the canonical schema for compact loops, including
-  per-driver sensor overrides.
+  per-driver sensor overrides. Surface fields use canonical `kerb`, then
+  `illegalSurface` order when enabled, regardless of configuration order.
+  `environmentObservationSchema.test.js` covers this across full/compact,
+  schema-free, array/Float32, and per-driver override paths.
 
 ## Remaining Formal Limits