@ttsc/wasm 0.30.4 → 0.31.0

package/shim-vendor/shim/checker/shim.go

@@ -13,22 +13,294 @@ import (
 
   innerast "github.com/microsoft/typescript-go/internal/ast"
   innerchecker "github.com/microsoft/typescript-go/internal/checker"
+  innernodebuilder "github.com/microsoft/typescript-go/internal/nodebuilder"
   innerprinter "github.com/microsoft/typescript-go/internal/printer"
   _ "unsafe"
 )
 
+// Checker owns the type graph and semantic queries for one compiler program.
+// Access shared instances under the mutex returned by NewChecker.
+//
+// @evidence contracts/common.md#principled-implementation The exact alias preserves compiler-owned type identity and query state; graph objects must stay associated with the checker that produced them.
+// @evidence contracts/common.md#clear-and-simple-design One upstream checker is the semantic authority, avoiding an independently maintained type graph at the shim boundary.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The alias exposes supported compiler objects without replacing query methods or synthesizing fixture semantics.
+// @evidence contracts/common.md#meaningful-documentation Native prose states program ownership and caller synchronization instead of implying immutable or thread-safe checker state.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources A type declaration acquires and holds no runtime resource.
+// @evidenceExclude contracts/performance.md#efficient-algorithms A type declaration chooses no processing strategy.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work A type declaration computes nothing, so there is no work to share.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation This type declaration describes a data shape only; it opens no file, builds no path and branches on no platform.
 type Checker = innerchecker.Checker
+
+// IndexInfo describes a compiler index signature, including its key and value types.
+//
+// @evidence contracts/common.md#principled-implementation The alias retains the compiler's key/value type identities and readonly/declaration facts for index-signature semantics.
+// @evidence contracts/common.md#clear-and-simple-design One existing record carries index-signature facts without a lossy shim projection.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts No index key or value is fabricated from consumer conventions.
+// @evidence contracts/common.md#meaningful-documentation Native prose identifies the semantic role and key/value distinction.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources A type declaration acquires and holds no runtime resource.
+// @evidenceExclude contracts/performance.md#efficient-algorithms A type declaration chooses no processing strategy.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work A type declaration computes nothing, so there is no work to share.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation This type declaration describes a data shape only; it opens no file, builds no path and branches on no platform.
 type IndexInfo = innerchecker.IndexInfo
+
+// Signature represents one checked call or construct signature and its parameters.
+// Signature objects belong to their producing Checker.
+//
+// @evidence contracts/common.md#principled-implementation Exact upstream identity preserves instantiated parameters, return and type-parameter relationships needed by checker queries.
+// @evidence contracts/common.md#clear-and-simple-design The compiler's signature object is shared rather than copied into a second overload model.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The alias preserves semantic signatures rather than inferring them from printed syntax.
+// @evidence contracts/common.md#meaningful-documentation Native prose distinguishes call/construct signatures and states checker ownership.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources A type declaration acquires and holds no runtime resource.
+// @evidenceExclude contracts/performance.md#efficient-algorithms A type declaration chooses no processing strategy.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work A type declaration computes nothing, so there is no work to share.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation This type declaration describes a data shape only; it opens no file, builds no path and branches on no platform.
 type Signature = innerchecker.Signature
+
+// SignatureFlags is the compiler bitmask for signature properties such as rest parameters.
+//
+// @evidence contracts/common.md#principled-implementation The upstream bitmask preserves combinable signature distinctions expected by compiler predicates.
+// @evidence contracts/common.md#clear-and-simple-design One compiler flag representation serves signature queries without shim-specific translation.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Upstream flag meanings remain unchanged rather than hardcoded from selected examples.
+// @evidence contracts/common.md#meaningful-documentation Native prose identifies bitmask composition and a meaningful signature distinction.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources A type declaration acquires and holds no runtime resource.
+// @evidenceExclude contracts/performance.md#efficient-algorithms A type declaration chooses no processing strategy.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work A type declaration computes nothing, so there is no work to share.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation This type declaration describes a data shape only; it opens no file, builds no path and branches on no platform.
 type SignatureFlags = innerchecker.SignatureFlags
+
+// SignatureKind selects call signatures or construct signatures in checker queries.
+//
+// @evidence contracts/common.md#principled-implementation The enum preserves the two upstream signature populations rather than conflating invocation and construction.
+// @evidence contracts/common.md#clear-and-simple-design One discriminant selects the intended query population.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The enum expresses language invocation categories without consumer exceptions.
+// @evidence contracts/common.md#meaningful-documentation Native prose names both selectable signature categories.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources A type declaration acquires and holds no runtime resource.
+// @evidenceExclude contracts/performance.md#efficient-algorithms A type declaration chooses no processing strategy.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work A type declaration computes nothing, so there is no work to share.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation This type declaration describes a data shape only; it opens no file, builds no path and branches on no platform.
 type SignatureKind = innerchecker.SignatureKind
+
+// Type is a compiler semantic type, including instantiated and composite types.
+// It belongs to its producing Checker and is not a serialized AST node.
+//
+// @evidence contracts/common.md#principled-implementation Exact type identity retains compiler links among unions, intersections, references and instantiations; its discriminants govern which payload is valid.
+// @evidence contracts/common.md#clear-and-simple-design The alias keeps semantic representation with the compiler instead of building a parallel shim type system.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts No semantic type is reconstructed from consumer names or printed text.
+// @evidence contracts/common.md#meaningful-documentation Native prose states semantic versus syntax identity and producing-checker ownership.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources A type declaration acquires and holds no runtime resource.
+// @evidenceExclude contracts/performance.md#efficient-algorithms A type declaration chooses no processing strategy.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work A type declaration computes nothing, so there is no work to share.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation This type declaration describes a data shape only; it opens no file, builds no path and branches on no platform.
 type Type = innerchecker.Type
+
+// TypeAlias retains a semantic type alias's symbol and instantiated arguments.
+// Obtain it from Type.Alias; its read-only accessors accept a nil alias.
+//
+// @evidence contracts/common.md#principled-implementation Exact alias identity preserves compiler-owned symbol and type-argument provenance exposed by Type.Alias.
+// @evidence contracts/common.md#clear-and-simple-design One upstream record exposes existing semantic metadata without duplicating checker state.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Alias metadata comes from a checked Type rather than reconstructed declaration names.
+// @evidence contracts/common.md#meaningful-documentation Native prose identifies metadata, its producer and nil-safe accessor behavior.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources A type declaration acquires and holds no runtime resource.
+// @evidenceExclude contracts/performance.md#efficient-algorithms A type declaration chooses no processing strategy.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work A type declaration computes nothing, so there is no work to share.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation This type declaration describes a data shape only; it opens no file, builds no path and branches on no platform.
+type TypeAlias = innerchecker.TypeAlias
+
+// NodeBuilderImpl serializes checked types within an active builder context.
+// Obtain it only inside WithNodeBuilderContext and do not retain it afterward.
+//
+// @evidence contracts/common.md#principled-implementation Exact upstream identity preserves the checker, emit factory and active serialization context required by TypeAlias.ToTypeReferenceNode.
+// @evidence contracts/common.md#clear-and-simple-design A borrowed compiler implementation serves the existing metadata conversion without another semantic serializer.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The implementation comes from the upstream builder with a real entered context; a nil-context constructor is not presented as usable state.
+// @evidence contracts/common.md#meaningful-documentation Native prose states the callback producer and forbids retaining the context-bound value beyond its lifetime.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources A type declaration acquires and holds no runtime resource.
+// @evidenceExclude contracts/performance.md#efficient-algorithms A type declaration chooses no processing strategy.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work A type declaration computes nothing, so there is no work to share.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation This type declaration describes a data shape only; it opens no file, builds no path and branches on no platform.
+type NodeBuilderImpl = innerchecker.NodeBuilderImpl
+
+// WithNodeBuilderContext converts checked metadata in a fresh builder context.
+// Hold the producing checker's mutex, supply this emit round's context, and
+// use an enclosing declaration from that same program (or nil). The callback
+// must not retain the borrowed implementation or use it concurrently.
+// Checker, emit context and callback must be nonnil and valid for this round.
+//
+// The compiler's default serialization flags and tracker apply. Callback
+// errors are returned unchanged; compiler serialization errors return a nil
+// node. After context entry succeeds, restoration runs on success, callback
+// error and panic. Restoring the active context does not release the caller's
+// emit factory or invalidate a returned node; that lifetime remains its owner's.
+//
+// @evidence contracts/common.md#principled-implementation NewNodeBuilder and its real enter/exit operations establish the host, tracker and enclosing-file context before the generated private field accessor supplies the implementation.
+// @evidence contracts/common.md#clear-and-simple-design A scoped callback separates compiler-state acquisition from caller conversion while a fresh builder owns each nested invocation.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts No private layout is handwritten or patched, and no unusable raw getter is published as a producer; official generation derives the one required field access.
+// @evidence contracts/common.md#meaningful-documentation Native prose states synchronization, program and emit identity, default flags, borrowing limits, nil result and error/panic restoration.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Each call acquires a builder/implementation, context stack and semantic bookkeeping maps/slices. Deferred pop restores active context after callback failure or panic; exit restores it on normal completion. Borrowed implementation use ends at that boundary, while returned nodes and emit-factory allocations remain under caller ownership. This helper neither releases that factory's arenas nor bounds retained callback results.
+// @evidence contracts/performance.md#efficient-algorithms A fresh builder isolates nested callback contexts without cloning the semantic graph. Construction creates bookkeeping storage, context entry finds the enclosing source file through parent links, and the callback's conversion can traverse arbitrary supported type/AST graphs; total work is not constant merely because the callback is invoked once. The scoped wrapper avoids a separate serializer and leaves conversion algorithms upstream.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work This helper coordinates a borrowed context lifetime rather than completed or in-flight conversion sharing. Active callback state is isolated per invocation; semantic reuse belongs to the supplied checker, and no independent context-result cache/invalidation policy is installed.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Works on in-memory compiler nodes only; it accesses no path or filesystem.
+func WithNodeBuilderContext(ch *Checker, emitContext *innerprinter.EmitContext, enclosing *innerast.Node, use func(*NodeBuilderImpl) (*innerast.Node, error)) (*innerast.Node, error) {
+  builder := innerchecker.NewNodeBuilder(ch, emitContext)
+  nodeBuilderEnterContext(builder, enclosing, innernodebuilder.FlagsNone, innernodebuilder.InternalFlagsNone, nil)
+  exited := false
+  defer func() {
+    if !exited {
+      nodeBuilderPopContext(builder)
+    }
+  }()
+  node, err := use(nodeBuilder_impl(builder))
+  if err != nil {
+    return nil, err
+  }
+  node = nodeBuilderExitContext(builder, node)
+  exited = true
+  return node, nil
+}
+
+//go:linkname nodeBuilderEnterContext github.com/microsoft/typescript-go/internal/checker.(*NodeBuilder).enterContext
+func nodeBuilderEnterContext(*innerchecker.NodeBuilder, *innerast.Node, innernodebuilder.Flags, innernodebuilder.InternalFlags, innernodebuilder.SymbolTracker)
+
+//go:linkname nodeBuilderExitContext github.com/microsoft/typescript-go/internal/checker.(*NodeBuilder).exitContext
+func nodeBuilderExitContext(*innerchecker.NodeBuilder, *innerast.Node) *innerast.Node
+
+//go:linkname nodeBuilderPopContext github.com/microsoft/typescript-go/internal/checker.(*NodeBuilder).popContext
+func nodeBuilderPopContext(*innerchecker.NodeBuilder)
+
+// IsTypeUsableAsPropertyName reports whether t is a string or number literal
+// or a unique symbol type. t must be a nonnil compiler semantic type.
+//
+// @evidence contracts/common.md#principled-implementation The upstream semantic flag test preserves literal and unique-symbol property-name eligibility.
+// @evidence contracts/common.md#clear-and-simple-design One predicate qualifies inputs to GetPropertyNameFromType without another type classifier.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Eligibility follows actual type flags rather than printed type spelling.
+// @evidence contracts/common.md#meaningful-documentation Native prose names supported semantic categories and nonnil input.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources IsTypeUsableAsPropertyName acquires no handle, buffer or cache and retains nothing after it returns.
+// @evidenceExclude contracts/performance.md#efficient-algorithms The upstream literal/unique-symbol flag classifier owns eligibility; this shim forwards the type without choosing a second name-decoding or graph-search strategy.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The predicate reads existing type flags and coordinates no completed or in-flight producer, cache or invalidation across requests.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation IsTypeUsableAsPropertyName computes from its arguments only; it opens no file, builds no path and calls no platform or process API.
+func IsTypeUsableAsPropertyName(t *Type) bool {
+  return innerchecker.IsTypeUsableAsPropertyName(t)
+}
+
+// GetPropertyNameFromType returns a literal or unique-symbol property's
+// compiler name. t must satisfy IsTypeUsableAsPropertyName; other types panic.
+// The input must be a nonnil compiler type with its matching payload. String
+// and unique-symbol names use existing text; numeric literals use the upstream
+// JavaScript-number spelling, including its special values.
+//
+// @evidence contracts/common.md#principled-implementation Upstream literal-value and unique-symbol decoding preserves semantic property identity and numeric spelling.
+// @evidence contracts/common.md#clear-and-simple-design One decoder consumes the adjacent eligibility predicate's qualified semantic input.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Property identity is not guessed from source text or converted from unsupported types.
+// @evidence contracts/common.md#meaningful-documentation Native prose states the qualification requirement and unsupported-type panic.
+// @evidence contracts/performance.md#bound-retention-and-release-resources The caller receives existing name storage for string/unique-symbol types or newly formatted numeric text; retaining that string retains its bytes, not a shim-owned history. Upstream numeric formatting owns any temporary serialization bytes. The bridge opens no handle and keeps no independent name registry.
+// @evidenceExclude contracts/performance.md#efficient-algorithms Upstream property-name decoding owns type-flag dispatch and numeric spelling, including integer formatting or JSON number serialization. Existing strings are returned without traversal; numeric conversion/output cost belongs to that formatter rather than a second shim encoding strategy.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The decoder transfers the type's name or numeric spelling and coordinates no repeated semantic producer, cache or invalidation across requests.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation GetPropertyNameFromType computes from its arguments only; it opens no file, builds no path and calls no platform or process API.
+func GetPropertyNameFromType(t *Type) string {
+  return innerchecker.GetPropertyNameFromType(t)
+}
+
+// GetSetAccessorValueParameter returns the value parameter of a setter,
+// accounting for an explicit this parameter. accessor must be a setter node.
+// The upstream rule selects the second parameter only when there are exactly
+// two and the first is a this parameter; otherwise it selects the first, or nil
+// for an empty parameter list. It does not validate malformed setter arity.
+//
+// @evidence contracts/common.md#principled-implementation Delegation preserves upstream setter-parameter selection and explicit-this handling.
+// @evidence contracts/common.md#clear-and-simple-design One syntax query exposes the compiler's existing accessor convention.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Parameter selection follows actual setter syntax rather than a fixed consumer name.
+// @evidence contracts/common.md#meaningful-documentation Native prose identifies the setter premise and explicit-this distinction.
+// @evidence contracts/performance.md#bound-retention-and-release-resources The caller receives an existing parameter node, whose parent links can retain its source AST. The supplied AST owner controls that lifetime; this bridge allocates no parameter copy and keeps no additional node registry or handle.
+// @evidenceExclude contracts/performance.md#efficient-algorithms The upstream syntax helper owns direct list-length inspection and first/second parameter selection without scanning the list. This wrapper forwards the node and does not select a competing parameter-search or validation algorithm.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The helper projects existing syntax and coordinates no completed or in-flight producer, cache or invalidation across requests.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation GetSetAccessorValueParameter computes from its arguments only; it opens no file, builds no path and calls no platform or process API.
+func GetSetAccessorValueParameter(accessor *innerast.Node) *innerast.Node {
+  return innerchecker.GetSetAccessorValueParameter(accessor)
+}
+
+// TypeMapper is the compiler's type-parameter substitution mapping.
+//
+// @evidence contracts/common.md#principled-implementation The alias preserves the compiler's simple, array and composite substitution representations and their source/target type identity.
+// @evidence contracts/common.md#clear-and-simple-design Substitution uses the compiler's existing mapper model across construction and instantiation wrappers.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts No ad hoc name-based substitution or foreign instantiator replacement is introduced.
+// @evidence contracts/common.md#meaningful-documentation Native prose identifies semantic type-parameter substitution rather than a generic object map.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources A type declaration acquires and holds no runtime resource.
+// @evidenceExclude contracts/performance.md#efficient-algorithms A type declaration chooses no processing strategy.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work A type declaration computes nothing, so there is no work to share.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation This type declaration describes a data shape only; it opens no file, builds no path and branches on no platform.
 type TypeMapper = innerchecker.TypeMapper
+
+// TypeMapperKind reports the compiler mapper's Simple, Array, Merged or default
+// Unknown classification. It does not uniquely identify every concrete mapper
+// implementation; a Composite mapper inherits the default Unknown kind.
+//
+// @evidence contracts/common.md#principled-implementation The exact enum preserves upstream Kind reporting without treating default Unknown as a unique concrete payload or replacing polymorphic Map dispatch.
+// @evidence contracts/common.md#clear-and-simple-design The same kind representation connects mapper constructors and consumers without a shim discriminator.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Compiler mapper variants are retained without selecting consumer-specific behavior.
+// @evidence contracts/common.md#meaningful-documentation Native prose lists reported kinds and the nonunique Unknown boundary rather than promising a complete concrete-representation discriminator.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources A type declaration acquires and holds no runtime resource.
+// @evidenceExclude contracts/performance.md#efficient-algorithms A type declaration chooses no processing strategy.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work A type declaration computes nothing, so there is no work to share.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation This type declaration describes a data shape only; it opens no file, builds no path and branches on no platform.
 type TypeMapperKind = innerchecker.TypeMapperKind
+
+// TypeFlags is the compiler bitmask describing semantic type categories.
+//
+// @evidence contracts/common.md#principled-implementation The upstream bitmask preserves semantic category combinations used to interpret type payloads and choose checker operations.
+// @evidence contracts/common.md#clear-and-simple-design One native flag vocabulary connects the compiler and its plugin consumers.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Flags are not inferred from textual type spelling or rewritten for fixtures.
+// @evidence contracts/common.md#meaningful-documentation Native prose distinguishes semantic categories and bitmask representation.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources A type declaration acquires and holds no runtime resource.
+// @evidenceExclude contracts/performance.md#efficient-algorithms A type declaration chooses no processing strategy.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work A type declaration computes nothing, so there is no work to share.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation This type declaration describes a data shape only; it opens no file, builds no path and branches on no platform.
 type TypeFlags = innerchecker.TypeFlags
+
+// ObjectFlags is the compiler bitmask refining object types, including references and tuples.
+//
+// @evidence contracts/common.md#principled-implementation The alias preserves object-specific flags distinct from general TypeFlags, matching upstream reference and tuple payload interpretation.
+// @evidence contracts/common.md#clear-and-simple-design Object refinement remains in the compiler's established flag layer rather than a new shim taxonomy.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The representation retains real object-category flags without guessing from declaration names.
+// @evidence contracts/common.md#meaningful-documentation Native prose identifies object refinement and examples relevant to exposed tuple queries.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources A type declaration acquires and holds no runtime resource.
+// @evidenceExclude contracts/performance.md#efficient-algorithms A type declaration chooses no processing strategy.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work A type declaration computes nothing, so there is no work to share.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation This type declaration describes a data shape only; it opens no file, builds no path and branches on no platform.
 type ObjectFlags = innerchecker.ObjectFlags
+
+// ElementFlags is the compiler bitmask for required, optional, rest and variadic tuple elements.
+//
+// @evidence contracts/common.md#principled-implementation Preserving tuple element flags retains positional optionality and variadic distinctions needed by compiler tuple semantics.
+// @evidence contracts/common.md#clear-and-simple-design Existing compiler flags describe tuple elements without separate shim metadata.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Tuple categories are not reduced to a guessed fixed-length representation.
+// @evidence contracts/common.md#meaningful-documentation Native prose explicitly lists required, optional, rest and variadic meanings.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources A type declaration acquires and holds no runtime resource.
+// @evidenceExclude contracts/performance.md#efficient-algorithms A type declaration chooses no processing strategy.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work A type declaration computes nothing, so there is no work to share.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation This type declaration describes a data shape only; it opens no file, builds no path and branches on no platform.
 type ElementFlags = innerchecker.ElementFlags
+
+// Program is the semantic input interface required to construct an upstream Checker.
+//
+// @evidence contracts/common.md#principled-implementation The exact interface alias retains the source/options and resolution capabilities the checker expects from its program.
+// @evidence contracts/common.md#clear-and-simple-design Checker construction consumes the compiler's existing program boundary without a second adapter contract.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A caller implements the real compiler interface rather than replacing checker internals.
+// @evidence contracts/common.md#meaningful-documentation Native prose identifies the checker-construction role and interface nature.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources A type declaration acquires and holds no runtime resource.
+// @evidenceExclude contracts/performance.md#efficient-algorithms A type declaration chooses no processing strategy.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work A type declaration computes nothing, so there is no work to share.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation This type declaration describes a data shape only; it opens no file, builds no path and branches on no platform.
 type Program = innerchecker.Program
+
+// Tracer carries the compiler's optional semantic tracing state for a Checker.
+//
+// @evidence contracts/common.md#principled-implementation The exact alias preserves tracing state expected by upstream checker construction without interpreting diagnostic events independently.
+// @evidence contracts/common.md#clear-and-simple-design Optional tracing remains a compiler-owned concern passed through NewChecker.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The alias introduces no injected expected trace or global tracer replacement.
+// @evidence contracts/common.md#meaningful-documentation Native prose identifies optional tracing and its checker context.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources A type declaration acquires and holds no runtime resource.
+// @evidenceExclude contracts/performance.md#efficient-algorithms A type declaration chooses no processing strategy.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work A type declaration computes nothing, so there is no work to share.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation This type declaration describes a data shape only; it opens no file, builds no path and branches on no platform.
 type Tracer = innerchecker.Tracer
 
 //go:linkname checkerNewAnonymousType github.com/microsoft/typescript-go/internal/checker.(*Checker).newAnonymousType
@@ -55,17 +327,30 @@ func checkerArePropertiesAbstractOrInterface(
 ) bool
 
 // Checker_isPropertyAssignableTo asks the upstream assignability relater about
-// exactly one source/target property pair. The anonymous types retain the
+// one source/target property pair admitted by the upstream named value-member
+// filter. Reserved internal members and symbols without value meaning are not
+// supported property inputs. The anonymous types retain the
 // original property symbols, so propertyRelatedTo still enforces instantiated
 // generic types, overloads, optionality, and private/protected declaration
 // origins without an unrelated sibling member participating in the result.
+// The symbols must have the same name and belong to recv's type graph. A
+// shared checker requires caller-owned synchronization.
+//
+// @evidence contracts/common.md#principled-implementation Single-member anonymous types retain the original named value-property symbols so upstream structural assignability applies generic, optional and visibility semantics to that member pair; both symbols must originate in the supplied checker and pass its named-member filter.
+// @evidence contracts/common.md#clear-and-simple-design Two minimal anonymous type views isolate one relation without rewriting the upstream property relater or introducing sibling-dependent results.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Anonymous types use the compiler's constructor rather than monkey patching its relater; equal names include valid empty-string property symbols rather than treating an empty spelling as a missing-symbol sentinel.
+// @evidence contracts/common.md#meaningful-documentation Native paragraphs explain retained-symbol semantics, same-name/type-graph premises and caller synchronization rather than promising a syntax-only override check.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Each call acquires two one-entry symbol maps and anonymous type views with property slices; the supplied checker owns type allocation and relation state, which can outlive this boolean result. These views retain original symbols instead of copying their graphs; the caller controls the checker's lifetime, and this bridge imposes no independent historical-state bound.
+// @evidence contracts/performance.md#efficient-algorithms Two single-member views isolate the selected pair without cloning or scanning its containing types. Name equality and map keys depend on name bytes; view setup is bounded in member count, but delegated assignability can traverse property types, signatures and declaration origins and use checker relation state. The boolean wrapper does not make that semantic work constant-time.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Upstream checker relation caches own reuse of semantic comparisons. This bridge supplies fresh single-member views preserving symbol identity and does not coordinate a separate cross-request pair cache or its invalidation.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation This bridge constructs semantic views from the supplied checker graph and delegates its relation; it does not select a filesystem, executable or platform policy independently of that graph's producer.
 func Checker_isPropertyAssignableTo(
   recv *innerchecker.Checker,
   sourceProperty *innerast.Symbol,
   targetProperty *innerast.Symbol,
 ) bool {
   if recv == nil || sourceProperty == nil || targetProperty == nil ||
-    sourceProperty.Name == "" || sourceProperty.Name != targetProperty.Name {
+    sourceProperty.Name != targetProperty.Name {
     return false
   }
   source := checkerNewAnonymousType(
@@ -92,6 +377,22 @@ func Checker_isPropertyAssignableTo(
 // structural assignability permits more shapes than a class extends clause:
 // notably a concrete property/accessor cannot be replaced by a method, while a
 // base method may be replaced by a function-valued property.
+// The symbols must belong to the supplied checker and represent direct class
+// members. This predicate checks member kind, not type assignability.
+// Same target identity returns false because no distinct override pair exists.
+// The result does not perform the full class check: private-member handling,
+// inherited abstract implementation and class-field overwrite diagnostics are
+// outside this selected member-kind rule. A shared checker needs caller-owned
+// synchronization.
+//
+// @evidence contracts/common.md#principled-implementation Resolving target symbols and applying the pinned checkKindsOfPropertyMemberOverrides flags preserves direct-class property/accessor/method constraints; structural assignability is a separate required relation.
+// @evidence contracts/common.md#clear-and-simple-design One direct-pair predicate exposes member-kind legality independently from Checker_isPropertyAssignableTo, so callers can require both without importing internal flag policy.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Assignment and abstract/interface exceptions are upstream class-member semantics; the mapped-property exception is absent because a direct class base member cannot be mapped.
+// @evidence contracts/common.md#meaningful-documentation Native prose contrasts class inheritance with structural assignment and states direct-member, same-checker and kind-only limits.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The boolean predicate keeps no symbols, tasks or result collection after return. Instantiated-symbol target links and declaration/modifier metadata belong to the supplied checker and AST; this predicate does not independently acquire or release their graph lifetime.
+// @evidence contracts/performance.md#efficient-algorithms Direct target/flag comparisons isolate this pair without traversing sibling members or running the full class diagnostic pass. Upstream modifier selection may scan accessor declarations and their modifier syntax, and abstract/interface checks short-circuit over base declarations; their declaration and syntax populations, rather than only the wrapper's branch count, determine cost.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Upstream target links and AST modifier state supply the semantic metadata; this selected kind predicate owns neither a cross-request override producer nor a cache/invalidation policy for a class check.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation This predicate interprets the supplied checker/AST member metadata and introduces no independent filesystem, executable or platform policy.
 func Checker_isValidClassMemberOverridePair(
   recv *innerchecker.Checker,
   derivedProperty *innerast.Symbol,
@@ -131,9 +432,20 @@ func Checker_isValidClassMemberOverridePair(
   return false
 }
 
-// NewChecker creates a checker that owns its complete type graph for program.
-// The returned mutex is the upstream checker-pool synchronization primitive;
+// NewChecker binds the supplied program and initializes a checker with its
+// source files, global symbols and semantic caches. Later queries can resolve
+// more of its type graph lazily and produce diagnostics.
+// The returned mutex belongs to that newly created upstream checker;
 // callers that share the checker must serialize access through it.
+//
+// @evidence contracts/common.md#principled-implementation Delegating construction keeps the checker, its program-dependent type graph and returned synchronization primitive paired under the upstream program interface.
+// @evidence contracts/common.md#clear-and-simple-design One constructor returns the semantic object and its lock together without a duplicate graph or locking layer.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Construction uses the actual supplied program and optional tracer rather than a foreign checker replacement or synthetic semantic result.
+// @evidence contracts/common.md#meaningful-documentation Native prose states binding/initialization, lazy semantic work and caller serialization through the checker's own mutex without claiming an already complete graph or a pool-owned lock.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Construction transfers a checker and its mutex to the caller. The checker retains its program/source ASTs, symbol/type state, caches, diagnostics and optional tracer; later semantic work can grow that population. The caller/program owner controls their lifetime, and this constructor supplies no independent cache eviction or disposal bound.
+// @evidenceExclude contracts/performance.md#efficient-algorithms Upstream construction owns program binding, source-file indexing, global-symbol merging, augmentation and intrinsic/global type initialization. File, declaration and symbol populations drive that work; this shim delegates without selecting a second initialization algorithm or claiming constant cost.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Program binding and checker semantic caches own upstream reuse. This constructor does not coordinate a separate checker pool, shared producer or cross-program invalidation policy; callers determine whether the transferred checker is shared under its mutex.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Delegates to the upstream checker constructor; the shim handles no path or file.
 func NewChecker(program Program, tracer *Tracer) (*Checker, *sync.Mutex) {
   return innerchecker.NewChecker(program, tracer)
 }
@@ -145,6 +457,19 @@ func checkerGetRegularTypeOfLiteralType(recv *innerchecker.Checker, t *innerchec
 // literal type. TypeScript's checker uses this before comparing switch case
 // types because a source literal's fresh type and a union member's regular type
 // denote the same runtime value but have different pointers.
+// Unions regularize their constituent types through upstream mapping and cache
+// the result; other type categories pass through. Nonnil types must belong to
+// recv's checker graph when recv is supplied.
+// Nil checker or type leaves the supplied type unchanged.
+//
+// @evidence contracts/common.md#principled-implementation The pinned regular-literal helper canonicalizes fresh literal identity while preserving its semantic value, making pointer-based comparison use the same representation as union members.
+// @evidence contracts/common.md#clear-and-simple-design One guarded bridge exposes compiler canonicalization without duplicating literal interning or conversion rules.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The nil fallback preserves the input rather than constructing a desired literal; actual canonicalization remains with the producing compiler checker.
+// @evidence contracts/common.md#meaningful-documentation Native prose explains fresh-versus-regular pointer identity, runtime meaning and nil input preservation.
+// @evidence contracts/performance.md#bound-retention-and-release-resources The caller receives an existing type or checker-owned regular type and can retain its semantic graph. Upstream union mapping owns temporary constituent slices and the cached regularType result; this wrapper keeps no independent result, buffer or handle.
+// @evidenceExclude contracts/performance.md#efficient-algorithms The wrapper's nil guards select no canonicalization strategy. Upstream fresh-literal access is direct, but uncached unions map constituent/origin lists recursively and can reconstruct a reduced union; their traversal, allocation and reduction costs belong to that checker implementation.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Literal regularType references and union regularType caching own canonical reuse upstream. The forwarding wrapper adds no type cache or coordination of repeated canonicalization.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Type canonicalization uses the supplied checker graph; this wrapper introduces no path, host or platform policy.
 func Checker_getRegularTypeOfLiteralType(recv *innerchecker.Checker, t *innerchecker.Type) *innerchecker.Type {
   if recv == nil || t == nil {
     return t
@@ -158,17 +483,45 @@ func Checker_getRegularTypeOfLiteralType(recv *innerchecker.Checker, t *innerche
 // enumerating a literal union reports the values the way the compiler prints
 // them, including numeric formatting and string escaping it should not re-derive.
 //
-// It panics on a value it does not handle — notably the nil a computed enum
-// member carries — so a caller holding a `LiteralType.Value()` must reject nil
+// It panics on a value it does not handle, notably the nil a computed enum
+// member carries, so a caller holding a `LiteralType.Value()` must reject nil
 // before calling this.
+// Accepted runtime values are string, jsnum.Number, bool and jsnum.PseudoBigInt;
+// ordinary Go numeric values and other representations are not accepted.
+// This delegates the compiler's spelling, including nonfinite-number text,
+// rather than preserving the original source token or validating arbitrary data.
+//
+// @evidence contracts/common.md#principled-implementation Delegating supported literal values to the checker's renderer preserves TypeScript escaping and numeric spelling; unsupported runtime values remain outside its domain and panic.
+// @evidence contracts/common.md#clear-and-simple-design One renderer bridge centralizes compiler literal syntax without a separate shim serializer.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Values are formatted from actual compiler data, with no expected string table or special-case enum member names.
+// @evidence contracts/common.md#meaningful-documentation Native paragraphs state source-form output and the unsupported/nil-value panic boundary with explanatory context.
+// @evidence contracts/performance.md#bound-retention-and-release-resources The caller receives constant boolean/special-value text or formatted string/number/bigint storage. Upstream escaping and numeric serialization own temporary builders/bytes; the bridge retains no output registry or handle. Retaining the result retains its backing text, whose size depends on input and escaping rather than a fixed wrapper branch count.
+// @evidenceExclude contracts/performance.md#efficient-algorithms Upstream value dispatch, JavaScript-string escaping and number/bigint spelling own the algorithms. Escaping scans input bytes and emits expanded text; numeric conversion and bigint sign/suffix construction have their own output costs. This forwarding bridge selects no separate serializer or escaping strategy.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The renderer transfers a formatted value and coordinates no completed or in-flight producer, output cache or cross-request invalidation policy.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation ValueToString computes from its arguments only; it opens no file, builds no path and calls no platform or process API.
 func ValueToString(value any) string {
   return innerchecker.ValueToString(value)
 }
 
-// Checker_typeToStringFullyQualified formats a type with the same stable,
-// alias-aware flags TypeScript uses in diagnostics that name union members.
+// Checker_typeToStringFullyQualified requests unique-symbol, external-alias
+// and fully qualified presentation from the upstream type formatter.
 // Keeping the flag bundle inside the shim avoids leaking checker-internal enum
 // types through consumer code.
+// Nil checker or type returns empty text. A nonnil type must belong to recv.
+// The optional enclosing declaration must belong to its program. This remains
+// diagnostic presentation: upstream output can be truncated or return its
+// serialization-depth marker, and is not a unique type-identity certificate.
+// Lazy member resolution can update checker state or produce diagnostics;
+// callers sharing the checker must synchronize access.
+//
+// @evidence contracts/common.md#principled-implementation AllowUniqueESSymbolType, UseAliasDefinedOutsideCurrentScope and UseFullyQualifiedType preserve unique-symbol and externally defined alias naming at the supplied declaration scope; this is a presentation query over the producing checker.
+// @evidence contracts/common.md#clear-and-simple-design One named formatting policy owns its flags, leaving graph consumers independent of internal formatting enums.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Flags are compiler-defined formatting controls rather than patches to type identity or consumer-specific output strings.
+// @evidence contracts/common.md#meaningful-documentation Native prose explains alias-aware scope, flag ownership, nil output and same-checker requirements.
+// @evidence contracts/performance.md#bound-retention-and-release-resources The caller receives generated text storage; truncating the returned slice is not proof that its backing storage has that size. Upstream formatting acquires a text writer and builder arenas, defers arena release and verbosity restoration, and keeps its builder and semantic-resolution caches under checker ownership. This bridge keeps no separate output history or resource-release policy.
+// @evidenceExclude contracts/performance.md#efficient-algorithms Upstream lazy type/member resolution, node construction and printing own the semantic-graph, generated-node and text-byte costs, including serialization-depth and output-length policy. The shim selects a flag bundle rather than implementing or claiming constant-time type traversal.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The checker-owned builder and semantic caches coordinate upstream reuse. This wrapper introduces no independent formatted-text cache or shared producer whose validity it would establish across scopes or programs.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Type presentation follows the supplied program's semantic graph, module authority and compiler options; this bridge chooses no independent filesystem, executable or platform policy.
 func Checker_typeToStringFullyQualified(recv *innerchecker.Checker, t *innerchecker.Type, enclosingDeclaration *innerast.Node) string {
   if recv == nil || t == nil {
     return ""
@@ -186,6 +539,20 @@ func Checker_typeToStringFullyQualified(recv *innerchecker.Checker, t *innerchec
 // Checker_symbolToValueString formats a symbol as a value-position expression
 // at enclosingDeclaration. AllowAnyNodeKind lets the checker emit indexed
 // access for enum members whose names cannot use dot notation.
+// Nil checker or symbol returns empty text. Symbols must belong to recv.
+// An enclosing declaration must belong to its program. This is presentation,
+// not an accessibility or runtime-evaluation certificate. The formatter uses
+// upstream ignore-error node building; callers sharing the checker synchronize
+// access to its builder and semantic state.
+//
+// @evidence contracts/common.md#principled-implementation Value meaning and AllowAnyNodeKind delegate expression spelling to the checker's symbol formatter, allowing indexed access where an identifier-like name is unavailable.
+// @evidence contracts/common.md#clear-and-simple-design One wrapper owns value-position formatting policy without manual namespace concatenation or an AST printer fallback.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Indexed member spelling comes from the compiler's real symbol representation rather than a consumer-name escape table.
+// @evidence contracts/common.md#meaningful-documentation Native prose explains expression-position output, indexed access and nil/same-checker limits before the tags.
+// @evidence contracts/performance.md#bound-retention-and-release-resources The caller receives generated string storage. Upstream formatting acquires a pooled writer and builder arenas, defers writer return and arena release, and retains the checker-owned builder and semantic caches for their owner lifetime. Returning a writer to its pool is not a bound on retained output bytes or pooled storage; this bridge owns no separate formatting registry.
+// @evidenceExclude contracts/performance.md#efficient-algorithms Upstream chain lookup, recursive expression construction, identifier/name inspection and printing own the algorithm and its symbol-chain, declaration, generated-node and text-byte costs. The bridge selects value meaning and AllowAnyNodeKind but implements no second spelling or traversal algorithm.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Writer pooling, the checker-owned builder and semantic chain caches own reuse upstream. This bridge coordinates no additional formatting producer or cached string whose validity it would establish across programs.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Formatting follows the supplied program's symbol, alias and module authority; this bridge adds no independent filesystem, executable or platform selection.
 func Checker_symbolToValueString(recv *innerchecker.Checker, symbol *innerast.Symbol, enclosingDeclaration *innerast.Node) string {
   if recv == nil || symbol == nil {
     return ""
@@ -198,11 +565,26 @@ func Checker_symbolToValueString(recv *innerchecker.Checker, symbol *innerast.Sy
   )
 }
 
-// Checker_isSymbolAccessibleAsValue verifies that SymbolToStringEx can name a
-// symbol from enclosingDeclaration. Unlike GetAccessibleSymbolChain, the
+// Checker_isSymbolAccessibleAsValue reports upstream value-meaning accessibility
+// from enclosingDeclaration. Unlike GetAccessibleSymbolChain, the
 // checker also follows containing enum, class, and namespace symbols, so a
 // qualified member such as Domain.Mode.Done is accepted when its container is
 // visible.
+// The upstream query also permits its external-module accessibility route;
+// true does not independently certify the text returned by a formatting query.
+// Alias-visibility marking is not requested, but semantic accessibility and
+// declaration-visibility caches can still be populated. Inputs must belong to
+// the supplied checker/program; a shared checker requires synchronization.
+// Nil checker, symbol or enclosing declaration returns false.
+//
+// @evidence contracts/common.md#principled-implementation Upstream IsSymbolAccessible applies value-meaning accessibility in the supplied scope, including containing symbols, so the result answers semantic visibility rather than merely whether a name can be printed.
+// @evidence contracts/common.md#clear-and-simple-design One boolean query separates accessibility from value-string formatting, keeping visibility policy in the compiler.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The wrapper does not assume a qualified name is accessible because its text is known; actual checker accessibility must succeed.
+// @evidence contracts/common.md#meaningful-documentation Native prose explains containing-symbol visibility and nil refusal, distinguishing this operation from an accessible-chain lookup.
+// @evidence contracts/performance.md#bound-retention-and-release-resources The boolean projection does not retain its temporary accessibility result, but delegated lookup acquires visited-table maps and container/chain storage and can retain accessible-chain and declaration-visibility state in the supplied checker/resolver. Their owner controls the program lifetime; this bridge neither clears those caches nor promises a separate historical-state bound.
+// @evidenceExclude contracts/performance.md#efficient-algorithms Scope-table lookup, recursive containing-symbol accessibility, declaration visibility and failure-name formatting are upstream checker algorithms. Their costs depend on scope depth, symbol tables, containers, declarations and generated text; the bridge only chooses value meaning and projects the result rather than owning those algorithms.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Upstream accessible-chain cache keys include the symbol, relevant scope, meaning and external-alias policy, and resolver state owns declaration visibility. This bridge does not coordinate an independent visibility producer/cache or its invalidation.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation The query uses the supplied program's symbols, scopes and module authority; it does not independently choose filesystem, process or platform policy.
 func Checker_isSymbolAccessibleAsValue(recv *innerchecker.Checker, symbol *innerast.Symbol, enclosingDeclaration *innerast.Node) bool {
   if recv == nil || symbol == nil || enclosingDeclaration == nil {
     return false
@@ -262,50 +644,149 @@ const (
   ElementFlagsVariadic = innerchecker.ElementFlagsVariadic
 )
 
-// IsTupleType reports whether t is a fixed-length tuple type.
+// IsTupleType reports whether t is a tuple reference, including rest and
+// variadic tuples. t must be nonnil.
+//
+// @evidence contracts/common.md#principled-implementation The upstream predicate checks reference and target tuple object flags, covering variadic tuples as well as fixed-length ones under the nonnil type premise.
+// @evidence contracts/common.md#clear-and-simple-design One predicate delegates representation classification without inferring tuples from printed syntax or element count.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts No fixed-size shortcut substitutes for the compiler's tuple identity.
+// @evidence contracts/common.md#meaningful-documentation Native prose states rest/variadic inclusion and the nonnil type requirement.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources IsTupleType acquires no handle, buffer or cache and retains nothing after it returns.
+// @evidenceExclude contracts/performance.md#efficient-algorithms Upstream tuple classification owns reference/target tuple-flag inspection; this forwarding shim chooses no separate element traversal or tuple-recognition strategy.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The predicate inspects an existing type representation and coordinates no completed or in-flight producer, cache or invalidation across requests.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation IsTupleType computes from its arguments only; it opens no file, builds no path and calls no platform or process API.
 func IsTupleType(t *innerchecker.Type) bool {
   return innerchecker.IsTupleType(t)
 }
 
-// Checker_getIndexInfosOfType returns the index signatures (string/number/symbol
-// index infos) declared on t.
+// Checker_getIndexInfosOfType returns semantic index information after reduced
+// apparent-type normalization. Results can include inherited or instantiated
+// index signatures and combined union/intersection information, rather than
+// only signatures directly declared on t.
+// recv and t must be nonnil and belong to the same checker graph.
+//
+// @evidence contracts/common.md#principled-implementation Upstream index-info lookup resolves semantic index signatures of the supplied checker type, preserving key/value identities instead of parsing declaration spelling.
+// @evidence contracts/common.md#clear-and-simple-design One direct semantic query exposes existing index information without a separate index-signature walker.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Index signatures come from the actual type graph rather than guessed numeric or string property names.
+// @evidence contracts/common.md#meaningful-documentation Native prose distinguishes normalized semantic index information from direct declarations and specifies same-checker nonnil premises.
+// @evidence contracts/performance.md#bound-retention-and-release-resources The returned index-info slice is structured-type state owned by the checker, and its entries reference semantic key/value types. Upstream resolution owns any synthesized members; the caller controls additional retention through the borrowed result, while the wrapper stores no separate cache or handle.
+// @evidenceExclude contracts/performance.md#efficient-algorithms The wrapper selects no resolution strategy. Upstream reduction, apparent-type normalization and structured-member resolution can instantiate signatures, traverse base types or combine union/intersection constituents and index lists; cost follows those graphs and lists rather than fixed wrapper steps.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work ObjectFlagsMembersResolved and structured-type member state coordinate reuse in the producing checker. This forwarding wrapper owns no additional index-query cache or repeated-work policy.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Type normalization and member resolution remain with the supplied checker/program; this wrapper adds no path, host or platform policy.
 func Checker_getIndexInfosOfType(recv *innerchecker.Checker, t *innerchecker.Type) []*innerchecker.IndexInfo {
   return recv.GetIndexInfosOfType(t)
 }
 
 // Checker_getPropertiesOfType returns the named property symbols of t. For
-// union and intersection types this is the set of properties visible on every
-// member.
+// unions, properties must be available across constituents; intersections
+// combine constituent properties under checker semantics. recv and t must be
+// nonnil and belong to the same checker graph.
+// Reduced apparent-type normalization and member resolution happen upstream;
+// the returned slice shares the checker's resolved property state.
+//
+// @evidence contracts/common.md#principled-implementation Upstream property lookup applies union common-property and intersection combined-property semantics, retaining compiler-generated symbol identities and instantiated property types.
+// @evidence contracts/common.md#clear-and-simple-design One checker query owns composite-type property formation instead of an independent shim intersection or union merger.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Composite properties are not reduced to a common-member approximation for every type category.
+// @evidence contracts/common.md#meaningful-documentation Native prose distinguishes union from intersection behavior and states graph/nonnil premises.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Resolved object/composite property slices and synthesized symbols belong to the producing checker graph. Upstream composite collection also owns its temporary checked-name set; the caller can retain that graph through the returned slice, while the wrapper stores no independent cache or handle.
+// @evidenceExclude contracts/performance.md#efficient-algorithms The wrapper selects no normalization or collection strategy. Upstream object resolution can traverse/instantiate members and bases; composite collection visits constituent properties, hashes names and resolves each candidate under union/intersection semantics. Their graph/list/name costs belong to that implementation rather than fixed wrapper steps.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Structured member state and composite resolvedProperties own reuse within the supplied checker. This forwarding wrapper coordinates no additional property cache or repeated-query policy.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Property normalization and resolution use the supplied checker/program; the wrapper introduces no path, host or platform policy.
 func Checker_getPropertiesOfType(recv *innerchecker.Checker, t *innerchecker.Type) []*innerast.Symbol {
   return recv.GetPropertiesOfType(t)
 }
 
 // Checker_getApparentProperties returns the properties visible on t after
 // resolving primitive wrapper types (e.g. string to String).
+// Callable or constructable types also receive applicable global function
+// properties when the type does not already declare those names.
+// recv and t must be nonnil and belong to the same checker graph.
+//
+// @evidence contracts/common.md#principled-implementation Delegating apparent-property lookup preserves the compiler's apparent-type normalization before collecting visible semantic properties.
+// @evidence contracts/common.md#clear-and-simple-design Apparent lookup remains distinct from direct properties so callers select the actual semantic question without a duplicated normalization layer.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Primitive properties come from compiler apparent types, not a hardcoded wrapper-member inventory.
+// @evidence contracts/common.md#meaningful-documentation Native prose gives the primitive-wrapper example and nonnil same-graph conditions.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Upstream augmentation creates a temporary name table and returns a symbol slice proportional to collected properties. The caller owns the returned slice lifetime and references into checker-owned semantic state; the wrapper stores no independent result or handle.
+// @evidenceExclude contracts/performance.md#efficient-algorithms The wrapper selects no collection strategy. Upstream apparent-type/property/signature resolution, name hashing and function-member augmentation precede named-member filtering and sorting; their property counts and comparison costs belong to that checker implementation rather than fixed local steps.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Semantic type/property reuse belongs to the supplied checker; the upstream augmentation builds its own per-query table and slice. The forwarding wrapper owns no additional cache or coordination of repeated queries.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Apparent-type and global-member interpretation use the supplied checker graph; this wrapper introduces no path, host or platform policy.
 func Checker_getApparentProperties(recv *innerchecker.Checker, t *innerchecker.Type) []*innerast.Symbol {
   return recv.GetApparentProperties(t)
 }
 
-// Checker_getTypeArguments returns the type arguments of a generic reference
-// type, or nil when t is not a reference.
+// Checker_getTypeArguments returns resolved type arguments of a generic
+// reference type. t must be a nonnil type reference in recv's checker graph;
+// other type representations do not satisfy the upstream accessor's domain.
+// Resolution can fill or instantiate arguments and populate reference state;
+// circular resolution can return error types and report diagnostics.
+//
+// @evidence contracts/common.md#principled-implementation The upstream reference query supplies resolved type arguments associated with the actual compiler reference rather than syntactic arguments that may omit inferred instantiation.
+// @evidence contracts/common.md#clear-and-simple-design One direct reference query exposes instantiated arguments without another generic type model.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Type argument identity is retained instead of guessed from type names or printed angle brackets.
+// @evidence contracts/common.md#meaningful-documentation Native prose identifies resolved generic-reference scope and the nonnil type-reference/producing-checker domain instead of promising non-reference nil.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Resolved argument slices and their semantic types belong to checker/reference state; circular resolution can also return a parameter-count-sized error-type slice. The caller controls additional retention through the result, while this wrapper keeps no separate cache or handle.
+// @evidenceExclude contracts/performance.md#efficient-algorithms This wrapper selects no argument-resolution strategy. Upstream uncached work resolves argument nodes, examines/fills parameter defaults and instantiates mapped types; tuple and cycle-result construction also depend on list lengths. Those semantic graph/list costs belong to the checker rather than fixed wrapper steps.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The upstream reference's populated resolvedTypeArguments and type-resolution state coordinate reuse and cycle handling. The forwarding wrapper adds no argument cache or repeated-query coordination.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Type-reference argument interpretation uses the supplied checker/program; this wrapper introduces no path, host or platform policy.
 func Checker_getTypeArguments(recv *innerchecker.Checker, t *innerchecker.Type) []*innerchecker.Type {
   return recv.GetTypeArguments(t)
 }
 
-// Checker_getTypeOfSymbol returns the declared type of symbol, resolving
-// aliases and following late-bound types.
+// Checker_getTypeOfSymbol resolves symbol's value type under the compiler's
+// symbol-category rules, including deferred/instantiated/mapped types and aliases.
+// For a class this is its constructor/static type; use
+// Checker_getDeclaredTypeOfSymbol for the instance type. Unsupported value
+// categories or recursive alias typing can return the checker's error type;
+// semantic resolution can populate symbol type state and diagnostics.
+// recv and symbol must be nonnil; the symbol must belong to recv.
+//
+// @evidence contracts/common.md#principled-implementation Upstream symbol typing dispatches on compiler symbol/check flags, including instantiated/mapped/deferred types and alias value targets, preserving producing-checker type identity and error-type fallbacks.
+// @evidence contracts/common.md#clear-and-simple-design One symbol-to-type query leaves binding and resolution with the existing checker.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts No type is synthesized from consumer naming or a cached textual annotation.
+// @evidence contracts/common.md#meaningful-documentation Native prose states symbol-category/alias handling, class value versus instance typing, state/error effects and nonnil checker ownership.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Resolved symbol types, constructed class/value types and diagnostics remain checker-owned. The caller can retain the semantic graph through the returned type; this forwarding wrapper stores no independent result, buffer or handle.
+// @evidenceExclude contracts/performance.md#efficient-algorithms The wrapper selects no typing strategy. Upstream flag dispatch delegates deferred, instantiated, mapped, accessor, variable and value-category typing or alias resolution; class/base and alias/instantiation paths can traverse semantic graphs rather than fixed local steps.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The producing checker owns symbol-type state, including valueSymbolLinks resolvedType caching for instantiated, class/value and alias paths. This wrapper adds no symbol cache or repeated-query coordination.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Symbol typing and related resolution use the supplied checker/program; this wrapper introduces no path, host or platform policy.
 func Checker_getTypeOfSymbol(recv *innerchecker.Checker, symbol *innerast.Symbol) *innerchecker.Type {
   return recv.GetTypeOfSymbol(symbol)
 }
 
-// Checker_getTypeOfSymbolAtLocation returns the contextual type of symbol as
-// observed at the given AST node (useful for narrowed types in control flow).
+// Checker_getTypeOfSymbolAtLocation returns upstream location-sensitive symbol
+// typing after exported-value-symbol normalization. Eligible identifier/private
+// references use the checked expression type when they resolve to that symbol;
+// setter declaration names and write-access contexts can select writable types.
+// Other locations, including nil, fall back to non-missing symbol typing.
+// Checker and symbol must be nonnil; symbol and any supplied node must belong
+// to the same checked program. An arbitrary node does not promise narrowing.
+//
+// @evidence contracts/common.md#principled-implementation Upstream location typing distinguishes a matching checked reference, setter/write contexts and non-missing symbol fallback after exported-symbol normalization, instead of inventing narrowing for arbitrary nodes.
+// @evidence contracts/common.md#clear-and-simple-design This wrapper makes location dependence explicit instead of conflating location-sensitive, contextual and declared-type queries.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Context comes from a real checked node, not a fixture offset or textual narrowing heuristic.
+// @evidence contracts/common.md#meaningful-documentation Native prose states reference-match, write/setter and non-missing fallback branches, same-program inputs and nil-location limits.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Node/symbol type state, checked-expression results and semantic diagnostics remain checker-owned; the caller can retain that graph through the returned type. This forwarding wrapper keeps no independent result, buffer or handle.
+// @evidenceExclude contracts/performance.md#efficient-algorithms The wrapper selects no location-typing strategy. Upstream syntax eligibility, expression/property-write checking and symbol/accessor typing own AST/control-flow/type graph work before reference matching or fallback, rather than fixed local steps.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The producing checker owns node/symbol links and checked semantic type state. This wrapper adds no location cache or coordination of repeated flow-sensitive queries.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Location-sensitive typing uses the supplied checked AST and checker/program; this wrapper introduces no path, host or platform policy.
 func Checker_getTypeOfSymbolAtLocation(recv *innerchecker.Checker, symbol *innerast.Symbol, node *innerast.Node) *innerchecker.Type {
   return recv.GetTypeOfSymbolAtLocation(symbol, node)
 }
 
 // Checker_getTypeOfPropertyOfType looks up the type of the named property on t
 // and returns nil when no such property exists.
+// recv and t must be nonnil and belong to the same checker graph.
+// It uses upstream default property lookup after reduced apparent-type
+// normalization, including inherited/composite and global-member rules, then
+// resolves the selected symbol's type in that checker.
+//
+// @evidence contracts/common.md#principled-implementation Semantic property lookup uses the compiler's instantiated type and member name, returning the property's checked type only when that member exists.
+// @evidence contracts/common.md#clear-and-simple-design One type/name lookup delegates property resolution without separately resolving symbols and reimplementing property typing.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Missing members remain absent rather than receiving a fabricated fallback type.
+// @evidence contracts/common.md#meaningful-documentation Native prose states missing-property nil and same-checker nonnil requirements.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Property/member/symbol type state remains owned by the producing checker; a returned type can retain its semantic graph through the caller's reference. The forwarding wrapper stores no independent result, buffer or handle.
+// @evidenceExclude contracts/performance.md#efficient-algorithms The wrapper selects no lookup or typing strategy. Upstream reduced-apparent normalization, structured/composite property lookup and symbol-category typing own graph traversal, instantiation and name processing costs rather than fixed local steps.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The supplied checker owns resolved member/composite property and symbol-type state, including instantiated-symbol result caching. This wrapper adds no name/type cache or repeated-query coordination.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Property and symbol typing use the supplied checker/program; this wrapper introduces no path, host or platform policy.
 func Checker_getTypeOfPropertyOfType(recv *innerchecker.Checker, t *innerchecker.Type, name string) *innerchecker.Type {
   return recv.GetTypeOfPropertyOfType(t, name)
 }
@@ -316,17 +797,21 @@ func checkerGetPropertyNameForKnownSymbolName(recv *innerchecker.Checker, symbol
 // Checker_getPropertyNameForKnownSymbolName returns the late-bound property
 // name the checker uses for a member keyed by the global well-known symbol
 // `Symbol.<symbolName>` (e.g. "asyncIterator", "asyncDispose", "iterator").
-// It resolves the unique-symbol type of that property on the global
-// `SymbolConstructor` — including lib-provided and `declare global` augmented
-// members — so `(*Checker).GetPropertyOfType(t, name)` with the returned name
-// finds exactly the members declared as `[Symbol.<symbolName>]`. This is the
-// same resolution the checker itself performs when it validates `for await`
-// iterability, which is why a lint rule that mirrors typescript-eslint's
-// well-known-symbol protocol checks must go through it instead of matching
-// property-name text. When the global `Symbol` constructor lacks the member,
-// the checker's internal fallback name (a `\xFE@`-prefixed string no
-// source-declared property can late-bind to) is returned, so lookups simply
-// find nothing. Returns "" if recv is nil.
+// It queries the global Symbol value's member type, including library and
+// global augmentation. A unique-symbol type supplies its semantic name;
+// upstream also accepts string/number literal member types and returns their
+// property names. Missing or unusable member types return the compiler's
+// internal-prefix fallback key, without proving that a protocol is supported.
+// Returns "" if recv is nil.
+//
+// @evidence contracts/common.md#principled-implementation Upstream global Symbol member typing selects a unique-symbol semantic name or a usable string/number literal name; missing or unusable types preserve the compiler fallback instead of claiming a supported protocol.
+// @evidence contracts/common.md#clear-and-simple-design One bridge owns well-known-symbol key resolution rather than duplicating a textual Symbol-name matcher in lint consumers.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Missing or unusable global members preserve upstream's internal fallback key rather than using a similarly spelled public property as an invented protocol identity.
+// @evidence contracts/common.md#meaningful-documentation Native prose states all usable type categories, global augmentation, fallback limits and nil receiver behavior.
+// @evidence contracts/performance.md#bound-retention-and-release-resources The returned name is a semantic/literal string or a newly constructed fallback proportional to symbolName bytes; the caller owns its retention. Global symbol and type state remain checker-owned, and the wrapper retains no separate result or handle.
+// @evidenceExclude contracts/performance.md#efficient-algorithms The wrapper only guards a nil checker. Upstream global/member/type resolution owns semantic graph and name-lookup costs; literal number formatting or fallback string construction adds representation work. This forwarding wrapper chooses none of those algorithms.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The producing checker memoizes global Symbol lookup and owns semantic type/member reuse. This wrapper has no independent key cache or coordination policy, and fallback construction remains per query upstream.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Global member typing uses the supplied checker/program; this wrapper introduces no path, host or platform policy.
 func Checker_getPropertyNameForKnownSymbolName(recv *innerchecker.Checker, symbolName string) string {
   if recv == nil {
     return ""
@@ -348,8 +833,20 @@ func checkerGetIterationTypeOfIterable(
 // TypeScript-Go traversal used for synchronous iteration, including inherited
 // and structural iterables, instantiated iterator returns, intersections, and
 // primitive strings. A nil result means the checker could not derive a valid
-// synchronous iteration type. Diagnostics are intentionally disabled because
-// callers use this as a type query after normal TypeScript checking.
+// synchronous iteration type, including the top-level any input case; it is
+// not a proof that a runtime value is non-iterable. Nonnil input must belong to
+// recv's checker graph. The nil error node suppresses this helper's iteration
+// error reporting; underlying semantic queries can still resolve/cache types.
+// Nil recv or inputType returns nil.
+//
+// @evidence contracts/common.md#principled-implementation The pinned helper's Element use and Yield kind obtain synchronous iterator values through actual inherited/instantiated protocol types. Its nil error node suppresses iteration error reporting without promising that underlying semantic resolution is effect-free.
+// @evidence contracts/common.md#clear-and-simple-design One guarded bridge exposes the compiler's iterator semantics without assembling Symbol.iterator and next signatures independently.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Iterator values are not guessed from property spelling or selected container names; upstream semantics cover structural iterables and strings.
+// @evidence contracts/common.md#meaningful-documentation Native prose states traversal categories, the any/nil-result limit, same-checker inputs and the specific iteration-error suppression boundary.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Upstream iteration/type caches belong to the producing checker; union/protocol/signature queries can also allocate temporary result lists. The caller can retain the semantic graph through a returned yield type, while this wrapper keeps no independent result or handle.
+// @evidenceExclude contracts/performance.md#efficient-algorithms The wrapper guards nil inputs and selects the pinned synchronous Element/Yield operation. Upstream reduction, union traversal, fast-reference recognition, iterator-property/signature filtering and return/iterator-result resolution own the graph/list costs rather than a fixed number of local steps.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The upstream iterationTypesCache keys results by reduced type identity and iteration-use flags, including no-iteration outcomes for this nil-error-node query. The wrapper owns no additional protocol cache or repeated-query coordination.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Iterator semantics and related global/member typing use the supplied checker/program; this wrapper adds no path, host or platform policy.
 func Checker_getSynchronousIterationYieldType(recv *innerchecker.Checker, inputType *innerchecker.Type) *innerchecker.Type {
   if recv == nil || inputType == nil {
     return nil
@@ -366,8 +863,19 @@ func Checker_getSynchronousIterationYieldType(recv *innerchecker.Checker, inputT
 //go:linkname checkerGetAliasSymbolForTypeNode github.com/microsoft/typescript-go/internal/checker.(*Checker).getAliasSymbolForTypeNode
 func checkerGetAliasSymbolForTypeNode(recv *innerchecker.Checker, node *innerast.Node) *innerast.Symbol
 
-// Checker_getAliasSymbolForTypeNode returns the alias symbol that a type node
-// refers to when the node is itself a type alias reference (e.g. `type Foo = ...`).
+// Checker_getAliasSymbolForTypeNode returns the symbol of a type alias
+// declaration enclosing node through parenthesized or readonly type wrappers.
+// It returns nil when that enclosing declaration is not a type alias; this
+// does not resolve the target of a referenced alias. Inputs must be nonnil.
+//
+// @evidence contracts/common.md#principled-implementation The pinned helper walks node parents through parenthesized and readonly type operators, then obtains the enclosing type-alias declaration's symbol rather than resolving a type-reference target.
+// @evidence contracts/common.md#clear-and-simple-design One specifically documented enclosure query exposes compiler alias provenance without conflating it with alias-target resolution.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts No alias is inferred from printed type text or a named consumer; the actual AST parent chain defines the result.
+// @evidence contracts/common.md#meaningful-documentation Native prose states wrapper traversal, non-alias nil, nonnil inputs and the enclosing-declaration distinction.
+// @evidence contracts/performance.md#bound-retention-and-release-resources A returned symbol remains checker-owned and can reference its declarations and semantic graph; the caller controls retention of that reference, while this forwarding wrapper stores no independent result, buffer or handle.
+// @evidenceExclude contracts/performance.md#efficient-algorithms The wrapper selects no traversal strategy: the pinned helper walks H enclosing parenthesized/readonly wrappers, then delegates declaration-symbol normalization to the checker. That upstream traversal and symbol state own the cost, not a fixed-step local algorithm.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Declaration symbols and merged-symbol reuse belong to the upstream checker; this forwarding wrapper owns no query cache or coordination of repeated enclosure walks.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Checker_getAliasSymbolForTypeNode computes from its arguments only; it opens no file, builds no path and calls no platform or process API.
 func Checker_getAliasSymbolForTypeNode(recv *innerchecker.Checker, node *innerast.Node) *innerast.Symbol {
   return checkerGetAliasSymbolForTypeNode(recv, node)
 }
@@ -375,8 +883,18 @@ func Checker_getAliasSymbolForTypeNode(recv *innerchecker.Checker, node *inneras
 //go:linkname checkerGetDeclarationOfAliasSymbol github.com/microsoft/typescript-go/internal/checker.(*Checker).getDeclarationOfAliasSymbol
 func checkerGetDeclarationOfAliasSymbol(recv *innerchecker.Checker, symbol *innerast.Symbol) *innerast.Node
 
-// Checker_getDeclarationOfAliasSymbol resolves an import/export alias symbol to
-// its original declaration node.
+// Checker_getDeclarationOfAliasSymbol returns the last alias declaration in
+// symbol's declarations, or nil when none exists. It does not follow the alias
+// to its target declaration. Inputs must be nonnil.
+//
+// @evidence contracts/common.md#principled-implementation Upstream FindLast with IsAliasSymbolDeclaration selects the alias's own declaration under compiler declaration ordering rather than dereferencing its final target.
+// @evidence contracts/common.md#clear-and-simple-design Declaration provenance is queried separately from Checker_getAliasedSymbol target resolution, retaining the difference in the public API's native explanation.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The declaration is selected from the actual symbol's compiler declarations without a guessed import/export source.
+// @evidence contracts/common.md#meaningful-documentation Native prose distinguishes alias declaration from target, specifies last-match ordering and absent/nonnil conditions.
+// @evidence contracts/performance.md#bound-retention-and-release-resources The result is an existing declaration node that can reach its compiler tree through parents and metadata; the caller controls retention of that reference. The forwarding wrapper creates no collection and stores no independent result or handle.
+// @evidenceExclude contracts/performance.md#efficient-algorithms The wrapper chooses no search strategy. Upstream FindLast scans up to D symbol declarations in reverse order, with IsAliasSymbolDeclaration's syntax-dependent predicate work, and stops at the first match.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The producing compiler owns the symbol's declaration sequence and alias classification; this forwarding wrapper owns no declaration-query cache or coordination of repeated searches.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Checker_getDeclarationOfAliasSymbol computes from its arguments only; it opens no file, builds no path and calls no platform or process API.
 func Checker_getDeclarationOfAliasSymbol(recv *innerchecker.Checker, symbol *innerast.Symbol) *innerast.Node {
   return checkerGetDeclarationOfAliasSymbol(recv, symbol)
 }
@@ -386,6 +904,19 @@ func checkerGetTargetOfImportSpecifier(recv *innerchecker.Checker, node *inneras
 
 // Checker_getTargetOfImportSpecifier resolves an import specifier node to the
 // exported symbol it binds. Returns nil if recv or node is nil.
+// A nonnil node must be an import specifier in recv's checked program.
+// Upstream import/default/module-member rules can preserve an alias rather
+// than its final target, report resolution diagnostics, and mark type-only
+// alias metadata. A missing resolved member can also yield nil.
+//
+// @evidence contracts/common.md#principled-implementation The linked helper uses the import specifier's actual binding context to resolve its exported target, retaining checker alias semantics rather than matching module text.
+// @evidence contracts/common.md#clear-and-simple-design One guarded import-specific query exposes the existing semantic operation without duplicating module export lookup.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Missing inputs remain nil and targets are not guessed from specifier names.
+// @evidence contracts/common.md#meaningful-documentation Native prose states target meaning, nil behavior and the import-specifier/same-program premise.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Resolution symbols, module/export state, type-only alias metadata and diagnostics remain checker-owned; a returned symbol can retain that semantic graph through the caller's reference. The wrapper stores no separate result or handle.
+// @evidenceExclude contracts/performance.md#efficient-algorithms The wrapper guards nil inputs and selects no resolution strategy. Upstream import/default/module-member resolution owns module, property and export queries, name processing and possible symbol combination; costs follow those semantic graphs rather than fixed wrapper steps.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The producing checker/program owns module, export, symbol and alias-state reuse. This forwarding wrapper adds no import-target cache or repeated-query coordination.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Import target and external-module interpretation use the supplied checker/program authority; this wrapper adds no path, host or platform policy and does not replace that resolution.
 func Checker_getTargetOfImportSpecifier(recv *innerchecker.Checker, node *innerast.Node) *innerast.Symbol {
   if recv == nil || node == nil {
     return nil
@@ -395,6 +926,18 @@ func Checker_getTargetOfImportSpecifier(recv *innerchecker.Checker, node *innera
 
 // Checker_getAliasedSymbol follows an alias chain to its final target symbol.
 // Returns nil if recv or symbol is nil.
+// A nonnil symbol must carry the compiler's Alias flag and belong to recv.
+// Unresolved or circular aliases can return the checker's unknown symbol;
+// the operation can populate checker alias links and diagnostics.
+//
+// @evidence contracts/common.md#principled-implementation The compiler follows an actual alias symbol's chain to its semantic target under the Alias-flag and producing-checker premises.
+// @evidence contracts/common.md#clear-and-simple-design Target resolution remains separate from declaration lookup and import-node-specific resolution.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The target is not reconstructed by reopening textual module paths or accepting a similarly named symbol.
+// @evidence contracts/common.md#meaningful-documentation Native prose states final-target meaning, nil handling and the alias-symbol domain.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Upstream alias links and diagnostics belong to recv's checker lifetime; the returned target or unknown symbol can retain semantic state through the caller's reference. The wrapper stores no separate result or resource.
+// @evidenceExclude contracts/performance.md#efficient-algorithms The wrapper only guards nil inputs and forwards. The upstream checker owns declaration searches, recursive alias resolution, cycle handling and module-target queries; uncached work depends on that semantic graph rather than a fixed number of wrapper steps.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The upstream aliasSymbolLinks cache stores resolved targets, including the unknown-symbol result. This wrapper owns no separate alias cache or coordination policy.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Alias and module-target interpretation remain with the supplied checker and program; the wrapper adds no path, host or platform policy and does not bypass that authority.
 func Checker_getAliasedSymbol(recv *innerchecker.Checker, symbol *innerast.Symbol) *innerast.Symbol {
   if recv == nil || symbol == nil {
     return nil
@@ -405,6 +948,18 @@ func Checker_getAliasedSymbol(recv *innerchecker.Checker, symbol *innerast.Symbo
 // Checker_getExportsOfModule returns the exported symbols of a source-file or
 // namespace module symbol, resolving export-star aggregation the same way the
 // checker does for emit and services.
+// Nil checker or symbol returns nil; a nonnil symbol must be a module in recv.
+// The returned slice excludes reserved internal names. Aggregation can cache
+// resolved exports and report export-star name collisions in the checker.
+//
+// @evidence contracts/common.md#principled-implementation Upstream module exports include export-star aggregation and compiler alias identities for the supplied semantic module, rather than only syntactically listed export declarations.
+// @evidence contracts/common.md#clear-and-simple-design One module query centralizes aggregation in the checker instead of a separate shim re-export walker.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Export targets follow actual compiler bindings without hardcoded barrel paths or consumer exceptions.
+// @evidence contracts/common.md#meaningful-documentation Native prose names source-file/namespace modules, export-star handling and nil/same-checker constraints.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Upstream aggregation owns temporary visited-symbol/name/collision tables and checker-lifetime resolved-export state. The caller owns the returned symbol slice lifetime and can retain the checker graph through its elements; the wrapper stores no independent result or handle.
+// @evidenceExclude contracts/performance.md#efficient-algorithms The wrapper only guards nil inputs and forwards. Uncached upstream work recursively visits export-star modules, checks visited symbols, clones/merges name tables and reports collisions; each result conversion also scans exports to filter reserved names. Graph size and name/predicate costs belong to that implementation.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The producing checker caches resolvedExports and type-only export-star metadata, while symbolsToArray creates the per-query result slice. This wrapper owns no additional export cache or repeated-query coordination.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Export and external-module target resolution use the supplied checker/program authority; this wrapper adds no path, host or platform policy.
 func Checker_getExportsOfModule(recv *innerchecker.Checker, symbol *innerast.Symbol) []*innerast.Symbol {
   if recv == nil || symbol == nil {
     return nil
@@ -423,10 +978,25 @@ func checkerResolveEntityName(
 ) *innerast.Symbol
 
 // Checker_resolveEntityName resolves a dotted entity name (identifier or
-// qualified name) to the symbol it denotes, filtered by meaning flags.
-// When ignoreErrors is true, resolution failures are silent. When
-// dontResolveAlias is true, the returned symbol may still be an alias.
-// Returns nil if recv or name is nil.
+// qualified name, or the upstream property-access form) under meaning flags.
+// Unsupported nonmissing node kinds panic upstream. ignoreErrors suppresses
+// the resolver's own missing-name/member diagnostics; it does not certify that
+// alias resolution or the CommonJS external-module route produces no diagnostic.
+// dontResolveAlias suppresses the final alias walk, not namespace resolution
+// for a qualified name's left side. The result can be an alias or unknown symbol.
+// Returns nil if recv or name is nil, or the resolver finds no symbol.
+// Name and optional location must belong to recv's checked program.
+// Alias/type-only metadata and semantic caches may change; callers sharing the
+// checker must synchronize access.
+//
+// @evidence contracts/common.md#principled-implementation The pinned entity-name resolver applies meaning flags, scope, alias-resolution and diagnostic controls to the actual AST name, preserving type/value/namespace distinctions.
+// @evidence contracts/common.md#clear-and-simple-design One bridge exposes the resolver's relevant controls explicitly rather than duplicating separate dotted-name lookup implementations.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The semantic name is resolved by compiler scope rules, not string concatenation or a consumer-specific namespace table.
+// @evidence contracts/common.md#meaningful-documentation Native prose states supported node forms, diagnostic and alias-control limits, unknown/nil outcomes and producing-program ownership rather than promising silent resolution of every delegated operation.
+// @evidence contracts/performance.md#bound-retention-and-release-resources The returned symbol can retain its checker/program graph. Upstream resolution owns alias targets, type-only metadata, export/module state and possible diagnostics; the caller owns the checker lifetime and returned reference. This bridge keeps no independent lookup registry or release policy for that state.
+// @evidenceExclude contracts/performance.md#efficient-algorithms Upstream scope/name resolution, recursive qualified lookup, alias walks, export resolution and diagnostic suggestions own the algorithms and their scope, name-byte, declaration and symbol-graph costs. The shim only forwards explicit controls after nil guards, without selecting a second lookup algorithm.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The supplied checker owns alias/export/module caches and metadata that establish semantic reuse. This bridge coordinates no additional name-resolution producer or cross-program cache/invalidation policy.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Resolution uses the supplied checked program's scope and module authority, including its CommonJS route; this bridge chooses no independent host paths, executable or platform policy.
 func Checker_resolveEntityName(
   recv *innerchecker.Checker,
   name *innerast.Node,
@@ -444,9 +1014,21 @@ func Checker_resolveEntityName(
 //go:linkname checkerGetTypeNameSymbol github.com/microsoft/typescript-go/internal/checker.getTypeNameSymbol
 func checkerGetTypeNameSymbol(t *innerchecker.Type) *innerast.Symbol
 
-// Type_getTypeNameSymbol returns the symbol attached to t's type name field,
-// or nil when t has no name symbol or t is nil. Linked via go:linkname because
+// Type_getTypeNameSymbol returns t's alias symbol when alias metadata exists;
+// otherwise it returns t's symbol for type parameters, string-mapping types,
+// classes/interfaces and references, or nil for other categories or nil input.
+// It does not format the type or establish a unique name for every type.
+// Linked via go:linkname because
 // getTypeNameSymbol is a package-level unexported function in the checker.
+//
+// @evidence contracts/common.md#principled-implementation The compiler's name-symbol helper preserves semantic type naming rules, while nil input remains absent without dereferencing a type payload.
+// @evidence contracts/common.md#clear-and-simple-design One query exposes name provenance independently of type formatting or general symbol resolution.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts No name symbol is guessed from printed text or declaration identifiers.
+// @evidence contracts/common.md#meaningful-documentation Native prose states optional name/nil results and why explicit internal linkage is used.
+// @evidence contracts/performance.md#bound-retention-and-release-resources The caller receives an existing alias/type symbol and can retain its declaration and semantic graph. The source type/checker owner controls that lifetime; the bridge allocates no name copy and keeps no separate symbol history or handle.
+// @evidenceExclude contracts/performance.md#efficient-algorithms Upstream alias-first flag/symbol projection owns the selection rule. This shim only guards nil and chooses no separate name resolution, graph traversal or formatting algorithm.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The helper projects existing type metadata and coordinates no completed or in-flight producer, name cache or invalidation across requests.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Type_getTypeNameSymbol computes from its arguments only; it opens no file, builds no path and calls no platform or process API.
 func Type_getTypeNameSymbol(t *innerchecker.Type) *innerast.Symbol {
   if t == nil {
     return nil
@@ -457,7 +1039,18 @@ func Type_getTypeNameSymbol(t *innerchecker.Type) *innerast.Symbol {
 //go:linkname checkerIsArrayType github.com/microsoft/typescript-go/internal/checker.(*Checker).isArrayType
 func checkerIsArrayType(recv *innerchecker.Checker, t *innerchecker.Type) bool
 
-// Checker_isArrayType reports whether t is the built-in Array<T> reference type.
+// Checker_isArrayType reports whether t is a built-in Array<T> or
+// ReadonlyArray<T> reference type.
+// recv and t must be nonnil and belong to the same checker graph.
+//
+// @evidence contracts/common.md#principled-implementation The linked predicate uses the producing checker's global Array and ReadonlyArray target identities, distinguishing both built-in references from unrelated array-like objects.
+// @evidence contracts/common.md#clear-and-simple-design One compiler identity predicate avoids a separate structural-array classifier.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Built-in arrays are not identified by a consumer's type name or numeric-property heuristic.
+// @evidence contracts/common.md#meaningful-documentation Native prose states built-in reference scope and nonnil same-checker inputs.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Checker_isArrayType acquires no handle, buffer or cache and retains nothing after it returns.
+// @evidenceExclude contracts/performance.md#efficient-algorithms The wrapper selects no classification strategy: the pinned checker tests the reference flag and compares its target with the two existing global array targets, without traversing members or type arguments.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The producing checker owns the existing global Array/ReadonlyArray identities. This forwarding boolean predicate owns no array-type discovery, cache or coordination of repeated semantic queries.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Checker_isArrayType computes from its arguments only; it opens no file, builds no path and calls no platform or process API.
 func Checker_isArrayType(recv *innerchecker.Checker, t *innerchecker.Type) bool {
   return checkerIsArrayType(recv, t)
 }
@@ -467,6 +1060,18 @@ func checkerGetBaseTypes(recv *innerchecker.Checker, t *innerchecker.Type) []*in
 
 // Checker_getBaseTypes returns the list of base types (from `extends` clauses)
 // for a class or interface type. Returns nil if recv or t is nil.
+// A nonnil t must be a declared class/interface type, not its generic reference.
+// The result shares the checker's resolved-base slice; resolving it can update
+// type-resolution state and report invalid or circular heritage diagnostics.
+//
+// @evidence contracts/common.md#principled-implementation The upstream base-type helper resolves a declared class/interface's heritage in its producing checker; generic references must first use their declared class/interface representation.
+// @evidence contracts/common.md#clear-and-simple-design One inheritance query leaves heritage resolution with the compiler and states its narrower input domain explicitly.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts No base is inferred from a textual extends clause or guessed class name.
+// @evidence contracts/common.md#meaningful-documentation Native prose describes heritage output, nil absence and the declared-type versus generic-reference distinction.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Resolved-base slices, resolution flags and diagnostics remain checker-owned; the returned slice references that type graph and the caller controls its additional retention. The wrapper stores no separate result or handle.
+// @evidenceExclude contracts/performance.md#efficient-algorithms This wrapper only guards nil inputs and forwards. Upstream class/interface heritage resolution owns declaration and extends-element walks, type/signature processing and recursive base checks; uncached cost follows that graph rather than fixed wrapper steps.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The upstream baseTypesResolved flag and resolvedBaseTypes slice own reuse within the producing checker. The forwarding wrapper introduces no additional cache or coordination policy.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Heritage interpretation remains with the supplied checker/program; this wrapper adds no path, host or platform policy.
 func Checker_getBaseTypes(recv *innerchecker.Checker, t *innerchecker.Type) []*innerchecker.Type {
   if recv == nil || t == nil {
     return nil
@@ -477,14 +1082,22 @@ func Checker_getBaseTypes(recv *innerchecker.Checker, t *innerchecker.Type) []*i
 //go:linkname checkerGetDeclaredTypeOfSymbol github.com/microsoft/typescript-go/internal/checker.(*Checker).getDeclaredTypeOfSymbol
 func checkerGetDeclaredTypeOfSymbol(recv *innerchecker.Checker, symbol *innerast.Symbol) *innerchecker.Type
 
-// Checker_getDeclaredTypeOfSymbol returns the declared (instance) type of a
-// class or interface symbol. Unlike Checker_getTypeOfSymbol, which yields the
-// constructor (static) type of a class symbol, the result IS a
-// ClassOrInterface type and is therefore safe to feed back into
-// Checker_getBaseTypes. This lets a consumer resolve a generic base's symbol to
-// its declared type and keep walking the base chain past the generic boundary
-// where getBaseTypes would otherwise dead-end (a Reference/Anonymous type has a
-// nil AsInterfaceType()). Returns nil if recv or symbol is nil.
+// Checker_getDeclaredTypeOfSymbol returns the compiler's declared type for a
+// symbol from recv's checker graph. For a class/interface symbol this is its
+// declared instance representation, suitable for Checker_getBaseTypes, rather
+// than a class value's constructor type or an instantiated reference.
+// Other symbol categories follow upstream declared-type dispatch and do not
+// promise a class/interface result; absence of a declared type yields the
+// checker's error type. Returns nil if recv or symbol is nil.
+//
+// @evidence contracts/common.md#principled-implementation For class/interface symbols, compiler declared-type lookup distinguishes the instance-side representation from a class value's constructor type and supports base-type traversal. Other symbol categories retain upstream dispatch and error-type fallback.
+// @evidence contracts/common.md#clear-and-simple-design The wrapper exposes instance declaration typing separately from ordinary symbol value typing instead of making consumers coerce type representations.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Generic heritage traversal uses actual declared compiler types rather than a compensating name-based base lookup.
+// @evidence contracts/common.md#meaningful-documentation Native prose scopes the class/interface result, states upstream dispatch/error-type behavior for other symbols, and specifies same-checker and nil conditions.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Declared-type links and any class/interface type, this-type or instantiation table remain checker-owned; the caller can retain that graph through the returned type. This forwarding wrapper keeps no separate cache, result or handle.
+// @evidenceExclude contracts/performance.md#efficient-algorithms The wrapper guards nil inputs and delegates symbol-category dispatch. Upstream uncached class/interface construction includes outer/local parameter collection and recursive interface heritage checks, while other categories own their semantic resolution costs; this is not a fixed-step local strategy.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The supplied checker owns declaredTypeLinks and type instantiation reuse. The forwarding wrapper does not coordinate or cache repeated declared-type queries.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Symbol typing and related resolution use the supplied checker/program; the wrapper introduces no path, host or platform policy.
 func Checker_getDeclaredTypeOfSymbol(recv *innerchecker.Checker, symbol *innerast.Symbol) *innerchecker.Type {
   if recv == nil || symbol == nil {
     return nil
@@ -496,10 +1109,21 @@ func Checker_getDeclaredTypeOfSymbol(recv *innerchecker.Checker, symbol *inneras
 func checkerGetMinArgumentCount(recv *innerchecker.Checker, signature *innerchecker.Signature) int
 
 // Checker_getMinArgumentCount returns the minimum number of required arguments
-// a call/construct signature accepts (parameters before the first optional or
-// rest parameter). A type-transform plugin uses this to gate the single-
-// required-parameter constructor strategy (`new C(x)`) and single-arg static
-// factory (`C.from(x)`). Returns 0 if recv or signature is nil.
+// a call/construct signature accepts under compiler rules, including required
+// tuple-rest positions and trailing void-accepting parameters. It uses the
+// upstream default arity flags, including the untyped-JavaScript zero rule;
+// this minimum alone does not validate a call's argument types or maximum arity.
+// Nonnil inputs must belong to the same checker graph. Returns 0 if recv or
+// signature is nil; computing a result can populate signature arity state.
+//
+// @evidence contracts/common.md#principled-implementation Upstream minimum-arity calculation accounts for required tuple-rest positions, optionality, untyped JavaScript and trailing void acceptance instead of counting declarations before a rest marker.
+// @evidence contracts/common.md#clear-and-simple-design One arity query exposes the compiler's default minimum-argument rule without a second parameter-counting policy or a promise of full call validation.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The result comes from actual signature semantics rather than a consumer's constructor strategy or fixed expected arity.
+// @evidence contracts/common.md#meaningful-documentation Native prose distinguishes default minimum arity from full call validation, includes tuple/void/JavaScript cases and documents same-checker and nil conditions.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources This forwarding wrapper returns an integer and owns no retained result graph, buffer or handle. Signature arity state and any semantic types resolved by the calculation remain owned by the producing checker.
+// @evidenceExclude contracts/performance.md#efficient-algorithms The wrapper only guards nil inputs. Upstream calculation can scan tuple-rest elements and trailing parameters, resolve their types and examine void-containing constituents; those list and semantic-resolution costs belong to the checker rather than fixed local steps.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Upstream resolvedMinArgumentCount coordinates ordinary default-flag reuse, while the untyped-JavaScript early-zero branch can return before caching. The wrapper owns no additional arity cache or repeated-query coordination.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Signature typing uses the supplied checker graph; the wrapper adds no path, host or platform policy.
 func Checker_getMinArgumentCount(recv *innerchecker.Checker, signature *innerchecker.Signature) int {
   if recv == nil || signature == nil {
     return 0
@@ -507,14 +1131,22 @@ func Checker_getMinArgumentCount(recv *innerchecker.Checker, signature *innerche
   return checkerGetMinArgumentCount(recv, signature)
 }
 
-// Checker_getSignaturesOfType returns the call or construct signatures declared
-// on t, selected by kind (SignatureKindCall / SignatureKindConstruct). This is
-// the producer companion to Checker_getMinArgumentCount and
-// Checker_getReturnTypeOfSignature: without it the *Signature those two consume
-// could not be obtained. A type-transform plugin uses the construct signatures
-// of a class's constructor type to detect the `new C(x)` strategy and the call
-// signatures of a static `from` member to detect the `C.from(x)` strategy.
-// Returns nil if recv or t is nil.
+// Checker_getSignaturesOfType returns semantic call or construct signatures
+// selected by kind (SignatureKindCall / SignatureKindConstruct), after reduced
+// apparent-type normalization. Structured-member resolution can inherit,
+// instantiate or combine signatures; these are not limited to direct declarations.
+// Results can be passed to minimum-arity or return-type queries and share the
+// checker's resolved signature slice. Nonnil t must belong to recv's graph.
+// Returns nil for nil recv/t or a normalized type with no structured signatures.
+//
+// @evidence contracts/common.md#principled-implementation The upstream type query selects call or construct signatures by kind, retaining instantiated overload identities for further checker queries.
+// @evidence contracts/common.md#clear-and-simple-design One explicit kind parameter separates invocation from construction without duplicating type traversal.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Signatures are actual compiler results rather than assumed constructor or factory shapes.
+// @evidence contracts/common.md#meaningful-documentation Native prose states selectable populations, relationships to arity/return queries and nil absence.
+// @evidence contracts/performance.md#bound-retention-and-release-resources The returned call/construct subslice shares checker-owned structured signature storage; entries can retain declarations, target/composite signatures and type mappers. The caller controls additional retention, while this wrapper stores no independent result or handle.
+// @evidenceExclude contracts/performance.md#efficient-algorithms The wrapper only guards nil inputs and forwards the kind. Upstream reduction and structured-member resolution own base/member instantiation and union/intersection signature formation or comparison; their type/signature graph costs precede the direct subslice selection.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Structured member resolution and its combined signature storage coordinate reuse within the producing checker. This wrapper adds no signature cache or repeated-query coordination.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Signature normalization and resolution use the supplied checker/program; this wrapper introduces no path, host or platform policy.
 func Checker_getSignaturesOfType(recv *innerchecker.Checker, t *innerchecker.Type, kind innerchecker.SignatureKind) []*innerchecker.Signature {
   if recv == nil || t == nil {
     return nil
@@ -522,10 +1154,21 @@ func Checker_getSignaturesOfType(recv *innerchecker.Checker, t *innerchecker.Typ
   return recv.GetSignaturesOfType(t, kind)
 }
 
-// Checker_getReturnTypeOfSignature returns the return type of signature, used to
-// verify that a static `from(x)` factory actually returns the class instance
-// type before selecting the `C.from(x)` construction strategy. Returns nil if
-// recv or signature is nil.
+// Checker_getReturnTypeOfSignature resolves a signature's semantic return type
+// in its producing checker, including instantiated/composite signatures and
+// annotation or body inference. Upstream recursion handling can yield error
+// or any types and report diagnostics; the resolved result is signature state.
+// This query does not select a consumer's construction strategy. Returns nil
+// if recv or signature is nil.
+//
+// @evidence contracts/common.md#principled-implementation Upstream signature return typing applies its instantiated semantic context rather than using a syntactic return annotation that may be inferred or generic.
+// @evidence contracts/common.md#clear-and-simple-design One return query complements signature enumeration while keeping semantic resolution inside the checker.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The return comes from signature semantics rather than a function's name or a consumer's construction convention.
+// @evidence contracts/common.md#meaningful-documentation Native prose states producing-checker resolution, inference/composite cases, recursion fallback/state effects and nil inputs without prescribing consumer policy.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Resolved return types, instantiation/composite type state and diagnostics belong to the producing checker/signature lifetime. The caller can retain that graph through the returned type; this wrapper stores no independent result or handle.
+// @evidenceExclude contracts/performance.md#efficient-algorithms The wrapper only guards nil inputs. Upstream uncached resolution follows target/composite signatures, instantiates their return types or resolves annotations/function bodies, with cycle handling and optional-chain adjustments; cost follows those semantic/body graphs rather than fixed wrapper steps.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Upstream resolvedReturnType and type-resolution state coordinate result reuse and recursion handling. This wrapper adds no return-type cache or repeated-query policy.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Return typing and inference remain with the supplied checker/program; the wrapper adds no path, host or platform policy.
 func Checker_getReturnTypeOfSignature(recv *innerchecker.Checker, signature *innerchecker.Signature) *innerchecker.Type {
   if recv == nil || signature == nil {
     return nil
@@ -533,19 +1176,25 @@ func Checker_getReturnTypeOfSignature(recv *innerchecker.Checker, signature *inn
   return recv.GetReturnTypeOfSignature(signature)
 }
 
-// Signature_parameterCount returns the number of declared value parameters of a
-// call/construct signature. A rest parameter counts as one and the `this`
+// Signature_parameterCount returns the number of stored value parameters of a
+// call/construct signature, including synthesized signatures. A rest parameter
+// counts as one and the `this`
 // parameter is excluded (it is held separately from the value parameters).
 //
 // Checker_getMinArgumentCount alone cannot tell a zero-parameter signature
 // (`()` minimum 0) from a single-optional-parameter one (`(x?)` also
-// minimum 0). A type-transform plugin needs that distinction to replicate the
-// type-level "single meaningful argument" rule: a FIRST parameter must exist
-// and every later parameter must be optional or rest, as
-// `Signature_parameterCount(sig) >= 1 && Checker_getMinArgumentCount(c, sig) <= 1`.
-// Without it the `new C(x)` / `C.from(x)` strategies silently fall back to field
-// copy for every optional-first constructor or factory. Returns 0 if signature
-// is nil.
+// minimum 0). This length query does not select a consumer's constructor or
+// factory strategy, nor replace overload/call validation. Returns 0 if
+// signature is nil.
+//
+// @evidence contracts/common.md#principled-implementation The compiler stores value parameters separately from this; their slice length counts actual stored entries, including one rest entry, independently of minimum call arity or declaration versus synthesized signature origin.
+// @evidence contracts/common.md#clear-and-simple-design A direct length query answers stored parameter count without conflating it with Checker_getMinArgumentCount.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts No constructor convention alters the count; it is computed from the actual signature parameter slice.
+// @evidence contracts/common.md#meaningful-documentation Native paragraphs explain rest/this counting, the distinction from minimum arity and nil zero with useful examples.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Signature_parameterCount acquires no handle, buffer or cache and retains nothing after it returns.
+// @evidenceExclude contracts/performance.md#efficient-algorithms This projection reads the existing upstream parameter slice length after a nil guard and owns no parameter construction, traversal or semantic arity-validation algorithm.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The length projection coordinates no completed or in-flight producer, cache or invalidation across requests; the signature owner supplies the already constructed parameter list.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Signature_parameterCount computes from its arguments only; it opens no file, builds no path and calls no platform or process API.
 func Signature_parameterCount(signature *innerchecker.Signature) int {
   if signature == nil {
     return 0
@@ -553,15 +1202,24 @@ func Signature_parameterCount(signature *innerchecker.Signature) int {
   return len(signature.Parameters())
 }
 
-// Signature_parameters returns the declared value-parameter symbols of a
-// call/construct signature, in declaration order, excluding the synthetic
-// `this` parameter. The first element is the seed parameter of a `new C(seed)`
-// constructor or a `C.from(seed)` factory; feeding it to Checker_getTypeOfSymbol
-// yields the seed TYPE the plugin must decode before constructing the instance.
+// Signature_parameters returns a call/construct signature's stored ordered
+// value-parameter symbols, including synthesized signature parameters. `this`
+// is held separately upstream. This accessor does not select a consumer's
+// constructor/factory seed or validate its type.
 //
 // Signature_parameterCount is len() of this slice; the slice itself is needed
-// because detection (count + min-args) is not enough; emission requires the
-// seed parameter's type. Returns nil if signature is nil.
+// for consumers that need the actual symbols rather than an arity projection.
+// Returns nil if signature is nil.
+// The returned slice is compiler-owned; callers must not mutate it.
+//
+// @evidence contracts/common.md#principled-implementation Returning the signature's existing value-parameter symbols preserves stored order and checker identity, including synthesized lists, with this represented separately upstream.
+// @evidence contracts/common.md#clear-and-simple-design One accessor exposes the same slice counted by Signature_parameterCount, avoiding a copied shim parameter representation.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The accessor does not create synthetic seed parameters or filter parameters for a particular consumer strategy.
+// @evidence contracts/common.md#meaningful-documentation Native prose states value/this separation, stored order, synthesized-list and consumer-policy limits, nil behavior and compiler-owned immutable-by-caller slice use.
+// @evidence contracts/performance.md#bound-retention-and-release-resources The caller receives the signature-owned slice without copying it; retaining that slice can retain its backing store, symbols and semantic graph. The supplied signature/checker owner controls their lifetime, and callers must not mutate the shared contents. This bridge keeps no additional parameter history or handle.
+// @evidenceExclude contracts/performance.md#efficient-algorithms The upstream accessor returns existing parameter storage directly. The guarded forwarding shim chooses no traversal, filtering, copying or parameter-construction algorithm.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The signature owner supplies an already constructed list; this bridge coordinates no completed or in-flight producer, parameter cache or invalidation across requests.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Signature_parameters computes from its arguments only; it opens no file, builds no path and calls no platform or process API.
 func Signature_parameters(signature *innerchecker.Signature) []*innerast.Symbol {
   if signature == nil {
     return nil
@@ -569,21 +1227,22 @@ func Signature_parameters(signature *innerchecker.Signature) []*innerast.Symbol
   return signature.Parameters()
 }
 
-// Signature_hasRestParameter reports whether the signature's last value
-// parameter is a rest parameter (`...xs: S[]`). It is the signal a from/new
-// transform needs to tell a rest-only single-seed call `(...xs: S[])`, whose
-// seed is the ELEMENT S, from a genuine array-typed parameter `(seed: S[])`,
-// whose seed is the array S[]: getTypeOfSymbol yields `S[]` for BOTH, so without
-// this flag they are indistinguishable and the rest case decodes the wrong
-// shape.
-//
-// The rest ELEMENT is the seed ONLY when the rest parameter is the sole value
-// parameter, i.e. `Signature_hasRestParameter(sig) && Signature_parameterCount(sig) == 1`.
-// A leading-required + rest-tail signature `(s: S, ...r: R[])` also has a rest
-// parameter (this returns true), but its seed is the FIRST parameter S. Read it
-// from Signature_parameters(sig)[0], NOT the rest element, matching
-// ClassifiableSeed, whose `[infer P, ...Rest]` arm picks P=S there. Returns
-// false if signature is nil.
+// Signature_hasRestParameter reads the upstream signature's rest flag, which
+// declaration checking and synthesized/composite signature construction set.
+// For ordinary declarations it distinguishes a rest parameter (`...xs: S[]`)
+// from an array-typed ordinary parameter (`xs: S[]`); an earlier required
+// parameter does not make a later rest parameter disappear. This predicate
+// does not choose a consumer's seed or compute its rest element type.
+// Returns false if signature is nil.
+//
+// @evidence contracts/common.md#principled-implementation Reading the actual signature flag preserves upstream declaration and synthesized-signature rest semantics; array typing alone and a consumer's seed policy do not replace that flag.
+// @evidence contracts/common.md#clear-and-simple-design One predicate exposes declaration shape separately from parameter count and rest element typing.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Array typing is not used as a shortcut for rest syntax; actual signature flags decide the result.
+// @evidence contracts/common.md#meaningful-documentation Native prose explains signature-flag provenance, ordinary rest-versus-array distinction, consumer-policy limits and nil false.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Signature_hasRestParameter acquires no handle, buffer or cache and retains nothing after it returns.
+// @evidenceExclude contracts/performance.md#efficient-algorithms Upstream HasRestParameter owns direct signature-flag inspection; this shim only guards nil and chooses no parameter traversal or rest-type calculation algorithm.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The predicate reads an existing signature and coordinates no completed or in-flight producer, cache or invalidation across requests.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Signature_hasRestParameter computes from its arguments only; it opens no file, builds no path and calls no platform or process API.
 func Signature_hasRestParameter(signature *innerchecker.Signature) bool {
   if signature == nil {
     return false
@@ -591,16 +1250,23 @@ func Signature_hasRestParameter(signature *innerchecker.Signature) bool {
   return signature.HasRestParameter()
 }
 
-// Checker_getRestTypeOfSignature returns the ELEMENT type of the signature's
-// rest parameter (`...xs: S[]` -> S; a tuple rest unwraps to its element too),
-// which is the seed type for a rest-ONLY single-argument constructor/factory,
-// matching ClassifiableSeed, which unwraps the rest to its element. When the
-// signature has NO rest parameter it falls back to `any` upstream; and a
-// leading-required + rest-tail `(s: S, ...r: R[])` has a rest parameter yet its
-// seed is the FIRST parameter S, not the rest element. So take the rest element
-// only when `Signature_hasRestParameter(sig) && Signature_parameterCount(sig) == 1`;
-// otherwise read Signature_parameters(sig)[0]. Returns nil if recv or signature
-// is nil.
+// Checker_getRestTypeOfSignature exposes the upstream rest-type query. It
+// numeric-indexes the last rest parameter's type (`...xs: S[]` -> S). For a
+// tuple rest, upstream first derives its variable tail and then numeric-indexes
+// that derived type; this is not a union of all fixed tuple positions.
+// Missing rest parameters or absent derived/index information return the
+// checker's any type. This query does not choose a consumer's seed parameter.
+// Nonnil inputs must belong to the same checker graph. Returns nil if recv or
+// signature is nil.
+//
+// @evidence contracts/common.md#principled-implementation The compiler derives the last rest parameter's type, extracts a tuple's variable rest part when present, then applies numeric indexing; absent derivable rest typing returns upstream any rather than a fabricated fixed-tuple element union.
+// @evidence contracts/common.md#clear-and-simple-design One query exposes upstream rest typing independently of declared parameter count or a consumer's choice of seed argument.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Ordinary array parameters are not treated as rest declarations and fixed tuple-rest absence is not hidden with a guessed element type.
+// @evidence contracts/common.md#meaningful-documentation Native prose states the tuple-tail then numeric-index pipeline, any fallback, consumer-policy boundary and same-checker/nil conditions.
+// @evidence contracts/performance.md#bound-retention-and-release-resources The result is a checker-owned semantic type, including the shared any fallback; the caller can retain its type graph. Upstream tuple-tail derivation owns temporary element slices and any constructed union/index state, while this wrapper keeps no independent result or handle.
+// @evidenceExclude contracts/performance.md#efficient-algorithms The wrapper only guards nil inputs. Upstream rest-symbol typing, tuple argument/tail traversal and union construction precede numeric index-info resolution; these semantic graph/list costs belong to the checker rather than a fixed-step local strategy.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Signature symbol types, tuple/type arguments and structured index information reuse producing-checker state; this wrapper introduces no rest-query cache or repeated-work coordination.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Rest and index typing remain with the supplied checker/program; this wrapper adds no path, host or platform policy.
 func Checker_getRestTypeOfSignature(recv *innerchecker.Checker, signature *innerchecker.Signature) *innerchecker.Type {
   if recv == nil || signature == nil {
     return nil
@@ -618,10 +1284,21 @@ func checkerNewSimpleTypeMapper(source *innerchecker.Type, target *innerchecker.
 func checkerNewTypeMapper(sources []*innerchecker.Type, targets []*innerchecker.Type) *innerchecker.TypeMapper
 
 // Checker_instantiateType substitutes the type parameters of `t` with the
-// concrete types in `mapper`, returning the instantiated type. A type-transform
-// plugin uses it to instantiate a generic class's constructor type with the
-// reference's type arguments, so a type parameter nested inside a container
-// (`A[]`, `[A, B]`) is substituted for free. Returns nil if recv or t is nil.
+// types selected by mapper through upstream semantic type structure. Nested
+// references, unions and other supported type forms use the compiler's
+// instantiation rules, not textual substitution. Types with no relevant type
+// variables can pass through; excessive depth/work can yield an error type
+// and a checker diagnostic. Returns nil if recv or t is nil.
+// Type and mapper entries must belong to recv; a nil mapper preserves the type.
+//
+// @evidence contracts/common.md#principled-implementation The compiler instantiator applies mapper identity through nested semantic type structure, preserving compiler type relationships instead of textual type-parameter replacement.
+// @evidence contracts/common.md#clear-and-simple-design One instantiation bridge consumes the same mapper model exposed by constructors, avoiding a separate recursive type copier.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Substitution uses actual type identities rather than parameter names or selected container special cases.
+// @evidence contracts/common.md#meaningful-documentation Native prose explains nested substitution, nil result, nil mapper identity and producing-checker premises.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Returned or constructed types and diagnostics belong to the producing checker graph, which the caller can retain through the result. Upstream active-mapper maps/lists own temporary instantiation state; normal pop clears map entries and mapper references while retaining storage for reuse. The wrapper stores no independent result or handle.
+// @evidenceExclude contracts/performance.md#efficient-algorithms This wrapper only guards nil inputs. Upstream type-variable detection, active-mapper lookup/cache-key work and recursive instantiation/reduction own graph/list costs, with compiler depth/count limits; the wrapper selects no replacement instantiation strategy.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Upstream active mapper caches and type-variable metadata coordinate instantiation reuse. The forwarding wrapper adds no instantiation cache or repeated-work policy.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Type/mapper instantiation uses the supplied checker/program; the wrapper introduces no path, host or platform policy.
 func Checker_instantiateType(recv *innerchecker.Checker, t *innerchecker.Type, mapper *innerchecker.TypeMapper) *innerchecker.Type {
   if recv == nil || t == nil {
     return nil
@@ -633,6 +1310,16 @@ func Checker_instantiateType(recv *innerchecker.Checker, t *innerchecker.Type, m
 // `source` with `target`. It is the building block for instantiating a generic
 // class's constructor type with its reference type arguments. Returns nil if
 // source or target is nil.
+// Source and target must belong to the same semantic checker context.
+//
+// @evidence contracts/common.md#principled-implementation Upstream's simple mapper records one source-type identity and its target, providing semantic substitution without name collisions.
+// @evidence contracts/common.md#clear-and-simple-design The one-pair constructor is distinct from parallel and composed mappings, exposing the representation required for its actual operation.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts No guessed type-parameter name or fixed consumer class determines the mapping.
+// @evidence contracts/common.md#meaningful-documentation Native prose identifies one-pair substitution, nil refusal and same-context types.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Construction acquires one upstream mapper retaining the source and target type references, and transfers it to the caller. Retaining that mapper can retain their semantic graphs; the bridge keeps no additional mapper registry, handle or historical population.
+// @evidenceExclude contracts/performance.md#efficient-algorithms The upstream simple-mapper constructor owns its fixed-size allocation and its later direct pointer-identity substitution. The bridge only rejects nil inputs and forwards the pair, selecting no separate graph-traversal or substitution algorithm.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work This constructor transfers a semantic mapping value; it does not coordinate a shared instantiation producer or cache its results. Any reuse by an instantiating checker is owned by that checker, not a new constructor cache.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Mapper construction retains supplied semantic type identities and introduces no independent host, path or process policy.
 func Checker_newSimpleTypeMapper(source *innerchecker.Type, target *innerchecker.Type) *innerchecker.TypeMapper {
   if source == nil || target == nil {
     return nil
@@ -645,6 +1332,21 @@ func Checker_newSimpleTypeMapper(source *innerchecker.Type, target *innerchecker
 // one substitution's target through later substitutions, so a mapping such as
 // `[A, B] -> [B, A]` preserves both target identities. Returns nil when the
 // slices are empty, differ in length, or contain nil types.
+//
+// For multiple pairs the compiler retains the supplied slices; callers must
+// not mutate them after construction. A single pair stores the two type
+// references in a simple mapper. All entries must belong to one semantic
+// checker context. Mapping selects the first matching source identity without
+// feeding the selected target back through this mapper.
+//
+// @evidence contracts/common.md#principled-implementation Parallel source/target identities are validated pairwise and passed to the compiler mapper without composing targets through other pairs, preserving simultaneous substitution such as a swap.
+// @evidence contracts/common.md#clear-and-simple-design One constructor owns parallel-shape validation, separate from the explicitly compositional mapper operation.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Invalid arrays are rejected rather than truncated, padded or converted into successive substitutions that change meaning.
+// @evidence contracts/common.md#meaningful-documentation Native paragraphs explain parallel-versus-composed substitution, a swap example, rejection conditions and retained-slice ownership.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Construction transfers one mapper to the caller: a single pair retains its type references, while multiple pairs retain both caller-owned slice backing stores and their type graphs without copying them. Slice contents must remain stable during use; dropping this mapper releases only its references, not graphs still owned elsewhere. The bridge keeps no historical mapper registry.
+// @evidence contracts/performance.md#efficient-algorithms One O(N) validation pass checks corresponding nonnil pairs without composing substitutions or allocating copied arrays. Upstream construction stores references in bounded wrapper storage; later mapping is direct for one pair and first-match linear in N for an array mapper. This preserves simultaneous substitution and input identity without a sequential substitution rebuild.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The constructor validates and transfers a mapping value rather than coordinating a shared instantiation result or in-flight producer. Instantiating checker state owns any semantic-result reuse; this bridge has no separate cross-request mapper cache/invalidation policy.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Works on in-memory type values only; it accesses no path or filesystem.
 func Checker_newTypeMapper(sources []*innerchecker.Type, targets []*innerchecker.Type) *innerchecker.TypeMapper {
   if len(sources) == 0 || len(sources) != len(targets) {
     return nil
@@ -666,6 +1368,17 @@ func checkerCombineTypeMappers(recv *innerchecker.Checker, m1 *innerchecker.Type
 // declaration-parameter mappings. Returns m2 when m1 is nil, including when
 // recv is nil. Returns nil when m1 is non-nil and recv or m2 is nil, because
 // both are required to build a usable composite mapper.
+//
+// Types and mappers must belong to recv's semantic checker context.
+//
+// @evidence contracts/common.md#principled-implementation Upstream mapper composition instantiates the first stage's target through the second, while absent first stage acts as identity; a nonempty first stage requires both checker and second mapper.
+// @evidence contracts/common.md#clear-and-simple-design Composition has its own named operation and explicit nil policy, distinct from simultaneous parallel parameter mapping.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The stages are composed by compiler semantics rather than flattened into a misleading pair list or repaired with arbitrary fallback types.
+// @evidence contracts/common.md#meaningful-documentation Native prose states composition order, parallel alternative, all nil cases and same-checker premises.
+// @evidence contracts/performance.md#bound-retention-and-release-resources The nonempty composition returns one upstream composite mapper retaining recv, m1 and m2; the caller owns its lifetime and the reachable checker/type state. Nil branches allocate no composite, and the wrapper keeps no separate handle or cache.
+// @evidence contracts/performance.md#efficient-algorithms Fixed nil checks delegate to the upstream O(1) composite construction without visiting mapped types. Applying the returned mapper later owns first-stage mapping and second-stage instantiation costs.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The wrapper transfers an existing second mapper or creates a caller-owned composition; it owns no semantic mapper cache or coordination of later mapping work, which belongs to the upstream checker.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Checker_combineTypeMappers computes from its arguments only; it opens no file, builds no path and calls no platform or process API.
 func Checker_combineTypeMappers(recv *innerchecker.Checker, m1 *innerchecker.TypeMapper, m2 *innerchecker.TypeMapper) *innerchecker.TypeMapper {
   if m1 == nil {
     return m2