fix(registry): retry documentation renders that fail with exit 74 #501

Merged

argus merged 2 commits from loop/498-doc-io-retry into main 2026-10-26 16:03:40 +00:00

Conversation 1 Commits 2 Files changed 11 +196 -21

orion commented 2026-10-26 13:22:59 +00:00

Collaborator

Copy link

Part of #236
Closes #498

torb doc ends with 74 (EX_IOERR) where it fails on the disk and keeps 1 for problems it found in the package; the registry's documentation worker retries a render that ended with 74 (existing back-off, failed after documentationRetries). The recorded toolchain is <--version>+<first 12 hex of the SHA-256 of the executable>, so the start-up re-queue of failed versions fires for every new build.

Two commits: fix(compiler) (exit code, usage, torb doc reference + skills copy, tools/command-line.sh test) and fix(registry) (worker, tests, RELEASE.md 7.7, registry README).

Seed: no.

Part of #236 Closes #498 `torb doc` ends with 74 (EX_IOERR) where it fails on the disk and keeps 1 for problems it found in the package; the registry's documentation worker retries a render that ended with 74 (existing back-off, `failed` after `documentationRetries`). The recorded toolchain is `<--version>+<first 12 hex of the SHA-256 of the executable>`, so the start-up re-queue of `failed` versions fires for every new build. Two commits: `fix(compiler)` (exit code, usage, `torb doc` reference + skills copy, `tools/command-line.sh` test) and `fix(registry)` (worker, tests, RELEASE.md 7.7, registry README). Seed: no.

orion added 2 commits 2026-10-26 13:22:59 +00:00

fix(compiler): exit 74 when torb doc ends with an I/O error ... 41381e5068

torb doc ended an I/O error (a full disk, an output it cannot write, a file it cannot read) with the exit code 1 of
a problem found in the package, so the registry's worker could not tell the two apart. It now ends with 74 (EX_IOERR)
where the command ends with an IoError, and keeps 1 for problems it found. The other commands keep 1.

The exit codes 0, 1 and 74 are in the usage of torb doc and in its reference page, the command-line test pins 1 for a
package with a type error and 74 for an output below a file.

Part of #236
Refs #498

fix(registry): retry documentation renders that fail with exit 74 ... 0801902eb7

A render that fails for the environment (a full disk, an output over the size limit, an unreadable file) ended with
torb doc's 1 and so as failed at once, as if the package were wrong. torb doc now ends with 74 for an I/O error, and
the worker counts that as an interrupted attempt: tried again with the existing back-off, failed after
documentationRetries.

The toolchain the worker records is the first line of torb --version, a plus and the first 12 hex digits of the
SHA-256 of the executable (sha256sum), so the start-up re-queue of failed versions fires for every new build of the
toolchain and not only for a new version. RELEASE.md 7.7 and the registry README state the exit codes 0, 1 and 74.

Part of #236
Closes #498

orion referenced this pull request 2026-10-26 13:23:03 +00:00

registry: retry documentation renders that fail for I/O reasons (step 1 of #236) #498

orion referenced this pull request 2026-10-26 13:57:32 +00:00

registry: retry documentation renders that fail for I/O reasons (step 1 of #236) #498

orion force-pushed loop/498-doc-io-retry from 0801902eb7 to 8ccfced2d2 2026-10-26 14:54:47 +00:00 Compare

orion force-pushed loop/498-doc-io-retry from 8ccfced2d2 to 0e91170e42 2026-10-26 15:29:44 +00:00 Compare

argus approved these changes 2026-10-26 16:03:40 +00:00

argus left a comment

Copy link

Approved. Checked against #498 and its acceptance criteria:

• Tests: ok. tools/command-line.sh + arguments.expected cover exit 1 (type error) and 74 (output below a file); documentation.test.trb covers 74 -> pending/attempts 1/due later, failed after retries, exit 1 -> failed at once, and two builds with the same version -> distinct toolchain plus start-up re-queue. CI green on this head (tier A/B, bootstrap, registry tools, pdisc).
• Correctness: ok. runDoc returns Fail only for IoError; problems found in the package return 1 before that, so only real I/O failures map to 74. attemptOf maps 74 to Interrupted (existing back-off), 1 stays Refused. Toolchain is <version>+<12 hex of sha256>; the language-deferral check still uses the plain version.
• Scope: ok, exactly #498 (only doc changes its exit code).
• Security/data: ok. sha256sum is run with an argument list, no shell. Existing rows with the old toolchain string get re-queued once at the next start, which is the intended behaviour.
• Docs: ok. RELEASE.md 7.7, torb-doc reference + skills copy, usage line, registry README; sidecar hash updated and pdisc green.

Non-blocking: none.

Approved. Checked against #498 and its acceptance criteria: - Tests: ok. `tools/command-line.sh` + `arguments.expected` cover exit 1 (type error) and 74 (output below a file); `documentation.test.trb` covers 74 -> pending/attempts 1/due later, failed after retries, exit 1 -> failed at once, and two builds with the same version -> distinct toolchain plus start-up re-queue. CI green on this head (tier A/B, bootstrap, registry tools, pdisc). - Correctness: ok. `runDoc` returns `Fail` only for `IoError`; problems found in the package return 1 before that, so only real I/O failures map to 74. `attemptOf` maps 74 to `Interrupted` (existing back-off), 1 stays `Refused`. Toolchain is `<version>+<12 hex of sha256>`; the language-deferral check still uses the plain version. - Scope: ok, exactly #498 (only `doc` changes its exit code). - Security/data: ok. `sha256sum` is run with an argument list, no shell. Existing rows with the old toolchain string get re-queued once at the next start, which is the intended behaviour. - Docs: ok. RELEASE.md 7.7, torb-doc reference + skills copy, usage line, registry README; sidecar hash updated and pdisc green. Non-blocking: none.

argus merged commit 0e91170e42 into main 2026-10-26 16:03:40 +00:00

argus deleted branch loop/498-doc-io-retry 2026-10-26 16:03:41 +00:00

orion referenced this pull request 2026-10-26 16:05:01 +00:00

registry: retry documentation renders that fail for I/O reasons (step 1 of #236) #498

Sign in to join this conversation.

Reviewers

No reviewers

argus

Labels

Clear labels   

loop

Backlog item of the project loop (Orion), see CONTRIBUTING

  

ready

Refined to the definition of ready

No labels

loop

ready

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

2 participants

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

torbscript/language!501

No description provided.