feat(lessons): a lesson names the rule it is an instance of — lesson_rule_links (milestone 440 step 1, #4630)

The link between a lesson (one concrete situation) and the rule that governs
it, with the operator's soft-then-hard design built into its state:
suggested while evidence accumulates, confirmed or rejected once judged. Only
confirmed will carry a rule in retrieval (#4633); rejected is kept so the pair
is never proposed again.

- models/lesson_rule_link.py + migration 0111: one row per (lesson, rule),
  CASCADE on both ends, indexed both ways, CHECK on state (rule 36), evidence
  JSONB and judged_at.
- services/lesson_rules.py: require_rules (validated before any write, so
  a bad id leaves nothing half-linked), set_lesson_rules (set-semantics;
  a dropped rule becomes rejected, not forgotten), judge_link, and the two
  reads. ACL: write on the lesson (share-aware), ownership of the rule; a
  reader sees only rules they own. Decorations are fail-open (#4286).
- MCP: create_lesson / update_lesson take rule_ids; get/create/update return
  `rules`; new judge_lesson_link tool. REST: the same on /api/lessons plus
  PUT /api/lessons/<id>/rules/<rule_id>. Rules: rule_detail carries `lessons`.
- Backup v18: export (full and user-scoped, both ends in scope), builder,
  importer; both column guards register the table.
- Tests: integration (states, set-semantics, judge, ACL all-or-nothing,
  cascade both ways, CHECK, one row per pair); unit (door wiring, judge
  registered, migration/model state agreement, backup skip and unjudged
  stays unjudged). conftest stubs the decorations for unit tests.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

src/scribe/services/backup.py

@@ -16,6 +16,7 @@ from scribe.models.rule_usage import RuleUsageEvent
 from scribe.models.retrieval_tuning import RetrievalTuningEvent
 from scribe.models.canonical_system import CanonicalSystem
 from scribe.models.rulebook import RuleRelation, rule_systems as rule_systems_t
+from scribe.models.lesson_rule_link import LessonRuleLink
 from scribe.models.code_shape import CodeShape, CodeShapeEvent, CodeShapeUse
 from scribe.models.project import Project
 from scribe.models.repo_binding import RepoBinding
@@ -80,8 +81,12 @@ logger = logging.getLogger(__name__)
 # say whether it still measures anything. Both travel NULLABLE and unfilled —
 # a row written before the stamp existed restores unstamped, because inventing
 # the model it was measured under would turn "unknown" into a stated fact.
+# v18 (2026-10) added lesson_rule_links (milestone 440): which rule each lesson
+# is an instance of, and the judgments that confirmed or rejected each pair. A
+# confirmed link is a judgment nothing else records, and a rejected one is
+# what stops the pair being proposed again — losing either undoes work.
 # Bump when the serialized schema changes.
-BACKUP_VERSION = 17
+BACKUP_VERSION = 18
 
 # Every table this backup carries, by its REAL name. Paired with _NOT_INCLUDED
 # below, these two lists must together account for the entire schema — which is
@@ -119,6 +124,8 @@ _BACKED_UP = [
     # on the operator's behalf, a restore that kept the numbers and dropped the
     # reasons would leave an install tuned by nobody it can name.
     "retrieval_tuning_events",
+    # v18 (2026-10): lesson → rule links and their judgments (milestone 440).
+    "lesson_rule_links",
 ]
 
 # Tables intentionally NOT in the backup, surfaced in the payload so the gap is
@@ -212,6 +219,8 @@ _COLUMN_EXCLUSIONS: dict[str, set[str]] = {
     "record_systems": {"id", "created_at"},
     "note_supersessions": {"id", "created_at"},
     "rule_relations": {"id", "created_at"},
+    # The pair is the row; everything else is the judgment and its evidence.
+    "lesson_rule_links": {"id"},
     "note_usage_events": {"id"},
     # Same as the note twin: the surrogate key is re-issued on insert.
     "rule_usage_events": {"id"},
@@ -299,6 +308,7 @@ _IMPORT_COLUMN_EXCLUSIONS: dict[str, set[str]] = {
     "record_systems": {"id", "created_at"},
     "note_supersessions": {"id", "created_at"},
     "rule_relations": {"id", "created_at"},
+    "lesson_rule_links": {"id"},
     "note_usage_events": {"id"},
     "rule_usage_events": {"id"},
     "retrieval_tuning_events": {"id"},
@@ -692,6 +702,21 @@ def _rule_relation_rows(rows) -> list[dict]:
     ]
 
 
+def _lesson_rule_link_rows(rows) -> list[dict]:
+    """Which rule each lesson is an instance of, with the judgment's state,
+    reason and evidence (milestone 440). Ids are SOURCE ids, remapped through
+    the note and rule maps at restore."""
+    return [
+        {
+            "lesson_id": r.lesson_id, "rule_id": r.rule_id, "state": r.state,
+            "note": r.note, "evidence": r.evidence,
+            "judged_at": r.judged_at.isoformat() if r.judged_at else None,
+            "created_at": r.created_at.isoformat() if r.created_at else None,
+        }
+        for r in rows
+    ]
+
+
 def _rule_rows(rows) -> list[dict]:
     return [
         {
@@ -739,6 +764,7 @@ async def export_full_backup() -> dict:
             .join(CanonicalSystem, CanonicalSystem.id == rule_systems_t.c.canonical_id)
         )).all()
         rule_relations = (await session.execute(select(RuleRelation))).scalars().all()
+        lesson_rule_links = (await session.execute(select(LessonRuleLink))).scalars().all()
         record_systems = (await session.execute(select(RecordSystem))).scalars().all()
         supersessions = (
             await session.execute(select(NoteSupersession))
@@ -797,6 +823,7 @@ async def export_full_backup() -> dict:
         "canonical_systems": _canonical_system_rows(canonical_systems),
         "rule_systems": _rule_system_rows(rule_system_rows),
         "rule_relations": _rule_relation_rows(rule_relations),
+        "lesson_rule_links": _lesson_rule_link_rows(lesson_rule_links),
         "systems": _system_rows(
             systems, {c.id: c.slug for c in canonical_systems}
         ),
@@ -957,6 +984,14 @@ async def export_user_backup(user_id: int) -> dict:
                 RuleRelation.to_rule_id.in_(_rule_ids),
             )
         )).scalars().all() if _rule_ids else []
+        # Both ends in THIS user's export, for the supersession reason: a link
+        # to a lesson or rule the import will not create restores as nothing.
+        lesson_rule_links = (await session.execute(
+            select(LessonRuleLink).where(
+                LessonRuleLink.lesson_id.in_(note_ids),
+                LessonRuleLink.rule_id.in_(_rule_ids),
+            )
+        )).scalars().all() if (_rule_ids and note_ids) else []
 
     return {
         "version": BACKUP_VERSION,
@@ -984,6 +1019,7 @@ async def export_user_backup(user_id: int) -> dict:
         "canonical_systems": _canonical_system_rows(canonical_systems),
         "rule_systems": _rule_system_rows(rule_system_rows),
         "rule_relations": _rule_relation_rows(rule_relations),
+        "lesson_rule_links": _lesson_rule_link_rows(lesson_rule_links),
         "systems": _system_rows(
             systems, {c.id: c.slug for c in canonical_systems}
         ),
@@ -1329,6 +1365,26 @@ def _build_rule_relation(row: dict, maps: _Maps) -> RuleRelation | None:
     )
 
 
+def _build_lesson_rule_link(row: dict, maps: _Maps) -> LessonRuleLink | None:
+    """Both ends must map: a link whose lesson or rule did not restore points
+    at whatever took that number in the destination."""
+    lesson = maps.notes.get(row.get("lesson_id", 0))
+    rule = maps.rules.get(row.get("rule_id", 0))
+    if lesson is None or rule is None:
+        return None
+    return LessonRuleLink(
+        lesson_id=lesson,
+        rule_id=rule,
+        state=row.get("state") or "suggested",
+        note=row.get("note") or None,
+        evidence=row.get("evidence"),
+        # Kept absent when absent: a suggested link was never judged, and
+        # stamping it with the restore time would say it was.
+        judged_at=_dt_or_none(row.get("judged_at")),
+        created_at=_dt(row.get("created_at")),
+    )
+
+
 def _build_rule_version(row: dict, maps: _Maps) -> RuleVersion | None:
     rid = maps.rules.get(row.get("rule_id", 0))
     if rid is None:
@@ -1725,7 +1781,7 @@ async def _restore_v2(data: dict) -> dict:
         "note_supersessions": 0, "code_shapes": 0, "code_shape_events": 0,
         "code_shape_uses": 0, "canonical_systems": 0,
         "rule_systems": 0, "rule_relations": 0, "rule_versions": 0,
-        "retrieval_tuning_events": 0,
+        "retrieval_tuning_events": 0, "lesson_rule_links": 0,
     }
 
     async with async_session() as session:
@@ -1920,6 +1976,16 @@ async def _restore_v2(data: dict) -> dict:
             session.add(relation)
             stats["rule_relations"] += 1
 
+        # Lesson → rule links (milestone 440): after both notes and rules are
+        # mapped, which is why they sit beside the rule edges. Archives before
+        # v18 carry no section and restore with none.
+        for lr in data.get("lesson_rule_links", []):
+            link = _build_lesson_rule_link(lr, maps)
+            if link is None:
+                continue
+            session.add(link)
+            stats["lesson_rule_links"] += 1
+
         # A rule's edit history (milestone 323). Must come after the rules
         # themselves — the rule map is only populated above — and both ids are
         # ids in the SOURCE database, which is #3182's arose_from_id trap.