Repository navigation
Description
Task
T-002a· Milestone M1 — Foundation · Size M · Priority P0 · Epic #1Implements FR-ORC-002 · FR-RUN-004
Branch
feat/t-002a-core-types-shared-enums-and— one task = one branch = one PR (doc 32 §6)
Summary
Implement roboprobe.core.types with the exact normative names and fields from doc 05 §1. These are the contracts every other module exchanges.
Context / motivation
Doc 05 marks these signatures as normative. Freezing them early is what allows the scenario, oracle, selection, storage and backend streams to be built in parallel (doc 22 §4).
Scope
In scope
- Enums:
ParamType,Verdict,FailureClass(valuesF-COL…F-INFRA),RunStatus,CampaignStatus(StrEnum). - Frozen pydantic v2 models:
Scenario,Proposal,Observation,OracleResult,RunOutcome. Traceas@dataclass(frozen=True, slots=True)with NumPy columns listed in doc 05 §1 plus__post_init__validation (equal lengths, monotonict, dtypes).TaskSpec(start/goal pose, tolerances, time-limit spec, nominal path reference, injected obstacles) andSutProfile(id, backend, config, config_hash) as frozen models (fields per doc 06 §1, §7 and doc 11sut_profiles).Pose2Dvalue object andJsonValuealias.
Out of scope
- Loading TaskSpec from YAML (T-027)
- Parquet serialisation of Trace (T-018)
- ParameterSpec/ScenarioSpace (T-020b — they live in
roboprobe.scenario)
Implementation guidance
- File:
backend/src/roboprobe/core/types.py(≤ 400 lines; if larger, split intocore/types/package re-exported fromcore/types/__init__.py). - Copy names/field order exactly from doc 05 §1.
Proposal.phasevalues:warmup | falsify | mode_search | boundary | refine | explore | baseline | manual | confirm | replay(doc 11runs.phase) — use aLiteralaliasPhase. Observation.robustnessisNoneiffverdict == INVALID— enforce with a model validator.OracleResult.robustnessandRunOutcome.robustnessconstrained to[-1, 1](Field(ge=-1, le=1)).Trace.duration_sandTrace.n_samplesconvenience properties; no I/O in this module.- Docstrings: Google style +
Implements:line (doc 16 §3). - 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
- All names/fields match doc 05 §1 (reviewer diff-checks).
- Models are immutable (assignment raises).
- Invalid robustness (e.g. 1.5) and mismatched trace column lengths raise
pydantic.ValidationError/ValueErrorwith clear messages. -
mypy --strictclean; 100 % line coverage ofcore/types.py. - 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/core/test_types.py: construction, immutability, validators, enum string values (FailureClass.COL == 'F-COL').- Hypothesis property: any valid
Observationround-trips throughmodel_dump_json/model_validate_json.
Dependencies
Blocked by: #12 (T-001)
Blocks: #25 (T-017), #59 (T-010a), #66 (T-013a), #33 (T-020b), #40 (T-027), #42 (T-016), #43 (T-030a), #45 (T-031a), #46 (T-031b), #47 (T-018), #48 (T-035a), #68 (T-036a), #79 (T-041c)
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/core/types.pybackend/tests/unit/core/test_types.py
Owns only core/types.py. Parallel with T-002b/c/d, T-003a, T-009. Interface freeze: after merge, changes require updating doc 05 (DoD).
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-002a (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 §1 · doc 05 §0 · doc 06 §1 · doc 06 §7 · doc 11 §6.2 · doc 34 §7
Requirements: FR-ORC-002 · FR-RUN-004 (traceability: doc 28)
External:
Metadata
Metadata
Assignees
Labels
Projects
- StatusShow more project fieldsDone
Activity
warehouse_v1.yaml#33tasks/warehouse_delivery_v1.yaml(time-limit formula, TBD guard) #40configs/sut_profiles/(k2d default + TB4 Nav2 default) #42