CLI dynamic `import()` of optional service packages resolves from the CLI's own location and cannot cross `link:` boundaries — `@objectstack/service-cluster` unresolvable in the EE image, same class as the AI Studio miss

[os-zhuang]

Filed by the triage seat as the framework leg of objectstack-ai/cloud#1502 (measured on the released EE 4.1.0 image: OS_CLUSTER_DRIVER=redis ⇒ Cannot find package '@objectstack/service-cluster' imported from /repo/objectstack/packages/cli/dist/commands/serve.js ⇒ migrate exits 1 ⇒ the whole stack cannot start).

Measured mechanism (from the cloud card)

• The image's /repo/objectstack/packages/cli/node_modules/@objectstack/ holds 48 packages, NOT service-cluster / service-cluster-redis.
• Those two are installed only under /repo/cloud/apps/objectos-ee/node_modules/@objectstack/ (the app's own package.json declares them).
• serve.js's dynamic import('@objectstack/service-cluster') resolves upward from the CLI's own location and cannot cross the link: boundary; the app side CAN load them (which is why the multi-node guard itself runs). Same defect class as the earlier "CLI dynamic-import auto-discovery cannot resolve cloud packages" (AI Studio) case.

Scope

Fix the resolution so an app-declared optional service package is loadable from the boot path: createRequire anchored at the app config directory (preferred — generalizes to every optional package), or declare the cluster packages as CLI optional deps (narrow). Implementer states the choice and why in the PR; pin with a fixture that loads an app-local-only package through the boot path.

Context note (does not change this card's scope)

The maintainer ruled cloud#1502 direction B (ADR-0010 DB-first; redis leaves the EE templates), so the REDIS route specifically is being de-recommended downstream — but the resolution defect is route-agnostic (any app-declared optional service hits it) and is worth fixing regardless. This card is the mechanism fix, not a redis endorsement.

Refs: objectstack-ai/cloud#1502 (measurement + ruling record) · the AI Studio dynamic-import sibling case.

[os-zhuang]

Claim: PM loop round 31

• Session: session_019siH5jDmk5hrayvfyojUqR (domain:cli lane execution seat, post [PM seat] domain:cli — 🟢 os-zhuang (session_019siH5jDmk5hrayvfyojUqR) · R31 · 落地 9 卡 / 8 PR · 入队 1 (#11378) · 在飞 5 · 待复审 1 · 决策箱 2 #6024)
• Branch: claude/issue-11185-app-anchored-optional-import
• Worktree: objectstack-issue-11185
• Domain: domain:cli
• File surface: packages/cli/src/commands/serve.ts (the importFromHost region, ~:223-290) and a new pin. Read-only over packages/types/src/node.ts (createHostImporter's own contract) (stop on breach; explain in the report)
• Container & model: M, mode:subagent, model: opus
• Clause-②: no — a resolution defect fix. It makes a load that currently throws succeed; it widens no public surface and changes no declared accept/reject behaviour. ⚠️ Re-derive on the actual diff: if the chosen route adds packages to packages/cli's own dependencies/optionalDependencies, that is a published-manifest change — stop and report before doing it.

fold-or-serial with #11157 — answered explicitly, ⛔ not defaulted

Both cards touch serve.ts's importFromHost, so the five gates are a must-answer. Verdict: SERIAL, #11185 first.

gate	verdict
① same defect form and same fix	❌ FAILS. Both concern the resolution base, but they anchor it in opposite directions: this card wants optional-service resolution anchored at the app (createRequire at the app config dir); #11157 wants the fallback to carry the CLI's own base. Not one fix in two places
② same package / area	⚠️ same file and same function ⇒ HARD SERIAL under ruling ① regardless of ①
③ every member graded	✅ #11185 bug, #11157 Task; neither in the decision box
④ independently checkable	⚠️ #11157 is measured harmless today — its verification is structural, not behavioural. Folded, it would hide behind this card's pin and get no independent check of its own
⑤ exclusion list	n/a — not folding

Order, and why this one leads: this is a Bug with a measured production outage (EE 4.1.0, OS_CLUSTER_DRIVER=redis ⇒ migrate exits 1 ⇒ the stack cannot start), and Bug outranks Task in the lane's selection order. More decisively, this card's fix may subsume or invalidate #11157's: if optional-service resolution is re-anchored at the app config directory, the fallbackImport question changes shape. #11157's own body applies that same logic internally — "Re-read it again with this change, not before."

⇒ #11157 goes into the hot-file serial queue behind this card, and its claimer must re-verify its premise on the merged ref, because this PR may absorb it.

Premise re-verified on origin/main at dispatch, ⛔ not taken from the card

reading	value
serve.ts:280	importer = createHostImporter(hostRoot); — no base passed (this is #11157's defect, still open)
serve.ts:230, :256-258	the file's own comments already document the EE @objectstack/service-cluster failure
serve.ts:474-490	the deliberate three-branch shape in importConfigPlugin, with its reasoning recorded

⚠️ #11268 landed in serve.ts about half an hour ago (the NODE_ENV production default, in run()). Different region from importFromHost, but re-derive every line number at your own head — do not trust the ones above.

⛔ Fences

• packages/cli/test/helpers/serve-process.ts and its 8 importers are HELD by e2e tests that spawn a real os serve under vitest inherit TEST=true, which makes better-auth silently skip origin/CSRF validation regardless of NODE_ENV #11267 (in flight, editing exactly that helper). ⛔ Read-only. If your pin wants runServe(), write a self-contained spawn instead — or stop and report. ⛔ Do not edit that helper.
• ⛔ Do not touch packages/types/src/node.ts. createHostImporter's contract is createHostImporter's undeclared fallback resolves from @objectstack/types, not from the calling package — its documented contract says otherwise #10943's and is out of scope; if the honest fix needs to change it, stop and report.
• ⛔ Do not fix serve.ts's importFromHost does not pass its own resolution base to createHostImporter — measured harmless today, open by construction #11157 here. If your change makes its two-line edit redundant, say so in the report — that is valuable and I will re-grade it — but do not implement it.

The card names two routes; state the choice and why

createRequire anchored at the app config directory (preferred — generalizes to every optional package) versus declaring the cluster packages as CLI optional deps (narrow). ⭐ The narrow route also has a manifest cost the card does not spell out: it makes the CLI declare packages it does not use, and it does not generalize to the next app-declared optional service — the same "fixed each instance, left the class open" shape #11157 and #10769 both record.

Anti-vacuity floor: pin with a fixture that loads an app-local-only package through the boot path, and show it failing on the pre-fix tree. A fixture whose package is resolvable from packages/cli proves nothing — the entire defect is about a package that is not.

Required of the report

gates / deviations / files_changed, the route chosen with the rejected one and why, and the reverse-verification quoted in both directions. ⛔ Do not restate the PR body. Re-derive gate families at your final head; re-run changeset gates after committing.

---

Generated by Claude Code

[claude]

{
 "issue": 11185,
 "status": "done",
 "branch": "claude/issue-11185-app-anchored-optional-import",
 "pr": "https://github.com/objectstack-ai/objectstack/pull/11349",
 "premise_still_valid": true,
 "premise_note": "Valid, but NOT for the trace the card quotes. The bare-import leg ('imported from .../packages/cli/dist/commands/serve.js') is already closed at origin/main by #10645 (53428b8c) and #10769 (3d7deb70) — re-measured: with CWD = the app, an app-local-only @objectstack/service-cluster loads fine today. The live residue is the RESOLUTION BASE: serve takes its config as an argument, so the app need not be the CWD, and every host-anchored load used process.cwd(). Booting by config path from elsewhere still dies at origin/main. That residue is exactly the route the card names as preferred ('createRequire anchored at the app config directory'), so the card is delivered rather than re-scoped.",
 "route_chosen": "createRequire anchored at the app CONFIG DIRECTORY. run() now resolves the config path and the app root in one call, anchorServedApp(), and every host-anchored load in serve.ts defaults to that root via servedAppRootOrCwd(): importFromHost's default parameter, Serve.importConfigPlugin's `hostRoot ?? ...`, and the boot body's `const hostRoot`. One call because the anchor must not be a statement a future author can write too late — the absolute config path every later line needs is produced by the same call that sets the root. Read as a FUNCTION at each use: a module-scope const would freeze the pre-boot process.cwd() into every call site. The config dir is adopted only when it holds a package.json, otherwise CWD is kept — readHostDeclaration reads a MANIFEST (#4719 — reachability is not the contract), so a manifest-less directory declares nothing and anchoring there could only turn a working boot into an `undeclared` refusal. No layout that resolves today resolves differently.",
 "route_rejected": "Declaring @objectstack/service-cluster* in packages/cli's own manifest. Three reasons, in ascending order of weight: (1) it makes the open-core CLI take a published dependency on packages it never imports — the coupling the non-literal specifier in serve.ts exists to avoid; (2) it fixes one instance and leaves the class open (the shape #10769 and #11157 both record) — a third-party or future optional service is still dead; (3) decisively, IT DOES NOT FIX THIS DEFECT AT ALL — with the base wrong the app's declaration is never read, so a CLI-side declaration changes nothing for an app addressed by config path. It is also the published-manifest change ruling ⑤ says to stop and report before making; it was never approached.",
 "summary": "serve's host-anchored optional-package resolution is now anchored at the directory holding the served app's objectstack.config.ts instead of process.cwd(). Measured at origin/main on a real serve process: with CWD = the app an app-local-only @objectstack/service-cluster loads (so #10645/#10769 hold), but `serve <app>/objectstack.config.ts` from any other CWD dies with `Cannot find package '@objectstack/service-cluster': the host app does not declare it. / host app: <the CWD>` while the app's own node_modules carries it. Surface: packages/cli/src/commands/serve.ts plus one new e2e pin. The #4719 declaration gate is untouched — an undeclared-but-present package is still refused; only the directory the refusal names changed, from the CWD to the app.",
 "gates": {
 "head": "0c93b6c1",
 "derivation": "node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack — no paths passed; script derived 3 changed paths from the merge base 9ca161830 itself. Header confirmed the answer belongs to objectstack-ai/objectstack at 0c93b6c1. 17 path-matched families + the convention-triggered set for 'adds or edits a test file'. No model-tier mandate from paths.",
 "green": [
 "pnpm check:changeset-gate-self-tests",
 "pnpm check:cross-package-test-inputs",
 "pnpm check:objectui-changeset",
 "pnpm check:published-files",
 "pnpm check:route-envelope",
 "pnpm check:slot-lookup",
 "pnpm check:test-source-alias",
 "pnpm check:type-check-coverage",
 "pnpm check:type-source-resolution",
 "node scripts/check-adr-0087-registration.mjs",
 "node scripts/check-changeset-no-major.mjs",
 "node scripts/check-ci-filter-parity.mjs",
 "node scripts/check-cross-package-test-inputs.mjs",
 "node scripts/check-empty-changeset.mjs",
 "node scripts/check-plugin-teardown-shape.mjs",
 "node scripts/docs-audit/check-affected-docs.mjs",
 "pnpm check:query-options-erasure",
 "pnpm check:engine-double-contract",
 "pnpm check:where-matcher",
 "pnpm check:nul-bytes"
 ],
 "type_check_debt": "pnpm check:type-check-debt --re-measure — FIRST RUN REFUSED (unbuilt workspace dependency @objectstack/service-knowledge): that is NOT MEASURED, not passed. Built the closure, re-ran. Its own verdict lines: `check-type-check-coverage: OK — 65/78 workspace packages type-checked (plus the root), 13 in the DEBT ledger` and `check-type-check-coverage --re-measure: OK — 33 ledger entr(ies) re-measured in 377.5s, 1897 raw tsc error(s) total, none above its recorded number.` The reported -1/-1/-12 surpluses are pre-existing informational lowering candidates in packages this PR does not touch.",
 "repo_wide_lint": "pnpm lint (eslint . --no-inline-config, WHOLE repo — NOT narrowed, so no narrowing declaration is owed) — os-verify-lock VERDICT command-exit 0, held 80s.",
 "changeset_gates_after_commit": "All changeset gates listed above were run AFTER the commit that carries .changeset/cli-serve-anchor-optional-import-at-app.md, at 0c93b6c1, with a clean tree (git status --porcelain = 0 paths).",
 "exit_code_capture": "Every gate ran as `cmd > <file> 2>&1; code=$?` with no pipe between the command and the capture."
 },
 "tests": "All at 0c93b6c1 (git rev-parse --short HEAD at the final commit; tree clean). (1) NEW PIN packages/cli/test/serve-app-anchored-optional-import.e2e.test.ts — spawns the real serve process (self-contained spawn; test/helpers/serve-process.ts is HELD by #11267 and was read only, never edited — and it always sets cwd = the app, which is the one shape this file must not use). (2) FIXED TREE: `pnpm --filter @objectstack/cli exec vitest run` → `Test Files 163 passed (163) / Tests 1839 passed (1839)`. `pnpm --filter @objectstack/cli typecheck` (tsc --noEmit) exit 0. (3) REVERSE-VERIFICATION, direction predicted BEFORE running (tests 1+3 and the 3 source-shape tests RED, the control GREEN) and observed exactly: serve.ts restored to origin/main with `git checkout origin/main -- packages/cli/src/commands/serve.ts`; MUTATION CONFIRMED ON DISK by grep counts anchored at the text changed, not by an editor exit code — `anchorServedApp` 0 occurrences (want 0), `servedAppRootOrCwd` 0 (want 0), `const absolutePath = path.resolve(process.cwd(), args.config!)` 1 (want 1), `const hostRoot = process.cwd();` 1 (want 1). Result: `Tests 5 failed | 1 passed (6)`, the single pass being the control 'still loads it when the CWD IS the app' — which is what isolates the failures to the base rather than to a broken fixture. Pre-fix quote: `✗ Cannot find package '@objectstack/service-cluster': the host app does not declare it. / host app: /tmp/os-anchored-neutral-cwd-PNv0hI` (the CWD) and `AssertionError: the remedy does not name the app being served ... expected ... to contain 'host app: /tmp/os-anchored-undeclared-…'`. The mutation ran under a script carrying `trap '<git checkout branch -- serve.ts>' EXIT INT TERM`; restore confirmed after (anchorServedApp back to 5 occurrences, `git status --porcelain` = 0). NO REBUILD WAS NEEDED FOR EITHER LEG and that is a property of the harness, not an omission: the pin spawns packages/cli/bin/run-dev.js, which runs serve.ts from TS SOURCE via tsx, and the source-shape half reads packages/cli/src/commands/serve.ts directly — no dist is on either path, so no stale-artifact false green is reachable. (4) The dependency closure WAS built before any of this (`pnpm --filter '@objectstack/cli^...' build`, then `--filter @objectstack/cli build`); the first repro attempt failed on unbuilt @objectstack/spec and was discarded as unmeasured. (5) INDEPENDENT PRE-FIX REPRO, outside vitest, before the pin existed: a two-case harness spawning serve against one fixture app — CASE 1 (cwd = app): service-cluster loaded true, driver loaded true; CASE 2 (cwd = neutral, config = absolute): both false, `host app: /tmp/os-neutral-cwd-jXHXdF`, `(fallback resolution also failed: … imported from …/packages/types/dist/node.mjs`.",
 "files_changed": [
 "packages/cli/src/commands/serve.ts — added module-scope `servedAppRoot`, `servedAppRootOrCwd()` and `anchorServedApp()`; importFromHost's default parameter and Serve.importConfigPlugin's fallback now read the anchored root; run() obtains absolutePath/configExists from anchorServedApp(args.config!); the boot body's `const hostRoot` reads the same answer instead of recomputing process.cwd()",
 "packages/cli/test/serve-app-anchored-optional-import.e2e.test.ts — NEW. 3 behavioural tests over a real spawned serve process + 3 source-shape tests",
 ".changeset/cli-serve-anchor-optional-import-at-app.md — NEW, @objectstack/cli patch"
 ],
 "deviations": [
 "Ruling ② honoured: test/helpers/serve-process.ts was READ ONLY (to learn the spawn shape) and never edited; the new pin writes its own spawn. Beyond the fence, this was independently necessary — runServe() always sets cwd = the app, which is precisely the invocation this card must NOT use.",
 "Ruling ③ honoured: packages/types/src/node.ts untouched. createHostImporter's own contract needed no change — the declared branch already does createRequire(join(hostRoot,'package.json')); only the hostRoot it was handed was wrong.",
 "Ruling ⑤ honoured: no package was added to packages/cli's dependencies or optionalDependencies. The manifest is unmodified (check:published-files green).",
 "Ruling ①: the diff is confined to packages/cli/src/commands/serve.ts plus the new pin and its changeset. Nothing else touched.",
 "The three-branch shape in importConfigPlugin (origin/main :474-490, now :558-574 at my head) was read before editing nearby and is UNCHANGED — only its `hostRoot ?? process.cwd()` fallback moved to the anchored root, which is the same value the boot loop already passes explicitly at its call site. All three source-shape assertions the two neighbouring config-plugin test files make about that helper still hold (both files green).",
 "#11268's NODE_ENV change was already at my base (9ca16183) and every line number in this report was re-derived at my own head, never taken from the dispatch.",
 "No local narrowing was declared or needed: pnpm lint ran over the whole repo."
 ],
 "open_questions": [],
 "out_of_scope_findings": [],
 "note_on_11157": "NOT made redundant by this PR — measured, not inferred. #11157 concerns the base of the UNDECLARED branch (createHostImporter is called with no `{ fallbackImport }`, so the fallback resolves from @objectstack/types). This PR corrects the base of the DECLARED branch (which manifest is read, whose node_modules is searched). Measured on THIS branch with an undeclared-but-present package and CWD elsewhere: `host app: /tmp/os-undecl-Z5N7g3` — now correctly the app — while the same message still carries `(fallback resolution also failed: … imported from /…/packages/types/dist/node.mjs` and `(the caller did not pass \\`fallbackImport\\`, so that fallback resolved from @objectstack/types …)`. Two different bases; #11157's two-line edit still has work to do and its premise survives this merge. One thing does change for its claimer: on the merged ref the undeclared diagnostic names the APP, so its own before/after must be re-measured against that text, not against the CWD-named text on today's main."
}

---

Generated by Claude Code

[claude]

{
"issue": 11185,
"status": "done",
"branch": "claude/issue-11185-app-anchored-optional-import",
"pr": "#11349",
"premise_still_valid": true,
"summary": "Patch round on PR 11349 — TEXT ONLY. No code, no test, no changeset touched; draft state and auto-merge left alone. Pushed 111f038 onto claude/issue-11185-app-anchored-optional-import. Both the anchorServedApp docblock in packages/cli/src/commands/serve.ts and the PR body asserted "No layout that resolves today resolves differently after this"; that absolute is false and both now say so. Each states the measured truth: the four listed rows are unchanged, PLUS a fifth row (CWD's manifest declares the optional package, the served app's does not) where the load moves off the declared leg onto createHostImporter's fallback leg — still succeeding wherever that fallback can reach the package, refusing where it cannot — and each names the remedy for the refusing case: declare the package in the SERVED app's own package.json, which is what 4719 asks for regardless. My own measurement AGREES with the dispatch reading: serve.ts builds its importer as createHostImporter(hostRoot) with no fallbackImport, so the undeclared leg is a bare import() physically inside @objectstack/types and Node ESM walks node_modules upward from there — a hoisted monorepo store above that install still resolves; a global/npx CLI with the package only beside the operator does not. No shim, no env hatch, no second base; packages/types/src/node.ts and packages/cli/test/helpers/serve-process.ts untouched. One incidental byte fix in the PR body: two literal angle-bracket placeholders were respelled in words, because GitHub's body sanitizer eats short angle fragments on every edit and one of them had already been served back stripped through the API.",
"tests": "All at 111f038 (git rev-parse --short HEAD after the final commit, clean tree). Dependency closure built first: pnpm --workspace-concurrency=2 --filter '@objectstack/cli^...' build — os-verify-lock: VERDICT command-exit 0 (the typecheck attempted before it printed ERR_PNPM_RECURSIVE_RUN_FIRST_FAIL / Exit status 2 with ~100 TS2307 'cannot find module' errors, i.e. the unbuilt-closure trap, not a real failure). (1) pnpm --filter @objectstack/cli typecheck — printed '> tsc --noEmit' with no diagnostics; os-verify-lock: VERDICT command-exit 0. (2) pnpm --filter @objectstack/cli exec vitest run test/serve-app-anchored-optional-import.e2e.test.ts --maxWorkers=2 — 'Test Files 1 passed (1) / Tests 6 passed (6)'; os-verify-lock: VERDICT command-exit 0. The comment edit did not disturb the pin. (3) pnpm exec eslint --no-inline-config --format json packages/cli/src/commands/serve.ts — exit 0, filesLinted=1 errors=0 warnings=0. NARROWING DECLARED, with its three pieces: the file count is read from eslint's own --format json output, not guessed; the repo runs one eslint.config.mjs which enables type-aware linting for NO file (no parserOptions.project, no typed @typescript-eslint rules) — that invariant is stated and positively controlled in that config's own header, so a comment-only edit inside one file cannot move any untouched file's verdict; the whole-repo run stays CI's. (4) Gate families re-run at 111f038, every one exit 0, quoting each gate's own verdict line: check:nul-bytes — 'check-nul-bytes: OK (scanned 6366 text file(s) ... no raw ASCII control bytes)'; check:slot-lookup — 'slot-lookup ratchet holds: 107 unswept site(s) in 25 file(s), none new'; check:test-source-alias — 'check-test-source-alias OK — 72 packages with tests scanned'; check:type-source-resolution — 'check-type-source-resolution OK — 77 packages with a tsconfig.json scanned'; check:published-files — '69 publishable package(s) ... declare a files whitelist'; check:route-envelope — '4 module(s) discovered and audited', exit 0; check:cross-package-test-inputs — 'OK: 14 package(s) read outside themselves, all declared'. Family list derived with node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack (no paths passed; it named 17 path-derived families for the PR's 3-file change set and confirmed the answer came from this checkout of objectstack-ai/objectstack). (5) NOT re-run, declared: check:type-check-debt --re-measure and the 1839-test @objectstack/cli suite. A docblock cannot move a tsc error count or a test outcome; both are green at 0c93b6c, the last commit that changed code, and CI runs them on this head anyway. Edit landed on disk, proven by anchored grep counts rather than an editor exit code: the absolute's line 0 occurrences after (1 before, asserted by the patch script), 'why it can only ADD working cases' heading 0, 'A FIFTH one is NOT' 1, the fifth-row bullet text 1; git diff --stat 29 insertions / 5 deletions in one file. Independent measurement of the fallback claim (two Node probes, run outside the repo): an importer inside a hoisted node_modules store resolved '@fake/target' from that store with the CWD elsewhere → 'RESOLVED'; the same importer in an unrelated install, with '@fake/target' present only in the CWD's node_modules → 'REFUSED: ERR_MODULE_NOT_FOUND Cannot find package', which is exactly the error createHostImporter re-throws as 'undeclared'. Agrees with the dispatch reading in both directions. No ablation in this round — nothing executable changed.",
"open_questions": [],
"out_of_scope_findings": []
}

---

Generated by Claude Code