flip_api.scripts.delete_trust
=============================

.. py:module:: flip_api.scripts.delete_trust

.. autoapi-nested-parse::

   Hard-delete a single trust on the hub (deploy-time CLI).

   Removes the trust row entirely so the slot can be UI-re-registered cleanly
   (name free, FL kit slot free, no archived row left behind). Handles the
   trust.id FK landscape explicitly — the schema has nine tables that reference
   trust.id and none of them declare ON DELETE CASCADE, so a naive
   ``session.delete(trust)`` would fail with a foreign-key violation. This
   script clears each dependent table in the right order before deleting the
   trust row.

   Dependent tables (from flip_api.db.models.main_models):

   | Table                    | FK field                  | Strategy        |
   |--------------------------|---------------------------|-----------------|
   | fl_kit_slot              | assigned_to_trust_id      | NULL the FK     |
   | fl_job_trust             | trust_id (PK part)        | DELETE rows     |
   | fl_metrics               | trust (NOT NULL)          | DELETE rows     |
   | fl_logs                  | trust (nullable)          | DELETE rows     |
   | model_trust_intersect    | trust_id (nullable)       | DELETE rows     |
   | project_trust_intersect  | trust_id (nullable)       | DELETE rows     |
   | query_result             | trust_id (nullable)       | DELETE rows     |
   | trust_task               | trust_id (NOT NULL)       | DELETE rows     |
   | xnat_project_status      | trust_id (nullable)       | DELETE rows     |

   For the nullable FKs we could either NULL or DELETE — DELETE makes the
   intent clearer (a metric/log/result tied to a now-gone trust serves no
   purpose and would orphan stats in the UI). The fl_kit_slot row is the
   exception: NULL'ing reclaims the slot for future registrations, which is
   the whole point of the delete.

   Contract:

   - **stdout** — a single JSON object:

     - ``status: "deleted"`` — hard-delete succeeded. Includes ``trust_id``,
       ``name``, ``freed_fl_kit_slot``, and a ``dependent_rows_deleted`` dict
       summarising the cascade.
     - ``status: "not_found"`` — no trust with that name; nothing to do.
       Includes ``name``.

   - **stderr** — human-readable logging.
   - Exit code 0 on either status; non-zero only on argument errors or
     unexpected exceptions (e.g. an FK we haven't accounted for).

   Invoked by ``deploy/providers/AWS/scripts/delete-trust.sh`` as a one-off
   ECS task (mirrors the ``register-trusts.sh`` pattern). For local dev:
   ``docker compose exec flip-api uv run python -m flip_api.scripts.delete_trust --name <slot>``.



Attributes
----------

.. autoapisummary::

   flip_api.scripts.delete_trust._DEPENDENT_TABLES


Functions
---------

.. autoapisummary::

   flip_api.scripts.delete_trust.delete_one_trust
   flip_api.scripts.delete_trust.main


Module Contents
---------------

.. py:data:: _DEPENDENT_TABLES
   :type:  tuple[tuple[type, str], Ellipsis]

.. py:function:: delete_one_trust(name: str, session: sqlmodel.Session) -> dict[str, Any]

   Hard-delete a trust by name. Cascades through dependent tables.

   :param name: Trust display name (matches ``trust.name`` exactly).
   :type name: str
   :param session: SQLModel session.
   :type session: Session

   :returns: ``{"status": "deleted", ...}`` on success or
             ``{"status": "not_found", "name": name}`` when there's nothing
             to delete.
   :rtype: dict[str, Any]


.. py:function:: main() -> None

   CLI entry point: hard-delete one trust, emit its status JSON to stdout.