test(docs): anchors from the functions behind design.md's rules to their docs, and a check they resolve #25

Open

dyst wants to merge 1 commit from dyst/Longshot:feat/doc-anchors into main

pull from: dyst/Longshot:feat/doc-anchors

merge into: MagicBeanDev:main

MagicBeanDev:main

Conversation 5 Commits 1 Files changed 5 +116

dyst commented 2026-11-12 23:38:30 +00:00

Member

• Copy link
• Copy Markdown

Why

The functions that keep design.md's hard-won rules (cross-queue waits, captures instead of live guest memory, passes split for clears and hazards) don't say so where they are defined, so an agent reading one sees a wait or a capture that looks redundant and may "simplify" it away. This puts a one-line pointer to the written rule above each, and a check that the pointers stay valid.

What changed

• renderer: // doc: docs/design.md#4-the-lessons-from-mkw-as-rules-here anchors above the functions behind docs/design.md §4's rules. Comments only; no code changes:

  • rule 1: submit_job in gpu/vk/vk_replay.cpp (cross-queue event waits);
  • rule 2: the pool captures in gpu/vk/vk_memory.cpp (the RX_VK_CAPTURE_POOL_MB comment above them: nothing the replay reads comes from live guest memory);
  • rule 3: register_texture_queued in gpu/vk/vk_replay.cpp (registrations in order with the submits);
  • rule 4: NOP_REPORT_COUNTER's timestamp scaling in replay(), gpu/vk/vk_replay.cpp (GPU timestamps drive dynamic resolution);
  • rule 5: clear_after_draws and draw_hazards in gpu/vk/vk_draw.cpp (a clear after draws, and a draw that samples what its pass wrote, get a pass of their own).

• build: rss_mb in nx2/build.py points to docs/compiler-memory-accounting.md.

• tests: new tests/test_doc_anchors.py (standard library):

  • every doc: anchor in our code (host/, gpu/, nx2/, scripts/, builder/; not eden, sirit or third_party) names a file under docs/ and, after #, one of its headings, by GitHub's anchor rule (slug(), anchors_of(): a repeated heading gets -1);
  • those seven functions keep theirs, just above them (REQUIRED).

  A renamed heading or a deleted anchor fails with the file and line.

Flags and settings

None

Measurements

main: 000f19fb (2026-11-13)
this PR: feat/doc-anchors @ 7691d857
Hardware: Ryzen 9 3900X, 64 GB, Windows 11 (RTX 3080; no game run: these are game-free checks)
Scene: none: game-free. The anchors from the rules' functions to their docs, checked
Method: tests/test_doc_anchors.py twice on this branch; then in a scratch copy of the tree, once each with a fault it must catch: the anchor above rss_mb deleted, a required anchor changed to #4-lessons, and a new anchor in host/hos_main.c to docs/design.md#4-lessons, a heading that is not there. main has neither the anchors nor the check
How to reproduce: python -I -B tests/test_doc_anchors.py; then make one of the faults and run it again

	main @ 000f19fb	this PR @ 7691d857
anchors from code to the docs	0	7
the check's runs passing	- (no check)	2 of 2
faults it catches	-	3 of 3

pr 1: exit 0: doc anchors: 7, each resolves; the 7 rules' functions keep theirs
pr 2: exit 0: doc anchors: 7, each resolves; the 7 rules' functions keep theirs
fault (anchor deleted): exit 1: nx2/build.py:427: no doc: docs/compiler-memory-accounting.md just above 'def rss_mb(proc):'
fault (required anchor changed): exit 1: gpu/vk/vk_replay.cpp:897: no doc: docs/design.md#4-the-lessons-from-mkw-as-rules-here just above "// (the GPU's time as the game measures it"
fault (an anchor to a missing heading): host/hos_main.c:2090: docs/design.md has no heading #4-lessons

Rebased since onto main 0c74253d: its four commits since 000f19fb are #177 (a log line's level, in the renderer's logging), #192, #193 and #194 (the README, the website, the Discord status), none in the runner or the checks measured here; #177's lines in vk_draw.cpp and vk_memory.cpp are not the ones the anchors sit above, and the check passes on the rebased branch, so the numbers hold.

Testing

Tested: the runs above; tests/run_all.py, the whole suite, on this branch and on main 0c74253d, Windows (483 passed and 6 failed on main, 484 passed and 6 failed here, no failure main doesn't have: test_check_third_party, test_display_pointer, test_fpx_sticky, test_release, test_spawn_emit and test_texture_staging_publication fail on main too (the last since #177; #202 fixes it)). The seven lines added in gpu/vk/vk_draw.cpp, vk_memory.cpp, vk_replay.cpp and nx2/build.py are comments, none after a line that continues (a backslash), so both platforms' compilers see the code main has.

Not tested: in the game (comments only, nothing runs differently); on Linux (the check is plain Python).

Needs other testers: None

Screenshots

Nothing on screen.

Risk and rollback

Nothing runs differently: the source changes are comments. The new check can fail a later PR that renames a heading in docs/design.md or docs/compiler-memory-accounting.md, or reshapes one of the seven functions so its marker moves; the message names the file and line. Reverting the commit is enough.

Reviewer notes

Carried over from https://github.com/NotRexed/Hookshot/pull/2942 with the move to Longshot: the same change on Longshot's main, with its rename applied. Its review and discussion are there.

The dev-loop proposal's F2 (https://github.com/NotRexed/Hookshot/pull/2636). Other functions can take anchors in later PRs, as their docs are written; the check covers every new one.

The checks were run on the GitHub version; this branch is the same change with the rename applied (the same files and line counts). Forgejo runs no checks, and they were not run again here. Only the checks that read the changed files were run, not the whole run_all.py.

Issues

See https://github.com/NotRexed/Hookshot/pull/2636 (F2).

Checklist

For everyone

• One topic.
• The title is a Conventional Commit (type(scope): description).
• Rebased on current main.
• python -I -B tests/run_all.py run and passing (any failure that also fails on main is named above).
• Tested in the game, or what wasn't is named under Testing.
• Testing filled in: what was tested, what wasn't, and what needs other testers (with test requests).
• Measured: main and this PR at named commits, on the same PC, scene and settings, at least 2 interleaved runs each, the median reported.
• No game files, dumps, build output or generated files.
• third_party/ untouched (a new folder with a PROVENANCE.md instead).
• The license is OK: GPL-3.0-or-later, nothing incompatible and nothing decompiled.

If applicable

• AI assistance recorded with Assisted-by: / Co-Authored-By: trailers.
• A game-free test added for the fix, failing on main and passing here.
• Host code builds on both Windows (llvm-mingw) and Linux, with UTF-8 paths.

🤖 Generated with Claude Code

## Why The functions that keep design.md's hard-won rules (cross-queue waits, captures instead of live guest memory, passes split for clears and hazards) don't say so where they are defined, so an agent reading one sees a wait or a capture that looks redundant and may "simplify" it away. This puts a one-line pointer to the written rule above each, and a check that the pointers stay valid. ## What changed - renderer: `// doc: docs/design.md#4-the-lessons-from-mkw-as-rules-here` anchors above the functions behind `docs/design.md` §4's rules. Comments only; no code changes: - rule 1: `submit_job` in `gpu/vk/vk_replay.cpp` (cross-queue event waits); - rule 2: the pool captures in `gpu/vk/vk_memory.cpp` (the `RX_VK_CAPTURE_POOL_MB` comment above them: nothing the replay reads comes from live guest memory); - rule 3: `register_texture_queued` in `gpu/vk/vk_replay.cpp` (registrations in order with the submits); - rule 4: `NOP_REPORT_COUNTER`'s timestamp scaling in `replay()`, `gpu/vk/vk_replay.cpp` (GPU timestamps drive dynamic resolution); - rule 5: `clear_after_draws` and `draw_hazards` in `gpu/vk/vk_draw.cpp` (a clear after draws, and a draw that samples what its pass wrote, get a pass of their own). - build: `rss_mb` in `nx2/build.py` points to `docs/compiler-memory-accounting.md`. - tests: new `tests/test_doc_anchors.py` (standard library): - every `doc:` anchor in our code (`host/`, `gpu/`, `nx2/`, `scripts/`, `builder/`; not eden, sirit or third_party) names a file under `docs/` and, after `#`, one of its headings, by GitHub's anchor rule (`slug()`, `anchors_of()`: a repeated heading gets `-1`); - those seven functions keep theirs, just above them (`REQUIRED`). A renamed heading or a deleted anchor fails with the file and line. ## Flags and settings None ## Measurements main: 000f19fb (2026-11-13) this PR: feat/doc-anchors @ 7691d857 Hardware: Ryzen 9 3900X, 64 GB, Windows 11 (RTX 3080; no game run: these are game-free checks) Scene: none: game-free. The anchors from the rules' functions to their docs, checked Method: `tests/test_doc_anchors.py` twice on this branch; then in a scratch copy of the tree, once each with a fault it must catch: the anchor above `rss_mb` deleted, a required anchor changed to `#4-lessons`, and a new anchor in `host/hos_main.c` to `docs/design.md#4-lessons`, a heading that is not there. main has neither the anchors nor the check How to reproduce: `python -I -B tests/test_doc_anchors.py`; then make one of the faults and run it again | | main @ 000f19fb | this PR @ 7691d857 | |---|---|---| | anchors from code to the docs | 0 | 7 | | the check's runs passing | - (no check) | 2 of 2 | | faults it catches | - | 3 of 3 | ``` pr 1: exit 0: doc anchors: 7, each resolves; the 7 rules' functions keep theirs pr 2: exit 0: doc anchors: 7, each resolves; the 7 rules' functions keep theirs fault (anchor deleted): exit 1: nx2/build.py:427: no doc: docs/compiler-memory-accounting.md just above 'def rss_mb(proc):' fault (required anchor changed): exit 1: gpu/vk/vk_replay.cpp:897: no doc: docs/design.md#4-the-lessons-from-mkw-as-rules-here just above "// (the GPU's time as the game measures it" fault (an anchor to a missing heading): host/hos_main.c:2090: docs/design.md has no heading #4-lessons ``` Rebased since onto main 0c74253d: its four commits since 000f19fb are #177 (a log line's level, in the renderer's logging), #192, #193 and #194 (the README, the website, the Discord status), none in the runner or the checks measured here; #177's lines in `vk_draw.cpp` and `vk_memory.cpp` are not the ones the anchors sit above, and the check passes on the rebased branch, so the numbers hold. ## Testing **Tested:** the runs above; `tests/run_all.py`, the whole suite, on this branch and on main 0c74253d, Windows (483 passed and 6 failed on main, 484 passed and 6 failed here, no failure main doesn't have: test_check_third_party, test_display_pointer, test_fpx_sticky, test_release, test_spawn_emit and test_texture_staging_publication fail on main too (the last since #177; #202 fixes it)). The seven lines added in `gpu/vk/vk_draw.cpp`, `vk_memory.cpp`, `vk_replay.cpp` and `nx2/build.py` are comments, none after a line that continues (a backslash), so both platforms' compilers see the code main has. **Not tested:** in the game (comments only, nothing runs differently); on Linux (the check is plain Python). **Needs other testers:** None ## Screenshots Nothing on screen. ## Risk and rollback Nothing runs differently: the source changes are comments. The new check can fail a later PR that renames a heading in `docs/design.md` or `docs/compiler-memory-accounting.md`, or reshapes one of the seven functions so its marker moves; the message names the file and line. Reverting the commit is enough. ## Reviewer notes Carried over from https://github.com/NotRexed/Hookshot/pull/2942 with the move to Longshot: the same change on Longshot's `main`, with its rename applied. Its review and discussion are there. The dev-loop proposal's F2 (https://github.com/NotRexed/Hookshot/pull/2636). Other functions can take anchors in later PRs, as their docs are written; the check covers every new one. The checks were run on the GitHub version; this branch is the same change with the rename applied (the same files and line counts). Forgejo runs no checks, and they were not run again here. Only the checks that read the changed files were run, not the whole `run_all.py`. ## Issues See https://github.com/NotRexed/Hookshot/pull/2636 (F2). ## Checklist ### For everyone - [x] One topic. - [x] The title is a Conventional Commit (`type(scope): description`). - [x] Rebased on current `main`. - [x] `python -I -B tests/run_all.py` run and passing (any failure that also fails on `main` is named above). - [x] Tested in the game, or what wasn't is named under Testing. - [x] Testing filled in: what was tested, what wasn't, and what needs other testers (with test requests). - [x] Measured: main and this PR at named commits, on the same PC, scene and settings, at least 2 interleaved runs each, the median reported. - [x] No game files, dumps, build output or generated files. - [x] `third_party/` untouched (a new folder with a `PROVENANCE.md` instead). - [x] The license is OK: GPL-3.0-or-later, nothing incompatible and nothing decompiled. ### If applicable - [x] AI assistance recorded with `Assisted-by:` / `Co-Authored-By:` trailers. - [x] A game-free test added for the fix, failing on `main` and passing here. - [x] Host code builds on both Windows (llvm-mingw) and Linux, with UTF-8 paths. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

dyst changed title from test(docs): anchors from the functions behind design.md's rules to their docs, and a check they resolve to WIP: test(docs): anchors from the functions behind design.md's rules to their docs, and a check they resolve 2026-11-13 01:13:47 +00:00

dyst commented 2026-11-13 01:13:47 +00:00

Author

Member

• Copy link
• Copy Markdown

Back to WIP under #48's process: this was carried over before the new template. Its description will be brought to the template and measured on Longshot (main against this PR, at named commits) when it's wanted for review; ask here if you'd like it sooner.

Back to WIP under #48's process: this was carried over before the new template. Its description will be brought to the template and measured on Longshot (main against this PR, at named commits) when it's wanted for review; ask here if you'd like it sooner.

dyst commented 2026-11-13 01:58:15 +00:00

Author

Member

• Copy link
• Copy Markdown

Description brought to Longshot's PR template (#48). Still WIP: its numbers are from the GitHub version, and it isn't rebased on current main; it gets measured on Longshot (main against this PR, at named commits) before it is marked ready.

Description brought to Longshot's PR template (#48). Still WIP: its numbers are from the GitHub version, and it isn't rebased on current main; it gets measured on Longshot (main against this PR, at named commits) before it is marked ready.

dyst commented 2026-11-13 02:00:30 +00:00

Author

Member

• Copy link
• Copy Markdown

Description moved to the template's Testing section and whole checklist (#72): what was tested, what wasn't, and what needs other testers (their test requests to open while this is WIP).

Description moved to the template's Testing section and whole checklist (#72): what was tested, what wasn't, and what needs other testers (their test requests to open while this is WIP).

dyst commented 2026-11-13 11:45:24 +00:00

Author

Member

• Copy link
• Copy Markdown

The description follows the template after #76 and #106: If applicable keeps only the boxes that apply (one that applies and isn't done yet stays unticked while this is WIP), the Flags table has the template's seven columns (Goal is now Recommendation), and GitHub references are full URLs. Nothing else changed.

The description follows the template after #76 and #106: If applicable keeps only the boxes that apply (one that applies and isn't done yet stays unticked while this is WIP), the Flags table has the template's seven columns (Goal is now Recommendation), and GitHub references are full URLs. Nothing else changed.

dyst commented 2026-11-13 13:56:30 +00:00

Author

Member

• Copy link
• Copy Markdown

Rebased onto main 0c74253d and measured on Longshot: the 7 anchors resolve (twice), and the check fails on all three faults it should catch (an anchor deleted, a required one changed, a stray anchor to a missing heading). Whole suite on this head and on main: no failure main doesn't have. Ready for review.

Rebased onto main 0c74253d and measured on Longshot: the 7 anchors resolve (twice), and the check fails on all three faults it should catch (an anchor deleted, a required one changed, a stray anchor to a missing heading). Whole suite on this head and on main: no failure main doesn't have. Ready for review.

dyst force-pushed feat/doc-anchors from 84be88a6d3 to de6e89ef34 2026-11-13 13:56:31 +00:00 Compare

dyst changed title from WIP: test(docs): anchors from the functions behind design.md's rules to their docs, and a check they resolve to test(docs): anchors from the functions behind design.md's rules to their docs, and a check they resolve 2026-11-13 13:57:15 +00:00

proci referenced this pull request 2026-11-14 00:01:43 +00:00

WIP: perf(vk): a mirror sync's pages from the captures go in one compute dispatch, not one copy region each #326

mooki added the

area/install

area/renderer

kind

chore

labels 2026-11-14 01:43:58 +00:00

mooki added the

priority

low

label 2026-11-14 04:17:09 +00:00

APusija04 referenced this pull request 2026-11-14 05:05:21 +00:00

[RX 6600] Game crashes with GPU timeout #365

Austin referenced this pull request 2026-11-14 17:33:36 +00:00

Game: #503

Austin referenced this pull request 2026-11-14 17:33:51 +00:00

Game: #504

Austin referenced this pull request 2026-11-14 17:34:07 +00:00

Game: #509

Austin referenced this pull request 2026-11-14 17:34:31 +00:00

Game: Longshot #510

Austin referenced this pull request 2026-11-14 17:34:39 +00:00

Game: #512

Austin referenced this pull request 2026-11-14 18:19:08 +00:00

Game: Switch Pro Controller issues when gamestreaming #535

mooki added the

gpu/nvidia

platform/linux

platform/windows

labels 2026-11-14 18:20:58 +00:00

Some checks failed

Hide checks

CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been skipped

Details

CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been skipped

Details

CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been skipped

Details

Third-party parts / The same as upstream (pull_request) Has been skipped

Details

Website / Website on Cloudflare (pull_request) Has been skipped

Details

PR description / Description follows the template (pull_request_target) Has been cancelled

Details

Third-party parts / As their notes say (pull_request) Has been cancelled

Details

CI / Conventional Commit title (pull_request) Has been cancelled

Details

CI / Workflow lint (actionlint) (pull_request) Has been cancelled

Details

Website / Website on Cloudflare (pull_request_target) Has been skipped

Details

This pull request doesn't have enough approvals yet. 0 of 1 approvals granted.

This branch is out-of-date with the base branch

You are not authorized to merge this pull request.

View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.

git fetch -u 'feat/doc-anchors:dyst-feat/doc-anchors'

git switch 'dyst-feat/doc-anchors'

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels   

area/accessibility

Barriers for people with disabilities

  

area/audio

Sound and music

  

area/input

Controllers, keyboard, mouse

  

area/install

Installing, updating, building from your game

  

area/menu

In-game menu and settings

  

area/renderer

Vulkan renderer, shaders, effects

  

area/saves

Save files

  

area/upscaling

DLSS, FSR, frame generation

  

good first issue

A good start for a new contributor

  

gpu/amd

AMD GPUs

  

gpu/igpu

Integrated GPUs

  

gpu/intel

Intel GPUs

  

gpu/nvidia

NVIDIA GPUs

  

help wanted

Extra hands or knowledge wanted

  

kind

bug

Something doesn't work as it should

  

kind

chore

Build, CI, dependencies, tidying

  

kind

docs

Documentation

  

kind

feature

A new feature or an improvement

  

kind

performance

Frame rate, frame time, loading, memory

  

kind

question

A question rather than a change

  

needs measurements

Waiting for before/after measurements

  

platform/linux

Affects Linux (a change for every system carries both Windows and Linux)

  

platform/macos

macOS (Apple silicon or Intel Macs)

  

platform/steam-deck

Steam Deck

  

platform/windows

Affects Windows (a change for every system carries both Windows and Linux)

  

preview

Maintainers: deploy a preview of this PR's website (read its changes first). Removed after the run.

  

priority

critical

Crashes, data loss, or blocks most players

  

priority

high

Important: next in line

  

priority

low

Nice to have

  

status

blocked

Waits on something else first

  

status

confirmed

Reproduced or agreed on

  

status

duplicate

Already reported or proposed

  

status

invalid

Not a problem in this project

  

status

needs-info

Waiting for more information from the reporter

  

status

wontfix

Will not be worked on

  

testing wanted

Wanted: a test on other hardware (posts a test request in #test-requests)

  

ci: approved

No labels

area/accessibility

area/audio

area/input

area/install

area/menu

area/renderer

area/saves

area/upscaling

good first issue

gpu/amd

gpu/igpu

gpu/intel

gpu/nvidia

help wanted

kind

bug

kind

chore

kind

docs

kind

feature

kind

performance

kind

question

needs measurements

platform/linux

platform/macos

platform/steam-deck

platform/windows

preview

priority

critical

priority

high

priority

low

status

blocked

status

confirmed

status

duplicate

status

invalid

status

needs-info

status

wontfix

testing wanted

ci: approved

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

MagicBeanDev/Longshot!25

No description provided.