# Mod API Surface

This document covers `TODOS.phase-72.72.14.1.4`: the curated engine API exposed
to `.mayamod` packages.

## Runtime Surface

- module: `V2Modding`
- policy: `FV2ModApiPolicy`
- catalog entry: `FV2ModApiCapabilityDescriptor`
- request/result: `FV2ModApiRequest` and `FV2ModApiResult`
- helper functions: `BuildDefaultModApiPolicy`, `BuildDefaultModApiCatalog`,
  `BuildSpawnCosmeticActorRequest`, `BuildModifyCosmeticComponentRequest`,
  `BuildRegisterEventListenerRequest`, `BuildCreateUIScreenRequest`,
  `EvaluateModApiRequest`, and `ExecuteModApiRequest`
- automation: `V2/ue/Source/V2Tests/Private/Modding/ModLoadingSystem.spec.cpp`
- contract: `V2/ue/Content/V2/Modding/ModApiSurface_V2_Contract.json`

## Capabilities

The v1 API surface exposes only these capabilities:

- `ReadPublicGameState`
- `SpawnCosmeticActor`
- `ModifyCosmeticComponent`
- `RegisterEventListener`
- `CreateUIScreen`
- `ReadModStorage`
- `WriteModStorage`

World mutation is cosmetic-only. Entity spawning is limited to approved cosmetic
actor templates, and component mutation is limited to approved cosmetic
components on mod-owned targets. Event listeners must live under `Mod.`,
`Gameplay.Public.`, or `UI.Public.` namespaces. UI creation must target
`HUD.ModOverlay`, `Menu.ModPanel`, or `Settings.ModPanel` roots so mods cannot
replace core HUD, ranked, commerce, or account surfaces.

## Policy Enforcement

Every API request is evaluated against `FV2ModApiPolicy` and an approved
`FV2ModSandboxDecision`. The default policy requires sandbox approval, denies
networked API calls, denies ranked-unsafe API calls, enforces cosmetic-only
world mutation, and caps accepted calls at 64 requests per tick.

Rejected requests return explicit issue types for capability denial, missing
sandbox approval, missing targets, ranked-unsafe requests, event namespace
denial, UI surface denial, non-cosmetic world mutation, and network denial.

## Verification

```bash
python3 V2/ue/Tools/check-v2-mod-api-surface.py
python3 V2/ue/Tools/check-v2-mod-sandboxing.py
python3 V2/ue/Tools/check-v2-mod-loading-system.py
python3 V2/ue/Tools/check-v2-ci-workflow.py
python3 V2/tools/validate-v2-docs.py
python3 -m py_compile V2/ue/Tools/check-v2-mod-api-surface.py V2/ue/Tools/check-v2-mod-sandboxing.py V2/ue/Tools/check-v2-mod-loading-system.py V2/ue/Tools/check-v2-ci-workflow.py
python3 -m json.tool V2/ue/Content/V2/Modding/ModApiSurface_V2_Contract.json
```