History of user-defined objects and drawing references - #156

History references on user-defined objects and drawing references

codegen 1.0.0 emitted C++ that did not compile for the history of an object: a variable of a user-defined type or of a drawing type whose history was read (obj[1]) was declared Series<double> and the object handles were pushed into it. The four probes of the blog fact-check (t13_ne_hist, t14a_udt_hist_typed, t14b_udt_hist_untyped, t14c_udt_hist_var) failed with "no viable conversion from 'Cell' to 'double'" and "no member named 'push' in 'Acc'".

What TradingView does

Checked against TradingView itself (synthetic probes and their TradingView trade exports in tests/fixtures/udt_history_tv, see its README) and the Pine v6 User Manual:

• "Type system", Value vs. reference types: user-defined types and the drawing types are reference types; "Variables of reference types hold these object references; they do not store objects directly." "Objects", Copying objects: objects are assigned by reference.
• obj[k] is the reference the variable held k bars back, na before the first bar, and (obj[k]).field reads that object as it is now: (acc[1]).total of a var object equals acc.total, and a change made through c[1] shows through (c[2]) on the next bar (udth_ref). Boxes, lines and labels alike, a box deleted through b[1] included (udth_box, udth_box2).
• In a function, a method and an if block the history counts the executions of the scope (udth_fn, udth_method, udth_fn2). At a call site that skips bars, a parameter's and a receiver's history is one slot per chart bar holding the last call's value: x[2] at a call on every third bar reads the call of two bars back, not two calls back (udth_clock, udth_clock_method).
• Drawings through parameters: a box receiver's or parameter's history read with a built-in method, (this[1]).get_top(), is the previous call's box, and a drawing passed to a drawing parameter is the drawing itself, a history read (f(b[1])), a var box's history, a new box and a line beside its history included (udth_drawparam).
• The history of an expression whose value is an object (o.inner[1], f()[1], (c ? a : b)[1]) is the reference it produced at its previous evaluation (udth_expr), and below a lazy edge it is kept on every bar, the bars a ternary's selector skips the arm included (udth_lazy: the arm is skipped on every even bar, and each odd bar reads the even bar before it).
• == / != compare line and label references by identity, na included (udth_line_eq); TradingView refuses them for every other reference type (CE10123) and a comparison with na (CE10187).
• Spellings TradingView refuses: a field or method straight after the history operator, c[1].v (CE10011) and b[1].get_top() (CE10010) -- "Migration guide to v6", History of UDT fields: "use the syntax (myObject[10]).field - ensure the object's historical reference is wrapped in parentheses, otherwise it is invalid" -- and the history of a field holding a value, c.v[1] and (c.v)[1] (CE10290). A field read of a na object stops the run (RE10041). So the four blog probes are TradingView compile errors as written; their parenthesized forms are the valid spelling.

The change

• A history-read variable holding an object or a drawing is a Series of its handles (Series<Cell>, Series<Box>; na is the handle's T{}): globals, var objects, block and function locals (with their per-call-site copies), history parameters and method receivers. (c[1]).v reads the arena record the handle names; a drawing parameter's or receiver's history takes its built-in methods ((x[1]).get_top()).
• A temporary drawing passed to a drawing parameter, which a callable takes as T& -- a history read, a history-read variable's current slot, a new drawing or chart point, a user call's result -- is bound through a staged call, as a fresh array already is. Variables, fields and collection elements keep their C++.
• The history of an object-valued expression keeps a Series of handles; below a lazy edge a read that is safe to evaluate (a pure or object-constructor call over pure arguments, a ternary over names, a named object's field) is pushed on every execution, as TradingView keeps it.
• A field chain now visits its receiver in the analyzer: (o[1]).inner.v registered no history and silently read the current object.
• == / != of two lines or two labels compare handle ids.
• Refused with a located diagnostic, as TradingView refuses them: x[k].field / x[k].method() (CE10011 / CE10010, hint (x[k]).field), reference comparisons other than line/label (CE10123) and with na (CE10187), the history of a value field (CE10290). Refused here (they never compiled): the history of a reference inside a request.security expression (TradingView reads the requested timeframe's objects, which PineForge does not keep), and the history of a chart.point variable whose fields the script changes (PineForge holds a point as a value).
• CLAUDE.md / AGENTS.md gain an "Object and drawing history" support-contract row.

No refusal applies to a script that compiled before: each one either is a spelling TradingView rejects or produced C++ that did not compile.

Tests

• tests/test_udt_history.py: every shape compiles (42 shapes: globals, var, locals, parameters, receivers, drawing parameters' and receivers' methods, temporary drawings passed to drawing parameters, call results, selections, fields, boxes, lines, labels, chart points, two call sites), the emitted Series types, and every refusal with its TradingView code, including the probes TradingView's compiler refused.
• tests/test_e2e_udt_history.py: eleven TradingView tapes replay exit for exit (336 of 336 each); bar-by-bar traces of obj[1], (obj[1]).field, a change through history, l != l[1] and a drawing parameter's and receiver's history read with a built-in method; a na object's field stopping the run; the pre-change build failing to compile every tape probe; and the receiver-clock gap below, pinned.
• tests/test_e2e_drawing_lifetime.py: w9dg-pin-holders2 (a box carried by s := s[1]), evidence-only until now because it did not compile, replays TradingView's tape.
• tests/test_codegen_matrix_typed.py: the matrix history test spells its read (m[1]).get(0, 0), which lowers to the same C++ as before; m[1].get(0, 0) is a TradingView compile error.

Run against main 01b4ee3, the new tests fail 76 and error 12 of 103; the 15 that pass there are the tape-content checks, the pre-change-build checks and three shapes that already compiled (a var box's history, a requested field value, a request without an expression). After the change all pass.

Gates

The full suite on a shared x86-64 build host (Ubuntu, GCC 13), against engine 6b45f510 (v1.0.0 and two docs commits), at this branch's head: pytest 4783 passed, 0 failed, 33 skipped (28 need an older commit the shipped checkout's history lacks, 5 empty parameter sets), junit tests=4816 failures=0; tests/test_compile_corpus.py 314 passed, 0 skipped; the Pyodide gate's fixtures PARITY OK over 277 (ok 264/264, err 13 rejected as expected).

Population: the transpiler's C++ for every one of the 1,384 unique population sources is byte-identical on main and on this branch's head (also on its earlier head bf9134f), transpiled in fresh processes; within one long census process two sources differ only by the known ordering flake of two .clear() lines. None of them reads an object's or drawing's history. An experiment on bf9134f measured the 208 population probes (58 sources) that declare a user-defined type, across 17 lanes: all 208 excellent, each with the tier and match % of the active baseline; the later commits leave every population source's C++ unchanged.

Not covered:

• A typed method's receiver at a call site that skips bars counts calls, where TradingView keeps one slot per chart bar: from the third call on, this[2] reads three bars further back (udth_clock_method, 111 of 336 closes; pinned by a test). Typed methods kept their own bridge when fix: hold last values for history-reading UDF series parameters at skipped callsites #109 moved plain functions' parameters to TradingView's clock; this lane's object parameters already have it (udth_clock replays).
• A UDT constructor given a non-constant int for a float field (Cell.new(v = bar_index)) narrows in a braced initializer and does not compile.
• The history of a collection ((a[1]).size(), (m[1]).get(0, 0)) and a method on an operator expression ((close * 2).m()) emit None.
• h.xs[1] on an array field keeps its current-collection lowering although TradingView refuses it (CE10290), as it refuses a drawing field's h.ln[1], which PineForge already refused.
• Dead Series members for history-read parameters (a receiver's pf_safe_this and its call-site copies) remain, as for every parameter type before; their copies are now typed like their base.

🤖 Generated with Claude Code