Engine ownership and callbacks
==============================

A ``Solver`` owns its native engine. Its domain views retain that owner, so a
view cannot outlive the Python object that manages its native memory. Calling
``close()`` or ``destroy()`` invalidates retained 2D and infiltration views;
structural edits also invalidate these views. Reacquire ``solver.surface2d``
after reopening or editing a model. Invalidated views raise
``StaleObjectError`` before entering the native library.

Use ``solver.surface2d`` or ``Surface2D(solver)``. Passing ``solver.handle`` to
``Surface2D`` is deprecated. For compatibility it is accepted only when the
address belongs to a live registered Python owner. Arbitrary native addresses
are rejected with ``BadHandleError``.

``ModelBuilder.to_solver()`` transfers ownership once. Existing builder views
become stale, and a second transfer raises ``BadHandleError``. The returned
solver has the same initialized Python state as a normally constructed solver.

Threads
-------

Different solvers may advance on different threads. Calls that release the
Python GIL pin their engine owner for the duration of the native operation.
Access from another thread to that same engine raises ``LifecycleError``
promptly. This includes attempts to destroy the engine while it is advancing.
Coordinate access in the application and collect snapshots between steps.

Callbacks
---------

Step callbacks run on the advancing thread. They may inspect results and apply
forcing supported at that stage by the engine. They must not reenter lifecycle
operations such as ``step()``, ``close()`` or ``destroy()``, or replace callback
registrations while a callback is active; these operations raise
``LifecycleError``.

A Python exception cannot unwind through the native callback ABI. The binding
captures the first exception and re-raises that same exception when the native
operation returns. Later callbacks in that operation are suppressed. The
current native step may finish, so callback failure does not roll back the
simulation. This behavior applies to ``step()``, ``stride()``, ``steps()`` and
``until()``. Unregister or repair the failing callback before advancing again.

Testing a local build
---------------------

Use the project's ``openswmm`` Conda environment for validation::

    conda run --no-capture-output -n openswmm python -m pytest tests/engine

Run this command from ``python/`` after building/installing the checkout into
that environment, or set ``PYTHONPATH`` to a staged build. Verify the loaded
extension path before testing::

    conda run -n openswmm python -c "import openswmm.engine._solver as m; print(m.__file__)"

A successful test of an older installed package does not validate a changed
checkout. Rebuild all extensions after changing a shared ``.pxd`` declaration.