typia 15.0.0 → 15.1.0

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

@@ -2,31 +2,58 @@ package metadata
 
 import "strings"
 
+// IMetadataSchema_IAtomic is the JSON form of an atomic: its primitive type name
+// and the tag rows.
+//
+// @evidence contracts/common.md#principled-implementation An atomic has no shared type, so its JSON form is the type name and the tags themselves.
+// @evidence contracts/common.md#clear-and-simple-design Two fields.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A data record.
+// @evidence contracts/common.md#meaningful-documentation Each field describes the atomic projection produced by ToJSON.
 type IMetadataSchema_IAtomic struct {
+  // Type is the primitive category of this atomic.
   Type string
+  // Tags contains alternative rows whose tags apply together within each row.
   Tags [][]IMetadataTypeTag
 }
 
+// MetadataAtomic is a primitive type (`boolean`, `number`, `bigint` or `string`)
+// with the rows of type tags that constrain it. Each row is one alternative and
+// the tags inside a row apply together. The name is computed once and cached, so
+// Type and Tags must be final before the first GetName.
+//
+// @evidence contracts/common.md#principled-implementation A primitive has no shared declaration, so the record holds the type and the tag alternatives directly, and the name is cached because it is compared and used as a key often.
+// @evidence contracts/common.md#clear-and-simple-design Two fields and one cache.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The cache limitation is stated, not hidden.
+// @evidence contracts/common.md#meaningful-documentation The doc states the row meaning and the cache limitation.
 type MetadataAtomic struct {
-  Type  string
+  // Type is the primitive category: boolean, number, bigint or string.
+  Type string
+  // Tags contains alternative rows of jointly applied type tags.
   Tags  [][]IMetadataTypeTag
   name_ string
 }
 
+// MetadataAtomic_create builds an atomic from props and copies the tag matrix, so
+// later edits of the caller's rows do not reach it.
+//
+// @evidence contracts/common.md#principled-implementation The comment-tag step rewrites atomic tag rows in place, so each atomic must own its rows, as every other tagged member does.
+// @evidence contracts/common.md#clear-and-simple-design One constructor using cloneTagMatrix.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Sharing the caller's matrix was the defect this ownership removes, and a unit test pins it.
+// @evidence contracts/common.md#meaningful-documentation The doc states that the matrix is copied.
 func MetadataAtomic_create(props MetadataAtomic) *MetadataAtomic {
   return &MetadataAtomic{
     Type: props.Type,
-    Tags: props.Tags,
+    Tags: cloneTagMatrix(props.Tags),
   }
 }
 
-func MetadataAtomic_from(json IMetadataSchema_IAtomic) *MetadataAtomic {
-  return MetadataAtomic_create(MetadataAtomic{
-    Type: json.Type,
-    Tags: json.Tags,
-  })
-}
-
+// GetName returns the type, or `(type & tag)` for one row, or
+// `(type & (row | row))` for several, with the tags of a row joined by `&`.
+//
+// @evidence contracts/common.md#principled-implementation The name is the type intersected with the tag alternatives, which is how the tagged type is written in TypeScript, and it is cached after the first call.
+// @evidence contracts/common.md#clear-and-simple-design A cache check and one private helper that formats the rows.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The cache limitation is documented on the record.
+// @evidence contracts/common.md#meaningful-documentation The doc gives the output forms.
 func (obj *MetadataAtomic) GetName() string {
   if obj.name_ == "" {
     obj.name_ = metadataAtomic_getName(obj)
@@ -34,10 +61,17 @@ func (obj *MetadataAtomic) GetName() string {
   return obj.name_
 }
 
+// ToJSON returns the JSON form with independent tag rows. References inside
+// individual tag values remain shared.
+//
+// @evidence contracts/common.md#principled-implementation The primitive and tag records are projected with copied matrix rows; nested tag payloads remain shared.
+// @evidence contracts/common.md#clear-and-simple-design One record construction.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The matrix is copied.
+// @evidence contracts/common.md#meaningful-documentation The doc states that the tags are copied.
 func (obj *MetadataAtomic) ToJSON() IMetadataSchema_IAtomic {
   return IMetadataSchema_IAtomic{
     Type: obj.Type,
-    Tags: obj.Tags,
+    Tags: cloneTagMatrix(obj.Tags),
   }
 }
 

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

@@ -14,21 +14,37 @@ package metadata
 // intersection tag assigner is one such site. A pointer type such as
 // `*math/big.Int` would compare identity there and, for bigints alone,
 // silently drop whatever the comparison decides.
+//
+// @evidence contracts/common.md#principled-implementation The value is kept as base-10 text, which stays exact at every magnitude and, as a comparable struct, compares by value with == like every other constant value, which the factories rely on.
+// @evidence contracts/common.md#clear-and-simple-design One string field.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The type is a stand-in for an unexported typescript-go type and invents no other representation.
+// @evidence contracts/common.md#meaningful-documentation The doc explains why the stand-in exists and why it must stay comparable.
 type MetadataBigint struct {
-  // Text is the exact value in base 10, prefixed with `-` when negative. A
-  // bigint exists to hold what a float64 cannot, so the digits are the only
-  // representation that stays exact at every magnitude.
+  // Text is the exact value in base 10, prefixed with `-` when negative.
+  // The metadata producer supplies the checker's canonical digits, avoiding
+  // conversion of an exact integer through float64.
   Text string
 }
 
 // String renders the base-10 digits, which is what every consumer that lowers a
 // bigint into emitted code reads through `fmt.Sprint`.
+//
+// @evidence contracts/common.md#principled-implementation Returning the stored digits is what code lowering a bigint into emitted text reads through fmt.Sprint.
+// @evidence contracts/common.md#clear-and-simple-design One accessor.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts No reformatting of the digits.
+// @evidence contracts/common.md#meaningful-documentation The doc states that it renders the digits.
 func (obj MetadataBigint) String() string {
   return obj.Text
 }
 
 // MarshalJSON writes the digits unquoted, so metadata marshaled by a
-// downstream tool carries the same JSON number a plain integer would.
+// downstream tool carries the same JSON number a plain integer would. Text is
+// expected to contain the producer's canonical decimal digits; empty text is 0.
+//
+// @evidence contracts/common.md#principled-implementation The digits are written unquoted as a JSON number, so metadata marshaled by a downstream tool carries the same number an integer would, and empty text is written as 0.
+// @evidence contracts/common.md#clear-and-simple-design One method with one empty-text branch.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The output is not routed through a float, so large values keep every digit.
+// @evidence contracts/common.md#meaningful-documentation The doc states the unquoted form.
 func (obj MetadataBigint) MarshalJSON() ([]byte, error) {
   if obj.Text == "" {
     return []byte("0"), nil