## What is wrong Two documents describe the same set of hand-rolled in-flight caps. `docs/dev/storage-accounting.md` holds the census, in `## In-flight caps of this shape, by the resource they draw on`. `docs/dev/remote-read-budgets.md` holds one cap's own section, in `### The detached retention-write cap`. Both documents state how many caps exist. `docs/dev/storage-accounting.md` also tables each cap with a `file:line` coordinate. The count and the line numbers both rot, and both have rotted already. The constant name and the file path do not rot the same way. A constant moves to a different line under any edit above it in the same file. A count changes under any merge request that adds or removes a cap anywhere in the tree. A name and a path change only when someone renames or moves the cap, and a reader who greps the name finds it either way. ## Evidence: three of the eleven tabled coordinates are wrong on `main` Measured at `origin/main` `7307bd94a`. Command: ```shell git grep -n "MaxInFlight = 64" origin/main -- internal ``` The command returns eleven rows. Three of them disagree with the table that claims to hold them: | Constant | Tabled at | The command reports | Table row | | --- | --- | --- | --- | | `bufferedUpdateMaxInFlight` | `internal/format/maven/buffered.go:82` | `internal/format/maven/buffered.go:73` | `docs/dev/storage-accounting.md:1509` | | `bufferedCounterUpdateMaxInFlight` | `internal/managementapi/artifact_write.go:417` | `internal/managementapi/artifact_write.go:435` | `docs/dev/storage-accounting.md:1512` | | `deleteCounterEmitMaxInFlight` | `internal/managementapi/artifact_write.go:291` | `internal/managementapi/artifact_write.go:309` | `docs/dev/storage-accounting.md:1527` | The other eight rows are correct at that commit. No pipeline reports the three wrong ones, because nothing reads a Markdown table cell as a coordinate. ## Evidence: two open merge requests already disagree about the count Both merge requests add a twelfth cap. Both rewrite the count. They partition the twelve differently, so each one makes the other wrong. | Branch | Total | Postgres partition | Redis partition | Row memory | | --- | --- | --- | --- | --- | | `origin/main` `7307bd94a` | Eleven | Six | Four | One | | Merge request 2324, `a8514c07f` | Twelve | Six | Five | One | | Merge request 2362, `a46e29362` | Twelve | Seven | Four | One | Merge request 2324 adds `counterEmitMaxInFlight` in `internal/lifecycle/emit_dispatch.go`, which draws on Redis. Merge request 2362 adds `repositoryStampMaxInFlight` in `internal/format/oci/emit_dispatch.go`, which draws on Postgres. Each branch is right about its own cap and wrong about the other one. Whichever merges second has to re-derive all four numbers by hand, in prose and in two headings. Merge request 2362 is also inconsistent with itself, on its own branch, with no other merge request involved. At `a46e29362`: - `docs/dev/storage-accounting.md:1467` says "Twelve hand-rolled in-flight caps". - `docs/dev/storage-accounting.md:1482` says "Eleven constants under `internal/` name an in-flight cap". - `docs/dev/storage-accounting.md:1500` is the heading "Seven bound a worker population that holds a pooled Postgres connection". Three numbers, one document, one branch. The census command returns twelve there. Both branches still carry the three wrong coordinates from `main`. A merged plan carries the same rot. `docs/plans/2026-09-03-repository-column-writers.md:640`, at `7307bd94a`, says the container steps of that plan add "no twelfth cap". Merge request 2362 is step 3 of that plan and it adds `repositoryStampMaxInFlight`. The sentence names a number and the number moved under it. ## Evidence: merged text already states no count, on purpose Three merged places take the position this change extends. `docs/dev/remote-read-budgets.md:182`, at `7307bd94a`: > No total is stated here, because a per-consumer number cannot derive one and the total grows as consumers are added. `docs/dev/storage-accounting.md:1489`, at `7307bd94a`: > A cap is identified by its constant and its path, and the line number is whatever the command reports, so a coordinate that has drifted is read off a fresh run rather than off a stamp. `internal/format/oci/emit_dispatch.md:37`, at `7307bd94a`: > This file states no count and no list of its own, so a copy added or removed moves one document rather than several. Work item 559 takes the same position in its own description: > The three tables below give the constant and its path, and no line number. > A line number goes stale at the next edit to the file. The census document is the one place that did not follow it. ## What to change In `docs/dev/storage-accounting.md`: - Remove every stated count of caps from the prose of `## In-flight caps of this shape, by the resource they draw on`. - Remove the count from the three partition headings. - Remove the count from the `Eleven hand-rolled in-flight caps` row of `## Known gaps`. - Remove the `:NNN` from every row of the three census tables. Keep the constant and the path. In `docs/dev/remote-read-budgets.md`: - Remove every stated count of caps from `### The detached retention-write cap`. Keep in both documents: - Every constant name and every file path. - The census command, `git grep -n "MaxInFlight = 64" -- internal`, and the sentence that says the line number is whatever the command reports. - The partition each cap belongs to and the resource behind it. The partition is the point of the section, and a new cap does not falsify it. - The named list of pool consumers at `docs/dev/remote-read-budgets.md:169` to `:172`. It names constants, not a number. - The exclusion argument for `Config.ReconciliationMaxInFlight`. Rewrite the sentence at `docs/dev/storage-accounting.md:1485`, which says the wider pattern "returns thirteen rows where the census returns eleven". The rewrite names both commands and the difference between them, and neither figure. ## The three headings are anchor targets Each partition heading opens with its count, so removing the count renames the anchor. Three inbound links have to move in the same change. Measured at `7307bd94a`: | Link at | Anchor | | --- | --- | | `docs/dev/remote-read-budgets.md:174` | `storage-accounting.md#six-bound-a-worker-population-that-holds-a-pooled-postgres-connection` | | `docs/dev/storage-accounting.md:1501` | `#four-bound-the-accounting-emit-which-holds-a-redis-connection` | | `docs/dev/storage-accounting.md:1487` | `#one-bounds-row-memory-rather-than-a-connection` | Command that finds them: ```shell git grep -n "six-bound-a-worker-population\|four-bound-the-accounting-emit\|one-bounds-row-memory" origin/main ``` The section anchor `#in-flight-caps-of-this-shape-by-the-resource-they-draw-on` carries no count and does not move. Four links in three files point at it, and all four stay valid. ## One claim outside the two documents goes false `internal/format/oci/emit_dispatch.md:36`, at `7307bd94a`, says of the census table: > it tables every one by constant and `file:line` That sentence is false once the coordinates go. Correct it in the same change, so it says the table names each cap by constant and path. This is a one-line edit and it keeps the change self-consistent. `docs/runbooks/npm-packument-cache-invalidation.md:67` also tables a coordinate, `internal/format/npm/inline_build.go:27`. That figure is correct at `7307bd94a`. The file is a runbook rather than the census, and this change leaves it alone. ## Size Measured at `origin/main` `7307bd94a`. `docs/dev/storage-accounting.md`: - 19 prose lines that state a cap count. Eighteen of them are inside `## In-flight caps of this shape, by the resource they draw on`, and one is the `## Known gaps` row at `:1465`. - 3 partition headings, at `:1498`, `:1518` and `:1534`. - 11 table rows that carry a `:NNN`, at `:1509` to `:1514`, `:1524` to `:1527`, and `:1538`. That is 33 lines. `docs/dev/remote-read-budgets.md`: - 6 prose lines that state a cap count, at `:174`, `:176`, `:177`, `:178`, `:179` and `:180`. `internal/format/oci/emit_dispatch.md`: - 1 line, at `:36`. Commands: ```shell git show origin/main:docs/dev/storage-accounting.md | grep -cE '^\| `[A-Za-z]+MaxInFlight` \| `internal/[^`]*:[0-9]+` \|$' git show origin/main:docs/dev/storage-accounting.md | sed -n '1478,1545p' | grep -nE '\b([Ee]leven(th)?|[Tt]welfth|[Tt]hirteen|[Tt]en|[Ss]ix(th)?|[Ss]even(th)?|[Ff]our|[Ff]ive)\b' git show origin/main:docs/dev/remote-read-budgets.md | grep -nE '\b([Ee]leven(th)?|[Tt]en|[Ss]ix(th)?|[Ss]even(th)?|[Ff]our|[Ff]ive)\b' ``` The first returns 11. The second returns 20 lines, and two of them are the headings that open with `Six` and `Four`. The third partition heading opens with `One`, which the pattern does not select. The third command returns 8 lines, and 6 of them state a cap count. The other two, at `:72` and `:94`, count response arms and a timeout multiple. An earlier pass measured 20 lines plus 3 headings in `docs/dev/storage-accounting.md`. That figure counts the same prose and the same headings, and it omits the 11 table rows. The figure of 6 lines in `docs/dev/remote-read-budgets.md` is confirmed exactly. ## Ordering This change is documentation only and it touches no Go file. It is a prerequisite of work item 559 rather than a part of it. It is cheapest while it goes first. The two open merge requests above each edit the same prose lines and the same headings. Once one of them merges, this change has to be re-derived against whatever count that branch wrote. ## Why the count is the thing that rots A count is a claim about the whole tree, so a change anywhere in the tree can falsify it. A constant name and a path are claims about one file, and a reader checks either one with a single grep. The census command already gives the reader a current answer, so a printed count adds nothing and takes on every future edit as a liability. The failure is quiet. Nothing compiles a Markdown table, and no lint job runs the census command. The reader who checks a number is the reader who needed it, and a stale number sends that reader the wrong way. Related to https://gitlab.com/gitlab-org/ops/artifact-registry/-/work_items/559 _This is a bot message 🤖 — /smurfit_