feat: contract 0.6 — GET/POST /perf, the performance metrics (budget, current frame, windows, zones, raw frames since one, a platform section) and their settings, and /status.capabilities; backend callbacks get_perf and set_perf return allocated JSON (#6) 8fd33bc520f9

## 0.6.0

- `GET /perf[?windows=][&zones=][&frames=][&since=]` — **performance metrics**:

  how much of each frame the program uses, in guest CPU cycles. `budget` (the

  frame and its budget), `current` (the last completed frame: total, work,

  idle, IRQ and main cycles, instructions, host time, utilisation), `windows`

  (min, mean, p50, p95, p99 and max per window, and overruns), `zones` (the

  program's own breakdown: address ranges, or regions the guest marks), raw

  per-frame records (`frames`, or every frame `since` one, so a harness never

  misses one), and `platform` for the rest. Backend callback: `get_perf`.

- `POST /perf` — settings as a JSON body: enabled, target FPS, idle mode,

  history, reset, and the zones (an address range, or a **name for a guest

  marker region**). Backend callback: `set_perf`.

- `/status.capabilities` — the endpoint groups a server serves, whatever level

  it reaches, so a client can ask for `perf` (or `pointer`) directly instead of

  inferring it from the cumulative ladder. Absent before 0.6.

- Both callbacks return allocated JSON the core frees, so the core stays

  platform-neutral: the backend owns the measurements and their shape.

- First backend: the enhanced X16 emulator, whose Performance panel and DAP

  `x16/perfStats` it answers from the same counters. Its `platform` section

  adds VERA's bus bandwidth per scanline and the sprite renderer's time; its

  guest markers are writes to `$9FBC`.

- Motivation: a released game that players found slow. Its port measured

  itself with scanline probes compiled into the game, at a cost in memory and

  with torn reads; the emulator already knew the answer and had no way to say

  it to a test.

| `GET /perf?windows=&frames=&since=` | performance metrics: the frame budget, work/idle/IRQ cycles, statistics windows, zones, raw frames | 0.6 |

| `POST /perf` | performance settings (JSON body): target FPS, idle mode, history, zones and marker names | 0.6 |

`/status` also lists `capabilities` from 0.6: the groups a server serves,

whatever level it reaches.

Current contract: **0.6.0**. Minors are purely additive (a missing capability

   set_pad/get_pad for 0.5, get_perf/set_perf for 0.6.

    .get_perf        = x16_get_perf,         /* 0.6: malloc'd JSON */

    .set_perf        = x16_set_perf,         /* 0.6 */

**Contract version: 0.6.0** (semver; clients assert on the MAJOR). 0.6 adds

performance metrics (`GET /perf`, `POST /perf`) and `/status.capabilities`; 0.5

added a virtual game controller (`POST /pad`, `GET /pad`); 0.4 added pointer injection

  "contract": "0.6.0",

  "running": true,

  "capabilities": ["mem", "regs", "screenshot", "step", "key", "reset",

                   "mem-write", "audio", "pointer", "pad", "perf"]

- `capabilities` *(0.6)* — the endpoint groups this server serves, whatever

  level `contract` reaches: `mem`, `regs`, `screenshot`, `step` (always), then

  `key`, `reset`, `mem-write` (`POST /mem`), `audio`, `pointer`, `pad`, `perf`.

  `contract` stays cumulative (0.6.0 means everything up to and including

  `/perf`); `capabilities` lets a client ask for one group directly, so a

  backend with no pointer can still offer `/perf` without a refusing stub.

  Absent on servers older than 0.6: read `contract` there.

### `GET /perf  [?windows=<list>] [&zones=0|1] [&frames=<n>] [&since=<frame>]`  *(0.6)*

How much of each frame the program uses: the measure a profiler gives, read by

a test the way `/mem` is. Answered on the emulator thread (see *Consistency*),

so it describes whole frames.

Query params, all OPTIONAL:

- `windows` — comma-separated statistics windows, each a number of seconds or

  `session` (the whole history). Default `1,10,30,60,session`.

- `zones` — `0` leaves `zones` out. Default `1`.

- `frames` — return the last `n` completed frames' raw records in `frames`

  (oldest first). Default `0`: none.

- `since` — return the raw records of every frame after `<frame>` still in the

  history (oldest first; `frames` then caps how many, the newest kept). Lets a

  harness poll and never miss a frame: pass the last `frame` it saw.

- A platform MAY accept more (the X16: `lines=1`, below); unknown params are

  ignored.

Every count is in **guest CPU cycles** unless its name says otherwise (`…Us`:

host microseconds; `…Pct`: percent). The shape:

```json

{

  "enabled": true,

  "budget": {

    "targetFps": 60, "vsyncHz": 59.52, "machineKhz": 8000,

    "cyclesPerFrame": 134400, "scanlinesPerFrame": 525, "cyclesPerScanline": 256,

    "budgetCycles": 134400, "framesPerBudget": 1,

    "historyFrames": 3600, "totalFrames": 7200, "idleMode": "auto"

  },

  "current": {

    "frame": 7199, "totalCycles": 134400, "workCycles": 31012,

    "idleCycles": 103388, "irqCycles": 3297, "mainCycles": 27715,

    "budgetWorkCycles": 31012, "instructions": 9120, "hostUs": 412,

    "utilizationPct": 23.1, "overBudget": false

  },

  "windows": [

    { "name": "1s", "seconds": 1, "frames": 60, "budgetCycles": 134400,

      "work":       {"min": 0, "mean": 0, "p50": 0, "p95": 0, "p99": 0, "max": 0},

      "budgetWork": {"min": 0, "mean": 0, "p50": 0, "p95": 0, "p99": 0, "max": 0},

      "total": {"…": 0}, "irq": {"…": 0}, "hostUs": {"…": 0},

      "overruns": 0, "overrunPct": 0.0, "worstOverrunCycles": 0, "worstFrame": 0,

      "meanUtilizationPct": 23.1, "p95UtilizationPct": 31.0, "maxUtilizationPct": 40.2 }

  ],

  "zones": [

    { "id": 0, "name": "sound", "kind": "marker", "markerId": 7, "idle": false,

      "current": 11520,

      "windows": { "1s": {"min": 0, "mean": 0, "p50": 0, "p95": 0, "p99": 0, "max": 0} } },

    { "id": 1, "name": "vblank wait", "kind": "address",

      "start": 49152, "end": 49408, "bank": -1, "idle": true, "current": 0, "windows": {} }

  ],

  "frames": [

    { "frame": 7198, "totalCycles": 134400, "workCycles": 30544,

      "idleCycles": 103856, "irqCycles": 3297, "instructions": 9001,

      "hostUs": 398, "budgetWorkCycles": 30544, "zones": [11520, 0] }

  ],

  "platform": { }

}

```

- `enabled` — whether the backend is measuring. Off, every count is 0 and the

  history is empty; `POST /perf {"enabled":true}` turns it on. A backend MAY

  start measuring on the first `/perf` request.

- `budget` — the frame and its budget. `budgetCycles` is the cycles the program

  may use per budget period of `framesPerBudget` frames (a 30 fps target on a

  60 Hz machine: 2 frames). `cyclesPerScanline` converts a count to scanlines.

- `current` — the last **completed** frame. `workCycles` = total − idle;

  `mainCycles` = work − irq. `idleCycles` are cycles the backend classifies as

  waiting (see *Idle*). `budgetWorkCycles` is the work over the trailing budget

  period, which `utilizationPct` and `overBudget` measure against `budgetCycles`.

- `windows` — per requested window: the frames it covers and `{min, mean, p50,

  p95, p99, max}` of each series (`budgetWork` per budget period, the rest per

  frame); `overruns` (periods over budget), their share, and the worst.

- `zones` — the program's own breakdown (see *Zones*). `current` is the zone's

  cycles in the last completed frame; `windows` its `{min…max}` per window, where

  the backend keeps a zone's history (`{}` where it does not). A cycle belongs

  to one zone at most: the innermost open marker region, else the address zone

  the PC is in.

- `frames` — raw per-frame records, `zones` indexed by zone `id`.

- `platform` — anything platform-specific, described in the *Per-platform

  appendix* (the X16's VERA bus bandwidth and sprite render time). A client

  that does not know the platform ignores it.

**Idle.** A backend counts as idle what the CPU spends waiting: a halt

instruction (`WAI`, `HALT`), a recognised spin loop, an address zone marked

idle, or what the guest marks so. `idleMode` says which: `auto` (all of them),

`markers` (only what the guest marks), `none`.

**Zones.** Two kinds, both optional:

- *address* zones — a PC range `[start, end)` (and `bank`, `-1` any), set by

  `POST /perf`.

- *marker* regions — the guest program writes markers to a platform-defined

  register as it enters and leaves a region of its own (the X16: `$9FBC`, see

  the appendix). A marker region exists once the guest first enters it, named

  `region <n>` unless `POST /perf` has named it.

### `POST /perf`  *(0.6)*

Settings. The body is a JSON object; every field is OPTIONAL, and a field left

out is left as it is:

```json

{

  "enabled": true,

  "targetFps": 60,

  "idleMode": "auto",

  "historyFrames": 3600,

  "reset": false,

  "zones": [

    { "name": "game", "marker": 1 },

    { "name": "vblank wait", "start": 49152, "end": 49408, "bank": -1, "idle": true }

  ]

}

```

- `enabled` — start or stop measuring. Stopping MAY discard the history.

- `targetFps` — the rate the program aims for, which sets `budget`.

- `idleMode` — `auto`, `markers` or `none` (see *Idle*).

- `historyFrames` — how many frames of history to keep.

- `reset` — `true` empties the history and the statistics.

- `zones` — **replaces** the zone list. An entry with `marker` names the guest's

  marker region `<n>`; one with `start`/`end` is an address zone.

- A platform MAY accept more (the X16: `sprites`, below); unknown fields are

  ignored.

- Response: `200` and the `GET /perf` body without `windows`, `zones` or

  `frames`, i.e. the settings as they now stand. A body that is not a JSON

  object, or a field of the wrong type, is `400`.

- `/perf` MUST be answered on the emulator thread, and describe completed

  frames only (`current` is the last whole frame, never the one in progress).

- Perf *(0.6)*: the **enhanced X16 emulator** (`enhanced-x16-emulator`, the one

  with the ImGui Performance panel) implements `/perf` from the same

  measurements the panel shows, and advertises **0.6.0**; the plain fork does

  not measure, and stays at 0.5.0. The budget is the X16's: 8 MHz, 525

  scanlines a frame at 59.52 Hz, 134,400 cycles, 256 a scanline. Idle: `WAI`,

  a short store-free backward branch taken twice, or markers.

  - Markers: the guest writes one byte to **`$9FBC`** (the emulator's register

    12; reading it returns `1`, the marker protocol, so a program can tell it

    is there): `$01`–`$3F` enter region n, `$80|n` leave region n, `$00` leave

    the innermost, `$F0` the frame's work begins, `$F1` the frame's work ends

    (the rest of the frame is idle), `$FE` reset the statistics. Up to 8

    regions nest; cycles go to the innermost. A write to a stock X16 or the

    plain fork does nothing.

  - Zones: up to 16; the first 8 keep a history (`windows`), the rest report

    `current` only.

  - `platform`:

    ```json

    { "bandwidth": { "frame": 7198, "lineClocks": 800, "linesActive": 480,

        "peakLine": 12, "peakLineClocks": 480, "p95LineClocks": 480,

        "meanLineClocks": 320, "linesOverBudget": 0,

        "layers": [ {"fetches": 57600, "bytes": 230400, "peakLine": 0, "peakFetches": 120},

                    {"fetches": 57600, "bytes": 230400, "peakLine": 0, "peakFetches": 120} ],

        "port": {"readBytes": 0, "writeBytes": 64, "accesses": 64, "vramBytes": 64},

        "lines": [320, 320, "…480 entries"] },

      "sprites": { "enabled": true, "frame": 7198, "lineBudget": 798,

        "peakLine": 40, "peakBudget": 612, "peakDemand": 612,

        "linesExhausted": 0, "spritesDropped": 0, "budgetUsedTotal": 51200,

        "slotsUsed": 24, "lines": [0, 0, "…480 entries"] } }

    ```

    `bandwidth` is VERA's VRAM bus in **bus clocks** (800 a scanline; a layer

    fetch or a CPU data-port access takes 2), for the last completed frame;

    `lines` (only with `?lines=1`) is each active line's clocks.

    `sprites` is the sprite renderer's time per line against its 798-clock

    budget, for the last frame; it is off until `POST /perf {"sprites":true}`

    (it costs the emulator time), `{"enabled":false}` until then.

  `set_pointer`/`get_pointer` for 0.4, `set_pad`/`get_pad` for 0.5, and

  `get_perf`/`set_perf` (which return allocated JSON) for 0.6 — a NULL

../SPEC.md (0.6.x). Depends only on the stdlib; Pillow is optional and only

    def capabilities(self) -> set[str]:

        """/status.capabilities as a set (contract 0.6); empty on older

        servers, which have no such field."""

        return set(self.status().get("capabilities") or ())

    def perf(self, windows=None, zones: bool = True, frames: int = 0,

             since: int | None = None, **extra) -> dict:

        """GET /perf — the performance metrics (contract 0.6).

        `windows` is a list of seconds or "session" (default: the server's,

        1, 10, 30, 60 and session). `frames=n` adds the last n frames' raw

        records; `since=f` every frame after f still in the history (pass the

        last frame you saw to never miss one). `extra` goes on the query

        string as it is (a platform's own params, e.g. lines=1 on the X16)."""

        parts = []

        if windows is not None:

            parts.append("windows=" + ",".join(str(w) for w in windows))

        if not zones:

            parts.append("zones=0")

        if frames:

            parts.append(f"frames={frames}")

        if since is not None:

            parts.append(f"since={since}")

        parts += [f"{k}={v}" for k, v in extra.items()]

        body, _ = self._get("/perf" + ("?" + "&".join(parts) if parts else ""))

        return json.loads(body)

    def perf_config(self, **settings) -> dict:

        """POST /perf — settings (contract 0.6): enabled, targetFps,

        idleMode, historyFrames, reset, zones (a list of {"name", "marker"} or

        {"name", "start", "end", "bank", "idle"}; replaces the list), and a

        platform's own (the X16: sprites). Returns the settings as they stand."""

        return json.loads(self._post("/perf", json.dumps(settings).encode()))

def _raw(emu, method, path, body=None):

    req = urllib.request.Request(emu.base + path, method=method, data=body)

# -- contract 0.6: performance metrics (skipped on < 0.6 servers) ------------

def test_capabilities_list_the_groups(emu):

    """/status.capabilities names each group the server serves. Always the

    four 0.1 groups; at 0.6 also perf, and the groups below it the ladder

    implies."""

    if _contract_minor(emu) < 6:

        pytest.skip("contract < 0.6 (no capabilities)")

    caps = emu.capabilities()

    for c in ("mem", "regs", "screenshot", "step", "key", "mem-write", "audio", "pointer", "pad", "perf"):

        assert c in caps, (c, caps)

def _perf_on(emu):

    emu.perf_config(enabled=True)

def test_perf_shape(emu):

    """GET /perf's sections and their arithmetic: work = total - idle, main =

    work - irq, the windows asked for, raw frames oldest first. The numbers

    themselves are the platform's and the program's; only their relations are

    the contract's."""

    if _contract_minor(emu) < 6:

        pytest.skip("contract < 0.6")

    _perf_on(emu)

    emu.pause()

    try:

        emu.step(10)

        p = emu.perf(windows=[1, "session"], frames=5)

    finally:

        emu.resume()

    assert p["enabled"] is True

    b = p["budget"]

    for k in ("targetFps", "vsyncHz", "cyclesPerFrame", "scanlinesPerFrame", "cyclesPerScanline",

              "budgetCycles", "framesPerBudget", "historyFrames", "totalFrames", "idleMode"):

        assert k in b, k

    assert b["cyclesPerFrame"] > 0 and b["budgetCycles"] > 0

    c = p["current"]

    assert c["workCycles"] == c["totalCycles"] - c["idleCycles"], c

    assert c["mainCycles"] == c["workCycles"] - c["irqCycles"], c

    assert isinstance(c["overBudget"], bool)

    assert [w["name"] for w in p["windows"]] == ["1s", "session"], p["windows"]

    for w in p["windows"]:

        for series in ("work", "budgetWork", "total", "irq", "hostUs"):

            s = w[series]

            assert s["min"] <= s["p50"] <= s["p95"] <= s["p99"] <= s["max"], (series, s)

    assert isinstance(p["zones"], list) and isinstance(p["platform"], dict)

    frames = [f["frame"] for f in p["frames"]]

    assert 1 <= len(frames) <= 5 and frames == sorted(frames), frames

    assert frames[-1] == c["frame"], (frames, c["frame"])

def test_perf_since_misses_no_frame(emu):

    """since=<f> returns every completed frame after f, so a harness that

    polls with the last frame it saw gets each frame exactly once."""

    if _contract_minor(emu) < 6:

        pytest.skip("contract < 0.6")

    _perf_on(emu)

    emu.pause()

    try:

        emu.step(2)

        last = emu.perf(zones=False)["current"]["frame"]

        emu.step(5)

        got = [f["frame"] for f in emu.perf(zones=False, since=last)["frames"]]

    finally:

        emu.resume()

    assert got == list(range(last + 1, last + 6)), (last, got)

def test_perf_zones_name_a_marker_region(emu):

    """POST /perf's zones replace the list, and a {name, marker} entry names

    the guest's marker region; the zone is reported under that name whether

    or not the program has entered it yet."""

    if _contract_minor(emu) < 6:

        pytest.skip("contract < 0.6")

    try:

        emu.perf_config(enabled=True, zones=[{"name": "conformance", "marker": 63}])

        names = [z["name"] for z in emu.perf()["zones"]]

        assert "conformance" in names, names

    finally:

        emu.perf_config(zones=[])

def test_perf_rejects_a_bad_body(emu):

    if _contract_minor(emu) < 6:

        pytest.skip("contract < 0.6")

    code, _ = _raw(emu, "POST", "/perf", b"not json")

    assert code == 400

               REQ_PAD_SET, REQ_PAD_GET, REQ_PERF_GET, REQ_PERF_SET } req_t;

static char     g_perf_query[1024];   /* GET /perf's query string (0.6) */

static const char *g_perf_body;       /* POST /perf's body, NUL-terminated (HTTP-thread owned) */

    case REQ_PERF_GET:

    case REQ_PERF_SET: {

        char *b = NULL;

        int st = 200;

        int have = (g_req == REQ_PERF_GET) ? g_be->get_perf != NULL : g_be->set_perf != NULL;

        if (!have) {

            st = 501;

        } else if (g_req == REQ_PERF_GET) {

            b = g_be->get_perf(g_perf_query);

        } else {

            b = g_be->set_perf(g_perf_body ? g_perf_body : "", &st);

            if (st != 200 && st != 400) st = 400;

        }

        if (!b) {                             /* not implemented, or the backend failed */

            const char *json = (st == 501) ? "{\"error\":\"not implemented\"}"

                                           : "{\"error\":\"perf failed\"}";

            if (st != 501) st = 500;

            size_t l = strlen(json);

            b = (char *)malloc(l + 1);

            if (b) memcpy(b, json, l + 1);

        }

        g_resp_body = (uint8_t *)b; g_resp_len = b ? strlen(b) : 0;

        g_resp_status = st;

        g_resp_ctype = "application/json";

        break;

    }

        status == 500 ? "Internal Server Error" :

    const int perf = g_be->get_perf && g_be->set_perf;

        (g_be->inject_key && g_be->write_mem && g_be->capture_audio &&

         g_be->set_pointer && g_be->get_pointer &&

         g_be->set_pad && g_be->get_pad && perf) ? "0.6.0" :

    /* 0.6: each endpoint group the backend serves, whatever level it reaches. */

    char caps[160];

    snprintf(caps, sizeof caps, "\"mem\",\"regs\",\"screenshot\",\"step\"%s%s%s%s%s%s%s",

        g_be->inject_key ? ",\"key\"" : "",

        g_be->reset ? ",\"reset\"" : "",

        g_be->write_mem ? ",\"mem-write\"" : "",

        g_be->capture_audio ? ",\"audio\"" : "",

        (g_be->set_pointer && g_be->get_pointer) ? ",\"pointer\"" : "",

        (g_be->set_pad && g_be->get_pad) ? ",\"pad\"" : "",

        perf ? ",\"perf\"" : "");

    char buf[512];

        "\"frame\":%llu,\"paused\":%s,\"running\":true,\"capabilities\":[%s]}",

        fc, (f == 0) ? "true" : "false", caps);

        }

        return;

    }

    if (!strcmp(target, "/perf")) {           /* 0.6: performance metrics */

        if (is_post) {

            size_t blen = 0;

            uint8_t *body = read_body(fd, req, n, &blen);

            char *text = (char *)malloc(blen + 1);

            if (!text) { free(body); send_json(fd, 500, "{\"error\":\"out of memory\"}"); return; }

            if (body && blen) memcpy(text, body, blen);

            text[blen] = 0;

            free(body);

            g_perf_body = text;

            do_marshalled(fd, REQ_PERF_SET);

            g_perf_body = NULL;

            free(text);

        } else {

            snprintf(g_perf_query, sizeof g_perf_query, "%s", query);

            do_marshalled(fd, REQ_PERF_GET);

 * whose backend callbacks are all present: 0.6.0 needs get_perf + set_perf (on

 * top of 0.5); 0.5.0 needs set_pad + get_pad (on top of 0.4); 0.4.0 needs

 * set_pointer + get_pointer (on top of 0.3); 0.3.0 needs inject_key +

 * write_mem + capture_audio; 0.2.0 needs inject_key; else 0.1.0. Keeps a

 * partial backend honest. /status.capabilities lists each group a backend

 * serves whatever level it reaches, so a client can ask for one directly. */

#define RETRO_CONTROL_CONTRACT "0.6.0"

    /* 0.6: the performance metrics, as the JSON body of GET /perf (SPEC

     * "GET /perf"). `query` is the request's raw query string ("" for none:

     * windows=, zones=, frames=, since=), for the backend to read. Return a

     * malloc'd NUL-terminated string the server frees, or NULL on failure

     * (server -> 500). Called on the emulator thread, so the metrics are read

     * at a frame/instruction boundary like /mem. NULL => GET /perf returns 501

     * and the server does not advertise 0.6.0. */

    char *(*get_perf)(const char *query);

    /* 0.6: apply a POST /perf settings body (a JSON object, NUL-terminated;

     * SPEC "POST /perf"). Set *status to 200, or 400 for a body the backend

     * cannot apply, and return a malloc'd JSON response the server frees (for

     * 200, the settings as they now stand; for 400, {"error":...}). NULL

     * return => 500. NULL callback => POST /perf returns 501. */

    char *(*set_perf)(const char *body, int *status);