@pineforge/codegen-pyodide 0.10.0 → 0.10.2

package/pineforge_codegen/analyzer/call_handlers.py

@@ -66,8 +66,9 @@ from __future__ import annotations
 from typing import Any
 
 from ..ast_nodes import (
-    ASTNode, BinOp, BoolLiteral, ExprStmt, FuncCall, Identifier, MemberAccess,
-    NumberLiteral, StringLiteral, Ternary, TupleLiteral, UnaryOp, VarDecl,
+    ASTNode, Assignment, BinOp, BoolLiteral, ExprStmt, FuncCall, Identifier,
+    IfStmt, MemberAccess, NumberLiteral, StringLiteral, Subscript, SwitchStmt,
+    Ternary, TupleLiteral, UnaryOp, VarDecl,
 )
 from ..symbols import PineType
 from .. import signatures as sigs
@@ -89,6 +90,278 @@ class CallHandlers:
     # TA call handling
     # ------------------------------------------------------------------
 
+    def _callsite_primitive_expr_type(
+        self,
+        expr: ASTNode | None,
+        parameter_types: dict[str, PineType],
+    ) -> PineType:
+        """Infer a primitive return using one written call's parameter types.
+
+        The analyzer's legacy ``FuncInfo`` is definition-wide, but Pine's
+        untyped parameters are polymorphic per written call.  Keep this helper
+        intentionally primitive and expression-local: it provides the exact
+        family needed by history-preserving identity/wrapper functions without
+        attempting to monomorphize collections or reference types here.
+        """
+        if expr is None:
+            return PineType.UNKNOWN
+        if isinstance(expr, ExprStmt):
+            return self._callsite_primitive_expr_type(
+                expr.expr, parameter_types
+            )
+        if isinstance(expr, Identifier):
+            if expr.name in parameter_types:
+                return parameter_types[expr.name]
+            if expr.name in {"true", "false"}:
+                return PineType.BOOL
+            return PineType.UNKNOWN
+        if isinstance(expr, Subscript):
+            # Pine's history operator preserves the receiver's scalar family.
+            return self._callsite_primitive_expr_type(
+                expr.object, parameter_types
+            )
+        if isinstance(expr, NumberLiteral):
+            return (
+                PineType.FLOAT
+                if isinstance(expr.value, float)
+                else PineType.INT
+            )
+        if isinstance(expr, BoolLiteral):
+            return PineType.BOOL
+        if isinstance(expr, StringLiteral):
+            return PineType.STRING
+        if isinstance(expr, UnaryOp):
+            if expr.op == "not":
+                return PineType.BOOL
+            return self._callsite_primitive_expr_type(
+                expr.operand, parameter_types
+            )
+        if isinstance(expr, BinOp):
+            left = self._callsite_primitive_expr_type(
+                expr.left, parameter_types
+            )
+            right = self._callsite_primitive_expr_type(
+                expr.right, parameter_types
+            )
+            if expr.op in {"==", "!=", ">", "<", ">=", "<=", "and", "or"}:
+                return PineType.BOOL
+            if left == PineType.STRING or right == PineType.STRING:
+                return PineType.STRING
+            if expr.op == "/" or PineType.FLOAT in {left, right}:
+                return PineType.FLOAT
+            if left == PineType.INT and right == PineType.INT:
+                return PineType.INT
+            return PineType.UNKNOWN
+        if isinstance(expr, Ternary):
+            true_type = self._callsite_primitive_expr_type(
+                expr.true_val, parameter_types
+            )
+            false_type = self._callsite_primitive_expr_type(
+                expr.false_val, parameter_types
+            )
+            if true_type == false_type:
+                return true_type
+            if PineType.STRING in {true_type, false_type}:
+                return PineType.STRING
+            if PineType.FLOAT in {true_type, false_type}:
+                return PineType.FLOAT
+            return PineType.UNKNOWN
+        if isinstance(expr, FuncCall):
+            callee = expr.callee
+            if isinstance(callee, Identifier):
+                if callee.name == "int":
+                    return PineType.INT
+                if callee.name == "float":
+                    return PineType.FLOAT
+                if callee.name == "bool":
+                    return PineType.BOOL
+                # A user callable's definition-wide return cache is not a
+                # call-site fact.  In particular, a pure untyped transform
+                # nested inside a polymorphic history wrapper may have been
+                # analyzed first as FLOAT even when this path carries an
+                # int64 timestamp or bool.  Exact direct-wrapper call edges are
+                # reconciled later; arbitrary nested transforms stay UNKNOWN
+                # and therefore fail closed instead of source-order coercing.
+                return PineType.UNKNOWN
+        return PineType.UNKNOWN
+
+    @staticmethod
+    def _join_callsite_primitive_types(
+        types: list[PineType],
+    ) -> PineType:
+        if not types or PineType.UNKNOWN in types:
+            return PineType.UNKNOWN
+        first = types[0]
+        if all(value == first for value in types):
+            return first
+        if set(types).issubset({PineType.INT, PineType.FLOAT}):
+            return PineType.FLOAT
+        return PineType.UNKNOWN
+
+    def _apply_callsite_local_type_effects(
+        self,
+        stmt: ASTNode,
+        local_types: dict[str, PineType],
+    ) -> None:
+        """Flow one statement's primitive local writes into ``local_types``.
+
+        This is deliberately a small callable-return analysis, not a second
+        semantic analyzer. It exists so a terminal alias such as
+        ``prior = src[1]; prior`` keeps the exact written-call family. Unknown
+        loops/collections remain unknown and cannot silently pick FLOAT.
+        """
+        if isinstance(stmt, VarDecl):
+            hinted = {
+                "int": PineType.INT,
+                "float": PineType.FLOAT,
+                "bool": PineType.BOOL,
+                "string": PineType.STRING,
+                "color": PineType.COLOR,
+            }.get(stmt.type_hint or "", PineType.UNKNOWN)
+            local_types[stmt.name] = (
+                hinted
+                if hinted != PineType.UNKNOWN
+                else self._callsite_primitive_expr_type(
+                    stmt.value, local_types
+                )
+            )
+            return
+        if (
+            isinstance(stmt, Assignment)
+            and isinstance(stmt.target, Identifier)
+        ):
+            rhs = self._callsite_primitive_expr_type(
+                stmt.value, local_types
+            )
+            if stmt.op == ":=":
+                # Pine variables retain their declaration/inferred primitive
+                # family for their lifetime. An ``na``/otherwise unknown
+                # declaration may acquire the first concrete family here.
+                current = local_types.get(
+                    stmt.target.name, PineType.UNKNOWN
+                )
+                local_types[stmt.target.name] = (
+                    current if current != PineType.UNKNOWN else rhs
+                )
+            else:
+                local_types[stmt.target.name] = (
+                    self._join_callsite_primitive_types(
+                        [
+                            local_types.get(
+                                stmt.target.name, PineType.UNKNOWN
+                            ),
+                            rhs,
+                        ]
+                    )
+                )
+            return
+        if isinstance(stmt, IfStmt):
+            before = dict(local_types)
+            branch_envs: list[dict[str, PineType]] = []
+            for body in (stmt.body, stmt.else_body):
+                branch = dict(before)
+                for child in body:
+                    self._apply_callsite_local_type_effects(child, branch)
+                branch_envs.append(branch)
+            all_names = set().union(*(env.keys() for env in branch_envs))
+            for name in all_names:
+                local_types[name] = self._join_callsite_primitive_types(
+                    [
+                        env.get(name, before.get(name, PineType.UNKNOWN))
+                        for env in branch_envs
+                    ]
+                )
+            return
+        if isinstance(stmt, SwitchStmt):
+            before = dict(local_types)
+            bodies = [body for _, body in stmt.cases]
+            if stmt.default_body:
+                bodies.append(stmt.default_body)
+            else:
+                bodies.append([])
+            branch_envs = []
+            for body in bodies:
+                branch = dict(before)
+                for child in body:
+                    self._apply_callsite_local_type_effects(child, branch)
+                branch_envs.append(branch)
+            all_names = set().union(*(env.keys() for env in branch_envs))
+            for name in all_names:
+                local_types[name] = self._join_callsite_primitive_types(
+                    [
+                        env.get(name, before.get(name, PineType.UNKNOWN))
+                        for env in branch_envs
+                    ]
+                )
+
+    def _callsite_body_return_type(
+        self,
+        body: list[ASTNode],
+        parameter_types: dict[str, PineType],
+    ) -> PineType:
+        if not body:
+            return PineType.UNKNOWN
+        local_types = dict(parameter_types)
+        for stmt in body[:-1]:
+            self._apply_callsite_local_type_effects(stmt, local_types)
+        terminal = body[-1]
+        if isinstance(terminal, ExprStmt):
+            terminal = terminal.expr
+        if isinstance(terminal, VarDecl):
+            return self._callsite_primitive_expr_type(
+                terminal.value, local_types
+            )
+        if isinstance(terminal, IfStmt):
+            if not terminal.body:
+                return PineType.UNKNOWN
+            branches = [terminal.body]
+            # A missing else produces contextual ``na`` in Pine and therefore
+            # does not erase the concrete family's type.
+            if terminal.else_body:
+                branches.append(terminal.else_body)
+            return self._join_callsite_primitive_types(
+                [
+                    self._callsite_body_return_type(
+                        branch, dict(local_types)
+                    )
+                    for branch in branches
+                ]
+            )
+        if isinstance(terminal, SwitchStmt):
+            bodies = [case_body for _, case_body in terminal.cases]
+            if terminal.default_body:
+                bodies.append(terminal.default_body)
+            if not bodies:
+                return PineType.UNKNOWN
+            return self._join_callsite_primitive_types(
+                [
+                    self._callsite_body_return_type(
+                        branch, dict(local_types)
+                    )
+                    for branch in bodies
+                ]
+            )
+        return self._callsite_primitive_expr_type(terminal, local_types)
+
+    def _callsite_callable_return_type(
+        self,
+        func_def,
+        param_types: list[PineType],
+        fallback: PineType,
+    ) -> PineType:
+        inferred = self._callsite_body_return_type(
+            func_def.body,
+            {
+                name: (
+                    param_types[index]
+                    if index < len(param_types)
+                    else PineType.UNKNOWN
+                )
+                for index, name in enumerate(func_def.params)
+            },
+        )
+        return inferred if inferred != PineType.UNKNOWN else fallback
+
     def _merge_ta_args(self, func_name: str, node: FuncCall) -> list:
         """Merge positional args and kwargs into a unified positional list."""
         param_names = sigs.get_param_names("ta", func_name)
@@ -316,6 +589,11 @@ class CallHandlers:
 
             returns_tuple = isinstance(expr_node, TupleLiteral)
             tuple_size = len(expr_node.elements) if returns_tuple else 0
+            tuple_element_types = (
+                self._tuple_element_types_by_node.get(id(expr_node), ())
+                if returns_tuple
+                else ()
+            )
             if not returns_tuple and isinstance(expr_node, FuncCall):
                 expr_func = None
                 expr_ns = None
@@ -323,6 +601,37 @@ class CallHandlers:
                         and isinstance(expr_node.callee.object, Identifier)):
                     expr_ns = expr_node.callee.object.name
                     expr_func = expr_node.callee.member
+                elif isinstance(expr_node.callee, Identifier):
+                    expr_func = expr_node.callee.name
+                    if self._func_returns_tuple.get(expr_func, False):
+                        tuple_size = self._func_tuple_element_count.get(expr_func, 0)
+                        tuple_types = self._func_tuple_element_types.get(expr_func, ())
+                        numeric_tuple = (
+                            tuple_size >= 2
+                            and len(tuple_types) == tuple_size
+                            and all(
+                                item in (PineType.INT, PineType.FLOAT)
+                                for item in tuple_types
+                            )
+                        )
+                        bool_tuple = (
+                            tuple_size >= 2
+                            and len(tuple_types) == tuple_size
+                            and all(item == PineType.BOOL for item in tuple_types)
+                        )
+                        if not (numeric_tuple or bool_tuple):
+                            inferred_types = ", ".join(
+                                item.value for item in tuple_types
+                            ) or "unknown"
+                            self._error(
+                                "request.security tuple-return helpers support two or more "
+                                "numeric int/float elements or homogeneous bool elements; inferred "
+                                f"{tuple_size} element(s) [{inferred_types}]",
+                                expr_node.loc,
+                            )
+                        else:
+                            returns_tuple = True
+                            tuple_element_types = tuple_types
                 if expr_ns == "ta":
                     if expr_func == "vwap":
                         merged_v = list(expr_node.args)
@@ -351,12 +660,15 @@ class CallHandlers:
             # so the codegen can resolve a parameter ``tf`` via the call sites.
             scope_name = self._symbols.current_scope.name
             containing_func = scope_name[5:] if scope_name.startswith("func_") else ""
+            if returns_tuple and tuple_element_types:
+                self._tuple_element_types_by_node[id(node)] = tuple_element_types
             self._security_calls.append(SecurityCallInfo(
                 sec_id=sec_id,
                 timeframe=tf_node,
                 expression=expr_node,
                 returns_tuple=returns_tuple,
                 tuple_size=tuple_size,
+                tuple_element_types=tuple_element_types,
                 gaps=gaps_node,
                 lookahead=lookahead_node,
                 ta_range=security_ta_range,
@@ -902,7 +1214,10 @@ class CallHandlers:
 
     def _materialize_user_func_call_site_state(
             self, func_name: str, cs_idx: int, node: FuncCall,
-            *, reuse_existing_owner: str | None = None) -> None:
+            *, reuse_existing_owner: str | None = None,
+            reuse_existing_targets: dict[int, int] | None = None,
+            ta_site_indices: list[int] | None = None,
+            materialize_fixnan: bool = True) -> dict[int, int]:
         """Materialize TA/fixnan state for one UDF call-site variant.
 
         Ordinary call sites are handled while walking the AST.  A second class
@@ -918,17 +1233,71 @@ class CallHandlers:
         ``{member}_cs{idx}`` clone for the borrowed callee site; when that clone
         belongs to the parent currently being propagated, it is the desired
         call-path state and must be reused rather than duplicated under a
-        disambiguated-but-unused name.
+        disambiguated-but-unused name. ``reuse_existing_targets`` maps each
+        source TA identity to the immediate parent's already-resolved target;
+        this extends the proof through another borrowed layer even when clone
+        name collisions forced a disambiguating suffix.
         """
-        func_def = self._func_defs[func_name]
+        func_def = self._func_defs.get(func_name)
+        method_info = None
+        if func_def is None:
+            method_info = next(
+                (
+                    info
+                    for info in self._func_infos
+                    if info.name == func_name
+                    and getattr(info, "is_udt_method", False)
+                ),
+                None,
+            )
+            if method_info is not None:
+                func_def = method_info.node
+        if func_def is None:
+            self._error(
+                f"Cannot materialize callable state for unknown function '{func_name}'.",
+                node.loc,
+            )
+            return {}
+
+        selected_ta_indices: dict[int, int] = {}
 
         param_arg_map: dict[str, str] = {}
+        if (
+            method_info is not None
+            and isinstance(node.callee, MemberAccess)
+            and func_name in self._method_signatures
+        ):
+            binding = self._bind_typed_method_call(func_name, node)
+            positional_args = [node.callee.object, *binding.args_by_param]
+        else:
+            positional_args = list(node.args)
+            if (
+                method_info is not None
+                and isinstance(node.callee, MemberAccess)
+            ):
+                positional_args.insert(0, node.callee.object)
         for p_idx, param_name in enumerate(func_def.params):
-            if p_idx < len(node.args):
-                param_arg_map[param_name] = self._expr_to_str(node.args[p_idx])
+            if p_idx < len(positional_args):
+                param_arg_map[param_name] = self._expr_to_str(
+                    positional_args[p_idx]
+                )
+            elif param_name in node.kwargs:
+                param_arg_map[param_name] = self._expr_to_str(
+                    node.kwargs[param_name]
+                )
 
         if func_name in self._func_ta_ranges:
             start, end = self._func_ta_ranges[func_name]
+            site_indices = (
+                list(ta_site_indices)
+                if ta_site_indices is not None
+                else list(self._func_ta_indices.get(func_name, ()))
+            )
+            if ta_site_indices is None and not site_indices:
+                site_indices = list(range(start, end))
+            func_ctor_templates = self._func_ta_ctor_args.setdefault(
+                func_name, {}
+            )
 
             # Map local derived length variables back to expressions over the
             # function's parameters before substituting call-site arguments.
@@ -966,46 +1335,105 @@ class CallHandlers:
             if cs_idx == 0:
                 # cs0 owns the source-level sites. Preserve their parameterized
                 # ctor args for every later direct or inherited clone.
-                for i in range(start, end):
+                for i in site_indices:
                     site = self._ta_call_sites[i]
                     if not hasattr(site, '_orig_ctor_args'):
                         site._orig_ctor_args = [
                             _expand_locals(arg) for arg in site.ctor_args
                         ]
+                    # Each callable owns its own view of a borrowed site's
+                    # constructor expression. Expand locals in that owner view
+                    # before substituting actual parameters; a template first
+                    # recorded at definition time can still contain a local
+                    # alias such as ``effectiveLen``.
+                    func_ctor_templates[i] = [
+                        _expand_locals(arg)
+                        for arg in func_ctor_templates.get(
+                            i, site._orig_ctor_args
+                        )
+                    ]
                     site.ctor_args = [
                         _subst_params(arg, param_arg_map)
-                        for arg in site._orig_ctor_args
+                        for arg in func_ctor_templates[i]
                     ]
-                    # If a ctor is now expressed in an enclosing UDF's params,
-                    # retain that expression so the enclosing call can resolve
-                    # it and widen the enclosing TA range as before.
+                    selected_ta_indices[i] = i
                     if enclosing_params and self._nested_ta_touched is not None:
                         for arg in site.ctor_args:
                             tokens = set(_re.findall(
                                 r"[A-Za-z_][A-Za-z_0-9]*", arg))
                             if tokens & enclosing_params:
-                                site._orig_ctor_args = list(site.ctor_args)
-                                self._nested_ta_touched.add(i)
+                                if self._enclosing_func_names:
+                                    caller = self._enclosing_func_names[-1]
+                                    self._func_ta_ctor_args.setdefault(
+                                        caller, {}
+                                    )[i] = list(site.ctor_args)
                                 break
             else:
                 clone_name_map: dict[str, str] = {}
-                for i in range(start, end):
+                for i in site_indices:
                     orig = self._ta_call_sites[i]
-                    orig_args = getattr(orig, '_orig_ctor_args', orig.ctor_args)
+                    if not hasattr(orig, '_orig_ctor_args'):
+                        orig._orig_ctor_args = [
+                            _expand_locals(arg) for arg in orig.ctor_args
+                        ]
+                    func_ctor_templates[i] = [
+                        _expand_locals(arg)
+                        for arg in func_ctor_templates.get(
+                            i, orig._orig_ctor_args
+                        )
+                    ]
+                    orig_args = func_ctor_templates[i]
                     resolved_ctor = [
                         _subst_params(arg, param_arg_map) for arg in orig_args
                     ]
+                    reuse_target = (
+                        reuse_existing_targets.get(i)
+                        if reuse_existing_targets is not None
+                        else None
+                    )
+                    if reuse_target is not None:
+                        # The parent's active clone already resolved this
+                        # exact source identity through the next outer call
+                        # boundary. Reuse it directly; do not overwrite its
+                        # concrete constructor with this edge's still-local
+                        # parameter spelling.
+                        selected_ta_indices[i] = reuse_target
+                        target_name = self._ta_call_sites[
+                            reuse_target
+                        ].member_name
+                        default_name = f"{orig.member_name}_cs{cs_idx}"
+                        if target_name != default_name:
+                            clone_name_map[orig.member_name] = target_name
+                        continue
+                    existing_target = self._func_ta_call_targets.get(
+                        (id(node), cs_idx), {}
+                    ).get(i)
+                    if existing_target is not None:
+                        self._ta_call_sites[existing_target].ctor_args = resolved_ctor
+                        selected_ta_indices[i] = existing_target
+                        continue
                     clone_name = f"{orig.member_name}_cs{cs_idx}"
-                    existing = next(
-                        (site for site in self._ta_call_sites
-                         if site.member_name == clone_name),
+                    existing_pair = next(
+                        (
+                            (index, site)
+                            for index, site in enumerate(self._ta_call_sites)
+                            if site.member_name == clone_name
+                        ),
                         None,
                     )
-                    if (reuse_existing_owner is not None
-                            and existing is not None
-                            and existing.owner_func == reuse_existing_owner):
+                    if (
+                        existing_pair is not None
+                        and (
+                            (
+                                reuse_existing_owner is not None
+                                and existing_pair[1].owner_func
+                                == reuse_existing_owner
+                            )
+                        )
+                    ):
                         # The active parent's widened range already made the
                         # exact member this inherited callee variant needs.
+                        selected_ta_indices[i] = existing_pair[0]
                         continue
                     if clone_name in self._ta_member_names:
                         base = clone_name
@@ -1024,15 +1452,36 @@ class CallHandlers:
                         is_static=orig.is_static,
                         owner_func=func_name,
                     )
+                    selected_ta_indices[i] = len(self._ta_call_sites)
                     self._ta_call_sites.append(cloned)
                     self._ta_member_names.add(clone_name)
                 if clone_name_map:
                     self._func_cs_ta_clone_names[(func_name, cs_idx)] = clone_name_map
 
+            # A nested stateful helper belongs to the enclosing callable's
+            # call path even when its constructor has no forwarded parameters
+            # (``ta.change`` is the canonical example). Constructor-template
+            # forwarding above is intentionally narrower: it only rewrites
+            # expressions that reference enclosing parameters. Keep state
+            # ownership independent from that substitution test so every
+            # written parent call site receives its exact borrowed TA targets.
+            if self._nested_ta_touched is not None:
+                self._nested_ta_touched.update(selected_ta_indices.values())
+
+            call_targets = self._func_ta_call_targets.setdefault(
+                (id(node), cs_idx), {}
+            )
+            call_targets.update(selected_ta_indices)
+            call_templates = self._func_ta_call_templates.setdefault(id(node), {})
+            for index in site_indices:
+                template = func_ctor_templates.get(index)
+                if template is not None:
+                    call_templates[index] = tuple(template)
+
         # fixnan is stateful for the same reason as a rolling TA reducer: each
         # emitted function variant needs its own previous-value member.
         fn_indices = self._func_fixnan_indices.get(func_name, [])
-        if cs_idx > 0 and fn_indices:
+        if materialize_fixnan and cs_idx > 0 and fn_indices:
             clone_map: dict[str, str] = {}
             for fi in fn_indices:
                 orig = self._fixnan_sites[fi]
@@ -1064,19 +1513,75 @@ class CallHandlers:
             if clone_map:
                 self._func_cs_fixnan_clone_names[(func_name, cs_idx)] = clone_map
 
+        return selected_ta_indices
+
     def _handle_user_func_call(self, func_name: str, node: FuncCall) -> PineType:
         """Handle calls to user-defined functions."""
         func_def = self._func_defs[func_name]
 
-        # Visit the call args
-        arg_types = []
+        # Visit every supplied argument in Pine source order, then bind both
+        # positional and keyword forms into declaration order.  The old
+        # positional-only path skipped kwargs entirely, hiding nested calls and
+        # leaving deferred map-history validation without a concrete TypeSpec.
+        bound_args = self._bind_callable_args(node, list(func_def.params))
+        visited_types: dict[int, PineType] = {}
         for arg in node.args:
-            arg_types.append(self._visit(arg))
+            visited_types[id(arg)] = self._visit(arg)
+        for arg in node.kwargs.values():
+            visited_types[id(arg)] = self._visit(arg)
+
+        param_types = [
+            visited_types.get(id(arg), PineType.UNKNOWN)
+            if arg is not None
+            else PineType.UNKNOWN
+            for arg in bound_args
+        ]
+        declared_specs = list(
+            self._func_param_type_specs.get(func_name, ())
+        )
+        effective_param_types = [
+            (
+                self._primitive_pine_type_from_spec(declared_specs[index])
+                if index < len(declared_specs)
+                and self._primitive_pine_type_from_spec(
+                    declared_specs[index]
+                ) != PineType.UNKNOWN
+                else param_type
+            )
+            for index, param_type in enumerate(param_types)
+        ]
+        self._callable_bound_param_types_by_node[id(node)] = list(
+            effective_param_types
+        )
 
-        # Determine param types from call-site args
-        param_types = arg_types[:len(func_def.params)]
-        while len(param_types) < len(func_def.params):
-            param_types.append(PineType.UNKNOWN)
+        # Per-param TypeSpec: declared hints are authoritative; for untyped
+        # params, infer from this call site's argument.  Validate deferred
+        # history receivers before series propagation/cloning can reinterpret
+        # a map handle (or map-bearing UDT) as ``Series<double>``.
+        param_specs = list(
+            getattr(self, "_func_param_type_specs", {}).get(func_name)
+            or self._param_type_specs_from_def(func_def)
+        )
+        arg_specs = [
+            self._type_spec_from_expr(arg) if arg is not None else None
+            for arg in bound_args
+        ]
+        for i in range(len(param_specs)):
+            if param_specs[i] is None and i < len(arg_specs):
+                param_specs[i] = arg_specs[i]
+        self._record_deferred_param_call_edge(
+            node,
+            func_name,
+            list(func_def.params),
+            bound_args,
+        )
+        self._validate_deferred_param_history_refs(
+            func_name,
+            {
+                name: spec
+                for name, spec in zip(func_def.params, param_specs)
+            },
+        )
 
         # Determine return type: re-analyze the function body with known param types
         # For now, use the cached return type from initial analysis
@@ -1105,14 +1610,24 @@ class CallHandlers:
                             return_type = PineType.FLOAT
                         break
 
+        # History and other primitive operations preserve an untyped
+        # parameter's family independently at each written call.  Do this
+        # before the legacy FuncInfo merge so the first call cannot dictate
+        # every later call's return type.
+        return_type = self._callsite_callable_return_type(
+            func_def, effective_param_types, return_type
+        )
+
         # If this function has series params, ensure bar-field arguments
         # passed at the call site are registered as series_bar_fields so that
         # the codegen can create Series<double> members for them.
         func_sv = self._func_series_vars.get(func_name, set())
         if func_sv:
             for p_idx, param_name in enumerate(func_def.params):
-                if param_name in func_sv and p_idx < len(node.args):
-                    arg = node.args[p_idx]
+                if param_name in func_sv and p_idx < len(bound_args):
+                    arg = bound_args[p_idx]
+                    if arg is None:
+                        continue
                     if isinstance(arg, Identifier) and arg.name in BAR_FIELDS:
                         self._series_bar_fields.add(arg.name)
                     elif isinstance(arg, Identifier):
@@ -1126,6 +1641,29 @@ class CallHandlers:
                                 caller_name = sym.scope[5:]
                                 self._func_series_vars.setdefault(caller_name, set()).add(arg.name)
                             else:
+                                # Keep the exact declaration/member registries
+                                # in lockstep with the legacy raw-name series
+                                # promotion.  Codegen uses those identities to
+                                # distinguish the real global binding from a
+                                # same-named lexical scalar tombstone.
+                                exact_member = getattr(
+                                    sym, "_pf_var_member_name", None
+                                )
+                                if exact_member is not None:
+                                    self._series_var_members.add(exact_member)
+                                decl_node_id = getattr(
+                                    sym, "_pf_decl_node_id", None
+                                )
+                                if decl_node_id is not None:
+                                    self._series_decl_nodes.add(decl_node_id)
+                                    binding_name = getattr(
+                                        sym,
+                                        "_pf_decl_binding_name",
+                                        arg.name,
+                                    )
+                                    self._series_decl_bindings.add(
+                                        (decl_node_id, binding_name)
+                                    )
                                 self._series_vars.add(arg.name)
 
         # Per-call-site cloning: TA, series/var, and fixnan state all advance
@@ -1134,10 +1672,25 @@ class CallHandlers:
         has_series = func_name in self._func_series_vars or func_name in self._func_var_members
         has_fixnan = func_name in self._func_fixnan_indices
         if has_ta or has_series or has_fixnan:
-            cs_idx = self._func_call_site_count.get(func_name, 0)
-            self._func_call_site_count[func_name] = cs_idx + 1
-            self._func_call_cs_map[id(node)] = (func_name, cs_idx)
-            self._materialize_user_func_call_site_state(func_name, cs_idx, node)
+            existing_site = self._func_call_cs_map.get(id(node))
+            if existing_site is None or existing_site[0] != func_name:
+                # Type/return inference may revisit the same FuncCall AST node
+                # several times.  It is still one Pine textual call site, not
+                # a new state instance on every analyzer pass.  Real caller
+                # clones are expanded later by _propagate_call_site_counts().
+                cs_idx = self._func_call_site_count.get(func_name, 0)
+                self._func_call_site_count[func_name] = cs_idx + 1
+                self._func_call_cs_map[id(node)] = (func_name, cs_idx)
+                self._materialize_user_func_call_site_state(
+                    func_name, cs_idx, node
+                )
+            callsite = self._func_call_cs_map.get(id(node))
+            if callsite is not None and callsite[0] == func_name:
+                key = (func_name, callsite[1])
+                self._func_callsite_param_types[key] = list(
+                    effective_param_types
+                )
+                self._func_callsite_return_types[key] = return_type
 
         # Create or update FuncInfo
         is_tuple = self._func_returns_tuple.get(func_name, False)
@@ -1145,19 +1698,64 @@ class CallHandlers:
         # Forward UDT-return inference (set in _visit_FuncDef) so codegen can
         # emit the struct return type. Probe: udt-method-probe-20.
         udt_ret = self._func_udt_return_types.get(func_name)
+        existing = [fi for fi in self._func_infos if fi.name == func_name]
+
+        # A direct terminal map call on an untyped parameter cannot be typed
+        # while the function definition is first visited: its map TypeSpec is
+        # learned only here, from the call-site argument. Re-run only the
+        # terminal-map classifier with those established parameter specs; do
+        # not re-analyze the body or participate in general return inference.
+        effective_param_specs = list(param_specs)
+        if existing and existing[0].param_type_specs:
+            for i, spec in enumerate(existing[0].param_type_specs):
+                if i < len(effective_param_specs) and spec is not None:
+                    effective_param_specs[i] = spec
+        terminal_map_return = self._terminal_map_call_return(
+            self._direct_terminal_return_expr(func_def),
+            {
+                name: spec
+                for name, spec in zip(func_def.params, effective_param_specs)
+            },
+        )
         ret_spec = getattr(self, "_func_return_type_specs", {}).get(func_name)
-        # Per-param TypeSpec: declared hints are authoritative; for untyped
-        # params, infer from the call-site argument's type_spec (so an untyped
-        # ``s`` used as a string, or a UDT passed by value, emits correctly).
-        param_specs = list(
-            getattr(self, "_func_param_type_specs", {}).get(func_name)
-            or self._param_type_specs_from_def(func_def)
+        terminal_expr = self._direct_terminal_return_expr(func_def)
+        terminal_selection_spec = self._terminal_map_selection_return_spec(
+            terminal_expr,
+            {
+                name: spec
+                for name, spec in zip(
+                    func_def.params, effective_param_specs
+                )
+            },
         )
-        arg_specs = [self._type_spec_from_expr(arg) for arg in node.args]
-        for i in range(len(param_specs)):
-            if param_specs[i] is None and i < len(arg_specs):
-                param_specs[i] = arg_specs[i]
-        existing = [fi for fi in self._func_infos if fi.name == func_name]
+        if (
+            terminal_map_return is None
+            and isinstance(terminal_expr, Identifier)
+            and terminal_expr.name in func_def.params
+        ):
+            terminal_index = func_def.params.index(terminal_expr.name)
+            terminal_identity_spec = (
+                effective_param_specs[terminal_index]
+                if terminal_index < len(effective_param_specs)
+                else None
+            )
+            if (terminal_identity_spec is not None
+                    and terminal_identity_spec.kind == "map"):
+                # An untyped identity UDF learns the map handle type from its
+                # call site. The handle is returned by value, preserving the
+                # backing ID rather than cloning map contents.
+                self._func_return_type_specs[func_name] = terminal_identity_spec
+                ret_spec = terminal_identity_spec
+        if terminal_selection_spec is not None:
+            self._func_return_type_specs[func_name] = terminal_selection_spec
+            ret_spec = terminal_selection_spec
+        if terminal_map_return is not None:
+            return_type, inferred_ret_spec = terminal_map_return
+            self._func_return_types[func_name] = return_type
+            if inferred_ret_spec is not None:
+                self._func_return_type_specs[func_name] = inferred_ret_spec
+                ret_spec = inferred_ret_spec
+
         if not existing:
             fi = FuncInfo(
                 name=func_name,
@@ -1174,7 +1772,10 @@ class CallHandlers:
         else:
             # Update with better type info if available
             fi = existing[0]
-            if fi.return_type in (PineType.UNKNOWN, PineType.VOID) and return_type not in (PineType.UNKNOWN, PineType.VOID):
+            if terminal_map_return is not None:
+                fi.return_type = return_type
+                fi.return_type_spec = ret_spec
+            elif fi.return_type in (PineType.UNKNOWN, PineType.VOID) and return_type not in (PineType.UNKNOWN, PineType.VOID):
                 fi.return_type = return_type
             for i, pt in enumerate(param_types):
                 if i < len(fi.param_types) and fi.param_types[i] == PineType.UNKNOWN:
@@ -1192,4 +1793,17 @@ class CallHandlers:
             if fi.return_type_spec is None and ret_spec is not None:
                 fi.return_type_spec = ret_spec
 
+        # A concrete map can arrive only at an outer wrapper's eventual call
+        # site, after every nested untyped UDF was initially analyzed with
+        # scalar fallbacks.  Propagate the concrete specs through the exact
+        # definition-time call edges and infer returns in post-order before
+        # codegen snapshots the FuncInfo table.
+        self._propagate_deferred_map_callable_specs(
+            func_name,
+            {
+                name: spec
+                for name, spec in zip(func_def.params, param_specs)
+            },
+        )
+
         return return_type