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

[ukint-vs]

Closes #1317.

Rework (2026-05-06) — addresses vobradovich's CHANGES_REQUESTED review ("violates self-sufficient service IDL concept"). Aligns this PR with the contract being formalized in #1341: a service IDL is independently distributable; service signatures resolve types from the service's own types plus its extends chain, never from program.types ambient scope. Internal-only API change — TypeResolver and the new resolveNamed/resolveGenerics/substituteGenerics/resolveInService surface stays the same. See the latest commit for details.

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: a single pre-merged Type[]; later entries override earlier ones
  // on name collision (last-write-wins).
  constructor(types: Type[]);

  // Look up a named user Type from this resolver's scope.
  // With concrete generics, returns a substituted concrete Type with type_params stripped.
  resolveNamed(type: TypeDecl): Type | undefined;
  resolveNamed(name: string, generics?: 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.
  resolveGenerics(userType: Type, generics?: TypeDecl[]): Record<string, TypeDecl>;
}

class SailsProgram {
  // Direct AST lookup scoped to a named service. Resolves from the service's own
  // `types` plus the types of every service it extends, transitively. Program-level
  // `types` are NOT in scope (they belong to program/ctor declarations).
  // Backed by a lazy O(1) Map index — safe to call in tight walker loops.
  resolveInService(serviceName: string, typeDecl: TypeDecl): Type | undefined;
}

Per-service TypeResolver instances seeded by SailsProgram.services see only the service's own types plus the transitive extends chain. The chain walk is depth-first with cycle detection; on a pathological A extends B, B extends A graph the constructor throws with the chain in the message. Service-local types shadow base-service types on name collision.

getTypeDeclString was also updated to call the renamed resolveGenerics 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:'generic', 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

24+ tests across the resolver + parser-resolver suites.

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 (raw and concrete-generics paths), returns undefined for primitives/slices/arrays/tuples/unknown names/bare type_params.
• resolveGenerics: zip, no type_params, extra generics truncated.
• Last-write-wins merge: locals override on name collision; registry reflects the last-declared shape.
• Cycle guard (rework): self-cycle (A extends A) and mutual cycle (A extends B, B extends A) throw with the chain reported; diamond inheritance does not throw.

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.
• Self-sufficient contract (rework): a service resolver does NOT see program-level types — resolveInService returns undefined and service.registry.hasType('Shared') is false. Mirrors the JS test added in chore: Clarify service-local IDL type scopes #1341.
• Extends-chain visibility (rework): an extender sees its base service's types through the transitive merge, both via program.resolveInService('Child', ...) and via child.typeResolver.resolveNamed(...).
• Sibling isolation (rework): two services with same-named Packet types resolved through SailsProgram.resolveInService return distinct shapes — no cross-service bleed.
• Envelope<[u8]> → walker feeds struct fields through substituteGenerics + resolveGenerics 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 resolveGenerics 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), and is backed by a lazy Map<serviceName, Map<typeName, Type>> that pre-merges each service's transitive extends scope. O(1) per call after the first invocation.
• 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.
• The extends-chain merge in _collectServiceScopeTypes uses the same visited-set + immutable-copy cycle-guard pattern as _substituteGenerics, 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.

[vobradovich]

Design rationale: self-sufficient service IDL

The ambientTypes plumbing in TypeResolver / SailsService reflects a stricter scoping rule than what the parser permits today as an authoring convenience.
Recording the contract here so the runtime, the codegen, and idl-gen stay consistent over time.

The rule

A service IDL is self-sufficient and independently distributable. A <service>.idl parses, validates, and resolves all of its functions and
events signatures using only its own types {} block (plus primitives and Option / Result / NonZero*).

Cross-scope type references are restricted to:

From → To	Mechanism	Status
Service → its base service's types	extends Base@<interface_id> (types merged into the extender)	implemented
Program ctor → service type	Service::Type qualified syntax	TBD per docs/idl-v2-spec.md lines 419–420
Service → sibling service type	forbidden	enforced by rs/idl-parser-v2/src/post_process.rs::Validator
Service → program type, unqualified	soft-allowed by parser as authoring convenience, NOT a contract	see below

The parser pushes program types into the root scope before validating each service (post_process.rs:32-44). That's a DRY affordance for hand-written multi-service IDLs in a single file.
Generators and the runtime must not rely on it for distributability. A type used by a service S must be present in S.types for S.idl to be parseable on its own.

program.types should not be treated as an ambient scope for every service. The service IDL boundary needs to stay self-contained: a service’s functions/events/throws should be resolvable from that service’s own types plus any explicitly extended service interfaces, not from the enclosing program. extends is a service-to-service dependency keyed by interface_id, so it can be distributed independently from a concrete program. The namespace TBD in the spec is better interpreted in the opposite direction: program/root declarations may eventually reference service-local types via Service::Type, but services should not implicitly see program.types. Otherwise the same service IDL becomes decodable only when bundled with a particular program IDL, which breaks independent service distribution.

[vobradovich]

violates self-sufficient service IDL concept