"""Near-declarative scenario specs: one loader for scenarios/*.yaml.

A ScenarioSpec is the lane-agnostic shape of a scenario: immutable id

(ADR-0005), optional fixture-registry reference (validated against

config/fixtures.json ids), the operation vocabulary, declarative checks,

modes, and a runtime class for runner placement.

Parsing reuses the same minimal YAML-subset reader the lanes already use

(scripts/mount_probe.parse_yaml_subset, also imported by

platform_lifecycle) so a spec that loads here loads identically in a lane.

MIGRATION STATUS: existing lanes do NOT load their specs through this

module yet. Each lane keeps its current reader until a parity-gated

migration (row_parity proof per lane, zero invariant drift) lands; this

module only has to agree with what the lanes parse today. New

near-declarative lanes should start here.

"""

from __future__ import annotations

import json

from dataclasses import dataclass, field

from pathlib import Path

from typing import Any

# scripts/ is on sys.path wherever oakbench is importable (oakbench lives in

# scripts/), so the lanes' shared mini-parser imports as a top-level module.

from mount_probe import parse_yaml_subset

ROOT = Path(__file__).resolve().parents[2]

DEFAULT_FIXTURES = ROOT / "config" / "fixtures.json"

RUNTIME_CLASSES = ("micro", "standard", "long")

DEFAULT_RUNTIME_CLASS = "standard"

@dataclass(frozen=True)

class ScenarioSpec:

    """One scenario, declaratively: identity plus what it runs and checks."""

    id: str

    fixture: str | None

    operations: tuple[str, ...]

    checks: dict[str, Any] = field(default_factory=dict)

    modes: tuple[str, ...] = ()

    runtime_class: str = DEFAULT_RUNTIME_CLASS

    extras: dict[str, Any] = field(default_factory=dict)

def _fail(path: Path, scenario: str | None, message: str) -> ValueError:

    where = f"{path}" if scenario is None else f"{path} (scenario {scenario!r})"

    return ValueError(f"{where}: {message}")

def _registered_fixture_ids(fixtures_path: Path) -> set[str]:

    data = json.loads(fixtures_path.read_text())

    fixtures = data.get("fixtures")

    if not isinstance(fixtures, dict):

        raise ValueError(f"{fixtures_path}: expected a 'fixtures' object")

    return set(fixtures)

def _string_list(path: Path, scenario: str, key: str, value: Any, *, required: bool) -> tuple[str, ...]:

    if value is None:

        if required:

            raise _fail(path, scenario, f"missing required key {key!r}")

        return ()

    if not isinstance(value, list) or not all(isinstance(item, str) and item for item in value):

        raise _fail(path, scenario, f"{key!r} must be a list of non-empty strings, got {value!r}")

    if required and not value:

        raise _fail(path, scenario, f"{key!r} must not be empty")

    return tuple(value)

_KNOWN_KEYS = {"id", "name", "fixture", "operations", "checks", "modes", "runtime_class"}

def _parse_scenario(path: Path, raw: Any, fixture_ids: set[str]) -> ScenarioSpec:

    if not isinstance(raw, dict):

        raise _fail(path, None, f"each scenario must be a mapping, got {raw!r}")

    # Existing specs (scenarios/platform.yaml and friends) use "name" for the

    # immutable scenario identity; near-declarative specs may say "id".

    spec_id = raw.get("id", raw.get("name"))

    if not isinstance(spec_id, str) or not spec_id:

        raise _fail(path, None, f"scenario missing 'id' (or legacy 'name'): {raw!r}")

    fixture = raw.get("fixture")

    if fixture is not None:

        if not isinstance(fixture, str) or not fixture:

            raise _fail(path, spec_id, f"'fixture' must be null or a fixture-registry id, got {fixture!r}")

        if fixture not in fixture_ids:

            known = ", ".join(sorted(fixture_ids))

            raise _fail(path, spec_id, f"unknown fixture ref {fixture!r}; registered ids: {known}")

    operations = _string_list(path, spec_id, "operations", raw.get("operations"), required=True)

    modes = _string_list(path, spec_id, "modes", raw.get("modes"), required=False)

    checks = raw.get("checks")

    if checks is None:

        checks = {}

    if not isinstance(checks, dict):

        raise _fail(path, spec_id, f"'checks' must be a mapping, got {checks!r}")

    runtime_class = raw.get("runtime_class", DEFAULT_RUNTIME_CLASS)

    if runtime_class not in RUNTIME_CLASSES:

        raise _fail(

            path, spec_id,

            f"'runtime_class' must be one of {RUNTIME_CLASSES}, got {runtime_class!r}",

        )

    extras = {key: value for key, value in raw.items() if key not in _KNOWN_KEYS}

    return ScenarioSpec(

        id=spec_id,

        fixture=fixture,

        operations=operations,

        checks=checks,

        modes=modes,

        runtime_class=runtime_class,

        extras=extras,

    )

def load_scenario_specs(path: Path, fixtures_path: Path = DEFAULT_FIXTURES) -> list[ScenarioSpec]:

    """Load every scenario in a scenarios/*.yaml spec as ScenarioSpec values.

    Raises ValueError with the spec path (and scenario id once known) in the

    message for any structural problem: unparseable spec, missing id,

    missing/empty operations, unknown fixture ref, bad runtime_class.

    """

    path = Path(path)

    if not path.is_file():

        raise ValueError(f"{path}: scenario spec not found")

    try:

        document = parse_yaml_subset(path.read_text())

    except Exception as exc:

        raise ValueError(f"{path}: could not parse scenario spec: {exc}") from exc

    raw_scenarios = document.get("scenarios")

    if not isinstance(raw_scenarios, list) or not raw_scenarios:

        raise ValueError(f"{path}: expected a non-empty top-level 'scenarios' list")

    fixture_ids = _registered_fixture_ids(Path(fixtures_path))

    specs = [_parse_scenario(path, raw, fixture_ids) for raw in raw_scenarios]

    seen: set[str] = set()

    for spec in specs:

        if spec.id in seen:

            raise ValueError(f"{path}: duplicate scenario id {spec.id!r} (ADR-0005: ids are immutable identity)")

        seen.add(spec.id)

    return specs