Exercise-session generation.

The pipeline.

One session generation, end to end. The planner is pure (no database, no clock read), so the plan is reproducible from the state snapshot and the session seed.

The six stages of grid().

Signature: grid(skind, &[LpState], base_lambda, n0, salt) -> Vec<Slot>. Returns empty for session kinds the grid does not own (Recalibrate, Project, Freeform, Placement), which fall back to the free-form prompt path.

Data structures.

Input snapshot and output slot. Both in sessions/grid.rs.

LpState, assembled by build_lp_states()

Slot, one exercise the AI must author

Groups, floors and base mix.

Six cognitive tiers are the unit of proportion. true_false is deliberately absent from every member list, because it is injected orthogonally and is never a quota kind.

base_mix(bloom) gives the percentage per tier at neutral band, λ = 0. floor_group_tier(bloom) is the lowest tier that carries mass for apply-and-above; below it the mix is zeroed and renormalised.

The floor is applied only for bloom.tier() >= 3; for remember and understand the lower tiers stay legal. A separate per-kind floor, bloom::kind_violates_floor, removes individual kinds from the offered set (for example mcq and writing are both illegal on an Apply point: one too low, one too high).

Calibration constants.

All tunable; these are the v1 defaults actually compiled in.

target_exercise_count(kind, duration_min) = base × clamp(duration/30, 0.5, 2.0), rounded, minimum 1.

depth_tilt(learning_depth) maps the course brief's depth string to λ by substring match:

A strong band with struggle below STRUGGLE_LOW adds +0.5 to λ (a stretch notch), never on an exam.

Prompt assembly.

Two layers. The system prompt (SESSION_EXERCISES_SYSTEM_PROMPT, DB-overridable via the prompt registry) carries the JSON envelope, the per-kind data shapes, the alignment rules, the strict MCQ-correctness rules and the self-contained-text rule. The user prompt is built per call by build_user_prompt() and then extended by append_grid_plan().

Request parameters: json_mode = true, temperature = 0.7, max_tokens = 8192, plus a JSON schema (exercises_response_schema()) unless the skill is in free-form mode.

Validation and persistence.

Up to MAX_ATTEMPTS = 3 cycles. All problems in a response are collected and fed back together, so one regeneration fixes them all; a provider or network error does not burn a retry.

• Count. The response must contain exactly one exercise per plan item.
• Kind. slot.allowed_kinds.contains(ex.kind) or the item is rejected by name and index. This is the hard boundary: the AI cannot escape the grid's tier decision.
• Shape. schema::validate_data(kind, data) rejects schema-valid-but-empty content, such as a fill_blank with a blank expected. A bad item is never silently dropped, because that would leave a pedagogically incomplete session.
• Persistence. write_exercises() deletes this session's freshly-authored exercises and reinserts, so regeneration is idempotent. Reused references (session_exercise_refs.reused = 1) are excluded from the cascade so a shared prior-session exercise survives.
• Parallel arrays. scaffolds and transfer_probes are index-aligned with the merged exercise list and written to exercises.scaffold_level and questions.transfer_probe. The probe flag is an intrinsic authoring fact, read identically by live submission and by replay, so a regrade cannot disagree with the original grading.
• What this loop does not check. All of the above verify structure: how many items came back, which kind each one is, and whether its fields are populated and internally consistent. None of them reads the exercise. Nothing here decides whether a statement is true, whether an answer key is right, whether the question actually tests the concept it is attached to, or whether the wording is answerable at all. Those rules exist — they are written into the generation prompt above — but a prompt states a rule, it does not enforce one, and this is the only place enforcement could happen. It is a real gap, it is named here on purpose, and it is why an exercise you find wrong or nonsensical is worth reporting.

Session composition (which concepts).

Upstream of the grid, compose.rs selects which learning points a session targets. Also pure. Retrieval kinds recompose skill-wide rather than trusting the plan's pinned list.

1. Due queue. Due candidates sorted by ascending retrievability, tie-broken by higher goal leverage, then lower stability, then id. Most-overdue-first.
2. Budget split. budget_split(debt, k, mandate, nu). A Review mandate is pure consolidation. A Course mandate reserves a new floor of round(k · 0.3 · (0.5 + nu)), clamped to at least 1 and at most the nominal ceiling, unless debt reaches 2·k, at which point new material is dropped entirely and the session becomes catch-up.
3. Top-up. If the due queue cannot fill the review pool, encoded-but-not-due items are added nearest-to-due first. Never-started items are excluded, because those are new material rather than review.
4. Interleave. Review and new picks are alternated rather than blocked, for discriminative spacing.
5. Serving order. The step above orders the concepts; the grid then emits every slot of one concept before moving to the next, so a session composed as an alternation could still be served in blocks. A final pass spaces them out, and it is conditional on what you already know: a concept you have answered before has its items dealt round-robin against the others, while a concept you are meeting for the first time keeps its items together. Interleaving buys the ability to tell methods apart, which is only worth its switching cost once you can carry out the method at all — so consolidation comes first, discrimination after. The two groups are then served due material first, new material after: whoever stops a session early loses what came last, and a missed review costs retention on something already learnt while a postponed first encounter costs only progress.

Enforced invariants.

These hold by construction inside grid() and are covered by unit tests. They are properties of the offered set, so no AI choice can violate them.