feat(js): service-scoped type resolution + generic substitution on TypeResolver

[ukint-vs]

Closes #1317.

Summary

Adds three public methods on TypeResolver and a convenience accessor on SailsProgram so downstream consumers (wallets, explorers, schema tooling, custom codegen) stop re-implementing type-scope and generic-substitution out-of-band.

New API

class TypeResolver {
  // Constructor: ambient (program-level) types visible to every service,
  // shadowed by service-local `types` on name collision.
  constructor(types: Type[], ambientTypes?: Type[]);

  // Look up a named user Type from this resolver's scope.
  resolveNamed(typeDecl: TypeDecl): Type | undefined;

  // Recursively substitute type parameters through a TypeDecl tree.
  // Pure, idempotent, same-ref return on unchanged subtrees.
  // Throws on cyclic substitution maps ({T: T} or {T: U, U: T}).
  substituteGenerics(typeDecl: TypeDecl, substitutions?: Record<string, TypeDecl>): TypeDecl;

  // Zip user type's type_params with a concrete generics list.
  genericsSubstitutions(userType: Type, generics?: TypeDecl[]): Record<string, TypeDecl>;
}

class SailsProgram {
  // Direct AST lookup — safe to call in tight walker loops.
  resolveInService(serviceName: string, typeDecl: TypeDecl): Type | undefined;
}

SailsProgram now threads program.types into every SailsService (including the extends chain) as ambient types, so per-service TypeResolver instances see program-level types with service-local shadowing.

getTypeDeclString was also updated to call the new genericsSubstitutions helper instead of the inline copy at lines 229-233.

Why

Two correctness bugs in consumer code before this change:

1. Name collisions across services. Two services each declaring Packet with different shapes silently collided when a consumer flattened types into a single map. No public API narrowed a lookup to a single service's scope.
2. Generic substitution. Envelope<[u8]>'s payload field came through as a bare {kind:'named', name:'T'} leaf, causing walkers to silently pass hex strings through untouched or SCALE-encode with wrong bytes. The substitution algorithm already lived inside getTypeDeclString — this PR factors it out and exposes it.

vara-wallet had ~180 lines of workaround (coerceHexToBytesV2, getRegistryTypes, ad-hoc substitution recursion) that can now collapse to a few method calls.

Tests

21 new tests, 46 total passing in the resolver + parser-resolver suites (64 total offline).

Unit (js/test/idl-v2-type-resolver.test.ts):

• substituteGenerics: bare-param substitution, recursion through slice/array/tuple/named-with-generics, pass-through for unknown names, idempotence, non-mutation, chain resolution (T → U → u32), self-referential throw, cyclic chain throw, unknown-kind throw.
• resolveNamed: returns user Type for named decl (including generic), returns undefined for primitives/slices/arrays/tuples/unknown names/bare type_params.
• genericsSubstitutions: zip, no type_params, extra generics truncated.
• Ambient types: unshadowed lookup, local-shadows-ambient, registry reflects shadowing (collision test encodes [u8; 8] after overriding an [u8; 4] ambient shape).

Integration (js/test/idl-v2-parser-type-resolver.test.ts):

• Two services each declaring Packet with different shapes → resolveInService('A', ...) vs 'B' return their own definitions.
• Unknown service name → undefined.
• Program-level Shared visible via service resolver (ctor arg path; the parser rejects program-level references from service signatures).
• Envelope<[u8]> → walker feeds struct fields through substituteGenerics + genericsSubstitutions to resolve payload from T to [u8].

Notes for reviewers

• substituteGenerics has a runtime cycle guard (visited set, throws with the full chain on detection) rather than just the JSDoc warning. Maps produced by genericsSubstitutions from parsed IDL can't produce cycles, but hand-merged or wire-sourced maps can.
• SailsProgram.resolveInService walks the AST directly rather than going through this.services (which rebuilds SailsService + a fresh TypeRegistry on every access). Safe for hot walker loops.
• substituteGenerics returns the same reference for subtrees that contained no substitutions — walkers traversing large trees with sparse type parameters don't allocate new nodes unnecessarily.
• _substituteGenerics uses immutable visited-set copies on the recursion path so a throw mid-recursion leaves no poisoned shared state.

[gemini-code-assist]

Code Review

This pull request introduces service-scoped type resolution and generic type substitution for the Sails IDL v2 implementation. Key enhancements include the addition of resolveInService to SailsProgram for scoped type lookups and the introduction of ambientTypes in SailsService to support program-level types. The TypeResolver has been significantly updated with logic for shadowing ambient types, recursive generic substitution with cycle detection, and helper methods for mapping type parameters. Feedback was provided regarding the performance of resolveInService, suggesting the use of Maps for $O(1)$ lookups to prevent bottlenecks in large IDLs.

[ukint-vs]

Rebased on master and addressed maintainer feedback:

1. TypeResolver constructor reverted to (types: Type[]). [...ambientTypes, ...localTypes] merging now happens at the call site in SailsService. The resolver no longer knows about the ambient-vs-local distinction; callers pass a single pre-merged array and rely on last-write-wins semantics for shadowing.
2. Adapted to TypeDecl::Generic (from feat: Migrate type registry to IDL AST, add explicit generic type declarations #1314). substituteGenerics now targets the explicit {kind:'generic'} variant for type-parameter leaves; a bare {kind:'named'} decl is always a concrete user-type reference and is no longer used as a type-param fallback. resolveNamed returns undefined for kind:'generic'. Tests updated accordingly.

Cycle detection, chain resolution (T → U → u32), and same-reference returns on unchanged subtrees are preserved. 64/64 offline tests + lint green locally.