`createHostImporter`'s undeclared fallback resolves from `@objectstack/types`, not from the calling package — its documented contract says otherwise

[os-elon]

Filed unassigned from the domain:cli lane while implementing #10908. Recording only — out of scope there, and it is a contract defect in packages/types, not in the CLI.

The claim

packages/types/src/node.ts, in createHostImporter's docblock (step 3):

Undeclared falls back to the importing package's own resolution, which is what keeps every framework-owned load working (serve's plugin-auth / service-i18n path, bootStack's service plugins).

What it actually does

The fallback is a bare import() written inside packages/types/src/node.ts. ESM resolves a bare specifier by walking up node_modules from the module that contains the call, so the fallback resolves from @objectstack/types, not from whichever package called the importer. Under a pnpm-isolated layout @objectstack/types can see only its own dependencies (@objectstack/spec).

Measured on main (worktree at eee2b65018), from a temp app root whose package.json declares nothing:

 via host importer bare import() from packages/cli
@objectstack/plugin-auth MODULE_NOT_FOUND OK
@objectstack/plugin-audit MODULE_NOT_FOUND OK
chalk MODULE_NOT_FOUND OK
@objectstack/spec OK —

@objectstack/spec is the one that resolves, and it is the only dependency packages/types declares. That is the whole pattern.

Why it matters

1. The docblock is load-bearing and wrong. It is what a reader consults before routing a load through the importer, and it says the undeclared case keeps resolving as it did. It does not; it re-bases to @objectstack/types.
2. It is layout-dependent, in the direction this whole line of work exists to catch. Under a hoisted npm/yarn layout the fallback usually does find the caller's dependencies, because they are flattened into one node_modules. Under pnpm isolation it does not. So "undeclared falls back" is green in some installs and absent in others — the same shape as cloud#1013 and cli: serve's dynamic cluster-driver import cannot resolve app-declared @objectstack/service-cluster* — EE multi-node OS_CLUSTER_DRIVER=redis dies at boot #10645, one level up.
3. It is a live trap for the remaining cards on this file. Two serve.ts comments claim the capability loop loads "host copy first", but it bare-imports — the CLI's copy always wins #10909 proposes host-anchoring the capability loop, whose providers are all CLI-declared (that is the standing justification in UNRESOLVABLE_BARE_IMPORTS). Swapping import(spec.pkg) for importFromHost(spec.pkg) there would make every one of them undeclared-by-the-app and hand them to this fallback. On a pnpm-isolated install that turns a working capability into a missing one.

#10908 sidestepped it rather than fixing it: Serve.importConfigPlugin consults the declaration itself and keeps the CLI's own import() for the undeclared case, so no app loses a plugin it does not declare but the CLI ships. That is a local workaround for one call site; every other caller of createHostImporter still inherits the claim above.

Options

• A. Fix the text. Document that the fallback resolves from @objectstack/types and that callers needing their own resolution must check isDeclaredByHost and import themselves. Cheapest; leaves each caller to re-derive the workaround serve.ts loads an app's own plugins: [...] config entries with a bare import(), so a plugin package the APP declares resolves from the CLI #10908 wrote.
• B. Fix the mechanism. Have createHostImporter take the caller's resolution base (e.g. an import.meta.url / a parentURL) and use it for the fallback, so the docblock becomes true for everyone. Larger blast radius — serve, bootStack, @objectstack/verify, cloud's loader — but it closes the class rather than documenting it.

Recommend B with A as the immediate stopgap, because the current text will keep producing exactly the reasoning error that #10908 caught only by measuring. Wants a maintainer decision either way.

Not a duplicate

• createHostRequire 认 NODE_PATH，于是 #4699 立下的「host app 必须自己声明」在 pnpm 工作区里根本没被强制 #4719 is whether a package may load (the declaration gate). This is where the fallback resolves from once the gate has said "undeclared".
• [finding] serve.ts's host-anchored importer is a mid-function const, so any app-declared optional package loaded ABOVE it silently falls back to CLI-anchored resolution — this has now shipped twice #10769 / serve.ts loads an app's own plugins: [...] config entries with a bare import(), so a plugin package the APP declares resolves from the CLI #10908 host-anchor specific call sites in serve.ts. This is the shared helper's own contract.

[huangyiirene]

Concentration-round first-touch: promoted finding → pm:queue, Bug, domain:cli (lands in packages/types, this lane's package).

Graded a Bug and queued rather than escalated: the docblock is the declared contract ("falls back to the importing package's own resolution") and the implementation measurably does something else — restoring an invariant is a named non-escalation class, and option B (fix the mechanism) is the declared=enforced direction. Route: thread the caller's resolution base (parentURL / import.meta.url) into createHostImporter so the documented sentence becomes true for every caller; A's doc rewrite then never happens (documenting the broken behaviour is the consumer-tolerance shape this repo refuses). Conditions: (1) blast radius measured first — every caller (serve, bootStack, @objectstack/verify; cloud's loader is out of this session's reach, name it in the PR as unverified) re-read against the new base; a caller measurably relying on the @objectstack/types-based fallback would be a genuine fork — stop and report, don't pick; (2) the #10908 local workaround in Serve.importConfigPlugin gets re-read once B lands (it may become redundant — remove only with its pin's agreement); (3) regression pin = the card's own 4-row matrix as a test. Size M. ⚠️ #10909 must not land its host-anchoring before this — the card documents that trap; cli seat sequences.

---

Generated by Claude Code