Skip to content

"Vibe-Trading: Your Personal Trading Agent"

24.2 KB
Raw Blame
"""pt-v1.1 / pt-v1.2 wire contract for ``paper_trade_step`` (shapes + vocabularies).

Declares the in-param, out-param and error-envelope shapes frozen by
``PAPER_TRADING_ENGINE_AMENDMENT_PT_V1.1.md`` §2 (the FROZEN summary), plus
the AM-14 closed vocabularies.  pt-v1.1 is APPROVED — G1 opened by the RM
written approval of 2026-10-19 (``PAPER_TRADING_ENGINE_APPROVAL_GRANTED_PT_V1.1.md``).
Every contract-sensitive value here is FROZEN per the approval §5
declaration: vocabulary or field-set changes are a major schema bump with
RM written confirmation; additive fields are a minor bump (REQUIREMENTS §9).

pt-v1.2 is the ADDITIVE bump for the cn_a 5m post-close step (P0 plan T2,
decision record D1-D8).  It adds four OPTIONAL request fields — ``interval``,
``session``, ``path_model``, ``fill_model`` — whose defaults reproduce the
pt-v1.1 semantics exactly, and three out-param additions —
``engine_fingerprint``, ``canceled_orders``, ``events`` — emitted ONLY for a
v1.2 call.  "v1.2 call" means at least one new request field is non-default
(D8): every call that omits them stays byte-identical to pt-v1.1, including
``received_state_hash`` (D4).  The pt-v1.1 vocabularies (``REASON_CODES``,
``SKIPPED_DAY_REASONS``, ``ERROR_CODES``) are NOT extended; the emergency
cancel token lives only inside ``canceled_orders`` (D2).

Companion artifacts:

* ``schema/tool_contracts/paper_trade_step-v1.1.json`` — frozen v1.1 out-param
  + error-envelope jsonschema (VD-13), loaded by :func:`load_contract_schema`.
* ``schema/tool_contracts/paper_trade_step-v1.2.json`` — the additive v1.2
  copy (same loader, ``version="pt-v1.2"``).
* ``state_hash.py`` — ``received_state_hash`` / ``effective_fee_model`` /
  ``engine_fingerprint``.
* ``wire.py`` — success/error payload builders + deterministic JSON
  serialization (Step 5 split: this module stays shapes + boundary parsing).

``jsonschema`` is deliberately NOT imported: it is not a declared runtime
dependency (zero-new-dependency red line, REQUIREMENTS §9), so
:func:`validate_payload` implements the small keyword subset the skeleton
uses.  The JSON file stays a standard draft-2020-12 document, so RM (or a
future declared dependency) can validate it with the real library.

Out-param dataclasses are declarative wire shapes: the engine (Steps 3-5)
assembles them and owns Decimal→JSON serialization (VD-9).  In-params are
parsed at the boundary by :func:`parse_request` (parse, don't validate —
downstream code receives typed values).
"""

from __future__ import annotations

import json
import math
import re
from dataclasses import dataclass, field
from pathlib import Path
from typing import Any

__all__ = [
    "CANCELED_REASON_CODE",
    "DEFAULT_FILL_MODEL",
    "DEFAULT_INTERVAL",
    "DEFAULT_PATH_MODEL",
    "DEFAULT_SESSION",
    "ERROR_CODES",
    "FILL_MODELS",
    "INTERVALS",
    "MARKETS",
    "PATH_MODELS",
    "REASON_CODES",
    "SCHEMA_VERSIONS",
    "SCHEMA_VERSION",
    "SCHEMA_VERSION_V1_2",
    "SESSION_EVENT_TYPES",
    "SESSIONS",
    "SIDES",
    "SKIPPED_DAY_REASONS",
    "TOOL_NAME",
    "AccountState",
    "CanceledOrder",
    "ErrorEnvelope",
    "Fill",
    "NavPoint",
    "Order",
    "PaperTradeSchemaError",
    "PaperTradeStepRequest",
    "PaperTradeStepResult",
    "Position",
    "RejectedOrder",
    "SessionEvent",
    "SkippedDay",
    "load_contract_schema",
    "parse_account_state",
    "parse_request",
    "validate_payload",
]

#: Wire contract version — FROZEN: pt-v1.1 is the first frozen implementation
#: version (G1 approved 2026-10-19; AMENDMENT header version-semantics ruling).
#: It stays the DEFAULT version emitted: a call that uses no pt-v1.2 field is
#: a pt-v1.1 document, byte-identical to the frozen output (D8).
#: Constant convention: backtest_summary.py:31, market_data_tool.py:71.
SCHEMA_VERSION = "pt-v1.1"

#: Additive bump version (P0 5m plan T2): emitted when at least one new
#: request field is non-default.
SCHEMA_VERSION_V1_2 = "pt-v1.2"

#: Every version this loader can resolve, oldest first.
SCHEMA_VERSIONS: tuple[str, ...] = (SCHEMA_VERSION, SCHEMA_VERSION_V1_2)

# ── pt-v1.2 additive request vocabularies (D1/D5/D8) ──
#
# Defaults are the pt-v1.1 semantics: omitting all four fields selects the
# frozen daily close-price path and leaves the wire document untouched.
#: ``interval`` — 1d keeps the frozen pt-v1.1 path; 5m is cn_a-only (D5).
INTERVALS: tuple[str, ...] = ("1d", "5m")
DEFAULT_INTERVAL = "1d"

#: ``session`` — ``auto`` resolves to cn_a for market=cn_a and is inert for
#: hk/us; ``cn_a`` with a non-cn_a market is an INVALID_REQUEST gate (D5).
SESSIONS: tuple[str, ...] = ("auto", "cn_a")
DEFAULT_SESSION = "auto"

#: ``path_model`` — how the reference price is derived from the matched bar
#: (D1). Ignored for interval=1d (which keeps the pt-v1.1 close path).
PATH_MODELS: tuple[str, ...] = ("bar_median", "bar_close")
DEFAULT_PATH_MODEL = "bar_median"

#: ``fill_model`` — the only P0 value: all-or-nothing, no partial fills.
FILL_MODELS: tuple[str, ...] = ("all_or_none",)
DEFAULT_FILL_MODEL = "all_or_none"

#: ``events[].event_type`` — pt-v1.2 session facts (T4, D2). Not an AM-14
#: vocabulary and not part of any frozen pt-v1.1 table.
SESSION_EVENT_TYPES: tuple[str, ...] = (
    "non_trading_day",
    "halted",
    "price_limit",
    "auction_window",
)

#: ``canceled_orders[].reason_code`` — the single T3 emergency-cancel token
#: (D2). Deliberately NOT a member of ``REASON_CODES``, which stays frozen.
CANCELED_REASON_CODE = "canceled_after_failed_match"

#: Bare MCP tool name (RM observer whitelists bare + ``vibe-trading_`` prefix).
TOOL_NAME = "paper_trade_step"

# FROZEN (G1 approved 2026-10-19): the three vocabularies below are the AM-14
# closed tables (11 reason_code + 2 skipped reason + 2 error code).  Any
# add/remove/change = major schema bump with RM written confirmation
# (REQUIREMENTS §9 / APPROVAL §5 frozen-surface declaration).
#: ``rejected_orders[].reason_code`` — closed vocabulary, 11 values (AM-14).
REASON_CODES: tuple[str, ...] = (
    "insufficient_cash",
    "insufficient_position",
    "t_plus_1",
    "limit_up",
    "limit_down",
    "suspended",
    "lot_size",
    "non_trading_day",
    "unknown_symbol",
    "corporate_action_unresolved",  # AM-2
    "limit_not_marketable",  # AM-7
)

#: ``skipped_days[].reason`` — closed vocabulary, 2 values (AM-14).
SKIPPED_DAY_REASONS: tuple[str, ...] = (
    "non_trading_day",  # cn_a only — CH trade_calendar truth (AM-6)
    "market_closed_inferred",  # hk/us only — bar-inferred, always + warning (AM-6)
)

#: In-band error envelope ``code`` — closed vocabulary, 2 values (AM-5/AM-14).
#: Transport-level MCP errors are reserved for engine-internal faults only.
ERROR_CODES: tuple[str, ...] = (
    "PAPER_DATA_NOT_READY",  # retryable — RM 30min × 3
    "INVALID_REQUEST",  # non-retryable — input contract violation
)

# FROZEN (G1 approved 2026-10-19): market/side enums per REQUIREMENTS §2.1
# (pt-v1.0 dispatched values, carried into pt-v1.1 unchanged).
MARKETS: tuple[str, ...] = ("cn_a", "hk", "us")
SIDES: tuple[str, ...] = ("buy", "sell")

_DATE_RE = re.compile(r"^\d{4}-\d{2}-\d{2}$")

#: Contract jsonschemas ship INSIDE the package (``tools/paper_trade/*.json`` is
#: declared package-data) so an installed wheel or sdist resolves them without
#: the repository root.  ``schema/tool_contracts/`` keeps the published mirror;
#: a test pins the two copies byte-identical.
_CONTRACT_SCHEMA_DIR = Path(__file__).resolve().parent
_CONTRACT_SCHEMA_PATHS: dict[str, Path] = {
    SCHEMA_VERSION: _CONTRACT_SCHEMA_DIR / "paper_trade_step-v1.1.json",
    SCHEMA_VERSION_V1_2: _CONTRACT_SCHEMA_DIR / "paper_trade_step-v1.2.json",
}


class PaperTradeSchemaError(ValueError):
    """Raised when a tool input violates the pt-v1.1 in-param contract.

    Step 6 (tool.py) maps this to the in-band ``INVALID_REQUEST`` envelope
    (AM-5); messages are deterministic English (VD-7).
    """


# ── In-params (REQUIREMENTS §2.1 + AM-3/AM-4 revisions) ──


@dataclass(frozen=True, slots=True)
class Position:
    """One holding inside ``account_state`` / ``end_state``."""

    symbol: str
    qty: float
    avg_cost: float


@dataclass(frozen=True, slots=True)
class AccountState:
    """RM-injected ledger snapshot.  The engine trusts but echoes its hash (R7)."""

    cash: float
    positions: tuple[Position, ...] = ()


@dataclass(frozen=True, slots=True)
class Order:
    """One order of the ``orders`` array (single-day mode only, AM-3)."""

    symbol: str
    side: str
    qty: float
    limit: float | None = None


@dataclass(frozen=True, slots=True)
class PaperTradeStepRequest:
    """Parsed ``paper_trade_step`` in-params.

    ``orders`` XOR ``strategy_path`` and the orders-mode single-day rule
    (AM-3) are SEMANTIC gates owned by tool.py (Step 6, INVALID_REQUEST);
    this shape parser does not pre-empt them.
    """

    account_id: str
    market: str
    account_state: AccountState
    from_date: str
    to_date: str
    orders: tuple[Order, ...] | None = None
    strategy_path: str | None = None
    # FROZEN (AM-4-3, G1 approved): RM dispatch always injects fee_model
    # explicitly (required-at-dispatch) while the field stays schema-optional
    # for backward compatibility (AMENDMENT §2.3).
    fee_model: dict[str, float] = field(default_factory=dict)
    # pt-v1.2 additive fields (D8): defaults ARE the pt-v1.1 semantics, so an
    # absent field is indistinguishable from the default value everywhere.
    interval: str = DEFAULT_INTERVAL
    session: str = DEFAULT_SESSION
    path_model: str = DEFAULT_PATH_MODEL
    fill_model: str = DEFAULT_FILL_MODEL

    @property
    def uses_v1_2(self) -> bool:
        """Whether this call selects the additive pt-v1.2 surface (D8).

        True iff at least one new request field is non-default.  A False
        request must keep the pt-v1.1 byte-identical output and hash (D4).
        """
        return (
            self.interval != DEFAULT_INTERVAL
            or self.session != DEFAULT_SESSION
            or self.path_model != DEFAULT_PATH_MODEL
            or self.fill_model != DEFAULT_FILL_MODEL
        )

    @property
    def schema_version(self) -> str:
        """The wire ``schema_version`` this request's result must carry."""
        return SCHEMA_VERSION_V1_2 if self.uses_v1_2 else SCHEMA_VERSION


def _require_number(value: Any, path: str) -> float:
    if isinstance(value, bool) or not isinstance(value, (int, float)):
        raise PaperTradeSchemaError(f"{path} must be a JSON number, got {type(value).__name__}")
    try:
        numeric = float(value)
    except OverflowError:
        # An integer literal beyond the double range is not a finite JSON
        # number for wire purposes (JCS interpretation stays within ±2^53
        # across implementations, state_hash.py module docstring).
        numeric = math.inf if value > 0 else -math.inf
    if not math.isfinite(numeric):
        raise PaperTradeSchemaError(f"{path} must be a finite JSON number, got {value!r}")
    return numeric


def _require_str(value: Any, path: str) -> str:
    if not isinstance(value, str):
        raise PaperTradeSchemaError(f"{path} must be a string, got {type(value).__name__}")
    return value


def _parse_date(value: Any, path: str) -> str:
    text = _require_str(value, path)
    if not _DATE_RE.match(text):
        raise PaperTradeSchemaError(f"{path} must be YYYY-MM-DD, got {text!r}")
    return text


def _parse_choice(value: Any, path: str, allowed: tuple[str, ...], default: str) -> str:
    """Parse one pt-v1.2 optional enum: absent/null → default, else closed check.

    ``None`` is the "field not supplied" spelling (JSON null and a missing key
    are the same intent for an optional field); a PRESENT non-string or an
    out-of-vocabulary string is a contract violation, never silently defaulted.
    """
    if value is None:
        return default
    text = _require_str(value, path)
    if text not in allowed:
        raise PaperTradeSchemaError(f"{path} must be one of {allowed}, got {text!r}")
    return text


def _parse_position(raw: Any, path: str) -> Position:
    if not isinstance(raw, dict):
        raise PaperTradeSchemaError(f"{path} must be an object, got {type(raw).__name__}")
    return Position(
        symbol=_require_str(raw.get("symbol"), f"{path}.symbol"),
        qty=_require_number(raw.get("qty"), f"{path}.qty"),
        avg_cost=_require_number(raw.get("avg_cost"), f"{path}.avg_cost"),
    )


def parse_account_state(raw: Any, path: str = "account_state") -> AccountState:
    """Parse ``account_state`` alone (public: the AM-4-4 error-path hash in
    ``wire.py`` gates on state parseability without a full request parse)."""
    if not isinstance(raw, dict):
        raise PaperTradeSchemaError(f"{path} must be an object, got {type(raw).__name__}")
    positions_raw = raw.get("positions", [])
    if not isinstance(positions_raw, list):
        raise PaperTradeSchemaError(f"{path}.positions must be an array")
    return AccountState(
        cash=_require_number(raw.get("cash"), f"{path}.cash"),
        positions=tuple(
            _parse_position(item, f"{path}.positions[{i}]") for i, item in enumerate(positions_raw)
        ),
    )


def _parse_order(raw: Any, path: str) -> Order:
    if not isinstance(raw, dict):
        raise PaperTradeSchemaError(f"{path} must be an object, got {type(raw).__name__}")
    side = _require_str(raw.get("side"), f"{path}.side")
    if side not in SIDES:
        raise PaperTradeSchemaError(f"{path}.side must be one of {SIDES}, got {side!r}")
    limit_raw = raw.get("limit")
    limit = None if limit_raw is None else _require_number(limit_raw, f"{path}.limit")
    return Order(
        symbol=_require_str(raw.get("symbol"), f"{path}.symbol"),
        side=side,
        qty=_require_number(raw.get("qty"), f"{path}.qty"),
        limit=limit,
    )


def parse_request(payload: dict[str, Any]) -> PaperTradeStepRequest:
    """Parse JSON-parsed tool input into the typed request contract.

    Shape-level boundary parse only: types, enums, date format.  Raises
    :class:`PaperTradeSchemaError` with a deterministic message naming the
    offending path.
    """
    if not isinstance(payload, dict):
        raise PaperTradeSchemaError(f"request must be an object, got {type(payload).__name__}")
    market = _require_str(payload.get("market"), "market")
    if market not in MARKETS:
        raise PaperTradeSchemaError(f"market must be one of {MARKETS}, got {market!r}")

    orders_raw = payload.get("orders")
    orders: tuple[Order, ...] | None = None
    if orders_raw is not None:
        if not isinstance(orders_raw, list):
            raise PaperTradeSchemaError("orders must be an array")
        orders = tuple(_parse_order(item, f"orders[{i}]") for i, item in enumerate(orders_raw))

    strategy_path = payload.get("strategy_path")
    if strategy_path is not None:
        strategy_path = _require_str(strategy_path, "strategy_path")

    # Only a missing or explicit null fee_model defaults to {} (AM-4-3 keeps
    # the field schema-optional); a PRESENT falsy non-dict ([] / "" / false /
    # 0) is a contract violation, not an absence — `or {}` would launder it.
    fee_model_raw = payload.get("fee_model")
    if fee_model_raw is None:
        fee_model_raw = {}
    if not isinstance(fee_model_raw, dict):
        raise PaperTradeSchemaError(
            f"fee_model must be an object, got {type(fee_model_raw).__name__}"
        )
    fee_model = {
        _require_str(key, "fee_model key"): _require_number(value, f"fee_model.{key}")
        for key, value in fee_model_raw.items()
    }

    return PaperTradeStepRequest(
        account_id=_require_str(payload.get("account_id"), "account_id"),
        market=market,
        account_state=parse_account_state(payload.get("account_state"), "account_state"),
        from_date=_parse_date(payload.get("from_date"), "from_date"),
        to_date=_parse_date(payload.get("to_date"), "to_date"),
        orders=orders,
        strategy_path=strategy_path,
        fee_model=fee_model,
        interval=_parse_choice(payload.get("interval"), "interval", INTERVALS, DEFAULT_INTERVAL),
        session=_parse_choice(payload.get("session"), "session", SESSIONS, DEFAULT_SESSION),
        path_model=_parse_choice(
            payload.get("path_model"), "path_model", PATH_MODELS, DEFAULT_PATH_MODEL
        ),
        fill_model=_parse_choice(
            payload.get("fill_model"), "fill_model", FILL_MODELS, DEFAULT_FILL_MODEL
        ),
    )


# ── Out-params (AMENDMENT §2.2) — declarative wire shapes ──


@dataclass(frozen=True, slots=True)
class DateRange:
    """``range`` — the closed [from, to] interval actually processed."""

    from_: str
    to: str


@dataclass(frozen=True, slots=True)
class Fill:
    """One executed fill.  ``reason`` dual-mode semantics FROZEN (VD-15/B2):
    orders mode = ``""``; strategy_path mode = strategy reason truncated to
    <=200 characters, UTF-8 safe (``wire.strategy_fill_reason``)."""

    trade_date: str
    symbol: str
    side: str
    qty: float
    price: float
    fee: float
    reason: str = ""


@dataclass(frozen=True, slots=True)
class RejectedOrder:
    """One rejected order; ``reason_code`` from the closed 11-value table."""

    trade_date: str
    symbol: str
    side: str
    qty: float
    reason_code: str
    detail: str = ""


@dataclass(frozen=True, slots=True)
class CanceledOrder:
    """One pt-v1.2 emergency-cancel row (T3, D2).

    ``reason_code`` is fixed at :data:`CANCELED_REASON_CODE`; it is NOT a
    member of the frozen ``REASON_CODES`` vocabulary.
    """

    trade_date: str
    symbol: str
    side: str
    qty: float
    reason_code: str = CANCELED_REASON_CODE
    detail: str = ""


@dataclass(frozen=True, slots=True)
class SessionEvent:
    """One pt-v1.2 session fact (T4, D2); ``event_type`` from
    :data:`SESSION_EVENT_TYPES`."""

    trade_date: str
    symbol: str
    event_type: str
    detail: str = ""


@dataclass(frozen=True, slots=True)
class NavPoint:
    """One ``nav_series`` row (skipped days produce NO row — R3)."""

    date: str
    nav: float
    cash: float
    position_value: float


@dataclass(frozen=True, slots=True)
class SkippedDay:
    """One ``skipped_days`` row; ``reason`` from the closed 2-value table."""

    date: str
    reason: str


@dataclass(frozen=True, slots=True)
class DataProvenance:
    """``data_provenance`` — extension set FINALIZED at G1: AM-9 merged-frame
    fields (cn_a), AM-2 ``corporate_actions`` events, VD-11 cn_a limit/ST/
    suspension path tokens (``limit_provenance``, ``<symbol>@<date>:<token>``).
    Further additions = minor schema bump (APPROVAL §5)."""

    source: str
    bars_as_of: str | None = None
    ch_as_of: str | None = None
    network_as_of: str | None = None
    corporate_actions: tuple[dict[str, Any], ...] = ()
    limit_provenance: tuple[str, ...] = ()


@dataclass(frozen=True, slots=True)
class PaperTradeStepResult:
    """Full success out-param document (AMENDMENT §2.2; pt-v1.2 additive fields).

    The three pt-v1.2 fields stay at their empty defaults for a v1.1 document
    and are serialized only when ``schema_version == SCHEMA_VERSION_V1_2``
    (D8).  ``engine_fingerprint`` is required in a v1.2 document (D3).
    """

    account_id: str
    market: str
    range: DateRange
    received_state_hash: str
    effective_fee_model: dict[str, float]
    fills: tuple[Fill, ...] = ()
    rejected_orders: tuple[RejectedOrder, ...] = ()
    end_state: AccountState = field(default_factory=AccountState)
    nav_series: tuple[NavPoint, ...] = ()
    skipped_days: tuple[SkippedDay, ...] = ()
    warnings: tuple[str, ...] = ()  # deterministic English, no timestamps (VD-7)
    data_provenance: DataProvenance = field(
        default_factory=lambda: DataProvenance(source="")
    )
    schema_version: str = SCHEMA_VERSION
    tool: str = TOOL_NAME
    engine_fingerprint: str = ""
    canceled_orders: tuple[CanceledOrder, ...] = ()
    events: tuple[SessionEvent, ...] = ()


@dataclass(frozen=True, slots=True)
class ErrorEnvelope:
    """In-band error envelope (AM-5, FROZEN field set) — same
    ``result.content[0].text`` channel as the success document, never a
    transport error; ``received_state_hash`` present only when the state was
    parseable (AM-4-4).  Serialized by ``wire.build_error_payload``."""

    code: str
    account_id: str
    market: str
    range: DateRange
    message: str
    received_state_hash: str | None = None
    status: str = "error"


# ── Contract schema loading + dependency-free subset validation ──


def load_contract_schema(
    name: str = "result", *, version: str = SCHEMA_VERSION
) -> dict[str, Any]:
    """Load one named jsonschema from a VD-13 contract file.

    ``name`` is ``"result"`` (success out-param) or ``"error_envelope"``;
    ``version`` is one of :data:`SCHEMA_VERSIONS` and defaults to the frozen
    pt-v1.1 file, so every existing caller keeps reading the same document.
    A v1.1 result validates ONLY against ``version="pt-v1.1"``; a v1.2 result
    (``engine_fingerprint`` present) validates against ``version="pt-v1.2"``.
    Read-only.
    """
    try:
        path = _CONTRACT_SCHEMA_PATHS[version]
    except KeyError:
        raise KeyError(
            f"unknown contract version {version!r}; available: {list(SCHEMA_VERSIONS)}"
        ) from None
    document = json.loads(path.read_text(encoding="utf-8"))
    schemas = document.get("schemas", {})
    if name not in schemas:
        raise KeyError(f"unknown contract schema {name!r}; available: {sorted(schemas)}")
    return schemas[name]


_TYPE_CHECKS: dict[str, tuple[type, ...]] = {
    "object": (dict,),
    "array": (list, tuple),
    "string": (str,),
    "boolean": (bool,),
}


def _type_matches(instance: Any, json_type: str) -> bool:
    if json_type == "null":
        return instance is None
    if json_type == "integer":
        return isinstance(instance, int) and not isinstance(instance, bool)
    if json_type == "number":
        return isinstance(instance, (int, float)) and not isinstance(instance, bool)
    if json_type == "boolean":
        return isinstance(instance, bool)
    expected = _TYPE_CHECKS.get(json_type)
    if expected is None or (json_type == "object" and isinstance(instance, bool)):
        return True  # unknown keyword value — not this validator's call
    return isinstance(instance, expected)


def _validate_node(instance: Any, schema: dict[str, Any], path: str, errors: list[str]) -> None:
    """Recursive subset validator: type/const/enum/required/properties/items/
    additionalProperties(bool).  Unknown keywords are ignored — the skeleton
    stays inside this subset so the hand-rolled pass is faithful."""
    if not isinstance(schema, dict):
        return
    json_type = schema.get("type")
    if isinstance(json_type, str) and not _type_matches(instance, json_type):
        errors.append(f"{path}: expected type {json_type!r}, got {type(instance).__name__}")
        return
    if "const" in schema and instance != schema["const"]:
        errors.append(f"{path}: expected const {schema['const']!r}, got {instance!r}")
    if "enum" in schema and instance not in schema["enum"]:
        errors.append(f"{path}: value {instance!r} not in enum {schema['enum']}")
    if isinstance(instance, dict):
        for key in schema.get("required", ()):
            if key not in instance:
                errors.append(f"{path}: missing required property {key!r}")
        properties = schema.get("properties", {})
        for key, sub_schema in properties.items():
            if key in instance:
                _validate_node(instance[key], sub_schema, f"{path}.{key}", errors)
        if schema.get("additionalProperties") is False and properties:
            unknown = sorted(set(instance) - set(properties))
            for key in unknown:
                errors.append(f"{path}: additional property {key!r} is not allowed")
    if isinstance(instance, (list, tuple)):
        items_schema = schema.get("items")
        if isinstance(items_schema, dict):
            for i, item in enumerate(instance):
                _validate_node(item, items_schema, f"{path}[{i}]", errors)


def validate_payload(payload: Any, schema: dict[str, Any]) -> list[str]:
    """Validate ``payload`` against a contract schema; return error strings.

    Empty list = valid.  Deterministic order: schema-declared order for
    required/properties, index order for arrays.
    """
    errors: list[str] = []
    _validate_node(payload, schema, "$", errors)
    return errors