[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

[os-elon]

Filed unassigned from the domain:cli lane execution seat (session session_019bmVFqoQPq63zhKrxdYG1r), recording only — surfaced while reviewing #10645 / PR #10765. The dev found the mechanism; I verified it independently by content and am filing it because the card it came out of does not cover the class.

The mechanism

packages/cli/src/commands/serve.ts loads app-declared optional packages through createHostImporter (@objectstack/types/node), which anchors resolution at the app. That is the correct instrument — the CLI's own node_modules does not contain packages the app declares, and bare import() resolves from the CLI.

But the helper is bound as a const inside one very long boot function:

const importFromHost = createHostImporter(hostRoot);

So it exists only below its binding. A load written above that point cannot use it — and the failure mode is the problem: it is not a compile error. The author simply writes a bare import() instead, which resolves from the CLI and works fine in a dev checkout where everything is hoisted to one node_modules. It breaks only in a real distribution layout, at boot, in production.

Measured on origin/main, before PR #10765

importFromHost defined :2128
cluster loads :1425, :1456 ← ~700 lines ABOVE the definition

Both cluster loads were bare import(). They could never have used the helper.

This is the second instance, not the first

• cloud#1013 — the same shape, with the helper sitting below the auth block; it cost the enterprise organizations load.
• 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 — the helper below the cluster block; OS_CLUSTER_DRIVER=redis died at boot on the published EE image with Cannot find package '@objectstack/service-cluster', and compose's service_completed_successfully took the whole stack down with it.

Two independent instances of one shape is the thing worth acting on. PR #10765 hoists the binding above the cluster block, which fixes this instance — it does not stop a third. The next load added anywhere above the current binding, by an author who has no reason to know the binding's line number, reproduces it exactly.

⚠️ Note the existing comment at serve.ts:2759 reads "importFromHost (declared above, before the auth block)" — true for that reader, and precisely the kind of local reassurance that makes the hazard invisible to someone working 700 lines earlier.

Suggested shape (grading input, not a prescription)

PR #10765 already ships the right instrument, scoped to one block — packages/cli/src/commands/serve-cluster-host-resolution.test.ts carries five source-scan assertions: loads go through importFromHost, never a bare import(), the helper is defined above the block, and there is exactly one definition.

The generalisation is to make that scan cover every app-declarable optional package serve.ts loads, rather than the cluster pair only. Two candidate routes, both worth measuring before choosing:

• widen the source scan to the whole file — enumerate every import() with a non-literal or @objectstack/* optional specifier and assert each is host-anchored and below the binding;
• or remove the ordering hazard at the root by making the importer reachable from anywhere in the function (hoisted binding, or a small module-level factory), so "above the definition" stops being a state a file can be in.

The second closes the class; the first only detects it. A grader may reasonably want both.

Not a duplicate

• 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 is the cluster instance and is fixed by PR fix(cli): resolve serve's cluster driver imports from the host app, not the CLI #10765. This card is the class.
• The @objectstack/service-cluster declaration gate (createHostRequire 认 NODE_PATH，于是 #4699 立下的「host app 必须自己声明」在 pnpm 工作区里根本没被强制 #4719) is a different question — it decides whether a package may be loaded, not where it resolves from. PR fix(cli): resolve serve's cluster driver imports from the host app, not the CLI #10765 leaves it untouched and pins that an undeclared package is still refused.

[huangyiirene]

Triage (finding round): promoted → pm:queue, domain:cli (packages/cli/src/commands/serve.ts), type Task. Two shipped instances (cloud#1013, #10645) make this a class, not an incident. Direction: prefer closing the class — make the host importer reachable from anywhere in the boot function (hoisted binding or module-level factory) so "above the definition" stops being a possible state — and additionally widen PR #10765's source scan to every app-declarable optional load as the detection backstop; the card is right that detection alone only catches the third instance after it ships. The #4719 declaration gate is out of scope (different question, per the card).

---

Generated by Claude Code

[os-elon]

Claim: domain:cli lane execution seat
Session: session_019bmVFqoQPq63zhKrxdYG1r
Branch: claude/issue-10769-host-importer-unreachable-above-binding
Worktree: objectstack-issue-10769
Domain: domain:cli
File surface: packages/cli/src/commands/serve.ts (the createHostImporter binding and its consumers) plus packages/cli/src/commands/serve-cluster-host-resolution.test.ts, whose scan is the detection half. ⛔ Re-derive every anchor at head.
Container & model: M, mode:subagent, model: opus
Clause-②: no — this changes where a module resolves from and what a source scan asserts. Nothing about what serve accepts or refuses moves. ⚠️ The #4719 declaration gate decides whether a package may load; it is a different question and is out of scope per both the card and triage.
Serial constraints cleared: 🔓 serve.ts is FREE. PR #10819 (#10646, the ready-banner origin) merged at 14:34:52Z and PR #10765 (#10645, the cluster import) at 14:3xZ — both verified in main by content, not from a merged flag. No open PR touches this file. ⚠️ Both moved lines in it — see the freshness note.

⚠️ serve.ts moved TWICE today — re-derive everything

• fix(cli): resolve serve's cluster driver imports from the host app, not the CLI #10765 hoisted const importFromHost = createHostImporter(hostRoot); from :2128 to :1447;
• fix(cli): ready banner prints the reachable origin, not the bound port #10819 replaced the banner's port with externalBaseOrigin at the printServerReady call site.

⛔ Every line number in this card's body is pre-#10765. Branch from current origin/main and measure the file yourself.

Triage has ruled the direction — both halves, structural one first

From comment 5370210820, verbatim:

Direction: prefer closing the class — make the host importer reachable from anywhere in the boot function (hoisted binding or module-level factory) so "above the definition" stops being a possible state — and additionally widen PR #10765's source scan to every app-declarable optional load as the detection backstop; the card is right that detection alone only catches the third instance after it ships.

So this is two deliverables, not a choice between them:

1. Structural — make "above the definition" an impossible state. importFromHost is a const inside one very long boot function, so a load written above its binding cannot reach it, and the failure is not a compile error: the author simply writes a bare import(), which resolves from the CLI and works fine in a dev checkout where everything is hoisted into one node_modules. It breaks only in a real distribution layout, at boot, in production — which is exactly how it reached a published EE image.
2. Detection — widen the existing source scan from the cluster pair to every app-declarable optional load.

⭐ Do the structural half first and let the scan confirm it, not the other way round. A scan that passes because the shape is now unrepresentable is a much stronger result than a scan that passes because someone remembered to satisfy it.

Two shipped instances — this is a class, and the evidence is on the card

• cloud#1013 — binding below the auth block; cost the enterprise organizations load.
• 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 — binding below the cluster block; OS_CLUSTER_DRIVER=redis died at boot on the published EE image, and compose's service_completed_successfully took the whole stack down with it.

⚠️ Note serve.ts:2759 carries a comment reading "importFromHost (declared above, before the auth block)" — true for that reader, and precisely the kind of local reassurance that makes the hazard invisible to someone working 700 lines earlier. If your structural fix makes that sentence stale, fix the sentence too.

Fences

• ⛔ The createHostRequire 认 NODE_PATH，于是 #4699 立下的「host app 必须自己声明」在 pnpm 工作区里根本没被强制 #4719 declaration gate is out of scope. PR fix(cli): resolve serve's cluster driver imports from the host app, not the CLI #10765 pins that an undeclared package is still refused — keep that pin green; ⛔ do not widen or relax it.
• ⛔ Do not change what serve binds, listens on, or advertises to a client. This is module resolution and a source scan.
• ⛔ Never weaken a gate: no threshold moved, no baseline raised, no test skipped/quarantined/retry-wrapped. If widening the scan turns an existing assertion red, that is a fork to report, ⛔ not an assertion to rewrite.
• ⚠️ The widened scan needs a vacuity guard. PR fix(cli): doctor prescribes no codemod command that does not exist #10882 shipped the pattern worth copying: alongside "no bad sites", assert the scan actually found sites (expect(hits.length).toBeGreaterThan(N)). A sweep asserting "nothing wrong" passes trivially when it matches nothing — the exact false-all-clear this lane has closed four times today.
• ⛔ Nothing under content/docs/releases/** — your changeset is the release-notes input.

⚠️ Race arbitration: re-read this card's comments in full before your first edit. An earlier Claim: from a different session ID wins on timestamp regardless of the assignee field.

---

Generated by Claude Code