@pineforge/codegen-pyodide 1.0.1 → 1.2.0

package/pineforge_codegen/codegen/capabilities.py

@@ -0,0 +1,186 @@
+"""Immutable execution metadata; it does not alter generated computation."""
+
+import json
+import math
+
+from ..ast_nodes import BoolLiteral, FuncCall, Identifier, MemberAccess, NumberLiteral, StrategyDecl, StringLiteral, UnaryOp, VarDecl
+from ..external_requests import CAPABILITY_UNPINNED_ANNOTATION
+from ..limits import iter_ast_nodes
+
+
+STRATEGY_PARAMETERS = (
+    "title", "shorttitle", "overlay", "format", "precision", "scale", "pyramiding",
+    "calc_on_order_fills", "calc_on_every_tick", "max_bars_back",
+    "backtest_fill_limits_assumption", "default_qty_type", "default_qty_value",
+    "initial_capital", "currency", "slippage", "commission_type", "commission_value",
+    "process_orders_on_close", "close_entries_rule", "margin_long", "margin_short",
+    "explicit_plot_zorder", "max_lines_count", "max_labels_count", "max_boxes_count",
+    "calc_bars_count", "risk_free_rate", "use_bar_magnifier", "fill_orders_on_standard_ohlc",
+    "max_polylines_count", "dynamic_requests", "behind_chart", "calc_on_every_history_tick",
+)
+
+
+DECLARATION_DEFAULTS = {
+    "calc_on_every_tick": False,
+    "calc_on_order_fills": False,
+    "process_orders_on_close": False,
+    "use_bar_magnifier": False,
+    "fill_orders_on_standard_ohlc": False,
+    "backtest_fill_limits_assumption": 0,
+    "currency": "currency.NONE",
+    "timeframe": "",
+    "timeframe_gaps": True,
+    "dynamic_requests": True,
+    "calc_on_every_history_tick": False,
+}
+
+
+def _expression(node):
+    if isinstance(node, (StringLiteral, NumberLiteral, BoolLiteral)):
+        return node.value
+    if isinstance(node, Identifier):
+        return node.name
+    if isinstance(node, MemberAccess):
+        return f"{_expression(node.object)}.{node.member}"
+    if isinstance(node, FuncCall):
+        return f"{_expression(node.callee)}({','.join(str(_expression(arg)) for arg in node.args)})"
+    return None
+
+
+def _literal(node):
+    if isinstance(node, (StringLiteral, NumberLiteral, BoolLiteral)):
+        return node.value, True
+    if isinstance(node, UnaryOp) and node.op in ("+", "-"):
+        value, valid = _literal(node.operand)
+        if valid and type(value) in (int, float):
+            return value if node.op == "+" else -value, True
+    if isinstance(node, MemberAccess):
+        value = _expression(node)
+        if value and value.split(".")[0] in ("currency", "format", "scale", "strategy"):
+            return value, True
+    return _expression(node), False
+
+
+def capabilities_document(emitter) -> str:
+    declarations = dict(DECLARATION_DEFAULTS)
+    unresolved = []
+    requests = []
+    lower_symbols = {}
+    intrabar = False
+    recorded = False
+    for node, _depth in iter_ast_nodes(emitter.ctx.ast):
+        if isinstance(node, StrategyDecl):
+            arguments = {STRATEGY_PARAMETERS[index] if index < len(STRATEGY_PARAMETERS)
+                         else f"strategy() positional argument {index + 1}": argument
+                         for index, argument in enumerate(node.args)}
+            unresolved.extend(arguments.keys() & node.kwargs.keys())
+            arguments.update(node.kwargs)
+            for name, argument in arguments.items():
+                value, valid = _literal(argument)
+                default = DECLARATION_DEFAULTS.get(name)
+                if name in DECLARATION_DEFAULTS:
+                    valid &= type(value) is type(default)
+                    if name == "backtest_fill_limits_assumption":
+                        valid = (type(value) is int and value >= 0) or (
+                            type(value) is float and math.isfinite(value) and value >= 0 and value == int(value))
+                        if valid:
+                            value = int(value)
+                    declarations[name] = value
+                if not valid or name not in STRATEGY_PARAMETERS and name not in DECLARATION_DEFAULTS:
+                    unresolved.append(name)
+        elif isinstance(node, VarDecl):
+            intrabar |= node.is_varip
+        elif isinstance(node, FuncCall):
+            name, namespace = emitter._resolve_callee(node.callee)
+            if namespace == "request" and name == "security_lower_tf":
+                expression = node.args[2] if len(node.args) > 2 else node.kwargs.get("expression")
+                lower_symbols[id(expression)] = node.args[0] if node.args else node.kwargs.get("symbol")
+            parts = (node.annotations or {}).get("pf_recorded_key")
+            if parts is not None:
+                recorded = True
+                requests.append({
+                    "function": f"{namespace}.{name}",
+                    "symbol": _expression(node.args[0]) if node.args else None,
+                    "timeframe": "",
+                    "lookahead": f"barmerge.lookahead_{parts.get('lookahead', 'off')}",
+                    "gaps": f"barmerge.gaps_{parts.get('gaps', 'off')}",
+                    "heikinashi": False,
+                    "feed": "recorded",
+                })
+        if isinstance(node, Identifier) and node.name == "timenow":
+            unresolved.append("timenow (bar timestamp approximation)")
+        if isinstance(node, Identifier) and node.name in ("last_bar_index", "last_bar_time"):
+            unresolved.append(f"{node.name} (stream endpoint is not batch-equivalent)")
+        if isinstance(node, MemberAccess) and _expression(node) == "barstate.isrealtime":
+            unresolved.append("barstate.isrealtime (compiled historical-only approximation)")
+        if isinstance(node, MemberAccess) and _expression(node) in (
+                "barstate.islast", "barstate.islastconfirmedhistory"):
+            unresolved.append(f"{_expression(node)} (stream endpoint is not batch-equivalent)")
+
+    auxiliary = False
+    for site in emitter._security_calls:
+        symbol_node = site.get("symbol_node")
+        if site.get("is_lower_tf_array"):
+            symbol_node = lower_symbols.get(id(site.get("expr_node")), symbol_node)
+        if isinstance(symbol_node, FuncCall) and site.get("heikinashi") and symbol_node.args:
+            symbol_node = symbol_node.args[0]
+        symbol = _expression(symbol_node) if symbol_node is not None else "syminfo.tickerid"
+        timeframe = _expression(site.get("tf_node"))
+        lookahead = _expression(site.get("lookahead_node")) or "barmerge.lookahead_off"
+        gaps = _expression(site.get("gaps_node")) or "barmerge.gaps_off"
+        if isinstance(symbol_node, Identifier) and symbol_node.name not in emitter._global_mutable_infos:
+            symbol = _expression((getattr(emitter.ctx, "global_expr_map", {}) or {}).get(
+                symbol_node.name, symbol_node))
+        feed = "chart" if symbol in ("syminfo.tickerid", "syminfo.ticker", "") else "auxiliary"
+        auxiliary |= feed == "auxiliary"
+        if not isinstance(site.get("tf_node"), StringLiteral) and timeframe != "timeframe.period":
+            unresolved.append(f"request.security[{site['sec_id']}].timeframe")
+        if lookahead not in ("barmerge.lookahead_off", "barmerge.lookahead_on"):
+            unresolved.append(f"request.security[{site['sec_id']}].lookahead")
+        requests.append({
+            "function": "request.security_lower_tf" if site.get("is_lower_tf_array") else "request.security",
+            "symbol": symbol,
+            "timeframe": timeframe,
+            "lookahead": lookahead,
+            "gaps": gaps,
+            "heikinashi": bool(site.get("heikinashi")),
+            "feed": feed,
+        })
+    for index, site in enumerate((emitter.ctx.ast.annotations or {}).get(CAPABILITY_UNPINNED_ANNOTATION, ())):
+        requests.append({
+            "function": site["function"],
+            "symbol": _expression(site["symbol_node"]),
+            "timeframe": _expression(site["tf_node"]) if site["function"] in (
+                "request.security", "request.security_lower_tf") else "",
+            "lookahead": _expression(site["lookahead_node"]) or "barmerge.lookahead_off",
+            "gaps": _expression(site["gaps_node"]) or "barmerge.gaps_off",
+            "heikinashi": False,
+            "feed": "unpinned",
+        })
+        unresolved.append(f"{site['function']}[unpinned:{index}]")
+    requirements = {
+        "auxiliary_security_feeds": auxiliary,
+        "native_security_feeds": False,
+        "fx_curve": declarations["currency"] != "currency.NONE",
+        "recorded_series": recorded,
+        "historical_probe_overrides": False,
+        "intrabar_persistence": intrabar,
+    }
+    return json.dumps({"version": 1, "declarations": declarations, "requests": requests,
+                       "requirements": requirements, "unresolved": sorted(set(unresolved))},
+                      sort_keys=True, separators=(",", ":"), allow_nan=False)
+
+
+def emit_capabilities_exports(emitter, lines: list[str]) -> None:
+    literal = json.dumps(capabilities_document(emitter))
+    lines.extend([
+        "#ifdef PF_SETTINGS_API_VERSION",
+        "#ifdef PF_CAPABILITIES_API_VERSION",
+        "    uint32_t strategy_capabilities_api_version(void) { return PF_CAPABILITIES_API_VERSION; }",
+        "    int strategy_capabilities_receipt(void* s, char* json, size_t capacity, size_t* required, char* error, size_t error_capacity) {",
+        "        if (required) *required = 0;",
+        "        return ::pineforge::checked_settings::boundary(error, error_capacity, [&] {",
+        '            ::pineforge::checked_settings::require(s != nullptr, "null strategy");',
+        f"            ::pineforge::checked_settings::receipt({literal}, json, capacity, required);",
+        "        });", "    }", "#endif", "#endif",
+    ])

package/pineforge_codegen/codegen/checked_settings.py

@@ -0,0 +1,285 @@
+"""Opt-in settings metadata, validation and exception-contained C exports."""
+
+from ..ast_nodes import Identifier, MemberAccess
+from ..errors import CompileError
+
+
+def _visit_setting_arg(emitter, expr) -> str:
+    """An input argument's C++ for the settings metadata. The metadata is
+    emitted in the constructor, ahead of the script body: an error here is
+    held until the body is generated (``CodeGen.generate``), so the script's
+    first error in source order is the one raised."""
+    try:
+        return emitter._visit_expr(expr)
+    except CompileError as error:
+        emitter._defer_settings_error(error)
+        return "0"
+
+
+def emit_settings_members(emitter, lines: list[str], constructor: list[str]) -> None:
+    lines.extend([
+        "    bool _pf_setting_failed_ = false;",
+        "    std::string _pf_setting_failure_;",
+        "    void _pf_record_failure(const char* entrypoint, const char* message) noexcept {",
+        "        try { last_error_ = entrypoint; last_error_ += \": \"; last_error_ += message; } catch (...) {}",
+        "    }",
+        "    void _pf_record_setting_failure(const char* entrypoint, const char* message) noexcept {",
+        "        if (!_pf_setting_failed_) {",
+        "            _pf_setting_failed_ = true;",
+        '            try { _pf_setting_failure_ = entrypoint; _pf_setting_failure_ += ": "; _pf_setting_failure_ += message; } catch (...) {}',
+        "        }",
+        "        _pf_refuse_failed_setting(nullptr);",
+        "    }",
+        "    void _pf_require_settings_ok() const {",
+        "#ifdef PF_SETTINGS_API_VERSION",
+        '        if (_pf_setting_failed_) throw ::pineforge::checked_settings::LatchedSettingsFailure(_pf_setting_failure_.empty() ? "legacy strategy setter failed" : _pf_setting_failure_);',
+        "#else",
+        '        if (_pf_setting_failed_) throw std::runtime_error(_pf_setting_failure_.empty() ? "legacy strategy setter failed" : _pf_setting_failure_);',
+        "#endif",
+        "    }",
+        "    bool _pf_refuse_failed_setting(ReportC* out) noexcept {",
+        "        if (!_pf_setting_failed_) return false;",
+        '        try { last_error_ = _pf_setting_failure_.empty() ? "legacy strategy setter failed" : _pf_setting_failure_; } catch (...) {}',
+        "        if (out) *out = ReportC{};",
+        "        return true;",
+        "    }",
+    ])
+    inputs = []
+    for node, binding in emitter._global_input_calls_with_names():
+        func_name, namespace = emitter._resolve_callee(node.callee)
+        name = emitter._get_input_title(node, var_name=binding)
+        key = emitter._input_key_literal(name)
+        default = emitter._get_input_default(node)
+        getter = emitter._input_getter_for_call(node, func_name, namespace)
+        default_cpp = _visit_setting_arg(emitter, default) if default is not None else "0"
+        default_cpp = emitter._coerce_string_input_default(getter, default_cpp)
+        value_type = {
+            "get_input_int": "int", "get_input_int64": "int",
+            "get_input_double": "float", "get_input_bool": "bool",
+            "get_input_string": "string",
+        }[getter]
+        kind = emitter._FORM_TYPE.get(func_name, value_type) if namespace == "input" else value_type
+        options = []
+        option_values = []
+        supported = "true"
+        default_serialized = None
+        names, merged = emitter._merged_args(node, func_name, namespace)
+        arguments = dict(zip(names or [], merged))
+        arguments.update(node.kwargs)
+        if emitter._is_source_input(node):
+            value_type = "source"
+            source = emitter._source_defval_to_base_series(default)[5:-1]
+            default_cpp = emitter._input_key_literal(source)
+            effective = f'(inputs_.count({key}) ? inputs_.at({key}) : {default_cpp})'
+            options = [emitter._input_key_literal(value)
+                       for value in sorted(emitter._NATIVE_SOURCE_SERIES)]
+        elif namespace == "input" and func_name == "enum":
+            value_type = "enum"
+            declared = getattr(arguments.get("options"), "elements", None)
+            enum_members = ([default] if isinstance(default, MemberAccess) else []) + list(declared or [])
+            enum_names = {member.object.name for member in enum_members
+                          if isinstance(member, MemberAccess) and isinstance(member.object, Identifier)}
+            if (len(enum_names) == 1 and enum_members
+                    and all(isinstance(member, MemberAccess) and isinstance(member.object, Identifier)
+                            for member in enum_members)):
+                enum_name = next(iter(enum_names))
+                members = emitter._enum_defs.get(enum_name, [])
+                selected = [member.member for member in declared] if declared is not None else members
+                options = [emitter._input_key_literal(f"{enum_name}.{member}")
+                           for member in selected]
+                option_values = [emitter._input_key_literal(str(members.index(member)))
+                                 for member in selected if member in members]
+                supported = "true" if options and len(options) == len(option_values) else "false"
+            else:
+                supported = "false"
+            if not isinstance(default, MemberAccess):
+                supported = "false"
+                default_serialized = 'std::string("na")'
+                effective = f'(inputs_.count({key}) ? inputs_.at({key}) : std::string("na"))'
+            else:
+                effective = f'::pineforge::checked_settings::number({getter}({key}, {default_cpp}))'
+        else:
+            declared = getattr(arguments.get("options"), "elements", None)
+            if declared:
+                for option in declared:
+                    option_cpp = _visit_setting_arg(emitter, option)
+                    options.append(option_cpp if getter == "get_input_string" else
+                                   f'::pineforge::checked_settings::number({option_cpp})')
+            expression = f'{getter}({key}, {default_cpp})'
+            effective = (expression if getter == "get_input_string" else
+                         f'::pineforge::checked_settings::number({expression})')
+        if default_serialized is None:
+            default_serialized = (default_cpp if value_type in ("string", "source") else
+                                  f'::pineforge::checked_settings::number({default_cpp})')
+        constraints = [_visit_setting_arg(emitter, arguments[name]) if arguments.get(name) is not None
+                       else "std::numeric_limits<double>::quiet_NaN()"
+                       for name in ("minval", "maxval", "step")]
+        metadata = (f'{{{key}, "{value_type}", {default_serialized}, '
+                    f'{{{", ".join(options)}}}, {", ".join(constraints)}, '
+                    f'{64 if getter == "get_input_int64" else 32}, {supported}, '
+                    f'{{{", ".join(option_values)}}}, "{kind}"}}')
+        inputs.append((metadata, effective))
+
+    overrides = [
+        ("initial_capital", "float", "initial_capital", "initial_capital", "0.0"),
+        ("commission_value", "float", "commission_value", "commission_value", "0.0"),
+        ("default_qty_value", "float", "default_qty_value", "default_qty_value", "0.0"),
+        ("pyramiding", "int", "pyramiding", "pyramiding", "0.0"),
+        ("slippage", "int", "slippage", "slippage", "0.0"),
+        ("process_orders_on_close", "bool", "process_orders_on_close", "process_orders_on_close", "nan"),
+        ("calc_on_order_fills", "bool", "calc_on_order_fills", "calc_on_order_fills", "nan"),
+        ("close_entries_rule", "string", "close_entries_rule_any", "close_entries_rule", "nan"),
+        ("default_qty_type", "string", "default_qty_type", "default_qty_type", "nan"),
+        ("commission_type", "string", "commission_type", "commission_type", "nan"),
+    ]
+    enum_options = {
+        "close_entries_rule": ["FIFO", "ANY"],
+        "default_qty_type": ["fixed", "percent_of_equity", "cash"],
+        "commission_type": ["percent", "cash_per_order", "cash_per_contract"],
+    }
+    lines.extend([
+        "#ifdef PF_SETTINGS_API_VERSION",
+        "    static pineforge::source::PineStrategyConfig _pf_settings_declared_config() {",
+        "        pineforge::source::PineStrategyConfig cfg{};",
+    ])
+    lines.extend(statement for statement in constructor if statement.startswith("        cfg."))
+    lines.extend([
+        "        return cfg;", "    }",
+        "    std::vector<::pineforge::checked_settings::Setting> _pf_settings_inputs() const {",
+        "        return {",
+    ])
+    lines.extend(f"            {metadata}," for metadata, _effective in inputs)
+    lines.extend([
+        "        };", "    }",
+        "    std::vector<::pineforge::checked_settings::Setting> _pf_settings_overrides() const {",
+        "        const double _pf_nan = std::numeric_limits<double>::quiet_NaN();",
+        "        const auto _pf_defaults = _pf_settings_declared_config();",
+        "        return {",
+    ])
+    override_effective = []
+    for name, value_type, config_field, override_field, minimum in overrides:
+        raw = f'config_.{config_field}'
+        declared_default = f'_pf_defaults.{config_field}'
+        overridden = f'override_.{override_field}'
+        selected = (f'(std::isnan({overridden}) ? {raw} : {overridden})'
+                    if value_type == "float" else
+                    f'({overridden} < 0 ? {raw} : {overridden})')
+        if name in enum_options:
+            options = enum_options[name]
+            default_value = f'_pf_{name}_word({declared_default})'
+            effective = f'_pf_{name}_word({selected})'
+        else:
+            options = []
+            default_value = f'::pineforge::checked_settings::number({declared_default})'
+            effective = f'::pineforge::checked_settings::number({selected})'
+            if value_type == "bool":
+                effective = f'::pineforge::checked_settings::number(static_cast<bool>({selected}))'
+        option_cpp = ", ".join(emitter._input_key_literal(option) for option in options)
+        floor = "_pf_nan" if minimum == "nan" else minimum
+        lines.append(f'            {{"{name}", "{value_type}", {default_value}, '
+                     f'{{{option_cpp}}}, {floor}}},')
+        override_effective.append(effective)
+    lines.extend(["        };", "    }"])
+    for name, options in enum_options.items():
+        lines.append(f'    static std::string _pf_{name}_word(int _pf_value) {{')
+        for index, option in enumerate(options):
+            lines.append(f'        if (_pf_value == {index}) return "{option}";')
+        lines.extend(['        return "invalid";', '    }'])
+    lines.extend([
+        "    void _pf_set_input_checked(const std::string& _pf_key, const std::string& _pf_value) {",
+        "        if (_pf_refuse_failed_setting(nullptr)) throw ::pineforge::checked_settings::Error{PF_SETTINGS_RUN_FAILED, last_error_.c_str()};",
+        '        ::pineforge::checked_settings::require(script_bars_processed() == 0 && stream_phase_ == StreamPhase::IDLE, "settings are frozen after execution begins", PF_SETTINGS_UNSUPPORTED);',
+        "        const auto _pf_inputs = _pf_settings_inputs();",
+        "        const ::pineforge::checked_settings::Setting* _pf_match = nullptr;",
+        "        for (const auto& _pf_input : _pf_inputs) {",
+        "            if (_pf_input.name != _pf_key) continue;",
+        '            ::pineforge::checked_settings::require(_pf_match == nullptr, "ambiguous input key", PF_SETTINGS_UNSUPPORTED);',
+        "            _pf_match = &_pf_input;",
+        "        }",
+        '        ::pineforge::checked_settings::require(_pf_match != nullptr, "unknown input key");',
+        "        const auto _pf_canonical = ::pineforge::checked_settings::validate(*_pf_match, _pf_value);",
+        "        set_input(_pf_key, _pf_canonical);",
+        '        ::pineforge::checked_settings::require(inputs_.count(_pf_key) && inputs_.at(_pf_key) == _pf_canonical, "input was not installed", PF_SETTINGS_UNSUPPORTED);',
+        "    }",
+        "    void _pf_set_override_checked(const std::string& _pf_key, const std::string& _pf_value) {",
+        "        if (_pf_refuse_failed_setting(nullptr)) throw ::pineforge::checked_settings::Error{PF_SETTINGS_RUN_FAILED, last_error_.c_str()};",
+        '        ::pineforge::checked_settings::require(script_bars_processed() == 0 && stream_phase_ == StreamPhase::IDLE, "settings are frozen after execution begins", PF_SETTINGS_UNSUPPORTED);',
+        "        for (const auto& _pf_override : _pf_settings_overrides()) {",
+        "            if (_pf_override.name != _pf_key) continue;",
+        "            auto _pf_alias = _pf_value;",
+    ])
+    for name, options in enum_options.items():
+        lines.append(f'            if (_pf_key == "{name}") {{')
+        for index, option in enumerate(options):
+            aliases = [str(index)]
+            if name == "close_entries_rule":
+                aliases.append(option.lower())
+            else:
+                prefix = "strategy.commission." if name == "commission_type" else "strategy."
+                aliases.append(prefix + option)
+            condition = " || ".join(f'_pf_value == "{alias}"' for alias in aliases)
+            lines.append(f'                if ({condition}) _pf_alias = "{option}";')
+        lines.append("            }")
+    lines.extend([
+        "            const auto _pf_canonical = ::pineforge::checked_settings::validate(_pf_override, _pf_alias);",
+        "            set_strategy_override(_pf_key, _pf_canonical);",
+        "            return;",
+        "        }",
+        '        throw ::pineforge::checked_settings::Error{PF_SETTINGS_INVALID_ARGUMENT, "unknown override key"};',
+        "    }",
+        "    std::string _pf_settings_receipt() const {",
+        '        ::pineforge::checked_settings::require(!_pf_setting_failed_, _pf_setting_failure_.empty() ? "legacy strategy setter failed" : _pf_setting_failure_.c_str(), PF_SETTINGS_RUN_FAILED);',
+        '        std::string _pf_document = "{\\\"version\\\":1,\\\"inputs\\\":[";',
+        "        const auto _pf_inputs = _pf_settings_inputs();",
+    ])
+    for index, (_metadata, effective) in enumerate(inputs):
+        if index:
+            lines.append("        _pf_document += ',';")
+        lines.append(f"        _pf_document += ::pineforge::checked_settings::describe(_pf_inputs[{index}], {effective});")
+    lines.extend([
+        '        _pf_document += "],\\\"overrides\\\":[";',
+        "        const auto _pf_overrides = _pf_settings_overrides();",
+    ])
+    for index, effective in enumerate(override_effective):
+        if index:
+            lines.append("        _pf_document += ',';")
+        lines.append(f"        _pf_document += ::pineforge::checked_settings::describe(_pf_overrides[{index}], {effective});")
+    lines.extend(['        return _pf_document + "]}";', "    }", "#endif"])
+
+
+def emit_settings_exports(lines: list[str]) -> None:
+    lines.extend([
+        "#ifdef PF_SETTINGS_API_VERSION",
+        "    uint32_t strategy_settings_api_version(void) { return PF_SETTINGS_API_VERSION; }",
+        "    int strategy_create_checked(const char* params_json, void** out, char* error, size_t error_capacity) {",
+        "        if (out) *out = nullptr;",
+        "        return ::pineforge::checked_settings::boundary(error, error_capacity, [&] {",
+        '            ::pineforge::checked_settings::require(out != nullptr, "strategy output pointer is null");',
+        '            ::pineforge::checked_settings::require(!params_json || !*params_json, "params_json is reserved; use checked setters", PF_SETTINGS_UNSUPPORTED);',
+        "            *out = new GeneratedStrategy();",
+        "        });",
+        "    }",
+    ])
+    for kind in ("input", "override"):
+        lines.extend([
+            f"    int strategy_set_{kind}_checked(void* s, const char* key, const char* value, char* error, size_t error_capacity) {{",
+            "        return ::pineforge::checked_settings::boundary(error, error_capacity, [&] {",
+            '            ::pineforge::checked_settings::require(s && key && value, "null strategy, key or value");',
+            f"            static_cast<GeneratedStrategy*>(s)->_pf_set_{kind}_checked(key, value);",
+            "        });", "    }",
+        ])
+    lines.extend([
+        "    int strategy_get_effective_settings(void* s, char* json, size_t capacity, size_t* required, char* error, size_t error_capacity) {",
+        "        if (required) *required = 0;",
+        "        return ::pineforge::checked_settings::boundary(error, error_capacity, [&] {",
+        '            ::pineforge::checked_settings::require(s != nullptr, "null strategy");',
+        "            ::pineforge::checked_settings::receipt(static_cast<GeneratedStrategy*>(s)->_pf_settings_receipt(), json, capacity, required);",
+        "        });", "    }",
+        "    int run_backtest_full_checked(void* s, Bar* bars, int n, const char* input_tf, const char* script_tf, int bar_magnifier, int magnifier_samples, int magnifier_dist, ReportC* out, char* error, size_t error_capacity) {",
+        "        return ::pineforge::checked_settings::boundary(error, error_capacity, [&] {",
+        '            ::pineforge::checked_settings::require(s && out && n >= 0 && (n == 0 || bars), "invalid batch arguments");',
+        "            _pf_run_backtest_full_impl(s, bars, n, input_tf, script_tf, bar_magnifier, magnifier_samples, magnifier_dist, out);",
+        "            const auto& _pf_error = static_cast<GeneratedStrategy*>(s)->last_error();",
+        '            ::pineforge::checked_settings::require(_pf_error.empty(), _pf_error.c_str(), PF_SETTINGS_RUN_FAILED);',
+        "        });", "    }", "#endif",
+    ])

package/pineforge_codegen/codegen/emit_top.py

@@ -130,6 +130,8 @@ class TopLevelEmitter:
         )
         lines.append('#include <pineforge/source/pine_strategy_host.hpp>')
         lines.append('#include <pineforge/ta.hpp>')
+        lines.extend(['#if __has_include(<pineforge/checked_settings.hpp>)',
+                      '#include <pineforge/checked_settings.hpp>', '#endif'])
         if self._ta_uses_dynamic_lengths():
             lines.append('#include <pineforge/source/pine_ta_length.hpp>')
         lines.append('#include <pineforge/math.hpp>')
@@ -598,6 +600,7 @@ class TopLevelEmitter:
             '#error "Generated lifecycle reset requires a matching PineForge engine; rebuild with script-run preparation support"',
             "#endif",
             "    void prepare_script_run(const Bar* bars, int n, bool allow_precalculation) override {",
+            "        _pf_require_settings_ok();",
             "        _pf_script_state_checkpoint_.reset();",
         ])
         seen: set[str] = set()
@@ -1277,6 +1280,8 @@ class TopLevelEmitter:
         lines.append("        }")
         lines.append("        pineforge::source::PineStrategyHost::set_strategy_override(overrides);")
         lines.append("    }")
+        from .checked_settings import emit_settings_members
+        emit_settings_members(self, lines, ctor_body)
 
         if self._uses_recorded_requests():
             lines.extend([
@@ -1889,24 +1894,38 @@ class TopLevelEmitter:
     def _emit_extern_c(self, lines: list[str]) -> None:
         lines.append('extern "C" {')
         lines.append("    void* strategy_create(const char* params_json) {")
-        lines.append("        return new GeneratedStrategy();")
+        lines.append("        try { return new GeneratedStrategy(); } catch (...) { return nullptr; }")
         lines.append("    }")
         lines.append("    void run_backtest(void* s, Bar* bars, int n, ReportC* out) {")
+        lines.append("        try {")
         lines.append("        auto* strat = static_cast<GeneratedStrategy*>(s);")
+        lines.append("#ifndef PF_SETTINGS_API_VERSION")
+        lines.append("        if (strat->_pf_refuse_failed_setting(out)) return;")
+        lines.append("#endif")
         if self._security_calls:
             # If there are security calls, use the full run path. Pass empty strings
             # so the C++ runtime auto-detects input_tf from bar timestamps.
             lines.append('        strat->run(bars, n, "", "", false, 4, MagnifierDistribution::ENDPOINTS);')
         else:
             lines.append("        strat->run(bars, n);")
-        lines.append("        strat->fill_report(out);")
+        lines.append("        if (!strat->_pf_refuse_failed_setting(out)) strat->fill_report(out);")
+        lines.append('        } catch (const std::exception& _pf_error) {')
+        lines.append('            if (out) *out = ReportC{};')
+        lines.append('            if (s) static_cast<GeneratedStrategy*>(s)->_pf_record_failure("run_backtest", _pf_error.what());')
+        lines.append('        } catch (...) {')
+        lines.append('            if (out) *out = ReportC{};')
+        lines.append('            if (s) static_cast<GeneratedStrategy*>(s)->_pf_record_failure("run_backtest", "unknown C++ exception");')
+        lines.append('        }')
         lines.append("    }")
-        lines.append("    void run_backtest_full(void* s, Bar* bars, int n,")
+        lines.append("    static void _pf_run_backtest_full_impl(void* s, Bar* bars, int n,")
         lines.append('                           const char* input_tf, const char* script_tf,')
         lines.append("                           int bar_magnifier, int magnifier_samples,")
         lines.append("                           int magnifier_dist,")
         lines.append("                           ReportC* out) {")
         lines.append('        auto* strat = static_cast<GeneratedStrategy*>(s);')
+        lines.append("#ifndef PF_SETTINGS_API_VERSION")
+        lines.append("        if (strat->_pf_refuse_failed_setting(out)) return;")
+        lines.append("#endif")
         lines.append('        std::string itf = input_tf ? input_tf : "";')
         lines.append('        std::string stf = script_tf ? script_tf : "";')
         if self._security_calls:
@@ -1943,26 +1962,44 @@ class TopLevelEmitter:
             lines.append("            strat->run(bars, n, itf, stf, bar_magnifier != 0, magnifier_samples,")
             lines.append("                       static_cast<MagnifierDistribution>(magnifier_dist));")
             lines.append("        }")
-        lines.append("        strat->fill_report(out);")
+        lines.append("        if (!strat->_pf_refuse_failed_setting(out)) strat->fill_report(out);")
         lines.append("    }")
+        lines.extend([
+            "    void run_backtest_full(void* s, Bar* bars, int n, const char* input_tf, const char* script_tf,",
+            "                           int bar_magnifier, int magnifier_samples, int magnifier_dist, ReportC* out) {",
+            "        try { _pf_run_backtest_full_impl(s, bars, n, input_tf, script_tf, bar_magnifier, magnifier_samples, magnifier_dist, out); }",
+            '        catch (const std::exception& _pf_error) { if (out) *out = ReportC{}; if (s) static_cast<GeneratedStrategy*>(s)->_pf_record_failure("run_backtest_full", _pf_error.what()); }',
+            '        catch (...) { if (out) *out = ReportC{}; if (s) static_cast<GeneratedStrategy*>(s)->_pf_record_failure("run_backtest_full", "unknown C++ exception"); }',
+            "    }",
+        ])
         lines.append("    void strategy_free(void* s) {")
-        lines.append("        delete static_cast<GeneratedStrategy*>(s);")
+        lines.append("        try { delete static_cast<GeneratedStrategy*>(s); } catch (...) {}")
         lines.append("    }")
         lines.append("    void report_free(ReportC* report) {")
-        lines.append("        BacktestEngine::free_report(report);")
+        lines.append("        try { BacktestEngine::free_report(report); } catch (...) {}")
         lines.append("    }")
         lines.append("    void strategy_set_input(void* s, const char* key, const char* value) {")
         lines.append("        if (!s || !key || !value) return;")
-        lines.append("        static_cast<GeneratedStrategy*>(s)->set_input(key, value);")
+        lines.append("        try { static_cast<GeneratedStrategy*>(s)->set_input(key, value); }")
+        lines.append('        catch (const std::exception& _pf_error) { static_cast<GeneratedStrategy*>(s)->_pf_record_setting_failure("strategy_set_input", _pf_error.what()); }')
+        lines.append('        catch (...) { static_cast<GeneratedStrategy*>(s)->_pf_record_setting_failure("strategy_set_input", "unknown C++ exception"); }')
         lines.append("    }")
         lines.append("    void strategy_set_override(void* s, const char* key, const char* value) {")
         lines.append("        if (!s || !key || !value) return;")
-        lines.append("        static_cast<GeneratedStrategy*>(s)->set_strategy_override(key, value);")
+        lines.append("        try { static_cast<GeneratedStrategy*>(s)->set_strategy_override(key, value); }")
+        lines.append('        catch (const std::exception& _pf_error) { static_cast<GeneratedStrategy*>(s)->_pf_record_setting_failure("strategy_set_override", _pf_error.what()); }')
+        lines.append('        catch (...) { static_cast<GeneratedStrategy*>(s)->_pf_record_setting_failure("strategy_set_override", "unknown C++ exception"); }')
         lines.append("    }")
         lines.append("    void strategy_set_magnifier_volume_weighted(void* s, int on) {")
         lines.append("        if (!s) return;")
-        lines.append("        static_cast<GeneratedStrategy*>(s)->set_magnifier_volume_weighted(on != 0);")
+        lines.append("        try { static_cast<GeneratedStrategy*>(s)->set_magnifier_volume_weighted(on != 0); }")
+        lines.append('        catch (const std::exception& _pf_error) { static_cast<GeneratedStrategy*>(s)->_pf_record_setting_failure("strategy_set_magnifier_volume_weighted", _pf_error.what()); }')
+        lines.append('        catch (...) { static_cast<GeneratedStrategy*>(s)->_pf_record_setting_failure("strategy_set_magnifier_volume_weighted", "unknown C++ exception"); }')
         lines.append("    }")
+        from .checked_settings import emit_settings_exports
+        emit_settings_exports(lines)
+        from .capabilities import emit_capabilities_exports
+        emit_capabilities_exports(self, lines)
         if self._declares_bar_magnifier():
             # TradingView runs a script that declares use_bar_magnifier = true
             # on its bar magnifier; the host reads this export to run it on

package/pineforge_codegen/codegen/helpers.py

@@ -282,6 +282,7 @@ CPP_EMITTER_NAMES = frozenset("""
     configure_security_evaluators snapshot_script_state restore_script_state
     commit_script_state set_strategy_override set_input
     set_magnifier_volume_weighted strategy_declares_bar_magnifier fill_report run
+    strategy_capabilities_api_version strategy_capabilities_receipt
     precalculate
     strategy_entry strategy_close strategy_close_all strategy_exit
     strategy_exit_cancel_bracket strategy_cancel strategy_cancel_all strategy_order
@@ -314,7 +315,13 @@ CPP_EMITTER_NAMES = frozenset("""
     _pf_drawing_na _pf_collect_drawings _pf_collect_lines_ _pf_collect_boxes_
     _pf_collect_labels_ _pf_new _pf_held
     get_input_int get_input_float get_input_bool get_input_string
-    trace is_na na nz fixnan
+    _pf_record_failure _pf_refuse_failed_setting _pf_settings_declared_config
+    _pf_record_setting_failure _pf_require_settings_ok
+    _pf_setting_failed_ _pf_setting_failure_
+    _pf_settings_inputs _pf_settings_overrides _pf_set_input_checked
+    _pf_set_override_checked _pf_settings_receipt
+    _pf_close_entries_rule_word _pf_default_qty_type_word _pf_commission_type_word
+    checked_settings trace is_na na nz fixnan
 """.split())
 
 # The generated history members, ``_<kind>_<n>`` (codegen/base.py