Temporal Engine

Status & scope

Module: lens/temporal/
Milestone: Phase 2 (complete)

Purpose

Action window optimization: intersect time-varying constraints, find optimal departure time, detect constraint conflicts. Answers "when should we move?"

Public API

`compute_action_windows(constraints, time_range) → ActionWindows`

Intersect boolean time constraints. Score viable windows by composite favorability.

`optimal_departure(route_cost_fn, time_range, step) → OptimalDeparture`

Evaluate route cost at departure times, find minimum. Sensitivity curve.

`detect_conflicts(constraints) → list[Conflict]`

Find time intervals where constraints are mutually exclusive.

Cost Models

Name	Function
window_score	Favorability of a time window (weather, coverage, darkness)
urgency_decay	Penalty increasing with delay from ideal departure

File Layout

lens/temporal/
  __init__.py
  windows.py         ← ActionWindows, constraint aggregation
  optimizer.py        ← OptimalDeparture, sensitivity curve
  conflict.py         ← Conflict detection
  cost_models.py      ← Temporal cost functions

Test References

tests/test_windows.py — constraint intersection, min window filter
tests/test_optimizer.py — optimal departure, sensitivity

DO NOT

Build a workflow engine — temporal lens finds windows, doesn't execute actions
Auto-route based on temporal output — human decides departure (Invariant 6)

Depends on: component.prism.cost-primitives, component.prism.universal-lens-parser