typia 15.0.0 → 15.1.0

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

@@ -8,12 +8,26 @@ import (
   nativemetadata "github.com/samchon/typia/packages/typia/native/core/schemas/metadata"
 )
 
+// Check_stringProps is the argument record of Check_string, which builds the
+// check entry of a string atomic.
+//
+// @evidence contracts/common.md#principled-implementation It is the argument record of Check_string, which builds the check entry of a string atomic; its 3 fields (Context, Atomic, Input) are named so that a producer and a consumer cannot transpose them.
+// @evidence contracts/common.md#clear-and-simple-design A 3-field record with no methods.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A data record: it derives, defaults and validates nothing.
+// @evidence contracts/common.md#meaningful-documentation The doc states what the record is.
 type Check_stringProps struct {
   Context nativecontext.ITypiaContext
   Atomic  *nativemetadata.MetadataAtomic
   Input   *shimast.Expression
 }
 
+// Check_string builds the check entry of a string atomic: a `typeof input ===
+// "string"` guard plus the atomic's type-tag conditions.
+//
+// @evidence contracts/common.md#principled-implementation It builds the check entry of a string atomic: a `typeof input === "string"` guard plus the atomic's type-tag conditions.
+// @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 Its inputs are its arguments and the context they carry, and it keeps no state of its own.
+// @evidence contracts/common.md#meaningful-documentation The doc states what it builds.
 func Check_string(props Check_stringProps) nativehelpers.ICheckEntry {
   f := nativecontext.EmitFactoryOf(check_string_factory, props.Context.Emit)
   conditions := check_string_type_tags(props)

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

@@ -12,6 +12,13 @@ import (
   nativemetadata "github.com/samchon/typia/packages/typia/native/core/schemas/metadata"
 )
 
+// Check_templateProps is the argument record of Check_template, which builds the
+// check entry of template literal types.
+//
+// @evidence contracts/common.md#principled-implementation It is the argument record of Check_template, which builds the check entry of template literal types; its 4 fields (Context, Templates, Input, Emit) are named so that a producer and a consumer cannot transpose them.
+// @evidence contracts/common.md#clear-and-simple-design A 4-field record with no methods.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A data record: it derives, defaults and validates nothing.
+// @evidence contracts/common.md#meaningful-documentation The doc states what the record is.
 type Check_templateProps struct {
   Context   nativecontext.ITypiaContext
   Templates []*nativemetadata.MetadataTemplate
@@ -19,6 +26,14 @@ type Check_templateProps struct {
   Emit      *shimprinter.EmitContext
 }
 
+// Check_template builds the check entry of template literal types: a string
+// guard plus one `RegExp(...).test` per template, with the type tags inlined
+// into the member when several templates are neighbors.
+//
+// @evidence contracts/common.md#principled-implementation It builds the check entry of template literal types: a string guard plus one `RegExp(...).test` per template, with the type tags inlined into the member when several templates are neighbors.
+// @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 Its inputs are its arguments and the context they carry, and it keeps no state of its own.
+// @evidence contracts/common.md#meaningful-documentation The doc states what it builds.
 func Check_template(props Check_templateProps) nativehelpers.ICheckEntry {
   f := nativecontext.EmitFactoryOf(check_template_factory, props.Emit)
   conditions := []*shimast.Node{

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

@@ -6,9 +6,19 @@ import (
   shimast "github.com/microsoft/typescript-go/shim/ast"
   shimprinter "github.com/microsoft/typescript-go/shim/printer"
   nativecontext "github.com/samchon/typia/packages/typia/native/core/context"
+  nativehelpers "github.com/samchon/typia/packages/typia/native/core/programmers/helpers"
   nativemetadata "github.com/samchon/typia/packages/typia/native/core/schemas/metadata"
 )
 
+// Decode_union_objectProps is the argument record of Decode_union_object, which
+// decodes a union of object types. Checker and Decoder receive one object type
+// at a time, Success wraps a checker result and Escaper builds the failure when
+// no object type matches.
+//
+// @evidence contracts/common.md#principled-implementation It is the argument record of Decode_union_object, which decodes a union of object types; its 8 fields (Checker, Decoder, Success, Escaper, Objects, Input, Explore, Emit) are named so that a producer and a consumer cannot transpose them.
+// @evidence contracts/common.md#clear-and-simple-design A 8-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 Decode_union_objectProps struct {
   Checker func(next Decode_union_object_next) *shimast.Node
   Decoder func(next Decode_union_object_next) *shimast.Node
@@ -16,21 +26,44 @@ type Decode_union_objectProps struct {
   Escaper func(next Decode_union_object_escape) *shimast.Node
   Objects []*nativemetadata.MetadataObjectType
   Input   *shimast.Expression
-  Explore any
+  Explore nativehelpers.UnionExplorer_IExplore
   Emit    *shimprinter.EmitContext
 }
 
+// Decode_union_object_next is the argument of the Checker and Decoder callbacks
+// of Decode_union_object: the input and the one object type to consider.
+//
+// @evidence contracts/common.md#principled-implementation It is the argument of the Checker and Decoder callbacks of Decode_union_object: the input and the one object type to consider; its 3 fields (Input, Object, Explore) are named so that a producer and a consumer cannot transpose them.
+// @evidence contracts/common.md#clear-and-simple-design A 3-field record with no methods.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A data record: it derives, defaults and validates nothing.
+// @evidence contracts/common.md#meaningful-documentation The doc states what the record is.
 type Decode_union_object_next struct {
   Input   *shimast.Expression
   Object  *nativemetadata.MetadataObjectType
-  Explore any
+  Explore nativehelpers.UnionExplorer_IExplore
 }
 
+// Decode_union_object_escape is the argument of the Escaper callback of
+// Decode_union_object: the input and the description of the expected union.
+//
+// @evidence contracts/common.md#principled-implementation It is the argument of the Escaper callback of Decode_union_object: the input and the description of the expected union; its 2 fields (Input, Expected) 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 Decode_union_object_escape struct {
   Input    *shimast.Expression
   Expected string
 }
 
+// Decode_union_object builds an immediately invoked function that tries each
+// object type in order with its checker and returns the decoded value of the
+// first match, and falls back to the escaper when none matches; a checker that
+// is always true ends the search.
+//
+// @evidence contracts/common.md#principled-implementation It builds an immediately invoked function that tries each object type in order with its checker and returns the decoded value of the first match, and falls back to the escaper when none matches; a checker that is always true ends the search.
+// @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 Its inputs are its arguments and the context they carry, and it keeps no state of its own.
+// @evidence contracts/common.md#meaningful-documentation The doc states what it builds.
 func Decode_union_object(props Decode_union_objectProps) *shimast.Node {
   unions := make([]decode_union_object_IUnion, 0, len(props.Objects))
   names := make([]string, 0, len(props.Objects))

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

@@ -0,0 +1,142 @@
+package iterate
+
+import (
+  "fmt"
+  shimast "github.com/microsoft/typescript-go/shim/ast"
+  "github.com/samchon/ttsc/packages/ttsc/driver"
+  nativecontext "github.com/samchon/typia/packages/typia/native/core/context"
+  factories "github.com/samchon/typia/packages/typia/native/core/factories"
+  metadata "github.com/samchon/typia/packages/typia/native/core/schemas/metadata"
+  "os"
+  "path/filepath"
+  "testing"
+)
+
+// TestExactOptionalCheckerEntryContract verifies compiler metadata reaches optional guards.
+//
+// The real Go checker reads optional-only, optional undefined-union and required
+// undefined-union properties under unset/false/true exactOptionalPropertyTypes.
+// Plugin undefined is independently omitted/false/true. Strict entries must
+// remove optional decoding only in the exact=true, undefined=false conjunction,
+// then allow an absent key through the object guard without mutating metadata.
+//
+// @evidence contracts/testing.md#behavioral-verification Loads three real TypeScript compiler contexts in process, analyzes all three property types, builds Feature_object_entries and inspects the resulting check_object AST for each undefined option row.
+// @evidence contracts/testing.md#independent-expectations Authored property declarations and literal optional/required tables define the metadata oracle; exact optional-only requires an absence short circuit, while explicit undefined unions remain value-valid.
+// @evidence contracts/testing.md#distinguishing-cases Compiler unset/false/true crosses plugin undefined omitted/false/true. Optional-only differs from optional and required explicit unions; only the strict entry changes decoded Optional and adds !in ||, and source metadata must remain unchanged.
+// @evidence contracts/testing.md#execution-ownership The native Go runner loads temporary tsconfig/source files with driver.LoadProgram and closes each program. Checker, metadata and emitter calls remain in process, without Node or compiler subprocesses. This metadata/AST case does not claim JavaScript runtime observations.
+func TestExactOptionalCheckerEntryContract(t *testing.T) {
+  compilerRows := []struct {
+    name, setting    string
+    optionalRequired bool
+  }{
+    {"unset", "", false}, {"false", `,"exactOptionalPropertyTypes":false`, false}, {"true", `,"exactOptionalPropertyTypes":true`, true},
+  }
+  yes, no := true, false
+  undefinedRows := []struct {
+    name  string
+    value *bool
+  }{{"omitted", nil}, {"false", &no}, {"true", &yes}}
+  expectedOptional := map[string]bool{"optional": true, "optionalUndefined": true, "requiredUndefined": false}
+  for _, compiler := range compilerRows {
+    t.Run(compiler.name, func(t *testing.T) {
+      dir := t.TempDir()
+      config := fmt.Sprintf(`{"compilerOptions":{"target":"ES2022","module":"commonjs","moduleResolution":"bundler","ignoreDeprecations":"6.0","strict":true,"skipLibCheck":true%s},"include":["main.ts"]}`, compiler.setting)
+      if err := os.WriteFile(filepath.Join(dir, "tsconfig.json"), []byte(config), 0o644); err != nil {
+        t.Fatal(err)
+      }
+      const sourceText = `interface Example { optional?: string; optionalUndefined?: string | undefined; requiredUndefined: string | undefined; }
+let input!: Example;
+`
+      sourcePath := filepath.Join(dir, "main.ts")
+      if err := os.WriteFile(sourcePath, []byte(sourceText), 0o644); err != nil {
+        t.Fatal(err)
+      }
+      program, diagnostics, err := driver.LoadProgram(dir, "tsconfig.json", driver.LoadProgramOptions{})
+      if err != nil {
+        t.Fatal(err)
+      }
+      defer program.Close()
+      if len(diagnostics) != 0 {
+        t.Fatalf("fixture diagnostics: %+v", diagnostics)
+      }
+      source := program.SourceFile(sourcePath)
+      if source == nil || source.Statements == nil || len(source.Statements.Nodes) != 2 {
+        t.Fatal("fixture declarations missing")
+      }
+      declaration := source.Statements.Nodes[1].AsVariableStatement().DeclarationList.AsVariableDeclarationList().Declarations.Nodes[0]
+      result := factories.MetadataFactory.Analyze(factories.MetadataFactory_IProps{Checker: program.Checker, Options: factories.MetadataFactory_IOptions{}, Components: metadata.NewMetadataCollection(), Type: program.Checker.GetTypeAtLocation(declaration)})
+      if !result.Success || result.Data == nil || len(result.Data.Objects) != 1 {
+        t.Fatalf("metadata analysis failed: %+v", result.Errors)
+      }
+      object := result.Data.Objects[0].Type
+      if len(object.Properties) != 3 {
+        t.Fatalf("property count=%d", len(object.Properties))
+      }
+      for _, property := range object.Properties {
+        key := property.Key.GetSoleLiteral()
+        if key == nil {
+          t.Fatal("literal key missing")
+        }
+        wantOptional, known := expectedOptional[*key]
+        if !known {
+          t.Fatalf("unexpected fixture property %s", *key)
+        }
+        wantRequired := *key == "optional" && compiler.optionalRequired
+        if property.Value.Optional != wantOptional || property.Value.Required != wantRequired || len(property.Value.Atomics) != 1 || property.Value.Atomics[0].Type != "string" {
+          t.Fatalf("%s metadata Optional=%v Required=%v Atomics=%+v", *key, property.Value.Optional, property.Value.Required, property.Value.Atomics)
+        }
+      }
+      factory := shimast.NewNodeFactory(shimast.NodeFactoryHooks{})
+      input := factory.NewIdentifier("candidate")
+      for _, undefined := range undefinedRows {
+        t.Run("undefined="+undefined.name, func(t *testing.T) {
+          context := nativecontext.ITypiaContext{Program: program, Checker: program.Checker, CompilerOptions: program.ParsedConfig.ParsedConfig.CompilerOptions, Options: nativecontext.ITransformOptions{Undefined: undefined.value}}
+          decoded := map[string]*metadata.MetadataSchema{}
+          entries := Feature_object_entries(Feature_object_entriesProps{Context: context, Object: object, Input: input, Config: Feature_object_entriesConfig{Decoder: func(props Feature_object_entriesDecoderProps) *shimast.Node {
+            decoded[*props.Key] = props.Metadata
+            return factory.NewIdentifier("decoded")
+          }}})
+          if len(entries) != 3 {
+            t.Fatalf("entry count=%d", len(entries))
+          }
+          for _, entry := range entries {
+            key := entry.Key.GetSoleLiteral()
+            if key == nil {
+              t.Fatal("entry key missing")
+            }
+            wantExact := compiler.name == "true" && undefined.name == "false" && expectedOptional[*key]
+            wantStrict := wantExact && *key == "optional"
+            if entry.OptionalProperty != wantExact || entry.StrictOptionalUndefined != wantStrict {
+              t.Fatalf("%s entry exact=%v strict=%v", *key, entry.OptionalProperty, entry.StrictOptionalUndefined)
+            }
+            if entry.Meta.Optional != expectedOptional[*key] || decoded[*key].Optional != (expectedOptional[*key] && !wantStrict) {
+              t.Fatalf("%s source or decoder optionality changed incorrectly", *key)
+            }
+            wrapped := check_object_regular_expression(Check_objectProps{Context: context, Input: input}, entry)
+            if !wantStrict {
+              if wrapped != entry.Expression {
+                t.Fatalf("%s acquired an unrelated presence guard", *key)
+              }
+              continue
+            }
+            if wrapped.Kind != shimast.KindBinaryExpression {
+              t.Fatal("strict entry missing absence short circuit")
+            }
+            outer := wrapped.AsBinaryExpression()
+            if outer.OperatorToken.Kind != shimast.KindBarBarToken || outer.Right != entry.Expression || outer.Left.Kind != shimast.KindPrefixUnaryExpression {
+              t.Fatal("strict entry must be absence || decoded value")
+            }
+            prefix := outer.Left.AsPrefixUnaryExpression()
+            if prefix.Operator != shimast.KindExclamationToken || prefix.Operand.Kind != shimast.KindBinaryExpression {
+              t.Fatal("absence must negate key presence")
+            }
+            presence := prefix.Operand.AsBinaryExpression()
+            if presence.OperatorToken.Kind != shimast.KindInKeyword || presence.Right != input || presence.Left.Kind != shimast.KindStringLiteral || shimast.NodeText(presence.Left) != "optional" {
+              t.Fatal("presence must test original optional key and input")
+            }
+          }
+        })
+      }
+    })
+  }
+}

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

@@ -0,0 +1,213 @@
+package iterate
+
+import (
+  shimast "github.com/microsoft/typescript-go/shim/ast"
+  "github.com/samchon/ttsc/packages/ttsc/driver"
+  nativecontext "github.com/samchon/typia/packages/typia/native/core/context"
+  factories "github.com/samchon/typia/packages/typia/native/core/factories"
+  helpers "github.com/samchon/typia/packages/typia/native/core/programmers/helpers"
+  metadata "github.com/samchon/typia/packages/typia/native/core/schemas/metadata"
+  "os"
+  "path/filepath"
+  "testing"
+)
+
+// TestExactOptionalGraphCloneRandomContract preserves the removed suite's declaration graph.
+//
+// Root, nested, array-element and discriminated-union declarations retain the
+// distinction between absent optional keys and explicitly allowed undefined.
+// Clone emits conditional own-property assignments for optional keys; random
+// emits both omission and inclusion branches and removes implicit undefined
+// from optional-only included values without mutating source metadata.
+//
+// @evidence contracts/testing.md#behavioral-verification Real checker metadata for both original interface graphs flows through Feature_object_entries, object guard, CloneJoiner.Object and RandomJoiner.Object. Literal guards, assignment keys, branch properties and decoder metadata are inspected in the generated AST.
+// @evidence contracts/testing.md#independent-expectations Original field declarations and independent literal key/type/optional tables define expectations. Missing clone keys require empty false branches, explicit undefined unions require key-presence alternatives and required undefined must remain an unconditional own assignment.
+// @evidence contracts/testing.md#distinguishing-cases Root/nested/array/union optional-only and explicit-union positions survive. Required string and required undefined are controls; random false/true inclusion produces empty versus own-key assignment branches, with string versus nested number value types retained.
+// @evidence contracts/testing.md#execution-ownership The Go runner loads and closes one compiler program in process, then calls actual metadata and emitter operations. It launches no Node or compiler subprocess and does not interpret JavaScript or certify runtime TypeGuardError class identity.
+func TestExactOptionalGraphCloneRandomContract(t *testing.T) {
+  dir := t.TempDir()
+  config := `{"compilerOptions":{"target":"ES2022","module":"commonjs","moduleResolution":"bundler","ignoreDeprecations":"6.0","strict":true,"exactOptionalPropertyTypes":true,"skipLibCheck":true},"include":["main.ts"]}`
+  sourceText := `interface IExactOptional { required: string; optional?: string; optionalUndefined?: string | undefined; requiredUndefined: string | undefined; nested?: IExactOptionalNested; array: IExactOptionalNested[]; union: IExactOptionalUnion; }
+interface IExactOptionalNested { optional?: number; optionalUndefined?: number | undefined; }
+type IExactOptionalUnion = { type: "a"; optional?: string; optionalUndefined?: string | undefined; } | { type: "b"; value: string; };
+interface IExactOptionalClone { required: string; optional?: string; optionalUndefined?: string | undefined; requiredUndefined: string | undefined; nested: IExactOptionalCloneNested; array: IExactOptionalCloneNested[]; }
+interface IExactOptionalCloneNested { optional?: number; optionalUndefined?: number | undefined; }
+let root!: IExactOptional; let clone!: IExactOptionalClone;
+`
+  for name, text := range map[string]string{"tsconfig.json": config, "main.ts": sourceText} {
+    if err := os.WriteFile(filepath.Join(dir, name), []byte(text), 0o644); err != nil {
+      t.Fatal(err)
+    }
+  }
+  program, diagnostics, err := driver.LoadProgram(dir, "tsconfig.json", driver.LoadProgramOptions{})
+  if err != nil {
+    t.Fatal(err)
+  }
+  defer program.Close()
+  if len(diagnostics) != 0 {
+    t.Fatalf("fixture diagnostics: %+v", diagnostics)
+  }
+  source := program.SourceFile(filepath.Join(dir, "main.ts"))
+  if source == nil || source.Statements == nil || len(source.Statements.Nodes) != 7 {
+    t.Fatal("original fixture graph declarations missing")
+  }
+  no := false
+  context := nativecontext.ITypiaContext{Program: program, Checker: program.Checker, CompilerOptions: program.ParsedConfig.ParsedConfig.CompilerOptions, Options: nativecontext.ITransformOptions{Undefined: &no}}
+  factory := shimast.NewNodeFactory(shimast.NodeFactoryHooks{})
+  input := factory.NewIdentifier("candidate")
+  for _, rootIndex := range []int{5, 6} {
+    collection := metadata.NewMetadataCollection()
+    declaration := source.Statements.Nodes[rootIndex].AsVariableStatement().DeclarationList.AsVariableDeclarationList().Declarations.Nodes[0]
+    result := factories.MetadataFactory.Analyze(factories.MetadataFactory_IProps{Checker: program.Checker, Options: factories.MetadataFactory_IOptions{Constant: true, Absorb: true}, Components: collection, Type: program.Checker.GetTypeAtLocation(declaration)})
+    if !result.Success || result.Data == nil || len(result.Data.Objects) != 1 {
+      t.Fatalf("graph analysis failed: %+v", result.Errors)
+    }
+    objects := collection.Objects()
+    wantObjects := 4
+    if rootIndex == 6 {
+      wantObjects = 2
+    }
+    if len(objects) != wantObjects {
+      t.Fatalf("graph object count=%d want %d", len(objects), wantObjects)
+    }
+    root := result.Data.Objects[0].Type
+    properties := map[string]*metadata.MetadataSchema{}
+    for _, p := range root.Properties {
+      properties[*p.Key.GetSoleLiteral()] = p.Value
+    }
+    if len(properties["array"].Arrays) != 1 || len(properties["array"].Arrays[0].Type.Value.Objects) != 1 || len(properties["nested"].Objects) != 1 || properties["array"].Arrays[0].Type.Value.Objects[0].Type != properties["nested"].Objects[0].Type {
+      t.Fatal("nested and array element must retain the same declared object")
+    }
+    if rootIndex == 5 && len(properties["union"].Objects) != 2 {
+      t.Fatal("both authored union arms must survive")
+    }
+    for _, object := range objects {
+      t.Run(object.Name, func(t *testing.T) {
+        originalOptional := map[string]bool{}
+        decoded := map[string]*metadata.MetadataSchema{}
+        for _, p := range object.Properties {
+          key := *p.Key.GetSoleLiteral()
+          originalOptional[key] = p.Value.Optional
+          if key == "optional" || key == "optionalUndefined" {
+            wantRequired := key == "optional"
+            if !p.Value.Optional || p.Value.Required != wantRequired || len(p.Value.Atomics) != 1 {
+              t.Fatalf("%s optional metadata differs", key)
+            }
+            wantType := "string"
+            if object.Name == "IExactOptionalNested" || object.Name == "IExactOptionalCloneNested" {
+              wantType = "number"
+            }
+            if p.Value.Atomics[0].Type != wantType {
+              t.Fatalf("%s must retain %s", key, wantType)
+            }
+          }
+        }
+        entries := Feature_object_entries(Feature_object_entriesProps{Context: context, Object: object, Input: input, Config: Feature_object_entriesConfig{Trace: true, Decoder: func(props Feature_object_entriesDecoderProps) *shimast.Node {
+          key := *props.Key
+          // Explore.Postfix is JavaScript expression text; all authored keys are identifiers.
+          // The literal must spell the .key path, including its source quotes.
+          if props.Explore.Postfix != `".`+key+`"` {
+            t.Fatalf("wrong property diagnostic suffix for %s: %s", key, props.Explore.Postfix)
+          }
+          decoded[key] = props.Metadata
+          return factory.NewIdentifier("decoded_" + key)
+        }}})
+        for _, entry := range entries {
+          key := *entry.Key.GetSoleLiteral()
+          wantStrict := key == "optional" || key == "nested" && rootIndex == 5
+          if entry.StrictOptionalUndefined != wantStrict || entry.OptionalProperty != originalOptional[key] {
+            t.Fatalf("%s optional entry differs", key)
+          }
+          if entry.Meta.Optional != originalOptional[key] || decoded[key].Optional != (originalOptional[key] && !wantStrict) {
+            t.Fatalf("%s decoder/source optionality differs", key)
+          }
+          guarded := check_object_regular_expression(Check_objectProps{Context: context, Input: input}, entry)
+          if wantStrict {
+            if guarded.Kind != shimast.KindBinaryExpression || guarded.AsBinaryExpression().OperatorToken.Kind != shimast.KindBarBarToken || guarded.AsBinaryExpression().Right != entry.Expression {
+              t.Fatalf("%s strict absence guard missing", key)
+            }
+          } else if guarded != entry.Expression {
+            t.Fatalf("%s unexpected absence guard", key)
+          }
+          cloned := helpers.CloneJoiner.Object(helpers.CloneJoiner_ObjectProps{Input: input, Entries: []helpers.IExpressionEntry{entry}})
+          property := cloned.AsObjectLiteralExpression().Properties.Nodes[0]
+          if entry.OptionalProperty {
+            if property.Kind != shimast.KindSpreadAssignment {
+              t.Fatalf("%s optional clone must conditionally spread own property", key)
+            }
+            conditional := property.AsSpreadAssignment().Expression.AsParenthesizedExpression().Expression.AsConditionalExpression()
+            if len(conditional.WhenFalse.AsObjectLiteralExpression().Properties.Nodes) != 0 || len(conditional.WhenTrue.AsObjectLiteralExpression().Properties.Nodes) != 1 {
+              t.Fatalf("%s clone must choose empty or one own property", key)
+            }
+            assignment := conditional.WhenTrue.AsObjectLiteralExpression().Properties.Nodes[0]
+            if assignment.Kind != shimast.KindPropertyAssignment || assignment.Name().Text() != key || assignment.AsPropertyAssignment().Initializer != entry.Expression {
+              t.Fatalf("%s clone value/ownership changed", key)
+            }
+            condition := conditional.Condition.AsBinaryExpression()
+            if wantStrict {
+              if condition.OperatorToken.Kind != shimast.KindExclamationEqualsEqualsToken {
+                t.Fatalf("%s strict clone must reject undefined value", key)
+              }
+            } else {
+              if condition.OperatorToken.Kind != shimast.KindBarBarToken || condition.Right.AsBinaryExpression().OperatorToken.Kind != shimast.KindInKeyword || shimast.NodeText(condition.Right.AsBinaryExpression().Left) != key || condition.Right.AsBinaryExpression().Right != input {
+                t.Fatalf("%s explicit undefined must preserve present key", key)
+              }
+            }
+          } else if property.Kind != shimast.KindPropertyAssignment || property.Name().Text() != key || property.AsPropertyAssignment().Initializer != entry.Expression {
+            t.Fatalf("%s required clone must assign own value unconditionally", key)
+          }
+        }
+        for _, include := range []bool{false, true} {
+          decodeIndex := 0
+          generated := helpers.RandomJoiner.Object(helpers.RandomJoiner_ObjectProps{Object: object, OptionalProperty: func(m *metadata.MetadataSchema) bool {
+            return helpers.OptionPredicator.ExactOptionalProperty(context, m)
+          }, StrictOptionalUndefined: func(m *metadata.MetadataSchema) bool {
+            return helpers.OptionPredicator.StrictOptionalUndefined(context, m)
+          }, Optional: func() *shimast.Node {
+            if include {
+              return factory.NewKeywordExpression(shimast.KindTrueKeyword)
+            }
+            return factory.NewKeywordExpression(shimast.KindFalseKeyword)
+          }, Decode: func(m *metadata.MetadataSchema) *shimast.Node {
+            if decodeIndex >= len(object.Properties) {
+              t.Fatal("unexpected random decoder")
+            }
+            original := object.Properties[decodeIndex]
+            decodeIndex++
+            key := *original.Key.GetSoleLiteral()
+            strict := key == "optional" || key == "nested" && rootIndex == 5
+            if m.Optional != (original.Value.Optional && !strict) || m.Required != original.Value.Required || original.Value.Optional != originalOptional[key] {
+              t.Fatalf("%s random included metadata violates optional-only/explicit-undefined distinction", key)
+            }
+            return factory.NewIdentifier("generated_value")
+          }})
+          properties := generated.AsObjectLiteralExpression().Properties.Nodes
+          if len(properties) != len(object.Properties) {
+            t.Fatal("random property population changed")
+          }
+          for index, property := range properties {
+            key := *object.Properties[index].Key.GetSoleLiteral()
+            if originalOptional[key] {
+              if property.Kind != shimast.KindSpreadAssignment {
+                t.Fatalf("%s missing random inclusion branch", key)
+              }
+              conditional := property.AsSpreadAssignment().Expression.AsParenthesizedExpression().Expression.AsConditionalExpression()
+              wantKind := shimast.KindFalseKeyword
+              if include {
+                wantKind = shimast.KindTrueKeyword
+              }
+              if conditional.Condition.Kind != wantKind || len(conditional.WhenFalse.AsObjectLiteralExpression().Properties.Nodes) != 0 || conditional.WhenTrue.AsObjectLiteralExpression().Properties.Nodes[0].Name().Text() != key {
+                t.Fatalf("%s random inclusion/omission own-key contract changed", key)
+              }
+            } else if property.Kind != shimast.KindPropertyAssignment || property.Name().Text() != key {
+              t.Fatalf("%s random required own-key assignment missing", key)
+            }
+          }
+          if decodeIndex != len(object.Properties) {
+            t.Fatal("random decoder population changed")
+          }
+        }
+      })
+    }
+  }
+}

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

@@ -9,6 +9,14 @@ import (
   nativemetadata "github.com/samchon/typia/packages/typia/native/core/schemas/metadata"
 )
 
+// Feature_object_entriesProps is the argument record of Feature_object_entries,
+// which turns the properties of an object type into expression entries. From
+// names the parent kind and defaults to `object`.
+//
+// @evidence contracts/common.md#principled-implementation It is the argument record of Feature_object_entries, which turns the properties of an object type into expression entries; its 5 fields (Config, Context, Object, Input, From) are named so that a producer and a consumer cannot transpose them.
+// @evidence contracts/common.md#clear-and-simple-design A 5-field record with no methods.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A data record: it derives, defaults and validates nothing.
+// @evidence contracts/common.md#meaningful-documentation The doc states what the record is and explains its non-obvious fields.
 type Feature_object_entriesProps struct {
   Config  Feature_object_entriesConfig
   Context nativecontext.ITypiaContext
@@ -17,12 +25,28 @@ type Feature_object_entriesProps struct {
   From    string
 }
 
+// Feature_object_entriesConfig is the configuration of Feature_object_entries.
+// Decoder decodes one property, and Path and Trace say whether the generated
+// function tracks the value path and whether it reports the exception.
+//
+// @evidence contracts/common.md#principled-implementation It is the configuration of Feature_object_entries; its 3 members (Decoder, Path, Trace) are supplied by the caller, so the shared programmer holds no feature-specific behavior.
+// @evidence contracts/common.md#clear-and-simple-design A 3-member record of values and callbacks.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A declaration only.
+// @evidence contracts/common.md#meaningful-documentation The doc states the role and the meaning of the members that are not obvious.
 type Feature_object_entriesConfig struct {
   Decoder func(props Feature_object_entriesDecoderProps) *shimast.Node
   Path    bool
   Trace   bool
 }
 
+// Feature_object_entriesDecoderProps is the argument of the Decoder callback of
+// Feature_object_entries: the property, its metadata, its sole key and input
+// accessor, and the explore state.
+//
+// @evidence contracts/common.md#principled-implementation It is the argument of the Decoder callback of Feature_object_entries: the property, its metadata, its sole key and input accessor, and the explore state; its 5 fields (Metadata, Property, Key, Input, Explore) are named so that a producer and a consumer cannot transpose them.
+// @evidence contracts/common.md#clear-and-simple-design A 5-field record with no methods.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A data record: it derives, defaults and validates nothing.
+// @evidence contracts/common.md#meaningful-documentation The doc states what the record is.
 type Feature_object_entriesDecoderProps struct {
   Metadata *nativemetadata.MetadataSchema
   Property *nativemetadata.MetadataProperty
@@ -31,6 +55,14 @@ type Feature_object_entriesDecoderProps struct {
   Explore  Feature_object_entriesExplore
 }
 
+// Feature_object_entriesExplore is the explore state that Feature_object_entries
+// hands to its decoder. Tracable says whether the path is tracked, Source and
+// From name the position and Postfix is the path suffix of the property.
+//
+// @evidence contracts/common.md#principled-implementation It is the explore state that Feature_object_entries hands to its decoder; its 4 fields (Tracable, Source, From, Postfix) 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 Feature_object_entriesExplore struct {
   Tracable bool
   Source   string
@@ -38,6 +70,14 @@ type Feature_object_entriesExplore struct {
   Postfix  string
 }
 
+// Feature_object_entries decodes every property of an object type into an
+// IExpressionEntry, with the optional flags decided by the options and, when
+// tracing, a path postfix.
+//
+// @evidence contracts/common.md#principled-implementation It decodes every property of an object type into an IExpressionEntry, with the optional flags decided by the options and, when tracing, a path postfix.
+// @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 Its inputs are its arguments and the context they carry, and it keeps no state of its own.
+// @evidence contracts/common.md#meaningful-documentation The doc states what it builds.
 func Feature_object_entries(props Feature_object_entriesProps) []nativehelpers.IExpressionEntry {
   output := make([]nativehelpers.IExpressionEntry, 0, len(props.Object.Properties))
   from := props.From

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

@@ -7,21 +7,27 @@ import (
   "math/big"
   "testing"
 
+  shimast "github.com/microsoft/typescript-go/shim/ast"
+  nativehelpers "github.com/samchon/typia/packages/typia/native/core/programmers/helpers"
   nativemetadata "github.com/samchon/typia/packages/typia/native/core/schemas/metadata"
 )
 
-// TestIterateUtilityCoverage exercises schema and stringify helpers.
+// TestIterateUtilityCoverage exercises schema helpers and property classification.
 //
 // The iterate package contains many small helpers that are normally selected by
 // very specific metadata shapes. This test builds those shapes directly so JSON
-// schema attributes, native exports, prune logic, and stringify property logic
+// schema attributes, native exports and required-property classification
 // remain covered without relying on broad TypeScript fixtures.
 //
 // 1. Apply x-prefixed JSDoc tags and cast their text values.
 // 2. Export title, description, constant, escaped, template, and native schemas.
-// 3. Build stringify output for regular and dynamic object properties.
-// 4. Build prune and native stringify statements for object metadata.
-// 5. Build full JSON schema station outputs for empty, any, native, and union metadata.
+// 3. Build full JSON schema station outputs for empty, any, native, and union metadata.
+// 4. Classify required, mixed optional and empty regular property populations.
+//
+// @evidence contracts/testing.md#behavioral-verification JSDoc casts and selected schema results are compared exactly. The actual dynamic-property helper must classify the original required string entry as all-required, reject the adjacent optional entry and accept an empty population. Remaining schema presence checks detect missing outputs only.
+// @evidence contracts/testing.md#independent-expectations Authored JSDoc text and expected casts are independent. Required/optional flags establish the all-required outcomes, and an empty list contains no optional property; those expectations are not produced by the classifier. Non-nil schema checks have no semantic oracle.
+// @evidence contracts/testing.md#distinguishing-cases The original required singleton is preserved beside a mixed optional negative and an empty boundary. Title, description, constants, escaped, template and native schema paths retain their existing checks without new negative twins.
+// @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 helpers on constructed metadata with no checker, filesystem fixture or process.
 func TestIterateUtilityCoverage(t *testing.T) {
   schema := json_schema_jsDocTags(JsonSchema{}, []nativemetadata.IJsDocTagInfo{
     {Name: "x-enabled", Text: []nativemetadata.IJsDocTagInfo_IText{{Kind: "text", Text: "true"}}},
@@ -76,6 +82,25 @@ func TestIterateUtilityCoverage(t *testing.T) {
 
   literal := iterateLiteral("fixed")
   stringMeta := iterateAtomic("string")
+  requiredInput := shimast.NewNodeFactory(shimast.NodeFactoryHooks{}).NewIdentifier("input")
+  requiredEntries := []nativehelpers.IExpressionEntry{
+    {Input: requiredInput, Key: literal, Meta: stringMeta, Expression: requiredInput},
+  }
+  if !check_dynamic_properties_every_required(requiredEntries) {
+    t.Fatal("the authored required string property must be classified as required")
+  }
+  optionalMeta := iterateAtomic("string")
+  optionalMeta.Required = false
+  optionalMeta.Optional = true
+  optionalEntries := append(requiredEntries, nativehelpers.IExpressionEntry{
+    Input: requiredInput, Key: iterateLiteral("optional"), Meta: optionalMeta, Expression: requiredInput,
+  })
+  if check_dynamic_properties_every_required(optionalEntries) {
+    t.Fatal("an optional property must prevent the all-required classification")
+  }
+  if !check_dynamic_properties_every_required(nil) {
+    t.Fatal("the empty property population has no optional entry")
+  }
   constantDescription := "constant"
   constantSchemas := json_schema_constant(nativemetadata.MetadataConstant_create(nativemetadata.MetadataConstant{
     Type: "bigint",