"""Shared LightGlue-runtime DTOs (L1 helper layer; AZ-278).

The cross-component ``MatchResult`` DTO previously lived here under
a placeholder schema; AZ-344 froze the real shape in
:mod:`gps_denied_onboard._types.matcher`. The two surviving classes
(:class:`KeypointSet`, :class:`CorrespondenceSet`) are the L1
helper substrate for :class:`gps_denied_onboard.helpers.lightglue_runtime.LightGlueRuntime`
and stay here.
"""

from __future__ import annotations

from dataclasses import dataclass

import numpy as np


@dataclass(frozen=True)
class KeypointSet:
    """A backbone-extracted keypoint + descriptor bundle.

    ``keypoints`` is shape ``(N, 2)`` (x, y in pixel coordinates);
    ``descriptors`` is shape ``(N, D)`` where ``D`` is the engine's
    expected descriptor dim. Both arrays MUST be ``float32`` (the
    runtime-default for LightGlue inputs).
    """

    keypoints: np.ndarray
    descriptors: np.ndarray


@dataclass(frozen=True)
class CorrespondenceSet:
    """Output of a single LightGlue match pass.

    ``correspondences`` is shape ``(M, 4)`` ``[x_a, y_a, x_b, y_b]``
    (matched pixel pairs); ``scores`` is shape ``(M,)`` per-match
    confidence in ``[0, 1]``.
    """

    correspondences: np.ndarray
    scores: np.ndarray
