Clarify object row strengthening contracts

Signed-off-by: Cristiano Calcagno <cristianoc@users.noreply.github.com>

Author: cristianoc

compiler/ml/ctype.ml

@@ -2707,9 +2707,9 @@ let filter_object_field_for_write env name ty :
   | Tobject f -> write_field ~can_promote:(is_Tvar (object_row ty)) f
   | _ -> Error Owrite_missing
 
-(* Require a readable [name] field and return its type. An open object row can
-   acquire the missing field; a closed row cannot. This operation does not
-   require or introduce write capability. *)
+(* Require a readable [name] field and return its type. If lookup reaches a
+   [Tvar] row terminator, it can acquire the missing field. Rigid and closed
+   rows cannot. This operation does not require or introduce write capability. *)
 let filter_method env name ty =
   let ty = expand_head_trace env ty in
   match ty.desc with

compiler/ml/ctype.mli

@@ -243,20 +243,23 @@ val filter_arrow_n :
 
 val filter_method : Env.t -> string -> type_expr -> type_expr
 (** Constrain a type to have the named readable object field and return the
-    field's stored type. A missing field extends an open row as [Immutable].
-    A closed row without the field, or a non-object type which cannot be
-    constrained to an object, raises [Unify]. *)
+    field's stored type. If lookup reaches a [Tvar] row terminator, a missing
+    field extends that inferred row as [Immutable]. A row ending in [Tunivar],
+    [Tconstr], or [Tnil] cannot acquire a missing field. A non-object type which
+    cannot be constrained to an object also raises [Unify]. *)
 
 type object_field_write_error = Owrite_missing | Owrite_not_mutable
 
 val filter_object_field_for_write :
   Env.t -> string -> type_expr -> (type_expr, object_field_write_error) Result.t
 (** Constrain a type for assignment to the named object field.
 
-    A mutable field returns its stored type. On an open row, an immutable field
-    is promoted without changing its type, and a missing field is added as
-    mutable. On a closed row, these cases return [Owrite_not_mutable] and
-    [Owrite_missing], respectively. *)
+    A mutable field returns its stored type. When the object row ends in a
+    [Tvar], an immutable field is promoted without changing its type, and a
+    missing field is added as mutable. [Tunivar] and private-row [Tconstr]
+    terminators are structurally open but cannot be strengthened. With either
+    of those terminators, or with [Tnil], an immutable field returns
+    [Owrite_not_mutable] and a missing field returns [Owrite_missing]. *)
 
 val occur_in : Env.t -> type_expr -> type_expr -> bool
 val deep_occur : type_expr -> type_expr -> bool