ADR 0006: Stable public strategy ids

Status:

Accepted

Context

Strategy ids are persisted on Games.strategyId / Tasks.strategyId and returned by the API. Tying them to Python class names would break stored data on any class rename or file move. An earlier version discovered strategies by scanning the filesystem and picking classes by a naming convention, which was brittle and working-directory dependent.

Decision

Strategy classes opt in by decorating with @register_strategy(id=..., version=...) (app/engine/strategy_registry.py). The decorator stamps a __strategy_id__ and registers the class under that public id, which is documented to remain stable across class renames or file moves. Discovery is now CWD-independent via pkgutil.iter_modules over app/engine (app/engine/all_engine_strategies.py).

Consequences

  • Class and file renames are safe; stored strategyId values keep resolving.

  • Registering two strategies under the same id fails loudly at import.

  • Strategy code is trusted (in-process), unlike the sandboxed DSL.

See also