typia 15.0.0 → 15.1.0

package/native/core/programmers/iterate/json_schema_array.go

@@ -2,6 +2,13 @@ package iterate
 
 import nativemetadata "github.com/samchon/typia/packages/typia/native/core/schemas/metadata"
 
+// Json_schema_array_export_props is the argument record of
+// Json_schema_array_export, which converts an array type to JSON schemas.
+//
+// @evidence contracts/common.md#principled-implementation It is the argument record of Json_schema_array_export, which converts an array type to JSON schemas; its 2 fields (Components, Array) are named so that a producer and a consumer cannot transpose them.
+// @evidence contracts/common.md#clear-and-simple-design A 2-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 Json_schema_array_export_props struct {
   Components *OpenApi_IComponents
   Array      *nativemetadata.MetadataArray
@@ -55,6 +62,15 @@ func json_schema_array(props struct {
   return factory()
 }
 
+// Json_schema_array_export converts an array type to its JSON schemas: an
+// `array` schema whose items come from the element metadata, or a reference to
+// the component of a recursive array type, which is registered the first time it
+// is met.
+//
+// @evidence contracts/common.md#principled-implementation It converts an array type to its JSON schemas: an `array` schema whose items come from the element metadata, or a reference to the component of a recursive array type, which is registered the first time it is met.
+// @evidence contracts/common.md#clear-and-simple-design One exported function; the pieces that repeat live in private helpers of the same file.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The only state it changes is the components record it is given.
+// @evidence contracts/common.md#meaningful-documentation The doc states what it builds.
 func Json_schema_array_export(props Json_schema_array_export_props) []JsonSchema {
   return json_schema_array(struct {
     components *OpenApi_IComponents

package/native/core/programmers/iterate/json_schema_bigint.go

@@ -12,6 +12,13 @@ func json_schema_bigint(atomic *nativemetadata.MetadataAtomic) []JsonSchema {
   })
 }
 
+// Json_schema_bigint_export converts a bigint atomic to its JSON schemas: an
+// `integer` schema, one per type-tag plugin row.
+//
+// @evidence contracts/common.md#principled-implementation It converts a bigint atomic to its JSON schemas: an `integer` schema, one per type-tag plugin row.
+// @evidence contracts/common.md#clear-and-simple-design A one-line exported wrapper over the package-private function.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The wrapper has no logic of its own.
+// @evidence contracts/common.md#meaningful-documentation The doc states what it builds.
 func Json_schema_bigint_export(atomic *nativemetadata.MetadataAtomic) []JsonSchema {
   return json_schema_bigint(atomic)
 }

package/native/core/programmers/iterate/json_schema_boolean.go

@@ -12,6 +12,13 @@ func json_schema_boolean(atomic *nativemetadata.MetadataAtomic) []JsonSchema {
   })
 }
 
+// Json_schema_boolean_export converts a boolean atomic to its JSON schemas: a
+// `boolean` schema, one per type-tag plugin row.
+//
+// @evidence contracts/common.md#principled-implementation It converts a boolean atomic to its JSON schemas: a `boolean` schema, one per type-tag plugin row.
+// @evidence contracts/common.md#clear-and-simple-design A one-line exported wrapper over the package-private function.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The wrapper has no logic of its own.
+// @evidence contracts/common.md#meaningful-documentation The doc states what it builds.
 func Json_schema_boolean_export(atomic *nativemetadata.MetadataAtomic) []JsonSchema {
   return json_schema_boolean(atomic)
 }

package/native/core/programmers/iterate/json_schema_discriminator_declaration_syntax_test.go

@@ -16,11 +16,16 @@ import (
 // referenced object type carrying a common literal tag, never on which bucket
 // the metadata factory happened to file it under.
 //
-// 1. Build the interface, alias, and mixed forms of one tagged union.
-// 2. Assert each emits the identical propertyName and mapping.
-// 3. Assert the negative shapes -- no common tag, a non-object member, a
-//    literal (inline) member, and an alias that does not name a lone object --
-//    still emit no discriminator, so the resolution cannot over-emit.
+//  1. Build the interface, alias, and mixed forms of one tagged union.
+//  2. Assert each emits the identical propertyName and mapping.
+//  3. Assert the negative shapes -- no common tag, a non-object member, a
+//     literal (inline) member, and an alias that does not name a lone object --
+//     still emit no discriminator, so the resolution cannot over-emit.
+//
+// @evidence contracts/testing.md#behavioral-verification Discriminator emission is run on constructed metadata modeling interface and type-alias members; each case must emit the discriminator with the same property name and a mapping object of the expected size.
+// @evidence contracts/testing.md#independent-expectations Both declaration forms export the same $ref, so eligibility cannot depend on syntax; the labeled cases and the expected property name and mapping size are authored.
+// @evidence contracts/testing.md#distinguishing-cases Interface and alias forms are positives; shapes that must not produce a discriminator are covered by the negative rows of the same table.
+// @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 schema writer on constructed metadata with no checker, filesystem fixture or process.
 func TestJsonSchemaDiscriminatorDeclarationSyntax(t *testing.T) {
   circle := func() *nativemetadata.MetadataObject {
     return discriminatorObject("Circle", "type", "circle")

package/native/core/programmers/iterate/json_schema_jsDocTags.go

@@ -1,10 +1,10 @@
 package iterate
 
 import (
-  "strconv"
   "strings"
 
   nativemetadata "github.com/samchon/typia/packages/typia/native/core/schemas/metadata"
+  nativeutils "github.com/samchon/typia/packages/typia/native/core/utils"
 )
 
 func json_schema_jsDocTags(schema JsonSchema, jsDocTags []nativemetadata.IJsDocTagInfo) JsonSchema {
@@ -31,6 +31,13 @@ func json_schema_jsDocTags_value(tag nativemetadata.IJsDocTagInfo) (string, bool
   return "", false
 }
 
+// json_schema_jsDocTags_cast reads an `@x-*` tag's text as a JSON value.
+//
+// Numbers use JavaScript's `Number()` grammar, the grammar of the v12 cast this
+// ports (samchon/typia#2442), so `0x10` is 16 while Go-only spellings such as
+// `0x1p4`, `1_000`, and `inf` stay text. Only finite numbers become numbers: the
+// schema is JSON, which has no NaN or infinity, so `NaN`, `Infinity`, and an
+// overflowing `1e400` keep their text instead of degrading to `null`.
 func json_schema_jsDocTags_cast(value string) any {
   if value == "true" {
     return true
@@ -38,8 +45,8 @@ func json_schema_jsDocTags_cast(value string) any {
   if value == "false" {
     return false
   }
-  if num, err := strconv.ParseFloat(value, 64); err == nil {
-    return num
+  if reading := nativeutils.NumberUtil.Read(value); reading.Numeric && reading.Finite {
+    return reading.Value
   }
   if value == "null" {
     return nil

package/native/core/programmers/iterate/json_schema_jsdoc_tags_cast_reads_javascript_numbers_test.go

@@ -0,0 +1,69 @@
+package iterate
+
+import (
+  "encoding/json"
+  "math"
+  "reflect"
+  "testing"
+)
+
+// TestJsonSchemaJsDocTagsCastReadsJavaScriptNumbers verifies the `@x-*`
+// extension cast.
+//
+// The Go port swapped the v12 cast's JavaScript `Number()` grammar for Go's
+// float syntax (samchon/typia#2442). `NaN` and every `Inf` spelling then became
+// floats that `encoding/json` refuses and JavaScript prints as `null`, while
+// `0x10` stopped being a number and `0x1p4` / `1_000` started being one. The
+// expectations restore v12's numbers where they are finite and keep the text
+// where JSON has no number: a non-finite spelling stays a string instead of
+// degrading to `null`, and empty text stays `""` instead of v12's `0`.
+//
+//  1. Cast every row of the issue's table.
+//  2. Assert no result is NaN or an infinity, and every result marshals.
+//
+// @evidence contracts/testing.md#behavioral-verification The @x- extension cast is called on JavaScript number spellings (hex, NaN, infinities, exponents) and ordinary text; each result must equal the authored value and numbers must marshal as JSON.
+// @evidence contracts/testing.md#independent-expectations The JavaScript Number() grammar defines which spellings are numbers; expected values are authored literals and JSON marshaling is the independent check.
+// @evidence contracts/testing.md#distinguishing-cases Accepted JavaScript spellings and Go-only spellings give positives and negatives.
+// @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 cast and encoding/json in memory with no checker, filesystem fixture or process.
+func TestJsonSchemaJsDocTagsCastReadsJavaScriptNumbers(t *testing.T) {
+  for _, item := range []struct {
+    text     string
+    expected any
+  }{
+    {"NaN", "NaN"},
+    {"nan", "nan"},
+    {"Infinity", "Infinity"},
+    {"-Infinity", "-Infinity"},
+    {"infinity", "infinity"},
+    {"inf", "inf"},
+    {"Inf", "Inf"},
+    {"1e400", "1e400"},
+    {"0x10", float64(16)},
+    {"0b101", float64(5)},
+    {"0o7", float64(7)},
+    {"0x1p4", "0x1p4"},
+    {"1_000", "1_000"},
+    {"", ""},
+    {"-0", float64(0)},
+    {"+5", float64(5)},
+    {".5", 0.5},
+    {"1e3", float64(1000)},
+    {"true", true},
+    {"false", false},
+    {"null", nil},
+    {"text", "text"},
+  } {
+    actual := json_schema_jsDocTags_cast(item.text)
+    if reflect.DeepEqual(actual, item.expected) == false {
+      t.Fatalf("cast(%q) = %#v, expected %#v", item.text, actual, item.expected)
+    }
+    if number, ok := actual.(float64); ok {
+      if math.IsNaN(number) || math.IsInf(number, 0) || math.Signbit(number) && number == 0 {
+        t.Fatalf("cast(%q) = %v violates the finite, normalized-zero contract", item.text, number)
+      }
+    }
+    if _, err := json.Marshal(actual); err != nil {
+      t.Fatalf("cast(%q) does not marshal: %v", item.text, err)
+    }
+  }
+}

package/native/core/programmers/iterate/json_schema_native.go

@@ -5,6 +5,13 @@ import (
   nativemetadata "github.com/samchon/typia/packages/typia/native/core/schemas/metadata"
 )
 
+// OpenApi_IComponents is the `components` of a JSON schema document being built:
+// the named schemas and the order in which they were first registered.
+//
+// @evidence contracts/common.md#principled-implementation It is the `components` of a JSON schema document being built: the named schemas and the order in which they were first registered; its 2 fields (Schemas, Order) are named so that a producer and a consumer cannot transpose them.
+// @evidence contracts/common.md#clear-and-simple-design The schema map owns lookup while Order owns discovery sequence; registration and literal rendering are methods on that shared store.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Registration records new keys before insertion and rendering follows the recorded sequence rather than relying on Go map iteration.
+// @evidence contracts/common.md#meaningful-documentation The doc states what the record is.
 type OpenApi_IComponents struct {
   Schemas map[string]JsonSchema
   // Order records the insertion sequence of Schemas keys so the emitted
@@ -18,6 +25,11 @@ type OpenApi_IComponents struct {
 // ToLiteral renders the components as an order-preserving object literal input
 // for LiteralFactory. The `schemas` member keeps the insertion order recorded
 // in Order so the emitted `components.schemas` matches the legacy TS output.
+//
+// @evidence contracts/common.md#principled-implementation A Go map has no order, so the schemas are written as an ordered object in the discovery order that Order recorded, which keeps the emitted `components.schemas` as the TypeScript implementation emitted it.
+// @evidence contracts/common.md#clear-and-simple-design One method over Order and Schemas.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Order is recorded data and nothing is sorted; an ordered key without a schema is skipped.
+// @evidence contracts/common.md#meaningful-documentation The doc states the order preservation.
 func (components *OpenApi_IComponents) ToLiteral() nativefactories.LiteralFactory_OrderedObject {
   schemas := make(map[string]any, len(components.Schemas))
   keys := make([]string, 0, len(components.Order))
@@ -52,6 +64,13 @@ func (components *OpenApi_IComponents) emplaceSchemaKey(key string) {
   components.Order = append(components.Order, key)
 }
 
+// Json_schema_native_export_props is the argument record of
+// Json_schema_native_export, which converts a built-in class to JSON schemas.
+//
+// @evidence contracts/common.md#principled-implementation It is the argument record of Json_schema_native_export, which converts a built-in class to JSON schemas; its 2 fields (Components, Native) are named so that a producer and a consumer cannot transpose them.
+// @evidence contracts/common.md#clear-and-simple-design A 2-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 Json_schema_native_export_props struct {
   Components *OpenApi_IComponents
   Native     *nativemetadata.MetadataNative
@@ -95,6 +114,14 @@ func json_schema_native(props struct {
   })
 }
 
+// Json_schema_native_export converts a built-in class to its JSON schemas: a
+// binary string for Blob and File, and otherwise a reference to an empty object
+// component that is registered the first time it is met.
+//
+// @evidence contracts/common.md#principled-implementation It converts a built-in class to its JSON schemas: a binary string for Blob and File, and otherwise a reference to an empty object component that is registered the first time it is met.
+// @evidence contracts/common.md#clear-and-simple-design One exported function; the pieces that repeat live in private helpers of the same file.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The only state it changes is the components record it is given.
+// @evidence contracts/common.md#meaningful-documentation The doc states what it builds.
 func Json_schema_native_export(props Json_schema_native_export_props) []JsonSchema {
   return json_schema_native(struct {
     components *OpenApi_IComponents

package/native/core/programmers/iterate/json_schema_number.go

@@ -12,6 +12,13 @@ func json_schema_number(atomic *nativemetadata.MetadataAtomic) []JsonSchema {
   })
 }
 
+// Json_schema_number_export converts a number atomic to its JSON schemas: a
+// `number` schema, one per type-tag plugin row.
+//
+// @evidence contracts/common.md#principled-implementation It converts a number atomic to its JSON schemas: a `number` schema, one per type-tag plugin row.
+// @evidence contracts/common.md#clear-and-simple-design A one-line exported wrapper over the package-private function.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The wrapper has no logic of its own.
+// @evidence contracts/common.md#meaningful-documentation The doc states what it builds.
 func Json_schema_number_export(atomic *nativemetadata.MetadataAtomic) []JsonSchema {
   return json_schema_number(atomic)
 }

package/native/core/programmers/iterate/json_schema_pattern_property_order_test.go

@@ -15,6 +15,11 @@ import (
 //
 //  1. Insert two patterns, then replace the first pattern with new metadata and schema values.
 //  2. Assert the ordered keys remain unique and the map retains the replacement pair.
+//
+// @evidence contracts/testing.md#behavioral-verification Pattern properties are recorded with a repeated pattern; the key order must keep the first position and the replacement pair must be retained.
+// @evidence contracts/testing.md#independent-expectations Replacing an existing key without moving it is JavaScript object assignment semantics; the order is authored.
+// @evidence contracts/testing.md#distinguishing-cases One repeated pattern; distinct patterns are covered by ordering in the same fixture.
+// @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 order recorder in memory with no checker, filesystem fixture or process.
 func TestJsonSchemaPatternPropertyOrderPreservesFirstPosition(t *testing.T) {
   first := &nativemetadata.MetadataSchema{}
   replacement := &nativemetadata.MetadataSchema{}

package/native/core/programmers/iterate/json_schema_plugin.go

@@ -2,6 +2,13 @@ package iterate
 
 import nativemetadata "github.com/samchon/typia/packages/typia/native/core/schemas/metadata"
 
+// JsonSchema is one JSON schema, an untyped keyword map. The keywords are the
+// ones of the OpenAPI schema dialect that the schema builders emit.
+//
+// @evidence contracts/common.md#principled-implementation It is one JSON schema, an untyped keyword map. The keywords are the ones of the OpenAPI schema dialect that the schema builders emit.
+// @evidence contracts/common.md#clear-and-simple-design A single type declaration.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A declaration only.
+// @evidence contracts/common.md#meaningful-documentation The doc states what the type is.
 type JsonSchema map[string]any
 
 func json_schema_plugin(props struct {

package/native/core/programmers/iterate/json_schema_station.go

@@ -12,6 +12,15 @@ type json_schema_station_props struct {
   metadata   *nativemetadata.MetadataSchema
 }
 
+// Json_schema_station_props is the argument record of Json_schema_station, which
+// converts a metadata schema to a JSON schema. BlockNever makes the conversion
+// return nil instead of a schema with no type restriction when metadata yields no member,
+// and Attribute holds the keywords that are merged into the result.
+//
+// @evidence contracts/common.md#principled-implementation It is the argument record of Json_schema_station, which converts a metadata schema to a JSON schema; its 4 fields (BlockNever, Components, Attribute, Metadata) 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 Json_schema_station_props struct {
   BlockNever bool
   Components *OpenApi_IComponents
@@ -19,6 +28,13 @@ type Json_schema_station_props struct {
   Metadata   *nativemetadata.MetadataSchema
 }
 
+// Json_schema_station converts a metadata schema to a JSON schema, registering
+// the components it refers to and merging the given attributes.
+//
+// @evidence contracts/common.md#principled-implementation It converts a metadata schema to a JSON schema, registering the components it refers to and merging the given attributes.
+// @evidence contracts/common.md#clear-and-simple-design One exported function; the pieces that repeat live in private helpers of the same file.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The only state it changes is the components record it is given.
+// @evidence contracts/common.md#meaningful-documentation The doc states what it builds.
 func Json_schema_station(props Json_schema_station_props) JsonSchema {
   return json_schema_station(json_schema_station_props{
     blockNever: props.BlockNever,

package/native/core/programmers/iterate/json_schema_string.go

@@ -12,6 +12,13 @@ func json_schema_string(atomic *nativemetadata.MetadataAtomic) []JsonSchema {
   })
 }
 
+// Json_schema_string_export converts a string atomic to its JSON schemas: a
+// `string` schema, one per type-tag plugin row.
+//
+// @evidence contracts/common.md#principled-implementation It converts a string atomic to its JSON schemas: a `string` schema, one per type-tag plugin row.
+// @evidence contracts/common.md#clear-and-simple-design A one-line exported wrapper over the package-private function.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The wrapper has no logic of its own.
+// @evidence contracts/common.md#meaningful-documentation The doc states what it builds.
 func Json_schema_string_export(atomic *nativemetadata.MetadataAtomic) []JsonSchema {
   return json_schema_string(atomic)
 }

package/native/core/programmers/iterate/openapi_v3_downgrader.go

@@ -7,24 +7,28 @@ import (
   nativefactories "github.com/samchon/typia/packages/typia/native/core/factories"
 )
 
-// OpenApiV3Downgrader rewrites an emended (OpenAPI 3.1) schema collection into
+// OpenApiV3Downgrader rewrites an emended schema collection into
 // the OpenAPI 3.0 dialect. `json.schema`, `json.schemas`, and `json.application`
-// all build their document through json_schema_station, which speaks 3.1 only:
+// all build their document through json_schema_station, whose normalized dialect
+// uses 3.1-style schema keywords:
 // it emits `const`, `prefixItems`, and a `{"type": "null"}` union member for a
 // nullable type. None of those exist in 3.0, which spells the same three things
 // as `enum`, `items` + `minItems`/`maxItems`, and the `nullable` flag.
 //
-// This is a port of `@typia/utils`' OpenApiV3Downgrader, which the TypeScript
-// implementation of JsonSchemasProgrammer called through
-// `OpenApiConverter.downgradeComponents` / `downgradeSchema` before the Go port
-// replaced it. The Go transform cannot call into TypeScript, so the two are
-// necessarily separate implementations of one contract; the port is kept
-// deliberately literal so the correspondence stays reviewable, and
+// This is a port of `@typia/utils`' OpenApiV3Downgrader. The Go transform cannot
+// call into TypeScript, so the two are necessarily separate implementations of
+// one contract; the port is kept deliberately literal so the correspondence stays
+// reviewable, and
 // `tests/test-typia-schema/src/features/json.schemas/test_json_schemas_v3_0_parity_converter.ts`
 // pins the two owners against each other on every emitted construct.
 //
 // Only the components-and-schemas surface is ported. The TypeScript owner also
 // downgrades paths, operations, and security schemes, none of which typia emits.
+//
+// @evidence contracts/common.md#principled-implementation It is the working state of OpenApiV3Downgrader; its 2 fields (Original, Downgraded) are named so that a producer and a consumer cannot transpose them.
+// @evidence contracts/common.md#clear-and-simple-design A 2-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 OpenApiV3Downgrader_IComponentsCollection struct {
   // Original is the emended 3.1 collection, read to resolve `$ref` targets
   // while deciding nullability. It is never mutated.
@@ -39,6 +43,11 @@ type OpenApiV3Downgrader_IComponentsCollection struct {
 // downgraded before its own key is registered, so the `X.Nullable` companions
 // that its references create land ahead of it exactly as the TypeScript owner's
 // argument-evaluation order places them.
+//
+// @evidence contracts/common.md#principled-implementation Every schema is downgraded in discovery order before its own key is registered, so the `X.Nullable` companions that its references create land ahead of it, and the input collection is only read.
+// @evidence contracts/common.md#clear-and-simple-design One loop over the ordered keys that delegates each schema to the schema downgrade.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Order comes from the recorded Order and not from sorting.
+// @evidence contracts/common.md#meaningful-documentation The doc states the order and why the companions come first.
 func OpenApiV3Downgrader_downgrade_components(input *OpenApi_IComponents) *OpenApiV3Downgrader_IComponentsCollection {
   collection := &OpenApiV3Downgrader_IComponentsCollection{
     Original:   input,
@@ -63,10 +72,20 @@ func OpenApiV3Downgrader_downgrade_components(input *OpenApi_IComponents) *OpenA
 // OpenApiV3Downgrader_downgrade_schema rewrites one emended schema into 3.0.
 //
 // The emended dialect expresses a union as `oneOf` and nullability as a
-// `{"type": "null"}` member of it. 3.0 has neither, so the schema is flattened
+// `{"type": "null"}` member of it. 3.0 supports oneOf but has no null type, so
+// the schema is flattened
 // into a union of concrete members, the null member is dropped, and the
 // surviving members carry `nullable: true` instead. Constants collapse into the
 // `enum` of a member of the same primitive type.
+// Tuple positions become an item union with prefix-length bounds, losing
+// positional and optional-prefix restrictions. Existing nullable companion names
+// are reused without comparing their schemas. A pure null result retains the
+// existing null-typed representation rather than acquiring a 3.0 nullable type.
+//
+// @evidence contracts/common.md#principled-implementation Constants merge into primitive enums, mixed null unions mark surviving members nullable, references may use nullable companions, and a discriminator survives only when each branch stays one member. Tuple conversion approximates positions and optional-prefix bounds. Existing nullable companion names are reused without schema comparison, and a pure null result keeps the existing null-typed representation; these are not universal lossless 3.0 mappings.
+// @evidence contracts/common.md#clear-and-simple-design One recursive function with a visitor over the schema kinds, delegating tuples, objects and nullable references to named helpers.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The rewrite follows the schema kinds and keywords of the dialect and special-cases no type name.
+// @evidence contracts/common.md#meaningful-documentation The doc states the flattening, the null handling and the constant folding.
 func OpenApiV3Downgrader_downgrade_schema(collection *OpenApiV3Downgrader_IComponentsCollection, input JsonSchema) JsonSchema {
   nullable := openApiV3Downgrader_is_nullable(map[string]bool{}, collection.Original, input)
   union := []JsonSchema{}
@@ -198,7 +217,7 @@ func openApiV3Downgrader_downgrade_tuple(collection *OpenApiV3Downgrader_ICompon
     elements := []JsonSchema{}
     elements = append(elements, prefixItems...)
     if rest := openApiV3Downgrader_schema(additional); rest != nil {
-      elements = append(elements, OpenApiV3Downgrader_downgrade_schema(collection, rest))
+      elements = append(elements, rest)
     }
     if len(elements) == 0 {
       items = JsonSchema{}

package/native/core/programmers/iterate/openapi_v3_downgrader_boolean_default_test.go

@@ -17,10 +17,15 @@ import (
 // from that declared type: only keys it allows may survive, and `examples` — the
 // one 3.0 does not define — must not.
 //
-// 1. Downgrade a boolean carrying `default`, and one also carrying attributes.
-// 2. Assert each keeps every declared keyword and drops only `examples`.
-// 3. Assert a keyword-less boolean still degrades to a bare `{"type": "boolean"}`
-//    and that a boolean inside a union keeps its `default`.
+//  1. Downgrade a boolean carrying `default`, and one also carrying attributes.
+//  2. Assert each keeps every declared keyword and drops only `examples`.
+//  3. Assert a keyword-less boolean still degrades to a bare `{"type": "boolean"}`
+//     and that a boolean inside a union keeps its `default`.
+//
+// @evidence contracts/testing.md#behavioral-verification The 3.0 downgrader is run on boolean schemas with default and other keywords and the serialized output is compared with the expected schema text.
+// @evidence contracts/testing.md#independent-expectations OpenAPI 3.0 retains the declared keywords of a boolean schema; the expected JSON is authored.
+// @evidence contracts/testing.md#distinguishing-cases Boolean schemas with and without extra keywords are compared row by row.
+// @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 downgrader and serializes in memory with no checker, filesystem fixture or process.
 func TestOpenApiV3DowngraderCarriesBooleanKeywords(t *testing.T) {
   collection := OpenApiV3Downgrader_downgrade_components(&OpenApi_IComponents{})
 

package/native/core/programmers/iterate/openapi_v3_downgrader_test.go

@@ -16,10 +16,15 @@ import (
 // expected shapes below come from the OpenAPI 3.0 specification, not from what
 // the downgrader happens to produce.
 //
-// 1. Downgrade a nullable atomic, a literal union, and a tuple.
-// 2. Assert each uses the 3.0 spelling: nullable flag, enum, bounded array.
-// 3. Assert no 3.1-only keyword (`const`, `prefixItems`, a null union member)
-//    survives.
+//  1. Downgrade a nullable atomic, a literal union, and a tuple.
+//  2. Assert each uses the 3.0 spelling: nullable flag, enum, bounded array.
+//  3. Assert no 3.1-only keyword (`const`, `prefixItems`, a null union member)
+//     survives.
+//
+// @evidence contracts/testing.md#behavioral-verification The 3.0 downgrader is run on nullable unions, literals and tuples; the output must equal the authored 3.0 text and no 3.1-only keyword may appear in the serialization.
+// @evidence contracts/testing.md#independent-expectations OpenAPI 3.0 defines nullable, enum and items instead of null types, const and prefixItems; expected texts and the banned keywords are authored.
+// @evidence contracts/testing.md#distinguishing-cases Nullable, literal and tuple constructs are each a row, with a keyword-leak check across all rows.
+// @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 downgrader and serializes in memory with no checker, filesystem fixture or process.
 func TestOpenApiV3DowngraderRewritesDialect(t *testing.T) {
   collection := OpenApiV3Downgrader_downgrade_components(&OpenApi_IComponents{})
 

package/native/core/programmers/iterate/postfix_of_tuple.go

@@ -7,6 +7,14 @@ func postfix_of_tuple(str string) string {
   return str + " + \""
 }
 
+// Postfix_of_tuple_export turns a path postfix into the prefix of a tuple
+// element's path: it drops the closing quote when there is one and otherwise
+// appends ` + "` so the index can be added.
+//
+// @evidence contracts/common.md#principled-implementation It turns a path postfix into the prefix of a tuple element's path: it drops the closing quote when there is one and otherwise appends ` + "` so the index can be added.
+// @evidence contracts/common.md#clear-and-simple-design A one-line exported wrapper over the package-private function.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The wrapper has no logic of its own.
+// @evidence contracts/common.md#meaningful-documentation The doc states what it builds.
 func Postfix_of_tuple_export(str string) string {
   return postfix_of_tuple(str)
 }

package/native/core/programmers/iterate/template_interpolation_tags_test.go

@@ -25,6 +25,11 @@ import (
 //  1. Count bare, alternation, nested, and non-capturing patterns.
 //  2. Count the numeric span (only inline groups) as zero.
 //  3. Count escaped parens as zero and a real group after `\\` as one.
+//
+// @evidence contracts/testing.md#behavioral-verification The capture-group counter is called on bare, alternation, nested, non-capturing, escaped and escaped-backslash patterns.
+// @evidence contracts/testing.md#independent-expectations JavaScript regex group numbering defines each count; patterns and counts are authored literals.
+// @evidence contracts/testing.md#distinguishing-cases Escaped parentheses and an unescaped group after an escaped backslash are the boundary rows.
+// @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 calls the private counter directly in the same package with no checker, filesystem fixture or process.
 func TestTemplateCountCapturingGroups(t *testing.T) {
   cases := []struct {
     pattern string
@@ -51,12 +56,17 @@ func TestTemplateCountCapturingGroups(t *testing.T) {
 // TestTemplateFullyConstrained gates which tag matrices earn a capture.
 //
 // A placeholder is only captured when every OR row contributes at least one
-// validate-able tag; otherwise some row admits the base type unconditionally and
+// runtime condition, including exclusion; otherwise some row admits the base type unconditionally and
 // honoring the others would reject values the type accepts.
 //
 //  1. Reject nil and empty matrices.
-//  2. Accept a matrix whose every row has a validate-able tag.
+//  2. Accept a matrix whose every row has a runtime condition.
 //  3. Reject a matrix with a row of only non-validating tags.
+//
+// @evidence contracts/testing.md#behavioral-verification The full-constraint gate is called on nil, empty, fully validating, mixed, exclusion-only and partially validating tag matrices, including an empty OR row.
+// @evidence contracts/testing.md#independent-expectations A placeholder is captured only when every OR row has a runtime condition, including exclusion; matrices and verdicts are authored.
+// @evidence contracts/testing.md#distinguishing-cases Nil, empty, empty-row and partial matrices are negatives; validating and exclusion-only matrices are positives.
+// @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 calls the private gate directly in the same package with no checker, filesystem fixture or process.
 func TestTemplateFullyConstrained(t *testing.T) {
   validating := nativemetadata.IMetadataTypeTag{Name: "Minimum<0>", Validate: "0 <= $input"}
   schemaOnly := nativemetadata.IMetadataTypeTag{Name: "Format<\"uuid\">"}
@@ -69,6 +79,8 @@ func TestTemplateFullyConstrained(t *testing.T) {
     {"empty", [][]nativemetadata.IMetadataTypeTag{}, false},
     {"single", [][]nativemetadata.IMetadataTypeTag{{validating}}, true},
     {"mixed-row", [][]nativemetadata.IMetadataTypeTag{{schemaOnly, validating}}, true},
+    {"exclude-only", [][]nativemetadata.IMetadataTypeTag{{{Kind: "exclude", Schema: map[string]any{"not": map[string]any{"enum": []any{"no"}}}}}}, true},
+    {"empty-row", [][]nativemetadata.IMetadataTypeTag{{validating}, {}}, false},
     {"schema-only-row", [][]nativemetadata.IMetadataTypeTag{{schemaOnly}}, false},
     {"one-unconstrained-row", [][]nativemetadata.IMetadataTypeTag{{validating}, {schemaOnly}}, false},
   }
@@ -88,6 +100,11 @@ func TestTemplateFullyConstrained(t *testing.T) {
 //
 //  1. Accept number, bigint, and string placeholders with validating tags.
 //  2. Reject boolean, unconstrained, nullable, optional, multi-bucket.
+//
+// @evidence contracts/testing.md#behavioral-verification The capture decision is called on number, bigint and string placeholders with validating tags and on boolean, unconstrained, nullable, optional and multi-bucket placeholders.
+// @evidence contracts/testing.md#independent-expectations Only sole required non-nullable primitives with runtime-checkable tags are captured; the verdicts are authored from that rule.
+// @evidence contracts/testing.md#distinguishing-cases Three accepted kinds and seven rejected shapes separate capture from structural-only matching.
+// @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 calls the private decision directly in the same package with no checker, filesystem fixture or process.
 func TestTemplateConstrainedCapture(t *testing.T) {
   minimum := [][]nativemetadata.IMetadataTypeTag{{{Name: "Minimum<0>", Validate: "0 <= $input"}}}
 
@@ -147,6 +164,11 @@ func TestTemplateConstrainedCapture(t *testing.T) {
 //  5. An ambiguous placeholder has no direct capture; backtracking owns it.
 //  6. A template with no constrained placeholder yields no captures and the
 //     historical pattern.
+//
+// @evidence contracts/testing.md#behavioral-verification The runtime template pattern builder is called on literal-plus-number, repeated number, sole string, bigint and ambiguous templates; the pattern text and capture index are compared.
+// @evidence contracts/testing.md#independent-expectations JavaScript numbers capture groups by position, so indices are authored by counting groups in the expected pattern.
+// @evidence contracts/testing.md#distinguishing-cases Each placeholder kind has a row and the ambiguous placeholder is the no-direct-capture case.
+// @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 calls the private builder directly in the same package with no checker, filesystem fixture or process.
 func TestTemplateRuntimePattern(t *testing.T) {
   number := iterateTemplateAtomic("number", [][]nativemetadata.IMetadataTypeTag{{{Name: "Minimum<0>", Validate: "0 <= $input"}}})
   numberB := iterateTemplateAtomic("number", [][]nativemetadata.IMetadataTypeTag{{{Name: "Maximum<9>", Validate: "$input <= 9"}}})
@@ -220,6 +242,11 @@ func TestTemplateRuntimePattern(t *testing.T) {
 // TestTemplateRequiresBacktracking separates unique captures from ambiguous
 // boundary searches and keeps each searched placeholder's standalone pattern
 // faithful to its runtime base type.
+//
+// @evidence contracts/testing.md#behavioral-verification The backtracking decision is called on unique and ambiguous placeholders and each searched placeholder's standalone pattern is compared with its base type pattern.
+// @evidence contracts/testing.md#independent-expectations A placeholder needs backtracking when its boundary can slide; verdicts and patterns are authored.
+// @evidence contracts/testing.md#distinguishing-cases Unique captures versus ambiguous boundary searches form the pairs.
+// @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 calls the private decision directly in the same package with no checker, filesystem fixture or process.
 func TestTemplateRequiresBacktracking(t *testing.T) {
   number := iterateTemplateAtomic("number", [][]nativemetadata.IMetadataTypeTag{{{Name: "Minimum<10>", Validate: "10 <= $input"}}})
   str := iterateTemplateAtomic("string", [][]nativemetadata.IMetadataTypeTag{{{Name: "MinLength<3>", Validate: "$input.length >= 3"}}})
@@ -261,6 +288,11 @@ func TestTemplateRequiresBacktracking(t *testing.T) {
 //  3. `${n}-${n}` clears ("-" not number-extendable); `${n}.${n}` does not (".").
 //  4. A string before a sibling absorbs the separator, unpinning both itself and
 //     the number; a number before a string keeps both.
+//
+// @evidence contracts/testing.md#behavioral-verification The clear-boundary predicate is called on single literals, atomics, constants, nil and templates with adjacent variables and separators; each boundary verdict is compared.
+// @evidence contracts/testing.md#independent-expectations A placeholder is pinned only when a literal edge or non-absorbed neighbor fixes the split; the verdict table is authored.
+// @evidence contracts/testing.md#distinguishing-cases Sole, literal-fenced and adjacent-variable placeholders, number-extendable and non-extendable separators and string-before-number order each flip a verdict.
+// @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 calls the private predicate directly in the same package with no checker, filesystem fixture or process.
 func TestTemplateClearBoundary(t *testing.T) {
   num := iterateTemplateAtomic("number", [][]nativemetadata.IMetadataTypeTag{{{Name: "Minimum<0>", Validate: "0 <= $input"}}})
   str := iterateTemplateAtomic("string", [][]nativemetadata.IMetadataTypeTag{{{Name: "MinLength<1>", Validate: "$input.length >= 1"}}})
@@ -321,6 +353,11 @@ func TestTemplateClearBoundary(t *testing.T) {
 //  2. variable_kind: number/bigint/string atomics map to themselves; everything
 //     else (boolean, constant-only, nil) is conservatively "string".
 //  3. literal_first: the text's first rune, or not-ok for empty/non-literal/nil.
+//
+// @evidence contracts/testing.md#behavioral-verification The right-extension, variable-kind and literal-first helpers are called on number, bigint, string, boolean, constant, nil and empty inputs.
+// @evidence contracts/testing.md#independent-expectations Number growth through digits, dot and exponent but not sign, and the conservative string default are authored from number grammar.
+// @evidence contracts/testing.md#distinguishing-cases Each helper has accepted and rejected rows.
+// @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 calls the private helpers directly in the same package with no checker, filesystem fixture or process.
 func TestTemplateBoundaryHelpers(t *testing.T) {
   for _, c := range []struct {
     kind string
@@ -381,6 +418,11 @@ func TestTemplateBoundaryHelpers(t *testing.T) {
 //  3. Sole template, whole-string tag only → unchanged whole-string conditions.
 //  4. Sole template, string placeholder with an exclude tag → string conditions.
 //  5. Union of constrained templates → no entry conditions, non-nil expression.
+//
+// @evidence contracts/testing.md#behavioral-verification The checker entry is built for sole templates with single-row, multi-row, whole-string and exclude tags and for a union of templates; condition counts and the inline expression are asserted.
+// @evidence contracts/testing.md#independent-expectations Authored tag matrices and the stated threading rule give expected row and condition counts.
+// @evidence contracts/testing.md#distinguishing-cases The original numeric, bigint, whole-string, exclusion and union scenarios change the matrix shape; the union case asserts no entry conditions and a non-nil expression.
+// @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 TestCheckTemplateInterpolationConditions(t *testing.T) {
   emit := shimprinter.NewEmitContext()
   factory := shimast.NewNodeFactory(shimast.NodeFactoryHooks{})
@@ -511,8 +553,8 @@ func TestCheckTemplateInterpolationConditions(t *testing.T) {
   }
 
   // 7. reducing an empty slice yields a literal (true/false) keyword.
-  if check_template_reduce(nil, shimast.KindBarBarToken) == nil {
-    t.Fatal("empty reduce should yield a keyword")
+  if check_template_reduce(nil, shimast.KindBarBarToken).Kind != shimast.KindTrueKeyword {
+    t.Fatal("empty reduce should yield the true keyword")
   }
 }