fix(types): find an aliased install through the host importer's ESM-only fallback

[os-trump]

Fixes #14278

The defect

createHostImporter's #14041 fallback finder verifies the one directory it consults — hostRoot/node_modules/KEY — by matching that directory's manifest name against the declared package name. An aliased install fails that check by construction:

{ "dependencies": { "foo": "npm:bar@1" } }

hostRoot/node_modules/foo holds a manifest named bar, not foo. The check rejected it, the fallback answered absent, and an ESM-only aliased package therefore kept the pre-#14041 INSTALL wording — the confidently-wrong remedy that sends an operator to run pnpm install against an install that is already correct, on a declaration shape packageNameFromSpecifier's own documentation blesses.

The fix: parse the DECLARATION, never widen the check

⛔ The manifest-name check is not loosened. It is what keeps the fallback strictly tighter than the CJS resolution it backs up — the property #14041 rests on and #4719 guards — and widening it would trade a confidently-wrong remedy for a wrong LOAD, the worse direction.

What moves is the expectation, and it is still authored by the host and still read out of the host's own package.json. A new declaredManifestName(declaration) reads the declaration value for the name it promises:

declaration value	expected manifest name	why
^1.0.0, *, a tag	the key	no alias declared
npm:bar@1, npm:@acme/x@^2, npm:bar	bar / @acme/x / bar	npm: values are always name[@range]
workspace:bar@*	bar	pnpm's aliased workspace form
workspace:*, workspace:^1.2.3	the key	a RANGE, no name in it
link:../bar, file:../bar.tgz, a git URL	the key	they name a LOCATION, not a package
anything not parsing as a bare package name	the key	no expectation to move to ⇒ today's refusal is kept

The last three rows are the conservative half: where no name is derivable, the pre-#14278 refusal stands rather than being guessed at. packageNameFromSpecifier is the single authority on what counts as a package name, so the parse cannot drift from the declaration gate's own idea of one.

declaredCjsResolveFallback and hostInstalledPackageDir now take the HostDeclaration itself instead of a (packageName, hostRoot) pair, so the key, the root and the expected name cannot be passed out of step with each other.

Proof — red-first, and which arm fired

The tests were written and run before the implementation, on unmodified packages/types/src/node.ts:

Tests  7 failed | 51 passed (58)

Six of the seven were the new alias-RESCUE arms, and only those:

× THE CARD: an aliased ESM-only package is rescued, not reported as an INSTALL problem
× THE CARD (wording): an aliased install with no loadable entry gets the PACKAGE message
× a SCOPED key aliasing an unscoped package is rescued too
× an aliased SUBPATH resolves against the aliased package
× an alias with no version range names its target just the same
× a `workspace:` ALIAS names its target; a plain `workspace:` range does not

with the red text on the card's own case being exactly the defect:

Cannot find module 'aliased-esm': the host app DECLARES it
(dependencies: "npm:@fixture/alias-esm-only@1") but it could not be resolved.
  This is an INSTALL problem, not a declaration problem …

The seventh red was not this change: the DEFAULT fallback is this package's own resolution — @objectstack/spec and nothing else failed with Failed to resolve entry for package "@objectstack/spec" — an unbuilt dependency closure in a fresh worktree. It goes green once pnpm --filter '@objectstack/types^...' build has run, and is green in the run below.

⭐ Every tightness control stayed green in the red-first run — the failure the card must not produce (an aliased red that also reddens a non-aliased control) did not occur:

• TIGHTNESS: a NON-aliased declaration is unchanged — the key is still the expected name
• TIGHTNESS: an alias naming one package does not license a directory holding another
• TIGHTNESS: an alias target carrying a SUBPATH is not a package name, and is refused
• TIGHTNESS: an alias does not reopen the hostRoot boundary
• BOUNDARY: a link: target whose manifest names something else keeps the refusal
• and the pre-existing the fallback trusts only a directory whose manifest NAMES the declared package, plus both TIGHTNESS cases of the createHostImporter's declared leg cannot load an ESM-only host package at all, and misreports it as a broken install #14041 block (NODE_PATH, above-hostRoot) and both traversal-span cases.

After the fix, with the dependency closure built:

Test Files  1 passed (1)
      Tests  58 passed (58)

Scope

Expected file face, and nothing wider: packages/types/src/node.ts plus its test, plus the changeset.

⚠️ #14270 is untouched. Its surface is the wording of the declared-no-loadable-entry remedy formatters; this diff touches zero lines of noLoadableEntryMessage, unresolvableMessage and undeclaredMessage (git diff origin/main -- packages/types/src/node.ts | grep -c 'noLoadableEntryMessage\|unresolvableMessage\|undeclaredMessage' ⇒ 0). The aliased cases here assert those messages, they do not edit them.

Changeset — the fork, measured: packages/types' own files field is ["dist", "README.md", "CHANGELOG.md"], so src/node.ts ships (as dist/node.*) and the error kind an aliased install answers with is published behaviour. ⇒ a changeset is owed, and .changeset/aliased-install-host-importer.md is it (patch).

Out-of-scope findings, filed unassigned, not fixed here

• packageRootOf matches the declaration KEY, so an aliased dual-published package silently loads its require build on the succeeding (#13330) path #15044 — packageRootOf matches the declaration KEY too, so an aliased dual-published package silently loads its require build on the succeeding (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) path. Not folded in: that path SUCCEEDS today, so correcting it changes a working load's selected entry — a decision, not a mechanical correction, and outside this card's ruled route.
• A link: / file: install whose manifest name differs from the key still keeps the wrong INSTALL wording — the location-carrying sub-case #14278 could not reach #15045 — a link: / file: / git-URL install whose manifest name differs from the key keeps the INSTALL wording. The ruled route cannot reach it (those specifiers carry no package name); the boundary is pinned by a test in this PR rather than left unnoticed.

Verification

Run at final HEAD 7bf2ed4080:

• pnpm --filter '@objectstack/types^...' build — dependency closure (34/34 declaration files emitted for @objectstack/spec)
• pnpm --filter @objectstack/types exec vitest run --maxWorkers=2 src/node.test.ts — 58/58
• pnpm --filter @objectstack/types typecheck — tsc --noEmit, clean. tsc --listFilesOnly confirms the program really contains src/node.ts and src/node.test.ts (1 hit each), so the green covers the edited test file rather than merely the sources.
• Gate union derived by node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack at this HEAD (never a hand-written list): 40 families, harvested with --commands so no spelling or section is dropped. All 40 were run locally, each exit code captured into a file before any pipe: 36 exit 0, 4 exit 3.

NOT MEASURED — the 4 exit-3s (PREREQUISITE NOT MET; neither a pass nor a red): check:dual-build-cjs-loads and check:type-check-debt both need the whole workspace built (85 packages have no dist/ in this worktree), scripts/check-test-completeness.mjs exited before parsing a single summary line, and scripts/pm/check-half-states.mjs needs the GitHub API census this seat cannot reach. All four are CI's to run; none of them is reported here as green.

ESLint — the full repo run, not a narrowing: pnpm lint (eslint . --no-inline-config, the whole tree, the same command CI's Lint & Repo Gates job runs) completed here with exit code 0 and no findings, so nothing about the lint result is scoped down or deferred.

---

🤖 Generated with Claude Code

https://claude.ai/code/session_016yfqQh2dBgPAymYd7xipza

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

5 anchor(s) derived from 1 changed package(s); no hand-written page names any of them, so this run has nothing to list — not a clean bill of health. This check sees only pages that NAME a derived anchor: one that documents this change in prose, or enumerates it in an authoring dialect, names none and stays invisible to it on every run.

What this run could not see

• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 1 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json d5b330dc6916b7ca56f4c751cc654c7aaf64bfe2 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 05a07e1ea1fae8bd8a6cfd7856f527decd4a81d9 — the merge of head 7bf2ed4080f03ca0d02456bdb86b80f409613122 into base d5b330dc6916b7ca56f4c751cc654c7aaf64bfe2, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 05a07e1ea1fae8bd8a6cfd7856f527decd4a81d9 && git checkout 05a07e1ea1fae8bd8a6cfd7856f527decd4a81d9
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin d5b330dc6916b7ca56f4c751cc654c7aaf64bfe2 7bf2ed4080f03ca0d02456bdb86b80f409613122 && git checkout -B drift-repro d5b330dc6916b7ca56f4c751cc654c7aaf64bfe2 && git merge --no-ff 7bf2ed4080f03ca0d02456bdb86b80f409613122

node scripts/docs-audit/affected-docs.mjs --json d5b330dc6916b7ca56f4c751cc654c7aaf64bfe2

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.