Repository navigation
Description
Task
T-020b· Milestone M2 — Scenario + kinematic2d · Size M · Priority P0 · Epic #2Implements FR-SCN-001 · FR-SCN-002 · NFR-SEC-003
Branch
feat/t-020b-scenariospace-parameterspec-models-yaml-loader— one task = one branch = one PR (doc 32 §6)
Summary
Implement ParameterSpec, PriorSpec, Constraint and ScenarioSpace.from_yaml() (doc 05 §3) with schema validation, semantic checks and space versioning (version = sha256(canonical YAML)[:12]), and ship configs/scenario_spaces/warehouse_v1.yaml (doc 06 §2/§4).
Context / motivation
The scenario space is the input to everything (selector, backends, risk maps). It must be strict: yaml.safe_load only (TM-02), precise errors, enabled flags for P7/P8.
Scope
In scope
backend/src/roboprobe/scenario/space.py:ParameterSpec,PriorSpec(uniform | loguniform | normal(trunc) | beta | discrete),ScenarioSpacewithfrom_yaml,dim,nominal(),params(enabled only),is_feasible(delegates to constraints when T-022 lands; returns True meanwhile).- Semantic checks: unique ids, nominal within bounds, log scale requires
low > 0, categorical has ≥ 2 choices, constraint expressions reference known ids. configs/scenario_spaces/warehouse_v1.yaml= doc 06 §4 (P1–P8, P7/P8enabled: falseby default).- Size limit on YAML input (bytes) from settings (
api.max_upload_mbreuse) and duplicate-key rejection.
Out of scope
- Normalisation (T-021)
- Constraint evaluator (T-022)
- Hashing (T-024)
- Pins (T-025)
- CLI
space validate(T-045a)
Implementation guidance
versionis computed from the canonical JSON of the parsed definition (not raw YAML bytes) so whitespace/comment edits don't change it — confirm against doc 06 note and document the decision in the docstring.- Errors: raise
ValidationError(code=SPACE_INVALID, context={"errors": [{"path": "/parameters/2/low", "message": ...}]}). to_unit/from_unit/make_scenarioare declared here but implemented in T-021/T-024 — leaveNotImplementedErrorstubs only if needed; preferably merge T-021 shortly after.- Standards: respect the layering contracts (doc 16 §2) and conventions in doc 34; no hard-coded tunables — thresholds/defaults come from typed settings (doc 27); no magic numbers (ruff
PLR2004); public APIs typed (mypy strict) and documented.
Acceptance criteria
-
warehouse_v1.yamlloads;dim == 6with defaults,8with P7/P8 enabled. - Every invalid fixture yields a precise error path; unsafe YAML tags (
!!python/object) rejected. - Space version stable across processes and unchanged by comment/whitespace edits.
- Tests listed below added and green in CI; coverage of new code meets the gate in doc 18 §3.
- Docs, config reference and CHANGELOG
Unreleasedupdated where behaviour, keys or interfaces changed. - Definition of Done (doc 32 §3) satisfied.
Tests required
tests/unit/scenario/test_space_loader.py, fixturestests/fixtures/spaces/.
Dependencies
Blocked by: #32 (T-020a), #15 (T-002a), #16 (T-002b)
Blocks: #34 (T-021), #35 (T-022), #89 (T-045a), #146 (T-081a)
Parallelization notes
Files / paths owned by this task — avoid editing other paths; shared files (pyproject.toml entry points, cli/main.py, api/routers/__init__.py, router.tsx, docker/compose.yaml, ci.yml) are append-only:
backend/src/roboprobe/scenario/space.pyconfigs/scenario_spaces/warehouse_v1.yamlbackend/tests/unit/scenario/test_space_loader.pybackend/tests/fixtures/spaces/**
Owns scenario/space.py. T-021–T-025 each add their own module and only call into this one.
Definition of Done
Per doc 32 §3 and AGENTS.md §5: lint, format, mypy strict and import-linter green; tests added and passing; docs updated; PR template completed with Closes #<this issue>; Conventional Commit messages referencing T-020b (doc 16 §6); commits authored only by the repository owner identity (AGENTS.md §4); CI green; reviewer checklist (doc 32 §5.1) satisfied.
References
Design docs: doc 05 §3 · doc 06 §2 · doc 06 §4 · doc 06 §5 · doc 31 §3 · doc 02 §3.1
Requirements: FR-SCN-001 · FR-SCN-002 · NFR-SEC-003 (traceability: doc 28)
External:
Metadata
Metadata
Assignees
Labels
Projects
- StatusShow more project fieldsDone
Activity
db upgradeandspace validate|register|list#89