From 70dccff53542f976abe4ce67e57c54b160077ec0 Mon Sep 17 00:00:00 2001 From: dayfine Date: Sat, 14 Nov 2026 14:53:37 -0800 Subject: [PATCH] Story wire cases: steps as an action plus typed args, as the native reader reads them data/story/wire-conformance.json moves to pokesim-story-wire-cases/2: steps name an action and its typed args, poses are {map, tiles, facing} or a zone {place, spot, heading}, and the file declares the test game actions. Accepted cases give the record as read, args with fallbacks filled. checkpoint_wire gains read_grid_pose, read_declared_pose, read_story_step and read_story_checkpoint, matching Arduino-Source's Pokemon_StoryStepJson (built-in actions, arg types, once_per_save). read_pose/read_step/ read_checkpoint stay for the authored plans and the replay, which still use the older record. The legacy schema no longer checks the wire cases. --- data/story/wire-conformance.json | 594 ++++++++++++++++------ docs/story/CHECKPOINT_CONTRACT.md | 60 ++- src/pokesim/formats/test_json_schema.py | 15 - src/pokesim/story/checkpoint_wire.py | 252 ++++++++- src/pokesim/story/test_checkpoint_wire.py | 23 +- 5 files changed, 736 insertions(+), 208 deletions(-) diff --git a/data/story/wire-conformance.json b/data/story/wire-conformance.json index 8a46122..506ad4a 100644 --- a/data/story/wire-conformance.json +++ b/data/story/wire-conformance.json @@ -1,302 +1,578 @@ { - "format": "pokesim-story-wire-cases/1", + "format": "pokesim-story-wire-cases/2", "status": "synthetic-contract-tests", + "actions": [ + { + "kind": "game_action", + "name": "mart", + "args": [ + {"key": "map", "type": "word", "required": true}, + {"key": "budget", "type": "integer", "required": true}, + {"key": "if_present", "type": "boolean", "fallback": false}, + {"key": "skip", "type": "words"} + ] + }, + {"kind": "game_action", "name": "walk", "args": [{"key": "legs", "type": "integer_rows", "required": true}]}, + {"kind": "game_action", "name": "timed_walk", "args": [{"key": "legs", "type": "timed_legs", "required": true}]}, + {"kind": "game_action", "name": "profile", "args": []} + ], "cases": [ { - "input": {"name": "kind new_game", "record": "step", "value": {"id": "event", "kind": "new_game"}}, - "expectation": {"canonical": {"id": "event", "kind": "new_game"}} + "input": {"name": "kind new_game", "record": "step", "value": {"id": "e", "kind": "new_game"}}, + "expectation": {"read": {"id": "e", "kind": "new_game"}} }, { - "input": {"name": "kind options", "record": "step", "value": {"id": "event", "kind": "options"}}, - "expectation": {"canonical": {"id": "event", "kind": "options"}} + "input": {"name": "kind options", "record": "step", "value": {"id": "e", "kind": "options"}}, + "expectation": {"read": {"id": "e", "kind": "options"}} }, { - "input": {"name": "kind route", "record": "step", "value": {"id": "event", "kind": "route"}}, - "expectation": {"canonical": {"id": "event", "kind": "route"}} + "input": { + "name": "kind route", + "record": "step", + "value": {"id": "e", "kind": "route", "args": {"target": {"map": "M", "tiles": [[1, 2]]}}} + }, + "expectation": { + "read": {"id": "e", "kind": "route", "args": {"fight_wild": false, "target": {"map": "M", "tiles": [[1, 2]]}}} + } + }, + { + "input": { + "name": "kind legs", + "record": "step", + "value": { + "id": "e", + "kind": "legs", + "action": "legs", + "args": {"legs": [{"direction": "south", "tiles": 2}], "fight_wild": true} + } + }, + "expectation": { + "read": { + "id": "e", + "kind": "legs", + "action": "legs", + "args": {"fight_wild": true, "legs": [{"direction": "south", "tiles": 2}]} + } + } }, { - "input": {"name": "kind legs", "record": "step", "value": {"id": "event", "kind": "legs"}}, - "expectation": {"canonical": {"id": "event", "kind": "legs"}} + "input": { + "name": "kind step", + "record": "step", + "value": {"id": "e", "kind": "step", "args": {"direction": "west"}} + }, + "expectation": {"read": {"id": "e", "kind": "step", "args": {"direction": "west"}}} }, { - "input": {"name": "kind step", "record": "step", "value": {"id": "event", "kind": "step"}}, - "expectation": {"canonical": {"id": "event", "kind": "step"}} + "input": {"name": "kind talk", "record": "step", "value": {"id": "e", "kind": "talk"}}, + "expectation": {"read": {"id": "e", "kind": "talk"}} }, { - "input": {"name": "kind talk", "record": "step", "value": {"id": "event", "kind": "talk"}}, - "expectation": {"canonical": {"id": "event", "kind": "talk"}} + "input": {"name": "kind answer", "record": "step", "value": {"id": "e", "kind": "answer"}}, + "expectation": {"read": {"id": "e", "kind": "answer", "args": {"yes": true}}} }, { - "input": {"name": "kind answer", "record": "step", "value": {"id": "event", "kind": "answer"}}, - "expectation": {"canonical": {"id": "event", "kind": "answer"}} + "input": {"name": "answer no", "record": "step", "value": {"id": "e", "kind": "answer", "args": {"yes": false}}}, + "expectation": {"read": {"id": "e", "kind": "answer", "args": {"yes": false}}} }, { - "input": {"name": "kind scene", "record": "step", "value": {"id": "event", "kind": "scene"}}, - "expectation": {"canonical": {"id": "event", "kind": "scene"}} + "input": {"name": "kind scene", "record": "step", "value": {"id": "e", "kind": "scene"}}, + "expectation": {"read": {"id": "e", "kind": "scene"}} }, { - "input": {"name": "kind battle", "record": "step", "value": {"id": "event", "kind": "battle"}}, - "expectation": {"canonical": {"id": "event", "kind": "battle"}} + "input": { + "name": "kind battle", + "record": "step", + "value": {"id": "e", "kind": "battle", "args": {"may_lose": true}} + }, + "expectation": {"read": {"id": "e", "kind": "battle", "args": {"may_lose": true}}} }, { - "input": {"name": "kind train", "record": "step", "value": {"id": "event", "kind": "train"}}, - "expectation": {"canonical": {"id": "event", "kind": "train"}} + "input": { + "name": "kind battle by its action name", + "record": "step", + "value": {"id": "e", "kind": "battle", "action": "fight"} + }, + "expectation": {"read": {"id": "e", "kind": "battle", "action": "fight", "args": {"may_lose": false}}} }, { - "input": {"name": "kind heal", "record": "step", "value": {"id": "event", "kind": "heal"}}, - "expectation": {"canonical": {"id": "event", "kind": "heal"}} + "input": {"name": "kind train", "record": "step", "value": {"id": "e", "kind": "train", "args": {"battles": 3}}}, + "expectation": {"read": {"id": "e", "kind": "train", "args": {"battles": 3}}} }, { - "input": {"name": "kind shop", "record": "step", "value": {"id": "event", "kind": "shop"}}, - "expectation": {"canonical": {"id": "event", "kind": "shop"}} + "input": {"name": "kind heal", "record": "step", "value": {"id": "e", "kind": "heal"}}, + "expectation": {"read": {"id": "e", "kind": "heal"}} }, { - "input": {"name": "kind save", "record": "step", "value": {"id": "event", "kind": "save"}}, - "expectation": {"canonical": {"id": "event", "kind": "save"}} + "input": { + "name": "kind shop", + "record": "step", + "value": {"id": "e", "kind": "shop", "args": {"items": [{"item": "potion", "quantity": 5}]}} + }, + "expectation": {"read": {"id": "e", "kind": "shop", "args": {"items": [{"item": "potion", "quantity": 5}]}}} }, { - "input": {"name": "kind ready", "record": "step", "value": {"id": "event", "kind": "ready"}}, - "expectation": {"canonical": {"id": "event", "kind": "ready"}} + "input": {"name": "kind save", "record": "step", "value": {"id": "e", "kind": "save"}}, + "expectation": {"read": {"id": "e", "kind": "save"}} }, { - "input": {"name": "kind game_action", "record": "step", "value": {"id": "event", "kind": "game_action"}}, - "expectation": {"canonical": {"id": "event", "kind": "game_action"}} + "input": { + "name": "kind ready", + "record": "step", + "value": {"id": "e", "kind": "ready", "args": {"target": {"map": "M", "tiles": [[1, 2]]}}} + }, + "expectation": {"read": {"id": "e", "kind": "ready", "args": {"target": {"map": "M", "tiles": [[1, 2]]}}}} }, { "input": { - "name": "uncertain arrival", - "record": "pose", + "name": "kind game_action", + "record": "step", + "value": {"id": "e", "kind": "game_action", "action": "profile"} + }, + "expectation": {"read": {"id": "e", "kind": "game_action", "action": "profile"}} + }, + { + "input": { + "name": "all shared fields", + "record": "step", "value": { - "map": "M", - "certainty": "set", - "where": {"kind": "tiles", "tiles": [[0, 0], [1, 0]], "facing": "east"} + "id": "all", + "kind": "game_action", + "why": "source reason", + "action": "profile", + "skip_if": ["flag"], + "once_per_save": true, + "declared_after": {"map": "B", "tiles": [[0, 0], [1, 0]], "facing": "east"} } }, "expectation": { - "canonical": { - "map": "M", - "certainty": "set", - "where": {"kind": "tiles", "tiles": [[0, 0], [1, 0]], "facing": "east"} + "read": { + "id": "all", + "kind": "game_action", + "why": "source reason", + "action": "profile", + "skip_if": ["flag"], + "declared_after": {"map": "B", "tiles": [[0, 0], [1, 0]], "facing": "east"}, + "once_per_save": true } } }, { "input": { - "name": "no position", - "record": "pose", - "value": {"map": "M", "certainty": "unknown", "where": {"kind": "unknown"}} + "name": "empty fields read as absent", + "record": "step", + "value": {"id": "e", "kind": "talk", "why": "", "action": "", "skip_if": [], "once_per_save": false} }, - "expectation": {"canonical": {"map": "M", "certainty": "unknown", "where": {"kind": "unknown"}}} + "expectation": {"read": {"id": "e", "kind": "talk"}} }, { "input": { - "name": "empty tile position", - "record": "pose", - "value": {"map": "M", "certainty": "unknown", "where": {"kind": "tiles", "tiles": []}} + "name": "game args", + "record": "step", + "value": { + "id": "buy", + "kind": "game_action", + "action": "mart", + "args": {"map": "CeruleanCity_Mart", "budget": 3000, "if_present": true} + } }, - "expectation": {"canonical": {"map": "M", "certainty": "unknown", "where": {"kind": "tiles", "tiles": []}}} + "expectation": { + "read": { + "id": "buy", + "kind": "game_action", + "action": "mart", + "args": {"budget": 3000, "if_present": true, "map": "CeruleanCity_Mart"} + } + } }, { "input": { - "name": "all shared fields", + "name": "game words", "record": "step", "value": { - "id": "all", + "id": "buy", "kind": "game_action", - "why": "source", - "direction": "west", - "fight_wild": true, - "yes": false, - "may_lose": true, - "battles": 3, - "legs": [{"direction": "south", "tiles": 0}], - "items": [{"item": "potion", "quantity": 0}], - "target": {"map": "M", "certainty": "unknown", "where": {"kind": "unknown"}}, - "declared_after": { - "map": "M", - "certainty": "set", - "where": {"kind": "tiles", "tiles": [[0, 0], [1, 0]], "facing": "east"} - }, - "variant": "profile", - "skip_if": ["flag"] + "action": "mart", + "args": {"map": "M", "budget": 1, "skip": ["a", "b"]} } }, "expectation": { - "canonical": { - "id": "all", + "read": { + "id": "buy", "kind": "game_action", - "why": "source", - "direction": "west", - "fight_wild": true, - "yes": false, - "may_lose": true, - "battles": 3, - "legs": [{"direction": "south", "tiles": 0}], - "items": [{"item": "potion", "quantity": 0}], - "target": {"map": "M", "certainty": "unknown", "where": {"kind": "unknown"}}, - "declared_after": { - "map": "M", - "certainty": "set", - "where": {"kind": "tiles", "tiles": [[0, 0], [1, 0]], "facing": "east"} - }, - "variant": "profile", - "skip_if": ["flag"] + "action": "mart", + "args": {"budget": 1, "if_present": false, "map": "M", "skip": ["a", "b"]} } } }, { "input": { - "name": "canonical default omission", + "name": "game integer rows", "record": "step", + "value": {"id": "w", "kind": "game_action", "action": "walk", "args": {"legs": [[0, 4500], [-90, 0], []]}} + }, + "expectation": { + "read": {"id": "w", "kind": "game_action", "action": "walk", "args": {"legs": [[0, 4500], [-90, 0], []]}} + } + }, + { + "input": { + "name": "timed legs", + "record": "step", + "value": {"id": "w", "kind": "game_action", "action": "timed_walk", "args": {"legs": [[0, 4500], [-90, 1200]]}} + }, + "expectation": { + "read": {"id": "w", "kind": "game_action", "action": "timed_walk", "args": {"legs": [[0, 4500], [-90, 1200]]}} + } + }, + { + "input": { + "name": "zero coordinates and counts", + "record": "step", + "value": {"id": "z", "kind": "legs", "args": {"legs": [{"direction": "north", "tiles": 0}]}} + }, + "expectation": { + "read": {"id": "z", "kind": "legs", "args": {"fight_wild": false, "legs": [{"direction": "north", "tiles": 0}]}} + } + }, + { + "input": {"name": "unknown facing stays absent", "record": "pose", "value": {"map": "M", "tiles": [[0, 0]]}}, + "expectation": {"read": {"map": "M", "tiles": [[0, 0]]}} + }, + { + "input": {"name": "no tiles", "record": "pose", "value": {"map": "M", "tiles": []}}, + "expectation": {"read": {"map": "M", "tiles": []}} + }, + { + "input": {"name": "tiles absent", "record": "pose", "value": {"map": "M"}}, + "expectation": {"read": {"map": "M", "tiles": []}} + }, + { + "input": { + "name": "alternative tiles", + "record": "pose", + "value": {"map": "M", "tiles": [[0, 0], [1, 0]], "facing": "east"} + }, + "expectation": {"read": {"map": "M", "tiles": [[0, 0], [1, 0]], "facing": "east"}} + }, + { + "input": { + "name": "declared tile pose", + "record": "declared", + "value": {"map": "M", "tiles": [[1, 2]], "facing": "north"} + }, + "expectation": {"read": {"map": "M", "tiles": [[1, 2]], "facing": "north"}} + }, + { + "input": { + "name": "declared place", + "record": "declared", + "value": {"place": "LumioseCity", "spot": "HotelZ", "heading": 90} + }, + "expectation": {"read": {"place": "LumioseCity", "spot": "HotelZ", "heading": 90}} + }, + { + "input": {"name": "declared place alone", "record": "declared", "value": {"place": "HotelZ"}}, + "expectation": {"read": {"place": "HotelZ"}} + }, + { + "input": { + "name": "checkpoint starting at a place", + "record": "checkpoint", "value": { - "id": "default", - "kind": "step", - "direction": "north", - "fight_wild": false, - "yes": true, - "may_lose": false, - "battles": 0, - "items": [], - "legs": [], - "skip_if": [], - "variant": "", - "why": "" + "id": "03.01", + "title": "Lobby", + "start": {"place": "HotelZ"}, + "events": [{"id": "down", "kind": "scene", "declared_after": {"place": "HotelZLobby", "heading": 180}}] } }, - "expectation": {"canonical": {"id": "default", "kind": "step"}} + "expectation": { + "read": { + "id": "03.01", + "title": "Lobby", + "start": {"place": "HotelZ"}, + "events": [{"id": "down", "kind": "scene", "declared_after": {"place": "HotelZLobby", "heading": 180}}] + } + } }, { "input": { - "name": "checkpoint order and beliefs", + "name": "ordered checkpoint", "record": "checkpoint", "value": { "id": "00.05", "title": "synthetic ordered checkpoint", - "start": { - "map": "M", - "certainty": "set", - "where": {"kind": "tiles", "tiles": [[0, 0], [1, 0]], "facing": "east"} - }, + "start": {"map": "M", "tiles": [[0, 0], [1, 0]], "facing": "east"}, "events": [ - {"id": "first", "kind": "route"}, - { - "id": "second", - "kind": "scene", - "declared_after": {"map": "M", "certainty": "unknown", "where": {"kind": "unknown"}} - } + {"id": "first", "kind": "route", "args": {"target": {"map": "M", "tiles": [[3, 4]]}}}, + {"id": "second", "kind": "scene", "declared_after": {"map": "M"}} ] } }, "expectation": { - "canonical": { + "read": { "id": "00.05", "title": "synthetic ordered checkpoint", - "start": { - "map": "M", - "certainty": "set", - "where": {"kind": "tiles", "tiles": [[0, 0], [1, 0]], "facing": "east"} - }, + "start": {"map": "M", "tiles": [[0, 0], [1, 0]], "facing": "east"}, "events": [ - {"id": "first", "kind": "route"}, - { - "id": "second", - "kind": "scene", - "declared_after": {"map": "M", "certainty": "unknown", "where": {"kind": "unknown"}} - } + {"id": "first", "kind": "route", "args": {"fight_wild": false, "target": {"map": "M", "tiles": [[3, 4]]}}}, + {"id": "second", "kind": "scene", "declared_after": {"map": "M", "tiles": []}} ] } } }, { - "input": {"name": "unsupported kind", "record": "step", "value": {"id": "a", "kind": "teleport"}}, + "input": { + "name": "checkpoint metadata", + "record": "checkpoint", + "value": { + "id": "x", + "title": "X", + "events": [], + "metadata": { + "phase": "reproduction", + "source": "synthetic", + "verified": {"steps_hash": "abc", "build": "b", "date": "2026-11-14", "runs": "3/3"}, + "postconditions": { + "position": {"map": "M", "tiles": [[3, 4]]}, + "items": [{"item": "LIFT_KEY", "quantity": 1}], + "flags": ["f"] + } + } + } + }, + "expectation": { + "read": { + "id": "x", + "title": "X", + "events": [], + "metadata": { + "phase": "reproduction", + "verified": {"steps_hash": "abc", "build": "b", "date": "2026-11-14", "runs": "3/3"}, + "source": "synthetic", + "postconditions": { + "position": {"map": "M", "tiles": [[3, 4]]}, + "items": [{"item": "LIFT_KEY", "quantity": 1}], + "flags": ["f"] + } + } + } + } + }, + { + "input": { + "name": "integer rows, not rows", + "record": "step", + "value": {"id": "w", "kind": "game_action", "action": "walk", "args": {"legs": [0, 4500]}} + }, "expectation": {"rejected": true} }, { - "input": {"name": "unknown field", "record": "step", "value": {"id": "a", "kind": "talk", "mystery": 1}}, + "input": { + "name": "integer rows, fraction", + "record": "step", + "value": {"id": "w", "kind": "game_action", "action": "walk", "args": {"legs": [[0, 4.5]]}} + }, "expectation": {"rejected": true} }, { - "input": {"name": "boolean count", "record": "step", "value": {"id": "a", "kind": "train", "battles": false}}, + "input": { + "name": "timed leg of three numbers", + "record": "step", + "value": {"id": "w", "kind": "game_action", "action": "timed_walk", "args": {"legs": [[0, 4500, 1]]}} + }, "expectation": {"rejected": true} }, { - "input": {"name": "negative count", "record": "step", "value": {"id": "a", "kind": "train", "battles": -1}}, + "input": { + "name": "unknown arg", + "record": "step", + "value": {"id": "a", "kind": "game_action", "action": "mart", "args": {"map": "M", "budget": 1, "budgte": 1}} + }, "expectation": {"rejected": true} }, { - "input": {"name": "wrong boolean", "record": "step", "value": {"id": "a", "kind": "answer", "yes": 0}}, + "input": { + "name": "missing required arg", + "record": "step", + "value": {"id": "a", "kind": "game_action", "action": "mart", "args": {"map": "M"}} + }, "expectation": {"rejected": true} }, - {"input": {"name": "missing id", "record": "step", "value": {"kind": "talk"}}, "expectation": {"rejected": true}}, { - "input": {"name": "empty id", "record": "step", "value": {"id": "", "kind": "talk"}}, + "input": {"name": "route without target", "record": "step", "value": {"id": "a", "kind": "route"}}, "expectation": {"rejected": true} }, { "input": { - "name": "duplicate events", - "record": "checkpoint", - "value": {"id": "x", "title": "X", "events": [{"id": "a", "kind": "talk"}, {"id": "a", "kind": "talk"}]} + "name": "args on a kind with none", + "record": "step", + "value": {"id": "a", "kind": "talk", "args": {"yes": true}} }, "expectation": {"rejected": true} }, + { + "input": {"name": "game step without action", "record": "step", "value": {"id": "a", "kind": "game_action"}}, + "expectation": {"rejected": true} + }, { "input": { - "name": "bad pair", - "record": "pose", - "value": {"map": "M", "certainty": "tile", "where": {"kind": "tiles", "tiles": [[0, true]]}} + "name": "unknown action name", + "record": "step", + "value": {"id": "a", "kind": "game_action", "action": "dance"} }, "expectation": {"rejected": true} }, { "input": { - "name": "unknown subtype", - "record": "pose", - "value": {"map": "M", "certainty": "unknown", "where": {"kind": "gps"}} + "name": "action of another kind", + "record": "step", + "value": {"id": "a", "kind": "shop", "action": "mart", "args": {"map": "M", "budget": 1}} }, "expectation": {"rejected": true} }, { "input": { - "name": "args", + "name": "fractional arg", "record": "step", - "value": { - "id": "buy", - "kind": "game_action", - "variant": "mart", - "args": {"map": "CeruleanCity_Mart", "budget": 3000, "if_present": true} - } + "value": {"id": "a", "kind": "game_action", "action": "mart", "args": {"map": "M", "budget": 1.5}} }, - "expectation": { - "canonical": { - "id": "buy", - "kind": "game_action", - "variant": "mart", - "args": {"map": "CeruleanCity_Mart", "budget": 3000, "if_present": true} - } - } + "expectation": {"rejected": true} }, { "input": { - "name": "fractional arg", + "name": "args not an object", "record": "step", - "value": {"id": "a", "kind": "game_action", "variant": "mart", "args": {"budget": 1.5}} + "value": {"id": "a", "kind": "game_action", "action": "mart", "args": ["map"]} }, "expectation": {"rejected": true} }, + { + "input": {"name": "old field", "record": "step", "value": {"id": "a", "kind": "battle", "may_lose": true}}, + "expectation": {"rejected": true} + }, + { + "input": {"name": "old variant", "record": "step", "value": {"id": "a", "kind": "game_action", "variant": "mart"}}, + "expectation": {"rejected": true} + }, + { + "input": {"name": "notes", "record": "step", "value": {"id": "a", "kind": "talk", "notes": ["n"]}}, + "expectation": {"rejected": true} + }, + { + "input": {"name": "unknown field", "record": "step", "value": {"id": "a", "kind": "talk", "mystery": 0}}, + "expectation": {"rejected": true} + }, + { + "input": {"name": "unknown kind", "record": "step", "value": {"id": "a", "kind": "magic"}}, + "expectation": {"rejected": true} + }, { "input": { - "name": "nested arg", + "name": "boolean count", "record": "step", - "value": {"id": "a", "kind": "game_action", "variant": "mart", "args": {"items": [1]}} + "value": {"id": "a", "kind": "train", "args": {"battles": false}} }, "expectation": {"rejected": true} }, + { + "input": {"name": "wrong bool", "record": "step", "value": {"id": "a", "kind": "answer", "args": {"yes": 0}}}, + "expectation": {"rejected": true} + }, { "input": { - "name": "args not an object", + "name": "once_per_save not boolean", + "record": "step", + "value": {"id": "a", "kind": "talk", "once_per_save": 1} + }, + "expectation": {"rejected": true} + }, + { + "input": { + "name": "unknown leg direction", + "record": "step", + "value": {"id": "a", "kind": "legs", "args": {"legs": [{"direction": "up", "tiles": 1}]}} + }, + "expectation": {"rejected": true} + }, + { + "input": { + "name": "negative quantity", "record": "step", - "value": {"id": "a", "kind": "game_action", "variant": "mart", "args": ["map"]} + "value": {"id": "a", "kind": "shop", "args": {"items": [{"item": "potion", "quantity": -1}]}} + }, + "expectation": {"rejected": true} + }, + {"input": {"name": "missing id", "record": "step", "value": {"kind": "talk"}}, "expectation": {"rejected": true}}, + { + "input": {"name": "empty id", "record": "step", "value": {"id": "", "kind": "talk"}}, + "expectation": {"rejected": true} + }, + { + "input": { + "name": "old pose", + "record": "pose", + "value": {"map": "M", "certainty": "unknown", "where": {"kind": "unknown"}} + }, + "expectation": {"rejected": true} + }, + { + "input": {"name": "bad coordinate", "record": "pose", "value": {"map": "M", "tiles": [[0, true]]}}, + "expectation": {"rejected": true} + }, + { + "input": {"name": "tile of three coordinates", "record": "pose", "value": {"map": "M", "tiles": [[0, 1, 2]]}}, + "expectation": {"rejected": true} + }, + { + "input": {"name": "unknown facing", "record": "pose", "value": {"map": "M", "facing": "up"}}, + "expectation": {"rejected": true} + }, + { + "input": {"name": "declared map and place", "record": "declared", "value": {"map": "M", "place": "HotelZ"}}, + "expectation": {"rejected": true} + }, + { + "input": { + "name": "declared place with tiles", + "record": "declared", + "value": {"place": "HotelZ", "tiles": [[1, 2]]} + }, + "expectation": {"rejected": true} + }, + { + "input": {"name": "declared map with heading", "record": "declared", "value": {"map": "M", "heading": 90}}, + "expectation": {"rejected": true} + }, + { + "input": {"name": "declared neither", "record": "declared", "value": {"spot": "Lobby"}}, + "expectation": {"rejected": true} + }, + { + "input": { + "name": "duplicate events", + "record": "checkpoint", + "value": {"id": "x", "title": "X", "events": [{"id": "a", "kind": "talk"}, {"id": "a", "kind": "talk"}]} + }, + "expectation": {"rejected": true} + }, + { + "input": {"name": "checkpoint without title", "record": "checkpoint", "value": {"id": "x", "events": []}}, + "expectation": {"rejected": true} + }, + { + "input": { + "name": "checkpoint sections", + "record": "checkpoint", + "value": {"id": "x", "title": "X", "sections": []} + }, + "expectation": {"rejected": true} + }, + { + "input": { + "name": "unknown phase", + "record": "checkpoint", + "value": {"id": "x", "title": "X", "events": [], "metadata": {"phase": "done"}} }, "expectation": {"rejected": true} } diff --git a/docs/story/CHECKPOINT_CONTRACT.md b/docs/story/CHECKPOINT_CONTRACT.md index 41ce1e7..86b0b3f 100644 --- a/docs/story/CHECKPOINT_CONTRACT.md +++ b/docs/story/CHECKPOINT_CONTRACT.md @@ -53,15 +53,20 @@ starter or battle strategy. Exporting current behavior precedes changing it. ## Implemented common record boundary -The new native `Pokemon_StoryStepJson` codec and Python -`pokesim.story.checkpoint_wire` reader cover these records: +The native `Pokemon_StoryStepJson` reader and Python +`pokesim.story.checkpoint_wire` (`read_story_checkpoint`, `read_story_step`, +`read_grid_pose`, `read_declared_pose`) read these records: ```json { "id": "example", "title": "Synthetic checkpoint", - "start": {"map": "ExampleMap", "certainty": "set", "where": {"kind": "tiles", "tiles": [[1, 2], [1, 3]]}}, - "events": [{"id": "answer_no", "kind": "answer", "yes": false}] + "start": {"map": "ExampleMap", "tiles": [[1, 2], [1, 3]]}, + "events": [ + {"id": "to_door", "kind": "route", "args": {"target": {"map": "ExampleMap", "tiles": [[4, 0]], "facing": "north"}}}, + {"id": "buy", "kind": "game_action", "action": "mart", "args": {"map": "ExampleMart", "budget": 3000}}, + {"id": "answer_no", "kind": "answer", "args": {"yes": false}} + ] } ``` @@ -69,31 +74,34 @@ This is a codec example, not an exported game plan. The common record has no implicit save, retry, handoff, inventory or observed effects. Those need the validated envelope and game bindings above. Loading this record does not run it. -The codec retains every shared `StoryStep` field, including `variant`, `skip_if`, -`fight_wild`, `may_lose`, training count, items and declared arrival. Native `MASH` -is named `scene`; `GAME` is `game_action`. A `declared_after` is the native -fallback declaration, not an observation. Optional start/target/arrival poses -preserve absence, certainty, tile alternatives and unknown facing. - -Only declared native defaults may be omitted: empty text/lists, north input -direction, false `fight_wild`/`may_lose`, true `yes`, and zero `battles`. In -particular, `yes: false` survives. A north action direction is an input parameter; -an absent pose facing remains unknown. Zero coordinates and zero quantities or -leg counts remain intact. Structural encoding does not approve a zero-quantity -shop request or prove a route feasible; native authoring/execution validation -still applies after binding. - -Unknown fields, action/position tags, malformed pairs, duplicate event IDs and -invalid primitive types fail. Native non-tile `Position` subtypes are unsupported -rather than converted to an empty belief. The first FRLG/BDSP adapters will bind -these tile poses to their runtime-local frames through pinned map identities. +A step names an `action` (empty: its kind's default) and the `args` that action +takes. The built-in actions are `route` and `ready` (`target` pose), `legs` +(`legs`, `fight_wild`), `face` (`direction`), `answer` (`yes`), `fight` +(`may_lose`), `train` (`battles`) and `shop` (`items`); a game adds its own, +each arg typed (boolean, integer, word, direction, grid_pose, legs, words, +items, integer_rows, timed_legs) and required or given a fallback. Both readers +check the args against the action's spec and fill in the fallbacks. Native +`MASH` is named `scene`; `GAME` is `game_action` and must name its action. + +A pose is `{"map", "tiles", "facing"}`: several tiles are alternatives, no tiles +is any tile of the map, and an absent facing is unknown. A `start` or +`declared_after` may instead be a zone, `{"place", "spot", "heading"}`, for a +game with no tiles. A `declared_after` is the fallback declaration, not an +observation. Unknown fields, kinds, actions and args, missing required args, +malformed pairs, duplicate event IDs and invalid primitive types fail. + +The authored plans in `data/story/` and the replay still use the older record +(poses with `certainty`/`where`, per-kind step fields, `variant`, `sections` +and `notes`), read by `read_checkpoint`; the native reader no longer reads it. ## Validation and next slice -`data/story/wire-conformance.json` contains synthetic input/expectation vectors -for every common step kind and the difficult defaults/uncertainty cases. Python -and the native executable consume the same data. Native-only cases cover the -in-memory boundary. These tests are not captured controller replay. +`data/story/wire-conformance.json` (`pokesim-story-wire-cases/2`) holds +synthetic input/expectation vectors for every step kind, the built-in and test +game actions (declared in its `actions`), poses and checkpoints. An accepted +case's `read` is the record as read, args with their fallbacks. Python and the +native reader consume the same file. These tests are not captured controller +replay. Next, export evaluated FRLG `00.05` and BDSP `01.03` through game adapters that populate the shared envelope, then compare all native fields and policy/state diff --git a/src/pokesim/formats/test_json_schema.py b/src/pokesim/formats/test_json_schema.py index b14a01d..aa56d94 100644 --- a/src/pokesim/formats/test_json_schema.py +++ b/src/pokesim/formats/test_json_schema.py @@ -48,21 +48,6 @@ def test_schemas_are_valid_and_published_data_passes(self): if name == 'runtime-map-v2': validate_map(value) - def test_story_vectors_and_canonical_records(self): - schema = json.loads((SCHEMAS / 'story-checkpoint.schema.json').read_text()) - cases = json.loads((ROOT / 'data/story/wire-conformance.json').read_text())['cases'] - for row in cases: - record = row['input']['record'] - selected = schema if record == 'checkpoint' else { - '$schema': schema['$schema'], '$defs': schema['$defs'], '$ref': '#/$defs/' + record} - check = jsonschema.Draft202012Validator(selected) - with self.subTest(name=row['input']['name']): - if 'canonical' in row['expectation']: - check.validate(row['input']['value']) - check.validate(row['expectation']['canonical']) - elif record != 'checkpoint' or 'duplicate' not in row['input']['name']: - self.assertFalse(check.is_valid(row['input']['value'])) - def test_map_pair_types_and_pickup_defaults(self): source = json.loads((ROOT / 'data/games/bdsp/maps/runtime/OreburghMine.json').read_text()) check = validator('runtime-map-v2') diff --git a/src/pokesim/story/checkpoint_wire.py b/src/pokesim/story/checkpoint_wire.py index dac782d..fe38b79 100644 --- a/src/pokesim/story/checkpoint_wire.py +++ b/src/pokesim/story/checkpoint_wire.py @@ -1,10 +1,19 @@ -"""Read the shared native checkpoint wire records without executing any action. +"""Read the shared story records without executing any action. PYTHONPATH=src python3 -m pokesim.story.checkpoint_wire checkpoint.json -The common record preserves all StoryStep/TilePose fields. Entry requirements, -tracked state, save/failure/handoff policy and game bindings belong to the plan -envelope; these records alone do not establish a runnable plan or observations. +read_grid_pose, read_declared_pose, read_story_step and read_story_checkpoint +read the records Arduino-Source's native reader (Pokemon_StoryStepJson) reads: a +step names an action and its typed args, checked against the action's spec. +data/story/wire-conformance.json holds the cases both readers share. + +read_pose, read_step and read_checkpoint read the older authored record (poses +with certainty/where, per-kind step fields, sections and notes) that the +authored plans and the replay still use. + +Entry requirements, tracked state, save/failure/handoff policy and game bindings +belong to the plan envelope; these records alone do not establish a runnable +plan or observations. """ import argparse @@ -181,6 +190,241 @@ def read_checkpoint(value): return result +# The records Arduino-Source's Pokemon_StoryStepJson reads. + +ARG_TYPES = ('boolean', 'integer', 'word', 'direction', 'grid_pose', 'legs', 'words', 'items', + 'integer_rows', 'timed_legs') +PHASES = ('testing', 'verification', 'reproduction') +INT_MIN, INT_MAX = -2147483648, 2147483647 +INT64_MIN, INT64_MAX = -9223372036854775808, 9223372036854775807 + + +def required(key, type_): + return dict(key=key, type=type_, required=True) + + +def optional(key, type_, fallback=None): + spec = dict(key=key, type=type_, required=False) + if fallback is not None: + spec['fallback'] = fallback + return spec + + +# Pokemon_BuiltinStoryActions.cpp: each kind's usual way; a kind's first +# action is its default. +BUILTIN_ACTIONS = ( + dict(kind='route', name='route', args=[required('target', 'grid_pose'), optional('fight_wild', 'boolean', False)]), + dict(kind='ready', name='ready', args=[required('target', 'grid_pose')]), + dict(kind='legs', name='legs', args=[required('legs', 'legs'), optional('fight_wild', 'boolean', False)]), + dict(kind='step', name='face', args=[required('direction', 'direction')]), + dict(kind='answer', name='answer', args=[optional('yes', 'boolean', True)]), + dict(kind='battle', name='fight', args=[optional('may_lose', 'boolean', False)]), + dict(kind='train', name='train', args=[required('battles', 'integer')]), + dict(kind='shop', name='shop', args=[required('items', 'items')]), +) + + +def read_tiles(value): + tiles = [] + for tile in array(value): + if len(array(tile)) != 2: + raise ValueError('a tile needs two coordinates') + tiles.append([integer(n, INT_MIN, INT_MAX) for n in tile]) + return tiles + + +def read_grid_pose(value): + """{"map", "tiles"?, "facing"?}; no tiles reads as none (any tile, or a zone game).""" + root = fields(value, ('map', 'tiles', 'facing')) + result = dict(map=text(root['map']), tiles=read_tiles(root.get('tiles', []))) + if 'facing' in root: + result['facing'] = choice(root['facing'], DIRECTIONS) + return result + + +def read_declared_pose(value): + """A tile pose (grid pose with "map") or a zone one ({"place", "spot"?, "heading"?}).""" + if not isinstance(value, dict): + raise ValueError('expected declared pose object') + if ('map' in value) == ('place' in value): + raise ValueError('a declared pose has a "map" or a "place", not both or neither') + if 'map' in value: + return read_grid_pose(value) + root = fields(value, ('place', 'spot', 'heading')) + result = dict(place=text(root['place'])) + if 'spot' in root: + result['spot'] = text(root['spot']) + if 'heading' in root: + result['heading'] = integer(root['heading'], INT_MIN, INT_MAX) + return result + + +def read_strings(value): + return [text(v) for v in array(value)] + + +def read_items(value): + items = [] + for item in array(value): + fields(item, ('item', 'quantity')) + items.append(dict(item=text(item['item']), quantity=integer(item['quantity'], 0, INT64_MAX))) + return items + + +def read_arg(value, type_): + """One arg's value read as `type_` (StoryArgType).""" + if type_ == 'boolean': + if type(value) is not bool: + raise ValueError('expected boolean') + return value + if type_ == 'integer': + return integer(value, INT64_MIN, INT64_MAX) + if type_ == 'word': + return text(value) + if type_ == 'direction': + return choice(value, DIRECTIONS) + if type_ == 'grid_pose': + return read_grid_pose(value) + if type_ == 'legs': + legs = [] + for leg in array(value): + fields(leg, ('direction', 'tiles')) + legs.append(dict(direction=choice(leg['direction'], DIRECTIONS), tiles=integer(leg['tiles'], INT_MIN, INT_MAX))) + return legs + if type_ == 'words': + return read_strings(value) + if type_ == 'items': + return read_items(value) + if type_ == 'integer_rows': + return [[integer(n, INT64_MIN, INT64_MAX) for n in array(row)] for row in array(value)] + if type_ == 'timed_legs': + legs = [] + for leg in array(value): + if len(array(leg)) != 2: + raise ValueError('a timed leg is [turn degrees, ms]') + legs.append([integer(n, INT_MIN, INT_MAX) for n in leg]) + return legs + raise ValueError('unsupported story arg type: ' + str(type_)) + + +def read_action_specs(value): + """Actions a game adds to the built-in ones: [{"kind", "name", "args": [{"key", + "type", "required"?, "fallback"?}]}], the fallbacks read as their types.""" + actions = [] + for action in array(value): + fields(action, ('kind', 'name', 'args')) + args = [] + for arg in array(action['args']): + fields(arg, ('key', 'type', 'required', 'fallback')) + spec = dict(key=text(arg['key']), type=choice(arg['type'], ARG_TYPES), required=arg.get('required', False)) + if type(spec['required']) is not bool: + raise ValueError('expected boolean: required') + if 'fallback' in arg: + spec['fallback'] = read_arg(arg['fallback'], spec['type']) + args.append(spec) + actions.append(dict(kind=choice(action['kind'], KINDS), name=text(action['name']), args=args)) + return tuple(BUILTIN_ACTIONS) + tuple(actions) + + +def find_action(actions, kind, name): + """The action of `kind` named `name`; for no name, the kind's first.""" + for action in actions: + if action['kind'] == kind and (not name or action['name'] == name): + return action + return None + + +def read_step_args(value, action): + """The args read against `action`'s spec, with its fallbacks filled in.""" + specs = {arg['key']: arg for arg in (action['args'] if action else [])} + if not isinstance(value, dict): + raise ValueError('expected args object') + result = {} + for key, item in value.items(): + if key not in specs: + raise ValueError('unknown argument: ' + key) + result[key] = read_arg(item, specs[key]['type']) + for key, spec in specs.items(): + if spec['required'] and key not in result: + raise ValueError('missing argument: ' + key) + if key not in result and 'fallback' in spec: + result[key] = spec['fallback'] + return dict(sorted(result.items())) + + +def read_story_step(value, actions=BUILTIN_ACTIONS): + """A step: its action among `actions` (the kind's default when it names none), + its args read against that action's spec. Empty why, action and skip_if and a + false once_per_save read as absent.""" + root = fields(value, ('id', 'kind', 'why', 'action', 'args', 'skip_if', 'declared_after', 'once_per_save')) + result = dict(id=text(root['id']), kind=choice(root['kind'], KINDS)) + if not result['id']: + raise ValueError('empty story step id') + for key in ('why', 'action'): + if key in root and text(root[key]): + result[key] = root[key] + name = result.get('action', '') + if result['kind'] == 'game_action' and not name: + raise ValueError('game_action step names no action: ' + result['id']) + action = find_action(actions, result['kind'], name) + if action is None and name: + raise ValueError('unknown action: ' + name) + args = read_step_args(root.get('args', {}), action) + if args: + result['args'] = args + skip = read_strings(root.get('skip_if', [])) + if skip: + result['skip_if'] = skip + if 'declared_after' in root: + result['declared_after'] = read_declared_pose(root['declared_after']) + once = root.get('once_per_save', False) + if type(once) is not bool: + raise ValueError('expected boolean: once_per_save') + if once: + result['once_per_save'] = True + return result + + +def read_metadata(value): + root = fields(value, ('phase', 'verified', 'source', 'postconditions')) + result = {} + if 'phase' in root: + result['phase'] = choice(root['phase'], PHASES) + if 'verified' in root: + verified = fields(root['verified'], ('steps_hash', 'build', 'date', 'runs')) + result['verified'] = {key: text(verified[key]) for key in ('steps_hash', 'build', 'date', 'runs') + if key == 'steps_hash' or key in verified} + if 'source' in root: + result['source'] = text(root['source']) + if 'postconditions' in root: + post = fields(root['postconditions'], ('position', 'items', 'flags')) + result['postconditions'] = {} + if 'position' in post: + result['postconditions']['position'] = read_grid_pose(post['position']) + if 'items' in post: + result['postconditions']['items'] = read_items(post['items']) + if 'flags' in post: + result['postconditions']['flags'] = read_strings(post['flags']) + return result + + +def read_story_checkpoint(value, actions=BUILTIN_ACTIONS): + """A checkpoint's id, title, start, events (unique ids) and metadata.""" + root = fields(value, ('id', 'title', 'start', 'events', 'metadata')) + result = dict(id=text(root['id']), title=text(root['title'])) + if not result['id']: + raise ValueError('empty checkpoint id') + if 'start' in root: + result['start'] = read_declared_pose(root['start']) + result['events'] = [read_story_step(event, actions) for event in array(root['events'])] + names = [step['id'] for step in result['events']] + if len(names) != len(set(names)): + raise ValueError('duplicate story event ids') + if 'metadata' in root: + result['metadata'] = read_metadata(root['metadata']) + return result + + def main(): parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter) parser.add_argument('checkpoint', type=Path) diff --git a/src/pokesim/story/test_checkpoint_wire.py b/src/pokesim/story/test_checkpoint_wire.py index 14044b5..0ce0a94 100644 --- a/src/pokesim/story/test_checkpoint_wire.py +++ b/src/pokesim/story/test_checkpoint_wire.py @@ -1,8 +1,9 @@ -"""Shared semantic data vectors, also consumed by the native codec executable.""" +"""The shared story cases, which Arduino-Source's native reader also reads.""" import json from pathlib import Path import unittest -from .checkpoint_wire import read_pose, read_step, read_checkpoint +from .checkpoint_wire import (read_action_specs, read_declared_pose, read_grid_pose, read_story_checkpoint, + read_story_step) ROOT = Path(__file__).resolve().parents[3] @@ -10,7 +11,11 @@ class CheckpointWireTest(unittest.TestCase): def test_shared_native_vectors(self): data = json.loads((ROOT / 'data/story/wire-conformance.json').read_text()) - readers = dict(pose=read_pose, step=read_step, checkpoint=read_checkpoint) + self.assertEqual(data['format'], 'pokesim-story-wire-cases/2') + actions = read_action_specs(data['actions']) + readers = dict(pose=read_grid_pose, declared=read_declared_pose, + step=lambda value: read_story_step(value, actions), + checkpoint=lambda value: read_story_checkpoint(value, actions)) for case in data['cases']: value, expected = case['input'], case['expectation'] with self.subTest(name=value['name']): @@ -19,9 +24,19 @@ def test_shared_native_vectors(self): readers[value['record']](value['value']) else: actual = readers[value['record']](value['value']) - self.assertEqual(actual, expected['canonical']) + self.assertEqual(actual, expected['read']) self.assertEqual(readers[value['record']](actual), actual) + def test_game_actions_need_their_spec(self): + step = {'id': 'buy', 'kind': 'game_action', 'action': 'mart', 'args': {'map': 'M', 'budget': 1}} + with self.assertRaisesRegex(ValueError, 'unknown action'): + read_story_step(step) + + def test_fallback_is_read_as_its_type(self): + spec = [{'kind': 'game_action', 'name': 'x', 'args': [{'key': 'n', 'type': 'integer', 'fallback': True}]}] + with self.assertRaises(ValueError): + read_action_specs(spec) + if __name__ == '__main__': unittest.main()