fix: prewarm perl runtime for nightly refresh

Author: github-actions[bot]

CHANGELOG.md

@@ -45,6 +45,7 @@ Released: TBA. [Diff](https://github.com/locutusjs/locutus/compare/v3.0.32...mai
 
 - Restored PHP-style scalar coercion for `strtotime()` numeric input and aligned `bcscale()` with modern PHP getter/setter semantics, including shared default `bcmath` scale across `bc*` helpers.
 - Hardened nightly Perl upstream-surface refresh by feeding the discovered namespace catalog through Docker stdin instead of a giant `perl -e` argv payload, and improved `runInDocker()` diagnostics when a container exits non-zero without stderr.
+- Marked Perl upstream-surface discovery as Docker-backed so refresh/enumeration pre-pulls `perl:5.40` instead of letting the first `docker run` fail on implicit pull output in nightly CI.
 
 ## v3.0.31
 

docs/prompts/LOG.md

@@ -3160,3 +3160,23 @@ LLMs log key learnings, progress, and next steps in one `### Iteration ${increme
 - Key learnings:
   - The nightly failure signature matched a transport problem, not a catalog or triage problem: local Perl discovery still worked, but the GitHub runner path was too dependent on a huge `argv` payload surviving unchanged.
   - Tightening error messages in shared infra is worth doing while fixing one concrete workflow; otherwise the next runner-only failure again collapses into an unhelpful `exit code 1`.
+
+### Iteration 156
+
+2026-03-28
+
+- **Area: Maintenance (Nightly parity follow-up)**
+- Plan:
+  - Verify whether the Perl stdin hardening actually fixed the nightly failure, and if not, isolate the remaining runner-only difference instead of guessing.
+  - Prefer a minimal follow-up once the real root cause is visible.
+- Progress:
+  - Re-ran `Nightly Parity` manually on the post-merge head and confirmed it still failed inside `Refresh live upstream snapshots`.
+  - Pulled the failed log and identified the real root cause: `scripts/upstream-surface-enumeration.ts` only pre-pulls Docker images for languages whose handlers set `discoverUsesDocker`, and `test/parity/lib/languages/perl.ts` incorrectly declared `discoverUsesDocker: false`.
+  - Updated the Perl handler to `discoverUsesDocker: true`, so refresh/enumeration now pre-pulls `perl:5.40` through `ensureDockerImage()` instead of letting the first `docker run` emit implicit pull output on stderr.
+  - Added a regression assertion in `test/util/upstream-surface.vitest.ts` to keep Perl marked as Docker-backed for upstream-surface discovery.
+- Validation:
+  - `corepack yarn exec vitest run test/util/upstream-surface.vitest.ts`
+  - `corepack yarn refresh:upstream-surface perl`
+- Key learnings:
+  - The stdin hardening was still worth keeping, but it solved the wrong layer first; the actual nightly break was the handler metadata that opted Perl out of image prewarming.
+  - For runtime-discovered languages, `discoverUsesDocker` is effectively part of the CI contract, not just optional metadata.

test/parity/lib/languages/perl.ts

@@ -175,7 +175,7 @@ export const perlHandler: LanguageHandler = {
   upstreamSurface: {
     discover: discoverPerlUpstreamSurface,
     discoverMode: 'live',
-    discoverUsesDocker: false,
+    discoverUsesDocker: true,
     discoverNamespaceCatalog: discoverPerlUpstreamNamespaceCatalog,
     getLocutusEntry: (func) => ({
       namespace: func.category,

test/util/upstream-surface.vitest.ts

@@ -1012,6 +1012,12 @@ describe('upstream surface inventory', () => {
     expect(isLanguageSupported('swift')).toBe(false)
   })
 
+  it('marks Perl upstream-surface discovery as Docker-backed so enumeration pre-pulls the runtime image', async () => {
+    const { perlHandler } = await import('../parity/lib/languages/perl.ts')
+
+    expect(perlHandler.upstreamSurface?.discoverUsesDocker).toBe(true)
+  })
+
   it('includes source functions even when they do not define examples', () => {
     const root = mkdtempSync(join(tmpdir(), 'locutus-upstream-surface-'))
     const srcDir = join(root, 'src')