Skip to content

Commit 517a1b4

Browse files
luisleo526HaoLiangWenCORE-TOPclaude
authored
docs: the 1.6.0 release (changelog, current pair, HPO note) (#399)
* docs: the 1.6.0 release (changelog, current pair, HPO note) Prepare the final 1.6.0 release documentation dated 2026-10-17, paired with pineforge-codegen 1.6.0 and the matching pineforge-hpo release for selected-window contract revision 1.3. CHANGELOG.md adds the 1.6.0 — 2026-10-17 entry above 1.6.0-rc.1 — 2026-10-14, carrying forward the release-candidate entry's substance and naming the six documentation and test-only changes merged since v1.6.0-rc.1 (#390, #393, #394, #395, #396, #397). README.md updates the current-release block and the codegen command-block pointer to 1.6.0 and adds the v1.6.0 bullet to the Releases section. The current-release block's 1.5.0 sentence from 4c78f39 ("The release notes cover recorded outputs, the call-scoped report rule and the test inputs' move to a private repository") is replaced on purpose by the 1.6.0 sentence that lists what 1.6.0 covers; that 1.5.0 summary stays in the Releases list (the v1.5.0 bullet) and in CHANGELOG.md's 1.5.0 entry. docs/pages/public-contract.md adds the 1.6.0 paragraph after the 1.5.0 paragraph and updates the same-version pairing line to 1.6.0. * docs: 1.6.0 notes review fixes (HPO pairing line, follow-up figures, value-ownership wording) The paired-HPO line no longer claims HPO support for selected-window revision 1.3; HPO 1.6.0 does not implement selected windows (docs/return-stats.md:9 in pineforge-hpo). The landed follow-ups #396/#397 are said to be checked against their own deliberate bugs, and the figures remain the candidate's. README.md and docker/README.md replace "complete value ownership with" by "value ownership through", the wording of the 1.6.0-rc.1 changelog entry, since no completeness proof was run. The changelog's no-code-change sentence names the docker/README.md rewording. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> --------- Co-authored-by: HaoLiangWen <[email protected]> Co-authored-by: CORE-TOP <[email protected]> Co-authored-by: Claude Opus 5.5 (1M context) <[email protected]>
1 parent ea209c1 commit 517a1b4

4 files changed

Lines changed: 194 additions & 12 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 166 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,172 @@ README's *Releases* section and on the GitHub releases page. From 1.0.0 the
55
version number follows semantic versioning over the surfaces the
66
[public contract](docs/pages/public-contract.md) lists.
77

8+
## 1.6.0 — 2026-10-17
9+
10+
**[1.6.0](https://github.com/pineforge-4pass/pineforge-engine/releases/tag/v1.6.0)**,
11+
paired with [pineforge-codegen 1.6.0](https://github.com/pineforge-4pass/pineforge-codegen-oss/releases/tag/v1.6.0).
12+
This minor release extends typed failures from source values through engine
13+
arithmetic and report production. It ships the
14+
[1.6.0-rc.1](https://github.com/pineforge-4pass/pineforge-engine/releases/tag/v1.6.0-rc.1)
15+
candidate (`04607c191b9f149dd7bbac05996c58f7988aacb5`, with [#388] merged
16+
before that tag) plus the documentation and test-only changes merged since the
17+
candidate ([#390], [#393], [#394], [#395], [#396], [#397]); no code or
18+
harness file under `src/`, `include/`, `cmake/`, `docker/` or `runner/`
19+
changed after `v1.6.0-rc.1` (these notes reword `docker/README.md` only). Regenerate strategy C++ with the matching codegen and relink
20+
against the matching engine headers and archive; replacing the archive alone
21+
does not update a statically linked strategy library.
22+
23+
- **The selected-window contract is revision 1.3 ([#388]).** The
24+
`docker/run_json.py --capabilities-json` probe declares
25+
`capabilities.selected_window_contract_revisions` as `["1.3"]` when the
26+
runtime supports selected windows and `[]` otherwise. This revision covers
27+
value ownership through `strategy_value_invalid`,
28+
`engine_command_value_invalid`, `report_result_invalid` and
29+
`report_post_execution_failed`. The selected-window wire version stays 1,
30+
the phase version 1 and the fingerprint/schema version 2.
31+
- **Invalid values receive typed failures ([#388]).** Source entry, exit,
32+
order, cancel, risk and declaration/margin paths check actionable text,
33+
levels and quantities through typed codes. Invalid derived sizing, margin,
34+
fee/commission, slippage, relative-price, risk threshold/equity and
35+
settlement arithmetic fails closed as `engine_command_value_invalid`.
36+
Native settlement guards refuse an invalid closed row.
37+
- **Trade and summary doubles must be finite ([#384], [#388]).** In ordinary
38+
and selected-window runs, a non-finite trade or summary double fails with
39+
`report_result_invalid`, `field` naming `trades.<leaf>` or
40+
`summary.<leaf>` and `reason` equal to `nonfinite`. Every report writer
41+
enforces JSON, so the document carries no bare `NaN` or `Infinity` token.
42+
After an acknowledged execution boundary, a writer fault stays
43+
`report_post_execution_failed` with `phase: serialization`; without
44+
`--run-phase-fd` in ordinary mode, a non-finite value elsewhere in the report
45+
document fails with `report_result_invalid`, `field: report.document` and
46+
`reason: nonfinite`. Other encoder `ValueError`s in unphased runs, and
47+
encoder refusals in the capabilities and `--validate-window-only` documents,
48+
keep `harness_internal_error` ([#384]). Metrics, the equity curve and
49+
recorded outputs keep their existing handling; a non-finite metric stays
50+
`null`.
51+
- **Retained refusals and diagnostic gaps ([#388]).** Native arming overflow
52+
of `relative_price.level` retains its typed `NonrepresentableQuantity`
53+
refusal, and the retained settlement row guards still use
54+
`engine_invariant`. The pinned signal-time rejection keeps precedence.
55+
An unknown `commission_type` integer still becomes `Percent`, and the
56+
generated legacy `strategy_set_override` export can lose a carried reason.
57+
- **Limits of the value-ownership proof ([#388], [#396], [#397]).** Eight
58+
changed report tests pass on both engine main and the candidate and provide
59+
no fail-before evidence; they have no advance preservation/control
60+
declaration. They cover post-boundary `out_of_memory` as reason
61+
`resource`, post-boundary `engine_unclassified_error` as reason
62+
`exception`, a missing observer acknowledgement stopping before report
63+
access, and a results-digest request refused before execution, each in
64+
ordinary and selected-window mode. Evidence for those behaviors rests on
65+
passing checks, the sweep and parity.
66+
Of 163 mutant pairings, 160 were killed by an assertion in the paired test.
67+
Two were detected by errors rather than assertions and are not counted as
68+
kills.
69+
`quantity_defined_fallback_becomes_error` in
70+
`test_value_admission_arith`: the test process aborted.
71+
`06-stream-half-report-to-stdout` in
72+
`test_encoder_failure_after_report_chunks[exception-selected]`: the test
73+
body's JSON decode of the child output raised.
74+
The one survivor, `d6_13_slippage_evaluation_order`, was closed in this release:
75+
the new row `d6_13_current_slippage_bits` passes on the head and fails under
76+
the mutant.
77+
All 163 restored trees pass, and all 10 settlement pairings were killed.
78+
The two follow-ups planned before the 1.6.0 final to make the two
79+
error-detected tests fail by an assertion landed after `v1.6.0-rc.1`
80+
([#396], [#397], each checked against its own deliberate bug), described
81+
below; the figures above are the candidate's.
82+
The proof does not close every
83+
word-composition or census gap: four mutant rows and an equivalent mutant
84+
remain uncovered.
85+
- **The C API documentation uses the shared PineForge favicon ([#355]).**
86+
The documentation selects the canonical icon through Doxygen's
87+
`PROJECT_ICON` setting.
88+
- **Tests, CI and benchmarks.** More test sources move from the public tree to
89+
private fixtures; rows that need them register SKIP placeholders when absent,
90+
and these source moves do not affect the release-built assets ([#375],
91+
[#386]). The rewritten public tests keep their intent, registration and
92+
pinned assertions ([#382]). Corpus
93+
updates keep the default validation sweep's scope and the baseline digests;
94+
corpus regeneration is pinned to codegen 1.5.0 ([#376], [#377]). Corpus
95+
probe directories that need non-public inputs are removed; the default
96+
validation sweep never included them and the baseline digests stay unchanged
97+
([#376]). CI removes stage and subprocess deadlines and native-live test wait
98+
bounds; a stop at the platform job maximum is labelled `HANG (re-run)` and
99+
the check fails. Two registered rows retain a 600-second wait and a 5-second
100+
read bound ([#378]). The native-live service test's cleanup no longer has a
101+
kill fallback ([#378]).
102+
- **Removed command-line options ([#378]).** `scripts/ci_verify.py` removes
103+
`--test-timeout`, `--ctest-timeout`, their config fields and the summary
104+
fields `testTimeoutSeconds` and `ctestTimeoutSeconds` ([#378]).
105+
- **Benchmark comparison and quiet gate.** Benchmarks describe the closed
106+
strategies as held-out private strategies, not redistributed ([#385]). The
107+
external comparison harness is optional: without it the comparison leg is
108+
skipped and a run leaves committed speed results intact ([#383]). The
109+
external comparison harness and the 2026-09-29 load-time table leave this
110+
repository; the optional leg requires a supplied harness directory, and speed
111+
reports without its timings omit that comparison's columns and rows ([#383]).
112+
Without `ps`, the busy count is `unknown (ps absent)` and timing figures are
113+
labelled `quiet-unverified`; those figures are not performance evidence and
114+
do not replace committed speed results ([#387]). Without `ps`, a benchmark
115+
run proceeds with an unknown busy count; `QUIET_LOAD_MAX` then uses load
116+
average alone and remains bounded by `QUIET_WAIT_S` ([#387]).
117+
- **Documentation and test-only changes since `v1.6.0-rc.1` ([#390], [#393], [#394], [#395], [#396], [#397]).**
118+
- **API documentation theme, canonical URLs, `robots.txt`, `sitemap.xml` and version label ([#390], [#394]).**
119+
The Doxygen footer links `https://pineforge.dev` in both footer branches,
120+
`docs/_theme/404.html` and `docs/_theme/robots.txt` are copied to the site
121+
root through `HTML_EXTRA_FILES` in `docs/Doxyfile`, and
122+
`docs/_theme/header.html` uses per-page title descriptions ([#390], [#394]).
123+
`docs/seo_postprocess.py` runs after Doxygen in `docs/build.sh` to add one
124+
`rel="canonical"` link per top-level page (`https://cdocs.pineforge.dev/<page>`,
125+
the landing page as the site root), rewrite relative `.html` page links
126+
(`index.html` to `./`, anchors preserved), set one meta description per
127+
page, and generate `sitemap.xml` from the built top-level pages excluding
128+
`404.html`. `docs/build.sh` sets the site version label to the tag name
129+
only for a clean checkout of an exact tag and to `unreleased` otherwise.
130+
The `.github/workflows/docs.yml` build job runs
131+
`bash docs/build.sh --self-test-seo` before building the site, and
132+
`scripts/ci_docs_only.py` (`PROOF_READS`), `scripts/test_ci_docs_only.py`
133+
and `docs/ci.md` list `docs/seo_postprocess.py` among the five
134+
documentation-build inputs excluded from docs-only CI skips ([#394]).
135+
- **Release-candidate notes, README apex link and 1.5.0 notes additions ([#393]).**
136+
Added the `1.6.0-rc.1` changelog entry, updated the `README.md` header
137+
link from `https://www.pineforge.dev` to `https://pineforge.dev`, and added
138+
*Additions to the 1.5.0 notes* in `CHANGELOG.md` for the opt-in
139+
selected-window mode ([#363]) and `_typed_failure` in `docker/run_json.py`.
140+
- **Value-failure raise sites on the run-failure-codes page ([#395]).**
141+
`docs/pages/run-failure-codes.md` lists fifteen of the 24 selected-window
142+
and report-contract codes as having a raise site in this tree:
143+
`strategy_value_invalid` in the C++ source layer,
144+
`engine_command_value_invalid` in the engine kernel, native engine and Pine
145+
adapter, and `report_result_invalid` in `docker/run_json.py`, alongside the
146+
twelve `docker/` wrapper codes, leaving nine codes with no producer in this
147+
tree.
148+
- **Assertion on the quantity-grid overflow fallback ([#396]).**
149+
In `tests/test_value_admission_arith.cpp`,
150+
`quantity_infinite_intermediate_fallback` places a cash-typed entry (`cash`
151+
`1e308`, `price` `2`, `grid` `0.001`) through `strategy_entry`, catches a
152+
thrown failure as a failed `CHECK` rather than terminating through a
153+
`noexcept` boundary, and asserts the admitted contracts equal `cash / price`
154+
bit for bit; the explicit fixed-quantity overflow check stays in
155+
`quantity_explicit_overflow_fallback` when the cash row records no failure.
156+
- **Assertion that a failed report writes one whole JSON document on stdout ([#397]).**
157+
In `tests/test_run_json_post_execution.py`, `assert_failure` requires the
158+
owned stdout to be one JSON-object line (turning a JSON decode error into
159+
an `AssertionError` naming the prefix and length), and
160+
`test_encoder_failure_after_report_chunks` asserts from the recorded fault
161+
prefix that no report chunk reached stdout and that `stdout.write` was
162+
called once.
163+
- **HPO.** Pair with the matching `pineforge-codegen 1.6.0` and `pineforge-hpo`
164+
1.6.0 (`pineforge-hpo` 0.13.2 pinned `pineforge-codegen <1.4`, and 0.14.0 added
165+
support for codegen 1.4 and 1.5).
166+
167+
[#390]: https://github.com/pineforge-4pass/pineforge-engine/pull/390
168+
[#393]: https://github.com/pineforge-4pass/pineforge-engine/pull/393
169+
[#394]: https://github.com/pineforge-4pass/pineforge-engine/pull/394
170+
[#395]: https://github.com/pineforge-4pass/pineforge-engine/pull/395
171+
[#396]: https://github.com/pineforge-4pass/pineforge-engine/pull/396
172+
[#397]: https://github.com/pineforge-4pass/pineforge-engine/pull/397
173+
8174
## 1.6.0-rc.1 — 2026-10-14
9175

10176
**[1.6.0-rc.1](https://github.com/pineforge-4pass/pineforge-engine/releases/tag/v1.6.0-rc.1)**,

‎README.md‎

Lines changed: 12 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -38,18 +38,20 @@ The separate PineForge compiler, [`pineforge-codegen`](https://github.com/pinefo
3838
Recorded outputs and their additional API declarations described here are
3939
part of **1.5.0**.
4040

41-
**[1.5.0](https://github.com/pineforge-4pass/pineforge-engine/releases/tag/v1.5.0)
42-
was released on 2026-10-12**, paired with
43-
[pineforge-codegen 1.5.0](https://github.com/pineforge-4pass/pineforge-codegen-oss/releases/tag/v1.5.0).
44-
The [release notes](CHANGELOG.md#150--2026-10-12) cover recorded outputs, the
45-
call-scoped report rule and the test inputs' move to a private repository.
46-
For the 1.5.0 pair, regenerate strategy C++ and relink against that pair's
41+
**[1.6.0](https://github.com/pineforge-4pass/pineforge-engine/releases/tag/v1.6.0)
42+
was released on 2026-10-17**, paired with
43+
[pineforge-codegen 1.6.0](https://github.com/pineforge-4pass/pineforge-codegen-oss/releases/tag/v1.6.0).
44+
The [release notes](CHANGELOG.md#160--2026-10-17) cover selected-window
45+
contract revision 1.3, typed failures across source values, engine arithmetic
46+
and report production, finite trade and summary doubles, and the documentation,
47+
test, CI and benchmark updates since 1.5.0.
48+
For the 1.6.0 pair, regenerate strategy C++ and relink against that pair's
4749
headers and archive. Published 1.3.0 download and installation examples below
4850
remain pinned to that earlier pair.
4951

5052
The engine/codegen **1.6.0** image advertises selected-window contract revision
51-
`1.3` through `docker/run_json.py --capabilities-json`: complete value ownership
52-
with `strategy_value_invalid`, `engine_command_value_invalid`,
53+
`1.3` through `docker/run_json.py --capabilities-json`: value ownership through
54+
`strategy_value_invalid`, `engine_command_value_invalid`,
5355
`report_result_invalid` and `report_post_execution_failed`.
5456
`capabilities.selected_window_contract_revisions` is `["1.3"]` when the runtime
5557
supports selected windows and `[]` otherwise; see the
@@ -152,7 +154,7 @@ TradingView's execution semantics on top of the kernel; this is the path the
152154
validation scoreboard below measures.
153155
154156
This command block is for the published engine/codegen **1.3.0 pair**.
155-
For 1.5.0, use the matching release tags linked above and regenerate and
157+
For 1.6.0, use the matching release tags linked above and regenerate and
156158
relink against that pair's headers and archive.
157159
158160
```bash
@@ -683,6 +685,7 @@ Documentation: [C ABI reference](https://cdocs.pineforge.dev) · [Getting starte
683685

684686
## Releases
685687

688+
- **[v1.6.0](https://github.com/pineforge-4pass/pineforge-engine/releases/tag/v1.6.0)** (2026-10-17) — selected-window contract revision `1.3` (`capabilities.selected_window_contract_revisions: ["1.3"]` on a supported runtime and `[]` otherwise); typed failures across source value admission (`strategy_value_invalid`), derived execution and settlement arithmetic (`engine_command_value_invalid`), non-finite canonical trade or summary doubles (`report_result_invalid`) and post-boundary serialization faults (`report_post_execution_failed`), with every report writer enforcing JSON so no bare `NaN` or `Infinity` token is emitted; Doxygen favicon, 404 page, `robots.txt`, `sitemap.xml`, canonical URLs and tag-or-`unreleased` version label; CI deadline and timeout-flag removals, private-fixture test moves and benchmark comparison/quiet-gate updates. The C layouts stay at ABI 4, `PF_ABI_VERSION` stays 4, the selected-window wire version stays 1, the phase version 1 and the fingerprint/schema version 2. Pair with codegen 1.6.0, regenerate and relink. See [CHANGELOG.md](CHANGELOG.md#160--2026-10-17).
686689
- **[v1.5.0](https://github.com/pineforge-4pass/pineforge-engine/releases/tag/v1.5.0)** (2026-10-12) — recorded outputs: a module can record per-bar doubles in named slots, run-level doubles and events, read through the nine `pf_outputs` runtime exports with coded refusals, off until a caller turns them on and byte-identical when unused; a run's report belongs to the call that began it; the engine's test inputs and strategy scripts moved to a private repository, with tests that need them skipping by name, a LEGAL.md *Data not distributed* note and a maintainers' private-fixture overlay. The C layouts stay at ABI 4, `PF_ABI_VERSION` stays 4 and the new members enter `engine_script_run_v19` without an epoch. Pair with codegen 1.5.0, regenerate and relink. See [CHANGELOG.md](CHANGELOG.md#150--2026-10-12).
687690
- **[v1.4.0](https://github.com/pineforge-4pass/pineforge-engine/releases/tag/v1.4.0)** (2026-10-08) — two additive C failure getters; typed input/override provenance with explicit unresolved reasons and duplicate-title counts; coded failure JSON and checked-setting refusals; Pine exit/fill-location corrections that can change trades, reports and hash values on the affected paths; chart-timeframe live input and final-delivery draining; feed ownership and verification improvements. The C layouts stay at ABI 4, while hash recipes and report content have the disclosed changes. Pair with codegen 1.4.0, regenerate and relink. See [CHANGELOG.md](CHANGELOG.md#140--2026-10-08).
688691
- **v1.3.0** (2026-10-06) — a minor release: `pineforge-live` admits the proven confirmed-bar request shapes and standalone close-only `varip` from the confirmed-bar receipt a strategy generated by pineforge-codegen 1.3.0 exports; Pine adapter parity changes (exit binding at the call, global exits on a held position beside an opposite entry or a same-side add, margin calls at the open after a `process_orders_on_close` close fill, the margin-call schedule, the exact reversal tie, the carried trail, the position view after a close fill, open-marketable exits first). `pineforge.h` is unchanged. No report key changes. The hub image `pineforge-release:1.3.0` carries the pair; regenerate and relink. See [CHANGELOG.md](CHANGELOG.md).

‎docker/README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -269,8 +269,8 @@ docker run --rm \
269269
### Selected-window contract revision
270270

271271
The engine/codegen **1.6.0** image's `run_json.py --so <strategy.so>
272-
--capabilities-json` probe declares revision `1.3`, meaning complete value
273-
ownership with `strategy_value_invalid`, `engine_command_value_invalid`,
272+
--capabilities-json` probe declares revision `1.3`, covering value ownership
273+
through `strategy_value_invalid`, `engine_command_value_invalid`,
274274
`report_result_invalid` and `report_post_execution_failed`.
275275

276276
| Capability member | Supported runtime | Unsupported runtime |

‎docs/pages/public-contract.md‎

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,20 @@ gives each run's report to the call that began it. The repository's
3939
[CHANGELOG.md](../../CHANGELOG.md#150--2026-10-12), under
4040
*1.5.0 — 2026-10-12*, inventories both and the test inputs' move to a
4141
private repository.
42-
Use the same-version 1.5.0 pair, with regeneration and relinking as below.
42+
43+
1.6.0 followed on 2026-10-17: engine v1.6.0 with pineforge-codegen 1.6.0.
44+
It declares selected-window contract revision `1.3` (`["1.3"]` under
45+
`capabilities.selected_window_contract_revisions` when the runtime supports
46+
selected windows and `[]` otherwise) and extends typed failures across source
47+
value admission (`strategy_value_invalid`), derived execution and settlement
48+
arithmetic (`engine_command_value_invalid`), non-finite canonical trade or
49+
summary doubles (`report_result_invalid`) and post-boundary serialization
50+
faults (`report_post_execution_failed`), without changing C layouts or
51+
`PF_ABI_VERSION` 4. The repository's
52+
[CHANGELOG.md](../../CHANGELOG.md#160--2026-10-17), under
53+
*1.6.0 — 2026-10-17*, inventories these changes and the documentation, test,
54+
CI and benchmark updates since 1.5.0.
55+
Use the same-version 1.6.0 pair, with regeneration and relinking as below.
4356

4457
## Versions
4558

0 commit comments

Comments
 (0)