Skip to content

Commit 58c42ca

Browse files
luisleo526claude
andauthored
docs: declare the selected-window path public for walk-forward use, with a doc-lint rule that holds it (#564)
Declares the selected-window path a public surface for walk-forward use: docs/pages/public-contract.md gains a section citing the public entry points (the run_json selected-window options and capabilities record, the report policy, and the selected_window.h / selected_window_plan.h PF_API functions), how a consumer detects support and the contract revision, the 1.x stability rule, what is not public, and how walk-forward windows map onto independent requests. The README points to it, and a doc-lint rule holds the section to the tree. Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
1 parent d590ca1 commit 58c42ca

5 files changed

Lines changed: 383 additions & 3 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,11 @@ diagnostics keys, described below.
1919

2020
### Compatibility and migration
2121

22+
- **Selected windows are public for walk-forward use.** The
23+
[public contract](docs/pages/public-contract.md#selected_windows_walk_forward)
24+
declares the CLI options, capability probe, report policy and versioned C
25+
headers consumers may build on, with append-only functions and flags in
26+
1.x. Each walk-forward window is one independent request.
2227
- **Supported platforms: Linux x86_64 and arm64.** From 1.8.0 the engine is built, tested and published for Linux only: the release carries `pineforge-v1.8.0-linux-x86_64.tar.gz` and `pineforge-v1.8.0-linux-aarch64.tar.gz` (each with a `.sha256`) and no macOS archive, and CI no longer runs macOS jobs. A macOS build is neither tested nor supported.
2328
- Pairs with codegen 1.8.0 exactly. Regenerate strategy C++ with codegen 1.8.0
2429
and relink every strategy library against the 1.8.0 headers and

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -73,6 +73,8 @@ without a hub image, declares `1.3-parity`).
7373
runtime supports selected windows and `[]` otherwise; see the
7474
[capability table](docker/README.md#selected-window-contract-revision) and
7575
[report schema](docs/pages/report-schema.md).
76+
The [public contract for selected windows and walk-forward use](docs/pages/public-contract.md#selected_windows_walk_forward)
77+
defines the supported CLI and C entry points, capability detection and stability rules.
7678

7779
---
7880

‎docs/pages/public-contract.md‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -83,6 +83,9 @@ published 1.6.0 image declared `1.3` without a completeness proof; and engine
8383
[CHANGELOG.md](../../CHANGELOG.md), under *1.7.0*, inventories this
8484
change.
8585

86+
The public surface and stability rules for these revisions are in
87+
[Selected windows and walk-forward use](#selected_windows_walk_forward).
88+
8689
## Versions
8790

8891
- A release's version is `X.Y.Z`, or `X.Y.Z-rc.N` (N from 1) for a release
@@ -152,6 +155,129 @@ structs and enumerations, and the `PF_*` constants.
152155
`src/c_abi.cpp`'s `static_assert`s pin the `pf_magnifier_distribution_t`
153156
values. No checker compares a value with the previous release.
154157

158+
## Selected windows and walk-forward use {#selected_windows_walk_forward}
159+
160+
The selected-window path is **PUBLIC for walk-forward use** through the
161+
`docker/run_json.py` command line or the C headers
162+
`<pineforge/selected_window.h>` and `<pineforge/selected_window_plan.h>`.
163+
A walk-forward driver such as the HPO native layer may submit successive
164+
non-overlapping windows over one chart, for example `[T0, T1)` followed by
165+
`[T1, T2)`. Each window is one independent request. The CLI creates a fresh
166+
strategy state for its request in `_make_state` (`docker/run_json.py:4841`)
167+
inside `_selected_run` (`docker/run_json.py:4748`).
168+
169+
### Public request and capability surface
170+
171+
These are the selected-window options declared by the CLI:
172+
173+
| Option | Contract | Declaration |
174+
| --- | --- | --- |
175+
| `--report-policy selected-window/v1` | Opt into the selected-window report policy. | `add_argument` (`docker/run_json.py:5236`) |
176+
| `--window-start-ms` | Start T in calendar-aligned Unix milliseconds. | `add_argument` (`docker/run_json.py:5256`) |
177+
| `--window-end-ms` | End E in calendar-aligned Unix milliseconds; T < E. | `add_argument` (`docker/run_json.py:5258`) |
178+
| `--preroll-bars` | Requested warm-up N in script bars, from 0 through 5000. | `add_argument` (`docker/run_json.py:5243`) |
179+
| `--fed-start-ms` | Frozen start F of the supplied primary feed; F <= T. | `add_argument` (`docker/run_json.py:5245`) |
180+
| `--capabilities-json` | With `--so LIB`, report runtime support without reading OHLCV or running a strategy. | `add_argument` (`docker/run_json.py:5247`) |
181+
| `--validate-window-only` | Validate and plan the request; return `report_window` with `applied: false`, without executing a strategy. | `add_argument` (`docker/run_json.py:5267`) |
182+
| `--run-phase-fd` | Inherited AF_UNIX SOCK_STREAM descriptor N >= 3 for phase transport v1. | `add_argument` (`docker/run_json.py:5253`) |
183+
| `--request-feed-inventory` | Inventory bound to the strategy library, used for selected-window admission. | `add_argument` (`docker/run_json.py:5256`) |
184+
| `--report-shape` | This build offers `full/v1` for selected-window requests. | `add_argument` (`docker/run_json.py:5276`) |
185+
| `--curve-point-budget` | Refused by this build, which does not offer a compact shape. | `add_argument` (`docker/run_json.py:5278`) |
186+
| `--results-digest` | Refused by this build, which does not offer a results digest. | `add_argument` (`docker/run_json.py:5264`) |
187+
188+
An execution request supplies the policy, all four window arguments and
189+
explicit `--input-tf` and `--script-tf` values, as checked by
190+
`validate_request` (`docker/selected_window_report.py:200`), together with the
191+
strategy library, chart and request-feed inventory. The selected interval is
192+
`[T, E)`; preroll precedes T, as the configuration header documents.
193+
194+
Before relying on the CLI path, probe the library with
195+
`docker/run_json.py --so LIB --capabilities-json`. The probe is
196+
`_capabilities_main` (`docker/run_json.py:4731`); its support decision is
197+
`_runtime_supports_selected_window` (`docker/run_json.py:4702`), which checks
198+
the selected-window ABI, execution observer, phase transport and planner.
199+
The capability record is built by
200+
`capabilities_record` (`docker/selected_window_report.py:718`).
201+
Require `capabilities.selected_window_wire_version == 1`,
202+
`capabilities.report_policy == "selected-window/v1"`, `full/v1` in
203+
`capabilities.report_shapes`, and a
204+
`capabilities.selected_window_contract_revisions` literal that the driver
205+
understands. This tree declares `["1.3"]` on a supported runtime and `[]`
206+
otherwise; see the [capability table](../../docker/README.md#selected-window-contract-revision)
207+
for revision history. The revision is declared in the probe, not in each
208+
report. The probe also sets `selected_window_bars_bin_version`
209+
(`docker/run_json.py:4744`) to 0: selected-window requests
210+
require a CSV chart. General binary-feed support does not imply selected-window
211+
binary-chart support.
212+
213+
### Public C entry points
214+
215+
The public declarations include the descriptors and return contracts in the
216+
two headers:
217+
218+
| Header | Function and declaration | Purpose |
219+
| --- | --- | --- |
220+
| `include/pineforge/selected_window.h` | `pf_selected_window_version` (`include/pineforge/selected_window.h:61`) | Selected-window ABI version, currently 1. |
221+
| `include/pineforge/selected_window.h` | `strategy_set_selected_window_v1` (`include/pineforge/selected_window.h:84`) | Copy pending bounds, or clear selection with a null descriptor, for the next admitted generation. |
222+
| `include/pineforge/selected_window.h` | `strategy_selected_window_counts_v1` (`include/pineforge/selected_window.h:99`) | Read counts belonging to the latest attempt's successful selected Results generation. |
223+
| `include/pineforge/selected_window_plan.h` | `pf_selected_plan_version` (`include/pineforge/selected_window_plan.h:114`) | Planner bridge version, currently 1. |
224+
| `include/pineforge/selected_window_plan.h` | `pf_plan_selected_primary_v1` (`include/pineforge/selected_window_plan.h:131`) | Plan one request over primary rows, without loading or running a strategy. |
225+
226+
For direct C use, check the relevant version getter returns 1 and initialize
227+
each descriptor's `struct_size` and `version` exactly as its header requires.
228+
The planner bridge is a separate shared library from the caller's pinned
229+
build; it is not the strategy library. The C ABI versions do not declare a
230+
CLI contract revision; consumers of the CLI must use its capability record.
231+
232+
The configuration setter and counts getter return 0 on success and negative
233+
values for the refusals documented in the header. A refused setter leaves the
234+
configuration unchanged; a failed counts read leaves valid output storage
235+
unchanged. The planner bridge instead returns 0 when it writes a whole
236+
result, including a planner refusal: inspect `status`, where 0 is a successful
237+
plan. A negative bridge return is a bridge failure and leaves valid output
238+
storage unchanged.
239+
240+
### Window reports and stability
241+
242+
The policy and report shape follow the [report schema](report-schema.md),
243+
including its [revision 3.1 clarification](../design/selected-window-wire-v1.3-revision-3.1.md).
244+
The report carries the window bounds and coverage, feed identity, and requested,
245+
available, used and trimmed preroll with its timestamps and shortfall, assembled
246+
by `build_report_window` (`docker/selected_window_report.py:460`). These warm-up
247+
bars precede the window and are counted separately. The lookback declaration
248+
is `unknown` in this build, so the requested preroll is not a proof of sufficient
249+
warm-up. The same `report_window` appears at the top level, in `applied_runtime`
250+
and in `fingerprint.provenance.runtime`, held by
251+
`check_report_placements` (`docker/selected_window_report.py:669`).
252+
The selected curve has one anchor at T with initial capital and zero open
253+
profit, then one point per window script bar, held by
254+
`check_selected_curve` (`docker/selected_window_report.py:609`).
255+
256+
An executed success is a complete report with `report_window.applied: true`
257+
and harness exit status 0. A validation-only plan has `applied: false` and
258+
does not establish execution success. Request or execution failures have a
259+
nonzero harness status and the typed `code` / `args` failure line described in
260+
@ref run_failure_codes. If stdout cannot take a whole report, the harness
261+
returns 1 with the reason on stderr and no second JSON document, as enforced by
262+
`_write_report` (`docker/run_json.py:4662`).
263+
264+
**Functions and flags are append-only.** No published function or flag above
265+
is removed or renamed in 1.x; new ones are added. The C layout rules above
266+
apply to these descriptors. A contract revision changes only by a new revision
267+
literal in `capabilities.selected_window_contract_revisions`, rather than by
268+
changing the meaning of an existing literal. The version rule applies here:
269+
a PATCH release fixes behaviour, a MINOR release adds to a surface, and only a
270+
MAJOR release removes or changes one. `scripts/check_c_abi_runtime.py` pins the
271+
runtime export names; review holds the flag and revision stability promise
272+
across releases.
273+
274+
The pure helper modules `docker/selected_window_*.py` and siblings such as
275+
`docker/run_phase_transport.py`, `docker/run_execution_observer.py` and
276+
`docker/request_feed_inventory.py` are implementation details, even where
277+
cited here as evidence. Their Python imports and call signatures are not a
278+
public API. Code under `src/` not reachable through the published headers or
279+
CLI is outside this contract. A consumer must go through the CLI or the headers.
280+
155281
## Run-failure codes
156282

157283
The run-failure vocabulary is `docker/run_failure_codes.json`: the codes

‎scripts/check_doc_lint.py‎

Lines changed: 130 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
#!/usr/bin/env python3
2-
"""Keep nine kinds of rot out of the published documentation.
2+
"""Keep ten kinds of rot out of the published documentation.
33
44
Why a second script rather than a mode of ``check_doc_anchors.py``
55
------------------------------------------------------------------
@@ -12,7 +12,7 @@
1212
and this one's offender list reads as a work list rather than as noise inside
1313
another report.
1414
15-
The nine rules
15+
The ten rules
1616
--------------
1717
1. ``lane L<n>`` in a published page (``docs/pages/*.md``, ``README.md``).
1818
A roadmap label is a promise about the future. Fifteen of them in
@@ -107,6 +107,14 @@
107107
file's (R5 lane H-DOCGATES). A version framed as history (``since``,
108108
``was``, a release-notes link) is not a claim about this tree.
109109
110+
10. The public selected-window section must name every ``PF_API`` function
111+
declared in ``selected_window.h`` and ``selected_window_plan.h`` and every
112+
option in ``run_json.py``'s selected-window argument block. Names come from
113+
the headers and the real ``add_argument`` calls, not a second inventory.
114+
A missing or duplicated section, unreadable source or unrecognised
115+
declaration/block is an offender too. Names elsewhere on the page, in
116+
comments or in fenced examples cannot stand in for the section.
117+
110118
Exit status
111119
-----------
112120
0 when no offender is found, 1 otherwise. ``ci_preflight`` runs it as a
@@ -115,6 +123,7 @@
115123
from __future__ import annotations
116124

117125
import argparse
126+
import ast
118127
import re
119128
import sys
120129
from pathlib import Path
@@ -127,6 +136,12 @@
127136
DOC_GLOBS = ('README.md', 'CONTRIBUTING.md', 'docs/*.md', 'docs/pages/*.md',
128137
'docs/adr/*.md', 'docs/design/*.md')
129138

139+
SELECTED_WINDOW_PAGE = 'docs/pages/public-contract.md'
140+
SELECTED_WINDOW_SECTION = 'selected_windows_walk_forward'
141+
SELECTED_WINDOW_HEADERS = ('include/pineforge/selected_window.h',
142+
'include/pineforge/selected_window_plan.h')
143+
SELECTED_WINDOW_CLI = 'docker/run_json.py'
144+
130145
VERIFIED = '<!-- verified HEAD -->'
131146

132147
LANE_RE = re.compile(r'\blane[s]?\s+L[0-9]')
@@ -561,6 +576,116 @@ def verified_live_claims(page: Path, body: str, live_ns_families: dict[str, set[
561576
return out
562577

563578

579+
def selected_window_header_names(text: str) -> set[str]:
580+
"""Read every complete PF_API function declaration from one public header."""
581+
code = re.sub(r'/\*.*?\*/|//[^\n]*', '', text, flags=re.DOTALL)
582+
names = re.findall(r'^[ \t]*PF_API\b[^;{}]*?\b([A-Za-z_]\w*)\s*'
583+
r'\([^;{}]*\)\s*;', code, re.MULTILINE)
584+
declarations = len(re.findall(r'\bPF_API\b', code))
585+
if (not declarations or len(names) != declarations
586+
or len(names) != len(set(names))):
587+
raise ValueError('expected complete, distinct PF_API function declarations')
588+
return set(names)
589+
590+
591+
def selected_window_options(text: str) -> set[str]:
592+
"""Parse the real selected-window add_argument block without executing it."""
593+
module = ast.parse(text)
594+
mains = [node for node in module.body
595+
if isinstance(node, ast.FunctionDef) and node.name == '_main']
596+
if len(mains) != 1:
597+
raise ValueError('expected one _main function')
598+
main = mains[0]
599+
lines = text.splitlines()
600+
starts = [number for number, line in enumerate(lines, 1)
601+
if main.lineno < number < main.end_lineno
602+
and re.match(r'^\s*# Selected-window mode \(', line)]
603+
stops = [node.lineno for node in main.body
604+
if isinstance(node, ast.Assign)
605+
and any(isinstance(target, ast.Name) and target.id == 'pre_profile_long'
606+
for target in node.targets)]
607+
if len(starts) != 1 or len(stops) != 1 or starts[0] >= stops[0]:
608+
raise ValueError('cannot delimit the selected-window argument block')
609+
610+
names: list[str] = []
611+
for node in main.body:
612+
if not starts[0] < node.lineno < stops[0]:
613+
continue
614+
if (not isinstance(node, ast.Expr) or not isinstance(node.value, ast.Call)
615+
or not isinstance(node.value.func, ast.Attribute)
616+
or not isinstance(node.value.func.value, ast.Name)
617+
or node.value.func.value.id != 'ap'
618+
or node.value.func.attr != 'add_argument'):
619+
raise ValueError('expected only ap.add_argument calls in the selected-window block')
620+
if (not node.value.args
621+
or any(not isinstance(arg, ast.Constant) or not isinstance(arg.value, str)
622+
or re.fullmatch(r'--[A-Za-z][A-Za-z0-9-]*', arg.value) is None
623+
for arg in node.value.args)):
624+
raise ValueError('expected literal long option strings in selected-window block')
625+
names.extend(arg.value for arg in node.value.args)
626+
if not names or len(names) != len(set(names)):
627+
raise ValueError('expected nonempty, distinct selected-window options')
628+
return set(names)
629+
630+
631+
def selected_window_page_section(text: str) -> tuple[str, int]:
632+
"""Return the anchored section with comments and fenced examples removed."""
633+
body = re.sub(r'<!--.*?-->',
634+
lambda match: '\n' * match.group(0).count('\n'),
635+
masked(text), flags=re.DOTALL)
636+
lines = body.splitlines()
637+
anchor = re.compile(r'\{#' + re.escape(SELECTED_WINDOW_SECTION) + r'\}')
638+
headings: list[tuple[int, int]] = []
639+
for index, line in enumerate(lines):
640+
match = re.match(r'^\s{0,3}(#{1,6})\s+', line)
641+
if match and anchor.search(line):
642+
headings.append((index, len(match.group(1))))
643+
if len(headings) != 1:
644+
raise ValueError(f'expected one {{#{SELECTED_WINDOW_SECTION}}} section')
645+
646+
start, level = headings[0]
647+
stop = len(lines)
648+
for index in range(start + 1, len(lines)):
649+
match = re.match(r'^\s{0,3}(#{1,6})\s+', lines[index])
650+
if match and len(match.group(1)) <= level:
651+
stop = index
652+
break
653+
return '\n'.join(lines[start + 1:stop]), start + 1
654+
655+
656+
def selected_window_contract(root: Path) -> list[Offender]:
657+
"""Hold the public section to the headers and CLI, failing closed."""
658+
page = root / SELECTED_WINDOW_PAGE
659+
found: list[Offender] = []
660+
section: str | None = None
661+
first = 1
662+
try:
663+
section, first = selected_window_page_section(page.read_text())
664+
except (OSError, UnicodeError, ValueError) as error:
665+
found.append(Offender(
666+
page, first, 'selected-window-contract', SELECTED_WINDOW_SECTION,
667+
f'cannot read or parse the selected-window public section: {error}'))
668+
669+
sources = [(rel, selected_window_header_names) for rel in SELECTED_WINDOW_HEADERS]
670+
sources.append((SELECTED_WINDOW_CLI, selected_window_options))
671+
for rel, reader in sources:
672+
try:
673+
names = reader((root / rel).read_text())
674+
except (OSError, UnicodeError, SyntaxError, ValueError) as error:
675+
found.append(Offender(
676+
page, first, 'selected-window-contract', rel,
677+
f'cannot read or parse selected-window source `{rel}`: {error}'))
678+
continue
679+
if section is None:
680+
continue
681+
for name in sorted(names):
682+
if re.search(r'(?<![\w-])' + re.escape(name) + r'(?![\w-])', section) is None:
683+
found.append(Offender(
684+
page, first, 'selected-window-contract', name,
685+
f'section omits `{name}` declared by `{rel}`'))
686+
return found
687+
688+
564689
def check(root: Path) -> list[Offender]:
565690
found: list[Offender] = []
566691
namespaces, domains = live_epochs(root)
@@ -621,6 +746,7 @@ def check(root: Path) -> list[Offender]:
621746
body = masked(text)
622747
found.extend(stale_counts(page, body, counts))
623748
found.extend(verified_live_claims(page, body, live_ns_families, live_domain_families))
749+
found.extend(selected_window_contract(root))
624750
found.sort(key=lambda o: (str(o.page), o.line, o.rule))
625751
return found
626752

@@ -672,7 +798,8 @@ def main(argv: list[str] | None = None) -> int:
672798

673799
if not found:
674800
print('\nno lane labels, stale negatives, stale epochs, dead links, dead paths, '
675-
'stale counts, stale ABI numbers or releases, or markers on a stale present')
801+
'stale counts, stale ABI numbers or releases, or markers on a stale present, '
802+
'or selected-window contract omissions')
676803
return 0
677804
print(f'\n{len(found)} offenders:')
678805
for offender in found:

0 commit comments

Comments
 (0)