ci(images): isolate Perl harness race

[apurvvkumaria]

Summary

Keeps the parallel Perl test-harness speedup from #7518 while isolating the one upstream test that is unsafe when it overlaps other test processes. ExtUtils::Constant/t/Constant.t now runs alone first, and the remaining complete suite runs in parallel without running that file twice.

Related Issue

Related to #7140. Follow-up to #7518 and #7338.

Changes

• Run ExtUtils::Constant/t/Constant.t serially before the parallel suite.
• Exclude exactly that already-passed MANIFEST path from the parallel harness.
• Preserve ci(images): parallelize Perl regression tests #7518's TEST_JOBS, PERL_TEST_HARNESS_ASAP, and parallel make behavior for the other 2,933 test files.
• Strengthen the source-shape contract to require both passes, their order, the exact exclusion, and the guard against restoring serial make test.

Type of Change

• Code change (feature, bug fix, or refactor)
• Code change with doc updates
• Doc only (prose changes, no code sample modifications)
• Doc only (includes code sample changes)

Quality Gates

• Tests added or updated for changed behavior
• Existing tests cover changed behavior — justification:
• Tests not applicable — justification:
• Docs updated for user-facing behavior changes
• Docs not applicable — justification: This only changes build-time scheduling of the existing upstream Perl suite; published image contents and supported behavior are unchanged.
• Sensitive paths changed (security, policy, credentials, preflight, onboarding, inference, runner, sandbox, or messaging)
• Sensitive-path review completed or maintainer-approved waiver recorded — reviewer/approval link/justification: Independent nine-category review at exact head 2169c6b found no correctness or security blocker; inputs are fixed build literals, and both harness passes fail closed before install and packaging.
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

Documentation Writer Review

• Documentation writer subagent reviewed the completed changes
• Result: no-docs-needed
• Evidence: The change is internal base-image test scheduling and does not alter image contents, CLI behavior, user workflows, security guarantees, or contributor commands.
• Agent: Codex Desktop

DGX Station Hardware Evidence

• Tested on DGX Station
• Tested commit:
• Station profile/scenario:
• Result:
• Supporting evidence:

Verification

• PR description includes a Signed-off-by: line and every commit appears as Verified in GitHub
• Normal pre-commit, commit-msg, and pre-push hooks passed, or npm run check:diff passed when hooks were skipped or unavailable
• Targeted behavior tests pass for the current change set, or tests are marked not applicable above — exact head 2169c6bc5: npx vitest run --project integration test/perl-critical-cve-remediation.test.ts test/dcode-base-image-workflow.test.ts passed 8/8; npx prek run --from-ref origin/main --to-ref HEAD passed all applicable hooks. Prior native-arm64 perl-builder evidence passed the isolated 302-test file, the remaining 2,933-file suite, install, package creation, and image build.
• Applicable broad gate passed — not applicable; this is an isolated Dockerfile test-scheduling change validated by the full upstream Perl suite and its focused repository contract.
• Quality Gates section completed with required justifications or waivers
• No secrets, API keys, or credentials committed
• npm run docs builds without warnings (doc changes only)
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

---

Signed-off-by: Apurv Kumaria akumaria@nvidia.com

Summary by CodeRabbit

• Bug Fixes

  • Improved Perl build reliability in parallel or emulated environments by running a sensitive test as a dedicated serial step before the remaining harness.
  • Added stronger validation that serial + parallel test selections exactly match the full upstream test set and include the sensitive test once.
  • Ensured the packaging step only occurs after the complete two-phase test process succeeds.

• Tests

  • Expanded CI test sequencing to verify ordering, correct test filtering, and proper inclusion/exclusion across phases.

[coderabbitai]

📝 Walkthrough

Walkthrough

The Perl build now runs Constant.t serially before a filtered parallel upstream test pass. The remediation test verifies selection equivalence, execution ordering, installation, and packaging.

Changes

Perl test harness workflow

Layer / File(s)	Summary
Two-phase Perl test execution Dockerfile.base	Documents the QEMU workaround, validates split selections against the full suite, and runs Constant.t serially before the remaining tests in parallel.
Execution ordering validation test/perl-critical-cve-remediation.test.ts	Checks enumeration, selection comparison, harness ordering, installation, packaging, split-removal guidance, and base-image build assertions.

Estimated code review effort: 2 (Simple) | ~10 minutes

Sequence Diagram(s)

sequenceDiagram
  participant DockerBuild
  participant PerlHarness
  participant TestSelection
  DockerBuild->>PerlHarness: Enumerate full test suite
  DockerBuild->>TestSelection: Compare serial and filtered parallel selections
  DockerBuild->>PerlHarness: Run Constant.t serially
  DockerBuild->>PerlHarness: Run remaining tests in parallel

Loading

Possibly related PRs

• NVIDIA/NemoClaw#7504: Follow-up refining the Perl build/test flow and its remediation assertions.
• NVIDIA/NemoClaw#7518: Updates the same Dockerfile and remediation test with the parallel Perl harness workflow refined here.

Suggested labels: area: sandbox, platform: container

Suggested reviewers: senthilr-nv

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title is concise and clearly reflects the main change: isolating the Perl test harness race in CI images.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/base-perl-parallel-tests

---

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

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage in commit 2169c6b in the codex/base-perl-para... branch remains at 96%, unchanged from commit ab54114 in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit 2169c6b in the codex/base-perl-para... branch remains at 81%, unchanged from commit ab54114 in the main branch.

Show a code coverage summary of the most impacted files.

File	main ab54114	codex/base-perl-para... 2169c6b	+/-
src/lib/onboard/docker-cdi.ts	80%	70%	-10%
src/lib/shields/index.ts	72%	67%	-5%
src/lib/onboard...host-anchors.ts	94%	90%	-4%
src/lib/onboard/preflight.ts	77%	78%	+1%
src/lib/onboard...ndbox-create.ts	83%	91%	+8%
src/lib/domain/.../connect-env.ts	89%	97%	+8%
src/lib/actions...confirmation.ts	69%	79%	+10%
src/lib/actions...ocker-health.ts	65%	82%	+17%
src/lib/onboard...box-prebuild.ts	74%	92%	+18%
src/lib/onboard...ndbox-create.ts	33%	83%	+50%

---

_{Updated July 25, 2026 23:47 UTC}

[github-actions]

PR Review Advisor — No blocking findings reported

Advisor assessment: No blocking advisor findings reported
Next action: No advisor follow-up needed.
Findings: 0 blockers · 0 warnings · 0 suggestions

Model lanes

• GPT-5.6 Terra (primary): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Nemotron 3 Ultra (second opinion): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Model comparison: normalized findings match; normalized E2E selections differ; severity counts match.

Nemotron output stays in workflow artifacts and does not change the assessment above.

E2E guidance

Advisory only. E2E / PR Gate selects and runs jobs independently.

Recommended E2E: cloud-onboard

Workflow run details

This automated review informs maintainers. Warnings and suggestions do not require a response. A maintainer decides whether to merge.

[apurvvkumaria]

Addressed PRA-1 in signed commit c6161a8. The Perl builder now uses upstream t/harness -dumptests during the image build to compare the sorted full suite against the union of the serial and filtered-parallel selections, and asserts cpan/ExtUtils-Constant/t/Constant.t appears exactly once. The existing commands then run those same selections. I also documented the removal condition: remove the split only after the unsplit parallel harness passes in two consecutive amd64 and arm64 base-image builds. Local evidence: npx vitest run --project integration test/perl-critical-cve-remediation.test.ts (4/4 passed), plus all changed-file prek hooks passed, including hadolint. Fresh exact-head CI is now authoritative.

[apurvvkumaria]

Documentation writer review completed for exact head c6161a8db: no-docs-needed.

The net change only hardens internal build-stage Perl test scheduling and proves selection equivalence. It does not change the packaged runtime, CVE disposition, sandbox behavior, user commands, configuration, setup, migration, or support claims. The temporary-removal criterion belongs beside the Dockerfile workaround and is enforced by the contract test; existing release/security documentation remains accurate.

• Documentation writer subagent reviewed the completed changes
• Result: no-docs-needed
• Agent: Codex Desktop

[apurvvkumaria]

Maintainer follow-up: I synced this branch to current main with signed merge commit d98aa4ffb (preserving the original author history). The targeted Perl parallel-lane regression suite passed locally (18 tests), and push hooks passed. Fresh CI is now running on this exact head; no reviewer question is outstanding yet.

[apurvvkumaria]

Exact-head maintainer follow-up for 90e0b3ea4: the two advisor warnings do not require another code change. The required amd64 image job and native arm64 image job each executed the split harness: Constant.t passed alone (1 file, 302 tests), the remaining 2,933-file suite passed with about 1.39M tests, and install/package creation completed. The Dockerfile already records the exact observed overlap signature and a two-architecture removal condition; this PR is the durable local regression reference.

The red E2E checks are unrelated to the Perl change: coordination failed in generate-matrix at Authenticate controller dispatch before any selected E2E job ran. That is the known controller defect fixed by #7529, so a same-head rerun would not be actionable. The PR remains gated on #7529 landing, fresh exact-head E2E, and independent approval.

[cv]

Maintainer approval for exact head 2169c6b: canonical gates pass; all 51 current checks are green, including exact-pair cloud-onboard E2E; DCO and all 7 commits are Verified; Advisor reports 0 blockers, 0 warnings, and 0 suggestions; all review threads are resolved; product scope, security, and documentation review gates pass.