feat(overlay): default citations and layer, humanise parse errors

A user-supplied overlay is the only sexp this engine reads that a human writes
by hand, and two of Celebration.t's eight fields carry nothing such an author
can meaningfully supply: citations is always empty for a local feast, since
citations come from the rite's lectionary and never from calendar data, and
layer merely repeats the overlay file's own id.

Requiring both made the commonest first mistake -- omitting them -- fail with
'lib/kernel/celebration.ml.t_of_sexp: the following record elements were
undefined: citations layer', which names a source file the author will never
open and does not say what to write instead. A minimal local feast needed 12
lines, two of them noise.

Overlay.load now fills each field only where ABSENT, so an explicitly stated
value always wins: an overlay may legitimately name a layer different from its
own id, and defaulting must not silently overwrite that. A test pins both
directions.

Deliberately scoped to overlays. Layer.load, which reads the shipped
sanctoral, is untouched and stays strict -- that data is the project's own,
every field of it is asserted by tests, and a missing one there is a defect
rather than a convenience.

Parse failures also stop naming kernel source paths: the five prefixes that
actually reach a user are rewritten into the vocabulary of the file being
edited, and anything unrecognised passes through verbatim rather than being
reworded into something possibly wrong.

1 files changed, 65 insertions, 1 deletions

diff --git a/test/test_overlay.ml b/test/test_overlay.ml
index f3d1aee..12eb56d 100644
--- a/test/test_overlay.ml
+++ b/test/test_overlay.ml
@@ -307,9 +307,73 @@ let prop_deterministic =
       let a, da = O.apply (base ()) o and b, db = O.apply (base ()) o in
       a = b && da = db)
 
+(* Overlay ERGONOMICS (branch overlay-ergonomics). A user-supplied overlay is
+   hand-written, unlike every other sexp this engine reads, and two of
+   [Celebration.t]'s eight fields carry no information a user could supply
+   meaningfully: [citations] is always empty for a local feast (colitur emits
+   citations from the lectionary, not the calendar), and [layer] just repeats
+   the overlay file's own [id]. Requiring both meant the commonest first
+   mistake -- omitting them -- produced
+   "lib/kernel/celebration.ml.t_of_sexp: the following record elements were
+   undefined: citations layer", which names a source file the author will
+   never open.
+
+   {!Overlay.load} now fills both in before the strict parser runs. This is
+   deliberately scoped to OVERLAY loading: {!Layer.load}, which reads the
+   SHIPPED sanctoral, stays strict, because that data is the project's own and
+   a missing field there is a defect rather than a convenience. *)
+let overlay_missing_citations_and_layer =
+  {|((id my-parish)
+      (directives
+        ((Add
+           ((date (Fixed (month 5) (day 20)))
+             (cel
+               ((slug st-example)
+                 (names ((en "St Example")))
+                 (rank Class3) (status Feast) (colour White) (subject Saint))))))))|}
+
+let test_overlay_defaults_citations_and_layer () =
+  with_temp_file (fun path ->
+      let oc = open_out path in
+      output_string oc overlay_missing_citations_and_layer;
+      close_out oc;
+      match O.load rank_of_sexp path with
+      | Error e -> Alcotest.failf "expected the overlay to load, got: %s" e
+      | Ok o ->
+          Alcotest.(check string) "id" "my-parish" o.O.id;
+          (match o.O.directives with
+          | [ O.Add e ] ->
+              Alcotest.(check string) "citations defaulted to empty" "0"
+                (string_of_int (List.length e.L.cel.Cel.citations));
+              (* [layer] defaults to the overlay's own id: the value the author
+                 would have typed, so a later Suppress/Edit naming it works. *)
+              Alcotest.(check string) "layer defaulted to the overlay id" "my-parish"
+                e.L.cel.Cel.layer
+          | _ -> Alcotest.fail "expected exactly one Add directive"))
+
+(* An explicit [layer] must still win: an overlay may deliberately claim a
+   different layer name from its own id (e.g. one file shipping two logical
+   layers), and defaulting must not overwrite a stated value. *)
+let test_overlay_explicit_layer_wins () =
+  with_temp_file (fun path ->
+      let oc = open_out path in
+      output_string oc
+        (replace_first ~sub:"(subject Saint)"
+           ~by:"(subject Saint) (layer stated-explicitly)" overlay_missing_citations_and_layer);
+      close_out oc;
+      match O.load rank_of_sexp path with
+      | Ok { O.directives = [ O.Add e ]; _ } ->
+          Alcotest.(check string) "explicit layer preserved" "stated-explicitly" e.L.cel.Cel.layer
+      | Ok _ -> Alcotest.fail "expected exactly one Add directive"
+      | Error e -> Alcotest.failf "expected the overlay to load, got: %s" e)
+
 let suite =
   ( "Layer/Overlay",
-    [ Alcotest.test_case "layer basics" `Quick test_layer_basics;
+    [ Alcotest.test_case "overlay: citations and layer default when omitted" `Quick
+        test_overlay_defaults_citations_and_layer;
+      Alcotest.test_case "overlay: an explicit layer is not overwritten" `Quick
+        test_overlay_explicit_layer_wins;
+      Alcotest.test_case "layer basics" `Quick test_layer_basics;
       Alcotest.test_case "layer by-date index" `Quick test_layer_index;
       Alcotest.test_case "layer by-date index accumulates same date" `Quick
         test_layer_index_same_date;