ADR 0016: Planning vs Evaluation Solver Boundary

Status: Accepted for architectural direction.

Date: 2026-05-11.

Context

The app needs both current-state answers and future-path exploration.

These are related but not identical.

Evaluation asks whether a fixed state satisfies a requirement.

Planning asks whether some future state or sequence of future states exists.

Evaluation can include explicit hypothetical changes.

Planning introduces decision variables.

Mixing the two concepts would make endpoint semantics, solver routing, caching, and explanation much harder to reason about.

Decision

Separate evaluation_problem from planning_problem.

An evaluation_problem has:

published index;
fixed student state;
optional explicit hypothetical changes;
target;
requirement scope;
assumptions;
limits.

A planning_problem has:

published index;
starting student state;
target;
finite horizon;
decision variables;
planning constraints;
optional objectives;
assumptions;
limits.

The direct evaluator owns fixed-state evaluation.

CP, SAT, SMT, and package-resolver style adapters may participate in bounded planning.

Every candidate plan returned by a planning route should be validated by direct evaluation or an equivalent exact validation route for the claimed final state.

Consequences

Basic unlock and progress queries can stay fast and synchronous.

Planning queries can have explicit time limits, horizons, and completeness policies.

The backend can later move expensive planning to asynchronous jobs without changing evaluation endpoints.

The frontend can treat evaluation status as a stable answer and planning output as candidate exploration.

An infeasible bounded plan must not be described as global impossibility unless the bounds cover the full academic claim.

Alternatives Considered

Alternative 1: Treat Evaluation as Planning With Zero Horizon

This is mathematically possible.

It would make all queries look uniform.

It would also force simple current-state questions through planning machinery.

That adds complexity and weakens explanation clarity.

This alternative is rejected.

Alternative 2: Let Planning Endpoints Return Evaluation Status Directly

A planning endpoint could return the same status field without exposing horizon or search assumptions.

This would be misleading.

Planning output depends on bounded search.

The response must disclose those bounds.

This alternative is rejected.

Alternative 3: Delay Planning Boundary Until Implementation

The project could postpone the distinction.

However, backend endpoint specs will depend on this boundary.

This alternative is rejected.

Follow-Up

Define endpoint specs with separate evaluation and planning request shapes.

Define planning horizon representation.

Define validation requirements for returned candidate plans.