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

[os-justin]

Claim: PM loop round 64
Session: session_015YPiiDdw96RGS25WLctCQP
Branch: claude/issue-14041-esm-only-host-package
Worktree: objectstack-issue-14041
Domain: domain:cli
File surface: packages/types/src/node.ts (createHostImporter's declared leg) plus a new ESM-only fixture and its tests. (stop on breach; explain in the report)
Container & model: M, mode:subagent, model: fable
Clause-②: yes — declared conservatively. The change makes a package that cannot load today load; whichever way the boundary test is read, the conservative direction routes to review. ⚠️ Re-declare from your actual diff.
Serial constraints cleared: ⭐ The #13330 serial is RELEASED — see below, verified rather than inherited. No open PR touches packages/types/src/node.ts. Sibling dispatch this round: #13906 (packages/rest/src/rest-server.ts) — different package, disjoint, and it pins nothing on this surface.

Comments re-read before claiming: one (triage, 03:24:36Z). ⛔ No claim from another session.

⭐ The serial triage imposed is discharged — checked on the tree, ⛔ not assumed

Triage ordered this card behind #13330 because both edit packages/types/src/node.ts and #13330 was p1 and in flight. Status now: #13330 is CLOSED (completed, 05:51:32Z) by merged PR #14042 (bfe13c86ab). Ruling ① releases on the merge ⇒ the file is free.

⚠️ And #14042's title is close enough to this card's subject to be dangerous — "resolve host-declared packages through the import condition". So I re-derived this card's premise on origin/main rather than trusting the card's claim that #13330 "leaves the FINDER alone". It holds:

• resolved = hostRequire.resolve(pkg) is still the finder, at :715;
• its throw is still classified declared-unresolvable, at :718;
• the "This is an INSTALL problem, not a declaration problem" wording is still at :375;
• the file's own doc comment still states "hostRequire.resolve(pkg) is a CommonJS resolution" at :388.

⇒ #14042 re-decided the condition for a package the CJS resolver had already located; it did not touch the finder. ⛔ Locate by symbol anyway — those line numbers are from my read, and the file just moved.

⭐ A measured trap now documented in the file you are editing — read it before choosing a finder

node.ts records, from its own measurement:

import.meta.resolve's parent argument is SILENTLY IGNORED without --experimental-import-meta-resolve

⇒ ⛔ Do not reach for import.meta.resolve as the "obvious" ESM finder. It will resolve against the wrong parent and answer confidently — the exact failure class this card is about. The card's own suggested shape is a node_modules walk from hostRoot, and that is the shape to implement.

⛔ The load-bearing constraint: the new finder must be STRICTLY TIGHTER

Triage's decisive point, and it is why this card is dispatchable at all:

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)

⛔ Do not implement any finder that is looser than CJS resolution. Specifically ⛔ no bare require, ⛔ no NODE_PATH honouring, ⛔ no walking above hostRoot. #4719 is a declaration gate and a looser finder reopens a security hole. This constraint outranks making the fixture pass.

The fallback fires only when hostRequire.resolve throws — strictly additive, because that path is a hard failure today, so ⛔ no currently-succeeding case may change behaviour. Pin that.

⭐ The way this card is most likely to be done wrong

No workspace package is affected today — every dual build here publishes both conditions (check:dual-build-cjs-loads: 102 require entry points across 66 packages, all loading).

⇒ No existing gate or test in this repo can detect this defect, because the repo contains no ESM-only package. ⛔ Green existing tests prove nothing here. You must build a new ESM-only fixture (the card gives its shape: {"type":"module","exports":{".":{"import":"./dist/index.js"}}} with a host declaring it) and drive the real importer against it. A fix "verified" by the existing suite is unverified.

Split the failure kind, do not just rescue the load

The two cases are byte-identical to the classifier today:

1. declared + install genuinely broken → the existing INSTALL message is right;
2. declared + installed fine + package publishes no CommonJS entry → the INSTALL message is wrong, and ⛔ nothing it tells the operator to do will help.

⇒ Rescuing (2) is half the card. The other half is that (2) must get a message about the package's own shape, so an operator is never again sent to run pnpm install against a correct install. ⛔ Do not collapse the two kinds into one friendlier message — that trades a wrong verdict for a vague one.

Report

Open a draft PR with Fixes #14041; ⛔ do not flip ready, arm, or merge. Post the terminal JSON report as a comment on this card first.

---

Generated by Claude Code