"""``Tag`` — short strings probes can carry for filtering + reporting.

See: ``DESIGN.md`` §3.1 (Probe carries tags) and §3.5 (Suite filters by tag).

Probes carry zero or more tags. The Suite filters by tag::

    suite.run(only_tags={Tag.READ, Tag.PUBLIC})
    suite.run(exclude_tags={Tag.UNSAFE})

The five canonical tags listed below cover the current use cases.
Probes may also carry arbitrary string tags — the Suite filter
accepts both. DESIGN.md mentions ``LRO``, ``SCENARIO_STEP``,
``MULTIPART`` etc.; those land alongside their respective features
in future versions.
"""

from __future__ import annotations

from enum import StrEnum


class Tag(StrEnum):
    """Canonical probe tags shipped in v0.1.

    String values are the public form (used in reports, env
    overrides, CLI ``--only-tags`` etc.). Any free-form string tag
    works too; this enum is a curated set, not a closed universe.
    """

    READ = "read"
    """Probe is a safe, idempotent read (GET / HEAD)."""

    WRITE = "write"
    """Probe mutates server state (POST / PUT / PATCH / DELETE)."""

    PUBLIC = "public"
    """Endpoint requires no authentication."""

    PRIVATE = "private"
    """Endpoint requires authentication."""

    UNSAFE = "unsafe"
    """Probe is intentionally malformed (mutation testing, fuzzing). Skip in normal runs."""


__all__ = ["Tag"]
