format todos and comment improvement

2 files changed, 17 insertions, 40 deletions

diff --git a/lib/prelude/catalog.ml b/lib/prelude/catalog.ml
index ae43c4d..a277066 100644
--- a/lib/prelude/catalog.ml
+++ b/lib/prelude/catalog.ml
@@ -1,14 +1,13 @@
 (** System catalog helpers.
-
     Pure definitions — no storage access, no manipulation dependency.
     Consumed by {!Manipulation.Make} to bootstrap and maintain the six
     catalog relations that make the database self-describing. *)
 
-let catalog_prefix = "sakura:"
+(* TODO: on_rel_name and timing_rel_name are defined and seeded but never
+   written to by any executor. They appear to be stubs for trigger/timing
+   metadata that was never implemented. *)
 
-(* 
-   Catalog relation names
-    *)
+let catalog_prefix = "sakura:"
 
 let relation_rel_name   = catalog_prefix ^ "relation"
 let domain_rel_name     = catalog_prefix ^ "domain"
@@ -26,12 +25,7 @@ let catalog_relation_names =
   ; timing_rel_name
   ]
 
-let is_catalog_relation name =
-  List.mem name catalog_relation_names
-
-(* 
-   Schema definitions
-    *)
+let is_catalog_relation name = List.mem name catalog_relation_names
 
 let relation_schema : Schema.t =
   Schema.empty |> Schema.add "name" "string"
@@ -56,7 +50,6 @@ let on_schema : Schema.t =
 let timing_schema : Schema.t =
   Schema.empty |> Schema.add "timing" "string"
 
-(** All (name, schema) pairs for the 6 catalog relations, in bootstrap order. *)
 let catalog_definitions =
   [ (relation_rel_name,   relation_schema)
   ; (domain_rel_name,     domain_schema)
@@ -66,9 +59,9 @@ let catalog_definitions =
   ; (timing_rel_name,     timing_schema)
   ]
 
-(* 
-   Tuple builders
-    *)
+(* TODO: all tuple builders use Obj.magic to coerce string values into
+   Attribute.value (Obj.t). This is the same UB pattern fixed in standard.ml;
+   should use Obj.repr instead. *)
 
 let build_relation_tuple rel_name : Tuple.materialized =
   { Tuple.relation = relation_rel_name
diff --git a/lib/prelude/standard.ml b/lib/prelude/standard.ml
index efcb7ae..68012fc 100644
--- a/lib/prelude/standard.ml
+++ b/lib/prelude/standard.ml
@@ -1,18 +1,14 @@
-(** Domain-parameterized comparison and arithmetic relations.
+(** Comparison and arithmetic relations over the natural domain. *)
 
-    All comparison relations use a two-attribute schema [(left, right)]
-    with both attributes in the same domain. The domain's [compare] function
-    is used for evaluation — no more spreading [Obj.magic]. *)
+(* TODO: all relations here are hardcoded to naturals. The make_comparison
+   factory accepts a domain_name string but membership_criteria always uses
+   Stdlib.compare on Obj.t, which only works correctly for unboxed integers.
+   Extending to other domains requires a proper typed comparison dispatch. *)
 
-(* Helper: wrap a native value in the Attribute.materialized record *)
 let mk v = { Attribute.value = Obj.repr v }
 
-(* ============================================================================
-   Comparison relation factory
-   ============================================================================ *)
-
-(** Build a comparison relation parameterized by domain.
-    [pred] receives the result of [Domain.compare left right]. *)
+(** Build a comparison relation over a single domain.
+    [pred] receives the result of [Stdlib.compare left right]. *)
 let make_comparison ~name ~domain_name ~pred ~cardinality ~generator =
   let schema =
     Schema.empty |> Schema.add "left" domain_name
@@ -34,13 +30,7 @@ let make_comparison ~name ~domain_name ~pred ~cardinality ~generator =
     ~provenance:(Relation.Provenance.Base name)
     ~lineage:(Relation.Lineage.Base name)
 
-(* ============================================================================
-   Pair enumeration for comparison generators
-   ============================================================================ *)
-
-(** Enumerate pairs (a, b) from naturals where a < b.
-    Uses triangular indexing: position n maps to row r, column c
-    where a = c, b = r, and a < b. *)
+(** Enumerate pairs (a, b) where a < b using triangular indexing. *)
 let pair_of_nat_lt n =
   let nf = float_of_int n in
   let r = int_of_float (floor ((1. +. sqrt (1. +. 8. *. nf)) /. 2.)) in
@@ -48,7 +38,7 @@ let pair_of_nat_lt n =
   let left = n - t_prev in
   (left, r)
 
-(** Enumerate all pairs (a, b) from naturals via Cantor pairing. *)
+(** Enumerate all pairs (a, b) via Cantor pairing. *)
 let cantor_pair_of_nat n =
   let w =
     int_of_float (floor ((sqrt (float_of_int (8 * n + 1)) -. 1.) /. 2.))
@@ -58,9 +48,6 @@ let cantor_pair_of_nat n =
   let a = w - b in
   (a, b)
 
-(* ============================================================================
-   Concrete comparison relations (natural domain)
-   ============================================================================ *)
 
 let less_than_natural : Relation.t =
   let rec generator (position : int option) : Generator.result =
@@ -179,9 +166,6 @@ let not_equal_natural : Relation.t =
     ~pred:(fun c -> c <> 0)
     ~cardinality:Conventions.Cardinality.AlephZero ~generator
 
-(* ============================================================================
-   Arithmetic relations (natural domain)
-   ============================================================================ *)
 
 let plus_natural : Relation.t =
   let schema =