typia 15.0.0 → 15.1.0

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

@@ -12,13 +12,22 @@ type classifyJoinerNamespace struct{}
 
 var ClassifyJoiner = classifyJoinerNamespace{}
 
+// ClassifyJoiner_ObjectProps is the argument record of ClassifyJoiner.Object,
+// which builds the object that `plain.classify` returns. ClassRef names the
+// runtime class value whose prototype receives the copied fields; when it is
+// nil, reconstruction falls back to a plain object.
+//
+// @evidence contracts/common.md#principled-implementation It is the argument record of ClassifyJoiner.Object, which builds the object that `plain.classify` returns; its 5 fields (Input, Entries, Object, ClassRef, Emit) 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 ClassifyJoiner_ObjectProps struct {
   Input   *shimast.Expression
   Entries []IExpressionEntry
   Object  *nativemetadata.MetadataObjectType
   // ClassRef is the value reference to the class (a bare identifier when in
   // lexical scope, or a resolved value import for a cross-module class). When
-  // nil the bare object name is used. Resolved by the classify programmer, which
+  // nil reconstruction uses a plain object. Resolved by the classify programmer, which
   // owns the importer and the call-site file.
   ClassRef *shimast.Node
   Emit     *shimprinter.EmitContext
@@ -37,11 +46,10 @@ var classifyJoiner_factory = shimast.NewNodeFactory(shimast.NodeFactoryHooks{})
 //	for (const [key, value] of Object.entries(input)) { ...dynamic keys... }
 //	return output;
 //
-// This is the universal fallback of the design's from -> new -> field-copy
-// precedence: Object.create never calls the constructor, so it reconstructs any
-// class regardless of its constructor signature. (The from / new strategies,
-// which need the construct-signature checker APIs and per-class arity metadata,
-// land in a later slice.)
+// PlainClassifyProgrammer selects supported from/new seed construction at the
+// root before reaching this joiner. This joiner owns field-copy reconstruction,
+// including nested class values. Object.create preserves the available class
+// prototype without calling its constructor or requiring a constructor seed.
 //
 // The class is referenced by props.ClassRef: a bare identifier when the class
 // is in lexical scope at the classify() call site (the common same-file case),

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

@@ -16,18 +16,40 @@ type cloneJoinerNamespace struct{}
 
 var CloneJoiner = cloneJoinerNamespace{}
 
+// CloneJoiner_ObjectProps is the argument record of CloneJoiner.Object, which
+// builds the cloned object.
+//
+// @evidence contracts/common.md#principled-implementation It is the argument record of CloneJoiner.Object, which builds the cloned object; its 3 fields (Input, Entries, Emit) 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 CloneJoiner_ObjectProps struct {
   Input   *shimast.Expression
   Entries []IExpressionEntry
   Emit    *shimprinter.EmitContext
 }
 
+// CloneJoiner_TupleProps is the argument record of CloneJoiner.Tuple, which
+// builds the cloned tuple from its element and rest expressions.
+//
+// @evidence contracts/common.md#principled-implementation It is the argument record of CloneJoiner.Tuple, which builds the cloned tuple from its element and rest expressions; its 3 fields (Elements, Rest, Emit) 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 CloneJoiner_TupleProps struct {
   Elements []*shimast.Expression
   Rest     *shimast.Expression
   Emit     *shimprinter.EmitContext
 }
 
+// CloneJoiner_OptionalElementProps is the argument record of
+// CloneJoiner.OptionalTupleElement, which clones an optional tuple element at
+// Index.
+//
+// @evidence contracts/common.md#principled-implementation It is the argument record of CloneJoiner.OptionalTupleElement, which clones an optional tuple element at Index; its 4 fields (Input, Value, Index, 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 CloneJoiner_OptionalElementProps struct {
   Input *shimast.Expression
   Value *shimast.Expression
@@ -35,6 +57,13 @@ type CloneJoiner_OptionalElementProps struct {
   Emit  *shimprinter.EmitContext
 }
 
+// CloneJoiner_ArrayProps is the argument record of CloneJoiner.Array, which
+// clones an array by mapping its elements with Arrow.
+//
+// @evidence contracts/common.md#principled-implementation It is the argument record of CloneJoiner.Array, which clones an array by mapping its elements with Arrow; its 3 fields (Input, Arrow, Emit) 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 CloneJoiner_ArrayProps struct {
   Input *shimast.Expression
   Arrow *shimast.Expression

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

@@ -9,7 +9,18 @@ import (
   nativefactories "github.com/samchon/typia/packages/typia/native/core/factories"
 )
 
+// FunctionProgrammer is the per-call collector of generated helper functions and
+// constants. It hands out collision-free names, records the unions and variables
+// a feature emplaces and declares them as constants in first-use order. Visit
+// tracking and the is-check prefix are per-call settings that recursive helpers
+// read late, so they are fields and not arguments.
+//
+// @evidence contracts/common.md#principled-implementation It is the per-call collector of generated helper functions and constants. It hands out collision-free names, records the unions and variables a feature emplaces and declares them as constants in first-use order. Visit tracking and the is-check prefix are per-call settings that recursive helpers read late, so they are fields and not arguments.
+// @evidence contracts/common.md#clear-and-simple-design One struct whose methods are short operations over its private tables.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts State is per instance and no package-level table is kept.
+// @evidence contracts/common.md#meaningful-documentation The doc states the collector role, and the field comments explain visit tracking, the emit context and the is-check prefix.
 type FunctionProgrammer struct {
+  // Method is the source callee label used in generated errors.
   Method         string
   local_         map[string]bool
   unions_        map[string]*functionProgrammer_union
@@ -46,6 +57,13 @@ type functionProgrammer_union struct {
 
 var functionProgrammer_factory = shimast.NewNodeFactory(shimast.NodeFactoryHooks{})
 
+// NewFunctionProgrammer returns an empty FunctionProgrammer labeled with the
+// typia method text and bound to an optional emit context.
+//
+// @evidence contracts/common.md#principled-implementation It returns an empty FunctionProgrammer labeled with the typia method text and bound to an optional emit context.
+// @evidence contracts/common.md#clear-and-simple-design One constructor that allocates the empty tables.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Every instance owns its tables.
+// @evidence contracts/common.md#meaningful-documentation The doc states what it builds.
 func NewFunctionProgrammer(method string, emit ...*shimprinter.EmitContext) *FunctionProgrammer {
   p := &FunctionProgrammer{
     Method:         method,
@@ -64,33 +82,78 @@ func NewFunctionProgrammer(method string, emit ...*shimprinter.EmitContext) *Fun
   return p
 }
 
+// UseLocal marks a helper function name as used and returns it, so declarations
+// that were never referenced can be skipped.
+//
+// @evidence contracts/common.md#principled-implementation It marks a helper function name as used and returns it, so declarations that were never referenced can be skipped.
+// @evidence contracts/common.md#clear-and-simple-design One small method on the per-call collector.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts State lives on the receiver and not in a package global.
+// @evidence contracts/common.md#meaningful-documentation The doc states what it builds.
 func (p *FunctionProgrammer) UseLocal(name string) string {
   p.local_[name] = true
   return name
 }
 
+// SetVisited turns per-invocation visit tracking on or off.
+//
+// @evidence contracts/common.md#principled-implementation It turns per-invocation visit tracking on or off.
+// @evidence contracts/common.md#clear-and-simple-design One small method on the per-call collector.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts State lives on the receiver and not in a package global.
+// @evidence contracts/common.md#meaningful-documentation The doc states what it builds.
 func (p *FunctionProgrammer) SetVisited(value bool) {
   p.visited_ = value
 }
 
+// Visited reports whether per-invocation visit tracking is on.
+//
+// @evidence contracts/common.md#principled-implementation It reports whether per-invocation visit tracking is on.
+// @evidence contracts/common.md#clear-and-simple-design One small method on the per-call collector.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts State lives on the receiver and not in a package global.
+// @evidence contracts/common.md#meaningful-documentation The doc states what it builds.
 func (p *FunctionProgrammer) Visited() bool {
   return p.visited_
 }
 
+// SetIsPrefix sets the is-check helper namespace that nested classify
+// discriminations emit under.
+//
+// @evidence contracts/common.md#principled-implementation It sets the is-check helper namespace that nested classify discriminations emit under.
+// @evidence contracts/common.md#clear-and-simple-design One small method on the per-call collector.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts State lives on the receiver and not in a package global.
+// @evidence contracts/common.md#meaningful-documentation The doc states what it builds.
 func (p *FunctionProgrammer) SetIsPrefix(prefix string) {
   p.isPrefix_ = prefix
 }
 
 // IsPrefix returns the is-check helper namespace classify's nested
 // discriminations emit under ("" => the default "_i"). See isPrefix_.
+//
+// @evidence contracts/common.md#principled-implementation The accessor exposes the is-check helper namespace that classify's nested discriminations emit under, where an empty string means the default `_i`, so recursive helpers read it from the per-function programmer instead of threading an argument.
+// @evidence contracts/common.md#clear-and-simple-design One accessor over a private field.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The value is per-programmer state and not a package global.
+// @evidence contracts/common.md#meaningful-documentation The doc states the empty-string default and points at the field comment.
 func (p *FunctionProgrammer) IsPrefix() string {
   return p.isPrefix_
 }
 
+// HasLocal reports whether a helper function name was marked as used.
+//
+// @evidence contracts/common.md#principled-implementation It reports whether a helper function name was marked as used.
+// @evidence contracts/common.md#clear-and-simple-design One small method on the per-call collector.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts State lives on the receiver and not in a package global.
+// @evidence contracts/common.md#meaningful-documentation The doc states what it builds.
 func (p *FunctionProgrammer) HasLocal(name string) bool {
   return p.local_[name]
 }
 
+// Declare returns the constant declarations of every emplaced variable in
+// emplacement order, followed by those of the emplaced unions unless
+// includeUnions is false.
+//
+// @evidence contracts/common.md#principled-implementation Ordered key slices preserve first emplacement order independently of Go map iteration. Variables precede unions, and the optional flag controls only union declarations.
+// @evidence contracts/common.md#clear-and-simple-design One small method on the per-call collector.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts State lives on the receiver and not in a package global.
+// @evidence contracts/common.md#meaningful-documentation The doc states what it builds.
 func (p *FunctionProgrammer) Declare(includeUnions ...bool) []*shimast.Node {
   output := []*shimast.Node{}
   for _, name := range p.variableOrder_ {
@@ -116,6 +179,13 @@ func (p *FunctionProgrammer) Declare(includeUnions ...bool) []*shimast.Node {
   return output
 }
 
+// DeclareUnions returns only the constant declarations of the emplaced unions in
+// emplacement order.
+//
+// @evidence contracts/common.md#principled-implementation The union-order slice indexes the same registered tuples and preserves first emplacement order without emitting variables.
+// @evidence contracts/common.md#clear-and-simple-design One small method on the per-call collector.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts State lives on the receiver and not in a package global.
+// @evidence contracts/common.md#meaningful-documentation The doc states what it builds.
 func (p *FunctionProgrammer) DeclareUnions() []*shimast.Node {
   output := []*shimast.Node{}
   for _, key := range p.unionOrder_ {
@@ -128,11 +198,25 @@ func (p *FunctionProgrammer) DeclareUnions() []*shimast.Node {
   return output
 }
 
+// Increment returns the next value of a per-call counter, which makes generated
+// parameter names unique.
+//
+// @evidence contracts/common.md#principled-implementation It returns the next value of a per-call counter, which makes generated parameter names unique.
+// @evidence contracts/common.md#clear-and-simple-design One small method on the per-call collector.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts State lives on the receiver and not in a package global.
+// @evidence contracts/common.md#meaningful-documentation The doc states what it builds.
 func (p *FunctionProgrammer) Increment() int {
   p.sequence_++
   return p.sequence_
 }
 
+// EmplaceUnion returns the name of the union function registered under prefix
+// and name, creating it with factory on first use.
+//
+// @evidence contracts/common.md#principled-implementation The prefix/name key identifies a union within this emission. Registering its reserved name before invoking factory allows recursive factories to refer back to the same name; the completed AST is declared afterward.
+// @evidence contracts/common.md#clear-and-simple-design One small method on the per-call collector.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts State lives on the receiver and not in a package global.
+// @evidence contracts/common.md#meaningful-documentation The doc states what it builds.
 func (p *FunctionProgrammer) EmplaceUnion(prefix string, name string, factory func() *shimast.Node) string {
   key := prefix + "::" + name
   if oldbie, ok := p.unions_[key]; ok {
@@ -146,6 +230,13 @@ func (p *FunctionProgrammer) EmplaceUnion(prefix string, name string, factory fu
   return accessor
 }
 
+// EmplaceVariable registers a variable under name and returns an identifier for
+// it.
+//
+// @evidence contracts/common.md#principled-implementation It registers a variable under name and returns an identifier for it.
+// @evidence contracts/common.md#clear-and-simple-design One small method on the per-call collector.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts State lives on the receiver and not in a package global.
+// @evidence contracts/common.md#meaningful-documentation The doc states what it builds.
 func (p *FunctionProgrammer) EmplaceVariable(name string, value *shimast.Expression) *shimast.Node {
   if _, ok := p.variables_[name]; !ok {
     if p.isNameReserved(name) {
@@ -159,6 +250,13 @@ func (p *FunctionProgrammer) EmplaceVariable(name string, value *shimast.Express
   return nativecontext.EmitFactoryOf(functionProgrammer_factory, p.emit_).NewIdentifier(name)
 }
 
+// EmplaceVariableByKey returns an identifier for the variable registered under
+// prefix and key, creating it with factory on first use.
+//
+// @evidence contracts/common.md#principled-implementation It returns an identifier for the variable registered under prefix and key, creating it with factory on first use.
+// @evidence contracts/common.md#clear-and-simple-design One small method on the per-call collector.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts State lives on the receiver and not in a package global.
+// @evidence contracts/common.md#meaningful-documentation The doc states what it builds.
 func (p *FunctionProgrammer) EmplaceVariableByKey(prefix string, key string, factory func(name string) *shimast.Expression) *shimast.Node {
   compound := prefix + "::" + key
   if name, ok := p.variableKeys_[compound]; ok {

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

@@ -2,12 +2,28 @@ package helpers
 
 import shimast "github.com/microsoft/typescript-go/shim/ast"
 
+// ICheckEntry is one check of a type: its expected description, an optional
+// guard on the value itself, and type-tag conditions. Conditions are
+// alternatives, each an and-list of conditions; the entry holds when Expression
+// holds and one alternative holds.
+//
+// @evidence contracts/common.md#principled-implementation It is one check of a type: its expected description, an optional guard on the value itself, and type-tag conditions; its 3 fields (Expected, Expression, Conditions) are named so that a producer and a consumer cannot transpose them.
+// @evidence contracts/common.md#clear-and-simple-design A 3-field record with no methods.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A data record: it derives, defaults and validates nothing.
+// @evidence contracts/common.md#meaningful-documentation The doc states what the record is and explains its non-obvious fields.
 type ICheckEntry struct {
   Expected   string
   Expression *shimast.Node
   Conditions [][]ICheckEntry_ICondition
 }
 
+// ICheckEntry_ICondition is one type-tag condition of a check entry, with its
+// expected description and condition expression.
+//
+// @evidence contracts/common.md#principled-implementation It is one type-tag condition of a check entry, with its expected description and condition expression; its 2 fields (Expected, Expression) 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 ICheckEntry_ICondition struct {
   Expected   string
   Expression *shimast.Node

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

@@ -5,6 +5,14 @@ import (
   nativemetadata "github.com/samchon/typia/packages/typia/native/core/schemas/metadata"
 )
 
+// IExpressionEntry is one property of an object, with the input accessor, the
+// key and value metadata, the decoded expression and whether the property is
+// exact-optional or strict-optional-undefined.
+//
+// @evidence contracts/common.md#principled-implementation It is one property of an object, with the input accessor, the key and value metadata, the decoded expression and whether the property is exact-optional or strict-optional-undefined; its 6 fields (Input, Key, Meta, Expression, OptionalProperty, StrictOptionalUndefined) are named so that a producer and a consumer cannot transpose them.
+// @evidence contracts/common.md#clear-and-simple-design A 6-field record with no methods.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A data record: it derives, defaults and validates nothing.
+// @evidence contracts/common.md#meaningful-documentation The doc states what the record is.
 type IExpressionEntry struct {
   Input                   *shimast.Node
   Key                     *nativemetadata.MetadataSchema

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

@@ -15,6 +15,11 @@ import (
 // transform must hand this the full call expression — Node.Text() panics on a
 // PropertyAccessExpression, which is why GetTextOfNode (the source-span text)
 // is used instead.
+//
+// @evidence contracts/common.md#principled-implementation The label embedded in TypeGuardError is the whole callee text, which is what the TypeScript transformer's `modulo.getText()` produced, so an identifier or string literal uses its text and any other expression is read from its source span because Node.Text() panics on a property access.
+// @evidence contracts/common.md#clear-and-simple-design One function with a nil guard and two branches.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The label is read from the call expression and not rebuilt from the kind of typia call.
+// @evidence contracts/common.md#meaningful-documentation The doc states the mirrored TypeScript behavior and why the source-span text is used.
 func ModuloMethodText(modulo *shimast.Node) string {
   if modulo == nil {
     return ""

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

@@ -12,6 +12,15 @@ type notationJoinerNamespace struct{}
 
 var NotationJoiner = notationJoinerNamespace{}
 
+// NotationJoiner_ObjectProps is the argument record of NotationJoiner.Object,
+// which builds the renamed object. Rename converts a static key, DynamicRename
+// and DynamicAssign build the key conversion and the assignment for a dynamic
+// key, and ThrowCollision builds the error for two keys that convert to one.
+//
+// @evidence contracts/common.md#principled-implementation It is the argument record of NotationJoiner.Object, which builds the renamed object; its 7 fields (Rename, DynamicRename, DynamicAssign, ThrowCollision, Input, Entries, Emit) are named so that a producer and a consumer cannot transpose them.
+// @evidence contracts/common.md#clear-and-simple-design A 7-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 NotationJoiner_ObjectProps struct {
   Rename         func(str string) string
   DynamicRename  func() *shimast.Node
@@ -22,12 +31,26 @@ type NotationJoiner_ObjectProps struct {
   Emit           *shimprinter.EmitContext
 }
 
+// NotationJoiner_TupleProps is the argument record of NotationJoiner.Tuple,
+// which builds the converted tuple from its element and rest expressions.
+//
+// @evidence contracts/common.md#principled-implementation It is the argument record of NotationJoiner.Tuple, which builds the converted tuple from its element and rest expressions; its 3 fields (Elements, Rest, Emit) 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 NotationJoiner_TupleProps struct {
   Elements []*shimast.Expression
   Rest     *shimast.Expression
   Emit     *shimprinter.EmitContext
 }
 
+// NotationJoiner_ArrayProps is the argument record of NotationJoiner.Array,
+// which converts an array by mapping its elements with Arrow.
+//
+// @evidence contracts/common.md#principled-implementation It is the argument record of NotationJoiner.Array, which converts an array by mapping its elements with Arrow; its 3 fields (Input, Arrow, Emit) 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 NotationJoiner_ArrayProps struct {
   Input *shimast.Expression
   Arrow *shimast.Expression

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

@@ -1,5 +1,13 @@
 package helpers
 
+// ProtobufWire is the wire type of a protobuf field. The values follow the
+// protobuf encoding specification: 0 varint (spelled VARIANT here), 1 64-bit, 2
+// length-delimited, 3 start group, 4 end group, 5 32-bit.
+//
+// @evidence contracts/common.md#principled-implementation It is the wire type of a protobuf field. The values follow the protobuf encoding specification: 0 varint (spelled VARIANT here), 1 64-bit, 2 length-delimited, 3 start group, 4 end group, 5 32-bit.
+// @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 ProtobufWire int
 
 const (

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

@@ -12,6 +12,13 @@ type pruneJoinerNamespace struct{}
 
 var PruneJoiner = pruneJoinerNamespace{}
 
+// PruneJoiner_ObjectProps is the argument record of PruneJoiner.Object, which
+// builds the pruning of an object.
+//
+// @evidence contracts/common.md#principled-implementation It is the argument record of PruneJoiner.Object, which builds the pruning of an object; its 4 fields (Input, Entries, Object, 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 PruneJoiner_ObjectProps struct {
   Input   *shimast.Expression
   Entries []IExpressionEntry
@@ -19,12 +26,26 @@ type PruneJoiner_ObjectProps struct {
   Emit    *shimprinter.EmitContext
 }
 
+// PruneJoiner_ArrayProps is the argument record of PruneJoiner.Array, which
+// prunes an array by visiting its elements with Arrow for side effects.
+//
+// @evidence contracts/common.md#principled-implementation Input is the array expression and Arrow is the in-place element pruner passed to forEach. Emit supplies AST creation context; this record does not model a mapped output array.
+// @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 PruneJoiner_ArrayProps struct {
   Input *shimast.Expression
   Arrow *shimast.Expression
   Emit  *shimprinter.EmitContext
 }
 
+// PruneJoiner_TupleProps is the argument record of PruneJoiner.Tuple, which
+// prunes the element and rest bodies of a tuple.
+//
+// @evidence contracts/common.md#principled-implementation It is the argument record of PruneJoiner.Tuple, which prunes the element and rest bodies of a tuple; its 3 fields (Elements, Rest, Emit) 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 PruneJoiner_TupleProps struct {
   Elements []*shimast.ConciseBody
   Rest     *shimast.ConciseBody

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

@@ -22,8 +22,24 @@ var RandomJoiner = randomJoinerNamespace{}
 // which escape it happened to own would make a depth bound unstatable.
 const RandomJoiner_RECURSION_CUTOFF = 5
 
+// RandomJoiner_Decoder is the callback that generates the random expression of
+// one metadata schema.
+//
+// @evidence contracts/common.md#principled-implementation It is the callback that generates the random expression of one metadata schema.
+// @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 RandomJoiner_Decoder func(metadata *nativemetadata.MetadataSchema) *shimast.Node
 
+// RandomJoiner_ArrayProps is the argument record of RandomJoiner.Array, which
+// builds a random array of the array type. Recursive marks an array type that
+// refers to itself, and Schema holds the constraint keywords that are written
+// into the call as a literal.
+//
+// @evidence contracts/common.md#principled-implementation It is the argument record of RandomJoiner.Array, which builds a random array of the array type; its 6 fields (Decode, Recursive, Expression, Array, Schema, Emit) are named so that a producer and a consumer cannot transpose them.
+// @evidence contracts/common.md#clear-and-simple-design A 6-field record with no methods.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A data record: it derives, defaults and validates nothing.
+// @evidence contracts/common.md#meaningful-documentation The doc states what the record is and explains its non-obvious fields.
 type RandomJoiner_ArrayProps struct {
   Decode     RandomJoiner_Decoder
   Recursive  bool
@@ -33,12 +49,27 @@ type RandomJoiner_ArrayProps struct {
   Emit       *shimprinter.EmitContext
 }
 
+// RandomJoiner_RecursiveArrayGuardProps is the argument record of the recursion
+// questions of RandomJoiner: whether a recursive array needs the depth guard,
+// and whether the array, object or tuple has a recursive owner path.
+//
+// @evidence contracts/common.md#principled-implementation It is the argument record of the recursion questions of RandomJoiner: whether a recursive array needs the depth guard, and whether the array, object or tuple has a recursive owner path; its 3 fields (Array, Object, Tuple) 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 RandomJoiner_RecursiveArrayGuardProps struct {
   Array  *nativemetadata.MetadataArrayType
   Object *nativemetadata.MetadataObjectType
   Tuple  *nativemetadata.MetadataTupleType
 }
 
+// RandomJoiner_TupleProps is the argument record of RandomJoiner.Tuple, which
+// builds a random tuple from the element schemas.
+//
+// @evidence contracts/common.md#principled-implementation It is the argument record of RandomJoiner.Tuple, which builds a random tuple from the element schemas; its 5 fields (Decode, Elements, ArrayExpression, HasDepth, Emit) 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 RandomJoiner_TupleProps struct {
   Decode          RandomJoiner_Decoder
   Elements        []*nativemetadata.MetadataSchema
@@ -51,13 +82,29 @@ type RandomJoiner_TupleProps struct {
   Emit     *shimprinter.EmitContext
 }
 
+// RandomJoiner_ObjectProps is the argument record of RandomJoiner.Object, which
+// builds a random object. OptionalProperty and StrictOptionalUndefined classify
+// a property schema, and Optional builds the condition for including an optional
+// property. A nil Optional callback includes the property.
+//
+// @evidence contracts/common.md#principled-implementation It is the argument record of RandomJoiner.Object, which builds a random object; its 6 fields (Decode, Object, OptionalProperty, StrictOptionalUndefined, Optional, Emit) are named so that a producer and a consumer cannot transpose them.
+// @evidence contracts/common.md#clear-and-simple-design A 6-field record with no methods.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A data record: it derives, defaults and validates nothing.
+// @evidence contracts/common.md#meaningful-documentation The doc states what the record is and explains its non-obvious fields.
 type RandomJoiner_ObjectProps struct {
-  Decode                  RandomJoiner_Decoder
-  Object                  *nativemetadata.MetadataObjectType
-  OptionalProperty        func(*nativemetadata.MetadataSchema) bool
+  Decode RandomJoiner_Decoder
+  Object *nativemetadata.MetadataObjectType
+
+  // OptionalProperty selects properties emitted through conditional spreads.
+  OptionalProperty func(*nativemetadata.MetadataSchema) bool
+
+  // StrictOptionalUndefined removes optionality from the included value schema.
   StrictOptionalUndefined func(*nativemetadata.MetadataSchema) bool
-  Optional                func() *shimast.Node
-  Emit                    *shimprinter.EmitContext
+
+  // Optional returns the inclusion condition, not an absence condition.
+  Optional func() *shimast.Node
+
+  Emit *shimprinter.EmitContext
 }
 
 type randomJoiner_DynamicPropertyProps struct {

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

@@ -15,11 +15,25 @@ type stringifyJoinerNamespace struct{}
 
 var StringifyJoiner = stringifyJoinerNamespace{}
 
+// StringifyJoiner_ObjectProps is the argument record of StringifyJoiner.Object,
+// which builds the JSON text of an object from its property entries.
+//
+// @evidence contracts/common.md#principled-implementation It is the argument record of StringifyJoiner.Object, which builds the JSON text of an object from its property entries; its 2 fields (Context, Entries) 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 StringifyJoiner_ObjectProps struct {
   Context nativecontext.ITypiaContext
   Entries []IExpressionEntry
 }
 
+// StringifyJoiner_ArrayProps is the argument record of StringifyJoiner.Array,
+// which builds the JSON text of an array from its element arrow.
+//
+// @evidence contracts/common.md#principled-implementation It is the argument record of StringifyJoiner.Array, which builds the JSON text of an array from its element arrow; its 4 fields (Context, Input, Arrow, 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 StringifyJoiner_ArrayProps struct {
   Context nativecontext.ITypiaContext
   Input   *shimast.Expression
@@ -27,6 +41,13 @@ type StringifyJoiner_ArrayProps struct {
   Emit    *shimprinter.EmitContext
 }
 
+// StringifyJoiner_TupleProps is the argument record of StringifyJoiner.Tuple,
+// which builds the JSON text of a tuple from its element and rest expressions.
+//
+// @evidence contracts/common.md#principled-implementation It is the argument record of StringifyJoiner.Tuple, which builds the JSON text of a tuple from its element and rest expressions; its 3 fields (Elements, Rest, Emit) 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 StringifyJoiner_TupleProps struct {
   Elements []*shimast.Expression
   Rest     *shimast.Expression
@@ -217,21 +238,26 @@ func stringifyJoiner_entry_omittable(entry IExpressionEntry) bool {
     stringifyJoiner_result_undefinable(entry.Meta)
 }
 
-// stringifyJoiner_result_undefinable reports whether a value that is present can
+// StringifyJoiner_ResultUndefinable reports whether a value that is present can
 // still serialize to nothing, which is the case an input test cannot see.
 //
 // `any` and `unknown` are serialized by JSON.stringify, which answers
 // `undefined` for a function, a symbol, and a `toJSON` returning nothing. A
 // declared `toJSON` is the same case without `any`: the member's text is its
 // return value, so a return type that admits `undefined` admits a member with no
-// text (#2253).
-// StringifyJoiner_ResultUndefinable exposes the same question to the element
-// positions the joiner does not build itself, so a tuple slot and an object
+// text (#2253). The joiner and the element positions it does not build itself,
+// such as a tuple slot, ask this one question, so a tuple slot and an object
 // member classify a value identically.
+//
+// @evidence contracts/common.md#principled-implementation The shared metadata classifier selects Any (the representation of any/unknown) or an escaped toJSON return admitting undefined. Their serialized result can disappear while input is present; direct function members are handled separately by the surrounding joiner.
+// @evidence contracts/common.md#clear-and-simple-design A one-line exported delegate over the package-private classifier.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Both positions call one classifier and the rule is not repeated.
+// @evidence contracts/common.md#meaningful-documentation The doc states the cases and cites #2253.
 func StringifyJoiner_ResultUndefinable(meta *nativemetadata.MetadataSchema) bool {
   return stringifyJoiner_result_undefinable(meta)
 }
 
+// stringifyJoiner_result_undefinable implements StringifyJoiner_ResultUndefinable.
 func stringifyJoiner_result_undefinable(meta *nativemetadata.MetadataSchema) bool {
   if meta == nil {
     return false
@@ -508,12 +534,5 @@ func stringifyJoiner_escape_template(text string) string {
 }
 
 func joinStrings(values []string, sep string) string {
-  if len(values) == 0 {
-    return ""
-  }
-  output := values[0]
-  for _, value := range values[1:] {
-    output += sep + value
-  }
-  return output
+  return strings.Join(values, sep)
 }