"""
qCompute with RTT-Inside — Preview Core
---------------------------------------
 
This module sketches a resonance-aware wrapper around "compute"
so every call can be:
 
- observed (what is being asked?)
- situated (in which resonance frame?)
- wrapped (so future tools can replay, audit, or remix)
 
Nothing here assumes a specific backend (NumPy, qiskit, custom solvers).
Think of it as a structural harness, not a final engine.
"""
 
from __future__ import annotations
from dataclasses import dataclass, field
from typing import Any, Callable, Dict, Optional, Protocol, Tuple
import time
import uuid
 
 
# -----------------------------
# 1. Core protocols and types
# -----------------------------
 
class ComputeBackend(Protocol):
    """
    Minimal protocol for a compute backend.
 
    Anything that can be wrapped by RTT-Inside only needs
    to implement this interface.
    """
 
    def run(self, payload: Any, **kwargs: Any) -> Any:
        ...
 
 
@dataclass
class ResonanceFrame:
    """
    A resonance frame is the smallest unit of "awareness"
    we attach to a compute call.
 
    It does NOT care what the math is yet.
    It cares about: who, where, why, and how we might replay it.
    """
 
    frame_id: str = field(default_factory=lambda: str(uuid.uuid4()))
    label: str = "unnamed-frame"
 
    # Triadic anchors
    intent: str = "unspecified-intent"      # what is being sought?
    context: str = "unspecified-context"    # where does this live?
    consequence: str = "unspecified-impact" # why does it matter?
 
    # Optional: tags for routing, governance, or replay
    tags: Dict[str, Any] = field(default_factory=dict)
 
    # Optional: timing and trace
    created_at: float = field(default_factory=time.time)
 
    def with_tag(self, key: str, value: Any) -> "ResonanceFrame":
        self.tags[key] = value
        return self
 
 
@dataclass
class ResonanceResult:
    """
    Wraps the raw backend result with RTT-Inside metadata.
    """
 
    frame: ResonanceFrame
    payload: Any
    backend_name: str
    started_at: float
    finished_at: float
 
    @property
    def duration(self) -> float:
        return self.finished_at - self.started_at
 
 
# -----------------------------
# 2. Wrapped core
# -----------------------------
 
@dataclass
class WrappedCore:
    """
    The WrappedCore is the RTT-Inside harness around any compute backend.
 
    It does three things:
    - accepts a ResonanceFrame (or builds a default one)
    - calls the backend
    - returns a ResonanceResult with timing + metadata
    """
 
    backend: ComputeBackend
    backend_name: str = "unnamed-backend"
 
    def qcompute(
        self,
        payload: Any,
        *,
        frame: Optional[ResonanceFrame] = None,
        **kwargs: Any,
    ) -> ResonanceResult:
        """
        Main entry point: qCompute with RTT-Inside.
 
        - `payload` is whatever the backend expects (circuit, array, graph, etc.)
        - `frame` is the resonance wrapper (intent/context/consequence)
        - `kwargs` are passed directly to the backend
        """
        frame = frame or ResonanceFrame(label="auto-frame")
 
        started_at = time.time()
        result = self.backend.run(payload, **kwargs)
        finished_at = time.time()
 
        return ResonanceResult(
            frame=frame,
            payload=result,
            backend_name=self.backend_name,
            started_at=started_at,
            finished_at=finished_at,
        )
 
 
# -----------------------------
# 3. Example: a toy backend
# -----------------------------
 
class EchoBackend:
    """
    A trivial backend for documentation and testing.
 
    It just echoes the payload and records that it was "processed".
    Replace this with NumPy, qiskit, or your real engine.
    """
 
    def run(self, payload: Any, **kwargs: Any) -> Dict[str, Any]:
        return {
            "echo": payload,
            "meta": {
                "kwargs": kwargs,
                "processed": True,
            },
        }
 
 
# -----------------------------
# 4. Example usage
# -----------------------------
 
def _demo() -> None:
    backend = EchoBackend()
    core = WrappedCore(backend=backend, backend_name="echo-core")
 
    frame = ResonanceFrame(
        label="demo-qcompute",
        intent="test-wrapped-core",
        context="docs/qCompute_with_RTT-Inside_Preview.md",
        consequence="validate-structural-harness",
    ).with_tag("author", "Nawder").with_tag("mode", "preview")
 
    result = core.qcompute(
        payload={"amplitude": 0.42, "phase": "π/3"},
        frame=frame,
        precision="preview",
    )
 
    print("Frame ID:", result.frame.frame_id)
    print("Intent:", result.frame.intent)
    print("Duration (s):", result.duration)
    print("Payload:", result.payload)
 
 
if __name__ == "__main__":
    _demo()

# -----------------------------
# 5. Triadic Router
# -----------------------------
 
class TriadicMode:
    """
    Triadic operational modes for RTT-Inside.
 
    - explore: fast, heuristic, playful, minimal constraints
    - verify: deterministic, logged, reproducible
    - deploy: strict, validated, production-safe
    """
 
    EXPLORE = "explore"
    VERIFY = "verify"
    DEPLOY = "deploy"
 
    ALL = {EXPLORE, VERIFY, DEPLOY}
 
 
@dataclass
class TriadicRouter:
    """
    The router decides *how* the backend should be invoked
    based on the triadic mode.
 
    This is intentionally lightweight. It does not assume
    any specific backend semantics — it only shapes the call.
    """
 
    def route(
        self,
        mode: str,
        backend: ComputeBackend,
        payload: Any,
        **kwargs: Any,
    ) -> Any:
 
        if mode not in TriadicMode.ALL:
            raise ValueError(f"Invalid triadic mode: {mode}")
 
        # -----------------------------
        # explore mode
        # -----------------------------
        if mode == TriadicMode.EXPLORE:
            # loosen constraints, allow heuristics
            kwargs.setdefault("precision", "low")
            kwargs.setdefault("allow_approx", True)
            kwargs.setdefault("trace", False)
            return backend.run(payload, **kwargs)
 
        # -----------------------------
        # verify mode
        # -----------------------------
        if mode == TriadicMode.VERIFY:
            # enforce determinism and logging
            kwargs.setdefault("precision", "high")
            kwargs.setdefault("allow_approx", False)
            kwargs.setdefault("trace", True)
            kwargs.setdefault("seed", 42)
            return backend.run(payload, **kwargs)
 
        # -----------------------------
        # deploy mode
        # -----------------------------
        if mode == TriadicMode.DEPLOY:
            # strictest path: validated inputs only
            kwargs.setdefault("precision", "strict")
            kwargs.setdefault("allow_approx", False)
            kwargs.setdefault("trace", True)
            kwargs.setdefault("validate_inputs", True)
            return backend.run(payload, **kwargs)

# -----------------------------
# 6. WrappedCore with Router
# -----------------------------
 
@dataclass
class WrappedCore:
    backend: ComputeBackend
    backend_name: str = "unnamed-backend"
    router: TriadicRouter = field(default_factory=TriadicRouter)
 
    def qcompute(
        self,
        payload: Any,
        *,
        frame: Optional[ResonanceFrame] = None,
        mode: str = TriadicMode.EXPLORE,
        **kwargs: Any,
    ) -> ResonanceResult:
 
        frame = frame or ResonanceFrame(label="auto-frame")
        frame.with_tag("mode", mode)
 
        started_at = time.time()
 
        # Route through triadic mode
        result = self.router.route(
            mode=mode,
            backend=self.backend,
            payload=payload,
            **kwargs,
        )
 
        finished_at = time.time()
 
        return ResonanceResult(
            frame=frame,
            payload=result,
            backend_name=self.backend_name,
            started_at=started_at,
            finished_at=finished_at,
        )

def _demo_triadic():
    backend = EchoBackend()
    core = WrappedCore(backend=backend, backend_name="echo-core")
 
    frame = ResonanceFrame(
        label="triadic-demo",
        intent="demonstrate-routing",
        context="docs/qCompute_with_RTT-Inside_Preview.md",
        consequence="show-mode-differences",
    )
 
    for mode in [TriadicMode.EXPLORE, TriadicMode.VERIFY, TriadicMode.DEPLOY]:
        result = core.qcompute(
            payload={"value": 3.14},
            frame=frame,
            mode=mode,
        )
        print(f"\nMode: {mode}")
        print("Payload:", result.payload)
        print("Duration:", result.duration)

# -----------------------------
# 7. qTrace Line Format
# -----------------------------
 
import json
import hashlib
 
def _hash_payload(payload: Any) -> str:
    """
    Minimal stable hash for replay identification.
    Converts payload to JSON (if possible) and hashes it.
    """
    try:
        encoded = json.dumps(payload, sort_keys=True).encode("utf-8")
    except Exception:
        encoded = repr(payload).encode("utf-8")
 
    return hashlib.sha256(encoded).hexdigest()[:16]  # short hash
 
 
def qtrace_line(result: ResonanceResult) -> str:
    """
    Produce a single-line, replay-ready qTrace entry.
 
    Format (one line):
    qTrace | frame=<id> | mode=<mode> | intent=<intent> | backend=<backend> |
            duration=<sec> | payload=<hash> | tags=<json>
 
    This is intentionally minimal and stable.
    """
    frame = result.frame
 
    mode = frame.tags.get("mode", "unknown")
    payload_hash = _hash_payload(result.payload)
 
    tags_json = json.dumps(frame.tags, sort_keys=True)
 
    return (
        f"qTrace | "
        f"frame={frame.frame_id} | "
        f"mode={mode} | "
        f"intent={frame.intent} | "
        f"backend={result.backend_name} | "
        f"duration={result.duration:.6f} | "
        f"payload={payload_hash} | "
        f"tags={tags_json}"
    )

# Inside WrappedCore.qcompute(), after constructing the ResonanceResult:
 
res = ResonanceResult(
    frame=frame,
    payload=result,
    backend_name=self.backend_name,
    started_at=started_at,
    finished_at=finished_at,
)
 
# Auto-generate qTrace line
res.qtrace = qtrace_line(res)
 
return res

# -----------------------------
# 10. Triadic Mode Validator
# -----------------------------
 
class TriadicValidator:
    """
    Validates payload structure depending on triadic mode.
 
    This is intentionally minimal:
    - explore: accept anything JSON-serializable or repr-able
    - verify: require dict-like or list-like structures
    - deploy: require strict dict with known keys (configurable)
    """
 
    def __init__(self, required_keys=None):
        # Keys required in DEPLOY mode
        self.required_keys = required_keys or {"amplitude", "phase"}
 
    def validate(self, mode: str, payload: Any) -> None:
        """
        Raises ValueError if the payload does not meet mode requirements.
        """
 
        # -----------------------------
        # explore mode — accept anything
        # -----------------------------
        if mode == TriadicMode.EXPLORE:
            return  # no constraints
 
        # -----------------------------
        # verify mode — must be structured
        # -----------------------------
        if mode == TriadicMode.VERIFY:
            if not isinstance(payload, (dict, list, tuple)):
                raise ValueError(
                    f"VERIFY mode requires structured payload (dict/list/tuple), "
                    f"got {type(payload).__name__}"
                )
            return
 
        # -----------------------------
        # deploy mode — strict dict with required keys
        # -----------------------------
        if mode == TriadicMode.DEPLOY:
            if not isinstance(payload, dict):
                raise ValueError(
                    f"DEPLOY mode requires dict payload, got {type(payload).__name__}"
                )
 
            missing = self.required_keys - payload.keys()
            if missing:
                raise ValueError(
                    f"DEPLOY mode missing required keys: {sorted(missing)}"
                )
            return
 
        # -----------------------------
        # unknown mode
        # -----------------------------
        raise ValueError(f"Unknown triadic mode: {mode}")

@dataclass
class TriadicRouter:
    validator: TriadicValidator = field(default_factory=TriadicValidator)
 
    def route(
        self,
        mode: str,
        backend: ComputeBackend,
        payload: Any,
        **kwargs: Any,
    ) -> Any:
 
        # Validate payload structure first
        self.validator.validate(mode, payload)
 
        # Existing routing logic continues below...
        if mode == TriadicMode.EXPLORE:
            kwargs.setdefault("precision", "low")
            kwargs.setdefault("allow_approx", True)
            kwargs.setdefault("trace", False)
            return backend.run(payload, **kwargs)
 
        if mode == TriadicMode.VERIFY:
            kwargs.setdefault("precision", "high")
            kwargs.setdefault("allow_approx", False)
            kwargs.setdefault("trace", True)
            kwargs.setdefault("seed", 42)
            return backend.run(payload, **kwargs)
 
        if mode == TriadicMode.DEPLOY:
            kwargs.setdefault("precision", "strict")
            kwargs.setdefault("allow_approx", False)
            kwargs.setdefault("trace", True)
            kwargs.setdefault("validate_inputs", True)
            return backend.run(payload, **kwargs)
 
        raise ValueError(f"Invalid triadic mode: {mode}")

core.qcompute(payload="hello", mode="explore")

core.qcompute(payload="hello", mode="verify")

core.qcompute(payload={"amplitude": 0.5}, mode="deploy")

core.qcompute(payload={"amplitude": 0.5, "phase": "π/3"}, mode="deploy")

# -----------------------------
# 13. qReplay — replay qTrace lines
# -----------------------------
 
import re
import json
 
_qtrace_pattern = re.compile(
    r"qTrace \| frame=(?P<frame>[^|]+) \| mode=(?P<mode>[^|]+) \| "
    r"intent=(?P<intent>[^|]+) \| backend=(?P<backend>[^|]+) \| "
    r"duration=(?P<duration>[^|]+) \| payload=(?P<payload>[^|]+) \| "
    r"tags=(?P<tags>.+)$"
)
 
def qReplay(
    trace_line: str,
    *,
    core_registry: Dict[str, WrappedCore],
    payload_lookup: Dict[str, Any],
) -> ResonanceResult:
    """
    Replays a qTrace line by reconstructing the frame and re-running qCompute.
 
    Parameters:
    - trace_line: the qTrace line produced earlier
    - core_registry: mapping backend_name -> WrappedCore instance
    - payload_lookup: mapping payload_hash -> original payload
 
    Returns:
    - ResonanceResult from the re-executed call
 
    Notes:
    - This requires that payloads are stored externally (payload_lookup)
      because qTrace lines only store a hash, not the full payload.
    """
 
    match = _qtrace_pattern.match(trace_line.strip())
    if not match:
        raise ValueError("Invalid qTrace line format")
 
    data = match.groupdict()
 
    backend_name = data["backend"]
    mode = data["mode"]
    intent = data["intent"]
    tags = json.loads(data["tags"])
    payload_hash = data["payload"]
 
    # Retrieve backend
    if backend_name not in core_registry:
        raise ValueError(f"Backend '{backend_name}' not found in registry")
 
    core = core_registry[backend_name]
 
    # Retrieve payload
    if payload_hash not in payload_lookup:
        raise ValueError(
            f"Payload hash '{payload_hash}' not found in payload lookup"
        )
 
    payload = payload_lookup[payload_hash]
 
    # Reconstruct resonance frame
    frame = ResonanceFrame(
        label="replay-frame",
        intent=intent,
        context="qReplay",
        consequence="re-executed-from-trace",
        tags=tags,
    )
 
    # Re-execute
    result = core.qcompute(
        payload=payload,
        frame=frame,
        mode=mode,
    )
 
    return result

# Setup registry and payload store
core = WrappedCore(backend=EchoBackend(), backend_name="echo-core")
core_registry = {"echo-core": core}
payload_lookup = {}
 
# Original call
res = core.qcompute(
    payload={"amplitude": 0.42, "phase": "π/3"},
    mode="verify",
)
 
# Store payload for replay
payload_lookup[_hash_payload(res.payload)] = {"amplitude": 0.42, "phase": "π/3"}
 
# Replay
replayed = qReplay(
    res.qtrace,
    core_registry=core_registry,
    payload_lookup=payload_lookup,
)
 
print("Replayed:", replayed.payload)
print("Trace:", replayed.qtrace)

# -----------------------------
# 15. qTraceCollector
# -----------------------------
 
@dataclass
class qTraceCollector:
    """
    Collects qTrace lines, payloads, and backend references for a session.
 
    Responsibilities:
    - store qTrace lines in order
    - store payloads keyed by payload-hash
    - store backend cores keyed by backend-name
    - provide batch replay
    """
 
    traces: list[str] = field(default_factory=list)
    payloads: Dict[str, Any] = field(default_factory=dict)
    cores: Dict[str, WrappedCore] = field(default_factory=dict)
 
    def register_core(self, core: WrappedCore) -> None:
        """Register a backend core for replay."""
        self.cores[core.backend_name] = core
 
    def record(self, result: ResonanceResult) -> None:
        """
        Record a qCompute result:
        - store qTrace line
        - store payload hash → payload
        - ensure backend is registered
        """
        trace_line = result.qtrace
        self.traces.append(trace_line)
 
        # store payload
        payload_hash = _hash_payload(result.payload)
        self.payloads[payload_hash] = result.payload
 
        # register backend
        if result.backend_name not in self.cores:
            raise ValueError(
                f"Backend '{result.backend_name}' not registered in collector"
            )
 
    def replay_all(self) -> list[ResonanceResult]:
        """Replay all traces in order."""
        results = []
        for line in self.traces:
            res = qReplay(
                line,
                core_registry=self.cores,
                payload_lookup=self.payloads,
            )
            results.append(res)
        return results
 
    def replay_last(self) -> ResonanceResult:
        """Replay the most recent trace."""
        if not self.traces:
            raise ValueError("No traces recorded")
        return qReplay(
            self.traces[-1],
            core_registry=self.cores,
            payload_lookup=self.payloads,
        )
 
    def export(self) -> dict:
        """
        Export the session as a dict:
        - traces
        - payloads
        - backend names
        """
        return {
            "traces": list(self.traces),
            "payloads": {k: repr(v) for k, v in self.payloads.items()},
            "cores": list(self.cores.keys()),
        }

def _demo_session():
    # Setup
    backend = EchoBackend()
    core = WrappedCore(backend=backend, backend_name="echo-core")
 
    collector = qTraceCollector()
    collector.register_core(core)
 
    # Run some qCompute calls
    r1 = core.qcompute(
        payload={"amplitude": 0.1, "phase": "π/6"},
        mode="explore",
    )
    collector.record(r1)
 
    r2 = core.qcompute(
        payload={"amplitude": 0.42, "phase": "π/3"},
        mode="verify",
    )
    collector.record(r2)
 
    r3 = core.qcompute(
        payload={"amplitude": 0.9, "phase": "π"},
        mode="deploy",
    )
    collector.record(r3)
 
    # Replay entire session
    replayed = collector.replay_all()
    for res in replayed:
        print("Replayed:", res.payload)
        print("Trace:", res.qtrace)

# -----------------------------
# 16. qSession — high-level API
# -----------------------------
 
@dataclass
class qSession:
    """
    High-level session wrapper around qTraceCollector.
 
    Features:
    - context manager support
    - automatic backend registration
    - automatic trace collection
    - batch replay
    - session export
    """
 
    collector: qTraceCollector = field(default_factory=qTraceCollector)
    active: bool = False
 
    def __enter__(self) -> "qSession":
        self.active = True
        return self
 
    def __exit__(self, exc_type, exc, tb) -> None:
        self.active = False
 
    # -----------------------------
    # Registration
    # -----------------------------
    def register_core(self, core: WrappedCore) -> None:
        """Register a backend core for use in this session."""
        self.collector.register_core(core)
 
    # -----------------------------
    # Recording
    # -----------------------------
    def record(self, result: ResonanceResult) -> None:
        """Record a qCompute result into the session."""
        if not self.active:
            raise RuntimeError("qSession is not active")
        self.collector.record(result)
 
    # -----------------------------
    # Replay
    # -----------------------------
    def replay_all(self) -> list[ResonanceResult]:
        """Replay all traces in this session."""
        return self.collector.replay_all()
 
    def replay_last(self) -> ResonanceResult:
        """Replay the most recent trace."""
        return self.collector.replay_last()
 
    # -----------------------------
    # Export
    # -----------------------------
    def export(self) -> dict:
        """Export the session as a portable dict."""
        return self.collector.export()

def _demo_qsession():
    backend = EchoBackend()
    core = WrappedCore(backend=backend, backend_name="echo-core")
 
    with qSession() as session:
        session.register_core(core)
 
        r1 = core.qcompute(
            payload={"amplitude": 0.1, "phase": "π/6"},
            mode="explore",
        )
        session.record(r1)
 
        r2 = core.qcompute(
            payload={"amplitude": 0.42, "phase": "π/3"},
            mode="verify",
        )
        session.record(r2)
 
        r3 = core.qcompute(
            payload={"amplitude": 0.9, "phase": "π"},
            mode="deploy",
        )
        session.record(r3)
 
        # Replay entire session
        replayed = session.replay_all()
        for res in replayed:
            print("Replayed:", res.payload)
            print("Trace:", res.qtrace)
 
    # Export session
    exported = session.export()
    print("Exported session:", exported)

# -----------------------------
# 17. qPretty — console-style pretty printer
# -----------------------------
 
class qPretty:
    """
    Human-friendly pretty printer for qTrace lines and ResonanceResults.
 
    Features:
    - aligned fields
    - optional ANSI colors
    - works with single results or batches
    """
 
    use_color = True
 
    COLORS = {
        "header": "\033[95m",
        "label": "\033[94m",
        "value": "\033[92m",
        "reset": "\033[0m",
    }
 
    @classmethod
    def _c(cls, key: str, text: str) -> str:
        if not cls.use_color:
            return text
        return f"{cls.COLORS.get(key, '')}{text}{cls.COLORS['reset']}"
 
    @classmethod
    def print_result(cls, result: ResonanceResult) -> None:
        """Pretty print a single ResonanceResult."""
        f = result.frame
 
        print(cls._c("header", "── qCompute Result ─────────────────────────────"))
        print(f"{cls._c('label','Frame ID:')}     {cls._c('value', f.frame_id)}")
        print(f"{cls._c('label','Intent:')}       {cls._c('value', f.intent)}")
        print(f"{cls._c('label','Mode:')}         {cls._c('value', f.tags.get('mode','unknown'))}")
        print(f"{cls._c('label','Backend:')}      {cls._c('value', result.backend_name)}")
        print(f"{cls._c('label','Duration:')}     {cls._c('value', f'{result.duration:.6f} s')}")
        print(f"{cls._c('label','Tags:')}         {cls._c('value', str(f.tags))}")
        print(f"{cls._c('label','Payload:')}      {cls._c('value', repr(result.payload))}")
        print(cls._c("header", "────────────────────────────────────────────────"))
 
    @classmethod
    def print_trace(cls, trace_line: str) -> None:
        """Pretty print a qTrace line."""
        print(cls._c("header", "── qTrace ─────────────────────────────────────"))
        print(cls._c("value", trace_line))
        print(cls._c("header", "────────────────────────────────────────────────"))
 
    @classmethod
    def print_session(cls, session: "qSession") -> None:
        """Pretty print all traces in a qSession."""
        print(cls._c("header", "══ qSession Log ════════════════════════════════"))
        for i, line in enumerate(session.collector.traces, start=1):
            print(cls._c("label", f"[{i}] "), end="")
            print(cls._c("value", line))
        print(cls._c("header", "════════════════════════════════════════════════"))

def _demo_pretty():
    backend = EchoBackend()
    core = WrappedCore(backend=backend, backend_name="echo-core")
 
    with qSession() as session:
        session.register_core(core)
 
        r = core.qcompute(
            payload={"amplitude": 0.42, "phase": "π/3"},
            mode="verify",
        )
        session.record(r)
 
        # Pretty print the result
        qPretty.print_result(r)
 
        # Pretty print the trace
        qPretty.print_trace(r.qtrace)
 
        # Pretty print the whole session
        qPretty.print_session(session)

# -----------------------------
# 18. Triadic Governance Layer
# -----------------------------
 
class GovernanceError(Exception):
    """Raised when a qCompute call violates governance policy."""
    pass
 
 
@dataclass
class TriadicGovernance:
    """
    Enforces permissions and policy constraints per triadic mode.
 
    This is intentionally minimal:
    - explore: allow everything except restricted operations
    - verify: require trusted context
    - deploy: require explicit permission token
    """
 
    # Example: operations that cannot be run in explore mode
    restricted_ops: set[str] = field(default_factory=lambda: {"sensitive", "unsafe"})
 
    # Example: trusted contexts allowed for verify mode
    trusted_contexts: set[str] = field(default_factory=lambda: {"unit-test", "ci", "docs"})
 
    # Example: required token for deploy mode
    deploy_token: str = "ALLOW_DEPLOY"
 
    def check_permissions(
        self,
        mode: str,
        frame: ResonanceFrame,
        payload: Any,
        **kwargs: Any,
    ) -> None:
 
        # -----------------------------
        # explore mode
        # -----------------------------
        if mode == TriadicMode.EXPLORE:
            op = frame.tags.get("operation")
            if op in self.restricted_ops:
                raise GovernanceError(
                    f"Operation '{op}' is restricted in EXPLORE mode"
                )
            return
 
        # -----------------------------
        # verify mode
        # -----------------------------
        if mode == TriadicMode.VERIFY:
            ctx = frame.context
            if ctx not in self.trusted_contexts:
                raise GovernanceError(
                    f"VERIFY mode requires trusted context, got '{ctx}'"
                )
            return
 
        # -----------------------------
        # deploy mode
        # -----------------------------
        if mode == TriadicMode.DEPLOY:
            token = frame.tags.get("token")
            if token != self.deploy_token:
                raise GovernanceError(
                    "DEPLOY mode requires explicit deploy token"
                )
            return
 
        raise GovernanceError(f"Unknown triadic mode: {mode}")

@dataclass
class TriadicRouter:
    validator: TriadicValidator = field(default_factory=TriadicValidator)
    governance: TriadicGovernance = field(default_factory=TriadicGovernance)
 
    def route(
        self,
        mode: str,
        backend: ComputeBackend,
        payload: Any,
        frame: ResonanceFrame,
        **kwargs: Any,
    ) -> Any:
 
        # 1. Governance check
        self.governance.check_permissions(
            mode=mode,
            frame=frame,
            payload=payload,
            **kwargs,
        )
 
        # 2. Structural validation
        self.validator.validate(mode, payload)
 
        # 3. Existing routing logic
        if mode == TriadicMode.EXPLORE:
            kwargs.setdefault("precision", "low")
            kwargs.setdefault("allow_approx", True)
            kwargs.setdefault("trace", False)
            return backend.run(payload, **kwargs)
 
        if mode == TriadicMode.VERIFY:
            kwargs.setdefault("precision", "high")
            kwargs.setdefault("allow_approx", False)
            kwargs.setdefault("trace", True)
            kwargs.setdefault("seed", 42)
            return backend.run(payload, **kwargs)
 
        if mode == TriadicMode.DEPLOY:
            kwargs.setdefault("precision", "strict")
            kwargs.setdefault("allow_approx", False)
            kwargs.setdefault("trace", True)
            kwargs.setdefault("validate_inputs", True)
            return backend.run(payload, **kwargs)
 
        raise ValueError(f"Invalid triadic mode: {mode}")

result = self.router.route(
    mode=mode,
    backend=self.backend,
    payload=payload,
    frame=frame,
    **kwargs,
)

frame.with_tag("operation", "sensitive")
core.qcompute(..., mode="explore")

frame.context = "production"
core.qcompute(..., mode="verify")

frame.with_tag("token", "WRONG")
core.qcompute(..., mode="deploy")

frame.with_tag("token", "ALLOW_DEPLOY")
core.qcompute(..., mode="deploy")

# -----------------------------
# 21. qSessionLogWriter
# -----------------------------
 
@dataclass
class qSessionLogWriter:
    """
    Streams qTrace lines to a `.qtrace` file in a Git-friendly format.
 
    Features:
    - append-only streaming
    - deterministic ordering
    - optional session headers/footers
    - integrates with qSession
    """
 
    path: str
    include_header: bool = True
    include_footer: bool = True
    opened: bool = False
    _file: Any = field(default=None, init=False, repr=False)
 
    def open(self) -> None:
        """Open the log file for streaming writes."""
        if self.opened:
            return
        self._file = open(self.path, "a", encoding="utf-8")
        self.opened = True
 
        if self.include_header:
            self._file.write("# qTrace Session Log\n")
            self._file.write("# -------------------\n")
 
    def write_trace(self, trace_line: str) -> None:
        """Write a single qTrace line to the log."""
        if not self.opened:
            self.open()
        self._file.write(trace_line + "\n")
        self._file.flush()
 
    def close(self) -> None:
        """Close the log file and optionally write a footer."""
        if not self.opened:
            return
 
        if self.include_footer:
            self._file.write("# End of qTrace Session\n\n")
 
        self._file.close()
        self.opened = False

@dataclass
class qSession:
    collector: qTraceCollector = field(default_factory=qTraceCollector)
    active: bool = False
    log_writer: Optional[qSessionLogWriter] = None
 
    def attach_log_writer(self, writer: qSessionLogWriter) -> None:
        """Attach

# -----------------------------
# 22. qPolicyFile — loadable governance policy
# -----------------------------
 
import json
from dataclasses import dataclass, field
from typing import Any, Dict
 
try:
    import yaml  # optional dependency
except ImportError:
    yaml = None
 
 
@dataclass
class qPolicyFile:
    """
    Loads governance rules from a YAML or JSON policy document.
 
    Expected structure:
    {
        "restricted_ops": ["sensitive", "unsafe"],
        "trusted_contexts": ["unit-test", "ci", "docs"],
        "deploy_token": "ALLOW_DEPLOY"
    }
    """
 
    path: str
    data: Dict[str, Any] = field(default_factory=dict)
 
    def load(self) -> None:
        """Load policy from YAML or JSON file."""
        if self.path.endswith(".json"):
            with open(self.path, "r", encoding="utf-8") as f:
                self.data = json.load(f)
 
        elif self.path.endswith((".yaml", ".yml")):
            if yaml is None:
                raise ImportError("PyYAML is required to load YAML policy files")
            with open(self.path, "r", encoding="utf-8") as f:
                self.data = yaml.safe_load(f)
 
        else:
            raise ValueError("Unsupported policy file format (use .json or .yaml)")
 
    def get(self, key: str, default: Any = None) -> Any:
        """Retrieve a policy value with fallback."""
        return self.data.get(key, default)

@dataclass
class TriadicGovernance:
    restricted_ops: set[str] = field(default_factory=set)
    trusted_contexts: set[str] = field(default_factory=set)
    deploy_token: str = "ALLOW_DEPLOY"
 
    @classmethod
    def from_policy(cls, policy: qPolicyFile) -> "TriadicGovernance":
        return cls(
            restricted_ops=set(policy.get("restricted_ops", [])),
            trusted_contexts=set(policy.get("trusted_contexts", [])),
            deploy_token=policy.get("deploy_token", "ALLOW_DEPLOY"),
        )

@dataclass
class TriadicRouter:
    validator: TriadicValidator = field(default_factory=TriadicValidator)
    governance: TriadicGovernance = field(default_factory=TriadicGovernance)
 
    def route(
        self,
        mode: str,
        backend: ComputeBackend,
        payload: Any,
        frame: ResonanceFrame,
        **kwargs: Any,
    ) -> Any:
 
        # 1. Governance check (policy-driven)
        self.governance.check_permissions(
            mode=mode,
            frame=frame,
            payload=payload,
            **kwargs,
        )
 
        # 2. Structural validation
        self.validator.validate(mode, payload)
 
        # 3. Existing routing logic...
        ...

# qcompute_policy.yaml
 
restricted_ops:
  - sensitive
  - unsafe
 
trusted_contexts:
  - unit-test
  - ci
  - docs
 
deploy_token: "ALLOW_DEPLOY"

# Load policy
policy = qPolicyFile("qcompute_policy.yaml")
policy.load()
 
# Build governance from policy
governance = TriadicGovernance.from_policy(policy)
 
# Inject into router
router = TriadicRouter(governance=governance)
 
# Build core
core = WrappedCore(
    backend=EchoBackend(),
    backend_name="echo-core",
    router=router,
)
 
# Now qCompute calls obey the policy file
frame = ResonanceFrame(
    label="demo",
    intent="test-governance",
    context="docs",
).with_tag("operation", "sensitive")
 
core.qcompute(
    payload={"amplitude": 0.42, "phase": "π/3"},
    mode="explore",  # will be blocked by policy
)

# -----------------------------
# 23. qPolicyWatcher
# -----------------------------
 
import os
import time
from dataclasses import dataclass, field
from typing import Optional, Callable
 
 
@dataclass
class qPolicyWatcher:
    """
    Watches a policy file for changes and reloads it automatically.
 
    Features:
    - timestamp-based change detection
    - auto-reload of qPolicyFile
    - optional callback on reload
    - integrates with TriadicGovernance
    """
 
    policy_file: qPolicyFile
    governance: TriadicGovernance
    on_reload: Optional[Callable[[TriadicGovernance], None]] = None
 
    _last_mtime: float = field(default=0.0, init=False)
 
    def check(self) -> None:
        """
        Check if the policy file has changed.
        If so, reload and update governance.
        """
        try:
            mtime = os.path.getmtime(self.policy_file.path)
        except FileNotFoundError:
            return  # silently ignore missing file
 
        # First run: initialize timestamp
        if self._last_mtime == 0.0:
            self._last_mtime = mtime
            return
 
        # Detect change
        if mtime != self._last_mtime:
            self._last_mtime = mtime
            self._reload_policy()
 
    def _reload_policy(self) -> None:
        """Reload policy and update governance."""
        self.policy_file.load()
        new_gov = TriadicGovernance.from_policy(self.policy_file)
 
        # Update governance object in place
        self.governance.restricted_ops = new_gov.restricted_ops
        self.governance.trusted_contexts = new_gov.trusted_contexts
        self.governance.deploy_token = new_gov.deploy_token
 
        # Optional callback
        if self.on_reload:
            self.on_reload(self.governance)

@dataclass
class TriadicRouter:
    validator: TriadicValidator = field(default_factory=TriadicValidator)
    governance: TriadicGovernance = field(default_factory=TriadicGovernance)
    policy_watcher: Optional[qPolicyWatcher] = None
 
    def route(
        self,
        mode: str,
        backend: ComputeBackend,
        payload: Any,
        frame: ResonanceFrame,
        **kwargs: Any,
    ) -> Any:
 
        # 0. Hot-swap governance if policy changed
        if self.policy_watcher:
            self.policy_watcher.check()
 
        # 1. Governance check
        self.governance.check_permissions(
            mode=mode,
            frame=frame,
            payload=payload,
            **kwargs,
        )
 
        # 2. Structural validation
        self.validator.validate(mode, payload)
 
        # 3. Existing routing logic...
        if mode == TriadicMode.EXPLORE:
            kwargs.setdefault("precision", "low")
            kwargs.setdefault("allow_approx", True)
            kwargs.setdefault("trace", False)
            return backend.run(payload, **kwargs)
 
        if mode == TriadicMode.VERIFY:
            kwargs.setdefault("precision", "high")
            kwargs.setdefault("allow_approx", False)
            kwargs.setdefault("trace", True)
            kwargs.setdefault("seed", 42)
            return backend.run(payload, **kwargs)
 
        if mode == TriadicMode.DEPLOY:
            kwargs.setdefault("precision", "strict")
            kwargs.setdefault("allow_approx", False)
            kwargs.setdefault("trace", True)
            kwargs.setdefault("validate_inputs", True)
            return backend.run(payload, **kwargs)
 
        raise ValueError(f"Invalid triadic mode: {mode}")

# Load policy file
policy = qPolicyFile("qcompute_policy.yaml")
policy.load()
 
# Build governance from policy
governance = TriadicGovernance.from_policy(policy)
 
# Build watcher
watcher = qPolicyWatcher(
    policy_file=policy,
    governance=governance,
    on_reload=lambda gov: print("Policy reloaded:", gov),
)
 
# Build router with watcher
router = TriadicRouter(
    governance=governance,
    policy_watcher=watcher,
)
 
# Build core
core = WrappedCore(
    backend=EchoBackend(),
    backend_name="echo-core",
    router=router,
)
 
# Now every qCompute call auto-checks for policy updates
frame = ResonanceFrame(
    label="demo",
    intent="test-hot-swap",
    context="docs",
).with_tag("operation", "sensitive")
 
# If you edit qcompute_policy.yaml while this runs,
# the governance rules update instantly.
core.qcompute(
    payload={"amplitude": 0.42, "phase": "π/3"},
    mode="explore",
)

# -----------------------------
# 26. qDaemon — background watcher thread
# -----------------------------
 
import threading
import time
from dataclasses import dataclass, field
from typing import Optional
 
 
@dataclass
class qDaemon:
    """
    Runs qPolicyWatcher in a background thread for continuous monitoring.
 
    Features:
    - starts/stops cleanly
    - configurable polling interval
    - optional on-reload callback
    - thread-safe and lightweight
    """
 
    watcher: qPolicyWatcher
    interval: float = 1.0  # seconds
    _thread: Optional[threading.Thread] = field(default=None, init=False)
    _running: bool = field(default=False, init=False)
 
    def start(self) -> None:
        """Start the background daemon thread."""
        if self._running:
            return
 
        self._running = True
 
        def _loop():
            while self._running:
                try:
                    self.watcher.check()
                except Exception as e:
                    # Optional: log or print errors
                    print(f"[qDaemon] Error during policy check: {e}")
                time.sleep(self.interval)
 
        self._thread = threading.Thread(
            target=_loop,
            daemon=True,
            name="qPolicyDaemon"
        )
        self._thread.start()
 
    def stop(self) -> None:
        """Stop the background daemon thread."""
        self._running = False
        if self._thread:
            self._thread.join(timeout=2.0)
            self._thread = None

# Load policy file
policy = qPolicyFile("qcompute_policy.yaml")
policy.load()
 
# Build governance from policy
governance = TriadicGovernance.from_policy(policy)
 
# Build watcher
watcher = qPolicyWatcher(
    policy_file=policy,
    governance=governance,
    on_reload=lambda gov: print("[qDaemon] Policy hot-reloaded:", gov),
)
 
# Build daemon
daemon = qDaemon(watcher=watcher, interval=1.0)
daemon.start()
 
# Build router with watcher (daemon will update it)
router = TriadicRouter(
    governance=governance,
    policy_watcher=watcher,
)
 
# Build core
core = WrappedCore(
    backend=EchoBackend(),
    backend_name="echo-core",
    router=router,
)

# -----------------------------
# 28. qOrchestrator — multi-backend compute fabric
# -----------------------------
 
from dataclasses import dataclass, field
from typing import Any, Dict, Optional, Callable
 
class OrchestratorError(Exception):
    """Raised when orchestration cannot complete a request."""
    pass
 
 
@dataclass
class qOrchestrator:
    """
    Coordinates multiple cores, daemons, and sessions into a single RTT compute fabric.
 
    Core ideas:
    - Many backends (cores) under one roof
    - Optional default core for convenience
    - Optional governance daemon (hot policy reload)
    - Sessions that automatically know about all registered cores
    """
 
    cores: Dict[str, WrappedCore] = field(default_factory=dict)
    default_core: Optional[str] = None
 
    daemon: Optional[qDaemon] = None
    on_event: Optional[Callable[[str, Dict[str, Any]], None]] = None
 
    _active_session: Optional[qSession] = field(default=None, init=False, repr=False)
 
    # -----------------------------
    # Registration
    # -----------------------------
 
    def register_core(self, core: WrappedCore, *, make_default: bool = False) -> None:
        """Register a core by its backend_name."""
        if not core.backend_name:
            raise OrchestratorError("Core backend_name must be non-empty")
 
        self.cores[core.backend_name] = core
        if make_default or self.default_core is None:
            self.default_core = core.backend_name
 
        self._emit("core_registered", {"backend": core.backend_name})
 
        # If a session is active, ensure it can replay this backend too
        if self._active_session is not None:
            self._active_session.register_core(core)
 
    def get_core(self, backend_name: Optional[str] = None) -> WrappedCore:
        """Fetch a core by name, or default if not provided."""
        name = backend_name or self.default_core
        if not name or name not in self.cores:
            raise OrchestratorError(f"Unknown core backend '{name}'")
        return self.cores[name]
 
    # -----------------------------
    # Daemon lifecycle
    # -----------------------------
 
    def attach_daemon(self, daemon: qDaemon) -> None:
        """Attach (but do not start) a background daemon."""
        self.daemon = daemon
        self._emit("daemon_attached", {"interval": getattr(daemon, "interval", None)})
 
    def start_daemon(self) -> None:
        """Start the attached daemon."""
        if not self.daemon:
            raise OrchestratorError("No daemon attached")
        self.daemon.start()
        self._emit("daemon_started", {})
 
    def stop_daemon(self) -> None:
        """Stop the attached daemon."""
        if not self.daemon:
            return
        self.daemon.stop()
        self._emit("daemon_stopped", {})
 
    # -----------------------------
    # Sessions
    # -----------------------------
 
    def open_session(self, *, log_writer: Optional[qSessionLogWriter] = None) -> qSession:
        """
        Create and activate a session that is aware of all registered cores.
        The returned session is active (entered) immediately.
        """
        if self._active_session is not None:
            raise OrchestratorError("A session is already active")
 
        session = qSession()
        session.__enter__()
        self._active_session = session
 
        # Register all cores for replay
        for core in self.cores.values():
            session.register_core(core)
 
        # Attach optional writer (if your qSession has this method)
        if log_writer is not None:
            if not hasattr(session, "attach_log_writer"):
                raise OrchestratorError("qSession.attach_log_writer() not found; add log-writer integration first")
            session.attach_log_writer(log_writer)
 
        self._emit("session_opened", {"cores": list(self.cores.keys())})
        return session
 
    def close_session(self) -> None:
        """Close the active session, if any."""
        if self._active_session is None:
            return
        self._active_session.__exit__(None, None, None)
        self._emit("session_closed", {"trace_count": len(self._active_session.collector.traces)})
        self._active_session = None
 
    @property
    def session(self) -> Optional[qSession]:
        """Access the currently active session (if any)."""
        return self._active_session
 
    # -----------------------------
    # Compute entry points
    # -----------------------------
 
    def qcompute(
        self,
        payload: Any,
        *,
        backend: Optional[str] = None,
        frame: Optional[ResonanceFrame] = None,
        mode: str = TriadicMode.EXPLORE,
        record: bool = True,
        **kwargs: Any,
    ) -> ResonanceResult:
        """
        Run qCompute against a selected backend (or the default core).
 
        If a session is active and record=True, the result is recorded
        (and streamed to disk if a log writer is attached to the session).
        """
        core = self.get_core(backend)
        res = core.qcompute(payload, frame=frame, mode=mode, **kwargs)
 
        if record and self._active_session is not None:
            self._active_session.record(res)
 
        self._emit("qcompute", {"backend": core.backend_name, "mode": mode})
        return res
 
    def replay_all(self) -> list[ResonanceResult]:
        """Replay all traces in the active session."""
        if self._active_session is None:
            raise OrchestratorError("No active session to replay")
        self._emit("replay_all", {"trace_count": len(self._active_session.collector.traces)})
        return self._active_session.replay_all()
 
    def replay_last(self) -> ResonanceResult:
        """Replay the most recent trace in the active session."""
        if self._active_session is None:
            raise OrchestratorError("No active session to replay")
        self._emit("replay_last", {})
        return self._active_session.replay_last()
 
    # -----------------------------
    # Internal event hook
    # -----------------------------
 
    def _emit(self, event: str, data: Dict[str, Any]) -> None:
        if self.on_event:
            self.on_event(event, data)

def _demo_orchestrator_fabric():
    # Two backends/cores
    echo_core = WrappedCore(backend=EchoBackend(), backend_name="echo-core")
    echo_core_2 = WrappedCore(backend=EchoBackend(), backend_name="echo-core-2")
 
    # Policy + governance + watcher + daemon
    policy = qPolicyFile("qcompute_policy.yaml")
    policy.load()
    governance = TriadicGovernance.from_policy(policy)
 
    watcher = qPolicyWatcher(
        policy_file=policy,
        governance=governance,
        on_reload=lambda gov: print("[policy] reloaded"),
    )
 
    daemon = qDaemon(watcher=watcher, interval=1.0)
 
    # Router injection example (shared governance) — optional pattern:
    echo_core.router.governance = governance
    echo_core.router.policy_watcher = watcher
 
    echo_core_2.router.governance = governance
    echo_core_2.router.policy_watcher = watcher
 
    # Orchestrator
    fabric = qOrchestrator(on_event=lambda e, d: print(f"[fabric] {e}: {d}"))
    fabric.register_core(echo_core, make_default=True)
    fabric.register_core(echo_core_2)
    fabric.attach_daemon(daemon)
    fabric.start_daemon()
 
    # Open session with log writer
    writer = qSessionLogWriter(path="session.qtrace", include_header=True, include_footer=True)
 
    session = fabric.open_session(log_writer=writer)
 
    # Compute across backends
    frame = ResonanceFrame(
        label="fabric-demo",
        intent="multi-backend-test",
        context="docs/qCompute_with_RTT-Inside_Preview.md",
        consequence="prove-fabric-coordination",
    ).with_tag("token", "ALLOW_DEPLOY")  # if needed by policy
 
    r1 = fabric.qcompute({"amplitude": 0.42, "phase": "π/3"}, mode=TriadicMode.VERIFY, frame=frame)
    r2 = fabric.qcompute({"amplitude": 0.1, "phase": "π/6"}, backend="echo-core-2", mode=TriadicMode.EXPLORE, frame=frame)
 
    qPretty.print_result(r1)
    qPretty.print_result(r2)
 
    # Replay session
    fabric.replay_all()
 
    # Close down
    fabric.close_session()
    fabric.stop_daemon()

# -----------------------------
# Capability model
# -----------------------------
 
from dataclasses import dataclass, field
from typing import Set
 
@dataclass(frozen=True)
class Capabilities:
    """
    Declares what a backend can support.
    """
    features: Set[str]
 
    def satisfies(self, required: Set[str]) -> bool:
        return required.issubset(self.features)

"physical_qubits"
"logical_qubits"
"error_corrected"
"real_time_decoder"
"long_circuit"
"simulator"
"classical_fallback"
"gpu_accelerated"

@dataclass
class WrappedCore:
    backend: ComputeBackend
    backend_name: str
    router: TriadicRouter = field(default_factory=TriadicRouter)
    capabilities: Capabilities = field(
        default_factory=lambda: Capabilities(set())
    )
 
    def qcompute(self, payload, frame=None, mode=TriadicMode.EXPLORE, **kwargs):
        ...

ibm_core.capabilities = Capabilities({
    "physical_qubits",
    "logical_qubits",
    "error_corrected",
    "long_circuit"
})
 
google_core.capabilities = Capabilities({
    "physical_qubits",
    "logical_qubits",
    "real_time_decoder"
})
 
sim_core.capabilities = Capabilities({
    "simulator",
    "classical_fallback"
})

# -----------------------------
# Capability resolver
# -----------------------------
 
class CapabilityResolutionError(Exception):
    pass
 
 
def resolve_by_capability(
    cores: dict[str, WrappedCore],
    required: set[str],
) -> WrappedCore:
    """
    Select the first backend that satisfies all required capabilities.
    Deterministic ordering by backend_name.
    """
    candidates = [
        core for core in cores.values()
        if core.capabilities.satisfies(required)
    ]
 
    if not candidates:
        raise CapabilityResolutionError(
            f"No backend satisfies required capabilities: {sorted(required)}"
        )
 
    # Deterministic choice
    return sorted(candidates, key=lambda c: c.backend_name)[0]

def qcompute(
    self,
    payload,
    *,
    requires: Optional[set[str]] = None,
    backend: Optional[str] = None,
    frame: Optional[ResonanceFrame] = None,
    mode: str = TriadicMode.EXPLORE,
    record: bool = True,
    **kwargs,
):
    # Explicit backend wins
    if backend:
        core = self.get_core(backend)
 
    # Capability‑based resolution
    elif requires:
        core = resolve_by_capability(self.cores, requires)
 
    # Default fallback
    else:
        core = self.get_core()
 
    res = core.qcompute(payload, frame=frame, mode=mode, **kwargs)
 
    if record and self._active_session:
        self._active_session.record(res)
 
    self._emit("qcompute", {
        "backend": core.backend_name,
        "mode": mode,
        "requires": sorted(requires) if requires else None
    })
 
    return res

fabric.qcompute(
    payload=circuit,
    requires={"logical_qubits", "real_time_decoder"},
    mode=TriadicMode.VERIFY,
)

fabric.qcompute(
    payload=workload,
    requires={"error_corrected", "long_circuit"},
    mode=TriadicMode.DEPLOY,
)

fabric.qcompute(
    payload=idea,
    requires={"simulator"},
    mode=TriadicMode.EXPLORE,
)

# -----------------------------
# Capability scoring primitives
# -----------------------------
 
from dataclasses import dataclass, field
from typing import Dict, Optional, Set, Any, Callable
 
@dataclass(frozen=True)
class ScoreProfile:
    """
    Normalized meaning:
    - latency_ms: lower is better
    - cost_per_shot: lower is better
    - fidelity: higher is better (0..1)
    """
    latency_ms: Optional[float] = None
    cost_per_shot: Optional[float] = None
    fidelity: Optional[float] = None
 
    # Optional extra numeric signals (queue depth, uptime, error rate, etc.)
    extras: Dict[str, float] = field(default_factory=dict)
 
 
@dataclass(frozen=True)
class CapabilityConstraints:
    """
    Hard filters (eligibility gates), not optimization weights.
    """
    requires: Set[str] = field(default_factory=set)
 
    max_latency_ms: Optional[float] = None
    max_cost_per_shot: Optional[float] = None
    min_fidelity: Optional[float] = None
 
    min_extras: Dict[str, float] = field(default_factory=dict)
    max_extras: Dict[str, float] = field(default_factory=dict)