awp-python 0.1.0a1__py3-none-any.whl

awp/clock.py

@@ -0,0 +1,61 @@
+"""Clock synchronization over the heartbeat (AWP-CLK-007, AWP-CLK-008)."""
+
+from __future__ import annotations
+
+from collections import deque
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class ClockSample:
+    offset_ns: int
+    rtt_ns: int
+
+
+def sample(origin_ns: int, receive_ns: int, transmit_ns: int, destination_ns: int) -> ClockSample:
+    rtt = (destination_ns - origin_ns) - (transmit_ns - receive_ns)
+    offset = ((receive_ns - origin_ns) + (transmit_ns - destination_ns)) // 2
+    return ClockSample(offset_ns=offset, rtt_ns=max(rtt, 0))
+
+
+class ClockEstimator:
+    """Keeps the minimum-RTT sample of the most recent eight exchanges."""
+
+    WINDOW = 8
+
+    def __init__(self) -> None:
+        self._samples: deque[ClockSample] = deque(maxlen=self.WINDOW)
+
+    def add(self, s: ClockSample) -> None:
+        self._samples.append(s)
+
+    @property
+    def samples(self) -> int:
+        return len(self._samples)
+
+    @property
+    def best(self) -> ClockSample | None:
+        return min(self._samples, key=lambda s: s.rtt_ns) if self._samples else None
+
+    @property
+    def offset_ns(self) -> int | None:
+        best = self.best
+        return best.offset_ns if best else None
+
+    @property
+    def error_bound_ns(self) -> int | None:
+        best = self.best
+        return best.rtt_ns // 2 if best else None
+
+    def to_session(self, agent_ns: int) -> int:
+        """Map an agent-clock value to the session clock (AWP-CLK-009)."""
+        offset = self.offset_ns
+        if offset is None:
+            raise RuntimeError("no clock sample yet; complete a ping exchange first (AWP-CLK-008)")
+        return agent_ns + offset
+
+    def to_agent(self, session_ns: int) -> int:
+        offset = self.offset_ns
+        if offset is None:
+            raise RuntimeError("no clock sample yet")
+        return session_ns - offset

awp/errors.py

@@ -0,0 +1,112 @@
+"""AWP error codes (spec/loop/events-and-errors) and the exception that carries them."""
+
+from __future__ import annotations
+
+from enum import IntEnum
+from typing import Any
+
+
+class ErrorCode(IntEnum):
+    PARSE_ERROR = -32700
+    INVALID_REQUEST = -32600
+    METHOD_NOT_FOUND = -32601
+    INVALID_PARAMS = -32602
+    INTERNAL_ERROR = -32603
+
+    VERSION_UNSUPPORTED = 1001
+    MALFORMED = 1002
+    EMBODIMENT_UNAVAILABLE = 2001
+    TIME_MODEL_UNSUPPORTED = 2002
+    SESSION_EXPIRED = 2003
+    SESSION_EXISTS = 2004
+    SESSION_UNKNOWN = 2005
+    INTEGER_RANGE = 2006
+    CHANNEL_UNKNOWN = 2007
+    PARAMS_INVALID = 3001
+    BUSY = 3002
+    QUEUE_FULL = 3003
+    ACTION_ID_CONFLICT = 3004
+    ESTOP_ACTIVE = 3005
+    TICK_NOT_AUTHORIZED = 3006
+    STALE_INTENT = 3007
+    ACTION_UNKNOWN = 3008
+    TICK_MISMATCH = 3009
+    FORBIDDEN = 4001
+    ENVELOPE_EXCEEDED = 4002
+    APPROVAL_DENIED = 4003
+    APPROVAL_TIMEOUT = 4004
+
+    @property
+    def is_jsonrpc(self) -> bool:
+        return -32768 <= self.value <= -32000
+
+    @property
+    def wire_name(self) -> str:
+        if self.is_jsonrpc:
+            return _JSONRPC_MESSAGES[self]
+        return f"AWP_{self.name}"
+
+
+_JSONRPC_MESSAGES = {
+    ErrorCode.PARSE_ERROR: "Parse error",
+    ErrorCode.INVALID_REQUEST: "Invalid request",
+    ErrorCode.METHOD_NOT_FOUND: "Method not found",
+    ErrorCode.INVALID_PARAMS: "Invalid params",
+    ErrorCode.INTERNAL_ERROR: "Internal error",
+}
+
+# AWP_ENVELOPE_EXCEEDED is retryable only for rate limits; callers pass retryable explicitly.
+RETRYABLE = frozenset(
+    {
+        ErrorCode.EMBODIMENT_UNAVAILABLE,
+        ErrorCode.BUSY,
+        ErrorCode.QUEUE_FULL,
+        ErrorCode.ESTOP_ACTIVE,
+        ErrorCode.STALE_INTENT,
+        ErrorCode.APPROVAL_TIMEOUT,
+    }
+)
+
+
+class AwpError(Exception):
+    """A JSON-RPC error object with AWP data (AWP-ERR-001)."""
+
+    def __init__(
+        self,
+        code: int,
+        detail: str | None = None,
+        *,
+        retryable: bool | None = None,
+        message: str | None = None,
+        **data: Any,
+    ) -> None:
+        try:
+            known: ErrorCode | None = ErrorCode(code)
+        except ValueError:
+            known = None
+        self.code = code
+        self.message = message or (known.wire_name if known else f"AWP_{code}")
+        self.retryable = retryable if retryable is not None else known in RETRYABLE
+        self.detail = detail
+        self.data = data
+        super().__init__(f"{self.message} ({code})" + (f": {detail}" if detail else ""))
+
+    def to_dict(self) -> dict[str, Any]:
+        err: dict[str, Any] = {"code": self.code, "message": self.message}
+        if not (-32768 <= self.code <= -32000) or self.detail or self.data:
+            data: dict[str, Any] = {"retryable": self.retryable, **self.data}
+            if self.detail:
+                data["detail"] = self.detail
+            err["data"] = data
+        return err
+
+    @classmethod
+    def from_dict(cls, err: dict[str, Any]) -> AwpError:
+        data = dict(err.get("data") or {})
+        retryable = bool(data.pop("retryable", False))
+        detail = data.pop("detail", None)
+        return cls(err["code"], detail, retryable=retryable, message=err.get("message"), **data)
+
+
+class ProtocolError(Exception):
+    """The peer violated the protocol in a way the receiver cannot recover from."""

awp/frames.py

@@ -0,0 +1,174 @@
+"""The frame envelope (spec/transport/frames): binary codec and the inline JSON form."""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import struct
+from dataclasses import dataclass, field
+from typing import Any
+
+from .errors import AwpError, ErrorCode
+from .jsonrpc import MAX_SAFE_INT
+
+MAGIC = b"AWPF"
+VERSION = 1
+HEADER = struct.Struct("<4sBBHQQI")
+
+KEYFRAME = 0x01
+END_OF_BURST = 0x02
+HAS_EXTENSIONS = 0x04
+RESYNC = 0x08
+
+EXT_TICK = 0x01
+EXT_TS_SIM_NS = 0x02
+EXT_TS_SEND_NS = 0x03
+_REGISTERED_LEN = {EXT_TICK: 8, EXT_TS_SIM_NS: 8, EXT_TS_SEND_NS: 8}
+
+
+@dataclass(frozen=True, slots=True)
+class Frame:
+    channel_id: int
+    seq: int
+    ts_mono_ns: int
+    payload: bytes = b""
+    keyframe: bool = False
+    end_of_burst: bool = False
+    resync: bool = False
+    tick: int | None = None
+    ts_sim_ns: int | None = None
+    ts_send_ns: int | None = None
+    vendor: tuple[tuple[int, bytes], ...] = field(default=())
+
+    @property
+    def flags(self) -> int:
+        """Flag bits 0, 1, and 3; bit 2 is a property of the binary encoding only."""
+        return (
+            (KEYFRAME if self.keyframe else 0)
+            | (END_OF_BURST if self.end_of_burst else 0)
+            | (RESYNC if self.resync else 0)
+        )
+
+
+def _malformed(detail: str) -> AwpError:
+    return AwpError(ErrorCode.MALFORMED, detail)
+
+
+def _bounded(value: int, name: str, *, signed: bool = False) -> int:
+    if value > MAX_SAFE_INT or (signed and value < -MAX_SAFE_INT):
+        raise AwpError(ErrorCode.INTEGER_RANGE, f"{name} exceeds 2^53-1")
+    return value
+
+
+def decode(data: bytes) -> Frame:
+    """Decode a binary frame (AWP-DAT-001..009). Raises AwpError MALFORMED or INTEGER_RANGE."""
+    if len(data) < HEADER.size:
+        raise _malformed("frame shorter than 28-byte header")
+    magic, version, flags, channel_id, seq, ts, payload_len = HEADER.unpack_from(data)
+    if magic != MAGIC:
+        raise _malformed("bad magic")
+    if version != VERSION:
+        raise _malformed(f"unsupported version {version}")
+    ext: dict[str, int] = {}
+    vendor: list[tuple[int, bytes]] = []
+    offset = HEADER.size
+    if flags & HAS_EXTENSIONS:
+        if len(data) < offset + 2:
+            raise _malformed("missing ext_len")
+        (ext_len,) = struct.unpack_from("<H", data, offset)
+        offset += 2
+        end = offset + ext_len
+        if end > len(data):
+            raise _malformed("ext_len exceeds frame")
+        seen: set[int] = set()
+        while offset < end:
+            if offset + 2 > end:
+                raise _malformed("truncated TLV header")
+            kind, length = data[offset], data[offset + 1]
+            value = data[offset + 2 : offset + 2 + length]
+            if offset + 2 + length > end:
+                raise _malformed("TLV value exceeds ext_len")
+            if kind in seen:
+                raise _malformed(f"duplicate extension type {kind:#04x}")
+            seen.add(kind)
+            if kind in _REGISTERED_LEN and length != _REGISTERED_LEN[kind]:
+                raise _malformed(f"extension {kind:#04x} has len {length}")
+            if kind == EXT_TICK:
+                ext["tick"] = _bounded(int.from_bytes(value, "little"), "tick")
+            elif kind == EXT_TS_SIM_NS:
+                ext["ts_sim_ns"] = _bounded(
+                    int.from_bytes(value, "little", signed=True), "ts_sim_ns", signed=True
+                )
+            elif kind == EXT_TS_SEND_NS:
+                ext["ts_send_ns"] = _bounded(int.from_bytes(value, "little"), "ts_send_ns")
+            elif kind >= 0x80:
+                vendor.append((kind, bytes(value)))
+            offset += 2 + length
+    if offset + payload_len != len(data):
+        raise _malformed(f"frame length {len(data)} != {offset} + payload_len {payload_len}")
+    return Frame(
+        channel_id=channel_id,
+        seq=_bounded(seq, "seq"),
+        ts_mono_ns=_bounded(ts, "ts_mono_ns"),
+        payload=bytes(data[offset:]),
+        keyframe=bool(flags & KEYFRAME),
+        end_of_burst=bool(flags & END_OF_BURST),
+        resync=bool(flags & RESYNC),
+        vendor=tuple(vendor),
+        **ext,
+    )
+
+
+def encode(frame: Frame) -> bytes:
+    entries = bytearray()
+    for kind, value, fmt in (
+        (EXT_TICK, frame.tick, "<Q"),
+        (EXT_TS_SIM_NS, frame.ts_sim_ns, "<q"),
+        (EXT_TS_SEND_NS, frame.ts_send_ns, "<Q"),
+    ):
+        if value is not None:
+            entries += bytes((kind, 8)) + struct.pack(fmt, value)
+    for kind, raw in frame.vendor:
+        entries += bytes((kind, len(raw))) + raw
+    flags = frame.flags | (HAS_EXTENSIONS if entries else 0)
+    header = HEADER.pack(
+        MAGIC, VERSION, flags, frame.channel_id, frame.seq, frame.ts_mono_ns, len(frame.payload)
+    )
+    ext = struct.pack("<H", len(entries)) + entries if entries else b""
+    return header + ext + frame.payload
+
+
+def to_inline(frame: Frame) -> dict[str, Any]:
+    """params of an obs.frame / cmd.frame notification (AWP-DAT-004)."""
+    params: dict[str, Any] = {
+        "channel_id": frame.channel_id,
+        "seq": frame.seq,
+        "ts_mono_ns": frame.ts_mono_ns,
+        "flags": frame.flags,
+    }
+    for name in ("tick", "ts_sim_ns", "ts_send_ns"):
+        value = getattr(frame, name)
+        if value is not None:
+            params[name] = value
+    params["payload_b64"] = base64.b64encode(frame.payload).decode("ascii")
+    return params
+
+
+def from_inline(params: dict[str, Any]) -> Frame:
+    try:
+        payload = base64.b64decode(params["payload_b64"], validate=True)
+        flags = int(params["flags"])
+        return Frame(
+            channel_id=int(params["channel_id"]),
+            seq=int(params["seq"]),
+            ts_mono_ns=int(params["ts_mono_ns"]),
+            payload=payload,
+            keyframe=bool(flags & KEYFRAME),
+            end_of_burst=bool(flags & END_OF_BURST),
+            resync=bool(flags & RESYNC),
+            tick=params.get("tick"),
+            ts_sim_ns=params.get("ts_sim_ns"),
+            ts_send_ns=params.get("ts_send_ns"),
+        )
+    except (KeyError, TypeError, ValueError, binascii.Error) as exc:
+        raise _malformed(f"invalid inline frame: {exc}") from None

awp/jsonrpc.py

@@ -0,0 +1,84 @@
+"""JSON-RPC 2.0 framing for the control channel (AWP-CTL-001..009)."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from .errors import AwpError, ErrorCode
+
+MAX_SAFE_INT = 2**53 - 1
+
+Message = dict[str, Any]
+
+
+def request(id: int | str, method: str, params: dict[str, Any] | None = None) -> Message:
+    msg: Message = {"jsonrpc": "2.0", "id": id, "method": method}
+    if params is not None:
+        msg["params"] = params
+    return msg
+
+
+def notification(method: str, params: dict[str, Any]) -> Message:
+    return {"jsonrpc": "2.0", "method": method, "params": params}
+
+
+def result(id: int | str | None, value: dict[str, Any]) -> Message:
+    return {"jsonrpc": "2.0", "id": id, "result": value}
+
+
+def error(id: int | str | None, err: AwpError) -> Message:
+    return {"jsonrpc": "2.0", "id": id, "error": err.to_dict()}
+
+
+def is_request(msg: Message) -> bool:
+    return "method" in msg and "id" in msg
+
+
+def is_notification(msg: Message) -> bool:
+    return "method" in msg and "id" not in msg
+
+
+def is_response(msg: Message) -> bool:
+    return "method" not in msg and ("result" in msg or "error" in msg)
+
+
+def encode(msg: Message) -> str:
+    return json.dumps(msg, separators=(",", ":"), ensure_ascii=False, allow_nan=False)
+
+
+def decode(text: str | bytes) -> Message:
+    """Parse one control-channel message; raise AwpError for anything a receiver must reject."""
+    try:
+        msg = json.loads(text, parse_constant=_reject_constant)
+    except (ValueError, UnicodeDecodeError) as exc:
+        raise AwpError(ErrorCode.PARSE_ERROR, str(exc)) from None
+    if isinstance(msg, list):
+        raise AwpError(ErrorCode.INVALID_REQUEST, "batch requests are not permitted (AWP-CTL-006)")
+    if not isinstance(msg, dict) or msg.get("jsonrpc") != "2.0":
+        raise AwpError(ErrorCode.INVALID_REQUEST, "not a JSON-RPC 2.0 object")
+    if not (is_request(msg) or is_notification(msg) or is_response(msg)):
+        raise AwpError(ErrorCode.INVALID_REQUEST, "neither request, notification, nor response")
+    if "method" in msg and not isinstance(msg["method"], str):
+        raise AwpError(ErrorCode.INVALID_REQUEST, "method must be a string")
+    check_integer_range(msg)
+    return msg
+
+
+def check_integer_range(value: Any) -> None:
+    """AWP-CTL-009: JSON integers beyond ±(2^53 - 1) close the session."""
+    if isinstance(value, bool):
+        return
+    if isinstance(value, int):
+        if not -MAX_SAFE_INT <= value <= MAX_SAFE_INT:
+            raise AwpError(ErrorCode.INTEGER_RANGE, f"integer {value} exceeds 2^53-1")
+    elif isinstance(value, dict):
+        for v in value.values():
+            check_integer_range(v)
+    elif isinstance(value, list):
+        for v in value:
+            check_integer_range(v)
+
+
+def _reject_constant(name: str) -> Any:
+    raise ValueError(f"{name} is not valid JSON")

awp/lifecycle.py

@@ -0,0 +1,78 @@
+"""The normative action lifecycle, loaded from the spec's transition table (AWP-LIF-001)."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from enum import StrEnum
+from importlib.resources import files
+from typing import Any
+
+
+class ActionState(StrEnum):
+    SUBMITTED = "submitted"
+    PENDING_APPROVAL = "pending_approval"
+    QUEUED = "queued"
+    ACCEPTED = "accepted"
+    EXECUTING = "executing"
+    CANCELLING = "cancelling"
+    REJECTED = "rejected"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    PREEMPTED = "preempted"
+    CANCELLED = "cancelled"
+
+    @property
+    def terminal(self) -> bool:
+        return _CLASSES[self] == "terminal"
+
+    @property
+    def pre_execution(self) -> bool:
+        return _CLASSES[self] == "pre-execution"
+
+
+@dataclass(frozen=True, slots=True)
+class Transition:
+    source: ActionState
+    target: ActionState
+    reasons: frozenset[str] | None
+    via_error: bool
+
+
+_TABLE = json.loads((files("awp") / "_spec" / "lifecycle.json").read_text())
+_CLASSES: dict[ActionState, str] = {ActionState(s): c for s, c in _TABLE["states"].items()}
+TRANSITIONS: dict[tuple[ActionState, ActionState], Transition] = {
+    (ActionState(t["from"]), ActionState(t["to"])): Transition(
+        ActionState(t["from"]),
+        ActionState(t["to"]),
+        frozenset(t["reasons"]) if "reasons" in t else None,
+        t.get("wire") == "error",
+    )
+    for t in _TABLE["transitions"]
+}
+
+
+def permitted(source: ActionState, target: ActionState, reason: str | None = None) -> bool:
+    """Whether a status notification may move an action from `source` to `target`."""
+    t = TRANSITIONS.get((source, target))
+    if t is None or t.via_error:
+        return False
+    if reason is None or t.reasons is None or reason.startswith("x-"):
+        return True
+    return reason in t.reasons
+
+
+SUBMIT_FIELDS = (
+    "type",
+    "params",
+    "embodiment_id",
+    "preempt",
+    "deadline_ms",
+    "basis_ts_mono_ns",
+    "valid_until_ns",
+)
+
+
+def same_submission(a: dict[str, Any], b: dict[str, Any]) -> bool:
+    """AWP-ACT-009: absent never equals present; x- fields are not compared."""
+    return all((f in a) == (f in b) and a.get(f) == b.get(f) for f in SUBMIT_FIELDS)

awp/schema.py

@@ -0,0 +1,158 @@
+"""Validation against the canonical schemas bundled from the pinned spec.
+
+The canonical schemas are receiver schemas: they accept unknown fields (AWP-VER-003). The sender
+form applies the `x-awp-closed` and `x-awp-lint` annotations, exactly as the spec's CI does.
+"""
+
+from __future__ import annotations
+
+import json
+from functools import cache
+from importlib.resources import files
+from typing import Any
+
+from jsonschema import Draft202012Validator
+from referencing import Registry, Resource
+from referencing.jsonschema import DRAFT202012
+
+from .errors import AwpError, ErrorCode
+
+BASE = "https://agentworldprotocol.com/schemas/v0.1/"
+VENDOR_FIELD = r"^x-[a-z0-9]+\."
+_META = "https://json-schema.org/draft/2020-12/schema"
+
+
+def _load() -> dict[str, dict[str, Any]]:
+    root = files("awp") / "_spec" / "schemas"
+    out: dict[str, dict[str, Any]] = {}
+
+    def walk(node: Any, prefix: str) -> None:
+        for child in node.iterdir():
+            if child.is_dir():
+                walk(child, f"{prefix}{child.name}/")
+            elif child.name.endswith(".schema.json"):
+                out[prefix + child.name.removesuffix(".schema.json")] = json.loads(
+                    child.read_text()
+                )
+
+    walk(root, "")
+    return out
+
+
+SCHEMAS = _load()
+
+# Method → schema of its params, result, and notification params, as the spec's validator maps them.
+METHODS: dict[str, dict[str, str]] = {
+    "initialize": {"params": "agent-manifest", "result": "world-manifest"},
+    "world.manifest": {"params": "empty-result", "result": "world-manifest"},
+    "ping": {"params": "ping", "result": "ping-result"},
+    "session.open": {"params": "session-open", "result": "session-ready"},
+    "session.resume": {"params": "session-resume", "result": "session-ready"},
+    "session.close": {"params": "empty-result", "result": "empty-result"},
+    "session.transfer": {"params": "session-transfer", "result": "session-transfer-result"},
+    "session.state": {"notification": "session-state"},
+    "session.telemetry": {"notification": "session-telemetry"},
+    "task.update": {"params": "task-update", "result": "empty-result"},
+    "obs.subscribe": {"params": "subscribe", "result": "subscribe-result"},
+    "obs.unsubscribe": {"params": "unsubscribe", "result": "subscribe-result"},
+    "obs.frame": {"notification": "frame-inline"},
+    "obs.report": {"notification": "obs-report"},
+    "cmd.frame": {"notification": "frame-inline"},
+    "action.submit": {"params": "action-submit", "result": "action-submit-result"},
+    "action.cancel": {"params": "action-ref", "result": "action-cancel-result"},
+    "action.status": {
+        "params": "action-ref",
+        "result": "action-status",
+        "notification": "action-status",
+    },
+    "world.tick": {"params": "tick", "result": "tick-result"},
+    "world.snapshot": {"params": "empty-result", "result": "snapshot-result"},
+    "world.restore": {"params": "restore", "result": "reset-result"},
+    "world.reset": {"params": "reset", "result": "reset-result"},
+    "world.event": {"notification": "world-event"},
+    "safety.approval_requested": {"notification": "approval-requested"},
+    "safety.approval.respond": {"params": "approval-respond", "result": "empty-result"},
+}
+
+
+def schema_for(method: str, part: str) -> str | None:
+    """The schema name for `part` ("params", "result", or "notification") of `method`."""
+    return METHODS.get(method, {}).get(part)
+
+
+def lint(node: Any) -> Any:
+    """The sender form of a canonical schema."""
+    if isinstance(node, list):
+        return [lint(v) for v in node]
+    if not isinstance(node, dict):
+        return node
+    out = {k: lint(v) for k, v in node.items() if k not in ("x-awp-closed", "x-awp-lint")}
+    if "x-awp-lint" in node:
+        out.update(lint(node["x-awp-lint"]))
+    if node.get("x-awp-closed") is True:
+        out["additionalProperties"] = False
+        out["patternProperties"] = {VENDOR_FIELD: {}, **out.get("patternProperties", {})}
+    return out
+
+
+@cache
+def _registry(sender: bool) -> Registry:
+    resources = [
+        (
+            s["$id"],
+            Resource.from_contents(lint(s) if sender else s, default_specification=DRAFT202012),
+        )
+        for s in SCHEMAS.values()
+    ]
+    return Registry().with_resources(resources)
+
+
+@cache
+def validator(name: str, *, sender: bool = False) -> Draft202012Validator:
+    """Validator for `name` (e.g. "action-submit" or "safety-policy#/$defs/envelope")."""
+    file, _, fragment = name.partition("#")
+    if file not in SCHEMAS:
+        raise KeyError(f"no schema {file!r}")
+    ref = BASE + file + ".schema.json" + (f"#{fragment}" if fragment else "")
+    return Draft202012Validator({"$ref": ref}, registry=_registry(sender))
+
+
+def errors(name: str, instance: Any, *, sender: bool = False) -> list[str]:
+    return [
+        f"{'/'.join(map(str, e.absolute_path)) or '<root>'}: {e.message}"
+        for e in validator(name, sender=sender).iter_errors(instance)
+    ]
+
+
+def check(name: str, instance: Any, *, sender: bool = False) -> None:
+    """Raise AwpError(MALFORMED) if `instance` does not validate."""
+    problems = errors(name, instance, sender=sender)
+    if problems:
+        raise AwpError(ErrorCode.MALFORMED, f"{name}: " + "; ".join(problems[:3]))
+
+
+class ParamsValidator:
+    """Validates action params against a manifest's params_schema (AWP-ACT-002, AWP-MAN-002).
+
+    Local `$ref`s resolve against the manifest's own `$defs`; shared primitives against the
+    published common schema.
+    """
+
+    _URI = "urn:awp:manifest"
+
+    def __init__(self, manifest: dict[str, Any]) -> None:
+        doc = {**manifest, "$schema": _META}
+        registry = _registry(False).with_resource(
+            self._URI, Resource.from_contents(doc, default_specification=DRAFT202012)
+        )
+        self._validators: dict[str, Draft202012Validator] = {}
+        for i, decl in enumerate(manifest["action_schemas"]):
+            Draft202012Validator.check_schema(decl["params_schema"])
+            ref = f"{self._URI}#/action_schemas/{i}/params_schema"
+            self._validators[decl["type"]] = Draft202012Validator({"$ref": ref}, registry=registry)
+
+    def errors(self, action_type: str, params: Any) -> list[str]:
+        return [
+            f"{'/'.join(map(str, e.absolute_path)) or '<root>'}: {e.message}"
+            for e in self._validators[action_type].iter_errors(params)
+        ]