typia 15.0.0 → 15.1.0

package/native/core/programmers/helpers/UnionExplorer.go

@@ -14,6 +14,16 @@ type unionExplorerNamespace struct{}
 
 var UnionExplorer = unionExplorerNamespace{}
 
+// UnionExplorer_IExplore is where a union is being explored. Tracable says
+// whether the path of the value is tracked, Source is where the value is checked
+// (`top` or `function`), From is the kind of parent (`top`, `array` or
+// `object`), Postfix is the path suffix and Start is the index offset of a rest
+// element.
+//
+// @evidence contracts/common.md#principled-implementation It is where a union is being explored; its 5 fields (Tracable, Source, From, Postfix, Start) are named so that a producer and a consumer cannot transpose them.
+// @evidence contracts/common.md#clear-and-simple-design A 5-field record with no methods.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A data record: it derives, defaults and validates nothing.
+// @evidence contracts/common.md#meaningful-documentation The doc states what the record is and explains its non-obvious fields.
 type UnionExplorer_IExplore struct {
   Tracable bool
   Source   string
@@ -22,62 +32,133 @@ type UnionExplorer_IExplore struct {
   Start    *int
 }
 
+// UnionExplorer_ObjectConfig is the configuration of UnionExplorer.Object, which
+// supplies the object operations.
+//
+// @evidence contracts/common.md#principled-implementation It is the configuration of UnionExplorer.Object, which supplies the object operations; its 1 members (Objector) are supplied by the caller, so the shared programmer holds no feature-specific behavior.
+// @evidence contracts/common.md#clear-and-simple-design A 1-member record of values and callbacks.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A declaration only.
+// @evidence contracts/common.md#meaningful-documentation The doc states the role.
 type UnionExplorer_ObjectConfig struct {
   Objector UnionExplorer_IObjector
 }
 
+// UnionExplorer_IObjector is the object operations that a feature supplies to
+// UnionExplorer.Object. Checker, Decoder, Unionizer, Failure and Full
+// build the feature's checks and results. Is and Required adapt a generated
+// predicate, rather than receiving the original input value.
+//
+// @evidence contracts/common.md#principled-implementation Checker tests a discriminator, Decoder emits the selected member and Unionizer handles members without a unique property. Failure/Full carry the feature's diagnostic policy; optional Is/Required adapt generated predicates, keeping the union explorer independent of checking or serialization results.
+// @evidence contracts/common.md#clear-and-simple-design The seven callbacks are the operations Object actually consumes; optional predicate/result adapters do not duplicate the feature's decoder or error policy.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A declaration only.
+// @evidence contracts/common.md#meaningful-documentation The doc states the role and the meaning of the members that are not obvious.
 type UnionExplorer_IObjector struct {
   Checker   func(props UnionExplorer_ObjectorCheckerProps) *shimast.Node
   Decoder   func(props UnionExplorer_ObjectorDecoderProps) *shimast.Node
-  Joiner    any
   Unionizer func(props UnionExplorer_ObjectorUnionizerProps) *shimast.Node
   Failure   func(props UnionExplorer_ObjectorFailureProps) *shimast.Node
-  Is        func(exp *shimast.Expression) *shimast.Node
-  Required  func(exp *shimast.Expression) *shimast.Node
-  Full      func(props UnionExplorer_ObjectorFullProps) *shimast.Node
-  Type      *shimast.TypeNode
+
+  // Is optionally adapts the chosen discriminator predicate.
+  Is func(exp *shimast.Expression) *shimast.Node
+
+  // Required optionally adapts a property-presence predicate for a unique key.
+  Required func(exp *shimast.Expression) *shimast.Node
+
+  Full func(props UnionExplorer_ObjectorFullProps) *shimast.Node
 }
 
+// UnionExplorer_ObjectorCheckerProps is the argument of the Checker operation,
+// which tests an input against one metadata schema.
+//
+// @evidence contracts/common.md#principled-implementation It is the argument of the Checker operation, which tests an input against one metadata schema; its 3 fields (Metadata, Input, Explore) are named so that a producer and a consumer cannot transpose them.
+// @evidence contracts/common.md#clear-and-simple-design A 3-field record with no methods.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A data record: it derives, defaults and validates nothing.
+// @evidence contracts/common.md#meaningful-documentation The doc states what the record is and explains its non-obvious fields.
 type UnionExplorer_ObjectorCheckerProps struct {
   Metadata *nativemetadata.MetadataSchema
   Input    *shimast.Expression
-  Explore  any
+  Explore  UnionExplorer_IExplore
 }
 
+// UnionExplorer_ObjectorDecoderProps is the argument of the Decoder operation,
+// which decodes an input as one object type.
+//
+// @evidence contracts/common.md#principled-implementation It is the argument of the Decoder operation, which decodes an input as one object type; its 3 fields (Input, Object, Explore) are named so that a producer and a consumer cannot transpose them.
+// @evidence contracts/common.md#clear-and-simple-design A 3-field record with no methods.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A data record: it derives, defaults and validates nothing.
+// @evidence contracts/common.md#meaningful-documentation The doc states what the record is.
 type UnionExplorer_ObjectorDecoderProps struct {
   Input   *shimast.Expression
   Object  *nativemetadata.MetadataObjectType
-  Explore any
+  Explore UnionExplorer_IExplore
 }
 
+// UnionExplorer_ObjectorUnionizerProps is the argument of the Unionizer
+// operation, which handles several object types that no property can
+// discriminate.
+//
+// @evidence contracts/common.md#principled-implementation It is the argument of the Unionizer operation, which handles several object types that no property can discriminate; its 3 fields (Objects, Input, Explore) are named so that a producer and a consumer cannot transpose them.
+// @evidence contracts/common.md#clear-and-simple-design A 3-field record with no methods.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A data record: it derives, defaults and validates nothing.
+// @evidence contracts/common.md#meaningful-documentation The doc states what the record is.
 type UnionExplorer_ObjectorUnionizerProps struct {
   Objects []*nativemetadata.MetadataObjectType
   Input   *shimast.Expression
-  Explore any
+  Explore UnionExplorer_IExplore
 }
 
+// UnionExplorer_ObjectorFailureProps is the argument of the Failure operation,
+// which reports that no object type matched.
+//
+// @evidence contracts/common.md#principled-implementation It is the argument of the Failure operation, which reports that no object type matched; its 3 fields (Input, Expected, Explore) are named so that a producer and a consumer cannot transpose them.
+// @evidence contracts/common.md#clear-and-simple-design A 3-field record with no methods.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A data record: it derives, defaults and validates nothing.
+// @evidence contracts/common.md#meaningful-documentation The doc states what the record is.
 type UnionExplorer_ObjectorFailureProps struct {
   Input    *shimast.Expression
   Expected string
-  Explore  any
+  Explore  UnionExplorer_IExplore
 }
 
+// UnionExplorer_ObjectorFullProps is the argument of the Full operation, which
+// wraps a matched condition with the expected description.
+//
+// @evidence contracts/common.md#principled-implementation It is the argument of the Full operation, which wraps a matched condition with the expected description; its 4 fields (Condition, Input, Expected, Explore) are named so that a producer and a consumer cannot transpose them.
+// @evidence contracts/common.md#clear-and-simple-design A 4-field record with no methods.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A data record: it derives, defaults and validates nothing.
+// @evidence contracts/common.md#meaningful-documentation The doc states what the record is.
 type UnionExplorer_ObjectorFullProps struct {
   Condition *shimast.Expression
   Input     *shimast.Expression
   Expected  string
-  Explore   any
+  Explore   UnionExplorer_IExplore
 }
 
+// UnionExplorer_ObjectProps is the argument record of UnionExplorer.Object,
+// which explores a union of object types. Level is the nesting depth: it grows
+// when the object types left after the first discrimination are explored again.
+//
+// @evidence contracts/common.md#principled-implementation It is the argument record of UnionExplorer.Object, which explores a union of object types; its 6 fields (Config, Level, Objects, Input, Explore, Emit) are named so that a producer and a consumer cannot transpose them.
+// @evidence contracts/common.md#clear-and-simple-design A 6-field record with no methods.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A data record: it derives, defaults and validates nothing.
+// @evidence contracts/common.md#meaningful-documentation The doc states what the record is and explains its non-obvious fields.
 type UnionExplorer_ObjectProps struct {
   Config  UnionExplorer_ObjectConfig
   Level   int
   Objects []*nativemetadata.MetadataObjectType
   Input   *shimast.Expression
-  Explore any
+  Explore UnionExplorer_IExplore
   Emit    *shimprinter.EmitContext
 }
 
+// UnionExplorer_ArrayLikeConfig is the configuration shared by the array, tuple,
+// set and map explorers, which supplies their operations. Empty and Success are
+// the nodes returned for an empty input and for a match.
+//
+// @evidence contracts/common.md#principled-implementation It is the configuration shared by the array, tuple, set and map explorers, which supplies their operations; its 6 members (Checker, Candidate, Decoder, Empty, Success, Failure) are supplied by the caller, so the shared programmer holds no feature-specific behavior.
+// @evidence contracts/common.md#clear-and-simple-design A 6-member record of values and callbacks.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A declaration only.
+// @evidence contracts/common.md#meaningful-documentation The doc states the role and the meaning of the members that are not obvious.
 type UnionExplorer_ArrayLikeConfig struct {
   Checker   func(props UnionExplorer_ArrayLikeCheckerProps) *shimast.Node
   Candidate func(props UnionExplorer_ArrayLikeCandidateProps) *shimast.Node
@@ -87,73 +168,158 @@ type UnionExplorer_ArrayLikeConfig struct {
   Failure   func(props UnionExplorer_ArrayLikeFailureProps) *shimast.Node
 }
 
+// UnionExplorer_ArrayLikeCheckerProps is the argument of the Checker operation
+// of an array-like union, which tests one definition against the input.
+//
+// @evidence contracts/common.md#principled-implementation It is the argument of the Checker operation of an array-like union, which tests one definition against the input; its 4 fields (Input, Definition, Explore, Container) are named so that a producer and a consumer cannot transpose them.
+// @evidence contracts/common.md#clear-and-simple-design A 4-field record with no methods.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A data record: it derives, defaults and validates nothing.
+// @evidence contracts/common.md#meaningful-documentation The doc states what the record is.
 type UnionExplorer_ArrayLikeCheckerProps struct {
-  Input      *shimast.Expression
+  Input *shimast.Expression
+
+  // Definition is element metadata for arrays/sets, a key/value metadata pair
+  // for maps, or the full MetadataTuple for tuples. The matching explorer and
+  // callback must agree on this representation.
   Definition any
-  Explore    any
-  Container  *shimast.Expression
+
+  Explore UnionExplorer_IExplore
+
+  // Container is the full array expression when Input is only its front value.
+  // Tuple callbacks may need it for container length checks.
+  Container *shimast.Expression
 }
 
+// UnionExplorer_ArrayLikeDecoderProps is the argument of the Decoder operation
+// of an array-like union, which decodes the input as one definition.
+//
+// @evidence contracts/common.md#principled-implementation It is the argument of the Decoder operation of an array-like union, which decodes the input as one definition; its 3 fields (Input, Definition, Explore) are named so that a producer and a consumer cannot transpose them.
+// @evidence contracts/common.md#clear-and-simple-design A 3-field record with no methods.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A data record: it derives, defaults and validates nothing.
+// @evidence contracts/common.md#meaningful-documentation The doc states what the record is.
 type UnionExplorer_ArrayLikeDecoderProps struct {
-  Input      *shimast.Expression
+  Input *shimast.Expression
+
+  // Definition is the full MetadataArray or MetadataTuple selected for decode.
+  // Set/map explorers provide their synthesized MetadataArray representation.
   Definition any
-  Explore    any
+
+  Explore UnionExplorer_IExplore
 }
 
+// UnionExplorer_ArrayLikeCandidateProps is the argument of the Candidate
+// operation of an array-like union, which tests the whole array against one
+// definition before it is decoded.
+//
+// @evidence contracts/common.md#principled-implementation It is the argument of the Candidate operation of an array-like union, which tests the whole array against one definition before it is decoded; its 3 fields (Input, Definition, Explore) are named so that a producer and a consumer cannot transpose them.
+// @evidence contracts/common.md#clear-and-simple-design A 3-field record with no methods.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A data record: it derives, defaults and validates nothing.
+// @evidence contracts/common.md#meaningful-documentation The doc states what the record is.
 type UnionExplorer_ArrayLikeCandidateProps struct {
-  Input      *shimast.Expression
+  Input *shimast.Expression
+
+  // Definition is the full candidate MetadataArray or MetadataTuple; Candidate
+  // validates container constraints before committing to its decoder.
   Definition any
-  Explore    any
+
+  Explore UnionExplorer_IExplore
 }
 
+// UnionExplorer_ArrayLikeFailureProps is the argument of the Failure operation
+// of an array-like union, which reports that no definition matched.
+//
+// @evidence contracts/common.md#principled-implementation It is the argument of the Failure operation of an array-like union, which reports that no definition matched; its 3 fields (Input, Expected, Explore) are named so that a producer and a consumer cannot transpose them.
+// @evidence contracts/common.md#clear-and-simple-design A 3-field record with no methods.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A data record: it derives, defaults and validates nothing.
+// @evidence contracts/common.md#meaningful-documentation The doc states what the record is.
 type UnionExplorer_ArrayLikeFailureProps struct {
   Input    *shimast.Expression
   Expected string
-  Explore  any
+  Explore  UnionExplorer_IExplore
 }
 
+// UnionExplorer_TupleProps is the argument record of UnionExplorer.Tuple, which
+// explores a union of tuple types.
+//
+// @evidence contracts/common.md#principled-implementation It is the argument record of UnionExplorer.Tuple, which explores a union of tuple types; its 6 fields (Config, Parameters, Input, Tuples, Explore, Emit) are named so that a producer and a consumer cannot transpose them.
+// @evidence contracts/common.md#clear-and-simple-design A 6-field record with no methods.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A data record: it derives, defaults and validates nothing.
+// @evidence contracts/common.md#meaningful-documentation The doc states what the record is.
 type UnionExplorer_TupleProps struct {
   Config     UnionExplorer_ArrayLikeConfig
   Parameters []*shimast.Node
   Input      *shimast.Expression
   Tuples     []*nativemetadata.MetadataTuple
-  Explore    any
+  Explore    UnionExplorer_IExplore
   Emit       *shimprinter.EmitContext
 }
 
+// UnionExplorer_ArrayProps is the argument record of UnionExplorer.Array, which
+// explores a union of array types.
+//
+// @evidence contracts/common.md#principled-implementation It is the argument record of UnionExplorer.Array, which explores a union of array types; its 6 fields (Config, Parameters, Input, Arrays, Explore, Emit) are named so that a producer and a consumer cannot transpose them.
+// @evidence contracts/common.md#clear-and-simple-design A 6-field record with no methods.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A data record: it derives, defaults and validates nothing.
+// @evidence contracts/common.md#meaningful-documentation The doc states what the record is.
 type UnionExplorer_ArrayProps struct {
   Config     UnionExplorer_ArrayLikeConfig
   Parameters []*shimast.Node
   Input      *shimast.Expression
   Arrays     []*nativemetadata.MetadataArray
-  Explore    any
+  Explore    UnionExplorer_IExplore
   Emit       *shimprinter.EmitContext
 }
 
+// UnionExplorer_ArrayOrTupleProps is the argument record of
+// UnionExplorer.Array_or_tuple, which explores a union of array and tuple
+// definitions in one pass.
+//
+// @evidence contracts/common.md#principled-implementation It is the argument record of UnionExplorer.Array_or_tuple, which explores a union of array and tuple definitions in one pass; its 6 fields (Config, Parameters, Input, Definitions, Explore, Emit) are named so that a producer and a consumer cannot transpose them.
+// @evidence contracts/common.md#clear-and-simple-design A 6-field record with no methods.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A data record: it derives, defaults and validates nothing.
+// @evidence contracts/common.md#meaningful-documentation The doc states what the record is.
 type UnionExplorer_ArrayOrTupleProps struct {
-  Config      UnionExplorer_ArrayLikeConfig
-  Parameters  []*shimast.Node
-  Input       *shimast.Expression
+  Config     UnionExplorer_ArrayLikeConfig
+  Parameters []*shimast.Node
+  Input      *shimast.Expression
+
+  // Definitions contains MetadataArray and MetadataTuple candidates in the
+  // order supplied by the owning feature; no other dynamic type is supported.
   Definitions []any
-  Explore     any
-  Emit        *shimprinter.EmitContext
+
+  Explore UnionExplorer_IExplore
+  Emit    *shimprinter.EmitContext
 }
 
+// UnionExplorer_SetProps is the argument record of UnionExplorer.Set, which
+// explores a union of set types.
+//
+// @evidence contracts/common.md#principled-implementation It is the argument record of UnionExplorer.Set, which explores a union of set types; its 6 fields (Config, Parameters, Input, Sets, Explore, Emit) are named so that a producer and a consumer cannot transpose them.
+// @evidence contracts/common.md#clear-and-simple-design A 6-field record with no methods.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A data record: it derives, defaults and validates nothing.
+// @evidence contracts/common.md#meaningful-documentation The doc states what the record is.
 type UnionExplorer_SetProps struct {
   Config     UnionExplorer_ArrayLikeConfig
   Parameters []*shimast.Node
   Input      *shimast.Expression
   Sets       []*nativemetadata.MetadataSet
-  Explore    any
+  Explore    UnionExplorer_IExplore
   Emit       *shimprinter.EmitContext
 }
 
+// UnionExplorer_MapProps is the argument record of UnionExplorer.Map, which
+// explores a union of map types.
+//
+// @evidence contracts/common.md#principled-implementation It is the argument record of UnionExplorer.Map, which explores a union of map types; its 6 fields (Config, Parameters, Input, Maps, Explore, Emit) are named so that a producer and a consumer cannot transpose them.
+// @evidence contracts/common.md#clear-and-simple-design A 6-field record with no methods.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A data record: it derives, defaults and validates nothing.
+// @evidence contracts/common.md#meaningful-documentation The doc states what the record is.
 type UnionExplorer_MapProps struct {
   Config     UnionExplorer_ArrayLikeConfig
   Parameters []*shimast.Node
   Input      *shimast.Expression
   Maps       []*nativemetadata.MetadataMap
-  Explore    any
+  Explore    UnionExplorer_IExplore
   Emit       *shimprinter.EmitContext
 }
 
@@ -569,7 +735,7 @@ type unionExplorer_check_union_array_likeProps struct {
   Parameters  []*shimast.Node
   Input       *shimast.Expression
   Definitions []any
-  Explore     any
+  Explore     UnionExplorer_IExplore
   Emit        *shimprinter.EmitContext
 }
 
@@ -1060,49 +1226,15 @@ func unionExplorer_return_or_statement(node *shimast.Node, emit ...*shimprinter.
   return f.NewReturnStatement(node)
 }
 
-func unionExplorer_with_tracable(base any, tracable bool) any {
-  switch value := base.(type) {
-  case UnionExplorer_IExplore:
-    value.Tracable = tracable
-    return value
-  case *UnionExplorer_IExplore:
-    next := *value
-    next.Tracable = tracable
-    return next
-  case map[string]any:
-    next := map[string]any{}
-    for k, v := range value {
-      next[k] = v
-    }
-    next["tracable"] = tracable
-    return next
-  default:
-    return base
-  }
+func unionExplorer_with_tracable(base UnionExplorer_IExplore, tracable bool) UnionExplorer_IExplore {
+  base.Tracable = tracable
+  return base
 }
 
-func unionExplorer_with_postfix(base any, tracable bool, postfix string) any {
-  switch value := base.(type) {
-  case UnionExplorer_IExplore:
-    value.Tracable = tracable
-    value.Postfix = postfix
-    return value
-  case *UnionExplorer_IExplore:
-    next := *value
-    next.Tracable = tracable
-    next.Postfix = postfix
-    return next
-  case map[string]any:
-    next := map[string]any{}
-    for k, v := range value {
-      next[k] = v
-    }
-    next["tracable"] = tracable
-    next["postfix"] = postfix
-    return next
-  default:
-    return base
-  }
+func unionExplorer_with_postfix(base UnionExplorer_IExplore, tracable bool, postfix string) UnionExplorer_IExplore {
+  base.Tracable = tracable
+  base.Postfix = postfix
+  return base
 }
 
 var unionExplorer_factory = shimast.NewNodeFactory(shimast.NodeFactoryHooks{})

package/native/core/programmers/helpers/UnionPredicator.go

@@ -6,6 +6,15 @@ type unionPredicatorNamespace struct{}
 
 var UnionPredicator = unionPredicatorNamespace{}
 
+// UnionPredicator_ISpecialized is one object type of a union with the property
+// that discriminates it. Index is the position of the object in the union, and
+// Neighbor says whether the discriminating property also exists in another
+// member.
+//
+// @evidence contracts/common.md#principled-implementation It is one object type of a union with the property that discriminates it; its 4 fields (Index, Object, Property, Neighbor) are named so that a producer and a consumer cannot transpose them.
+// @evidence contracts/common.md#clear-and-simple-design A 4-field record with no methods.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A data record: it derives, defaults and validates nothing.
+// @evidence contracts/common.md#meaningful-documentation The doc states what the record is and explains its non-obvious fields.
 type UnionPredicator_ISpecialized struct {
   Index    int
   Object   *nativemetadata.MetadataObjectType

package/native/core/programmers/helpers/clone_joiner_optional_condition_test.go

@@ -11,12 +11,17 @@ import (
 //
 // Exact optional properties use two runtime branches: `optional?: T` must only
 // emit the property when the decoded value is not undefined, while
-// `optional?: T | undefined` must also preserve a present own `undefined`
+// `optional?: T | undefined` must also preserve a present `undefined`
 // property.
 //
 //  1. Build a strict optional clone entry and assert it uses only value presence.
 //  2. Build an explicit undefined-union optional entry and assert it also checks
 //     property presence with the `in` operator.
+//
+// @evidence contracts/testing.md#behavioral-verification The clone joiner builds entries for optional?: T and optional?: T | undefined; the strict entry must test only value presence and the explicit-union entry must add an in-operator presence test on the literal key of the original input.
+// @evidence contracts/testing.md#independent-expectations Exact optional property semantics decide which guard each form needs; the expected condition shapes are authored in the test and inspected on the AST.
+// @evidence contracts/testing.md#distinguishing-cases Strict optional is the baseline and explicit undefined union the one-axis variant; required properties are not asserted here.
+// @evidence contracts/testing.md#execution-ownership The canonical native Go command (pnpm test:go:native) runs this same-package Test function in process. It builds AST nodes in memory and inspects them, with no checker, filesystem fixture or process.
 func TestCloneJoinerOptionalConditionDistinguishesExplicitUndefined(t *testing.T) {
   factory := shimast.NewNodeFactory(shimast.NodeFactoryHooks{})
   input := factory.NewIdentifier("input")
@@ -36,6 +41,10 @@ func TestCloneJoinerOptionalConditionDistinguishesExplicitUndefined(t *testing.T
   if strict.AsBinaryExpression().OperatorToken.Kind != shimast.KindExclamationEqualsEqualsToken {
     t.Fatal("strict optional condition should only test value presence")
   }
+  strictValue := strict.AsBinaryExpression()
+  if strictValue.Right != property || strictValue.Left.Kind != shimast.KindIdentifier || strictValue.Left.Text() != "undefined" {
+    t.Fatal("strict optional condition must compare the requested value with undefined")
+  }
 
   explicit := cloneJoiner_optional_condition(IExpressionEntry{
     Input: property,
@@ -45,6 +54,10 @@ func TestCloneJoinerOptionalConditionDistinguishesExplicitUndefined(t *testing.T
   if outer.OperatorToken.Kind != shimast.KindBarBarToken {
     t.Fatal("explicit undefined union should add a property-presence branch")
   }
+  valuePresence := outer.Left.AsBinaryExpression()
+  if valuePresence.OperatorToken.Kind != shimast.KindExclamationEqualsEqualsToken || valuePresence.Right != property || valuePresence.Left.Kind != shimast.KindIdentifier || valuePresence.Left.Text() != "undefined" {
+    t.Fatal("explicit undefined union must retain the requested value-presence comparison")
+  }
   if outer.Right.AsBinaryExpression().OperatorToken.Kind != shimast.KindInKeyword {
     t.Fatal("explicit undefined union should use the in operator")
   }

package/native/core/programmers/helpers/function_programmer_unique_names_test.go

@@ -12,6 +12,11 @@ import (
 // Object-property helpers and array-like union helpers can use related prefixes
 // inside the same generated validator. They must never reserve the same `const`
 // name, even when their deduplication keys are different.
+//
+// @evidence contracts/testing.md#behavioral-verification Object-property and array-like union helper names are registered in one function programmer and must never repeat; the same union key must deduplicate to its first name.
+// @evidence contracts/testing.md#independent-expectations Uniqueness of declared const names is a language requirement for the generated scope, so the check compares names against each other and not against a snapshot.
+// @evidence contracts/testing.md#distinguishing-cases Distinct keys with related prefixes and a repeated key separate collision avoidance from deduplication.
+// @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 programmer in memory with no checker, filesystem fixture or process.
 func TestFunctionProgrammerKeepsHelperDeclarationNamesUnique(t *testing.T) {
   factory := shimast.NewNodeFactory(shimast.NodeFactoryHooks{})
   functor := NewFunctionProgrammer("typia.createIs")

package/native/core/programmers/helpers/joiner_branch_coverage_test.go

@@ -22,6 +22,11 @@ import (
 // 2. Exercise clone, prune, and stringify joiners for objects, arrays, and tuples.
 // 3. Exercise function programmer variable declaration and declaration-disable branches.
 // 4. Verify string joining, internal import fallback, and metadata pattern helpers.
+//
+// @evidence contracts/testing.md#behavioral-verification Clone, notation, prune and stringify joiners are called with literal, dynamic string, numeric, boolean and template keys for objects, arrays and tuples; most assertions only require a non-nil AST result and a few compare skipped or converted pieces.
+// @evidence contracts/testing.md#independent-expectations There is no independent oracle for most checks; they certify that a node is produced. This is a limitation of the test.
+// @evidence contracts/testing.md#distinguishing-cases Many metadata shapes are visited but few negative twins exist, so a joiner emitting the wrong code for a shape could still pass.
+// @evidence contracts/testing.md#execution-ownership The typia_native_internal Go command (go -C packages/typia/test test -tags typia_native_internal ../native/...) runs this same-package Test function in process. The tagged test builds AST nodes in memory with no checker, filesystem fixture or process.
 func TestJoinerBranchCoverage(t *testing.T) {
   factory := shimast.NewNodeFactory(shimast.NodeFactoryHooks{})
   input := factory.NewIdentifier("input")

package/native/core/programmers/helpers/option_predicator_contract_matrix_test.go

@@ -0,0 +1,84 @@
+package helpers
+
+import (
+  shimcore "github.com/microsoft/typescript-go/shim/core"
+  nativecontext "github.com/samchon/typia/packages/typia/native/core/context"
+  metadata "github.com/samchon/typia/packages/typia/native/core/schemas/metadata"
+  "testing"
+)
+
+// TestOptionPredicatorContractMatrix verifies option defaults and their exact-optional conjunction.
+//
+// Finite implies numeric admission, while omitted undefined permits undefined.
+// Exact optionality requires the compiler flag, explicit undefined:false and an
+// optional property; only an optional property without undefined is strict.
+//
+// @evidence contracts/testing.md#behavioral-verification Calls all six option predicates with nil, false and true options and the complete compiler/undefined/property decision table.
+// @evidence contracts/testing.md#independent-expectations Literal numeric rows and the two authored positive exact-optional rows define the oracle; every other exact-optional row must be false.
+// @evidence contracts/testing.md#distinguishing-cases Nil compiler, unset/false/true compiler flags, omitted/false/true undefined, nil metadata and all optional/required pairs are exercised. Finite-on/numeric-off must still enable numeric admission.
+// @evidence contracts/testing.md#execution-ownership The native Go runner invokes this same-package unit in process on actual contexts and metadata, without a compiler or JavaScript subprocess.
+func TestOptionPredicatorContractMatrix(t *testing.T) {
+  yes, no := true, false
+  flags := []struct {
+    name  string
+    value *bool
+  }{{"nil", nil}, {"false", &no}, {"true", &yes}}
+  numeric := map[string]bool{"nil/nil": false, "nil/false": false, "nil/true": true, "false/nil": false, "false/false": false, "false/true": true, "true/nil": true, "true/false": true, "true/true": true}
+  for _, n := range flags {
+    for _, f := range flags {
+      t.Run("numeric="+n.name+"/finite="+f.name, func(t *testing.T) {
+        options := nativecontext.ITransformOptions{Numeric: n.value, Finite: f.value}
+        if actual := OptionPredicator.Numeric(options); actual != numeric[n.name+"/"+f.name] {
+          t.Fatalf("numeric=%v", actual)
+        }
+        if actual := OptionPredicator.Finite(options); actual != (f.name == "true") {
+          t.Fatalf("finite=%v", actual)
+        }
+      })
+    }
+  }
+  for _, flag := range flags {
+    t.Run("functional-and-undefined="+flag.name, func(t *testing.T) {
+      options := nativecontext.ITransformOptions{Functional: flag.value, Undefined: flag.value}
+      if actual := OptionPredicator.Functional(options); actual != (flag.name == "true") {
+        t.Fatalf("functional=%v", actual)
+      }
+      if actual := OptionPredicator.Undefined(options); actual != (flag.name != "false") {
+        t.Fatalf("undefined=%v", actual)
+      }
+    })
+  }
+  compilers := []struct {
+    name  string
+    value *shimcore.CompilerOptions
+  }{
+    {"nil", nil}, {"unset", &shimcore.CompilerOptions{}}, {"false", &shimcore.CompilerOptions{ExactOptionalPropertyTypes: shimcore.TSFalse}}, {"true", &shimcore.CompilerOptions{ExactOptionalPropertyTypes: shimcore.TSTrue}},
+  }
+  properties := []struct {
+    name  string
+    value *metadata.MetadataSchema
+  }{
+    {"nil", nil}, {"optional-required", &metadata.MetadataSchema{Optional: true, Required: true}},
+    {"optional-undefined", &metadata.MetadataSchema{Optional: true, Required: false}},
+    {"required-only", &metadata.MetadataSchema{Optional: false, Required: true}},
+    {"required-undefined", &metadata.MetadataSchema{Optional: false, Required: false}},
+  }
+  positive := map[string][2]bool{"true/false/optional-required": {true, true}, "true/false/optional-undefined": {true, false}}
+  for _, compiler := range compilers {
+    for _, undefined := range flags {
+      for _, property := range properties {
+        name := compiler.name + "/" + undefined.name + "/" + property.name
+        t.Run(name, func(t *testing.T) {
+          context := nativecontext.ITypiaContext{CompilerOptions: compiler.value, Options: nativecontext.ITransformOptions{Undefined: undefined.value}}
+          expected := positive[name]
+          if actual := OptionPredicator.ExactOptionalProperty(context, property.value); actual != expected[0] {
+            t.Fatalf("exact=%v want %v", actual, expected[0])
+          }
+          if actual := OptionPredicator.StrictOptionalUndefined(context, property.value); actual != expected[1] {
+            t.Fatalf("strict=%v want %v", actual, expected[1])
+          }
+        })
+      }
+    }
+  }
+}

package/native/core/programmers/helpers/random_joiner_recursive_array_guard_test.go

@@ -18,6 +18,11 @@ import (
 //     decision while still detecting that an owner path exists below them.
 //  3. Check tuple owners and map-key graph cycles.
 //  4. Ignore arrays of a separate recursive object when the current owner differs.
+//
+// @evidence contracts/testing.md#behavioral-verification The random joiner's recursive-array decision is called on direct recursive arrays, fixed edges to the owner, owner tuples and a separate recursive object; guards are required for the first three and not for the last, and boundaries terminate inside nested containers.
+// @evidence contracts/testing.md#independent-expectations A depth guard is needed exactly when the array is the variable edge back to the owning recursive object; authored graphs state which edge is which.
+// @evidence contracts/testing.md#distinguishing-cases Required and not-required guards are both asserted, with several container shapes for the boundary case.
+// @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 helper on constructed metadata with no checker, filesystem fixture or process.
 func TestRandomJoinerRequiresRecursiveArrayGuardFor(t *testing.T) {
   stringMeta := randomJoinerGuardAtomic("string")
   direct := nativemetadata.MetadataArrayType_create(nativemetadata.MetadataArrayType{