Skip to content

docs, comments and diagnostics: describe behaviour in plain words instead of internal tracking labels - #580

Merged
luisleo526 merged 30 commits into
mainfrom
docs/plain-wording-2
Oct 28, 2026
Merged

luisleo526 merged 30 commits into
mainfrom
docs/plain-wording-2

Conversation

@luisleo526

@luisleo526 luisleo526 commented Oct 27, 2026 •

Copy link
Copy Markdown
Collaborator

docs: describe behaviour in plain words instead of internal tracking labels

Reword published documentation that carried internal task and card labels so each
passage says what the thing is. Lines that only changed a label keep their meaning.

Sentences replaced or dropped, named by the commit that introduced each:

  • 91353de: the heading of a read-only census note and
    "All eight vectors use the three-term verdict;" (arena-bound pages), and the two
    passages of cr150-contracts.md that cite the external design lane's work files
    and its revision 6 amendment.
  • d093560: the paragraph of native-refactor-progress.md that quotes the supervisor
    cap and the decision that stopped the R5 performance wave.
  • a77fb73: "R4-D L1 advanced BacktestEngine, NativeStrategyHost, and the private
    consumer to engine_script_run_v17;" (abi-stability.md).
  • 44bb687: "R5 L4 adds NativeRunSpec::margin, folded only when it is set;" and
    "R5 L5 adds calculation, max_recalculations_per_point and open_ba..." (abi-stability.md).

comments, docstrings and diagnostics: describe behaviour in plain words instead of internal tracking labels

Replace internal task, card and work-lane labels in source comments, docstrings,
workflow comments and human-readable progress lines of test programs with plain
descriptions. About 620 text lines in 285 files; no identifier, file name, CTest
selector, CMake fence, assertion or data file is renamed or edited.

Files whose exact bytes are pinned or whose text is data stay unchanged: the
frozen run_json fixture (its digest is asserted), fixture sources hashed by the
heap census, the ci/ gate data, the broker-state waiver list, the ownership probe
notes, the heap census report heading and the run-failure label passed to
note_run_failure. Printed lines that changed are listed in the pull request; each
old text was searched across the engine and the other repositories and nothing
reads them.

comments: restore the workflow files and the preflight text that mirrors them

The CI workflows carry a verbatim authorization job and comments that scripts/ci_preflight.py
and its test expect byte for byte (the contract check "must start with the verbatim canon
authz job" failed on the reworded comments). Restore .github/, scripts/ci_preflight.py and
scripts/test_ci_preflight.py to their previous text.

🤖 Generated with Claude Code

luisleo526 and others added 28 commits October 28, 2026 00:50
…ith a doc-lint rule that holds it

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
… drop the stale 180 s wording

test_selected_window_ownership_manifest_controls_shard_1of4 took 74 s on an idle
8-vCPU box while shards 2-4 took 41-50 s (the modulo split over sorted case ids
put the heaviest controls together). The four rows carry no explicit TIMEOUT
any more (#504 removed it) but the tree still described a 180 s budget and the
CMake guard still exempted the exact old statement.

- Shards are now assigned largest-first to the lightest shard, with a weight per
  case read from its AST (checker subprocess launches, through self helpers and
  literal loops). No measured seconds are stored. The partition stays exact,
  order independent and deterministic; --shard I/N validation and the
  "ran N tests as selected" fail-closed check are unchanged.
- The two 60 s subprocess deadlines inside the controls are removed.
- scripts/check_cr150_cmake_d.py no longer exempts the old six-row
  "TIMEOUT 180" statement, and its test now requires the refusal.
- docs/ci.md, tests/ownership/README.md and the CMake comment describe the
  balancing and no deadline.
- New rows: balance bound (max/min <= 5/4, violated by the old split) and an
  estimator row; the partition row now checks input-order independence.

Documentation sentences removed from docs/ci.md, all introduced by 375795a (the
change that split the ownership manifest controls into four CTest shards): the
sentence saying that change splits the controls into four CTest shards
(`test_selected_window_ownership_manifest_controls_shard_1of4` through the
fourth), the sentence saying it adds three public registered/run rows to every
engine profile in both fixture worlds and only raises the counts above the
pinned minimum floors, and the sentence saying the private-fixture and receipt
row populations stay the same. The replacement paragraph states the balanced
four-shard split and the unchanged row populations.

Measured on a throwaway 8-vCPU spot VM: shards 51/57/53/55 s after, 74/42/41/50 s
before.

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
Attribute exclusive opens and fork-descendant scratch files to their creating
process, keep unrelated co-tenants out of the witness, and report the offending
path with its PID or an explicit unattributable reason. Add three public Linux
CTest cases for exclusive open, inherited evidence, and diagnostics.

Carry the three rows through verifier floors and mock accounting. Preserve
documentation line counts and refresh the floor-table citations.

Documentation replacements from 3ea5a0d name the old wording:
"Their default runs now enter strict exclusion accounting"
"Verifier 8 + preflight 8 + command-after 8 + report 4 add 28 public rows; plain Debug-type runs enforce the increased registration floors."
"Release 938 with the overlay or 631 without it"
"The floor itself remains fixed at 631/334 absent or 938/365 present"
"The native PR registration floor is 1000"
"Both numbers are constants of the profile"
"The full-run release and kernel floors are the table's own numbers above"
"EXCLUDED_REGISTERED_MIN holds 904 for debug, 895 for sanitizers"
"The run floors in the table above"
The release and kernel table rows from 3ea5a0d use the new floors.

The population wording and table header from b97c409 are replaced:
"The registered column is why the absent floor is not the absent registration, and it is to be re-measured after the registration fix lands."
"registered (present / absent)"

The four citation edits retain the passages named by:
"The floors' numbers live in one place"
"Each profile counts the rows that"
"the minimum number of CTest rows"
"The profile carries a row floor"

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
Corrects four comments that no longer match the code they describe, and one
stale line number in a script comment:

- scripts/ci_verify.py: the selected-sink memory test is registered at its
  current line of tests/CMakeLists.txt.
- tests/test_scratch_create_pinned_text.cpp: the header names the files that
  produce the pinned create diagnostics instead of a release.
- src/source/pine_adapter.cpp: the placement table scans the retained
  placements and consults the historical minima for erased rows; it has no
  per-id index.
- include/pineforge/native_host.hpp: the live-order read comment no longer
  claims the reads allocate nothing, since a spilled row is read into a buffer.

No code changes.

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
… path it pins

The header named two producing files; the test also pins the id-pair scratch
file and the successor-roots create. It now lists all four scratch paths by
what they are, and drops a stale note about an unobserved prediction. Comment
text only.

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
…labels

Reword published documentation that carried internal task and card labels so each
passage says what the thing is. Lines that only changed a label keep their meaning.

Sentences replaced or dropped, named by the commit that introduced each:
- 91353de: "Read-only census for CR-150 L22u / A6 and A5-WIDER." and
  "All eight vectors use the three-term verdict;" (arena-bound pages), and the two
  passages of cr150-contracts.md that cite the external design lane's work files
  and its revision 6 amendment.
- d093560: the paragraph of native-refactor-progress.md that quotes the supervisor
  cap and the decision that stopped the R5 performance wave.
- a77fb73: "R4-D L1 advanced BacktestEngine, NativeStrategyHost, and the private
  consumer to engine_script_run_v17;" (abi-stability.md).
- 44bb687: "R5 L4 adds NativeRunSpec::margin, folded only when it is set;" and
  "R5 L5 adds calculation, max_recalculations_per_point and open_ba..." (abi-stability.md).

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
…ds instead of internal tracking labels

Replace internal task, card and work-lane labels in source comments, docstrings,
workflow comments and human-readable progress lines of test programs with plain
descriptions. About 620 text lines in 285 files; no identifier, file name, CTest
selector, CMake fence, assertion or data file is renamed or edited.

Files whose exact bytes are pinned or whose text is data stay unchanged: the
frozen run_json fixture (its digest is asserted), fixture sources hashed by the
heap census, the ci/ gate data, the broker-state waiver list, the ownership probe
notes, the heap census report heading and the run-failure label passed to
note_run_failure. Printed lines that changed are listed in the pull request; each
old text was searched across the engine and the other repositories and nothing
reads them.

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
…ors them

The CI workflows carry a verbatim authorization job and comments that scripts/ci_preflight.py
and its test expect byte for byte (the contract check "must start with the verbatim canon
authz job" failed on the reworded comments). Restore .github/, scripts/ci_preflight.py and
scripts/test_ci_preflight.py to their previous text.

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
… capital export edit

The export added to the report writer moved the argument parser and the
selected-window helpers of docker/run_json.py by 16 lines (17 for the parser's
flags), so eleven citations in the public contract page pointed at neighbouring
lines. They cite the same functions and flags again.

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
…e fence text

Four CTest rows pin these bytes or fence markers: the oracle SHA-256 pin hashes tests/oracle,
the cr150 CMake-directory check and the private-fixture reads check read the fence text and the
per-lane CMake fragments, and the source gate and its fixtures mirror them. Restore tests/oracle,
tests/cr150.d, tests/CMakeLists.txt, scripts/check_cr150_cmake_d.py,
scripts/check_private_fixture_reads.py, scripts/cr150_source_gate.py and scripts/fixtures to their
previous text.

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
Two overlapping passages are resolved to the preceding members' text, which this
branch only re-worded: the manifest control shard paragraph of docs/ci.md and the
cleanup inspection line of tests/default_scratch_tmpfs_fixture.hpp.
@luisleo526
luisleo526 marked this pull request as ready for review October 28, 2026 00:26
…main

The native order ABI check compares this file with the frozen base commit and
fails when a single byte differs. The wording pass changed one comment line
in it; restore main's bytes so the file stays pinned. The comment is cleaned
together with the pin in a later joint change.
@luisleo526
luisleo526 merged commit d55b116 into main Oct 28, 2026
12 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant