pineforge-codegen 1.4.0__tar.gz → 1.5.0rc1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (74) hide show
  1. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/CHANGELOG.md +92 -0
  2. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/PKG-INFO +53 -18
  3. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/README.md +52 -17
  4. pineforge_codegen-1.5.0rc1/VERSION +1 -0
  5. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/docs/PUBLIC_CONTRACT.md +215 -23
  6. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/pineforge_codegen/__init__.py +60 -4
  7. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/pineforge_codegen/diagnostic_codes.py +18 -8
  8. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/pineforge_codegen/diagnostics_catalog.json +629 -629
  9. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/pineforge_codegen/errors.py +12 -1
  10. pineforge_codegen-1.5.0rc1/pineforge_codegen/request_feed_inventory.py +311 -0
  11. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/pineforge_codegen/support_checker.py +15 -6
  12. pineforge_codegen-1.5.0rc1/pineforge_codegen/timeframe_token_cli.py +133 -0
  13. pineforge_codegen-1.4.0/VERSION +0 -1
  14. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/.gitignore +0 -0
  15. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/CONTRIBUTING.md +0 -0
  16. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/LEGAL.md +0 -0
  17. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/LICENSE +0 -0
  18. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/docs/codegen-coverage-gaps.md +0 -0
  19. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/docs/pine-cap-activation.md +0 -0
  20. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/pineforge_codegen/analyzer/__init__.py +0 -0
  21. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/pineforge_codegen/analyzer/base.py +0 -0
  22. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/pineforge_codegen/analyzer/call_handlers.py +0 -0
  23. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/pineforge_codegen/analyzer/contracts.py +0 -0
  24. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/pineforge_codegen/analyzer/diagnostics.py +0 -0
  25. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/pineforge_codegen/analyzer/tables.py +0 -0
  26. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/pineforge_codegen/analyzer/types.py +0 -0
  27. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/pineforge_codegen/ast_nodes.py +0 -0
  28. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/pineforge_codegen/block_locals.py +0 -0
  29. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/pineforge_codegen/builtin_keywords.py +0 -0
  30. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/pineforge_codegen/codegen/__init__.py +0 -0
  31. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/pineforge_codegen/codegen/base.py +0 -0
  32. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/pineforge_codegen/codegen/capabilities.py +0 -0
  33. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/pineforge_codegen/codegen/checked_settings.py +0 -0
  34. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/pineforge_codegen/codegen/collection_history.py +0 -0
  35. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/pineforge_codegen/codegen/constant_fold.py +0 -0
  36. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/pineforge_codegen/codegen/drawing.py +0 -0
  37. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/pineforge_codegen/codegen/emit_top.py +0 -0
  38. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/pineforge_codegen/codegen/helpers.py +0 -0
  39. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/pineforge_codegen/codegen/helpers_syminfo.py +0 -0
  40. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/pineforge_codegen/codegen/host_members.py +0 -0
  41. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/pineforge_codegen/codegen/input.py +0 -0
  42. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/pineforge_codegen/codegen/order_shapes.py +0 -0
  43. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/pineforge_codegen/codegen/run_stops.py +0 -0
  44. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/pineforge_codegen/codegen/security.py +0 -0
  45. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/pineforge_codegen/codegen/session_market.py +0 -0
  46. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/pineforge_codegen/codegen/ta.py +0 -0
  47. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/pineforge_codegen/codegen/tables.py +0 -0
  48. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/pineforge_codegen/codegen/tv_number_format.py +0 -0
  49. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/pineforge_codegen/codegen/types.py +0 -0
  50. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/pineforge_codegen/codegen/visit_call.py +0 -0
  51. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/pineforge_codegen/codegen/visit_expr.py +0 -0
  52. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/pineforge_codegen/codegen/visit_stmt.py +0 -0
  53. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/pineforge_codegen/collection_history.py +0 -0
  54. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/pineforge_codegen/external_requests.py +0 -0
  55. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/pineforge_codegen/finite_ta_length.py +0 -0
  56. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/pineforge_codegen/lexer.py +0 -0
  57. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/pineforge_codegen/library_inline.py +0 -0
  58. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/pineforge_codegen/library_modules.py +0 -0
  59. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/pineforge_codegen/library_v5.py +0 -0
  60. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/pineforge_codegen/limits.py +0 -0
  61. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/pineforge_codegen/matrix_overloads.py +0 -0
  62. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/pineforge_codegen/method_binding.py +0 -0
  63. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/pineforge_codegen/parser.py +0 -0
  64. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/pineforge_codegen/pine_libraries.py +0 -0
  65. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/pineforge_codegen/pine_spelling.py +0 -0
  66. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/pineforge_codegen/pragmas.py +0 -0
  67. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/pineforge_codegen/request_discovery.py +0 -0
  68. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/pineforge_codegen/security_contexts.py +0 -0
  69. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/pineforge_codegen/session_reads.py +0 -0
  70. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/pineforge_codegen/signatures.py +0 -0
  71. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/pineforge_codegen/symbols.py +0 -0
  72. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/pineforge_codegen/tokens.py +0 -0
  73. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/pineforge_codegen/tv_input_choices.py +0 -0
  74. {pineforge_codegen-1.4.0 → pineforge_codegen-1.5.0rc1}/pyproject.toml +0 -0
@@ -20,6 +20,98 @@ supported as exact pairs; on the 0.x line they are independent. See the
20
20
  the release commit. A prerelease note describes changes since the preceding
21
21
  prerelease or stable tag; the final stable note consolidates the series.
22
22
 
23
+ ## 1.5.0 — Unreleased
24
+
25
+ The planned number of the next release; it stays **Unreleased** until its tag
26
+ exists, and the package version is unchanged. This entry records the diagnostic
27
+ additions below and the report-contract documentation for the paired engine
28
+ fix, and nothing else: the engine pairing, the rest of the content and the date
29
+ of 1.5.0 are set when the release is prepared. The codegen change is
30
+ diagnostics only; the report documentation adds no Python, JSON, diagnostic or
31
+ emitted-C++ change of its own, and no analyzer or code-generation file differs.
32
+
33
+ ### Compatibility and migration
34
+
35
+ - **`note` is a third diagnostic severity, and it is nonfatal.** A diagnostic
36
+ is now an `error`, a `warning` or a `note`: `Level.NOTE` in Python and `"note"`
37
+ as the `severity` of a catalog entry and of a JSON diagnostic. A note is
38
+ nonfatal like a warning. `transpile_full()["diagnostics"]` and the success
39
+ envelope's `diagnostics` list warnings and notes, a script with only notes
40
+ still returns `ok: true` and its C++, and a `CompileError` can carry notes
41
+ beside its errors. `transpile()` still returns no nonfatal diagnostics.
42
+ `CompileError.format()` prints `note[...]` where it printed `warning[...]` for
43
+ the codes below. Code written for two severities must handle `note`: read an
44
+ unknown severity as a warning, never as an error. A note does not mean that
45
+ results are unaffected; PF-W1505 describes a warmup approximation.
46
+ - **Exactly eleven codes change from warning to note:** PF-W1505, PF-W1508,
47
+ PF-W1509, PF-W1525, PF-W1526, PF-W1527, PF-W1528, PF-W1529, PF-W1530,
48
+ PF-W1531 and PF-W1532. They describe calls PineForge skips as visual only
49
+ (`plot(...)`, `table.new(...)`), earnings, dividends, splits, financial,
50
+ footprint and other-symbol requests whose value reaches only display and alert
51
+ sinks and is lowered to `na`, and the `ta.ema` warmup approximation. Every
52
+ other code keeps its severity. PF-W1502 (`color(...)` cast), PF-W1506
53
+ (`color.from_gradient`), PF-W1507 (drawing setters that drop color, style or
54
+ size), PF-W1078 (visual or style constants) and PF-W1552 (a
55
+ `request.security_lower_tf` whose value reaches only display and alert sinks)
56
+ also speak of visual-only or display-only handling and remain warnings: a
57
+ message's wording does not classify it. A consumer that tallied these eleven
58
+ codes as warnings, to gate a run, count warnings or color a banner, now
59
+ receives notes. PF-W1509 still classifies as PF-W1508 where the two templates
60
+ tie, so no new emitted code appears.
61
+ - **`user_message` is a raw ICU template over `args`.** Every catalog entry,
62
+ every `Diagnostic` (`Diagnostic.user_message`) and every JSON diagnostic gains
63
+ `user_message`: a short English ICU template that uses only that diagnostic's
64
+ existing `args` names and may be constant (`{name}() does nothing in a backtest.`
65
+ with `args.name = "plot"`). It is not pre-rendered English. Render it with
66
+ `args` as plain text, never as template syntax or markup, or translate by
67
+ `code`; do not display the unrendered template. It does not replace `message`
68
+ and `hint`. The templates of the eleven migrated codes are fixed string for
69
+ string by a delta fixture. Every template is checked for form (short,
70
+ parseable, over that code's own `args` names). Each of the 97 warning twins
71
+ of an error (`PF-W1nnn` for `PF-E1nnn`) has a sentence of its own that says
72
+ PineForge warns, and the 91 that warn only inside a `switch` arm also say it
73
+ keeps the arm's lowering. No warning or note template says that PineForge
74
+ refuses or rejects something, though one may say what TradingView refuses or
75
+ rejects. Beyond these checks a template's exact wording is not pinned.
76
+ - **Legacy fields are stable.** `code`, `args`, `message`, `hint`, `line`,
77
+ `col`, `endCol`, `ok`, `error` and the envelope keys keep their meaning and
78
+ values: no key is renamed or removed, and no code is renumbered or reused (the
79
+ notes keep their `PF-W` codes, and the prefix is not the severity).
80
+ `render_diagnostic()` still returns the unchanged English `message` and
81
+ `hint`. The catalog schema id stays `pineforge-diagnostics-catalog/v1`, so a
82
+ reader that checks `severity` against two values or rejects unknown entry
83
+ fields must accept `note` and `user_message`. The receiver examples in
84
+ `tests/fixtures/diagnostic_notes/receiver.json` specify the compatibility
85
+ rule; they are not evidence of any application's behavior.
86
+ - **The warmup sidecar is later work.** No compile-time or runtime sidecar
87
+ exists in this entry. PF-W1505 stays the static `ta.ema` note it was, with
88
+ only its severity changed: the support checker emits it at each `ta.ema` call
89
+ it visits, with no per-call condition or suppression and no call-site
90
+ identifier. The startup inventory and extraction that would bind a versioned
91
+ sidecar to a diagnostic by `call_site_id` and source range, so that a consumer
92
+ can show a startup sentence only for a known finite shortfall, are not part of
93
+ this entry, and no diagnostic carries a call-site identifier or a startup
94
+ length.
95
+
96
+ ### Documentation
97
+
98
+ The engine side of the report-ownership text below is a report fix, in
99
+ preparation, that engine `v1.4.0` does not carry.
100
+
101
+ - The [public contract](docs/PUBLIC_CONTRACT.md#a-report-belongs-to-the-call-that-returned-it)
102
+ states that a report belongs to the call that returned it. A call the engine
103
+ refuses without beginning gets the empty report, never an earlier run's rows;
104
+ a run that began and then failed keeps its partial rows; the explicit stream
105
+ snapshot keeps the owner's rows; recorded outputs keep their own record of
106
+ the last run that began.
107
+ - Read the error text, the error code **and** the run status after every run.
108
+ A refusal the engine makes before it admits the begin leaves the status at its
109
+ earlier value (0 after a completed run), so the status alone misses it. The
110
+ README's "Compile & run against the engine" section says the same.
111
+ - Pairing is unchanged in kind: regenerate the strategy C++ and relink against
112
+ the engine release's headers and `libpineforge.a` on a pair change (README
113
+ [Engine pairing](README.md#engine-pairing)).
114
+
23
115
  ## 1.4.0 — 2026-10-08
24
116
 
25
117
  A minor release of the exact engine/codegen pair. Its behavior was validated
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: pineforge-codegen
3
- Version: 1.4.0
3
+ Version: 1.5.0-rc.1
4
4
  Summary: PineScript v6 to C++ transpiler that targets the pineforge-engine runtime.
5
5
  Project-URL: Homepage, https://github.com/pineforge-4pass/pineforge-codegen-oss
6
6
  Project-URL: Issues, https://github.com/pineforge-4pass/pineforge-codegen-oss/issues
@@ -321,8 +321,8 @@ for the changes in each release from 1.0.0 on and the release-note policy.
321
321
  `transpile_full()` are the supported Python entry points.
322
322
  - **Located diagnostics** — the support checker rejects unsupported Pine with
323
323
  a `file:line:col` location before any C++ is emitted, and
324
- `transpile_full()` returns warnings for supported scripts with documented
325
- approximations.
324
+ `transpile_full()` returns nonfatal warnings and, since 1.5.0, notes for supported scripts,
325
+ including those with documented approximations.
326
326
 
327
327
  ## Releases and this README
328
328
 
@@ -349,6 +349,10 @@ covers 1.0.0 on and links the notes of earlier releases. A source install
349
349
  reports the version in `VERSION`, which the release workflow sets when it tags
350
350
  a release.
351
351
 
352
+ Text that says "since 1.5.0" describes the source tree on `main`, not a
353
+ published package: 1.5.0 is the planned number of the next release, and the
354
+ statements about 1.4.0 keep their historical meaning.
355
+
352
356
  ### Upgrading from 1.3.0
353
357
 
354
358
  For the 1.4.0 pair, regenerate C++ and relink against engine
@@ -475,8 +479,8 @@ transpile(
475
479
  Returns the generated C++ source as a string. Raises
476
480
  `pineforge_codegen.errors.CompileError` on a rejected construct and, since 1.0.0,
477
481
  on a syntax error or an input limit (0.10.4 recovers from some syntax errors
478
- and has no input limits). It does not return nonfatal warnings; use
479
- `transpile_full()` to inspect them.
482
+ and has no input limits). It does not return nonfatal diagnostics (warnings and,
483
+ since 1.5.0, notes); use `transpile_full()` to inspect them.
480
484
 
481
485
  `libraries` is new in 1.0.0. It maps an import path to the library's
482
486
  source (`{"user/name/version": source_text}`), and each import the script uses
@@ -503,8 +507,8 @@ It returns `{"cpp": str, "inputs": list[dict], "strategyParams": dict,
503
507
  "diagnostics": list[Diagnostic], "requests": list[dict]}` on success (0.10.4
504
508
  returns the first three keys; `requests` is new in 1.1.0). `inputs` is the input
505
509
  manifest; its `title` is the actual override key, and an `input.symbol` entry
506
- also has `"kind": "symbol"` (since 1.1.0). `diagnostics` contains nonfatal
507
- warnings. Since 1.4.0, each input also has `supported`, the checked-settings receipt's
510
+ also has `"kind": "symbol"` (since 1.1.0). `diagnostics` contains the nonfatal
511
+ warnings and, since 1.5.0, notes. Since 1.4.0, each input also has `supported`, the checked-settings receipt's
508
512
  flag. Hide inputs with a false flag, exclude them from sweeps and optimization,
509
513
  and do not send a value: the compiled default is used, and the paired engine
510
514
  refuses a supplied value with `setting_unsupported`. A true flag is not a full
@@ -535,17 +539,29 @@ renamed or removed, and the changelog lists the values that changed.
535
539
  A rejected script raises `CompileError` with its diagnostics. The Pyodide
536
540
  package ships `gate/glue.py`'s `transpile_json(source) -> str`, whose JSON
537
541
  success and error envelopes carry the same manifest and, since 1.0.0, the same
538
- warnings; since 1.1.0 the success envelope also carries `requests`. See the
542
+ warnings; since 1.1.0 the success envelope also carries `requests`. Since 1.5.0, notes, the
543
+ informational level described under [Diagnostic codes](#diagnostic-codes),
544
+ travel in the same `diagnostics` lists with `"severity": "note"`. See the
539
545
  [1.0 public contract](https://github.com/pineforge-4pass/pineforge-codegen-oss/blob/main/docs/PUBLIC_CONTRACT.md)
540
546
  for the exact fields, severity values, and input key rules. There is no
541
547
  installed CLI or exit-code contract.
542
548
 
543
549
  ### Diagnostic codes
544
550
 
545
- Every diagnostic carries a stable `code` and named `args` (since 1.2.0):
546
- `PF-E1203` for an error, `PF-W0412` for a warning, and the data its English
547
- `message` and `hint` were built from — identifiers, types, keywords and
548
- numbers, raw.
551
+ Every diagnostic carries a stable `code` (of the form `PF-E1203` or `PF-W0412`)
552
+ and named `args` (since 1.2.0): the data its English `message` and `hint` were
553
+ built from — identifiers, types, keywords and numbers, raw.
554
+
555
+ An `E` code is an error. A `W` code can be a warning or, since 1.5.0, a note:
556
+ read its declared `level` (`severity` in JSON entries and the catalog).
557
+ A note is a nonfatal, informational diagnostic, and it keeps
558
+ the `PF-W` code it had as a warning. Eleven codes are notes: PF-W1505 (the
559
+ `ta.ema` initial-warmup approximation, reported at every `ta.ema` call as a
560
+ general caveat, not a measured shortfall), PF-W1508 and PF-W1509 (a call such as
561
+ `plot` or `alert` that has no effect in a backtest) and PF-W1525 to PF-W1532 (a
562
+ request for outside data whose value reaches only display and alert sinks,
563
+ lowered to `na`). Every other diagnostic keeps its severity, the other
564
+ visual-only and display-only ones included; the catalog is authoritative.
549
565
 
550
566
  ```python
551
567
  from pineforge_codegen import diagnostics_catalog, transpile_full
@@ -557,15 +573,21 @@ for d in transpile_full(source)["diagnostics"]:
557
573
  entry = diagnostics_catalog()["codes"]["PF-W1067"]
558
574
  # {'severity': 'warning', 'area': 'support',
559
575
  # 'message': '{name} diverges from TradingView semantics in PineForge.',
560
- # 'hint': '...', 'explanation': '...', 'args': {'name': {'kind': 'identifier'}}}
576
+ # 'hint': '...', 'explanation': '...', 'args': {'name': {'kind': 'identifier'}},
577
+ # 'user_message': '...'}
561
578
  ```
562
579
 
563
580
  The catalog (`pineforge_codegen/diagnostics_catalog.json`, also attached to
564
581
  each GitHub release) gives each code its severity, English ICU MessageFormat
565
- templates and a one-line explanation; rendering the templates with `args`
566
- gives the `message` and `hint` byte for byte, so an application can translate
567
- a diagnostic by its code. Codes are never reused. See
568
- [Diagnostic codes](docs/PUBLIC_CONTRACT.md#diagnostic-codes).
582
+ `message` and `hint` templates, a one-line explanation and a short
583
+ `user_message` template; rendering the `message` and `hint` templates with
584
+ `args` gives the diagnostic's `message` and `hint` byte for byte, so an
585
+ application can translate a diagnostic by its code. `user_message` is a
586
+ separate short English ICU template (since 1.5.0) over the same `args` (it may be constant):
587
+ the translation source and the fallback for a code an application does not
588
+ know. It is a template, not pre-rendered English, and each `Diagnostic` and
589
+ JSON diagnostic entry carries it as `user_message` too. Codes are never reused.
590
+ See [Diagnostic codes](docs/PUBLIC_CONTRACT.md#diagnostic-codes).
569
591
 
570
592
  ### List the other symbols a script requests
571
593
 
@@ -656,7 +678,8 @@ transpile(src, filename="my_strategy.pine")
656
678
 
657
679
  Not every request for outside data is refused. A
658
680
  `request.financial()` whose value reaches only plots, alerts, tables or logs
659
- transpiles with a warning and reads `na`; 0.10.4 refuses it. The
681
+ transpiles with a note since 1.5.0 (a warning in earlier releases) and reads `na`; 0.10.4
682
+ refuses it. The
660
683
  [changelog](https://github.com/pineforge-4pass/pineforge-codegen-oss/blob/main/CHANGELOG.md)
661
684
  lists what 1.0.0 reads, warns about or refuses for such requests.
662
685
 
@@ -871,6 +894,18 @@ presence of `strategy.close` or `strategy.close_all` in the source. Older C++
871
894
  has removed; regenerate it before compiling there. Reachable close commands
872
895
  keep their ordinary runtime lowering.
873
896
 
897
+ Check how a run ended before you use its report. Read the error text
898
+ (`strategy_get_last_error`), the error code (`strategy_get_last_error_code`)
899
+ **and** the run status (`strategy_last_run_status`): the run failed when the
900
+ text or the code is non-empty or the status is 1. A refusal the engine makes
901
+ before it admits the begin, such as a bar array with a non-finite price, leaves
902
+ the status at its earlier value, so a rerun on a handle whose last run completed
903
+ can read status 0 beside a non-empty error. An engine without the report gate
904
+ (`v1.4.0` and earlier) can also hand a refused rerun on a reused handle the
905
+ previous run's rows. The
906
+ [public contract](https://github.com/pineforge-4pass/pineforge-codegen-oss/blob/main/docs/PUBLIC_CONTRACT.md#a-report-belongs-to-the-call-that-returned-it)
907
+ states the report rule and the engine release that carries it.
908
+
874
909
  Prefer no local build? [pineforge.dev](https://www.pineforge.dev) runs a free
875
910
  hosted MCP server, with a weekly backtest quota, whose `backtest_pine` tool
876
911
  transpiles and backtests a strategy for an AI agent. The
@@ -36,8 +36,8 @@ for the changes in each release from 1.0.0 on and the release-note policy.
36
36
  `transpile_full()` are the supported Python entry points.
37
37
  - **Located diagnostics** — the support checker rejects unsupported Pine with
38
38
  a `file:line:col` location before any C++ is emitted, and
39
- `transpile_full()` returns warnings for supported scripts with documented
40
- approximations.
39
+ `transpile_full()` returns nonfatal warnings and, since 1.5.0, notes for supported scripts,
40
+ including those with documented approximations.
41
41
 
42
42
  ## Releases and this README
43
43
 
@@ -64,6 +64,10 @@ covers 1.0.0 on and links the notes of earlier releases. A source install
64
64
  reports the version in `VERSION`, which the release workflow sets when it tags
65
65
  a release.
66
66
 
67
+ Text that says "since 1.5.0" describes the source tree on `main`, not a
68
+ published package: 1.5.0 is the planned number of the next release, and the
69
+ statements about 1.4.0 keep their historical meaning.
70
+
67
71
  ### Upgrading from 1.3.0
68
72
 
69
73
  For the 1.4.0 pair, regenerate C++ and relink against engine
@@ -190,8 +194,8 @@ transpile(
190
194
  Returns the generated C++ source as a string. Raises
191
195
  `pineforge_codegen.errors.CompileError` on a rejected construct and, since 1.0.0,
192
196
  on a syntax error or an input limit (0.10.4 recovers from some syntax errors
193
- and has no input limits). It does not return nonfatal warnings; use
194
- `transpile_full()` to inspect them.
197
+ and has no input limits). It does not return nonfatal diagnostics (warnings and,
198
+ since 1.5.0, notes); use `transpile_full()` to inspect them.
195
199
 
196
200
  `libraries` is new in 1.0.0. It maps an import path to the library's
197
201
  source (`{"user/name/version": source_text}`), and each import the script uses
@@ -218,8 +222,8 @@ It returns `{"cpp": str, "inputs": list[dict], "strategyParams": dict,
218
222
  "diagnostics": list[Diagnostic], "requests": list[dict]}` on success (0.10.4
219
223
  returns the first three keys; `requests` is new in 1.1.0). `inputs` is the input
220
224
  manifest; its `title` is the actual override key, and an `input.symbol` entry
221
- also has `"kind": "symbol"` (since 1.1.0). `diagnostics` contains nonfatal
222
- warnings. Since 1.4.0, each input also has `supported`, the checked-settings receipt's
225
+ also has `"kind": "symbol"` (since 1.1.0). `diagnostics` contains the nonfatal
226
+ warnings and, since 1.5.0, notes. Since 1.4.0, each input also has `supported`, the checked-settings receipt's
223
227
  flag. Hide inputs with a false flag, exclude them from sweeps and optimization,
224
228
  and do not send a value: the compiled default is used, and the paired engine
225
229
  refuses a supplied value with `setting_unsupported`. A true flag is not a full
@@ -250,17 +254,29 @@ renamed or removed, and the changelog lists the values that changed.
250
254
  A rejected script raises `CompileError` with its diagnostics. The Pyodide
251
255
  package ships `gate/glue.py`'s `transpile_json(source) -> str`, whose JSON
252
256
  success and error envelopes carry the same manifest and, since 1.0.0, the same
253
- warnings; since 1.1.0 the success envelope also carries `requests`. See the
257
+ warnings; since 1.1.0 the success envelope also carries `requests`. Since 1.5.0, notes, the
258
+ informational level described under [Diagnostic codes](#diagnostic-codes),
259
+ travel in the same `diagnostics` lists with `"severity": "note"`. See the
254
260
  [1.0 public contract](https://github.com/pineforge-4pass/pineforge-codegen-oss/blob/main/docs/PUBLIC_CONTRACT.md)
255
261
  for the exact fields, severity values, and input key rules. There is no
256
262
  installed CLI or exit-code contract.
257
263
 
258
264
  ### Diagnostic codes
259
265
 
260
- Every diagnostic carries a stable `code` and named `args` (since 1.2.0):
261
- `PF-E1203` for an error, `PF-W0412` for a warning, and the data its English
262
- `message` and `hint` were built from — identifiers, types, keywords and
263
- numbers, raw.
266
+ Every diagnostic carries a stable `code` (of the form `PF-E1203` or `PF-W0412`)
267
+ and named `args` (since 1.2.0): the data its English `message` and `hint` were
268
+ built from — identifiers, types, keywords and numbers, raw.
269
+
270
+ An `E` code is an error. A `W` code can be a warning or, since 1.5.0, a note:
271
+ read its declared `level` (`severity` in JSON entries and the catalog).
272
+ A note is a nonfatal, informational diagnostic, and it keeps
273
+ the `PF-W` code it had as a warning. Eleven codes are notes: PF-W1505 (the
274
+ `ta.ema` initial-warmup approximation, reported at every `ta.ema` call as a
275
+ general caveat, not a measured shortfall), PF-W1508 and PF-W1509 (a call such as
276
+ `plot` or `alert` that has no effect in a backtest) and PF-W1525 to PF-W1532 (a
277
+ request for outside data whose value reaches only display and alert sinks,
278
+ lowered to `na`). Every other diagnostic keeps its severity, the other
279
+ visual-only and display-only ones included; the catalog is authoritative.
264
280
 
265
281
  ```python
266
282
  from pineforge_codegen import diagnostics_catalog, transpile_full
@@ -272,15 +288,21 @@ for d in transpile_full(source)["diagnostics"]:
272
288
  entry = diagnostics_catalog()["codes"]["PF-W1067"]
273
289
  # {'severity': 'warning', 'area': 'support',
274
290
  # 'message': '{name} diverges from TradingView semantics in PineForge.',
275
- # 'hint': '...', 'explanation': '...', 'args': {'name': {'kind': 'identifier'}}}
291
+ # 'hint': '...', 'explanation': '...', 'args': {'name': {'kind': 'identifier'}},
292
+ # 'user_message': '...'}
276
293
  ```
277
294
 
278
295
  The catalog (`pineforge_codegen/diagnostics_catalog.json`, also attached to
279
296
  each GitHub release) gives each code its severity, English ICU MessageFormat
280
- templates and a one-line explanation; rendering the templates with `args`
281
- gives the `message` and `hint` byte for byte, so an application can translate
282
- a diagnostic by its code. Codes are never reused. See
283
- [Diagnostic codes](docs/PUBLIC_CONTRACT.md#diagnostic-codes).
297
+ `message` and `hint` templates, a one-line explanation and a short
298
+ `user_message` template; rendering the `message` and `hint` templates with
299
+ `args` gives the diagnostic's `message` and `hint` byte for byte, so an
300
+ application can translate a diagnostic by its code. `user_message` is a
301
+ separate short English ICU template (since 1.5.0) over the same `args` (it may be constant):
302
+ the translation source and the fallback for a code an application does not
303
+ know. It is a template, not pre-rendered English, and each `Diagnostic` and
304
+ JSON diagnostic entry carries it as `user_message` too. Codes are never reused.
305
+ See [Diagnostic codes](docs/PUBLIC_CONTRACT.md#diagnostic-codes).
284
306
 
285
307
  ### List the other symbols a script requests
286
308
 
@@ -371,7 +393,8 @@ transpile(src, filename="my_strategy.pine")
371
393
 
372
394
  Not every request for outside data is refused. A
373
395
  `request.financial()` whose value reaches only plots, alerts, tables or logs
374
- transpiles with a warning and reads `na`; 0.10.4 refuses it. The
396
+ transpiles with a note since 1.5.0 (a warning in earlier releases) and reads `na`; 0.10.4
397
+ refuses it. The
375
398
  [changelog](https://github.com/pineforge-4pass/pineforge-codegen-oss/blob/main/CHANGELOG.md)
376
399
  lists what 1.0.0 reads, warns about or refuses for such requests.
377
400
 
@@ -586,6 +609,18 @@ presence of `strategy.close` or `strategy.close_all` in the source. Older C++
586
609
  has removed; regenerate it before compiling there. Reachable close commands
587
610
  keep their ordinary runtime lowering.
588
611
 
612
+ Check how a run ended before you use its report. Read the error text
613
+ (`strategy_get_last_error`), the error code (`strategy_get_last_error_code`)
614
+ **and** the run status (`strategy_last_run_status`): the run failed when the
615
+ text or the code is non-empty or the status is 1. A refusal the engine makes
616
+ before it admits the begin, such as a bar array with a non-finite price, leaves
617
+ the status at its earlier value, so a rerun on a handle whose last run completed
618
+ can read status 0 beside a non-empty error. An engine without the report gate
619
+ (`v1.4.0` and earlier) can also hand a refused rerun on a reused handle the
620
+ previous run's rows. The
621
+ [public contract](https://github.com/pineforge-4pass/pineforge-codegen-oss/blob/main/docs/PUBLIC_CONTRACT.md#a-report-belongs-to-the-call-that-returned-it)
622
+ states the report rule and the engine release that carries it.
623
+
589
624
  Prefer no local build? [pineforge.dev](https://www.pineforge.dev) runs a free
590
625
  hosted MCP server, with a weekly backtest quota, whose `backtest_pine` tool
591
626
  transpiles and backtests a strategy for an AI agent. The
@@ -0,0 +1 @@
1
+ 1.5.0-rc.1