Twin-parcel realism: dual hook time, pup handling, twin tare and route GVW caps

[Orinks]

Adds the three remaining twin-parcel realism fixes on top of feat/career-2.0 at 9cdea51, after #252 merged: dual hook time (FIX 3), pup handling (FIX 4), and twin tare and GVW (FIX 5). No written spec was found beyond the ROADMAP Track A outline and #218's note that the caps were recorded, so this PR follows that outline. Where a figure had no public source, I picked the conservative option and listed it below.

What each fix does

FIX 3: dual hook and walk-around time (feat(pickup))

• At the shipper, a set of doubles (parcel_doubles on double_van, turnpike_doubles on turnpike_double) adds 15 minutes for the second hook-up and 10 minutes for a walk-around of both trailers and the converter dolly. That is 25 extra minutes on the game clock and in HOS on-duty time, for both live loads and drop-and-hook. Detention still counts only the shipper's own time.
• Spoken at check-in and when loading or hooking starts, and shown on the pickup screen:
  • Spoken: "A set of doubles is two hook-ups, about 15 minutes more, and a walk-around of both trailers and the converter dolly, about 10 minutes more: 25 extra minutes on duty."
  • Screen line: "Doubles: two hook-ups and a walk-around of both trailers and the dolly, 25 extra minutes on duty"
  • The duty-log activity reads "dropping and hooking a set of doubles" or "loading and hooking a set of doubles".
  • A clean pickup walk-around says "Walking , both trailers and the converter dolly: lamps lit, ..."
• At delivery, breaking the set (drop the rear pup, unhook and park the converter dolly, drop the lead) adds 15 minutes on the game clock and on duty, whichever way the freight comes off. Spoken on arrival and when the work starts: "Breaking a set of doubles is dropping the rear trailer, unhooking and parking the converter dolly, then dropping the lead trailer: about 15 extra minutes on duty." Shown on the receiver's screen: "Doubles: drop the rear trailer, park the converter dolly, drop the lead, 15 extra minutes on duty"
• With doubles hooked, the rest-stop walk-around takes 15 + 10 = 25 minutes. The row reads "Walk around the truck, both trailers and the dolly, 25 minutes", and the result reads "Walk-around done, both trailers and the converter dolly, 25 minutes. ..."

FIX 4: pup handling compared with a single (feat(driving), fix(driving))

• Lane keeping reports the truck's lateral g from yaw rate and a low-passed "steady" part (3 s time constant), so a held bend reads as steady and a quick steer or lane change as transient. It also reports the crosswind gust's sideways shove as an acceleration.
• Rear-trailer swing = (transient steer g + gust shove × light-set factor) × rearward amplification (RA: STAA pups 1.7, turnpike doubles about 1.36, single 1.0). The light-set factor is a fixed per-program reference mass over the set's actual gross (a = F/m): 80,000 lb for parcel pups, 127,400 lb for turnpike doubles on every corridor, never the route's cap. It is clamped to 1.0–2.0, so an empty set sways at most twice as hard in a gust and a set at or over its reference reads 1.0. RA applies only to the rear trailer's sway and the whip warning; the tractor's own lane drift in a crosswind is the same as with a single.
• Whip threshold = the existing roll-warning share (ROLL_WARN_SHARE) of the roll threshold, floored at the loaded trailer's (0.35 g × share = 0.30 g), so a light load never raises it.
• At 40 mph and up, a swing past the threshold shifts rear-trailer freight (bend rate × half the load × fragility). Every whip episode is spoken and shown when it starts (see fix J): "The rear trailer whipped on that steer and shifted its freight. On doubles the back trailer swings harder than the tractor, so ease into lane changes." (an empty set drops "and shifted its freight").
• Full lane keeping runs no drift model. Its steering keys only request a timed, signalled lane change, so no abrupt evasive steer is reachable under it, and its lane changes never whip. A test pins this.
• No backing a set of doubles. Reverse is refused on the manual shift and on the automatic's held-brake direction change, with no grind and no damage. Spoken and shown: "Reverse refused. You don't back a set of doubles: the converter dolly is a second pivot and the rear trailer jackknifes within a few feet. Pull forward and go around instead."

FIX 5: twin tare, dolly and GVW (fix(weights))

• Gross weight now counts both trailers plus the converter dolly:
  • Pups: 2 × 6,185 lb + 2,740 lb = 15,110 lb behind the tractor, replacing the stock 6,400 kg single.
  • Turnpike doubles: the stock single + 16,200 lb.
• Legal gross:
  • parcel_doubles (STAA twin 28s): 80,000 lb.
  • turnpike_doubles: the lowest recorded turnpike cap among the route's states (OH/IN/MA 127,400; NY 143,000; KS 120,000). A route through any state without a recorded cap is refused, never held to 80,000 lb: the board offers no such job (and prices each load on the lanes the route menu will offer, taking the lowest cap), the route menu drops such a lane, and a trip already under way on one from an older save is grandfathered: it takes the lowest recorded cap among its capped states, or 80,000 lb if none is capped, so it finishes clean with no overweight red light, no fine and a normal legal ticket line.
• Where it is enforced:
  • The job board's weight clamp: cap − tractor − set tare.
  • The live overweight check.
  • The axle split's tractor share.
  • The board's load weight line, which for doubles adds "The limit for this set of doubles on this route is N pounds, counting both trailers and the converter dolly."
  • The CAT Scale ticket for doubles reads only the gross line and the legal/over line: "Gross N pounds, both trailers and the converter dolly included. Legal under the X pound gross limit for this set on this route." (or "N pounds over the X pound gross limit for this set on this route."). The platform split stays a ROADMAP debt.
• The set is hooked on delivery runs. Pickup deadheads still pull one empty trailer.

Every number and its source

Number	Use	Source
30,350 lb	tractor + two 28-ft trailers (2-S1-2) tare	READ: FHWA 2014 CTSW Modal Shift Comparative Analysis, Table 4 "Assumed Tare Weights" (ops.fhwa.dot.gov/freight/sw/map21tswstudy/technical_rpts/mscanalysis/03shift_result.htm)
39,275 lb	tractor + three 28-ft trailers (2-S1-2-2) tare	READ: same table
2,740 lb	single-axle converter dolly	READ: Silver Eagle VAST-20 converter dolly spec sheet, Section VA, updated 04-06-05 (silvereaglemfg.com/wp-content/uploads/Section-1-VA_Dolly.pdf)
6,185 lb	one 28-ft pup	DERIVED: 39,275 − 30,350 − 2,740
15,110 lb	pup set (two pups + dolly)	DERIVED: 2 × 6,185 + 2,740
30,500 lb	five-axle semitrailer empty	READ: FHWA 2000 CTSW Study Vol III, Ch V, Table V-3
46,700 lb	nine-axle turnpike double empty	READ: same table
16,200 lb	turnpike set over a single van	DERIVED: 46,700 − 30,500
1.0 / 1.7	RA of a semitrailer / STAA 28-ft doubles	READ: FHWA 2000 CTSW Vol III, Ch VIII, p. VIII-9
1.3589	RA of a turnpike double	DERIVED: Figure VIII-11 charts it 35.89% worse than the semitrailer (the STAA A-train charts 79.93% worse, which agrees with the 1.7 in the text)
127,400 / 143,000 / 120,000 lb	OH·IN·MA / NY / KS turnpike caps	Already recorded in data::lcv_turnpikes::LCV_TURNPIKE_GVW_CAP_LB (#218)
80,000 lb	STAA doubles and fallback	Existing LEGAL_GVW_LB (federal Interstate cap)
15 min	existing walk-around	Existing WALK_AROUND_MIN
6,400 kg	stock single-trailer tare	Existing TRAILER_TARE_KG
0.30/0.35	whip threshold share of roll threshold	Existing ROLL_WARN_SHARE
12 %/g·s	freight shift rate	Existing CARGO_CORNER_PCT_PER_G_S
0.5	rear trailer's share of the freight	DERIVED: both programs' trailers are equal length
15 min	second hook-up	ASSUMED: no public time study found; KEEP per realism review
15 min	breaking the set at delivery	Realism review figure ("about 15 minutes")
10 min	extra walk-around (second trailer + dolly)	ASSUMED: no public time study found; KEEP per realism review
40 mph	whip floor	ASSUMED (SAE J2179, cited by FHWA, runs its lane change at 55 mph)
3 s	steady/transient filter	ASSUMED
80,000 lb / 127,400 lb	sway reference mass, pups / turnpike doubles	80,000 lb federal gross; 127,400 lb is the OH/IN/MA turnpike cap, used as one constant (ruling I)
reference / actual gross, clamped 1.0–2.0	light-set gust factor	DERIVED: a = F/m; the lane model's gust is taken as the push at the reference mass (ASSUMED calibration). The 2.0 clamp is ASSUMED (unclamped empty: about 2.4 pups, 2.6 turnpike doubles)
0.35 g	loaded roll threshold the whip threshold is floored at	Existing TRUCK_ROLLOVER_G
0.3 g/s	rear-trailer steer slew	ASSUMED (keyboard steer is a step; fix J)
3 s	whip episode gap (one line per episode)	UI pacing, not a realism figure

Realism review rulings (at 735811d)

1. Pickup 15 + 10 minutes: resolved KEEP.
2. Delivery unhooking and pickup deadheads: fixed. Breaking the set at delivery now takes 15 minutes. The deadhead to a doubles pickup still pulls one empty trailer (behavior unchanged); a ROADMAP debt says it should be bobtail or an empty set.
3. FHWA twin and triple on the same tractor: resolved KEEP. The 6,185 lb pup is on the light side (real 28s run about 6,500 to 7,500 lb) but inside tolerance.
4. The unsplit 16,200 lb turnpike set: resolved KEEP.
5. The 1.36 reading of Figure VIII-11: resolved KEEP.
6. RA and crosswind, the 40 mph floor and the 3 s filter: KEEP with limits. RA now applies only to rear-trailer sway and the whip, never to the tractor's lane drift. The floor and the filter stay.
7. Load dependency backwards: fixed. The whip threshold is floored at the loaded pup's, and a light set sways harder in a gust.
8. Full lane-keeping assist: KEEP with limits. Assisted lane changes stay gentle and report no whip. No abrupt evasive steer is reachable under full assist, because its steering keys only request a timed lane change. This is tested.
9. Axle sentence on the doubles ticket: fixed. The sentence is removed; gross-only is a ROADMAP debt.
10. Minimum cap and the fallback: fixed. The minimum-cap rule is kept, and the 80,000 lb fallback for turnpike doubles is removed. Uncapped routes are refused, and a test checks that every offered turnpike-doubles lane has a cap in every state. Parcel pups keep 80,000 lb.

Realism rulings H and I (at 07cb21a)

• H. Legacy trips on uncapped lanes: fixed. A turnpike-doubles trip already under way on a lane through a state with no recorded cap (an old save) is grandfathered at the lowest recorded cap among its capped states, or 80,000 lb if none. No overweight flag, no fine, a normal legal ticket line. The "not legal on this route at any weight" ticket line had no other use and is removed. The board and route menu still refuse new jobs on those lanes.
• I. Sway reference mass: fixed. Sway still scales inversely with mass, but against a fixed reference per program (80,000 lb pups, 127,400 lb turnpike doubles), not the route's legal gross, so the same set and load sway identically on a NY and a KS lane. The reference-over-actual ratio is clamped to 1.0–2.0; empty sets read 2.0. Overweight sets read 1.0 (the existing floor, kept: a heavy set is not made steadier than the reference). The uncalibrated push stays a ROADMAP debt.

QA fix J: keyboard lane changes and silent whip damage

• A steering key steps the tractor to its 0.2 g cap in one frame; read raw, that is 0.197 g transient × 1.7 = 0.334 g, over the 0.300 g threshold, so every keyboard lane change at 40+ mph on loaded pups whipped. The rear trailer now feels the tractor's lateral acceleration rate-limited to 0.3 g/s (sim::lane::REAR_WHIP_STEER_SLEW_G_PER_S, ASSUMED), and the steady-bend filter follows that reading.
• Result at 60 mph, 10 t pups: taps of 0.05–0.2 s and Left 0.1 s → Right 0.1 s give no whip and no damage with lane keeping off or partial. A full-lock swerve one way then the other still whips. Partial-assist 1 s hold: about 0.30% (was 1.25%), now always announced. Turnpike doubles stay non-whipping on a keyboard lane change.
• No silent damage: the 20 s cooldown is replaced by whip episodes. An episode restarts on every whip frame and ends after 3 s without one; every episode is spoken and shown at its start, so each damaging frame is covered by its own line. The loaded-set line now reads "The rear trailer whipped on that steer and shifted its freight. On doubles the back trailer swings harder than the tractor, so ease into lane changes." An empty set keeps the old line (no freight clause).
• Board wording: the doubles weight line now says "on the lanes offered" (it is the lowest cap across the lanes the route menu will offer), not "on this route".

QA fix K: no whip from the road's own bend

• Loaded pups whipped on ordinary curves at or under advisory with no key pressed: the rear trailer's slewed steer followed the tractor's whole lateral g, including curve assistance's tracking steer, which arrives in one frame where a baked bend starts. QA trace: Chattanooga→Knoxville, 883 ft at 65 mph, transient 0.264 g, whip for 1.6 s; Denver→SLC reached 100% cargo damage.
• Fix (sim::lane): the slewed rear-trailer steer now follows only the driver's share of the lateral g: driver_yaw (keys/stick plus the lane-keeping helper, clamped to the driver cap), held to the same road cap and grip, without the tracking steer. The steady filter still follows the slewed reading. The partial-assist snap-back rides in the helper, so it still counts. Curves taken too fast stay the rollover and curve warnings' job.
• Tests: every mapped bend at advisory speed, loaded pups, no input, lane keeping off and partial, curve assist on: Chattanooga→Knoxville (11 bends), Denver→SLC (389), Portland→Seattle (46) give no whip line and zero damage. Before the fix, Chattanooga alone gave 16 whip lines. Sim test: an 883 ft bend at 65 mph shows no transient from its first frame. J tests unchanged and passing; a new test pins that a 1 s hold under partial lane keeping still whips on the snap-back, with one line.

Remaining open questions

• The gust shove calibration (the lane model's gust taken as the push on a combination at the fixed reference mass) and the 2.0 clamp are assumed.
• The 40 mph whip floor and the 3 s filter are assumed (kept by review).

Tests

• ff-core unit tests:
  • models::doubles: programs, hook and walk-around time, tare figures, RA ordering, route caps.
  • sim::vehicle::doubles: gross includes both tares and the dolly, legal gross is the route cap, scale ticket, reverse refused, quick steer swings the pup harder, an empty set whips at a steer no larger than a loaded set needs (and at a smaller one in a gust), whip costs rear freight while a single costs nothing, crosswind sways the rear trailer and not the tractor.
  • models::doubles: exact refused-reverse wording; uncapped turnpike routes return no legal gross; a legacy trip takes its lowest recorded cap or 80,000 lb.
  • sim::vehicle::doubles (H/I): the same load sways identically under NY and KS caps; an empty set's factor is above 1 and at most 2, and a set over its reference reads 1.0.
  • sim::lane: a held bend is steady and a quick steer is transient.
  • trailer_yard: doubles add the second hook-up and walk-around, and 15 minutes to break the set at delivery.
  • jobs: doubles loads stay under their route cap with both trailers and the dolly; every offered turnpike-doubles lane has a recorded cap in every state.
• Integration tests (tests/it/twin_parcel_doubles.rs):
  • The pickup speaks and shows the doubles time and adds exactly 25 minutes to the clock and on-duty time.
  • Reverse is refused and spoken with pups hooked, with no damage, and a single is not refused.
  • The road walk-around is 25 minutes against 15.
  • Toledo→Elkhart turnpike doubles run under 127,400 lb and the ticket names it.
  • Pups sit at 80,000 lb and read overweight when loaded past it.
  • Breaking a set at the receiver speaks and shows the time and adds exactly the planned minutes to the clock and on duty.
  • A crosswind drifts the tractor identically with pups and with a single.
  • Full lane keeping changes lanes with doubles without a whip.
  • (J) Loaded pups at 60 mph through ctx.input with a fake pacer clock, lane keeping off and partial: a 0.05 s tap, Left 0.1 s → Right 0.1 s, and 0.2 s / 0.3 s gap / 0.2 s give no whip line and zero damage. A 1 s Left → 1 s Right swerve whips with exactly one line, also shown in the status, and damage; empty, the line claims no freight. Turnpike doubles: no whip on a keyboard lane change.
  • Legacy turnpike-doubles trips Buffalo→Erie (143,000 lb) and Chicago→Milwaukee (80,000 lb) finish clean: not overweight, no scale verdict against them, a legal ticket line.
  • The same turnpike set sways identically on Buffalo→Rochester (NY cap) and Wichita→Emporia (KS cap).

Local checks

• cargo fmt --all --check: pass
• cargo clippy --workspace --all-targets --locked -- -D warnings: pass
• cargo test --workspace --locked --no-fail-fast: pass
• python3 tools/release_notes.py check --base origin/feat/career-2.0 --head HEAD: pass