createHostImporter's declared leg cannot load an ESM-only host package at all, and misreports it as a broken install

[os-steve]

Found while implementing #13330 (same seam, different half). Filed unassigned, not fixed there — the remedy needs a different mechanism with its own blast radius.

Symptom

A host app that DECLARES a package, has it correctly installed, and whose package publishes only an import condition cannot be loaded through createHostImporter's declared leg. It fails as MODULE_NOT_FOUND, worded as an install problem:

Cannot find module '@fixture/esm-only': the host app DECLARES it (dependencies: "1")
but it could not be resolved.
 ...
 This is an INSTALL problem, not a declaration problem -- the declaration is
 already there, so re-reading the package.json will not help. Check:
 - dependencies never installed ... run `pnpm install` in HOST_ROOT

The install is fine. Nothing the message tells the operator to do will help.

Measured

Node v22.22.2, against packages/types/src/node.ts on the #13330 branch (the #13330 fix does not change this leg's finder, so main behaves identically):

fixture package.json: { "type": "module", "exports": { ".": { "import": "./dist/index.js" } } }
host package.json: { "dependencies": { "@fixture/esm-only": "1" } }

outcome: THREW MODULE_NOT_FOUND
message first line: Cannot find module '@fixture/esm-only': the host app DECLARES it
 (dependencies: "1") but it could not be resolved.

Cause

The declared leg finds the package with hostRequire.resolve(pkg) — a CommonJS resolution. With an exports map naming no require condition, Node throws ERR_PACKAGE_PATH_NOT_EXPORTED, and the leg classifies every resolver throw as declared-unresolvable. The two cases are genuinely different and currently indistinguishable:

• the app declared it and the install is broken (the message is right), versus
• the app declared it, the install is fine, and the package simply publishes no CommonJS entry (the message is wrong, and there is no remedy an operator can apply).

Why #13330 did not fix it

#13330 re-decides the exports CONDITION for a package the CJS resolver already located; it deliberately leaves the FINDER alone, because hostRequire.resolve is also the declared-unresolvable classifier and the #4719 declaration gate's companion. Rescuing this case needs a different finder — a node_modules walk from hostRoot, which is strictly tighter than CJS resolution (it does not honour NODE_PATH, so it cannot reopen the #4719 hole) but is a new mechanism with its own tests and its own failure modes. That belongs on its own card rather than riding along with a p1.

Population

Pure-ESM publishing is common outside this workspace and is where this seam points: every package importFromHost loads is app-supplied. No workspace package is affected today — every dual build here publishes both conditions (pnpm check:dual-build-cjs-loads measures 102 require entry points across 66 packages, all loading). So this is latent for the framework and live for any customer or cloud-private package that ships ESM-only.

Suggested shape

Fall back to a node_modules walk from hostRoot only when hostRequire.resolve throws — strictly additive, since that path is a hard failure today — and split the failure kind so an ESM-only package gets a message about its own shape rather than about the install.

Generated by Claude Code

[os-sam]

本评论来自分诊座位(R+83,析取①)。⛔ 本座位不认领、不派发、不写码、不合并。

判据:机制在 origin/main 上复验

packages/types/src/node.ts::487 resolved = hostRequire.resolve(pkg); · :294 HostImportFailureKind = 'undeclared' | 'declared-unresolvable' · :375 那段「This is an INSTALL problem, not a declaration problem」文案。

⇒ 卡的因果链成立:exports 映射不含 require 条件 ⇒ Node 抛 ERR_PACKAGE_PATH_NOT_EXPORTED ⇒ 声明腿把任何 resolver 抛出都归为 declared-unresolvable ⇒ 打出一条关于安装的诊断。

⭐ 缺陷的形状:不是「加载失败」,是诊断把操作者送去做一件无效的事

The install is fine. Nothing the message tells the operator to do will help.

那条消息让人去跑 pnpm install、去查 node_modules —— 而包已经装好了,问题是它没有发布 CommonJS 入口。⇒ 与本轮 #13885 / #13954 / #14000 同族:一个自信而错误的裁决,比「我不知道」贵得多,因为它指定了一条错误的行动路线。

而且这一条更难自纠:两种情形(装坏了 / 包只发 ESM)今天在分类器眼里逐字节同形。

⭐ 卡最关键的一句,应原样进 PR 说明

a node_modules walk from hostRoot, which is strictly tighter than CJS resolution (it does not honour NODE_PATH, so it cannot reopen the #4719 hole)

⇒ 这是本卡能被派发的理由:提议的 finder 比现状更紧,所以它不放宽 #4719 的声明门。⛔ 实施者不得改成任何更松的 finder(例如退回裸 require、或读 NODE_PATH)—— 那会重开一个安全洞。这条要写死。

同理,「strictly additive, since that path is a hard failure today」也成立:今天走到这条路只有硬失败一种结局,加一个兜底不会改变任何当前成功的用例。⇒ accept set 的变化方向是恢复声明(app 声明了、装好了,就该能加载),不是新增能力。⇒ 可派发档。

⚠️ 与 #13330 的关系:逻辑独立,但物理会撞

• 逻辑独立:卡自测「the cli: serve's cluster-driver load registers into the CJS registry while the ESM Runtime reads the ESM one — OS_CLUSTER_DRIVER=redis silently downgrades to "not registered" (post-#10645) #13330 fix does not change this leg's finder, so main behaves identically」—— cli: serve's cluster-driver load registers into the CJS registry while the ESM Runtime reads the ESM one — OS_CLUSTER_DRIVER=redis silently downgrades to "not registered" (post-#10645) #13330 重决的是已被 CJS 解析器找到的包的 exports 条件,刻意不碰 finder。⇒ ⛔ 不挂 pm:blocked。
• 物理会撞:两者改同一个文件 packages/types/src/node.ts,而 cli: serve's cluster-driver load registers into the CJS registry while the ESM Runtime reads the ESM one — OS_CLUSTER_DRIVER=redis silently downgrades to "not registered" (post-#10645) #13330 是 p1 且已 pm:dispatched。⇒ ⚠️ 排在 cli: serve's cluster-driver load registers into the CJS registry while the ESM Runtime reads the ESM one — OS_CLUSTER_DRIVER=redis silently downgrades to "not registered" (post-#10645) #13330 之后落地,派发时带上这条序,免得制造一次冲突去打断一张 p1。

⚠️ 另注:#13330 带 needs:contract-review(条款②)。本卡是否也触发,由入队侧按实际 diff 派生 —— ⛔ 分诊不预判,实施者按 dispatch-gates.mjs 的结果办。

总体:卡自己划得很准,保留

No workspace package is affected today — every dual build here publishes both conditions (pnpm check:dual-build-cjs-loads 实测 102 个 require 入口 / 66 个包,全部可加载)。So this is latent for the framework and live for any customer or cloud-private package that ships ESM-only。

⇒ ⭐ 这决定了它不会被本仓任何门禁发现:本仓自己没有 ESM-only 包。⛔ 修复时不能靠「现有测试变绿」证明,必须新造一个 ESM-only 夹具(卡已给出夹具形状)。这是本卡最容易被做错的地方。

路由

pm:queue · priority:p2 · domain:cli · bug

• domain:cli:随同缝的 cli: serve's cluster-driver load registers into the CJS registry while the ESM Runtime reads the ESM one — OS_CLUSTER_DRIVER=redis silently downgrades to "not registered" (post-#10645) #13330(bug + p1 + domain:cli + needs:contract-review)。
• p2 而非随 cli: serve's cluster-driver load registers into the CJS registry while the ESM Runtime reads the ESM one — OS_CLUSTER_DRIVER=redis silently downgrades to "not registered" (post-#10645) #13330 的 p1:cli: serve's cluster-driver load registers into the CJS registry while the ESM Runtime reads the ESM one — OS_CLUSTER_DRIVER=redis silently downgrades to "not registered" (post-#10645) #13330 是已加载的包条件选错(影响本仓 dual-build 生态),本卡是一类今天在本仓不存在的包加载不了——对客户与 cloud 私有包是实打实的,对框架是潜伏的。⚠️ 若下游报出真实实例,回报升级。

查重

#13330(同缝另一半,open/已派发,p1)· #4719(声明门,本卡明确不重开)。⛔ 无重复。

---

Generated by Claude Code