typia 15.0.0 → 15.1.0

package/native/core/factories/metadata_comment_tag_factory_rejects_out_of_range_integer_test.go

@@ -29,6 +29,11 @@ import "testing"
 //  3. Keep the existing non-integer and unsigned diagnostics untouched.
 //  4. Require the accepted range to be int64's on every platform, not the
 //     compiling platform's `int`.
+//
+// @evidence contracts/testing.md#behavioral-verification Integer comment tag parsing is called on values at or beyond int64's unsupported upper bound, below its lower bound, and on accepted int64 boundary values; rejection requires a report, while accepted results are compared with authored int64 literals, including values beyond int32.
+// @evidence contracts/testing.md#independent-expectations The destination integer range and the documented rule that no value may wrap silently supply the expectations, which are authored numerals.
+// @evidence contracts/testing.md#distinguishing-cases Large positive and negative magnitudes are the negatives and boundary in-range values the positives.
+// @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 parser in memory with no checker, filesystem fixture or process.
 func TestMetadataCommentTagFactoryRejectsOutOfRangeInteger(t *testing.T) {
   parse := func(value string, unsigned bool) (*int64, []string) {
     messages := []string{}
@@ -102,8 +107,8 @@ func TestMetadataCommentTagFactoryRejectsOutOfRangeInteger(t *testing.T) {
   // These sit above int32 and below int64. A guard written against `int`
   // accepts them here and converts them out of range on `@ttsc/linux-arm` --
   // the same defect this test closes, moved to a platform the suite does not
-  // usually run on. `GOARCH=arm go vet ./core/factories/` is what executes this
-  // case for real; on a 64-bit host it is the declared type that carries it.
+  // usually run on. Cross-platform vet can check the destination types but
+  // does not execute this test; runtime portability needs a run on that target.
   for _, tuple := range []struct {
     value    string
     expected int64

package/native/core/factories/metadata_comment_tag_factory_string_length_helpers_test.go

@@ -15,6 +15,11 @@ import (
 //
 //  1. Parse @length and require both comparison helpers at the same boundary.
 //  2. Parse @minLength and @maxLength and require their corresponding helper.
+//
+// @evidence contracts/testing.md#behavioral-verification @length, @minLength and @maxLength comment tags are parsed and the emitted validators must name the same comparison helpers as the type-tag spellings.
+// @evidence contracts/testing.md#independent-expectations The type-tag declarations are the reference for which helpers a length constraint imports; the expected helper names come from that reference.
+// @evidence contracts/testing.md#distinguishing-cases Three spellings are checked for both bounds and one bound each.
+// @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 factory in memory with no checker, filesystem fixture or process.
 func TestMetadataCommentTagFactoryStringLengthHelpers(t *testing.T) {
   parse := func(name string, value string) []schemametadata.IMetadataTypeTag {
     t.Helper()

package/native/core/factories/metadata_type_tag_factory_accepts_legal_tag_combinations_test.go

@@ -13,9 +13,14 @@ import (
 // that over-matches would reject `Minimum<0> & Maximum<10>`, which neither tag's
 // `exclusive` list names and which every bounded-range type depends on.
 //
-// 1. Combine each array-form tag with a kind absent from its exclusive list.
+// 1. Accept each array-form tag alone and all four opposite-end numeric bound pairs.
 // 2. Combine bool-form tags of differing kinds, which the untouched branch owns.
 // 3. Require every combination, and each tag alone, to validate.
+//
+// @evidence contracts/testing.md#behavioral-verification The type tag validator is called on single tags, opposite-end bound pairs and bool-form tags of different kinds, and must report nothing.
+// @evidence contracts/testing.md#independent-expectations The declared exclusive lists, transcribed in the test, name the only forbidden pairs, so combinations outside them are legal by specification.
+// @evidence contracts/testing.md#distinguishing-cases This is the negative twin of the rejection cases and guards against 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 validator on constructed tags with no checker, filesystem fixture or process.
 func TestMetadataTypeTagFactoryAcceptsLegalTagCombinations(t *testing.T) {
   declarations := metadataTypeTagFactoryTestDeclarations()
   byKind := map[string]metadataTypeTagFactoryTestDeclaration{}

package/native/core/factories/metadata_type_tag_factory_keeps_bool_form_exclusivity_test.go

@@ -16,6 +16,11 @@ import (
 //
 // 1. Duplicate a bool-form kind and require rejection naming the kind.
 // 2. Require an opted-out `exclusive: false` tag to permit its own duplicate.
+//
+// @evidence contracts/testing.md#behavioral-verification The validator is called on a duplicated bool-form kind, and on a tag that opts out of exclusivity; the first must be rejected with a report naming the kind and the second must be accepted.
+// @evidence contracts/testing.md#independent-expectations Bool-form exclusivity is declared by each tag; both verdicts are authored from the declaration.
+// @evidence contracts/testing.md#distinguishing-cases Rejected duplicate versus permitted opted-out duplicate form the pair.
+// @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 validator on constructed tags with no checker, filesystem fixture or process.
 func TestMetadataTypeTagFactoryKeepsBoolFormExclusivity(t *testing.T) {
   success, messages := metadataTypeTagFactoryTestValidate("string", []schemametadata.IMetadataTypeTag{
     {Target: "string", Name: "Format<\"uuid\">", Kind: "format", Exclusive: true},

package/native/core/factories/metadata_type_tag_factory_rejects_cross_kind_exclusive_tags_test.go

@@ -21,6 +21,11 @@ import (
 // 1. Derive every declared cross-kind pair from the declarations themselves.
 // 2. Validate each pair, both orders, and require rejection naming the conflict.
 // 3. Require all six declarations to contribute exactly one cross-kind partner.
+//
+// @evidence contracts/testing.md#behavioral-verification For every array-form declaration the validator is called with its declared cross-kind partner and must reject the pair with a conflict report.
+// @evidence contracts/testing.md#independent-expectations The transcribed interface declarations are the specification of which kinds conflict.
+// @evidence contracts/testing.md#distinguishing-cases The sweep covers every declaration and asserts each names exactly one cross-kind partner, so omissions 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 calls the validator on constructed tags with no checker, filesystem fixture or process.
 func TestMetadataTypeTagFactoryRejectsCrossKindExclusiveTags(t *testing.T) {
   declarations := metadataTypeTagFactoryTestDeclarations()
   byKind := map[string]metadataTypeTagFactoryTestDeclaration{}

package/native/core/factories/metadata_type_tag_factory_rejects_duplicated_array_form_tags_test.go

@@ -21,6 +21,11 @@ import (
 // 1. Build two tags of one kind from each array-form declaration.
 // 2. Validate the pair and require rejection.
 // 3. Require the report to name the kind and the conflicting tag.
+//
+// @evidence contracts/testing.md#behavioral-verification For every array-form declaration the validator is called with two tags of its own kind and must reject the duplicate with a report.
+// @evidence contracts/testing.md#independent-expectations Each declaration lists its own kind as exclusive, so a duplicate is forbidden by specification.
+// @evidence contracts/testing.md#distinguishing-cases One duplicate pair per declaration; distinct-kind pairs are owned by the legal-combinations 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 validator on constructed tags with no checker, filesystem fixture or process.
 func TestMetadataTypeTagFactoryRejectsDuplicatedArrayFormTags(t *testing.T) {
   for _, declaration := range metadataTypeTagFactoryTestDeclarations() {
     first := declaration.tag("A")

package/native/core/factories/metadata_type_tag_factory_reports_all_invalid_candidates_test.go

@@ -18,6 +18,11 @@ import (
 //  1. Build one structurally recognizable tag with a non-literal value.
 //  2. Analyze it without a valid companion and require no emitted metadata tag.
 //  3. Require the collected validation message to reach the factory errors.
+//
+// @evidence contracts/testing.md#behavioral-verification Analyze runs on a lone typia.tag object of kind default whose value metadata is a string atomic and not a literal; no metadata tag may be produced and exactly one error with messages must be retained.
+// @evidence contracts/testing.md#independent-expectations A rejected tag must surface its diagnostic even without a valid companion; the single non-literal-value input and the expected empty tags plus one error are authored. The exact diagnostic text is not asserted.
+// @evidence contracts/testing.md#distinguishing-cases Only the lone invalid tag is asserted; a rejected tag beside a valid one is not asserted by this test.
+// @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 factory on constructed tags with no checker, filesystem fixture or process.
 func TestMetadataTypeTagFactoryReportsAllInvalidCandidates(t *testing.T) {
   invalid := metadataTypeTagFactoryAllInvalidContainer("InvalidValue",
     metadataTypeTagFactoryAllInvalidProperty("target", MetadataFactory.SoleLiteral("array")),

package/native/core/factories/numeric_range_factory_enforces_64bit_bounds_test.go

@@ -15,8 +15,13 @@ import (
 // bounds inclusively at its maximum (`2 ** 63 - 1`, `2 ** 64 - 1`, and the
 // exactly-representable 32-bit bounds).
 //
-// 1. Require neither bigint type to emit a bare `true` keyword.
-// 2. Require every number predicate to use an inclusive upper bound.
+// 1. Require number and bigint comparisons to use their exact signed/unsigned limits.
+// 2. Require both bounds to be inclusive, with unknown types unrestricted.
+//
+// @evidence contracts/testing.md#behavioral-verification Generated number and bigint comparison trees contain exactly two inclusive bound checks with the authored lower and upper values and input operand; bigint limits are constructed from exact decimal strings. Unknown types retain the unrestricted true result.
+// @evidence contracts/testing.md#independent-expectations Signed N-bit integers range from minus 2^(N-1) to 2^(N-1)-1 and unsigned integers from zero to 2^N-1. Decimal expectations are written independently of the factory; checking both values and operand positions rejects shifted or swapped limits.
+// @evidence contracts/testing.md#distinguishing-cases Number int32/uint32/int64/uint64, bigint int64/uint64 and unknown controls distinguish signedness, width, exact string construction and unrestricted fallback.
+// @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 with no checker, filesystem fixture or process.
 func TestNumericRangeFactoryEnforces64BitBounds(t *testing.T) {
   input := numericRangeFactory_factory.NewIdentifier("input")
 
@@ -38,6 +43,57 @@ func TestNumericRangeFactoryEnforces64BitBounds(t *testing.T) {
       t.Fatalf("number range %s must compare both bounds inclusively", name)
     }
   }
+
+  for _, tc := range []struct{ name, lower, upper string }{
+    {"int32", "-2147483648", "2147483647"},
+    {"uint32", "0", "4294967295"},
+    {"int64", "-9223372036854775808", "9223372036854775807"},
+    {"uint64", "0", "18446744073709551615"},
+  } {
+    numericRangeFactoryAssertBounds(t, NumericRangeFactory.Number(tc.name, input), tc.lower, tc.upper, false)
+    if tc.name == "int64" || tc.name == "uint64" {
+      numericRangeFactoryAssertBounds(t, NumericRangeFactory.Bigint(tc.name, input), tc.lower, tc.upper, true)
+    }
+  }
+  if NumericRangeFactory.Number("unknown", input).Kind != shimast.KindTrueKeyword || NumericRangeFactory.Bigint("unknown", input).Kind != shimast.KindTrueKeyword {
+    t.Fatal("unknown numeric types must remain unrestricted")
+  }
+}
+
+func numericRangeFactoryAssertBounds(t *testing.T, node *shimast.Node, lower, upper string, bigint bool) {
+  t.Helper()
+  bounds := []*shimast.BinaryExpression{}
+  var walk func(*shimast.Node) bool
+  walk = func(n *shimast.Node) bool {
+    if n.Kind == shimast.KindBinaryExpression {
+      b := n.AsBinaryExpression()
+      if b.OperatorToken.Kind == shimast.KindLessThanEqualsToken {
+        bounds = append(bounds, b)
+      }
+    }
+    n.ForEachChild(walk)
+    return false
+  }
+  walk(node)
+  if len(bounds) != 2 {
+    t.Fatalf("range must have two inclusive bounds, got %d", len(bounds))
+  }
+  decimal := func(n *shimast.Node) string {
+    if bigint {
+      if n.Kind != shimast.KindCallExpression {
+        t.Fatalf("bigint bound must be a decimal-string constructor, got %v", n.Kind)
+      }
+      call := n.AsCallExpression()
+      if call.Expression.Text() != "BigInt" || call.Arguments == nil || len(call.Arguments.Nodes) != 1 || call.Arguments.Nodes[0].Kind != shimast.KindStringLiteral {
+        t.Fatal("bigint bound lost its exact string constructor")
+      }
+      return call.Arguments.Nodes[0].Text()
+    }
+    return n.Text()
+  }
+  if decimal(bounds[0].Left) != lower || bounds[0].Right.Text() != "input" || bounds[1].Left.Text() != "input" || decimal(bounds[1].Right) != upper {
+    t.Fatalf("wrong bound values or operand positions: expected %s <= input <= %s", lower, upper)
+  }
 }
 
 // numericRangeFactoryCountTokens counts binary operators of one kind in a predicate tree.

package/native/core/factories/protobuf_factory_bigint_keeps_each_width_test.go

@@ -0,0 +1,47 @@
+package factories
+
+import (
+  "testing"
+
+  schemametadata "github.com/samchon/typia/packages/typia/native/core/schemas/metadata"
+  nativeprotobuf "github.com/samchon/typia/packages/typia/native/core/schemas/protobuf"
+)
+
+// TestProtobufFactoryBigintKeepsEachWidth verifies that a bigint with two width
+// tags yields one entry per width.
+//
+// The bigint emplacer keyed every row by the default width while naming the
+// entry by the tagged width, so `bigint & Type<"int64"> | bigint &
+// Type<"uint64">` collapsed to the last row. The number emplacer keys by the
+// resolved name, and the bigint emplacer must do the same.
+//
+//  1. Emplace two rows tagged int64 and uint64 under a default of int64.
+//  2. Assert both widths are present and named by their own tag.
+//  3. Emplace untagged rows and assert the default width is the only entry.
+//
+// @evidence contracts/testing.md#behavioral-verification The emplacer is called with tagged rows and the resulting map is read for both keys and names.
+// @evidence contracts/testing.md#independent-expectations The expected keys are the two protobuf widths named in the tags and not values read back from the implementation.
+// @evidence contracts/testing.md#distinguishing-cases Two widths against none are the cases, and the collapse of the first is what the old key hid.
+// @evidence contracts/testing.md#execution-ownership The canonical native Go command (pnpm test:go:native) runs this same-package Test function in process on an in-memory map with no checker, filesystem fixture or process.
+func TestProtobufFactoryBigintKeepsEachWidth(t *testing.T) {
+  row := func(width string) []schemametadata.IMetadataTypeTag {
+    return []schemametadata.IMetadataTypeTag{{Kind: "type", Value: width}}
+  }
+  output := map[string]nativeprotobuf.IProtobufPropertyType{}
+  protobufFactory_emplaceBigint(output, [][]schemametadata.IMetadataTypeTag{row("int64"), row("uint64")}, "int64")
+  if len(output) != 2 {
+    t.Fatalf("expected one entry per width, got %d", len(output))
+  }
+  for _, width := range []string{"int64", "uint64"} {
+    entry, ok := output[width].(*nativeprotobuf.IProtobufPropertyType_IBigint)
+    if ok == false || entry.Name != width {
+      t.Fatalf("entry %s missing or misnamed: %#v", width, output[width])
+    }
+  }
+
+  plain := map[string]nativeprotobuf.IProtobufPropertyType{}
+  protobufFactory_emplaceBigint(plain, nil, "int64")
+  if len(plain) != 1 || plain["int64"] == nil {
+    t.Fatalf("untagged bigint should keep the default width only, got %v", plain)
+  }
+}

package/native/core/factories/protobuf_factory_rejects_invalid_field_names_test.go

@@ -19,6 +19,11 @@ import (
 //  2. Validate keys with dashes, leading digits, spaces, and empty names and
 //     assert each is rejected.
 //  3. Assert a dynamic string-typed key passes the name rule untouched.
+//
+// @evidence contracts/testing.md#behavioral-verification The protobuf object validator runs on identifier and non-identifier sole-literal keys and on a dynamic string key; invalid names must be rejected and dynamic keys exempted.
+// @evidence contracts/testing.md#independent-expectations The proto3 identifier grammar defines which names are legal; keys are authored.
+// @evidence contracts/testing.md#distinguishing-cases Accepted identifiers, rejected punctuated keys and the exempt dynamic key give three decision classes.
+// @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 validator on constructed metadata with no checker, filesystem fixture or process.
 func TestProtobufFactoryRejectsInvalidFieldNames(t *testing.T) {
   literal := func(value string) *schemametadata.MetadataSchema {
     return schemametadata.MetadataSchema_create(schemametadata.MetadataSchema{

package/native/core/factories/protobuf_recovery_ownership_test.go

@@ -16,6 +16,11 @@ import (
 //  1. Verify unsupported metadata remains an ordinary diagnostic.
 //  2. Build a static object with an impossible empty semantic schema.
 //  3. Require the panic to escape the post-validation emplacement pass.
+//
+// @evidence contracts/testing.md#behavioral-verification The protobuf emplacer runs on unsupported metadata, which must produce an ordinary diagnostic, and on a static object with an impossible schema, which must panic and not be swallowed.
+// @evidence contracts/testing.md#independent-expectations Diagnostics for unsupported input and visibility of invariant failures are the stated contract; the expected error and panic are authored.
+// @evidence contracts/testing.md#distinguishing-cases Diagnostic versus panic separates expected failure from an invariant violation.
+// @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 emplacer on constructed metadata and recovers a panic in the test itself, with no checker, filesystem fixture or process.
 func TestProtobufEmplacerRecoveryOwnership(t *testing.T) {
   unsupported := schemametadata.MetadataSchema_initialize()
   unsupported.Any = true

package/native/core/programmers/AssertProgrammer.go

@@ -15,11 +15,28 @@ type assertProgrammerNamespace struct{}
 
 var AssertProgrammer = assertProgrammerNamespace{}
 
+// AssertProgrammer_IConfig selects the generator's variants: Equals is the
+// strict form that also rejects properties the type does not declare and Guard
+// is the assertion-signature form, `asserts input is T`.
+//
+// @evidence contracts/common.md#principled-implementation Each variant of the generator is one boolean or option on a record, so the transformers pick a form by naming the field and no second code path is copied.
+// @evidence contracts/common.md#clear-and-simple-design A record of 2 fields.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A data record.
+// @evidence contracts/common.md#meaningful-documentation The doc states what each field selects.
 type AssertProgrammer_IConfig struct {
   Equals bool
   Guard  bool
 }
 
+// AssertProgrammer_IProps is the input of Write for the assert generator:
+// Context (the transform context), Modulo (the call's callee expression), Type
+// (the type to generate for), Name (an optional type name), Init (the optional
+// initializer of the error factory parameter) and Config (the configuration).
+//
+// @evidence contracts/common.md#principled-implementation Write needs the transform context, the call's callee expression, the type to generate for, an optional type name, the optional initializer of the error factory parameter and the configuration, and the record carries them in one argument.
+// @evidence contracts/common.md#clear-and-simple-design A flat argument record of 6 fields.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A data record.
+// @evidence contracts/common.md#meaningful-documentation The doc names each field.
 type AssertProgrammer_IProps struct {
   Context nativecontext.ITypiaContext
   Modulo  *shimast.Node
@@ -29,6 +46,16 @@ type AssertProgrammer_IProps struct {
   Config  AssertProgrammer_IConfig
 }
 
+// AssertProgrammer_DecomposeProps is the input of Decompose for the assert
+// generator: Config (the configuration), Context (the transform context),
+// Functor (the collector of the helper functions that the generator emits), Type
+// (the type to generate for), Name (an optional type name) and Init (the
+// optional initializer of the error factory parameter).
+//
+// @evidence contracts/common.md#principled-implementation Decompose needs the configuration, the transform context, the collector of the helper functions that the generator emits, the type to generate for, an optional type name and the optional initializer of the error factory parameter, and the record carries them in one argument.
+// @evidence contracts/common.md#clear-and-simple-design A flat argument record of 6 fields.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A data record.
+// @evidence contracts/common.md#meaningful-documentation The doc names each field.
 type AssertProgrammer_DecomposeProps struct {
   Config  AssertProgrammer_IConfig
   Context nativecontext.ITypiaContext

package/native/core/programmers/IsProgrammer.go

@@ -16,6 +16,15 @@ type isProgrammerNamespace struct{}
 
 var IsProgrammer = isProgrammerNamespace{}
 
+// IsProgrammer_CONFIG_IOptions selects the generator's variants: Numeric is
+// whether number leaves are guarded against NaN, Finite is whether number leaves
+// are guarded against NaN and the infinities, Undefined is whether undefined
+// property values are accepted and Object is the object check.
+//
+// @evidence contracts/common.md#principled-implementation Each variant of the generator is one boolean or option on a record, so the transformers pick a form by naming the field and no second code path is copied.
+// @evidence contracts/common.md#clear-and-simple-design A record of 4 fields.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A data record.
+// @evidence contracts/common.md#meaningful-documentation The doc states what each field selects.
 type IsProgrammer_CONFIG_IOptions struct {
   Numeric   *bool
   Finite    *bool
@@ -23,26 +32,58 @@ type IsProgrammer_CONFIG_IOptions struct {
   Object    func(props IsProgrammer_CONFIG_IOptions_ObjectProps) *shimast.Node
 }
 
+// IsProgrammer_CONFIG_IOptions_ObjectProps is the input of the object check
+// hook: the checked expression, the property checks and the object type.
+//
+// @evidence contracts/common.md#principled-implementation A custom object check receives the already composed property checks together with the input and the object type, so it need not recompute them.
+// @evidence contracts/common.md#clear-and-simple-design A three-field record.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A data record.
+// @evidence contracts/common.md#meaningful-documentation The doc names each field.
 type IsProgrammer_CONFIG_IOptions_ObjectProps struct {
   Input   *shimast.Expression
   Entries []nativehelpers.IExpressionEntry
   Object  *nativemetadata.MetadataObjectType
 }
 
+// IsProgrammer_IConfig selects the generator's variants: Equals is the strict
+// form that also rejects properties the type does not declare and Depth is the
+// remaining nesting depth, where nil means unlimited and a spent budget accepts
+// composites as a bare object.
+//
+// @evidence contracts/common.md#principled-implementation Each variant of the generator is one boolean or option on a record, so the transformers pick a form by naming the field and no second code path is copied.
+// @evidence contracts/common.md#clear-and-simple-design A record of 2 fields.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A data record.
+// @evidence contracts/common.md#meaningful-documentation The doc states what each field selects.
 type IsProgrammer_IConfig struct {
   Equals bool
   Depth  *int
 }
 
+// IsProgrammer_IProps is the input of Write for the is generator: Context (the
+// transform context), Modulo (the call's callee expression), Type (the type to
+// generate for), Name (an optional type name) and Config (the configuration).
+//
+// @evidence contracts/common.md#principled-implementation Write needs the transform context, the call's callee expression, the type to generate for, an optional type name and the configuration, and the record carries them in one argument.
+// @evidence contracts/common.md#clear-and-simple-design A flat argument record of 5 fields.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A data record.
+// @evidence contracts/common.md#meaningful-documentation The doc names each field.
 type IsProgrammer_IProps struct {
   Context nativecontext.ITypiaContext
   Modulo  *shimast.Node
   Type    *nativechecker.Type
   Name    *string
-  Init    *shimast.Node
   Config  IsProgrammer_IConfig
 }
 
+// IsProgrammer_DecomposeProps is the input of Decompose for the is generator:
+// Context (the transform context), Functor (the collector of the helper
+// functions that the generator emits), Config (the configuration), Type (the
+// type to generate for) and Name (an optional type name).
+//
+// @evidence contracts/common.md#principled-implementation Decompose needs the transform context, the collector of the helper functions that the generator emits, the configuration, the type to generate for and an optional type name, and the record carries them in one argument.
+// @evidence contracts/common.md#clear-and-simple-design A flat argument record of 5 fields.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A data record.
+// @evidence contracts/common.md#meaningful-documentation The doc names each field.
 type IsProgrammer_DecomposeProps struct {
   Context nativecontext.ITypiaContext
   Functor *nativehelpers.FunctionProgrammer
@@ -51,6 +92,15 @@ type IsProgrammer_DecomposeProps struct {
   Name    *string
 }
 
+// IsProgrammer_WriteFunctionStatementsProps is the input of
+// Write_function_statements: the transform context, the Functor that collects
+// helpers and the Collection whose objects get is-helpers. Prefix selects the
+// helper namespace.
+//
+// @evidence contracts/common.md#principled-implementation The helpers are written from the caller's own collection under a caller-chosen prefix, so two collections never collide on indexes.
+// @evidence contracts/common.md#clear-and-simple-design A four-field record with a documented Prefix.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A data record.
+// @evidence contracts/common.md#meaningful-documentation The doc names each field and the field comment explains the prefix.
 type IsProgrammer_WriteFunctionStatementsProps struct {
   Context    nativecontext.ITypiaContext
   Functor    *nativehelpers.FunctionProgrammer
@@ -63,6 +113,14 @@ type IsProgrammer_WriteFunctionStatementsProps struct {
   Prefix string
 }
 
+// IsProgrammer_DecodeProps is the input of Decode: the transform context, the
+// Functor, the Metadata and Input to check, the Explore state and the helper
+// Prefix.
+//
+// @evidence contracts/common.md#principled-implementation A union ladder is decoded against the same metadata and input it was written for, with the caller's helper namespace.
+// @evidence contracts/common.md#clear-and-simple-design A six-field record with a documented Prefix.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A data record.
+// @evidence contracts/common.md#meaningful-documentation The doc names each field and the field comment explains the prefix.
 type IsProgrammer_DecodeProps struct {
   Context  nativecontext.ITypiaContext
   Functor  *nativehelpers.FunctionProgrammer
@@ -76,6 +134,14 @@ type IsProgrammer_DecodeProps struct {
   Prefix string
 }
 
+// IsProgrammer_DecodeObjectProps is the input of Decode_object: the transform
+// context, the Functor, the Object type and Input to check, the Explore state
+// and the helper Prefix.
+//
+// @evidence contracts/common.md#principled-implementation Nested object discrimination uses the caller's helper namespace as the surrounding union ladder does.
+// @evidence contracts/common.md#clear-and-simple-design A six-field record with a documented Prefix.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A data record.
+// @evidence contracts/common.md#meaningful-documentation The doc names each field and the field comment explains the prefix.
 type IsProgrammer_DecodeObjectProps struct {
   Context nativecontext.ITypiaContext
   Functor *nativehelpers.FunctionProgrammer

package/native/core/programmers/RandomProgrammer.go

@@ -23,6 +23,15 @@ type randomProgrammerNamespace struct{}
 
 var RandomProgrammer = randomProgrammerNamespace{}
 
+// RandomProgrammer_IProps is the input of Write for the random generator:
+// Context (the transform context), Modulo (the call's callee expression), Type
+// (the type to generate for), Name (an optional type name) and Init (the
+// optional initializer of the generator parameter).
+//
+// @evidence contracts/common.md#principled-implementation Write needs the transform context, the call's callee expression, the type to generate for, an optional type name and the optional initializer of the generator parameter, and the record carries them in one argument.
+// @evidence contracts/common.md#clear-and-simple-design A flat argument record of 5 fields.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A data record.
+// @evidence contracts/common.md#meaningful-documentation The doc names each field.
 type RandomProgrammer_IProps struct {
   Context nativecontext.ITypiaContext
   Modulo  *shimast.Node
@@ -31,6 +40,16 @@ type RandomProgrammer_IProps struct {
   Init    *shimast.Node
 }
 
+// RandomProgrammer_IDecomposeProps is the input of Decompose for the random
+// generator: Context (the transform context), Functor (the collector of the
+// helper functions that the generator emits), Type (the type to generate for),
+// Name (an optional type name) and Init (the optional initializer of the
+// generator parameter).
+//
+// @evidence contracts/common.md#principled-implementation Decompose needs the transform context, the collector of the helper functions that the generator emits, the type to generate for, an optional type name and the optional initializer of the generator parameter, and the record carries them in one argument.
+// @evidence contracts/common.md#clear-and-simple-design A flat argument record of 5 fields.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A data record.
+// @evidence contracts/common.md#meaningful-documentation The doc names each field.
 type RandomProgrammer_IDecomposeProps struct {
   Context nativecontext.ITypiaContext
   Functor *nativehelpers.FunctionProgrammer
@@ -146,6 +165,13 @@ func (randomProgrammerNamespace) Decompose(props RandomProgrammer_IDecomposeProp
   if init == nil {
     init = f.NewToken(shimast.KindQuestionToken)
   }
+  // A caller's initializer can itself be named generator. A generated binding
+  // prevents its default expression from resolving to this parameter's TDZ.
+  generatorEmit := props.Context.Emit
+  if generatorEmit == nil {
+    generatorEmit = shimprinter.NewEmitContext()
+  }
+  generator := generatorEmit.Factory.NewUniqueName("generator")
   resolvedType := randomProgrammer_import_type(props.Context, nativecontext.ImportProgrammer_TypeProps{
     File: "typia",
     Name: "Resolved",
@@ -168,7 +194,7 @@ func (randomProgrammerNamespace) Decompose(props RandomProgrammer_IDecomposeProp
       nil,
       nil,
       f.NewNodeList([]*shimast.Node{
-        nativefactories.IdentifierFactory.Parameter("generator", randomGeneratorType, init, props.Context.Emit),
+        nativefactories.IdentifierFactory.Parameter(generator.Clone(generatorEmit.Factory), randomGeneratorType, init, props.Context.Emit),
       }),
       resolvedType,
       nil,
@@ -179,7 +205,7 @@ func (randomProgrammerNamespace) Decompose(props RandomProgrammer_IDecomposeProp
           f.NewIdentifier("_generator"),
           nil,
           f.NewToken(shimast.KindEqualsToken),
-          f.NewIdentifier("generator"),
+          generator.Clone(generatorEmit.Factory),
         )),
         f.NewReturnStatement(randomProgrammer_decode(randomProgrammer_decodeProps{
           Context: props.Context,
@@ -569,7 +595,8 @@ func randomProgrammer_decode(props randomProgrammer_decodeProps) *shimast.Node {
   return randomProgrammer_decode_pick(props, expressions)
 }
 
-// randomProgrammer_decode_pick draws one of the candidate expressions uniformly.
+// randomProgrammer_decode_pick selects a lazy candidate through the optional pick hook or uniform built-in fallback.
+// The custom hook receives its generator object as the receiver; only the selected candidate executes.
 func randomProgrammer_decode_pick(props randomProgrammer_decodeProps, expressions []*shimast.Node) *shimast.Node {
   f := nativecontext.EmitFactoryOf(randomProgrammer_factory, props.Context.Emit)
   pickers := make([]*shimast.Node, 0, len(expressions))
@@ -587,10 +614,11 @@ func randomProgrammer_decode_pick(props randomProgrammer_decodeProps, expression
   }
   return f.NewCallExpression(
     f.NewCallExpression(
-      randomProgrammer_internal(props.Context, "randomPick"),
+      nativefactories.IdentifierFactory.Access(props.Context.Emit, randomProgrammer_coalesce(props.Context, "pick", "randomPick"), "call"),
       nil,
       nil,
       f.NewNodeList([]*shimast.Node{
+        f.NewIdentifier("_generator"),
         f.NewArrayLiteralExpression(f.NewNodeList(pickers), true),
       }),
       shimast.NodeFlagsNone,
@@ -1507,24 +1535,13 @@ func randomProgrammer_is_typed_array(name string) bool {
 // randomProgrammer_typed_array_range reports the type tag and range a TypedArray's
 // elements are generated from.
 //
-// These bounds are a generation hint, not a validation gate, and they are the one
-// copy of the 64-bit bound that is deliberately inexact. They become `minimum` and
-// `maximum` comment tags on a number-typed JSON schema, and `number` cannot
-// represent 2**63 - 1 or 2**64 - 1 -- both arrive rounded up to the next power of
-// two. That costs nothing here, and not because the generator is careless: it
-// draws Math.floor(Math.random() * (maximum - minimum + 1)) + minimum, and that
-// span is 2**64 either way, where consecutive doubles are 2048 apart. So the
-// largest draw is 2**63 - 2048 for int64 and 2**64 - 2048 for uint64, both
-// inside the width. (Nearer the int64 maximum itself the spacing is 1024, which
-// is why the largest double below 2**63 is 2**63 - 1024; the span is what bounds
-// the draw.) The TypedArray constructor then wraps whatever it is handed anyway.
-//
-// Only the `bigint` path is exact, in _isTypeInt64Bigint and _isTypeUint64Bigint,
-// which take the true inclusive bound through a BigInt string a `number` literal
-// here could not spell. _isTypeInt64 and _isTypeUint64 on the `number` path
-// carry the same rounding this table does: their maxima are written 2**63 - 1
-// and 2**64 - 1, which are the powers of two as doubles, so each accepts one
-// value above its width -- the only float form that maximum has.
+// These strings become generation tags, not validation gates. BigInt typed
+// arrays select a bigint atomic schema, while the minimum/maximum tags pass
+// through the existing number-based schema representation. Endpoints beyond
+// JavaScript's exact integer range therefore retain that representation's
+// rounding limit. The default generator or a supplied generator consumes the
+// resulting schema, and the TypedArray constructor performs its normal element
+// conversion; this table does not promise an exact draw distribution.
 func randomProgrammer_typed_array_range(name string) (string, string, string) {
   switch name {
   case "Uint8Array", "Uint8ClampedArray":

package/native/core/programmers/ValidateProgrammer.go

@@ -15,20 +15,47 @@ type validateProgrammerNamespace struct{}
 
 var ValidateProgrammer = validateProgrammerNamespace{}
 
+// ValidateProgrammer_IConfig selects the generator's variants: Equals is the
+// strict form that also rejects properties the type does not declare and
+// StandardSchema is whether the validator is wrapped as a Standard Schema
+// object.
+//
+// @evidence contracts/common.md#principled-implementation Each variant of the generator is one boolean or option on a record, so the transformers pick a form by naming the field and no second code path is copied.
+// @evidence contracts/common.md#clear-and-simple-design A record of 2 fields.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A data record.
+// @evidence contracts/common.md#meaningful-documentation The doc states what each field selects.
 type ValidateProgrammer_IConfig struct {
   Equals         bool
   StandardSchema bool
 }
 
+// ValidateProgrammer_IProps is the input of Write for the validate generator:
+// Context (the transform context), Modulo (the call's callee expression), Type
+// (the type to generate for), Name (an optional type name) and Config (the
+// configuration).
+//
+// @evidence contracts/common.md#principled-implementation Write needs the transform context, the call's callee expression, the type to generate for, an optional type name and the configuration, and the record carries them in one argument.
+// @evidence contracts/common.md#clear-and-simple-design A flat argument record of 5 fields.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A data record.
+// @evidence contracts/common.md#meaningful-documentation The doc names each field.
 type ValidateProgrammer_IProps struct {
   Context nativecontext.ITypiaContext
   Modulo  *shimast.Node
   Type    *nativechecker.Type
   Name    *string
-  Init    *shimast.Node
   Config  ValidateProgrammer_IConfig
 }
 
+// ValidateProgrammer_DecomposeProps is the input of Decompose for the validate
+// generator: Context (the transform context), Modulo (the call's callee
+// expression), Functor (the collector of the helper functions that the generator
+// emits), Config (the configuration), Type (the type to generate for) and Name
+// (an optional type name).
+//
+// @evidence contracts/common.md#principled-implementation Decompose needs the transform context, the call's callee expression, the collector of the helper functions that the generator emits, the configuration, the type to generate for and an optional type name, and the record carries them in one argument.
+// @evidence contracts/common.md#clear-and-simple-design A flat argument record of 6 fields.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A data record.
+// @evidence contracts/common.md#meaningful-documentation The doc names each field.
 type ValidateProgrammer_DecomposeProps struct {
   Context nativecontext.ITypiaContext
   Modulo  *shimast.Node