Recover an interrupted environment
==================================

The symptom
-----------

A command or a ``connect`` call fails with a recovery error:

.. code-block:: console

   $ ontoenv status
   Error: OntoEnv recovery required: interrupted mutation marker at
   ./.ontoenv/catalog.pending; run `ontoenv recover` or call OntoEnv::recover
   to rebuild the catalog

In Python this surfaces as :class:`ontoenv.CatalogRecoveryError`.

This means a process stopped between changing the graph store and publishing
the updated index. The store may contain changes that the index does not
describe. OntoEnv refuses to use that index until recovery scans the stored
graphs and replaces it.

The fix
-------

.. code-block:: console

   $ ontoenv recover
   Recovered catalog at ./.ontoenv with 12 ontology records.

.. code-block:: python

   from ontoenv import OntoEnv, CatalogRecoveryError

   try:
       env = OntoEnv.connect("./ontology-env")
   except CatalogRecoveryError:
       env = OntoEnv.recover("./ontology-env")

With a custom graph store, pass it:

.. code-block:: python

   env = OntoEnv.recover("./ontology-env", graph_store=store)

Recovery scans every stored graph and publishes a replacement index. It is
much slower than a normal open, so it is not something OntoEnv does for you
automatically.

``ontoenv recover`` uses the same environment discovery as every other
command: it walks up from the current directory and honours ``ONTOENV_DIR``.

.. warning::

   Do not delete ``.ontoenv/catalog.pending`` by hand. The marker is what
   tells OntoEnv the index is untrustworthy; removing it makes a possibly
   incomplete index look valid. ``recover`` removes it only after the
   replacement index is successfully published.

If recovery fails
-----------------

Recovery requires a stable, fully readable snapshot of the backend. It aborts
and leaves the marker in place if a graph cannot be read or the backend
changes mid-scan — so the operation is always safe to retry.

Stop anything else writing to the environment, then run it again.

When this is *not* the problem
------------------------------

A missing ``owl:imports`` target does **not** leave a recovery marker. In
non-strict mode, ``import_dependencies(..., fetch_missing=True)`` and
``get_dependencies(..., fetch_missing=True)`` are best-effort: they skip what
they cannot reach and commit the partial result cleanly.

So a recovery marker always means an interrupted or failed commit, never
merely an unresolved import. For missing imports, see
:doc:`diagnose-imports`.

Recovery is unavailable for temporary environments (``--temporary`` /
``OntoEnv(temporary=True)``), which have nothing persisted to recover from.

Start over instead
------------------

If you would rather rebuild from your source files than recover:

.. code-block:: console

   $ ontoenv reset
   $ ontoenv init ./ontologies

These commands form a destructive sequence. ``reset`` asks for confirmation,
then deletes ``.ontoenv/`` entirely, including its catalog, stored graphs, and
cached remote ontologies. ``init`` creates a new environment, scans
``./ontologies``, and follows its imports; remote imports must be downloaded
again. The source files under ``./ontologies`` are not deleted.