Repository navigation
Qualify docs loop budgets before the Perl site integration #270
Description
Summary
The Perl integration is ready for shared-site build and review coordination. Local documentation checks repeatedly exceed the existing development-loop deadlines on a resource-constrained WSL host; hosted CI has not yet supplied a complete timing result for this integration.
Motivation
The integration adds native POD-based API documentation, guides, navigation, source links, and separate core, async, and workspace product inventories. The distributions are source-only and must remain labelled unpublished. The source branch is available for review; shared-site deployment is awaiting specific authorization.
We need to distinguish a correctness failure, an implementation slowdown, and a deadline exceeded under host contention before deciding whether a timing budget should change. Repeating broad local checks under the same pressure has not resolved that distinction.
Evidence
Local measurements and hosted verification status
The shared runner currently enforces inner, medium, and outer deadlines of 2, 10, and 60 seconds. Whole-command measurements from this integration include:
| Check | Local result |
|---|---|
pnpm test:medium |
Deadline exceeded; 10.74 seconds including shutdown. |
pnpm test |
Deadline exceeded; 60.55 seconds including shutdown. |
| Shared Node type check | Cancelled at approximately 59 seconds; no current complete verdict. |
| Separate source-only unit diagnostic | Passed 4,358 assertions in 40.872 seconds; four assembly suites and 251 cases explicitly skipped. This is correctness evidence for that subset, not a passing development loop or publication audit. |
The local environment uses Linux 6.18 on WSL2, Node 26.5.1, and pnpm 12.15.0. Observed Linux pressure included CPU avg10 values of 85–93 percent and memory avg10 of 26.56 percent. Other active workspaces were left untouched. CPU, memory, and disk constraints need consideration; disk saturation was not established by these measurements.
A later run on the corrected source passed pnpm test:inner in 1.87 seconds but still exceeded the medium deadline at 10.77 seconds, with CPU avg10 approximately 13 percent and memory pressure subsiding. Earlier high contention alone does not establish the cause of every deadline failure.
The first build-only workflow run used Perl source 219f5dd0adec24f6a4f9320bcd5fea3ac7221438 and shared builder 3198ae8216efd824f2d9593e43511342ca36c7c5, with publish=false. It failed during assembly because the shared reader entry omitted the parsePythonDoc export. This is a concrete source defect, separate from the timing question. The source branch now includes the fix and a check through the public reader entry; a successful complete rerun remains required.
The separate native-package CI run covers the Perl packages and Linux/tmux matrix. Native compatibility and shared-site timing are separate gates.
Proposal
Coordinate review and eventual publication of the Perl documentation with the docs maintainer. Measure the exact checks on their intended local and CI runners, record runner resources and contention, and then decide whether the existing deadlines need environment-specific adjustment. Preserve correctness checks and explicit failed, cancelled, skipped, and unverified results while making that decision.
Activity
tony commentedon Nov 8, 2026
Pending r18 reconciliation: the docs maintainer clarified that unpublished product overviews remain valid destinations; only explicit exclusion removes the product destination. The earlier broad guard and test oracle conflated page existence with implementation availability. After #267/r18 merges, #274 will adopt the common fix, drop its overlapping navigation code, and retain Perl-specific exclusion/native-guide coverage. Current ninth CI is provisional for that pending tree. Native core/archive qualification is unaffected, but the 7ef/322 compiled docs artifact needs a post-r18 renderer refresh before target publication. No branch source change was made before r18.
Perl docs PR #274 is at
56d5ebc6bcc4dd42fb3dd1d0daf3ddbd125a6dc7. The ninth full audit is running. This commit changes one test file; rendering, library, exporter and workflow inputs remain unchanged. Native artifact/publisher pins remain at verified shared322a7b1.The eighth full audit ended FAIL after 2h09m37s. Its complete preview assembly link audit passed: 42,622 pages, 7,604,358 links, zero broken links. Production-root renders, Sphinx inventories and preview isolation also passed. Output tests then reported 17 failed, 9,207 passed, 34 skipped, all failures in
product-docs.test.ts. Both automatic preview jobs were skipped. Subsequent audits did not run.Those assertions still expected unavailable product placeholders as matching destinations, used generic titles for Perl's native guide/reference, and omitted Perl's source-guide counterpart. The repair retains exact counterpart counts, targets and resolution checks; it strengthens unavailable-product exits to require core homes. The current test commit uses an explicit availability oracle; its unpublished-overview exclusions are superseded by the clarified policy and will be reconciled after r18. Perl's authored titles and four source-guide counterparts remain required. Only an empty Perl browse-test registration was removed. Independent review found no blocker and caught the previously masked
LibTmux::Workspace API referencetitle. Focused source checks passed 51 tests in 3.28s, with 107 assembled-output skips explicitly retained; authentic native HTML facts passed in 0.64s, lint in 0.10s, and whitespace checks passed. These do not replace the new complete hosted run.Native
7ef1371b97fdaa48973f47fc7b0bc198ed4acc03package CI passes all 15 jobs, including installed archives and every required Linux/tmux cell. Its source-bound build-only docs run passes with publication skipped. The exact archive verifies all 4,299 files and clean library/exporter/renderer identities. The test-only change preserved the recorded artifact proof. The newly clarified destination policy does require a later renderer/pin/artifact refresh; the existing byte verification does not qualify that future navigation behavior.The dangling-reference ceiling remains 60. The hosted root renders measured 58 total, zero Perl. The local selected-source build completed in 111.66s, but its raw zero assertion FAILED with 76 candidates, 18 labelled Perl. The complete Perl-labelled list is:
tmux.conftmux.sockEnterscreen.txtcapture:0.0workspace.confllms.txtllms-full.txtNone=work:editorsphinx.ext.intersphinxIndependent review traced all 18 to shared tmux examples, key guides and Sphinx/AI metadata prose, rather than Perl-owned APIs. The existing reporter test expects shared literals under the selected build port and excludes selected builds from the root ceiling. The two reports count different populations. Raw rows/failure and source occurrence evidence remain; no reporter suppression or ceiling change was made. NDJSON lacks source locations, so repeated
Enterrecords cannot be uniquely paired with occurrences. The local diagnostic had an untracked author-dependency symlink and is separate from the verified clean publication artifact.Hosted component timings from the eighth run:
Component timings run from the stage announcement to its build summary; they are not whole-command qualification. The whole hosted job took 7,777 seconds including setup. The workflow renders production roots again to check canonical URLs, robots, sitemaps and indexing.
Local shared-docs timing failures remain historical diagnostics. The operator accepts passing hosted CI as the gate. No deadline, assertion or ceiling was raised. Draft automatic previews are authorized; main merge and production deployment remain held.
tony commentedon Nov 8, 2026
Perl’s current source-bound docs build passes. PR #274 is pushed at
6201662cfc35c5266d907dd4c8cfcc9369008289, using native source/exporter352715a4fa66a96eed7763b90daaa536aa2f121d. Its full shared-site run is still running; automatic preview remains pending.The Ruby legacy-guide timeout reproduces when an external badge response is held: the correct destination document is ready, but
loadstill waits for the image. The committed regression checks URL and parsed-document readiness while holding that response. It does not claim visual readiness with pending images. No timeout or retry allowance was increased. The separate status-badge suite passes in isolation; the earlier hostedECONNRESETcause remains unverified.Local heavy checks use the shared 8 GiB / 4 CPU cap. Astro type checking required a 6 GiB Node heap within that cap; the earlier default-heap failure remains recorded. Native POD section links, Markdown member summaries, async prerequisites and workspace package notices are corrected. Earlier cancelled shared runs remain cancelled evidence, not successes.
Native current-head CI passes all six jobs. Support covers tmux 3.3a–3.8, including intermediate releases. CI tests only 3.3a and 3.8 on the latest stable Perl, currently 5.44.0. Plain tmux 3.3 remains below the support floor. This changes test coverage, not the supported range.
The PR stays draft until the full shared check and preview pass. Shared-main integration remains with the docs maintainer; production publication is still held. No deadline or dangling-reference ceiling change is requested.