docs: state the fixed-point bound and how a non-converging build reports

[thedavidmeister]

Closes#81

Note

Rewritten against post-#140main, and no longer blocked. The paragraph
this PR previously added documented a bound that does not exist, and patched a
README that #140 has since rewritten. Both are corrected here — see "What
changed since the last push". The PR no longer depends on
rainlanguage/rainix#319, because it no longer states anything that PR would
make true.

What #81 asks for here

#81 has two halves and says so: the loop itself "is rainix's to own and is filed
separately at rainlanguage/rainix#314", leaving this repo the half that lives
here — README.md stating the fixed-point invariant as prose with no bound,
and .github/workflows/build-pointers.yaml inheriting the single-shot
behaviour.

The second half is void: #138 deleted build-pointers.yaml outright along with
the worked example it regenerated. This repo generates nothing and no longer
calls rainix-copy-artifacts.yaml at all, so there is no single-shot behaviour
left here to inherit or to fix.

The first half is what this PR discharges. #81 files it as a hazard: a build
that does not converge is indistinguishable, from CI, from a build the developer
forgot to re-run. The README cannot remove that hazard — removing it means
putting the loop in the machine, which is rainix's and is tracked at
rainlanguage/rainix#314. What the README can do, and now does, is stop leaving
the reader to guess: it says who owns the loop, what to do at a shell, and how
to tell "one more pass" from "this will never settle".

What the README says now

One paragraph, immediately after the fixed-point invariant it qualifies:

Reaching that fixed point is the consumer's job: nothing bounds or iterates
the loop. A tree that has not settled fails the currency check exactly as a
tree nobody regenerated does — see
rainix-copy-artifacts.yaml
— so regenerate until the working tree stops changing before committing, and
read a tree that never stops changing as a cycle that does not converge rather
than one more pass to run. Committing part-way records a deployed-bytecode
hash for a contract compiled against a different pass of the same file.

It is addressed to consumers — rain.deploy and every other repo that drives
this library from script/Build.sol. Nothing in this repo is generated, so
nothing here loops.

What changed since the last push

1. The bound it documented does not exist. Re-verified independently
against rainlanguage/rainix at HEAD 7f223b4:
.github/workflows/rainix-copy-artifacts.yaml runs
forge script ./script/Build.sol exactly once, inside a plain if [ -f ... ]
guard. No loop. max-codegen-passes gets 0 hits across the whole rainix
repo, so there is no such input and no default of 5. fixed point and
did not reach get 0 hits too; the only failure that step's currency check
can emit is Committed artifacts are stale.
rainlanguage/rainix#319,
which would add the bound, is still open (checked at this push).

So the previous paragraph stated a bound, a default, an input name and a failure
message that no deployed workflow has. It is replaced, not softened: the
regeneration loop is unbounded, nothing iterates it, and the operator repeats
until the working tree stops changing.

2. It patched a README that no longer exists.#140 landed today, closing
#139, and rewrote the README so it stops narrating rainix's workflow internals —
mechanism cut, consequence kept, one link to the workflow that owns it. #139
names this PR explicitly as adding a fifth instance of the defect it fixes.

The replacement paragraph is written in that register: the consequence for
someone working in a consuming repo, plus the one link, and no transcription of
what the reusable does step by step. It says what the reader must do and what CI
will and will not tell them; it does not describe the workflow's steps, name its
inputs, or quote its messages.

What was cut

The false-bound paragraph, in full — see above for why. Everything it
asserted about max-codegen-passes, the default of 5, and a
did not reach a fixed point failure is gone rather than hedged.

An earlier paragraph, cut on the previous push and confirmed still cut
through this merge:

One run settles it here: CodeGennable imports nothing from src/generated/,
so its codehash does not move when the file recording it is rewritten. A
consumer whose contracts import what they generate has no such guarantee, and
locally has only git status to tell it that a run changed nothing — repeat
until it does.

Every noun in it is gone: #138 deleted script/Build.sol,
src/generated/CodeGennable.sol and build-pointers.yaml. A plain git merge
does not cut it — its anchor was deleted, so git reattaches it silently to
whatever paragraph now precedes that line. It was removed by hand, and the
merged tree here was diffed against main to confirm it stayed removed.

The blocked-on-rainix#319 banner, because the PR no longer claims anything
#319 would make true.

QA

• Discriminating tests: n/a — the diff is README prose only, with no
  executable behaviour to test. Every factual claim in the paragraph was checked
  against the system it describes: rainix at HEAD 7f223b4 for what CI does and
  does not do (grep counts above), and this repo's own emitters for the
  deployed-bytecode-hash constant the last sentence is about.
• Mutations applied: n/a — docs-only diff, no code paths to mutate.
• Oracle:The generation fixed point is a human loop with no bound and no diagnosis #81's own statement of the invariant, and rainlanguage/rainix at
  HEAD as the authority on CI behaviour — deliberately not rainix#319, which is
  unmerged and therefore not behaviour anyone has.
• Category check:The generation fixed point is a human loop with no bound and no diagnosis #81 asks for (a) the README's unbounded prose to be fixed,
  and (b) this repo's single-shot inheritance to be addressed. (a) is this
  paragraph. (b) is void by Strip the script/Build.sol worked example, leave the library lean #138's deletion, stated here as a finding rather
  than left as a silent omission. The machine-side bound is out of scope by
  The generation fixed point is a human loop with no bound and no diagnosis #81's own text and lives at rainix-copy-artifacts runs codegen exactly once, so a non-converging build is indistinguishable from a forgotten regeneration rainix#314.
• Known future staleness: if rainix#319 lands, "nothing bounds or iterates
  the loop" becomes false and this paragraph needs a revisit. That is the drift
  The README narrates rainix's workflow internals in four places, so it drifts whenever rainix changes and nothing here can catch it #139 is about, and it is why the paragraph states the consequence and links
  the workflow instead of transcribing it — the correction is then one sentence,
  not a re-transcription.
• Post-docs: stop the README narrating rainix's workflow internals #140 tree:main merged in; the merged branch differs from main by
  this one README paragraph and nothing else (git diff origin/main HEAD
  reports README.md | 10 ++++++++++, one file).

[coderabbitai]

Warning

Review limit reached

@thedavidmeister, you've reached your PR review limit, so we couldn't start this review.

Next review available in:16 minutes

Limit details: You’ve used all 1 included review currently available under your plan.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 16ee1008-5cb9-4d13-8662-a0f4195dc755

📥 Commits

Reviewing files that changed from the base of the PR and between c816251 and 0bba9fa.

📒 Files selected for processing (1)

• README.md

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}