Skip to content

docs: explain host-wide build bounding - #89

Merged
catinspace-au merged 1 commit into
mainfrom
docs/host-wide-build-bounding
Sep 4, 2026
Merged

docs: explain host-wide build bounding#89
catinspace-au merged 1 commit into
mainfrom
docs/host-wide-build-bounding

Conversation

@catinspace-au

Copy link
Copy Markdown
Contributor

Adds docs/concurrent-dev-cache.md and corrects three factual errors it
surfaced in tracked files.

The new document

What bounds concurrent builds on one host, and what is deliberately left
unbounded. Rust builds are held by a memory semaphore, the artefact pool by a
ceiling derived from the disk, and the compiler caches by fixed byte ceilings.

It existed untracked as a pre-work design note whose opening line said none of
the work was built. Four of the five things it scoped had shipped, so it is
restructured rather than patched: the Gap 1..5 numbering is gone, so are the
sections addressed to one reader (Decisions for Derek, Not verified, an
open question that was answered), and the unbuilt work is stated as limitations
rather than as a task list. 11 sections became 7, and the slot/memory model is a
diagram instead of three paragraphs.

Nothing linked to it, so it is now linked from the role README, beside its
sibling.

The three corrections

  • developer-rust/README.md said sccache "passes those through" for
    incremental compilation. It does not cache them, which is what the sentence
    meant, but setting CARGO_INCREMENTAL=1 by hand makes sccache refuse the
    build outright. Both cases are now stated. Checked against
    mozilla/sccache,
    not decided by preference.
  • That README and rust-build-governor.md both claimed every build lands in
    rust-build.slice.
    The shim reaches the slice only on Linux with a live
    user manager, and otherwise falls back to a QoS clamp on macOS or to nice.
    All three files now carry the same qualifier.
  • rust-build-governor.md gave HYPERI_RUST_GOVERN_NO_INCREMENTAL=0 as the
    hand override. That is a no-op where the role leaves the setting off, which is
    the default. Both directions are now stated.

Gates

hyperi-ai docs lint clean on all three but for two soft-ceiling findings
(concurrent-dev-cache.md 4 words over, the role README 12). maid reports
Valid on both files under docs/.

Two adversarial review rounds, fresh context each, defaulting to FAIL. The first
failed on five confirmed contradictions. The second caught a regression the
first remediation introduced into a tracked file, which is why there was a
third pass. Every claim in the new document is traced to the role source, the
shim, or the prune tooling.

Known, not fixed here

ansible/roles/developer-rust/README.md carries a ## SSoT section of dated
history about a script that no longer exists, which is the class
documentation-structure.md keeps out of docs. Cutting it would also take the
file under the word ceiling. Left alone deliberately: it is 180 words of why an
earlier approach was rejected, and removing it is a separate call from this
change.

Adds docs/concurrent-dev-cache.md: what bounds concurrent builds on one
host, and what is deliberately left unbounded. Rust builds are held by a
memory semaphore, the artefact pool by a ceiling derived from the disk,
and the compiler caches by fixed byte ceilings.

The file existed untracked as a pre-work design note whose opening said
none of the work was built. Four of the five things it scoped had
shipped, so it is restructured rather than patched: the gap numbering
and the sections addressed to one reader are gone, and the unbuilt work
is stated as limitations. Linked from the role README, which is where
its sibling is linked from.

Corrects three errors in tracked files that the rewrite surfaced.

developer-rust/README.md said sccache passes incremental calls through.
It does not cache them, which is what the sentence meant, but setting
CARGO_INCREMENTAL=1 by hand makes sccache refuse the build outright.
Both cases are now stated.

That README and rust-build-governor.md both claimed every build lands in
rust-build.slice. The shim reaches the slice only on Linux with a live
user manager, and otherwise falls back to a QoS clamp on macOS or to
nice, where the semaphore and the job cap are the bounds. All three
files now carry the same qualifier.

rust-build-governor.md gave HYPERI_RUST_GOVERN_NO_INCREMENTAL=0 as the
hand override. That is a no-op where the role leaves the setting off,
which is the default. Both directions are now stated.
@catinspace-au
catinspace-au merged commit 9e31e1f into main Sep 4, 2026
16 checks passed
@catinspace-au
catinspace-au deleted the docs/host-wide-build-bounding branch September 4, 2026 06:57
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