docs/map/validation.md

Validation Map — replicalab/utils/validation.py

Deterministic protocol validation against scenario constraints. Pure functions — no LLM calls, no side effects.

Tasks implemented: MOD 05

Public API

validate_protocol(protocol: Protocol, scenario: NormalizedScenarioPack) -> ValidationResult

Main entry point. Never raises — always returns a ValidationResult.

Checks run (in order):

1. _check_obvious_impossibilities — sample_size < 1, no controls, duration < 1
2. _check_duration_vs_time_limit — protocol days vs lab time_limit_days
3. _check_equipment_vocabulary — items vs available/booked/substitutable
4. _check_reagent_vocabulary — items vs in-stock/out-of-stock/substitutable
5. _check_required_element_coverage — protocol text vs hidden_reference_spec.required_elements

Result: valid=True only if zero ERROR-level issues.

Data Classes

IssueSeverity(str, Enum)

Value	Meaning
error	Hard failure — protocol cannot proceed
warning	Advisory — protocol is suboptimal but possible

ValidationIssue(BaseModel) — extra="forbid"

Field	Type	Example
severity	IssueSeverity	ERROR
category	str	"equipment", "duration", "sample_size"
message	str	"Equipment 'X' is booked and has no substitution."

ValidationResult(BaseModel) — extra="forbid"

Field	Type
valid	bool
issues	list[ValidationIssue]

Properties:

• errors → list[ValidationIssue] (severity=ERROR only)
• warnings → list[ValidationIssue] (severity=WARNING only)

Check Details

_check_obvious_impossibilities

Condition	Severity	Category
sample_size < 1	ERROR	sample_size
controls empty	WARNING	controls
duration_days < 1	ERROR	duration

_check_duration_vs_time_limit

Condition	Severity	Category
duration_days > time_limit_days	ERROR	duration

_check_equipment_vocabulary

Condition	Severity	Category
Item available	— (pass)	—
Item booked + has substitution	WARNING	equipment
Item booked + no substitution	ERROR	equipment
Item unknown (not in inventory)	WARNING	equipment

_check_reagent_vocabulary

Condition	Severity	Category
Item in stock	— (pass)	—
Item out of stock + has substitution	WARNING	reagent
Item out of stock + no substitution	ERROR	reagent
Item unknown (not in inventory)	WARNING	reagent

_check_required_element_coverage

Checks each hidden_reference_spec.required_elements against protocol text fields using token matching.

Protocol text searched: technique, rationale, controls, equipment, reagents (joined, lowercased). Token extraction: _element_tokens(element) splits on spaces, keeps tokens with 3+ chars. Match: any token from element found in protocol text → covered.

Condition	Severity	Category
Element not addressed	WARNING	required_element

Internal Helpers

Function	Purpose
_normalize(label)	Lowercase, strip, collapse whitespace
_element_tokens(element)	Split element string into searchable tokens (3+ chars)
_substitution_alternatives(scenario)	Set of normalized original items from allowed_substitutions

Who Consumes This

• lab_manager_policy.py — check_feasibility() calls validate_protocol() and wraps result in protocol DimensionCheck
• scoring/ (future) — JDG 01 rigor score will reuse _element_tokens for required element matching