Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions docs/story/CHECKPOINT_CONTRACT.md
Original file line number Diff line number Diff line change
Expand Up @@ -93,6 +93,9 @@ 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.
`schemas/story-checkpoint.schema.json` describes only that older record, not
the v2 common record. For v2, `pokesim.story.checkpoint_wire` and
`data/story/wire-conformance.json` are authoritative.

## Validation and next slice

Expand Down
3 changes: 2 additions & 1 deletion schemas/story-checkpoint.schema.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,8 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://raw.githubusercontent.com/dayfine/PokemonSimulation/main/schemas/story-checkpoint.schema.json",
"title": "Common native story checkpoint",
"title": "Legacy authored story checkpoint",
"description": "Legacy certainty/where and sections format read by read_checkpoint; v2 is defined by checkpoint_wire.py and data/story/wire-conformance.json.",
"type": "object",
"properties": {
"id": {"type": "string", "minLength": 1},
Expand Down
109 changes: 71 additions & 38 deletions src/pokesim/story/checkpoint_wire.py
Original file line number Diff line number Diff line change
Expand Up @@ -29,11 +29,24 @@


def fields(value, allowed):
if not isinstance(value, dict) or set(value) - set(allowed):
raise ValueError('expected record with only fields: ' + ', '.join(allowed))
if not isinstance(value, dict):
raise ValueError('expected record')
unsupported = set(value) - set(allowed)
if unsupported:
raise ValueError('unsupported field: ' + str(min(unsupported, key=str)))
return value


def field(value, name, reader):
"""Read required field `name`, naming it when absent or malformed."""
if name not in value:
raise ValueError('missing field: ' + name)
try:
return reader(value[name])
except ValueError as error:
raise ValueError(name + ': ' + str(error)) from error


def text(value):
if not isinstance(value, str):
raise ValueError('expected string')
Expand All @@ -58,6 +71,12 @@ def array(value):
return value


def boolean(value):
if type(value) is not bool:
raise ValueError('expected boolean')
return value


def read_args(value):
"""A step's args: flags, whole numbers and words by name, as the step's
action declares them in the game's C++ (StoryArgSpec); this reader checks
Expand Down Expand Up @@ -236,9 +255,11 @@ def read_tiles(value):
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', [])))
result = dict(map=field(root, 'map', text), tiles=[])
if 'tiles' in root:
result['tiles'] = field(root, 'tiles', read_tiles)
if 'facing' in root:
result['facing'] = choice(root['facing'], DIRECTIONS)
result['facing'] = field(root, 'facing', lambda item: choice(item, DIRECTIONS))
return result


Expand All @@ -251,11 +272,11 @@ def read_declared_pose(value):
if 'map' in value:
return read_grid_pose(value)
root = fields(value, ('place', 'spot', 'heading'))
result = dict(place=text(root['place']))
result = dict(place=field(root, 'place', text))
if 'spot' in root:
result['spot'] = text(root['spot'])
result['spot'] = field(root, 'spot', text)
if 'heading' in root:
result['heading'] = integer(root['heading'], INT_MIN, INT_MAX)
result['heading'] = field(root, 'heading', lambda item: integer(item, INT_MIN, INT_MAX))
return result


Expand All @@ -267,7 +288,8 @@ 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)))
items.append(dict(item=field(item, 'item', text),
quantity=field(item, 'quantity', lambda number: integer(number, 0, INT64_MAX))))
return items


Expand All @@ -289,7 +311,8 @@ def read_arg(value, type_):
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)))
legs.append(dict(direction=field(leg, 'direction', lambda item: choice(item, DIRECTIONS)),
tiles=field(leg, 'tiles', lambda number: integer(number, INT_MIN, INT_MAX))))
return legs
if type_ == 'words':
return read_strings(value)
Expand All @@ -314,15 +337,18 @@ def read_action_specs(value):
for action in array(value):
fields(action, ('kind', 'name', 'args'))
args = []
for arg in array(action['args']):
for arg in field(action, 'args', array):
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')
spec = dict(key=field(arg, 'key', text),
type=field(arg, 'type', lambda item: choice(item, ARG_TYPES)),
required=field(arg, 'required', boolean) if 'required' in arg else False)
if spec['required'] and 'fallback' in arg:
raise ValueError('fallback: required argument cannot have a fallback: ' + spec['key'])
if 'fallback' in arg:
spec['fallback'] = read_arg(arg['fallback'], spec['type'])
spec['fallback'] = field(arg, 'fallback', lambda item: read_arg(item, spec['type']))
args.append(spec)
actions.append(dict(kind=choice(action['kind'], KINDS), name=text(action['name']), args=args))
actions.append(dict(kind=field(action, 'kind', lambda item: choice(item, KINDS)),
name=field(action, 'name', text), args=args))
return tuple(BUILTIN_ACTIONS) + tuple(actions)


Expand All @@ -343,7 +369,10 @@ def read_step_args(value, action):
for key, item in value.items():
if key not in specs:
raise ValueError('unknown argument: ' + key)
result[key] = read_arg(item, specs[key]['type'])
try:
result[key] = read_arg(item, specs[key]['type'])
except ValueError as error:
raise ValueError('argument ' + key + ': ' + str(error)) from error
for key, spec in specs.items():
if spec['required'] and key not in result:
raise ValueError('missing argument: ' + key)
Expand All @@ -357,29 +386,30 @@ def read_story_step(value, actions=BUILTIN_ACTIONS):
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))
result = dict(id=field(root, 'id', text), kind=field(root, 'kind', lambda item: choice(item, KINDS)))
if not result['id']:
raise ValueError('empty story step id')
for key in ('why', 'action'):
if key in root and text(root[key]):
if key in root and field(root, key, text):
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)
raise ValueError('action: unknown action: ' + name)
try:
args = read_step_args(root.get('args', {}), action)
except ValueError as error:
raise ValueError('args: ' + str(error)) from error
if args:
result['args'] = args
skip = read_strings(root.get('skip_if', []))
skip = field(root, 'skip_if', read_strings) if 'skip_if' in root else []
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')
result['declared_after'] = field(root, 'declared_after', read_declared_pose)
once = field(root, 'once_per_save', boolean) if 'once_per_save' in root else False
if once:
result['once_per_save'] = True
return result
Expand All @@ -389,39 +419,42 @@ def read_metadata(value):
root = fields(value, ('phase', 'verified', 'source', 'postconditions'))
result = {}
if 'phase' in root:
result['phase'] = choice(root['phase'], PHASES)
result['phase'] = field(root, 'phase', lambda item: choice(item, 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}
verified = field(root, 'verified', lambda item: fields(item, ('steps_hash', 'build', 'date', 'runs')))
result['verified'] = {'steps_hash': field(verified, 'steps_hash', text)}
for key in ('build', 'date', 'runs'):
if key in verified:
result['verified'][key] = field(verified, key, text)
if 'source' in root:
result['source'] = text(root['source'])
result['source'] = field(root, 'source', text)
if 'postconditions' in root:
post = fields(root['postconditions'], ('position', 'items', 'flags'))
post = field(root, 'postconditions', lambda item: fields(item, ('position', 'items', 'flags')))
result['postconditions'] = {}
if 'position' in post:
result['postconditions']['position'] = read_grid_pose(post['position'])
result['postconditions']['position'] = field(post, 'position', read_grid_pose)
if 'items' in post:
result['postconditions']['items'] = read_items(post['items'])
result['postconditions']['items'] = field(post, 'items', read_items)
if 'flags' in post:
result['postconditions']['flags'] = read_strings(post['flags'])
result['postconditions']['flags'] = field(post, 'flags', read_strings)
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']))
result = dict(id=field(root, 'id', text), title=field(root, 'title', text))
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'])]
result['start'] = field(root, 'start', read_declared_pose)
events = field(root, 'events', array)
result['events'] = [read_story_step(event, actions) for event in 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'])
result['metadata'] = field(root, 'metadata', read_metadata)
return result


Expand Down
26 changes: 25 additions & 1 deletion src/pokesim/story/test_checkpoint_wire.py
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ def test_shared_native_vectors(self):
value, expected = case['input'], case['expectation']
with self.subTest(name=value['name']):
if expected.get('rejected'):
with self.assertRaises((ValueError, KeyError, TypeError)):
with self.assertRaises(ValueError):
readers[value['record']](value['value'])
else:
actual = readers[value['record']](value['value'])
Expand All @@ -37,6 +37,30 @@ def test_fallback_is_read_as_its_type(self):
with self.assertRaises(ValueError):
read_action_specs(spec)

def test_required_arg_cannot_have_a_fallback(self):
spec = [{'kind': 'game_action', 'name': 'x',
'args': [{'key': 'n', 'type': 'integer', 'required': True, 'fallback': 1}]}]
with self.assertRaisesRegex(ValueError, 'required argument cannot have a fallback'):
read_action_specs(spec)

def test_invalid_records_raise_field_level_value_errors(self):
cases = (
('pose map', read_grid_pose, {}, 'missing field: map'),
('declared place', read_declared_pose, {'place': 1}, 'place: expected string'),
('action args', read_action_specs, [{'kind': 'game_action', 'name': 'x'}], 'missing field: args'),
('step id', read_story_step, {'kind': 'talk'}, 'missing field: id'),
('checkpoint events', read_story_checkpoint, {'id': 'x', 'title': 'X'}, 'missing field: events'),
('item quantity', read_story_step,
{'id': 'shop', 'kind': 'shop', 'args': {'items': [{'item': 'potion'}]}},
'argument items: missing field: quantity'),
('verification hash', read_story_checkpoint,
{'id': 'x', 'title': 'X', 'events': [], 'metadata': {'verified': {}}},
'missing field: steps_hash'),
)
for name, reader, value, message in cases:
with self.subTest(name=name), self.assertRaisesRegex(ValueError, message):
reader(value)


if __name__ == '__main__':
unittest.main()
Loading