feat: cooked up something fierce

src/authoring/select.rs

@@ -33,8 +33,9 @@ use crate::course::{CourseFile, SCHEMA_VERSION};
 use crate::date::Date;
 use crate::error::{Error, Result};
 use crate::history::History;
+use crate::item::{Choice, Item};
 use crate::rng::Rng;
-use crate::taxonomy::Level;
+use crate::taxonomy::{Format, Level};
 
 /// The result of a draw.
 #[derive(Debug, Clone)]
@@ -466,15 +467,23 @@ pub fn to_record(
             .chain(selection.bonus.iter().map(|u| (u, true))),
     ) {
         let e = catalog.require(uid)?;
+        let (key, distractors) = draw_options(
+            &e.item,
+            catalog.course.policy.options_per_item,
+            blueprint.seed.unwrap_or(0),
+            uid,
+        );
         items.push(Placement {
             number,
             item: uid.clone(),
             version: None,
             stem_digest: Some(e.item.stem_digest()),
+            variant: Some(e.item.variant_digest(&key, &distractors)),
             fingerprint: Some(e.item.fingerprint()),
             points: Some(e.item.points(default_points)),
             bonus: is_bonus || e.item.bonus,
-            key: e.item.key_letters(),
+            distractors,
+            key,
             level: Some(e.item.level),
             learning_targets: e.item.learning_targets.clone(),
             credit_overrides: BTreeMap::new(),
@@ -571,6 +580,85 @@ pub fn layout(record: &AssessmentFile, form: &Form) -> Vec<Placement> {
     scored.into_iter().chain(bonus).collect()
 }
 
+/// Draws the key and the distractors one placement administers.
+///
+/// Resolved here, at assembly, and written into the record as explicit lists.
+/// Nothing downstream samples: an export that drew its own options would print
+/// a different paper every time the bank was touched.
+///
+/// The draw is seeded on the blueprint and the item, so re-running `assemble`
+/// with the same seed produces the same paper, and two items in one assessment
+/// draw independently.
+///
+/// # Arguments
+///
+/// * `item` - the item, whose options are a pool.
+/// * `per_item` - how many options a form shows, from course policy.
+/// * `seed` - the blueprint seed.
+/// * `uid` - the item id, salting the draw.
+///
+/// # Returns
+///
+/// The keyed ids and the distractor ids, each sorted, naming options of `item`.
+/// Both empty for an item with no options, which is an open response.
+pub fn draw_options(
+    item: &Item,
+    per_item: usize,
+    seed: u64,
+    uid: &str,
+) -> (Vec<String>, Vec<String>) {
+    let (keys, distractors) = item.pool();
+    if keys.is_empty() && distractors.is_empty() {
+        return (Vec::new(), Vec::new());
+    }
+
+    // Multiple response keys every correct option; anything else keys one, and
+    // when the pool offers several defensible keys the draw picks one so that
+    // the record says which.
+    let wanted_keys = match item.format {
+        Format::MultipleResponse => keys.len(),
+        _ => 1.min(keys.len()),
+    };
+    let mut rng = Rng::from_label(&format!("{seed}/{uid}/options"));
+
+    let mut key_ids = pick(&keys, wanted_keys, &mut rng);
+    key_ids.sort();
+
+    // A pool with fewer usable distractors than the policy asks for is a
+    // finding, not a failure: the form comes out short and `lint` says so,
+    // rather than `assemble` refusing to build the assessment at all.
+    let wanted = per_item.saturating_sub(key_ids.len());
+    let mut distractor_ids = pick(&distractors, wanted.min(distractors.len()), &mut rng);
+    distractor_ids.sort();
+
+    (key_ids, distractor_ids)
+}
+
+/// Takes `n` options, preferring the ones that were designed rather than merely
+/// written.
+///
+/// A distractor carrying a misconception and an error type is one you thought
+/// about; one carrying neither is filler. When the pool is larger than the form,
+/// the thought-about ones go on the paper. The shuffle comes first so that
+/// options of equal standing are drawn by seed rather than by declaration
+/// order.
+fn pick(options: &[&Choice], n: usize, rng: &mut Rng) -> Vec<String> {
+    if n >= options.len() {
+        return options.iter().map(|o| o.id.clone()).collect();
+    }
+    let mut order: Vec<usize> = (0..options.len()).collect();
+    rng.shuffle(&mut order);
+    order.sort_by_key(|&i| {
+        let o = options[i];
+        u8::from(o.misconception.is_none()) + u8::from(o.error_type.is_none())
+    });
+    order
+        .into_iter()
+        .take(n)
+        .map(|i| options[i].id.clone())
+        .collect()
+}
+
 /// The option order for one item on one form.
 ///
 /// # Arguments
@@ -693,6 +781,68 @@ mod tests {
         assert_eq!(form_label(27), "AB");
     }
 
+    /// An item whose options are given as YAML, so the test needs no literal.
+    fn pool_item(options: &str) -> Item {
+        let src = format!(
+            r#"id: q-x
+status: approved
+level: 1
+cognitive_process: recall
+stem: Which line holds the quality scores?
+learning_targets: [t-x]
+sources: [{{ lecture: L1 }}]
+options:
+{options}"#
+        );
+        serde_yaml_ng::from_str(&src).expect("item parses")
+    }
+
+    const DESIGNED: &str = r#"  - { id: o-key, text: right, correct: true }
+  - { id: o-designed-a, text: a, misconception: mistakes the separator, error_type: recall_confusion }
+  - { id: o-designed-b, text: b, misconception: confuses the two, error_type: recall_confusion }
+  - { id: o-filler-a, text: c }
+  - { id: o-filler-b, text: d }
+"#;
+
+    #[test]
+    fn a_draw_prefers_designed_distractors_and_is_reproducible() {
+        let item = pool_item(DESIGNED);
+
+        let (key, distractors) = draw_options(&item, 3, 1103, "q-x");
+        assert_eq!(key, vec!["o-key".to_string()]);
+        assert_eq!(distractors.len(), 2);
+        // Thought-about distractors go on the paper before filler does.
+        assert!(
+            distractors.iter().all(|d| d.starts_with("o-designed")),
+            "{distractors:?}"
+        );
+
+        // Same seed, same paper.
+        assert_eq!(draw_options(&item, 3, 1103, "q-x"), (key, distractors));
+
+        // A retired option is not drawn, and the form comes out of the rest.
+        let retired = pool_item(&DESIGNED.replace(
+            "{ id: o-designed-a, text: a,",
+            "{ id: o-designed-a, text: a, retired: { 'on': 2026-09-20, reason: nonfunctioning },",
+        ));
+        let (_, after) = draw_options(&retired, 3, 1103, "q-x");
+        assert!(!after.iter().any(|d| d == "o-designed-a"), "{after:?}");
+    }
+
+    #[test]
+    fn a_thin_pool_comes_out_short_rather_than_refusing_to_build() {
+        let item = pool_item(
+            "  - { id: o-key, text: right, correct: true }\n  - { id: o-one, text: wrong }\n",
+        );
+        let (key, distractors) = draw_options(&item, 4, 7, "q-y");
+        assert_eq!(key.len(), 1);
+        assert_eq!(
+            distractors.len(),
+            1,
+            "one usable distractor, so one is drawn"
+        );
+    }
+
     #[test]
     fn option_order_is_a_reproducible_permutation() {
         let form = Form {