fix(kernel): a transferred candidate can settle by being capped out, too (fix round 1, F1)

The prior fix (settled_at) recognised two settlement channels for a
transferred candidate at its target -- winning outright (observed) or
surviving as a commemoration -- but missed a third: reaching the target
and then being CAPPED OUT there, by admit's own RG-111-style admission
count limit or by disposition's own Omit. That candidate lands in the
target's own omitted list, genuinely settled and accurately labelled, but
settled_at did not check that list, so the origin reported it as
unresolved under the same wrong, hardcoded unconverged_reason -- the exact
original bug, one level further out.

Unreachable on shipped EF data (the Major Litanies are the only privileged
Commemoration_only candidate real data carries, and no second one can ever
share Easter+2), but reachable by construction: a second privileged
Commemoration_only entry on the Litanies' own transfer target that
outranks it in admit's Class1 selection, or -- without any synthetic data
-- forcing the Litanies' own RG 109(f) privilege to Ordinary, which makes
the transferred candidate lose that same cap against its own real target.

Fixed by adding target-omitted membership as a third disjunct in
settled_at. New regression test in test_calendar.ml, built the same way:
the real EF layer plus one synthetic privileged Commemoration_only entry
on the real 2011 transfer target, sorting ahead of the Litanies so it wins
the Class1 slot. Mutation-verified to fail specifically when the third
disjunct is removed. COLITUR_EXHAUSTIVE_SWEEP=1 dune test --force stays
clean after the fix, confirming it changes no shipped day's output.

1 files changed, 89 insertions, 1 deletions

diff --git a/test/test_calendar.ml b/test/test_calendar.ml
index 93cd0bb..22f5f04 100644
--- a/test/test_calendar.ml
+++ b/test/test_calendar.ml
@@ -426,6 +426,90 @@ let test_transfer_guard_records_failure_instead_of_looping () =
   in
   Alcotest.(check bool) "non-convergence is recorded rather than silently dropped or hung" true stuck
 
+(* ef-major-litanies task, fix round 1 (F1) -- a regression test for a
+   THIRD settlement channel `build_day`'s own `settled_at` had to learn to
+   recognise: a transferred candidate that reaches its target and is then
+   CAPPED OUT there by the target day's own RG 111 admission-count limit
+   (not `observed`, not surviving as a `commemoration` -- the two channels
+   the first version of this fix checked), rather than settling cleanly.
+   Missing it reproduces the exact original bug ONE LEVEL FURTHER OUT: the
+   origin wrongly reports the transferred candidate as
+   `unconverged_reason`, even though placement genuinely converged.
+
+   Unreachable on real EF data ALONE (the Major Litanies, RG 80, are the
+   only privileged `Commemoration_only` candidate real data carries, and
+   no second one can ever coincide with Easter+2) -- reproduced here the
+   same way the fix-round review did: one synthetic privileged
+   `Commemoration_only` candidate, added directly to the REAL EF layer
+   (not a hand-built synthetic rite -- this bug is about the real Litanies
+   candidate's own real transfer, so the real rite is the honest fixture),
+   on the real Litanies' own real 2011 transfer target (26 April -- Easter
+   2011 = 24 April, so 25 April is Easter Monday, RG 80's second trigger,
+   landing on Easter+2 = 26 April), with a slug ("aaa-probe") sorting
+   ahead of "major-litanies" so it wins {!Rite_ef.Precedence_ef.admit}'s
+   Class1 "one privileged commemoration only" selection there, capping the
+   Litanies out. *)
+let real_ef_layer_for_transfer_probes =
+  match Colitur_kernel.Layer.load Rite_ef.Vocab_ef.rank_of_sexp "../data/ef/sanctoral.sexp" with
+  | Error e -> failwith ("../data/ef/sanctoral.sexp: " ^ e)
+  | Ok layer -> (
+      match Colitur_kernel.Overlay.load Rite_ef.Vocab_ef.rank_of_sexp "../data/ef/adjustments.sexp" with
+      | Error e -> failwith ("../data/ef/adjustments.sexp: " ^ e)
+      | Ok overlay ->
+          let layer, diagnostics = Colitur_kernel.Overlay.apply layer overlay in
+          if diagnostics <> [] then failwith "unexpected overlay diagnostics loading the real EF layer";
+          layer)
+
+let test_transferred_commemoration_only_capped_out_at_target_settles_cleanly () =
+  let probe_date =
+    match Colitur_kernel.Date_spec.fixed ~month:4 ~day:26 with Ok d -> d | Error e -> failwith e
+  in
+  let probe =
+    { Colitur_kernel.Layer.date = probe_date;
+      cel =
+        Cel.make ~slug:(Sl.of_string_exn "aaa-probe") ~rank:Rite_ef.Vocab_ef.Class1
+          ~status:Cel.Commemoration_only ~colour:Colitur_kernel.Colour.White
+          ~subject:Colitur_kernel.Subject.Saint ~layer:"synthetic-probe" ()
+    }
+  in
+  let augmented_layer = Colitur_kernel.Layer.set real_ef_layer_for_transfer_probes probe in
+  (* Liturgical year "2010" (Advent 2010 -- eve of Advent 2011) covers both
+     25 and 26 April 2011. *)
+  let year = C.year Rite_ef.context augmented_layer 2010 in
+  let find_date target =
+    match Array.to_list year |> List.find_opt (fun d -> D.compare d.LD.date target = 0) with
+    | Some d -> d
+    | None -> failwith "date not found in resolved year"
+  in
+  let origin = find_date (mk 2011 4 25) and target = find_date (mk 2011 4 26) in
+  let slug_s (c : Rite_ef.Vocab_ef.rank Cel.t) = Sl.to_string c.Cel.slug in
+  Alcotest.(check string) "2011-04-25 is Easter Monday, RG80's second trigger" "ef-easter-1-monday"
+    (slug_s origin.LD.observed);
+  let omitted_s d = List.map (fun (c, r) -> (slug_s c, r)) d.LD.omitted in
+  Alcotest.(check (list (pair string string))) "origin: major-litanies is NOT in [omitted] at all -- it \
+    genuinely, cleanly transferred away, no false 'did not converge'" []
+    (List.filter (fun (s, _) -> s = "major-litanies") (omitted_s origin));
+  let contains_substring s ~needle =
+    let ls = String.length s and ln = String.length needle in
+    let rec at i = i + ln <= ls && (String.sub s i ln = needle || at (i + 1)) in
+    ln = 0 || at 0
+  in
+  Alcotest.(check (list (pair string string))) "origin: no [omitted] entry anywhere claims non-convergence \
+    (the exact regression this test guards against, stated directly rather than only via the slug check \
+    above)" []
+    (List.filter (fun (_, r) -> contains_substring r ~needle:"did not converge") (omitted_s origin));
+  Alcotest.(check (list string)) "origin: [transferred_out] still correctly names major-litanies -> target"
+    [ "major-litanies->2011-04-26" ]
+    (List.map
+       (fun (c, d) -> Printf.sprintf "%s->%s" (slug_s c) (D.to_iso8601 d))
+       origin.LD.transferred_out);
+  Alcotest.(check (list string)) "target: aaa-probe wins the Class1 privileged slot (sorts ahead of \
+    major-litanies at the tied [unclassified] band)" [ "aaa-probe" ]
+    (List.map (fun (c, _) -> slug_s c) target.LD.commemorations);
+  Alcotest.(check bool) "target: major-litanies is capped out into [omitted] there, with the REAL \
+    admission-limit reason, not lost and not mislabelled" true
+    (List.mem ("major-litanies", "omitted: admission limit reached") (List.map (fun (c,r) -> (slug_s c, r)) target.LD.omitted))
+
 let suite =
   ( "Calendar",
     [ Alcotest.test_case "year covers every day" `Quick test_year_covers_every_day;
@@ -447,4 +531,8 @@ let suite =
       Alcotest.test_case "transfer target outside year is recorded not lost" `Quick
         test_transfer_target_outside_year_is_recorded_not_lost;
       Alcotest.test_case "transfer guard records failure instead of looping" `Quick
-        test_transfer_guard_records_failure_instead_of_looping ] )
+        test_transfer_guard_records_failure_instead_of_looping;
+      Alcotest.test_case
+        "ef-major-litanies fix round 1 (F1): a transferred candidate capped out at its own target settles \
+         cleanly, no false 'did not converge'"
+        `Quick test_transferred_commemoration_only_capped_out_at_target_settles_cleanly ] )