Skip to content

Commit fd7013e

Browse files
authored
docs: CHANGELOG 1.8.0 section with migration notes (#527)
## What Adds the `## 1.8.0 — 2026-10-27` section (with migration notes) to `CHANGELOG.md`, above `## 1.7.0`. `CHANGELOG.md` is the only file changed (+131/-0). Documentation only: no `src/`, `include/`, `docker/`, `scripts/`, `tests/` or workflow file is touched. ## Why The engine release body is generated from git-log subjects only and carries no migration notes; the release notes users read are this file (and the GitHub release body edited from it after publish). The notes must be on main before the release dispatch. ## Content - Compatibility and migration: exact pairing with codegen 1.8.0, regenerate C++ and relink every strategy library, no public header change, the new codegen `color` input type, the changed harness file `docker/run_json.py`. - Faster `run_json` report handling (#517) with the measured table against 1.6.3 and 1.7.0 and the statement that the gap to 1.6.3 is not closed. - Scratch placement restated (#518); the unused storage building block (#515; its allocation-gate sites are unreviewed, no bound claimed); a known limit (memory with never-filled pending orders, "a fix is planned for a later release"). - CI and release process: every merged change since 1.7.0 not listed above (#505-#510, #513, #514, #516, #519, #520, #522, #469, #481, #504). Every line is taken from the merged commit body; none claims a behaviour change for a tests-only or CI-only change. Not in this commit (not on main at base `641349a`): the release gate, tmpwatch and the TvJO fix. Each gets one line from its merged PR body as a follow-up commit on this branch before this PR merges; this PR is meant to merge after those three. ## Checks - Route: docs-only, `lab verify --via ci-only` (no sweep). - Read as a committed diff by an independent reviewer: GO. All 18 engine commits `v1.7.0..641349a` have a bullet, none extra. - Numbers: the #517 timings and RSS are the measurements in the #517 body; the ratios in the text were recomputed (1.77/0.36 = 4.9, 8.26/1.35 = 6.1, 8.94/5.39 = 1.66; 4.61/0.36 = 12.8, 22.31/1.35 = 16.5, 22.99/5.39 = 4.27). - The heading date `2026-10-27` is the planned tag date and is corrected before the tag if the date moves. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
1 parent d463222 commit fd7013e

1 file changed

Lines changed: 159 additions & 0 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 159 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,165 @@ 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.8.0 — 2026-10-27
9+
10+
**[1.8.0](https://github.com/pineforge-4pass/pineforge-engine/releases/tag/v1.8.0)**,
11+
paired with [pineforge-codegen 1.8.0](https://github.com/pineforge-4pass/pineforge-codegen-oss/releases/tag/v1.8.0).
12+
A minor release. It speeds up the `run_json` wrapper (the wrapper only, not the
13+
engine), adds one unused storage building block to the library, states where
14+
scratch files are placed, and carries release-gate and CI changes. The C ABI
15+
(`PF_ABI_VERSION` 4), the report keys and the run-failure code catalog are
16+
unchanged (0 codes added, changed or removed since 1.7.0).
17+
18+
### Compatibility and migration
19+
20+
- Pairs with codegen 1.8.0 exactly. Regenerate strategy C++ with codegen 1.8.0
21+
and relink every strategy library against the 1.8.0 headers and
22+
`libpineforge.a`, as for every pair change; replacing the archive alone does
23+
not update a statically linked strategy library.
24+
- No public header changed. The only new header is
25+
`include/pineforge/detail/o1_store.hpp`, an internal building block that no
26+
engine path uses yet (below); its object code is part of `libpineforge.a`,
27+
which therefore grows slightly.
28+
- Hosts that read the codegen input manifest must recognize the new input type
29+
`color` (a packed unsigned `0xAARRGGBB` integer default). That is a codegen
30+
change, described in the codegen 1.8.0 notes; the engine side is unchanged:
31+
color inputs are still stored and reported as `int64` through
32+
`get_input_int64`.
33+
- The release harness file `docker/run_json.py` changed (below). The hub image
34+
for this pair carries the 1.8.0 copy.
35+
36+
### Faster `run_json` report handling
37+
38+
- **Fewer passes over the report sink (#517).** `docker/run_json.py`
39+
now takes about three full passes over the report sink instead of about
40+
eleven. The verify pass, which already reads the whole sink for its digest,
41+
also folds the trade summary, the first and last equity points and the equity
42+
finiteness check; the annualization block gets a two-point object instead of
43+
five full re-reads (`point_at`); and the report writer emits flat records of
44+
exact scalar types with one `json.dumps`, joined in batches fixed at 512
45+
records and 256 KiB (a string field over 4096 characters keeps the windowed
46+
path). The sink reader (`pf_sink.py`) is untouched. Trades and report
47+
bytes are unchanged (identical under the accepted normalization of the timing
48+
fields in all six measured cells) and peak RSS is unchanged (72.9 MB against
49+
72.7 MB at 100k bars). Measured on one spot box, four repetitions per cell,
50+
same tag build and shared library, only the wrapper replaced:
51+
52+
| bars | script | 1.6.3 | 1.7.0 | 1.8.0 |
53+
|---|---|---|---|---|
54+
| 20k | fixed ids | 0.36 s | 4.61 s | 1.77 s |
55+
| 100k | fixed ids | 1.35 s | 22.31 s | 8.26 s |
56+
| 100k | unique ids | 5.39 s | 22.99 s | 8.94 s |
57+
58+
This removes the wrapper's multi-pass cost, and it is a partial recovery: the
59+
1.7.0 wrapper took about 4 to 17 times the 1.6.3 time on these cells (12.8x,
60+
16.5x and 4.3x), and 1.8.0 takes about 5 times at 20k bars with fixed ids,
61+
about 6 times at 100k bars with fixed ids and about 1.7 times at 100k bars
62+
with unique ids. The gap to 1.6.3 is **not** closed. The engine's own
63+
per-record sink parse and the dense-script close path are separate work, not in
64+
this release.
65+
66+
### Scratch placement (behaviour of 1.7.0 and later, restated)
67+
68+
- **Where scratch goes and when a run is refused.** The text is in
69+
[run-failure-codes](docs/pages/run-failure-codes.md) (#518) and restates the
70+
1.7.0 rules for hosts that place scratch on memory-backed paths. Without an
71+
explicit scratch directory, a native run with no scratch arena attached
72+
creates one unlinked command-scratch file at begin, under the nonempty
73+
`TMPDIR`, or under `/tmp` when `TMPDIR` is unset or empty. If that candidate
74+
is proven tmpfs/ramfs, the engine falls back to `/var/tmp`, and only when
75+
`/var/tmp` is disk-backed. If both candidates are memory-backed the run is
76+
refused at begin: the engine raises `scratch_io_failed`, and the default
77+
unjailed `run_json` profile refuses first with `run_request_invalid`;
78+
through the hub entrypoint the refusal surfaces as container exit code 4.
79+
An explicit `PINEFORGE_COMMAND_SCRATCH_DIR` on tmpfs/ramfs never falls back
80+
and raises `scratch_io_failed`. Example: in a container image where `/run`
81+
is tmpfs while `/tmp` and `/var/tmp` are on ext4, a work directory under
82+
`/run` is memory-backed; a run with `TMPDIR` set there falls back to
83+
`/var/tmp`. To choose the location, set `TMPDIR` to a disk-backed directory
84+
such as `/var/tmp`; `PINEFORGE_COMMAND_SCRATCH_DIR` covers the command stores
85+
only, not the trade ledger or the report files. This is not a change of
86+
behaviour in 1.8.0.
87+
88+
### Storage building block
89+
90+
- **Fixed-shape O(1) store for Pine collections (#515).**
91+
`pineforge::detail` gains a chunked store (`o1_store.hpp`, `o1_store.cpp`)
92+
whose chunk buffer and resident pages are capped in the constructor
93+
(`kMaxChunkBytes` 64 KiB, `kMaxResidentPages` 1024) with a typed refusal at
94+
the cap, and transactions with rollback. Nothing in the engine uses it yet,
95+
so no run changes. It is tested in `tests/test_o1_store.cpp`, and the
96+
source allocation gate lists its new sites as unreviewed entries
97+
(no bound is claimed for them).
98+
99+
### Known limits
100+
101+
- **Memory with never-filled pending orders.** On dense scripts,
102+
memory still grows with the number of pending orders that never fill, by
103+
about 2.5 kB each. A fix is planned for a later release.
104+
105+
### CI and release process
106+
107+
- **Light jobs on a pinned hosted image.** The light, secret-free CI jobs run
108+
on a pinned GitHub-hosted image (#514); the AGENTS.md runner
109+
routing is documented (#513).
110+
- **Actions pinned to commit shas.** Every third-party GitHub Action is pinned
111+
to a full commit sha with a version comment, and preflight lints it
112+
(#508).
113+
- **Release guard hardening.** The permission-claim text guard also catches
114+
backslash-wrapped, bytes-decoded and fullwidth respellings (#506); the
115+
release ruleset probe lists every branch ruleset and changes no gate verdict
116+
(#505); the promote-baseline ancestry check and the doc-reverts default base
117+
fully qualify their remote-tracking refs (#507).
118+
- **Source allocation bound gate.** CI checks the engine and generated C++
119+
against an allocation-bound inventory with scoped site identities
120+
(#469). The inventory is not yet reviewed: its entries are unreviewed or
121+
pending flat-memory work, and the gate fails on a new container site.
122+
- **Release gate reads the post-merge run (#526).** The release gate
123+
(`scripts/ci_release_gate.py`) now also requires a green, non-skipped
124+
`ci-post` run of the commit being released, with all four build legs
125+
(`ubuntu-24.04` and `macos-26`, Debug and Release) successful. Until now it
126+
read only the `pineforge/verify` and `pineforge/parity` statuses. When the
127+
release commit is documentation-only it checks the nearest earlier commit that
128+
is not (at most 20 documentation-only commits), and every skipped
129+
documentation-only commit needs a successful `ci-post` run of its own. A newer
130+
run of the same commit with a failed, cancelled or timed-out build job
131+
refuses the release; so does any other non-success result. A newer run whose build legs
132+
were all skipped is passed over in favour of an older full green run. Runs on
133+
other branches are not counted. The gate only reads results: it changes no
134+
build or engine behaviour, and its command line is unchanged.
135+
- **Live equivalence row.** Corpus equivalence runs as a required CTest row in
136+
the live suites (#481).
137+
- **Kernel residuals check.** `scripts/check_kernel_residuals.py` no longer
138+
reports a free-standing `strings` line as an unruled identifier when no
139+
symbol, installed header or decoded source literal corroborates it: the macOS
140+
arm64 Release archive prints a four-byte machine-code run through
141+
`strings -a`, which the check had read as an identifier. The limit is stated
142+
in the change: a bare archive identifier with no corroborating evidence is no
143+
longer detected by this check (#525, checker and its tests only, no engine
144+
behaviour change).
145+
- **Scratch-on-tmpfs tests ignore co-tenant files.** The default and jailed
146+
scratch-on-tmpfs tests no longer fail when another job on the same CI machine
147+
creates files in `/tmp`, `/var/tmp` or `/dev/shm`: the tmpfs candidate is a
148+
private directory owned by the test, and in `/tmp` and `/var/tmp` only files
149+
this process creates through `mkstemp` are counted. Tests only, no change to the
150+
engine or its headers; the stated limit is that scratch created through
151+
another call in those two roots would not be seen (#521).
152+
- **Post-runner capability canary.** A dispatch-only workflow
153+
(`fleet-post-capability.yml`) checks that a new post runner VM can run the
154+
post jobs before it joins the post pool. It has no push, pull request or
155+
schedule trigger, builds nothing and runs no engine suite (#520).
156+
- **Tests and docs.** The `TIMEOUT 180` ctest property is dropped (#504); the
157+
run-failure diff tests hold before and after a release reset (#509); the
158+
doc-reverts test no longer inherits the caller's base (#516); release notes
159+
for earlier engine releases are backfilled (#510); the three borrowed-fd
160+
tests compare a descriptor's flags without Darwin's "descriptor was written"
161+
bit, with diagnostics that name the flag and step that changed (#519, tests
162+
only, no `src/` or `include/` change); the pytest-backed
163+
`test_run_json_stream_fastpath` row no longer carries the `fast` label, so the
164+
pull request release job's `fast` selection, which installs no pytest, does
165+
not run it (#522, tests only).
166+
8167
## 1.7.0 — 2026-10-25
9168

10169
This release adds report-sink transport, scratch-backed history and bounded

0 commit comments

Comments
 (0)