cooptools 1.65__tar.gz → 1.67__tar.gz

{cooptools-1.65 → cooptools-1.67}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cooptools
-Version: 1.65
+Version: 1.67
 Summary: Generic Tooling
 Home-page: https://github.com/tylertjburns/cooptools
 Author: tburns

{cooptools-1.65 → cooptools-1.67}/cooptools/physics/kinematic_utils.py

@@ -182,8 +182,16 @@ def _tick_accel_from_profile(profile: Tuple[PhaseResult, ...], dt: float) -> flo
     many phases fit within dt so the tick's velocity change matches the true profile
     instead of overshooting by committing the whole tick to one extreme.
     """
+    if dt < 0:
+        raise ValueError(f"_tick_accel_from_profile: dt must be >= 0, got {dt}")
     if not profile:
         return 0.0
+    if dt == 0:
+        # No time elapses this tick (e.g. delta_time_ms=0 for a position-only /
+        # realign update) -- the time-weighted average has no window to average
+        # over, so fall back to the instantaneous decision: the first phase's
+        # acceleration, which is what the weighted average converges to as dt -> 0+.
+        return profile[0].accel
     remaining = dt
     weighted = 0.0
     for phase in profile:
@@ -241,48 +249,113 @@ def _axis_arrival_accel(d: float, v: float, a: float, dt: float) -> float:
     return _tick_accel_from_profile(profile, dt)
 
 
+def _settle_time(d: float, vs: float, a: float) -> float:
+    """Total time for single_axis_motion_profile(d, vs, ve=0, a) to settle at rest.
+    0.0 for the trivial already-settled case (empty profile)."""
+    return sum(p.time for p in single_axis_motion_profile(d=d, vs=vs, ve=0.0, a=a))
+
+
+def _solve_accel_for_target_settle_time(
+        d: float, vs: float, target_time: float, a_max: float,
+        max_iter: int = 20, tol_frac: float = 0.02,
+) -> float:
+    """Bisects for the accel magnitude a in (0, a_max] such that this axis's own
+    settle time (single_axis_motion_profile(d, vs, 0, a)'s total time) equals
+    target_time. _settle_time is monotonically decreasing in a (more accel -> less
+    time), so a solution in (0, a_max] always exists provided target_time >=
+    _settle_time(d, vs, a_max) (true by construction in arrival_acceleration: target
+    is the max settle time across axes at a_max, so every other axis's a_max-settle-
+    time is <= target). tol_frac is a fraction of a_max, not an absolute distance/time
+    tolerance, so it stays scale-appropriate across very different accel magnitudes.
+    """
+    lo, hi = 1e-6, a_max
+    tol = tol_frac * a_max
+    for _ in range(max_iter):
+        mid = (lo + hi) / 2.0
+        if _settle_time(d, vs, mid) > target_time:
+            lo = mid  # too slow (this much accel takes longer than target) -- need more accel
+        else:
+            hi = mid
+        if hi - lo < tol:
+            break
+    return hi
+
+
 def arrival_acceleration(
         vector_to_goal: vec.FloatVec,
         velocity: vec.FloatVec,
         accel_magnitude: float,
         dt: float,
 ) -> vec.FloatVec:
-    """Per-axis acceleration to arrive at the goal (rest, no overshoot).
-
-    Each axis's accel budget is allocated proportional to its own share of the total
-    remaining distance (accel_magnitude * |d_i| / |d|) -- not given the full budget
-    independently and reconciled after the fact. This keeps every axis's own
-    accelerate/decelerate profile synchronized: for two axes covering distances d_x, d_y
-    with proportional budgets a*d_x/d, a*d_y/d, each axis's own symmetric time-optimal
-    profile takes 2*sqrt(d_i/a_i) = 2*sqrt(d/a) to complete -- identical regardless of
-    d_i, so both axes finish at the same time instead of one (having been given an equal
-    or independently-negotiated share unrelated to how far it actually has to go)
-    finishing and parking early while the other is still working through a much longer,
-    independent overshoot-and-return of its own -- the previous design's real failure
-    mode whenever the axes' distances were disproportionate.
-
-    Per-axis budgets already sum, in a vector sense, to exactly accel_magnitude
-    (sqrt(sum((a*|d_i|/d)^2)) = a), and _axis_arrival_accel never exceeds the budget
-    it's given, so the combined result is guaranteed to stay within accel_magnitude --
-    no further clamping needed.
+    """Per-axis acceleration to arrive at the goal (rest, no overshoot), synchronized
+    so every axis settles at the same time.
+
+    Each axis's OWN settle time if it alone had the full accel_magnitude is
+    _settle_time(d_i, v_i, accel_magnitude) -- this correctly incorporates both
+    distance AND velocity (an axis carrying a lot of unwanted velocity takes a long
+    time to settle even if its distance is small, so it is never mistakenly treated
+    as "almost done"). The slowest axis (largest natural settle time, call it T)
+    defines the pace: it gets the full accel_magnitude budget. Every other, faster
+    axis is deliberately throttled down to whatever smaller accel_i makes its OWN
+    settle time also equal T (via bisection against the same exact solver, since
+    settle time is a transcendental function of accel once vs != 0 -- no closed form
+    the way there is for the vs=0 case, where accel_i = accel_magnitude * d_i/d
+    happens to make 2*sqrt(d_i/accel_i) exactly constant across axes).
+
+    A prior design allocated budget via a static per-tick weighting PROXY (distance,
+    or distance-minus-velocity) instead of each axis's actual dynamics. Proxies have
+    two failure modes seen in practice: (1) weighting by raw distance alone starves
+    an axis that is positionally aligned but still carrying a lot of velocity --
+    this was a real production bug (unbounded orbiting around the goal); (2)
+    weighting by distance-minus-velocity can cancel to exactly zero for perfectly
+    ordinary motion (d_i numerically close to v_i), starving an axis and dividing by
+    zero downstream. Solving each axis's real settle time via the same exact
+    solver used for the actual per-tick control decision has neither failure mode --
+    an axis with small d_i and large v_i naturally has a LARGE settle time (it
+    genuinely takes a while to shed that velocity), so it is never starved; and nothing
+    here can cancel to exactly zero the way a linear proxy can.
+
+    The final per-axis accelerations (via _axis_arrival_accel, so the actual per-tick
+    command still benefits from the cheap-path/one-tick-lookahead/exact-profile-blend
+    machinery -- this synchronization only decides each axis's BUDGET, not its tick
+    command) are combined into one vector and rescaled to accel_magnitude only if
+    their combined length exceeds it -- a safety net, not the primary mechanism (by
+    construction by the time we get here, this should rarely trigger).
+
+    Cost note: this calls the exact single_axis_motion_profile solver on the order
+    of 2-3 times per non-dominant axis per tick (bisection), roughly 12-15x the cost
+    of the plain per-axis cheap-path check. This is deliberate: the alternative
+    (fast, proxy-based synchronization) has real correctness failure modes at
+    production velocity scales, including the orbiting bug this synchronization
+    exists to fix.
 
     This still does not fully solve simultaneous multi-axis arrival under one shared
     budget in general (a genuinely coupled constrained-control problem) -- known
-    residual: very close to the goal, where |d| itself is near zero, can still settle to
-    a small bounded oscillation rather than an exact stop; use a close/slow tolerance
-    sized to your application rather than near-zero.
+    residual: very close to the goal, where every axis's own settle time is already
+    near zero, can still settle to a small bounded oscillation rather than an exact
+    stop; use a close/slow tolerance sized to your application rather than near-zero.
     """
-    d_total = vec.vector_len(vector_to_goal)
-    if math.isclose(d_total, 0, abs_tol=1e-9):
-        # no distance left to proportion by -- just kill residual velocity per axis
-        # with the full budget available
+    settle_times = [_settle_time(d, v, accel_magnitude) for d, v in zip(vector_to_goal, velocity)]
+    target_time = max(settle_times)
+
+    if math.isclose(target_time, 0, abs_tol=1e-9):
         return tuple(_axis_arrival_accel(d, v, accel_magnitude, dt)
                      for d, v in zip(vector_to_goal, velocity))
 
-    return tuple(
-        _axis_arrival_accel(d, v, accel_magnitude * abs(d) / d_total, dt)
-        for d, v in zip(vector_to_goal, velocity)
+    per_axis_budget = tuple(
+        accel_magnitude if math.isclose(t, target_time, abs_tol=1e-6)
+        else _solve_accel_for_target_settle_time(d, v, target_time, accel_magnitude)
+        for d, v, t in zip(vector_to_goal, velocity, settle_times)
+    )
+
+    per_axis_ideal = tuple(
+        _axis_arrival_accel(d, v, budget, dt)
+        for d, v, budget in zip(vector_to_goal, velocity, per_axis_budget)
     )
+    magnitude = vec.vector_len(per_axis_ideal)
+    if magnitude <= accel_magnitude:
+        return per_axis_ideal
+    return vec.scaled_to_length(per_axis_ideal, accel_magnitude)
 
 
 def scalar_lookahead_speed_accel(

cooptools-1.67/cooptools/physics/orbit_fuzzer.py

@@ -0,0 +1,151 @@
+"""Long-running fuzz harness for WaypointFollower/GoalSeeker "gets stuck orbiting a
+target instead of converging" bugs, under realistic, continually-rerouted usage.
+
+Rather than guessing exact initial conditions, this runs a WaypointFollower that
+behaves like a real game agent: continually injects fresh chains of 3-10 waypoints
+once it reaches a destination, and (at REROUTE_PROB_PER_TICK) intermittently replaces
+its remaining queue entirely before reaching the destination -- a "reroute", which
+leaves whatever velocity it was carrying suddenly pointed at a new, unrelated goal.
+A per-destination watchdog flags a run as "stuck" if a destination takes far longer
+than physically necessary to reach, and dumps a full state snapshot at that moment so
+the exact scenario can be replayed deterministically in a unit test.
+
+This harness found two real, since-fixed/documented bugs (see physics/CLAUDE.md
+gotchas #2 and #5, and tests.test_waypointFollower.Test_WaypointFollower_OrbitingRisk):
+  - WaypointFollower._cascade_realign could hand off a velocity pointed ~148 degrees
+    away from the actual next waypoint (fixed).
+  - The seek/lookahead branch of GoalSeeker.update() (continue_after_goal_reached=True)
+    applies acceleration always pointed at a fixed target with no velocity damping
+    whenever there's still "plenty of room" to the eventual destination -- still open.
+
+Deterministic via a fixed RNG seed -- rerun with the same seed to reproduce a find.
+Run with: python -m cooptools.physics.orbit_fuzzer [--seed N] [--reroute-prob P]
+"""
+import argparse
+import math
+import random
+
+from cooptools.physics.waypointFollower import WaypointFollower
+from cooptools.physics.waypoint import Waypoint
+from cooptools.transform import Transform
+
+DT_MS = 16
+MAX_ACCELERATION = 140.0
+AREA_MIN, AREA_MAX = 0.0, 1000.0
+CLOSE_TOLERANCE = 2.0
+SLOW_TOLERANCE = 2.0
+REALIGN = True
+
+MIN_CHAIN, MAX_CHAIN = 3, 10
+
+# Watchdog: a destination should never realistically take longer than this many ticks.
+# Sized generously (10x a rough worst-case direct-line time across the whole area at
+# this accel) so only genuinely pathological (stuck/orbiting) runs trip it.
+WORST_CASE_DIRECT_TICKS = int(2 * math.sqrt((AREA_MAX - AREA_MIN) * math.sqrt(2) / MAX_ACCELERATION) * 1000 / DT_MS)
+STUCK_TICK_THRESHOLD = 10 * WORST_CASE_DIRECT_TICKS
+
+
+def random_point(rng: random.Random):
+    return (rng.uniform(AREA_MIN, AREA_MAX), rng.uniform(AREA_MIN, AREA_MAX))
+
+
+def make_chain(rng: random.Random):
+    n = rng.randint(MIN_CHAIN, MAX_CHAIN)
+    return [Waypoint(end_pos=random_point(rng), is_destination=(i == n - 1)) for i in range(n)]
+
+
+def snapshot(follower: WaypointFollower, seed: int, total_ticks: int, ticks_since_target_set: int,
+             destinations_reached: int, reroutes: int):
+    print("=" * 70)
+    print("STUCK CONDITION DETECTED")
+    print("=" * 70)
+    print(f"seed={seed}")
+    print(f"total_ticks={total_ticks}  (~{total_ticks * DT_MS / 1000 / 60:.1f} min sim time)")
+    print(f"ticks_since_current_target_set={ticks_since_target_set}  "
+          f"(~{ticks_since_target_set * DT_MS / 1000 / 60:.1f} min)")
+    print(f"destinations_reached={destinations_reached}  reroutes={reroutes}")
+    print(f"Position={follower.Position}")
+    print(f"Velocity={follower.Velocity.CurrentVelocity_M_S}")
+    print(f"Acceleration={follower.Acceleration.CurrentAccel_M_S}")
+    print(f"CurrentTarget={follower.CurrentTarget}")
+    print(f"remaining waypoints ({len(follower.waypoints)}):")
+    for wp in follower.waypoints:
+        print(f"  {wp}")
+    dist_to_target = math.hypot(
+        follower.Position[0] - follower.CurrentTarget.end_pos[0],
+        follower.Position[1] - follower.CurrentTarget.end_pos[1],
+    )
+    print(f"distance_to_current_target={dist_to_target:.3f}")
+    print(f"config: max_acceleration={MAX_ACCELERATION} close_tol={CLOSE_TOLERANCE} "
+          f"slow_tol={SLOW_TOLERANCE} realign={REALIGN} dt_ms={DT_MS}")
+    print("=" * 70)
+
+
+def run(seed: int, reroute_prob_per_tick: float, total_tick_budget: int):
+    rng = random.Random(seed)
+    start = random_point(rng)
+    follower = WaypointFollower(
+        name='fuzzer',
+        initial_transform=Transform(translation=start),
+        max_acceleration=MAX_ACCELERATION,
+    )
+    follower.add_waypoints(make_chain(rng))
+
+    total_ticks = 0
+    ticks_since_target_set = 0
+    destinations_reached = 0
+    reroutes = 0
+
+    while total_ticks < total_tick_budget:
+        # intermittent disruption: replace the whole remaining queue before it's
+        # consumed, simulating a reroute mid-flight
+        if follower.waypoints and rng.random() < reroute_prob_per_tick:
+            follower.waypoints = []
+            follower.add_waypoints(make_chain(rng))
+            ticks_since_target_set = 0
+            reroutes += 1
+
+        reached = follower.update(
+            delta_time_ms=DT_MS,
+            close_enough_tolerance=CLOSE_TOLERANCE,
+            slow_enough_tolerance=SLOW_TOLERANCE,
+            realign_to_next_waypoint=REALIGN,
+        )
+
+        total_ticks += 1
+        ticks_since_target_set += 1
+
+        for wp in reached:
+            ticks_since_target_set = 0
+            if wp.is_destination:
+                destinations_reached += 1
+
+        if not follower.waypoints:
+            follower.add_waypoints(make_chain(rng))
+            ticks_since_target_set = 0
+
+        if ticks_since_target_set >= STUCK_TICK_THRESHOLD:
+            snapshot(follower, seed, total_ticks, ticks_since_target_set, destinations_reached, reroutes)
+            return
+
+        if total_ticks % 200_000 == 0:
+            print(f"... {total_ticks} ticks (~{total_ticks * DT_MS / 1000 / 60:.1f} min), "
+                  f"{destinations_reached} destinations reached, {reroutes} reroutes, "
+                  f"still going (ticks_since_target_set={ticks_since_target_set})")
+
+    print(f"no stuck condition found within {total_tick_budget} ticks")
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--seed', type=int, default=1)
+    parser.add_argument('--reroute-prob', type=float, default=0.0,
+                         help='per-tick probability of a mid-flight reroute (0 disables)')
+    parser.add_argument('--budget', type=int, default=20_000_000,
+                         help='total tick safety cap so the script always terminates')
+    args = parser.parse_args()
+    run(seed=args.seed, reroute_prob_per_tick=args.reroute_prob, total_tick_budget=args.budget)
+
+
+if __name__ == '__main__':
+    main()

{cooptools-1.65 → cooptools-1.67}/cooptools/physics/waypointFollower.py

@@ -169,12 +169,21 @@ class WaypointFollower:
         remaining_overshoot = vec.distance_between(anchor, self._goal_seeker.Position)
         last_direction = None
 
-        # A tiny fixed epsilon, not close_enough_tolerance -- this only guards against
-        # floating-point noise (exactly zero overshoot). Using the caller's arrival
-        # tolerance here instead would silently skip realigning any real overshoot
-        # smaller than that tolerance (e.g. a 2px arrival tolerance would disable
-        # redirecting a legitimate 0.5px overshoot entirely).
-        while remaining_overshoot > 1e-9 and len(self.waypoints) > 0:
+        # Loop on len(self.waypoints) alone, NOT also remaining_overshoot > 0 -- a
+        # waypoint can be consumed via the close_enough_tolerance slack below even when
+        # the actual overshoot is slightly LESS than the segment length, which drives
+        # remaining_overshoot negative. Exiting the loop right there (as an earlier
+        # version did) freezes last_direction at the heading of the segment just
+        # consumed -- pointing AT the waypoint just reached, not toward whatever comes
+        # after it -- and hands that stale, often wildly wrong heading to
+        # set_velocity below (confirmed regression: a real cascade redirected velocity
+        # ~148 degrees away from the actual next waypoint, feeding directly into the
+        # unbounded-orbiting bug). Continuing the loop (with overshoot clamped to a
+        # non-negative floor) lets it recompute direction toward the NEW anchor's next
+        # waypoint; since a clamped-to-zero remaining_overshoot can essentially never
+        # cover another real segment, the very next iteration's threshold check settles
+        # partway (zero distance) along that newly-correct direction instead.
+        while len(self.waypoints) > 0:
             next_wp = self.waypoints[0]
             direction = vec.unit_vector(vec.vector_between(anchor, next_wp.end_pos))
 
@@ -195,7 +204,7 @@ class WaypointFollower:
 
             logger.info(f"\'{self.Name}\' overshot into waypoint \'{self._goal_seeker.Name}\' "
                         f"at {tuple(round(x, 3) for x in next_wp.end_pos)} while realigning")
-            remaining_overshoot -= seg_len
+            remaining_overshoot = max(0.0, remaining_overshoot - seg_len)
             anchor = next_wp.end_pos
             popped = self.waypoints.pop(0)
             self._last_reached_waypoint = popped

{cooptools-1.65 → cooptools-1.67}/cooptools.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cooptools
-Version: 1.65
+Version: 1.67
 Summary: Generic Tooling
 Home-page: https://github.com/tylertjburns/cooptools
 Author: tburns

{cooptools-1.65 → cooptools-1.67}/cooptools.egg-info/SOURCES.txt

@@ -104,6 +104,7 @@ cooptools/physics/__init__.py
 cooptools/physics/kinematic.py
 cooptools/physics/kinematic_utils.py
 cooptools/physics/movement.py
+cooptools/physics/orbit_fuzzer.py
 cooptools/physics/trajectory.py
 cooptools/physics/waypoint.py
 cooptools/physics/waypointFollower.py

{cooptools-1.65 → cooptools-1.67}/setup.py

@@ -7,7 +7,7 @@ with open('requirements.txt') as f:
     requirements = f.read().splitlines()
 
 setuptools.setup(name='cooptools',
-      version='1.65',
+      version='1.67',
       description='Generic Tooling',
       url='https://github.com/tylertjburns/cooptools',
       author='tburns',

{cooptools-1.65 → cooptools-1.67}/tests/test_kinematic.py

@@ -1,3 +1,4 @@
+import math
 import unittest
 
 import cooptools.geometry_utils.vector_utils as vec
@@ -170,5 +171,67 @@ class Test_GoalSeeker_ArrivalWithLooseTolerance(unittest.TestCase):
         self.assertLess(max_single_tick_drop, 10.0)
 
 
+class Test_GoalSeeker_OrbitingRisk(unittest.TestCase):
+    """Reported bug: a mover with velocity purely tangential to (perpendicular to) the
+    vector-to-goal can settle into a slow, near-circular decaying orbit instead of
+    converging in a time comparable to a direct approach.
+
+    Initial conditions follow the classic circular-orbit balance for a CONSTANT-
+    magnitude central acceleration (unlike real gravity's inverse-square law): the
+    speed required for a circular orbit of radius r under constant inward acceleration
+    a is v = sqrt(a*r), from equating centripetal acceleration a_c = v^2/r to a. For
+    goal=(0,0), init_pos=(10,0), max_acceleration=1: v = sqrt(1*10) = sqrt(10) ~= 3.162.
+
+    This is not a contrived edge case: sqrt(a*r) is also exactly the peak speed a
+    direct one-axis bang-bang deceleration over the same distance would reach (v_peak =
+    sqrt(a*d)) -- same kinetic-energy scale as an ordinary approach, just pointed
+    entirely the wrong way.
+
+    Suspected root cause: kinematic_utils.arrival_acceleration solves each axis
+    independently with a budget proportional to |d_i|/|d| (physics/CLAUDE.md gotcha
+    #2), which is not a true centripetal correction -- confirmed empirically: with
+    these exact initial conditions the mover holds within ~2% of its initial radius
+    for roughly the first 300 ticks, then decays into the goal only after ~30 real-time
+    seconds (measured stable across dt from 1ms to 100ms, so this is a genuine
+    continuous-time property of the control law, not a tick-size artifact) -- about
+    4.7x longer than the ~6.3s a direct radial deceleration over the same distance
+    would take.
+
+    Named test_orbiting_risk_converges as a known-failure regression: it currently
+    FAILS (documenting the bug) and should PASS once the arrival controller converges
+    from tangential velocity in a time comparable to a direct approach."""
+
+    def test_orbiting_risk_converges(self):
+        # arrange -- goal at the origin, mover 10 units out with a purely tangential
+        # velocity at the circular-orbit resonance speed for this radius/accel (see
+        # class docstring for the derivation).
+        seeker = _make_seeker(start=(10.0, 0.0), max_acceleration=1.0)
+        seeker.set_velocity((0.0, math.sqrt(10.0)))
+        goal = (0.0, 0.0)
+
+        # a direct one-axis bang-bang deceleration over the same distance (d=10, a=1)
+        # takes 2*sqrt(d/a) seconds; a healthy arrival controller should converge from
+        # an equal-energy tangential kick in not too much more time than that -- 3x is
+        # a generous margin, not a tight bound. (Actual observed behavior: ~4.7x, i.e.
+        # this margin is not met today.)
+        direct_optimal_time_s = 2 * math.sqrt(10.0 / 1.0)
+        delta_time_ms = 16
+        max_acceptable_steps = int(3 * direct_optimal_time_s * 1000 / delta_time_ms)
+
+        reached = False
+        steps = 0
+        while not reached and steps < max_acceptable_steps:
+            reached = seeker.update(delta_time_ms=delta_time_ms, goal_pos=goal)
+            steps += 1
+
+        self.assertTrue(
+            reached,
+            f'seeker failed to converge within {max_acceptable_steps} steps (3x the '
+            f'direct-approach optimal time of {direct_optimal_time_s:.2f}s) -- it is '
+            f'likely stuck in a slow decaying orbit around the goal instead of '
+            f'converging directly'
+        )
+
+
 if __name__ == '__main__':
     unittest.main()

{cooptools-1.65 → cooptools-1.67}/tests/test_kinematic_utils.py

@@ -71,6 +71,18 @@ class Test_AxisArrivalAccel(unittest.TestCase):
         self.assertNotEqual(result, a)  # not the naive "just keep accelerating" answer
         self.assertLess(result, a)
 
+    def test__dt_zero__in_braking_regime__does_not_raise_and_returns_brake(self):
+        # regression: a position-only update (delta_time_ms=0, e.g. a waypoint
+        # realign) while already past the switching threshold used to fall through
+        # to single_axis_motion_profile + _tick_accel_from_profile(profile, dt=0),
+        # which raised ZeroDivisionError. d=10, v=20, a=5 is the same past-threshold
+        # state as test__well_past_stopping_distance__brakes above.
+        result = kin._axis_arrival_accel(d=10, v=20, a=5, dt=0)
+        self.assertEqual(result, -5.0)
+
+    def test__dt_zero__in_cheap_accelerate_regime__still_accelerates(self):
+        self.assertEqual(kin._axis_arrival_accel(d=1000, v=1, a=5, dt=0), 5.0)
+
 
 class Test_TickAccelFromProfile(unittest.TestCase):
     """Direct unit coverage for the tick-blending helper in isolation, using
@@ -100,6 +112,21 @@ class Test_TickAccelFromProfile(unittest.TestCase):
         result = kin._tick_accel_from_profile((p1,), dt=0.03)
         self.assertAlmostEqual(result, (-8.0 * 0.01) / 0.03, places=9)
 
+    def test__dt_zero__non_empty_profile__returns_first_phase_accel_without_dividing_by_zero(self):
+        # regression: dt=0 (e.g. a position-only / realign update with
+        # delta_time_ms=0) used to divide weighted-by-zero into a ZeroDivisionError.
+        p1 = kin.PhaseResult(length=0, time=0.01, label="brake", accel=-8.0)
+        p2 = kin.PhaseResult(length=0, time=5.0, label="accel", accel=3.0)
+        self.assertEqual(kin._tick_accel_from_profile((p1, p2), dt=0), -8.0)
+
+    def test__dt_zero__empty_profile__returns_zero(self):
+        self.assertEqual(kin._tick_accel_from_profile((), dt=0), 0.0)
+
+    def test__dt_negative__raises_value_error(self):
+        p1 = kin.PhaseResult(length=0, time=0.01, label="brake", accel=-8.0)
+        with self.assertRaises(ValueError):
+            kin._tick_accel_from_profile((p1,), dt=-0.01)
+
 
 class Test_ArrivalAcceleration(unittest.TestCase):
     """Direct unit coverage for the multi-axis wrapper around _axis_arrival_accel."""
@@ -142,16 +169,21 @@ class Test_ArrivalAcceleration(unittest.TestCase):
         self.assertAlmostEqual(result[0], result[1], places=6)
 
     def test__budget_allocated_proportional_to_each_axis_share_of_total_distance(self):
-        # d=(100, 25) -> axis 0 should get 4x axis 1's budget (100/25), matching each
-        # axis's share of the resultant direction, not an equal or independently
-        # negotiated split
+        # d=(100, 25), starting from rest -- axis 0 should get ~4x axis 1's budget
+        # (100/25), matching each axis's share of the resultant direction, not an
+        # equal or independently negotiated split. For the vs=0 case this ratio has
+        # a closed form (budget_i = accel_magnitude * d_i/d exactly equalizes each
+        # axis's own 2*sqrt(d_i/a_i) settle time), which the settle-time-sync design
+        # now reaches via bisection rather than that closed form directly -- places=2
+        # reflects the bisection's tolerance, not a loss of correctness (see
+        # _solve_accel_for_target_settle_time's tol_frac).
         result = kin.arrival_acceleration(
             vector_to_goal=(100, 25),
             velocity=(0, 0),
             accel_magnitude=5,
             dt=DT,
         )
-        self.assertAlmostEqual(result[0] / result[1], 4.0, places=6)
+        self.assertAlmostEqual(result[0] / result[1], 4.0, places=2)
 
     def test__disproportionate_axis_distances__still_synchronizes_arrival_time(self):
         # Regression test: a real case (traced from the demo) had one axis complete its