Worker path helper: one opaque `return` discards the whole candidate union

[proggeramlug]

Summary

resolve_worker_path's return-union walk aborts the entire candidate set when any single return is outside the static path grammar. One opaque return therefore turns a Worker that is 2/3 resolvable into a hard compile-time refusal:

Error: worker_threads Worker filename was not statically resolvable at compile time;
       constructing this Worker is unsupported in the compiled binary

This is the OpenCode TUI wall. packages/opencode/src/cli/cmd/tui.ts runs the whole TUI inside a Worker, so when construction throws (inside an enclosing try), the error is swallowed, the command returns, and the process sits in an idle event loop with a blank screen — alive, no output, no diagnostic.

The one line that does it

packages/opencode/src/cli/cmd/tui.ts:52:

async function target() {
  if (typeof OPENCODE_WORKER_PATH !== "undefined") return OPENCODE_WORKER_PATH  // ← opaque
  const dist = new URL("./cli/tui/worker.js", import.meta.url)                   // resolvable
  if (await Filesystem.exists(fileURLToPath(dist))) return dist
  return new URL("../tui/worker.ts", import.meta.url)                            // resolvable, and the one actually taken
}

Measured on a fixture reproducing target() exactly (perry @ v0.5.1579 + #10356):

variant	modules compiled	result
OpenCode's target() verbatim	1	THREW not statically resolvable
same, minus the typeof OPENCODE_WORKER_PATH guard	2	OK {"ran":true}
same, minus the Filesystem.exists probe, guard kept	1	THREW not statically resolvable

"modules compiled: 1" is the tell — the worker entry is never compiled into the binary at all.

Everything else about the feature already works

The surrounding machinery handles partial unions correctly; only the union walk is all-or-nothing.

spelling	result
new Worker("./w.ts")	OK
new Worker(new URL("./w.ts", import.meta.url))	OK
new Worker(fileURLToPath(new URL("./w.ts", import.meta.url)))	OK
new Worker(OPENCODE_WORKER_PATH) with --define	OK
new Worker(new URL("./w.ts", import.meta.url).pathname)	THREW not statically resolvable
new Worker(new URL("./w.ts", import.meta.url).href)	THREW not statically resolvable

Indirection is fine — a const, an awaited arrow, an async helper with branches all resolve. And a missing file among the candidates is handled exactly right:

candidates	result
one candidate, exists	OK
two candidates, the unused one missing	OK — compiles the good one
two candidates, the taken one missing	throws at runtime: "Worker filename did not match an existing compile-time-resolved worker entry"

So a partial union is already a supported, tested concept. collect_modules/worker.rs::resolve_candidates says so in its own comment:

Missing candidates never become import edges. Retain their spellings alongside valid ones so codegen cannot mistake a partial union for a proven single target: choosing a missing candidate must throw at runtime.

Root cause

crates/perry-hir/src/dynamic_import/worker_paths.rs, in returns():

Stmt::Return(Some(value)) => {
    let returned = self.resolve(value, depth + 1)?;   // ← `?` aborts the whole union
    values.is_url |= returned.is_url;
    for path in returned.paths {
        push_path(&mut values.paths, path, &mut self.work)?;
    }
    always_returns = true;
}

resolve_worker_path then maps that Err to Resolution::Unresolved, discarding the returns that did resolve.

The function's own doc comment already draws the right distinction for conditions —

Discover edges, not control flow: conditions can contain opaque calls (including awaited filesystem probes).

— but a return gets no such tolerance, even though an unresolvable return is the same kind of fact: it means "this edge is unknown", not "no edge is knowable".

Suggested fix

Treat an unresolvable return like a missing candidate: drop it from the union, keep the resolvable ones, and compile those as worker entries. The runtime dispatch in perry-codegen/src/expr/worker_new.rs::lower_candidates already matches the actual filename against the compiled set and throws when nothing matches, so an opaque path that is genuinely taken still fails loudly — at the moment it is used, rather than poisoning every sibling.

One caution for whoever implements it: the union must stay marked as partial so codegen cannot collapse a single surviving candidate into a proven single target. Otherwise new Worker(opaquePath) would silently run the one compiled worker instead of throwing. resolve_candidates solves this for missing files by retaining their spellings; an opaque return has no spelling, so it needs an explicit flag rather than relying on set size.

Workaround

--define 'OPENCODE_WORKER_PATH="/abs/path/to/worker.ts"' makes the first return resolvable and the Worker compiles. That is what OpenCode's define hook is for, and it is how I am unblocking the TUI build meanwhile.

[proggeramlug]

The "mark it partial" caution is real, not hypothetical — here is the line

I flagged in the issue body that a fix must keep the union marked partial so codegen cannot collapse a lone survivor into a proven single target. Having read the lowering, that hazard is concrete.

crates/perry-codegen/src/expr/dyn_extern_i18n.rs:519:

Expr::WorkerNew { paths, filename, options, is_eval: _ } => {
    if paths.len() > 1 {
        return worker_new::lower_candidates(ctx, paths, filename, options.as_deref());
    }
    let _ = lower_expr(ctx, filename)?;
    ...

Only paths.len() > 1 reaches lower_candidates, which is the arm that compares the runtime filename against the compiled aliases and throws on no match. With exactly one path, codegen lowers the filename expression for effect and uses that single compiled target without comparing.

So the naive version of this fix — drop the unresolvable return in worker_paths.rs::returns() and keep the rest — is actively dangerous for OpenCode's exact shape:

async function target() {
  if (typeof OPENCODE_WORKER_PATH !== "undefined") return OPENCODE_WORKER_PATH  // opaque, dropped
  const dist = new URL("./cli/tui/worker.js", import.meta.url)                   // file missing → not an import edge
  if (await Filesystem.exists(fileURLToPath(dist))) return dist
  return new URL("../tui/worker.ts", import.meta.url)                            // the only compiled entry
}

That leaves one compiled candidate. Codegen then takes the len() == 1 arm, and a build that did set OPENCODE_WORKER_PATH to some other worker would silently run ../tui/worker.ts instead — a wrong-worker bug that is far worse than today's honest compile-time refusal.

Note this is not symmetric with the missing-file case: resolve_candidates retains a missing candidate's spelling in paths, so that union still has len() > 1 and still reaches lower_candidates. An opaque return has no spelling to retain, so set size alone cannot carry the fact.

So the fix needs an explicit signal. Either:

• add a partial: bool to Resolution::Set (or a third variant) and thread it through Expr::WorkerNew, changing the gate to paths.len() > 1 || partial; or
• have returns() record the opaque return as a reserved non-path spelling that resolve_candidates retains and lower_candidates filters out of targets (it already filters by dynamic_import_path_to_prefix membership), so the union naturally has len() > 1.

The first is explicit and harder to misread later; the second reuses the machinery that already exists for missing files. Either way the runtime behaviour should end up identical to the current missing-candidate case — construct the matching compiled worker, and throw "Worker filename did not match an existing compile-time-resolved worker entry" when the taken path is the opaque one.

I am not sending a patch for this: the safe version touches the HIR→codegen contract, and I would rather hand over the verified analysis than a change that trades a loud failure for a silent one.

[proggeramlug]

Correction: this does NOT affect OpenCode. I was wrong about that.

The issue title and the "Summary" claim that OpenCode's TUI worker is never compiled. That is false, and I want it corrected before anyone prioritises this on OpenCode's behalf.

The real OpenCode build resolves the worker fine. From an untruncated compile log of opencode@1.18.30 (perry compile src/index.ts --platform bun, perry v0.5.1579 + #10356):

  Worker entry: /…/opencode/packages/opencode/src/cli/tui/worker.ts
  Warning: worker_threads Worker in module cli/cmd/tui.ts: skipping candidate "./cli/tui/worker.js": file not found

Both lines are exactly the correct behaviour: the missing candidate is skipped, the real entry is compiled. strings on the resulting binary confirms the worker module's content is present. So the typeof OPENCODE_WORKER_PATH guard does not poison the union in the real program, and the TUI's blank screen has some other cause, which I am still chasing.

Why my fixture said otherwise. My reproducer stubbed the Filesystem.exists probe as a module-local const holding an async arrow that does a dynamic import("node:fs/promises"):

const Filesystem = { exists: async (p: string) => { try { const fs = await import("node:fs/promises"); await fs.stat(p); return true } catch { return false } } }

OpenCode's real Filesystem.exists is an ordinary imported binding. That difference is inside the variable under test — returns() walks Stmt::Let and condition expressions — so my stub changed the very thing I was measuring. The fixture's failure is real for the fixture; it is not OpenCode's failure.

What I believe still stands, on the fixture evidence only:

• new Worker(new URL(…, import.meta.url).pathname) and .href are refused where the URL object form is accepted. That matrix was measured on minimal fixtures with no stubbing and I have no reason to doubt it.
• returns() aborting the whole union on one unresolvable return is visible in the code (self.resolve(value, depth + 1)?) regardless of which fixture triggers it, and the single-target hazard I documented in the previous comment is real — dyn_extern_i18n.rs:519 only reaches lower_candidates when paths.len() > 1.

So: still a genuine sharp edge, but no known real-world repro, and the priority should drop accordingly. Retitling would be reasonable — something like "Worker path helper: one opaque return discards the whole candidate union" without the OpenCode clause.

Apologies for the noise. The lesson is the standard one and I walked into it anyway: a proxy that differs from the original inside the variable under test can falsify a correct hypothesis just as easily as it can manufacture a false one.