typia 15.0.0 → 15.1.0

package/native/core/programmers/random_programmer_length_argument_test.go

@@ -3,6 +3,7 @@ package programmers
 import (
   "testing"
 
+  shimast "github.com/microsoft/typescript-go/shim/ast"
   shimprinter "github.com/microsoft/typescript-go/shim/printer"
   nativeiterate "github.com/samchon/typia/packages/typia/native/core/programmers/iterate"
 )
@@ -14,11 +15,16 @@ import (
 // to lose the length bounds because only the plain-string fall-through carried
 // the full schema, so the generated value failed its own validator (#2189). The
 // format and pattern branches now forward a length object, and the format-only
-// and pattern-only branches must stay byte-identical (no extra argument).
+// and pattern-only branches must retain their original argument counts.
 //
 // 1. A format or pattern without a length tag emits no length argument.
 // 2. A format or pattern with a length tag forwards exactly one length object.
 // 3. The length-argument helper is nil without a length tag.
+//
+// @evidence contracts/testing.md#behavioral-verification The random programmer composes constrained string leaves with and without length bounds for email, date-time and pattern forms; argument counts and exact authored bound names/values require the length object to be forwarded intact.
+// @evidence contracts/testing.md#independent-expectations The generated value must satisfy minLength and maxLength, so forwarding the length object is required exactly when bounds exist; the expected argument counts are authored.
+// @evidence contracts/testing.md#distinguishing-cases Each format and pattern is checked with and without length, so dropped bounds fail.
+// @evidence contracts/testing.md#execution-ownership The canonical native Go command (pnpm test:go:native) runs this same-package Test function in process. It checks argument counts and literal bound objects in memory, with no checker, filesystem fixture or process.
 func TestRandomProgrammerComposeAtomicThreadsLength(t *testing.T) {
   emit := shimprinter.NewEmitContext()
 
@@ -44,6 +50,31 @@ func TestRandomProgrammerComposeAtomicThreadsLength(t *testing.T) {
     t.Fatalf("pattern with length must emit RegExp and the length object, got %d", len(patternLength.Arguments))
   }
 
+  for _, tc := range []struct {
+    node     *shimast.Node
+    expected map[string]string
+  }{
+    {formatLength.Arguments[0], map[string]string{"minLength": "40"}},
+    {datetimeLength.Arguments[0], map[string]string{"maxLength": "10"}},
+    {patternLength.Arguments[1], map[string]string{"minLength": "10", "maxLength": "20"}},
+  } {
+    if tc.node == nil || tc.node.Kind != shimast.KindObjectLiteralExpression || len(tc.node.AsObjectLiteralExpression().Properties.Nodes) != len(tc.expected) {
+      t.Fatal("length argument must contain exactly the authored bounds")
+    }
+    seen := map[string]bool{}
+    for _, property := range tc.node.AsObjectLiteralExpression().Properties.Nodes {
+      if property.Kind != shimast.KindPropertyAssignment {
+        t.Fatal("length bound must be a literal property assignment")
+      }
+      value := property.AsPropertyAssignment().Initializer
+      name := property.Name().Text()
+      expected, known := tc.expected[name]
+      if !known || seen[name] || value.Kind != shimast.KindNumericLiteral || value.Text() != expected {
+        t.Fatal("length bound name or numeric value changed")
+      }
+      seen[name] = true
+    }
+  }
   if randomProgrammer_length_argument(nativeiterate.JsonSchema{"type": "string"}, emit) != nil {
     t.Fatal("length argument must be nil without minLength/maxLength")
   }

package/native/core/programmers/random_programmer_min_items_tag_test.go

@@ -19,6 +19,11 @@ type randomProgrammerDefinedInt int
 // 1. Check positive direct, schema-backed, defined numeric, and fractional tags.
 // 2. Check zero, negative, and unrelated tags are ignored.
 // 3. Verify the helper returns the matching tag name for diagnostics.
+//
+// @evidence contracts/testing.md#behavioral-verification The positive-MinItems lookup is called on direct, schema-backed, bridge numeric and fractional tags and on zero, negative and unrelated tags.
+// @evidence contracts/testing.md#independent-expectations Only positive MinItems values matter to the recursion check; the tags and verdicts are authored.
+// @evidence contracts/testing.md#distinguishing-cases Five detected rows and four ignored rows separate positive detection from over-matching.
+// @evidence contracts/testing.md#execution-ownership The canonical native Go command (pnpm test:go:native) runs this same-package Test function in process. It calls the lookup on constructed tags with no checker, filesystem fixture or process.
 func TestRandomProgrammerFindPositiveMinItems(t *testing.T) {
   for _, tags := range [][][]schemametadata.IMetadataTypeTag{
     {{{Name: "MinItems<2>", Kind: "minItems", Value: 2}}},

package/native/core/programmers/random_programmer_pick_hook_test.go

@@ -0,0 +1,88 @@
+package programmers
+
+import (
+  "testing"
+
+  shimast "github.com/microsoft/typescript-go/shim/ast"
+  shimprinter "github.com/microsoft/typescript-go/shim/printer"
+  nativecontext "github.com/samchon/typia/packages/typia/native/core/context"
+)
+
+// TestRandomProgrammerPickHook preserves lazy selection, fallback and receiver.
+//
+// A union picker must choose a lazy callback before generating its value. Its
+// optional customization is independent of integer leaves, and a stateful pick
+// method must receive its generator object instead of an unbound invocation.
+//
+//  1. Build singleton and two-candidate selections directly in memory.
+//  2. Require the optional pick/fallback target and exact generator receiver.
+//  3. Check every original expression remains in a zero-argument thunk and only
+//     the selected thunk is invoked by the outer zero-argument call.
+//
+// @evidence contracts/testing.md#behavioral-verification The actual randomProgrammer_decode_pick AST builder runs for one and two candidate expressions. Its nullish hook/fallback, .call receiver, lazy callback array, expression identities and outer invocation are inspected structurally.
+// @evidence contracts/testing.md#independent-expectations The customization contract requires generator.pick when present and randomPick otherwise; JavaScript method receiver semantics require .call(generator). Lazy candidate bodies and zero-argument selected invocation follow from selecting before generating, independently of emitted text.
+// @evidence contracts/testing.md#distinguishing-cases Singleton and two-alternative inputs retain candidate order and identity. Nullish fallback and optional access are explicit boundaries; no integer leaf callback is substituted for union selection. Native schema cases separately execute stateful selection and default runtime behavior.
+// @evidence contracts/testing.md#execution-ownership The native Go unit runner discovers this same-package Test function. It constructs and inspects AST nodes in process with no consumer fixture, native build or JavaScript subprocess.
+func TestRandomProgrammerPickHook(t *testing.T) {
+  for _, size := range []int{1, 2} {
+    emit := shimprinter.NewEmitContext()
+    factory := shimast.NewNodeFactory(shimast.NodeFactoryHooks{})
+    candidates := []*shimast.Node{factory.NewStringLiteral("left", shimast.TokenFlagsNone), factory.NewStringLiteral("right", shimast.TokenFlagsNone)}
+    candidates = candidates[:size]
+    node := randomProgrammer_decode_pick(randomProgrammer_decodeProps{
+      Context: nativecontext.ITypiaContext{Emit: emit},
+    }, candidates)
+    if node.Kind != shimast.KindCallExpression {
+      t.Fatal("selected lazy candidate must be called")
+    }
+    outer := node.AsCallExpression()
+    if outer.Arguments != nil && len(outer.Arguments.Nodes) != 0 {
+      t.Fatal("selected candidate invocation must have no arguments")
+    }
+    if outer.Expression.Kind != shimast.KindCallExpression {
+      t.Fatal("outer target must be the selector result")
+    }
+    selected := outer.Expression.AsCallExpression()
+    if selected.Arguments == nil || len(selected.Arguments.Nodes) != 2 || selected.Arguments.Nodes[0].Text() != "_generator" {
+      t.Fatal("selector must receive the generator object as its receiver")
+    }
+    if selected.Expression.Kind != shimast.KindPropertyAccessExpression {
+      t.Fatal("selector must be invoked through call")
+    }
+    target := selected.Expression.AsPropertyAccessExpression()
+    if target.Name().Text() != "call" {
+      t.Fatal("selector must preserve method receiver with call")
+    }
+    choice := target.Expression
+    for choice.Kind == shimast.KindParenthesizedExpression {
+      choice = choice.AsParenthesizedExpression().Expression
+    }
+    if choice.Kind != shimast.KindBinaryExpression {
+      t.Fatal("custom selector must retain its nullish fallback")
+    }
+    coalesce := choice.AsBinaryExpression()
+    if coalesce.OperatorToken.Kind != shimast.KindQuestionQuestionToken || coalesce.Right.Text() != "randomPick" {
+      t.Fatal("missing built-in randomPick fallback")
+    }
+    if coalesce.Left.Kind != shimast.KindPropertyAccessExpression {
+      t.Fatal("custom pick must be read from the generator")
+    }
+    custom := coalesce.Left.AsPropertyAccessExpression()
+    if custom.Name().Text() != "pick" || custom.Expression.Text() != "_generator" || custom.QuestionDotToken == nil {
+      t.Fatal("custom pick must use optional generator access")
+    }
+    array := selected.Arguments.Nodes[1]
+    if array.Kind != shimast.KindArrayLiteralExpression || len(array.AsArrayLiteralExpression().Elements.Nodes) != size {
+      t.Fatal("candidate population must remain unchanged")
+    }
+    for index, candidate := range array.AsArrayLiteralExpression().Elements.Nodes {
+      if candidate.Kind != shimast.KindArrowFunction {
+        t.Fatal("candidate must remain lazy")
+      }
+      thunk := candidate.AsArrowFunction()
+      if thunk.Body != candidates[index] || (thunk.Parameters != nil && len(thunk.Parameters.Nodes) != 0) {
+        t.Fatal("candidate expression/order or zero-argument shape changed")
+      }
+    }
+  }
+}

package/native/core/programmers/reflect/ReflectLiteralsProgrammer.go

@@ -14,6 +14,13 @@ type reflectLiteralsProgrammerNamespace struct{}
 
 var ReflectLiteralsProgrammer = reflectLiteralsProgrammerNamespace{}
 
+// ReflectLiteralsProgrammer_IProps is the transform context and the type argument
+// of the `typia.reflect.literals` call.
+//
+// @evidence contracts/common.md#principled-implementation The programmer needs the transform context and the type argument of the call.
+// @evidence contracts/common.md#clear-and-simple-design A two-field argument record for Write.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A data record.
+// @evidence contracts/common.md#meaningful-documentation The doc states both fields.
 type ReflectLiteralsProgrammer_IProps struct {
   Context nativecontext.ITypiaContext
   Type    *shimchecker.Type
@@ -106,6 +113,14 @@ func (reflectLiteralsProgrammerNamespace) Write(props ReflectLiteralsProgrammer_
   )
 }
 
+// ReflectLiteralsProgrammer_ErrorMessages are the two reasons the literal list
+// is refused: no constant literal was found, or a member other than a constant
+// literal exists.
+//
+// @evidence contracts/common.md#principled-implementation The two rejection reasons are named constants of a string type, so the validator and the diagnostics share one spelling and no free text is repeated.
+// @evidence contracts/common.md#clear-and-simple-design A string type with two constants.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A declaration only.
+// @evidence contracts/common.md#meaningful-documentation The doc states the two reasons.
 type ReflectLiteralsProgrammer_ErrorMessages string
 
 const (

package/native/core/schemas/metadata/IMetadataTypeTagSequence.go

@@ -12,6 +12,11 @@ import (
 // `jsnum.Number` — a defined float64 type living under `typescript-go/internal`
 // that typia cannot import — so the conversion must go through reflection
 // kinds instead of a closed type switch.
+//
+// @evidence contracts/common.md#principled-implementation A sequence tag stores its field number in the schema map under the key x-protobuf-sequence, and the number may arrive as a type typescript-go does not export, so it is read through reflection kinds and a missing, non-sequence or unreadable value gives nil, which the callers treat as no assigned number.
+// @evidence contracts/common.md#clear-and-simple-design One guard sequence over the tag kind, the schema map and the key, then a call to the converter.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts There is no closed type switch to extend for each new numeric type.
+// @evidence contracts/common.md#meaningful-documentation The doc explains why reflection is needed and what nil means.
 func IMetadataTypeTag_getSequence(tag IMetadataTypeTag) *int {
   if tag.Kind != "sequence" {
     return nil
@@ -31,7 +36,13 @@ func IMetadataTypeTag_getSequence(tag IMetadataTypeTag) *int {
 }
 
 // IMetadataTypeTag_toInt coerces a tag schema value to an int, accepting any
-// defined integer, float, or numeric-string type by reflection kind.
+// defined integer, float, or numeric-string type by reflection kind. A float is
+// truncated toward zero and no range is checked; any other kind reports false.
+//
+// @evidence contracts/common.md#principled-implementation Any integer or unsigned kind converts directly, a float kind is truncated toward zero, and a string must parse as a base-10 integer; every other kind reports failure, so an unreadable value never becomes a field number by accident.
+// @evidence contracts/common.md#clear-and-simple-design One switch over reflection kinds.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Truncation of a float and the lack of range checks are limits that the doc states, not hidden behavior.
+// @evidence contracts/common.md#meaningful-documentation The doc states the accepted kinds and the failure result.
 func IMetadataTypeTag_toInt(value any) (int, bool) {
   if value == nil {
     return 0, false

package/native/core/schemas/metadata/MetadataAlias.go

@@ -1,12 +1,30 @@
 package metadata
 
+// MetadataAlias is one use of a shared alias type in a schema, together with
+// the type tag rows that apply at that use. The two cached names are computed on
+// first read. Type names and Tags must be final beforehand; later changes do
+// not invalidate either cache.
+//
+// @evidence contracts/common.md#principled-implementation A use site carries its own tags while the alias type is shared, so tags live on the reference and the type stays one value; the name caches avoid re-rendering the tagged name on every comparison.
+// @evidence contracts/common.md#clear-and-simple-design A reference record with two cached strings.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The record copies nothing from the type and does not hide the cache behavior.
+// @evidence contracts/common.md#meaningful-documentation The doc states the shared type, the per-use tags and the cache limitation.
 type MetadataAlias struct {
-  Type          *MetadataAliasType
+  // Type is the shared alias definition referenced by this use.
+  Type *MetadataAliasType
+  // Tags contains this use's alternative rows of jointly applied tags.
   Tags          [][]IMetadataTypeTag
   name_         string
   display_name_ string
 }
 
+// MetadataAlias_create references props.Type and copies the tag matrix, so later
+// edits of the caller's rows do not reach the new use.
+//
+// @evidence contracts/common.md#principled-implementation The use owns its tags like every other tagged reference, and the shared alias type is stored by pointer because it is meant to be shared.
+// @evidence contracts/common.md#clear-and-simple-design One constructor; cloneTagMatrix keeps nil as nil.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts No field is dropped silently: the two name caches start empty on purpose.
+// @evidence contracts/common.md#meaningful-documentation The doc states which part is copied and which is shared.
 func MetadataAlias_create(props MetadataAlias) *MetadataAlias {
   return &MetadataAlias{
     Type: props.Type,
@@ -14,6 +32,13 @@ func MetadataAlias_create(props MetadataAlias) *MetadataAlias {
   }
 }
 
+// GetName returns the identity name of the use: the alias type's Name with the
+// tags applied. Identity-sensitive logic such as keys and deduplication reads it.
+//
+// @evidence contracts/common.md#principled-implementation The identity name is built from the alias's Name and the use's tags once and cached, which is cheap for the repeated comparisons the analysis does.
+// @evidence contracts/common.md#clear-and-simple-design One cached call to taggedName.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The cache limitation is documented on the record.
+// @evidence contracts/common.md#meaningful-documentation The doc distinguishes it from the display name.
 func (obj *MetadataAlias) GetName() string {
   if obj.name_ == "" {
     obj.name_ = taggedName(obj.Type.Name, obj.Tags)
@@ -21,6 +46,13 @@ func (obj *MetadataAlias) GetName() string {
   return obj.name_
 }
 
+// GetDisplayName returns the human-facing name of the use: the alias type's
+// display name with the tags applied.
+//
+// @evidence contracts/common.md#principled-implementation Messages should show the structural form of an inline type while identity logic keeps the stable name, so the two are separate and computed from the type's own pair.
+// @evidence contracts/common.md#clear-and-simple-design One cached call to taggedName.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts No consumer-specific rewriting.
+// @evidence contracts/common.md#meaningful-documentation The doc states it is the human-facing counterpart of GetName.
 func (obj *MetadataAlias) GetDisplayName() string {
   if obj.display_name_ == "" {
     obj.display_name_ = taggedName(obj.Type.GetDisplayName(), obj.Tags)
@@ -28,6 +60,14 @@ func (obj *MetadataAlias) GetDisplayName() string {
   return obj.display_name_
 }
 
+// ToJSON returns the by-name reference to the alias type with a copy of the
+// tag rows. Nested tag payloads remain shared. The type's own JSON is written
+// once by the components.
+//
+// @evidence contracts/common.md#principled-implementation A reference in the JSON form is the type name plus tags, because the shared type is serialized once in the components and a copy here would break sharing and recursion.
+// @evidence contracts/common.md#clear-and-simple-design One record construction.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Matrix rows are copied; nested tag payloads retain their existing references.
+// @evidence contracts/common.md#meaningful-documentation The doc states the by-name form.
 func (obj *MetadataAlias) ToJSON() IMetadataSchema_IReference {
   return IMetadataSchema_IReference{
     Name: obj.Type.Name,

package/native/core/schemas/metadata/MetadataAliasType.go

@@ -1,24 +1,59 @@
 package metadata
 
+// IMetadataSchema_IAliasType is the JSON form of an alias type: its name, value
+// schema, description, JSDoc tags, recursion flag and nullability list.
+//
+// @evidence contracts/common.md#principled-implementation The JSON form lists what must survive serialization of an alias and leaves out the display name, which is derived at analysis time.
+// @evidence contracts/common.md#clear-and-simple-design One flat record.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A data record.
+// @evidence contracts/common.md#meaningful-documentation Each field describes the alias definition produced by ToJSON.
 type IMetadataSchema_IAliasType struct {
-  Name        string
-  Value       *IMetadataSchema
+  // Name identifies the shared alias definition.
+  Name string
+  // Value is the serialized aliased schema.
+  Value *IMetadataSchema
+  // Description is optional documentation attached to the alias.
   Description *string
-  JsDocTags   []IJsDocTagInfo
-  Recursive   bool
-  Nullables   []bool
+  // JsDocTags contains the alias's ordered documentation tags.
+  JsDocTags []IJsDocTagInfo
+  // Recursive marks a recursive alias definition.
+  Recursive bool
+  // Nullables records the nullability of analyzed uses.
+  Nullables []bool
 }
 
+// MetadataAliasType is a type alias shared by every use of it: the name that
+// identifies it, the display name for messages, the aliased schema, its
+// documentation, whether it refers to itself and which uses were nullable.
+//
+// @evidence contracts/common.md#principled-implementation An alias is the unit that gives recursive and repeated types a name, so its value, flags and documentation are kept once and every use points here.
+// @evidence contracts/common.md#clear-and-simple-design One flat record whose uses are MetadataAlias values.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A data record.
+// @evidence contracts/common.md#meaningful-documentation The doc names each part.
 type MetadataAliasType struct {
-  Name        string
+  // Name identifies the shared alias definition.
+  Name string
+  // DisplayName is the human-facing rendering, falling back to Name when empty.
   DisplayName string
-  Value       *MetadataSchema
+  // Value is the analyzed aliased schema; it must be set before ToJSON.
+  Value *MetadataSchema
+  // Description is optional documentation attached to the alias.
   Description *string
-  JsDocTags   []IJsDocTagInfo
-  Recursive   bool
-  Nullables   []bool
+  // JsDocTags contains the alias's ordered documentation tags.
+  JsDocTags []IJsDocTagInfo
+  // Recursive marks a recursive alias definition.
+  Recursive bool
+  // Nullables records the nullability of analyzed uses.
+  Nullables []bool
 }
 
+// MetadataAliasType_create builds an alias type from props. The JSDoc tags and
+// nullability list are copied; Value and Description are stored as given.
+//
+// @evidence contracts/common.md#principled-implementation The slices that other code appends to are copied so two types never share a backing array, while the value schema is shared because it is the type's definition.
+// @evidence contracts/common.md#clear-and-simple-design One constructor.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A nil Value is stored as nil and is left for the caller or a later load to set.
+// @evidence contracts/common.md#meaningful-documentation The doc states which fields are copied.
 func MetadataAliasType_create(props MetadataAliasType) *MetadataAliasType {
   return &MetadataAliasType{
     Name:        props.Name,
@@ -31,20 +66,14 @@ func MetadataAliasType_create(props MetadataAliasType) *MetadataAliasType {
   }
 }
 
-func MetadataAliasType__From_without_value(props IMetadataSchema_IAliasType) *MetadataAliasType {
-  return MetadataAliasType_create(MetadataAliasType{
-    Name:        props.Name,
-    Value:       nil,
-    Description: props.Description,
-    Recursive:   props.Recursive,
-    JsDocTags:   append([]IJsDocTagInfo{}, props.JsDocTags...),
-    Nullables:   append([]bool{}, props.Nullables...),
-  })
-}
-
 // GetDisplayName returns the human-facing rendering of the type: the
 // structural form for anonymous (inline) types, the identifier name otherwise.
 // Identity-sensitive logic (function keys, deduplication) must keep using Name.
+//
+// @evidence contracts/common.md#principled-implementation The display name is used when it was recorded, which is the structural form of an anonymous alias type, and otherwise the identifier name, while identity logic keeps reading Name.
+// @evidence contracts/common.md#clear-and-simple-design One branch.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The two names are separate fields and the identity name is not overwritten.
+// @evidence contracts/common.md#meaningful-documentation The doc states the rule and the identity warning.
 func (obj *MetadataAliasType) GetDisplayName() string {
   if obj.DisplayName != "" {
     return obj.DisplayName
@@ -52,6 +81,13 @@ func (obj *MetadataAliasType) GetDisplayName() string {
   return obj.Name
 }
 
+// ToJSON returns the JSON form of the alias type, which requires Value to be
+// set. The display name is not part of it.
+//
+// @evidence contracts/common.md#principled-implementation The JSON form is the serializable projection of the type, with the value schema converted recursively and the slices copied.
+// @evidence contracts/common.md#clear-and-simple-design One record construction.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A nil Value is a caller error that the doc states and the code does not mask.
+// @evidence contracts/common.md#meaningful-documentation The doc states the Value precondition and the omitted display name.
 func (obj *MetadataAliasType) ToJSON() IMetadataSchema_IAliasType {
   return IMetadataSchema_IAliasType{
     Name:        obj.Name,

package/native/core/schemas/metadata/MetadataArray.go

@@ -1,12 +1,28 @@
 package metadata
 
+// MetadataArray is one use of a shared array type in a schema, with the type tag
+// rows of that use. Type names and Tags must be final before the first cached
+// name lookup; later changes do not invalidate either cache.
+//
+// @evidence contracts/common.md#principled-implementation Tags are per use while the array type is shared, so the reference owns the tags and points to the type.
+// @evidence contracts/common.md#clear-and-simple-design A reference record with two cached strings.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The cache behavior is stated rather than hidden.
+// @evidence contracts/common.md#meaningful-documentation The doc states the sharing and the cache limitation.
 type MetadataArray struct {
-  Type          *MetadataArrayType
+  // Type is the shared array definition referenced by this use.
+  Type *MetadataArrayType
+  // Tags contains this use's alternative rows of jointly applied tags.
   Tags          [][]IMetadataTypeTag
   name_         string
   display_name_ string
 }
 
+// MetadataArray_create references props.Type and copies the tag matrix.
+//
+// @evidence contracts/common.md#principled-implementation The use owns its tags and shares the array type, which is meant to be shared.
+// @evidence contracts/common.md#clear-and-simple-design One constructor.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Nothing is dropped except the caches, which start empty.
+// @evidence contracts/common.md#meaningful-documentation The doc states which part is copied.
 func MetadataArray_create(props MetadataArray) *MetadataArray {
   return &MetadataArray{
     Type: props.Type,
@@ -14,6 +30,13 @@ func MetadataArray_create(props MetadataArray) *MetadataArray {
   }
 }
 
+// GetName returns the identity name of the use: the array type's Name with the
+// tags applied, cached after the first call.
+//
+// @evidence contracts/common.md#principled-implementation Identity logic needs a stable name for the use, built from the type's identity name and the tags.
+// @evidence contracts/common.md#clear-and-simple-design One cached call to taggedName.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The cache is documented on the record.
+// @evidence contracts/common.md#meaningful-documentation The doc states the identity role and the caching.
 func (obj *MetadataArray) GetName() string {
   if obj.name_ == "" {
     obj.name_ = taggedName(obj.Type.Name, obj.Tags)
@@ -21,6 +44,13 @@ func (obj *MetadataArray) GetName() string {
   return obj.name_
 }
 
+// GetDisplayName returns the human-facing name of the use: the array type's
+// display name with the tags applied.
+//
+// @evidence contracts/common.md#principled-implementation Messages use the structural display form while identity logic keeps GetName.
+// @evidence contracts/common.md#clear-and-simple-design One cached call to taggedName.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts No consumer-specific rewriting.
+// @evidence contracts/common.md#meaningful-documentation The doc states it is the human-facing counterpart.
 func (obj *MetadataArray) GetDisplayName() string {
   if obj.display_name_ == "" {
     obj.display_name_ = taggedName(obj.Type.GetDisplayName(), obj.Tags)
@@ -28,6 +58,12 @@ func (obj *MetadataArray) GetDisplayName() string {
   return obj.display_name_
 }
 
+// ToJSON returns the by-name reference to the array type with a copy of the tags.
+//
+// @evidence contracts/common.md#principled-implementation The shared array type is serialized once in the components, so a use is written as its name and tags.
+// @evidence contracts/common.md#clear-and-simple-design One record construction.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The tags are copied.
+// @evidence contracts/common.md#meaningful-documentation The doc states the by-name form.
 func (obj *MetadataArray) ToJSON() IMetadataSchema_IReference {
   return IMetadataSchema_IReference{
     Name: obj.Type.Name,

package/native/core/schemas/metadata/MetadataArrayType.go

@@ -1,32 +1,55 @@
 package metadata
 
+// IMetadataSchema_IArrayType is the JSON form of an array type: name, element
+// schema, nullability list, recursion flag and the optional index.
+//
+// @evidence contracts/common.md#principled-implementation The JSON form lists what an array type needs to be rebuilt and leaves out the derived display name.
+// @evidence contracts/common.md#clear-and-simple-design One flat record.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A data record.
+// @evidence contracts/common.md#meaningful-documentation Each field describes the array definition produced by ToJSON.
 type IMetadataSchema_IArrayType struct {
-  Name      string
-  Value     *IMetadataSchema
+  // Name identifies the shared array definition.
+  Name string
+  // Value is the serialized element schema.
+  Value *IMetadataSchema
+  // Nullables records the nullability of analyzed uses.
   Nullables []bool
+  // Recursive marks a recursive array definition.
   Recursive bool
-  Index     *int
+  // Index is the optional collection-assigned recursive index.
+  Index *int
 }
 
+// MetadataArrayType is an array type shared by every use of it: its name, the
+// display name for messages, the element schema, which uses were nullable,
+// whether it refers to itself and its index in the collection.
+//
+// @evidence contracts/common.md#principled-implementation The element schema, flags and index belong to the type and are kept once, while tags belong to each use.
+// @evidence contracts/common.md#clear-and-simple-design One flat record.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A data record.
+// @evidence contracts/common.md#meaningful-documentation The doc names each part.
 type MetadataArrayType struct {
-  Name        string
+  // Name identifies the shared array definition.
+  Name string
+  // DisplayName is the human-facing rendering, falling back to Name when empty.
   DisplayName string
-  Value       *MetadataSchema
-  Nullables   []bool
-  Recursive   bool
-  Index       *int
-}
-
-func MetadataArrayType__From_without_value(props IMetadataSchema_IArrayType) *MetadataArrayType {
-  return MetadataArrayType_create(MetadataArrayType{
-    Name:      props.Name,
-    Value:     nil,
-    Index:     props.Index,
-    Recursive: props.Recursive,
-    Nullables: append([]bool{}, props.Nullables...),
-  })
+  // Value is the analyzed element schema; it must be set before ToJSON.
+  Value *MetadataSchema
+  // Nullables records the nullability of analyzed uses.
+  Nullables []bool
+  // Recursive marks a recursive array definition.
+  Recursive bool
+  // Index is the optional collection-assigned recursive index.
+  Index *int
 }
 
+// MetadataArrayType_create builds an array type from props. The nullability list
+// is copied; Value and Index are stored as given.
+//
+// @evidence contracts/common.md#principled-implementation The slice that others append to is copied; the element schema is the type's definition and is shared.
+// @evidence contracts/common.md#clear-and-simple-design One constructor.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A nil Value is stored as nil and left to the caller.
+// @evidence contracts/common.md#meaningful-documentation The doc states what is copied.
 func MetadataArrayType_create(props MetadataArrayType) *MetadataArrayType {
   return &MetadataArrayType{
     Name:        props.Name,
@@ -41,6 +64,11 @@ func MetadataArrayType_create(props MetadataArrayType) *MetadataArrayType {
 // GetDisplayName returns the human-facing rendering of the type: the
 // structural form for anonymous (inline) types, the identifier name otherwise.
 // Identity-sensitive logic (function keys, deduplication) must keep using Name.
+//
+// @evidence contracts/common.md#principled-implementation The display name is used when it was recorded, which is the structural form of an anonymous array type, and otherwise the identifier name, while identity logic keeps reading Name.
+// @evidence contracts/common.md#clear-and-simple-design One branch.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The two names are separate fields and the identity name is not overwritten.
+// @evidence contracts/common.md#meaningful-documentation The doc states the rule and the identity warning.
 func (obj *MetadataArrayType) GetDisplayName() string {
   if obj.DisplayName != "" {
     return obj.DisplayName
@@ -48,6 +76,12 @@ func (obj *MetadataArrayType) GetDisplayName() string {
   return obj.Name
 }
 
+// ToJSON returns the JSON form of the array type, which requires Value to be set.
+//
+// @evidence contracts/common.md#principled-implementation It is the serializable projection of the type, with the element schema converted recursively.
+// @evidence contracts/common.md#clear-and-simple-design One record construction.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A nil Value is a caller error that the doc states.
+// @evidence contracts/common.md#meaningful-documentation The doc states the Value precondition.
 func (obj *MetadataArrayType) ToJSON() IMetadataSchema_IArrayType {
   return IMetadataSchema_IArrayType{
     Name:      obj.Name,