Composed spherical API migration
================================

Status and compatibility
------------------------

The three Stable workflow containers remain the compatibility foundation:
``EquirectangularImage``, ``GnomonicFace``, and
``GnomonicFaceSet``. Existing imports in ``panorai.image_processing``,
``panorai.features`` and ``panorai.stereo`` remain available. The new
generic Pipeline and general NumPy operation contracts are Stable. Application
base classes, DoG, Stereo, Mask R-CNN Workflow, and CAM/SAM instance stages remain
Experimental until their own tracked promotion gates pass. SLIC is Stable
across its historical function, configured operation, and application wrapper
as ``panorai-spherical-slic/v1``. The optional generic Torch layer
grammar is Stable on CPU as ``panorai-spherical-ops-torch/v1``; CUDA and MPS
remain outside that device guarantee pending independent matrices.

From manual view workflows to Pipeline
--------------------------------------

The existing Stable form remains valid:

.. code-block:: python

   result = panorama.views("cube", size=256).map(model).reconstruct(
       blend="gaussian"
   )

The equivalent composable form is:

.. code-block:: python

   from panorai.pipeline import Pipeline, SampleViews, PerView, ReconstructERP

   result = Pipeline(
       SampleViews("cube", size=256),
       PerView(model),
       ReconstructERP(blend="gaussian"),
   )(panorama)

Third-party stages now implement public ``execute(value) -> StageResult``
with declared ``input_kind`` and ``output_kind``. They do not subclass a
private base or implement ``_run``.

Typed results and grids
-----------------------

Spatial Pipeline outputs are ``RasterField`` values carrying support,
validity and ``RasterGrid``. Classification and embedding outputs are
``ClassificationResult`` and ``EmbeddingResult``. Mixed branches use
``ResultBundle``; ``ReconstructERP`` fuses only raster branches and
retains the rest.

Shape-changing operations create a derived spherical lattice. They cannot be
attached as canonical ERP fields until an explicit regridding operation
returns them to ERP pixel centres.

Applications
------------

The wrappers ``SphericalSLIC``, ``SphericalDoGFeatures``,
``SphericalStereoDepth`` and ``SphericalMaskRCNNWorkflow`` expose
``run()``, ``__call__()``, parameters, immutable variants, descriptions
and their lower-level Pipeline. They delegate to the existing algorithms.
``SphericalSLIC`` is Stable and writes
``panorai-spherical-slic-config/v1``; the generic application configuration
format and the other wrappers remain Experimental.

Mask R-CNN users should distinguish:

* ``mask_rcnn.workflow(...)`` returns the executable workflow. CAM or SAM
  supplies proposals, SAM supplies refinement or reusable masks, and an
  abstaining heuristic supplies instance decisions.
* ``SphericalMaskRCNNPaper`` and ``mask_rcnn.paper(...)`` preserve the original
  Experimental imports; the factory warns and delegates to the workflow.
* ``SphericalMaskRCNN`` describes the future trainable
  Backbone/RPN/RoIAlign/Box/Mask topology. It remains Experimental and
  non-executable; PanorAi does not add a trainer, dataset framework or
  checkpoints.

Persistence and cache
---------------------

Only registered components can be saved. Arbitrary callables continue to work
in memory, but persistence fails with the exact parameter path. Pipeline
topology is canonical JSON. Registered Torch modules use a trusted identifier
registry and safetensors weights; an archive cannot select a class to import.

Torch cache entries require eval mode, cannot contain tensors that require
gradients, and include the registered weight hash. These rules prevent cache
reuse from silently disconnecting autograd or crossing model identities.

Promotion boundary
------------------

Installed-wheel execution is necessary but not sufficient for Stable
promotion of a scientific algorithm or application. The content-hashed
``contracts/spherical-application-promotion-v1.json`` freezes analytic and
external held-out gates for SLIC, DoG, StereoDepth and Mask R-CNN Workflow
(historically recorded as ``mask-rcnn-paper``). The
SLIC portion has passed prospectively and is recorded in the stability
inventory. Missing datasets, checkpoints, licenses or held-out results leave
only the corresponding remaining scientific surface Experimental; they do not
demote the generic Pipeline, general NumPy operations, or SLIC. Thresholds are
not relaxed after results are opened.