feat(learn): retrieval and the evaluation boundary (decision-engine 6.3)

learn/retrieve.py: stage 1 is a per-instrument Gower distance over the
profile's allow-listed features with explicit missing (both ran: mean
feature distance; differing states 1; same non-ran state 0; null in one 1;
priors dropped with priors=off), n1 = 40 with seeded tie-breaks; stage 2
re-ranks by r = lam(1 - D) + (1 - lam)cos, signals_only without the
target's vector; the balance rule takes k_ret = 6 (<= k/2 per label, <= 2
per group, <= 2 other families; `short` recorded). eligible() is the only
way into a prompt: not the target's group, not an evaluated group, not the
held-out source or framework, and outside deployment not a near-duplicate
(cos >= 0.98). assert_boundary repeats the check on rendered ids;
demonstrations of a held-out framework swap to their alternates;
deployment_fold excludes a scanned repository that is a corpus group;
seed_memory never hands a case its own group.

learn/folds.py: compile split (25% of groups per primary family, 60/40
boot/val), outer grouped 5-fold stratified by family and label mix,
leave-one-source-out, leave-one-framework-out (insufficient data below 10
groups), assert_disjoint and a folds digest; all seeded.

Tests: test_learn_retrieve.py (hand-computed Gower, lam 0/0.5, balance,
near-duplicates, test_boundary over outer/LOSO/LOFO folds with
demonstrations), test_learn_folds.py.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01EmM1j46qgKMh3zqD1QMwEo

benchmarks/measurements/2026-09-08-module-audit.json

@@ -1,7 +1,7 @@
 {
-  "modules": 147,
+  "modules": 149,
   "counts": {
-    "load_bearing": 140,
+    "load_bearing": 142,
     "standalone_capability": 7
   },
   "orphaned": [],
@@ -357,6 +357,8 @@
         "learn.examples",
         "learn.excerpt",
         "learn.features",
+        "learn.folds",
+        "learn.retrieve",
         "learn.roles",
         "plane.tasks.features",
         "plane.tasks.remember",
@@ -376,7 +378,8 @@
       "classification": "load_bearing",
       "reason": "reachable from gate, map_gate, pair_gate or the CLI",
       "importers": [
-        "learn.cli"
+        "learn.cli",
+        "learn.retrieve"
       ]
     },
     {
@@ -384,7 +387,9 @@
       "classification": "load_bearing",
       "reason": "reachable from gate, map_gate, pair_gate or the CLI",
       "importers": [
-        "learn.cli"
+        "learn.cli",
+        "learn.folds",
+        "learn.retrieve"
       ]
     },
     {
@@ -405,6 +410,14 @@
         "plane.tasks.features"
       ]
     },
+    {
+      "module": "learn.folds",
+      "classification": "load_bearing",
+      "reason": "imported by learn.retrieve",
+      "importers": [
+        "learn.retrieve"
+      ]
+    },
     {
       "module": "learn.labels",
       "classification": "load_bearing",
@@ -413,9 +426,16 @@
         "cli",
         "learn.cli",
         "learn.examples",
-        "learn.excerpt"
+        "learn.excerpt",
+        "learn.retrieve"
       ]
     },
+    {
+      "module": "learn.retrieve",
+      "classification": "load_bearing",
+      "reason": "learned-decision-engine Req 3.2/3.4: retrieval from the local memory and the evaluation boundary; the program (task 6.4) and `ousast learn compile` (6.5) are its callers",
+      "importers": []
+    },
     {
       "module": "learn.roles",
       "classification": "load_bearing",
@@ -432,6 +452,7 @@
       "reason": "reachable from gate, map_gate, pair_gate or the CLI",
       "importers": [
         "learn.features",
+        "learn.retrieve",
         "learn.roles",
         "plane.tasks.remember",
         "plane.tasks.roles"