@pineforge/codegen-pyodide 1.0.0 → 1.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pineforge/codegen-pyodide",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Gate-validated Pyodide payload for the PineScript v6 -> C++ transpiler: archive (run in Pyodide), unpacked source, introspected tables, and release metadata.",
   "type": "module",
   "main": "index.mjs",

package/pineforge_codegen/analyzer/base.py

@@ -32,6 +32,10 @@ from ..errors import SourceLocation, Diagnostic, CompileError, Level, Phase
 from ..limits import TimeBudget, iter_ast_nodes
 from ..security_contexts import PASS_WARNINGS_ANNOTATION, context_key, reads_bar_series
 from ..session_reads import emitted_session_reads
+from ..collection_history import (
+    COLLECTION_HISTORY_ANNOTATION, LEGACY, REFUSED, SUPPORTED,
+    CollectionHistoryChecker, HistoryRead,
+)
 from ..method_binding import (
     BoundMethodArgs,
     MethodBindError,
@@ -431,6 +435,13 @@ class Analyzer(CallHandlers, DiagnosticsHelper, TypeHelper):
         # pass can tell borrowed clones apart from a dead function's own
         # sites (see contracts.TACallSite.owner_func).
         self._enclosing_func_names: list[str] = []
+        # Array and matrix history reads (``a[1]``), each decided where the
+        # visit meets it (pineforge_codegen/collection_history.py), and the
+        # declarations writing each class member, by name (a sibling block's
+        # declaration closes another one's history).
+        self._collection_history_reads: list[HistoryRead] = []
+        self._collection_history_checker: CollectionHistoryChecker | None = None
+        self._member_writer_decls: dict[str, set[int]] = {}
         # Exact TA targets borrowed through nested callable edges while visiting
         # the current callable body. Constructor templates are tracked
         # separately in ``_func_ta_ctor_args`` because state ownership also
@@ -552,6 +563,7 @@ class Analyzer(CallHandlers, DiagnosticsHelper, TypeHelper):
         self._ensure_pine_v6()
         self._check_direct_terminal_array_element_callee_shadows()
         self._visit(self._ast)
+        collection_history = self._check_collection_history()
         self._check_direct_terminal_array_temporary_cycles()
         self._register_resolved_direct_terminal_array_forward_calls()
         self._refresh_direct_terminal_array_temporary_returns()
@@ -652,6 +664,7 @@ class Analyzer(CallHandlers, DiagnosticsHelper, TypeHelper):
                 for owner, names in self._func_var_storage_names.items()
             },
             func_series_vars=self._func_series_vars,
+            collection_history=collection_history,
             func_global_history_reads={
                 owner: list(names)
                 for owner, names in self._func_global_history_reads.items()
@@ -4345,6 +4358,7 @@ class Analyzer(CallHandlers, DiagnosticsHelper, TypeHelper):
         self._symbols.define(sym)
         setattr(sym, "_pf_decl_node_id", id(node))
         setattr(sym, "_pf_decl_binding_name", node.name)
+        self._note_member_writer(sym, node.name, node)
         if (type_spec is None
                 and self._collection_scope_stack
                 and self._block_node_stack
@@ -4647,6 +4661,7 @@ class Analyzer(CallHandlers, DiagnosticsHelper, TypeHelper):
             self._symbols.define(sym)
             setattr(sym, "_pf_decl_node_id", id(node))
             setattr(sym, "_pf_decl_binding_name", name)
+            self._note_member_writer(sym, name, node)
 
             if (self._collection_scope_stack
                     and self._block_node_stack
@@ -6174,6 +6189,19 @@ class Analyzer(CallHandlers, DiagnosticsHelper, TypeHelper):
             if self._type_spec_contains_map(object_spec):
                 assert object_spec is not None
                 self._reject_unsupported_map_history(object_spec, node)
+            if (object_spec is not None
+                    and object_spec.kind in ("array", "matrix")):
+                # A parameter given an array or a matrix: its history is a
+                # parameter's, which PineForge does not keep; the earlier
+                # lowering stays where it compiled (collection_history.py).
+                # A selection of one is an expression's history.
+                checker = self._history_checker()
+                if isinstance(node.object, Identifier):
+                    decision = checker.decide_parameter_history(node, object_spec)
+                    if decision.outcome == REFUSED:
+                        self._collection_history_raise(decision, node)
+                else:
+                    self._refuse_collection_expression_history(node, object_spec)
 
         # Propagate concrete caller specs through wrapper calls.  Each edge is
         # identity-keyed from the definition pass, so a local that shadows a
@@ -6428,8 +6456,10 @@ class Analyzer(CallHandlers, DiagnosticsHelper, TypeHelper):
     def _visit_Subscript(self, node: Subscript) -> PineType:
         obj_type = self._visit(node.object)
         self._visit(node.index)
+        self._refuse_collection_field_history(node)
 
         object_spec = self._history_receiver_type_spec(node.object)
+        self._refuse_collection_expression_history(node, object_spec)
         if self._type_spec_contains_map(object_spec):
             assert object_spec is not None
             self._reject_unsupported_map_history(object_spec, node)
@@ -6461,7 +6491,17 @@ class Analyzer(CallHandlers, DiagnosticsHelper, TypeHelper):
                             "Series buffer for that binding.",
                             node.loc,
                         )
-                    if getattr(sym, "type_spec", None) is None or sym.type_spec.kind not in ("array", "map"):
+                    # An array's or a matrix's history: copies kept beside
+                    # the variable, not a Series of it (collection_history.py);
+                    # a legacy matrix parameter's read keeps the registration
+                    # below, as it had.
+                    keeps_series = not (
+                        getattr(sym, "type_spec", None) is not None
+                        and sym.type_spec.kind in ("array", "matrix")
+                        and not self._note_collection_history_read(node, name, sym)
+                    )
+                    if keeps_series and (getattr(sym, "type_spec", None) is None
+                                         or sym.type_spec.kind not in ("array", "map")):
                         exact_member = getattr(sym, "_pf_var_member_name", None)
                         if exact_member is not None:
                             self._series_var_members.add(exact_member)
@@ -6510,6 +6550,150 @@ class Analyzer(CallHandlers, DiagnosticsHelper, TypeHelper):
 
         return obj_type
 
+    def _refuse_collection_field_history(self, node: Subscript) -> None:
+        """The history of an object's array, matrix or map field: TradingView
+        refuses ``h.xs[1]`` and ``(h.xs)[1]`` alike ("Cannot use the
+        history-referencing operator on fields of user-defined types",
+        CE10290: fixtures/array_history_tv ahist_field_noparen,
+        ahist_field_paren, ahist_mfield) and takes ``(h[1]).xs``. The C++
+        indexed the field's current collection."""
+        field = node.object
+        if not isinstance(field, MemberAccess):
+            return
+        owner = self._history_receiver_type_spec(field.object)
+        if (owner is None or owner.kind != "udt"
+                or owner.name not in self._udt_fields):
+            return
+        spec = (self._udt_field_type_specs.get(owner.name) or {}).get(field.member)
+        if spec is None or spec.kind not in ("array", "matrix", "map"):
+            return
+        receiver = (field.object.name if isinstance(field.object, Identifier)
+                    else "object")
+        raise CompileError([Diagnostic(
+            level=Level.ERROR,
+            phase=Phase.ANALYZER,
+            location=node.loc or SourceLocation(self._filename, 1, 1, 1),
+            message=(f"{receiver}.{field.member}[...]: TradingView refuses the "
+                     "history-referencing operator on fields of user-defined "
+                     "types (CE10290)."),
+            hint=(f"Read the field of the object's history: "
+                  f"({receiver}[1]).{field.member}."),
+        )])
+
+    def _history_checker(self) -> CollectionHistoryChecker:
+        """The script's array and matrix history checker, built when the
+        visit first meets such a read."""
+        if self._collection_history_checker is None:
+            self._collection_history_checker = CollectionHistoryChecker(
+                self._ast, self._collection_history_name_kind)
+        return self._collection_history_checker
+
+    def _collection_history_name_kind(self, name: str) -> str | None:
+        """``array`` / ``matrix`` / ``map`` / ``scalar`` for a script
+        variable, else None (collection_history.CollectionHistoryChecker)."""
+        sym = self._symbols.global_scope.symbols.get(name)
+        if sym is None:
+            return None
+        spec = getattr(sym, "type_spec", None)
+        if spec is not None and spec.kind in ("array", "matrix", "map"):
+            return spec.kind
+        if sym.pine_type in (PineType.INT, PineType.FLOAT, PineType.BOOL,
+                             PineType.STRING, PineType.COLOR):
+            return "scalar"
+        return None
+
+    def _note_member_writer(self, sym, name: str, node) -> None:
+        """A declaration writing the class member of its name (the script's
+        top level and its blocks): a sibling block's declaration of the name
+        closes another one's array history before it writes
+        (codegen/collection_history.py)."""
+        if sym.scope == "global":
+            self._member_writer_decls.setdefault(name, set()).add(id(node))
+
+    def _collection_history_raise(self, decision, node) -> None:
+        raise CompileError([Diagnostic(
+            level=Level.ERROR,
+            phase=Phase.ANALYZER,
+            location=(getattr(decision.node, "loc", None) or node.loc
+                      or SourceLocation(self._filename, 1, 1, 1)),
+            message=decision.message,
+            hint=decision.hint,
+        )])
+
+    def _refuse_collection_expression_history(self, node: Subscript, spec) -> None:
+        """The history of an expression whose value is an array or a matrix
+        (a call's result, a selection): TradingView reads the copy the
+        expression produced k executions back (fixtures/array_history_tv
+        ahist_fn ``c1``), which PineForge does not keep. A use whose earlier
+        lowering compiled keeps it; one only a collection fits never compiled
+        and is refused (collection_history.py)."""
+        if (isinstance(node.object, Identifier) or spec is None
+                or spec.kind not in ("array", "matrix")):
+            return
+        checker = self._history_checker()
+        decided = checker.decision_for(node) is not None
+        decision = checker.decide_expression(node, spec)
+        if decision.outcome == REFUSED:
+            self._collection_history_raise(decision, node)
+        if decision.outcome == LEGACY and decision.use == "element" and not decided:
+            self._warn(
+                "(...)[...] reads an element of the selected current array in "
+                "PineForge: no history of a selection is kept, where TradingView "
+                "reads the array it selected that many bars back.",
+                node.loc,
+            )
+
+    def _note_collection_history_read(self, node: Subscript, name: str, sym) -> bool:
+        """Decide ``a[k]`` of an array or a matrix variable
+        (collection_history.py): annotate a supported read, refuse a refused
+        one, and keep a legacy one's earlier lowering. True where that
+        lowering registered a series (a matrix parameter's), which the caller
+        then does as it did."""
+        decl_node_id = getattr(sym, "_pf_decl_node_id", None)
+        read = HistoryRead(
+            node=node,
+            name=name,
+            kind=sym.type_spec.kind,
+            spec=sym.type_spec,
+            in_callable=bool(self._enclosing_func_names),
+            is_parameter=sym.scope != "global" and decl_node_id is None,
+            is_global=sym.scope == "global",
+            is_var=bool(sym.is_var),
+            decl_node_id=decl_node_id,
+            scope_name=sym.scope or "",
+        )
+        decision = self._history_checker().decide(read)
+        if node.annotations and COLLECTION_HISTORY_ANNOTATION in node.annotations:
+            node.annotations = dict(node.annotations)
+            del node.annotations[COLLECTION_HISTORY_ANNOTATION]
+        if decision.outcome == REFUSED:
+            self._collection_history_raise(decision, node)
+        if decision.outcome == SUPPORTED:
+            node.annotations = dict(node.annotations or {})
+            node.annotations[COLLECTION_HISTORY_ANNOTATION] = {
+                "var": name, "kind": read.kind, "use": decision.use,
+                "spec": read.spec, "member": None,
+            }
+            if not any(r.node is node for r in self._collection_history_reads[-1:]):
+                self._collection_history_reads.append(read)
+            return False
+        return decision.outcome == LEGACY and decision.use == "series"
+
+    def _collection_history_is_supported(self, node: Subscript) -> bool:
+        """Whether the checker supports the history read ``node`` (decided
+        where the visit met it; a read not met yet keeps its old typing)."""
+        checker = self._collection_history_checker
+        decision = checker.decision_for(node) if checker is not None else None
+        return decision is not None and decision.outcome == SUPPORTED
+
+    def _check_collection_history(self) -> dict:
+        """The declarations whose history the supported reads need, keyed
+        by their members (pineforge_codegen/collection_history.py)."""
+        if not self._collection_history_reads:
+            return {}
+        return self._history_checker().history_variables(
+            self._collection_history_reads, self._member_writer_decls)
+
     def _note_function_global_history_read(
             self, node: Subscript, name: str, sym) -> None:
         """Record ``x[k]`` in a plain UDF body on a script variable.
@@ -6807,6 +6991,10 @@ class Analyzer(CallHandlers, DiagnosticsHelper, TypeHelper):
             if owner_spec is not None and owner_spec.kind == "udt" and owner_spec.name:
                 field_spec = (self._udt_field_type_specs.get(owner_spec.name) or {}).get(node.member)
                 if field_spec is not None:
+                    # The receiver is read too: ``(o[1]).inner.v`` reads the
+                    # history of ``o`` (fixtures/udt_history_tv udth_ref),
+                    # which only its visit registers.
+                    self._visit(node.object)
                     return self._type_hint_to_pine(str(field_spec))
             self._visit(node.object)
             # strategy.closedtrades.* and strategy.opentrades.* return types

package/pineforge_codegen/analyzer/contracts.py

@@ -337,6 +337,9 @@ class AnalyzerContext:
     # per read. TradingView keeps that history per call site, so codegen gives
     # each emitted body its own chart-clocked buffer of the variable.
     func_global_history_reads: dict = field(default_factory=dict)
+    # Array and matrix variables whose history the script reads, by name
+    # (pineforge_codegen/collection_history.py HistoryVariable).
+    collection_history: dict = field(default_factory=dict)
     func_global_history_nodes: dict = field(default_factory=dict)
     # FuncDef owner -> declaration-bound non-persistent history-local names.
     # Parameters are deliberately excluded so a same-named qualified

package/pineforge_codegen/analyzer/types.py

@@ -347,14 +347,25 @@ class TypeHelper:
         if isinstance(value, Subscript):
             # Pine's history operator preserves the value type: a
             # ``Series<line>`` read such as ``h[1]`` is a scalar ``line``
-            # handle, not the legacy numeric fallback.  Keep this refinement
-            # drawing-only; collection subscripts have separate array/map
-            # semantics and primitive history inference already flows through
-            # PineType in ``_visit_Subscript``.
+            # handle and ``c[1]`` of a user-defined object the reference ``c``
+            # held (fixtures/udt_history_tv), not the legacy numeric fallback.
+            # Collection subscripts have separate array/map semantics and
+            # primitive history inference already flows through PineType in
+            # ``_visit_Subscript``.
             receiver_spec = self._type_spec_from_expr(value.object)
             if (receiver_spec is not None
                     and receiver_spec.kind == "udt"
-                    and receiver_spec.name in _DRAWING_TYPE_NAMES):
+                    and (receiver_spec.name in _DRAWING_TYPE_NAMES
+                         or receiver_spec.name in self._udt_fields)):
+                return receiver_spec
+            if (receiver_spec is not None
+                    and receiver_spec.kind in ("array", "matrix")
+                    and isinstance(value.object, Identifier)
+                    and self._collection_history_is_supported(value)):
+                # An array's or a matrix's history is a collection of its
+                # type (fixtures/array_history_tv; pineforge_codegen/
+                # collection_history.py); a legacy read keeps the element
+                # typing it had.
                 return receiver_spec
             return None
         if isinstance(value, IfStmt):

package/pineforge_codegen/ast_nodes.py

@@ -6,6 +6,13 @@ from typing import Any
 from pineforge_codegen.errors import SourceLocation
 
 
+# A MemberAccess (a field, or a method call's callee) written straight after a
+# history reference, ``c[1].v`` / ``b[1].get_top()``: TradingView refuses it
+# (CE10011 / CE10010) and takes ``(c[1]).v``, which parses to the same nodes.
+# Set by the parser, refused by the support checker.
+HISTORY_MEMBER_ANNOTATION = "pf_history_member"
+
+
 # ---------------------------------------------------------------------------
 # Base class
 # ---------------------------------------------------------------------------

package/pineforge_codegen/codegen/base.py

@@ -145,6 +145,7 @@ TA_TUPLE_RESULT_TYPES = {
 
 # CPP_RESERVED + the NamingHelper mixin are pulled in from helpers.py so the
 # small naming/walk utilities can be shared with future visitor mixins.
+from .collection_history import CollectionHistoryEmitter
 from .helpers import (
     CPP_RESERVED, INLINE_HISTORY_KINDS, SESSION_FLAG_MEMBERS, NamingHelper,
     cpp_code_only, na_preserving_int_cast, pine_truth_cast,
@@ -194,7 +195,7 @@ from .drawing import DrawingVisitor
 # CodeGen class
 # ---------------------------------------------------------------------------
 
-class CodeGen(CallVisitor, ExprVisitor, StmtVisitor, TopLevelEmitter, SecurityEmitter, TaSiteHelper, TypeInferer, InputHelper, DrawingVisitor, NamingHelper):
+class CodeGen(CallVisitor, ExprVisitor, StmtVisitor, TopLevelEmitter, SecurityEmitter, TaSiteHelper, TypeInferer, InputHelper, DrawingVisitor, CollectionHistoryEmitter, NamingHelper):
     """Generate C++ from an AnalyzerContext (visitor pattern).
 
     Mixin chain (Python MRO is left-to-right; method names are
@@ -1945,7 +1946,12 @@ class CodeGen(CallVisitor, ExprVisitor, StmtVisitor, TopLevelEmitter, SecurityEm
                     )
                 elif (orig_safe in self._series_var_member_names
                         or vname in self.ctx.series_vars):
-                    lines.append(f"    Series<{cpp_type}> {cloned_safe}{series_suffix};")
+                    # A history-read var object keeps its references, as
+                    # its base member does.
+                    udt_t = udt_spec.name if udt_spec is not None else member_udt_type
+                    element = (self._safe_name(udt_t) if udt_t in self._udt_defs
+                               else cpp_type)
+                    lines.append(f"    Series<{element}> {cloned_safe}{series_suffix};")
                 elif collection_spec is not None:
                     lines.append(
                         f"    {self._type_spec_to_cpp(collection_spec)} {cloned_safe};"
@@ -1987,8 +1993,13 @@ class CodeGen(CallVisitor, ExprVisitor, StmtVisitor, TopLevelEmitter, SecurityEm
                     lines.append(f"    {cpp_type} {cloned_safe};")
                 return
         # Non-var series var
-        if orig_safe in [self._safe_name(n) for n in self.ctx.series_vars]:
-            cpp_type = self._series_type_for(orig_safe)
+        raw_names = [n for n in self.ctx.series_vars if self._safe_name(n) == orig_safe]
+        if raw_names:
+            # A history-read object or drawing (a receiver ``this`` spelled
+            # ``pf_safe_this``) holds handles, as its base member does.
+            handles = {self._series_handle_cpp_type(n) for n in raw_names}
+            cpp_type = (handles.pop() if len(handles) == 1 and None not in handles
+                        else self._series_type_for(orig_safe))
             lines.append(f"    Series<{cpp_type}> {cloned_safe}{series_suffix};")
         else:
             lines.append(f"    double {cloned_safe} = 0.0;")
@@ -2112,6 +2123,14 @@ class CodeGen(CallVisitor, ExprVisitor, StmtVisitor, TopLevelEmitter, SecurityEm
                 declared_spec = self._type_spec_from_hint_name(stmt.type_hint)
             elif isinstance(stmt.value, (Ternary, IfStmt, SwitchStmt)):
                 declared_spec = self._type_spec_from_expr(stmt.value)
+            elif self._roots_at_collection_history(stmt.value):
+                # A copy of an array's or a matrix's history, or a built-in's
+                # result on one (``pm = m[1]``, ``c = (m[1]).copy()``).
+                declared_spec = self._type_spec_from_expr(stmt.value)
+                if declared_spec is not None and declared_spec.kind == "array":
+                    self._array_vars.add(stmt.name)
+                    self._collection_types.setdefault(stmt.name, declared_spec)
+                    continue
             else:
                 continue
             if declared_spec is None or declared_spec.kind != "matrix":
@@ -2225,10 +2244,17 @@ class CodeGen(CallVisitor, ExprVisitor, StmtVisitor, TopLevelEmitter, SecurityEm
 
         Walks chained ``FuncCall`` receivers (e.g. ``m.transpose().copy()``)
         until it finds an ``Identifier`` so the source matrix's TypeSpec can
-        be propagated through fluent call chains.
+        be propagated through fluent call chains. A history read (``m[1]``)
+        is the variable's: its copy has the variable's type.
         """
         if not isinstance(call_node, FuncCall):
             return None
+
+        def unwrap(node):
+            if isinstance(node, Subscript) and isinstance(node.object, Identifier):
+                return node.object
+            return node
+
         callee = call_node.callee
         # Method form: m.method(...) — possibly chained: m.foo().bar()
         if isinstance(callee, MemberAccess):
@@ -2240,12 +2266,13 @@ class CodeGen(CallVisitor, ExprVisitor, StmtVisitor, TopLevelEmitter, SecurityEm
                     obj = inner_callee.object
                 else:
                     break
+            obj = unwrap(obj)
             if isinstance(obj, Identifier):
                 if obj.name != "matrix":
                     return obj.name
                 # matrix.method(m, ...) functional form
                 if call_node.args:
-                    first = call_node.args[0]
+                    first = unwrap(call_node.args[0])
                     if isinstance(first, Identifier):
                         return first.name
         return None
@@ -3623,13 +3650,21 @@ class CodeGen(CallVisitor, ExprVisitor, StmtVisitor, TopLevelEmitter, SecurityEm
             if len(states) > 1
         }
 
+        # A history parameter holding a user-defined object or a drawing keeps
+        # the references its calls passed (``_series_param_element_cpp_type``).
+        handle_cpp_types = {
+            *DRAWING_TYPE_TO_CPP.values(),
+            *(self._safe_name(name) for name in self._udt_defs),
+        }
+
         def register_one(
             kind: str,
             source_key: tuple,
             cpp_type: str,
             context: str | None,
         ) -> None:
-            if cpp_type not in ("double", "int", "int64_t", "bool"):
+            if (cpp_type not in ("double", "int", "int64_t", "bool")
+                    and cpp_type not in handle_cpp_types):
                 cpp_type = "double"
             key = (kind, *source_key, context)
             if key in self._inline_history_member_by_key:
@@ -3721,6 +3756,27 @@ class CodeGen(CallVisitor, ExprVisitor, StmtVisitor, TopLevelEmitter, SecurityEm
             lexical.update(self._func_collection_types.get(owner, {}))
             return lexical
 
+        def owner_typed(owner: str | None, compute):
+            """``compute()`` with the owner's parameter types bound, as the
+            emitter binds them: a history read of a typed parameter's field
+            (``f(Outer p) => p.inner[1]``) types its Series by the field."""
+            previous = self.__dict__.get("_current_func_param_specs")
+            self._current_func_param_specs = owner_lexical_specs(owner)
+            try:
+                return compute()
+            finally:
+                if previous is None:
+                    self.__dict__.pop("_current_func_param_specs", None)
+                else:
+                    self._current_func_param_specs = previous
+
+        def history_cpp_type(expr, owner: str | None) -> str:
+            """``_history_value_cpp_type`` of ``expr``, a reference's handle
+            resolved with the owner's parameters bound; any other value keeps
+            the inference every earlier build registered."""
+            return (owner_typed(owner, lambda: self._reference_cpp_type(expr))
+                    or self._infer_type(expr))
+
         def plain_udf_info(call: FuncCall):
             if not isinstance(call.callee, Identifier):
                 return None
@@ -3846,7 +3902,8 @@ class CodeGen(CallVisitor, ExprVisitor, StmtVisitor, TopLevelEmitter, SecurityEm
             owner = owner_by_node.get(id(node))
             if isinstance(node, Subscript) and isinstance(node.object, FuncCall):
                 register(
-                    "hist_call", (id(node),), self._infer_type(node.object), owner
+                    "hist_call", (id(node),), history_cpp_type(node.object, owner),
+                    owner,
                 )
             elif (isinstance(node, Subscript)
                     and self._is_session_flag(node.object)):
@@ -3865,9 +3922,13 @@ class CodeGen(CallVisitor, ExprVisitor, StmtVisitor, TopLevelEmitter, SecurityEm
                         self._session_call_flags.setdefault(owner, set()).add(flag)
                         register("session_call", (owner, flag), "bool", owner)
             elif (isinstance(node, Subscript)
-                    and self._is_compound_history_object(node.object)):
+                    and (self._is_compound_history_object(node.object)
+                         or (isinstance(node.object, (Ternary, MemberAccess))
+                             and owner_typed(owner, lambda: self._reference_cpp_type(
+                                 node.object)) is not None))):
                 register(
-                    "hist_call", (id(node),), self._infer_type(node.object), owner
+                    "hist_call", (id(node),), history_cpp_type(node.object, owner),
+                    owner,
                 )
 
             if not isinstance(node, FuncCall):
@@ -4021,6 +4082,38 @@ class CodeGen(CallVisitor, ExprVisitor, StmtVisitor, TopLevelEmitter, SecurityEm
             ("fn_global_hist", id(fi.node), name, self._current_instance_name)
         )
 
+    def _reference_cpp_type(self, expr) -> str | None:
+        """The handle type of an expression whose value is a user-defined
+        object or a drawing reference (``Cell``, ``Box``), else None."""
+        spec = self._type_spec_from_expr(expr)
+        if (spec is None or spec.kind != "udt"
+                or not (spec.name in DRAWING_TYPE_TO_CPP
+                        or spec.name in self._udt_defs)):
+            return None
+        return DRAWING_TYPE_TO_CPP.get(spec.name) or self._safe_name(spec.name)
+
+    def _registered_history_handle(self, node: Subscript) -> str | None:
+        """The handle type of the synthetic history Series the prepass
+        registered for ``node`` (``_prepare_inline_history_members``), else
+        None: emission reads the type the member was declared with."""
+        member = self._inline_history_member_by_key.get(
+            ("hist_call", id(node), self._current_instance_name))
+        if member is None:
+            return None
+        handles = {*DRAWING_TYPE_TO_CPP.values(),
+                   *(self._safe_name(name) for name in self._udt_defs)}
+        for info in self._inline_history_members:
+            if info["member_name"] == member:
+                return info["cpp_type"] if info["cpp_type"] in handles else None
+        return None
+
+    def _history_value_cpp_type(self, expr) -> str:
+        """The element type of the synthetic Series that keeps ``expr``'s
+        history: a reference's handle (TradingView's history of such an
+        expression is the reference it produced at its previous evaluation:
+        fixtures/udt_history_tv udth_expr), else the scalar it infers."""
+        return self._reference_cpp_type(expr) or self._infer_type(expr)
+
     def _is_compound_history_object(self, node) -> bool:
         """Whether ``node[k]`` is history on an operator expression or a
         ``session.*`` flag.
@@ -4038,6 +4131,12 @@ class CodeGen(CallVisitor, ExprVisitor, StmtVisitor, TopLevelEmitter, SecurityEm
         """
         if self._is_session_flag(node):
             return True
+        if (isinstance(node, (Ternary, MemberAccess))
+                and self._reference_cpp_type(node) is not None):
+            # ``(c ? a : b)[1]`` and an object-typed field's ``o.inner[1]``:
+            # the reference the expression produced at its previous
+            # evaluation (fixtures/udt_history_tv udth_expr).
+            return True
         return (isinstance(node, (BinOp, UnaryOp, Ternary))
                 and self._infer_type(node) in ("double", "int", "int64_t", "bool"))
 
@@ -4614,6 +4713,10 @@ class CodeGen(CallVisitor, ExprVisitor, StmtVisitor, TopLevelEmitter, SecurityEm
         # per-callsite instances are declared below inside GeneratedStrategy
         # and therefore join the automatic COOF checkpoint inventory.
         self._emit_lazy_source_clock_helper(lines)
+        # The history of an array or a matrix variable: its support types
+        # (pineforge_codegen/collection_history.py), emitted only for a script
+        # that reads one.
+        self._emit_collection_history_helper(lines)
         # The chart-bar session type, inserted here once the class is lowered
         # and known to call it (codegen/session_market.py).
         _session_market_at = len(lines)
@@ -4847,9 +4950,13 @@ class CodeGen(CallVisitor, ExprVisitor, StmtVisitor, TopLevelEmitter, SecurityEm
                 continue
             callable_udt_spec = self._callable_var_udt_spec(name)
             if callable_udt_spec is not None:
-                lines.append(
-                    f"    {self._type_spec_to_cpp(callable_udt_spec)} {safe};"
-                )
+                handle_cpp = self._type_spec_to_cpp(callable_udt_spec)
+                if safe in self._series_var_member_names:
+                    # A history-read var object: its history holds the
+                    # references it held (``_series_handle_cpp_type``).
+                    lines.append(f"    Series<{handle_cpp}> {safe}{_mbb};")
+                else:
+                    lines.append(f"    {handle_cpp} {safe};")
                 continue
             # Detect array vars from init expression. Guard the substring
             # heuristic against a UDT constructor that merely WRAPS array.new /
@@ -4941,7 +5048,13 @@ class CodeGen(CallVisitor, ExprVisitor, StmtVisitor, TopLevelEmitter, SecurityEm
                         udt_type = udt_name
                         break
             if udt_type:
-                lines.append(f"    {self._safe_name(udt_type)} {safe};")
+                if safe in self._series_var_member_names:
+                    # A history-read var object: its history holds the
+                    # references it held (``_series_handle_cpp_type``).
+                    lines.append(
+                        f"    Series<{self._safe_name(udt_type)}> {safe}{_mbb};")
+                else:
+                    lines.append(f"    {self._safe_name(udt_type)} {safe};")
                 continue
             cpp_type = PINE_TYPE_TO_CPP.get(ptype, "double")
             # Promote int->int64_t when init RHS is an int64-returning builtin
@@ -5150,6 +5263,15 @@ class CodeGen(CallVisitor, ExprVisitor, StmtVisitor, TopLevelEmitter, SecurityEm
             lines.append("    DrawingArena<LabelRec> _pf_labels_{_PF_DRAWING_UNBOUNDED};")
             lines.append("    DrawingArena<LinefillRec> _pf_linefills_{_PF_DRAWING_UNBOUNDED};")
 
+        # 8e. The copies an array or a matrix variable's executions left
+        #     (pineforge_codegen/collection_history.py).
+        for variable in self._collection_history_variables():
+            lines.append(
+                f"    _PFCollectionHistory<{self._collection_history_cpp_type(variable)}> "
+                f"{self._collection_history_member(variable)}"
+                f"{self._collection_history_capacity(variable)};"
+            )
+
         # 9. _var_initialized flag
         if self.ctx.var_members:
             lines.append("    bool _var_initialized = false;")