Vendor airborne primitives from the 3d branch

[ekiefl]

Vendor airborne primitives from the 3d branch

Summary

The next step against the 2D/3D vendoring plan. The previous PR delivered the architectural slot for 3D — SimulationEngine.is_3d, Dim capability declarations on every strategy, EventDetector as a peer to Resolver. This stage vendors the prerequisite primitives from the 3d branch: the airborne motion state, the BALL_TABLE event type, and airborne equations of motion.

No simulation behavior changes. The constants and event types exist as enum members, an airborne ball has well-defined parabolic evolution under gravity, but nothing in this PR wires these into resolution or detection. The default 2D simulation is byte-identical to before.

What's in this PR

New motion state (pooltool/constants.py):

• airborne: int = 5 motion state
• Added to state_dict and to the energetic set
• on_table and nontranslating left alone — airborne is correctly excluded from both

New event type (pooltool/events/):

• EventType.BALL_TABLE in datatypes.py + entries in is_collision() / has_ball()
• ball_table_collision(ball, time, set_initial=False) factory in factory.py
• EventType.BALL_TABLE: {0} registry entry in utils.py::event_type_to_ball_indices
• Re-export of ball_table_collision from events/__init__.py

Airborne kinematics (pooltool/physics/):

• get_airborne_time(rvw, R, g) in physics/utils.py — time until an airborne ball's bottom intersects the table plane. Routes through the existing pooltool.ptmath.roots.quadratic.solve rather than inlining the quadratic-solver math (a small departure from the strict-vendor path; see "What's not in this PR" below).
• _evolve_airborne_state(rvw, g, t) in physics/evolve/__init__.py — parabolic position, linear velocity, conserved angular velocity. Verbatim from the 3d branch.
• Dispatch branch added to evolve_ball_motion for state == const.airborne. Airborne does not cascade to another state on a timer — it only transitions via BALL_TABLE collision, which Stage 3 wires up.
• get_airborne_time re-exported from pooltool/physics/__init__.py.

Tests:

• tests/physics/evolve/test_airborne.py — five tests covering xy-velocity conservation, angular velocity conservation, linear xy-displacement, gravity direction, parabolic z. Ported byte-identical from the 3d branch via git show.
• tests/physics/test_utils.py extended with a parametrized test_get_airborne_time (zero gravity → ∞, drop from apex, xy-velocity independence, ball at z=R with downward v_z → 0).

What's NOT in this PR (and shouldn't be)

• pooltool/physics/resolve/ball_table/ resolver package — Stage 3
• BallTableDetection strategy — Stage 3
• Any Dim.THREE-tagged strategies — Stage 4
• on_table(rvw, R) predicate function (the 3d branch adds this in physics/utils.py, but it's only used by airborne-aware code; defer to Stage 3)
• Updates to ball_cushion / ball_pocket / stick_ball resolvers that produce vz — Stage 4

Vendor faithfulness

Three function bodies were re-typed from the 3d branch rather than piped — _evolve_airborne_state, ball_table_collision, and the function-body of get_airborne_time (before its quadratic-solver refactor). All three were verified byte-faithful via AST comparison after stripping docstrings (the function bodies proved to be identical to the 3d source). The test file test_airborne.py was piped directly via git show 3d:... > path and is byte-identical by construction.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 7b3dcd90-0043-4fb6-a2ac-aded1b9416bd

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch ek/airborne-state

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

❌ Patch coverage is 35.48387% with 20 lines in your changes missing coverage. Please review.
✅ Project coverage is 47.41%. Comparing base (eb128f1) to head (355646a).

Files with missing lines	Patch %	Lines
pooltool/physics/evolve/__init__.py	13.33%	13 Missing ⚠️
pooltool/physics/utils.py	40.00%	6 Missing ⚠️
pooltool/events/factory.py	50.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #295      +/-   ##
==========================================
- Coverage   47.45%   47.41%   -0.05%     
==========================================
  Files         153      153              
  Lines       10479    10509      +30     
==========================================
+ Hits         4973     4983      +10     
- Misses       5506     5526      +20     

Flag	Coverage Δ
service	47.41% <35.48%> (-0.05%)	⬇️
service-no-ani	57.89% <35.48%> (-0.12%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.